---
name: forge-doc-release
description: |
  发布后文档更新。读取所有项目文档，与 diff 交叉对照，
  更新 README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md 使之匹配已发布内容，
  润色 CHANGELOG 语气，清理 TODOS，可选地更新 VERSION。
allowed-tools:
  - Bash
  - Read
  - Write
  - Edit
  - Grep
  - Glob
  - AskUserQuestion
---

# /forge-doc-release：发布后文档更新

## 前置脚本（每次先运行）

```bash
_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "当前分支: $_BRANCH"
```

---

## AskUserQuestion 格式规范

每次提问结构：
1. **重新聚焦**：当前项目、分支、正在审查的文档
2. **通俗解释**：高中生能懂的语言描述问题
3. **给出建议**：推荐选项 + 完整度评分
4. **列出选项**：`A) B) C)` + 工作量估算

---

## 第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 2 -name "*.md" -not -path "./.git/*" -not -path "./node_modules/*" -not -path "./.gstack/*" -not -path "./.context/*" | 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 清理

如果 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 已更新：** 不要静默跳过。检查更新是否覆盖了此分支所有变更的完整范围：

   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`）。如果前面的步骤没有修改任何文档文件，输出"所有文档都是最新的。"并退出，不提交。

**提交：**

1. 按文件名暂存修改的文档文件（绝不用 `git add -A` 或 `git add .`）。
2. 创建单次提交：

```bash
git commit -m "$(cat <<'EOF'
docs: 更新项目文档

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"
```

3. 推送到当前分支：

```bash
git push
```

**PR body 更新（幂等、竞态安全）：**

1. 将现有 PR body 读入临时文件：

```bash
gh pr view --json body -q .body > /tmp/doc-release-pr-body-$$.md
```

2. 如果临时文件已包含 `## 文档` 段落，替换该段落。如果没有，在末尾追加 `## 文档` 段落。

3. 文档段落应包含 **文档 diff 预览** —— 每个修改的文件描述具体改了什么。

4. 写回更新的 body：

```bash
gh pr edit --body-file /tmp/doc-release-pr-body-$$.md
```

5. 清理临时文件：

```bash
rm -f /tmp/doc-release-pr-body-$$.md
```

6. 如果 `gh pr view` 失败（没有 PR）：跳过并提示"未找到 PR——跳过 body 更新。"
7. 如果 `gh pr edit` 失败：警告"无法更新 PR body——文档变更在提交中。"并继续。

**结构化文档健康摘要（最终输出）：**

```
文档健康:
  README.md       [状态] ([详情])
  ARCHITECTURE.md [状态] ([详情])
  CONTRIBUTING.md [状态] ([详情])
  CHANGELOG.md    [状态] ([详情])
  TODOS.md        [状态] ([详情])
  VERSION         [状态] ([详情])
```

其中状态为：
- 已更新 — 附变更描述
- 最新 — 无需变更
- 语气润色 — 措辞调整
- 未更新 — 用户选择跳过
- 已更新 — 版本已由 /forge-ship 设置
- 跳过 — 文件不存在

---

## 重要规则

- **编辑前先读。** 修改文件前始终完整读取其内容。
- **绝不覆盖 CHANGELOG。** 只润色措辞。绝不删除、替换或重新生成条目。
- **绝不静默更新 VERSION。** 始终询问。即使已更新，也检查是否覆盖了完整变更范围。
- **明确说明改了什么。** 每次编辑附一行摘要。
- **通用启发式，非项目特定。** 审计检查适用于任何仓库。
- **可发现性很重要。** 每个文档文件都应从 README 或 CLAUDE.md 可达。
- **语气：友好、面向用户、不晦涩。** 像给一个没看过代码的聪明人解释一样写。