anian0/skills/project-doc-sync

项目文档同步更新 Skill

概述

本skill用于在项目迭代过程中，自动化维护 docs/项目最新概况 目录下的功能模块文档，确保文档与代码保持一致。

核心流程：

1. 评估阶段：并行派发subagent检查现有文档是否需更新 + 评估是否需新增文档
2. 确认阶段：汇总建议，用户确认
3. 执行阶段：并行派发subagent执行文档更新/新增
4. 审查阶段：并行派发subagent审查文档质量，循环修复直到通过

---

工作流程

第一步：收集改动范围信息

用户输入： 用户需指定git改动范围，如：

• HEAD~3..HEAD - 最近3个commit
• abc123..def456 - 指定commit范围
• main..feature-branch - 分支对比

操作： 执行 git diff <range> 和 git log <range> --oneline 获取变更内容和commit信息，整理成结构化摘要供后续subagent使用。

---

第二步：评估现有文档是否需要更新

目标： 检查每个现有文档是否涉及本次改动，评估更新必要性。

操作：

1. 列出 docs/项目最新概况 下所有 .md 文件
2. 为每个文档派发一个独立的subagent（并行执行）

Subagent任务模板：

你是一个文档评估agent。

**改动摘要：**
{本次改动的结构化摘要}

**待评估文档：**
{文档路径}

**任务：**
1. 读取该文档内容，理解其覆盖的功能范围
2. 分析改动内容是否涉及该文档描述的功能
3. 评估文档是否需要更新：
   - **需要更新**：改动修改了文档中描述的实现细节、API接口、数据结构、文件路径等
   - **不需要更新**：改动与该文档功能无关，或仅涉及文档未覆盖的边缘逻辑

**输出格式（JSON）：**
{
  "doc_path": "文档路径",
  "doc_topic": "文档覆盖的功能主题",
  "is_affected": true/false,
  "update_needed": true/false,
  "reason": "判断理由",
  "suggested_updates": [
    {
      "section": "章节名称",
      "current_content_summary": "当前内容简述",
      "change_description": "需要修改的内容描述",
      "priority": "high/medium/low"
    }
  ]
}

**重要约束：**
- 只做评估，不要修改任何文档
- 基于文档内容判断，不要猜测

---

第三步：评估是否需要新增文档

目标： 探索本次改动是否引入了新的独立功能模块，需要新增文档。

操作： 派发一个独立的subagent执行此任务。

Subagent任务模板：

你是一个文档规划agent。

**改动摘要：**
{本次改动的结构化摘要}

**现有文档列表：**
{列出所有现有文档的名称和主题}

**任务：**
1. 分析改动内容，识别引入的新功能或模块
2. 判断是否需要新增文档：
   - **需要新增**：改动引入的功能模块，**历史文档未覆盖**，且**没有任何现有指导说明**
   - **不需要新增**：功能已被现有文档覆盖，或仅是现有功能的扩展/修复

3. 若需要新增，规划文档结构：
   - 建议的文档编号（延续现有编号序列）
   - 文档名称
   - 应包含的章节概要

**输出格式（JSON）：**
{
  "new_doc_needed": true/false,
  "reason": "判断理由",
  "proposed_doc": {
    "number": "建议编号",
    "name": "建议名称",
    "topic": "覆盖功能主题",
    "sections_outline": [
      "系统架构",
      "数据库设计",
      ...
    ],
    "key_files_to_document": ["关键文件路径列表"]
  }
}

**重要约束：**
- 只做评估，不要创建任何文档
- 新文档条件：历史文档未覆盖 + 无现有指导说明
- 与现有文档主题独立，避免内容重叠

---

第四步：汇总建议，用户确认

操作：

1. 收集所有subagent的评估结果
2. 生成汇总报告：

## 文档更新评估汇总

### 现有文档评估结果

| 文档 | 是否涉及 | 是否需更新 | 优先级 | 建议修改内容 |
|------|----------|------------|--------|--------------|
| ... | ... | ... | ... | ... |

### 新增文档评估

- 是否需要新增：{yes/no}
- 若需要：{文档规划详情}

### 执行计划

- 待更新文档数量：{N}
- 待新增文档数量：{M}
- 预计涉及的文件操作：{列表}

---

**请确认是否执行上述更新计划？**
- 确认后我将并行派发subagent执行文档更新
- 您可以提出修改意见，调整更新内容

3. 使用 AskUserQuestion 等待用户确认：
   • 用户确认：继续执行
   • 用户提出意见：根据意见调整计划后重新确认
   • 用户拒绝：终止流程

---

第五步：执行文档更新

条件： 用户确认后执行

操作： 根据待更新/新增的文档数量，并行派发多个subagent执行更新任务。

Subagent任务模板（更新现有文档）：

你是一个文档更新agent。

**任务：**
更新文档 `{文档路径}`，使其反映最新的代码实现。

**改动信息：**
{相关的改动摘要}

**更新建议：**
{评估阶段的suggested_updates}

**文档标准格式：**
所有文档必须遵循以下结构：
1. 文档目的（> 引用块）
2. 系统概述
3. 技术栈
4. 目录（带锚点链接）
5. 系统架构
6. 数据库设计（如适用）
7. 后端实现
8. 前端实现（如适用）
9. 使用指南
10. 注意事项
11. 相关文件清单（表格形式）
12. 创建时间/版本（更新时修改版本号）

