触发器

面向接入 OpenBot 客户端或扩展服务端的开发者。示例需要本页说明的访问权限。从开发者手册开始。

触发器用一句 prompt 把一个任务交给一个 Bot。它可以按计划时间触发，也可以通过 webhook 触发，或者两者都有。它只做这一件事：怎么完成工作由 Bot 决定。Bot 可以先做计划、维护待办列表，也可以把工作交给其他 Bot。任务结束时，结果会进入你和这个 Bot 的 Chat。

创建触发器

curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Check the open issues and sum them up.","schedule":{"cron":"0 9 * * 1-5","timeZone":"Europe/Berlin"}}' \
  https://api.example.com/v1/triggers

字段	作用
`prompt`	任务。
`bot`	可选。做这项工作的 Bot。不填时由你的默认 Bot来做。
`schedule`	可选。触发器什么时候自己触发。
`shared`	可选。`true` 表示创建属于组织的共享触发器。
`enabled`	可选。`false` 表示触发器不会触发。默认是 `true`。

返回 201 和这个触发器。它有 nextRunAt（计划下一次触发的时间）和 lastFiredAt。

GET /v1/triggers 列出你自己的触发器和共享的触发器。GET、PATCH 和 DELETE /v1/triggers/:triggerId 读取、修改和删除一个触发器。修改需要 expected，也就是你读到的 revision。旧的 revision 会返回 409 和 TriggerConflict。

一次触发做什么

每次触发都把任务作为一个委派交给 Bot。工作在这个 Bot 的一个新 task Chat 中运行。它的第一条输入是这句 prompt，来自“一个触发器”。这个委派有 trigger，其中是触发器的 ID。

工作结束时，结果作为通知进入 actor 和这个 Bot 的 direct Chat。那个 Chat 还不存在时，OpenBot 会创建它。所以 Bot 在那里读到结果，它可以把结果告诉 actor，或者接着做这项工作。审计日志会记录 trigger.fired，并在 details.delegation 中记下委派的 ID。

要找到触发器的工作，请为那个 direct Chat 读取 GET /v1/chats/:chatId/delegations，或者用 GET /v1/chats?kind=task&bot=<id> 列出这个 Bot 的 task Chat。

计划时间

计划时间有一个五个字段的 cron 文本，例如 0 9 * * 1-5 表示工作日的 9:00。timeZone 是 IANA 时区，例如 Europe/Berlin。不填时使用 UTC。无效的 cron 文本会返回 400 和 TriggerInvalid。永远不会触发的 cron 文本，例如 0 0 30 2 *（2 月 30 日），也会返回同样的错误。

触发器的 executionId 指向持久化计时器，没有计时器时为 null。重启不会丢失计时器。到期的计时器启动一个任务，再设置下一次时间。任务、审计记录和下一次计时器在同一事务中提交。修改触发器会替换计时器，不会停止已启动的任务。失败的计时器保留错误 ID，修复原因后修改触发器即可重试。

Webhooks

PUT /v1/triggers/:triggerId/webhook 会生成一个 webhook 密钥。OpenBot 只显示一次：

{
  "url": "https://api.example.com/v1/hooks/triggers/trg_4c1e...",
  "secret": "otg_..."
}

另一个系统用这个密钥触发它：

curl -H "Authorization: Bearer $WEBHOOK_SECRET" \
  -H "Idempotency-Key: issue-42" \
  -H "Content-Type: application/json" \
  -d '{"issue": 42}' \
  https://api.example.com/v1/hooks/triggers/trg_4c1e...

返回 202，包含 delegation、executionId、commandKey 和 sequence。每次调用都要发送稳定的 Idempotency-Key。丢失响应后，复用该键和相同内容。同一键配不同内容会返回 409 ExecutionKeyConflict。通过执行 API 读取事件和取消工作。SDK 的 Triggers.fire 生成一个键；保留返回的命令，通过 command.send 重试。JSON 内容会和任务一起交给 Bot。OpenBot 会标明它是另一个系统发来的数据，不是指令。密钥错误、触发器没有 webhook，或者触发器已停用，都会返回 401 和 TriggerHookDenied。

再次 PUT 会生成新的密钥，旧的密钥就不能用了。DELETE /v1/triggers/:triggerId/webhook 会删除 webhook。

如果执行者已不能向 Bot 分派任务，或 Bot 已归档，webhook 会返回 403 ExecutionForbidden。执行存储故障返回 503 ExecutionUnavailable 和安全的错误 ID。

工作为谁服务

触发器的工作为它的 actor 服务，也就是最后一个创建或修改这个触发器或它的 webhook 的成员。所以你修改它以后，你就成了 actor。task Chat 属于 actor，结果也会进入 actor 的 Chat。actor 必须能把工作交给这个 Bot。如果 actor 不再能这样做，触发器就不会触发。

保存的调用身份包含原始用户 token 及其限制。每个步骤都会重新检查当前权限。撤销的 token 不能启动或恢复工作。提示词和 webhook 数据以加密形式保存。需要新能力时，Bot 用 requests 申请。这些请求会交给 actor。

数据升级后，触发器可能显示 needsAuthorization: true。其提示词、时间安排、下一次时间和启用设置会保留，但计时器和 webhook 都不能启动工作。使用当前权限保存一次修改，以建立新的调用身份并清除此状态。新计时器使用修改后的下一次时间。旧任务保持原有状态，不会以新调用人的身份重新执行。

权限

`Trigger` 上的操作	允许做什么
`read`	读取触发器：它们的计划时间和 webhook。
`write`	创建、修改和删除触发器，并设置它们的 webhook 密钥。

你自己的触发器的路径是 org / <org> / user / <you> / trigger / <id>。共享触发器的 owner 为 { "_tag": "Organization" }。个人触发器的 owner 为 { "_tag": "Member", "userId": "<member id>" }。每个成员都能读取共享触发器，管理员可以修改它们。列表中只有你可以读取的触发器。见权限。