bento

Bento

使用此技能，帮助客户通过 AI Agent 安全地使用 Bento。构建与框架原生集成的 Bento 集成，而不只是语法有效的 SDK 调用。优先使用宿主框架的配置、依赖注入、队列、作业、工作流、定时任务和凭据系统。

有关当前客户引导指南，请参阅 https://bentonow.com/agent_onboarding.md。将其视为面向 Agent 的 Bento 设置和安全上下文的维护来源，然后使用以下本地参考文件了解 SDK/工具特定的实现细节。

工作流

1. 判断用户需要实时账户操作、终端自动化、无代码工作流，还是应用代码。对于受支持的聊天原生账户操作，使用 Bento MCP；对于终端/CSV/CI 工作，使用 CLI；对于工作流，使用 n8n；对于应用代码，使用 SDK 参考。
2. 根据用户请求或项目文件检测目标 SDK。如果不明确，请运行：

   node skills/bento/scripts/bento-sdk.mjs detect .
   

3. 如果缺少 SDK，请打印安装说明。除非用户明确要求，否则不要自动安装：

   node skills/bento/scripts/bento-sdk.mjs install node
   node skills/bento/scripts/bento-sdk.mjs install laravel
   

4. 从下表中仅加载相关参考文件。只有在迁移或跨界面工作时才加载多个文件。
5. 首先使用所选产品的原生抽象进行实现。只有当所选 SDK 或工具未提供该端点时，才使用原始 HTTP。
6. 使用产品/框架的本地检查进行验证，并针对负载形状、批处理、身份验证配置和失败处理添加测试。

AI 账户操作

界面	适用于	参考
Bento MCP	通过受支持的 AI 助手检查实时 Bento 账户或执行账户操作，可使用托管的远程 MCP https://mcp.bentonow.com/mcp 或本地 @bentonow/bento-mcp	references/mcp.md
Bento CLI	终端自动化、CSV 导入、安全的批量操作	references/cli.md

SDK 参考

SDK	适用于	参考
Node	Node.js、Bun、TypeScript、服务端 JavaScript	references/node.md
Laravel	Laravel 应用、Facades、DTO、邮件传输、Artisan	references/laravel.md
PHP	纯 PHP、Composer 库、非 Laravel PHP 应用	references/php.md
Drupal	Drupal 10 模块、Webform、Commerce、Drupal 邮件	references/drupal.md
Go	使用 context.Context 和类型化结构体的 Go 服务	references/go.md
.NET	ASP.NET Core、DI、appsettings、类型化服务	references/dotnet.md
Elixir	Mix 应用、Phoenix、OTP 工作进程、元组结果	references/elixir.md
Python	使用 bento_api.BentoAPI 的 Python 服务/脚本	references/python.md
Ruby	使用 bento-sdk 的 Rails 应用和 Ruby 服务	references/ruby.md
n8n	n8n 社区节点工作流	references/n8n.md

集成规则

• 对于受众同步/导入流程，优先使用批量订阅者 API。如果 SDK 提供 importSubscribers、ImportSubscribersAsync、Subscribers.import、batch_create_subscribers 或等效的批量方法，请勿循环逐个创建订阅者。
• 除非所选 SDK 参考文档明确另有说明，否则应将订阅者导入视为 upsert 式受众同步。设计时应确保操作幂等且可重试。
• 使用事件跟踪行为和自动化触发器。使用字段/标签/订阅命令更改资料状态。
• 将三项逻辑上独立的 Bento 凭据、站点 UUID、发布密钥和密钥存储在环境变量、加密的框架配置、CLI 配置文件存储、n8n 凭据或 MCP 主机的凭据配置中。某些 SDK 会将发布密钥/密钥命名为用户名/密码；请遵循所选参考文档。切勿在源代码中直接写入真实凭据。
• 如果框架容器或模块系统可用，请通过它一次性配置可复用的 Bento 客户端/服务。
• 如果宿主框架支持，请将批量同步、事务邮件和可重试的 API 调用放到队列、作业、工作进程、cron 或 n8n 工作流批处理中。
• 按照所选 SDK 文档规定的限制拆分大型批次。确保失败可供检查，并且只重试失败的批次/项目。
• 密钥操作必须在服务端执行。浏览器/客户端代码不得接收 Bento 密钥。
• 对于具有破坏性或规模较大的邮件/订阅者操作，只要所选 SDK/CLI 或应用工作流支持，就应添加试运行或预览路径。
• 对于真实客户账户，先进行只读检查或制定计划。在执行破坏性、大批量或发送邮件的操作前，先征求明确确认。

