快速開始：5 分鐘上手 Plannotator

學完你能做什麼

✅ 瞭解 Plannotator 的核心功能和使用情境
✅ 在 5 分鐘內完成 Plannotator 安裝
✅ 設定 Claude Code 或 OpenCode 整合
✅ 完成首次計畫審查和程式碼審查

你現在的困境

Plannotator 是一個為 Claude Code 和 OpenCode 設計的互動式審查工具，可以幫你解決以下問題：

痛點 1：AI 產生的實施計畫在終端機裡閱讀，文字量大、結構不清晰，審查起來很累。

痛點 2：想給 AI 回饋時，只能用文字描述「刪除第 3 段」、「修改這個函式」，溝通成本高。

痛點 3：程式碼審查時，需要開啟多個終端機或 IDE，來回切換，難以集中注意力。

痛點 4：團隊成員想參與審查，但不知道如何共享計畫內容。

Plannotator 能幫你：

視覺化 UI 取代終端機閱讀，結構清晰
選取文字即可新增註解（刪除、取代、評論），精確回饋
Git diff 視覺化審查，支援行級註解
URL 分享功能，無需後端即可團隊協作

什麼時候用這一招

使用情境：

使用 Claude Code 或 OpenCode 進行 AI 輔助開發
需要審查 AI 產生的實施計畫
需要審查程式碼變更
需要與團隊成員共享計畫或程式碼審查結果

不適用情境：

純手工撰寫程式碼（不涉及 AI 產生計畫）
已經有完整的程式碼審查流程（如 GitHub PR）
不需要視覺化審查工具

核心思路

Plannotator 是什麼

Plannotator 是一個為 AI Coding Agent（Claude Code、OpenCode）設計的互動式審查工具，主要提供兩大功能：

計畫審查：視覺化審查 AI 產生的實施計畫，支援新增註解、批准或拒絕
程式碼審查：視覺化審查 Git diff，支援行級註解和多種檢視模式

運作原理

┌─────────────────┐
│  AI Agent      │
│  (產生計畫)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Plannotator   │  ← 本機 HTTP 伺服器
│  (視覺化 UI)   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  瀏覽器        │
│  (使用者審查)  │
└─────────────────┘

核心流程：

AI Agent 完成計畫或程式碼變更
Plannotator 在本機啟動 HTTP 伺服器，開啟瀏覽器
使用者在瀏覽器中檢視計畫/程式碼，新增註解
使用者批准或拒絕，Plannotator 將決策回傳給 AI Agent
AI Agent 根據回饋繼續實施或修改

安全性

所有資料本機處理，不會上傳到雲端：

計畫內容、程式碼 diff、註解都儲存在你的本機電腦
本機 HTTP 伺服器使用隨機連接埠（或固定連接埠）
URL 分享功能透過壓縮資料到 URL hash 中實現，無需後端

🎒 開始前的準備

系統需求：

作業系統：macOS / Linux / Windows / WSL
執行環境：Bun（安裝腳本會自動處理）
AI 環境：Claude Code 2.1.7+ 或 OpenCode

安裝方式選擇：

如果使用 Claude Code：需要安裝 CLI + 外掛
如果使用 OpenCode：需要設定外掛
如果只做程式碼審查：只需安裝 CLI

跟我做

第 1 步：安裝 Plannotator CLI

macOS / Linux / WSL：

bash

curl -fsSL https://plannotator.ai/install.sh | bash

Windows PowerShell：

powershell

irm https://plannotator.ai/install.ps1 | iex

Windows CMD：

cmd

curl -fsSL https://plannotator.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

你應該看到：安裝腳本會自動下載 Plannotator CLI 並將其加入系統路徑中，並顯示版本號（如 "plannotator v0.6.7 installed to ..."）。

安裝腳本做了什麼？

安裝腳本會：

下載最新版本的 Plannotator CLI
加入系統路徑（PATH）
清理可能存在的舊版本
自動安裝 /plannotator-review 指令（用於程式碼審查）

第 2 步：設定 Claude Code（可選）

如果你使用 Claude Code，需要安裝外掛。

在 Claude Code 中執行：

/plugin marketplace add backnotprop/plannotator
/plugin install plannotator@plannotator

