# Qkeymapper Release Notes > 为 QKeyMapper 编写 README.md 的中文 release note，收集最近正式 release tag 之后的已提交更新，先展示完整草稿供审阅，批准实施后仅更新 README 并创建本地 commit。用于发布说明、更新日志和“新添加功能列表”维护。 - Skill: `zalafina/qkeymapper-release-notes` (Agent Skill) - Install (CLI): `npx skillmds@latest add zalafina/qkeymapper-release-notes` - Raw SKILL.md: https://api.skillmd.com/api/skills/zalafina/qkeymapper-release-notes/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: zalafina (https://skillmd.com/u/zalafina) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/zalafina/qkeymapper-release-notes --- # QKeyMapper Release Notes 只维护仓库根目录 `README.md` 的“新添加功能列表(根据更新时间降序排列)”段。说明面向使用者，沿用现有格式，简洁描述使用上的关键点。遵守仓库指令，不增加脚本、依赖或全局配置。 ## 先审阅，再实施 - 首次调用只读收集证据并展示完整草稿，不写文件、不暂存、不提交。用户已明确批准当前草稿并要求实施时，直接进入实施阶段，不重复索要确认。 - 技能不能切换 Codex 协作模式，也不能保证出现原生计划按钮。建议用户在计划模式调用 `$qkeymapper-release-notes`；处于计划模式时，以 `` 展示计划，等待用户通过界面开始实施并实际退出计划模式。普通模式下展示同样的草稿，等待明确批准。 - 草稿批准同时授权本次 README 本地提交，计划中必须明确这一点。用户明确要求仅草稿、不提交或调整范围时，遵从其要求。不能把技能的自动匹配视为未经审阅即可提交的授权。 - 需要等待审阅时，引用本技能路径及“首次调用只读收集证据并展示完整草稿，不写文件、不暂存、不提交。”，简短说明这是用户要求的审阅步骤。 ## 收集证据 1. 确认 Git 仓库根目录、分支、HEAD 完整哈希、工作区和暂存区状态。记录 README 当前内容及已有差异，后续复核使用；不要创建额外的仓库状态文件。 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 ` 的最终差异，以及必要的相关源码。使用提交说明定位线索，不能直接翻译标题。合并同一功能的多次修复，排除最终已撤销的功能；部分撤销按最终行为描述。纯重构、构建内部细节、代理技能/经验文档、纯 release note 提交不作为用户更新点。 5. 同时读取 `git show :README.md`、HEAD 中的 README 和当前 README，识别已记录内容及发布边界。已有说明不是新功能证据，必要时核对实现；不把“已编译”或“源码有实现”写成“已运行验证”。 ## 组织待发布条目 - 版本和 Build 日期按以下优先级选择：用户本次明确指定的值；当前 README 已有待发布目标条目的值；仅在没有待发布条目、需要新建时，沿用现有产品版本并使用用户当前时区的当天日期。用户仅指定其中一项时，另一项仍按此规则选择。不修改程序版本、标签或发布配置。 - 原样保留已有待发布标题，即使日期在未来或已经过去，也不自动调整、不因未来日期本身再次询问，无需证明日期是用户手动修改的。是否已发布仍依据 release tag 和历史判断。例如已有 `v1.3.8(Build 20260912)`，后续更新直接合入该段，不改为当天日期、不另建当天条目；用户本次明确要求改期时除外。 - 合并本次发布前的未发布更新段为一个待发布条目，并保留已发布历史。结合基准 README、提交历史和当前内容识别未发布段，不仅比较日期。同日标签之后追加到旧日期段的内容也可能尚未发布；不能据此擅自移动或重写历史，边界不清时展示差异并请用户确认。 - 多个已确认的未发布段需要合并时，默认以列表顶部的待发布段为目标并保留其标题，除非用户本次明确指定其他版本或日期。不要因合并而重设日期；发布边界不清时才确认合并范围。 - 对所有已有条目去重；已发布的说明不要重新加入待发布段。保留待发布段中仍有证据支持的更新，不因单条提交标题不明显而遗漏。 - 若内容已经完整、没有实质更新，不因调用日期变化而改动 README，不创建空条目或空 commit。需要更新时按上述优先级选定标题并保持日期降序，不为排序擅自改期；用户明确要求改期属于有意修改，不属于自动刷新日期。 - 沿用 `* vX.Y.Z(Build YYYYMMDD)` 和缩进的 `*` 条目格式。按用户功能组织说明，同一功能的相关调整和修复合并为一条，不按提交数或修复点逐项展开。每条默认一句话，说明调整了什么功能及主要效果；不为完整罗列证据增加细节。 - 默认省略恢复正常行为的细节（如列宽自适应）、内部调用和菜单同步过程。例如同次视图修复可概括为“修复视图选项切换及设定变更提示相关问题”。仅当影响用户操作、兼容性或排障时补充必要信息，如快捷键及生效条件、诊断文件位置；不得省略关键限制或夸大效果。 - 审阅输出必须包含：基准 tag 及提交哈希、审阅 HEAD、目标版本和日期、将合并或替换的现有条目、可直接写入的完整 Markdown，以及“批准实施后仅更新并本地提交 README”的约定。证据或疑问放在草稿外，不进入 README。 - 采用已有日期时，草稿外注明“沿用 README 已有待发布日期”。手动日期尚未提交时，也以当前 README 的该日期生成草稿，同时展示已有差异并确定提交范围；这不改变只收集已提交源码更新的规则，也不自动授权夹带 README 原有修改。 - 无更新时直接说明结果，不输出要求执行空修改的计划。尚有发布边界或内容疑问时先解决，再提交完整草稿供审阅。 ## 写入和本地提交 1. 只有当前草稿获批准且实际处于允许写入的模式，才能实施。复核 HEAD、基准标签所指提交、README 和暂存区；内容变化会影响草稿或提交范围时重新展示修订稿等待批准。无关文件变化不扩大本次范围。 2. README 原有 staged/unstaged 修改必须先展示并明确处理边界，不默认包含在本次提交中。不 stash、reset 或覆盖用户改动。若不能清楚隔离本次 README 修改，暂停提交，请用户先处理或明确授权范围。 3. 只改批准的更新段，保留其他内容、编码和换行；不改 `README_en.md`、源码或标签。核对完整差异、条目顺序和重复项，运行 `git diff --check`。文档任务不运行编译或设备测试。 4. 提交前确认 README 差异与批准稿一致。README 原先无用户改动时，使用限定路径的 `git commit --only -m "docs: update release notes for Build YYYYMMDD" -- README.md`，避免夹带其他已暂存文件；不要使用 `git add .`、`git commit -a` 或不限定范围的提交。README 原先有改动时先按第 2 步解决范围，不能直接执行整文件提交。 提交消息中的 `YYYYMMDD` 使用批准稿的目标 Build 日期，不使用执行当天日期。 5. 不 push、不打 tag、不创建远端 release、不 amend。Git 写权限不足时按环境权限流程处理；若仍被阻止，保留已完成文档，说明未提交及原因，不声称成功。 6. 提交后检查提交实际只含批准的 README 修改，并核对其他文件的 staged/unstaged 状态未被改变。报告 commit ID、更新版本和检查结果；存在其他工作区修改时不要称工作区干净。 ## 验收要点 - 正常调用：草稿前零写入，明确 tag 到 HEAD 的范围，批准实施后只有 README 的一个本地 commit。 - 重复调用/无新增：不重复条目、不仅刷新日期、不空提交。 - 日期选择：未来日期和已过但未发布日期均保留；用户明确改期时采用指定值；没有待发布段才默认当天；多个待发布段合并保留顶部目标标题。草稿与 commit 消息日期一致。 - 未提交日期修改：草稿沿用当前 README 日期，但先明确原有差异的提交范围，不自动夹带；仅调用日期变化不产生修改或 commit。 - 未提交源码：提示但排除；其他文件已暂存：不夹带、不取消暂存。 - README 有用户改动：先确定边界；审阅后 HEAD/tag/README 改变：复核，影响草稿则重新审阅。 - 回滚提交：检查最终差异，不宣告已撤销的功能；已发布和未发布条目同日混合：不擅自按日期搬移历史。