运行时、Worker 与 Webhook
将 Worker 创建、连接器同步和入站 Webhook 视为可观察的生命周期系统。
Worker 创建、连接器同步和 Webhook 投递都是异步操作。一次成功的创建请求，并不一定意味着运行时已经就绪、外部数据源已经发现，或同步已经结束。请将每个系统视为有状态的生命周期，其中包含资源 ID、可见活动和可恢复的失败路径。
托管 Worker 生命周期
/v1/workers 是组织管理的 Worker 资源族。它对本地桌面工作区是可选的。只有当部署确实需要托管或远程管理的 iPolloWork 运行时时，才使用它。
创建操作可能返回立即创建状态，也可能返回异步接收状态。假设它可用前，应读取 Worker 与 Runtime 状态。
- 01创建
携带名称和 destination 创建 Worker。可选字段描述工作区、Sandbox 或镜像选择。
- 02创建中
处理声明的 201 或 202 响应，并保存 `wrk_` 资源 ID。
- 03检查
读取 Worker、活动心跳或 Runtime 表示，以确认是否就绪。
- 04运行
仅在 Runtime 报告有效运行状态后，请求 Runtime Token 或升级。
需要明确建模的 Worker 路由
| 需求 | 路由族 | 客户端行为 |
|---|---|---|
| 列表或创建 | /v1/workers | 使用 Cursor 分页。创建需要 name 与 destination。 |
| 读取状态 | /v1/workers/{id} | 将 Worker ID 视为稳定标识，不要按展示名称重新查询。 |
| 观察活跃度 | /v1/workers/{id}/activity-heartbeat | 将其作为活动信号，而非任务已完成的承诺。 |
| 读取或升级 Runtime | /v1/workers/{id}/runtime、/runtime/upgrade | 发送升级请求后重新读取状态。 |
| 获取访问 Token | /v1/workers/{id}/tokens | 409 可能表示 Worker 尚未就绪。先检查就绪状态再重试。 |
连接器图谱
连接器以多个层级表达外部系统。Account 证明连接身份。Instance 定义如何使用该 Account。随后 Target、Mapping、Discovery 和 Sync Event 描述实际对外部数据执行的工作。
每一层都会生成不同 ID 与失败模式。保留图谱，才能让运维者准确重试正确对象。
谁可以连接
一个已授权的外部身份或连接账户。
集成如何被使用
可启用、禁用、发现和配置 Target 的集成实例。
用于导入或同步的外部范围目标。
系统实际做了什么
同步或导入后的资源表示之间的关系。
具备可观察、可重试失败路径的活动记录。
GitHub 配置与 Webhook
GitHub 连接器在 /v1/connectors/github/* 下提供了专用的配置、安装、账号、仓库和验证路由。入站投递到达 POST /v1/webhooks/connectors/github。
应将周边服务实现为一个窄的入口边界：
- 仅通过组织 Ingress 策略暴露该 Endpoint。
- 使用当前检出 OpenAPI 契约与连接器实现中的请求验证行为和 Response Schema。调用方不要自行假设签名方案。
- 只有当接收服务可以持久化或安全入队事件后，才返回确认。
- 在 API 暴露相关信息时，将投递关联至 Connector Instance、Target 和最终 Sync Event。
- 依赖不可用时，返回可观察的错误状态，而不是静默丢弃事件。
OpenAPI 为 GitHub Webhook Operation 声明了 200、202、401、503。将 202 视为已接收的异步工作，503 则应先在连接器或依赖边界排查，再从发送端重试。
运维恢复闭环
对尚未就绪的 Worker、失败 Sync Event 或已接收的 Webhook 投递，都应遵循同一模式。
- 01记录标识
保存 API 返回的 Worker、Account、Instance、Target、Event 或 Delivery ID。
- 02读取状态
再次写入前，先检查资源、Runtime、活动或 Sync Event。
- 03修复边界
在各自归属层修复凭据、配置、就绪状态或依赖健康度。
- 04窄范围重试
只重试特定操作，并确认它产生的状态或产物。
资源授权和认证范围请见 认证与访问控制。完整 Request Body 与 Response Schema 请使用同一 iPolloWork 版本中的 packages/docs/openapi.json。