重要：安裝外掛後，必須重新啟動 Claude Code 才能讓 hook 生效。

你應該看到：外掛安裝成功後，Claude Code 的外掛清單中會出現 plannotator。

手動設定方式（可選）

如果你不想使用外掛系統，可以手動設定 hook。詳見 Claude Code 外掛安裝章節。

第 3 步：設定 OpenCode（可選）

如果你使用 OpenCode，需要編輯 opencode.json 檔案。

編輯 opencode.json：

json

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@plannotator/opencode@latest"]
}

重新啟動 OpenCode。

你應該看到：重新啟動後，OpenCode 會自動載入外掛，submit_plan 工具將可用。

第 4 步：首次計畫審查（Claude Code 範例）

觸發條件：讓 Claude Code 產生一個實施計畫，並呼叫 ExitPlanMode。

範例對話：

使用者：幫我寫一個使用者認證模組的實施計畫

Claude：好的，這是實施計畫：
1. 建立使用者模型
2. 實作註冊 API
3. 實作登入 API
...
（呼叫 ExitPlanMode）

你應該看到：

瀏覽器自動開啟 Plannotator UI
顯示 AI 產生的計畫內容
可以選取計畫文字，新增註解（刪除、取代、評論）
底部有「Approve」和「Request Changes」按鈕

操作：

瀏覽器檢視計畫
如果計畫沒問題，點擊 Approve → AI 繼續實施
如果需要修改，選取要改的文字，點擊 Delete、Replace 或 Comment → 點擊 Request Changes

你應該看到：點擊後，瀏覽器會自動關閉，Claude Code 會收到你的決策並繼續執行。

第 5 步：首次程式碼審查

在專案目錄中執行：

bash

/plannotator-review

你應該看到：

瀏覽器開啟程式碼審查頁面
顯示 Git diff（預設是未提交的變更）
左側是檔案樹，右側是 diff viewer
點擊行號可以選取程式碼範圍，新增註解

操作：

在 diff viewer 中瀏覽程式碼變更
點擊行號選擇要審查的程式碼
在右側面板新增註解（comment/suggestion/concern）
點擊 Send Feedback 傳送給 agent，或點擊 LGTM 批准

你應該看到：點擊 Send Feedback 後，瀏覽器會關閉，終端機中會輸出格式化的回饋內容，agent 會自動處理。

檢查點 ✅

完成以上步驟後，你應該能夠：

[ ] 安裝腳本顯示 "plannotator vX.X.X installed to ..."
[ ] 在 Claude Code 中觸發計畫審查，瀏覽器自動開啟 UI
[ ] 在 UI 中選取計畫文字，新增註解
[ ] 點擊 Approve 或 Request Changes，看到瀏覽器關閉
[ ] 執行 /plannotator-review，看到程式碼審查介面
[ ] 在程式碼審查中新增行級註解，點擊 Send Feedback

如果某一步失敗，詳見：

踩坑提醒

常見錯誤 1：安裝後執行 plannotator 提示「command not found」

原因：PATH 環境變數未更新，或需要重新啟動終端機。

解決：

macOS/Linux：執行 source ~/.zshrc 或 source ~/.bashrc，或重新啟動終端機
Windows：重新啟動 PowerShell 或 CMD

常見錯誤 2：Claude Code 安裝外掛後，計畫審查沒有觸發

原因：未重新啟動 Claude Code，hook 未生效。

解決：完全退出 Claude Code（不只是關閉視窗），然後重新開啟。

常見錯誤 3：瀏覽器沒有自動開啟

原因：可能是遠端模式（如 devcontainer、SSH），或者連接埠被佔用。

解決：

檢查是否設定了 PLANNOTATOR_REMOTE=1 環境變數
查看終端機輸出的 URL，手動在瀏覽器中開啟
詳見遠端/Devcontainer 模式

常見錯誤 4：程式碼審查顯示「No changes」

原因：目前沒有未提交的 git 變更。

解決：

先執行 git status 確認有變更
或執行 git add 暫存一些檔案
或切換到其他 diff 類型（如 last commit）

本課小結

Plannotator 是一個本機執行的審查工具，透過視覺化 UI 提升計畫審查和程式碼審查的效率：

