Agent 框架源码
第 2 节:OpenMuse 用三个进程和一个 KV 表装下 agent
OpenMuse 用 38356 行做完了 server、worker、computer 三个进程,存储压成 1 张 records 表,领域模型放在代码里而不是数据库里。它的取舍是「clone 下来就能跑」,代价是会话线程必须接 CopilotKit Intelligence。
- 代码体量
- 38356 行全仓 .ts/.tsx 物理行数,含注释与空行
- 进程数
- 3 个apps 下参与运行的 server、worker、computer,另有一个 mobile 客户端
- 存储表
- 1 张records 表存全部实体,data 列为 JSON
- 领域实体
- 12 个packages/domain/src/agent.ts 的 interface/type,排除枚举与输入类型
三个进程,各管一件事
速览:OpenMuse 用 38356 行装下三个进程和一张单表 KV 存储,浏览器与容器各有一个专属 worker。读这节能知道:小体量怎么做到 clone 下来就能跑,以及它为什么必须把会话线程交给 CopilotKit Intelligence。
OpenMuse 的全部服务端代码在 apps 下,38356 行分给三个能独立启动的进程,外加一个客户端。划分方式很朴素:谁跟浏览器打交道、谁跟容器打交道、谁跟客户端打交道。
| 进程 | 干什么 | 关键技术 | 单独部署的理由 |
|---|---|---|---|
| server | API、鉴权、任务引擎、CopilotKit 运行时 | Hono + @copilotkit/runtime |
要能水平扩,且要接 Intelligence |
| worker | 浏览器会话、下载、出网代理 | Playwright + 持久 profile | Chromium 吃内存,和 API 混在一起会互相拖死 |
| computer | Linux 容器里的命令与文件 | 非 root 容器 + 文件服务 | 要给 agent 一块可丢弃的磁盘 |
| mobile | iOS / Android / Web 三端界面 | React Native + CopilotKit hooks | 客户端,不参与服务端编排 |
把 worker 拆出去这一步,是三者里唯一一个「被现实逼出来的」架构决策。浏览器不是无状态函数:一个登录态、一个下载中的 PDF、一个正在等验证码的页面,都挂在具体的 BrowserContext 上。这种资源不能跟着 API 请求的生命周期走,否则每次重启服务就全部丢失。
所以它把浏览器做成了有身份的长期对象:每个会话一个 UUID,profile 落盘,闲置超时才回收。API 只是拿着会话 id 去 worker 上操作它。这条边界一旦画对,server 就可以随便重启、随便多副本。
另外两个项目在这件事上没有做同样的切分。OpenDots 是单容器单进程;rakazo 有独立的 apps/worker,但它的 worker 跑的是 agent 执行队列,浏览器在沙箱里。三种切法对应三种故障域,没有对错,取决于你想让什么先挂。
一张表存下所有东西
这是 OpenMuse 最反常识的设计。它没有 schema、没有迁移文件、没有 ORM 实体。整个存储层就是一张 records 表,四列:owner、kind、id、data。前三个是键,data 是一坨 JSON。
SELECT data FROM records WHERE owner=$1 AND kind=$2 AND id=$3
就这样。kind 是实体类型(task、goal、memory、browser_session…),id 是实体 id。想加一种新实体?往 kind 里塞个新字符串,代码改完就能用,不需要写迁移。
| 维度 | rakazo:122 张表 | OpenMuse:1 张表 |
|---|---|---|
| 加一个字段 | 改 schema、写迁移、跑 migrate | 改 TypeScript 类型,不用动库 |
| 跨实体查询 | SQL 直接 join | 要自己拉出来在内存里筛 |
| 数据一致性 | 外键与事务兜底 | 靠代码纪律 |
| 分析报表 | 直接写 SQL | 基本没法做 |
| 上手成本 | 要懂 122 个模型的关系 | 看类型定义就够 |
第二行是这张表真正的代价。一旦所有实体都在 JSON 里,「查所有运行失败的任务」这种问题就变成了全表扫描加内存过滤。对个人 agent 这个量级完全够用——一个人的任务量撑不起复杂的查询需求;但如果要给一个团队用,这条路第二天就走不通。
数据库本身也有讲究。它默认用 PGlite,也就是把 PostgreSQL 编译成 WASM 跑在进程内。好处是 pnpm dev 起来就有库,不用装 Docker 不用连服务;坏处是单进程、不能多副本共享。要正经部署就切到真的 PostgreSQL,代码里两条路都留着。
这个设计的选择标准非常清楚:优先「别人 clone 下来能立刻跑」,牺牲「长期可演进」。对一个以模板为定位的项目,这个优先级是对的。对一个要跑三年的内部系统,它是错的。
领域模型写在代码里,不在数据库里
存储极简,不代表它没有领域模型。恰恰相反,packages/domain/src/agent.ts 里那 12 个实体是这三个项目里最像「产品设计文档」的一段代码。
| 实体 | 含义 | 为什么单独存在 |
|---|---|---|
| AgentTask | 一件被委托的事 | 和会话解耦,关掉 app 它还在 |
| TaskStep | 任务内的一步 | 进度可见、可断点续跑 |
| RunEvent | 执行事件流 | 界面靠它渲染「它正在做什么」 |
| Goal | 长期目标 | 任务之上的意图层 |
| Monitor | 持续观察的东西 | 「盯着这件事,有变化告诉我」 |
| Idea | 它主动提的想法 | 允许 agent 未经请求地提议 |
| Evidence | 结论的出处 | 让结果可核对,不是凭空说 |
| AgentMemory | 记住的东西 | 跨会话 |
| AgentArtifact | 产出的文件 | PDF、文档、结构化结果 |
| AgentIdentity | 它对外是谁 | 发邮件时的身份 |
| AgentWorkspace | 工作区 | 文件与配置的归属 |
| AgentNotification | 它来找你的消息 | 主动性的出口 |
Idea 和 Monitor 这两个实体值得单独说。它们不是「任务」的子类型,是两种不同的主动性:Monitor 是「我告诉你盯什么」,Idea 是「它自己想到的」。商业产品里,Claude Duet 对应前者(晨间简报、几小时巡检一次),OpenAI Dots 对应两者(跟踪进度 + 带回结果和需要你决策的问题)。
把「主动性」拆成两个实体的好处是可配置:用户可以关掉 Idea 但保留 Monitor,或者反过来。如果只有一个 proactive: boolean,这两种偏好就没法表达。
Evidence 这一项也很实用。它把「这个结论从哪来的」做成了实体,而不是让模型在正文里加个链接。凡是产出结论的动作都能挂证据,界面上可以逐条展开。这是「可信」这件事唯一可工程化的做法——不是让模型说「我认为」,是让每条断言都有个 id 指回去。
浏览器 worker:会话是个有身份的东西
apps/worker/src 只有 8 个文件,但把浏览器自动化最难的部分都写了。
第一个是会话模型。SESSION_ID 是一个严格的 UUID 正则,validateSessionId 直接拒绝非法输入——不是为了安全,是为了让「会话 id 就是磁盘目录名」这件事成立。每个会话一个 BrowserContext 加一个 Page,profile 存在 dataDir 下,闲置超时才关。
第二个是出网控制。validatePublicUrl 拦住内网地址,startEgressProxy 给浏览器装一层代理。这两件事在自托管场景里比在云服务里更重要:agent 跑在你自己机房的 VPC 里,它能访问到的内网地址远比云上多。一个被提示词注入的 agent,第一件事就是去扫 169.254.169.254 和你的内部管理面板。
第三个是下载。capturePdfDownload 配合 MAX_DOWNLOAD_BYTES 把 PDF 截下来交给上层,同时有 readDownloadFailures 记录失败原因。这个能力看着不起眼,但它决定了 agent 能不能「把账单 PDF 存下来」——很多业务流程的最后一步就是拿一个文件。
对比一下商业产品对这块的描述。OpenAI Dots 说「你可以随时打开它的电脑看它干活」,Claude Duet 说「用云端浏览器处理没有连接器的网站」。它们卖的是结果。OpenMuse 这三件事加起来说明的是:浏览器要能当工作台用,必须同时解决身份保持、出网边界和文件落地三件事,少一件就只是个截图工具。
电脑:一个非 root 容器,加一个只读文件服务
它的 computer 是三个项目里最容易照抄的一份,因为整个 Dockerfile 只有十来行。
FROM node:22.22.0-bookworm-slim RUN apt-get install -y --no-install-recommends bash python3 git coreutils RUN mkdir -p /opt/openmuse /workspace && chown 1000:1000 /workspace COPY files.py /opt/openmuse/files.py RUN chmod 0555 /opt/openmuse/files.py USER 1000:1000 VOLUME ["/workspace"] ENTRYPOINT ["/usr/bin/sleep"] CMD ["infinity"]
三个细节值得记下来。USER 1000:1000 是非 root;files.py 权限是 0555(可读可执行、不可写),agent 不能改自己的文件服务;ENTRYPOINT sleep infinity 意味着容器本身不跑业务进程,所有命令都是外部 exec 进来的。最后这条让「容器活着」和「任务结束」解耦——任务做完了容器还在,下一个任务接着用。
文件读写走 files.py 而不是直接挂载目录,是为了给文件操作加一层边界:路径校验、大小限制、错误码都在这一层收敛。
第二种模式是 E2B 桌面。COMPUTER_PROVIDER=e2b-desktop 时换成真正的图形桌面,分辨率 1280×800,带 VNC 流。computer-e2b-desktop.ts 里那堆常量把成本控制写得很直白:闲置 15 分钟自动暂停,开着桌面则延长到 30 分钟(因为 VNC 流量不算「活动」);单条命令输出上限 1MB,超过就杀;临时文件上限 32MB。
| 项 | Docker 容器 | E2B 桌面 |
|---|---|---|
| 能看到界面 | 不能 | 能,可 VNC 接管 |
| 启动成本 | 秒级,本地镜像 | 分钟级,要拉云沙箱 |
| 计费 | 自己的机器 | 按沙箱时长 |
| 适用 | 跑命令、处理文件 | 需要点图形界面的老软件 |
这两档覆盖了大多数场景,但也止步于此。rakazo 的 15 个 provider 里有 Kubernetes、有本地机器、有国内云桌面;OpenMuse 只有这两个。差异不在技术难度,在目标用户:一个要给企业选基础设施,一个要给个人跑起来。
边界:它开源到哪一层为止
把上面五节读下来,结论会有点反直觉:这份代码的自包含程度比它的名声高。server、worker、computer 三个进程你自己都能跑,PGlite 让本地不需要外部数据库,Google 集成只是可选适配器。真正缺的只有一样:它记不住上一次对话。
README 的架构图里,线程那一格标的是 CopilotKit Intelligence required in every mode。也就是说,不管你用 sample 引擎、自带模型,还是接自己的 AG-UI 端点,会话的持久化都要经过 CopilotKit 的托管服务。这不是代码没写完,是设计如此——它把一个最难做好的部件(长期对话的存储、检索、压缩)交给了上游。
第二个边界是单人假设。鉴权里写死 owner: "local-user",会话 token 是一个随机串的摘要,没有用户表、没有组织、没有权限模型。这跟 rakazo 的 SCIM、Space、AccessGrant 是两个世界。对「个人 agent」这个定位,单人是对的;想给团队用就得先加一整层身份。
| 取值 | 用谁的脑 | 适合 |
|---|---|---|
| sample | 内置脚本化流程,固定决策 | 演示、回归测试 |
| model | 自带模型 key,走内置引擎 | 想自己掌控提示词与工具 |
| agui | 转发到你自己的 AG-UI 端点 | 已有 agent 服务,只借它的壳 |
这三个取值是它最有价值的设计。它承认了一件事:agent 的「脑」和「身体」可以分开买。你可以用 Claude Code、用自己的 LangGraph 服务、用任何实现了 AG-UI 的东西当脑,OpenMuse 提供眼睛(浏览器)、手(容器)和界面(三端 app)。
OpenDots 的 README 也提到了这条:说 OpenMuse 和 OpenBot 是「常驻工作、agent 电脑、执行控制」的代码参考。两家在同一个生态里,各自演示一种切法。
判断标准写在这里:如果你想做的是一个「有身体」的 agent——它要看网页、跑命令、把文件存下来、在手机上看进度——OpenMuse 是目前最干净的起点,38356 行里没有一行是为了演示而写的假代码。如果你要的是「记住我、懂我、主动找我」的那种 agent,那它的记忆与主动性都还停在实体定义阶段,没有实现到位。
顺带记一个工程上的事实:它和 CopilotKit 的耦合面只有两个文件——agent.ts 和 tanstack-agent.ts。剩下的工具、任务引擎、审批、浏览器、电脑全是自己的代码。这意味着换掉框架只影响这两处,也意味着你读它的时候可以把框架部分跳过去。
续跑不靠模型记性,靠 60 秒租约
「你走开它继续干」这句话落到代码上,要回答一个很硬的问题:进程被杀掉之后,任务怎么知道该从哪继续?OpenMuse 的答案是两层:把长任务变成数据库记录,用租约保证只有一个进程在跑它。
第一层是循环有界。聊天的循环上限是 6 步,带桌面时 16 步,后台任务 16 步,到顶不是报错,而是注入一句「说 continue 我接着干」。后台任务另有 5 分钟硬超时。这个设计的意思是:模型不被允许一直转下去,转不完就落成任务。
queued → running → waiting_approval | waiting_input | scheduled | paused
↓
succeeded | failed | cancelled
第二层是调度。TaskWorker 每秒 tick 一次,扫一遍 tasks 表,挑四种活:排队的、到点的、在跑但租约过期的、等审批的。并发上限 3。
认领用的是乐观并发 CAS:写进 leaseId 和 leaseUntil(60 秒租约),跑起来之后每 20 秒续一次。要是续不上——说明有别的进程抢走了——就抛 LostLeaseError,任务回到 queued 等下一轮接管。进程重启不需要任何恢复逻辑,因为「恢复」就是「租约过期后被别人重新认领」。
第三层是断点。每执行完一个工具步就 checkpoint(),把 state.operations patch 回库。这个 operations 里存着每个工具调用的结果,按「工具名 + 参数」的 sha256 做键。于是重跑时同参数的调用直接命中缓存,不会把已经发出去的邮件再发一遍。
| 机制 | 解决什么 | 不解决什么 |
|---|---|---|
| 有界循环 | 模型无限绕圈烧钱 | 任务本身太长 |
| 租约 + CAS | 多进程抢同一个任务 | 任务已经产生的副作用 |
| 工具结果缓存 | 重跑时重复执行有副作用的调用 | 缓存丢失或参数微变 |
第三列才是真问题。缓存键是工具名加参数,参数一变就绕过去了;进程在工具执行中途被杀,那一步的副作用到底发生没发生,本地无法判断。所以它在启动时做一件事:recoverInterruptedActions() 把所有处于 executing 的动作标成 outcome_unknown——不知道成没成,交给人看。
更硬的一层设计在这里:对邮件和日历这类外部写操作,模型根本没有对应的执行工具。它能做的只是生成一份提案——内容用 hash 钉死、30 分钟内有效、必须人工批准,然后由服务层执行。失败之后绝不自动重试,因为重试可能发出第二封邮件。
这条设计值得单独说。绝大多数 agent 项目在这里会假装可以恢复,或者干脆不处理。标成「结果未知」是个诚实的选择,也是唯一安全的选择:对外部世界的写操作,宁可让人复核一次,也不要自动重试。
对比一下 OpenDots 的做法:同样是租约队列,同样是一秒 tick,但它是单并发、90 秒超时、退出时把任务标 interrupted 并提示人工复核。两个项目在同一个问题上得出了几乎相同的结论,说明这不是风格问题,是这类系统的必然。
本节依据:README.md(架构图与进程表)、engine/worker.ts(任务调度与租约)、db.ts(单表 records)、browser.ts(会话与出网代理)、apps/computer/Dockerfile、agent.ts(12 个领域实体)。核对日 2026-11-07。
变更记录
| 日期 | 类型 | 改了什么 | 范围 |
|---|---|---|---|
| 新建 | 按进程 / 存储 / 领域模型 / 浏览器 / 电脑 / 边界六段拆 | 全页 | |
| 口径 | 进程数只数 apps 下参与服务端运行的三项,mobile 记为客户端 | 全页 | |
| 待更 | alpha 期,Intelligence 依赖与 OpenBot 适配器状态需复核 | 全页 |