跳转至

External Connector Action Gateway：外部 Connector 动作边界实验

生成时间：2026-06-14T02:30:00+08:00

数据分类：synthetic_internal_demo。样例使用合成企微、GitHub 和业务系统响应，用于验证外部 Connector action contract，不代表真实员工、客户、仓库或消息记录。

实验定位

这个实验验证真实外部系统 adapter 接入前的统一动作边界：

  • 外部响应不能直接进入模型。
  • action 必须先经过 Tool Gateway 的 schema、scope、approval / draft-only 和输出净化。
  • 允许执行或草稿化的结果只能写成可审计 writeback event。
  • safe output 和 writeback event 不能暴露原始消息 ID、会话 ID、URL、owner、业务对象 ID 或外部正文。

当前结果

  • Case 数：6
  • 通过数：6
  • 失败数：0
  • 通过率：100%
  • 记录 writeback：4
Case 期望 实际 Writeback 结果 说明
wecom_delivery_records_safe_writeback allow allow yes pass 企微投递类 action 允许执行后，只写安全 writeback，不暴露消息 ID、会话 ID、URL、owner 或消息正文。
deny_wecom_missing_directory_scope_no_writeback deny deny no pass 缺少组织目录 scope 时，企微投递 action 被拒绝，且不能写入投递成功事件。
github_pr_checks_read_records_safe_status allow allow yes pass GitHub 只读状态检查可以写入安全状态事件，但不暴露 run_id、PR 编号、commit sha 或 action URL。
business_write_downgraded_to_draft_writeback draft_only draft_only yes pass 业务系统正式写操作先降级为 draft-only，只写内部草稿事件，不声明源系统已更新。
deny_r4_merge_without_approval_no_writeback require_approval require_approval no pass R4 外部写动作无 approval_id 时只返回 require_approval，不写成功事件。
approved_r4_merge_records_safe_writeback allow allow yes pass R4 外部写动作获批后可以记录安全 writeback，但仍不泄露 PR 编号和 commit sha。

关键结论

  1. 外部 Connector action 不能把源系统响应直接暴露给 Agent；只能暴露状态、计数、warning 数和安全指标。
  2. writeback event 可以保留 connector_id、action_id、状态和外部引用 hash，但不能保存原始消息 ID、会话 ID、URL、owner 或业务对象 ID。
  3. draft-only 写操作可以进入内部草稿 / review 队列，但不应被视为已经写入源系统。
  4. R4 外部动作没有 approval_id 时不会生成 writeback；获批后也只返回安全状态和计数。
  5. 已记录的 writeback event 可以作为 project status event timeline 的安全事件源。
  6. 企微 adapter 后续只需要替换 delivery / callback 实现，仍然复用这个 action contract、Tool Gateway 和 writeback 边界。

外部系统随后回调回来时，还需要经过 Connector Callback Ledger，验证签名、时间窗、幂等、必填字段和安全 ledger 事件，不能让 webhook 直接更新知识库或暴露给 Agent。

没证明什么

  • 这还不是企微真实 API、GitHub API 或 CRM API 的网络调用。
  • 这还没有验证 OAuth token 轮换、真实 webhook 签名、超时、重试和幂等。
  • 这还没有实现完整 MVC；它只固定外部动作进入 Framework 的最小安全边界。

代码入口

  • Fixture：vault/90-system/external-connector-actions.json
  • 实现：framework/governance/external_connector_action.py
  • 测试：tests/test_external_connector_action.py
  • 运行：python scripts/external_connector_action_conformance.py --write-report
  • 输出：vault/50-outputs/external-connector-action-analysis.md
  • Timeline source：vault/50-outputs/external-connector-action-results.json

下一步

  1. 把企微通讯录、消息投递和回调 adapter 按这个 contract 接入，而不是绕过 Tool Gateway。
  2. 把 writeback event 继续落到 ontology registry 的真实持久化表，并接入 worker retry / callback 的同一事件链。
  3. 继续扩展 Connector Callback Ledger，增加 timeout、retry、idempotency key、callback signature 和 source-system permission 的真实 adapter conformance。