面向真實環境的 Loop Engineering
模型能力決定了 Agent 單輪推理的上限；LongHorizon-Harness 負責工程化模型外部的執行閉環。它解決單輪對話結束後的後續規劃、真實系統驗證、進度持久化，以及在執行失敗或上下文刷新後的狀態恢復。
系統支援跨桌面 GUI 與命令列 CLI 混合工作流。單一任務可在瀏覽器蒐集資料、在命令列執行處理腳本、於桌面軟體產出交付物，再回到終端進行測試驗證。目標、進度與稽核證據全程由統一狀態系統維持。
執行架構將單一閉環拆分為三種專注職責：Manager 負責狀態與步驟規劃、Executor 在全新上下文中執行單步動作、Auditor 獨立檢查真實檔案與系統回饋。未通過驗證的結果僅保留為失敗證據，不計入有效進度。
原始目標與已驗證狀態
規劃單步邊界任務
全新上下文執行
真實環境獨立驗證
保存進度或記錄失敗恢復
已驗證交付成果
「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.」
一條命令安裝與工作區初始化
環境需求包含 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 .角色劃分與可配置組件
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）。執行長時間任務時，先確立狀態隔離、全新上下文與獨立稽核機制，以維持執行穩定度與結果可信度。
全新上下文執行
每輪 Executor 皆以乾淨的 context 啟動，僅接收當前目標、最新已驗證狀態與上一輪失敗記錄，避免歷史訊息膨脹導致指令偏離。
來源 · 官方架構設計
獨立客觀稽核
Auditor 獨立檢查實體檔案系統、UI 截圖、終端日誌與測試回傳碼，不直接信任 Executor 的文字回報。
來源 · 官方 README
可持久化檢查點
僅有通過 Auditor 驗證的步驟才會被寫入已驗證進度（checkpoint）。未通過的嘗試保留為失敗證據，作為下一輪規劃依據。
來源 · 官方狀態管理
按角色模型路由
Manager 與 Auditor 建議配置高推理能力模型（如 Claude 3.7 / GPT-5），Executor 則可搭配成本效益較高的模型以降低 token 總花費。
來源 · 官方設定指南
工作區安全隔離
任務執行預設作用於當前工作目錄，而 ./.lh-harness/ 狀態目錄保持受保護，避免 Agent 誤改自身日誌與歷史。
來源 · 官方安全邊界
連續對話延續性
任務結束後在 Web 工作台直接追問，系統會沿用該任務已完成的 round ledger 繼續推進，不需從頭重複執行。
來源 · v0.1.7 更新日誌
外掛隔離與優先權
Computer-use 外掛設定存放於 ~/.lh-harness/plugins/，不改動全域 config；當安裝多個外掛時按優先序自動選取。
來源 · 官方外掛管理
規模化基準實證
在 WeaveBench 混合任務達到 80.7%（提升 28.9%）、OSWorld 2.0 桌面任務達 3.0 倍完成率，並在 TB 2.1 節省 24% token。
來源 · arXiv:2608.01964
跨桌面與終端的端到端執行流程
以下示範一項典型任務：從命令列或 Web 工作台啟動，先在桌面瀏覽器中排查系統錯誤，再於命令列中修復後端 API 與更新測試，最後由 Auditor 執行端到端驗證並持久化檢查點。
> lh-harness run --task "Inspect dashboard error in Chrome, fix API handler in Python, and verify via pytest" --agent codex
claude: Manager › Round 1/3
hl: 目標解析完成。規劃第 1 步：啟動桌面瀏覽器檢視 http://127.0.0.1:3000/metrics 並截取錯誤記錄。
claude: Executor (GUI) ›
[使用全新上下文操作 Chrome · 開啟頁面 · 擷取畫面與主控台日誌]
發現錯誤：KeyError: 'latency_p99' 在渲染指標卡片時引發例外。
claude: Auditor ›
[獨立檢查截圖 .lh-harness/runs/run-001/artifacts/error.png 與主控台輸出]
ok: 稽核通過：錯誤重現成功。寫入檢查點 Checkpoint 1。
claude: Manager › Round 2/3
hl: 已確認錯誤根因。規劃第 2 步：修改 src/metrics.py 加入缺省防護值，並執行 pytest 測試。
claude: Executor (CLI) ›
[使用全新上下文修改 src/metrics.py · 執行 pytest tests/test_metrics.py]
程式碼已加入預設值；執行測試通過。
claude: Auditor ›
[獨立在工作區重新執行 pytest 測試套件並核對 git diff]
ok: 稽核通過：14 passed in 0.82s · 程式碼修復符合規格。寫入檢查點 Checkpoint 2。
claude: Final Response ›
ok: 任務已由已驗證狀態確認完成：
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.」
驗收與持久化機制
每次任務執行會在 ./.lh-harness/runs/<run-id>/ 建立獨立目錄，完整記錄每輪次之規劃步驟、操作截圖、終端歷程與稽核報表 logs/report.json。
在 Web 工作台直接輸入追問時，系統會自動繼承既有 round ledger 與檢查點狀態，無縫接續後續工作，避免重複消耗 token 與時間。
長時間執行的操作邊界
自訂配置與評測重現
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.」