將選定的程式碼變更轉化為具備佐證連結的版本資訊

撰寫站得住腳的陳述，而非 commit 訊息摘要

要將選定的程式碼變更轉化為站得住腳的版本資訊：請親自閱讀 diff、依受影響對象分類變更、為每項變更撰寫一條清楚明白且附有來源參照的陳述、附上實際驗證過的紀錄，並刪除缺乏佐證的每個句子。您可以在檢視 diff 時使用 Cue 口述說明，隨後根據審閱過的文字請求生成草稿。這項純文字練習不會授權存取儲存庫、執行測試、標記 tag 或執行發布。這是一項任務邊界，並非表示 Cue 或連線的 Agent 缺乏這些功能。

Commit 訊息僅概述作者的意圖；在程式碼審查後，它們可能已不完整或過時。版本資訊則是將這些主張轉化為無法直接看見程式碼的人所產生的預期。請對照 diff、測試與部署紀錄來查驗主體，而非將任何單一來源視為最終使用者體驗的完整證明。

有三種替代途徑可供選擇，它們是並列的選項而非先後步驟：

1. 口述至您現有的工具中。將游標聚焦在撰寫筆記的可編輯欄位（如暫存筆記或草稿檔案），使用 Cue Dictation 說出說明。檢查插入的文字並親自送出。Cue 僅負責輸入文字，接收的應用程式才擁有該文件。
2. 在 Cue 內選取外部 Agent。在具備 Agent 選取器的 Cue 版本中，Claude 與 Codex 會顯示為本機 Agent 選項。清單中列出項目（如 Claude、Codex 或 Gemini）並不等於連線正常、已登入、模型可用或擁有儲存庫存取權。在向該 Agent 傳遞任何內容之前，請務必先確認其可存取的範圍。
3. 搭配支援的模型使用 Cue Agent。在 Agent 欄位中選取 Cue，然後選取可用的模型。這只會變更是由哪個模型來起草文字，並不會賦予終端機權限、檢出（checkout）您的儲存庫或提供發布權限。

針對較長的變更集，Cue 的錄音與轉錄控制項可以在開啟 diff 時留存口述演練內容。請將該轉錄文字視為原始素材，而非經過驗證的紀錄。錄音轉上下文工作流程涵蓋了後續的核對步驟。

準備變更集、驗證紀錄與發布目的地

此工作流程預設由專人對發布文字負責。在開始之前，請備齊四項要素。下方的實作練習已提供這四項內容，讓您無需儲存庫即可跟著操作。

• 確切的變更集。您打算說明的 commit 範圍、tag 或 pull request，並包含 commit 識別碼。「上週的工作」並不是一個變更集。若無法指明邊界，就無法判斷哪些變更屬於這份版本資訊。
• Diff 本身。變更的程式碼行，以及足以解讀它們的周邊上下文程式碼。單純的 commit 主題行並不能作為程式碼實際運作方式的依據。
• 實際驗證的紀錄。存在並通過了哪些測試、在哪些平台上執行過、未涵蓋哪些部分，以及任何實際進行的測量數據。若未進行任何測量，這本身就是一項紀錄，在版本資訊中應當留白或不提，而非寫入預估值。
• 目的地及其規範。版本資訊要發布至何處、由誰核准，以及團隊是否有新聞禁令或安全性揭露程序。某些修正項目在修補程式送達使用者手中之前，絕不能進行詳細描述。

使用 Cue 時，請使用您安裝版本中的控制項，確認 Dictation 的麥克風與輸入權限，並從暫存筆記開始操作，避免未完成的句子直接變成已發布的版本資訊。預設快速鍵因平台而異且可更改；您軟體複本中的設定優先於指南中提及的任何按鍵。Dictation 教學涵蓋了設定與文字插入檢查步驟。

在此處，授權問題比多數寫作任務更為關鍵。私有 diff 可能不得與外部 Agent 分享，且版本資訊可能會讓您的組織承擔某種行為承諾。請僅分享最低限度的節錄內容，遵循組織的資料處理規範，並在提供任何機密內容前查閱 Cue 的隱私權政策。

練習：虛構筆記應用的 1.4.0 版本發布

以下所有內容皆為名為 Example Notes 的應用程式虛構練習材料。本練習中的 commit 與測試紀錄均為杜撰，程式碼亦為不完整的節錄。此處內容皆非 Cue 產品行為、非已記錄的 Cue 實際執行結果，亦非實測數據。您可以手動處理這些來源資料，無需儲存庫或 Agent 帳號。將四個來源複製到空白筆記中。在此練習中，假設取用端直接匯入由 src/index.mjs 重新匯出的函式；無提供其他相容性匯出。

