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

Agent 框架源码

第 1 节:rakazo 把「能做什么」拆成了 82 个工具

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

rakazo 是三者里唯一整套可自托管的:28 个包、122 张表、82 个内置工具、15 个沙箱 provider,模型、记忆、语音、通道全部走可替换契约。代价是 945477 行代码和 82 个工具的维护面。

关键事实 · 5 条口径随行标注
内置工具
82 个BUILTIN_TOOL_NAMES 数组的元素数
数据表
122 个packages/db/prisma/schema.prisma 的 model 声明数
沙箱 provider
15 个factory 的 13 个可选项,加 host-computer 与 remote-desktop 两条独立路径
记忆 provider
3 家Honcho、Serenity、Supermemory 三个外部实现,另有内置
代码体量
945477 行全仓 .ts/.tsx 物理行数,含注释与空行

Bot 是主对象,会话只是它的一个窗口

速览:rakazo 是 TypeScript monorepo,28 个 package.json、122 张表、82 个内置工具,模型、沙箱、记忆、语音、通道全部走可替换契约。读这节能知道两件事:它凭什么做到断网可跑,以及 945477 行换来的代价落在谁身上。

打开 rakazo 的 Prisma schema,122 个 model 里排在最前面的不是 Thread 也不是 Message,是一串以 Bot 为中心的实体。这个顺序就是它的产品观。

122 张表按职责分四层
层 代表实体 说明
身份 Bot、BotSection、BotDeletion 一个长期存在的「队友」,有名字、头像、设置
工作 Thread、Message、Event、Task、Run、Attempt 一条消息可能触发多次 Run,每次 Run 有多个 Attempt
边界 Space、SpaceMember、AccessGrant、ActionApprovalRule Space 是授权边界,私聊、文件、记忆不跨 Space 混
组织 Organization、Member、ScimUser、ScimGroup、AuditEvent 企业侧:SCIM 同步、审计、计费

第二层那个 Run / Attempt 的拆分值得停一下。大多数 agent 实现里,「一次对话」和「一次执行」是同一个东西:用户发一条,模型回一条。rakazo 把它们分开了——一个 Task 可以有多次 Run,一次 Run 可以有多个 Attempt。这是为了让「重试」成为一等公民:模型超时、沙箱挂了、工具报错,不需要重新走一遍上下文,只要新起一个 Attempt。

这个设计不是为了好看。个人 agent 的特征就是长时间挂着,失败率比单次问答高一个量级;如果重试会破坏会话状态,那就没法做「你走开之后继续跑」。

第一层的 Bot 也有讲究。它有 BotSection——不是配置项,是可以分节的、可被编辑的人格与规则。这意味着 bot 的「设定」是结构化数据,不是一段 system prompt 文本。改设定会留痕,也能按节生效。

第三层的 Space 是它和另外两个项目最大的结构差异。OpenMuse 和 OpenDots 都是单人单工作区的形态,rakazo 直接按「组织 → 空间 → 成员」三层建模,还带 ScimUser、ScimGroup、AuditEventForwarding。这套东西不是给个人用户准备的,是给「公司想把它当内部工具跑」准备的。

一次执行的四个环节 一条消息落四张表,失败单独记一笔 一条消息 落成 Task Run 带租约,worker 认领 审批门 按域判定,多数直接过 沙箱执行 15 个 provider 之一 Attempt 失败重试,独立记账 成功的 Run 只留一条 失败的才多出 Attempt 把「一次执行」和「一次重试」分开存,是它能挂着跑、崩了能续的前提。
Run 与 Attempt 拆开之后,重试不需要重走上下文,也不用担心会话状态被破坏。这是「走开之后继续跑」在数据层的实现。

82 个工具:把能力摊开,而不是塞进一个万能接口

商业产品介绍能力时用一句话:「它能用你的浏览器和终端」。rakazo 把这句话拆成了 82 个具名工具。这个选择决定了三件事:模型看到的提示词有多长、审批能细到什么粒度、以及你能不能在部署时砍掉一部分。

82 个工具按「碰到什么」分类
类别 代表工具 数量
自己的电脑 computer_observe、browser_act、shell、write_file、launch_app 12
你的电脑 user_computer_shell、user_computer_act、request_takeover 4
记忆与技能 remember、recall_memory、save_shared_memory、skill_create 11
协作 spawn_bot、message_bot、handoff_to_bot、run_subagent 9
外部执行 cloud_agent_launch、connect_agent、add_mcp_server 8
花钱与凭据 request_purchase、paid_request、request_secret、generate_secret 8
其余 邮件、调度、工单、页面、媒体生成、联网检索 30

第四类和第五类是这个项目最有意思的地方。它把「别的 agent」当成了工具:spawn_bot 造一个临时队友,handoff_to_bot 把活交出去,cloud_agent_launch 直接起一个云端 coding agent(cursor-cloud-agent.ts 就是接 Cursor 的)。

这对应商业侧同期的产品动作:Grok Bot 让你把多个 bot 放进一个群聊,让它们自己传活;OpenAI Dots 预告「未来是一队 dot 为你工作」。差别在于 rakazo 把这件事降级成了一个 tool call,而不是产品结构。你不需要先接受「多 bot 是核心体验」,才能用上多 bot。

