将选定代码变更转化为附带证据链的发布说明

撰写立论站得住脚的陈述，而非提交信息的摘要

要将选定代码变更转化为立论站得住脚的发布说明：亲自阅读 diff，按受影响对象分类变更，为每项变更撰写一条附带来源引用的朴素陈述，附上实际核对记录，并删除所有证据不支持的句子。您可以在对照 diff 时使用 Cue 听写解读，然后根据核对过的文本请求草稿。此纯文本练习不授权仓库访问、测试、打标签或发布权限。这属于任务边界，并不代表 Cue 或连接的 Agent 缺乏这些能力。

提交信息仅概括作者意图；经评审后可能并不完整或已过时。发布说明则将这些宣称转化为无法查看代码之人的预期。应将陈述对象对照 diff、测试与部署记录进行核实，切勿将单一来源视为最终用户体验的完整证明。

现有三条路径可用，彼此为替代选项而非递进步骤：

1. 直接听写至您正在使用的工具中。将光标聚焦于正在编写说明的可编辑字段、草稿便签或草稿文件中，使用 Cue Dictation 讲述解读。检查插入的文本并亲自提交。Cue 仅负责输入文字；接收方应用拥有该文档的所有权。
2. 在 Cue 内部选择外部 Agent。在带有 Agent 选择器的 Cue 版本中，Claude 和 Codex 会作为本地 Agent 选项出现。列表中能看到 Claude、Codex 或 Gemini 条目，并不等同于连接正常、已登录、模型可用或具备仓库访问权限。在向该 Agent 传递任何内容之前，请先确认其可访问范围。
3. 将 Cue Agent 与受支持的模型配合使用。在 Agent 列中选择 Cue，然后选择一个可用模型。这只会更改由哪个模型来起草文本，并不会授予终端权限、检出您的仓库或提供发布授权。

对于更长的变更集，Cue 的录音和转写控件可在打开 diff 时保留语音解读。请将转写内容视为未经核实的基础素材。校验步骤详见“从录音到上下文”工作流。

准备变更集、验证记录与发布目的地

该工作流假定由专人对发布文本负责。在开始之前，请备齐四样要素。下方的练习提供了全部四样内容，以便您无需代码仓库即可跟练。

• 确切的变更集。您打算描述的提交范围、标签或拉取请求，并附带提交标识符。“上周做的工作”不算变更集。如果您无法划定边界，就无法判断哪些变更属于发布说明范畴。
• diff 本身。发生变更的代码行，且包含足以解读上下文的周边代码。单独一行提交摘要不足以作为代码具体行为的证据。
• 实际验证记录。存在且通过了哪些测试、覆盖了哪些平台、遗漏了哪些内容，以及任何实际测得的指标。若未进行任何测量，此即为事实记录，应在说明中如实保持沉默而非提供估算。
• 发布目的地及其规则。发布说明将在何处展示、由谁审批，以及您的团队是否存在封锁期或安全披露流程。某些漏洞修复在补丁送达用户手中之前，严禁详细描述。

在 Cue 中，请使用您已安装版本的各项控件，确认 Dictation 的麦克风和输入权限，并先在临时便签中起草，以免未完成的句子直接变成已发布的说明。各平台的默认快捷键存在差异且可修改；您本地副本中的设置优先于指南中提及的任何按键。Dictation 教程涵盖了配置与文字插入核对步骤。

在此处，授权比在大多数撰写任务中更为关键。私有 diff 可能无法与外部 Agent 共享，而发布说明可能会让您的组织承担行为承诺。请仅共享最少量的摘录，遵守组织的数据处理规范，并在提供任何保密内容前审阅 Cue 的隐私政策。

练习：虚构笔记应用的 1.4.0 版本发布

以下全部内容皆为名为 Example Notes 应用的虚构练习材料。提交和测试记录专为本练习杜撰，代码仅为不完整的摘录。此处内容不代表 Cue 产品行为、录制的 Cue 实际运行或测量数据。无需仓库或 Agent 账号即可手动梳理各项来源。请将四份来源复制到空白便签中。在本练习中，假定使用者导入 src/index.mjs 重新导出的函数；不提供其他兼容性导出。

这四个来源代码块在所有语言版本中均保留英文，以确保代码、标识符及待核对陈述完全一致。解释与解题范例则单独翻译。请勿将此不完整的 diff 作为程序运行。

C-01 — 选定的变更集（五个提交，虚构）：

