编者摘要：LongHorizon‑Harness 是面向计算机使用智能体的循环工程开源框架 (arXiv:2608.01964，MIT 协议)，不训练新模型，在现有 Agent 外层构建持久执行闭环，支持 Claude Code、Codex、OpenCode、DeepSeek Harness。核心循环为：规划→执行→校验→检查点 / 故障恢复→重复。
框架拆分三大角色：Manager 规划下一步；Executor 执行 GUI / 终端子任务；Auditor 独立校验真实环境输出，只有审计通过才视为有效进度，失败则从最近校验点恢复，解决长任务上下文丢失、幻觉、中途崩溃问题。
同时支持桌面 GUI 与终端 CLI 混合工作流，各角色可自由选配不同模型 / 后端。在 WeaveBench、OSWorld2.0、Terminal‑Bench2.1 基准取得显著提升，任务通过率大幅上涨，Token 消耗下降。
提供 React+FastAPI 网页工作台、完整 CLI 工具链、插件系统、MCP 接入，支持环境自检、任务轨迹留存、中途追加指令。主要面向 macOS，Windows 实验性支持，最大轮次等参数可配置，eval 目录提供评测复现脚本。
7 个关键问题 Q&A
Q1：LongHorizon‑Harness 是一个大模型吗？
A：不是。它不训练模型，是外层编排框架，复用 Claude Code / Codex / DeepSeek Harness 等已有智能体，新增循环、校验、断点恢复逻辑。
Q2：Manager‑Executor‑Auditor 三个角色是什么关系？
A：属于同一个循环内职责拆分，不是三套独立 Agent 各自做任务。Manager 做计划，Executor 干活，Auditor 做客观环境校验；审计不通过，结果不算任务进度。
Q3：它怎么实现几十小时长任务，解决上下文溢出？
A：每一轮 Executor 使用全新干净上下文；任务状态不依赖大模型上下文窗口，依靠外部保存「已校验检查点、原始目标、失败证据」，上下文刷新后从检查点继续推进。
Q4：是否同时支持图形桌面 GUI 和终端 CLI？
A：支持。一个任务可以浏览器→终端处理数据→桌面软件生成产物→回到终端调试；统一一套状态管理。需要安装对应 computer‑use 插件；DeepSeek‑Harness v1 阶段只支持 CLI。
Q5：不同角色可以使用不同模型吗？
A：可以。Manager、GUI 执行器、CLI 审计器均可单独指定 agent/model。常见策略：强模型用于 Manager/Auditor，低成本模型做 Executor，平衡效果与成本。
Q6：Auditor 审计器和普通 Agent 自我反思区别？
A：普通自我反思是模型自说自话；Auditor直接读取真实操作系统文件、日志、界面状态，独立客观核验，不采信 Executor 的口头输出。
Q7：任务中途停止、或者运行结束之后，还能追加指令继续任务吗？
A：v0.1.7 支持。工作台是会话式，结束后输入后续指令，系统基于历史运行记录继续执行，不会全部重新规划。中途下发消息会被下一轮直接接收，不会丢失。
作者简介：LongHorizon‑Harness 出自阿里巴巴高德 DreamX（AMAP‑ML）团队，论文发布于 2026 年 8 月 arXiv，代码以 MIT 协议开源。 团队核心研究方向为面向真实电脑环境的长时序智能体工程，针对传统 Agent 将规划、执行、评估耦合在同一上下文，造成幻觉错误不断向后传导的痛点，创新提出 MEA 管理‑执行‑审计分离循环：任务状态外置保存，执行者每一轮使用全新干净上下文，审计角色读取真实系统环境信息独立核验，只有客观校验通过才更新任务进度。 依托 AgentAdapter 适配器，框架可无缝接入 Claude Code、Codex、DeepSeek‑Harness、Qwen 等不同智能体，无需改动原有 Agent 内部逻辑；同时支持 GUI 桌面图形任务与 CLI 终端任务混合执行，在 WeaveBench、OSWorld2.0、Terminal‑Bench2.1 基准验证，显著提升长任务完成率并降低 Token 消耗。
附录 LongHorizon‑Harness 面向计算机使用智能体的循环工程
只需给 Claude Code、Codex、OpenCode 或 DeepSeek Harness 设定一次目标，它就可以跨桌面应用与终端持续工作数十小时。
规划 → 执行 → 校验 → 保存检查点或故障恢复 → 重复—— 直到任务真正完成。
项目链接：官网｜arXiv 论文 2608.01964｜GitHub 仓库｜Hugging‑Face 运行轨迹｜Hugging‑Face 每日论文｜MIT 开源协议 相关板块：Python 智能体｜基准测试｜使用说明・执行循环・计算机操作能力・实验结果・项目官网・简体中文
通过命令行安装并运行 LongHorizon‑Harness
模型决定智能体单轮可以完成的能力上限。LongHorizon‑Harness 在模型外层搭建一套执行循环：确定下一步动作、在真实计算机环境校验结果、保存已取得的进度，在发生失败或上下文刷新后继续推进任务。
这是一套面向 Claude Code、Codex、OpenCode、DeepSeek Harness 的循环工程系统。一键安装，开箱即用。
LongHorizon‑Harness 可以把现有智能体改造为可长时间运行的计算机操作系统。它跨桌面应用与命令行终端，会持续还原原始目标与已校验状态，选取下一个边界明确的子步骤，使用全新上下文执行该步骤，核验真实运行结果；通过校验的进度会保存为检查点，失败证据则会输入下一轮迭代。它不会训练新模型，也不会替换原有智能体；而是为现有智能体提供一套具备持久执行能力的外层循环。
✨ 更新动态
[v0.1.7 · 2026‑08‑20]任务运行结束不再代表流程终结：工作台现已支持会话交互。你可以读取回复，输入后续指令，系统会基于本次任务已有的执行记录继续运行，而不是从零重新规划。中途发送的指令会在下一轮执行中被接收，停止再继续任务不会丢失消息。 新增可针对各个角色配置推理强度（可通过--manager‑reasoning‑effort等参数单独覆写某一角色配置），参数会转发给支持该能力的后端。运行日志严格按照时间顺序输出；工作进程收到优雅停止指令后，若工作单元无视停止信号，会升级为强制终止。
[v0.1.6 · 2026‑08‑15]新增 OpenCode 命令行支持。现在可以通过--agent opencode调用opencode run prompt；支持角色级别的读写权限隔离、自定义 OpenCode API 接口、标准化 JSON 返回结果，兼容命令行、配置文件、环境自检工具。网页工作台可为每个角色独立选择 OpenCode Harness 以及配套模型。
[v0.1.5 · 2026‑08‑14]第一阶段：新增 DeepSeek Harness 命令行支持。可通过--agent deepseek_harness运行dsh --profile headless；提供隔离的 DSH_HOME 环境、角色粒度读写权限、可自定义 DeepSeek API 接口，输出标准化 JSONL 结果，兼容命令行、配置、环境自检工具。网页工作台可给各个角色独立选用 DeepSeek Harness 与对应模型。
GUI 计算机操作与 MCP 协议支持将在后续版本上线，详见命令行部署文档。
[v0.1.4 · 2026‑08‑11]全新控制面板上线：基于 React / FastAPI 构建的网页工作台，完全通过浏览器操作。创建任务、为不同角色选择后端与模型、审批操作请求、任务运行中途下发指令、停止或重启任务。启动命令：lh‑harness web；详见浏览器内运行任务。
[2026‑08‑10]接入 Terminal‑Bench 2.1 评测集。
[v0.1.3 · 2026‑08‑07]每次任务结束，都会基于已校验的任务状态生成自然语言总结回复。任务默认在启动命令所在目录执行；控制台实时打印每一轮执行信息。
[2026‑08‑06]LongHorizon‑Harness 登上 Hugging‑Face 每日论文周榜第一名。
[v0.1.2 · 2026‑08‑06]统一计算机操作插件管理体系；审计模块只读校验能力与角色隔离得到增强；进程清理更加可靠；环境自检诊断项得到扩充。详见管理计算机操作插件。
🚀 项目迭代速度很快，敬请关注更新！
演示视频
宣传视频 1440p MP4 打开 1440P MP4 宣传视频
面向真实计算机环境的循环工程
向 LongHorizon‑Harness 给定一个最终目标。系统会反复把剩余工作拆解为边界清晰的子步骤，在对应的计算机环境执行步骤，校验真实发生的结果，将已验证结果带入下一轮循环。
这就是循环工程：围绕智能体设计整套执行、校验、纠错、故障恢复的闭环，而不仅仅是编写单轮提示词。
一套执行循环，三类核心职责角色。 这些角色是循环内部的实现边界，并不是三个独立智能体各自维护一套任务副本。
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
只有通过独立审计校验的结果，才会被信任为任务有效状态。校验不通过的结果仅作为证据留存，不算作任务进度。 当上下文刷新、动作执行失败、交付物未通过审计时，下一轮会从原始目标和上一个通过校验的检查点重新启动，基于剩余工作继续推进。
同时支持桌面图形应用与命令行，实现连续任务
LongHorizon‑Harness 同时支持图形界面 GUI 与命令行 CLI 工作流。
|
|
|
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
同一个任务可以从浏览器开始，切到命令行做数据处理，再切换到桌面软件生成产物，最后回到终端做验证调试。全程目标、进度、证据统一由同一套状态管理系统维护。
兼容任意模型、任意智能体后端
LongHorizon‑Harness 不绑定特定模型或智能体后端。现有模型和智能体仅通过配置接入，无需改动原有工作逻辑。
|
|
|
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
轻量的 AgentAdapter 适配器保留每个智能体原生执行循环，LongHorizon‑Harness 在外部协调角色边界、已校验任务状态以及跨轮次的进度。
你可以全部角色使用同一个模型；也可以搭配不同模型与后端，在效果、速度、成本之间做权衡。
数百项真实任务，可量化性能提升
LongHorizon‑Harness 的效果不局限于少数精心挑选的成功样例。 我们在数百项复杂任务上完成测试，覆盖图形界面、命令行以及混合计算机环境
|
|
|
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
完全相同模型、完全相同执行后端；仅外层 Harness 框架改变。GUI+CLI 任务完成率：由约 50% 提升至约 80% WeaveBench：桌面全量任务完成度提升 3 倍 Terminal‑Bench 2.1 代码 + 命令行任务成功率：69.7% → 77.2%，Token 消耗降低 24%
各基准测试性能对比
全部实验均使用 Qwen 3.7‑Plus 基座，Claude Code 作为执行后端。
|
|
|
|
|
|
|---|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
完整结果表格与任务运行轨迹见 LongHorizon‑Harness 项目官网。
一条命令，全链路可观测
安装
步骤 1‑2 每台机器执行一次；步骤 3 每个项目执行一次。之后可以浏览器（步骤 4）或者命令行（步骤 5）运行任务。
环境依赖
|
|
|
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
平台状态：主要在 macOS 完成测试；Windows 支持已内置，但尚未充分验证。 随时执行
lh‑harness doctor校验全部环境；详见校验运行环境。
- 安装 LongHorizon‑Harness
uv tool install lh‑harness
# 或者使用 pip
pip install lh‑harness
升级：uv tool upgrade lh‑harness或 pip install --upgrade lh‑harness
- 安装计算机操作插件
如果你的任务完全不需要图形界面 GUI，可以跳过这一步。插件默认不会启用；一次安装对本机所有项目生效。
使用 Codex：
lh‑harness plugin install codex‑computer‑use
使用 Claude Code，或同时使用多个智能体：
lh‑harness plugin install open‑computer‑use
codex‑computer‑use是 Codex CLI 官方配套插件，仅可用于 Codex。open‑computer‑use通过 npm 分发，需要 Node.js20+，同时支持两款智能体。 macOS 系统下二者都需要手动授予系统权限。详见管理计算机操作插件，同时介绍第三方插件 clawdcursor，以及插件工作原理。
- 生成项目配置文件
cd /path/to/your/project
lh‑harness init
生成 ./.lh‑harness/config.toml，不会覆盖已有配置；强制重新生成：lh‑harness init --force。打开文件修改默认参数。全部字段说明见配置参考。
- 浏览器运行任务（推荐）
lh‑harness web --workspace-root .
会打开工作台页面 http://127.0.0.1:8799/。在网页内完成：新建任务、为不同角色选择后端与模型、处理审批请求、任务中途下发指令、停止 / 重启任务；任务结束后还可以继续追加指令，系统会基于已完成的执行记录继续运行，而不是重新规划。 --workspace‑root设置网页端新建任务的默认工作目录；更多参数参考控制面板命令。
- 或者直接命令行运行任务
TASK="检查当前目录，汇总目录内全部文件信息。"
lh‑harness run --task "${TASK}" --agent codex
命令行显式参数会覆盖项目配置文件对应配置；省略参数就使用配置文件默认值。
使用第一阶段 DeepSeek Harness 命令行后端：先安装官方 npm 包，配置 DeepSeek API 密钥，指定
deepseek_harness后端。
npm install -g @deepseek‑ai/dsh
# 如果npm镜像未同步包，使用官方源
# npm install -g @deepseek‑ai/dsh --registry=https://registry.npmjs.org
dsh --version
export DEEPSEEK_API_KEY="sk‑..."
# 可选，用于私有或兼容接口
# export DEEPSEEK_BASE_URL="https://your‑endpoint.example.com"
lh‑harness doctor
lh‑harness run --task @task.md --agent deepseek_harness \
--model deepseek‑v4‑flash --no‑dashboard
把 DeepSeek Harness 设置为项目默认，写入 ./.lh‑harness/config.toml
[run]
agent = "deepseek_harness"
model = "deepseek‑v4‑flash"
dashboard = false
之后直接运行：
lh‑harness run --task @task.md
LongHorizon 网页工作台的各个角色下拉框也可以选择 DeepSeek Harness (CLI)，并选择 deepseek‑v4‑flash 或自定义模型 ID。启动 web 服务前需要导出环境变量，保证子进程可以读取密钥。
export DEEPSEEK_API_KEY="sk‑..."
# export DEEPSEEK_BASE_URL="https://your‑endpoint.example.com"
lh‑harness web --workspace-root .
适配器内部调用 dsh --profile headless；每次任务拥有独立 DSH_HOME；执行器拥有工作区写权限，规划器与审计器仅只读。 --api‑key映射环境变量DEEPSEEK_API_KEY，--base‑url映射DEEPSEEK_BASE_URL；LH_HARNESS_DSH_BINARY可指定非 PATH 路径下 dsh 二进制程序。
DeepSeek Harness 目前还处于开发者预览版本；第一阶段不会暴露它自身 WebUI、计算机操作插件、MCP 配置、
--mcp‑add‑dir。headless 模式仅返回最终回答，DeepSeek 中间工具调用事件不会输出到运行轨迹。上游任务入参机制会导致任务文本在进程参数列表可见。
智能体在你启动命令的目录工作，会直接操作你的真实项目文件。可以通过workspace配置或者--workspace参数指定其他目录。框架自身目录./.lh‑harness会被隔离保护，任务不会读写框架日志和状态文件。
控制面板会自动在浏览器打开；控制台为每个角色输出执行日志。任务结束后，系统会基于已校验状态输出自然语言回答；如果任务未完成，也会明确告知。
每一次运行全部保存在 ./.lh‑harness/runs/<run‑id>/；完整报告（包含最终回复）保存在运行日志内 logs/report.json。
校验运行环境
lh‑harness doctor
doctor 工具为只读，检查 Python 运行环境、智能体 CLI、Node.js、插件状态；检查不通过返回非零退出码。 检测智能体 CLI 时会执行<binary> --version，不只是判断文件是否存在；可以捕获二进制损坏的情况，例如微软商店生成的无效零字节 exe 快捷方式，同时给出修复提示。 还会检查 PyPI 是否存在新版本。单独版本检查：
lh‑harness check‑update
配置参考
lh‑harness run会自动读取./.lh‑harness/config.toml。配置优先级：
-
命令行显式参数 ./.lh‑harness/config.toml配置文件 -
程序内置默认值
任务文本、运行 ID、API 密钥不会写在配置文件中，只能来自命令行或环境变量，避免密钥被提交到版本仓库。
[run] 主配置段
表格
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<run‑id>文件夹
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
[run.timeouts] 超时配置段
单位：秒；是单次角色调用超时，不是整个任务总时长。
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
[run.roles.*] 角色独立配置段
每个角色都可以独立设置agent、model、reasoning_effort；例如高能力模型用于规划和审计，执行器使用成本更低的模型。默认全部注释，代表继承上层配置。
配置继承链路： gui_executor→ executor→ [run]cli_auditor→ auditor→ [run]
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
每一项配置都有对应的 CLI 命令行参数，例如--gui‑executor‑model、--auditor‑timeout，单次运行临时覆写。完整列表查看 lh‑harness run --help。
如果规划器、执行器、审计器触发单次角色调用超时，系统会保留已有的轨迹与任务状态；下一轮规划器读取真实工作区环境尝试恢复继续执行。该超时视为智能体执行超时，不直接判定为服务商网络故障。连续多轮超时，控制面板会触发人工介入拦截。
管理计算机操作插件
计算机操作插件和任务执行相互独立：doctor仅做状态检查；lh‑harness run不会自动增删修改插件。全部插件操作通过lh‑harness plugin子命令。
查看插件列表，包含安装状态、支持智能体、项目主页：
lh‑harness plugin list|
|
|
|
|
|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
安装插件不需要指定智能体；插件会配置它所支持的全部智能体。
lh‑harness plugin install clawdcursor
一次安装对本机全部项目生效；安装会完成包下载、操作系统权限确认，为每个智能体生成 MCP 配置文件；PATH 找不到的智能体会跳过。 --agent限定只配置某一个智能体；无头服务器环境可以加--no‑activate跳过图形权限确认步骤。
lh‑harness run运行时自动加载插件；多插件共存时，加载优先级顺序： codex‑computer‑use > open‑computer‑use > clawdcursor--claude‑mcp‑config、--codex‑mcp‑config参数可以强制指定，覆盖优先级规则。 plugin list和doctor会打印每个智能体实际加载哪一个插件，权限是否授予。
卸载插件：
lh‑harness plugin uninstall clawdcursor
GUI 权限完全隔离在 Harness 体系内。npm 系列插件全部安装存储在~/.lh‑harness/，不会改动用户原本的 ~/.codex/config.toml、~/.claude.json以及用户全局 MCP 注册中心。 唯一例外codex‑computer‑use：Codex 会读取自身注册表，执行codex plugin add写入其配置。
macOS 使用 codex‑computer‑use 需要手动授予权限；插件不会弹出授权窗口，未授权会直接调用失败。安装命令会引导打开系统设置，前往「隐私与安全性→辅助功能」、「隐私与安全性→屏幕与系统音频录制」勾选 Codex；完成后重新执行安装校验。 Windows 环境无需勾选权限；但是 Harness 必须运行在登录后的桌面会话，禁止管理员提升权限运行。 安装阶段就会提示所有缺失前置依赖。
配置 MCP 服务
不局限计算机操作插件；任意 MCP 服务都可以接入。不同后端读取各自原生格式，配置不会互相翻译转换。
Claude Code 读取.mcp.json，通过--claude‑mcp‑config指定路径：
{
"mcpServers": {
"computer-use": {
"command": "/path/to/mcp-server",
"args": ["--option", "value"],
"env": {
"EXAMPLE_VARIABLE": "value"
}
}
}
}
Codex 读取 TOML 格式 MCP 配置，通过--codex‑mcp‑config传入，格式与~/.codex/config.toml保持一致：
[mcp_servers.my-server]
command = "/path/to/mcp-server"
args = ["--option", "value"]
[mcp_servers.my-server.env]
EXAMPLE_VARIABLE = "value"
为正在使用的后端传入配置，同时声明 MCP 服务允许读取的目录：
lh‑harness run --task @task.md --agent codex \
--codex‑mcp‑config /path/to/mcp.toml \
--mcp‑add‑dir /path/to/mcp/files
当不同角色使用不同后端，可以同时传入两套配置；--mcp‑add‑dir可多次传参。 也可以通过环境变量设置：LH_HARNESS_CLAUDECODE_MCP_CONFIG、LH_HARNESS_CODEX_MCP_CONFIG、LH_HARNESS_MCP_ADD_DIRS；macOS/Linux 冒号分隔，Windows 分号分隔。
建议密钥全部放在环境变量，不要硬编码写入配置文件。
控制面板命令
lh‑harness run --task @task.md --dashboard # 运行任务同时打开实时监控面板
lh‑harness dashboard # 浏览历史任务与正在运行任务
lh‑harness web --workspace-root . # 独立启动工作台服务，指定默认工作目录
dashboard与web启动同一套工作台，参数完全一致；web作为独立服务入口，而不是依附单次任务。
|
|
|
|---|---|
|
|
|
|
|
./.lh‑harness/runs
|
|
|
|
|
|
|
|
|
|
|
|
|
常用命令行参数
|
|
|
|---|---|
|
|
@task.md读取文件作为任务
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
从文件读取长任务并打开控制面板：
lh‑harness run --task @task.md --dashboard
控制面板展示每一轮的计划、执行结果、审计证据、返工原因。当任务完成、阻塞、需要人工输入、反复失败，会触发人工确认闸门。
📋计划｜⚡执行｜🔍审计｜♻️返工 下一步要干什么｜智能体实际做了什么｜来自环境的客观证据｜需要开启新一轮迭代的理由
每一次任务运行隔离保存在runs/<run‑id>/文件夹。完整任务状态与审计链路，保证任务过程可观测、可恢复、可复现。
|
|
|
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
评测复现
eval/目录包含三套基准测试的完整可复现套件。
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
阅读每个目录下 README.md 或 README.zh‑CN.md，查看环境配置、参数、启动命令。 嵌套目录harness/cua_harness是评测冻结兼容副本；新的集成开发请使用源码目录 src/lh_harness/。
引用论文
@article{longhorizonharness2026,
title={LongHorizon‑Harness: Advancing Long‑Horizon Agents for Real‑World Tasks},
author={Ziyu Ma and Hailang Huang and Shun Zou and Yong Wang and Shidong Yang and Yiming Hu and Fei Wei and XiangXiang Chu},
journal={arXiv preprint arXiv:2608.01964},
year = {2026},
url = {https://arxiv.org/abs/2608.01964}
}
操控完整计算机；保存经过验证的进度；持续工作直到任务真正完成。