工具多也有直接的账单:82 个工具的 schema 全塞进上下文,光定义就可能上万 token。它的解法是 lazy-tool-catalog.ts 加 run-tool-selection.ts——按当前场景挑一批工具给模型,而不是全量暴露。这是 82 个工具能成立的前提,也是「工具多了反而变笨」这个常见问题的正解。

对比一下另外两个:OpenDots 的工具是 computer / page / connection / composio 四组,合计二十来个;OpenMuse 更少,集中在浏览器和电脑操作。它们不需要选工具这套机制,因为一次对话里能用的工具本来就不多。工具数量的量级差,直接决定了架构里要不要多一层「工具路由」。

rakazo 分层结构 五个 app、四个核心包、一层可替换的 provider 客户端 web desktop(Electron) mobile(iOS + Android) www 服务端 api(Hono + oRPC) worker(run 执行 + 定时任务) 核心包 core memory contracts db(Prisma) 适配层 沙箱 · 15 个实现 记忆 · 3 家 语音 · 5 家 连接器 · 2 个聚合层 外部 Postgres E2B / Daytona / Docker 模型 API / 本地 Ollama Slack / Telegram / 飞书 橙色边框那一层是「可替换」的全部含义:换 provider 不改上层,换不掉就不叫自托管。
28 个 package.json 里,apps 6 个、packages 13 个,其余在 infra 与 examples。真正决定「能不能自托管」的是第四层,不是前三层。

六类 provider:模型只是其中一类

rakazo 的 packages/adapters 目录里,几乎每个外部依赖都有一个 factory 和一套 conformance 测试。这是它「可以完全自托管」的实现方式:不是把厂商写死在代码里,而是把每家厂商都做成一个可替换实现。

哪一类都能换,这是 VISION 里那句承诺的落地方式
契约 已有实现 换掉它意味着
模型 pi-runtime 适配,底层是外部包 @earendil-works/pi-ai,含 OAuth 与本地 provider 换 provider 不换 agent 行为
沙箱 15 个实现,13 个可直接开关切换 机器从云上搬回你自己的机房或笔记本
记忆 Honcho、Serenity、Supermemory 3 家,另有内置 长期记忆不锁在某家向量库
语音 ElevenLabs、OpenAI、Cartesia、Fish Audio、macOS 本机 打电话的 TTS 可以用本机声音
连接器 Composio、Pipedream Connect、MCP、OpenAPI 应用集成可以自己接
消息通道 Slack、Telegram、飞书、短信、SMTP 收发 通道跟着公司现用的工具走

记忆这一行最能说明问题。绝大多数 agent 的「长期记忆」就是一段拼进 system prompt 的摘要,换模型或换服务就丢。rakazo 把记忆做成了 provider:Honcho 管用户画像,Serenity、Supermemory 管语义检索,还能退回内置实现。三个外部实现并存不是为了炫技,是因为这三家的取舍不同——有的强在结构化画像,有的强在原始对话召回。

语音那行同理。它甚至支持 macOS 本机的声音(macos-voice.ts),意思是你不用买任何 TTS 服务,用自己电脑上已装的声音就能让 bot 说话。这种东西商业产品不会做,因为没法计费。

代价是每个 provider 都要写一致性测试。目录里 sandbox-conformance.test.ts、browser-conformance.test.ts、cloud-agent-conformance.test.ts、email-conformance.test.ts、payment-wallet-conformance.test.ts 就是干这个的:所有实现必须过同一套断言,否则「可替换」只是嘴上说说。

这套写法值得抄的地方很具体:先写 conformance 测试,再写第二个实现。只有一个实现时,接口长什么样是由实现决定的;有了第二个实现,接口才被逼成真正的契约。rakazo 有 15 个沙箱 provider,所以它的沙箱接口是三者里唯一被真正压过的。

沙箱的抽象:机器在谁那儿,边界就在哪儿

15 个沙箱实现覆盖了几乎所有「一台机器可能在的地方」:自己机房的 Docker 与 Kubernetes、第三方沙箱 E2B 与 Daytona、国内云桌面无影(wuying)、云主机 Railway,以及最特殊的三个——host-computer(用户自己的电脑)、remote-desktop(远程桌面)、none(不隔离)。其中 13 个挂在 SANDBOX_PROVIDER 这一个开关上,另两个走独立路径。

none 这个 provider 存在本身就是一种诚实:承认有人就是想让它直接跑在宿主机上。它同时解释了为什么审批要按「域」设计——当 provider 是 none 时,沙箱边界不存在了,原来免审批的 shell 就必须靠别的东西兜(desktop-command-guard.ts、sandbox-safety-stop.ts 这类守卫)。

Team Computer 与 Private Computer 的区分也在这里落地。Team 版在同一个信任域里共享文件、已装工具、浏览器身份;Private 版完全不共享。这个区分解决了一个真实矛盾:同一个团队的几个 bot 应该看到同一套登录态,否则每个 bot 都要重新登一次;但不同客户的项目绝不能混在同一个浏览器 profile 里。

