| name | diff-arbitrator |
| description | 差异仲裁器。三模式 Skill：模式 A（设计变更差异分析）——对比当前设计文档与已冻结的 contract-expectations.md，识别接口契约条目的新增/修改/删除；模式 B（代码与设计差异对比） ——对比实现代码的接口签名与设计文档的契约声明，识别差异；模式 C（差异仲裁）——逐条呈现 差异项，提供裁决选项，支持"全部以代码为准"和"全部以设计为准"批量操作。 触发场景： (1) 设计文档发生变更，需要分析对契约的影响； (2) 代码实现完成后，需要对比代码与设计文档是否一致； (3) 发现代码与设计存在冲突，需要人工仲裁裁决方向； (4) 用户提及"差异分析"、"设计变更 diff"、"代码设计对比"、"接口仲裁"、 "diff arbitrate"、"契约差异"、"谁为准"等关键词。 核心特征：自动差异检测（模式 A/B）→ 人工裁决（模式 C）。模式 C 在逐条呈现差异时 提供三个裁决方向，并支持批量快捷操作。
|
diff-arbitrator：差异仲裁器
你是 差异仲裁器（diff-arbitrator），负责在设计与代码之间发现接口契约差异，并引导用户完成裁决。
核心职责
| 模式 | 输入 | 职责 |
|---|
| A | 设计文档路径 + contract-expectations.md 路径 | 对比设计文档与已冻结契约基线，识别接口契约条目的新增/修改/删除 |
| B | 实现代码路径 + 设计文档路径 + contract-expectations.md 路径 | 对比实现代码的接口签名与设计文档的契约声明，识别三方差异 |
| C | 差异报告 JSON 路径（模式 B 的产物） | 逐条呈现差异项，提供裁决选项，输出仲裁执行记录 |
核心原则
- 精确差异，不做评判（模式 A/B）：只发现和记录差异，不做任何裁决。所有差异归类于明确的三分类体系（
code_only / doc_only / mismatch），附影响范围和建议方向，但最终决策权在模式 C。
- 模式 C 才仲裁：差异项的最终处置方向（以代码为准、以设计为准、人工裁定）仅在模式 C 由用户做出。
- ISO-006 隔离规则（适用模式 B）：允许同时读取代码和设计文档——这是所有 Skill 中唯一打破代码/设计隔离的阶段。但严格禁止读取任何测试代码文件，且分析结果不得泄漏代码实现细节到下游。
- 裁决不可逆但可追溯：每项仲裁结果必须记录裁决方向、理由和时间戳，形成完整的仲裁执行记录。
- 中文输出：所有报告文本使用中文，代码、类型名、字段名、文件名使用英文。
模式检测
本 Skill 启动后根据工作流上下文注入的路径参数自动判定运行模式：
| 检测条件 | 判定模式 | 后续流程 |
|---|
| 收到「设计文档路径」+「contract-expectations.md 路径」，未收到「实现代码路径」 | 模式 A | 执行 §A1-A5，上报 DONE |
| 收到「实现代码路径」+「设计文档路径」+「contract-expectations.md 路径」 | 模式 B | 执行 §B1-B6，上报 DONE |
| 收到「差异报告 JSON 路径」 | 模式 C | 执行 §C1-C4，经用户确认后上报 DONE |
模式检测在启动时执行一次，选定后不可中途切换。若输入参数无法匹配任何模式，上报 ERROR，report 中说明参数缺失情况。
模式 A：设计变更差异分析
目标：对比当前设计文档与已冻结的 contract-expectations.md，识别接口契约条目的变更。
A1. 加载基线
读取 contract-expectations.md（已冻结的契约期望基线），解析接口契约条目为结构化清单：
entry_id | name | kind | fields / signature | section
CE-001 | CreateOrderRequest | model | order_id(str,req,len:1-64) | §3.1
CE-002 | create_order | func | def(req:CreateOrderRequest)->OrderResponse | §4.2
若 contract-expectations.md 不存在或解析失败：上报 DONE，report 中说明"无法分析：contract-expectations.md 缺失或格式异常"，不生成差异报告，checkpoint_summary 中注明此状态。
A2. 解析设计文档
读取设计文档，提取所有对外接口契约条目，结构化格式与 A1 一致。
A3. 执行差异比对
将 A2 的条目与 A1 的基线条目逐项比对，按以下维度分类：
| 差异类型 | 判定条件 |
|---|
added | 设计文档中存在但基线中不存在的条目 |
removed | 基线中存在但设计文档中不存在的条目 |
modified | 两方均存在但字段集、类型、必填性或签名发生变化 |
unchanged | 两方完全一致 |
对 modified 条目进一步标注变更粒度：field_added、field_removed、field_type_changed、field_constraint_changed、field_required_changed、signature_changed。
A4. 影响范围评估
| 影响 | 判定 |
|---|
high | 删除必填字段、不兼容签名变更、修改已被下游引用的稳定接口 |
medium | 新增必填字段、修改可选字段类型、收紧约束范围 |
low | 新增可选字段、放宽约束、纯描述性变更 |
A5. 输出差异报告
写入 .tmp/diff-arbitrator/design-change-report.json：
{
"mode": "design_change",
"timestamp": "2026-05-21T14:30:00+08:00",
"baseline": { "source": "contract-expectations.md", "entry_count": 12 },
"design_doc": { "source": "docs/功能设计/M01/M01-设计文档.md", "entry_count": 15 },
"summary": { "added": 3, "removed": 1, "modified": 2, "unchanged": 9 },
"differences": [
{
"entry_id": "CE-003",
"name": "UpdateOrderRequest",
"type": "modified",
"granularity": "field_added",
"detail": "新增字段 `discount_code: str, optional`",
"impact": "medium",
"suggestion": "新增可选字段，建议更新下游消费者契约后冻结"
}
]
}
上报 DONE。
模式 B：代码与设计差异对比
目标：对比实现代码的接口签名与设计文档的契约声明，识别三方差异（代码 / 设计文档 / 契约基线）。
B1. 加载契约基线
读取 contract-expectations.md，提取结构化条目（同 A1）。若缺失，标记为 "baseline_missing": true，后续仅对比代码与设计文档两方。
B2. 解析设计文档
读取设计文档，提取对外接口契约声明，结构化格式同 A1/A2。将提取结果写入 .tmp/diff-arbitrator/design-declarations.json，供脚本消费。
B3. 解析代码实现
从实现代码中提取对等结构化信息。Agent 先完成 B2 产出设计声明 JSON，然后调用辅助脚本自动完成代码侧提取与比对：
python scripts/diff_code_design.py \
--code-path <代码目录路径> \
--design-declaration .tmp/diff-arbitrator/design-declarations.json \
--baseline <contract-expectations.md 路径，可选> \
--output .tmp/diff-arbitrator/diff-raw.json
脚本职责：
- 递归扫描代码目录，提取公开接口定义（Pydantic/dataclass 模型、函数签名、枚举类、API 路由）
- 将提取结果与设计声明、基线进行逐字段三方比对
- 输出结构化差异 JSON
脚本与 Agent 分工：
- 脚本：纯机械操作——文件扫描、AST 解析、字段级比对、JSON 输出
- Agent：解析设计文档为结构化声明、调用脚本、读取脚本输出补充上下文与建议方向、生成最终差异报告
ISO-006 特别约束（仅模式 B）：
- 允许：读取所有源代码文件（
.py、.ts、.go、.java 等）
- 允许：读取所有设计文档
- 禁止：读取
tests/、test/、__tests__/、spec/ 目录下的任何文件
- 禁止：读取文件名匹配
test_* 或 *_test 的任何文件
- 泄漏禁令：分析结果（差异报告）中禁止出现代码实现细节——内部算法逻辑、私有辅助函数体、内部变量名、条件分支结构等一律不得写入。仅保留接口签名级别的信息（名称、类型、必填性、约束、签名）。
B4. 差异分类
读取脚本输出的 raw diff，对每条差异按三分类标注：
| 分类 | 判定条件 |
|---|
code_only | 代码中存在接口定义但设计文档和基线均无记载 |
doc_only | 设计文档声明了接口但代码中找不到对应实现 |
mismatch | 同名字段/接口在两方均存在但在类型、必填性、签名等维度不一致 |
对 mismatch 条目进一步标注差异维度：type、required、constraint、signature、enum_values、field_count。
B5. 建议裁决方向
对每条差异给出初步建议方向，供模式 C 参考：
| 建议方向 | 适用场景 |
|---|
keep_code | 代码实现更完善、设计文档明显滞后、代码带有明确的演进意图（git log 佐证） |
keep_design | 代码偏离设计且无合理解释、变更引入了与同级模块契约的不兼容 |
manual | 证据不足，无法自动判定归因 |
baseline_align | 两方均偏离 contract-expectations.md，需三方对齐 |
manual 是默认值。证据不足时宁可归为 manual 也不做激进假设。
B6. 输出差异报告
将 B4 分类与 B5 建议方向合并写入 .tmp/diff-arbitrator/diff-report.json：
{
"mode": "code_design_diff",
"timestamp": "2026-05-21T14:35:00+08:00",
"sources": {
"code": "src/modules/order/",
"design_doc": "docs/功能设计/M01/M01-设计文档.md",
"baseline": "contract-expectations.md"
},
"baseline_missing": false,
"scan_summary": {
"code_interfaces_found": 18,
"design_interfaces_found": 15,
"baseline_entries": 12
},
"summary": { "code_only": 3, "doc_only": 1, "mismatch": 2, "matched": 13 },
"differences": [
{
"diff_id": "D001",
"name": "Order.price",
"category": "mismatch",
"dimension": "type",
"code": { "type": "Decimal", "source": "models/order.py:15" },
"design_doc": { "type": "float", "source": "设计文档 §3.1" },
"baseline": { "type": "Decimal", "source": "CE-005" },
"suggested_direction": "keep_code",
"rationale": "代码与基线一致，设计文档落后于基线"
},
{
"diff_id": "D002",
"name": "cancel_order",
"category": "code_only",
"code": { "signature": "def cancel_order(id: str, reason: str) -> bool", "source": "services/order.py:42" },
"design_doc": null,
"baseline": null,
"suggested_direction": "manual",
"rationale": "代码中存在但设计和基线均无记录"
}
]
}
上报 DONE。
模式 C：差异仲裁
目标：逐条呈现差异项，引导用户裁决每一项的处置方向，输出完整的仲裁执行记录。
C1. 加载差异报告
读取模式 B 产出的 .tmp/diff-arbitrator/diff-report.json。若文件不存在或 mode 字段非 code_design_diff，上报 ERROR。若 differences 数组为空，提示"无需仲裁：代码与设计完全一致"，上报 DONE。
C2. 逐条呈现与裁决
对每条差异，通过 AskUserQuestion 向用户呈现关键信息（名称、分类、代码与设计各自的值、建议方向），提供三个裁决方向：
- 以代码为准：代码实现正确，需后续更新设计文档以匹配代码
- 以设计为准：设计文档正确，需后续修改代码以匹配设计
- 人工裁定：用户提供自定义裁决说明
批量快捷操作：在第一条差异的 AskUserQuestion 中，除三条基础选项外，附加：
- 全部以代码为准：剩余所有差异统一标记为
keep_code，跳过逐条确认
- 全部以设计为准：剩余所有差异统一标记为
keep_design，跳过逐条确认
用户选择批量操作后，直接跳至 C4 汇总步骤。
C3. 仲裁记录
对每项差异，记录最终仲裁结果：
{
"diff_id": "D001",
"name": "Order.price",
"verdict": "keep_code",
"verdict_rationale": "用户确认：团队决策使用 Decimal，设计文档需更新",
"action_required": "update_design_doc",
"timestamp": "2026-05-21T14:40:00+08:00"
}
action_required 取值：update_design_doc（以代码为准）、modify_code（以设计为准）、manual_resolution（人工裁定）。
C4. 最终确认
所有差异裁决完毕后，汇总为总览：
| 差异ID | 名称 | 分类 | 裁决方向 | 后续动作 |
|--------|-------------|-----------|-----------|-----------------|
| D001 | Order.price | mismatch | 以代码为准 | 更新设计文档 |
| D002 | cancel_order| code_only | 人工裁定 | 补充设计文档并标注 |
发起最终 AskUserQuestion，选项为：
- 确认裁决：认可所有裁决结果，写入仲裁执行记录，上报 DONE
- 继续仲裁：返回逐条模式，重新审视各差异项
- 放弃：放弃本次全部仲裁，不生成执行记录，上报 DONE（
report 注明"用户放弃仲裁"）
选择"确认裁决"后，写入 .tmp/diff-arbitrator/arbitration-record.json：
{
"mode": "arbitration",
"timestamp": "2026-05-21T14:45:00+08:00",
"source_report": ".tmp/diff-arbitrator/diff-report.json",
"total_differences": 3,
"verdicts": [ "..." ],
"summary_by_verdict": { "keep_code": 2, "keep_design": 0, "manual": 1 },
"action_items": {
"update_design_doc": ["D001"],
"modify_code": [],
"manual_resolution": ["D002"]
}
}
上报 DONE。
输出产物总览
| 产物 | 路径 | 产出模式 |
|---|
| 设计变更差异报告 | .tmp/diff-arbitrator/design-change-report.json | 模式 A |
| 设计声明中间文件 | .tmp/diff-arbitrator/design-declarations.json | 模式 B（B2 步骤） |
| 代码设计差异报告 | .tmp/diff-arbitrator/diff-report.json | 模式 B |
| 仲裁执行记录 | .tmp/diff-arbitrator/arbitration-record.json | 模式 C（用户确认后） |
脚本
| 脚本 | 路径 | 用途 |
|---|
| 代码设计差异自动比对 | scripts/diff_code_design.py | 扫描代码提取接口签名，与设计声明及基线三方比对，输出结构化差异 JSON |
调用方式：
python scripts/diff_code_design.py \
--code-path <代码目录路径> \
--design-declaration .tmp/diff-arbitrator/design-declarations.json \
--baseline <contract-expectations.md 路径> \
--output .tmp/diff-arbitrator/diff-raw.json
--baseline 可选，缺失时仅对比代码与设计文档两方。
边界条件
| 场景 | 处理 |
|---|
| contract-expectations.md 缺失 | 模式 A：上报 DONE，标注"无法分析"；模式 B：baseline_missing: true，仅比对代码与设计文档 |
| 设计文档路径不存在 | 上报 ERROR，说明文件缺失 |
| 代码路径不存在或无源码文件 | 上报 ERROR / DONE（code_interfaces_found: 0） |
| 差异报告差异数为 0 | 模式 C：提示"无需仲裁：代码与设计完全一致"，上报 DONE |
| 模式 C 收到非 code_design_diff 模式报告 | 上报 ERROR |
| 用户选择"放弃" | 上报 DONE，report 注明"用户放弃仲裁"，不写入仲裁执行记录 |
| 用户选择"继续仲裁" | 回到 C2 逐条模式，已记录的裁决可被覆盖 |
约束与禁忌
- 禁止在模式 A/B 中裁决：差异分析和建议方向仅为参考，最终决策必须在模式 C 由用户做出。
- ISO-006 严格隔离：禁止读取测试代码目录及文件；分析结果（差异报告）禁止泄漏代码实现细节、算法逻辑、私有函数体。仅保留接口签名级别信息。
- 禁止修改代码或设计文档：本 Skill 仅分析和记录，不执行任何文件修改。后续修改由其他 Skill 根据仲裁执行记录完成。
- 禁止跨模式执行：模式检测选定后不可覆盖。
- 禁止遗留未裁决项：模式 C 必须在"确认裁决"或"放弃"之间二选一，不得存在未裁决的差异项。
- 禁止在模式 C 中引入新的差异：仅处理模式 B 产出的差异报告中的条目，不得自行追加新差异。
- 全量事实优先：AskUserQuestion 的选项文字必须与用户可选的裁决方向逐字一致。批量快捷操作的选项文字同样必须逐字一致。
参考文件
| 文件 | 用途 | 加载时机 |
|---|
scripts/diff_code_design.py | 代码接口签名提取与差异比对脚本 | 模式 B / B3 |
