document-release

步骤 0：前提条件与基准分支检测

开始任何操作之前，请先确认环境支持此工作流。这些检查可避免工作过程中出现令人困惑的失败。

1. **Git 仓库检查：**运行 git rev-parse --git-dir。如果失败，则中止并提示："Not a git repository."
2. **gh CLI 检查：**运行 gh auth status。如果失败，则警告："gh CLI is not authenticated — PR-related steps (body update, base branch detection via PR) will be skipped. Falling back to git-only detection." 继续工作流，但跳过步骤 9 中的 PR 正文更新。
3. **工作区干净状态检查：**运行 git status --porcelain（绝不使用 -uall）。如果文档文件（.md、VERSION、CHANGELOG*）有未提交的更改，请通过 AskUserQuestion 警告用户： "You have uncommitted changes to doc files that may conflict with this workflow. Continue anyway?"

然后确定此 PR 的目标分支。后续所有步骤中都将其称为“基准分支”。

4. 检查此分支是否已有 PR： gh pr view --json baseRefName -q .baseRefName 如果命令成功，则将输出的分支名称作为基准分支。

5. 如果不存在 PR（命令失败），则检测仓库的默认分支： gh repo view --json defaultBranchRef -q .defaultBranchRef.name

6. 如果两个命令都失败，则回退到 main。

---

文档发布：发布后更新文档

你正在运行 /document-release 工作流。此工作流在 /ship 之后（代码已提交，PR 已存在或即将创建）运行，但在 PR 合并之前运行。你的任务是确保项目中的每个文档文件都准确、及时更新，并采用友好、以用户为先的语气撰写。

此流程大部分会自动执行。请直接进行显而易见的事实性更新。只有在涉及有风险或主观的决定时，才暂停并询问。

**试运行模式：**如果用户说“dry run”“preview”或“what would change”，请完整运行步骤 0–2（分析和审查），但不要应用任何编辑。请改为按文件整理每项计划变更，并将每项变更归类为自动更新或询问用户，然后输出结构化预览。接着停止并询问：“准备应用这些更改，还是想调整计划？”如果用户批准，则根据计划从步骤 3 继续。如果用户提出调整，则纳入反馈并重新预览。

仅在以下情况暂停：

• 有风险或值得商榷的文档更改（叙述、理念、安全性、删除、大幅改写）
• VERSION 升级决策（如果尚未升级）
• 需要新增的 TODOS 项目
• 跨文档之间存在叙述性（而非事实性）矛盾

绝不因以下情况暂停：

• 根据差异可明确判断的事实更正
• 向表格或列表添加项目
• 更新路径、数量、版本号
• 修复过时的交叉引用
• 润色 CHANGELOG 的语气（细微措辞调整）
• 将 TODOS 标记为已完成
• 跨文档的事实不一致（例如版本号不匹配）

绝对不要：

• 覆盖、替换或重新生成 CHANGELOG 条目——只能润色措辞，并保留所有内容
• 未经询问就升级 VERSION——更改版本号时务必使用 AskUserQuestion
• 对 CHANGELOG.md 使用 Write 工具——务必使用 Edit 并精确匹配 old_string

步骤 1：预检与差异分析

1. 检查当前分支。如果处于基础分支上，中止：“You're on the base branch. Run from a feature branch.”

2. 收集更改的上下文：

git diff <base>...HEAD --stat
git log <base>..HEAD --oneline
git diff <base>...HEAD --name-only

