跳转至

Connector Callback Ledger：外部回调与 writeback 幂等实验

生成时间：2026-06-14T04:10:00+08:00

数据分类：synthetic_internal_demo。样例使用合成企微、GitHub 和业务系统回调，不代表真实员工、客户、仓库、PR、会话或消息记录。

实验定位

这个实验验证外部 Connector action 之后的回调进入系统时，必须先满足签名、时间窗、必填字段和幂等约束，再落到安全 ledger。它是企微真实 webhook、GitHub checks callback、CRM writeback callback 接入前的本地 contract。

它承接 External Connector Action Gateway：前者约束“能不能调用外部动作、动作结果如何安全 writeback”，本页约束“外部系统随后回调回来时，能不能被系统采信、如何避免重复和泄漏”。

当前结果

  • Case 数：6
  • 通过数：6
  • 失败数：0
  • 通过率：100%
  • 记录事件：2
  • Evidence source：2
  • Ontology registry event：1
  • Ontology state：recorded
  • 幂等抑制重复：1
  • 拒绝回调：3
Case 期望 实际 Recorded Duplicate 结果 说明
wecom_delivery_callback_records_safe_event allow allow yes no pass 企微投递回调签名有效时，只记录安全 ledger event，不暴露消息 ID、会话 ID、URL、owner 或消息正文。
wecom_delivery_callback_duplicate_suppressed duplicate duplicate no yes pass 同一 idempotency key 的企微重试回调只能返回 duplicate，不能追加第二条 ledger event。
wecom_delivery_callback_invalid_signature_denied deny deny no no pass 签名无效的企微回调不能落 ledger，即使 body 看起来是送达成功。
wecom_delivery_callback_stale_timestamp_denied deny deny no no pass 超过时间窗的企微回调不能落 ledger，避免旧回调或重放攻击污染当前状态。
github_check_callback_records_safe_status allow allow yes no pass GitHub check 回调可以记录安全状态和计数，但不暴露 run_id、commit sha 或 action URL。
wecom_delivery_callback_missing_required_field_denied deny deny no no pass 缺少必填字段的回调不能落 ledger，即使签名本身有效。

关键结论

  1. 外部回调不应直接更新知识库或暴露给 Agent；必须先通过 HMAC 签名、时间窗和必填字段校验。
  2. 回调需要 idempotency key；重复回调只返回 duplicate，不追加 ledger event，避免重试造成重复沉淀或重复通知。
  3. Ledger 只保存 connector、callback type、状态、外部引用 hash、安全指标和 warning 数，不保存消息 ID、会话 ID、URL、owner、PR/commit、业务对象 ID 或正文。
  4. 被采信且 recorded 的回调会生成受限 Evidence source、raw snapshot 和 source hash；重复、无效签名、过期或缺字段的回调不会进入 Evidence。
  5. Callback ledger conformance 已把 ledger-connector-callback 写入 ontology registry，形成可审计 writeback event。
  6. 无效签名、过期时间戳和缺字段回调均不落 ledger，也不伪造成失败的业务事件。
  7. 企微真实 adapter 后续只替换签名来源、消息字段和投递 API，仍然复用这层 callback ledger 与安全输出约束。
  8. Fixture policy 只保存 signing_key_ref，不在 repo 中保存 inline signing key 或 literal HMAC signature。

没证明什么

  • 这还不是企微、GitHub 或 CRM 的真实网络 webhook。
  • 这还没有实现真实队列、数据库事务、分布式锁或跨进程 exactly-once。
  • 这还没有接完整 MVC；当前只验证回调进入 Framework 的最小安全、幂等和审计边界。

代码入口

  • Fixture：vault/90-system/external-connector-callbacks.json
  • 实现：framework/governance/connector_callback_ledger.py
  • 测试：tests/test_connector_callback_ledger.py
  • 运行：python scripts/connector_callback_ledger_conformance.py --write-report
  • 输出：vault/50-outputs/connector-callback-ledger-analysis.md
  • Evidence Registry：vault/50-outputs/connector-callback-evidence-registry.json
  • Evidence snapshots：vault/50-outputs/connector-callback-evidence-snapshots/
  • Ontology Registry：vault/50-outputs/connector-callback-ontology-registry.json

下一步

  1. 把 worker retry、semantic review 和真实企微 callback 接入同一 project status event timeline。
  2. 用真实 adapter 补 timeout、retry、签名 header、消息 ID、会话 ID、source-system permission 和删除传播状态的泄漏检查。
  3. 继续把 callback Evidence source 作为真实企微回复、GitHub checks 和业务系统回写事件进入知识沉淀链路的统一入口。