anian0/version-doc-updater

版本文档更新 Skill

这个 Skill 是做什么的

帮助你在项目迭代后，自动同步更新三类文档：

• 版本更新说明 - 给用户看的版本变更日志
• 管理后台操作说明 - 给管理员看的操作手册
• 对外能力说明 - 给业务方看的能力清单

整体流程

第1步：读取当前三类文档的内容
    ↓
第2步：分析本次迭代变更
    ↓
第3步：判断需要更新哪些文档、哪些章节
    ↓
第4步：按各文档的风格更新内容
    ↓
第5步：输出更新后的完整文档

流程详解

第1步：读取现有文档

读取工作目录下的三类文档文件：

• 管理后台操作说明.md
• 对外能力说明.md
• 版本更新说明.md

如果文件不存在，根据本次变更决定是否需要创建。

第2步：分析变更

用户提供本次迭代的变更说明，需要提取以下信息：

• 版本号（如 v0.3.0）
• 变更类型：新增功能 / 功能优化 / 问题修复
• 涉及模块（如 Agent管理、MCP管理、应用管理等）
• 变更详情描述

第3步：决策 - 影响范围判断

| 决策点 | 判断依据 | 更新目标 | |--------|----------|----------| | 是否为新版本 | 版本号与文档中最新版本不同 | 版本更新说明需要新增版本章节 | | 是否新增功能 | 变更类型为"新增" | 三类文档都可能需要新增条目 | | 是否优化功能 | 变更类型为"优化" | 版本更新说明记录优化；操作说明更新描述；能力说明更新描述 | | 是否修复问题 | 变更类型为"修复" | 仅需在版本更新说明中记录 | | 是否涉及后台操作 | 变更影响管理员的操作方式或界面 | 管理后台操作说明需要更新 | | 是否涉及对外接口或能力 | 变更影响业务系统对接或暴露新能力 | 对外能力说明需要更新 | | 是否涉及模块结构变化 | 新增/删除/重命名菜单或模块 | 管理后台操作说明需要调整章节结构 |

第4步：按文档风格更新

版本更新说明的写法

结构要求：

## vX.X.X

### 新增与优化

#### 一、模块名称

- **功能名称**：功能描述（用大白话说明用户能获得什么好处）
- **功能名称**：功能描述

#### 二、另一个模块
...

### 问题修复

- 修复了 XXX 问题

写作原则：

• 按模块分节，用"一、二、三"编号
• 功能名用粗体，后面跟冒号
• 描述用第二人称"你"，说明用户能怎么用、有什么好处
• 技术细节放在括号里或省略
• 多个相关功能可以合并成一条

管理后台操作说明的写法

结构要求：

### X.X 模块名称

#### X.X.1 列表说明

| 字段 | 说明 |
|------|------|
| 字段名 | 字段说明 |

#### X.X.2 新增/编辑主要字段

| 区域/字段 | 说明 |
|-----------|------|
| 字段名 | 填写说明 |

#### X.X.3 操作说明
...

写作原则：

• 使用表格展示字段说明
• 新增功能需要补充：列表字段说明、表单字段说明、操作步骤
• 如果新增独立模块，需要新增完整章节（列表+字段+操作）
• 如果修改现有功能，定位到对应章节更新描述

对外能力说明的写法

结构要求：

## 数字、模块名称

- **能力点**：能力描述（说明对业务系统的价值）
- **能力点**：能力描述

写作原则：

• 用条目式，不是表格
• 强调"能做什么"而不是"怎么做"
• 面向业务系统开发者，说明对接价值
• 与版本更新说明的能力描述保持同步

第5步：输出文档

输出更新后的三类文档完整内容，告知用户：

• 哪些文档被更新
• 哪些章节是新增的
• 哪些章节被修改

执行指令

当用户要求更新版本文档时：

1. 询问变更信息（如果用户没提供）：

   • 版本号是多少？
   • 本次迭代有哪些变更？（可以贴需求列表、PR描述、会议纪要等）

2. 读取现有文档：

   • 用 Read 工具读取当前目录下的三类文档

3. 分析并决策：

   • 对照"第3步：决策"表格，判断需要更新哪些内容

4. 生成更新内容：

   • 严格遵循"第4步"各文档的写法和结构
   • 保持与原文档风格一致

5. 输出结果：

   • 用 Write 或 Edit 工具保存更新后的文档
   • 向用户说明更新的具体内容

注意事项

• 不要改变原有结构：除非模块有增删，否则保持原有章节顺序
• 保持一致性：同一个功能在三类文档中的描述要对齐
• 面向非技术人员：避免技术术语，用"你能..."、"支持..."这样的表达
• 版本更新说明是增量更新（追加新版本），操作说明和能力说明是全量更新（替换整个章节）