Reef

Reef

面向成群编码 Agent 的版本控制系统。

Reef 保留了 Git 的内容寻址存储，并用适合众多并发、试探性且受令牌限制的贡献者的工作模型取代了 Git 的工作模型。这个名字寓意着：由无数微小生物构筑而成的持久结构。

状态：第 1 阶段（租赁式写时复制工作区）已完成，并于 2026-10-25 发布为 0.1.0。第 2 阶段（类型化 API、MCP 服务和实时状态）已满足所有退出标准，并于 2026-11-02 发布为 0.3.0，同时提供 macOS 和 Linux 预编译二进制文件；Python 和 TypeScript SDK 随后推出。请从快速入门开始。CLI 尚不稳定。相关工作记录在 docs/dev-tickets 中；请参阅当前运行的内容和下方路线图。

为什么

Git 是为每天提交几次代码的几十名开发者设计的。Agent 打破了这一设计背后的每项假设。

• 提交量呈数量级增长。 数十个并发写入者每天产生数千项小改动。任何耗费 O（仓库大小）成本的操作都会成为瓶颈。
• 大多数工作都是试探性的。 Agent 尝试几种方案，再择一保留。分支、创建快照和丢弃必须几乎不花成本。
• 历史记录的使用者也是 Agent。 令牌是性能指标。读取一个需要 40k 个令牌的差异，无论计算速度多快都很慢。
• 冲突是常态。 两个 Agent 同时编辑同一个文件是正常情况。让 Agent 停在模态界面中的冲突，也会让整个集群停摆。
• 信任从作者转向证据。 没有人能审查每一行代码。每项更改都必须附带可验证的证据，证明测试是在完全相同的代码树上运行的。
• Git 的繁琐流程是浪费。 暂存区、分离的 HEAD 和解析 porcelain 输出都会消耗令牌并导致错误。Agent 需要类型化 API。

Git worktree 是目前用于隔离 Agent 的方案，它让问题具体化了：每个 worktree 都是一份完整副本，其依赖目录比源代码大得多，而且没有所有者，也没有过期时间；它还持有未提交工作的唯一副本，因此没人敢删除它。

Reef 有何不同

1. 快照，而不是提交。 工作副本始终是快照。没有暂存区，也没有未提交状态。
2. 身份稳定，内容可变。 更改拥有永久 ID，即使经过变基和修订也不会改变。
3. 冲突是一等对象。 存在冲突的合并仍会生成有效快照。快照可以存储、委派给冲突解决器，或留待日后修复。不会阻塞任何操作。
4. 所有操作都可撤销。 全局操作日志会记录每次变更，因此任何 Agent 操作都可以通过一次调用撤销（reef undo <op>）。
5. 工作区是缓存，不是真相。 工作目录采用租赁式写时复制；Agent 离开后会自动回收。删除工作区不会丢失任何内容。
6. Hub 和临时工作区。 每个仓库只有一个权威存储，客户端按需获取数据。完整克隆是例外情况。
7. 证据随更改变动。 测试结果和构建哈希是签名的、内容寻址的对象，并与其所基于的快照关联。是否允许合入取决于证据，而非谁进行了推送。
8. API 优先，CLI 次之。 本地守护进程使用类型化协议通信。CLI 和 MCP 服务都是轻量客户端。任何 Agent 都不应使用正则表达式解析日志。

提案是审查的基本单位：一项更改或一组更改，连同其证据一起提交给 main。它就是处于提议状态的更改本身，并由其更改 ID 标识。这里没有拉取请求。

目前已实现的功能

Reef 可用于现有的 git 和 Jujutsu 仓库。0.1.0 版是第一阶段，旨在为 Agent 替代 git worktree；0.2.0 和 0.3.0 版则加入了第二阶段的功能。如果你使用的是 0.2 版，请先阅读从 0.2 版升级；如果使用的是 0.1 版，也请阅读从 0.1 版升级。

第一阶段（0.1.0）

