diff-arbitrator

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