aps-agent/docs/round-2-contract-gate-plan.md

第 2 轮工作计划（轻量合并版）：契约漂移门禁补全

更新日期：2026-08-01

1. 本轮目标

把三个公共排产契约（scheduling_problem.schema.json / scheduling_solution.schema.json / plan_node.schema.json）纳入 tests/golden/test_contract_sync.py 的跨层契约校验链（schema ↔ Python DTO ↔ 消费方），并增加不兼容消费者测试与文档清单门禁；矩阵 M0「跨层契约和文档同轮同步」由 Partial 升为 Done。

2. 背景和当前状态

• 当前已完成：test_contract_sync.py 已覆盖 intent/ui_block/viewport_command/schedule_result 四个契约的三方一致性（schema 枚举/必填 ↔ pydantic ↔ TS literal union），并有 InterfaceGate 启动握手测试；scheduling_problem/scheduling_solution 的 Python 模型在 server/aps_domain/scheduling_dto.py，plan_node 的模型在 server/agent_core/plan_runtime.py（PlanLayer/PlanStatus/PlanCreator 枚举与 schema 一致，字段集合一致）。
• 当前缺口：三个公共排产契约未进入校验链；无"不兼容消费者"回归测试；无文档清单门禁（docs/README.md 目录与契约文件的对应关系无自动化检查）。
• 本轮为什么现在做：矩阵 P0 批次点名「三层契约漂移门禁已有可运行首切片」，剩余验收标准为"增加契约生成/差异检查和文档清单门禁，漂移直接阻断合并"。
• Workspace preflight：第 1 轮（证据链 v1）已收口（425 passed / 审计 PASS）；共享脏工作区、无提交。
• 方向分析：Q1 推荐选项 C（契约漂移门禁），目标续跑轮授权执行。

3. 本轮工作方向

test_contract_sync.py（4 契约覆盖）
-> 扩展校验链：scheduling_problem / scheduling_solution / plan_node（schema ↔ Python DTO ↔ 消费方）
-> 不兼容消费者测试：Schema 漂移（删字段/改枚举）→ 校验失败
-> 文档清单门禁：docs/README.md 契约目录 ↔ shared/schemas/*.json 一一对应
-> 全量黄金测试 + 矩阵 M0 行 → Done

4. 已确认决策

任务重量：

• 档位：轻型（单测试域：test_contract_sync.py + docs/README.md；集成点唯一：黄金测试）。
• 规模依据：核心改动集中在 tests/golden/test_contract_sync.py 与 docs/README.md；无生产代码行为变化，风险 LOW。
• 选择原因：纯门禁/测试工程，直接服务 P0 批次验收出口「契约三方一致」。

P0/P1 决策（按 Q1 推荐采纳）：

• 决策 1（P0）：本轮切片 = 契约漂移门禁补全（选项 C）。
• 决策 2（P1）：不新建分支、不提交、不推送（沿用共享脏工作区约束）。
• 决策 3（P1）：验证深度 = 聚焦 test_contract_sync + 全量黄金回归。

默认假设：

• 假设 1：scheduling_problem/scheduling_solution 的 TS 消费方 = apps/web/src/skills/SkillConsole.tsx 只读展示（不做强类型消费），因此校验重点为 schema ↔ Python DTO 一致 + 网关契约端点返回可用。
• 假设 2：plan_node 消费方 = server/agent_core/plan_runtime.py（模型）与 server/gateway/plan_api.py（API），TS 无独立类型，校验 schema ↔ Python 模型一致。
• 假设 3：不兼容消费者测试用「schema 漂移注入」模拟：删除/改名 schema 字段或枚举 → 断言校验函数检测到漂移。

未决但不阻塞：契约生成自动化（从 schema 生成 pydantic/TS）留待后续轮次，本轮先做差异检查门禁。

5. 范围

In scope:

• tests/golden/test_contract_sync.py：新增三个契约的 schema↔Python 校验（字段集合、必填、枚举）、网关契约端点冒烟、不兼容消费者（漂移注入）测试。
• docs/README.md：文档清单门禁（列出全部 shared/schemas 契约与对应消费方文档）；必要时补一个 docs/product/contracts.md 或复用现有文档。
• docs/product/plan-completion-matrix.md：M0 契约行 Partial → Done。
• docs/CHANGELOG.md：追加本轮条目。

Out of scope:

• 契约生成器（schema → pydantic/TS 自动生成）；前端强类型化三个契约；任何生产代码行为变化。
• 提交/推送/合并/清理用户改动。

6. 成功标准

• python -m pytest -q tests/golden/test_contract_sync.py -p no:cacheprovider 全部通过（原 6 项 + 新增）。
• 全量 python -m pytest tests/golden -q -p no:cacheprovider（固定 .venv 运行时）通过，≥ 425。
• python -m ruff check 改动文件干净。
• git diff --check 无空白错误；git status 仅本轮文件。

7. 验证方式

• 聚焦：python -m pytest -q tests/golden/test_contract_sync.py -p no:cacheprovider
• 回归：全量黄金套件。
• 静态：ruff + git diff --check。

8. 关键风险

风险	影响	控制方式
三个契约存在真实漂移导致新测试失败	需要修复模型/schema	先核对再断言；漂移修复限定契约文件
SkillConsole 只读展示被误判为消费方	校验范围偏差	明确 TS 侧为展示型消费，校验 schema↔Python 为主
文档清单门禁误伤	无关文档改动触发失败	门禁只检查契约目录 ↔ docs 映射，不做全量文档校验

9. 停止条件

• 全量黄金测试出现非本轮相关回归且无法快速定位时暂停。
• 任何需要提交/推送/合并/清理用户改动的操作一律停下等待授权。

10. 本轮完成定义

• 实现、测试、审计、文档全部完成；聚焦与全量验证通过；矩阵与 CHANGELOG 回写；不提交。
• 收口：向用户报告主要结论、关键洞察、需要特别留意的地方。

11. 下一步

轻量合并版：主 agent 实现 + 验证 + 收口报告。