a1b2c3d  feat(export): include the note title in the exported file name
e4f5a6b  refactor(export): extract buildExportName from the export handler
9c0d1e2  fix(export): stop trimming the final page when a note ends with an empty block
7f8a9b0  chore(deps): update markdown-render 2.3.1 -> 2.4.0
3d4e5f6  feat(sync): add background sync retry behind the disabled syncRetry flag

C-02 — 上述提交对应的 diff（合并展示）：

--- a/src/export-name.mjs
+++ b/src/export-name.mjs
@@
-export function exportName(note) {
-  return `note-${note.id}.pdf`;
-}
+const MAX_TITLE = 40;
+
+export function buildExportName(note) {
+  const title = (note.title || '').trim().slice(0, MAX_TITLE);
+  const safe = title.replace(/[^\p{L}\p{N} _-]/gu, '').trim();
+  return safe ? `${safe}.pdf` : `note-${note.id}.pdf`;
+}

--- a/src/index.mjs
+++ b/src/index.mjs
@@
-export { exportName } from './export-name.mjs';
+export { buildExportName } from './export-name.mjs';

--- a/src/export-pages.mjs
+++ b/src/export-pages.mjs
@@
 export function exportPages(blocks) {
-  return paginate(blocks.filter(block => block.text.length > 0));
+  return paginate(blocks);
 }

--- a/package.json
+++ b/package.json
@@
-    "markdown-render": "2.3.1"
+    "markdown-render": "2.4.0"

--- a/src/sync.mjs
+++ b/src/sync.mjs
@@
 export function scheduleSync(config, queue) {
+  if (config.syncRetry) return scheduleWithRetry(queue, { attempts: 3 });
   return scheduleOnce(queue);
 }

C-03 — 本次发布实际已核对事项的记录：

Unit tests for export-name.mjs: 6 cases pass. Covered: usable title, empty title,
title of only punctuation, title over 40 characters, missing title property,
non-Latin title.
export-pages.mjs: no test covers this file, before or after the change.
Manual export: run on macOS only. Not run on Windows.
markdown-render 2.4.0: upstream release notes were not read. Reason for the bump
is recorded only as "routine update".
config/defaults.json: syncRetry is false. Not changed in this release.
Performance: no measurement was taken before or after these changes.
Crash reports: none were linked to any commit in this change set.

C-04 — 待验证的同事起草的发布陈述：

1. Exports are now named after your note.
2. Fixed a crash that caused the last page to disappear.
3. Export is about twice as fast.
4. Background sync retry is now available.
5. Internal refactor only, no API changes.
6. Updated markdown-render for security.

为提高可读性，上述 diff 合并在一个代码块中展示，但这并不能确定各代码行具体由哪个提交引入。解题范例中请引用 C-02 并附带文件路径；C-01 的提交摘要仅作为待核验断言。在实际任务中，请在将提交标识符绑定至某条陈述前，先查看该提交独立的 diff。

请先阅读 C-02，再看 C-04。这些陈述需要不同层面的订正：源码行为、测试覆盖与可用性属于完全不同的问题。被重命名的函数通过测试用例的公共入口点重新导出。移除 filter 调用会将所有区块传给 paginate，但其具体实现并不存在：最终 PDF 版式效果以及是否存在崩溃修复均未证实。默认关闭的标志位无法说明用户能否在其他地方启用它。此外，JavaScript 的 slice(0, 40) 计算的是 UTF-16 代码单元，并不等同于 40 个可见字符。

记录解读内容并请求生成受约束的草稿

1. 将 diff 和空白便签并排打开。切勿直接在发布工具的说明描述字段中起草。
2. 聚焦便签文本框，使用 Cue 设置中显示的快捷键启动 Dictation，并在说话前确认处于录音状态。若无法使用语音录制，可直接键入解读内容；本练习并不强制依赖音频。对于更长的录音，请先参考关联的“从录音到上下文”指南完成配置与审查检查。
3. 口头逐条解读变更。针对每一处，说明代码当前的实际行为、受影响对象以及您个人实际核对的内容。若未做核查，请明确说明“未核对”；直接保留该短语比事后重新推敲要容易得多。
4. 停止听写，等待处理完毕，并审阅已插入的文本。提交标识符、文件路径、版本号和标志名请直接从源文本复制粘贴，不要通过语音输入。语音适合传达解释，但输入诸如 9c0d1e2 等内容极不可靠。
5. 将参考来源汇总在笔记旁。如果您修改后的文本已足够清晰，可跳过 Agent 自行编辑。若需在结构和措辞上获得帮助，可打开 Cue Agent 或已连接的外部 Agent，并明确粘贴 C-01 至 C-04。打开的代码仓库窗口并不等于 Agent 接收到了上下文。
6. 发送起草请求。要求将发布说明、证据表和断言校验作为三个独立部分返回，以防无证据支持的句子被悄悄混入润色好的段落中。
7. 根据核验步骤，自行对照 C-02 和 C-03 检查草稿。随后将经批准的文本复制到发布工具中，确认正在编辑的版本与目标，并亲自发布。切勿要求任何 Agent 执行打标签、推送代码、部署或发布说明的操作。

