changelog

!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 类别始终提示）。

更新日志

最近历史

最近的提交：

!git log --oneline -30 2>/dev/null || true

最近的标签（从新到旧）：

!git tag --list --sort=-v:refname 2>/dev/null | head -5

来源检查 — 信任上述历史前

上述提交可能并不属于这款游戏。 此技能的历史区块会在正文运行 前自动解析，因此读取已经发生——这项检查决定的是能否使用该输出，而不是是否获取它。

1. 阅读上方注入的提交主题。如果没有提交——日志为空或 git 不可用——跳过此检查：没有内容需要 分类，Phase 1 中无历史记录的分支就是正确的停止点。
2. 逐条分类为 游戏（机制、内容、平衡、艺术、音频、 UI 或上述方面的 Bug）、框架 / 维护（主题涉及技能、 hooks、Agent、测试计划、CI 或框架自身文档），或 不明确 ——并将不明确归为框架类。
3. 根据数量作出判断：
   • 至少有一条游戏提交 → 仅使用这些提交继续，并说明使用了多少条， 共多少条。
   • 没有游戏提交 → 停止，并使用下方消息。

逐条筛选；包含维护工作的仓库并不意味着仓库错了。 这个框架中的每个项目都会积累涉及 hooks、CI 和 技能的提交——游戏仓库 就是 框架仓库，因此若因此停止，几乎每个真实项目都会触发。 真正的风险是这些提交变成面向玩家的更新说明，而排除它们正好可以避免这一点。

有意让此规则与 /patch-notes 完全一致——两者读取相同历史，但面向不同受众， 对历史归属的判断必须一致。若要更改，必须同时更改两者。

真正表明历史记录属于错误项目的信号有所不同：游戏提交提到某个产品，但 design/ 和代码根目录（src/、Assets/ 或 Source/）从未提及该产品。如果 看到这种情况，请停止。

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

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

结论：已阻止——在此停止，不要生成更新日志。

为什么这是硬性停止，而不是警告。 将框架内部提交写成面向玩家的文案， 会让人误以为是真实的游戏变更：会话钩子的超时会变成“修复了启动时可能丢失上次会话进度的问题”，但游戏根本没有存档系统。这段文案流畅、可信，却完全不真实。读者无法分辨；只有这项检查能够做到。

不要把前置内容的存在当成证据。 注入的输出只表示命令已运行，绝不意味着其主题与游戏有关。

---

两个区块都已在此技能运行前解析。将它们作为 Phase 2 的起点，而不是重新运行相同命令。

阶段 1：解析参数

读取目标版本或冲刺编号参数。如果提供了版本，则使用对应的 git 标签。如果提供了冲刺编号，则使用冲刺日期范围。

确认仓库已初始化：运行 git rev-parse --is-inside-work-tree，确认 git 可用。如果不是 git 仓库，告知用户并妥善终止。

如果没有历史记录可供读取——不是 git 仓库，或尚无提交：

"未找到 git 历史记录。变更日志需根据提交生成——请先提交工作， 或直接提供变更列表。"

结论：受阻——在此停止，不生成变更日志。

---

阶段 2：收集变更数据

读取自上一个标签或版本发布以来的 git 日志：

git log --oneline [last-tag]..HEAD

如果不存在标签，请明确限定范围——git log --oneline -n 100。不要退回到完整日志：在已建立的仓库中，这会为一篇仅涵盖一个版本发布的变更日志带来数千行内容，而且其中最早的提交最不相关。如果 100 次提交还不够，请说明情况并询问起始引用，而不是盲目扩大范围。

读取 production/sprints/ 中相关时间段的冲刺报告，以了解计划工作以及变更背后的背景。

读取 design/gdd/ 中本时间段实施的所有新功能对应的已完成设计文档。按章节读取：使用 Grep 工具（模式 ^#，内容模式）查找所需标题，再使用偏移量和限制参数读取这些范围。

---

阶段 3：对变更进行分类

将每项变更归入以下类别之一：

• 新功能：全新的游戏系统、模式或内容
• 改进：现有功能增强、用户体验改进、性能提升
• 错误修复：修正异常行为
• 平衡性调整：调整游戏数值、难度、经济系统
• 技术债务 / 重构：重构和清理游戏代码，不改变玩家可见内容——提交说明称其为重构、清理或整理，且未提及任何修复、功能或数值调整。仅用于内部变更日志，绝不出现在面向玩家的变更日志中
• 已知问题：团队已知但尚未解决的问题
• 其他：不符合上述类别的变更，或提交说明过于含糊、无法有把握地分类的提交

