第十五節 子任務與背景執行

復雜任務往往需要把工作拆給"子助手"。AVL Code 內置子任務調度能力，支持前景同步與後台並行兩種模式。

15.1 派發子任務

助手在對話中可以呼叫一個「子助手」工具，把一段提示詞派給獨立的子任務執行，子任務完成後把結果合並回主對話流。這一過程對你是透明的，但你可以在工具呼叫卡片裡看到每個子任務的詳情。

15.1.1 子 Agent 繼承外部 MCP 工具

派出去的子 Agent 自動繼承你在工作區配好的外部 MCP 工具（之前子任務用不到這些外接工具，得回到主對話才行）：

• 機制：派發時經 /admin/routes + /admin/backends 解析本工作區所有外部後端的工具前綴（如 notion / memory / channels 等命名空間），通過環境變數 ZAGENT_MCP_INHERIT_PREFIXES 注入；子 Agent 的 ZAGENT_ALLOWED_TOOLS 白名單無條件穿透這些前綴。
• 覆蓋範圍：所有聲明了 tools: 的子代理（plan / assess / prepare / mcp-admin 與使用者自建）；所有工作模式統一（含 plan）。
• fail-safe：解析失敗 → 返空 → 不繼承，不影響子任務正常派發。

15.1.2 子任務模型 / 供應商匹配修正

之前在多供應商配置下，派出去的子任務沿用父工作階段的模型，但供應商恆取列表裡的第一個，兩者對不上時會報「模型不存在」起不來。本版改為供應商跟着繼承的模型走 — 優先選真正包含該模型的那個供應商，子任務能穩定啟動。

15.1.3 並行 fan-out：一次拆多路同時跑

除了一次派一個子任務，AI 還能用 AgentParallel 工具把一個任務一次拆成 2–16 條「腿」同時跑，每條腿是獨立的 fresh-context 子 Agent、互不可見，全部完成後自動匯總結果傳回。適合需要多路並行的活（如同時審好幾個模組、並行檢索多個來源），比一個個排隊串行快很多。

• 每條腿各自帶提示詞、可單獨指定子代理類型與模型；提示詞需自包含（腿看不到主對話歷史）。
• 並行上限 16 條（遠低於背景任務總並行 64，單次 fan-out 不會霸占全部槽位）；不足 2 條請改用單個 Agent。
• 整體等待超時預設 600 秒、上限 1800 秒；到時未完成的腿傳回 pending 並在後台繼續，可用 TaskWait / TaskOutput 續跟。
• 單條腿失敗 / 被攔不會拖垮整批，失敗原因會一並隨結果傳回讓 AI 自行處置。每條腿輸出過長會截斷（提示用 TaskOutput 取全文）。
• 執行期就能看到實時狀態：並行子任務的呼叫卡片在執行期間即出現（不必等終態才冒出來），並實時反映各子任務的執行狀態；停止後不再持續轉圈，極簡密度下結果塊也不會被誤折疊。

15.2 前景 vs 後台

• 前景：主助手等待子任務完成（預設 10 分鐘超時），適合"必須等結果"的任務。
• 後台：子任務非同步執行，主助手立刻得到一個任務編號，後續可主動拉取狀態或停止該任務。背景任務有總數上限（防失控）和自動回收（終態超時清理）。

15.2.1 「空閒制」看門狗 + 絕對兜底

子任務超時改成「按空閒計時」：只要還在持續產出就不算超時，看門狗只針對真的卡住、長時間無任何輸出的情形。再疊加一道絕對兜底（預設 60 分鐘），防止極端死循環 / hang 把任務永遠留在跑的狀態。

• 空閒視窗：預設 15 分鐘無輸出 即超時（錯誤訊息會明確寫「子 Agent 空閒超時」）。
• 絕對上限：預設 60 分鐘 強制結束（寫「絕對兜底」）。
• 正常長任務不受影響：只要還在 stream 產出（包括思考段、增量字元）就一直續命。
• RunAgentToolBackground 後台路徑不計執行超時（你顯式把它放後台跑就接受它跑久）。

15.3 並行上限

為防止一次發起過多背景任務造成失控，AVL Code 會限制同時在跑的子任務數；超出後助手會被告知"先稍等再發起"，避免雪崩。

15.3.1 阻塞等待 — TaskWait 工具

主助手可以「一次呼叫、阻塞等待」背景任務 / 子代理跑完，不用再一輪一輪反復查詢進度：

• 支持等「全部完成」或「任一完成」。
• 可設超時（預設 5 分鐘、最長 30 分鐘）；到點會如實傳回「還在跑」讓模型決定是否繼續等。
• 等待期間只回狀態與最終結果，不把中間過程灌回主對話，省上下文也更省 token。

15.4 終止

• 在桌面端，點擊輸入框右側 停止 按鈕會同步終止主助手與所有派生子任務。
• 在微信側，發送 /stop 同樣會觸發級聯終止。
• 子任務也能單獨停止：子代理抽屜裡每個正在跑的子任務都有獨立的停止按鈕，不必整輪一起停（對後台 / 並行 fan-out 的腿尤其方便；同步內聯的子代理需停整輪）。