四個來源區塊在所有語言版本中均保留為英文，以確保程式碼、識別碼與待查驗陳述保持完全一致。說明與解答範例則分開翻譯。請勿將這份不完整的 diff 作為程式執行。

C-01 — 選定的變更集（五個 commit，虛構）：

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 — 這些 commit 的 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 為了易讀性而合併顯示為單一區塊。它並未界定每一行是由哪個 commit 所引入。在解答範例中請引用 C-02 加上檔案路徑；C-01 的主旨僅能作為待查核的主張。在實際任務中，在將 commit 識別碼連結至陳述前，請務必先閱讀每個 commit 專屬的 diff。

請在閱讀 C-04 之前先閱讀 C-02。這些陳述需要不同的修正：原始碼行為、測試覆蓋率與可用性是各自獨立的問題。更名後的函式已從測試範例的公開進入點重新匯出。移除 filter 呼叫會將所有區塊傳遞給 paginate，但其具體實作並未提供：既無法確認最終 PDF 的版面配置，也無法證實修復了當機問題。預設關閉的 feature flag 並不能說明是否有人能在其他地方啟用它。此外，JavaScript 的 slice(0, 40) 計算的是 UTF-16 程式碼單元（code units），並不必然等於 40 個可見字元。

擷取口述演練並請求範圍受限的草稿

1. 將 diff 與空白暫存筆記並排開啟。切勿直接在發布工具的版本描述欄位中開始操作。
2. 將游標聚焦在筆記的文字欄位，使用 Cue 設定中顯示的快速鍵啟動 Dictation，並在開口說話前確認錄音狀態。若語音擷取無法使用，請改為手動輸入演練筆記；本練習不強制依賴音訊。若需進行較長的錄音，請先遵循相關錄音轉上下文指南中的設定與審查檢查步驟。
3. 大聲地逐一說明各項變更。針對每項變更，說出程式碼目前的運作方式、誰會察覺到差異，以及您個人實際檢查了什麼。若未進行檢查，請直接說出「未檢查（not checked）」；及時保留這句話，遠比事後重新推敲容易得多。
4. 停止聽寫，等待文字處理完成，並閱讀已插入的文字。請從來源直接複製並貼上 commit 識別碼、檔案路徑、版本號碼與 flag 名稱，不要透過語音口述。語音適合用於表達概念說明，但要辨識 9c0d1e2 這類字串則不可靠。
5. 將來源資料整理在筆記旁。如果您修正後的文字已經很明確，可跳過 Agent 自行編輯。若需協助架構與措辭，請開啟 Cue Agent 或已連線的外部 Agent，並明確貼上 C-01 至 C-04。開啟的儲存庫視窗並非 Agent 自動接收到的上下文。
6. 發送起草請求。要求將版本資訊、佐證表格與主張驗證分成三個獨立的區塊產出，這樣缺乏佐證的句子就無法被悄悄混入潤飾後的段落中。
7. 請親自運用驗證審查步驟，將草稿對照 C-02 與 C-03 進行核對。隨後將核准通過的文字複製到您的發布工具中，確認您正在編輯的版本與發布目標，並由您親自發布。切勿要求任何 Agent 去打 tag、push、部署或張貼版本資訊。

複製版本資訊生成請求

將中括號內的欄位替換為您自己審查過的來源資料，或貼上 C-01 至 C-04 進行練習。在實際任務中請勿留下任何預留位置符號。

任務：僅根據提供的來源資料起草版本資訊。請勿發布任何內容。
發布版本：[版本與平台]
來源資料：
C-01 commit 清單、C-02 diff、C-03 實際驗證紀錄、
C-04 他人撰寫的陳述草稿。

請產生三個獨立區塊。

區塊 A. 版本資訊，分組如下：
- 為您帶來的變更
- 適用於任何匯入此套件的人（僅在公開介面有變更時列出）
- 內部與依賴套件變更
- 預設未啟用或尚未確認可用的項目
- 未測量項目
以淺顯易懂的文字為每項變更撰寫一條陳述。程式碼與介面陳述請引用 C-02 及其檔案路徑；檢查、測量與預設設定請引用 C-03。合併後的 diff 並未將個別程式碼行對應至特定 commit；請勿從 C-01 的主旨推斷該對應關係。凡來源資料顯示有條件限制處，均須陳述其條件與極限，包括相容替代方案（fallback）、截斷處理、預設值及未測試的檔案。

