👋 Hi，我擅长 AI 大模型应用落地、意识解码与 AI 开发工具链 。 💡 创业路上，用技术换时间，一起把 AI 变成生产力 🚀 >

Worktrunk 速查手册：为并行 AI Agent 工作流重构 Git 工作树管理

什么时候用这份手册？当你在本地同时运行 3+ 个 LLM 编码智能体（如 Qwen3.6 Max、DeepSeek 4.0 Pro 的多 agent 实例），每个需独立沙箱环境、频繁分支切换、且 git worktree add 手动路径管理已引发冲突/误删/缓存污染时——立刻查本手册。

① 重构前的症状

# ❌ 手动管理 worktree：路径硬编码、命名不一致、易冲突
git worktree add ../ai-reviewer-feature feature/review-agent
git worktree add ../ai-testgen-hotfix hotfix/testgen-v2
git worktree add ../ai-docs-rewrite docs/refactor-v3

# 后果：
# - `../ai-reviewer-feature` 路径被其他脚本误读为相对主仓库根目录
# - `hotfix/testgen-v2` 分支名含斜杠，worktree 目录名被转义为 `hotfix_testgen-v2` → hooks 失效
# - 无自动清理机制，`git worktree prune` 遗留僵尸 worktree 占用 2.1GB 磁盘

② 问题诊断

根因不是 Git 本身缺陷，而是工作树与分支名的语义解耦：
Git 的 worktree add <path> <branch> 要求路径唯一，但 AI agent 场景中分支名（如 agent/plan-v2, agent/exe-cpp）才是逻辑标识符，路径只是临时载体。手动映射导致：

• 分支名变更 → worktree 路径失效
• 并行启动 → 路径竞争（mkdir: cannot create directory '../ai-*': File exists）
• 无 hooks 集成 → LLM 生成代码后无法自动 lint/format/commit

③ 重构后的写法

关键配置（~/.worktrunk/config.toml）：

# 自动 hooks：LLM 生成后立即格式化
[hooks]
pre-commit = ["shfmt -w .", "ruff check --fix ."]

# 写时复制缓存（加速 clone）
[cache]
enabled = true
base-dir = "~/.worktrunk/cache"

④ 收益与代价

⑤ 适用边界与检查清单

不该用的场景：

• 单一开发者单任务开发（git checkout 更轻量）
• 工作树需跨文件系统挂载（Worktrunk 当前不支持 bind mount 模式）
• 分支名含非法路径字符（如 :、*）且未配置 template 转义

上线前检查清单：

• wt list 输出中无 prunable 标记项（执行 wt prune 清理）
• wt config template 已设为团队约定格式（避免 agent/plan 和 agent_plan 混用）
• hooks 脚本在 wt switch 后首次运行成功（验证 git status 是否干净）
• CI 流水线仍使用原生 git worktree（Worktrunk 仅限本地开发，CI 无需安装）