backnotprop/plannotator 開源審查神器教學:在瀏覽器畫重點批改 Claude Code 與 Codex 計畫

backnotprop/plannotator 讓開發者在 AI 動手改碼前先在瀏覽器或 TUI 視覺化審查計畫與 Diff,直接劃線批註並回傳代理,徹底告別盲目放行風險。

Share
plannotator官方 GitHub 專案封面圖:plannotator 教學
plannotator官方開源專案視覺圖。 圖片來源:官方原文。

用 AI 程式代理寫程式時,最令人頭痛的不是它寫不出來,而是它在終端機吐出一長串修改計畫後,直接問你要不要放行。在黑底白字的小視窗裡閱讀幾百行計畫與 Diff,往往讓人眼睛發花。

很多工程師最後乾脆盲目按下確認,結果代理改錯方向,還得花更多時間收拾殘局。這篇 plannotator 教學要介紹的開源審查工具,正是為了補上「人類與代理之間最後一道審查介面」而設計。

先講我的判斷:如果你每天都在用 Claude Code、Codex 或 Gemini CLI 進行多檔案重構,這套工具幾乎是必裝神器。但如果你只習慣單行自動補全、很少使用代理的計畫模式,那它對你的幫助就相對有限。

這套工具透過掛鉤與外掛直接接入現有代理。每當代理提出改碼計畫、產生 HTML 原型或完成階段性修改時,本機就會自動彈出清晰的瀏覽器畫面,讓你像批改文件一樣直接劃線留言,再一鍵把回饋送回給代理。

接下來我會帶你認識它的核心設計、五分鐘一鍵安裝流程、三大實戰審查模式,以及團隊分享與隱私安全上的注意事項。

什麼是 Plannotator?補上人類與 AI 代理之間的審查層

簡單來說,它是一套運行在本機端、以瀏覽器或終端機介面為核心的視覺化審查層。它本身不負責推論寫程式,而是專門攔截各大程式代理產生的計畫與程式碼變更,把枯燥的終端機文字轉成好讀的互動介面。

目前官方支援的代理生態相當廣泛,涵蓋 Claude Code、Codex、Copilot CLI、Gemini CLI、OpenCode、Kiro、Droid、Amp、DeepSeek Harness 與 Pi。透過標準化的 MCP 協定,它也能串接個人助理與跨裝置控制面板。

在日常開發中,工程師最常遇到的卡關就是代理提出的實作計畫太長,終端機捲軸一滑就錯過關鍵細節。當這套審查層啟動時,代理進入規劃模式產出的 Markdown 方案會透過掛鉤自動在瀏覽器展開。

你可以像閱讀技術規格書一樣,直接在指定段落反白畫重點、補充架構限制,然後一次送回給代理修正。這種交互方式比在命令列打字補充說明精準得多,也大幅減少代理誤解需求的次數。

除了審查計畫,它在程式碼變更比對上也下了很大功夫。無論是本地尚未提交的修改、GitHub 拉取請求或是 GitLab 合併請求,都能用檔案樹搭配並排 Diff 檢視,並完整支援 Git、GitButler、Jujutsu 與 Perforce 等版本控制系統。

當一次重構牽涉到幾十個檔案時,逐檔點開往往讓人失去耐心。此時只要按下 Cmd+Shift+G 或 Ctrl+Shift+G 啟動 Guided Review 導覽模式,代理就會先把龐大的 Diff 整理成核心改動、連帶影響與膠水程式碼等章節,讓你把專注力留在最重要的邏輯上。

對於同時開好幾個終端機視窗平行開發的人,新加入的 Inbox 收件匣更是救星。所有代理在背景遇到的問題、產生的原型畫面與審查請求,都會集中送到同一個非阻塞視窗裡,你隨時有空再點選回覆,完全不會卡死其他代理的進度。

延伸閱讀:Code Mode 是什麼?Claude Code 實驗功能的啟用步驟與限制

plannotator官方 GitHub 專案封面圖:plannotator 教學
plannotator官方開源專案視覺圖。 圖片來源:官方原文。
Plannotator 官方操作示範影片,非本站實測。 來源:官方 YouTube。

plannotator 教學:一鍵安裝與各家代理串接步驟

官方提供了一支跨平台自動安裝腳本,會從發布頁面下載二進位執行檔,並自動偵測你電腦裡已經安裝的 AI 代理,順便把對應的技能、斜線指令與掛鉤一併寫入設定。

步驟一:執行官方安裝腳本

請依據你的作業系統,在終端機或 PowerShell 貼上以下指令。如果不想讓安裝程式自動修改任何代理設定,只想單純取得主程式放到 ~/.local/bin,可以加上 --minimal 旗標。

# macOS / Linux / WSL 完整安裝
curl -fsSL https://plannotator.ai/install.sh | bash

# 僅安裝執行檔,不更動任何代理設定
curl -fsSL https://plannotator.ai/install.sh | bash -s -- --minimal

