新增計畫註解：掌握四種註解類型

學完你能做什麼

✅ 選取計畫文字，新增四種不同類型的註解（刪除、取代、插入、評論）
✅ 使用 type-to-comment 快捷鍵直接輸入評論
✅ 在註解中附加圖片（參考圖、截圖等）
✅ 理解每種註解類型的含義和使用情境
✅ 檢視註解匯出後的 Markdown 格式

你現在的困境

問題 1：知道要刪除某段內容，但選取文字後不知道點擊哪個按鈕。

問題 2：想取代一段程式碼，但工具列裡只有「刪除」和「評論」，沒有「取代」選項。

問題 3：選取多行文字想直接輸入評論，每次都要先點擊「Comment」按鈕，效率低。

問題 4：想給某段程式碼附加參考圖，但不知道怎麼上傳圖片。

Plannotator 能幫你：

清晰的按鈕圖示，一眼看出刪除、取代、插入、評論的區別
type-to-comment 快捷鍵，直接輸入無需點擊按鈕
註解中支援圖片附件，方便新增參考圖
註解自動轉換為結構化 Markdown，AI 準確理解

什麼時候用這一招

使用情境：

審查 AI 產生的實施計畫，需要精確回饋修改意見
某段內容不需要（刪除）
某段內容需要改成另一種寫法（取代）
某段內容後面需要補充說明（插入）
對某段內容有疑問或建議（評論）

不適用情境：

只是整體批准或拒絕計畫（無需註解，直接決策即可）
已經在審查程式碼變更（使用程式碼審查功能）

🎒 開始前的準備

前置條件：

✅ 已完成計畫審查基礎教學
✅ 瞭解如何觸發 Plannotator 計畫審查介面

本課假設：

你已經開啟了 Plannotator 計畫審查頁面
頁面中顯示了一個 AI 產生的 Markdown 計畫

核心思路

註解類型詳解

Plannotator 支援四種計畫註解類型（外加一種全域評論）：

註解類型	圖示	用途	是否需要輸入內容
刪除 (DELETION)	🗑️	標記此內容應從計畫中移除	❌ 不需要
評論 (COMMENT)	💬	對選取內容提出問題或建議	✅ 需要輸入評論
取代 (REPLACEMENT)	透過評論實現	用新內容取代選取內容	✅ 需要輸入新內容
插入 (INSERTION)	透過評論實現	在選取內容後插入新內容	✅ 需要輸入新內容
全域評論 (GLOBAL_COMMENT)	頁面底部輸入框	對整個計畫提出回饋	✅ 需要輸入評論

為什麼取代和插入沒有獨立按鈕？

因為從原始碼實現來看，取代和插入本質上是特殊的評論類型（packages/ui/utils/parser.ts:287-296）：

取代：評論內容作為取代的新文字
插入：評論內容作為插入的新文字

它們都使用 評論 (COMMENT) 按鈕建立，區別在於你如何描述意圖。

工具列工作流程

選取文字 → 工具列彈出（選單步驟）
                 │
                 ├── 點擊 Delete → 立即建立刪除註解
                 ├── 點擊 Comment → 進入輸入步驟 → 輸入內容 → 儲存
                 └── 直接輸入字元 → type-to-comment → 自動進入輸入步驟

兩個步驟的區別：

選單步驟：選擇操作類型（刪除、評論、取消）
輸入步驟：輸入評論內容或附加圖片（從評論/取代/進入）

type-to-comment 快捷鍵

這是提升效率的關鍵功能。當你選取一段文字後，直接開始打字（不需要點擊任何按鈕），工具列會自動：

切換到「評論」模式
將你輸入的第一個字元放入輸入框
游標自動定位到輸入框末尾

原始碼實現位置：packages/ui/components/AnnotationToolbar.tsx:127-147

跟我做

第 1 步：啟動計畫審查

為什麼 需要一個實際的計畫來練習新增註解。

操作

在 Claude Code 或 OpenCode 中觸發計畫審查：

bash

# Claude Code 範例：讓 AI 產生計畫後，它會呼叫 ExitPlanMode
"請產生一個使用者認證功能的實施計畫"

# 等待 AI 完成計畫，Plannotator 會自動在瀏覽器中開啟

你應該看到：

瀏覽器開啟計畫審查頁面
頁面顯示一個 Markdown 格式的實施計畫

第 2 步：新增刪除註解

為什麼 刪除註解用於標記不希望出現在最終計畫中的內容。

操作

在計畫中找到你不需要的段落（例如某個不相關的功能描述）
滑鼠選取文字
工具列自動彈出，點擊 刪除按鈕（🗑️）

你應該看到：

被選取的文字顯示為刪除樣式（通常是刪除線或紅色背景）
工具列自動關閉

刪除註解的特點

刪除註解不需要輸入任何內容。點擊刪除按鈕後，註解立即建立完成。

第 3 步：使用 type-to-comment 新增評論

為什麼 評論是最常用的註解類型，type-to-comment 能讓你少點一次按鈕。

操作

