patch-notes

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation

自动化模式：解析 modes.automation（project.local.yaml → project.yaml → 默认值 collaborative）。每次调用 AskUserQuestion 和 每次写入文件都遵循 .claude/docs/automation-modes.md （collaborative 始终提问 · guided 仅重大事项提问 · autonomous 记录并继续； automation_always_ask 类别始终提示）。

补丁说明

来源检查——读取任何历史记录前

确认你即将读取的历史记录属于此游戏。 在 Phase 2 之前运行此检查，若失败则停止。

1. 查看近期日志：git log --oneline -20。如果日志为空或 git 不可用，请跳过此检查——没有内容需要分类，Phase 2 中“无变更日志数据”分支就是正确的停止方式。
2. 逐条对范围内的每个提交进行分类，且只能归入以下类别之一：
   • 游戏——更改玩家所玩的游戏：机制、内容、平衡性、美术、音频、UI，或上述任何方面的错误。
   • 框架／维护——更改 CCGS 本身或项目工具：主题涉及技能、钩子、Agent、测试计划、CI、框架自身文档的提交。不纳入面向玩家的说明，但不是停止的理由。
   • 不明确——视为框架。无法确信归属的提交不能用来撰写面向玩家的文案。
3. 然后根据数量作出判断：
   • 至少有一个游戏提交 → 继续，但只使用这些提交。说明使用了多少条（共多少条），让读者知道筛选已执行。
   • 没有游戏提交 → 使用下方的消息并停止，同时给出数量（0 条，共多少条），让读者知道筛选已执行。

逐条筛选；不要因为仓库中包含维护工作就停止。 基于此框架构建的每个项目都会积累涉及钩子、CI 和技能的提交——游戏仓库本身就是框架仓库，因此仓库级停止条件几乎会触发于每个真实项目。危险不在于这类提交存在，而在于它们被写成面向玩家的文案。排除这些提交正好能解决这个问题，而仓库级停止条件解决不了。

继续之前，先用低成本方式交叉验证：游戏提交应提及 design/ 和代码根目录（src/、Assets/ 或 Source/）中出现的系统。如果提交提及这些目录从未提到的产品，那才是真正的历史记录错误信号——停止。

如果范围内没有任何提交属于此游戏，请说明并停止：

“此仓库中的 git 历史记录似乎不属于 [game]：近期 [N] 条提交中，游戏提交为 0 条。近期 提交描述的是 [它们实际描述的内容]。我无法据此生成发行说明——请提供正确的历史记录，或直接提供变更列表。”

结论：已阻止——在此停止，不要生成说明。

为何这是硬性停止条件，而非警告。 将框架内部提交写成面向玩家的文案，会让它们看起来像真实改动：会话钩子的超时问题变成了这样一句话：“修复了启动时可能丢失上次会话进度的问题”，但游戏根本没有存档系统。这段文案流畅、可信，却完全错误。读者无法分辨其中差异；只有此检查能做到。

---

Phase 1：解析参数

• version：要生成说明的发行版本（例如 1.2.0）
• --style：输出风格——brief（项目符号）、detailed（附带背景信息）、full（附带开发者说明）。默认值：detailed。

如果未提供版本，请先询问用户再继续。

---

阶段 2：收集变更数据

• 如果内部更新日志 production/releases/[version]/changelog.md 存在，请阅读
• 同时检查 docs/CHANGELOG.md 中与相关版本对应的条目
• 作为备用方案，运行 git log，查看上一个发布标签与当前标签/HEAD 之间的提交记录
• 阅读 production/sprints/ 中的冲刺回顾，了解背景
• 阅读 design/balance/ 中的平衡性调整文档
• 如果有 QA 的错误修复记录，也请阅读

如果没有可用的更新日志数据（既不存在 production/releases/[version]/changelog.md，也没有 docs/CHANGELOG.md 中该版本的条目，且 git log 为空或不可用）：

"No changelog data found for [version]. Run /changelog [version] first to generate the internal changelog, then re-run /patch-notes [version]."

结论：已阻止——在此处停止，不要生成说明。

---

阶段 2b：检测语气指南和模板

语气指南检测——起草说明前，检查是否有写作风格指南：

