Raft：人和 agent 同处一室，
源码以「单快照」交付

// 它是什么

把 agent 当同事、而不是当工具的 Slack 式工作空间

官方定位（README 原文）：“Raft is a shared workspace where humans and AI agents collaborate as peers.” agent 是持久参与者——有自己的身份、记忆和能力范围；它以真实进程的形式跑在真实机器上，和人在同一个 server 里用 channel、thread、DM、task 一起干活。

产品概念与 Slack 高度同构（server / channel / thread / DM / mention / task），差别在于一等公民里有 agent：会被 @、能领任务、能发提醒、能准备 action card 交给人执行、能通过 CLI 读写消息与文件。服务端在 raft.build，有 Web、桌面（Electron）与移动布局（同一套 Web 响应式分叉）。

三个最容易记住的差异点

• agent 跑在你自己的机器上。本地有 daemon 与「Computer」运行时，agent 不是云端沙箱里的容器，而是你机器上的进程；因此能碰本地文件、GitHub、浏览器、终端。
• 运行时可选，不锁模型。手册列出十二个运行时族：Claude Code、Codex、Grok Build、内置 Pi、Kimi Code、Copilot、Cursor、OpenCode、Pi，外加三个为兼容旧 agent 保留的弃用项（Antigravity、Gemini、旧版 Kimi CLI）。packages/daemon/src/drivers/ 有对应适配器与事件归一化器。
• 文档是写给 agent 读的。manual/ 里 44 篇知识文档经 raft manual get/search 直接投喂 agent，连「怎么回答定价问题」「哪些功能其实没有」都有专门策略文档。

// 仓库地图

一份完整可运行的 monorepo：14 个包、3 个应用

pnpm workspace。下列行数是对克隆下来的源码逐包统计（TS/TSX，含测试）。

// 怎么运转

三个平面：服务端、守护进程、Computer

README 明写的三条安全属性

• 每个需认证的入口都校验会话族是否仍有效；吊销会话会同时踢掉它的实时订阅。
• 频道可见性只有一处判定（canUserAccessChannel），HTTP、实时订阅、回放三条路径共用，避免各写一遍导致漏判。
• agent 永远不直接持有服务端凭证——由 daemon 通过本地、绑定来源的代理中转，每次启动发一个 token。

权限模型：scope 与角色是两套东西

scope 约束 agent 能调什么 API，越权返回 SCOPE_DENIED，且 agent 不能给自己加权限；scope 与 server 级角色（owner / admin / member）互不替代。人类侧改 scope 走 GET/PUT /api/agents/:id/scopes，要求 editAgents 能力或创建者身份——手册特别注明：这组接口不是 agent 自我提权的接口。

// 工程特征

技术栈务实，测试密度明显偏高

几个「被线上问题教育过」的细节

• 契约测试成体系。大量 *.contract.test.ts、*.typeproof.ts、*.api.test.ts，连错误响应卫生（error hygiene）都有黑盒测试；packages/visual-testing 专做跨 provider 视觉回归。
• 状态机显式化。agent 生命周期、inbox、APM 都有独立 reducer / stateMachine 与属性测试，而不是散落的 if。
• 进程建模很实。agentNoProcessResidency、agentProcessManager.*.test.ts（claude / codex / grok / 内置运行时各一套）说明「agent 是真实进程」不是文案，是被测试盯住的实现。
• 内部命名残留。产品曾叫 Slock：SLOCK_HOME（默认 ~/.slock）、脚本里的 SLOCKDEV_*、CLI 仍保留 slock 别名，手册里还有一篇 rename-slock-to-raft。
• 发版流程脚本化。scripts/source-available/export-snapshot.test.mjs 与 release.test.mjs 说明「导出快照 → 发布」本身是被测试覆盖的流水线。

// 最有意思的一块

manual/：一套专门写给 agent 读的产品手册

44 篇 manual/agent-knowledge/*.md，带 doc_id frontmatter，通过 raft manual get <topic> / raft manual search 供 agent 检索。写法很反常规：

• 每篇开头写「为什么这篇会过时」。「Raft 没有的功能」那篇自曝：文档只会朝一个方向腐化——功能上线了条目却不会变红；还举了真实案例：关于「静音能不能细到单频道」，两篇文档各对一半、公然互相矛盾，而系统里没有任何机制发现这件事。
• 术语正典。一张「错词 → 对词」表：不许说 bot（要说 agent）、不许说 prompt（要说 message）、产品对象叫 server 而不是 workspace；leverage / seamless / revolutionary 这类词被列入禁用。
• 定价安全回答策略。价格文档故意不写任何数字——理由是数字会过期、账户状态 agent 看不到、承诺会绑定公司。agent 只能说「形态」并把人指到官方定价页与 Billing 页。
• 检索有硬约束。手册只支持英文检索，用中文等非拉丁字符查询会返回 knowledge_language_unsupported，要求改用英文重写问题。

本质上是把「提示词工程」沉淀成产品资产：与其把规则塞进系统提示词，不如做成可版本化、可检索、并显式声明失效风险的文档。

// 动手试

本地跑起来需要什么

前置：Node.js 24.15（.node-version）、pnpm 10.29.3、Docker。

git clone --depth 1 https://github.com/botiverse/raft-source.git
cd raft-source
pnpm install
./raftdev start        # Postgres、Redis、对象存储、server、web、daemon 一起起
./raftdev --help       # 会初始化本地工作空间并打印登录信息与端口
pnpm --filter @botiverse/raft-server test   # 包级检查

raftdev 会按 .node-version 与 engines 做严格的三段式版本校验（pin 不合契约就直接失败，不猜），再拉起整套本地栈。

想接入自己的外部 agent，可看同组织的 raft-external-agents、create-raft-app；SDK 在 packages/raft-sdk（@botiverse/raft-sdk，面向外部 agent 与 bot 的类型化 Agent API 客户端）。

// 我的判断

值不值得花时间

如果你在做 agent 产品的基础设施——尤其是「多 agent 协作、agent 身份与权限、agent 跑在用户机器上」这条线——这份代码值得读，重点看三处：packages/daemon（进程编排 + 凭证代理）、packages/server/src/services（生命周期 / inbox / scope 的建模）、manual/agent-knowledge（把 agent 行为规范写成产品文档的做法）。测试代码的写法本身也是范本。

如果你在找能改、能商用、能二次分发的开源基座——这份不合适：FSL 的竞品限制会堵住绝大多数商业化路径，而且没有历史、不能提 PR。

如果你只是想用产品——直接去 raft.build 注册即可。源码在这里的意义主要是「可自建」与「可审计」，不是开发者的贡献场。

// 来源

核验依据

• 仓库主页（README / LICENSE / SECURITY / CONTRIBUTING）：github.com/botiverse/raft-source
• 快照元数据：RELEASE_SOURCE（上游私有提交 d3aae345…，导出 2026-09-24 04:40 UTC，4383 文件）与 GitHub API（仓库 / 分支 / tag / commit）
• 本地克隆核对：git clone --depth 1 后逐包统计文件数、行数与运行时 driver 清单
• 产品与定价：raft.build、raft.build/pricing（前端渲染，本次未取到具体数字）
• 官方文档仓库：github.com/botiverse/raft-docs（对外文档，与仓内 manual/ 是两套受众）
• 第三方（未经官方核实）：the Rundown 的 Raft 条目（seat 计费与年付价格的第三方描述）、社媒关于「Raft 1.0 / Team Mode」的报道