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

这篇讲的是：如何让 Hermes Agent 同时派出多个“分身”去干活，再把结果汇总给你——就像你同时雇了三个实习生，各干各的，最后交报告。

---

为什么要用“分身”？

想象一下：你让一个助手去查资料、改代码、做调研。如果它一件一件做，又慢又容易乱。子代理委派（Subagent Delegation）就是让主代理临时创建几个独立的“小代理”，每个小代理有全新的对话记忆，只专注于你交给它的那一件事。干完后，它只把最终结论汇报给主代理，中间过程完全不打扰你。

⚠️ 重要：分身什么都不知道！
小代理的脑子里是空的。它不知道你之前聊了什么，也不知道“那个错误”指的是什么。你必须在派活时，把所有背景信息写清楚。

（有个小例外：如果主代理已经确定了工作目录，那这个目录里的项目上下文文件——.hermes.md、AGENTS.md 那一串、CLAUDE.md、.cursorrules——会自动塞进分身的系统提示里。所以分身进到仓库里干活，能直接按仓库自己的规矩来，不用重新摸索一遍。）

---

第1步：派一个分身干单件事

最基础的用法，就是给一个目标（goal）和背景（context）：

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

注意：背景写得越详细，分身干得越好。下面这个例子就是“坏”和“好”的对比：

# ❌ 坏——分身不知道“那个错误”是什么
delegate_task(goal="修复那个错误")

# ✅ 好——所有信息都给全了
delegate_task(
    goal="修复 api/handlers.py 里的 TypeError",
    context="""文件 api/handlers.py 第47行报错：
    'NoneType' object has no attribute 'get'。
    函数 process_request() 从 parse_body() 拿数据，
    但 Content-Type 缺失时 parse_body() 返回 None。
    项目在 /home/user/myproject，用 Python 3.11。"""
)

---

第2步：一次派多个分身（并行批处理）

默认最多同时跑 10 个分身（可以改配置，没有硬性上限）。把任务放在一个列表里就行：

delegate_task(tasks=[
    {"goal": "调研主题A", "context": "重点关注近期原始资料"},
    {"goal": "调研主题B", "context": "比较主流解释"},
    {"goal": "修复构建失败", "context": "项目根目录：/home/user/project"}
])

Hermes 会并行跑这三个任务，全部完成后，把结果按你给的顺序汇总成一条消息发给你。

---

第3步：给分身换一个更便宜的模型

分身默认用和主代理一样的 AI 模型。如果你想省钱，可以让分身用便宜快速的模型：

# 在 ~/.hermes/config.yaml 里
delegation:
  model: "google/gemini-flash-2.0"   # 便宜模型
  provider: "openrouter"             # 可选：换供应商

---

第4步：控制分身的工作量

• 最大迭代次数：分身最多能调用多少次工具（默认50次）。简单任务可以调小：

delegate_task(
    goal="快速检查文件",
    context="检查 /etc/nginx/nginx.conf 是否存在，打印前10行",
    max_iterations=10   # 简单任务，10次够了
)

• 超时时间：默认没有硬性超时。以前有10分钟上限，结果深度代码审查这种活经常被掐断。现在只要分身还在干活（比如在等模型回复），就不算卡死。只有它完全没动静才会被判定为“卡住”——心跳监控会盯着每个分身的进度信号（API 调用、工具启动、活动时间戳），一旦彻底冻住（两轮之间闲置 450 秒，或者卡在某个工具里 1200 秒），就把它中断掉，父代理会收到一条 status: "timeout" 的结果。这样即使是一次性运行（比如 hermes chat -Q、Bot Chat 单次、cron）也不会被一个卡死的分身永远拖住。

---

第5步：用 output_schema 约束分身的输出格式

如果你希望分身返回的结果是固定结构（比如 JSON），可以给任务加一个 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": "检查这三个端点哪些返回 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 的任务不受影响。

---

第6步：给分身递图片

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

delegate_task(tasks=[{
    "goal": "对比渲染出的仪表盘和设计稿，列出布局偏差",
    "context": "应用跑在 http://localhost:3000；仓库在 /home/user/dash。",
    "images": ["/home/user/mocks/dashboard-v2.png",
               "https://cdn.example.com/current-render.png"],
}])

图片的走法和用户自己发的图一样（看 agent.image_input_mode 配置）：

• 分身模型支持视觉：图片会作为原生多模态内容出现在它的第一轮对话里，本地文件会转成 data URL（跟其他文件读取一样受读取守卫限制），远程和 data: 链接原样传过去。分身看到的是真正的像素。
• 分身模型不支持视觉：目标里会加上 [Image attached at: <path>] 这样的提示行，并告诉分身用 vision_analyze 去看。

图片转发是尽力而为的：读不了的路径会跳过并记一条日志，图片环节出任何问题都会退回纯文本目标——绝不会因此让分身创建失败。图片是给分身必须亲眼看的东西用的；普通的文本文件路径还是照常写在 context 里。

---

实用场景举例

并行调研：一次查三个话题（WebAssembly、RISC-V、量子计算），各写各的报告。

代码审查+修复：让分身在一个全新环境里审查登录模块的安全性，发现问题直接改，然后跑测试。

大范围重构：把“把所有 print() 改成 logging”这种会刷爆主代理记忆的活，丢给分身去干，它干完只汇报结果。

---

小总结

子代理委派就是把大任务拆成小任务，分给多个“失忆”但专注的分身。关键记住两点：背景信息给足、任务描述清楚。这样你就能同时干好几件事，效率翻倍。

下篇预告：分身们干活时，你还能继续和主代理聊天——下一篇讲讲后台任务与消息队列，看看 Hermes 是怎么做到“边聊边干”的。