AMAP-ML/LongHorizon-Harness · 上手攻略

仓库：AMAP-ML/LongHorizon-Harness
链接：https://github.com/AMAP-ML/LongHorizon-Harness
分类：AI Agent · 计算机使用 · 长周期任务执行
作者：Tom
更新：2026-08-27

是什么

LongHorizon-Harness 是一个长周期计算机使用（Computer Use）Agent 执行框架。它不训练新模型，而是围绕已有的 Agent（如 Claude Code、OpenCode、DeepSeek Harness）构建一个可靠的"执行-验证-恢复"循环，让 AI Agent 能在桌面应用和 CLI 环境中连续工作数十小时、可靠地完成复杂工作流。

核心论文：arXiv 2608.01964（2026-08 发布当周登顶 Hugging Face Daily Papers 榜首）。

核心理念：模型决定单轮能力上限，Harness 负责工程化外围循环——下一步做什么、如何在真实环境中验证结果、保留哪些进度、如何在失败后恢复。

解决什么问题

现有 Agent 的三大致命缺陷

错误累积：早期一个错误会让后续所有决策扭曲，Agent 逐渐偏离原始目标
上下文腐化：历史记录越来越长，关键信息越来越难检索，性能急剧下降
任务状态丢失：没有准确记录"做了什么、产生了什么、环境实际包含什么"，无法可靠恢复

LongHorizon-Harness 的答案：循环工程（Loop Engineering）

不是改进 Agent 的 Prompt，而是重新设计 Agent 与环境交互的整个循环结构：

原始目标 + 已验证状态
    ↓
管理器：规划下一个有界步骤
    ↓
执行器：在桌面应用或CLI中执行（使用全新上下文）
    ↓
审计员：独立检查真实环境中的实际结果（只读）
    ↓
通过 → 检查点记录已验证的进度
失败 → 记录证据并进入下一轮
    ↓
任务完成？→ 否 → 循环
    是 → 输出已验证结果

快速安装

环境要求

Python 3.10+（官方推荐 Python 3.10+）
支持的 Agent 后端之一：Claude Code / OpenCode / DeepSeek Harness（需提前安装并配置好）

安装方式

# 方式一：pip 安装
pip install lh-harness

# 方式二：从源码安装
git clone https://github.com/AMAP-ML/LongHorizon-Harness.git
cd LongHorizon-Harness
pip install -e .

# 方式三：使用 uv（推荐）
uv pip install lh-harness

前置：安装 Agent 后端（按需选择）

# Claude Code（需先安装 Node.js）
npm install -g @anthropic-ai/claude-code

# OpenCode
# 参考 https://github.com/anomalyco/opencode

# DeepSeek Harness
# 参考 https://github.com/deepseek-ai/deepseek-harness

启动 Web 工作台（推荐）

lh-harness web
# 打开 http://localhost:8000（默认）

在 Web 界面中可以： - 启动任务 - 为每个角色（Manager / Executor / Auditor）独立选择后端和模型 - 实时查看进度、发送指令、停止或重启任务

CLI 启动示例

# 使用 Claude Code 作为执行后端
lh-harness run "帮我把这个数据分析脚本跑完并生成报告" \
  --agent claude_code \
  --model claude-sonnet-4-20250514

# 使用 DeepSeek Harness
lh-harness run "分析 /home/user/project 目录的代码结构" \
  --agent deepseek_harness \
  --profile headless

常用配置参数

# 指定工作目录（Agent 默认从当前目录启动）
lh-harness run "任务描述" --cwd /path/to/project

# 为 Manager 单独设置推理 effort（适用于支持该特性的模型）
lh-harness run "任务描述" --manager-reasoning-effort high

# 查看诊断信息
lh-harness doctor

核心概念：三重角色架构

LongHorizon-Harness 将 Agent 循环分解为三个职责明确的角色：

角色	职责	输入	输出
Manager（管理器）	状态感知 + 任务分解	原始目标 + 已验证进度 + 失败证据 + 剩余工作	下一个有界子任务（含目标、依赖、验收标准）
Executor（执行器）	单步执行	一个明确子任务 + 依赖证据	在真实环境中产生变更
Auditor（审计员）	独立验证	真实环境状态（不看到执行器的推理过程）	审计报告：哪些变更被验证，哪些失败

