工具系統參考

file_read

功能：

• 讀取完整檔案內容或特定行範圍
• 在修改前理解程式碼的必要工具
• 透過範圍指定有效處理大型檔案

使用情境：

• 編輯前讀取設定檔
• 理解既有的實作模式
• 審查測試檔案以了解覆蓋率

範例：

# Read entire file
file_read("src/components/Button.tsx")

# Read specific range for large files
file_read("package-lock.json", start_line=1, max_lines=50)

file_edit

功能：

• 使用完全字串相符進行精準文字替換
• 透過 multiple 旗標進行多處替換
• 保留檔案結構與格式

使用情境：

• 更新函式實作
• 修改設定值
• 跨檔案重構變數名稱

最佳做法： 用於針對性的變更。若要完整重寫，請改用 file_write。

file_write

功能：

• 從零開始建立新檔案
• 完全替換既有檔案內容
• 處理任何以文字為基礎的格式

使用情境：

• 產生新元件或模組
• 建立設定檔
• 撰寫測試檔案

警告： 會完全覆寫既有檔案。針對局部修改請使用 file_edit。

glob

功能：

• 找出符合模式的檔案：**/*.ts、src/**/*.js
• 依目錄路徑篩選
• 以排除模式縮小結果
• 控制結果數量

使用情境：

• 找出專案中的所有元件
• 定位測試檔案
• 跨目錄識別設定檔

範例模式：

**/*.tsx          # All TypeScript React files
src/**/*.test.js  # All test files in src
**/config.*       # All config files anywhere

grep_content

功能：

• 使用正規表達式模式搜尋檔案內容
• 顯示相符項目前後的上下文行（-B、-A 旗標）
• 不分大小寫搜尋
• 使用 glob 模式依檔案類型篩選

使用情境：

• 找出函式定義
• 定位 API 端點實作
• 搜尋特定錯誤訊息
• 識別安全模式

範例：

# Find authentication-related code
grep_content("auth.*login", glob="**/*.ts")

# Search with context
grep_content("TODO", glob="src/**", context_before=2, context_after=2)

grep_file

功能：

• 列出含有相符模式的檔案
• 當你只需檔案位置時，比 grep_content 更快
• 支援正規表達式模式
• 以 glob 篩選檔案類型

使用情境：

• 識別哪些檔案需要重構
• 找出匯入特定模組的檔案
• 定位含過時模式的檔案

最佳做法： 先用 grep_file 識別相關檔案，再用 file_read 進行詳細檢視。

list_dir

功能：

• 顯示目錄階層
• 透過 max_depth 參數控制深度
• 以排除模式篩選輸出

使用情境：

• 理解專案結構
• 驗證目錄組織
• 找出特定子目錄

bash

功能：

• 執行 shell 命令
• 最大逾時：120 秒（2 分鐘，硬性限制）
• 以 && 串接有相依關係的命令
• 提供說明性摘要以利清晰

使用情境：

• 執行測試
• 建置專案
• 安裝相依套件
• Git 操作
• 資料庫遷移

範例：

# Run tests
bash("npm test", timeout=60000, summary="Run Jest test suite")

# Chain dependent commands
bash("npm install && npm run build", timeout=120000)

安全性： 命令以使用者權限執行。請在手動接受模式下審查命令。

spawn_subagent

功能：

• 啟動具有獨立上下文的專門子代理
• 類型：explorer、verifier、code-reviewer
• 委派複雜任務而不污染主要上下文
• 平行執行子代理以提升效率

使用情境：

• explorer： 在大型程式碼庫中搜尋模式
• verifier： 驗證實作邏輯
• code-reviewer： 安全與品質評估

最佳做法： 將探索性研究委派給 Explorer 子代理，以保留主要對話的上下文。

todo_update

功能：

• 建立並管理任務清單
• 更新任務狀態（pending、in_progress、completed）
• 在複雜實作過程中追蹤進度

使用情境：

• 拆解多步驟功能
• 追蹤重構進度
• 管理遷移任務

web_search

功能：

• 查詢網路搜尋引擎
• 控制結果數量
• 依新鮮度篩選（近期天數）

使用情境：

• 為不熟悉的 API 尋找文件
• 研究錯誤訊息
• 查看目前的最佳做法

web_fetch

