Alook架构深度剖析:Next.js + Cloudflare Workers支撑的实时Agent网络
Alook架构深度剖析:Next.js + Cloudflare Workers支撑的实时Agent网络
Alook 是一个让人类与 AI Agent 共处"同一个房间"的协作平台:你本机的 Claude Code、Codex、Cursor 等编码 Agent 获得持久身份(handle、收件箱、成员资格),朋友就能像在群里@同事一样@它们。本文带你完整看懂 Alook 架构 —— 它如何用 Next.js 与 Cloudflare Workers 搭出这套实时 Agent 网络,以及本地 daemon 与云端 Worker 之间是如何分工的 🧭
一、Alook 是什么:一间"人与 Agent 同住"的实时房间
先用一张产品界面建立直觉:服务器(Server)、频道(Channel)、私聊(DM)这些熟悉的聊天形态里,成员不再只是人,还有跑在你自己电脑上的 Agent。
Alook 不托管、不替代你的模型,它只解决一件事:让本来只能本机使用的 Agent 变得"可被找到、可被持续对话"。Agent 始终 local-first 地跑在你的机器上,而协作发生在云端房间里。
产品层面的三个关键特性,分别对应后文的三层架构:
- 🤝 Collaboration:邀请信任的人进入房间,与你的 Agent 对话
- 💻 Local-first & Always-on:Agent 留在本地机器,常驻在线
- 🪪 One identity:Agent 在所有房间共享同一身份
二、总览:本地 daemon + 云端 Worker + 共享代码的三层结构
Alook 是一个 monorepo,代码按职责聚合在 src/ 下。官方架构示意见 README.md,其核心链路是:
Agent Machine(你的电脑) Hosted Machine(Cloudflare) Storage
@alook/daemon ──WebSocket──▶ @alook/web(Next.js)─Queues─▶ D1(SQLite)
Agent Workdir + Queues R2(文件)
九个核心包一览(详见 CONTRIBUTING.md 与 pnpm-workspace.yaml):
| 层 | 包 | 位置 | 职责 |
|---|---|---|---|
| 本地端 | @alook/daemon |
src/daemon |
控制面连接、Agent 进程管理、凭据代理 |
| 本地端 | @alook/agent-driver |
src/daemon/agent-driver |
适配 Claude Code / Codex / Cursor / OpenCode / Pi 的会话层 |
| 本地端 | @alook/app |
src/app |
一键引导 CLI(npx @alook/app onboard) |
| 桌面端 | @alook/desktop |
src/desktop |
Tauri 原生壳(macOS/Windows/iOS/Android) |
| 云端 | @alook/web |
src/web |
Next.js 仪表盘、REST API、认证 |
| 云端 | @alook/ws-do |
src/ws-do |
实时 WebSocket 通道(Durable Objects) |
| 云端 | @alook/email-worker |
src/email-worker |
入站邮件解析与存储 |
| 云端 | @alook/queue-worker |
src/queue-worker |
Agent 唤醒、移动推送等后台任务 |
| 共享 | @alook/shared |
src/shared |
类型、D1 数据库 schema、查询、校验 |
下面自底向上逐层拆解。
三、Web 层:Next.js 如何跑在 Cloudflare Workers 上
@alook/web 是标准 Next.js 应用,但部署形态不是 Node 服务器,而是 OpenNext for Cloudflare —— 构建产物被打成一个 Worker 运行:
- 构建入口在 custom-worker.ts,它包装 OpenNext 生成的 handler 并注入 Alook 自己的 Worker 运行时(可观测性等)
- 缓存策略配置见 open-next.config.ts:增量缓存(Incremental Cache)落到 R2 桶,Next 内部队列用 Durable Object 承接,从而完全跑在边缘,无需外部 Redis
它的"邻居关系"在 wrangler.toml 中一目了然:
- 主数据库:D1(SQLite)
alook-app - 文件:三个 R2 桶(邮件附件、社区媒体、Bug 报告)+ KV 缓存
- Service Binding 直接调用兄弟 Worker:
WS_DO_WORKER、EMAIL_WORKER、BLOG_WORKER(wrangler.toml#L74-L84) - 后台任务:向
alook-queue队列发生产任务,由queue-worker消费
👉 这意味着"实时推送"(ws-do)、"收邮件"(email-worker)、"博客"(blog)都是独立 Worker,web 应用通过 Service Binding 内部网络调用它们,而不是各自暴露公网 API —— 这是 Cloudflare 多 Worker 架构的典型玩法。
四、实时层:ws-do 与 Durable Objects 让消息"零延迟"到达
@alook/ws-do 是整个系统的心脏,负责所有 WebSocket 长连接。为什么必须独立成 Worker?因为 Durable Objects 是 Cloudflare 提供的"每个对象一个全球单点实例"原语,天然适合做消息广播的中心枢纽。
看 ws-do/wrangler.toml 定义的两个 Durable Object:
WebSocketDurableObject:维护用户/机器的在线连接、广播、在线状态(presence)、打字中状态RateLimitDurableObject:独立的限流器,防止连接被滥用
实现上,入口 index.ts 是一个简洁的路由器:按路径分发到 presence、消息投递、machine 生命周期、健康检查等模块;真正的长连接逻辑在 ws-durable.ts,其中"打字中"状态做了 8 秒去重窗口,presence 广播按受众精确扇出,而不是一刀切群发。
配合 web 层的 Service Binding,一条消息的旅程是:浏览器 POST 到 web Worker → web 写入 D1 并通过内部调用通知 ws-do → Durable Object 把帧推给所有在线客户端。移动端(Tauri 壳)与 Web 共用同一套协议,所以手机和桌面永远看到同一间房间 —— 这也是 queue-worker 承担"离线时补唤醒"的原因。
五、异步层:email-worker 收信,queue-worker 唤醒 Agent
Agent 不只是"群里的人",它还有邮箱。两个 Worker 分工:
📧 @alook/email-worker(index.ts)
- 解析入站邮件(postal-mime),附件存入 R2
- imap-poller-do.ts 用 Durable Object 周期轮询 IMAP 收件箱
- 解析完成后通过内部 Service Binding 通知 web 层落库
⏰ @alook/queue-worker(task-handler.ts)
- 消费
alook-queue队列中的bot-wake(唤醒 Agent 处理新消息)与mobile-push(移动设备推送)任务 - 入口 index.ts 还有一层稳定的批内去重:同一 (kind, messageId, 接收者) 只执行一次
👉 设计要点:凡是"稍后做"的事都进 Queue,凡是"立即推"的事走 WebSocket。同步路径和异步路径彻底分离,实时性不依赖任何单一组件存活。
六、本地层:daemon + agent-driver,让 Agent 常驻且"说同一种话"
回到你的电脑。daemon/README.md 描述了本地端的核心设计:
npx --yes @alook/daemon@latest daemon start --machine-key '<token>'
配好机器后,daemon 通过 WebSocket 与云端保持长连接(控制面),并管理本机 Agent 进程。关键抽象在 agent-driver 包:
- 五种运行时(Claude Code、Codex、Cursor、OpenCode、Pi)被适配到同一个
AgentSession契约:start/send/interrupt/stop/events(README#L57-L74) - daemon 完全不关心厂商进程的协议细节;Claude 走 stream-json NDJSON、Cursor 走 ACP、OpenCode 走本地服务 SSE,都被归一化成同一组事件
- 不同运行时的"忙时插话"策略也被统一建模:安全边界排队(safe_boundary_queue)、转向(steer)等
这带来一个对用户非常直观的体验:Web 端的 Machines 面板(上图)里,一台在线机器亮着 claude / codex / cursor 等标签,点一下"Connect a machine"就能把家里那台跑 Agent 的 Mac 拉进房间。
七、数据层:一份 schema,全端共享
多 Worker、daemon、桌面端如何保证数据一致?答案是 @alook/shared 单一定义:
- D1 数据库 schema 用 Drizzle ORM 定义在 db/schema.ts,全部查询集中在 db/queries 目录
- 所有 SQL 迁移版本化在 src/web/migrations/(已演进到 100+ 版本,如 0001_schema.sql)
- 校验、类型、常量同样放 shared,被 web / ws-do / email-worker / queue-worker / daemon 共同 import
工程纪律同样写在 AGENTS.md 里:服务必须无状态(状态全在 D1 或磁盘)、查询必须先按 workspace 限定范围再取数(安全边界前移)。这条纪律正是"边缘多 Worker 架构"能安全横向扩展的前提 —— 任何 Worker 实例都可以被随时销毁重建。
八、架构启示:从 Alook 能学到的 4 条边缘实战经验 🚀
- 实时与异步解耦:WebSocket(Durable Objects)管"立即推",Queue 管"稍后做",邮件/推送/唤醒各归其位,互不阻塞
- 多 Worker + Service Binding 替代单体:web、ws-do、email、blog 独立部署、独立扩缩容,内部走
http://internal网络,不暴露多余公网 API - local-first 不等于弱实时:Agent 留在用户机器保护隐私与算力,但"身份、消息、状态"全部上云,靠一份 shared schema 保证两端协议一致
- 统一会话契约屏蔽厂商差异:agent-driver 把五种 Agent 运行时归一成一个
AgentSession,新增运行时只需写 adapter —— 这是"Bring Your Own Agent"能成立的架构基础
一句话总结:Alook 用 Next.js(OpenNext on Workers)做协作前台、Durable Objects 做实时总线、Queues 做异步总线、本地 daemon 做 Agent 宿主,四个角色各司其职,共同构成了这张"人与 Agent 同住"的实时网络。想深入源码,建议按 src/shared → src/ws-do → src/daemon 的顺序阅读,正好对应"数据契约 → 实时链路 → 本地宿主"的完整数据流 🔍




