OpenRig守护进程架构深度解析Hono HTTP Daemon如何成为本地控制平面【免费下载链接】openrigBuild your own network of agents from Claude Code, Codex and Pi: persistent teams with roles, shared context and owned work.项目地址: https://gitcode.com/GitHub_Trending/op/openrigOpenRig守护进程是开源项目 OpenRig 的核心引擎它基于 Hono 框架在本地监听 7433 端口把 Claude Code、Codex 等编码代理组成的智能体团队统一收进一个本地控制平面Control Plane。守护进程用 SQLite 持久化团队状态、用 tmux 托管每个代理会话并对外暴露 69 个 HTTP 路由——rig命令行、TUI 终端界面和 MCP 服务器全部通过本地 HTTP 与它对话。本文将从新手视角拆解这套 Hono HTTP Daemon 架构启动流程、路由分层、事件流与安全边界并附上源码路径方便你深入阅读。 一张图看懂守护进程在系统中的位置OpenRig 的设计哲学是代理本身不改一行代码OpenRig 只负责它们周围的协调。所有客户端CLI / TUI / MCP / Web UI都不直接操作代理而是把请求发给守护进程由它统一调度 tmux 会话、消息队列与上下文投影CLI / TUI / MCP 服务器 │ 本地 HTTP默认端口 7433 ▼ server.ts 的 createApp()中间件 /healthz 69 个 /api/* 路由 │ ┌────┴─────────────┬──────────────┐ SQLitedb/ tmux 适配器adapters/ 运行时适配器 ×5 claude-code / codex / pi / terminal / stub完整的请求链路说明见 ARCHITECTURE.md其中还附有一个可自查的关键数字表格。 启动流程守护进程如何唤醒理解架构最快的入口是进程入口 index.ts它只做三件事解析监听地址——通过 resolveBindPlan 决定绑定 loopback 还是 Tailscale 接口调用 createDaemon()——定义在 startup.ts负责打开 SQLite 数据库WAL 模式、启用外键、执行migrate(db, ALL_MIGRATIONS)全部 89 个迁移、构造所有服务与适配器再交给 server.ts 的createAppWithWebSocket(deps)运行周期性清扫任务——队列保留清理、卡死队列扫描与唤醒阶梯wake ladder在入口内按固定节拍轮转。一个细节值得新手注意入口还定义了 HEARTBEAT_INTERVAL_MS 5_000 的心跳常量用于守护进程的生命周期存活性上报——CLI 的rig daemon系列命令就靠它判断守护进程是否还活着。️ Hono 应用骨架一个中间件 69 个路由挂载packages/daemon/src/server.ts 是整个控制平面的总装配车间。createApp(deps)的开头有一组硬性不变量校验所有领域服务必须共享同一个 SQLite 句柄否则直接抛错server.ts#L434-L485从根上杜绝两套状态的经典 bug。随后核心就三步app.use(*)全局中间件把每个服务注入请求上下文c.set(rigRepo, ...)等路由层随取随用见 server.ts#L492-L538/healthz健康检查端点供 CLI 与监控系统探活app.route(/api/area, ...)挂载 69 个路由模块未匹配的/api/*路径返回 JSON 404其余 GET 请求则回落到 Web UI 的构建产物——API 与前端共享同一个端口无需额外静态服务器。routes/目录下共有 67 个文件、其中 65 个创建 Hono 路由器。以 routes/ps.ts 为例它只是从上下文取出psProjectionService并把条目序列化成 JSON——路由保持薄行为下沉到 domain 层这是新手阅读源码时最值得记住的分层约定。️ SQLite让团队状态在重启后依然在线守护进程的全部状态存放在$OPENRIG_HOME默认~/.openrig下的openrig.sqlite路径解析逻辑在 daemon-db-path.ts。数据库层位于 packages/daemon/src/db/connection.ts负责连接migrate.ts负责按名称排序执行迁移并把已应用记录写入schema_migrationsall-migrations.ts汇总当前 89 个迁移文件。这个设计带来两个对新手友好的特性状态是持久的队列里的任务、快照、会话登记都落库守护进程崩溃或重启后rig restore能把代理原样接回来迁移是幂等且向前兼容的已应用过的迁移永不重跑旧安装升级时只对真实数据增量执行新迁移——所以仓库规范明确要求改行为加新迁移而不是改旧迁移ARCHITECTURE.md#L166-L181。 事件流TUI 如何实时感知每个代理的动态控制平面不只是请求-响应。routes/events.ts 用 Hono 的streamSSE实现了带断点续传的服务端事件流客户端连接时携带Last-Event-ID守护进程先订阅实时事件总线保证无间隙再从数据库重放错过的事件最后按单调序号推送实时事件。TUI 正是订阅/api/activity/events这条流才能让拓扑图上的状态指示灯与上下文百分比实时跳动 安全边界默认 loopbackBearer 令牌兜底控制平面掌握着能替你操作代理的权力middleware/auth-bearer-token.ts 划定了清晰的边界默认只听 loopback检测到 Tailscale 接口时才允许远程绑定非 loopback 绑定 空 Bearer 配置 → 拒绝启动把裸奔暴露挡在门口令牌比较使用 Node 的crypto.timingSafeEqual做常量时间比较auth-bearer-token.ts#L36-L51防止时序侧信道。对本地单人使用场景这套最小权限 纵深防御的组合比引入完整 OAuth 更务实也是新手可以直接借鉴的取舍。️ 多前端同一平面CLI、TUI、MCP 与 Web UI同一个守护进程同时服务四类客户端这是控制平面价值的关键证明前端与守护进程的连接方式源码位置rigCLIDaemonClient走 HTTPpackages/cli/src/client.tsTUIHTTP 读投影 SSE 事件流packages/tui/src/daemon-client.tsMCP 服务器18 个工具复用同一DaemonClientpackages/cli/src/mcp-server.tsWeb UI守护进程直接托管构建产物packages/ui/在 Web UI 中你可以从 Explorer 选择 rig 查看它的实时拓扑甚至直接点 CMUX 按钮打开编排者的终端窗口守护进程还会把技能与上下文投影到每个代理的 tmux 工作区——5 个运行时适配器claude-code、codex、pi、terminal、stub各自实现RuntimeAdapter接口位于 packages/daemon/src/adapters/这就是同一套控制平面驱动不同代理运行时的扩展点。 关键数字速查来自官方架构文档指标数量出处数据库迁移89packages/daemon/src/db/migrations/routes/ 文件 / 其中 Hono 路由器67 / 65packages/daemon/src/routes/app.route(...)挂载点69server.ts顶层rig命令85packages/cli/src/index.ts运行时适配器5packages/daemon/src/adapters/守护进程 npm 依赖hono、better-sqlite3、hono/node-ws 等package.json#L80-L89️ 想扩展守护进程改哪里ARCHITECTURE.md 提供了按配方改代码的指引核心动作都是三到四处编辑加路由在routes/新建一个薄路由器 → 在server.ts的 404 兜底之前app.route挂载 → 用app.request(...)写单测加服务AppDeps加字段 server.ts加一行c.setstartup.ts里构造它加迁移新建编号最大的NNN_名称.ts导入all-migrations.ts并同步测试夹具清单。依赖面也很克制package.json 的核心依赖只有 Hono、better-sqlite3、hono/node-ws 与几个工具库——控制平面的心脏其实很小。✅ 小结为什么这套架构值得学习OpenRig守护进程用一个Hono HTTP Daemon就完成了本地控制平面的四个关键职责持久状态SQLite 迁移、实时性SSE 事件流 心跳、多前端复用一个端口服务 CLI/TUI/MCP/Web、最小攻击面loopback 优先 Bearer 兜底。对新手而言它提供了一个可完整通读的范本入口、装配、路由、领域、适配器层层分明且每一层都有测试与文档锚定。从 packages/daemon/src/index.ts 开始顺着读下去你就能看到智能体团队是如何从一堆终端会话变成一支有角色、有共享上下文、有持久工作的rig。【免费下载链接】openrigBuild your own network of agents from Claude Code, Codex and Pi: persistent teams with roles, shared context and owned work.项目地址: https://gitcode.com/GitHub_Trending/op/openrig创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考