Worktrunk

帮助用户使用 Worktrunk，一个用于管理 git worktrees 的 CLI 工具。

可用文档

参考文件从 worktrunk.dev 文档同步：

• reference/config.md：用户和项目配置（大语言模型、钩子、命令默认值）
• reference/hook.md：钩子类型、时机和执行顺序
• reference/switch.md, merge.md, list.md 等：命令文档
• reference/llm-commits.md：大语言模型提交信息生成
• reference/tips-patterns.md：特定语言的提示和模式
• reference/shell-integration.md：Shell 集成调试
• reference/troubleshooting.md：针对大语言模型和钩子的故障排除（Claude 专用）

有关特定命令的选项，请运行 wt <命令> --help。关于配置，请遵循以下工作流程。

两种配置类型

Worktrunk 使用两个独立的配置文件，具有不同的范围和行为：

用户配置 (~/.config/worktrunk/config.toml)

• 范围：单个开发者的个人偏好
• 位置：~/.config/worktrunk/config.toml（永远不提交到 git）
• 包含内容：大语言模型集成、工作树路径模板、命令设置、用户钩子、已批准的命令
• 权限模型：始终提出更改建议并在编辑前征得同意
• 详见：reference/config.md 获取详细指导

项目配置 (.config/wt.toml)

• 范围：所有开发者共享的团队级自动化
• 位置：<仓库>/.config/wt.toml（提交到 git）
• 包含内容：工作树生命周期的钩子（post-create, pre-merge 等）
• 权限模型：主动创建（直接创建，更改可通过 git 撤销）
• 详见：reference/hook.md 获取详细指导

确定使用哪种配置

当用户寻求配置帮助时，根据以下线索确定类型：

用户配置的线索：

• “设置大语言模型” 或 “配置提交信息生成”
• “更改工作树的创建位置”
• “自定义提交信息模板”
• 只影响他们自己的环境

项目配置的线索：

• “为此项目设置钩子”
• “自动化 npm install”
• “在合并前运行测试”
• 影响整个团队

两种配置都可能需要：例如，设置提交信息生成需要用户配置，但自动化质量检查需要项目配置。

核心工作流程

设置提交信息生成（用户配置）

最常见的请求。有关支持的工具和确切的命令语法，请参阅 reference/llm-commits.md。

1. 检测可用工具

   which claude codex llm aichat 2>/dev/null
   

2. 如果未安装任何工具，推荐 Claude Code（在 Claude Code 会话中已可用）
3. 建议配置更改 — 从 reference/llm-commits.md 获取确切命令

   [commit.generation]
   command = "..."  # 查看 reference/llm-commits.md 获取特定于工具的命令
   

   询问：“我应该将此添加到您的配置中吗？”

4. 获得批准后，应用更改
   • 检查配置是否存在：wt config show
   • 如果不存在，指导运行 wt config create
   • 读取、修改、写入，同时保持结构不变
5. 建议测试

   wt step commit --show-prompt | head  # 验证提示构建
   wt merge  # 在存在未提交更改的仓库中
   

设置项目钩子（项目配置）

工作流自动化的常见请求。遵循发现过程：

1. 检测项目类型

   ls package.json Cargo.toml pyproject.toml
   

2. 识别可用命令
   • 对于 npm：读取 package.json 中的脚本
   • 对于 Rust：常用的 cargo 命令
   • 对于 Python：检查 pyproject.toml
3. 设计合适的钩子（有 7 种钩子类型可用）
   • 依赖项（快速，必须完成）→ post-create
   • 测试/代码检查（必须通过）→ pre-commit 或 pre-merge
   • 长时间构建、开发服务器 → post-start
   • 终端/集成开发环境更新 → post-switch
   • 部署 → post-merge
   • 清理任务 → pre-remove
4. 验证命令可用

   npm run lint  # 验证存在
   which cargo   # 验证工具存在
   

5. 创建 .config/wt.toml

   # 创建工作树时安装依赖
   post-create = "npm install"
   
   # 提交前验证代码质量
   [pre-commit]
   lint = "npm run lint"
   typecheck = "npm run typecheck"
   
   # 合并前运行测试
   pre-merge = "npm test"
   

