HomeRail 架构解剖:protocol、Manager、Node、Worker、CLI、agent-ui 六大模块如何协同

原创2026-10-22 21:18:322,281 阅读

HomeRail 架构解剖:protocol、Manager、Node、Worker、CLI、agent-ui 六大模块如何协同

HomeRail 是一个语音优先的本地 Agent 编排运行时(Voice-first local agent orchestration runtime),它把一次性的 Agent 对话变成可审计、可回放、可复用的 DAG 工作流。整个仓库由六大模块组成:共享协议包 homerail_protocol、大脑服务 homerail_manager、容器调度服务 homerail_node、干活容器 homerail_worker、命令行工具 homerail_cli(命令名 hr),以及浏览器界面 agent-ui。本文带你快速看懂这六个模块各自负责什么、数据如何在它们之间流动,以及新手应该从哪里入手阅读源码。

HomeRail 项目图标:语音优先的本地 Agent 编排运行时标识

一张图看懂:六个模块各扮演什么角色

先把结论放上来,官方 README.md 中的架构表是最精炼的说明书:

模块 目录 一句话定位
协议包 homerail_protocol/ 所有运行时通信的"单一事实来源"(Single source of truth)
大脑 homerail_manager/ Manager 服务 + DAG 协调器,拥有语音界面与生成式 UI 契约
调度 homerail_node/ Node 服务,用 Docker 为每个 DAG 节点开通 Worker 容器
执行 homerail_worker/ Worker 运行时,接入 Claude Agent SDK、Codex 等 Agent 后端
命令行 homerail_cli/ hr CLI,配置、运行、检查 DAG 工作流
界面 agent-ui/ 与 Manager 解耦的浏览器 UI,渲染语音界面与 Widget

可以把它类比成一家公司:protocol 是公司的《公文格式规范》,Manager 是总经理,Node 是行政部(负责给每个项目开独立办公室/容器),Worker 是实际干活的员工,CLI 是员工手里的对讲机,agent-ui 则是挂在墙上的电子看板。

protocol:先约定"怎么说话",再谈干活

理解 HomeRail 架构的第一站不是 Manager,而是 homerail_protocol/src/index.ts。这个包被 README 称为"runtime communication 的单一事实来源",Manager、Node、Worker 三个进程之间的每条消息,都必须符合这里的契约:

配套的 homerail_protocol/fixtures/ 目录里放着一整套消息样例 JSON(如 request-message.json、handoff-request.json),是理解各消息长什么样的最佳起点。对新手来说,读 fixtures + schemas 比读业务代码快得多。

Manager:DAG 协调器与"聪明的大脑"

homerail_manager/src/index.ts 启动 Manager 服务,它是整个系统的指挥中心,内部按职责分层:

  • 编排核心 homerail_manager/src/orchestration/:这是最精华的目录,dag-engine.ts(DAG 引擎)、dag-dispatcher.ts(任务分发)、dag-message-router.ts(节点间消息路由)、graph-validator.ts(图结构校验)、graph-executor.ts(执行器)、yaml-loader.ts(加载工作流模板)都在这里;
  • 持久化 homerail_manager/src/persistence/:基于 better-sqlite3 的本地数据库,保存 run、消息与工件引用;
  • HTTP/WebSocket 服务 homerail_manager/src/server/:对外暴露 REST 与 WS 接口(默认端口 19191),CLI 和 UI 都是它的客户端;
  • 生成式 UI homerail_manager/src/generative-ui/:Agent 不再倾倒 JSON 日志,而是按契约生成"一眼可读"的结构化视图;
  • Manager Agent homerail_manager/src/runtime/:能理解自然语言(尤其是语音)并把请求规划成 DAG 的 AI 层,README 当前推荐 Codex(codex_appserver)作为首选 harness。

架构上的一个重要理念写在 README 的 "Smart brain, efficient workers" 一节:昂贵的模型不必事事亲为——每个 DAG 节点拥有独立的上下文窗口,接收交接、完成分内工作、把证据传递下去,而且不同节点可以配置不同的模型(模板里用 provider/model 映射 + "*" 通配回退),让最聪明的模型负责规划与评审,更便宜的模型承担大部分体力活。

Node:给每个 DAG 节点开一个 Docker 容器

Manager 自己不做重活。真正执行节点的是容器化的 Worker,而负责"造容器"的是 homerail_node/src/cli.ts 启动的 Node 服务:

  • Node 依赖 dockerode,通过 homerail_node/src/providers/(Docker CLI / Docker API / Mock 三种 provider)调度和构建 homerail-worker:latest 镜像;
  • 一个 DAG 节点对应一个 Worker 容器,同一 run 的所有 Worker 共享 ${HOMERAIL_HOME}/workspace/<run_id> 工作区,既隔离又便于审计;
  • homerail_node/src/lifecycle/ 下的 create.ts / start.ts / stop.ts / remove.ts 完整覆盖了容器的生命周期管理;
  • Worker 容器通过 Manager 下发的回调 URL 建立 WebSocket 回连(Linux 上通常要处理 host-gateway 或 HOMERAIL_MANAGER_WORKER_WS_BASE_URL),远程连接则要求认证过的 wss:// 端点,见 docs/control-plane-security.md。

