AMAP-ML 開源工程 · Loop Engineering 執行閉環

面向 Computer-Use
的長時間 Agent
執行閉環

LongHorizon-Harness 是面向 Claude Code、Codex、OpenCode 與 DeepSeek Harness 的開源執行閉環系統。它在跨桌面 App 與終端環境中持續管理目標狀態、分配邊界明確的單步執行、在真實系統中獨立稽核，並在失敗或上下文刷新後自動恢復。

1.1k

GitHub Stars

閉環核心角色

8799

Web 工作台連接埠

MIT

開源授權

專案定位

面向真實環境的
Loop Engineering

模型能力決定了 Agent 單輪推理的上限；LongHorizon-Harness 負責工程化模型外部的執行閉環。它解決單輪對話結束後的後續規劃、真實系統驗證、進度持久化，以及在執行失敗或上下文刷新後的狀態恢復。

系統支援跨桌面 GUI 與命令列 CLI 混合工作流。單一任務可在瀏覽器蒐集資料、在命令列執行處理腳本、於桌面軟體產出交付物，再回到終端進行測試驗證。目標、進度與稽核證據全程由統一狀態系統維持。

執行架構將單一閉環拆分為三種專注職責：Manager 負責狀態與步驟規劃、Executor 在全新上下文中執行單步動作、Auditor 獨立檢查真實檔案與系統回饋。未通過驗證的結果僅保留為失敗證據，不計入有效進度。

LongHorizon-Harness 閉環執行流程

原始目標與已驗證狀態→ 規劃單步邊界任務→ 全新上下文執行→ 真實環境獨立驗證→ 保存進度或記錄失敗恢復→ 已驗證交付成果

「The model determines what an agent can do in one round. LongHorizon-Harness engineers the loop around it: what to do next, how to verify the result in the real computer, what progress to preserve, and how to continue after failure or context refresh.」

— LongHorizon-Harness 官方專案主旨

安裝與環境設定

一條命令安裝與
工作區初始化

環境需求包含 Python ≥3.10、Node.js 22.19+ 或 24+，以及至少一組受支援的 Agent CLI（Claude Code、Codex CLI、OpenCode 或 DeepSeek Harness）。使用 uv 或 pip 安裝核心套件。

uv tool install lh-harness # 或: pip install lh-harness
      

安裝 Computer-Use 外掛與專案初始化

若任務涉及桌面 GUI 操作，需依使用的 Agent 安裝對應外掛。外掛在全機安裝一次即可供所有專案共用，並自動生成各 Agent 專屬的 MCP 設定。

# 安裝 Claude Code / Codex 通用 GUI 外掛
lh-harness plugin install open-computer-use

# 若僅使用 Codex，可安裝官方外掛：
# lh-harness plugin install codex-computer-use

# 進入專案目錄並生成設定檔 ./.lh-harness/config.toml
cd /path/to/your/project
lh-harness init

# 啟動 Web 工作台（預設監聽 127.0.0.1:8799）
lh-harness web --workspace-root .
      

macOS 系統權限與環境診斷。GUI 操作需在 macOS「系統設定 → 隱私權與安全性」手動勾選輔助使用（Accessibility）與螢幕錄製（Screen Recording）權限。執行 lh-harness doctor 可自動檢查 Python、Node.js、Agent 二進位檔及外掛授權狀態。

閉環職責與能力地圖

角色劃分與
可配置組件

LongHorizon-Harness 將複雜的長時間任務分解為同一閉環內的專注職責與可插拔組件。不同角色可在設定檔中獨立指定模型與後端，兼顧執行品質與 token 成本。

Role · 01

manager

狀態與下一步

每輪自原始目標、已驗證進度與失敗記錄重建狀態，規劃邊界明確的單步動作。

Role · 02

cli_executor

終端執行器

以全新上下文執行命令列操作、腳本除錯、相依套件安裝與檔案修改。

Role · 03

gui_executor

桌面操作員

跨瀏覽器、試算表、設計軟體與系統視窗執行點擊、文字輸入與介面操作。

Role · 04

auditor

獨立稽核員

獨立檢查真實檔案、UI 截圖、日誌與測試結果，不直接信任 Executor 自述。

Role · 05

final_response

結果總結

任務結束時僅依據真實已驗證狀態產出自然語言結論，未完成時據實說明。

Surface · 06

lh-harness web

Web 工作台

基於 React/FastAPI 的瀏覽器介面，支援即時進度監控、審批處理與動態指令。

Surface · 07

lh-harness run

CLI 執行入口

透過命令列直接執行任務，支援參數覆寫與 --no-dashboard 輕量模式。

Feature · 08

conversation-turn

連續追問機制

任務完成後直接追問，沿用既有 round ledger 繼續執行，不從頭重複規劃。

Feature · 09

reasoning-effort

思考強度配置

