【2026 最新】Pi 1.0 Codemode 怎麼用？同一任務比較工具載入與成本

你想讓 Pi 幫忙修一個小程式，卻看到「Codemode」「延後載入工具」和一串 token 數字：開啟新工具真的會讓工作更省、更順嗎？光看功能介紹，答案很容易變成猜測。這篇 Pi 1.0 Codemode 教學帶你用同一個可回復的 coding 任務，自己記下工具載入、完成品質與成本。

本文寫給第一次使用終端機 Coding Agent、願意照著少量指令操作的讀者。你會學會啟用 Pi 內建 Codemode、辨認 MCP 工具的載入方式、建立兩份乾淨的執行紀錄，最後用一張待填成績單判斷是否值得保留設定。範例欄位是測量方法，不是 AlphaLab 已跑出的效能結果。

先說結論：Pi 1.0 Codemode 值不值得用，要看三張收據

工具載入效益 ＝ 同一任務的成果品質＋實際工具路徑＋完整 session 用量。 Codemode 像替 Agent 加上一張「工作桌」：模型寫一小段 JavaScript，把讀檔、搜尋或 MCP 工具呼叫串起來，整理過的結果才送回模型。工具描述是否少佔上下文，還取決於哪些工具被設定為直接顯示、由 Codemode 取用或延後搜尋；它不是單靠一個開關就能保證省錢。Pi 的官方 Codemode 文件和MCP 曝光方式說明把這兩層分開定義。

• 成果收據：測試是否通過、修改了哪些檔案、人工補救花多久。
• 路徑收據：模型實際用了哪些工具、何時搜尋工具、是否真的呼叫 Codemode。
• 用量收據：輸入、輸出、cache read、cache write、總成本與失敗重跑。

Pi 1.0 Codemode 是什麼？先拆開三種工具入口

把 Agent 想成一位修理師。直接顯示的工具像桌上攤開的每一把工具，模型一開始就看到名稱與用法；Codemode像工作桌，模型先寫出短腳本，再透過 tools.<name>()調用工具與整理輸出；延後載入像工具櫃，先用 tool_search找對工具，找到的工具才在下一次模型呼叫中宣告。Pi 的 MCP 文件把 direct、codemode、deferred、hidden列為不同曝光模式；hidden代表該工具在這項設定下不可達。

容易混淆的是「Codemode」與「deferred」並非同一件事。Codemode 決定模型能否用腳本編排工具；deferred 決定工具何時被模型看見。MCP 伺服器的預設曝光在現行官方 MCP 文件標為 codemode。若你想測「延後載入」本身，應另設一組 deferred 條件，而不是把 Codemode 組的差異直接說成延後載入的效果。

開始前：固定任務、模型與測試環境

先依Pi 官方 Quickstart安裝並在終端機執行 pi --version。官方目前提供 macOS／Linux 安裝腳本，也提供需要 Node.js 22.19 以上的 npm 路徑 npm install -g --ignore-scripts @earendil-works/pi-coding-agent。首次進入 Pi 後用 /login接上你已有權限的模型供應商，再用 /model選同一個模型。先把版本、供應商、精確模型 ID 和思考等級寫進紀錄；不同模型或方案的費用不可直接互比。

在一個隔離的練習資料夾準備小型 Git repo：一個有明確錯誤的函式、一個會先失敗的測試、固定的測試指令。範例題目可以是「修正折扣計算的邊界條件，讓既有測試通過；只改 src/discount.js，跑 npm test，最後報告修改與測試結果」。先自行執行一次測試，保存失敗輸出與初始 commit。這份題目、檔案和測試必須在兩組完全相同；真正的品質判準是測試、diff 和人工檢查，而不是模型最後一句「完成」。

Pi 的安全文件說明：它會以啟動者的系統權限讀寫與執行，且不會逐次要求工具批准。練習時把 repo 複製到隔離環境，移走真實憑證、正式環境設定與不相關資料。工作目錄方便找檔，不是檔案存取邊界；需要強邊界時，依官方隔離環境指南把整個 Pi 程序放進容器或虛擬環境。

Pi 1.0 Codemode 怎麼用？先跑一組基準，再跑一組 Codemode

① 基準組：列出一般工具

在第一份相同初始 commit 的 repo 裡，啟用一般檔案工具。Pi 的 --tools 會取代預設清單，所以要列出任務需要的每個工具；下例的 MODEL_ID請換成 pi --list-models顯示、你已取得使用權的精確 ID，任務提示詞則貼上剛才固定的完整題目：

pi --model MODEL_ID --tools read,bash,edit,write,grep,find,ls --mode json --session-id pi-baseline "任務提示詞" > baseline.jsonl

官方 CLI 文件確認 --model、--tools、--mode json與 --session-id的用途。執行後保存 JSONL、git diff、測試輸出及是否需要人工修正；把包含路徑、程式碼或憑證的 session 當成私有紀錄。

② Codemode 組：只改工具路徑

把第二份 repo 還原到同一初始 commit，保留相同模型、思考等級、提示詞、測試指令與環境，只在工具清單加上 codemode：

pi --model MODEL_ID --tools read,bash,edit,write,grep,find,ls,codemode --mode json --session-id pi-codemode "任務提示詞" > codemode.jsonl

關鍵驗收：打開 JSONL，找這次模型是否真的呼叫 codemode、呼叫幾次，以及輸出是否只帶回任務需要的摘要。工具可用不等於模型一定選它；若這次沒用到 Codemode，標記「未採用」，不能把用量差異歸因給它。讓每組從新 session、相同初始 repo 重跑數輪，把成功、失敗和人工補救都留下，避免一次偶然輸出被誤認為穩定改善。

