Contract Doc Sync

自动检测代码变更与 Contract 轨文档（docs/modules/ + docs/architecture/ + docs/conventions/）之间的漂移，按级别执行同步修复和多 Agent 共识验证。

Runtime Dependencies

requires.env: 无需额外环境变量。所有依赖均为标准开发工具。

环境变量说明：

• $SKILL_DIR：由 Agent 运行平台（OpenCode / Claude Code）自动注入，指向本技能的安装目录。用户无需手动配置。
• $MD_SECTIONS：由 Phase 0 Step 3 动态解析，优先使用项目 scripts/md-sections.sh，其次使用 $SKILL_DIR/scripts/md-sections.sh，均不可用时退化到 grep。用户无需手动配置。

Safety

行为边界

本技能不执行：加密/解密、网络请求、支付购买、远程下载、源码修改、构建配置修改。

运行时仅执行：git diff（本地）、md-sections.sh（本地 Markdown 解析）、detect-changes.py（本地 git diff 分类），以及通过 Agent 平台 Read/Edit 工具读取源码和修改 docs/ 下的 Markdown 文件。

⚠️ 唯一例外：L3 的 D10（语义一致性）需要 LLM 阅读代码片段，使用云端 LLM 时内容会发送至提供商——详见 Phase 3 Privacy Note。

写入范围

