Link Search Menu Expand Document
AIEE

🧭 OPENCODE 檔案管理工具使用範例

Table of contents

OPENCODE 代理 AI 檔案管理工作

以下以 OPENCODE 為例，列出「代理 AI」能夠協助完成的 檔案管理工作，從最簡單的「列目錄」到能在大型專案中自動化、並行、合併、版本控制等高度複雜的任務。

（所有範例均假設你已知 OPENCODE 的 API 參數格式，例如 glob、grep、read、apply_patch、multi_tool_use.parallel、bash 等；若希望操作 local 版本，請先加上 path 或 workdir。）

1️⃣ 基礎檔案管理（單一檔案/目錄）

任務目標OPENCODE 參數範例產生結果
列出指定目錄下所有檔案快速定位{"tool":"glob","pattern":"*","path":"/app/src"}回傳檔名陣列
在某個程式碼資料夾尋找 TODO追蹤待修/待審{"tool":"grep","pattern":"TODO","include":"*.js","path":"/app/src"}簡短列出檔案位置信息
讀取單一檔案前 200 行取用摘要或檢查內容{"tool":"read","filePath":"/app/src/main.py","limit":200}文字內容
新增一個 README快速新增資訊{"tool":"apply_patch","patchText":"*** Begin Patch\n*** Add File: README.md\n+Hi, this project is about…\n*** End Patch"}README 被創建
刪除一個設定檔清理不再使用的檔案{"tool":"apply_patch","patchText":"*** Begin Patch\n*** Delete File: .DS_Store\n*** End Patch"}檔案被移除
直線式複製檔案（避開 shell）在資料夾 A 內直接複製到 B① apply_patch Create new file ＂B/file.txt＂內容自 A 讀取；② apply_patch Delete old兩個檔案同步

注意：所有「寫入」必須使用 apply_patch，不能使用 echo/cat 或直接寫入。

2️⃣ 中階檔案處理（多檔案、多條件）

任務與之相對應的 OPENCODE 調用說明
同時跑多個 grep 查找跨站的 bug tag{"tool":"multi_tool_use.parallel","tool_uses":[{"tool":"grep","pattern":"FIXME","include":"*.ts"},{"tool":"grep","pattern":"BUG","include":"*.js"}]}并行提高查詢速度
在大量檔案中批次加上統一註解迭代每個檔案：先 read、產生 patch、再 apply_patch可先一次性產出多筆 patch 再一次 apply_patch 批次提交
大型專案的資料夾層級結構生成圖glob 取得所有檔案，bash 呼叫 svggraph 或 mermaid把結構輸出為可視化圖表
針對多個不同程式碼語言的重構先 glob + grep 篩選 → 逐一 read → 用前端工具（如 bash) 做語言特定重命名、方法抽離 → apply_patch兼備原始碼一致性與版本控制
同步多個專案目錄下的相同檔案版本先 glob 跨專案列舉 → 逐一 read → 實作內容一致比較 → apply_patch 同步保持多 repo 的樣板檔案同步

備援：對於極大檔案集合，先使用 glob 找到候選，再把 grep 與 read 並行執行，可大幅縮短總耗時。

3️⃣ 進階多檔案並行與自動化（使用 multi_tool_use.parallel）

任務示範程式碼說明
同時讀 10 個文檔{"tool":"multi_tool_use.parallel","tool_uses":[{"tool":"read","filePath":"/app/src/a.py"},{"tool":"read","filePath":"/app/src/b.py"}, …]}調用多個 read，降低單筆 I/O 週期
批次比對差異① glob 取得所有檔案；② multi_tool_use.parallel 執行多個 read；③ 用腳本做 diff（在 bash 內）只要提供 read 全部內容，後續再引擎做 diff
一鍵修正多個格式錯誤先 grep 找出所有 “console.log”；再一次 apply_patch 創建一個 patch，對所有檔案同時 replace 為 logger.info一次性修改多檔中所有錯誤格式
排程化自動化檢查使用 bash 後面配合 CI pipeline；腳本在 post-commit 時執行 grep / apply_patch 進行安全檢查讓每次 commit 都自動執行檢查，保持品質
大檔案分段讀取read 只讀取 2000 行，之後第二次 read 以 offset 2001 開始適用於二進位檔、log 與影片等

4️⃣ 版本控制（Git）整合

任務機制何時使用事例
顯示 Git 狀態bash 執行 git status檢查本地變更
批次加入 & Commitbash 執行 git add -A && git commit -m "... "如代碼重構後提交
產生 PR 標籤bash ex git push + hub pull-request需要手動授權時
拉取上游更新bash 執行 git pull --rebase先同步遠端
整理分支bash 執行 git branch -d feature-x成功 merge 後
注意：除非得到明確指示，不允許執行 git reset --hard, git merge --abort 等破壞性操作。  

最佳實踐

  • 所有編輯仍透過 apply_patch 來保持可追蹤；
  • bash 只做版本控制或構建操作（如 npm run build、mvn package）。
  • 以 multi_tool_use.parallel 來同時執行 git status + git blame 等多個 shell 指令，提升 CI 執行速度。

5️⃣ 高度自動化（複雜工作流）

任務說明OPENCODE 參數
自動程式碼風格檢查 & 修正① glob + grep 選出所有 .py; ② 用 apply_patch 生成 PEP8 修正 patch → apply_patch 一次提交apply_patch 生成一大 patch 或分片 patch
多重平台文件同步① 在 Linux 服務器與 Windows 服務器各執行 bash 取得檔案 Hash；② 若不一致，使用 read 分段同步，最後 apply_patch 更新透過雙程式確認相容性
資料遷移（大型 SQL dump）① read 讀取部分 SQL 檔；② 伺服器執行 bash 接入 psql / mysql；③ 產生對應 apply_patch 以新增或刪除遷移文件過程複雜但可完全由 AI 監控
安全備份與刪除① 針對「敏感」關鍵字（如 password）用 grep 查找；② 若檔案過大則分段 read 產生加密版本；③ 最後 apply_patch 替換成加密檔；④ bash 做備份安全性、不可逆操作

🌟 總結：代理 AI（OPENCODE）能做到的檔案管理能力

能力層級代表功能主要工具
基礎列目錄、搜尋、讀取、單檔修改、刪除、建立glob, grep, read, apply_patch
中階多檔並行搜尋、批次 patch、跨語言重構、目錄結構圖multi_tool_use.parallel, bash, apply_patch
進階自動化 CI/CD 任務、與 Git 緊密結合、版本同步、 整合測試bash, apply_patch + Git, glob/grep
高階大型檔處理（分段 read、二進位安全）、多機器備份、加密遷移、安全審計、完整工作流自動化read(分段+limit), apply_patch, bash, multi_tool_use.parallel

核心原則

  1. 安全先行：所有寫入必須走 apply_patch；
  2. 可審核：patch 文字可審計、可回溯；
  3. 效率守護：使用 glob + grep 篩選後再 read/patch，並行處理提升 I/O 時間。

這樣的代理 AI 能把「零件」級別的檔案操作，組合成完整、可追蹤、可重複的工作流，讓開發、維護、測試、部署變得更有章法、更安全，也更易於在團隊協作時保持一致性。