檔案工具
最後更新
尋找、讀取、編輯、移除、還原、開啟與追蹤檔案的工具。
| 工具 | 說明 |
|---|---|
find_files | 尋找檔案（queries: [{dir, pattern, file_pattern, recursive}]）。mode=list 回傳目錄內容（依字母排序），mode=glob 以檔名 pattern 比對路徑，自 v1.0.23 起依最近修改時間由新到舊排序，mode=search 以 RE2 regex grep 檔案內容。省略 mode 時自動推斷：pattern + file_pattern → search、只有 pattern → glob、兩者皆無 → list。glob pattern 必須含字面字元，全萬用字元（**/*）會被拒絕。多筆 query 的結果會合併去重。mode=list 與 mode=glob 上限為總計 128 KiB，截斷時結尾會說明丟棄了幾筆。mode=search 自 v1.0.11 起改為分頁而非截斷：output=files（預設）每個命中檔案回一列 {path, count, lines} —— 自 v1.0.23 起 lines 帶前五個匹配的行號，可直接交給 read_files 的 around —— output=content 回帶行號的匹配行，multiline=true（v1.0.23）改以整份檔案比對 regex，讓 . 可跨越換行，並回報匹配涵蓋的每一行；offset / limit（預設 256）翻頁，context 附上前後文行數 —— 標記 context: true 且不計入 offset / limit。單一匹配行超過 512 bytes 會被截短。每頁結尾帶 [files a-b of N ...] / [lines a-b of N ...] 說明下一個 offset，或標示 last page；翻頁期間 query 與 output 必須維持不變 |
read_files | 批次讀取一個或多個檔案（files: [{path, offset, limit, around, context}]）；支援文字、PDF、DOCX、PPTX、CSV/TSV、圖片，以及音訊 / 影片 —— 媒體檔會經由已設定的 speech-to-text 模型回傳逐字稿，因此不再有獨立的轉錄工具。預設最多讀 2048 行（文件上限 1 MiB、圖片 10 MiB），超過時以 offset/limit 分頁 —— PDF 以頁、PPTX 以投影片、CSV 以列為單位。自 v1.0.23 起 around 接受純文字檔的 1-based 行號，並在每行前後各讀 context 行（預設 20，0 = 只讀該行），重疊的區段會合併、略過的內容以 ... 行標示（此時忽略 offset/limit）；同一路徑可在 files 中出現多次，結果依序串接。自 v1.0.11 起被截斷的文字讀取會在結尾附上 [lines a-b of N; call again with offset=... for more]，接續的 offset 不必用猜的。文字行以 "<row>\t<line>" 形式回傳，行號由讀取端加上、不存在於檔案中，拿該行當 edit_file anchor 前必須先去除。edit_file 修改既有檔案前必須先呼叫：自 v1.0.23 起，檔案須在本次執行中讀過、且讀取後修改時間未變，編輯才會被接受。自 v1.3.11 起，設定 decision model 時，4096 字元以上且被判定與當前請求無關（信心 0.7 以上，與 chat_history mode=read 共用同一檢查）的檔案會被扣下：該項改回一行 File withheld 說明而非內容。同一檔案在同一 session 最多被扣下一次，第二次讀取即回傳內容；帶 around 的讀取不檢查；沒有 decision model 或檢查失敗時，內容照常回傳。敏感檔案防護：SSH keys、.pem、.key、.env 一律需要確認，無論是否處於 sudo 或 allowlist |
edit_file | 對磁碟上檔案的所有變更。mode=write 建立首版或刻意整份覆寫；mode=patch 透過 targets 陣列做區域編輯 —— 每個 target 為 {old_string, new_string} 加上選用的 replace_all，所有 anchor 都在套用任何變更前對原始檔案內容定位。兩個 target 覆蓋同一區域，或某 target 的 old_string 出現在較早 target 的 new_string 內時，整次呼叫被拒絕、不寫入任何內容。以下情況同樣整次拒絕：old_string 匹配多處卻未設 replace_all、patch 會把非空檔案清空、把歷史紀錄的佔位字串當成內容貼回，或檔案超過 1 MiB。new_string 留空即為刪除；插入的寫法是把 old_string 原樣放在 new_string 開頭。以行號定位的 row / insert_string 形式已移除 —— 行號會把同一次呼叫中先前的 target 一併算入，而那些內容尚未寫入磁碟。只剩 mode=write 與 mode=patch，且 path 為必填：mode=remove 與 mode=restore 移除於 v1.3.11（改用 remove_file / restore_file）。省略 mode 時：有 content → write、有 targets → patch。自 v1.0.23 起，覆寫既有檔案的 write 與每一次 patch 都要通過讀取新鮮度檢查：檔案須在本次執行中以 read_files 讀過，且之後未在磁碟上被變更（使用者、formatter 或其他指令），否則不寫入任何內容，錯誤訊息要求重新讀取；成功寫入後即視為已重新讀取，可接著編輯。patch 的 anchor 若只在彎引號與直引號上與檔案不同仍可命中，取代內容會沿用檔案原本的引號樣式。工具描述會把未指定位置、為使用者產生的檔案導向 system prompt 所列的輸出目錄，並要求給完整路徑；path 留空會直接被拒絕，不會落到輸出目錄。path 可為絕對路徑或相對於工作目錄 |
remove_file | v1.3.11 新增，取代 edit_file(mode=remove)。把單一檔案（path，必填；絕對路徑或相對於工作目錄）移到 ~/.config/agenvoy/.store/temp/ 而非刪除，在檔案歷史記下這次搬移，並回傳移到哪裡；restore_file 可放回。每次呼叫都要求確認，除非使用者已允許本輪所有呼叫。只在明確要求或 Skill 步驟中使用；skill 或 script tool 改用 edit_skill / edit_tool 的 mode=remove。subagent leg 不可用。tool-call 行顯示為 Remove(<path>) |
restore_file | v1.3.11 新增，取代 edit_file(mode=restore)。以 version（file_history 某列的 id，同時指明檔案與狀態；優先於 task_id）放回一個紀錄版本，或以 task_id（chat_history 的 task id，或以 current 表示當前執行中的任務）回滾整個任務，把該任務動過的每個檔案還原到執行前；path 搭配 task_id 時只還原該檔。version / task_id 至少擇一。也能放回被 remove_file 移走的檔案。每次呼叫都要求確認，除非使用者已允許本輪所有呼叫。subagent leg 不可用。tool-call 行顯示為 Restore(...)，括號內為路徑、version N 或 task id |
file_history | 工具動過的每個檔案的版本紀錄 —— 何時變更、當時任務目標為何、內容是什麼。mode=list 由新到舊列出版本，可用 path、task_id、from/to 本地時間與 limit（上限 24）過濾；mode=read 將每個路徑的最新紀錄版本與磁碟現況做 diff。這是 restore_file 還原時所依據的快照層 |
open_file | 以 OS 預設處理程式開啟檔案或 URL（播放影片、檢視圖片、開啟 PDF 閱讀器；自 v1.2.1 起也可開啟連結或系統設定面板，如 x-apple.systempreferences:...）。URL 一律先請使用者確認。取代沙箱無法觸及的 run_command open/xdg-open。上限 10 秒 |