ZCode 的 Git Worktrees

每个线程都会拥有自己的 worktree——而且是全自动的。Git Worktrees 为每个新的 ZCode 线程提供一个隔离的仓库检出，因此任务可以并行运行，无需 stash、跳来跳去地切分支，也不会互相覆盖。开始聊天吧，你已经被隔离好了。

/worktree:new fix-auth "Refactor the login flow"   ← worktree + background agent
/worktree                                          ← dashboard: branches, sizes, agents
/worktree:end fix-auth                             ← commit everything, remove cleanly

为什么你会需要它

• 零配置。 自动会话模式（默认开启）会在每个新线程启动的那一刻就给它分配一个 worktree——而恢复线程时又回到同一个。永远不需要输入命令。

• 绝不丢活。 删除脏 worktree、有代理运行或未合并的分支时，没有 force 是会被拒绝的；即使带上了 force，未提交的更改也会先做成快照（已跟踪 diff + 未跟踪文件），存入可恢复的目录。分支默认会被保留。

• 你的环境随你动身。 .env 和它的伙伴们（凡是 .gitignore 命中并出现在 .worktreeinclude 中的文件）都会被带进新 worktree；setupCommands（pnpm install、docker compose up -d）会自动运行。

• 不改动你的工作区。 worktree 统一存放在中央储物（~/.zcode/worktrees），你的仓库保持原样，有过期清理机制（retention sweep）让磁盘占用有界。永远不会有任何东西被静默删除。

安装

1. 在 ZCode Desktop 里打开 设置 → 插件管理，并点击 添加市场。

2. 粘贴仓库的地址——可以是 GitHub 的 owner/repo slug，也可以是一个完整的 Git URL：

   agallardol/zcode-git-worktrees

3. 在目录中安装 Git Worktrees。

4. 打开任意 git 仓库，开启一个线程——这就是隔离的了。输入 /worktree 打开管理面板。

要求：ZCode ≥ 3.8.1，PATH 中的 node ≥ 18、git。

如果 /worktree 没有出现：请在终端里运行 node --version（MCP 服务器需要 node），确认插件在「已安装」下已启用如果你是在应用打开期间安装的，重启 ZCode。

Related MCP server: hop-mcp

这些命令

背后涉及：九个 MCP 工具（worktrees_create、worktrees_list、worktrees_status、worktrees_remove、worktrees_cleanup、worktrees_prune、worktrees_snapshot、worktrees_set_task、worktrees_auto_session）、一个模型可见的 skill，以及 hooks——这样，当你要求并行或隔离的操作时，agent 也可以自己用 worktree。

自动会话 worktree（默认会开）

仓库主检出里每个新会话都会获得自己的 worktree（zcode/session-…）；恢复时会回到同一个，对手在主检出的文件编辑会被阻止并引导到会话的 worktree 上。可以在 设置 → 插件 → Git Worktrees 里或使用 /worktree:auto 来切换（以后一次生效）。仓库也可以明确地用手动退出：

// .zcode/worktree.json in the repo
{ "autoSession": false }

仓库侧配置（可选）

.worktreeinclude——gitignore 风格的模式；只有也被 gitignore 的文件才会被复制到新的 worktree（跟踪文件永不被复制）：

.env
config/secrets.json

.zcode/worktree.json——全同步的特定文件、生命周期 hooks 以及 auto-session 覆盖：

{
  "autoSession": true,
  "copyFiles": [".env.local"],
  "setupCommands": ["pnpm install"],
  "preRemoveCommands": ["docker compose down"]
}

插件设置（设置 → 插件 → Git Worktrees）：worktree 根目录、默认基（fresh 表示 origin/HEAD（离线时自动回退），或 head）、最大天数（14）、每项目最大 worktree 数（15）。

安全模型

• 不让任何东西逃出 store——名称经过路径与 git-ref double 安全性校验（会拒绝路径遍历、.lock、大小写变体、unicode 危险片段）；全路径会校验，防止符号链接；store 的路径会被规范化；一次失败的 git worktree add -> 会将其分支一起回滚。

• 并发安全——所有改动通过进程内队列 + 跨进程 lockfile 串行化；并行创建也不会丢状态。

• 自愈——损坏的状态被隔离后重建；worktree 会从 git 手中重新被接管，带外删除会通过 prune/cleanup 对账。

• 绝不执行来自不可信仓库的代码——setupCommands / preRemoveCommands 只在显式创建的 worktree 上运行。auto-session 生成时绝不会执行仓库提供的命令：打开一个 clone 出来的仓库不代表它是一种代码执行。每个 git 调用都通过 execFile；唯一允许 shell 执行的是 setupCommands / preRemoveCommands 那些你主动选择加入的函数。

与影响它的这些工具相比：PR number checkout 和 .worktreeinclude 语义来自 Claude Code，快照先于删除和中央存储的思想来自 Codex，而配套的有界回收来自 Cursor/Codex——另外还加入了后台 agent 的任务编排以及严格的编辑隔离，这三者中没有任何一个能把它们开放给插件。

测试

npm test   # 129 tests: 80 unit (validators, state, carry-over, hooks, edit guard)
           #        + 13 integration (real MCP stdio JSON-RPC + protocol edges)
           #        + 36 adversarial & security (hostile names, races, corrupt
           #           state, out-of-band damage, exploit regressions)

CI runs the suite on macOS and Linux (Node 20 and 22).

各套测试完全在本地 fixtures 上运行——无网络，无模型调用。

备注和局限

• 自动会话隔离在命令上是“软”的，在编辑上是“硬”的：Write/Edit 工具会命中 PreToolUse 守卫的最先被阻断，防止它碰主仓库，而 Bash 是通过注入的上下文来引导的，而不是静态地被自动监听。

• ZCore 没有“会话结束”的时机：所以退出时不会自动 commit 或删除东西——/worktree:end 是那个明确的“结束=”，而清理 sweep 只是来收集空闲的闲置内容。

• 设置中的 auto-session 改动会让一个会话滞后才生效（hooks 读取的是 MCP 服务器回会话 junctions 同步的一个标记）。

许可证

MIT © Alfredo Gallardo