---
name: qkeymapper-release-notes
description: 为 QKeyMapper 编写 README.md 的中文 release note，并默认联动 qkeymapper-readme-en-sync 定向同步更新英文版 README_en.md。收集最近正式 release tag 之后的已提交更新，先展示中英双语完整草稿供审阅，批准实施后分阶段原子提交两个 README。用于发布说明、更新日志和中英文版本信息维护。
---

# QKeyMapper Release Notes

维护仓库根目录 `README.md` 的“新添加功能列表(根据更新时间降序排列)”段，并默认联动 `qkeymapper-readme-en-sync` 定向同步更新 `README_en.md` 对应 Build 条目。说明面向使用者，沿用现有格式，简洁描述使用上的关键点。遵守仓库指令，不增加脚本、依赖或全局配置。

## 先审阅，再实施

- 首次调用只读收集证据并展示完整草稿，不写文件、不暂存、不提交。用户已明确批准当前草稿并要求实施时，直接进入实施阶段，不重复索要确认。
- **默认中英双语协同审阅**：默认同时展示中文版 `README.md` 待发布条目草稿，以及根据 `qkeymapper-readme-en-sync` 定向同步规范生成的英文版 `README_en.md` 翻译草稿。用户一次批准，同时授权两阶段限定本地提交（先提交中文版，后提交英文版）。
- **支持仅中文降级**：若用户明确要求“仅更新中文”、“仅草稿”或“不改英文版”，则仅生成并提交中文版 release note，跳过英文版同步。
- 技能不能切换 Codex 协作模式，也不能保证出现原生计划按钮。建议用户在计划模式调用 `$qkeymapper-release-notes`；处于计划模式时，以 `<proposed_plan>` 展示计划，等待用户通过界面开始实施并实际退出计划模式。普通模式下展示同样的草稿，等待明确批准。
- 草稿批准同时授权本次本地提交，计划中必须明确说明提交策略。用户明确要求仅草稿、不提交或调整范围时，遵从其要求。不能把技能的自动匹配视为未经审阅即可提交的授权。
- 需要等待审阅时，引用本技能路径及“首次调用只读收集证据并展示完整草稿，不写文件、不暂存、不提交。”，简短说明这是用户要求的审阅步骤。

## 收集证据

1. 确认 Git 仓库根目录、分支、HEAD 完整哈希、工作区和暂存区状态。记录中文 `README.md` 及英文 `README_en.md` 当前内容及已有差异，后续复核使用；不要创建额外的仓库状态文件。
2. 从本地正式标签中选取基准，名称严格匹配 `^v[0-9]+\.[0-9]+\.[0-9]+\.[0-9]{8}$`，并检查日期有效。将 annotated tag 解析到提交；排除测试/预发布标签。默认沿 HEAD 的 first-parent 历史选择最近的正式标签，不按创建时间或名称字典序选取。若同一提交有多个正式标签、其他合并分支的正式标签使发布主线不明确，列出候选请用户指定。无符合标签或历史不完整时也请用户指定，不猜测基准。
3. 不自动 fetch，明确此次依据本地标签。固定范围为基准提交到审阅时 HEAD，即 `release_tag..HEAD`，包含已合入该范围的分支提交。只收集已提交更新；未提交源码仅提示存在，不写入更新说明、不一并提交。
4. 阅读范围内提交记录、`git diff <base> <head>` 的最终差异，以及必要的相关源码。使用提交说明定位线索，不能直接翻译标题。合并同一功能的多次修复，排除最终已撤销的功能；部分撤销按最终行为描述。纯重构、构建内部细节、代理技能/经验文档、纯 release note 提交不作为用户更新点。
5. 同时读取 `git show <base>:README.md`、HEAD 中的 README 和当前 README，识别已记录内容及发布边界。已有说明不是新功能证据，必要时核对实现；不把“已编译”或“源码有实现”写成“已运行验证”。

## 组织待发布条目

- 版本和 Build 日期按以下优先级选择：用户本次明确指定的值；当前 README 已有待发布目标条目的值；仅在没有待发布条目、需要新建时，沿用现有产品版本并使用用户当前时区的当天日期。用户仅指定其中一项时，另一项仍按此规则选择。不修改程序版本、标签或发布配置。
- 原样保留已有待发布标题，即使日期在未来或已经过去，也不自动调整、不因未来日期本身再次询问，无需证明日期是用户手动修改的。是否已发布仍依据 release tag 和历史判断。例如已有 `v1.3.8(Build 20260912)`，后续更新直接合入该段，不改为当天日期、不另建当天条目；用户本次明确要求改期时除外。
- 合并本次发布前的未发布更新段为一个待发布条目，并保留已发布历史。结合基准 README、提交历史和当前内容识别未发布段，不仅比较日期。同日标签之后追加到旧日期段的内容也可能尚未发布；不能据此擅自移动或重写历史，边界不清时展示差异并请用户确认。
- 多个已确认的未发布段需要合并时，默认以列表顶部的待发布段为目标并保留其标题，除非用户本次明确指定其他版本或日期。不要因合并而重设日期；发布边界不清时才确认合并范围。
- 对所有已有条目去重；已发布的说明不要重新加入待发布段。保留待发布段中仍有证据支持的更新，不因单条提交标题不明显而遗漏。
- 若内容已经完整、没有实质更新，不因调用日期变化而改动 README，不创建空条目或空 commit。需要更新时按上述优先级选定标题并保持日期降序，不为排序擅自改期；用户明确要求改期属于有意修改，不属于自动刷新日期。
- 中文条目格式：沿用 `* vX.Y.Z(Build YYYYMMDD)` 和缩进的 `*` 条目格式。按用户功能组织说明，同一功能的相关调整和修复合并为一条，不按提交数或修复点逐项展开。每条默认一句话，说明调整了什么功能及主要效果；不为完整罗列证据增加细节。
- 默认省略恢复正常行为的细节（如列宽自适应）、内部调用和菜单同步过程。例如同次视图修复可概括为“修复视图选项切换及设定变更提示相关问题”。仅当影响用户操作、兼容性或排障时补充必要信息，如快捷键及生效条件、诊断文件位置；不得省略关键限制或夸大效果。
- **英文版定向同步草稿规范**（严格遵守 `qkeymapper-readme-en-sync` 规则）：
  - 格式差异（与中文版不同）：条目标题带空格 `* vX.Y.Z (Build YYYYMMDD)`；要点 4 空格缩进 `* `；子项 6 空格 `- `；Build 条目之间紧接下一条，不空行。
  - 固定术语：使用英文版现有标准用词（Original Key、Mapped Key、Key Release Mapping、Send Timing、Burst、Lock、Long Press、Double Click、Mapping Item Settings window、Floating Button、Virtual Button Panel 等）。
  - 不翻译：所有按键名、映射键名（含参数形式如 `vJoy-Key11(LT)_BRAKE[...]`）、命令行、文件路径、驱动与库名称。