區塊 B. 佐證表格：陳述、適用的程式碼行或 C-03 紀錄，以及仍未驗證的事項。請區分原始碼支援的行為與經過測試的行為。缺乏測試代表未經測試，不代表必然為假；未被節錄內容證實的結果必須保持為未驗證狀態。

區塊 C. 逐一驗證 C-04 的各項陳述：判定為有依據、不完整、無依據或相矛盾，並說明理由；在可能的情況下，提供證據所允許的措辭。單獨列出每一條必須完全刪除的陳述。

規則：
僅能使用提供的來源資料。切勿推論原因、當機、使用者人數、速度變化、安全性影響或客戶投訴。
Commit 訊息僅為主張，而非佐證。若與 diff 相衝突，請以 diff 為準並標註該衝突。
預設關閉並不能證明完全無法使用。請回報有文件記載的預設值；切勿擅自推論選擇加入途徑、逐步推出狀態或全體使用者的可用性。
切勿描述 C-03 中未記載的測試。
僅限起草。請勿打 tag、發布、發行、push、部署或編輯檔案。

範例輸出

以下三個區塊是為此練習撰寫的示意範例。它們並非已記錄的 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）

適用於任何匯入此套件的人
- 套件 index 中原本匯出的函式 exportName 現已更名為 buildExportName。基於本練習中公開進入點的假設，匯入 exportName 的程式碼需要更新。（C-02：src/index.mjs）

內部與依賴套件變更
- markdown-render 從 2.3.1 更新至 2.4.0。上游版本資訊未經審閱，因此其影響與安全性關聯並未獲得證實。（C-02：package.json；C-03）

預設未啟用
- 存在重試分支程式碼，但在提供的預設值中 syncRetry 仍為 false。未提供手動加入（opt-in）途徑與部署狀態。（C-02：src/sync.mjs；C-03）

未測量項目
- 本次發布未進行任何效能測量。（C-03）
- 沒有任何當機回報連結至此變更集中的任何 commit。（C-03）
- 匯出功能僅在 macOS 上進行手動驗證。（C-03）

佐證表格範例（區塊 B）：

主張驗證範例，C-04 檢核清單：

陳述 5 是最值得放慢腳步仔細檢視的一項。「內部（Internal）」是一項關於受眾的主張，而非針對檔案本身的主張。單一模組內部的更名屬於內部變更；但套件入口 index 處的相同更名，對所有匯入它的使用者而言都是破壞性變更（breaking change）。

依據 diff 逐一核對每項陳述

請親自執行這項核對，將草稿置於一側，C-02 與 C-03 置於另一側。切勿要求撰寫該筆記的同一個 Agent 來確認筆記內容是否準確。

最後進行反向研讀。遮住 C-01 與 C-04，閱讀 diff 與 C-03，問問自己在沒有參考的情況下會寫出什麼。任何留存的宣稱都必須具備來源依據；切勿推測無佐證陳述的來源。若紀錄後續發生變更（例如有人為 export-pages.mjs 補充了測試），請一併更新該陳述與其佐證。

此方法不適用的情況

• 本練習僅限純文字且僅供起草。請明確提供審閱過的來源資料。在此練習中，請勿授權修改檔案、執行測試、發出網路請求、標記 tag 或進行發布。實際工具可用性取決於安裝版本、所選 Agent、連線與權限；本文章不作任何保證。
• 龐大或經過 squash 合併的發布版本無法透過單次審查處理。此方法適用於您可以從頭到尾完整閱讀的變更集。數百個 commit 需要先進行分流分類，而打包了無關變更的 squash commit 則是薄弱的參照依據；遇到此情況時請改為指向特定檔案或範圍，並清楚說明。
• 私有程式碼可能不得離開您的內部環境。未經授權，切勿將雇主或客戶的 diff 貼入任何 Agent 中。若有疑慮，請直接從暫存筆記起草，略過 Agent 步驟。
• 安全性修復具備獨立的專屬處理程序。在修補程式送達使用者之前描述漏洞可能會引發資安風險。您組織的資訊揭露規範優先於此處的所有措辭建議。
• 程式碼已合併（shipped）不等於使用者已可使用（available）。Feature flag、階段性推出（staged rollouts）、伺服器端門控與應用程式商店審查，都介於已合併的 commit 與使用者之間。單憑 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 修復小型錯誤：在具體邊界內實作並測試變更，隨後才轉化為版本資訊條目。
• 透過語音撰寫每週狀態更新：為同事撰寫進度報告，其目標受眾不同，且無需將每行字句追溯至特定 commit。
• 精準口述技術詞彙：準確保留識別碼、版本號碼與錯誤字串。
• Cue 隱私權政策：在提供任何非公開程式碼或紀錄之前，請務必先仔細查閱。