还有一个容易被忽略的工程细节:generation-fencing。多个 Chromium 进程不能同时往同一个 profile 目录写,所以每次浏览器身份变更都要带代次号,旧的桌面重启后不能覆盖新的共享状态。这类问题不在任何产品文档里,但它在真实部署里一定会出现——这也是 945477 行里相当一部分的去处:不是功能,是并发与恢复。

把它和商业产品对照:OpenAI Dots 说「你可以随时打开它的电脑看它在做什么」,Claude Duet 说「用云端的虚拟机和浏览器」。它们描述的是同一件事的一个固定实现。rakazo 描述的是这件事的所有可能实现,代价是你要自己选一个并维护它。

教一遍就会:录屏变 playbook

Grok Bot 上线时主打的一个功能是「下次你做这件事的时候让它跟着看一遍,它就把流程记住了」。rakazo 有对应的实现,叫 teaching session,代码在 teaching-session.ts。

它的做法比「记下你的操作」复杂一点。录下来的事件先过 sanitizeTeachRecordingEvent 清理,再由 buildPlaybookFromRecording 生成一份 playbook(可重放的步骤脚本),最后落成 TaughtSkill 存进技能库。中间还有 skillTeachingExpireJobKey——教学过程会超时,不会永远挂在那里。

两种「让它自己跑」不是一回事
机制 输入 产物 适用
Teaching session 你操作一遍,它录 TaughtSkill + playbook 有固定界面的重复操作
Routine 一句话 + 时间表达式 定时触发的 prompt 「每天早上汇总」这类
Skill 手写的说明文档 可被读取的指令集 判断类、写作类任务

注意第二行。rakazo 的 VISION 里有一句明确的话:Routines remain scheduled prompts rather than becoming a visual workflow language. 它刻意不做可视化工作流编排。理由也能理解——一旦上了拖拽节点,产品就从「给你的队友派活」变成「你在配一套自动化」,用户群和维护成本都变了。

这条取舍和国内很多 agent 产品相反。做工作流的产品会把「能画流程图」当卖点;rakazo 把它当负债。判断依据是:这个自动化的复杂度,用户能不能用一句话说清。能,就不要给编辑器。

routine 的实现细节也印证了这一点。相关文件是 routine-backoff.ts、routine-coalescing.ts、routine-lateness.ts、routine-watch.ts——全是在处理「定时任务在真实世界里会遇到的麻烦」:错过了怎么补、同时触发怎么合并、失败了怎么退避。这些是执行层的问题,不是编排层的问题。

账单:94 万行换来了什么,又欠下了什么

读完上面的部分,很容易产生「这个才是正经做产品」的印象。事实是它确实最完整,但完整的代价要摊开看。

省下的和欠下的
换来的 欠下的
断网可跑,模型与记忆都能换 28 个包、28 组版本约束,升级要跟着上游走
15 个沙箱 provider 覆盖各种落地形态 每加一个 provider 都要过 conformance 测试,边际成本不低
82 个工具让能力可组合 工具路由、上下文预算、工具间冲突都要自己调
按域审批,不打扰用户 shell 免审批的前提是沙箱真的隔离,配错一次就是事故
企业侧的 SCIM 与审计齐全 这些表你不上企业就永远用不到,但迁移时全都得跟着走

第三行的成本最容易被低估。82 个工具意味着模型有 82 种走错的方式,而每一种走错都要有对应的错误处理。目录里那些 run-tool-*.ts 文件——邮箱、文件、记忆、消息、页面、偏好、密钥、任务、采购——每个都是一组工具的编排与容错。

第四行是真正的风险点。审批按域设计的前提是域划分正确。host-computer 和 none 这两个 provider 会让「域」变得模糊:机器是你的日常机器,上面有你的一切。选这两个的时候,要么把审批调回按动作,要么接受「模型可以在你的电脑上做任何事」。这是一条需要显式决策的线,而不是一个配置项。

最后给一个判断标准。如果你的场景是「给公司几十个人配 agent,数据不能出门,模型要走自己的网关」,rakazo 是这个方向上目前唯一完整的开源实现,值得投入。如果你是「自己一个人用,想快点跑起来」,那 28 个包和 122 张表就是纯负担——你会在第三个小时就遇到第一个没配好的 provider。

下一节看另一条路:OpenMuse 用 3.8 万行、3 个包,做了哪些取舍才把体量压到这个程度。

本节依据:VISION.md(自托管原则)、schema.prisma(122 个 model)、builtin-tools.ts(82 个工具名)、computer-provider-registry.ts 与同目录 *-sandbox.ts、package.json(@earendil-works/pi-ai 1.5.0)。核对日 2026-11-07。

变更记录

日期类型改了什么范围
新建 按数据模型 / 工具 / 契约 / 沙箱 / 教学 / 代价六段拆 全页
口径 工具数取 contracts/src/builtin-tools.ts 数组长度,不含 skill 与 MCP 动态工具 全页
待更 beta 期 provider 清单与工具数组变动频繁,升级后回填 全页
赞助推荐 一键部署 AI 大模型
赞助推荐 一键部署 AI 大模型