3. 使用 Glob 工具（而非 find）查找仓库中的所有文档文件：

   • 查找项目根目录下的 **/*.md，然后过滤掉 .git/、node_modules/ 和 vendor/ 路径。
   • 优先检查顶层和下一层目录中的文件——它们是主要文档。更深层的文件 通常是自动生成的或不太重要。

4. 将更改归类到与文档相关的类别：

   • 新功能——新文件、新命令、新技能、新能力
   • 行为变更——服务修改、API 更新、配置变更
   • 功能移除——删除文件、移除命令
   • 基础设施——构建系统、测试基础设施、CI

5. 输出简短摘要：“正在分析跨 M 次提交更改的 N 个文件。发现 K 个文档文件需要审核。”

---

步骤 2：逐文件审核文档

阅读每个文档文件，并对照差异进行核查：

README.md：

• 是否描述了差异中体现的所有功能和能力？
• 安装／设置说明是否与更改一致？
• 示例、演示和用法说明是否仍然有效？
• 故障排除步骤是否仍然准确？

ARCHITECTURE.md：

• ASCII 图表和组件说明是否与当前代码一致？
• 设计决策和“原因”说明是否仍然准确？
• 应谨慎处理——只有在差异明确表明内容不符时才更新。

CONTRIBUTING.md——新贡献者冒烟测试：

• 假设自己是刚加入的贡献者，按步骤执行设置说明。
• 列出的命令是否准确？每个步骤都能成功吗？
• 标记任何会失败或让首次贡献者感到困惑的内容。

CLAUDE.md / AGENTS.md / 项目说明：

• 项目结构部分是否与实际文件树一致？
• 列出的命令和脚本是否准确？
• 构建／测试说明是否与配置文件中的内容一致？

任何其他 .md 文件：

• 阅读文件，确定其用途和目标受众。
• 对照差异进行核查，检查文件中的内容是否有矛盾。

内联文档和生成的文档： 代码级文档常常会与 Markdown 文档不同步。当差异涉及公共 API 的更改时，请检查以下内容是否过时：

• PHPDoc / JSDoc / 文档块——如果函数签名、返回类型或行为在差异中发生变化，请确认相应的文档块仍然匹配。使用 Grep 在更改的文件中搜索 @param、@return、@throws。
• OpenAPI / Swagger 规范——如果新增、更改或移除了 API 端点，请检查是否存在 openapi.yaml、swagger.json 或类似规范文件，并确认是否需要更新。使用 Glob 查找 **/openapi.*、**/swagger.*。
• README 徽章／自动生成部分——如果仓库使用徽章（覆盖率、版本、构建状态），请确认它们引用的值仍然正确。如果某些部分标记为自动生成（例如 ``），应标记出来，而不要编辑——这些内容应由相应工具重新生成，而不是手动编辑。

这些是补充检查——不要深入检查每个源文件。重点关注出现在差异中，且可能影响面向用户文档的文件。

对每个文件，将所需更新分为：

• 自动更新——差异明确要求进行的事实更正：在表格中添加条目、更新文件路径、修正数量、更新项目结构树。
• 询问用户——叙述性更改、删除章节、安全模型更改、大幅重写（单个章节约超过 10 行）、相关性不明确或添加全新章节。

步骤 3：应用自动更新

使用 Edit 工具，直接应用所有明确、准确的更新。

对于修改的每个文件，输出一行摘要，具体说明更改了什么，不要只写“更新了 README.md”，而应写“README.md：在技能表格中添加了 /new-skill，将技能数量从 9 更新为 10。”

绝不自动更新：

• README 介绍或项目定位
• ARCHITECTURE 中的理念或设计依据
• 安全模型说明
• 不要删除任何文档中的完整章节

---

步骤 4：询问有风险或存疑的更改

对于步骤 2 中识别出的每项有风险或存疑的更新，使用 AskUserQuestion，并包含：

• 背景信息：项目名称、分支、正在审阅的文档文件及内容
• 具体的文档修改决定
• RECOMMENDATION: Choose [X] because [one-line reason]
• 选项中包括 C) 跳过 — 保持现状

每次得到答复后，立即应用获批的更改。

---

步骤 5：VERSION 版本号更新问题

VERSION 的处理先于 CHANGELOG 润色，因为如果用户在此处更新了版本，后续步骤中的 CHANGELOG 条目和跨文档一致性检查就能反映正确的版本号。

