MCP 工具對照表

CatDesk 有兩種本地工具模式：multi-tools（多工具）預設暴露 10 個工具（開啟 Library handoff 後 11 個），read-only（唯讀）預設 3 個（開啟 handoff 後 4 個）。本文是完整對照表，以及長時任務 (long-running job) 的正確使用模式。

multi-tools 模式：10 個工具（開啟 handoff 後 11 個）

工具	類型	行為
`catdesk_instruction`	Guide	回傳 CatDesk 使用說明，並渲染 Binagotchy
`read`	Read	讀取 workspace 中一或多個文字檔（v0.4.3 起單次最多 32 檔）
`search`	Read	用 `rg`、`grep` 或內建搜尋器搜尋 workspace 內文字
`write`	Write	建立或覆寫檔案
`edit`	Write	以原子方式 (atomic) 套用帶防護的 replace/range 編輯
`delete`	Write	刪除檔案或目錄
`run_command`	Shell	執行短 shell 指令並等待完成
`start_command`	Job	啟動長時 shell 指令，立即回傳 job ID
`poll_command`	Job	讀取背景指令的增量輸出與狀態（v0.4.3 起預設 10 秒 long polling）
`cancel_command`	Job	停止背景指令及其整個子程序樹
`create_handoff`	Session	把工作脈絡打包透過 ChatGPT Library 帶到下一個 session（v0.7.0 新增；v0.9.2 起 opt-in，預設關閉）

read-only 模式：3 個工具

唯讀模式預設只開放 3 個工具（開啟 Library handoff 後為 4 個）。上游 README 未逐一列名，一般理解為 Guide / Read 類工具（catdesk_instruction、read、search），實際清單以 TUI 顯示為準：

catdesk_instruction
read
search

適合想讓 ChatGPT 只看程式碼、不動檔案的場景。

長時任務模式：start → poll → drain

長時指令刻意與 MCP HTTP 請求的生命週期解耦 (decouple)。建置、編譯、相依套件安裝、長測試套件、開發伺服器，都應該走這條路：

start_command：啟動指令，立即拿到 job ID 與初始 cursor
poll_command：帶著 cursor 輪詢，取得增量輸出與狀態

關鍵細節：poll 回應的輸出量有上限 (bounded)。若回應中 hasMoreOutput 為 true，即使指令已到達終態 (terminal state)，也要繼續用 nextCursor 輪詢，把緩衝區裡剩下的輸出排乾 (drain)，否則會漏掉結尾日誌。

run_command 的 120 秒上限

run_command 是短指令的簡單路徑，等待完成後直接回傳結果。最長 120 秒逾時 (timeout)，超時即失敗。任何可能跑超過 2 分鐘的指令，改用 start_command + poll_command。

create_handoff：跨 session 交接（v0.7.0）

ChatGPT 的 session 有長度限制，長任務勢必要拆。create_handoff 讓交接有正式管道，而不需要在 workspace 裡留交接筆記檔。

帶走什麼

一次 handoff 包含：

目前目標——這個 session 在做什麼
已完成的工作——做到哪裡了
決策——為什麼這樣做（下一步的 agent 需要理由，不只是結果）
驗證——哪些已驗證可用、怎麼驗證的
下一步——接手後應該做什麼
Git context——分支、狀態等版本控制脈絡

三個設計重點

不寫檔進 workspace：交接資料存放在 ChatGPT Library，你的專案目錄保持乾淨——不需要 .handoff.md 之類的約定檔案，也不會被 git 追蹤到。
精確恢復：新 session 依 workspace 精確比對找到對應的 handoff；多個 handoff 並存時明確處理，不會拿錯。
讀後清理：handoff 成功讀取後才清理——讀取失敗時資料還在，不會交接不成又丟了脈絡。

v0.9.2 起：opt-in，預設關閉

create_handoff 現在預設不會出現，由 TUI Settings 的持久化設定控制是否暴露，同時也控制 workspace 指示中的 ChatGPT Library 連續性指引。要使用時：

在 TUI Settings 開啟 Library handoff（前提是你的 ChatGPT 環境有 Library Search）
開新對話並在 ChatGPT 設定中重新整理 CatDesk，讓工具清單生效——multi-tools 變成 11 個工具、read-only 變成 4 個

使用模式

[session A 尾聲]
使用者：把目前進度做個 handoff，下個 session 接著做
→ agent 呼叫 create_handoff（目標/已完成/決策/驗證/下一步/Git context）

[session B 開始]
新 session 對同一個 workspace → 自動比對到待讀 handoff
→ 讀取成功後清理，接手工作

適合搭配長時任務模式使用：背景 job 交給 poll_command 追蹤，session 間的脈絡交給 create_handoff。

瀏覽器模式的額外工具

若啟用瀏覽器模式 (browser mode)，CatDesk 會額外暴露瀏覽器 / DevTools 工具。這些工具由 chrome-devtools-mcp 橋接 (bridge) 提供，實際清單取決於你的環境，不是固定集合。

search 的後備鏈

search 工具依以下順序挑選搜尋後端：

rg（ripgrep）— 有裝就用，效能最好
grep — 沒有 ripgrep 時退回
內建掃描器 (built-in scanner) — 最後手段

安裝 ripgrep 是可選的，但對大型 workspace 的搜尋速度幫助明顯。安裝方式見安裝與啟動 CatDesk。