关键设计原则

只读完整性：审计员只能读取环境，不能修改；框架监控审计员行为，若发现修改受保护状态则报告 integrity violation
轮次局部执行：执行器每次用全新上下文，只执行一个子任务，推理过程在轮次结束后丢弃
检查点之外无记忆：只有通过审计的变更才能成为任务状态的一部分，未验证的失败留在轮次内不外泄
停止后可继续：v0.1.7+ 支持在任务中途发送消息，消息会被下一轮次认领，不会丢失

典型适用场景

场景	说明
复杂代码重构（数十小时）	AI Agent 跨越多个文件、多次编译/测试循环，需要可靠的状态追踪
数据处理流水线（跨日运行）	需要 Agent 第二天接着干，不丢失中间状态
桌面应用自动化	跨越 GUI 应用的复杂操作序列（如填表、截图、比对结果）
多 Agent 协作审查	Manager + Auditor 双重验证关键代码变更，确保没有"AI 幻觉自我确认"
Agent 基准测试	Terminal-Bench 2.1 等基准评测框架，统一测量 Agent 在长任务中的可靠性

坑与注意

安全边界：LongHorizon-Harness 在真实机器上执行任意操作（文件读写、GUI 操作等）。确保运行环境与敏感系统隔离；框架本身不提供沙箱隔离。
Agent 后端依赖：框架本身不包含 Claude Code 等 Agent，需要提前安装配置；不同后端的接口差异可能影响兼容性（v0.1.7+ 已支持 OpenCode 和 DeepSeek Harness，Claude Code 兼容性最佳）。
Web 工作台端口冲突：默认 lh-harness web 使用 8000 端口，若已被占用可用环境变量或命令行参数覆盖（具体参数需参考 lh-harness --help）。
版本迭代快：仓库更新频繁（v0.1.x 系列），README 顶部的 changelog 显示几乎每天都有新版本；安装前建议确认版本号：pip show lh-harness。
计算机使用插件管理：v0.1.2+ 引入了统一的计算机使用插件管理，不同后端可能需要不同的插件配置，具体参考 README 中的 Manage computer-use plugins 章节。
审计员独立性问题：理论上审计员必须完全独立于执行器，但实际部署中 Manager/Executor/Auditor 可能共用同一个 Agent 后端实例（只是 Prompt 不同），这在理论上存在 Prompt 泄露风险。
GUI / MCP 支持：截至 v0.1.7，DeepSeek Harness 的 GUI 计算机使用和 MCP 支持尚未完成（CLI 已支持）；若需要 GUI + MCP 能力，需关注后续版本。

与同类对比

维度	LongHorizon-Harness	Anthropic Computer Use	OpenAI Operator	LangGraph
架构	Manager/Executor/Auditor 三角色循环	单 Agent + 工具	单 Agent + 浏览器控制	DAG/状态机工作流
验证机制	强制独立审计门	无强制验证	无强制验证	视具体节点设计
多 Agent 后端	✅ Claude Code / OpenCode / DeepSeek Harness	❌（专用）	❌（专用）	❌（需自行集成）
长周期恢复	✅ 检查点 + 消息续接	❌	❌	部分（取决于状态设计）
桌面 GUI 支持	✅（通过 Agent 后端）	✅	✅（浏览器）	需自行集成
开源	✅（MIT）	❌	❌	✅
基准测试	✅（Terminal-Bench 2.1）	❌	❌	❌

核心差异：LongHorizon-Harness 是目前唯一将"独立审计验证"作为强制门（而非可选步骤）的长周期 Agent 框架——这直接针对 AI 幻觉自我确认这一根本性问题。

一句话推荐结论

如果你需要在真实机器上运行超过几分钟的 AI Agent 任务，且对"AI 自我报告的进度是否可信"有疑虑，LongHorizon-Harness 的三角色审计架构是当前开源方案中设计最完整的——尤其是与 Claude Code 配合做复杂代码任务长周期运行时。