关键 — 未经询问，绝不更新 VERSION。

1. 如果 VERSION 不存在： 静默跳过。

2. 检查当前分支上是否已修改 VERSION：

git diff <base>...HEAD -- VERSION

3. 如果 VERSION 尚未更新： 使用 AskUserQuestion：

   • RECOMMENDATION: Choose C (Skip) because docs-only changes rarely warrant a version bump
   • A) 更新 PATCH — 如果文档更改与代码更改一同发布
   • B) 更新 MINOR — 如果这是一次重要的独立发布
   • C) 跳过 — 无需更新版本号

4. 如果 VERSION 已更新： 检查此次更新是否涵盖全部变更范围。如果仍有重要变更未涵盖，询问是否再次更新版本号，或将这些变更并入现有版本。

---

步骤 6：润色 CHANGELOG 的表述

关键 — 绝不覆盖 CHANGELOG 条目。

此步骤只润色表述，不会重写、替换或重新生成 CHANGELOG 内容。

规则：

1. 先通读整个 CHANGELOG.md，了解现有内容。
2. 只修改现有条目中的措辞。绝不删除、重排或替换条目。
3. 绝不从头重新生成 CHANGELOG 条目。该条目基于实际差异和提交历史编写，是事实依据。你要润色文字，而不是改写历史。
4. 如果某个条目看起来有误或不完整，请使用 AskUserQuestion — 不要擅自修正。
5. 使用 Edit 工具和精确的 old_string 匹配 — 绝不使用 Write 覆盖 CHANGELOG.md。

如果当前分支未修改 CHANGELOG： 跳过此步骤。

如果当前分支修改了 CHANGELOG， 请检查条目的表述风格：

• 吸引力检验： 用户读到每条内容时，是否会觉得“不错，我想试试”？如果不会，改写措辞（不要改动内容）。
• 先说明用户现在可以做什么，不要先讲实现细节。
• 用“你现在可以……”而不是“重构了……”。
• 标记并改写任何读起来像提交说明的条目。
• 内部或贡献者相关的变更应单独放入“### 贡献者须知”小节。
• 自动修正轻微的表述问题。如果改写会改变含义，请使用 AskUserQuestion。
• 如果在步骤 5 中更新了 VERSION，请确认 CHANGELOG 条目引用了正确的版本号。

步骤 7：跨文档一致性、链接与可发现性检查

逐个审核完文件后，进行跨文档一致性检查：