**操作要求：**
1. 先读取当前文档内容
2. 读取相关代码文件，确认实际实现
3. 按标准格式更新文档，确保：
   - 内容准确性：描述与代码一致
   - 内容全面性：覆盖该功能的所有关键实现点
   - 文件清单完整：列出所有相关文件路径
4. 更新版本号和最后更新时间

**输出：**
完成更新后，输出更新摘要（修改了哪些章节，关键变更点）。

Subagent任务模板（新增文档）：

你是一个文档创建agent。

**任务：**
创建新文档 `{文档路径}`，记录 `{功能主题}` 的完整实现。

**改动信息：**
{相关的改动摘要}

**文档规划：**
{评估阶段的proposed_doc}

**文档标准格式：**
（同上）

**操作要求：**
1. 探索相关代码文件，理解功能实现
2. 按标准格式创建文档
3. 确保内容准确、全面
4. 在文档末尾标注创建时间

**输出：**
完成创建后，输出文档内容摘要。

---

第六步：文档审查

目标： 确保更新后的文档质量达标。

审查标准：

1. 内容准确性：文档描述与实际代码实现一致
2. 内容全面性：覆盖该功能的所有关键点（API、数据结构、核心流程）
3. 格式规范性：符合标准文档模板结构
4. 文件清单完整性：相关文件清单列出所有涉及的文件路径

操作： 为每个更新/新增的文档派发一个subagent执行审查。

Subagent任务模板：

你是一个文档审查agent。

**任务：**
审查文档 `{文档路径}` 的质量。

**审查标准：**
1. 内容准确性：文档描述与代码实现是否一致
2. 内容全面性：是否覆盖所有关键实现点
3. 格式规范性：是否符合标准模板结构
4. 文件清单完整性：是否列出所有相关文件

**操作：**
1. 读取文档内容
2. 读取文档中提到的关键代码文件
3. 对每个审查项给出评分和具体问题列表

**输出格式（JSON）：**
{
  "doc_path": "文档路径",
  "accuracy": {
    "score": 1-5,
    "issues": ["具体问题列表"]
  },
  "completeness": {
    "score": 1-5,
    "issues": ["具体问题列表"]
  },
  "format": {
    "score": 1-5,
    "issues": ["具体问题列表"]
  },
  "file_list": {
    "score": 1-5,
    "issues": ["具体问题列表"]
  },
  "overall_pass": true/false,
  "fix_suggestions": ["修复建议列表"]
}

**重要：**
- 只做审查，不要修改文档
- 给出具体、可操作的修复建议

---

第七步：审查结果处理

判断：

• 所有文档 overall_pass === true：流程完成
• 存在未通过的文档：进入修复循环

修复循环：

1. 汇总所有未通过文档的问题
2. 并行派发subagent执行修复（每个未通过文档一个subagent）
3. 修复完成后，重新派发审查subagent
4. 重复直到所有文档通过

修复Subagent任务模板：

你是一个文档修复agent。

**任务：**
修复文档 `{文档路径}` 的质量问题。

**审查结果：**
{审查输出的JSON}

**操作：**
1. 根据审查结果中的fix_suggestions逐项修复
2. 确保修复后满足审查标准
3. 不改变文档的核心结构，只修正具体问题

**输出：**
完成修复后，输出修复摘要。

---

第八步：完成报告

所有文档通过审查后，输出完成报告：

## 文档同步更新完成

### 更新文档
- {文档列表}

### 新增文档
- {文档列表}

### 审查结果
- 所有文档审查通过

### 建议
- 建议在下次代码变更时再次调用此skill保持文档同步

---

技术细节

文档目录路径

默认路径：docs/项目最新概况

若用户项目使用不同路径，在执行时询问确认。

文档编号规则

延续现有编号序列：

• 现有最大编号为 N
• 新增文档编号为 N+1

文档模板结构

所有文档必须包含以下章节（按顺序）：

1. 文档目的 - 用 > 引用块说明
2. 系统概述 - 一句话说明功能定位
3. 技术栈 - 列出关键技术
4. 目录 - 带锚点链接的章节目录
5. 系统架构 - 核心模块表格/流程图
6. 数据库设计 - 表结构（如适用）
7. 后端实现 - API、核心逻辑代码片段
8. 前端实现 - 组件、Hook（如适用）
9. 使用指南 - 使用步骤
10. 注意事项 - 开发注意事项
11. 相关文件清单 - 路径表格
12. 创建时间/版本 - 日期和版本号

---

使用示例

用户输入：

更新文档，改动范围是 HEAD~2..HEAD

Skill执行：

1. 执行 git diff HEAD~2..HEAD 获取变更
2. 并行派发7个subagent评估7个现有文档
3. 并行派发1个subagent评估是否需新增文档
4. 汇总结果：
   • 01登录注册鉴权说明.md 需更新（修改了JWT过期时间）
   • 07agentchat页面说明.md 需更新（修改了MCP工具命名规则）
   • 不需新增文档
5. 用户确认
6. 并行派发2个subagent执行更新
7. 并行派发2个subagent审查
8. 审查通过，完成

---

注意事项

1. 改动范围必须明确：用户需提供git范围、文件列表或功能描述
2. 评估阶段不修改文档：只产出建议，等待确认
3. 并行执行：评估、更新、审查阶段均并行派发subagent
4. 审查循环：直到所有文档通过才完成
5. 文档一致性：确保文档描述与实际代码一致是核心目标