工具設計與規則
工具設計規則
新增或編輯工具的四條強制規則（build-time 契約來自 reasoning_guide(topics=["tool_generate"])，對外部 agent 則以 tool_generate_guide 曝露；後續品質由 code-reviewer skill 檢查，v1.0.17 起需以 /skills 安裝）：
- name 是首要的語意載體 — 此規則源自只有名稱的 stub 工具；自 v1.0.27 起所有工具在首輪即帶完整 schema，但模型瀏覽整份清單時最先看的仍是 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（唯讀工具） |
AlwaysLoad |
原意：第一輪即帶上 schema，而非只有名稱的 stub。共 15 個工具具備此旗標：ask_user、calculate、chat_history、edit_file、fetch_page、find_files、find_tools、http_request、read_files、reasoning_guide、run_command、run_skill、search_web、write_result、write_todo。自 v1.0.27 起所有工具都帶完整 schema 送出，此旗標已不影響 payload |
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 起使用）取消上限 |
加入 Concurrent: true 需同時滿足「無副作用」與「上游允許並行」。當前的並行工具集列於執行引擎頁。
工具 timeout 矩陣
toolRegister.Dispatch 會以工具註冊的 timeout（未覆寫時為 DEFAULT_TOOL_TIMEOUT——v1.1.2 起 15 分鐘，先前 1 分鐘）包住每一次呼叫——內建、script、API 與 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 分鐘 |
API（api_*） |
15 分鐘（v1.1.2 前為 60 秒） | extensions/apis/<name>.json 的 doc.Endpoint.Timeout——v1.1.2 起同時註冊為 dispatch timeout |
Endpoint.Timeout 的值，未設定為 15 分鐘 |
| MCP HTTP | Transport ResponseHeaderTimeout 15 分鐘（v1.1.2 前為 60 秒） |
無 | 15 分鐘 dispatch 預設 |
| MCP stdio | 無 | 無 | 15 分鐘 dispatch 預設 |
長時間執行的工具（script + API）每 30 秒向 daemon log 發出 running name=... elapsed=Ys/Zs 以利可見性。
長時執行的內建工具於註冊時宣告各自上限：run_command = 30 分鐘（RUN_COMMAND_TIMEOUT；v1.1.2 前為 60 分鐘）、subagents = MAX_SUBAGENT_TIMEOUT_MIN（30 分鐘）、download_file = 註冊 10 分鐘，請求本身由自身參數限制（預設 120 秒、上限 600 秒）、generate_audio = 5 分鐘、fetch_page / search_web = 90 秒、http_request = 由自身參數指定（預設 60 秒、上限 300 秒），仍受 15 分鐘預設約束、generate_image = 15 分鐘、html_template = 30 秒、open_file = 10 秒、ask_user = 無上限。
憑證自動修復
store_secret 為 SystemUse 工具，不出現在一般的 find_tools(mode=list) 列表；自 v1.0.27 起它和其他工具一樣，完整 schema 就在首輪 payload 中。System prompt 原本的 §10 Credential auto-heal 段落已移除；現在 system prompt 只留一行 Credentials —— 金鑰存放於 OS keychain（service agenvoy、account = 金鑰名稱），Linux 再查 ~/.config/agenvoy/.secrets，最後才是同名環境變數 —— 要求模型先讀 keychain，只有金鑰確實不存在時才使用 store_secret。流程寫在該工具自己的 description。遇到認證失敗——缺 key、401、403、token 過期——agent 從錯誤中取出 key 名稱、呼叫 store_secret（透過遮罩輸入取得新值 — 該值永不到達 LLM），再重新呼叫失敗的工具。每個工具每回合上限為兩輪 store_secret。