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

Agent 框架源码

第 2 节:OpenMuse 用三个进程和一个 KV 表装下 agent

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

OpenMuse 用 38356 行做完了 server、worker、computer 三个进程,存储压成 1 张 records 表,领域模型放在代码里而不是数据库里。它的取舍是「clone 下来就能跑」,代价是会话线程必须接 CopilotKit Intelligence。

关键事实 · 4 条口径随行标注
代码体量
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 进程架构 三个进程,一条外部依赖 mobile(RN 三端) iOS / Android / Web server Hono + CopilotKit runtime + 任务引擎 Intelligence 线程与记忆(外部) AG-UI worker Playwright + 持久 profile computer Docker 或 E2B 桌面 橙色虚线是唯一没被开源的部分:会话线程。其余三个进程都能自己跑。
客户端只跟 server 说话,server 分派给两个执行进程。这样 server 可以随便重启,浏览器会话和容器里的工作都还活着。

一张表存下所有东西

这是 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 个实体是这三个项目里最像「产品设计文档」的一段代码。

12 个实体回答「一个个人 agent 由什么构成」
实体 含义 为什么单独存在
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 指回去。

任务状态机 租约过期就回排队,不需要恢复逻辑 queued running waiting_approval succeeded CAS 认领 批准后继续 60 秒租约过期,下一轮重领 每 20 秒心跳续租,续不上就抛错退出——进程被杀,任务自然回到队列。
断点续跑不是靠保存进度,是靠「谁持有租约」。这条思路和 OpenDots 的 SQLite 租约队列同一个来源,只是它把并发开到了 3。

浏览器 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。

容器模式 vs 桌面模式
项 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」这个定位,单人是对的;想给团队用就得先加一整层身份。

config.agentBackend 的三个取值
取值 用谁的脑 适合
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 适配器状态需复核 全页
赞助推荐 一键部署 AI 大模型
赞助推荐 一键部署 AI 大模型