- 审阅输出必须包含：
  1. 基准 tag 及提交哈希、审阅 HEAD、目标版本和日期；
  2. 中文版 `README.md` 待合并或写入的完整 Markdown 草稿；
  3. 英文版 `README_en.md` 定向同步的完整 Markdown 翻译草稿（除非用户明确指定仅更新中文）；
  4. 明确说明“批准实施后将先后执行中文与英文两阶段本地提交”的约定。
- 采用已有日期时，草稿外注明“沿用 README 已有待发布日期”。手动日期尚未提交时，也以当前 README 的该日期生成草稿，同时展示已有差异并确定提交范围；这不改变只收集已提交源码更新的规则，也不自动授权夹带 README 原有修改。
- 无更新时直接说明结果，不输出要求执行空修改的计划。尚有发布边界或内容疑问时先解决，再提交完整草稿供审阅。

## 写入和本地提交

1. 只有当前草稿获批准且实际处于允许写入的模式，才能实施。复核 HEAD、基准标签所指提交、两个 README 和暂存区；内容变化会影响草稿或提交范围时重新展示修订稿等待批准。无关文件变化不扩大本次范围。
2. 两个 README 原有 staged/unstaged 修改必须先展示并明确处理边界，不默认包含在本次提交中。不 stash、reset 或覆盖用户改动。若不能清楚隔离本次修改，暂停提交，请用户先处理或明确授权范围。
3. **两阶段原子本地提交**：
   - **阶段 1：写入并提交中文版 `README.md`**：
     1. 只改批准的更新段，保留其他内容、UTF-8 无 BOM 编码和换行风格。
     2. 运行 `git diff --check`，核对完整差异。
     3. README 原先无用户改动时，执行限定路径提交：`git commit --only -m "docs: update release notes for Build YYYYMMDD" -- README.md`，避免夹带其他已暂存文件；严禁使用 `git add .`、`git commit -a` 或不限定范围的提交。README 原先有改动时先按第 2 步解决范围。提交消息中的 `YYYYMMDD` 使用批准稿的目标 Build 日期，不使用执行当天日期。
   - **阶段 2：定向同步写入并提交英文版 `README_en.md`**（默认执行，若指定仅中文则跳过）：
     1. 按照 `/qkeymapper-readme-en-sync Build <日期>` 的定向同步规则，将英文草稿写入 `README_en.md`（若英文版尚未包含该 Build 则按日期降序紧接插入下一条；若已存在则仅对条目内部 bullet 要点比对补漏）。
     2. 运行 `git diff --check` 确认无格式错误；确认文件仍为 UTF-8 无 BOM 且条目间无多余空行。
     3. README_en.md 原先无用户改动时，执行限定路径提交：`git commit --only -m "docs: sync README_en.md for Build YYYYMMDD" -- README_en.md`，避免夹带。
4. 不 push、不打 tag、不创建远端 release、不 amend。Git 写权限不足时按环境权限流程处理；若仍被阻止，保留已完成文档，说明未提交及原因，不声称成功。
5. 提交后检查各提交实际只含批准的对应单个 README 修改，并核对其他文件的 staged/unstaged 状态未被改变。报告两阶段 commit ID、更新版本和检查结果；存在其他工作区修改时不要称工作区干净。

## 验收要点

- 正常调用（默认双语）：草稿前零写入，明确 tag 到 HEAD 的范围；批准实施后先后产生两个限定的独立本地 commit（中文 release notes 提交 + 英文定向同步提交）。
- 仅中文模式：用户明确指定仅更新中文时，跳过英文同步，仅产生 1 个 `README.md` 的本地 commit。
- 重复调用/无新增：不重复条目、不仅刷新日期、不空提交。
- 日期与格式对齐：草稿与 commit 消息日期一致；中文版标题无空格 `* vX.Y.Z(Build YYYYMMDD)`，英文版标题有空格 `* vX.Y.Z (Build YYYYMMDD)` 且 4 空格缩进。
- 未提交日期修改：草稿沿用当前 README 日期，但先明确原有差异的提交范围，不自动夹带；仅调用日期变化不产生修改或 commit。
- 未提交源码：提示但排除；其他文件已暂存：不夹带、不取消暂存。
- README 有用户改动：先确定边界；审阅后 HEAD/tag/README 改变：复核，影响草稿则重新审阅。
- 回滚提交：检查最终差异，不宣告已撤销的功能；已发布和未发布条目同日混合：不擅自按日期搬移历史。