返回列表
2026年10月15日 上午07:40

Pi Agent 1.0 Code Mode：用 JavaScript 编排工具调用

原始影片

學習筆記：Pi Agent 1.0 Code Mode 深度解析

TL;DR

Code Mode 透過讓模型生成 JavaScript 腳本並在沙箱中自動化執行工具鏈，解決了傳統模型反覆交互造成的上下文冗餘與規劃效率低下的問題，特別適用於需要多步驟重複執行、資料篩選與匯總的任務。

快速結論

Code Mode 的核心價值在於「從模型直接操作工具」轉向「模型定義流程，程式自動執行」。在傳統模式下，模型必須為每個步驟規劃並處理大量返回的原始數據，導致上下文被佔滿且效率低；Code Mode 將邏輯封裝在 QuickJS 沙箱內運行，模型僅需處理「腳本執行結果」的摘要，從而精簡了上下文並提高了複雜任務（如大規模文件檢查）的處理效率。

此機制並不保證所有任務都變快，其關鍵在於任務是否能被程式化穩定表達。實作時，QuickJS 沙箱通過 Bridge 工具代理與宿主進行資源交互，確保了隔離性。若任務包含可編程的重複步驟、需處理結構化數據，且具備容錯處理，則非常適合使用 Code Mode。

這支影片在說什麼

這支影片介紹了 Pi Agent 1.0 新增的「Code Mode」功能，探討該功能如何透過執行 JavaScript 腳本來優化 AI Agent 對工具的調用流程。適合希望提升 AI 自動化任務處理效率、理解 Agent 工具調用機制（如沙箱與宿主通訊）的開發者與進階用戶閱讀。

最重要的 3-5 個重點

  1. 交互範式轉移：從「模型逐次反覆調用」改為「模型生成腳本，程式一次執行」，大幅降低了模型在處理大量文件時的上下文負載。
  2. 沙箱執行環境：利用 QuickJS + WASM 沙箱進行腳本執行，該環境不具備 Node API 或直接訪問系統的權限，必須透過預先注入的 Bridge 工具代理來存取檔案或 Shell，確保安全性。
  3. 優化數據處理：在處理如 Monorepo 依賴檢查等任務時，中間層的篩選、JSON 解析與聚合都在沙箱內完成，模型最終僅接收精簡後的「結果」，而非原始的十七份文件內容。
  4. 容錯與限制：程式執行過程具備基本的錯誤處理（如處理不存在的文件），但要注意腳本一旦執行失敗，已完成的工具調用不會自動回滾，開發者需自行設計錯誤處理邏輯。

知識架構

  • 執行流程層次：
    • 模型層 (LLM)：負責規劃邏輯、生成執行腳本（JavaScript）。
    • 執行層 (QuickJS Sandbox)：執行 JavaScript 腳本，具備迴圈、條件判斷、並發處理能力。
    • 宿主層 (Host)：實際執行檔案讀取、Bash 指令、網路請求等工具，並透過 Bridge 將結果回傳至沙箱。

關鍵概念

  • Code Mode：Pi Agent 新增功能，允許模型寫程式碼來調用一組工具，而非一次只調用一個。
  • QuickJS 沙箱：一個輕量級的 JavaScript 執行引擎，與主機隔離，僅能透過特定的 Bridge 接口操作外部資源。
  • Bridge 工具代理：連接沙箱與宿主系統的橋樑，負責檢查權限並執行真實的操作。
  • ON vs ONLY 模式：ON 模式同時提供傳統工具與 Code Mode；ONLY 模式則僅開放 Code Mode，限制模型直接調用工具的行為。

重要例子與細節

  • 實戰案例：在找出某倉庫中依賴 pi-codemode 的套件時，普通模式需要 18 次交互（1 次 Bash + 17 次 Read），而 Code Mode 將這 18 次操作整合在 1 次腳本執行中。
  • 錯誤處理：在讀取多個文件時，若其中一個不存在，Code Mode 可透過處理 ENOENT 錯誤標誌，讓腳本持續完成剩餘工作，而非因單點錯誤中斷。
  • 副作用注意：Code Mode 不能省略必要的操作保護，且不具備事務回滾（Rollback）機制。

可學習的洞察

  • 任務評估三問：在決定是否使用 Code Mode 前，確認：
    1. 是否包含

可編程的重複步驟？ 2. 工具是否返回穩定的結構化數據？ 3. 外部副作用是否有獨立的權限審批或補償機制？

  • 複雜性封裝：當任務涉及大量的中間邏輯（如解析、篩選、排序）時，這類工作應交給腳本而非模型，模型應專注於結果輸出。

可行動的整理

  • 設定優化：可透過 .pi-settings.json 在項目級別設置 Default Tools，將 Code Mode 預設開啟。
  • 開發習慣：在編寫 Agent 任務時，將「檔案遍歷」、「資料篩選」等重複性高、邏輯固定的任務，轉移為編寫 Code Mode 腳本。
  • 權限設定：透過 SetActiveTools 隨時開關 Code Mode，避免在不適合的場景濫用，增加模型決策複雜度。

複習問題

  1. Code Mode 與傳統 AI 工具調用在交互流程上有何本質區別？
  2. 為什麼在 QuickJS 沙箱中無法直接使用 Node.js 的 fs 模組？
  3. 在 Code Mode 中，模型與腳本的角色分別是什麼？
  4. 當腳本執行失敗時，已執行的工具調用會發生什麼？
  5. 什麼樣的任務類型最適合使用 Code Mode，請舉例說明。

待確認資訊

  • [資訊不足] 關於 SetActiveTools 的詳細 API 定義與調用限制，需參考官方文件。
  • [資訊不足] 關於橋接器（Bridge）的具體安全邊界，在面對更複雜的 Shell 命令注入風險時的防護細節。

觀看原始影片