对每项提交，检查说明中是否包含任务 ID 或故事引用（例如 [STORY-123]、TR-、#NNN 或类似内容）。统计缺少任何任务引用的提交数量，并将此数量纳入阶段 4 的指标部分，格式为：缺少任务引用的提交： [N]。

---

阶段 4：生成内部变更日志

# Internal Changelog: [Version]
Date: [Date]
Sprint(s): [Sprint numbers covered]
Commits: [Count] ([first-hash]..[last-hash])

## New Features
- [Feature Name] -- [Technical description, affected systems]
  - Commits: [hash1], [hash2]
  - Owner: [who implemented it]
  - Design doc: [link if applicable]

## Improvements
- [Improvement] -- [What changed technically and why]
  - Commits: [hashes]
  - Owner: [who]

## Bug Fixes
- [BUG-ID] [Description of bug and root cause]
  - Fix: [What was changed]
  - Commits: [hashes]
  - Owner: [who]

## Balance Changes
- [What was tuned] -- [Old value -> New value] -- [Design intent]
  - Owner: [who]

## Technical Debt / Refactoring
- [What was cleaned up and why]
  - Commits: [hashes]

## Miscellaneous
- [Change that didn't fit other categories, or vague commit message]
  - Commits: [hashes]

## Known Issues
- [Issue description] -- [Severity] -- [ETA for fix if known]

## Metrics
- Total commits: [N]
- Files changed: [N]
- Lines added: [N]
- Lines removed: [N]
- Commits without task reference: [N]

---

阶段 5：生成面向玩家的变更日志

# What is New in [Version]

## New Features
- **[Feature Name]**: [Player-friendly description of what they can now do
  and why it is exciting. Focus on the experience, not the implementation.]

## Improvements
- **[What improved]**: [How this makes the game better for the player.
  Be specific but avoid jargon.]

## Bug Fixes
- Fixed an issue where [describe what the player experienced, not what was
  wrong in the code]
- Fixed [player-visible symptom]

## Balance Changes
- [What changed in player-understandable terms and the design intent.
  Example: "Healing potions now restore 50 HP (up from 30) -- we felt
  players needed more recovery options in late-game encounters."]

## Known Issues
- We are aware of [issue description in player terms] and are working on a
  fix. [Workaround if one exists.]

---
Thank you for playing! Your feedback helps us make the game better.
Report issues at [link].

---

阶段 6：输出

向用户输出两份变更日志。内部变更日志是主要工作文档。面向玩家的变更日志经审核后即可发布到社区。

---

阶段 7：提议写入文件

呈现变更日志后，询问用户：

"可以将此变更日志写入 docs/CHANGELOG.md 吗？ [A] 可以，追加此条目（如果文件已存在，推荐此选项） [B] 可以，完全覆盖文件 [C] 不可以——我会手动复制"

• 询问前检查 docs/CHANGELOG.md 是否存在。如果存在，默认推荐 [A] 追加。
• 如果用户选择 [A]：将新的内部变更日志条目追加到现有文件顶部 （最新条目在前）。
• 如果用户选择 [B]：用新变更日志覆盖整个文件。
• 如果用户选择 [C]：在此停止，不写入文件。

成功写入后：结论：变更日志已写入——变更日志已保存至 docs/CHANGELOG.md。 如果用户拒绝：结论：已完成——变更日志已生成。

---

阶段 7：后续步骤

• 使用 /patch-notes [version] 生成适合公开发布、带样式的版本。
• 对外发布变更日志前，使用 /release-checklist。

指南

• 面向玩家的更新日志中，绝不要透露内部代码引用、文件路径或开发者姓名
• 将相关更改归为一组，而不是逐条列出提交
• 如果提交说明不清晰，请查看相关文件和冲刺数据以了解背景
• 平衡性调整应始终说明设计原因，而不只是列出数值
• 如实说明已知问题——玩家会认可坦诚
• 如果 Git 历史记录混乱（包含合并提交、回滚、修正提交），请整理叙述，不要照搬每条提交记录