多Agent协作
实战课
🦞 龙虾学校 · L3 进阶 — 白虎·织流 驱动
从同步调用100%失败，到异步协作34秒完成。通过四象飞轮→ 已演化为五行飞轮分析，掌握多Agent协作的核心架构模式。不是理论课——每一行代码都来自真实生产环境。
在 Windows 上让 OpenClaw Agent（Lucas）调用 Hermes（本地代码生成器），看似简单的"帮我写个文件"，实际触发了四层叠加故障。
✗ 同步调用 — 死亡螺旋
| 问题层 | 现象 | 结果 |
|---|---|---|
| L1 超时 | OpenClaw exec 90s 上限 | SIGKILL |
| L2 stdout | Windows PTY 捕获全空 | 黑洞 |
| L3 Shell | PowerShell 展开 $变量 | 参数损坏 |
| L4 循环 | Hermes 重试验证4次 | 时间耗尽 |
| 综合成功率 | 0% | |
✓ 异步架构 — 收敛结果
| 维度 | 方案 | 结果 |
|---|---|---|
| 超时 | 无父进程，独立运行 | 消除 |
| stdout | Write-Only，只写文件 | 绕过 |
| Shell | Python subprocess 直传 | 消除 |
| 循环 | max-turns 15 限制 | 控制 |
| 综合成功率 | 100% | |
四个飞轮独立分析，收敛到同一个答案——这不是巧合，是架构必然性。
青龙 · 源流
Hermes 是写手，不是执行者。能力分离——只调用已验证的能力。
朱雀 · 势流
同步调用是瓶颈。异步解耦——文件队列替代父子进程。
白虎 · 织流
文件系统是唯一可靠通道。File-as-API——最简接口最稳定。
玄武 · 信流
只信任已验证能力。原子任务——一个任务只做一件事。
🎯 收敛点
用最简单的接口连接
异步执行
只路由到可信能力
四个飞轮，同一个答案。这就是架构的确定性。
从零搭建 OpenClaw × Hermes 双 Agent 协作系统。每课30-45分钟，包含理论讲解 + 动手实操。
认识你的搭档：Hermes 安装与配置
在 Windows 上安装 Hermes v0.10.0，配置百炼/MiniMax 双通道 API，理解 Hermes 的能力边界。
- Git clone + pip install -e . 安装
- 百炼 provider=alibaba 正确配置
- MiniMax anthropic-messages API 格式
- terminal_tool Windows 适配修复
为什么同步调用必定失败
亲手复现 SIGKILL、stdout 黑洞、PowerShell 变量展开三大致命问题。理解问题才能设计方案。
- exec 工具 90s 超时实验
- Windows PTY stdout 捕获验证
- PowerShell $变量 展开陷阱
- Hermes 验证死循环观察
四象飞轮分析法
用四象引擎（青龙/朱雀/白虎/玄武）分析问题。学会从四个维度独立推导，验证架构收敛性。
- Seed 视角：能力分离原则
- Task 视角：同步→异步解耦
- Link 视角：File-as-API 设计
- Auth 视角：信任路由机制
Agent Bridge：文件系统消息协议
搭建 bridge.py — 基于文件系统的 Agent 间通信协议。JSON 任务文件 + 目录轮询 + 状态追踪。
- bridge.py 消息协议实现
- send_task / pick_task / mark_done
- lucas-to-hermes / hermes-to-lucas Ŀ¼
- CLI 接口设计
Hermes Worker：异步任务守护进程
构建 hermes_worker.py — 独立守护进程，轮询任务目录，Write-Only Prompt 设计，subprocess 直传参数。
- hermes_worker.py 守护进程架构
- Write-Only Prompt 设计模式
- subprocess.run 直传（绕过 Shell）
- -Q --max-turns 15 --yolo 参数
端到端验证 + 生产部署
完整流程测试：派发任务 → Hermes 生成代码 → 收取结果 → 验证输出。部署为 Windows 服务。
- format_lux.py 代码生成任务
- health_probe.py 健康检查任务
- trust-dashboard.html 页面生成
- 计划任务自启 + 错误恢复
最终收敛架构：两个 Agent + 文件系统 = 异步协作。
数据流
Write-Only Prompt
Hermes 只用 write_file 工具。不读终端输出、不执行命令、不验证结果。消除 stdout 黑洞。
File-as-API
JSON 文件 = 消息。目录 = 队列。文件名 = 消息 ID。无需 HTTP、无需 Socket、零依赖。
原子任务
一个任务 = 一个文件 = 一次调用。成功写 result.json，失败写 error。无中间状态。
核心代码
subprocess.run(
['hermes', 'chat', '-q', prompt_text,
'-Q', '--max-turns', '15', '--yolo'],
timeout=300, cwd=work_dir
)
{
"id": "1777037089_11affe2b",
"from": "lucas",
"task": "Write format_lux.py ...",
"output_files": ["utils/format_lux.py"],
"constraints": ["write_file ONLY"]
}
这些都是真实生产环境中遇到的问题。每个坑都有人花了几个小时才爬出来。
🔴 同步 SIGKILL
OpenClaw exec 工具 90s 超时（后台 180s），Hermes 启动 15-30s + LLM 思考 + 工具调用，几乎必超时。
🔴 stdout 黑洞
Windows PTY stdout 捕获完全失效。Hermes terminal_tool 运行命令成功但输出永远为空。进入验证死循环。
🟡 PowerShell $变量展开
PowerShell 会展开 prompt 中的 $p、$result 等变量名，导致 Hermes 收到损坏的 prompt。
🟡 Provider 配置陷阱
百炼用 provider=alibaba（不是 openai）。MiniMax 端点是 api.minimaxi.com（多一个 i）。coding.aiapi.top 代理已失效。
🟠 NSSM 服务死锁
NSSM 在 Windows Server 上创建的服务卡在 SERVICE_PAUSED 状态，无法启动/停止/删除。
🟠 GBK 编码地狱
PowerShell 默认 GBK 编码。Hermes config show 因 Unicode 特殊字符（⚕）崩溃。中文路径/文件名全面受影响。
真实数据，不是模拟。每一项都在生产环境中验证。
✗ 修复前
| 指标 | 数值 |
|---|---|
| 成功率 | 0% |
| 平均耗时 | 60-120s（然后被杀） |
| 文件产出 | 0 个 |
| 可用能力 | write_file + terminal（不可用） |
✓ 修复后
| 指标 | 数值 |
|---|---|
| 成功率 | 100% |
| 平均耗时 | 34.3s |
| 文件产出 | 完整模块 + JSON 报告 |
| 可用能力 | write_file ONLY（设计如此） |