Link Search Menu Expand Document
AIEE

🧭 OPENCODE 檔案管理工具簡介

Table of contents

OPENCODE 為一整套受控、工程化的「檔案管理」工具集合，專為專案開發團隊設計。
它結合了安全性、可審核性與高效作業的特性，將常見危險命令（如 echo/cat、交互式 Git）先封裝或限制，並鼓勵以專門 API（glob、grep、read、apply_patch、multi_tool_use、bash）完成大部分開發流程。

下面將 （1）更細緻說明各功能、（2）展示可調控參數、（3）提供實務範例，並整理 最佳實務與注意事項。

1. 高階能力（核心功能）

能力作用範圍典型使用順序
檔案搜尋（glob）依正則式或扁平字串快速定位檔案路徑先用 glob 找出候選檔案
內容搜尋（grep）以正則式在檔案內容中查找關鍵字／字串先用 grep 結合 glob 過濾
讀取檔案（read）安全地把檔案內容拉到記憶體先 read 再進行更複雜處理
編輯檔案（apply_patch）以純文字 patch 統一修改、追加、刪除、移動檔案只允許請求 patch，禁止直接覆寫
並行作業（multi_tool_use.parallel）同時啟動多個工具呼叫（如多個 read）提升 I/O 效率必要時使用，配合 read 並行
受控執行 shell（bash）執行 Git、建置等必要命令僅限非檔案編輯，需做 Git Safety Protocol

關鍵說明

  • apply_patch 是 OPENCODE 唯一被允許直接改寫檔案內容的 API。
  • bash 只能用來執行指令，禁止直接使用 echo/cat/sed 等改寫檔案。
  • 所有 API 都會進行安全檢查，確保命令不會在專案外部造成破壞。

2. 可調控項（依工具）

2.1 glob

參數作用參考示例
patternGlob 表達式（support **、*、? 以及大括號列舉）"**/*.ts"、"src/**/index.*"
path (可選)搜尋起始目錄（未指定則從專案根搜尋）"/app"

注意：

  • Glob 只對檔名做匹配，不會閱讀檔內容。
  • 速度快、低記憶體使用。

2.2 grep

參數作用參考示例
pattern正則表達式，搜尋檔案內容"TODO.*"
include (可選)檔案型別過濾，支持多個（如 *.js, *.{ts,tsx}）"*.py"
path (可選)搜尋目錄"/app"

優化技巧：

  • include 可先縮小搜尋範圍，避免對大量文字檔進行正則頻繁匹配。
  • 只在相信正則式正確時使用，避免 CPU 與 IO 過度消耗。

2.3 read

參數作用參考示例
filePath檔案絕對路徑（必填）"C:/project/src/main.py"
limit (可選)返還最大行數，預設 2000 行500
offset (可選)從第幾行開始讀（1-indexed）1

實務說明

  • 長行被截斷，若需完整二進位內容請先拆分成多個 read。
  • 讀取過程鎖定檔案，確保不被同時編輯。

2.4 apply_patch

參數作用參考示例
patchText專門格式的 patch；必須以宣告 header 開頭，例：
*** Begin Patch
*** Add File: new_file.txt
+This is a new file
*** End Patch		參見下方詳細範例

編輯限制

  • 只允許 Add / Update / Delete / Move 相關指令。
  • 不能在此 API 內使用 echo/cat，確保修改可被審核。
  • 新增檔案建議使用 ASCII，若含 Unicode 需自行保留。

2.5 multi_tool_use.parallel

參數作用參考示例
tool_uses需要並行呼叫的工具呼叫陣列（如多個 read）[ read(params1), read(params2), ... ]

使用時機：大檔案或多檔案同時讀取、處理時，可顯著提升 I/O 效率。

2.6 bash

參數作用參考示例
command要執行的 shell 命令"git add -A"
description5–10 個字簡短說明（必填）"Add all changes"
workdir (可選)執行目錄（預設為專案根）"/app/repo"
timeout (可選)最大執行時間（秒）120

Git Safety Protocol

  • 禁止強制推送、reset --hard、rebase -i 等破壞性命令。
  • 只允許非破壞性 Git 操作（如 status、log、add、commit 等）。
  • 若需要 commit，請在用戶明確提出需求後再執行。

3. 呼叫範例（實務流程）

步驟 1： 用 glob 取得所有 .py 檔案

{
  "tool": "glob",
  "pattern": "**/*.py"
}

步驟 2： 用 grep 選出含 TODO 的檔案

{
  "tool": "grep",
  "pattern": "TODO",
  "include": "*.py"
}

步驟 3： 同時讀取多個符合條件的檔案

{
  "tool": "multi_tool_use.parallel",
  "tool_uses": [
    {"tool":"read","filePath":"path/to/file1.py","limit":200},
    {"tool":"read","filePath":"path/to/file2.py","limit":200}
  ]
}

步驟 4： 使用 apply_patch 進行小範圍修改（加入註解、修正語法）

{
  "tool":"apply_patch",
  "patchText":"*** Begin Patch\n*** Update File: src/utils.py\n@@\n-  print(\"processing\")\n+  print(\"processing... done\")\n*** End Patch"
}

步驟 5： 若需提交變更，使用 bash 執行 Git 指令

{
  "tool":"bash",
  "command":"git add -A && git commit -m \"Fix TODOs\"",
  "description":"Commit TODO fixes",
  "workdir":"/app",
  "timeout":60
}

註：Commit 只在你明確要求我建立 commit 時才會進行。
這樣的流程確保所有檔案操作經過審核、可追蹤，並且減少直接使用 shell 編輯的風險。

4. 最佳實務與注意事項（總結）

類別建議做法反面做法（避免）
搜尋glob → grep → read同時執行大量 grep 或大檔案搜尋
編輯只用 apply_patch直接 echo/cat 覆寫檔案
並行需要時用 multi_tool_use.parallel同步執行多個重複 I/O
** Git**僅做必要非破壞性操作git reset --hard、強制推送
長檔案分段 read 讀取一次性載入整個大檔
非 ASCII檢查並保留原始編碼直接用 patch 新增非 ASCII，可能損壞
安全始終使用受控 API在 bash 官方歸零工作目錄外執行命令

核心原則：安全 → 可審核 → 高效。
采用 OPENCODE 方案可以大幅降低意外損壞專案檔案、提升工作流可追踪性，同時保持高效開發體驗。

結語