在計畫中選取文字（例如某個函式名稱或描述）
不要點擊任何按鈕，直接開始打字
輸入你的評論內容（例如：「這個函式名稱不夠清晰」）
按 Enter 鍵儲存，或點擊 Save 按鈕

你應該看到：

工具列自動切換到輸入框模式
你輸入的第一個字元已經在輸入框中
游標自動定位到輸入框末尾
按 Enter 後，選取的文字顯示為評論樣式（通常是黃色背景）

type-to-comment 的快捷鍵

Enter：儲存註解（如果輸入框有內容）
Shift + Enter：換行（輸入多行評論時使用）
Escape：取消輸入，返回選單步驟

第 4 步：新增取代註解

為什麼 取代註解用於用新內容取代選取內容，AI 會根據你的註解修改計畫。

操作

在計畫中選取文字（例如「使用 JWT token 進行認證」）
使用 type-to-comment 或點擊評論按鈕
在輸入框中輸入新的內容（例如：「使用 session cookie 進行認證」）
按 Enter 儲存

你應該看到：

選取的文字顯示為評論樣式
註解側邊欄中顯示你的評論內容

匯出後的格式（packages/ui/utils/parser.ts:292-296）：

markdown

## 1. Change this

**From:**

使用 JWT token 進行認證


**To:**

使用 session cookie 進行認證

取代與刪除的區別

刪除：直接移除內容，不需要說明理由
取代：用新內容取代舊內容，需要指定新內容

第 5 步：新增插入註解

為什麼 插入註解用於在選取內容後補充說明或程式碼片段。

操作

在計畫中選取文字（例如函式簽章的末尾）
使用 type-to-comment 或點擊評論按鈕
在輸入框中輸入要插入的內容（例如：「，需要處理認證失敗的情況」）
按 Enter 儲存

你應該看到：

選取的文字顯示為評論樣式
註解側邊欄中顯示你的評論

匯出後的格式（packages/ui/utils/parser.ts:287-290）：

markdown

## 1. Add this

，需要處理認證失敗的情況

第 6 步：在註解中附加圖片

為什麼 有時候文字描述不夠直觀，需要附加參考圖或截圖。

操作

選取任意文字，進入輸入步驟（點擊評論按鈕或 type-to-comment）
在工具列輸入框旁邊，點擊 附件按鈕（📎）
選擇要上傳的圖片（支援 PNG、JPEG、WebP 格式）
可以繼續輸入評論內容
按 Enter 儲存

你應該看到：

圖片縮圖顯示在輸入框中
儲存後，圖片顯示在註解側邊欄中

圖片儲存位置

上傳的圖片儲存在本機 /tmp/plannotator 目錄（原始碼位置：packages/server/index.ts:163）。如果清理暫存檔案，圖片會遺失。

第 7 步：新增全域評論

為什麼 當你對整個計畫有回饋（不是針對具體某段文字）時，使用全域評論。

操作

在頁面底部找到輸入框（標籤可能是「Add a general comment about the plan...」）
輸入你的評論內容
按 Enter 儲存或點擊傳送按鈕

你應該看到：

評論出現在頁面底部的全域評論區域
評論顯示為獨立卡片，不關聯任何文字區塊

全域評論 vs 文字評論

全域評論：對整個計畫的回饋，不關聯具體文字（例如「整個計畫缺少效能考量」）
文字評論：對某段文字的回饋，會醒目提示對應的文字

檢查點 ✅

完成上述步驟後，你應該：

[ ] 成功新增了至少一個刪除註解
[ ] 使用 type-to-comment 新增了評論
[ ] 新增了取代和插入註解
[ ] 在註解中附加了圖片
[ ] 新增了全域評論
[ ] 在右側側邊欄看到所有註解清單

踩坑提醒

坑 1：找不到「取代」按鈕

錯誤操作：

選取文字後，工具列只有 Delete 和 Comment，沒有 Replace 或 Insert 按鈕

正確做法：

取代和插入透過 評論 (COMMENT) 按鈕實現
在評論內容中描述你的意圖（取代或插入）
AI 會根據評論內容理解你的意圖

坑 2：type-to-comment 失效

可能原因：

沒有選取文字
先點擊了某個按鈕，工具列已進入輸入步驟
輸入了特殊鍵（Ctrl、Alt、Escape 等）

正確做法：

先選取文字，確保工具列顯示在選單步驟（有 Delete、Comment 按鈕）
直接輸入普通字元（字母、數字、標點）
不要按功能鍵

坑 3：圖片上傳後找不到

可能原因：

圖片儲存在 /tmp/plannotator 目錄
系統清理了暫存檔案

正確做法：

如果需要長期保存圖片，建議複製到專案目錄
匯出註解時，圖片路徑是絕對路徑，確保其他工具可以存取

坑 4：按 `Enter` 換行卻儲存了註解

錯誤操作：

在輸入框中想換行，直接按 Enter，結果註解被儲存

正確做法：

使用 Shift + Enter 換行
Enter 鍵專用於儲存註解

本課小結

四種註解類型：

