HarnessRouter 与 Unified Harness Protocol：自托管 agent harness 网关

wiki/ai/sources/harnessrouter-unified-harness-protocol.md

分类：ai / sources · 更新：2026-08-21 09:09

HarnessRouter 与 Unified Harness Protocol：自托管 agent harness 网关

一句话结论

HarnessRouter Community Edition 把 Codex、Claude Code、Hermes 等 agent harness 包到一个自托管网关和控制台里，并实现 Unified Harness Protocol（UHP）：Responses-compatible API、harness CRUD、sessions、streaming、cancellation、idempotency、conformance suite。它代表 agent runtime 正在从“各自 CLI”走向“可协议化、可路由、可测试的 harness gateway”。

为什么对用户重要

用户已经在 Hermes、Claude Code、Codex、MCP gateway、llm-wiki 之间切换。HarnessRouter/UHP 的价值在于提供统一 runtime surface：同一个 API 可启动不同 harness、管理 session/workspace/checkpoint、流式观察任务，并通过 conformance suite 降低“工具名相同但语义不同”的风险。对 Hermes 来说，这提示未来外部 agent 生态接入不应只靠命令行 wrapper，而应重视协议、幂等、取消语义和 conformance evidence。

机制 / 一阶原理

README 描述的架构是一个 container：UI 只暴露 3000；Gateway 在 loopback 上提供 Responses API 和 harness CRUD；Runner 为每个 session 启动一个 agent CLI；/data volume 保存 SQLite、files、secrets、workspaces。每个 session 有独立 workspace、conversation state 和 checkpoint。UHP 部分包含 specification、OpenAPI/JSON Schema、conformance suite 和 governance；HarnessRouter CE 是 reference implementation，并声称最近 conformance run 达到 class Full。

与已有 wiki 的关系

对 MCP-Gateway-Runtime：UHP 更偏 agent harness runtime API，而 MCP Gateway 更偏工具/上下文服务器与 inference routing；两者都在把 agent side effects 包到可治理协议层。
对 Harness-Engineering：它把 harness 从单机 CLI 提升为带 session、streaming、cancellation、idempotency 和 conformance 的 gateway。
对 Agentic-Engineering：说明未来工程系统需要把 agent runtime 作为基础设施组件，而不是把每个 agent 当一次性进程。

对 Hermes / llm-wiki 的可执行启发

Hermes 若接入外部 harness，应优先记录 protocol/conformance/cancellation/idempotency，而不是只记录“支持某模型”。
长期 cron/agent run 的取消和继续语义需要真实验证；README 中的 sessions/checkpoints 是值得跟踪的 runtime primitive。
wiki 的关注名单应加入 “harness protocol / conformance / agent gateway” 轮换主题。

失败模式 / 边界

README 提到已知问题：HR_BACKENDS 若排除 hermes 会导致 container exit，说明 CE 仍有工程成熟度风险。
自托管不等于安全；本地 workspace、provider key、agent CLI license 和浏览器能力仍需要 operator 自行治理。
UHP 是新标准，生态接受度、跨实现互操作和治理机制仍待观察。

写入记录

2026-08-21 09:06 CST：新增 HarnessRouter/UHP source page，沉淀 agent harness gateway、UHP conformance、session/checkpoint/cancellation 语义。