01
Contract · workflow

cross-repo-contract-alignment

01-cross-repo-contract-alignment.md
⛓️
P0 source: codex-sessions created: 2026-06-13
◉

WHAT IS THIS

定位

跨仓库契约对齐 workflow。适合一个功能横跨 producer、consumer、CLI、desktop、agent runtime、多端 SDK 时使用。

这个 workflow 的核心判断是：不要先在 consumer 侧补适配层。先确认 owner repo 的 contract 是否稳定，再决定 consumer 应该接什么。

⚡

TRIGGERS

触发场景
▸CLI、frontend、desktop、agent 调用同一个后端能力，但字段、状态、错误语义不一致。
▸一个 repo 的测试通过了，真实链路仍然失败。
▸新增 API 后，需要同步 SDK、CLI、docs、schema cache。
▸历史里出现过“只改 client，最后发现 server contract 才是根因”。
▸多个 repo 都有同名 capability，但语义或状态机不同。
▸Agent capability、tool schema、UI 展示层都声称支持同一能力，但运行时证据不一致。
▸登录、token exchange、callback、tool backend auth 横跨多个 repo，需要确认 canonical token flow。
↹

INPUT & OUTPUT

输入 / 产出
↘ INPUT
  • 相关 repo 列表。
  • 已知失败症状或目标能力名。
  • Producer contract 文件，比如 OpenAPI、DTO、schema、API handler、event type。
  • Consumer 调用点，比如 CLI command、frontend action、desktop adapter、agent tool。
  • 运行时证据，比如 session id、audit log、tool call、DB row、network trace，可选。
  • 当前测试命令和部署 smoke 命令。
↗ OUTPUT
  • Contract owner repo 的修复或确认文档。
  • Consumer repo 的最小接入改动。
  • Contract tests 和 integration tests。
  • 每个 repo 独立 commit，commit message 说明该 repo 在链路里的职责。
  • 一个最终对齐报告，列出 producer、consumer、docs、tests 的状态。
🪜

STEPS

编排步骤
  1. 1
    建立能力地图
    用 rg 找 capability 名称、endpoint、DTO、schema、command 名。输出 producer 和 consumer 两张表。
  2. 2
    锁定 owner repo
    判断哪个 repo 定义了真实 contract。通常是 API server、shared schema package、agent runtime，而不是 CLI 或 UI。
  3. 3
    读 owner contract
    检查字段命名、状态枚举、错误 envelope、鉴权要求、分页和版本策略。不要从 consumer 代码反推 contract。
  4. 4
    写 contract alignment note
    在 owner repo 里补一份短文档，说明 canonical contract、兼容策略、迁移边界。
  5. 5
    先补 owner tests
    补 list/get/call、状态转换、错误响应、schema 兼容测试。测试先失败，再改实现。
  6. 6
    Consumer 接入 canonical contract
    删除本地重复解析、兼容假设、手写状态映射。只保留 domain 级配置和展示逻辑。
  7. 7
    同步文档和例子
    更新 CLI reference、API docs、README、PRD 状态字段。文档必须引用 canonical contract。
  8. 8
    跑端到端 smoke
    从用户入口发起调用，经过 consumer 到 producer，再验证输出和错误语义。
  9. 9
    分流专门审计
    如果根因落在 agent session 运行时，转 →#18；如果落在 tool schema 和 side effect，转 →#21；如果落在 token exchange，转 →#23。
⚙

AGENT ROLES

Agent 分工
⚙
Contract Mapper
扫描 repo，产出 producer/consumer 能力地图。
⚙
Owner Contract Agent
只负责 owner repo 的 contract 和 tests。
⚙
Consumer Agent
只负责接入 canonical contract，不改 owner repo。
⚙
Docs Agent
同步 reference、PRD、ADR、README。
⚙
Verifier Agent
独立跑 smoke，检查是否仍有本地适配层。
✓

ACCEPTANCE GATE

验收 gate
⊘

FAILURE HANDLING

失败处理
⊘
如果 owner contract 不清楚，先停下来写 ADR，不继续实现。
⊘
如果 consumer 需要兼容旧 contract，必须写明兼容期限和删除条件。
⊘
如果无法跑全链路 smoke，至少保留可复现的 curl、CLI command 或 fixture。
⊘
如果 contract 看起来一致但真实用户仍失败，不在 consumer 侧继续补猜测逻辑，改走运行时证据链。
⌘

TEMPLATE

最小落地模板
TEMPLATE
## Contract Alignment

- Capability:
- Owner repo:
- Consumers:
- Canonical request:
- Canonical response:
- Error envelope:
- State enum:
- Compatibility policy:
- Tests added:
- Smoke command: