软件教程

worktrunk 上手:给每个 AI Agent 一份独立的 git 工作区

一、先搞清楚它在补哪一层缺口

同时开三个 agent 改同一个仓库,真正拦住你的通常不是模型能力上限,而是两个 agent 动了同一个目录:一个在跑长任务,另一个要切分支,未提交的改动、stash、构建缓存互相踩。

git worktree 早就提供了隔离原语,一个分支一个目录,但它只管创建和删除。命名规则、怎么列出、怎么在几个工作区之间切换、任务结束后怎么清理、怎么防泄漏,全靠自己写 shell。worktrunk 补的就是这层生命周期管理。

它的核心抽象只有一句:把 worktree 的寻址单位从路径换成分支名,路径由可配置模板生成。你可以直接跟 agent 说去 feature-auth 那个工作区干活,名字就够了。

二、装和用的最短路径

安装任选其一:brew install worktrunk,cargo install worktrunk,或者 conda 与 pixi。Windows 用 winget install max-sixty.worktrunk,注意二进制名是 git-wt,因为 wt 与 Windows Terminal 的短名冲突。

装完必须做一步 shell 集成:wt config shell install。这不是可选项。程序无法改变父 shell 的目录,安装器会注入一个小函数,没有它,wt switch 能建出工作区但没法把你切进去。

然后是四条命令,覆盖完整生命周期。wt switch -c feat 一步完成建分支、建工作区、切进去;加 -x 参数可以顺手在目标目录里拉起 agent,比如 wt switch -c -x claude feat。wt list --full 列出所有工作区的状态、ahead/behind、CI 状态,甚至给每个分支附一段 AI 摘要。wt merge 把 squash、rebase、快进合并、清理一步做完,提交信息可以由外部 LLM CLI 从 diff 生成。wt remove 在 PR 合完之后回收工作区和分支。

还有几个实用细节:hash_port 模板过滤器给每个工作区分配唯一端口,多个开发服务器不打架;wt switch pr:123 直接检出某个 PR 的分支;钩子可以在创建、合并前、合并后执行装依赖、起服务这类动作。

仓库自述的原话是:Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows.

三、三个必须提前知道的坑

第一,构建缓存共享有文件系统限制。十个工作区各自拥有 target/ 和 node_modules/ 而不实际复制,靠的是写时复制,目前只在 APFS、btrfs、XFS 上生效。ext4 和 NTFS 用不了,别指望省下那几十 GB。

第二,钩子就是任意代码。仓库自带的配置文件来自刚 clone 的仓库,未经确认就执行等于远程代码执行。worktrunk 的处理方式值得学:把选择命令、确认授权、渲染三件事分开,门禁做一次选择并冻结成审批计划,执行器在类型上就无法重新选择。它另有已知问题,Codex 会反复要求用户确认 worktrunk 的活动钩子,遇到就手动放行一次。

第三,Windows 脚本里一律写 git-wt,别写 wt,否则会被 Windows Terminal 抢走。

如果还想要跨会话记忆,可以再叠一层 claude-mem:npx claude-mem install,钩子记录工具调用,模型压成语义摘要存进 SQLite,下次会话按需注入。注意安装器默认引导你登录它的托管服务,想纯本地就得显式关掉线上选项,否则会话记录有可能离开你的机器。