第十八节 子任务与后台执行
[!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 |