內建工具
檔案操作
| 工具 | 說明 |
|---|---|
read_files |
批次讀取一個或多個檔案（files: [{path, offset, limit}]）；支援文字、PDF、DOCX、PPTX、CSV/TSV 或圖片。預設讀整份（上限 1 MB），超過時以 offset/limit 分頁。必須在 patch_file 之前呼叫。敏感檔案防護：SSH keys、.pem、.key、.env 一律需要確認，無論是否處於 sudo 或 allowlist |
write_file |
建立尚不存在的檔案，或刻意整份覆寫。對已存在檔案的修改一律走 patch_file |
patch_file |
透過 targets 陣列進行目標編輯——每筆目標為取代（old_string/new_string[, replace_all][, row]）或純插入（insert_string/row）；帶 row 的目標由高到低套用，確保行號在套用過程中維持有效 |
list_files |
批次列出目錄內容（dirs: [{dir, recursive}]）；回傳以每個請求目錄為 key 的 JSON 物件 |
glob_files |
批次 glob 樣式搜尋（queries: [{dir, pattern}]）；結果合併並去重。catch-all 樣式（**/*）會被拒絕——每個 pattern 必須帶有字面字串 |
search_files |
批次以 RE2 regex 搜尋檔案內容（queries: [{dir, pattern, file_pattern}]）；結果合併並去重 |
open_file |
以 OS 預設應用程式開啟檔案（播放影片、檢視圖片、開啟 PDF）。取代 run_command 的 open/xdg-open——沙箱路徑無法觸及該服務。上限 15 秒 |
網頁（唯讀，可並行）
| 工具 | 說明 |
|---|---|
fetch_page |
抓取網頁（readability + 4xx/5xx 透過 ToriiDB 跳過 cache）；same_session=true 用於需登入的站台，save=true 存成本地檔案。上限 90 秒 |
search_web |
DuckDuckGo 搜尋；cdp=true 強制以瀏覽器抓取（收到 202 時自動啟用）。上限 90 秒 |
search_google_news |
Google News RSS；結果為空時逐級放大時間窗（1 小時 → 24 小時 → 7 天），再回退到 search_web |
HTTP
| 工具 | 可並行 | 說明 |
|---|---|---|
send_http_request |
✓ | 原始 HTTP 請求（GET/POST/PUT/PATCH/DELETE，可選 multipart 上傳），回傳 status + headers + body。內建 SSRF 防護（DNS 解析後比對 loopback / private / link-local）；要放行特定 host 透過 net_white_list |
download_file |
✓ | 下載二進位檔案到本地（tar.gz、圖片、壓縮檔）；JSON/HTML 請用 send_http_request 或 fetch_page(save=true)。上限 10 分鐘 |
媒體
| 工具 | 可並行 | 說明 |
|---|---|---|
transcribe_media |
✓ | 透過 Gemini 進行本地音訊 / 影片轉錄（ogg、oga、opus、mp3、wav、m4a、flac、aac、mp4、mov、webm、mpeg、3gp）。對於收到的語音訊息，轉錄結果就是要執行的指令。上限 5 分鐘。(需 gemini 憑證) |
圖片生成目前停用——generate_image 工具、/image2 指令與 enable_image2 設定旗標已於 router 整合重新設計期間移除。
工具類
| 工具 | 可並行 | 說明 |
|---|---|---|
calculate |
✓ | 批次運算式計算（算術、單位換算、貨幣運算）。回傳 {expression: result}；單一運算式失敗只回該筆錯誤字串，不會讓整個呼叫失敗 |
Agent 編排
| 工具 | 說明 |
|---|---|
list_subagent_sessions |
列出可作為 subagent 重用的具名（非暫時）session 及其角色。委派單一子任務前先呼叫 |
invoke_subagent |
在獨立 session 中啟動 subagent（in-process，不走 HTTP）；name 留空即為暫時 session。同時最多 3 條並行——第 4 條會排隊等待且自身 timeout 照跑，因此大量 fan-out 須以 3 為單位分批。結果帶 [subagent · <model> · session=<id> · usage: in=X out=Y cached=Z] 前綴，並匯總進母 session 的用量。Timeout 為 MaxSubagentTimeoutMin（30 分鐘） |
互動
| 工具 | 說明 |
|---|---|
ask_user |
自由文字 / 單選 / 多選 / secret 遮蔽輸入；執行暫停並在新一輪帶完整 context 續跑。有 listener 時走 pending registry，否則回退到 stdin（CLI）或非互動指引 |
store_secret |
以遮蔽輸入取得值並直接寫入 keychain——該值不會進入 LLM context、歷史或日誌。schema 不接受 value 參數，agent 只看得到 name 與描述。每個 tool 每輪最多 2 次 |
write_todo |
使用者即時看得到的任務清單。每次呼叫都重送整份排序清單（狀態為取代而非合併）；恆保持剛好一項 in_progress |
install_dependence |
跨平台安裝缺少的系統 binary（僅 TUI/CLI）。已在 PATH 則跳過。沙箱阻擋 sudo，故此工具繞過沙箱。語言層套件（pip/npm/cargo/gem）→ 輸出指令由使用者自行執行 |
記憶
| 工具 | 說明 |
|---|---|
search_chat_history |
搜尋當前 session 的歷史訊息；mode=keyword 為精確比對，mode=semantic 為語意比對 |
remember_error |
將工具錯誤紀錄（resolved / failed / abandoned）寫入跨 session 記憶。Fire-and-forget |
search_error_history |
跨 session 搜尋錯誤記憶；結果具權威性——resolved 就照做、failed/abandoned 就避開 |
read_error |
以 hash 取回先前的錯誤紀錄（工具回傳 no data: {hash} 時使用） |
RAG
透過 KuraDB 子行程進行外部文件 RAG。當 ~/.config/kuradb/endpoint 不存在時，工具會逐輪動態排除——KuraDB 關閉時 LLM 根本看不到它們。
| 工具 | 說明 |
|---|---|
list_rag |
列出可用的 KuraDB 資料庫（如 notes、inbox、code）；已知資料庫名稱時跳過 |
search_rag |
透過 KuraDB 統一的 /api/search 搜尋（預設關鍵字 + 語意同時進行）；mode=keyword 用於精確字串，mode=semantic 用於自然語言查詢。上限 15 秒 |
當 search_rag 載入時，system prompt 會強制任何資訊查詢的第一波工具呼叫為 list_rag + search_rag。外部網頁 / 搜尋工具轉為次要（補缺），而非備援或替代。
Channel
跨 session 推播工具。每個工具同時檢查 telegram_enabled / discord_enabled 設定旗標與 keychain 憑證是否存在。平台格式規則已內嵌於 channel system prompt，不再透過工具取得。
| 工具 | 說明 |
|---|---|
list_chatbot |
列出指定平台的已授權聊天（platform=telegram 或 platform=discord） |
send_to_chatbot |
依 target_id 發送格式化訊息到已授權聊天。Telegram：HTML + 短暫 client。Discord：markdown + 短暫 client |
輸出標記（channel 專屬行為）
任何工具或 LLM 回應的輸出文字都會後處理以下標記：
| 標記 | 行為 |
|---|---|
[SEND_FILE:<path>] |
Channel runtime 自動附加檔案（Telegram → 依副檔名分流 photo/document，Discord → 統一 SendFiles 每則 10 個批次） |
[SEND_VOICE:<text>] |
僅限 Telegram。透過 Gemini TTS 合成並以 OGG 語音發送。上傳以 async 觸發（go func 搭配 context.WithoutCancel），回覆文字立即返回。失敗 → slog.Error + 聊天通知（不靜默） |
標記 regex + 去重 + os.Stat 過濾位於 internal/utils/utils.go；語音標記 regex 位於 internal/runtime/chatbot/chatbot.go。
探索與推理規則
| 工具 | 說明 |
|---|---|
search_tools |
以關鍵字（或 select:<name> 精確啟用）搜尋 tool registry，並注入對應 schema |
list_tools |
以名稱 + 一行描述列出已註冊工具（唯讀，不注入 schema）；mcp=true 只顯示 MCP 對外工具 |
run_skill |
將指定 skill 的參考資料載入當前回合；結果為建議性質 |
reasoning_guide |
依 topic 取得完整規則集——tool_generate、tool_error、rag_web、market_analysis、targeted_read、ask_user、subagent_dispatch、write_todo、html_render。取代先前各自獨立的 guide 工具 |
Skill 與 tool 變體（always-allow 的 write_file 變體）
| 工具 | 說明 |
|---|---|
write_skill |
建立或完整改寫 ~/.config/agenvoy/skills/ 底下的檔案 |
patch_skill |
對 skill 檔案進行精確字串替換 |
remove_skill |
將 skill 目錄移至 .Trash/（可透過 restore_revision 復原） |
write_tool |
寫入 tool 檔案——tag=json|script 寫入 script tool 目錄，tag=api 寫入 API tool 目錄的單一 JSON |
patch_tool |
對 tool 檔案（tool.json、script.py 或 API tool JSON）進行精確字串替換 |
test_tool |
在沙箱內以 JSON 輸入執行 script tool 的 script.py——write_tool / patch_tool 後的驗證步驟 |
remove_tool |
將 script tool 目錄移至 .Trash/ |
所有變體皆為 always-allow 且限縮在各自目錄。每次 write/patch/remove 都會自動 commit 到對應的 git repo（skills 或 tools）。
版本紀錄
範圍僅限 Agenvoy 自身位於 ~/.config/agenvoy 的儲存——永不涉及使用者的專案 repo。
| 工具 | 說明 |
|---|---|
list_revisions |
列出 skill 或 tool 儲存的修訂歷史；用於找出目標修訂或確認 auto-commit 有落地 |
restore_revision |
將 skill 或 tool 儲存硬重設到較早的修訂；請先跑 list_revisions |
系統
| 工具 | 說明 |
|---|---|
run_command |
以 argv 執行 binary（argv-only schema，經 go-pkg/sandbox 包裝）；['cd', '<path>'] 為特例，驗證路徑後直接更動 Executor.WorkDir。Shell 功能需明確使用 ['sh','-c','...']，其腳本會被逐一解析驗證——每個 binary 必須是 allowlist 上的裸指令名，rm 與動態指令一律拒絕。位於唯讀指令清單者（git status、ls、cat、pwd …）跳過 confirm gate |
排程
| 工具 | 說明 |
|---|---|
add_schedule |
將既有 scheduler skill 綁定到一次性觸發時間（target=task）或 5 欄位 cron 運算式（target=cron）。時間格式：+5m（相對）、HH:MM（今天）、YYYY-MM-DD HH:MM 或 RFC3339。屬 scheduler-skill-creator 流程內部使用——手寫的 skill_name 一定失敗，因為每個 scheduler skill 都帶生成的 hash 後綴 |
patch_schedule |
依 skill_name 與 target 重新排程；只改時間 / 運算式，不動綁定的 SKILL 內容 |
remove_schedule |
依 skill_name 與 target 取消；綁定的 scheduler skill 目錄移至 .Trash/ |
list_schedule |
列出當前 session 的 task 與 / 或 cron。target 接受 task、cron 或 all（預設） |
scheduler-skill-creator 是建立 scheduler skill 內容並呼叫 add_schedule 綁定的高階 skill。新的週期性 / 一次性需求應啟動該 skill，而非直接呼叫低階工具。
Daemon 端 runtime 以 fsnotify 監看 ~/.config/agenvoy/{tasks,crons}.json，於 Write / Create / Rename 熱重載。啟動或重載時自動觸發並移除逾期 task；觸發經 runtime.SetRunner → 對 scheduler skill 內容啟動 in-process subagent（always-allow context）。
TUI 提供 /cron、/task（add / remove / edit）與 /sched-<name>（手動觸發既有 scheduler skill 內容）來管理排程。