Windows 使用者則可開啟 PowerShell 執行官方提供的對應腳本,完成後重新整理終端機路徑即可使用。

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

步驟二:完成不同代理的最後啟用設定

執行完腳本後,部分代理如 Gemini CLI、Kiro CLI 與 Codex 已經自動配置完成,不需要額外動作。不過在 Codex 環境中,因為它依賴實驗性的停止掛鉤來攔截計畫,所以呼叫做程式碼審查時,指令要改寫成驚嘆號開頭或呼叫專屬技能。

如果你使用的是 Claude Code、OpenCode 或 Pi,還需要補上各自的外掛註冊步驟。在 Claude Code 中,請依序執行外掛市集指令並重啟會話,才能讓瀏覽器視窗順利接管規劃模式。

# 在 Claude Code 內依序輸入以下指令後重啟
/plugin marketplace add backnotprop/plannotator
/plugin install plannotator@plannotator

值得一提的是,從 Claude Code 2.1.287 版起,審查介面預設改成非阻塞模式,代理丟出計畫後就會先結束該回合,等你批改送出後再以新訊息接續。如果你比較習慣代理在原地停住等候核准,只要在環境變數設定 PLANNOTATOR_CLAUDE_MOD=0 就能切回經典模式。

至於使用 Pi 代理的開發者,官方建議直接略過全局安裝腳本,改用 pi install npm:@plannotator/pi-extension 安裝擴充,啟動時加上 --plan 參數即可。

OpenCode 使用者則只需在設定檔 opencode.json 的外掛陣列補上 "@plannotator/opencode@latest" 並重新啟動工作階段。

若你同時也是 T3 Code 的使用者,只要執行 plannotator t3 --help 並完成兩個步驟的登入與 MCP 設定,你在收件匣送出的批註就能直接寫回該執行緒,跨裝置接力審查完全不斷線。

習慣在 Herdr 終端機環境工作的開發者,也能透過 herdr plugin install plannotator/herdr-annotate 安裝整合外掛。裝好後就能直接在終端機裡批改整個 Markdown 資料夾與各家代理的回覆,且所有標註都會共用本機資料目錄,累積下來的審查紀錄不會分散。

實戰工作流:計畫攔截、Diff 導覽與即時網頁批註

裝好環境後,這套審查工具最實用的情境可以從三個日常動作切入。最無感也最省心的是「計畫模式攔截」,只要代理在終端機準備開始規劃架構,瀏覽器就會自動跳出排版乾淨的文件視窗。

你可以用滑鼠反白任何一句不滿意的技術選型,在旁邊打上「這裡不要引入新套件,改用現有工具函式」,全部標記完再按下送出,代理就會立刻收到精準的修改指示並重寫方案。

第二個高頻動作是「局部與遠端程式碼審查」。當代理寫完一批程式碼卻還沒提交時,在終端機輸入 /plannotator-review 就能在瀏覽器開啟完整 Diff 進行行內評論,直接針對某幾行建議改寫寫法。

除此之外,你也可以把 GitHub 拉取請求網址或 GitLab 合併請求網址直接當成參數傳進去,甚至搭配 --gitbutler 旗標審查單一虛擬堆疊,或是用 --patch-file 讀取靜態的補丁檔來做離線檢視。

第三個工作流則非常受到前端工程師歡迎,叫做「即時網頁與 HTML 批註」。當代理幫你建好一個本地開發伺服器,例如運行在 5173 埠的 Vite 網頁時,只要執行以下指令就能透過本機代理直接對真實畫面批註。

# 直接在運行中的本機開發網頁上圈選元素並留評論,熱重載仍會正常運作
plannotator annotate http://localhost:5173

這個模式的厲害之處在於它不是抓一張死板的螢幕截圖,而是透過本機反向代理直接載入真實網頁,所以元件互動與熱重載都會正常運作。你點選畫面上歪掉的按鈕並寫下修正建議,代理就能立刻精準定位到對應元件。

如果代理產出的是一份靜態 HTML 報告而不是 Markdown 文件,加上 --render-html 旗標就能直接以渲染後的網頁樣貌進行批註。審查過程中若對某段邏輯有疑問,也能隨時呼叫內建的 AI 輔助檢視,讓它先幫你抓出潛在的邊界漏洞。

如果你想在純終端機環境下作業,不想離開 SSH 連線或鍵盤操作,也可以安裝獨立的文字介面版本,或是搭配 Herdr 整合使用。下表整理了日常最常用的指令速查,方便你在開發時隨時對照。

