| name | api-contract-consistency-validator |
| description | 校验业务代码与 IDL 契约同步、字段冻结状态是否被破坏。作为 8 维度 code review 的"契约一致"维度，可被 design-checker / code-review-preparer 调用，也可独立运行。 |
| allowed-tools | Read, Bash, Glob, Grep |
Skill: api-contract-consistency-validator
原文 §8.3 把契约一致定位为 Skill（不是 Agent），因为它是一组确定性检查——无需主观判断，只需机械比对 diff 与契约状态。
输入
{
"feature_ids": ["FT-001"],
"commit_range": "abc..def",
"business_diff_path?": "...",
"idl_diff_path?": "..."
}
检查项
| ID | 检查 | 阻塞 |
|---|
| K1 | feature 标记 idl_change: true → IDL 仓必须存在对应 diff | YES |
| K2 | feature 标记 idl_change: false → 业务 diff 中不允许引用新 IDL 字段 | YES |
| K3 | IDL 中带 frozen: true 注释/标记的字段，禁止类型/语义变更 | YES |
| K4 | 业务代码引用的 IDL 字段必须存在（防止编译期不报但运行期 panic） | YES |
| K5 | 新增 IDL 字段必须有默认值或 optional 标记（向后兼容） | YES |
| K6 | detail-design.md 的"IDL 变更"小节覆盖了本次 IDL diff（字段一致、版本号一致） | YES |
| K7 | 同名分支策略：业务仓改 IDL 字段 → IDL 仓必须有同名分支 | YES（已在 4.3 门禁覆盖，这里再次确认） |
工作流
- 解析
tasks/features.json → 找出 idl_change=true 的 features
git -C {idl-repo} diff 取 IDL diffgit -C {business-repo} diff 取业务 diff- 解析两份 diff 的字段引用
- 对照 detail-design.md 的"IDL 变更"小节
- 输出结构化结论
输出
{
"skill": "api-contract-consistency-validator",
"verdict": "PASS|WARN|FAIL",
"findings": [
{ "id": "K3", "file": "{idl-repo}/coupon.jce", "line": 24,
"issue": "frozen 字段 user_ids 类型从 list<int> 改为 list<string>",
"suggestion": "新增 user_ids_v2 字段，保持兼容" }
]
}
调用方
code-review-preparer Agent 在阶段 4.4 把它作为第 6 维度调用detail-design-quality-reviewer 在阶段 3.3 调用其中 K5/K6 做设计期 IDL 预审- CLI 直接调用：
/agentic:check-contract
与 Agent 的边界
- Skill = 确定性检查，输出结构化数据
- Agent = 可能调用多个 Skill，做综合判断，写门禁文件
