
为 AI agent 提供工作区的隔离副本
Replica 为每次 agent 运行提供一份完全安装好的项目副本,借助 APFS 写时复制在毫秒级创建完成。每份副本都是真实的 git checkout,自动清理机制让磁盘总占用保持在有限范围内。
cd "$(replica new --ttl 2h --name fix-login)" # 一个就绪的工作区;路径输出到 stdout
git checkout -b agent/fix-login && git commit -am "fix login" && git push -u origin agent/fix-login
replica rm <id> # 完成;或者让 TTL 到期
为什么
Agent 负载的主要开销来自创建和删除小文件(一次 checkout、node_modules、构建产物),而这正是 macOS 最慢的地方。一次全新安装要花几秒到几分钟,之后 agent 才能开始干活。
Replica 会预先构建一个 base:一个已安装依赖的 git clone。每次 replica new 只用一次 clonefile(2) 调用克隆该 base。数据块在文件发生变更前与 base 共享,因此新工作区几乎立刻可用。在 Apple M1 Max 上实测,对含 1,700 个文件的项目执行 replica new,在 N = 1 时约需 100 ms,在 N = 10 个并发工作区时约需 230 ms;相比之下,git clone 加安装需要数秒。数据与方法见文。
你会得到什么
- 快速工作区。克隆含 1,700 个文件的项目在 N = 1 时约需 100 ms(10 个并发工作区时约 230 ms),而 git clone 加安装需要数秒。确切数值随机器负载变化;完整表格与方法见 docs/BENCHMARKS.md。
- 真正的 git。每个工作区都是完整的 git checkout,可以建分支、提交和推送,而 base 保持不变。详见下文。
- 有界磁盘占用。TTL 到期、最近最少使用淘汰、字节上限,以及可选的带配额的专用 APFS 卷。
- 低成本的更新。replica base refresh 让 base 与其远端保持同步,无需完整重建。详见下文。
- 为 agent 而生。稳定的 CLI,支持 --json 输出、有文档的退出码,以及面向 Claude Code、Cursor、Copilot、Zed 和 Aider 的 skills。
- 并发经过测试。tests/concurrency.rs 同时运行 10 个 replica new/use/rm 循环,零 SQLite busy 错误、无损坏,所有工作区都成功创建并移除。replica gc 会跳过持有新鲜 lease(.replica/lease)的工作区,因此每 10 分钟一次由 launchd 触发的 gc 永远不会删除 agent 正在使用的工作区。
要求
- APFS 卷上的 macOS。Replica 使用 clonefile(2),Linux 不提供该调用。已在 macOS 26.6(Apple M1 Max)上测试。
- base 树与每个工作区必须位于同一个 APFS 卷。克隆不能跨卷,Replica 会拒绝而不是静默复制。
安装
二进制发布覆盖 macOS 的 Apple Silicon(arm64)与 Intel(x86_64)。通用二进制同时涵盖两者。
# Homebrew 暂不可用;见 HOMEBREW.md。
# 安装脚本:使用 sha256sums.txt 校验下载内容
curl -fsSL https://raw.githubusercontent.com/gabrielvfonseca/replica/main/scripts/get-replica.sh | sh
# 从源码构建(需要 Rust 工具链,https://rustup.rs)
git clone https://github.com/gabrielvfonseca/replica.git && cd replica
make release && PREFIX=$HOME/.local make install
运行 replica help 查看引导式概览,或运行 replica help quickstart 快速上手。
快速开始
- 选择一个卷。带配额的专用 APFS 卷是最安全的配置,因为克隆永远不会填满你的主磁盘。
diskutil apfs list # 找到你的 APFS 容器
./scripts/setup-volume.sh disk3 100g Work # 创建 /Volumes/Work,并在那里关闭 Spotlight 索引
export REPLICA_ROOT=/Volumes/Work/replica
任意 APFS 目录也可以。添加 REPLICA_MAX_BYTES 来限制其大小。权衡取舍见 DISK_SAFETY。
- 构建一次 base。
文章标题:Show HN: 100ms copy-on-write workspaces for AI agents on macOS
正文:
replica base build --repo https://github.com/you/proj.git --setup "npm ci"
replica base check # find build output that breaks when cloned
- 创建、使用并删除工作区。
cd "$(replica new --ttl 4h --name feature-x)" # path on stdout, status on stderr
eval "$(replica env <id>)" # per-workspace TMPDIR and shared caches
replica touch <id> # keep a long session out of LRU eviction
replica list # table; add --json for scripts
replica rm <id> # remove one (idempotent)
不同 lockfile 的分支。如果你要从 lockfile 与 base 不同的分支创建工作区,请使用 --ref:
replica new --ref my-feature-branch
Replica 会将分支的 lockfile 哈希与 base 记录的哈希进行比较。如果两者匹配,则直接克隆工作区(直接克隆)。如果两者不同,Replica 会克隆 base,检出 my-feature-branch,然后运行 setup 命令(增量安装),以便工作区获得正确的依赖,并报告分支 my-feature-branch 上的 lockfile 漂移;正在运行增量安装。CLI 始终会告诉你它走了哪条路径。
- 把你的 skill 交给你的 agents。
npx skills add gabrielvfonseca/replica # skills.sh CLI: all six skills
replica setup --dry-run # see what setup would write for Claude Code, Cursor, Copilot, Zed, Aider
replica setup # write it
Git:从工作区创建分支、提交并推送
可以。工作区是一个完整的 git 仓库,而不是只读副本:
| 操作 | 在工作区中 | 对 base 的影响 |
|---|---|---|
| git checkout -b , git commit | 可用。提交位于工作区的 .git 中 | 无 |
| git push origin <branch> | 可用,推送到构建 base 时所用的远程仓库 | 无 |
| git pull , git fetch | 可用 | 无 |
| git status , git diff | 可用 | 无 |
注意事项:
- 远程凭据。push 使用本机上 git 所使用的任何凭据(SSH 密钥、凭据助手)。Replica 不添加也不存储任何凭据。
- 远程仓库就是你构建时所用的那个。工作区中的 origin 就是你传给 base build 的 --repo。如果那是一个本地路径,push 就会推送到该路径。
- 工作区彼此独立。同一分支上的两个工作区在 push 时会冲突,就像两个克隆一样。每个工作区使用一个分支。
- 已验证。tests/git_workspace.rs 会从一个裸仓库构建 base,从工作区提交并推送,并检查 origin 和 base 是否符合预期。
对于会创建 pull request 的 agents,流程是:replica new,在分支上工作并提交,push,用 gh pr create 创建 PR,然后 replica rm。
保持 base 最新
当远程仓库向前推进时,replica base refresh 会更新 base。它不会从头重建:
- Clonefiles 当前 base。这仅复制元数据,因此速度很快,且几乎不占用额外磁盘。
- 运行 git fetch 并将副本重置到 origin/HEAD。只有上游发生变化的文件会被重写。
- 仅在 lockfile 发生变化时才重新运行 setup。如果没有变化,则完全跳过 setup。
- 换入新的 base。现有工作区不受影响,因为每个工作区拥有自己的块。
因此,一个不涉及依赖的上游提交只需付出一次 fetch 和一次检出。lockfile 变化则需要大约与 setup 命令本身相当的开销。如果快速路径因任何原因失败,refresh 会回退到完整重建。
用 replica base status 检查新鲜度,并使用 replica new --require-fresh 拒绝过期的 base。
磁盘占用:工作区实际需要多少成本
- 创建时,工作区会为其包含的每个文件和目录添加 APFS 元数据。对于基准测试样本(约 1,700 个文件),这大约是 1.4 MB。数据块与 base 共享。
文章标题:Show HN: 100ms copy-on-write workspaces for AI agents on macOS
- agent 工作后,它修改的每个文件都会占用真实空间,因为 APFS 会复制发生变化的块。重写 500 MB 构建产物就要花 500 MB,npm rebuild 重写 node_modules 也一样。
- 删除工作区只会释放没有其他文件共享的块。新建的工作区释放得很少,改动很多的工作区释放得多得多。
这就是 TTL、LRU 淘汰和字节上限存在的原因。DISK_SAFETY 对每一项都有说明。
Spotlight 在繁忙的卷上也可能带来额外写入。scripts/setup-volume.sh 只对专用卷关闭索引(它需要 sudo)。我们还没有测量这会多大程度改变基准测试结果。
限制
- 路径相关的构建产物。有些工具会把绝对路径写进输出:Python venvs、node_modules/.bin 脚本、TypeScript .tsbuildinfo。这些文件在克隆环境中会失效。运行 replica base check 找出它们,再用 --post-clone 或重新生成来修复。参见 replica-base skill。
- Cargo target/ 克隆安全但会增加成本。克隆的 target/ 在没有任何变化时能给出正确的增量空操作构建(约 20 ms,不重新编译),在源码变动后只重新编译发生变化的 crate——它不会强制全量重新构建。但是,target/ 是由 setup 命令创建的,所以 .gitignore 无法把它挡在 base 之外。用其他方式排除它:要么在 setup 期间不构建 target/,要么给你的 base 构建加一个排除选项。大型项目的克隆 target/ 每次克隆可能增加数十 MB 的 APFS 元数据,所以如果磁盘成本要紧就排除它。共享的 CARGO_TARGET_DIR 放在 $REPLICA_ROOT/cache 下可以保持增量构建很快,但会重新引入 Cargo 的文件锁等待,所以并行 agent 可能会卡在 “Blocking waiting for file lock”。并行使用时,考虑用 sccache 代替共享 target 目录。
- 成本随文件数量增长。每次克隆都要为每个文件写入元数据。Replica 比逐文件复制或克隆快得多,但它不是免费的,而且超大目录树(数十万个文件)尚未测量。
- 仅限同一卷。源、base 和工作区必须共享同一个 APFS 卷。
- 不是运行中 agent 内部的加速。Replica 让工作区创建变快。它不会加快运行期间的读写,不会减少同时运行大量 agent 所占用的 RAM 或 CPU,也不会解决 Spotlight 或 XProtect 扫描的问题。
- 仅限 macOS。Linux 和 Windows 不在范围内。
基准测试
benchmarks/ 中的测试套件将 replica new 与 git clone 加 install、git worktree 加 install、使用全局虚拟存储的 pnpm,以及 cp -c 进行对比,同时还测量 replica rm 和 replica base refresh,并发数 N = 1、5、10。
make release # target/release/replica
make bench # bundled fixture (~15 min)
make bench CONCURRENCY=1,5,10 # parallel workspace creation
完整结果、方法、机器详情和确切命令见 docs/BENCHMARKS.md。
要点(Apple M1 Max,macOS 26.6.2,带负载,1,739 文件的 npm 项目):
| 并发数 | replica new 中位数 | cp -c -R 中位数 | git clone + setup 中位数 |
|---|---|---|---|
| N = 1 | ~100 ms | ~958 ms | ~3.96 s |
| N = 10(同时) | ~230 ms | ~3.55 s | ~4 s |
即使有 10 个并发工作区,replica new 也比 cp -c -R 快约 15 倍,比 git clone 加 install 快数十倍。一次性的 replica base 构建(约 2–3 s)比单次 git clone + setup 还少,所以 Replica 在第一个工作区上就已经胜出。
- 2026-11-09,带负载(10 核上 1 分钟负载 171–184)。这些绝对时间因共享机器负载而偏高;相对排序保持成立,但不要把这些比值当作定论引用。确切数字和 P95 值见 docs/BENCHMARKS.md。
- 2026-10-25,空闲机器(旧测试框架,1,842 文件):replica new 66 ms,git clone + setup 3.10 s,cp -c 1.33 s。测试框架和 fixture 不同;不能与 2026-11-09 的运行直接比较。
文章标题:Show HN: 100ms copy-on-write workspaces for AI agents on macOS
正文: Replica 会为每次克隆的每个文件添加 APFS 元数据(在安静机器上,一个 1,700 文件的项目约 1.4 MB);数据块与基础版本共享,随着 agent 工作,被修改的文件会占用实际空间。replica-benchmarks 技能列出了干净运行所需的条件。
Development
make help # every target
make check # fmt, clippy (warnings are errors), and tests; what CI runs
make bench # benchmark suite
make dist # release binaries in bin/
CI 在 GitHub Actions 的 macOS runner 上运行。CONTRIBUTING.md 介绍了工作流程,AGENTS.md 包含编码 agent 的规则。replica-dev 技能描述了代码布局。
Docs
| CLI | 每个命令、标志、输出和退出码 |
|---|---|
| SPEC | 问题、目标、非目标、需求 |
| ARCHITECTURE | 组件、布局和流程 |
| DATA_MODEL | SQLite schema、状态机、迁移 |
| DISK_SAFETY | 配额、TTL、驱逐、缓存,以及删除会释放什么 |
| BENCHMARKS | 方法论、结果和更正 |
| benchmarks/ | 基准测试套件和 fixture 项目 |
| skills/ | Agent 技能:usage、base、maintenance、development、benchmarks、release |
| ROADMAP | 已交付工作、下一步、开放问题 |
| CHANGELOG | 按版本列出的显著变更 |