第十八節 子任務與背景執行
[!ref] 詳解見使用者手冊「子任務與背景執行」節。
18.1 派發參數
| 參數 | 類型 | 預設 | 說明 |
|---|---|---|---|
prompt |
string | — | 子任務提示詞；必填 |
agent_id |
string | 當前助手 | 指派子助手人設 |
model |
string | 當前模型 | 子任務模型 |
run_in_background |
bool | false | true 走後台 |
timeout_ms |
int | 600_000 | 前景超時；後台不適用 |
18.2 BackgroundRegistry
| 欄位 | 預設 | 說明 |
|---|---|---|
| 同時在跑上限 | 64 | 超出立即拒絕並提示稍後重試 |
| 終態保留 | 30 分鐘 | 超過視窗被回收 |
| 優先級 | killed > done | 外部 stop 與自然結束撞拍時 killed 勝 |
18.3 子任務工具
| 工具 | 參數 | 說明 |
|---|---|---|
Agent |
prompt, agent_id, run_in_background? |
派發單個子任務 |
AgentParallel |
legs[]（2–16）, timeout_seconds? |
一次拆多路並行 fan-out（見 §18.3.1） |
TaskOutput |
task_id, limit? |
拉取背景任務狀態 / 輸出片段 |
TaskStop |
task_id |
強制終止背景任務 |
StopAgentToolRun |
child_session_id |
單獨停止某個正在跑的子代理（後台 / 並行腿）；冪等，同步內聯子代理需停整輪 |
TaskWait |
task_ids, mode=all|any, timeout_seconds（預設 300，最長 1800） |
阻塞等待背景任務 / 子代理；超時傳回「還在跑」讓模型決定繼續 |
EnterPlanMode / ExitPlanMode |
無 | 進入 / 結束籌劃 |
TodoWrite |
todos |
寫入或更新待辦列表 |
18.3.1 AgentParallel 參數
| 參數 | 類型 | 預設 | 說明 |
|---|---|---|---|
legs |
array | — | 必填，2–16 條；每條獨立 fresh-context 子 Agent，全部完成後聚合傳回 |
legs[].subagent_type |
string | — | 必填，目標子代理類型 |
legs[].prompt |
string | — | 必填，自包含子任務提示詞（腿看不到主對話歷史） |
legs[].description |
string | — | 可選，3–5 詞，僅用於記錄檔 / UI |
legs[].model |
string | 繼承 | 可選，單腿模型覆蓋 |
timeout_seconds |
int | 600 | 整體等待超時，上限 1800；到時未完成的腿傳回 pending 並在後台繼續 |
少於 2 條會報錯（改用 Agent），多於 16 條靜默截斷到前 16。每條腿作為真實背景任務派發、內部統一 Wait(all) 聚合；單腿輸出超 8000 runes 截斷（提示用 TaskOutput 取全文）。腿為葉子層、不可再嵌套 Agent / AgentParallel。v1 僅 all 模式。傳回 ParallelResult（completed / num_ok / num_failed / num_pending / legs[] 等，永不拋錯）。
渲染：呼叫卡片執行期即顯示並隨實時 store 反映各腿執行狀態（停止後不再轉圈）；極簡密度下結果塊不被工具組誤折疊。
18.4 長程任務當機復原
背景任務（run_in_background=true）的進度落盤到本機全域目錄（每任務一份 JSON 快照）；走到終態（done / error / killed）即刪除快照。
| 項 | 預設 | 說明 |
|---|---|---|
| 落盤範圍 | 僅背景任務 | 前景同步任務不落盤 |
| 啟動掃描 | 非同步、不阻塞 | 先做髒條目清理（父工作階段已刪的條目自動剔除），再列出殘留任務 |
| 自動復原開關 | 關（auto_resume_tasks） |
設置 → 智慧體 → 自省；啟用後啟動自動續跑（夜間無人值守） |
| 啟動自動復原上限 | 5 | 防「續跑訊息風暴」；其餘轉手動橫幅 |
| 復原方式 | 注入父工作階段續跑 | 不直接重新啟動子程序，而是向原父工作階段注入「繼續 / 重新委派」訊息（對使用者可見） |
| 手動入口 | 頂部復原橫幅 | 每條可「復原 / 忽略」，另有「全部忽略」 |
18.5 自修正循環參考
錯誤按來源（request / gateway / upstream）與類別分流後映射到 4 類修正政策，各有按工作階段計的嘗試上限：
| 修正政策 | 適用錯誤 | 上限 |
|---|---|---|
transient_compact（壓縮重試） |
上下文超限 | 2 |
transient_fallback（切換供應商，需確認） |
無可用通道 / 上游過載 / 上游認證失敗 | 3 |
backoff（退避重試） |
限流 / 超時 / 網路 | 3 |
terminal（交還使用者） |
餘額不足 / 需重登 / 模型不存在 | — |
特例：upstream 來源的 auth_error 重判為 transient_fallback（某通道 key 失效而非使用者憑證）；仍可重試的 terminal 救回為 backoff；5xx / 408 預設可重試，其它 4xx 終止。
- 網路抖動自愈：瞬斷 / 臨時離線時探測「離線 → 線上」再續跑，這段等待不計入重試預算；連線重設、DNS 暫時解析失敗、交握中斷等連線級瞬斷細分為網路問題（而非籠統
llm_error）。 - 產出型自愈（
MaxOutcomeHeal = 3）：回復被長度截斷自動續寫（truncated_continue）、推理繞圈打斷（reasoning_loop）、內容過濾換述（content_filter）。 - 門禁升級：同一處檢查 / 測試失敗或待辦無進展達上限（測試門禁 3 次、無進展待辦 2 次）時升級提示換思路。
- 供應商備選經
App.RespondProviderFallback回寫確認，前端SelfRepairFallbackBanner；後端事件self_repair:fallback_confirm/_applied/_declined/self_repair:outcome。
18.6 經驗學習閉環參考
| 組成 | 說明 |
|---|---|
| 自愈歷史學習（P1） | 每類自愈成敗落盤 ~/.config/avlcode/self-heal-stats.json；平滑率 (succ+1)/(total+2)。樣本 < 5 用預設上限 3；率 < 0.2 → 1、0.2–0.5 → 2、≥ 0.5 → 3；每類至少 1，僅下調不上調 |
| 自動反省（P2/P3） | auto_reflect（預設關，設置 → 智慧體 → 自省）啟用後，多步任務收尾非同步跑一次 GRAI+KISS 復盤；讀軌跡摘要（最多 5 個錯誤步）+ 自愈統計，產出 ≤ 8 條 Keep/Improve/Stop/Start 教訓 |
| 教訓去向 | 沉澱到記憶宮殿 _pending 草稿盒（房間 scratch、類型 decision、不衰減），需人工簽核後才入正式函式庫；按標題去重；事件 reflection:done |