協作工具
最後更新
subagent、排程、清單、向使用者提問與最終結果的工具。
| 工具 | 說明 |
|---|---|
subagents | mode=invoke 在獨立 session 中執行子任務（in-process，不走 HTTP）；mode=list 回傳可重用的具名 session 與其角色。任務描述必須自我完備 —— 子任務看不到母對話的任何內容。前景 leg 同時最多 min(MAX_CONCURRENT_TOOLS, MAX_CONCURRENT_SUBAGENTS) 條 —— v1.3.0 起為 CPU 核心數的一半、至少 3（之前固定為 3）—— 超出的會在自己的 timeout 計時中排隊，因此大規模 fan-out 以此數量為一批派送。結果帶有 [subagent · <model> · session=<id> · usage: in=X out=Y cached=Z write=W] 標頭，並累計進母 session 的用量。自 v1.0.22 起 leg 的報告內文不再直接回傳：它會寫入 ~/.config/agenvoy/download/temp-<report_name>.md，結果只含上述標頭與檔案路徑，呼叫端須先以 read_files 讀取再轉述或彙整。report_name 為簡短 kebab-case 名稱（工作 + 對象，例如 nvda-news）；名稱已存在時加上隨機後綴，空白則使用隨機名稱。self_id 用於原樣重用既有的非暫時 session，v0.35.0 起取代 name / session_id，且 mode=list 必須帶它 —— 現在是解析單一被指名的 agent，而非列出所有 session；自 v1.1.0 起每次 mode=invoke 都必須帶 model —— 空白 model 改由 dispatcher 代選的退路已移除，改為明確傳 model: "auto"（v1.1.0 後的 hotfix）交由 dispatcher 依任務挑選，與一般請求相同；self_id 解析到綁定自有模型的 session 時改用該模型，停在 auto 的 session 則使用傳入的模型。前景 leg 上限為 MAX_SUBAGENT_TIMEOUT_MIN（30 分鐘）。background 與 timeout_min 參數（v1.3.0 新增）已移除於 v1.3.2；請改用 background_subagents，工具描述會把幾乎確定超過 5 分鐘的 leg，或「take your time」「let me know when it's done」「run it in the background」這類請求導向該工具（v1.3.7 起觸發語只寫英文）。自 v1.0.21 起每條 leg 只有一個 job —— collect、analyze、compare、review、transform 或 code —— 並對應到一種工作類別；自 v1.1.0 起 leg 的 tier 順序比 dispatcher 低一階（collect → fetch C>B>A>S、transform → chat C>B>A>S、analyze / compare / review → work B>A>C>S、程式碼或高精度 → code A>B>C>S）。原本的 reason job 拆成 analyze、compare 與 code。model 會對照即時 registry 檢查，啟動後才新增的模型也能用；未註冊或 pass tier 的名稱會直接報錯並列出可用模型。reasoning 預設 auto（沿用 leg 所在 session 的設定，否則由 dispatcher 挑選）；不是合法推理等級的值會直接報錯。leg 只負責蒐集：一律拿不到 subagents、background_subagents、edit_file、remove_file、restore_file、edit_tool、test_tool、edit_skill、write_result、html_template、任何 generate_* 工具、open_file、schedules、store_secret 與 TUI 專屬工具（configs/jsons/tui_tools.json，v1.3.2 中其工具清單為空），程式碼以文字回傳由主 agent 套用；exclude_tools 在此之上追加。完整派送協定與模型 tier → reasoning_guide(topics=["subagent_dispatch"]) |
background_subagents | v1.3.2 新增。在背景啟動一條 leg 並立即回傳 task id，當輪繼續進行。參數沿用 subagents 的 mode=invoke（task 與 model 必填；report_name、self_id、reasoning、new、system_prompt、exclude_tools），另加 timeout_min（1-60，預設 60）取代 30 分鐘上限，v1.3.8 起另有 objective 與 next。同一回合開的 leg 組成一組（v1.3.8）。leg 完成時，發起的任務仍在執行或 pending 時，存好的報告路徑送進該任務；任務結束後，整組等所有 leg 完成，以 objective＋next＋所有報告另開新任務，可經 chat_history 讀取發起的任務。v1.3.8 之前每份報告各自接回原任務。背景 leg 從不觸發確認：需要確認的呼叫不會執行，leg 會被告知回報該呼叫仍待使用者核准；它也拿不到 ask_user。每條 leg 的進度（模型、工具呼叫與結果、文字、錯誤）寫入 ~/.config/agenvoy/sessions/<session>/background/<task id>.log，leg 結束即刪除。leg 佔用背景任務名額而非前景名額：每個 session 最多 MAX_BACKGROUND_TASKS 個（CPU 核心數的一半，至少 3），與 background_command 共用。工具描述只在 leg 幾乎確定超過 5 分鐘，或使用者提出「take your time」「let me know when it's done」「run it in the background」這類請求時才使用；使用者要在蒐集後進行的動作寫進 next，幾分鐘內就能完成的請求仍留在前景（v1.3.8）。同一組的 leg 都在同一回合派出。請求不是來自 TUI（cli- origin 且沒有 deliver target）時排除 |
schedules | 綁定 scheduler skill 的排程執行。mode=list 顯示本 session 已排入的項目、mode=patch 調整時間、mode=remove 取消並丟棄其 skill、mode=write 是 scheduler-skill-creator 流程的內部綁定步驟。target 為 task（單次）、cron（5 欄位表達式）或 all（僅 list 可用）。task 時間格式：+5m / +1h30m（相對）、15:04（僅限今天稍後，不會順延到明天）、2006-01-02 15:04（本地日期時間）或 RFC3339。skill_name 帶有生成的 hash 後綴 —— 手寫的名稱必定失敗 |
write_todo | 使用者即時觀看的任務清單。每次呼叫都重送整份有序清單（狀態是取代而非合併）；恰好一個步驟維持 in_progress。計畫執行期間步驟集合固定 —— 只推進狀態，不改寫、不重排。清單以 task hash 分開儲存，同一 session 的並行任務各自保有清單。最後一步完成且該任務尚未寫出 report-*.md 或 report-*.html 時，回傳結果會提示模型對長篇產出呼叫 write_result。自 v1.0.26 起帶有 Concurrent 旗標，會與同一輪的其他 fan-out 呼叫一起執行。回答需要超過一輪工具呼叫時就開清單，分析或研究類請求不論計畫多短也一律開；執行中的 Skill 若步驟需要超過一輪工具呼叫，會在第一步前依自身步驟開清單 —— 略去本次請求用不到的步驟；單輪完成的 Skill 不開清單（v1.1.1 的門檻為三個步驟） |
ask_user | 自由輸入 / 單選 / 複選 / 遮罩輸入的提問。每個問題可帶多行 detail 承載補充說明（v1.3.5 前名為 hint）。v1.3.8 起 Telegram 與 Discord 把問題、detail 與 question n/m（多題時才有）分行送出，網頁卡片顯示同樣的進度；工具呼叫行為 Ask(...)，內容為第一題 detail 的第一行（沒有則用 question），最多 128 字元。自 v1.0.23 起 TUI（cli- origin）直接就地提問：問題出現在原處，同一次執行拿到回答後繼續。自 v1.2.0 起由 daemon 執行 agent，問題經 Unix socket 只送到發起該次執行的 TUI 視窗。其他 origin（web、Telegram、Discord、API、排程）則存下 pending 快照 —— 工具結果每筆截至 32 KiB、參數截至 4 KiB（v1.1.2 前為 4 KiB / 1 KiB） —— 結束本次執行，待使用者回答後以完整脈絡於新 turn 恢復。此工具沒有 timeout。工具描述要求：作用中 Skill 的 SKILL.md 或工具可取得的資料已能回答時不再提問。憑證一律不從這裡問 → store_secret |