复制发布说明提示词请求

将括号内的字段替换为您自己审查过的来源材料，或直接粘贴 C-01 至 C-04 进行练习。在真实任务中切勿保留占位符。

任务：仅根据提供的来源起草发布说明。不要发布任何内容。
发布版本：[版本与平台]
来源：
C-01 提交列表、C-02 diff、C-03 实际核对记录、
C-04 他人起草的陈述草案。

请输出三个独立的部分：

部分 A. 发布说明，分类如下：
- 您的体验变化
- 适用于引用本软件包的开发者（仅当公共接口变更时）
- 内部与依赖项变更
- 默认未启用或尚未验证可用性的功能
- 未经测量的项目
请用质朴明了的语言对每项变更撰写一条陈述。代码与接口陈述引用 C-02 及其文件路径；检查、测量和默认配置引用 C-03。合并的 diff 并未将代码行映射至具体提交；
切勿根据 C-01 的主题行推断此映射。凡来源中有体现之处，
均须如实说明条件与限制，包括回退逻辑、截断、默认值及未测试的文件。

部分 B. 证据表：陈述、适用的代码行或 C-03 条目，以及仍未验证的事项。请将源码支持的行为与经过测试的行为区分开来。测试缺失代表未经测试，
不自动等同于错误；摘录中未明确的结果必须保持“未验证”状态。

部分 C. 对 C-04 各陈述的校验：已证实、不完整、缺乏依据或存在矛盾，
附带原因，并在可行处给出证据允许的措辞。单独列出所有必须彻底删除的陈述。

规则：
仅使用提供的来源。切勿推断原因、崩溃情况、用户数量、速度变化、安全影响或客户投诉。
提交信息仅为宣称，不可作为证据。若其与 diff 冲突，以 diff 为准并标明冲突。
“默认关闭”不等于完全不可用。请说明记录在案的默认状态；切勿推断选择性开启路径、灰度状态或对所有用户的可用性。
切勿描述 C-03 中未记录的测试。
仅起草文本。切勿打标签、发布、推送、部署或编辑文件。

参考输出示例

以下三个代码块是为本练习编写的参考示例。它们并非录制的 Cue 实际运行记录，不是产品输出样本，也不构成对任何 Agent 实际返回结果的保证。请将您自己的结果与之对照。

参考发布说明：

Example Notes 1.4.0（虚构练习版本）

您的体验变化
- 导出的文件名将取自经去除首尾空格后的标题的前 40 个 UTF-16 代码单元，随后剔除不支持的字符。
  若处理后为空，名称将回退为 note-{id}.pdf。
  提供的测试记录列出六项通过的用例；未提供测试源码本身。
  (C-02: src/export-name.mjs; C-03)
- 所有区块现在都将传给 paginate，不再过滤文本为空的区块。
  最终 PDF 排版效果以及崩溃修复均未验证：未提供 paginate 实现，
  且 C-03 记录该文件无测试覆盖。
  (C-02: src/export-pages.mjs; C-03)

适用于引用本软件包的开发者
- 在包索引入口中，导出的函数名 exportName 现已变更为 buildExportName。
  根据本练习关于公共入口点的假设，直接导入 exportName 的代码需要更新。
  (C-02: src/index.mjs)

内部与依赖项变更
- markdown-render 从 2.3.1 升级至 2.4.0。由于未查看上游发布说明，
  其带来的具体影响及安全层面的意义尚未明确。
  (C-02: package.json; C-03)

默认未启用
- 存在重试分支逻辑，但在提供的默认配置中 syncRetry 仍为 false。
  未提供主动开启机制及部署状态说明。
  (C-02: src/sync.mjs; C-03)

未经测量的项目
- 本次发布未进行任何性能测量。(C-03)
- 本次变更集中的任何提交均未关联崩溃报告。(C-03)
- 导出功能仅在 macOS 上进行了手动验证。(C-03)