核心功能：

計畫審查：視覺化審查 AI 產生的計畫，支援精確註解
程式碼審查：視覺化審查 Git diff，支援行級註解
URL 分享：無需後端即可分享審查內容
第三方整合：自動儲存批准的計畫到 Obsidian/Bear

核心優勢：

本機執行，資料安全
視覺化 UI，提升效率
精確回饋，減少溝通成本
團隊協作，無需帳號系統

下一課預告

下一課我們學習 Claude Code 外掛安裝。
你會學到：
詳細的 Claude Code 外掛安裝步驟
手動設定 hook 的方法
如何驗證安裝是否成功
常見安裝問題的解決方法

附錄：原始碼參考

點擊展開檢視原始碼位置

更新時間：2026-01-24

功能	檔案路徑	行號
CLI 入口（計畫審查）	`apps/hook/server/index.ts`	1-50
CLI 入口（程式碼審查）	`apps/hook/server/index.ts`	46-84
計畫審查伺服器	`packages/server/index.ts`	1-200
程式碼審查伺服器	`packages/server/review.ts`	1-150
Git 工具	`packages/server/git.ts`	1-100
計畫審查 UI	`packages/editor/App.tsx`	1-200
程式碼審查 UI	`packages/review-editor/App.tsx`	1-200

關鍵常數：

MAX_RETRIES = 5：連接埠重試次數（packages/server/index.ts:80）
RETRY_DELAY_MS = 500：連接埠重試延遲（packages/server/index.ts:80）

關鍵函式：

startPlannotatorServer()：啟動計畫審查伺服器（packages/server/index.ts）
startReviewServer()：啟動程式碼審查伺服器（packages/server/review.ts）
runGitDiff()：執行 git diff 指令（packages/server/git.ts）

環境變數：

PLANNOTATOR_REMOTE：遠端模式標誌（apps/hook/server/index.ts:17）
PLANNOTATOR_PORT：固定連接埠（apps/hook/server/index.ts:18）
PLANNOTATOR_BROWSER：自訂瀏覽器（apps/hook/README.md:79）
PLANNOTATOR_SHARE：URL 分享開關（apps/hook/server/index.ts:44）

5 分鐘快速上手

審查 AI 計畫和程式碼

多人協作+筆記存檔

遇到問題怎麼辦

查 API 和資料結構

看看新功能

快速開始：5 分鐘上手 Plannotator

學完你能做什麼

你現在的困境

什麼時候用這一招

核心思路

Plannotator 是什麼

運作原理

安全性

🎒 開始前的準備

跟我做

第 1 步：安裝 Plannotator CLI

第 2 步：設定 Claude Code（可選）

第 3 步：設定 OpenCode（可選）

第 4 步：首次計畫審查（Claude Code 範例）

第 5 步：首次程式碼審查

檢查點 ✅

踩坑提醒

本課小結

下一課預告

附錄：原始碼參考

快速開始：5 分鐘上手 Plannotator ​

學完你能做什麼 ​

你現在的困境 ​

什麼時候用這一招 ​

核心思路 ​

Plannotator 是什麼 ​

運作原理 ​

安全性 ​

🎒 開始前的準備 ​

跟我做 ​

第 1 步：安裝 Plannotator CLI ​

第 2 步：設定 Claude Code（可選） ​

第 3 步：設定 OpenCode（可選） ​

第 4 步：首次計畫審查（Claude Code 範例） ​

第 5 步：首次程式碼審查 ​

檢查點 ✅ ​

踩坑提醒 ​

本課小結 ​

下一課預告 ​

附錄：原始碼參考 ​

快速開始：5 分鐘上手 Plannotator

學完你能做什麼

你現在的困境

什麼時候用這一招

核心思路

Plannotator 是什麼

運作原理

安全性

🎒 開始前的準備

跟我做

第 1 步：安裝 Plannotator CLI

第 2 步：設定 Claude Code（可選）

第 3 步：設定 OpenCode（可選）

第 4 步：首次計畫審查（Claude Code 範例）

第 5 步：首次程式碼審查

檢查點 ✅

踩坑提醒

本課小結

下一課預告

附錄：原始碼參考