• 本地守护进程（reef daemon run|start|stop|status）通过 Unix 套接字提供 gRPC 服务，其状态、配置和日志均存放在每位用户专属的状态目录下。它可为多个仓库提供服务；在检出目录中首次运行 reef 命令时，会注册该仓库；如果是普通 git 检出目录，则会先创建 jj 侧的共置仓库（.jj/，并在 .git/info/exclude 中添加一行）。
• 带租约的工作区。 在包含 10 万个文件的仓库中，reef ws create 可在一两秒内基于某个 change 创建工作区（使用 overlayfs 时不到半秒）；reef ws run 会在新工作区中运行命令，在进程运行期间持续续租，并在退出时释放工作区；reef ws move 可将另一个 change 放入工作区目录，同时保留租约；reef ws list|inspect|release 用于管理工作区。Agent 退出后，租约会过期，最终快照会写入存储，目录也会被回收。不会丢失任何内容。
• 写时复制后端。 macOS 上使用 APFS 克隆，Linux 上使用内核 overlayfs 或 fuse-overlayfs，btrfs 和 XFS 上使用 reflink 克隆，并在其他平台上回退为普通复制。它们统一由一个 Backend trait 和一套一致性测试管理。工作区占用的磁盘空间与 Agent 所做的更改量成正比。
• 持续快照。 文件系统监视器（notify，或大型仓库使用 Watchman）会在每次经过防抖处理的写入后，通过 jj-lib 为每个工作区创建快照。监视器创建的快照标记为仅本地可用，在发布 change 前绝不会离开本机。
• 垃圾回收。 reef ws gc 会回收超出撤销期限的操作、没有工作区使用的基础缓存条目以及过期的工作区记录，并报告释放的内容。
• 备份与恢复。 即使 Agent 持续写入，reef backup <dir> 也会复制守护进程的数据库以及每个仓库的 jj 状态；它只会在复制操作文件期间暂停对应仓库。reef restore 会在离线状态下恢复数据；下次启动时，会根据每个工作区的最新快照重建其目录，但不会回收任何工作区（ADR 0020）。此外，还可通过 quiesce RPC 暂停守护进程，以创建文件系统快照。
• 共享依赖存储。 仓库中的 reef.toml 可声明 node_modules 或 target 等存储；reef store build 会在临时工作区中构建存储并将其封存，守护进程会先根据 lockfile 哈希验证存储，再以只读方式将其挂载到每个工作区中。
• 便于 Agent 学习的 CLI。 单独运行 reef 会显示一屏指南；reef here 会说明你所在的工作区以及接下来要运行的命令；所有有已知修复方法的错误都会附带相应的 hint 和 next 命令；任何命令都不会等待用户输入（ADR 0025）。
• 基准测试：在包含 1,000 到 100,000 个文件的合成仓库中测试快照成本和工作区创建速度，并通过 CI 在两个平台上发布结果。有关各项数据与第一阶段退出标准的对比，请参阅 docs/benchmarks.md。
• 入门基准测试。 使用一个从未接触过 Reef 的真实 Claude Code Agent；仅将 reef 放在 PATH 上，运行 reef init 后，且 Reef 尚未安装时，在 reef ws run 内进行测试。按需在 CI 中运行，每项测试进行三次，记录工具调用次数、失败的 reef 调用次数、token 数量，以及进入可用工作区所需的成本。请参阅 docs/onboarding-benchmark.md。

第二阶段（0.2.0 和 0.3.0）