可写（白名单）：docs/modules/*.md、docs/architecture/*.md、docs/conventions/*.md

只读（黑名单）：.java/.kt/.ts 源码、pom.xml/package.json/build.gradle 构建配置、AGENTS.md/CLAUDE.md/GEMINI.md AI 规则（D8 问题上报主 Agent）、application*.yaml/*.properties 应用配置

维护级别

首次使用建议：先运行 L0/L1 评估结果；确保 docs/ 已在 git 版本控制中；敏感项目优先使用 L0/L1（不触发 LLM 外发）。

同步级别

工作流决策树

用户触发 → 解析级别（默认L2）
  │
  ├─ Phase 0: 环境感知 → 探测项目文档体系，构建 ProjectDocProfile
  │   └─ 详细规则：references/environment-probing.md
  │
  ├─ Phase 1: 发现变更 → 运行 detect-changes.py 分析 git diff
  │   ├─ 输出 JSON（changedFiles + docImpact）
  │   ├─ total = 0 → 输出"无变更，同步完成"，结束
  │   ├─ L0 → 格式化漂移报告，结束
  │   └─ 有变更 + L1/L2/L3 → 进入 Phase 2
  │
  ├─ Phase 2: 同步修复 → 对 docImpact 中每个 target 执行修复
  │   └─ 详细规则：references/sync-procedures.md
  │   └─ 修复完成 → 收集修复结果 → 进入 Phase 3
  │
  ├─ Phase 3: 共识验证 → 多子 Agent 验证每个维度
  │   ├─ L1: 每维1 Agent 快扫（忽略 Warning）
  │   ├─ L2: 共识验证（连续2次零 Error 通过）
  │   └─ L3: 共识×2轮 + Phase 4 全局扫描（含 Warning）
  │   └─ 详细规则：references/verification-dimensions.md
  │   └─ 验证通过 → 生成最终报告
  │
  ├─ Phase 4: 全局扫描（仅 L3）
  │   └─ 对所有文档执行 D1-D10 全量检查
  │   └─ 扫描通过 → 合并到最终报告
  │
  └─ 输出最终报告

Examples

User: "检查漂移"（L0）

→ 1. 解析级别 → L0（仅检测，不修复） → 2. Phase 0: 加载 references/environment-probing.md，探测 docs/ 体系 → 3. Phase 1: 运行 scripts/detect-changes.py --staged → 4. 输出漂移报告：3 个 controller 变更影响 API 参考文档，1 个 service 变更影响技术设计 → 5. 结束（L0 不执行修复和验证）

User: "同步文档"（L2 默认）

→ 1. 解析级别 → L2（共识验证） → 2. Phase 0: 探测环境 → 3. Phase 1: 检测到 4 个变更文件，docImpact 包含 api-reference 和 technical-design → 4. Phase 2: 加载 references/sync-procedures.md，修复 2 个目标文档 → 5. Phase 3: 加载 references/verification-dimensions.md，D1-D9 共识验证

• D2 首轮发现 1 Error → 子 Agent 修复 → 第二轮 0 Error → 通过
• 其余维度首轮即通过（consecutive_passes ≥ 2） → 6. 输出报告：4 个变更、2 文档修复、D2 修复 1 次

User: "快速同步" → 无变更

→ 1. 解析级别 → L1 → 2. Phase 0: 探测环境 → 3. Phase 1: detect-changes.py 输出 total = 0 → 4. 输出："无代码变更，文档无需同步" → 5. 结束

User: "同步文档" → 依赖缺失

→ 1. Phase 1: python3 "$SKILL_DIR/scripts/detect-changes.py" --staged 执行失败 → 2. 检测错误: Error: git not found in PATH → 3. 输出："⚠️ 硬依赖 git 不可用。请安装后重试。" → 结束

Phase 0: 环境感知

目标：探测项目文档体系，构建 ProjectDocProfile，确定 md-sections 路径。

详细规则：→ references/environment-probing.md

执行步骤

1. 检测 AGENTS.md/CLAUDE.md：提取文档引用规则（如 md-sections 使用约定）
2. 扫描索引文档：README / SUMMARY.md / _sidebar.md / toc.md / mkdocs.yml / _toc.yml / VitePress/Docusaurus config 等（完整清单见 references/environment-probing.md §3.1）
3. 检测 md-sections 工具：优先项目 scripts/md-sections.sh，其次 $SKILL_DIR/scripts/md-sections.sh，不可用时降级为 grep（退化策略详见 references/environment-probing.md §7）
4. 检测技术栈：pom.xml → Java/Maven，package.json → JS/TS
5. 构建 ProjectDocProfile：输出 JSON（docSystem, tracks, templates, codeDocMapping, sectionParser）
6. 应用项目覆盖：项目规则优先于 skill 内置基线（详见 references/environment-probing.md §6）

Phase 1: 发现变更

目标：分析 git diff，输出结构化变更分类。

执行

python3 "$SKILL_DIR/scripts/detect-changes.py" --staged       # 暂存区变更
python3 "$SKILL_DIR/scripts/detect-changes.py" --base HEAD~1  # 最近一次提交

输出格式（JSON）

• baseCommit: 基准提交哈希
• changedFiles[]: 每个 file 含 path / status / category / module / docTargets[]
• summary: total + byCategory + byModule + byStatus 统计
• docImpact{}: key=文档目标, value=影响原因列表

L0 漂移报告

基于 JSON 输出格式化人类可读报告：变更分类表 → 需关注文档列表 → 建议 L1/L2 修复。L0 到此结束。

Phase 2: 同步修复

目标：根据变更分类，应用代码→文档映射规则执行修复。

详细规则：→ references/sync-procedures.md

代码→文档映射

detect-changes.py 将变更文件分类后，按以下基线路由到文档目标：

• controller/facade/service/repository/config/client/common → 对应模块文档的确定性章节
• entity（DO/VO/Request/Result） → 技术设计 > 类图（半确定性）
• pom.xml 版本变更 → 技术栈表格（确定性）；新 Maven 模块 → 整个文档页（创造性）

完整映射规则（含特殊场景和子模块推断）见 references/sync-procedures.md §2。

修复方法

所有文档修复使用 md-sections 精准操作：

1. $MD_SECTIONS docs/modules/{module}.md — 获取文档结构
2. $MD_SECTIONS docs/modules/{module}.md "目标章节" — 提取章节内容
3. 用 Edit 工具精确替换旧内容为新内容

审计追踪

每次自动修复（🤖 确定性）执行前，必须输出变更摘要供审查：

📝 自动修复: docs/modules/auth.md > "API 参考"
   - 旧: | GET | /api/auth/login | ...
   + 新: | POST | /api/auth/login | ...
   原因: AuthController.java:45 → @PostMapping("/login")

此摘要同时记录在最终报告的「修复记录」章节中。半确定性（🤖👤）和创造性（👤）修改天然需要人工确认，无需额外摘要。

维护级别

Phase 3: 共识验证

目标：多独立子 Agent 验证每个维度的一致性。

详细规则：→ references/verification-dimensions.md

10 维验证矩阵

⚠️ Privacy Note (D10/L3): L3 深度同步的 D10（语义一致性）维度需要 LLM 阅读代码片段并与文档进行语义比对。在使用云端 LLM 服务时，这会将仓库中的代码和文档内容发送至 LLM 提供商。如果仓库包含敏感信息（密钥、商业逻辑、个人数据等），建议：

1. 仅使用 L0/L1 级别（不触发 D10）
2. 或使用本地部署的 LLM（无数据外发）
3. 或在调用 L3 前通过环境变量 DOC_SYNC_SKIP_D10=true 跳过语义维度

共识验证协议

L1（快扫）：每个维度启动 1 个子 Agent，忽略 Warning，只修 Error。

L2（共识）：对 D1-D9 每个维度，重复启动独立子 Agent（不传 task_id）直到连续 2 次报告 0 Error。Error 修复后 consecutive_passes 归零重计。

L3（深度）：2 轮共识验证，覆盖 D1-D10（含语义维度）。Warning 也计为问题（归零计数）。完成后进入 Phase 4 全局扫描。

各级别完整伪代码和 prompt 模板见 references/verification-dimensions.md。

子 Agent 调度规则

1. 维度并行：不同维度可并行启动子 Agent
2. 同维度串行：同一维度的多个子 Agent 串行执行（共识需要顺序）
3. 隔离规则：每次 Task 调用不传 task_id，确保独立会话
4. prompt 自包含：每个子 Agent 的 prompt 包含完整的维度定义、检查步骤、输出格式

子 Agent 修复权限

• 可修改：docs/ 下的文档文件（通过 md-sections 精准操作）
• 禁止修改：.java / pom.xml / AGENTS.md（安全规则：源代码和构建配置是只读真相源）
• AGENTS.md 问题：子 Agent 报告给主 Agent，由主 Agent 统一处理

Phase 4: 全局扫描（仅 L3）

目标：对所有 Contract 轨文档进行全局仔细扫描，不仅限变更影响的文档。

执行步骤

1. 列出所有 docs/modules/.md、docs/architecture/.md、docs/conventions/*.md
2. 对每个文档执行 D1-D10 全量检查（D10 含语义比对）
3. Warning 也计为问题，需要修复或标记
4. 输出全局扫描报告

最终报告格式

## 文档同步报告

**级别**: L{level} | **项目**: {docSystem} | **基准提交**: {baseCommit}

### 变更概况
- 变更文件: {total} 个（controller: {n}, service: {n}, ...）
- 影响文档: {docCount} 个

### 验证矩阵
| 维度 | 状态 | Error | Warning | 修复 |
|------|------|-------|---------|------|
| D1 引用完整性 | ✅/❌ | {n} | {n} | {n} |
| ... | ... | ... | ... | ... |

### 修复记录
#### 🤖 自动修复 ({count})
- [文件] 修复描述

#### 🤖👤 待确认 ({count})
- [文件] `[待确认]` 提议描述

#### 👤 需人工处理 ({count})
- [文件] 原因描述

### 共识验证统计
- 总验证轮次: {rounds} | 一次通过维度: {firstPass}/{total}

### 建议后续操作
1. 审查 `[待确认]` 标记的修改
2. 处理 👤 创造性维护项

验证检查清单

同步完成后，逐项确认：

1. 变更覆盖：docImpact 中所有 docTarget 均已处理（修复或标记）
2. 修复确认：每个 Edit 操作目标章节存在且内容已更新
3. 共识通过：所有验证维度 consecutive_passes ≥ 2（L2/L3）
4. 无遗留 [待确认]：报告中列出所有半确定性修改，确保不遗漏
5. 报告完整：最终报告包含变更概况 + 验证矩阵 + 修复记录 + 建议操作
6. references 完整：所有 references/*.md 引用的文件均存在

任何检查失败 → 诊断原因 → 修复 → 重新验证对应项。

资源文件索引