工具設計與規則
最後更新
工具設計規則
新增或編輯工具的四條強制規則（build-time 契約來自
reasoning_guide(topics=["tool_generate"])，對外部 agent 則以 tool_generate_guide 曝露；後續品質由 code-reviewer skill 檢查，v1.0.17 起不再內建，需以 /skill → system 安裝（v1.0.22 前為 /skills））：- name 是首要的語意載體 — 自 v1.2.0 起，模型在
find_tools取得 schema 前只看得到工具名稱 —— 除claude-code外的 provider 看的是每輪的Tools清單，claude-code同樣只收到名稱，模型就是依 name 挑選工具 - description 固定 3 行、60-200 字元 — What（核心動作）／When（觸發時機 vs 替代方案，例：
use for X; Y for Z）／Precondition（關鍵限制，無則省略）。不放填充語、不用粗體、不放輸出 schema dump。 - 僅限英文 — 中文只出現在面向使用者的 handler 回傳訊息
- 選用欄位必須宣告
default— handler 仍需防禦 nil/缺失
觸發條件與同類工具比較是 When 行的必要內容，不是禁止項——只寫核心動作而沒有觸發訊號的 description 視為不完整。Parameter description 須涵蓋 How／When／Example，非平凡型別（object/array/enum）若說明少於 20 字元視為不完整。
工具並行標記
toolRegister.Def 帶有五個行為旗標：| 旗標 | 效果 |
|---|---|
AlwaysAllow | 豁免 confirm gate（唯讀工具） |
Concurrent | 選擇加入 Pass 2 fan-out（每次呼叫一個 goroutine） |
Background | 迴圈不等待其結果 |
SystemUse | 內部管理用工具——不出現在一般列表，只有在對 find_tools(mode=list) 要求系統工具時才顯示 |
Timeout | 覆寫預設上限（DEFAULT_TOOL_TIMEOUT，v1.1.2 起 15 分鐘，先前 1 分鐘）；NoToolTimeout（ask_user 自 v1.0.23 起使用）取消上限 |
AlwaysLoad 旗標已移除；schema 改經 find_tools 載入（移除於 v1.2.0）。加入
Concurrent: true 需同時滿足「無副作用」與「上游允許並行」。當前的並行工具集列於執行引擎頁。工具 timeout 矩陣
toolRegister.Dispatch 會以工具註冊的 timeout（未覆寫時為 DEFAULT_TOOL_TIMEOUT——v1.1.2 起 15 分鐘，先前 1 分鐘）包住每一次呼叫——內建、script 與 MCP 皆然。各 adapter 在此上限內再套自己的限制：| Adapter | Adapter 預設 | 可設定 | 實際上限 |
|---|---|---|---|
| Built-in | 15 分鐘 | 每個工具的 Def.Timeout | Def.Timeout |
Script（script_*） | 15 分鐘（v1.1.2 前為 300 秒） | ~/.config/agenvoy/tools/script/<name>/ 的 tool.json "timeout": <seconds>——同時註冊為 dispatch timeout | tool.json 的值，未設定為 15 分鐘 |
| MCP HTTP | Transport ResponseHeaderTimeout 15 分鐘（v1.1.2 前為 60 秒） | 無 | 15 分鐘 dispatch 預設 |
| MCP stdio | 無 | 無 | 15 分鐘 dispatch 預設 |
長時間執行的 script 工具每 30 秒向 daemon log 發出
running name=... elapsed=Ys/Zs 以利可見性。API 工具 adapter（api_*）與其 Endpoint.Timeout 已隨使用者自訂 API 工具移除於 v1.3.2。長時執行的內建工具於註冊時宣告各自上限：
run_command = 30 分鐘（RUN_COMMAND_TIMEOUT；v1.1.2 前為 60 分鐘）、subagents = MAX_SUBAGENT_TIMEOUT_MIN（30 分鐘，前景 leg）、download_file = 註冊 10 分鐘，請求本身由自身參數限制（預設 120 秒、上限 600 秒；v1.3.6 新增的 render=true 存網頁不套用此參數）、generate_audio = 5 分鐘、fetch_page / search_web = 90 秒、http_request = 由自身參數指定（預設 60 秒、上限 300 秒），仍受 15 分鐘預設約束、generate_image = 15 分鐘、html_template = 30 秒、open_file = 10 秒、ask_user = 無上限。background_command 與 background_subagents 呼叫後立即回傳 task id，因此不另註冊上限；背景指令或 leg 改受各自的 timeout_min（1-60 分鐘，預設 60）限制。在 TUI 以外兩者皆被排除。run_command_background 已更名為 background_command（移除於 v1.3.2）；run_websocket 與其 timeout（1-1440 分鐘）已移除於 v1.3.2，subagents 的 background / timeout_min 參數也已移除於 v1.3.2，改用 background_subagents。憑證自動修復
store_secret 為 SystemUse 工具，不出現在一般的 find_tools(mode=list) 列表；自 v1.2.0 起它和固定組（find_tools、run_tool、reasoning_guide、write_todo、chat_history、ask_user、write_result）以外的工具一樣，schema 經 find_tools 取得。System prompt 原本的 §10 Credential auto-heal 段落已移除；自 v1.2.0 起 system prompt 只留一行短句 —— 憑證存放於 OS keychain（service agenvoy），查找方式見 store_secret。查找順序（keychain、account = 金鑰名稱，Linux 再查 ~/.config/agenvoy/.secrets，最後是同名環境變數）、「不會匯出到行程環境變數，因此 printenv 為空不代表沒有金鑰」的說明，以及處理流程都寫在該工具自己的 description。遇到認證失敗——缺 key、401、403、token 過期——agent 從錯誤中取出 key 名稱、呼叫 store_secret（透過遮罩輸入取得新值 — 該值永不到達 LLM），再重新呼叫失敗的工具。每個工具每回合上限為兩輪 store_secret。