檔案工具
最後更新
尋找、讀取、編輯、移除、還原、開啟與追蹤檔案的工具。
| 工具 | 說明 |
|---|---|
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 的 lines —— output=content 回帶行號的匹配行,multiline=true(v1.0.23)改以整份檔案比對 regex,讓 . 可跨越換行,並回報匹配涵蓋的每一行;offset / limit(預設 256)翻頁,context_lines 附上前後文行數 —— 標記 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, lines, context_lines, full}]);支援文字、PDF、DOCX、PPTX、CSV/TSV、圖片,以及音訊 / 影片 —— 媒體檔會經由已設定的 speech-to-text 模型回傳逐字稿,因此不再有獨立的轉錄工具。預設最多讀 2048 行(文件上限 1 MiB、圖片 10 MiB),超過時以 offset/limit 分頁 —— PDF 以頁、PPTX 以投影片、CSV 以列為單位。v1.3.21 起 lines 接受純文字檔的 1-based 行號,並在每行前後各讀 context_lines 行(預設 64,0 = 只讀該行),重疊的區段會合併、略過的內容以 ... 行標示(此時忽略 offset/limit);同一路徑可在 files 中出現多次,結果依序串接。自 v1.0.11 起被截斷的文字讀取會在結尾附上 [lines a-b of N; call again with offset=... for more],接續的 offset 不必用猜的。文字行以 "<row>\t<line>" 形式回傳,行號由讀取端加上、不存在於檔案中,拿該行當 write_file anchor 前必須先去除。write_file 修改既有檔案前必須先呼叫:自 v1.0.23 起,檔案須在本次執行中讀過、且讀取後修改時間未變,編輯才會被接受。v1.3.21 起,decision model 可依任務篩選讀取結果;至少 16,384 個 rune 時逐區塊判斷,不相關的區塊會標示略過。未設定模型或判斷失敗時保留內容。每個檔案項目可設 full: true 跳過相關性篩選,不會取消分頁或行號範圍;整份覆寫前請用此旗標讀取所有頁 |
write_file | filename 必填,可用絕對路徑或工作目錄的相對路徑。mode=write 以 write_content 建立或整份覆寫檔案;mode=patch 以 patch_contents 局部修補。每筆修補需有 old_string 與 new_string,可選 replace_all。錨點一律比對原始內容,同一行只要編輯範圍未重疊即可一起修補。空的 new_string 會刪除匹配內容,搭配 replace_all 會刪除所有匹配項目;未啟用而命中多處、範圍重疊,或會清空原本非空的檔案時,整批拒絕。修補上限為 1 MiB。修改既有檔案前必須在本輪用 read_files 讀取,且檔案其後未變動;成功寫入也算一次新讀取。工具預設顯示為 Write,修補模式顯示為 Edit |
remove_file | v1.3.11 新增,取代 edit_file(mode=remove)。把單一檔案(filename,必填;絕對路徑或相對於工作目錄)移到 ~/.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 表示當前執行中的任務)回滾整個任務,把該任務動過的每個檔案還原到執行前;filename 搭配 task_id 時只還原該檔。請傳入三個欄位:不用的 version 填 0,不用的 task_id 或 filename 填空字串。也能放回被 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 秒 |
edit_file 移除於 v1.3.20,改用 write_file。舊參數 content 改為 write_content,targets 改為 patch_contents。移除於 v1.3.21:
read_files 的 around/context 改為 lines/context_lines;find_files 的 context 改為 context_lines;write_file、remove_file、restore_file 的 path 改為 filename。