forge-doc-release · diff
git:20260717.f9c3c90 to git:20260717.95d1b1c
39 added, 230 removed. Audit A to A.
---
name: forge-doc-release
description: |
发布后文档更新。读取所有项目文档，与 diff 交叉对照，
更新 README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md 使之匹配已发布内容，
润色 CHANGELOG 语气，清理 TODOS，可选地更新 VERSION。
触发方式：用户说"更新文档"、"文档同步"、"forge-doc-release"，或 forge-ship 之后、PR 合并之前由 forge-dev --full 调度。
allowed-tools:
- Bash
- Read
- Write
- Edit
- Grep
- Glob
- AskUserQuestion
---
> **文档落地路径**：遵循 forge-doc-policy 规范。完整白名单 + frontmatter schema 见
> `~/.claude/skills/forge-doc-policy/doc-paths.md`。
> **当前文档加载顺序**：优先审查 `CLAUDE.md`、`docs/README.md`、`docs/INDEX.md`、
> 根级当前真相源、相关模块附录和 `.features`；`docs/archive/raw/` 只作历史证据，不纳入默认同步。
> 详细规则见 `~/.claude/skills/_shared/current-doc-loading.md`。
# /forge-doc-release：发布后文档更新
## 前置脚本（每次先运行）
```bash
_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "当前分支: $_BRANCH"
```
---
> 提问格式与批量策略见 `~/.claude/skills/_shared/interaction-protocol.md`。
---
## 第0步：检测基础分支
确定此 PR 的目标分支。后续所有步骤以此为"基础分支"。
1. 检查是否已有 PR：
`gh pr view --json baseRefName -q .baseRefName`
如果成功，使用打印的分支名。
2. 如果没有 PR（命令失败），检测仓库默认分支：
`gh repo view --json defaultBranchRef -q .defaultBranchRef.name`
3. 如果都失败，回退到 `main`。
---
## 角色定义
你在运行 `/forge-doc-release` 工作流。这在 `/forge-ship`（代码已提交，PR 已存在或即将创建）**之后**、PR 合并 **之前** 运行。你的任务：确保项目中的每个文档文件都准确、最新、用友好且面向用户的语气书写。
你主要是自动化的。明显的事实性更新直接做。只在风险或主观决策时停下来问。
**只在以下情况停下来问：**
- 风险/可疑的文档变更（叙事、理念、安全、删除、大规模重写）
- VERSION 更新决策（如果尚未更新）
- 要添加的新 TODOS 项
- 叙事性的跨文档矛盾
**绝不因以下原因停下来：**
- 从 diff 明确可得的事实性更正
- 向表格/列表添加条目
- 更新路径、数量、版本号
- 修复过期的交叉引用
- CHANGELOG 语气润色（小幅措辞调整）
- 标记 TODOS 已完成
- 跨文档事实性不一致（如版本号不匹配）
**绝不做：**
- 覆盖、替换或重新生成 CHANGELOG 条目——只润色措辞，保留所有内容
- 不经询问就更新 VERSION——始终用 AskUserQuestion 确认版本变更
- 对 CHANGELOG.md 使用 `Write` 工具——始终用 `Edit` 精确匹配 `old_string`
---
- ## 第1步：预检与 Diff 分析
-
- 1. 检查当前分支。如果在基础分支上，**中止**："你在基础分支上。请从功能分支运行。"
-
- 2. 收集变更上下文：
-
- ```bash
- git diff <base>...HEAD --stat
- ```
-
- ```bash
- git log <base>..HEAD --oneline
- ```
-
- ```bash
- git diff <base>...HEAD --name-only
- ```
-
- 3. 发现仓库中需要同步的当前文档文件：
-
- ```bash
- find . -maxdepth 3 -name "*.md" \
- -not -path "./.git/*" \
- -not -path "./node_modules/*" \
- -not -path "./.gstack/*" \
- -not -path "./.context/*" \
- -not -path "./docs/archive/raw/*" | sort
- ```
-
- 4. 将变更分类为与文档相关的类别：
- - **新功能** — 新文件、新命令、新技能、新能力
- - **行为变更** — 修改的服务、更新的 API、配置变更
- - **移除的功能** — 删除的文件、移除的命令
- - **基础设施** — 构建系统、测试基础设施、CI
-
- 5. 输出简要摘要："分析了 N 个文件的变更，跨 M 次提交。找到 K 个文档文件待审查。"
-
- ---
-
- ## 第2步：逐文件文档审计
-
- 读取每个文档文件，与 diff 交叉对照。使用以下通用启发式方法（适用于任何项目）：
-
- **README.md：**
- - 是否描述了 diff 中可见的所有功能和能力？
- - 安装/设置说明与变更一致吗？
- - 示例、演示和使用描述仍然有效吗？
- - 故障排除步骤仍然准确吗？
-
- **ARCHITECTURE.md：**
- - ASCII 图和组件描述与当前代码匹配吗？
- - 设计决策和"为什么"的解释仍然准确吗？
- - 保守处理——只更新被 diff 明确矛盾的内容。
-
- **CONTRIBUTING.md — 新贡献者冒烟测试：**
- - 以全新贡献者的身份走一遍设置说明。
- - 列出的命令准确吗？每一步都会成功吗？
- - 测试层级描述与当前测试基础设施匹配吗？
- - 工作流描述是最新的吗？
- - 标记任何会失败或让首次贡献者困惑的内容。
-
- **CLAUDE.md / 项目说明：**
- - 项目结构部分与实际文件树匹配吗？
- - 列出的命令和脚本准确吗？
- - 构建/测试说明与 package.json（或等效文件）匹配吗？
-
- **其他 .md 文件：**
- - 读取文件，确定其目的和受众。
- - 与 diff 交叉对照，检查是否与文件所述内容矛盾。
-
- 对每个文件，将所需更新分类为：
-
- - **自动更新** — 从 diff 明确可得的事实性更正：向表格添加条目、更新文件路径、修正数量、更新项目结构树。
- - **询问用户** — 叙事变更、删除段落、安全模型变更、大规模重写（单个段落超过约 10 行）、相关性不明确、添加全新段落。
-
- ---
-
- ## 第3步：应用自动更新
-
- 用 Edit 工具直接做所有明确的事实性更新。
-
- 对每个修改的文件，输出一行摘要描述 **具体改了什么** —— 不只是"更新了 README.md"，而是"README.md：在技能表中添加了 /new-skill，技能计数从 9 更新为 10。"
-
- **绝不自动更新：**
- - README 的简介或项目定位
- - ARCHITECTURE 的理念或设计理由
- - 安全模型描述
- - 不从任何文档中删除整个段落
-
- ---
-
- ## 第4步：询问风险/可疑变更
-
- 对第2步识别的每个风险或可疑更新，用 AskUserQuestion 确认：
- - 上下文：项目名、分支、哪个文档文件、正在审查什么
- - 具体的文档决策
- - `建议：选择 [X] 因为 [一句话原因]`
- - 选项包括 C) 跳过——保持原样
-
- 每个回答后立即应用已批准的变更。
-
- ---
-
- ## 第5步：CHANGELOG 语气润色
-
- **关键——绝不覆盖 CHANGELOG 条目。**
-
- 此步骤润色语气。它 **不** 重写、替换或重新生成 CHANGELOG 内容。
-
- **规则：**
- 1. 先完整读取 CHANGELOG.md。理解已有内容。
- 2. 只修改现有条目的措辞。绝不删除、重排或替换条目。
- 3. 绝不从头重新生成 CHANGELOG 条目。条目由 `/forge-ship` 从实际 diff 和提交历史写成。它是事实来源。你只是润色措辞。
- 4. 如果条目看起来有误或不完整，用 AskUserQuestion——**不要** 默默修复。
- 5. 用 Edit 工具精确匹配 `old_string`——绝不用 Write 覆盖 CHANGELOG.md。
-
- **如果此分支未修改 CHANGELOG：** 跳过此步骤。
-
- **如果此分支修改了 CHANGELOG**，审查条目语气：
-
- - **推销测试：** 用户读每个条目时会想"不错，我想试试"吗？如果不会，改写措辞（不改内容）。
- - 以用户现在能 **做什么** 开头——不是实现细节。
- - "你现在可以..." 而非"重构了..."
- - 标记并改写读起来像 commit 消息的条目。
- - 内部/贡献者变更归入单独的"### 贡献者相关"子段落。
- - 小幅语气调整自动做。用 AskUserQuestion 确认会改变含义的重写。
-
- ---
-
- ## 第6步：跨文档一致性与可发现性检查
-
- 逐文件审计后，做跨文档一致性检查：
-
- 1. README 的功能/能力列表与 CLAUDE.md（或项目说明）描述的一致吗？
- 2. ARCHITECTURE 的组件列表与 CONTRIBUTING 的项目结构描述一致吗？
- 3. CHANGELOG 的最新版本与 VERSION 文件一致吗？
- 4. **可发现性：** 每个文档文件都能从 README.md 或 CLAUDE.md 到达吗？如果 ARCHITECTURE.md 存在但两者都没链接到它，标记出来。每个文档都应该从两个入口文件之一可发现。
- 5. 标记文档间的矛盾。事实性不一致自动修复（如版本号不匹配）。叙事矛盾用 AskUserQuestion。
-
- ---
-
- ## 第7步：TODOS.md 清理
-
- 如果 TODO.md / TODOS.md 都不存在，跳过此步骤（下文统称 TODOS.md，以项目实际存在的文件为准）。
-
- 1. **已完成但未标记的项目：** 将 diff 与未完成的 TODO 项交叉对照。如果 TODO 明确被此分支的变更完成了，移到已完成部分并标注 `**已完成：** vX.Y.Z.W (YYYY-MM-DD)`。保守处理——只标记在 diff 中有明确证据的项目。
-
- 2. **需要更新描述的项目：** 如果 TODO 引用的文件或组件有重大变更，其描述可能过期。用 AskUserQuestion 确认该 TODO 应该更新、完成还是保持原样。
-
- 3. **新的延迟工作：** 检查 diff 中的 `TODO`、`FIXME`、`HACK` 和 `XXX` 注释。对每个代表有意义延迟工作的注释（不是琐碎的内联备注），用 AskUserQuestion 询问是否应纳入 TODOS.md。
-
- ---
-
- ## 第8步：VERSION 更新问题
-
- **关键——绝不在不询问的情况下更新 VERSION。**
-
- 1. **如果 VERSION 不存在：** 静默跳过。
-
- 2. 检查此分支是否已修改 VERSION：
-
- ```bash
- git diff <base>...HEAD -- VERSION
- ```
+ ## 执行手册（按需加载，执行时必读）
- 3. **如果 VERSION 未更新：** 用 AskUserQuestion：
- - 建议：选择 C（跳过）因为纯文档变更很少需要版本更新
- - A) PATCH 更新（X.Y.Z+1）— 如果文档变更随代码变更一起发布
- - B) MINOR 更新（X.Y+1.0）— 如果这是一次重要的独立发布
- - C) 跳过 — 不需要版本更新
+ 本文件只保留铁律、流程总览和出口。**进入执行阶段前，必须先读对应手册**：
- 4. **如果 VERSION 已更新：** 不要静默跳过。检查更新是否覆盖了此分支所有变更的完整范围：
+ | 场景 | 必读文件 | 内容 |
+ |---|---|---|
+ | 第1步~第9步全部执行细节 | [references/release-details.md](references/release-details.md) | diff 收集命令、逐文件审计启发式、CHANGELOG 润色规则、TODOS/VERSION 决策树、提交与 PR body 更新流程、文档健康摘要模板 |
- a. 读取当前 VERSION 的 CHANGELOG 条目。它描述了什么功能？
- b. 读取完整 diff。有没有重要变更（新功能、新技能、新命令、大重构）没有在当前版本的 CHANGELOG 条目中提及？
- c. **如果 CHANGELOG 条目覆盖了一切：** 跳过——输出"VERSION: 已更新到 vX.Y.Z，覆盖所有变更。"
- d. **如果有重要的未覆盖变更：** 用 AskUserQuestion 解释当前版本覆盖了什么 vs 什么是新的，并询问：
- - 建议：选择 A 因为新变更值得自己的版本
- - A) 更新到下一个 patch（X.Y.Z+1）— 给新变更自己的版本
- - B) 保持当前版本 — 将新变更添加到现有 CHANGELOG 条目
- - C) 跳过 — 保持原样，稍后处理
+ **规矩**：不允许凭记忆执行细则——骨架没写的操作细节，一律以手册为准；手册与骨架冲突时，以骨架的铁律为准。
---
- ## 第9步：提交与输出
-
- **先检查是否为空：** 运行 `git status`（不用 `-uall`）。如果前面的步骤没有修改任何文档文件，输出"所有文档都是最新的。"并退出，不提交。
-
- **提交：**
+ ## 流程总览（9 步）
- 1. 按文件名暂存修改的文档文件（绝不用 `git add -A` 或 `git add .`）。
- 2. 创建单次提交：
+ ### 第1步：预检与 Diff 分析
- ```bash
- git commit -m "$(cat <<'EOF'
- docs: 更新项目文档
+ 确认不在基础分支上，收集 `git diff <base>...HEAD` 的 stat/log/文件清单，
+ 用 find 发现待同步文档，将变更分为新功能/行为变更/移除/基础设施四类并输出摘要。
+ 命令与分类细则见手册"第1步"。
- Co-Authored-By: Claude <noreply@anthropic.com>
- EOF
- )"
- ```
+ ### 第2步：逐文件文档审计
- 3. 推送到当前分支：
+ 读取每个文档文件与 diff 交叉对照，按文件类型套用通用审计启发式
+ （README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md/其他各有清单），
+ 把所需更新分成"自动更新"与"询问用户"两类。各文件的检查清单与分类标准见手册"第2步"。
- ```bash
- git push
- ```
+ ### 第3步：应用自动更新
- **PR body 更新（幂等、竞态安全）：**
+ 用 Edit 直接做所有明确的事实性更新，每个文件输出一行"具体改了什么"的摘要。
+ 简介/理念/安全模型/整段删除属于绝不自动更新范围，完整清单见手册"第3步"。
- 1. 将现有 PR body 读入临时文件：
+ ### 第4步：询问风险/可疑变更
- ```bash
- gh pr view --json body -q .body > /tmp/doc-release-pr-body-$$.md
- ```
+ 对第2步识别的每个风险项用 AskUserQuestion 确认（含上下文、建议、跳过选项），
+ 每个回答后立即应用。提问要素格式见手册"第4步"。
- 2. 如果临时文件已包含 `## 文档` 段落，替换该段落。如果没有，在末尾追加 `## 文档` 段落。
+ ### 第5步：CHANGELOG 语气润色
- 3. 文档段落应包含 **文档 diff 预览** —— 每个修改的文件描述具体改了什么。
+ 只润色现有条目措辞，绝不覆盖/删除/重排/重新生成；条目由 /forge-ship 写成，是事实来源。
+ 分支没改 CHANGELOG 就跳过。五条规则与"推销测试"等改写方向见手册"第5步"。
- 4. 写回更新的 body：
+ ### 第6步：跨文档一致性与可发现性检查
- ```bash
- gh pr edit --body-file /tmp/doc-release-pr-body-$$.md
- ```
+ 对照 README/CLAUDE.md/ARCHITECTURE/CONTRIBUTING/CHANGELOG/VERSION 做五项交叉检查；
+ 事实性不一致自动修，叙事矛盾询问；每个文档须从 README 或 CLAUDE.md 可达。
+ 完整清单见手册"第6步"。
- 5. 清理临时文件：
+ ### 第7步：TODOS.md 清理
- ```bash
- rm -f /tmp/doc-release-pr-body-$$.md
- ```
+ 文件不存在则跳过。三件事：diff 有明确证据的 TODO 标记已完成、
+ 描述过期的 TODO 询问处置、diff 里有意义的 TODO/FIXME 注释询问是否纳入。
+ 细则见手册"第7步"。
- 6. 如果 `gh pr view` 失败（没有 PR）：跳过并提示"未找到 PR——跳过 body 更新。"
- 7. 如果 `gh pr edit` 失败：警告"无法更新 PR body——文档变更在提交中。"并继续。
+ ### 第8步：VERSION 更新问题
- **结构化文档健康摘要（最终输出）：**
+ 文件不存在则静默跳过。绝不静默更新：未更新时用 AskUserQuestion 给 PATCH/MINOR/跳过三选项；
+ 已更新时检查是否覆盖此分支全部变更范围，有遗漏再询问。完整决策树见手册"第8步"。
- ```
- 文档健康:
- README.md [状态] ([详情])
- ARCHITECTURE.md [状态] ([详情])
- CONTRIBUTING.md [状态] ([详情])
- CHANGELOG.md [状态] ([详情])
- TODOS.md [状态] ([详情])
- VERSION [状态] ([详情])
- ```
+ ### 第9步：提交与输出
- 其中状态为：
- - 已更新 — 附变更描述
- - 最新 — 无需变更
- - 语气润色 — 措辞调整
- - 未更新 — 用户选择跳过
- - 已更新 — 版本已由 /forge-ship 设置
- - 跳过 — 文件不存在
+ 无文档改动则输出"所有文档都是最新的"并退出。否则按文件名暂存（绝不 `git add -A`）、
+ 单次提交并推送；随后幂等更新 PR body 的 `## 文档` 段落；最终输出结构化文档健康摘要。
+ 提交命令、PR body 更新流程与摘要模板见手册"第9步"。
---
## 重要规则
- **编辑前先读。** 修改文件前始终完整读取其内容。
- **绝不覆盖 CHANGELOG。** 只润色措辞。绝不删除、替换或重新生成条目。
- **绝不静默更新 VERSION。** 始终询问。即使已更新，也检查是否覆盖了完整变更范围。
- **明确说明改了什么。** 每次编辑附一行摘要。
- **通用启发式，非项目特定。** 审计检查适用于任何仓库。
- **可发现性很重要。** 每个文档文件都应从 README 或 CLAUDE.md 可达。
- **语气：友好、面向用户、不晦涩。** 像给一个没看过代码的聪明人解释一样写。