支援全域或按角色個別設定推理強度，並精確轉發至支援該參數的模型後端。

Plugin · 10

lh-harness plugin

外掛生命週期

統一安裝管理 codex-computer-use、open-computer-use 與 clawdcursor。

Backend · 11

AgentAdapter

多後端轉接層

原生轉接 Claude Code、Codex CLI、OpenCode、DeepSeek Harness 與自訂後端。

Protocol · 12

mcp configuration

MCP 協定支援

支援 Claude Code 的 .mcp.json 與 Codex 的 TOML 設定檔，並支援自訂目錄掛載。

Diag · 13

lh-harness doctor

環境診斷工具

唯讀檢查 Python、Node.js、各 Agent 二進位檔版本、PATH 與 GUI 授權狀態。

Eval · 14

eval reproduction

評測重現套件

內建 WeaveBench、OSWorld 2.0 與 Terminal-Bench 2.1 的凍結評測重現環境。

使用情境與入口選擇

使用情境	推薦入口	適用動作
互動式任務與視覺監控	`lh-harness web --workspace-root .`	瀏覽器工作台、角色模型切換、審批互動與多輪追問
自動化腳本與 CI 流程	`lh-harness run --task @task.md`	命令列單次執行、排程執行、`--no-dashboard` 模式
環境檢查與二進位排查	`lh-harness doctor`	檢查 Python、Node.js、CLI 二進位檔與 macOS 權限
桌面 GUI 外掛管理	`lh-harness plugin install <name>`	安裝或移除 open-computer-use / codex-computer-use
基準評測與論文重現	`eval/<benchmark>-harness/`	重現 WeaveBench、OSWorld 2.0 或 Terminal-Bench 2.1

官方架構原則

長時間執行的
核心工程原則

以下原則整理自 LongHorizon-Harness 官方 README 與論文（arXiv:2608.01964）。執行長時間任務時，先確立狀態隔離、全新上下文與獨立稽核機制，以維持執行穩定度與結果可信度。

TIP 01

全新上下文執行

每輪 Executor 皆以乾淨的 context 啟動，僅接收當前目標、最新已驗證狀態與上一輪失敗記錄，避免歷史訊息膨脹導致指令偏離。

來源 · 官方架構設計

TIP 02

獨立客觀稽核

Auditor 獨立檢查實體檔案系統、UI 截圖、終端日誌與測試回傳碼，不直接信任 Executor 的文字回報。

來源 · 官方 README

TIP 03

可持久化檢查點

僅有通過 Auditor 驗證的步驟才會被寫入已驗證進度（checkpoint）。未通過的嘗試保留為失敗證據，作為下一輪規劃依據。

來源 · 官方狀態管理

TIP 04

按角色模型路由

Manager 與 Auditor 建議配置高推理能力模型（如 Claude 3.7 / GPT-5），Executor 則可搭配成本效益較高的模型以降低 token 總花費。

來源 · 官方設定指南

TIP 05

工作區安全隔離

任務執行預設作用於當前工作目錄，而 ./.lh-harness/ 狀態目錄保持受保護，避免 Agent 誤改自身日誌與歷史。

來源 · 官方安全邊界

TIP 06

連續對話延續性

任務結束後在 Web 工作台直接追問，系統會沿用該任務已完成的 round ledger 繼續推進，不需從頭重複執行。

來源 · v0.1.7 更新日誌

TIP 07

外掛隔離與優先權

Computer-use 外掛設定存放於 ~/.lh-harness/plugins/，不改動全域 config；當安裝多個外掛時按優先序自動選取。

來源 · 官方外掛管理

TIP 08

規模化基準實證

在 WeaveBench 混合任務達到 80.7%（提升 28.9%）、OSWorld 2.0 桌面任務達 3.0 倍完成率，並在 TB 2.1 節省 24% token。

來源 · arXiv:2608.01964

完整任務實例

跨桌面與終端的
端到端執行流程

以下示範一項典型任務：從命令列或 Web 工作台啟動，先在桌面瀏覽器中排查系統錯誤，再於命令列中修復後端 API 與更新測試，最後由 Auditor 執行端到端驗證並持久化檢查點。

~/projects/data-service · lh-harness v0.1.7

$ lh-harness run --task "Inspect dashboard error in Chrome, fix API handler in Python, and verify via pytest" --agent codex [載入 ./.lh-harness/config.toml；建立 run-20260824-001 隔離狀態]

Manager › Round 1/3 目標解析完成。規劃第 1 步：啟動桌面瀏覽器檢視 http://127.0.0.1:3000/metrics 並截取錯誤記錄。

Executor (GUI) › [使用全新上下文操作 Chrome · 開啟頁面 · 擷取畫面與主控台日誌] 發現錯誤：KeyError: 'latency_p99' 在渲染指標卡片時引發例外。

