跳到主要内容
赞助推荐 搬瓦工怎么选:三网直连 CN2 GIA-E
核对于 2026-11-07
课程目录 · 5 节

Agent 框架源码

第 3 节:OpenDots 只开源了壳,循环在 TanStack

核对 2026-11-07 更新 3 次 引用 6 个来源

OpenDots 是三者里最轻的一份:src 下 13639 行、单进程、SQLite 单文件,却把 Web、Slack、语音三个通道接到了同一条云端线程上。它的开源边界很清楚——壳是你的,会话与 Learning 是 CopilotKit 的。

关键事实 · 5 条口径随行标注
业务代码
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 个直接依赖。

2.2 万行里真正跑业务的只有 1.36 万
部分 规模 内容
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 或日志——因为那些消息里可能带凭据。这种「日志本身也是攻击面」的意识,在开源项目里不常见。

三个通道汇流 三个入口,一条线程 Web Slack 语音 DotAgent 装配工具,不实现循环 TanStack AI 的 chat() 循环,maxIterations 5 或 10 工具:computer ×12、页面 5、审批 2、技能 2 隔离浏览器与 workspace Intelligence thread 会话真源,在云端 通道只负责收与发 跨通道记忆靠同一条线程
归一化交给 Channels SDK,不自己做事件总线。代价是所有入口都绑在同一条云端线程上——线程不可用,三个通道一起失效。

语音:控制面走服务端,媒体面走直连

语音是这份代码里工程含量最高的部分,也是最容易被误读的部分。

它不是「打电话」。真实的 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 的做法正好相反。

语音的控制面与媒体面 语音:控制走服务端,音频走直连 浏览器 RTCPeerConnection server 拿 VOICE_API_KEY,加会话配置 OpenAI Realtime 硬编码,不可替换 SDP offer 转发 音频媒体面:WebRTC 直连,服务端不经手流量 代价:每进程同时只能有一通电话
API key 不出服务器,所以控制面必须中转;音频不进服务器,所以带宽不花钱。这个拆法值得抄,但「一通电话」的限制也来自它。

always-on 的真相:一个 1000ms 的 tick 加一张租约表

「常驻」「你走开它还在干」听着像需要一套消息队列和调度系统。打开 runner.ts 会发现只有一个 setInterval,每 1000 毫秒跑一次。

用 SQLite 当队列,换掉了哪些基础设施
通常要的 这里用什么替代 代价
消息队列(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 的接口仍在变 全页
赞助推荐 一键部署 AI 大模型
赞助推荐 一键部署 AI 大模型