AI 写版本更新说明，先整理“这一版对哪些用户开放了什么”，再把代码变更改写成用户语言。不要把提交记录逐条翻译成公告：已合并、已部署和已开放是三个状态，重构或开关关闭的功能不一定该写进用户版。墨刀 AI 客户端可辅助读取本地变更材料、归类并起草，发布范围与开放状态仍要来自团队确认。
更新日志与用户公告，不必写成同一份
研发需要追溯提交、依赖、兼容风险和回滚条件；用户想知道哪里变好了、是否影响自己的操作、要不要做什么。这两种阅读任务不同。保留一份结构化变更表，分别写内部交接版与用户公告版，比把所有细节塞进一段“本次优化了体验”更清楚。
| 产物 | 主要读者 | 应保留的细节 |
|---|---|---|
| 内部变更记录 | 研发、测试、客服及发布负责人 | 版本范围、变更 ID、功能开关、兼容影响、验证状态 |
| 用户更新说明 | 实际使用这一版的人 | 新增能力、修复现象、适用范围、需要采取的动作 |
| 完整提交日志 | 需要追溯代码的人 | 原始提交或 PR、作者、时间等记录 |
GitHub 自动生成发布说明可以基于合并的 PR、贡献者和完整变更链接形成初稿，并按标签归类。它为整理提供材料，但这些列表本身并不能证明每项功能已经向所有用户开放。
开始前，补齐一份发布范围表
先让研发给出上一发布基线与本次目标版本，再由产品或发布负责人确认可见范围。日期只能辅助定位，不能简单把“这周合并的提交”全部视为同一次发布：回滚、挑选提交、分批开放都可能改变范围。
# release-scope.md
产品：预约管理后台
目标版本：v1.8
上一发布基线：由研发填写实际 tag/commit
本次发布基线：由研发填写实际 tag/commit
开放状态：以下变更表逐项确认
发布渠道：站内更新页
读者：使用预约管理后台的管理员
语气：说清操作变化，不写未测得的效率百分比
输出：internal-handoff.md 与 user-release-notes.md
外发：本任务仅生成草稿，不自动发布如果当前只能拿到工单、PR 摘要和验收记录，也可以先整理；缺少版本基线时标记范围待确认，不用猜一个提交区间。需要处理大量本地材料时，可参考本地项目的资料分层，把源材料与公告草稿分开放。
六项变更，哪些应该写给用户
下面是一组预约后台的写作练习。关键不在条目多少，而在每条是否有用户可感知的变化以及确切的开放范围。
| 变更 ID | 内部记录 | 状态 | 用户版处理 |
|---|---|---|---|
| C-01 | 成员列表增加角色筛选 | 已部署，对全部管理员开放 | 写为新增；说明在哪里、能做什么 |
| C-02 | 修复切换月份后日历仍显示旧月份数据 | 已部署并验证，对全部用户开放 | 写为修复；描述原来的现象 |
| C-03 | 重构成员列表的数据请求模块 | 已部署，操作无变化 | 留在内部记录，不凑一条“体验升级” |
| C-04 | 批量预约导入功能完成合并 | 未部署，尚未开放 | 不写进本版用户公告 |
| C-05 | 预约提醒支持新渠道 | 仅指定试用团队开放 | 一般公告不称全面支持；如需说明，明确试用范围 |
| C-06 | 修复表格空状态在窄屏上的错位 | 已部署，对全部用户开放 | 可以与相关展示修复合并说明 |
C-04 最容易被 AI 写错：提交摘要常用“新增某功能”，却没有表达开放状态。应先把这六条转成事实表再写正文，不要让模型从语气猜测是否上线。
把技术描述改成用户能辨认的变化
| 不够清楚的表述 | 更有用的表述 | 为什么 |
|---|---|---|
| 优化列表查询逻辑 | 成员列表新增角色筛选，可按角色缩小查找范围 | 说清新增入口及结果 |
| 修复状态不同步问题 | 修复切换月份后，预约日历仍可能显示上个月数据的问题 | 用户能识别是否与自己遇到的现象一致 |
| 全面提升响应速度 | 只有得到可靠测量和适用条件后才写性能变化；否则不写百分比 | 避免把重构或主观感受当成性能结论 |
| 支持新的提醒渠道 | 新提醒渠道已向指定试用团队开放，其他团队暂不受影响 | 把范围写进正文，不埋在脚注 |
| 修复若干问题 | 修复窄屏查看时，空列表提示与表格边界错位的问题 | 给出可辨认的行为，减少空话 |
一条更新最好回答三个问题中的至少两个：改了哪里、现在可以怎样做、谁会受影响。不是每条都要写收益，更不要把每项小修复扩成“全新体验”。与用户操作没有直接关系的内部调整，可以不进入公告。
一条可复制的 AI 写作指令
请读取 release-scope.md 和本次变更表，生成两个 Markdown 草稿。
先列事实表：ID、用户可见变化、开放范围、来源、待确认。
若缺少开放状态，不推断为已上线。
internal-handoff.md：保留全部 6 项、变更 ID、发布状态与待确认内容。
user-release-notes.md：只写已确认面向目标读者开放的变化。
结构：版本及适用范围、新增、修复、需要用户操作的事项。
技术词改为可识别的用户操作；不添加未给出的性能、兼容或稳定性承诺。
未部署的功能不进入本版公告；试用功能按发布范围决定是否单列。
每条用户文案在内部事实表保留对应 ID，公告正文不强行展示研发编号。
只生成草稿，不发送、不发布。对这组材料，面向全部管理员的公告可以写成下面这样。若 C-05 没有在本次面向所有人的渠道中宣传，就不必为了凑篇幅添加。
# 预约管理后台 v1.8 更新
本次更新适用于预约管理后台的管理员。
## 新增
成员列表新增角色筛选，可按角色缩小查找范围。
## 修复
- 修复切换月份后，预约日历仍可能显示上个月数据的问题。
- 修复窄屏查看时，空列表提示与表格边界错位的问题。
## 需要操作吗
本次无需迁移已有预约数据。
（这一项只有发布负责人确认后才能保留；未确认时删除并补问。）最后一段刻意保留了写作时常见的待确认处：即使没有看到数据库变更，也不能直接得出“无需迁移”的结论。正式公告应删除括号内编辑提示，改为负责人已确认的事实；如果没有任何用户操作事项，可不设这一节。
发布前校对重点：漏写影响比少写亮点更严重
把公告与事实表逐条核对：是否把未开放功能写成已支持，是否遗漏操作习惯变化，是否把局部修复夸大为全面稳定，是否出现用户看不懂的内部简称。若某项更新需要重新登录、调整配置或迁移数据，应该放在显眼位置，而不是藏在一串新增功能之后。
| 问题 | 处理 |
|---|---|
| 一个修复涉及多个 PR | 合并成一条用户可理解的变化，内部保留所有关联 ID |
| 同一功能只向部分团队开放 | 写明确范围，或等全面开放后再发面向全部用户的公告 |
| AI 把重构写成速度提升 | 要求回到测量数据；没有证据就删除该结论 |
| 发布过程临时回滚一项 | 以实际开放状态重新核对公告，不沿用旧草稿 |
| 更新后需要补充说明 | 保留版本与变更记录，写清新增事实，不悄悄改成曾经就支持 |
当这套事实表和口径稳定之后，可以把整理方法做成可复用的 Skill。若还要定期收集候选变更，可参考定时任务的周期与去重方法；收集候选与正式发布说明仍应分开。
墨刀 AI 客户端适合把本地变更记录、需求说明与验收材料整理成两种文稿。你可以从客户端里的一次小版本开始：先让六条变更准确归类，再决定公告需要多长。
