wt

wt - Worktree 管理器技能

使用 git worktree 管理彼此隔离的 LlamaFarm 开发环境。每个 worktree 都有自己的服务、端口和数据目录，可让多个 Agent 会话并行运行而互不冲突。

完整文档

完整文档、架构详情和高级用法请参阅： @scripts/wt/README.md

---

快速参考

任务	命令
创建 worktree 并启动服务	wt create feat/my-feature
创建 worktree 并切换到其中	wt create --go feat/my-feature
列出所有 worktree 及其状态	wt list
检查服务运行状况	wt status 或 wt health
启动／停止服务	wt start / wt stop
查看服务日志	wt logs [server|rag|runtime|designer|all]
删除 worktree	wt delete <name>
切换到指定 worktree	wt switch <name>
在浏览器中打开 Designer	wt open
诊断问题	wt doctor
清理孤立数据	wt gc

---

何时使用 wt

以下情况请使用 wt：

• 开始需要运行服务的功能／任务隔离开发
• 并行运行多个编码会话（多个 Agent 或终端）
• 测试更改而不影响主开发环境
• 避免并发运行的 LlamaFarm 实例之间发生端口冲突

---

常见工作流

开始新任务

# Create isolated environment with services running
wt create --go feat/my-task

# Work in the worktree...
# Services are already running on auto-assigned ports

# Check status anytime
wt status

# View logs if needed
wt logs server

检查正在运行的内容

# List all worktrees with their port assignments
wt list

# Example output:
# NAME              STATUS    SERVER   DESIGNER  RUNTIME
# feat-my-task      running   8150     5150      11150
# fix-bug           stopped   8234     5234      11234

清理

# Stop services and remove a worktree
wt delete feat-my-task

# Remove data for worktrees that no longer exist
wt gc

# Remove worktrees for branches merged to main
wt prune

故障排查

# Diagnose common issues (ports, stale PIDs, missing tools)
wt doctor

# Restart stuck services
wt stop && wt start

# Force delete if normal delete fails
wt delete my-worktree --force

---

服务 URL

每个 worktree 都会获得唯一端口。使用以下命令查看 URL：

wt url
# Outputs:
#   Server:   http://localhost:8150
#   Designer: http://localhost:5150
#   Runtime:  http://localhost:11150

如果 Caddy 代理正在运行，请使用不带端口的 URL：

http://server.feat-my-task.localhost
http://designer.feat-my-task.localhost

---

关键环境详情

• Worktree 位置：~/worktrees/llamafarm/
• 数据目录：~/.llamafarm/worktrees/<name>/
• 端口分配：根据 worktree 名称的确定性哈希分配（14345+offset、5000+offset、11000+offset）
• 日志：~/.llamafarm/worktrees/<name>/logs/

---

给 Agent 的注意事项

1. 设置新任务环境时始终使用 wt create --go——它会处理所有事项（分支、依赖项、构建、服务）
2. 创建新 worktree 前先运行 wt list，查看已有内容
3. 运行测试或调用 API 前，使用 wt status 确认服务运行正常
4. 遇到无法解释的服务问题时，运行 wt doctor
5. 任务完成后使用 wt delete 清理，释放资源