功能：

• 取得網頁內容
• 以特定查詢分析內容
• 擷取結構化資訊

使用情境：

• 閱讀文件頁面
• 分析 API 文件
• 從教學擷取範例

資料格式

建置與套件檔案

file_read 效率

最佳做法：

• 對超過 500 行的檔案使用行範圍，以避免上下文超載
• 只讀取任務所需的相關區段
• 對於大型檔案，先用 grep_content 識別相關的行號

# Good: Read specific section
file_read("large-config.json", start_line=100, max_lines=50)

# Less efficient: Read entire large file
file_read("large-config.json")  # May consume excessive context

file_edit 精準度

最佳做法：

• 確保完全字串相符以避免失敗的編輯
• 對多處類似變更，使用 multiple=true 旗標
• 編輯前驗證檔案路徑

file_write 安全性

最佳做法：

• 仔細檢查路徑以防止意外覆寫
• 僅用於新檔案或完整重寫
• 進行修改時，為求安全請優先使用 file_edit

glob 模式具體性

最佳做法：

• 使用具體模式以縮小範圍：用 src/**/*.ts 而非 **/*
• 以排除模式排除目錄：!**/node_modules/**
• 限制結果以防止輸出過多

# Good: Specific scope
glob("src/components/**/*.tsx", max_results=50)

# Less efficient: Too broad
glob("**/*")  # Returns thousands of results

grep 策略

建議的工作流程：

1. 使用 grep_file 識別相關檔案
2. 以 file_read 讀取特定檔案
3. 當你需要周圍上下文時，使用 grep_content

效能提示：

• 正規表達式模式可能比純字串花更久
• 不分大小寫搜尋較慢
• 將上下文行（-A、-B）限制在必要範圍內

bash 最佳做法

安全的命令執行：

• 為命令說明提供清楚的摘要
• 為長時間執行的操作設定適當的逾時
• 以 && 串接有相依關係的命令
• 仔細審查破壞性命令（rm、drop、truncate）

# Good: Clear summary, reasonable timeout
bash("npm run build", timeout=120000, summary="Build production bundle")

# Good: Chained dependencies
bash("npm install && npm run test", timeout=180000)

安全性考量

關鍵安全規則：

• 命令以使用者權限執行
• 切勿執行不受信任的命令
• 在共用程式碼庫中使用手動接受模式進行審查
• 避免會暴露憑證或敏感資料的命令

子代理委派效率

何時使用子代理：

• Explorer： 程式碼庫搜尋、架構問題（節省主要上下文）
• Verifier： 快速驗證檢查（獨立驗證）
• Code-reviewer： 安全與品質審查（詳細分析）
• General： 複雜的多步驟任務（平行執行）

最佳做法： 將探索與研究任務委派給子代理，以保留主要對話的上下文供進行中的開發工作使用。

上下文管理

策略性工具使用：

• 有策略地讀取檔案——只讀取所需內容
• 使用子代理進行背景研究
• 在長時間工作階段中監控上下文消耗
• 以 todo_update 將複雜操作拆解為步驟

高效的工作流程：

1. 規劃： 使用 glob/grep 識別範圍
2. 讀取： 只讀取相關的檔案／區段
3. 執行： 適當時委派給子代理
4. 驗證： 以 Verifier 子代理進行快速檢查

檔案大小限制

大型檔案處理： 非常大的檔案（>10,000 行）應分段讀取，以避免：

• 上下文視窗耗盡
• 回應緩慢
• 記憶體問題

工具逾時預設值

工具限制：

• Bash 逾時： 最大 120 秒（2 分鐘）
• 檔案操作： 無大小限制（大型檔案會自動分批讀取）
• 大型檔案處理： >256KB 的檔案僅回傳前 256KB 的內容
• 搜尋結果： glob 或 grep_content 的結果無限制
• 並行子代理： 平行執行無限制

逾時設定：

• 為長時間執行的操作設定明確的逾時
• 監控是否有掛起的處理程序
• 超過 2 分鐘逾時的命令將被終止

並行操作

平行執行： 多個子代理可平行執行，以加快複雜操作。主要代理會自動處理協調。

效能優勢：

• 減少多步驟任務的總執行時間
• 高效的資源運用
• 自動任務編排
• 並行子代理數量無限制