拓冰网站定制 
HarnessRouter 架构深潜Console、Gateway、Runner 三层如何协作附代码地图【免费下载链接】harnessrouterHarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.项目地址: https://gitcode.com/gh_mirrors/ha/harnessrouterHarnessRouter 是一个开源的「Agent 统一接口」基础设施它把 Codex、Claude Code、Hermes、PI 等 Agent Harness 装进同一个 Docker 容器用一套 OpenAI Responses 兼容 API 统一调度。它的 Community Edition 由三层组成——Console浏览器控制台、Gateway统一 API 网关、RunnerAgent 执行沙箱。本文带你用 10 分钟看懂这三层的数据流、安全边界并给出一张代码地图帮新手快速上手阅读这个 2.6 万行代码的项目。1. 一图看懂一个容器里的三层分工HarnessRouter CE 最聪明的地方是「单容器、三进程」你只需要docker run一条命令对外只暴露一个端口 3000而 Console、Gateway、Runner 在容器内各司其职。项目 README 里有一张官方架构图README.md┌─ HarnessRouter 容器 ─────────────────────────────────┐ │ Console :3000 ← 唯一对外发布的端口 │ │ │ 同源代理 │ │ ▼ │ │ Gateway :8080 Responses API Harness 生命周期 │ │ │ loopback │ │ ▼ │ │ Runner :8081 在会话工作区中运行各 Harness │ │ │ │ /data 卷数据库 · 文件 · 密钥 · 工作区 │ └─────────────────────────────────────────────────────┘三层职责一句话总结层端口一句话职责Console3000唯一对外给人看的界面 给产品用的统一 API 入口Gateway8080仅 loopback统一 API 大脑路由、会话、流式、文件、取消Runner8081仅 loopback真正干活的「手脚」驱动各 Harness CLI 注意Gateway 和 Runner 只监听回环地址外部流量必须经过 Console。这意味着即使你误把 8080/8081 配错它们也不会暴露到网络上。2. Console你看到的「脸」Console 是基于 Next.js 构建的 Web 应用源码在 ui/src/以output: standalone模式打包进镜像ui/next.config.ts。它对新手来说有两个关键点同源代理你在浏览器里发起的每一个 API 请求都由 Console 原样转发给同容器内的 Gateway默认http://127.0.0.1:8080见 docker/entrypoint.sh。所以你作为集成方只需要记住一个地址——http://localhost:3000既开 UI也调 API。登录即门槛CE 默认账号密码是harnessrouter / harnessrouterProfile 页面可随时改密改密会重启 Console 并让旧会话失效docker/entrypoint.sh。页面路由组织在 ui/src/app/(app)//)按功能分目录tasks/任务、harnesses/Harness 管理、keys/API Key、integrations/模型接入等目录名即功能名非常好找。3. Gateway统一 API 的「大脑」Gateway 是整个项目的核心主入口是 gateway/app.pyFastAPI约 1.7 万行。它实现 UHPUnified Harness Protocol的Full 级能力核心路线有四个发起任务POST /v1/responses。这是你产品后端唯一需要懂的端点。请求体里用metadata.harness_id指定跑哪个 HarnessGateway 负责解析模型授权、路由 backend、续接会话previous_response_id。流式进度SSEServer-Sent Events实时推送 Agent 的思考、工具调用与产出事件。文件与产物上传输入文件、下载 Agent 生成物、打包整个会话工作区。取消与失败cancel_response随时叫停所有失败都带机器可读的错误码而不是让人去解析散文。配套模块也各有分工新手可按职责跳转gateway/backing.py本地模式存储层——SQLite 图数据库 文件 Blob 加密密钥库全部落在/data卷无任何外部依赖。gateway/control_sqlite.py / gateway/control_store.py幂等idempotency、租约lease等控制面状态保证请求重放安全。llm_brokerapp.py 内模型请求「经纪人」把 Agent 的模型调用转发到你接入的模型供应商供应商密钥不出容器。4. Runner真正执行任务的「手脚」Runner 的主入口是 runner/server.pyFastAPI约 8 千行它的工作模式在文件头部的 docstring 中写得非常清楚runner/server.py一轮 一个 CLI一个 turn 对应一次性运行某个 backend CLIclaude、codex、hermes、pi、dsh 等 16 个在会话专属的真实 POSIX 工作区里执行带真实的 bash 和 git。事件归一化每个 Harness 的输出被归一化为统一的事件 schema下游Gateway、Console看到的就是同一种「语言」——这正是「换 Harness 不改产品代码」的技术根基。按会话隔离不是每会话一个容器而是每会话一个工作区 一个操作系统用户uid。文件权限就是隔离墙写进别的会话目录或数据库路径的产物会直接失败。只读项目层runner/environments.py 支持把项目文件与依赖「构建一次、多会话只读挂载」。这些 Agent CLI 并不打包在镜像里而是首次启动时由 docker/ 下的安装脚本装到/data卷如 install-kits.sh装什么、怎么装入口脚本里都有严格的版本钉死与校验。5. 安全边界特权是怎么切开的docker/entrypoint.sh 里有一段值得细读的注释——容器的安全模型由**三个身份principal**构成root仅入口脚本与 Runner 持有。Runner 需要 root 才能为每个 Agent 进程切换 uid用的是 Docker 默认就有的CAP_SETUID等能力无需--privileged。agent产品身份跑 Console、Gateway独占读取/data里的数据库、Blob 和密钥库。20000 的会话 uid每个会话一个只拥有自己的会话目录。它读不到别的会话的工作区、数据库和密钥。配合「只发布 :3000 一个端口」就得到了清晰的纵深浏览器 → Console登录门槛→ GatewayAPI 门槛→ RunnerOS 级隔离每一层都有自己的钥匙。6. UHP让三层对齐的开放协议三层能各改各的、却永远对齐靠的是 protocol/ 下的Unified Harness ProtocolUHP——一个版本化的开放标准。它对架构的定义只有三个角色Client → Server → Harnessprotocol/versions/2026-09-28/architecture.md客户端你的产品、Console只说 UHP不需要知道背后是哪家 Harness服务器Gateway Runner如何执行完全黑盒实现细节不得泄漏到线上格式Harness 以稳定的base字符串codex、claude-code、hermes…被寻址。协议还分 Core / Extended / Full 三档符合性等级并附带 protocol/conformance/ 合规测试套件、protocol/schema/ 下的 OpenAPI 与 JSON Schema。换句话说规范、参考实现、测试三件套齐发改协议必须先过测试。7. 代码地图速查表 ️想找什么直接看这里整体架构与快速上手README.md含架构图与 Quickstart三进程如何拉起、特权如何切分docker/entrypoint.sh统一 API任务/流式/文件/取消gateway/app.py本地存储SQLite Blob 密钥库gateway/backing.pyHarness 驱动与事件归一化runner/server.py只读环境/项目层runner/environments.pyUHP 规范最新 2026-09-28 版protocol/versions/2026-09-28/UHP 合规测试套件protocol/conformance/Console 页面与路由ui/src/app/自托管、升级、备份指南docs/self-hosting-guide.md结语HarnessRouter 的三层设计其实回答了一个朴素的问题「我的产品想跑 10 种 Agent但只愿意维护 1 套接口」。Console 把入口收敛成一个端口Gateway 把 16 种 Harness 的差异吞进统一 APIRunner 用「工作区 独立 uid」把每个会话关进各自的房间。读懂entrypoint.sh的权限布局、app.py的任务路由和server.py的事件归一化这三处你就拿到了这张地图的钥匙 【免费下载链接】harnessrouterHarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.项目地址: https://gitcode.com/gh_mirrors/ha/harnessrouter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 HarnessRouter 架构深潜：Console、Gateway、Runner 三层如何协作（附代码地图）
HarnessRouter 架构深潜Console、Gateway、Runner 三层如何协作附代码地图【免费下载链接】harnessrouterHarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.项目地址: https://gitcode.com/gh_mirrors/ha/harnessrouterHarnessRouter 是一个开源的「Agent 统一接口」基础设施它把 Codex、Claude Code、Hermes、PI 等 Agent Harness 装进同一个 Docker 容器用一套 OpenAI Responses 兼容 API 统一调度。它的 Community Edition 由三层组成——Console浏览器控制台、Gateway统一 API 网关、RunnerAgent 执行沙箱。本文带你用 10 分钟看懂这三层的数据流、安全边界并给出一张代码地图帮新手快速上手阅读这个 2.6 万行代码的项目。1. 一图看懂一个容器里的三层分工HarnessRouter CE 最聪明的地方是「单容器、三进程」你只需要docker run一条命令对外只暴露一个端口 3000而 Console、Gateway、Runner 在容器内各司其职。项目 README 里有一张官方架构图README.md┌─ HarnessRouter 容器 ─────────────────────────────────┐ │ Console :3000 ← 唯一对外发布的端口 │ │ │ 同源代理 │ │ ▼ │ │ Gateway :8080 Responses API Harness 生命周期 │ │ │ loopback │ │ ▼ │ │ Runner :8081 在会话工作区中运行各 Harness │ │ │ │ /data 卷数据库 · 文件 · 密钥 · 工作区 │ └─────────────────────────────────────────────────────┘三层职责一句话总结层端口一句话职责Console3000唯一对外给人看的界面 给产品用的统一 API 入口Gateway8080仅 loopback统一 API 大脑路由、会话、流式、文件、取消Runner8081仅 loopback真正干活的「手脚」驱动各 Harness CLI 注意Gateway 和 Runner 只监听回环地址外部流量必须经过 Console。这意味着即使你误把 8080/8081 配错它们也不会暴露到网络上。2. Console你看到的「脸」Console 是基于 Next.js 构建的 Web 应用源码在 ui/src/以output: standalone模式打包进镜像ui/next.config.ts。它对新手来说有两个关键点同源代理你在浏览器里发起的每一个 API 请求都由 Console 原样转发给同容器内的 Gateway默认http://127.0.0.1:8080见 docker/entrypoint.sh。所以你作为集成方只需要记住一个地址——http://localhost:3000既开 UI也调 API。登录即门槛CE 默认账号密码是harnessrouter / harnessrouterProfile 页面可随时改密改密会重启 Console 并让旧会话失效docker/entrypoint.sh。页面路由组织在 ui/src/app/(app)//)按功能分目录tasks/任务、harnesses/Harness 管理、keys/API Key、integrations/模型接入等目录名即功能名非常好找。3. Gateway统一 API 的「大脑」Gateway 是整个项目的核心主入口是 gateway/app.pyFastAPI约 1.7 万行。它实现 UHPUnified Harness Protocol的Full 级能力核心路线有四个发起任务POST /v1/responses。这是你产品后端唯一需要懂的端点。请求体里用metadata.harness_id指定跑哪个 HarnessGateway 负责解析模型授权、路由 backend、续接会话previous_response_id。流式进度SSEServer-Sent Events实时推送 Agent 的思考、工具调用与产出事件。文件与产物上传输入文件、下载 Agent 生成物、打包整个会话工作区。取消与失败cancel_response随时叫停所有失败都带机器可读的错误码而不是让人去解析散文。配套模块也各有分工新手可按职责跳转gateway/backing.py本地模式存储层——SQLite 图数据库 文件 Blob 加密密钥库全部落在/data卷无任何外部依赖。gateway/control_sqlite.py / gateway/control_store.py幂等idempotency、租约lease等控制面状态保证请求重放安全。llm_brokerapp.py 内模型请求「经纪人」把 Agent 的模型调用转发到你接入的模型供应商供应商密钥不出容器。4. Runner真正执行任务的「手脚」Runner 的主入口是 runner/server.pyFastAPI约 8 千行它的工作模式在文件头部的 docstring 中写得非常清楚runner/server.py一轮 一个 CLI一个 turn 对应一次性运行某个 backend CLIclaude、codex、hermes、pi、dsh 等 16 个在会话专属的真实 POSIX 工作区里执行带真实的 bash 和 git。事件归一化每个 Harness 的输出被归一化为统一的事件 schema下游Gateway、Console看到的就是同一种「语言」——这正是「换 Harness 不改产品代码」的技术根基。按会话隔离不是每会话一个容器而是每会话一个工作区 一个操作系统用户uid。文件权限就是隔离墙写进别的会话目录或数据库路径的产物会直接失败。只读项目层runner/environments.py 支持把项目文件与依赖「构建一次、多会话只读挂载」。这些 Agent CLI 并不打包在镜像里而是首次启动时由 docker/ 下的安装脚本装到/data卷如 install-kits.sh装什么、怎么装入口脚本里都有严格的版本钉死与校验。5. 安全边界特权是怎么切开的docker/entrypoint.sh 里有一段值得细读的注释——容器的安全模型由**三个身份principal**构成root仅入口脚本与 Runner 持有。Runner 需要 root 才能为每个 Agent 进程切换 uid用的是 Docker 默认就有的CAP_SETUID等能力无需--privileged。agent产品身份跑 Console、Gateway独占读取/data里的数据库、Blob 和密钥库。20000 的会话 uid每个会话一个只拥有自己的会话目录。它读不到别的会话的工作区、数据库和密钥。配合「只发布 :3000 一个端口」就得到了清晰的纵深浏览器 → Console登录门槛→ GatewayAPI 门槛→ RunnerOS 级隔离每一层都有自己的钥匙。6. UHP让三层对齐的开放协议三层能各改各的、却永远对齐靠的是 protocol/ 下的Unified Harness ProtocolUHP——一个版本化的开放标准。它对架构的定义只有三个角色Client → Server → Harnessprotocol/versions/2026-09-28/architecture.md客户端你的产品、Console只说 UHP不需要知道背后是哪家 Harness服务器Gateway Runner如何执行完全黑盒实现细节不得泄漏到线上格式Harness 以稳定的base字符串codex、claude-code、hermes…被寻址。协议还分 Core / Extended / Full 三档符合性等级并附带 protocol/conformance/ 合规测试套件、protocol/schema/ 下的 OpenAPI 与 JSON Schema。换句话说规范、参考实现、测试三件套齐发改协议必须先过测试。7. 代码地图速查表 ️想找什么直接看这里整体架构与快速上手README.md含架构图与 Quickstart三进程如何拉起、特权如何切分docker/entrypoint.sh统一 API任务/流式/文件/取消gateway/app.py本地存储SQLite Blob 密钥库gateway/backing.pyHarness 驱动与事件归一化runner/server.py只读环境/项目层runner/environments.pyUHP 规范最新 2026-09-28 版protocol/versions/2026-09-28/UHP 合规测试套件protocol/conformance/Console 页面与路由ui/src/app/自托管、升级、备份指南docs/self-hosting-guide.md结语HarnessRouter 的三层设计其实回答了一个朴素的问题「我的产品想跑 10 种 Agent但只愿意维护 1 套接口」。Console 把入口收敛成一个端口Gateway 把 16 种 Harness 的差异吞进统一 APIRunner 用「工作区 独立 uid」把每个会话关进各自的房间。读懂entrypoint.sh的权限布局、app.py的任务路由和server.py的事件归一化这三处你就拿到了这张地图的钥匙 【免费下载链接】harnessrouterHarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.项目地址: https://gitcode.com/gh_mirrors/ha/harnessrouter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考