刪除 (DELETION)：標記不希望出現在計畫中的內容
取代 (REPLACEMENT)：用新內容取代選取內容（透過評論實現）
插入 (INSERTION)：在選取內容後補充內容（透過評論實現）
評論 (COMMENT)：對選取內容提出問題或建議
全域評論 (GLOBAL_COMMENT)：對整個計畫的回饋

關鍵操作：

選取 → 工具列彈出 → 選擇操作類型
type-to-comment：直接輸入字元，自動進入評論模式
Shift + Enter：換行；Enter：儲存
附件按鈕：上傳圖片到註解

註解匯出格式：

刪除：## Remove this + 原文字
插入：## Add this + 新文字
取代：## Change this + From/To 對比
評論：## Feedback on: "..." + 評論內容

下一課預告

下一課我們學習 新增圖像標註。
你會學到：
如何在計畫審查中附加圖像
使用畫筆、箭頭、圓形工具進行標註
標註圖像作為參考回饋

附錄：原始碼參考

點擊展開檢視原始碼位置

更新時間：2026-01-24

功能	檔案路徑	行號
註解類型列舉定義	`packages/ui/types.ts`	1-7
Annotation 介面	`packages/ui/types.ts`	11-33
註解工具列元件	`packages/ui/components/AnnotationToolbar.tsx`	29-272
---	---	---
註解匯出格式化	`packages/ui/utils/parser.ts`	246-323
Markdown 解析為 Blocks	`packages/ui/utils/parser.ts`	70-244
Viewer 元件（文字選取處理）	`packages/ui/components/Viewer.tsx`	66-350

關鍵常數：

AnnotationType.DELETION = 'DELETION'：刪除註解類型
AnnotationType.INSERTION = 'INSERTION'：插入註解類型
AnnotationType.REPLACEMENT = 'REPLACEMENT'：取代註解類型
AnnotationType.COMMENT = 'COMMENT'：評論註解類型
AnnotationType.GLOBAL_COMMENT = 'GLOBAL_COMMENT'：全域評論類型

關鍵函式：

exportDiff(blocks, annotations)：將註解匯出為 Markdown 格式，包含 From/To 對比
parseMarkdownToBlocks(markdown)：將 Markdown 解析為線性 Block 陣列
createAnnotationFromSource()：從文字選取建立 Annotation 物件

5 分鐘快速上手

審查 AI 計畫和程式碼

多人協作+筆記存檔

遇到問題怎麼辦

查 API 和資料結構

看看新功能

新增計畫註解：掌握四種註解類型

學完你能做什麼

你現在的困境

什麼時候用這一招

🎒 開始前的準備

核心思路

註解類型詳解

工具列工作流程

type-to-comment 快捷鍵

跟我做

第 1 步：啟動計畫審查

第 2 步：新增刪除註解

第 3 步：使用 type-to-comment 新增評論

第 4 步：新增取代註解

第 5 步：新增插入註解

第 6 步：在註解中附加圖片

第 7 步：新增全域評論

檢查點 ✅

踩坑提醒

坑 1：找不到「取代」按鈕

坑 2：type-to-comment 失效

坑 3：圖片上傳後找不到

坑 4：按 `Enter` 換行卻儲存了註解

本課小結

下一課預告

附錄：原始碼參考

新增計畫註解：掌握四種註解類型 ​

學完你能做什麼 ​

你現在的困境 ​

什麼時候用這一招 ​

🎒 開始前的準備 ​

核心思路 ​

註解類型詳解 ​

工具列工作流程 ​

type-to-comment 快捷鍵 ​

跟我做 ​

第 1 步：啟動計畫審查 ​

第 2 步：新增刪除註解 ​

第 3 步：使用 type-to-comment 新增評論 ​

第 4 步：新增取代註解 ​

第 5 步：新增插入註解 ​

第 6 步：在註解中附加圖片 ​

第 7 步：新增全域評論 ​

檢查點 ✅ ​

踩坑提醒 ​

坑 1：找不到「取代」按鈕 ​

坑 2：type-to-comment 失效 ​

坑 3：圖片上傳後找不到 ​

坑 4：按 Enter 換行卻儲存了註解 ​

本課小結 ​

下一課預告 ​

附錄：原始碼參考 ​

新增計畫註解：掌握四種註解類型

學完你能做什麼

你現在的困境

什麼時候用這一招

🎒 開始前的準備

核心思路

註解類型詳解

工具列工作流程

type-to-comment 快捷鍵

跟我做

第 1 步：啟動計畫審查

第 2 步：新增刪除註解

第 3 步：使用 type-to-comment 新增評論

第 4 步：新增取代註解

第 5 步：新增插入註解

第 6 步：在註解中附加圖片

第 7 步：新增全域評論

檢查點 ✅

踩坑提醒

坑 1：找不到「取代」按鈕

坑 2：type-to-comment 失效

坑 3：圖片上傳後找不到

坑 4：按 `Enter` 換行卻儲存了註解

本課小結

下一課預告

附錄：原始碼參考