• 类型化 API 和精简 CLI。 守护进程提供 reef.api.v1，这是一个版本化的 protobuf schema，由 buf 在 CI 中进行 lint 和破坏性变更检查（ADR 0029）。reef 二进制文件是它的客户端，自身不包含 jj-lib（ADR 0033）。
• 无需 jj 即可管理变更。 reef status、log、show、diff、describe、abandon、undo、op log、op show、ws snapshot、file read 和 file list 可在工作区或检出目录中查看并还原 Agent 执行的操作；每条命令都支持 JSON 输出，且每当错误有已知修复方法时，都会给出 next 命令（ADR 0034）。API 还可在没有工作区目录的情况下读取文件、列出目录，并在任意修订版本上应用编辑（ADR 0032）。
• MCP 服务。 reef mcp 通过标准输入/输出将 API 提供给 Agent 执行框架，包含 21 个以其 RPC 命名的工具：工作区、状态、日志、变更、差异、文件（无需目录即可读取、列出和编辑）、描述、放弃、操作日志、撤销、查询哪些变更涉及某个文件或符号，以及等待其他 Agent 操作的工具。reef init 会为 Claude Code、Codex 和 opencode 写入对应配置（ADR 0035）。
• 实时操作。 SubscribeOperations 会在操作记录时流式传输操作日志，可按仓库、变更、工作区或 Agent 筛选，并从游标处继续；reef op watch 会输出这些操作（ADR 0036）。中间件只读取每个操作一次，再将其分发出去（ADR 0038）：在 12 核 Mac 上，当有 500 个订阅者且每分钟有 1,000 个操作时，操作的 p99 送达延迟为 53 毫秒，状态信息为 57 毫秒（负载测试）。
• 状态信息。 显示每个 Agent 当前正在做什么：其活动、正在编辑的文件、租约心跳，以及工作区创建和存储构建的进度；这些信息绝不持久化（ADR 0037）。reef ws run 和 reef mcp 会自动上报状态，reef presence report 和 clear 可上报更细致的活动，reef presence watch 可查看状态，而 reef ws renew 可续租在 ws run 之外持有的租约。
• 符号索引。 守护进程在后台使用 tree-sitter 为 Python、TypeScript 和 JavaScript、Go 及 Rust 提取定义和引用，处理新快照和编辑，并接受上传的 SCIP 索引；可通过 reef symbols index、upload 和 list 操作（ADR 0042）。
• 符号级差异和历史记录。 reef diff --symbols 会指出变更新增、删除、修改或移动了哪些定义，以及受影响的调用点（ADR 0043）。reef history 和 MCP query_changes 工具可以查询哪些变更涉及某个文件或符号、由谁操作，以及每项变更的最终状态：开放、已合入、已放弃或已撤销（ADR 0044）。
• 适合 Agent 的输出。 管道输出为简短 JSON，只包含 Agent 会使用的键（ADR 0045）；reef --help 则是面向任务、仅 509 字节的帮助信息（ADR 0051）：在 Claude Code 的实际 CLI 运行中，回答“这个仓库的状态是什么”所需的 token 数量仅为 git 的七分之一（token 基准测试）。reef schema 会将命令、MCP 工具和 API 输出为 JSON Schema，可用于生成工具定义。
• 一行命令即可为 Agent 安装。 本仓库提供 Claude Code 插件和 Codex 插件，支持 reef init --agents opencode --user，MCP 服务也已发布到 MCP 注册表（ADR 0052）。将会话隔离在 git 工作树中的执行框架可以通过工作区提供方契约改为向 Reef 请求工作区；Claude Code 的对应插件以可选的 reef-workspaces 插件形式提供（ADR 0053）。
• 无需遍历目录树即可查看状态。 监视器会维护变更索引，因此对于未发生变更的 100,000 个文件工作区，查询状态只需 12 毫秒，而遍历目录树则需 161 毫秒（ADR 0048）。
• 远程访问。 VM 中的守护进程可通过 TLS 向另一台机器提供相同的 API 和 Web UI，并使用权限范围受限且可撤销的令牌（ADR 0049）。
• 本地 Web UI。 reef ui 会在浏览器中打开只读页面，并实时展示操作流和状态流：每个仓库的最新操作、各仓库的 smartlog、工作区和 Agent、谁正在处理哪项变更、每个租约的健康状况和磁盘使用情况，以及活动动态；页面还配有回放控件，可将任意页面还原到某个历史操作时的状态（ADR 0047）。
• 定时垃圾回收。 守护进程会按 [gc] interval（默认为一天）自行运行 reef ws gc；GC 会保留用户自己的 jj 工作区，使其仍可加载（ADR 0040，ADR 0041）。 Phase 2 尚待推出：Python 和 TypeScript SDK。相关条目见 docs/dev-phases.md。

安装

让你的 Agent 来安装。 在你想使用 Reef 的代码库中，向你的编码 Agent（Claude Code、Codex、Cursor，或任何能使用 shell 的 Agent）提供以下提示词：

Install Reef from https://github.com/reef-vcs/reef, then run `reef init` in this repository and walk me through anything I still need to do.

Agent 会找到下面的安装程序并运行。随后，reef init 会注册该代码库，在 git 旁添加 .jj/ 并启动 Reef 守护进程，然后将 Reef 的使用说明写入 AGENTS.md，以及各个 Agent 自行读取的文件：即代码库中已有的文件，以及 Reef 能识别时，运行 reef init 的 Agent 所用的文件。之后的 Agent 会话便会自动在工作区中启动，无需额外交代。在入门基准测试中，从未接触过 Reef 的 Claude Code Agent 仅凭该链接，就安装了它，并在工作区中完成了一项任务；工具调用次数的中位数为 5 或 6 次（测试在 0.1.0 发布前进行，使用的是安装程序的本地副本）。

或者自行安装。 最新版本 0.3.0 的预编译二进制文件可用于 macOS 和 Linux，支持 arm64 和 x86_64。Linux 二进制文件是静态编译的，因此可在任何容器中运行。

curl -fsSL https://raw.githubusercontent.com/reef-vcs/reef/main/install.sh | sh   # ~/.local/bin, no sudo
brew install reef-vcs/tap/reef
cargo binstall --git https://github.com/reef-vcs/reef reef-vcs reef-daemon

安装程序会根据该版本的 SHA256SUMS 校验 tarball，且不会提示确认。目前二进制文件尚未签名或公证（R4.17）。快速入门介绍了安装程序的选项、系统要求，以及如何验证 tarball 的来源。

如需从源码构建，需使用 Rust 1.97.1 或更高版本：运行 cargo install --locked --git https://github.com/reef-vcs/reef reef-vcs reef-daemon，即可安装 reef 和它运行的守护进程 reef-daemon。该命令会构建 main，其版本可能领先于正式发布版；reef --version 会显示提交记录。从代码检出目录运行 cargo build --release，会将两者构建到 target/release。从源码构建的版本不包含 Web UI，除非先运行 just web-build（需要 Node 24）；否则 reef ui 会说明这一点。从 0.2 升级的用户，请先阅读从 0.2 升级；从 0.1 升级的用户，还请阅读从 0.1 升级。