参考证据表（代码块 B）：

参考断言校验，针对 C-04 的核对表：

陈述 5 最值得深入审视。“内部”是对受众层面的判断，而非针对文件本身。单一模块内部的重命名属于内部变更；而在包索引入口处发生同样的重命名，对所有导入该模块的人而言都属于破坏性变更。

对照 diff 逐句核对陈述

请亲自进行此轮核对，一边放置草稿，另一边放置 C-02 和 C-03。切勿让撰写发布说明的同一个 Agent 来核验说明的准确性。

最后进行反向阅读。遮住 C-01 和 C-04，通读 diff 和 C-03，思考如果从零开始您会写出什么内容。所有保留下来的陈述均须有据可查；切勿臆测无支撑陈述的来源出处。若后续事实记录发生改变（例如有人为 export-pages.mjs 补全了测试），请同步更新陈述及其对应的证据。

本方法不适用的场景

• 本练习仅涉及文本且仅用于起草。请明确提供已审查的来源材料。在本练习中，切勿授权文件更改、测试、网络请求、打标签或发布操作。工具的实际可用性取决于安装版本、所选 Agent、连接状态和权限；本文不保证其实际具备。
• 庞大或经过 squash 合并的发布超出了单次处理的能力。该方法适合您可以从头到尾完整阅读的变更集。数百个提交需要先进行初筛，而打包了不相关变更的 squash 提交属于薄弱证据；此时应改为指向具体文件或区间，并明确说明这一情况。
• 私有代码可能受限而无法移出本地环境。未经授权，切勿将雇主或客户的 diff 粘贴至任何 Agent。若有疑虑，请直接在临时便签中起草并跳过 Agent 步骤。
• 安全修复有其专属处理流程。在补丁触达用户前描述漏洞可能引发安全风险。您所在组织的信息披露规范效力高于此处的任何措辞建议。
• 代码合入不等于功能已向用户开放。标志位、分阶段发布、服务端门控和应用商店审核都横亘在合并提交与终端用户之间。diff 本身无法告知您当前处于哪个阶段。
• 发布说明不等于质量认证。它们只负责描述变更，无法证明发布的版本绝对正确、安全或完备。
• 转换语言即等于重新审查。经过翻译的发布说明是一组全新的陈述。核验了英文版本并不代表翻译版本同样合格。

草稿或记录有误时的挽救方法

若遇到 Cue 录制或插入故障，请联系 Cue 支持团队，并附上您的系统平台、Cue 版本、运行模式及脱敏后的示例。切勿发送私有仓库、凭据或未公开的安全细节。

本练习引发的问题

练习该流程需要代码仓库吗？不需要。C-01 至 C-04 内容是完整的。本练习完全基于文本，可以安全粘贴到任何 Agent 中，因为其中不包含来自真实产品的真实代码。

Cue 能替我拉取 diff 吗？请勿做此假设。请核实您安装的版本及所选 Agent 的实际访问能力，在确认之前不要依赖它。在此工作流中，您将 diff 作为文本提供，这也促使您亲自通读代码。

发布说明中是否应该包含内部重构？通常会放在独立板块中，或根本不提。衡量标准不在于改动大小，而在于团队之外的任何人（包括引入您软件包的用户）能否观察到此变更。

撰写“无面向用户的变更”是否安全？只有在全面核对过公共接口、输出格式、错误提示信息、默认配置和依赖项之后才是安全的。练习中的陈述 5 恰恰违反了这一准则。

参考来源与相关工作流

本教程根据指南说明描述了 Cue 的 Dictation 与 Agent 边界。本文不宣称支持 Git、CI、软件包仓库或发布工具集成。您实际安装的控件和组织的发布流程效力优先于虚构练习。

• Cue Dictation 教程：输入焦点、录音状态与插入恢复。
• Cue Voice Agent 教程：显式上下文与受约束请求。
• 在编程 Agent 中使用 Cue：直接听写至工具、选择外部 Agent 与使用 Cue Agent 搭配模型的差异。
• 使用 Codex 审查代码变更：该工作流用于判断变更是否正确；本文则用于描述已被接受的变更。
• 使用 Claude Code 修复小缺陷：在变更写入发布说明之前，实现并测试受约束的修改。
• 通过语音编写每周状态更新：面向同事的进度报告，其受众不同且无需将每行内容对应至具体提交。
• 精确听写技术术语：保留标识符、版本和错误字符串。
• Cue 隐私政策：在提供任何非公开代码或记录前请先审阅。