Newshot

Show HN:在 macOS 上为 AI 代理提供的 100ms 写时复制工作区

Translation(model translation, not the source's own text)
Replica Banner
Replica Banner

为 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 快速上手。

快速开始

  1. 选择一个卷。带配额的专用 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。

  1. 构建一次 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
      
  1. 创建、使用并删除工作区。

        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 始终会告诉你它走了哪条路径。

  1. 把你的 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_MODELSQLite schema、状态机、迁移
DISK_SAFETY配额、TTL、驱逐、缓存,以及删除会释放什么
BENCHMARKS方法论、结果和更正
benchmarks/基准测试套件和 fixture 项目
skills/Agent 技能:usage、base、maintenance、development、benchmarks、release
ROADMAP已交付工作、下一步、开放问题
CHANGELOG按版本列出的显著变更

License

The translation is machine-generated and individual terms may be off. Nothing is rewritten or cut; the original is authoritative.

Published by HN AI
This site only summarises and aggregates; copyright stays with the original author. Headlines and summaries follow the source — where they differ, the original wins.
Read the original ↗