指令或環境變數 功能說明 適用場景
/plannotator-annotate README.md 在瀏覽器開啟並批註指定文件或資料夾 審查架構規格書、產品需求文件
/plannotator-last 把代理上一則回覆轉成可劃線批註的文件 代理長篇解釋難以在終端機閱讀時
plannotator inbox 開啟集中管理多代理提問的收件匣 同時平行開啟多個代理視窗開發時
plannotator sessions 列出目前進行中的審查會話並可重新開啟 不小心關掉瀏覽器分頁想找回畫面
plannotator archive 以唯讀模式瀏覽過去儲存的計畫決策紀錄 回顧先前為何採用某個技術架構
brew install plannotator/tap/plannotator-tui 安裝獨立運作的終端機文字審查介面 遠端 SSH 開發或無圖形介面環境

安全邊界、連結分享風險與乾淨移除方式

這套審查工具的運作核心都在本機端,但安裝與分享功能涉及對外網路連線,團隊在導入主力開發環境前務必先看清楚它的安全邊界。

首先在安裝階段,完整腳本除了從 GitHub Releases 下載主程式外,還會視情況連線至 npm 取得外掛與執行環境,以及下載可選的 sem 輔助元件。如果企業內網有嚴格的網路稽核或代理限制,建議改用 --minimal 參數只裝單一執行檔,避免腳本自動對外拉取其他套件。

第二個要注意的是「計畫連結分享」機制。這套工具允許你把審閱中的計畫產生連結傳給同事批註,小份量的資料會直接編碼在網址裡,但較大的計畫會在前端加密後上傳暫存,並在 7 天後自動過期。

官方明確指出,任何拿到完整連結的人都能解密閱讀內容。如果你的公司嚴禁任何程式碼計畫離開內網,請務必在系統環境變數中設定 PLANNOTATOR_SHARE=disabled,徹底關閉分享按鈕,防止工程師手誤把內部架構傳到外部暫存空間。

第三個實務細節是日後想移除時的乾淨程度。官方設計了相當謹慎的解除安裝機制,預設執行 plannotator uninstall 只會清除主程式與已註冊的代理掛鉤,並刻意保留你本機的歷史審查紀錄與草稿。

若確定要連同所有本機紀錄徹底清空,則需加上 --purge 旗標並手動輸入確認字詞。如果過程中遇到某個代理的設定檔損毀或權限不足,移除程式會主動停下來提示你手動處理,不會留下半套壞掉的設定導致原本的程式代理無法啟動。

延伸閱讀:Apple 宣布 macOS 27.3 拆分裝置控制與資料存取權限:AI 代理時代的 Mac 資安新防線

常見問題

這套工具本身會消耗我的 AI 模型額度嗎?

單純開啟瀏覽器查看計畫、手動劃線批註與審查 Diff 完全在本機運行,不會消耗額外額度。只有當你主動點擊內建的 AI 審查或章節導覽功能時,才會透過你原本設定的代理呼叫模型。

如果我都在遠端 Linux 主機開發,沒有瀏覽器怎麼辦?

你可以透過 brew install plannotator/tap/plannotator-tui 安裝純終端機文字介面版,直接在終端機裡移動游標批註 Markdown 與代理回覆,所有標記資料都會與主程式互通。

安裝後會不會影響我原本代理的快捷鍵或既有外掛?

安裝程式只會為支援的代理新增專屬的技能與計畫攔截掛鉤,不會覆蓋你原有的個人提示詞或工具權限設定。若在 Claude Code 想回到傳統的阻塞等候模式,設定 PLANNOTATOR_CLAUDE_MOD=0 即可。

如果要徹底關閉團隊連結分享功能該怎麼設定?

只要在你的 Shell 設定檔例如 .zshrc 或 .bashrc 加入 export PLANNOTATOR_SHARE=disabled 並重新載入,系統就會禁用所有加密上傳與分享連結功能。

結語

走完這份 plannotator 教學,你會發現它解決了一個被多數人忽略、卻每天都在發生的效率瓶頸:AI 產生程式碼的速度已經遠超人類在終端機裡閱讀文字的速度。透過把計畫與 Diff 搬進視覺化批註介面,工程師終於能把心力放在架構把關,而不是跟雜亂的終端機捲軸搏鬥。

  • 適合誰:重度使用 Claude Code、Codex、Gemini CLI 或 OpenCode 進行多檔案修改的工程師、習慣先看計畫書再放行的技術主管,以及需要針對本地開發網頁進行視覺回饋的前端開發者。
  • 不適合誰:只使用 IDE 內建行內補全的開發者、從不檢視代理計畫書就全自動放行的使用者,以及處於完全斷網且禁止本機啟用 HTTP 埠的極端封閉環境。
  • 為什麼:因為它的價值建立在人機協作的審查迴圈之上;只要你重視程式碼品質與修改前的方向校準,把文字互動升級成視覺化批註就能立刻省下大量來回修正的溝通時間。

如果你想持續追蹤更多提升開發效率的開源 AI 工具實測與工作流教學,歡迎免費訂閱 AI 郵報,每週精選第一手技術乾貨直送你的信箱。

資料來源

Read more