---
name: patch-notes
description: "从 git 历史记录、Sprint 数据和内部更新日志生成面向玩家的补丁说明。将开发者语言转化为清晰、有吸引力的玩家沟通内容。"
argument-hint: "[版本号] [--style brief|detailed|full]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Bash
---

当此技能被调用时：

1. **解析参数**：
   - `version`：要生成补丁说明的发布版本（例如 `1.2.0`）
   - `--style`：输出风格 — `brief`（要点列表）、`detailed`（含上下文）、`full`（含开发者评论）。默认：`detailed`。

2. **从多个来源收集变更数据**：
   - 如果存在，读取内部更新日志 `production/releases/[version]/changelog.md`
   - 运行 `git log` 查看上一个发布标签与当前标签/HEAD 之间的变更
   - 读取 `production/sprints/` 中的 Sprint 回顾以获取上下文
   - 读取 `design/balance/` 中的数值平衡变更文档
   - 如果可用，读取 QA 的 Bug 修复记录

3. **将所有变更分类**为面向玩家的类别：
   - **新内容**：新功能、地图、角色、物品、模式
   - **玩法变更**：数值平衡调整、机制变更、进度变更
   - **体验优化 (Quality of Life)**：UI 改进、便利功能、无障碍
   - **Bug 修复**：按系统分组（战斗、UI、联网等）
   - **性能**：玩家可能注意到的优化改进
   - **已知问题**：透明地告知未解决的问题

4. **将开发者语言翻译为玩家语言**：
   - "重构了伤害计算管线" -> "提升了命中检测的准确性"
   - "修复了背包管理器中的空引用" -> "修复了打开背包时的崩溃问题"
   - "减少了战斗循环中的 GC 分配" -> "改善了战斗性能"
   - 移除不影响玩家的纯内部变更
   - 保留数值平衡变更的具体数字（伤害：50 -> 45）

5. **使用适当的风格生成补丁说明**：

### 简要风格
```markdown
# 补丁 [版本] — [标题]

**新增**
- [功能 1]
- [功能 2]

**变更**
- [数值平衡/机制变更，附变更前 -> 变更后的值]

**修复**
- [Bug 修复 1]
- [Bug 修复 2]

**已知问题**
- [问题 1]
```

### 详细风格
```markdown
# 补丁 [版本] — [标题]
*[日期]*

## 亮点
[1-2 句话总结最令人兴奋的变更]

## 新内容
### [功能名称]
[2-3 句话描述该功能以及玩家应该期待什么]

## 玩法变更
### 数值平衡
| 变更 | 变更前 | 变更后 | 原因 |
| ---- | ---- | ---- | ---- |
| [物品/技能] | [旧值] | [新值] | [简要理由] |

### 机制
- **[变更]**：[变更内容及原因的说明]

## 体验优化
- [改进及上下文]

## Bug 修复
### 战斗
- 修复了 [玩家遇到的问题描述]

### UI
- 修复了 [描述]

### 联网
- 修复了 [描述]

## 性能
- [玩家会注意到的改进]

## 已知问题
- [问题及可用的临时解决方案]
```

### 完整风格
包含详细风格的所有内容，加上：
```markdown
## 开发者寄语
### [主题]
> [开发者对重大变更的洞察 — 为什么这么做、考虑了什么、
> 团队学到了什么。以团队第一人称撰写。]
```

6. **审查输出**，确保：
   - 没有内部术语（用玩家友好的语言替换技术术语）
   - 没有引用内部系统、工单或 Sprint 编号
   - 数值平衡变更包含变更前/后的值
   - Bug 修复描述的是玩家体验，而非技术原因
   - 语气符合游戏的声音风格（根据游戏风格调整正式程度）

7. **保存补丁说明**到 `production/releases/[version]/patch-notes.md`，
   如果需要则创建目录。

8. **向用户输出**：完整的补丁说明、文件路径、按类别的变更计数，以及被排除的内部变更（供审核）。