檔案系統和 Shell 工具

Triggerfish 為代理提供通用的檔案系統和 Shell 工具，用於讀取、寫入、搜尋和執行指令。這些是其他功能（執行環境、探索、技能）建構的基礎工具。

工具

read_file

讀取絕對路徑下的檔案內容。

參數	類型	必要	描述
path	string	是	要讀取的絕對檔案路徑

回傳檔案的完整文字內容。

write_file

將內容寫入工作區相對路徑的檔案。

參數	類型	必要	描述
path	string	是	工作區中的相對路徑
content	string	是	要寫入的檔案內容

寫入範圍限定在代理的工作區目錄。代理無法寫入檔案系統上的任意位置。

edit_file

替換檔案中的唯一字串。old_text 必須在檔案中恰好出現一次。

參數	類型	必要	描述
path	string	是	要編輯的絕對檔案路徑
old_text	string	是	要尋找的精確文字（必須在檔案中唯一）
new_text	string	是	替換文字

這是一個精確編輯工具——它找到一個精確匹配並替換它。如果文字出現多次或完全不出現，操作會失敗並回傳錯誤。

list_directory

列出給定絕對路徑下的檔案和目錄。

參數	類型	必要	描述
path	string	是	要列出的絕對目錄路徑

目錄條目以 / 後綴回傳。

search_files

搜尋匹配 glob 模式的檔案，或使用 grep 搜尋檔案內容。

參數	類型	必要	描述
path	string	是	要搜尋的目錄
pattern	string	是	檔案名稱的 glob 模式，或在檔案內搜尋的文字/正規表達式
content_search	boolean	否	如果為 true，搜尋檔案內容而非檔案名稱

run_command

在代理工作區目錄中執行 Shell 指令。

參數	類型	必要	描述
command	string	是	要執行的 Shell 指令

回傳 stdout、stderr 和退出碼。指令在代理的工作區目錄中執行。PRE_TOOL_CALL hook 在執行前檢查指令是否在拒絕清單中。

與其他工具的關係

這些檔案系統工具與執行環境工具（exec.write、exec.read、exec.run、exec.ls）有重疊。區別：

• 檔案系統工具操作絕對路徑和代理的預設工作區。它們始終可用。
• 執行工具在具有明確隔離、測試執行器和套件安裝的結構化工作區中操作。它們是執行環境整合的一部分。

代理使用檔案系統工具進行一般檔案操作，使用執行工具進行開發工作流程（寫入/執行/修復迴圈）。

安全性

• write_file 範圍限定在代理的工作區目錄
• run_command 通過 PRE_TOOL_CALL hook，以指令作為上下文
• 指令拒絕清單封鎖危險操作（rm -rf /、sudo 等）
• 所有工具回應通過 POST_TOOL_RESPONSE 進行分類和 taint 追蹤
• 在計畫模式中，write_file 在計畫被核准前被封鎖