1. README 的功能／能力列表是否与 CLAUDE.md/AGENTS.md 中的描述一致？
2. ARCHITECTURE 的组件列表是否与 CONTRIBUTING 对项目结构的描述一致？
3. CHANGELOG 的最新版本是否与 VERSION 文件一致？
4. **可发现性：**每个文档文件都能否从 README.md 或 CLAUDE.md 找到？如果存在 ARCHITECTURE.md，但 README 和 CLAUDE.md 都没有链接到它，请标记出来。每个文档都应能从这两个入口文件之一找到。
5. 标记文档之间的任何矛盾。自动修复明确的事实不一致（例如版本不匹配）。对于叙述性矛盾，使用 AskUserQuestion。
6. **内部链接检查：**扫描所有文档文件中的相对链接，包括文件链接（如 [Architecture](./ARCHITECTURE.md)）和锚点链接（如 [see setup](#setup)）。对于文件链接，使用 Glob 验证目标文件是否存在。对于锚点链接，验证目标标题是否存在于链接指向的文件中。尤其要关注差异中涉及文件重命名、删除或标题变更的情况。如果目标文件显然是重命名后的文件，自动修复失效的文件链接（使用 git diff --diff-filter=R 检测重命名）。如果目标不明确，则使用 AskUserQuestion。

---

步骤 8：清理 TODOS.md

如果 TODOS.md 不存在，则跳过此步骤。

1. **尚未标记的已完成事项：**将差异与未完成的 TODO 项交叉比对。如果当前分支的更改明确完成了某项 TODO，请将其移至 Completed 部分，并标注 **Completed:** vX.Y.Z (YYYY-MM-DD)。应谨慎处理——只有差异中有明确证据时才标记为已完成。

2. **需要更新描述的事项：**如果某项 TODO 提到了已发生重大变更的文件或组件，其描述可能已过时。使用 AskUserQuestion 确认应更新、完成还是保持不变。

3. **新增的待处理工作：**检查差异中的 TODO、FIXME、HACK 和 XXX 注释。对于每个代表有意义的待处理工作（而非琐碎的行内备注）的注释，使用 AskUserQuestion 询问是否应将其记录在 TODOS.md 中。

---

步骤 9：提交并输出

**先检查是否为空：**运行 git status（绝不使用 -uall）。如果之前的步骤没有修改任何文档文件，则输出 "All documentation is up to date." 并退出，不进行提交。

提交：

1. 按名称暂存修改过的文档文件（绝不运行 git add -A 或 git add .）。
2. 根据步骤 3–6 中生成的单行摘要编写描述性提交消息。将这些摘要合并到提交正文中，让 git log 能清楚说明更改内容，而不只是写 "updated docs."。例如：

git commit -m "$(cat <<'EOF'
docs: update documentation to match shipped changes

- README.md: added /new-skill to skills table, updated skill count from 9 to 10
- ARCHITECTURE.md: updated component diagram to reflect new service layer
- CHANGELOG.md: polished voice for v2.3.0 entry

Co-Authored-By: Claude Opus 4.6 <[email protected]>
EOF
)"

主题行不得超过 72 个字符。正文中以项目符号列出每个修改文件及其单行摘要。如果只修改了一个文件，则只需填写主题行。

3. 推送到当前分支：

git push

更新 PR 正文（如果存在 PR）：

1. 将现有 PR 正文读入临时文件（使用 mktemp 以避免冲突）：

PR_BODY_TMP=$(mktemp /tmp/pr-body-XXXXXX.md)
gh pr view --json body -q .body > "$PR_BODY_TMP"

2. 如果正文已包含 ## Documentation 部分，则替换该部分；否则在正文末尾追加该部分。请包含一份文档差异预览，说明每个修改文件的具体变更。

3. 写回并清理：

gh pr edit --body-file "$PR_BODY_TMP"
rm -f "$PR_BODY_TMP"

4. 如果 gh pr view 失败（不存在 PR），则跳过并输出 "No PR found — skipping body update."

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

Documentation health:
  README.md       [status] ([details])
  ARCHITECTURE.md [status] ([details])
  CONTRIBUTING.md [status] ([details])
  CHANGELOG.md    [status] ([details])
  TODOS.md        [status] ([details])
  VERSION         [status] ([details])

其中，状态为以下之一：

• Updated — 说明变更内容
• Current — 无需更改
• Voice polished — 已调整措辞
• Links fixed — 已修复失效链接
• Not bumped — 用户选择跳过
• Already bumped — 版本已由 /ship 设置
• Skipped — 文件不存在

如果 gh 不可用（在步骤 0 中检测到），请在摘要中注明 "PR body update skipped (gh not authenticated)"。

---

重要规则

• 编辑前先阅读。 修改文件前，务必先阅读其完整内容。
• 绝不覆盖 CHANGELOG。 只能润色措辞，绝不删除、替换或重新生成条目。
• 绝不擅自更新 VERSION。 务必先询问。
• 明确说明更改内容。 每次编辑都附上一行摘要。
• 采用通用启发式，而非项目特定规则。 审查应适用于任何代码仓库。
• 注重可发现性。 每个文档文件都应能从 README 或 CLAUDE.md 访问。
• 语气：友好、以用户为中心、通俗易懂。 写得像是在向一位聪明但不了解代码的人解释。