选择接入方式
不要新增凭据存储,也不要把应用请求移到 guest 来绕过审批。复用请求映射时保留出处和许可;当前复用映射的来源保存在 third_party/activepieces。
定义有边界的读写操作
types.ts定义 AppDefinition、AppOperation 与 RequestSpec。每个操作提供严格对象 schema、表达实际副作用的write 标记和固定请求映射。路径标识要编码,字符串和分页要有上限,拒绝未知字段,不能让模型参数随意选择主机或 HTTP 方法。POST 也可能是读取,例如 Notion 搜索;按语义判断副作用。
以下示意放在 integrations/apps 模块内。.invalid 服务故意不可访问,需要针对自己的受控服务实现并测试后才能注册:
verify 请求,然后加入 registry.ts的 applications 列表。可参考 productivity.ts中的 Todoist get_task 与 create_task。
当前注册表缺省只选择非写操作;显式选择的写操作要求审批,并使用 replay: 'never'。供 broker 使用的方法由 write 推导,真实上游 HTTP 方法来自 RequestSpec,审查时不能认为二者一定相同。Session 绑定还会限制 Harness 可用的连接和操作。
接入认证与限定范围的验证
缺省认证为 Bearer。Provider 要求其他请求头、组合凭据或令牌交换时,使用 AppDefinition 的认证钩子。操作参数、schema、结果、URL 和诊断信息中都不能包含秘密。共享请求路径拒绝重定向、限制结果大小并替换已知凭据值,但这不能替代对 Provider 返回内容的审查,也不能替代源头防泄漏。 API key 使用受管凭据存储。OAuth 复用现有模块、加密 token envelope 和租户或部署所属的应用配置,声明真实端点、scope 与客户端认证规则。复用绑定租户、连接版本、Provider 和 redirect URI 的过期单次事务,不另做临时 callback,不向浏览器返回 Token。账户或权限变更使旧审批失效;刷新 Token 有单独的并发和版本语义。 身份请求成功不能证明全部选定操作有权限。有依据时补充操作 scope、安全权限探测或对象元数据检查,否则保持未知。不能静默发送消息或创建真实对象来验证写权限;实测写入需要明确授权的可丢弃目标。断开本地连接不代表上游授权已经撤销。 连接、Secret、OAuth 事务、Session 绑定和 Tool call 查询都检查租户所有权。知道上游对象 ID 不代表拥有引用它的 Hexagon 资源。保留审批与未知结果语义
broker 在执行前保存调用与 request hash;相同调用 ID 使用不同参数会冲突,并固定实际执行的连接版本和策略。授权建立账户访问条件,审批允许具体副作用,二者不能替代。 使用共享错误分类。当前应用传输中,401 触发重新认证;除 408 外的大多数其他 4xx 返回拒绝结果;5xx、传输失败及响应处理歧义可能留下未知结果。还需要解析应用错误信封,例如 Linear mutation 返回 GraphQL errors,即使data: null 也可能已经发生写入。不能把全部 HTTP 200 当成功,或把全部错误响应当作没有副作用的证明。
写入响应丢失时,保留原调用并停止重发。通过安全读操作或 Provider UI 查询真实记录,再按 Tool 对账使用精确 request_hash、观察到的结果、返回文字和证据完成 resolve。resolve 记录操作者结论,不会发出新的上游请求。重复相同结论幂等,冲突或过期决定失败。无法确定结果时保持未知或取消 Run,不能编造成功或再次创建。
三种相似等待,三种不同决定
第三行尤其容易被新适配器处理错:Run 的等待状态本身不能区分审批与未知结果。查看 Tool call 的 state、approval_id、execution_policy 和 resolution,必要时查询审批记录。派发后的
executing 状态在 worker 故障后同样需要按持久策略判断,而不是假定请求没有发送。
broker 对可重放读取或明确 idempotency_key 策略有自己的规则;具名应用写操作当前固定为 replay: never。实际 POST 读取在 broker 的语义策略中可能是 GET,不应直接复制供应商 HTTP 方法作为重放依据。若原调用固定的 connection_version 与当前版本不同,未知结果不能沿新配置继续重放。扩展策略必须同时验证上游去重约束,不能只添加一个字段就宣称 exactly-once。
completed 不一定意味着上游操作成功
Tool call 的 completed 表示已经有可交付结果;该结果可以是isError: true。AppRequestError 会形成已完成的错误结果,授权拒绝也会完成原调用并返回错误。人工 resolve 选择 outcome: failed 同样将调用置为 completed,并让 Harness 收到失败内容。
因此,测试应同时断言调用状态、isError / 错误码、外部写入次数和 Run 是否按预期继续。只断言 completed 会把权限拒绝或失败对账误判为业务成功。
对账接口的重复与竞争
resolve 使用与 broker 相同的调用锁;请求仍在执行时返回tool_call_in_flight,即使 worker lease 已到期也不能抢先填写结论。首次决定要求原 Run 仍处于允许状态、调用为 unknown,并提供精确 request_hash。
已保存的完全相同决定可以幂等返回,检查发生在首次决定的活动状态要求之前;这不意味着旧终态 Run 能接受一个新决定。不同 text、evidence 或 outcome 会与原 resolution 冲突。测试取消与对账竞争时,要区分“重复读取既有决定”和“试图提交新决定”,不能笼统写成取消后所有 resolve 都失败。
实现依据:ToolBroker、对账事务和应用请求分类。HTTP 请求及错误契约见审批与 Tool 恢复参考。
验证具体读写示例
使用 fake transport 与数据库 broker 测试。上述示例可以在 fixture 中维护内存报告存储和请求计数:读请求返回固定报告,写请求先保存报告再故意丢失响应,稳定触发未知结果。
已有回归入口:
TEST_DATABASE_URL。为新 Provider 增加断言,不能用已有测试通过代替新接入覆盖。OAuth 变更还需测试 state 重放与过期、并发刷新和权限变更。
添加新示例之前先复用仓库中的测试
上面的报告映射用于解释扩展位置,不要求为了验证共享 broker 再建设第二个应用。按职责复用现有具体测试:
这些测试是共享契约的已有可执行示例,不证明新加入的 Provider 已经可用。只为新 Provider 添加请求映射 / 鉴权差异和确实缺少的契约用例。缺少
TEST_DATABASE_URL 时数据库相关测试会跳过,跳过不能作为通过证据;真实账户状态仍按下文单独记录。
请求映射测试与调度测试分开
对read_report,含 / 的 ID 必须编码为单一路径段,额外参数必须在发送请求前被 schema 拒绝。对 create_report,独立检查固定 POST 地址和 JSON body,不把审批测试混入映射断言。映射测试无需账户即可证明请求形状,但不能证明 broker 会等待、拒绝租户不匹配或避免重复写入。
模拟响应丢失时,先向假上游存储插入报告,再抛错。使用同一数据库重建 broker,保留上游存储与计数器。按业务引用读回报告,再用保存的 request_hash 对账原调用;断言对账前后上游写入计数都为一。重新创建空数据库或空上游存储会让测试失去检测重放的能力。真实账户验证仍是独立步骤。