# 檔案工具

尋找、讀取、編輯、開啟與追蹤檔案的工具。

| 工具 | 說明 |
|---|---|
| `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 起，檔案須在本次執行中讀過、且讀取後修改時間未變，編輯才會被接受。**敏感檔案防護**：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` 內時，整次呼叫被拒絕、不寫入任何內容。`new_string` 留空即為刪除；插入的寫法是把 `old_string` 原樣放在 `new_string` 開頭。以行號定位的 `row` / `insert_string` 形式已移除 —— 行號會把同一次呼叫中先前的 target 一併算入，而那些內容尚未寫入磁碟；`mode=remove` 將檔案移置一旁，仍可還原；`mode=restore` 以 `version` id 還原單一版本，或以 `task_id` 回滾整個任務動過的所有檔案（`current` = 當前執行中的任務）。省略 mode 時：有 `content` → write、有 `targets` → patch；remove 與 restore 永不自動推斷。自 v1.0.23 起，覆寫既有檔案的 `write` 與每一次 `patch` 都要通過讀取新鮮度檢查：檔案須在本次執行中以 `read_files` 讀過，且之後未在磁碟上被變更（使用者、formatter 或其他指令），否則不寫入任何內容，錯誤訊息要求重新讀取；成功寫入後即視為已重新讀取，可接著編輯。`patch` 的 anchor 若只在彎引號與直引號上與檔案不同仍可命中，取代內容會沿用檔案原本的引號樣式。工具描述會把未指定位置、為使用者產生的檔案導向輸出目錄 |
| `file_history` | 工具動過的每個檔案的版本紀錄 —— 何時變更、當時任務目標為何、內容是什麼。`mode=list` 由新到舊列出版本，可用 `path`、`task_id`、`from`/`to` 本地時間與 `limit`（上限 24）過濾；`mode=read` 將每個路徑的最新紀錄版本與磁碟現況做 diff。這是 `edit_file(mode=restore)` 還原時所依據的快照層 |
| `open_file` | 以 OS 預設應用程式開啟檔案（播放影片、檢視圖片、開啟 PDF 閱讀器）。取代沙箱無法觸及的 `run_command` `open`/`xdg-open`。上限 10 秒 |