HomeRail 架构解剖:protocol、Manager、Node、Worker、CLI、agent-ui 六大模块如何协同
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。本文带你快速看懂这六个模块各自负责什么、数据如何在它们之间流动,以及新手应该从哪里入手阅读源码。
一张图看懂:六个模块各扮演什么角色
先把结论放上来,官方 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/src/types.ts 和 homerail_protocol/src/validation.ts(基于 zod/ajv)定义并校验所有线上消息;
- 编解码:homerail_protocol/src/codec.ts 负责消息的序列化/反序列化;
- 版本兼容:导出常量
WORKER_CONTRACT_VERSION是 Manager 与 Worker 之间的兼容契约版本号,只有当线上契约发生不兼容变化时才会递增——这与产品发布版本刻意解耦,方便异构节点混跑; - 专项契约:DAG 活动事件(dag-activity.ts)、DAG 节点 Surface 补丁与媒体流、Manager Agent 工具定义(manager-agent-tools.ts)、生成式 UI(homerail_protocol/src/generative-ui/)等。
配套的 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 执行。
值得注意的几处设计:
- 多后端支持:homerail_worker/src/agent/ 下的 backend-selection 等文件负责选择 Agent 后端,依赖里同时接入了
@anthropic-ai/claude-agent-sdk、@openai/codex、Kimi 等,对应"不同节点不同模型"的能力; - 凭证投影:homerail_worker/src/credential-projection.ts 实现凭据的安全投影,API Key 存在 Manager 的加密配置里,而不是散落在容器或仓库文件里;
- 控制面安全:homerail_worker/src/control-plane-security.ts 与仓库根的 docs/control-plane-security.md 共同定义 token、反代与证书边界。
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 完全解耦、可以独立构建部署。
主要看点:
- agent-ui/src/views/ 与 agent-ui/src/components/:语音界面(Voice Surface)与消息流的渲染;
- agent-ui/src/generative-ui/:与 Manager 的 generative-ui 契约对接,渲染 Agent 实时生成的视图而非原始 JSON;
- agent-ui/src/api/clients/:REST/WS 客户端,直接消费 protocol 包的类型定义。
一次 run 的完整旅程:六个模块如何串联
以 README Quickstart 里的两节点模板为例,把整条链路走一遍:
- CLI 发起:
hr run assets/orchestrations/public-two-node.yaml.template --profile offline-deterministic --prompt "...",命令经 homerail_cli/src/client.ts 打到 Manager 的 REST 接口,拿回run_id; - Manager 校验与编排:
yaml-loader载入模板,graph-validator校验图结构,dag-engine创建 run 并落库(persistence),dag-dispatcher决定调度哪些节点; - Node 开容器:Manager 通知 Node,Node 用 Docker 为每个 DAG 节点拉起一个 Worker 容器,注入共享工作区与回调地址;
- Worker 执行:容器内 Worker 连接 Manager WS,按 protocol 契约接收节点配置,由所选 Agent 后端(Claude/Codex/Kimi…)执行任务,流式上报活动事件;
- 交接与流转:
dag-message-router把每个节点的产物按边路由给下游节点,全程消息可查、run 可回放(hr replay)、可打分(hr scorecard); - 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/ |
总结:给新手的阅读顺序建议
- 先读 README.md 的 Quickstart,跑通
hr start→hr doctor→hr run(离线确定性 profile)这条最小闭环; - 再对照本文的表格,按 protocol → Manager(orchestration) → Node → Worker → CLI → agent-ui 的顺序浏览入口文件,每个模块只需读
index.ts/cli.ts就能建立骨架认知; - 想深入某条线时,用
hr dag supervise <run_id>实时观察节点交接,同时翻 homerail_protocol/fixtures/ 里的样例消息,"现场 + 契约"对照着看,比硬啃源码效率高得多。
这套架构最值得借鉴的点在于:把"通信契约"抽成独立包先行固化,让大脑(Manager)、手脚(Node/Worker)和界面(CLI/UI)可以独立演进、甚至由不同的模型和进程实现,而审计、回放、评分这些"可运维性"能力从第一天就内建在 DAG 运行时里——这正是 HomeRail 想解决的核心问题:让人类的注意力尽量少地参与,同时让机器做的每一件事都可被检查。