Happier整体架构设计解析:如何构建一个多设备AI Agent编排系统
Happier整体架构设计解析:如何构建一个多设备AI Agent编排系统
Happier 是一个开源、可自托管、端到端加密的 AI Agent 编排系统,把 Claude Code、Codex、OpenCode、Pi 等主流编程智能体统一纳入一个"多设备控制室":在桌面端发起会话,在手机上批准权限,在浏览器里审查 diff,让你名下的每一台机器并行跑 Agent 任务。本文拆解它的整体架构设计,看看一个多设备 AI Agent 编排系统是如何搭起来的。
先搞清楚:Happier 解决了什么问题
编程智能体正成为开发者的日常工具,但它们的运行方式有个天然局限:被锁死在一台机器的一个终端里。Agent 在跑,你必须守在电脑前盯着;换个地方,就得中断它。
Happier 的思路不是再造一个 Agent,而是做一个编排层:
- 所有编码 Agent(Claude Code、Codex、OpenCode、Pi,以及 30+ 个 ACP 协议 Agent)继续在你自己的机器上、用自己的订阅运行;
- Happier 负责会话的多设备同步、权限审批、跨 Agent 协作和代码审查;
- 中继服务器只做转发,且内容端到端加密——官方称之为 "multi-device control room to orchestrate teams of 100+ coding agents"。
一句话概括它的架构哲学:客户端加密 → 盲中继 → 本机守护进程 → 本地 Agent,四段接力。
架构总览:一个"看不见的中继"设计
官方 README 中用一张极简的 ASCII 图概括了数据流(见 README.md):
Phone / Desktop / Browser
│
▼
Happier relay (hosted or yours) ← 只存转发"读不懂"的加密数据
│
▼
Your machines (laptop, VPS, dev box)
│ daemon 在代码所在处拉起 Agent
▼
Claude Code · Codex · OpenCode · Pi ...
每个 Agent 直连自己的模型服务商
这个设计有三个值得注意的取舍:
- 中继无状态化:服务器不理解内容,只处理路由必需的元数据(会话 ID、时间戳、回合状态、用量),因此可以托管也可以一条命令自托管(
happier relay host install); - 模型流量不过中继:每个 Agent 直连自己的模型服务商,Happier 不碰 token 费用,也不成为推理瓶颈;
- 守护进程贴近代码:真正执行任务的进程(daemon)跑在"代码所在的地方",而不是集中在一台服务器上。
五层拆解:每一层负责什么
1️⃣ 客户端层:手机、桌面、浏览器、终端平权
Happier 的客户端不是"一个 App 加几个附属",而是四个平权入口:
| 入口 | 位置 | 形态 |
|---|---|---|
| 移动端 | apps/ui/ | React Native + Tauri 一套代码,iOS / Android / 桌面 |
| Web 端 | 同 apps/ui |
浏览器直连中继 |
| CLI | apps/cli/ | 交互式工具 + 后台会话管理器 |
| 守护进程 | apps/cli 内的 daemon |
后台常驻,托管 Agent 进程 |
移动端界面与桌面端完全同源,登录同一账号后"你的会话、机器和设置已经在那了":
CLI 的入口是 apps/cli/src/index.ts,负责解析子命令(auth、connect、codex、默认运行流),本地状态(settings、access key、daemon 状态)持久化在 ~/.happy 下,实现见 apps/cli/src/persistence.ts。整体结构在 docs/cli-architecture.md 中有完整文档。
2️⃣ 中继层:一台"读不懂"的服务器
中继服务器(apps/server/)是整套系统的同步中枢,技术栈刻意保持朴素:Fastify 处理 HTTP,Socket.IO 处理实时,Postgres(Prisma)存状态,S3/MinIO 存大对象(见 docs/backend-architecture.md)。
它的启动流程很直白(入口 apps/server/sources/main.ts):
- 连接 Postgres,初始化在线状态缓存;
- 初始化加密模块(KeyTree、S3 桶校验、token 签发器);
- 启动 API 服务器(apps/server/sources/app/api/api.ts)+ 指标服务器 + 在线状态超时循环。
真正体现设计功力的是事件路由(apps/server/sources/app/events/eventRouter.ts)。每条 Socket.IO 连接按"作用域"打标:
user-scoped:接收该账号的全部更新(手机/桌面 App);session-scoped:只接收某一个会话的更新(专注模式);machine-scoped:守护进程专用,收发机器状态。
事件分两类:update(持久) 带用户级单调序列号 seq,断线重连后可按序补齐;ephemeral(瞬时) 承载在线状态、用量信号,不落库。完整事件目录在 docs/protocol.md。
3️⃣ 机器层:守护进程让"任何一台机器"成为算力节点
每台接入的机器上跑着一个 Happier daemon。它通过 machine-scoped 连接上报 machine-alive 心跳与机器状态,同时在本机拉起和托管 Agent 进程。这就是"多设备"里"多设备跑任务"的关键——任务不迁移,任务可以分发:
- 新机器一条命令接入:
happier machine setup --ssh user@host; - 会话可以整段移交给另一台机器(session handoff),甚至把工作树一起带走;
- 心跳有合并写入策略(presence 模块),保证高并发下数据库不被心跳打爆。
4️⃣ Agent 执行层:用 ACP 统一 30+ 种 Agent
这是 Happier 最有辨识度的设计。不同厂商的 Agent(Claude Code、Codex、OpenCode、Pi……)接口各异,packages/agents/ 这个共享包把它们抽象成统一的运行时:
- 以 ACP(Agent Client Protocol) 为通用协议,任何会说 ACP 的 Agent 都能从设置里直接添加;
- 原生适配的 Agent 走各自的 runner,未适配的走 ACP 桥接;
- 会话内能力(工具调用、权限请求、流式输出)被归一化,客户端只面对一套 UI 语义。
这层直接支撑了两个高阶玩法:跨 Agent 子代理(Claude 把审查任务委托给 Codex 子代理)和会话中途切换 Agent(换引擎,同一会话继续,回来的 Agent 只补它错过的上下文)。
5️⃣ 横向共享包:协议、加密、运行时
跨四个客户端与服务器复用的能力被抽成了独立包:
| 包 | 职责 |
|---|---|
| packages/protocol/ | 线上协议的唯一事实来源:事件形状、系统任务契约、类型定义(742 个源文件) |
| packages/privacy-kit/ | 认证 token 生成/校验、加密服务 token |
| packages/agents/ | Agent 目录、ACP 适配、运行时选择 |
| packages/relay-server/ | 自托管中继运行时 |
| packages/cli-common/ | CLI 与桌面引导流程共享的任务系统 |
"协议即包"意味着四个端永远不会各说各话——新字段、新事件先在 protocol 包里立约,再由各端消费。
多设备实时同步:一个会话如何同时出现在三块屏幕
把"手机批准权限 → 桌面端立即响应"变成可能,靠的是三个协议原语(设计动机完整记录在 docs/protocol.md):
- 单调序列号:每个用户有一个
Account.seq全局计数器,所有持久update按seq排序下发。客户端"按序应用即一致",重连后从最后seq补齐即可,天然支持离线队列; - 乐观并发:所有会被多方修改的字段(会话元数据、Agent 状态、KV 存储)都要求
expectedVersion,版本冲突时服务器回传当前版本和数据,冲突解决权在客户端——避免"手机和桌面同时改,后者静默覆盖前者"; - 持久/瞬时分离:必须能在重连后恢复的走
update,在线状态和用量走ephemeral。这样数据库不存噪音,事件流不存垃圾。
协议还刻意保持"小表面积":路由以 GET + POST 为主,不追求完整 REST 动词集——因为多数操作(发一条消息、改模型、启动审查)本质是动作而非实体变更。
端到端加密:为什么服务器是"盲邮差"
Happier 的加密边界在 docs/encryption.md 中有完整定义,核心原则是让服务器对内容失明(数据机密性模型见 docs/backend-architecture.md#L318-L356):
- 会话元数据、消息内容、Agent 状态、KV 值全部在客户端加密后以 base64 不透明块形式上行,服务器只存转发;
- 内容加密支持两套方案:旧版 NaCl secretbox(XSalsa20-Poly1305)和新的 AES-256-GCM 数据密钥方案(按会话/机器持有独立 DEK,DEK 本身再用临时密钥对包裹),二进制布局在文档中精确到字节;
- 服务器仅对服务 token(如 GitHub OAuth token)使用主密钥 KeyTree 加解密——这是它与内容加密唯一交叉的地方。
结果就是那张极简的信任图:用户内容 → 加密块 → Postgres;路由元数据 → 服务器可读。托管版与自托管版跑的是同一套代码、同一套加密,自托管者只是换掉了存储策略的决策人。
跨 Agent 协作:让 Claude 给 Codex 的代码做审查
多数 Agent 工具是"单人单会话",Happier 把编排做成了系统能力,这也是"AI Agent 编排系统"这个词的实义:
- Subagents 跨 Agent 启动:任何会话都能向另一个 Agent 发起 review / plan / delegate 任务并读回结果——Claude 把审查交给 Codex,Codex 把活拆给 Claude,配对随意;
- 中途换引擎:同一会话从 Claude Code 切到 Codex,换入的 Agent 自动恢复自己的线程、只接收缺失上下文;
- 并行会话:不限数量,每个会话独立指定机器、目录、Agent、模型。
下面这张图展示的就是"会话分叉"的交互:原生分叉、重放分叉、或带全新配置(换 Agent/模型/机器)迁移整段对话:
支撑这一切的是动作注册表:Happier 能做的每个动作(新建会话、发消息、设模型、启动审查)只定义一次,App、斜杠命令、语音、CLI 和外部 MCP 宿主调用的是同一份定义,并且每个动作可单独配置"哪些入口可执行、哪些必须先问你"。
仓库结构导航
| 目录 | 一句话说明 |
|---|---|
| apps/ui/ | 移动端 + 桌面端 + Web,React Native / Tauri 多端统一 |
| apps/cli/ | CLI、守护进程、各 Agent runner |
| apps/server/ | 中继服务器:API、Socket.IO、事件路由、Prisma |
| apps/bootstrap/ | 桌面端引导系统(hsetup),一键接管本机 CLI 与守护进程 |
| packages/protocol/ | 线上协议契约的唯一来源 |
| packages/privacy-kit/ | 端到端加密与认证 token 基建 |
| packages/agents/ | Agent 目录与 ACP 适配层 |
| packages/relay-server/ | 自托管中继 |
| docs/ | 架构、协议、加密、CLI 等全套工程文档 |
架构文档入口推荐先读 docs/backend-architecture.md(服务器)和 docs/cli-architecture.md(CLI 与守护进程),两份文档都带 mermaid 流程图。
总结:这套架构给我们留了什么
如果抛开产品外壳,Happier 的架构设计里有五个可以直接复用的模式:
- "盲中继 + 客户端加密":服务器不理解内容,只理解路由元数据,隐私承诺和可审计性同时成立;
- 单调 seq + 乐观并发:比向量时钟轻得多,却足以支撑多设备写冲突,实现成本极低;
- 持久/瞬时事件分离:让同步流和状态库各自干净,重连语义清晰;
- 协议即共享包:多端一致性不靠纪律靠构建——字段契约在编译期就收敛;
- 用统一协议(ACP)吃掉 Agent 碎片化:新 Agent 接入是配置而非开发,这是"编排 100+ Agent"能成立的底层原因。
多设备 AI Agent 编排的难点从来不是"把消息转发出去",而是同步、权限、加密与多 Agent 异构四件事同时做对。Happier 给出的答案,是一个可以自托管、可以整体阅读的开源范本。