③ 要測延後載入？把 MCP 曝光另開一組

若你本來就有一個已連線、適合此任務的 MCP 伺服器，先用 pi mcp list確認工具與曝光模式。接著只改該伺服器或單一工具的 exposure／toolExposure，比較 direct與 deferred；後者由 tool_search找到後才宣告給下一次模型呼叫。官方範例示範在 MCP 設定中混用 search_code: direct、get_*: codemode、delete_*: hidden。這是第三個獨立實驗：伺服器、工具版本與權限要固定，別與上面的「有無 Codemode」結果混算。

只為測量工具載入而臨時接入陌生 MCP 伺服器，會把新伺服器的連線、資料範圍與故障混進結果。先在自己可控制的測試環境完成基準／Codemode 兩組；已經有 MCP 工作流的人，再加 direct／deferred 對照即可。

怎麼記錄成本？把「省 token」拆成可核對欄位

每一輪填同一列：Pi 版本、模型 ID、條件、初始 commit、任務提示詞雜湊、成功／失敗、測試結果、工具呼叫數、Codemode 是否使用、tool_search 是否使用、輸入 token、輸出 token、cache read、cache write、總成本、人工補救時間。 Pi 的session 格式文件說明訊息與額外 usage entry 都會計入 session token／成本；RPC 的 get_session_stats會回傳 toolCalls、各類 token 與 cost。若採 JSON 模式，請依官方事件格式擷取完成後的用量，不要把串流中的暫時數字當最終總計。

比較時先看兩組是否都通過同一測試。若一組少花 token 卻修錯檔案或多花人工時間，這不是有用的節省。再看 cache read／write：重跑、供應商快取狀態與提示長度會改變帳面費用。最後才比較每次成功完成的總成本與耗時，並保留失敗輪次；請勿只挑漂亮的一輪。這些欄位是一張待填量表，本文沒有填入 Pi 1.0 的實測數字。

兩個常見失敗：輸出被截斷，或工具權限超出任務

輸出太長：摘要要保留可追溯的錯誤

Codemode 的重點是讓腳本先處理大量工具輸出，模型只接收必要結果。例如先搜尋相關檔案，再回傳「檔名、行號、符合片段」，而非整份測試 log。但若摘要吞掉失敗訊息，Agent 會失去診斷依據。Codemode 文件說明腳本可看到 truncated與 full_output_path等欄位；遇到截斷，先記下原始路徑、退出碼與錯誤尾段，再決定要不要擴大讀取。回傳「測試失敗，詳見檔案」還不夠：下一步需要知道哪一條測試、哪個檔案、什麼錯誤。

權限太寬：先停手，從乾淨副本重來

若 JSONL 顯示工具要讀任務外資料、執行超出測試範圍的命令，或 Git diff 出現題目外修改，先停止該輪、保存 trace 與 diff、撤銷練習環境中的臨時憑證，再從初始 commit 的乾淨副本重跑。--tools只決定 Pi 對模型宣告哪些工具；bash與擴充套件的實際系統權限仍要靠作業系統或容器限制。這也是為什麼練習應只用假資料與可丟棄的 repo。

常見問題：Pi 1.0 Codemode 與延後載入的八個判斷

1. 打開 Codemode 就一定省 token 嗎？

不一定。它能讓腳本整理工具輸出；模型是否使用、腳本回傳多少、是否引入額外呼叫，都要從 trace 和完整 session 用量核對。

2. Codemode 等於延後載入嗎？

兩個不同設定。Codemode 是編排工具的腳本入口；deferred 是工具經搜尋後才宣告給模型的曝光模式。

3. 只看工具呼叫次數能判斷成本嗎？

不能單看。一次呼叫可能回傳大量文字，還可能觸發模型再次讀入。把 token、cache、成功率及人工補救一起記。

4. 為什麼兩組都要用新 session？

避免把前一輪的對話和工具宣告帶進下一輪。同一初始 commit 和相同提示詞，才方便比較執行路徑。

5. 模型沒有呼叫 Codemode，該怎麼記？

標為「未採用」。此輪仍是可用的工作流觀察，但不能當 Codemode 編排效果的證據。

6. 只有一個 MCP 伺服器，也要測 deferred 嗎？

看任務。若它的工具集很小且常用，先確認直接顯示的基準；若工具多而任務只碰少數幾個，再做 direct／deferred 對照較有意義。

7. Codemode 腳本會直接看到本機檔案嗎？

它透過可用工具接觸外部環境。Pi 文件描述的 QuickJS 腳本環境本身沒有 Node、檔案系統或網路 API；但腳本可呼叫被提供的工具，所以實際風險仍取決於工具與執行環境。

8. 成績單只填一次，可以下結論嗎？

先把它當試跑。保留數輪成功與失敗紀錄，再看結果方向是否一致；模型輸出具有波動，一次低成本不代表日常工作都會較低。

給新手的決定規則：先讓工作完成，再決定保留哪種入口

如果一般工具已能穩定完成小任務，而 Codemode 多次實際被使用、保留相同品質並減少你要閱讀的長輸出，就值得把它帶到下一個可回復任務；若 Codemode 輪次常漏錯誤或需要更多人工修補，先縮小腳本任務與回傳格式。若你的主要痛點是 MCP 工具清單太大，再單獨比較 direct 與 deferred。回到開頭的公式：成果品質、真實工具路徑、完整用量三張收據要一起看。