1. 检查 .claude/docs/technical-preferences.md 中是否有任何“语气”“口吻”或“风格”字段或章节。
2. 检查 docs/PATCH-NOTES-STYLE.md 是否存在。
3. 检查 design/community/tone-guide.md 是否存在。
4. 如果任何来源包含语气/口吻/风格说明，提取并应用到生成说明的语言和表达方式中。
5. 如果没有找到任何语气指南，默认采用：对玩家友好、非技术性的语言；热情但不夸张；聚焦玩家的体验，而非开发者所做的改动。

模板检测——检查是否存在更新说明模板：

1. 查找 docs/patch-notes-template.md 和 .claude/docs/templates/patch-notes-template.md。
2. 如果任一位置存在模板，请阅读并将其用作阶段 4 的输出结构，替代内置风格模板（简要 / 详细 / 完整）。将分类后的数据填入模板的各个章节，把每个类别映射到含义相同的模板章节（新增内容 → 新功能章节，错误修复 → 修复章节）；没有对应章节的类别应放入最接近的章节，不得省略。保留模板原有的页眉和页脚文本。请在输出中说明使用了哪个模板；如果传入了 --style，还要说明模板取代了该风格。
3. 如果未找到模板，则使用阶段 4 中定义的内置风格模板。

---

阶段 3：分类并转换语言

将所有变更归类为面向玩家的类别：

• 新增内容：新功能、地图、角色、物品、模式
• 玩法变更：平衡性调整、机制变更、进度变更
• 易用性改进：UI 改进、便利功能、无障碍功能
• 错误修复：按系统分组（战斗、UI、网络等）
• 性能：玩家可能察觉到的优化改进
• 已知问题：坦诚说明尚未解决的问题

将开发者语言转换为玩家语言：

• “重构伤害计算流程” → “提升命中判定的准确性”
• “修复物品栏管理器中的空引用” → “修复打开物品栏时发生崩溃的问题”
• “减少战斗循环中的 GC 分配” → “提升战斗性能”
• 移除不会影响玩家的纯内部改动
• 保留平衡性调整的具体数值（伤害：50 → 45）

---

阶段 4：生成更新说明

简要风格

# Patch [Version] — [Title]

**New**
- [Feature 1]
- [Feature 2]

**Changes**
- [Balance/mechanic change with before → after values]

**Fixes**
- [Bug fix 1]
- [Bug fix 2]

**Known Issues**
- [Issue 1]

详细风格

# Patch [Version] — [Title]
*[Date]*

## Highlights
[1-2 sentence summary of the most exciting changes]

## New Content
### [Feature Name]
[2-3 sentences describing the feature and why players should be excited]

## Gameplay Changes
### Balance
| Change | Before | After | Reason |
| ---- | ---- | ---- | ---- |
| [Item/ability] | [old value] | [new value] | [brief rationale] |

### Mechanics
- **[Change]**: [explanation of what changed and why]

## Quality of Life
- [Improvement with context]

## Bug Fixes
### Combat
- Fixed [description of what players experienced]

### UI
- Fixed [description]

### Networking
- Fixed [description]

## Performance
- [Improvement players will notice]

## Known Issues
- [Issue and workaround if available]

完整风格

包含详细风格的所有内容，另加：

## Developer Commentary
### [Topic]
> [Developer insight into a major change — why it was made, what was considered,
> what the team learned. Written in first-person team voice.]

---

阶段 5：审核输出

检查生成的说明，确保：

• 不含内部术语（将技术术语替换为玩家友好的语言）
• 不提及内部系统、工单或冲刺编号
• 平衡性调整包含调整前后的数值
• 错误修复描述玩家体验，而非技术原因
• 语气符合游戏的风格（根据游戏风格调整正式程度）

---

阶段 6：保存补丁说明

向用户展示已完成的补丁说明，并附上：按类别统计的变更数量，以及为供审查而排除的任何内部变更。

询问：“可以将这些补丁说明写入 docs/patch-notes/[version].md，并在 production/releases/[version]/patch-notes.md 中保存一份归档副本吗？”

如果可以，写入这两个文件，并在需要时创建目录。 如果不可以，则不写入任何内容。

---

阶段 7：后续步骤

结论：已完成——补丁说明已生成并保存。（如果用户拒绝写入：结论：已完成——补丁说明已生成并展示，未保存。）

• 运行 /release-checklist，在发布前确认所有其他发布门槛均已满足。
• 在公开发布前，将补丁说明草稿分享给 community-manager，请其审阅语气。