看懂 LongHorizon-Harness 三大核心角色:Manager、Executor、Auditor 如何分工协作?
看懂 LongHorizon-Harness 三大核心角色:Manager、Executor、Auditor 如何分工协作?
LongHorizon-Harness 是一个面向 AI Agent 长时运行的开源执行框架,它把跨桌面应用和终端的复杂任务,拆成 Manager 负责计划、Executor 负责执行、Auditor 负责独立验证 的三角色协作循环:Plan → act → verify → checkpoint or recover → repeat,直到任务真正完成。这篇文章用新手友好的方式讲清三个角色各自管什么、怎么配合、以及为什么这样分工能显著提升长时任务的完成率。
为什么长时 AI Agent 任务需要"三角色分工"?
如果你用过 Claude Code、Codex 这类 Agent 直接跑长任务,大概率遇到过这些坑:
- 🌀 上下文越滚越长:几十轮对话后,模型开始"忘记"最初的目标,甚至跑偏;
- 🗣️ 自说自话:Agent 说"文件已保存",但实际没保存,自己还觉得自己成功了;
- 💥 失败后全盘作废:中途一报错,之前几十小时的进度全部丢掉,从头再来。
LongHorizon-Harness 的思路是"循环工程"(Loop Engineering):不训练新模型,而是围绕现有 Agent 设计执行、验证、纠正、恢复的闭环。它不替换你的 Agent,而是把任务管理、动手执行、结果审计拆给三个边界清晰的角色,每个角色只干一件事,干得可靠。
一轮循环里三角色如何协作:计划 → 执行 → 验证
整个系统每一轮(Round)都固定走三步:Manager 出一个有边界的子任务 → Executor 在全新上下文中执行 → Auditor 只读审计真实环境。下面这张官方架构图完整展示了三个角色的信息流和权限边界:
三个角色不是各自为政的三个 Agent,而是同一条循环里的实现边界——它们共享同一份"已验证的任务状态",谁也不能绕过审计去推进任务。
Manager:只管计划和调度,绝不动手
Manager(任务管理器)是循环的"大脑",但它从不接触真实环境:不能改文件、不能点鼠标、不能跑命令。它的输入是:
- 原始任务描述;
- 一份跨轮维护的"任务契约"(把用户请求落成可验证的目标状态);
- 上一轮的任务状态;
- 所有历史 Auditor 报告的原文(这是可信中间状态的唯一权威来源)。
每轮 Manager 的输出非常克制:维护"当前任务状态"、评估依赖关系,然后给出且仅给出一个路由决策:
| 路由 | 含义 |
|---|---|
Next: gui |
把当前最关键的子任务交给 GUI Executor(点击、输入、截图等视觉操作) |
Next: cli |
交给 CLI Executor(shell、代码、日志、数据等非视觉工作) |
Next: ask |
缺少必须由用户提供的信息,向人请示 |
Next: done |
仅当 Auditor 连续三行控制头为"完成 / 干净 / 对齐"时才允许 |
Next: blocked |
确实无法推进时如实上报 |
两条铁规矩值得新手记住:① 一轮只安排一个"主导状态变化",禁止把多个大目标塞给一个子任务;② Manager 引用的每条事实都必须标注来自哪一轮审计报告(如 round_003),Executor 未经验证的自述一律不采信。
相关实现见 src/lh_harness/role_prompts.py 中的 build_role_manager_prompt,角色指令文本在 src/lh_harness/prompt_texts.py。
Executor:每轮全新上下文,只干一个子任务
Executor 是循环里的"双手",分 GUI 和 CLI 两种变体,但共同点只有一个:每轮都从全新上下文(fresh context)启动,只完成 Manager 分派的那一个有明确边界和验收标准的子任务。
- GUI Executor:主目标必须是真实屏幕状态——观察、点击、输入、滚动、等待、视觉确认、保存真实屏幕截图;禁止用脚本绘图等手段伪造"GUI 证据";
- CLI Executor:主目标是 shell、文件、代码、测试、日志、服务诊断,允许小范围借用 Computer Use 做辅助观察,但视觉核心工作必须改派 GUI;
两个 Executor 都不能与真人对话——需要用户输入时,只能停下并报告 Manager 走 ask 通道。子任务完成后,Executor 报告自己实际做了什么、产物路径在哪、还有什么遗留问题,然后等待审计,而不是自我宣布成功。
三角色的执行循环由 src/lh_harness/manager.py 驱动,不同 Agent 后端(Claude Code / Codex / OpenCode / DeepSeek Harness)通过 src/lh_harness/adapters/ 下的适配器接入,各后端保留原生执行方式,harness 只负责角色边界和跨轮状态。
Auditor:只读独立验证,唯一可信状态的来源
Auditor(审计员)是循环里最关键的角色——它决定"什么算真的做完了"。它的纪律性极强:
- 🔒 严格只读:不点击、不输入、不修改任务文件;Computer Use 只能用于观察和截图。harness 还会在审计前后对工作区做快照比对,发现 Auditor 动了文件就恢复快照并标记违规(见 src/lh_harness/auditor_agent.py 中的只读违规处理);
- 📋 标准控制头:每份审计报告的前三行必须固定为
Status(完成/未完成/阻塞)、Integrity(干净/存疑/违规)、Contract audit(对齐/未知/需修订/无效),正文再给出审计事实、证据、缺口和给 Manager 的状态更新; - 🕵️ 独立取证:对照子任务直接检查真实文件内容、界面状态、日志、测试输出;对截图产物还会检查元数据,确认它来自真实屏幕而非脚本合成。
被拒绝的结果不会消失,而是降级为"证据"(evidence)——它只用来指导下一步修复,绝不计入进度。只有通过独立审计的结果,才能成为下一轮的可信任务状态。
三角色的协作闭环:验证状态 + 断点恢复
把三个角色串起来,就得到 LongHorizon-Harness 的完整闭环:
- Manager 基于"原始目标 + 已验证状态"规划本轮唯一子任务;
- Executor 在全新上下文中执行,输出产物和自述;
- Auditor 只读审计,产出权威报告;
- 审计通过 → 进度固化为检查点(checkpoint),进入下一轮;审计失败 → 失败证据连同产物交回 Manager,下一轮从"原始目标 + 最后一个已验证检查点"恢复。
这意味着即使上下文刷新、动作失败、甚至中途崩溃,任务也不会失控:下一轮永远基于原始目标和最后验证过的状态重新开始,而不是基于 Executor 的自述。每次运行的完整审计轨迹都保存在 ./.lh-harness/runs/<run-id>/ 下,包含任务状态、事件流、审计报告和各角色轨迹,进度可检查、可恢复、可复现。
如何配置三个角色使用不同模型和后端
三大角色的一大实用特性:每个角色都可以独立指定 Agent 后端和模型,用强模型做 Manager 和 Auditor,用高性价比模型做 Executor,兼顾质量、速度和成本。
在项目的 ./.lh-harness/config.toml 中通过 <a href="https://link.gitcode.com/i/9c56210cec853da4803d6f690b169316" target="_blank">run.roles.*] 分段配置(如 [run.roles.manager]、[run.roles.auditor]),解析链为 gui_executor → executor → [run] 的继承兜底;也可在命令行用 --gui-executor-model、--auditor-timeout 等参数单次覆盖。配置体系定义在 [src/lh_harness/config.py。
每个角色还配有独立的超时预算(Manager 默认 600 秒、Executor 1800 秒、Auditor 600 秒),某角色超时不会毁掉整轮——harness 保留部分轨迹和任务状态,让下一轮 Manager 检查真实工作区后恢复。配合 lh-harness web 启动的 Dashboard(src/lh_harness/webapi/server.py),你可以在浏览器里实时查看每轮的计划、执行结果、审计证据和返工原因,并在任务完成、阻塞、反复失败时人工介入。
实测提升:三角色协作带来多少收益
同样的模型、同样的执行后端,只把执行方式换成 Manager–Executor–Auditor 循环,在数百个真实复杂任务上测得:
| 基准 | 指标 | 普通 Agent | LongHorizon-Harness | 提升 |
|---|---|---|---|---|
| WeaveBench(114 个 GUI+CLI 混合任务) | PassRate | 51.8 | 80.7 | +28.9 |
| OSWorld 2.0(108 个桌面任务) | 二值完成率 | 2.8 | 8.3 | 3.0× |
| Terminal-Bench 2.1 | 成功率 | 69.7 | 77.2 | +7.5(token 还省 24%) |
复现套件在 eval/ 下按基准分目录存放(如 eval/WeaveBench-harness/、eval/OSWorldv2-harness/、eval/TB-harness/),完整数据表可参考 README.md。
快速上手:第一次跑起三角色协作
只需三步(详见 README.md):
uv tool install lh-harness # 1. 安装(要求 Python 3.10+ 与一个 Agent CLI)
lh-harness init # 2. 在项目目录生成 ./.lh-harness/config.toml
lh-harness run --task @task.md --dashboard # 3. 从文件启动任务并打开 Dashboard
运行过程中控制台会按角色逐轮打印进展;任务结束时,你会收到一份仅基于已验证状态写成的白话总结——没做完就直说没做完,绝不美化。
小结
| 角色 | 一句话定位 | 关键纪律 |
|---|---|---|
| 🧭 Manager | 状态机:维护任务契约,每轮调度一个子任务 | 不碰环境,事实必须引用审计报告 |
| ⚡ Executor | 行动者:全新上下文执行单个有边界的子任务 | 不自宣成功,需用户输入时停下上报 |
| 🔍 Auditor | 守门员:只读独立验证真实环境 | 严格只读,三行控制头给出权威结论 |
LongHorizon-Harness 的核心洞察可以浓缩成一句话:模型决定 Agent 一轮能做多少,而循环工程决定它能可靠地走多远。当你需要 AI Agent 在桌面应用和终端里连续工作几个小时而不失忆、不漂移、不谎报时,这套 Manager–Executor–Auditor 分工协作机制,就是值得理解并采用的那套方案。

