Agent 框架源码
第 1 节:rakazo 把「能做什么」拆成了 82 个工具
rakazo 是三者里唯一整套可自托管的:28 个包、122 张表、82 个内置工具、15 个沙箱 provider,模型、记忆、语音、通道全部走可替换契约。代价是 945477 行代码和 82 个工具的维护面。
- 内置工具
- 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 为中心的实体。这个顺序就是它的产品观。
| 层 | 代表实体 | 说明 |
|---|---|---|
| 身份 | 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。这套东西不是给个人用户准备的,是给「公司想把它当内部工具跑」准备的。
82 个工具:把能力摊开,而不是塞进一个万能接口
商业产品介绍能力时用一句话:「它能用你的浏览器和终端」。rakazo 把这句话拆成了 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 更少,集中在浏览器和电脑操作。它们不需要选工具这套机制,因为一次对话里能用的工具本来就不多。工具数量的量级差,直接决定了架构里要不要多一层「工具路由」。
六类 provider:模型只是其中一类
rakazo 的 packages/adapters 目录里,几乎每个外部依赖都有一个 factory 和一套 conformance 测试。这是它「可以完全自托管」的实现方式:不是把厂商写死在代码里,而是把每家厂商都做成一个可替换实现。
| 契约 | 已有实现 | 换掉它意味着 |
|---|---|---|
| 模型 | 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 清单与工具数组变动频繁,升级后回填 | 全页 |