TechSpecs搜尋

Theme / v0.5.0

CatDesk

把 ChatGPT Web 變成本地 Coding Agent

主題首頁GitHub ↗
基礎觀念

CatDesk 的 10 個本地工具詳解

逐一拆解 CatDesk 在 multi-tools 模式下提供的 10 個本地工具，解釋長時間任務 (start_command + poll_command) 的設計原理，以及 Token 用量估算機制。

CatDesk 的 10 個本地工具詳解

CatDesk 有兩種本地工具模式：

模式 工具數量 適用情境
multi-tools 10 個 完整編碼代理：讀、寫、搜尋、執行指令一應俱全
read-only 3 個 只允許讀取的低風險場景（詳見第三課）

本篇聚焦 multi-tools 模式的完整工具表。

10 個工具總覽

工具 類型 作用
catdesk_instruction Guide 回傳 CatDesk 使用說明，並渲染 Binagotchy
read Read 讀取工作區內一或多個文字檔
search Read 以 rg、grep 或內建搜尋器搜尋工作區內文字
write Write 建立或覆寫檔案
edit Write 以帶防護 (Guarded) 的取代/範圍編輯，原子性地 (Atomically) 套用修改
delete Write 刪除檔案或目錄
run_command Shell 執行短 shell 指令並等待完成
start_command Job 啟動長時間 shell 指令，立即回傳工作 ID (Job ID)
poll_command Job 讀取背景指令的增量輸出與狀態
cancel_command Job 停止背景指令及其子程序樹

各工具細節

catdesk_instruction：入口指南

回傳 CatDesk 的使用說明。上游建議的 Custom Instructions 寫法是「在 list_resources 之後永遠先呼叫 catdesk_instruction，並遵循其中的指示」，所以這支工具是 ChatGPT 每次連上後的第一站。附帶彩蛋：它會渲染 Binagotchy，一隻鯊魚貓吉祥物，每次啟動 CatDesk 都會隨機生成一隻。

read：批次讀檔

一次讀取一或多個文字檔。所有檔案工具都以工作區 (Workspace) 為基準路徑，工作區外的路徑會被拒絕。

search：三級後備搜尋

search 的後備鏈 (Fallback Chain) 是：

rg → grep → CatDesk 內建掃描器

有裝 ripgrep 就走 rg（效能最佳），沒有就退到 grep，連 grep 都沒有就用內建掃描器。安裝 ripgrep 是選配，但能換到最佳搜尋效能。

write / edit / delete：寫入三件套

  • write 負責建立或整檔覆寫。
  • edit 負責精修：以帶防護的取代 (Replace) 或範圍 (Range) 編輯，原子性套用，要麼整個改成功、要麼不改，不會改到一半留下損壞檔案。
  • delete 負責刪除檔案或整個目錄。這是最危險的寫入工具之一，權限請參考第三課。

run_command：短指令直跑

執行一條 shell 指令並等待完成，最長 120 秒逾時 (Timeout)。適合 git status、ls、快速單元測試這種很快結束的指令。超過 120 秒的任務不該用它。

長時間任務模式：start → poll → cancel

run_command 的 120 秒上限擋不住建置、編譯、依賴安裝、長測試套件與開發伺服器 (Dev Server)。這類任務走三支 Job 工具組成的模式：

start_command  →  回傳 Job ID，指令在背景執行
poll_command   →  用 cursor 讀取增量輸出與狀態
cancel_command →  殺掉背景指令與整個子程序樹

設計關鍵：長時間指令刻意與 MCP HTTP 請求的生命週期解耦 (Decoupled)。背景工作不會因為單次 HTTP 請求結束而中斷，這正是建置與 Dev Server 需要的行為。

poll_command 的使用規則：

  1. Poll 回應是有界的 (Bounded)，每次只回一部分。
  2. 若回應中 hasMoreOutput 為 true，就帶著 nextCursor 繼續 poll。
  3. 即使指令已達終態 (Terminal State)，只要還有 hasMoreOutput 就要持續 poll，把緩衝區剩餘輸出排乾 (Drain) 為止。

典型的正確用法：start_command 啟動 pnpm build → 反覆 poll_command 直到看見建置完成與 hasMoreOutput: false → 若中途發現卡住，用 cancel_command 收掉整棵子程序。

瀏覽器模式的額外工具

若啟用瀏覽器控制模式 (Browser Mode)，CatDesk 會額外暴露瀏覽器/DevTools 相關工具。這些工具由瀏覽器橋接 (Browser Bridge) 提供，確切的工具清單取決於你的環境。底層是 chrome-devtools-mcp 整合，讓 ChatGPT Web 能讀取頁面元素、控制你的瀏覽器分頁。

Token 用量估算機制

CatDesk 拿不到 ChatGPT Web 的官方 Token 用量數字，改以 o200k_base tokenizer（與 GPT-5.5 系列模型同家族）在本地估算：

欄位 符號 意義 對應價格
inputTokens ↓ 工具輸入 = LLM 的輸出 約 $30.00 / 1M 輸出 Token
outputTokens ↑ 工具輸出 = LLM 的輸入 約 $5.00 / 1M 輸入 Token
totalTokens Σ inputTokens + outputTokens 輸入價 + 輸出價

注意方向：工具的「輸入」其實是模型吐出來的內容，所以按輸出價算（較貴）；工具的「輸出」會餵回模型當輸入，按輸入價算（較便宜）。

沒有計入的部分：完整的 ChatGPT 對話內容、隱藏提示詞 (Hidden Prompts) 與推理 Token (Reasoning Tokens)、其他 OpenAI 內部 Token。

另外一個容易誤會的點：載入動畫只是視覺效果。ChatGPT Web 並不會把 MCP 工具的部分輸入/輸出串流 (Stream) 給 CatDesk；小工具 (Widget) 先在本地播放動畫，等真正的工具結果抵達後才鎖定為估算值。