Agent 框架源码
第 3 节:OpenDots 只开源了壳,循环在 TanStack
OpenDots 是三者里最轻的一份:src 下 13639 行、单进程、SQLite 单文件,却把 Web、Slack、语音三个通道接到了同一条云端线程上。它的开源边界很清楚——壳是你的,会话与 Learning 是 CopilotKit 的。
- 业务代码
- 13639 行src 下 .ts/.tsx 物理行数,全仓含测试为 22265 行
- 通道数
- 3 个Web、Slack、语音,代码里无短信与 Twilio 相关实现
- SQLite 表
- 21 张store、workspace、pages、connection-store、computer-store 的建表语句合计
- 工具定义点
- 14 处defineTool 调用,另有 MCP 与 Composio 动态工具
- 直接依赖
- 30 个根 package.json 的 dependencies 数
先看体量:业务代码只有 1.36 万行
速览:OpenDots 的 src 下只有 13639 行,单进程加 SQLite,却把 Web、Slack、语音三个通道接到了同一条云端线程上。读这节能知道:always-on 的最小实现长什么样,以及它的开源边界到底切在哪一层。
三个仓库统计口径不一样,先把账对清。全仓 .ts 与 .tsx 是 22265 行,但其中一半在测试与文档示例里。只看 src 下的业务代码是 13639 行,84 个文件,单进程单包,30 个直接依赖。
| 部分 | 规模 | 内容 |
|---|---|---|
| src/server | 约 5906 行 | Hono 服务、agent 装配、工具、队列、存储 |
| src/client | 约 5995 行 | React 界面、Spaces 编辑器、计算机视图 |
| src/shared + browser | 约 1738 行 | 类型、审批卡、浏览器入口 |
| tests | 57 个文件 | 不参与运行 |
服务端和客户端各占一半,这个比例说明它是个「界面驱动」的项目——不是先有引擎再配界面,而是围绕「你能看见它在干什么」来设计。计算机视图、页面编辑器、审批卡都在客户端,服务端只负责产出事件。
它的存储层是 SQLite,用 Node 24 内置的 node:sqlite,默认落在 data/opendots.sqlite,两个 Store 类共享同一个文件。21 张表全部手写建表语句,没有 ORM、没有迁移框架。
这跟 OpenMuse 的「一张 KV 表」不同,也跟 rakazo 的「122 张 Prisma model」不同。21 张手写表是个中间态:比 KV 表查询能力强,比 ORM 省事,代价是加字段要自己写 ALTER。对一个模板项目,这个位置是对的——读者能一眼看完所有表结构。
三个通道,怎么归一成一条对话
代码里能数出 3 个通道:Web、Slack、语音。没有短信——全库检索 twilio 与 sms 零命中,README 里的「text」指的是网页聊天。这一点值得说明,因为它的宣传语「move between text, calls, and Slack」容易被读成「支持短信」。
| 通道 | 接入方式 | 消息怎么进来 | 回复怎么出去 |
|---|---|---|---|
| Web | CopilotKit runtime 的 HTTP 端点 | AG-UI 请求 | AG-UI 事件流 |
| Slack | @copilotkit/channels 的 createChannel |
@提及后订阅线程 | thread.post() |
| 语音 | OpenAI Realtime | 浏览器 WebRTC 接通 | 实时音频 + 通话纪要回写 |
关键设计在第三列和第四列之间:它没有自研统一事件总线。归一化交给 Channels SDK 的 IncomingMessage 抽象——message.platform === 'slack'、message.actor.kind === 'human' 这类字段把不同来源压成同一个形状。这一层省下的是「每接一个新通道就要改一遍分发逻辑」的成本。
Slack 那边还有两个细节值得抄。一是 store: { concurrency: 'serial' }——同一个通道的消费是串行的,不会因为两条消息同时到就并发跑两个 agent。二是身份白名单:slackIdentity 把 Slack team 加用户 ID 映射成唯一 owner,白名单外的人 @它直接被忽略。对单人 agent,这比做一套权限系统实在。
还有一个细节在错误处理上。safeFailure 只透出错误类名和 HTTP 状态码,不把 provider 的原始消息写进 Slack 或日志——因为那些消息里可能带凭据。这种「日志本身也是攻击面」的意识,在开源项目里不常见。
语音:控制面走服务端,媒体面走直连
语音是这份代码里工程含量最高的部分,也是最容易被误读的部分。
它不是「打电话」。真实的 PSTN 呼入呼出需要 SIP 中继和号码资源,这里完全没有。它的「call」是浏览器里的一次 WebRTC 对讲:你在网页上点通话,浏览器生成 SDP offer,POST 到 /api/voice/calls,服务端加上会话配置后转发给 OpenAI 的 Realtime 接口,拿回 SDP answer,然后音频直接在浏览器和 OpenAI 之间跑。
这个拆法有明确目的:API key 不出服务器。浏览器只拿到一个协商好的媒体通道,拿不到凭据。服务端保留的是控制面——挂断、超时、状态机——而不经手音频流,所以它不用扛带宽。
代价写在代码里两处常量上:连接租约有 30 秒超时,会话租约 15 分钟。还有一行更要紧的:if (this.jobs.size) throw。意思是每个进程同时只能有一通电话。单用户假设在这里被固化成了一个硬限制。
最巧的是语音和干活的桥。realtime 会话里只注册了一个工具 ask_compute,模型一旦要「真的做点什么」,服务端就通过 platform.turn() 把请求发回同一个 Intelligence 会话,跑一轮完整的 DotAgent——90 秒超时,每通电话最多 6 次。通话结束再把纪要 syncReceipt 回写同一线程。
于是「聊到一半让它去查点东西」这件事成立了,而且不打断通话。这条设计比语音本身值钱:它把「实时对话」和「长时间执行」解耦,用一条线程当交接面。商业产品里 Claude Duet 的「通话中也能继续安排活、挂了电话活还在跑」是同一个思路。
锁定也很清楚:https://api.openai.com/v1/realtime/calls 是硬编码字面量,转写模型 gpt-4o-mini-transcribe 同样写死。想换成别家 TTS 或 STT,得改源码。这和 rakazo 把语音做成五家 provider 的做法正好相反。
always-on 的真相:一个 1000ms 的 tick 加一张租约表
「常驻」「你走开它还在干」听着像需要一套消息队列和调度系统。打开 runner.ts 会发现只有一个 setInterval,每 1000 毫秒跑一次。
| 通常要的 | 这里用什么替代 | 代价 |
|---|---|---|
| 消息队列(Redis / RabbitMQ) | SQLite tasks 表 + 轮询 |
轮询有 1 秒内的延迟抖动 |
| 分布式锁 | BEGIN IMMEDIATE 事务里写租约 |
多进程会争抢同一个库文件 |
| 工作进程池 | 单进程串行,if (this.active.size) return |
一次只跑一个任务,长任务互相排队 |
| 失败补偿与对账 | 租约到期自动重领 | 副作用不回滚,只能提示人工复核 |
第二行是这套实现能成立的关键。领任务的写法是在一个 BEGIN IMMEDIATE 事务里读出任务、写入随机 lease 和 leaseUntil(默认 180 秒),再提交。进程崩了,租约过期,下一个 tick 自动重领。这是教科书式的租约队列,只不过跑在同一个进程里。
第三行才是它的真限制。严格单并发意味着:你让它整理一份周报(可能跑三分钟),这三分钟里别的后台任务全在排队。对一个人用的 agent,这通常无所谓;对想跑十个定时任务的场景,这就是硬瓶颈。
最后一行是它诚实的部分。进程退出时 shutdown.ts 会把在跑的任务标成 interrupted,并提示 Review completed effects before retrying——不假装任务可以无损恢复。因为工具已经产生的副作用(发出去的邮件、写进去的页面)没法撤回,重试只能靠人看一遍。
还有一条容易被忽略:权限撤销是 100 毫秒轮询。你在界面上点暂停,在跑的 agent 一秒内被 abort,中止信号沿 AbortSignal 传到每个工具执行的检查点。粒度粗——整轮对话作废,已产生的副作用不回滚——但「关掉就真停」这件事做到了。
三套框架各管一层,会话真源在云端
OpenDots 同时用了 CopilotKit、TanStack AI、AG-UI 三套框架,容易看得眼花。按职责拆开其实很干净:
| 框架 | 管什么 | 不管什么 |
|---|---|---|
| TanStack AI | 模型循环、工具执行、迭代上限 | 端点、线程、通道 |
| CopilotKit runtime | HTTP 端点、agent 注册表、Intelligence 客户端、Channels | 具体的模型调用 |
| AG-UI | 事件流协议(Observable<BaseEvent>) |
业务语义 |
所以工具这一层才是自己写的:computer_* 十二个(导航、读页、快照、截图、点击、输入、按键、滚动、列文件、读文件、写文件、执行),加页面的五个增删改查、两个审批工具、两个技能读取。这些一共由 14 处 defineTool 调用点生成——computer 那十二个走同一个工厂,所以调用点比工具数少。剩下的是动态的:MCP 工具按 连接名__工具名 确定性命名,最多 100 个、schema 16KB、结果截断到 20KB;Composio 的工具整包转发。
会话真源放在云端是这份代码最重要的一个决定。history()、线程创建、learning container 全部委托给 Intelligence,本地只存一张 thread_bindings 表记绑定关系。
收益是跨通道天然打通:Slack 里说的一句、电话里说的一句、定时任务触发的一轮,都只是「往同一条线程里再发一条消息」,不需要自己做会话合并。
代价是单点。requireReady() 在会话不可用时直接抛错——不是降级到本地缓存,是整个产品不可用。这条边界必须让使用它的人知道:你自托管的是一个前端和一套工具,不是一套完整的 agent 运行时。
三条硬边界,决定了它适合谁
把上面五节收成三条边界。这三条不是缺陷清单,是它的定位声明。
| 假设 | 代码证据 | 想突破要做什么 |
|---|---|---|
| 只有一个主人 | OWNER_ID 全局唯一,identifyUser 永远返回同一人 |
重写身份层,加组织与角色 |
| 语音只走 OpenAI | api.openai.com/v1/realtime/calls 是字面量 |
抽一层 provider 接口 |
| 后台任务串行且限时 | 单并发,默认 90 秒超时 | 换真队列,改多 worker |
第一条最彻底。它没有「用户」这个概念,只有一个 owner token 加一个本地工作区。想做成给团队用的产品,等于从头加一层身份体系——而这恰好是 rakazo 那 122 张表里相当一部分在做的事。
第二条是取舍而不是疏忽。语音这块如果做成 provider 抽象,就要处理五家不同的音频格式、断句策略、延迟特性,工作量翻几倍。对一个演示「什么叫常驻同事」的模板,锁一家是理性的。
第三条限制它的使用场景。90 秒能干完的活是「查一下、写一段、存个页」;干不完的是「整理三个月的账单」。它没打算做后者。
那它适合谁?适合已经决定用 CopilotKit 技术栈、要一个能 fork 的参考实现、并且能接受把会话交给托管服务的团队。2.2 万行里有完整的审批卡、计算机视图、页面编辑器、Slack 接入和语音链路,这些是照着文档自己拼要花两周的东西。
反过来,如果你要的是「数据一点都不出门」,它就不合适——不是代码不好,是它从一开始就没打算解决这个问题。这一点它自己在 README 里写了:A template, not a hosted product.
下一节把三个项目和五家商业产品放在一张表里,算清「自托管」到底买到了什么。
本节依据:README.md、compose.yml(Intelligence 与语音变量)、dot-agent.ts(装配层)、voice.ts(OpenAI Realtime 字面量)、runner.ts(租约队列)、slack-channel.ts。核对日 2026-11-07。
变更记录
| 日期 | 类型 | 改了什么 | 范围 |
|---|---|---|---|
| 新建 | 按体量 / 通道 / 语音 / 队列 / 会话真源 / 边界六段拆 | 全页 | |
| 口径 | 行数分开记两个口径:src 业务代码与全仓含测试 | 全页 | |
| 待更 | alpha 期,Intelligence 与 Channels 的接口仍在变 | 全页 |