文档管理 Skill (docs-manager)

设计哲学: AI 是智能决策者，不是脚本调用者

🔄 状态机

                    /docs-sync
                         │
                         ▼
IDLE ──/docs-*──▶ SCAN ──▶ ANALYZE ──▶ COMPARE ──▶ REPORT ──▶ DONE
                   │         │           │           │
                   │         │           │           └─ confirm → UPDATE → VERIFY
                   │         │           │           └─ skip → DONE
                   │         │           └─ 无差异 → REPORT (干净)
                   │         └─ 代码分析完成
                   │
                   └─ /docs-check//ref/archive/new ──▶ PLAN ──▶ CONFIRM ──▶ EXECUTE ──▶ VERIFY ──▶ DONE
                                                  │         │          │
                                                  │         │          └─ 失败 → ROLLBACK → IDLE
                                                  │         └─ 拒绝 → IDLE
                                                  └─ 需补充 → SCAN

🎯 命令

/docs-check — 检查文档健康

状态路径: SCAN → REPORT (只读，无需 CONFIRM/EXECUTE)

目标: 发现断链、孤立文档、索引缺失

策略:

1. Glob("docs/**/*.md") 扫描结构
2. Grep 多模式搜索引用
3. 验证每个引用目标存在
4. 输出健康报告

/docs-ref <target> — 查看引用关系

状态路径: SCAN → REPORT (只读，无需 CONFIRM/EXECUTE)

目标: 理解文档连接网络

策略:

1. Grep(target, "**/*.md") 搜索所有引用
2. Read(target) 分析其引用的文档
3. 生成双向引用图

/docs-archive <files> — 归档文档

状态路径: SCAN → PLAN → CONFIRM → EXECUTE → VERIFY (完整流程)

目标: 移动到归档并保持引用有效

策略:

1. SCAN: 查找所有反向引用
2. PLAN: 计算新路径、生成更新清单
3. CONFIRM: 展示影响、等待确认
4. EXECUTE: git mv + 批量 Edit
5. VERIFY: 确认零断链

大规模操作 (>20 文件): 分批处理，每批确认后继续

/docs-new <type> <name> — 创建文档

状态路径: SCAN → PLAN → EXECUTE (无需 CONFIRM，创建无破坏性)

目标: 在正确位置创建符合规范的文档

策略:

1. Glob 分析现有结构
2. 归纳命名规范 (如 P{phase}-{team}{id}-{name}.md)
3. Bash 创建文件: cat > path/to/new.md << 'EOF'
4. 更新相关索引文件 (README.md / INDEX.md)

/docs-sync [scope] — 文档保鲜

状态路径: SCAN → ANALYZE → COMPARE → REPORT → [UPDATE]

目标: 对比文档描述与实际代码实现，标记过时内容

策略:

1. SCAN: 扫描 docs/ 目录结构，识别需要检查的文档
2. ANALYZE: 使用 Task tool + code-explorer agent 分析代码实现
   • API 文档 → 对比 proto/**/*.proto 定义
   • 架构文档 → 对比实际目录结构
   • 功能清单 → 扫描代码中的特性实现
3. COMPARE: 生成差异清单

   | 文档            | 声明       | 实际     | 状态   |
   | :-------------- | :--------- | :------- | :----- |
   | ARCHITECTURE.md | 5 个代理   | 6 个代理 | ⚠️ 过时 |
   | BACKEND_DB.md   | 支持 MySQL | 已移除   | ⚠️ 过时 |
   

4. REPORT: 输出保鲜报告，包含：
   • 过时内容列表
   • 缺失的文档条目
   • 建议的更新操作
5. UPDATE (可选): 经用户确认后更新文档

文档状态标记格式:

## 功能描述

> **保鲜状态**: ✅ 已验证 (YYYY-MM-DD)
> **覆盖范围**: `path/to/code.go`
> **最后检查**: vX.Y.Z

获取项目当前版本 (从 git tag 动态获取):

# 方法 1: 获取最新 git tag (推荐 - 单一版本来源)
git tag -l | sort -V | tail -1 | sed 's/^v//'

# 方法 2: 使用 git describe (包含 commit 信息)
git describe --tags --always | sed 's/^v//'

# 方法 3: 从 CHANGELOG.md 获取 (备选，可能与 tag 不同步)
grep "^## \[v" CHANGELOG.md | head -1 | sed 's/.*\[v//;s/\].*//'

scope 选项:

• all (默认) — 检查所有文档
• specs — 仅检查规格文档 (docs/specs/)
• guides — 仅检查开发指南 (docs/dev-guides/)
• <path> — 检查指定路径下的文档

✅ 执行前自检

⚠️ 错误恢复

🔧 工具使用

📖 动态发现

不硬编码，每次执行时发现:

Glob("docs/**/*.md")       → 目录结构
Glob("docs/specs/**/*.md") → 命名模式 P{phase}-{team}{id}-{name}.md
Grep("@docs/")             → 引用格式
ls *.md                    → 查找最新版本号 (RELEASE_NOTES_v*.md)

Skill 版本: v6.0 | 新增: 文档保鲜 (/docs-sync) | 理念: 状态机驱动 + 元认知自检

注意: Skill 版本与项目版本独立。文档保鲜标记应使用动态获取的项目版本。