Auditor › [獨立檢查截圖 .lh-harness/runs/run-001/artifacts/error.png 與主控台輸出] 稽核通過：錯誤重現成功。寫入檢查點 Checkpoint 1。

Manager › Round 2/3 已確認錯誤根因。規劃第 2 步：修改 src/metrics.py 加入缺省防護值，並執行 pytest 測試。

Executor (CLI) › [使用全新上下文修改 src/metrics.py · 執行 pytest tests/test_metrics.py] 程式碼已加入預設值；執行測試通過。

Auditor › [獨立在工作區重新執行 pytest 測試套件並核對 git diff] 稽核通過：14 passed in 0.82s · 程式碼修復符合規格。寫入檢查點 Checkpoint 2。

Final Response › 任務已由已驗證狀態確認完成： 1. 排查出前端指標看板因缺少 latency_p99 欄位崩潰。 2. 於 src/metrics.py 完成缺省回退邏輯修復。 3. 通過獨立 pytest 測試套件全數 14 項測試。

「Only results that pass independent verification become trusted task state. A rejected result remains evidence, not progress.」

— LongHorizon-Harness 官方架構說明

驗收與持久化機制

每次任務執行會在 ./.lh-harness/runs/<run-id>/ 建立獨立目錄，完整記錄每輪次之規劃步驟、操作截圖、終端歷程與稽核報表 logs/report.json。

在 Web 工作台直接輸入追問時，系統會自動繼承既有 round ledger 與檢查點狀態，無縫接續後續工作，避免重複消耗 token 與時間。

限制與安全條件

長時間執行的
操作邊界

macOS 系統權限需手動開啟。GUI 操作外掛（如 codex-computer-use 與 open-computer-use）依賴輔助使用與螢幕錄製權限。系統不會彈出授權提示，未授權呼叫會直接靜默失敗；安裝後請至「隱私權與安全性」完成勾選。
DeepSeek Harness 處於第一階段 CLI 預覽。目前僅支援以 headless 模式執行純文字命令列任務，GUI 操作與 MCP 設定尚未支援，且中間工具事件不支援串流輸出。
長時間任務存在 Token 累積成本。長時間執行的多輪閉環會消耗顯著的 API token。應於 config.toml 明確配置 max_rounds 與 [run.timeouts] 防止無限循環。
保護 ./.lh-harness 狀態目錄。該目錄存放專案設定、執行紀錄與檢查點檔案。請勿將任務工作區指向該目錄，亦不可讓 Agent 修改其內容。
Windows 平台環境限制。目前支援 Windows 系統，但必須在已登入的一般桌面工作階段中執行，且不可使用系統管理員提權模式（unelevated）。
單輪逾時為 Agent 執行逾時。Manager、Executor 或 Auditor 達到 run.timeouts 上限時，代表該角色未在時限內完成，不等於網路連線中斷；下一輪 Manager 會讀取未完成狀態進行復原。
API 金鑰應使用環境變數管理。切勿將 API 金鑰或 Token 寫入 ./.lh-harness/config.toml 等可能被提交至版控的檔案中。
多外掛載入存在固定優先順序。當同時安裝多個 computer-use 外掛時，載入優先順序固定為 codex-computer-use > open-computer-use > clawdcursor。

進階路徑

自訂配置與
評測重現

LongHorizon-Harness 的進階延伸包含自訂角色模型權限、撰寫自訂 AgentAdapter、掛載專屬 MCP 伺服器，以及重現官方論文的評測基準。

進階實作地圖

1. 角色專屬模型與推理配置。在 ./.lh-harness/config.toml 設定 [run.roles.manager] 與 [run.roles.auditor] 分別指定 model 與 reasoning_effort，實作精準分工。

2. 自訂 Agent 轉接器。繼承 AgentAdapter 介面實作自訂 Agent 呼叫邏輯、權限邊界管理與輸出結果結構化正規化。

3. 掛載私有 MCP 伺服器。使用 --claude-mcp-config 或 --codex-mcp-config 連接企業內部資料庫、API 工具或自訂除錯工具。

4. 重現論文基準評測。進入 eval/WeaveBench-harness/ 或 eval/OSWorldv2-harness/ 依專屬 README 配置環境，重現實驗數據。

5. 整合 CI/CD 自動化任務。透過 lh-harness run --task @task.md --no-dashboard 串接 GitHub Actions，建立夜間長時間自動化重構與驗證流程。

延伸閱讀與論文資源

① arXiv:2608.01964：LongHorizon-Harness 論文全文，詳解 Loop Engineering 數學架構與評測方法。
② eval/ 目錄評測套件：WeaveBench、OSWorld 2.0 與 Terminal-Bench 2.1 凍結重現指令。
③ 專案官方網站：完整實驗軌跡、案例分析與 Web 工作台最新功能預覽。

「Operate the whole computer. Preserve verified progress. Keep working until the task is done.」

— LongHorizon-Harness 官方專案宣言