Worker:真正"动手"的 Agent 运行时

homerail_worker/src/index.ts 是 Worker 的入口,逻辑非常直接:读取环境变量 → 通过 homerail_worker/src/ws-client.ts 连接 Manager 的 WebSocket → 把任务交给 homerail_worker/src/prompt-runner.ts 执行。

值得注意的几处设计:

CLI:新手最常打交道的 hr 命令

homerail_cli/src/cli.ts 用 commander 注册了所有子命令,实现分布在 homerail_cli/src/commands/,每个文件对应一个命令,结构非常清晰。日常操作的典型路径:

命令 作用 源码
hr start <a href="https://link.gitcode.com/i/9ae8912ab00c06a66f830e6b71f0f687" target="_blank">--ui] 一起拉起 Manager(和 UI) [runtime.ts
hr doctor 体检:Manager 可达性、Node、模型配置 doctor.ts
hr run <模板> 运行一个 DAG,返回 run_id run.ts
hr dag supervise <run_id> 实时观看节点交接流转 dag-supervise.ts
hr scorecard / hr eval-run 给一次运行打分、做运行评估 scorecard.ts
hr replay 回放一次运行,可审计可复现 replay.ts

官方还刻意把 README 写成"agent 可读的 runbook":你完全可以把自己信任的编码 Agent(Claude Code、Codex 等)当"规划者",让它直接驱动 hr CLI 完成规划、运行、检查、迭代的闭环,跳过 Manager Agent 层但保留完整的 DAG 审计能力。相关技能说明见 skills/homerail-cli/SKILL.md。

agent-ui:解耦的浏览器看板

agent-ui/ 是一个独立的 Vue 3 + Vite 工程,默认由 hr start --ui 在 https://localhost:19192 拉起,通过 homerail_cli/src/static-ui-server.ts 和 homerail_cli/src/ui-admin-proxy.ts 静态托管并代理到 Manager,因此它与 Manager 完全解耦、可以独立构建部署。

主要看点:

一次 run 的完整旅程:六个模块如何串联

以 README Quickstart 里的两节点模板为例,把整条链路走一遍:

  1. CLI 发起:hr run assets/orchestrations/public-two-node.yaml.template --profile offline-deterministic --prompt "...",命令经 homerail_cli/src/client.ts 打到 Manager 的 REST 接口,拿回 run_id;
  2. Manager 校验与编排:yaml-loader 载入模板,graph-validator 校验图结构,dag-engine 创建 run 并落库(persistence),dag-dispatcher 决定调度哪些节点;
  3. Node 开容器:Manager 通知 Node,Node 用 Docker 为每个 DAG 节点拉起一个 Worker 容器,注入共享工作区与回调地址;
  4. Worker 执行:容器内 Worker 连接 Manager WS,按 protocol 契约接收节点配置,由所选 Agent 后端(Claude/Codex/Kimi…)执行任务,流式上报活动事件;
  5. 交接与流转:dag-message-router 把每个节点的产物按边路由给下游节点,全程消息可查、run 可回放(hr replay)、可打分(hr scorecard);
  6. UI 呈现:agent-ui 订阅实时事件与 Surface 补丁,把进度渲染成人类友好的看板或生成式视图——而不是让你盯日志。

用 README 的话概括就是:"聊天会话是黑盒,DAG 是一张你可以检查、回放和改进的图",HomeRail 就站在两者之间——人的入口窄(一句语音/一句话),机器的一侧宽(多 Agent、多模型、多环境)。

模块资料速查清单

想理解什么 从哪里看
模块职责总表 README.md 的 Architecture 一节
消息契约与样例 homerail_protocol/src/、homerail_protocol/fixtures/
DAG 引擎与分发 homerail_manager/src/orchestration/
工作流模板写法 docs/dag-workflow-spec-v1-overview.zh-CN.md、docs/workflow-spec-v1-authoring.md
多轮 DAG 与恢复 docs/multi-round-dags.md
架构专题(live steering、durable actors 等) docs/architecture/
CLI 命令技能手册 skills/homerail-dag-ops/SKILL.md
插件体系 homerail_plugin_sdk/src/、plugins/builtin/

总结:给新手的阅读顺序建议

  1. 先读 README.md 的 Quickstart,跑通 hr start → hr doctor → hr run(离线确定性 profile)这条最小闭环;
  2. 再对照本文的表格,按 protocol → Manager(orchestration) → Node → Worker → CLI → agent-ui 的顺序浏览入口文件,每个模块只需读 index.ts / cli.ts 就能建立骨架认知;
  3. 想深入某条线时,用 hr dag supervise <run_id> 实时观察节点交接,同时翻 homerail_protocol/fixtures/ 里的样例消息,"现场 + 契约"对照着看,比硬啃源码效率高得多。

这套架构最值得借鉴的点在于:把"通信契约"抽成独立包先行固化,让大脑(Manager)、手脚(Node/Worker)和界面(CLI/UI)可以独立演进、甚至由不同的模型和进程实现,而审计、回放、评分这些"可运维性"能力从第一天就内建在 DAG 运行时里——这正是 HomeRail 想解决的核心问题:让人类的注意力尽量少地参与,同时让机器做的每一件事都可被检查。

登录后查看全文
homerail