15.4.1 真實總消耗看得清（含子代理）

用量統計會把子代理（並行 / 子任務）的真實消耗也算進來：目標條（GoalStrip）與每輪結束的識別都顯示真實總 token 消耗 + 工具呼叫次數，有子代理時還會拆出「自身 + 子代理」的構成。該統計按工作階段持久化，長工作階段看到的是全程真實總量（即使沒設目標也照常累計）。

15.5 輸出聚合

背景任務的中間記錄檔可作為獨立卡片在主對話流裡展開檢視；任務完成後會以一段精簡摘要傳回，避免淹沒主線索。

15.5.1 AI 建議任務：一鍵拆分去做

AI 幹活時如果順手發現了分外但值得做的事（死程式碼、過期文件、確認存在的 TODO、安全隱患等），會在訊息流裡掛出一張「建議任務」卡片，而不是打斷當前正事。

卡片上的執行按鈕是個 split button：

• 主按鈕一鍵：預設「啟用新工作階段執行」。
• 展開 ▾ 還有 4 種方式：
  • 在新工作階段中執行（主按鈕預設）
  • 在當前工作階段中執行
  • 複製到輸入框
  • 複製到剪貼板

由你來決定怎麼處置。已執行的建議會標記狀態，AI 也可以撤回已經過時的建議。多條建議會聚合到輸入框上方的一個條裡統一管理。

15.6 例行程式：讓 AI 按計畫自動幹活

「例行程式（Routine）」讓你給某個工作區定一條指令，讓 AI 按時自動或按需手動執行 — 比如每天早上拉取並總結昨日 issue。

新增入口：

• 工作區側邊欄「新增例行程式」一鍵開啟對話框（也支持從 Header 當前工作區進）。
• 表單欄位：名稱、指令內容、執行模式、模型（與正常對話同款選擇器：模式色卡說明、模型搜尋分組）、計畫時刻。
• 寫到一半自動暫存 — 中途跳去設置或 Agent 管理器調配置，回來自動重開並復原已填內容。

計畫方式：

時刻選擇順手：

• 時 / 分雙列下拉（選中置中、選完分鐘自動收起）；每小時一次模式下只露分鐘列
• 週幾用圓形單字字塊，附「工作日 / 週末」一鍵預設
• 調度精度：30 秒 tick；hourly 跨日 / DST 用時間算術天然正確

統一管理：

設置 → 例行程式 Tab 按來源工作區分組：

• 啟停開關（與其它設置頁同款）
• 立即執行
• 檢視最近執行痕跡
• 未開啟的工作區有徽標提示並可一鍵開啟
• 側邊欄圖示直達本工作區的例行程式列表
• 支持按名稱 / 工作區搜尋

執行行為：

• 每次執行會在對應工作區生成正常工作階段，過程與結果都可回看。
• 同一條例行程式執行中會自動跳過下一次觸發，不會疊跑。

15.7 長程任務當機後可復原

放到後台跑的長任務（即以 run_in_background 派發的子任務），其進度會實時落盤儲存；應用意外結束 / 被殺 / 當機 / 升級打斷後重新開啟，能把沒正常結束的任務找回來接着乾，不必從頭再來。

它怎麼工作：

• 每個未結束的背景任務都以一份快照寫到本機（跨工作區的全域目錄）；任務正常走到 done / error / killed 終態時會刪除該快照。所以重開後還留在盤上的，就是上次被中斷、沒跑完的任務。
• 啟動時會非同步掃描這些殘留任務，先做一次「髒條目清理」——父工作階段已不存在、再也無法復原的條目自動刪掉；掃描不阻塞啟動，沒有殘留就靜默無感。
• 復原並不是直接重新啟動子程序，而是往原來的父工作階段裡注入一句「之前委派的背景任務尚未完成，請繼續或重新委派」，讓主助手以「先派發」的方式接着完成——這一步對你可見，你能看到「正在復原任務 X」。

你會看到什麼（復原橫幅）：

• 有被中斷的任務時，頂部出現一條復原橫幅，標題形如「N 個背景任務上次被中斷」；沒有就不顯示。
• 每條任務旁有兩個按鈕：復原（，注入續跑訊息並從盤上移除該條）/ 忽略（從盤上刪除，下次不再提示）。右上角還有「全部忽略」。
• 復原成功後彈 toast「已復原:將在原工作階段繼續該任務」；失敗則提示具體原因（如「原工作階段已不存在,已清除該復原項」）。

自動復原（可選，預設關）：

• 在 設置 → 智慧體 → 自省 開啟「自動復原被中斷的任務」開關，重新啟動後會自動接着跑上次當機 / 被殺時未完成的背景任務，適合夜間無人值守的長任務。
• 為防「續跑訊息風暴」，啟動自動復原每次最多 5 個，其餘仍留在頂部橫幅供手動復原。
• 關閉該開關時（預設），所有被中斷的任務都只在頂部列出，由你手動決定復原或忽略。