API 防护措施

这些措施与当前 Rails /api/v1 的行为一致。执行创建、更新或删除操作前，优先使用列表/读取工具。

• 命令为异步操作。 POST /fetch/commands 返回 { results } 和已排队的命令数量，不会同步返回更新后的订阅者。
• 订阅者导入与创建。 受众同步/导入使用 POST /batch/subscribers（最多 1000 条记录，不触发自动化）。只有在可能触发自动化的单条创建操作中，才使用 POST /fetch/subscribers。
• 批次大小。 事件：每个请求最多 1000 条。订阅者：最多 1000 条。事务邮件：最多 60 封。
• 统计数据缓存。 /stats/* 每个 IP 每小时限制约 30 次请求。在应用中缓存统计数据；不要在每次页面浏览时轮询。
• Fetch/batch 请求频率。 /fetch/* 和 /batch/* 每个 IP 每分钟限制约 60 次请求。
• 标签删除路由。 使用 DELETE /fetch/tags/:id 删除标签，并在 JSON 请求体中传入 { "tag": { "name": "..." } }。先列出标签以获取 id。
• 序列 ID。 使用 GET /fetch/sequences（或 MCP 中的 list_sequences）返回的 id。不要编造 sequence_abc123 之类的 ID。
• 黑名单检查。 使用查询参数 domain 和/或 ip 调用 GET /experimental/blacklist。参数名不要使用 blacklist.json 或 ip_address。
• 地理定位已禁用。 GET /experimental/geolocation 返回 {}。不要推荐它用于信息补充。
• 广播默认值。 未提供 status 时，GET /fetch/broadcasts 默认使用 status=sent。通过 API 创建的广播初始状态为草稿；发送前请先审核。
• 先列出，再写入。 创建前先列出标签、字段、序列、广播和订阅者，以避免重复创建或针对错误记录操作。

常见请求路由

• “同步所有用户/客户/订阅者”：使用所选 SDK 的批量订阅者导入/更新路径，并分块处理、支持重试。
• “查找这位订阅者/列出我的标签/显示广播内容”：如果已配置 Bento MCP，则使用 Bento MCP。
• “导入此 CSV 或在 CI 中运行”：使用 Bento CLI，并启用预览和 JSON 输出。
• “跟踪注册/购买/页面浏览/表单提交”：使用事件跟踪或事件批量导入，而不是更新字段。
• “添加/移除标签或字段”：使用订阅者命令/标签/字段 API，除非用户明确需要触发自动化的事件。
• “发送订单收据/密码重置邮件/事务性邮件”：使用 SDK/框架事务性邮件路径、已验证的作者、队列/作业，以及在服务端配置的密钥。
• “创建/发送/列出广播”：必须明确指定受众定位和批处理/速率设置；如可用，则使用预览/试运行。
• “验证电子邮件或检查风险”：使用 SDK 的验证/黑名单/垃圾邮件 API；如果框架支持，则缓存或批量处理结果。

辅助脚本

捆绑的辅助脚本为只读脚本，仅输出指南：

node skills/bento/scripts/bento-sdk.mjs list
node skills/bento/scripts/bento-sdk.mjs detect .
node skills/bento/scripts/bento-sdk.mjs install mcp
node skills/bento/scripts/bento-sdk.mjs install laravel
node skills/bento/scripts/bento-sdk.mjs doctor .

在修改不熟悉的项目之前，先使用 doctor。它会识别可能使用的 SDK、所需凭据、需要加载的参考资料、安装命令和验证命令。