第22篇：子代理委派——AI 的分身术

第22篇：子代理委派——AI 的分身术

你有没有遇到过这种情况：手头有一堆活儿，但自己只有一双手？Hermes 的 delegate_task 工具就是你的“分身术”——它能召唤出多个 AI 小助手，各干各的，互不干扰，最后把结果汇总给你。

第1步：理解子代理的核心逻辑

子代理就像你临时雇的实习生：它对你的过往对话一无所知，你给它什么资料（goal 和 context），它就基于这些干活。干完后，它只把一份“工作总结”交给你，不会把中间过程全塞进你的脑子里。

⚠️ 关键提醒：子代理是“失忆”的。你必须在调用时把所有背景信息写清楚，否则它只能瞎猜。

# 错误示范：子代理根本不知道“那个错误”是什么
delegate_task(goal="修复那个错误")

# 正确示范：把背景、路径、错误信息全交代清楚
delegate_task(
    goal="修复 api/handlers.py 里的 TypeError",
    context="文件在第47行报错：'NoneType' object has no attribute 'get'。函数 process_request() 依赖 parse_body() 的返回值，但后者在缺少 Content-Type 时返回 None。项目路径 /home/user/myproject，Python 3.11。"
)

第2步：单任务委派

最基础用法——把一件事交给一个子代理：

delegate_task(
    goal="调试测试失败的原因",
    context="错误信息：test_foo.py 第42行断言失败"
)

第3步：并行批量委派

同时派多个子代理干活，默认最多10个（可配置，无硬上限）。它们并行执行，最后汇总成一个结果：

delegate_task(tasks=[
    {"goal": "研究主题A", "context": "重点看近期一手资料"},
    {"goal": "研究主题B", "context": "比较主流解释"},
    {"goal": "修复构建", "context": "项目根目录：/home/user/project"}
])

第4步：结构化输出（output_schema）

每个任务可以带一个可选的 output_schema，它是一个 JSON Schema 对象，子代理的最终答案必须通过它的校验。子代理一开始就会看到这个 schema，把它当作输出契约（提示它“只返回 JSON 值，别写解释、别加代码围栏”）；答案返回后由父代理校验，如果没通过，会再给子代理一次有界的纠正机会，并把校验错误原样带上（不会重新粘贴 schema）。任务结果里会多出 schema_valid（true/false），失败时还会有 schema_errors。

就算纠正后还是没对上，子代理的活儿也不会白干：结果依然是 status: completed，原始文本放在 summary 里，同时带上 schema_valid: false、schema_errors 和一条 schema_note 说明这段文本未经校验。父代理直接从原始文本里挑需要的东西就行，不用把一个可能跑了一小时的任务重跑一遍。另外，只要 JSON 本身合法（对象或数组），外面包一层说明文字或代码围栏也能被校验器接受。

delegate_task(
    tasks=[{
        "goal": "Check which of these three endpoints return 200",
        "context": "https://a.example, https://b.example, https://c.example",
        "output_schema": {
            "type": "object",
            "properties": {
                "healthy": {"type": "array", "items": {"type": "string"}},
                "failing": {"type": "array", "items": {"type": "string"}}
            },
            "required": ["healthy", "failing"]
        }
    }]
)

写 schema 时尽量宽松：只要求你真正会读取的字段。没有 output_schema 的任务不受影响。

第5步：给子代理传图片

有些活儿光靠文字说不清——比如用户发来的截图、设计稿、渲染出来的图表。这时可以给任务加一个可选的 images 列表（最多 8 个，支持本地路径、http(s) 链接或 data:image/... 链接）：

delegate_task(tasks=[{
    "goal": "Compare the rendered dashboard against the design mock and list layout deviations",
    "context": "The app runs at http://localhost:3000; the repo is at /home/user/dash.",
    "images": ["/home/user/mocks/dashboard-v2.png",
               "https://cdn.example.com/current-render.png"],
}])

图片怎么送进去，跟用户自己贴图走的是同一套逻辑（agent.image_input_mode）：

子代理模型支持视觉——图片会作为原生多模态内容出现在子代理的第一轮里：本地文件转成 data URL（和其他文件读取一样受读取守卫约束），远程和 data: 链接原样透传。子代理看到的是真正的像素。
子代理模型不支持视觉——goal 里会多出 [Image attached at: <path>] 提示行，并告诉子代理用 vision_analyze 去看。

传图是尽力而为：读不了的路径会跳过并记一条日志，图片环节出任何问题都会退回纯文本 goal，绝不会把 spawn 搞挂。图片是给子代理“看”的，纯文本文件路径还是照常放 context 里。

第6步：典型应用场景

并行调研：同时查三个技术方向，省时省力。

代码审查+修复：让子代理在全新环境里审查并修复安全漏洞，不污染你的对话上下文。

大规模重构：比如把整个 src/ 目录里的 print() 替换成 logging，这种琐碎又占上下文的活儿，交给子代理再合适不过。

第7步：批量模式细节

当你传 tasks 数组时，Hermes 会返回一个后台句柄，所有子代理跑完后，统一发回一份合并结果。如果父代理本身是“编排者”，它会等自己的子代理全部完成，再综合结果返回。

另外，后台终端进程归属于启动它的那个代理：子代理在委派结束时被关闭，它剩下的进程（包括更早轮次里启动的）也会被终止，但不会影响父代理或兄弟代理的进程。共享同一个终端环境并不等于转移进程所有权。所以子代理在返回最终总结前，应该先等自己的构建、测试等有界后台命令跑完；如果某个 CI 监听或服务器需要在子代理结束后继续运行，请在父会话里启动它——返回一个进程 ID 并不会把所有权交给父代理。

取消操作：普通的后续消息不会取消后台子代理。/stop（网关 /stop、CLI /stop、桌面/TUI 的 Stop 按钮、ACP cancel）或关闭/重置所属会话，会终止该会话正在跑的后台委派；被停掉的子代理仍会返回一条结构化结果（status="interrupted"），summary 里是它最后输出的文本。

卡死的子代理：如果子代理彻底不动了，心跳陈旧监控会盯着它的进度信号（API 调用、工具启动、活动时间戳）。超过阈值（轮次间空闲 450 秒，或在工具里卡住 1200 秒）就会被中断，父代理收到一条 status: "timeout" 的结果。这样即使在一次性运行（hermes chat -Q、Bot Chat 一次性、cron）里，卡住的子代理也不会永远占着这一轮。注意，正在等模型返回也算“有进度”，所以慢速本地模型或长 prefill 不会被误判为卡死。

一次性运行的额外限制：hermes chat -q / --oneshot 会话总共最多只能生成 delegation.oneshot_max_children 个子代理（默认 2，0 表示不限）。因为一次性运行没有后续轮次来接收结果，而且基准测试里这类 spawn 大多是“独立复查我自己的工作”，每个子代理都要重新付一次冷启动系统提示、重新读一遍仓库。交互式和网关会话不受影响。

总结：子代理委派 = 上下文隔离 + 并行执行 + 结果汇总。用好它，你就能同时推进多个任务，而不会被海量中间信息淹没。

下一篇预告：第23篇将介绍“工具调用进阶——如何自定义 Hermes 的工具”，敬请期待！