# Docs Manager

> 项目文档管理 - 引用完整性 + 文档保鲜 Use when this capability is needed.

- Skill: `tomevault-io/docs-manager` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/docs-manager`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/docs-manager/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/docs-manager

---


# 文档管理 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
```

| 状态         | 动作                     | 工具                                |
| :----------- | :----------------------- | :---------------------------------- |
| **SCAN**     | 发现目录结构、搜索引用   | `Glob`, `Grep`                      |
| **ANALYZE**  | 深度分析代码实现         | `Task` + `code-explorer` agent      |
| **COMPARE**  | 对比文档 vs 实现         | 内置比对逻辑                        |
| **REPORT**   | 生成保鲜/健康报告        | 输出 Markdown 表格                  |
| **UPDATE**   | 更新文档状态标记         | `Edit`                              |
| **PLAN**     | 构建影响图、生成变更清单 | `Read`                              |
| **CONFIRM**  | 展示影响、获取确认       | `AskUserQuestion`                   |
| **EXECUTE**  | 移动文件、更新引用       | `Bash`, `Edit`                      |
| **VERIFY**   | 验证无断链               | `Grep`, `Glob`                      |
| **ROLLBACK** | 回滚变更至执行前状态     | `Bash` (`git checkout`/`git reset`) |

---

## 🎯 命令

### `/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** (可选): 经用户确认后更新文档

**文档状态标记格式**:
```markdown
## 功能描述

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

**获取项目当前版本** (从 git tag 动态获取):
```bash
# 方法 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>` — 检查指定路径下的文档

---

## ✅ 执行前自检

| 检查项   | 验证方法             | 通过标准 |
| :------- | :------------------- | :------- |
| 引用覆盖 | 使用 ≥3 种 Grep 模式 | 无遗漏   |
| 影响完整 | 反向引用全部发现     | 100%     |
| 路径正确 | 新路径可达性验证     | 存在     |
| 可回滚   | 记录 git 状态        | 有快照   |

---

## ⚠️ 错误恢复

| 错误场景       | 恢复策略                      |
| :------------- | :---------------------------- |
| 引用更新失败   | `git checkout` 回滚受影响文件 |
| 文件移动失败   | 报告错误，保持原状态          |
| 发现新引用格式 | 添加到检测模式，重新扫描      |
| 用户取消       | 无副作用退出                  |

---

## 🔧 工具使用

| 任务     | 工具   | 示例                         |
| :------- | :----- | :--------------------------- |
| 发现文档 | `Glob` | `docs/**/*.md`               |
| 搜索引用 | `Grep` | `\[.*\]\(.*ARCHITECTURE.*\)` |
| 读取内容 | `Read` | 验证目标存在                 |
| 更新引用 | `Edit` | 精确替换路径                 |
| 移动文件 | `Bash` | `git mv` 保留历史            |

---

## 📖 动态发现

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

```
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 版本与项目版本独立。文档保鲜标记应使用动态获取的项目版本。

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/hrygo) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->