AMAP-ML/LongHorizon-Harness

LongHorizon‑Harness – 컴퓨터 사용 에이전트를 위한 루프 엔지니어링

정의

• 기존 LLM 기반 에이전트(Claude Code, Codex, OpenCode, DeepSeek Harness)를 루프로 감싸 실제 데스크톱 애플리케이션과 터미널에서 몇 시간 동안 실행할 수 있게 하는 Python 기반 프레임워크.
• 루프는 매 라운드마다 실행되는 세 가지 역할로 구성됩니다:
  1. Manager – 목표, 검증된 진행 상황, 실패 증거를 재구성하고 다음 경계 있는 단계를 계획합니다.
  2. Executor – 새 컨텍스트에서 해당 단계를 실행합니다(GUI 클릭/입력 또는 CLI 명령).
  3. Auditor – 파일 시스템, UI, 로그 또는 테스트를 독립적으로 검사하여 단계가 실제로 성공했는지 검증합니다.
• 검증된 결과만 영구 작업 상태의 일부가 됩니다. 실패는 다음 라운드의 증거로 기록됩니다.

중요성

• 기존 코드 생성 에이전트는 단일 턴 프롬프트에는 뛰어나지만 길고 다단계 컴퓨터 사용 작업에서는 실패합니다. LongHorizon‑Harness는 누락된 실행, 검증, 복구 메커니즘을 제공하여 에이전트가 여러 애플리케이션에 걸친 복잡한 워크플로를 완료할 수 있게 합니다.
• 모델을 재학습 없이 작동합니다 – 하네스를 이미 사용 중인 에이전트에 연결하기만 하면 됩니다.

주요 기능

• 원커맨드 설치 (uv tool install lh-harness 또는 pip install lh-harness).
• 다중 백엔드 지원 – Claude Code, Codex CLI, OpenCode, DeepSeek Harness 또는 사용자 정의 AgentAdapter.
• GUI + CLI 지원 – 단일 작업에서 클릭, 입력, 스크롤, 문서 편집, 터미널 명령 실행, 패키지 설치 등이 가능합니다.
• 대시보드 – React/FastAPI 웹 워크벤치(lh-harness web)로 실행 시작, 승인 응답, 실행 중 지시 전송, 로그 검사가 가능합니다.
• 플러그인 시스템 – 컴퓨터 사용 플러그인(codex-computer-use, open-computer-use, clawdcursor)을 설치하여 에이전트에 OS 수준 제어를 제공합니다.
• 강력한 복구 – 실패한 라운드의 증거가 다음 계획 단계에 피드백됩니다. 실행은 일시 중지, 재개 또는 후속 쿼리로 계속할 수 있습니다.
• 역할 수준 구성 – Manager, Executor, Auditor 각각에 다른 모델 또는 백엔드를 사용할 수 있습니다.
• 진단 – lh-harness doctor가 환경(Python, 에이전트 바이너리, Node.js, 권한)을 확인합니다.

벤치마크 및 결과

벤치마크	지표	기준(Claude Code)	LongHorizon‑Harness	향상
WeaveBench(114개 작업)	통과율	51.8%	80.7%	+28.9%
WeaveBench	전체 점수	0.702	0.835	+0.133
OSWorld 2.0(108개 작업)	이진 성공	2.8%	8.3%	3×
OSWorld 2.0	부분 성공	21.5%	35.2%	+13.7%
Terminal‑Bench 2.1	성공률	69.7%	77.2%	+7.5%
모든 실험은 기본 모델로 Qwen 3.7‑Plus, 실행 백엔드로 Claude Code를 사용했습니다.

일반적인 워크플로

1. 하네스와 컴퓨터 사용 플러그인을 설치합니다.
2. 프로젝트에서 lh-harness init을 실행하여 config.toml을 생성합니다.
3. 실행 시작 – 웹 UI(lh-harness web --workspace-root .) 또는 CLI에서 직접:

   TASK="Inspect the current directory and summarize its files."
   lh-harness run --task "$TASK" --agent codex
   

4. 하네스는 반복적으로:
   • 다음 단계를 계획하고,
   • 선택한 환경에서 실행하고,
   • 결과를 검증하고,
   • 진행 상황을 체크포인트하거나 실패 증거를 기록합니다.
5. 목표에 도달하면 평이한 언어의 최종 답변이 출력되고 JSON 보고서가 ./.lh-harness/runs/<run‑id>/에 저장됩니다.

설치 스냅샷

# 권장 격리 설치
uv tool install lh-harness   # 또는: pip install lh-harness

# 컴퓨터 사용 플러그인 설치(Claude Code 예시)
lh-harness plugin install open-computer-use

# 프로젝트 초기화
cd /my/project
lh-harness init

지원 플랫폼

• macOS에서 개발 및 테스트됨. Windows 지원은 현재 WSL2가 필요합니다(POSIX 전용 프리미티브가 없음).
• Python ≥ 3.10, 플러그인용 Node.js ≥ 20, 선택한 에이전트 바이너리가 PATH에 있어야 합니다.

라이선스

• MIT 라이선스(LICENSE 참조).

---

결론 – LongHorizon‑Harness는 실용적이고 오픈소스인 "루프 엔지니어링" 레이어로, 모든 LLM 기반 코드/어시스턴트 에이전트를 실제 GUI 및 CLI 워크플로를 처리할 수 있는 안정적이고 장기 실행되는 컴퓨터 사용 시스템으로 전환할 수 있습니다.