安装后，在 git 或 jj 代码库中运行 reef ws run -- <your agent command>，即可在全新工作区中运行 Agent。单独运行 reef 会输出 Agent 指南，reef here 会说明你当前所在的工作区以及接下来该做什么，reef --help 则会列出其他命令。在 CI 中运行 reef init --check，可确保 reef init 写入的文件保持最新。stdout 不是终端时，输出为简短 JSON（使用 -o json 可输出所有字段）；如果错误有已知的修复方法，则会通过 hint 字段提供提示，并在 next 字段中给出要运行的命令。

路线图

Reef 基于 Jujutsu 的数据模型和 Rust crate 构建，而不是从头开始。每个阶段都会交付可独立使用的功能。

1. 带租约的写时复制工作区（已完成，作为 0.1.0 发布）。一个通过 overlayfs 或 APFS 克隆创建工作区的守护进程，使用文件系统监视器创建快照，为租约发送心跳，并在租约过期后回收工作区，同时创建最终快照。挂载共享依赖存储。作为独立工具发布，可用于现有的 git 和 jj 仓库。仅此一项就能解决 worktree 问题。
2. 类型化 API、MCP 服务和实时状态（所有退出标准均已达成，作为 0.3.0 发布；SDK 后续推出）。通过本地套接字提供结构化的状态、快照、差异、日志和撤销功能，CLI 作为客户端使用。提供实时操作流和在线状态流。为首批支持的语言提供符号级差异。提供实时显示工作区集群状态的本地 Web UI。
3. 证据对象和落地门禁。 证明格式、可信证明者策略，以及一个落地服务：该服务会批量处理变基后的提案，在批次头提交上运行检查，并在失败时进行二分查找。此阶段会先以 Web UI 的形式推出分诊收件箱，之后再推出桌面应用、iOS 应用和 Android 应用，让人类无论身处何处都能引导并批准 Agent。
4. 共享懒加载对象存储。 提供一个使用原生协议的存储服务端，支持懒加载到本地缓存，并支持存储之间的联邦。
5. 结构化合并。 基于 tree-sitter 的合并，从 Mergiraf 起步，支持 Python、TypeScript、Go 和 Rust。
6. 协议规范和一致性测试套件。 前四个阶段稳定后发布，以便出现替代实现。

范围

Reef 面向开放生态，而非某一家组织的单体仓库。任何人都可以托管枢纽，信任关系按仓库声明，与 git 的互操作性是采用途径：团队中的一个人应该能够对一个其他人从未听说过的普通 GitHub 仓库使用 Reef。

非目标：取代 GitHub 或任何代码审查平台、运行构建或测试，以及作为托管服务。

仓库布局

• crates/reef-error：所有 crate 共用的错误约定：错误类型、分类和建议。
• crates/reef-lib：核心库。数据模型、嵌入的 jj-lib、快照、操作日志和撤销。
• crates/reef-api：API 架构 reef.api.v1（proto/reef/api/v1），以及生成的 Rust 客户端和服务端（ADR 0029）。
• crates/reef-client：API 的轻量客户端、稳定的 JSON，以及查找守护进程的方式，不依赖 jj-lib（ADR 0033）。
• crates/reef-broker：有界内存环形缓冲区，只读取一次日志，并将其分发到后续订阅的流，不依赖 jj-lib（ADR 0038）。
• crates/reef-symbols：用于符号索引的 tree-sitter 标签提取和 SCIP 规范化（ADR 0042）。
• crates/reef-daemon：本地服务和 reef-daemon 二进制文件。工作区、物化后端、监视器、租约、垃圾回收、共享存储和 gRPC 服务。
• crates/reef-vcs：仅基于 reef-client 构建的 reef 二进制文件，以及重新导出 API 和客户端的统合库。
• crates/reef-testing：未发布的测试夹具和合成仓库生成器。

设计

完整的设计文档见 docs/design.md。工作分为多个阶段和工单，详见 docs/dev-phases.md；每个阶段的工单都在 docs/dev-tickets 下附有实现说明，方便 Agent 领取并完成。

架构决策记录在 docs/adr 中。

基准测试、测量内容及基线数据见 docs/benchmarks.md；200 个工作区的崩溃、回收和负载测试见 docs/load-tests.md。

快速入门指南将带你从安装 Reef 开始，一直到回收 Agent 的工作区。

参与贡献

阅读 CONTRIBUTING.md，了解环境设置、工作流以及每次提交都需要的 DCO 签署。尚未完成的工作包括 docs/dev-phases.md 中 Phase 2 尚未完成的事项，以及标记为 phase-2 的问题。

许可证

Apache 2.0。