文档
目的
文档生命周期管理器。生成初始项目文档,使文档与代码变更保持同步,生成 API 参考,并自动生成变更日志。解决了文档领域的头号问题:文档存在但已过时。
触发器
- 由
scaffold的 Phase 7 在初始文档生成时调用 - 由
cook在 Phase 7 之后调用,以在功能实现后更新文档 - 由
launch在部署前调用,以确保文档是最新的 /rune docs init— 首次文档生成/rune docs update— 将文档与最近的代码变更同步/rune docs api— 生成 API 文档/rune docs changelog— 从 Git 历史自动生成变更日志
调用(出站)
scout(L2):扫描代码库以获取文档目标(路由、导出、组件、配置)doc-processor(L3):按需生成 PDF/DOCX 导出git(L3):读取变更日志生成的提交历史
被谁调用(入站)
scaffold(L1):Phase 7 — 为新项目生成初始文档cook(L1):实现后 — 为变更的模块更新文档launch(L1):部署前 — 验证文档是最新的mcp-builder(L2):生成 MCP 服务器文档- 用户:直接调用
/rune docs
模式
初始化模式 — /rune docs init
项目的首次文档生成。
更新模式 — /rune docs update
增量同步 — 仅更新受近期代码变更影响的文档。
API 模式 — /rune docs api
专门生成或更新 API 文档。
变更日志模式 — /rune docs changelog
从 Git 提交历史自动生成变更日志。
可执行步骤
初始化模式
步骤 1 — 扫描代码库
调用 rune:scout 以提取:
- 项目名称、描述、技术栈
- 目录结构和关键文件
- 入口点(main, index, app)
- 公共 API 表面(导出、路由、组件)
- 配置文件(.env.example, 配置模式)
- 现有文档(如有 — 合并,而非覆盖)
步骤 2 — 生成 README.md
结构:
# [项目名称]
[一行描述]
## 快速开始
[3-5 条命令启动:安装、配置、启动]
## 功能特性
[从代码中提取的列表 — 路由、组件、能力]
## 技术栈
[从 package.json, requirements.txt, Cargo.toml 等检测]
## 项目结构
[关键目录及其一行描述]
## 配置
[来自 .env.example 的环境变量及其描述]
## 开发
[开发服务器、测试、检查、构建命令]
## API 参考
[API.md 的链接(如适用),或内联摘要]
## 许可证
[从 LICENSE 文件或 package.json 检测]
步骤 3 — 生成 ARCHITECTURE.md(如果项目有 10 个以上文件)
结构:
# 架构
## 概述
[以文本/mermaid 形式呈现的系统图 — 组件和数据流]
> 架构概述可以调用 `rune:diagram` 来生成设计的系统图(类型为 `architecture`)而不是原始的 Mermaid — `suggested_next: diagram`。
## 关键决策
[检测到的模式:框架选择、状态管理、数据库、认证方式]
## 模块映射
[每个顶级目录:目的、关键文件、依赖关系]
## 数据流
[请求生命周期或数据管道描述]
步骤 4 — 生成 API.md(如果检测到路由/端点)
扫描路由文件并提取:
- HTTP 方法 + 路径
- 请求参数(路径、查询、主体)
- 响应格式
- 认证要求
- 错误响应
格式化为 Markdown 表格或兼容 OpenAPI 的参考。
步骤 5 — 报告
向用户呈现生成的文档,并附上摘要:
- 生成的文件:[列表]
- 覆盖率:[记录了哪些内容与存在哪些内容]
- 差距:[没有文档的代码区域 — 建议下一步操作]
更新模式
步骤 1 — 检测变更
读取自上次文档更新以来的 git diff(通过文档文件的 Git 日志或 .rune/docs-sync.json 跟踪)。
识别:
- 新文件/模块 → 需要新的文档章节
- 变更的函数/路由 → 需要文档更新
- 已删除的代码 → 需要删除文档
- 新配置 → 需要更新配置文档
步骤 2 — 更新受影响的章节
对于每个变更的区域:
- 读取变更的代码
- 找到对应的文档章节
- 更新文档以匹配当前代码
- 如果文档章节不存在 → 创建它
- 如果代码已被删除 → 在文档中标记为已删除或弃用
步骤 3 — 生成变更日志条目
委托给 rune:git changelog,以从上次文档更新以来的提交中生成变更日志条目。
步骤 4 — 交叉文档一致性检查
交叉文档一致性可防止第二常见的文档问题:文档存在但相互矛盾。
在更新任何文档后,验证所有项目文档的一致性:
| 检查项 | 文件 | 比较内容 |
|---|---|---|
| 版本号 | README, CLAUDE.md, package.json, CHANGELOG | 必须全部匹配当前版本 |
| 功能列表 | README, 登录页面, CLAUDE.md | 列出的功能相同(详细程度可能不同) |
| 统计数据 | README, CLAUDE.md, 登录页面, 仪表盘 | 技能数量、测试数量、信号数量必须匹配 |
| 命令 | README, CLAUDE.md, docs/ | 相同的命令带有相同的标志 |
| 技术栈 | README, ARCHITECTURE.md, CLAUDE.md | 一致的框架/库引用 |
交叉文档一致性:
- [x] README.md ↔ CLAUDE.md:版本匹配,命令匹配
- [x] README.md ↔ docs/index.html:统计数据匹配,功能匹配
- [ ] README.md 说“62 个技能”但 CLAUDE.md 说“59 个” → 修复 CLAUDE.md
立即修复不一致之处 — 不仅仅是报告它们。更新陈旧的文档以匹配事实来源(通常是代码或最近更新的文档)。
步骤 5 — 报告
向用户展示:更新了什么,添加了什么,标记了哪些内容以供审查。包括交叉文档一致性结果。
API 模式
步骤 1 — 检测 API 框架
| 框架 | 路由模式 | 文件模式 |
|---|---|---|
| Express | router.get/post/put/delete | routes/*.ts, *.router.ts |
| FastAPI | @app.get/post/put/delete | routers/*.py, main.py |
| NestJS | @Get/@Post/@Put/@Delete | *.controller.ts |
| Next.js App | export async function GET/POST | app/**/route.ts |
| Next.js Pages | export default function handler | pages/api/**/*.ts |
| SvelteKit | export function GET/POST | src/routes/**/+server.ts |
| Hono | app.get/post/put/delete | src/*.ts |
步骤 2 — 提取端点
对于每个检测到的路由:
- 方法(GET, POST, PUT, DELETE, PATCH)
- 路径(高亮参数)
- 请求:参数、查询、主体形状(来自 Zod schema、TypeScript 类型、Pydantic 模型)
- 响应:形状(来自返回类型或响应辅助函数)
- 认证:是否需要?(检测诸如
authMiddleware,@UseGuards之类的中间件) - 描述:如果可用,来自 JSDoc/docstring
步骤 3 — 生成 API 参考
格式化为 Markdown:
# API 参考
## 认证
[认证机制描述]
## 端点
### `POST /api/auth/login`
**描述**:验证用户身份并返回令牌
**认证**:无
**请求体**:
| 字段 | 类型 | 必填 | 描述 |
|-------|------|----------|-------------|
| email | string | 是 | 用户邮箱 |
| password | string | 是 | 用户密码 |
**响应** (200):
```json
{ "token": "string", "refreshToken": "string" }
错误:
- 401:无效凭据
- 422:验证错误
#### 步骤 4 — 输出
保存到 `docs/API.md` 或项目特定位置。如果请求 OpenAPI,则生成 `openapi.yaml`。
### 变更日志模式
#### 步骤 1 — 委托给 Git
调用 `rune:git changelog` 以按类型对提交进行分组,并格式化为“Keep a Changelog”。
#### 步骤 2 — 增强
向原始变更日志添加上下文:
- 将 PR 编号链接到实际描述
- 将相关更改分组到功能标题下
- 突出显示重大变更
#### 步骤 3 — 输出
追加到或更新 `CHANGELOG.md`。
## 输出格式
### 初始化模式输出
在项目根目录生成的文件:
- `README.md` — 快速开始、功能特性、技术栈、结构、配置、开发命令
- `ARCHITECTURE.md` — 概述图、关键决策、模块映射、数据流(如果有 10 个以上文件)
- `docs/API.md` — 端点参考,包含方法、路径、参数、响应、认证(如果检测到路由)
### 更新模式输出
修改的文档章节及变更摘要:
文档更新报告:
- 已更新:[修改的文档章节列表]
- 已添加:[新代码的新章节]
- 已标记:[引用已删除代码的陈旧章节]
- 变更日志:[已追加到 CHANGELOG.md 的条目]
### API 模式输出
`docs/API.md` — 按端点的 Markdown 参考:
METHOD /path/:param
描述:[来自 JSDoc/docstring] 认证:[必需/无] 请求:[参数、查询、主体表格] 响应:[包含状态码的形状] 错误:[错误码及描述]
### 变更日志模式输出
`CHANGELOG.md` — “Keep a Changelog”格式,按以下分组:新增、修复、变更、移除。
## 约束
1. 必须从实际代码生成文档 — 绝不捏造不存在的功能或 API
2. 必须保留现有文档 — 更新章节,而不是覆盖整个文件
3. 必须检测文档过时 — 标记引用已删除/变更代码的章节
4. 每个 README 必须包含快速开始 — 用户需要在 2 分钟内启动
5. 不得为尚不存在的代码生成文档(除非明确创建规范文档)
6. API 文档必须与实际路由签名匹配 — 错误的 API 文档比没有文档更糟糕
## 输出物
| 工件 | 格式 | 位置 |
|----------|--------|--------------|
| README.md | Markdown | 项目根目录 |
| ARCHITECTURE.md | Markdown | 项目根目录(如果有 10 个以上文件) |
| API 参考 | Markdown | `docs/API.md` |
| 变更日志条目 | Markdown (Keep a Changelog) | `CHANGELOG.md` |
| 文档更新报告 | Markdown | 内联(聊天输出) |
**范围护栏:** 只记录代码库中存在的内容 — 绝不捏造功能、端点或 API。
## 边缘情况
| 失败模式 | 严重性 | 缓解措施 |
|---|---|---|
| 凭空捏造不存在的 API 端点 | 严重 | 约束 1:扫描实际路由文件,而非猜测 |
| 覆盖用户编写的 README 章节 | 高 | 约束 2:合并,而非覆盖 — 检测自定义章节 |
| 代码变更后文档过时 | 高 | 更新模式检测差异并更新受影响的章节 |
| API 文档具有错误的请求/响应格式 | 高 | 从 Zod/Pydantic/TypeScript 类型提取,而非凭记忆 |
| 缺少快速开始章节 | 中 | 约束 4:每个 README 都有快速开始 |
| 变更日志包含孤立的 PR 链接 | 低 | 链接前验证 PR 编号是否存在 |
| 交叉文档不一致(README 说 X,CLAUDE.md 说 Y) | 高 | 步骤 7:交叉文档一致性检查 — 验证所有文档中的统计数据、版本和功能列表是否匹配 |
| 更新一个文档但不更新其他文档(统计数据漂移) | 高 | 在更新任何文档后,扫描所有相关文档以查找陈旧的统计数据 — 特别是 README ↔ CLAUDE.md ↔ 登录页面 |
## 完成条件
### 初始化模式
- 使用 scout 扫描代码库
- 生成 README.md,包含快速开始、功能特性、技术栈、结构
- 生成 ARCHITECTURE.md(如果有 10 个以上文件)
- 生成 API.md(如果检测到路由)
- 向用户展示覆盖率报告
### 更新模式
- 检测到自上次文档更新以来的变更
- 更新受影响的文档章节
- 生成变更日志条目
- 向用户展示更新报告
### API 模式
- 检测到 API 框架
- 提取所有端点,包含方法、路径、请求、响应
- 以 Markdown 格式生成 API 参考
- 保存到 docs/API.md
### 变更日志模式
- 提交按类型分组
- 格式化为“Keep a Changelog”
- 更新 CHANGELOG.md
## 成本概况
大约 2000-5000 个输入令牌,大约 1000-3000 个输出令牌。Sonnet — 文档编写需要理解代码模式,但无需深入的架构推理。