代理框架

Perch 在桌面版與 CLI 上執行完整的代理框架：shell、搜尋、檔案編輯、背景工作、封閉沙箱、規劃模式，以及依風險分級的權限。本頁說明完整工具組，以及管理這些工具的控制機制。

在文件工作與稽核的底層，Perch 是通用的代理框架。它會執行命令、搜尋與編輯檔案、建立輔助代理，並在沙箱中執行程式碼。核對帳本的同一套機制也能重構模組，因為兩者用的就是同一套機制。

本頁可供你查閱 Perch 在電腦上實際能做什麼，以及哪些控制機制決定它能在事先不詢問你的情況下執行多少工作。

僅限桌面版與 CLI

這裡的一切都需要本機存取權。Perch AI Web 是輕量的介面，沒有檔案系統、shell 或沙箱。各介面的差異請見工作區。

Shell 與搜尋

工具	功能
`bash`	在工作區中執行 shell 命令。
`grep`	搜尋整個資料夾中的檔案內容。
`glob`	依模式尋找檔案。

搜尋會實際執行 grep 與 glob，而不是依語意猜測，因此尋找每個呼叫位置，就是找出每個呼叫位置。

讀取與寫入檔案

工具	功能
`readLocalFile`	將檔案讀入上下文。
`writeLocalFile`	寫入檔案。
`editLocalFile`	就地編輯檔案的一部分。
`moveLocalFile`、`copyLocalFile`	移動或複製。
`createDirectory`、`deleteLocalFile`	建立目錄、移除檔案。
`statPath`	檢視路徑而不讀取內容。

每次呼叫都會依工作區已核准的根目錄驗證，因此 Perch 無法存取你開啟的資料夾之外的內容。

背景工作

長時間工作不必阻擋對話。Perch 可以在背景啟動命令，並繼續工作。

工具	功能
`run_in_background`	將命令啟動為獨立背景工作。
`check_background_task`	檢查工作狀態。
`list_background_tasks`	列出執行中的工作。
`wait_for_background_task`	等待直到工作完成。
`kill_background_task`	停止工作。

因此 Perch 能監督測試套件、建置或長時間安裝，而不必一直等待其中的工作。

沙箱

對於需要實際運算，而不是推理數字的工作，Perch 會撰寫程式碼，並以 run_sandbox_code 在封閉沙箱中執行。這讓總額來自計算，而不是猜測。

沙箱刻意採取了安全強化措施：

停用網路。 沙箱沒有對外存取權。
macOS seatbelt。 執行作業受 sandbox-exec 設定檔約束，與電腦的其餘部分隔離。
記錄產出來源。 沙箱執行會留下記錄，因此計算出的數字可以追溯到產生它的程式碼。

規劃與任務追蹤

Perch 有完整的規劃功能，而不只是「逐步思考」的指示：

規劃模式讓 Perch 檢視工作區並擬定計畫，在你核准前，會封鎖會改動內容的工具。你會收到計畫卡片，在你閱讀時不會寫入任何內容。
待辦事項讓 Perch 在長時間執行中維持可見的任務清單，讓你觀看進度，而不是猜測。
提問。 當 Perch 確實因應由你決定的事項而受阻時，它會詢問，而不是替你選擇。

聊天模式

輸入區有三種模式，會改變當輪允許執行的工作：

模式	行為
Ask	對話。詢問資料夾、上傳內容，或接下來該做什麼。
Plan	Perch 會檢視、擬定計畫，並在行動前等待核准。
Agents	Perch 會規劃並執行任務。

權限模式

權限設定與聊天模式分開，決定多少工作可以在未經核准的情況下執行。它依風險分級，而不是單一的開關：

模式	不必詢問即可執行的內容
Default	不執行有風險的事。寫入、命令、傳送、刪除及其他不可逆動作都需要核准。
Auto Review	可逆的低、中風險工作會自行執行。超出此範圍、可能造成重大影響的每個動作，會由另一個審查者檢查，只有不確定時才會詢問你。
Take the Wheel	完全自主。Perch 可以在不詢問的情況下寫入、刪除、傳送，以及採取不可逆的現實世界行動。
Plan	唯讀。會改動內容的工具，在計畫核准前仍會被封鎖。

Auto Review 可以不需你介入地執行，也不會盲目行動：可逆編輯與專案本身的命令會繼續執行，可能造成重大影響的動作會在執行前審查，風險最高的動作（強制推送、大量刪除）則一律停下來等你決定。它區分的是可逆與不可逆，而不是簡單與困難，因此能復原的檔案編輯，與寄出電子郵件的處理方式不同。審查者如何決定，請見權限模式。

推理投入程度

推理投入程度控制項決定模型在當輪投入多少心力。它是一條分成五段的控制列：四個投入程度，再加上一個獨立的 Flock 檔位。

設定	意義
Off	不進行思考。速度最快，用量消耗最少。
Low	淺層推理。適合重視速度、範圍明確的短任務。
Medium	平衡。工具呼叫較少，整合程度更高。
High	預設。複雜推理與代理工作。
Flock	不是投入程度。會規劃工作者團隊並平行執行，最適合大型、可拆分的工作。

有意思的是底層。供應商表達推理的方式完全不同：有些模型完全忽略推理參數，有些接受單一開關，有些則提供自己具名的等級階梯。模型清單中的每個模型都會宣告自己屬於哪一種，而你選擇的投入程度會依當輪實際選定的模型轉換。

因此，無論 Roost 將你路由到哪個模型，或你手動指定哪個模型，同一個控制項的行為都一致。這條控制列絕不會要求模型做到它無法做到的事。

Pro 上的 Claude Opus 5.5 有自己的等級階梯：投入程度為 low、medium、high、xhigh 與 max，思考一律啟用，因此沒有 Off。

Pro 上的 Gemini 4 Argon 接受 Low、Medium 與 High。它一律會思考，因此 Off 會以 Low 執行。

子代理

Perch 可以在當輪建立輔助代理，你可以選擇它們使用的模型。預設為 Inherit，會跟隨執行主要工作的模型。指定不同模型，能讓一個模型檢查另一個模型的工作，而不是評分自己的工作。

這項設定也涵蓋背景委派代理。指定模型的成本比維持自動路由更高。

完整說明請見子代理；四種多代理模式的差異請見操作代理與代理。

技能

Perch 附帶一組操作代理技能，只在相關時載入：工作區導覽、GitHub 與 git、文件、試算表、簡報、PDF、圖表、研究、資料品質與瀏覽器操作。每項技能都是特定工作的一組指示與偏好工具；中繼資料掃描成本低，完整指示則只在符合時載入。

每項技能也包含驗證標準，也就是交付結果前必須確認的事項。完整技能組與選用方式請見技能。

專案規則

Perch 每一輪都會從你的資料夾讀取常設指示，來源包括 .perch/PERCH.md、.perch/rules/，以及 ~/Documents/Perch/PERCH.md 的全域手冊。你放在這裡的規則會覆寫 Perch 的預設規則。

專案檔案、長期記憶與從更正中學習如何配合，請見記憶。

工作區

資料夾、編輯器、終端機、畫布與瀏覽器工作階段。

記憶

三套記憶系統，以及它們如何在每一輪送達模型。

本頁內容