6. 添加注释解释选择
7. 建议测试

   wt switch --create test-hooks
   

有关完整详情，请参阅 reference/hook.md。

向现有配置添加钩子

当用户希望向现有项目添加自动化时：

1. 读取现有配置：cat .config/wt.toml
2. 确定钩子类型 – 应该在何时运行？
   • 创建工作树（阻塞）→ post-create
   • 创建工作树（后台）→ post-start
   • 每次切换 → post-switch
   • 提交前 → pre-commit
   • 合并前 → pre-merge
   • 合并后 → post-merge
   • 移除前 → pre-remove
3. 如需转换格式，进行处理

   单个命令转换为命名表：

   # 之前
   post-create = "npm install"
   
   # 之后（添加 db:migrate）
   [post-create]
   install = "npm install"
   migrate = "npm run db:migrate"
   

4. 保留现有结构和注释

添加命令前的验证

在添加钩子之前，验证：

# 验证命令存在
which npm
which cargo

# 对于 npm，验证脚本存在
npm run lint --dry-run

# 对于 shell 命令，检查语法
bash -n -c "if [ true ]; then echo ok; fi"

危险模式 — 在创建包含以下内容的钩子前警告用户：

• 破坏性命令：rm -rf, DROP TABLE
• 外部依赖：curl http://...
• 权限提升：sudo

权限模型

用户配置：保守

• 未经同意绝不编辑 – 始终显示建议的更改并等待批准
• 绝不安装工具 – 提供命令让用户自己运行
• 保留结构 – 保持现有注释和组织
• 先验证 – 确保 TOML 有效后再写入

项目配置：主动

• 直接创建 – 更改已版本化，易于撤销
• 验证命令 – 添加前检查命令是否存在
• 解释选择 – 添加注释说明钩子存在的原因
• 危险警告 – 添加前标记破坏性操作

常见任务参考

用户配置任务

• 设置提交信息生成 → reference/llm-commits.md
• 自定义工作树路径 → reference/config.md#worktree-path-template
• 自定义提交模板 → reference/llm-commits.md#templates
• 配置命令默认值 → reference/config.md#command-settings
• 设置个人钩子 → reference/config.md#user-hooks

项目配置任务

• 为新项目设置钩子 → reference/hook.md
• 向现有配置添加钩子 → reference/hook.md#configuration
• 使用模板变量 → reference/hook.md#template-variables
• 将开发服务器 URL 添加到列表 → reference/config.md#dev-server-url

关键命令

# 查看所有配置
wt config show

# 创建初始用户配置
wt config create

# 大语言模型设置指南
wt config --help

加载附加文档

加载参考文件以获取详细的配置、钩子规范和故障排除信息。

使用 grep 查找特定部分：

grep -A 20 "## Setup" reference/llm-commits.md
grep -A 30 "### post-create" reference/hook.md
grep -A 20 "## Warning Messages" reference/shell-integration.md

高级：智能体交接

当用户请求在后台会话中生成一个带有 Claude 的工作树（“为…生成一个工作树”、“移交给另一个智能体”）时，根据其终端复用器使用适当的模式：

tmux（检查 $TMUX 环境变量）：

tmux new-session -d -s <分支名> "wt switch --create <分支名> -x claude -- '<任务描述>'"

Zellij（检查 $ZELLIJ 环境变量）：

zellij run -- wt switch --create <分支名> -x claude -- '<任务描述>'

要求（必须全部满足）：

• 用户明确请求生成/交接
• 用户在支持的复用器（tmux 或 Zellij）中
• 用户的 CLAUDE.md 或明确指示授权此模式

不要将此模式用于常规的工作树操作。

示例 (tmux)：

tmux new-session -d -s fix-auth-bug "wt switch --create fix-auth-bug -x claude -- \
  '登录会话在5分钟后过期。找到会话超时配置并将其延长至24小时。'"

示例 (Zellij)：

zellij run -- wt switch --create fix-auth-bug -x claude -- \
  '登录会话在5分钟后过期。找到会话超时配置并将其延长至24小时。'