clawk票据模式全解析:一条命令为多仓库创建worktree并自动开出关联PR
clawk票据模式全解析:一条命令为多仓库创建worktree并自动开出关联PR
clawk 是一款为编程 Agent 提供一次性 Linux VM 的开源工具,其票据模式(ticket mode)让你用一条 clawk work INFRA-123 命令,就能为一个工单自动创建 VM 沙箱、为每个仓库开出以工单号命名的 git worktree 分支,最后再用一条 clawk pr 自动推送并跨仓库开出关联 PR——多仓库改动的重复劳动一次搞定。
为什么需要 clawk 票据模式?
一个工单(ticket)往往横跨 1 到 N 个仓库。传统流程下,你要手动为每个仓库切换或新建 worktree、创建同名片分支、逐个推送并开 PR,还要在分支合并后小心避让已占用的分支名。clawk 票据模式把这些步骤收敛为三条命令:
| 阶段 | 命令 | 作用 |
|---|---|---|
| 开工 | clawk work INFRA-123 |
快照模板、建沙箱、每个仓库一个 worktree,附加 Agent |
| 查看 | clawk status INFRA-123 |
每个 worktree 的分支与 PR 状态一览 |
| 交付 | clawk pr INFRA-123 |
推送全部分支,每仓库开一个互相关联的 PR |
完整的票据生命周期说明见官方文档 docs/ticket-mode.md。
准备工作:用 clawk.mod 描述多仓库工作区
在包含 clawk.mod 的工作区目录里工作。带 includes ( … ) 的 sandbox 块就是一个多仓库工作区根,把参与该工单的仓库列出来即可:
# clawk.mod — 工作区根
sandbox acme (
includes ( ./api ./web ./infra )
network ( allow api.example.com )
)
clawk work 从当前目录向上查找最近的带 includes 的 clawk.mod,所以在工作区树内的任何位置执行都能命中。模板只在创建时读取一次并快照进沙箱记录——之后修改 clawk.mod 不会影响已存在的沙箱。更完整的语法(网络策略、端口转发、MCP 服务器、启动钩子等)见 docs/configuration.md。
💡 没有
clawk.mod也可以:在任意 git 仓库目录内直接clawk work feature-x即可按单仓库默认值走。
一条命令开出沙箱:clawk work 做了什么
cd ~/code/my-workspace
clawk work INFRA-123
这一条命令依次完成四件事:
- 读模板:解析
clawk.mod的sandbox块并快照; - 建沙箱:启动一个以工单号命名的 VM 沙箱,仓库以只读挂载之外的 worktree 形式引入;
- 开 worktree:为
includes中的每个仓库创建 git worktree,分支名即工单号(已存在则复用,绝不覆盖); - 附加 Agent:默认接入 Claude Code(
--safe可保留逐条确认)。
几个实用细节:
- 幂等:沙箱已存在时,
clawk work不会重建、也不会重读模板,而是直接启动并重新附加 Agent; - 换 Agent:
clawk work INFRA-123 --bare先不启动,再clawk run codex INFRA-123接入其他 runner; - 只碰部分仓库:
--only k8s-deploy,monorepo限定本次工单涉及的仓库; - 自定义沙箱名:
--name覆盖默认(默认取分支名,非字母数字替换为-)。
命令实现见 internal/cli/work.go,worktree 与分支解析的核心逻辑在 internal/worktree/worktree.go。
随时回来看:clawk status 的分支与 PR 状态总览
clawk status INFRA-123
status 会列出沙箱内每个 worktree 的仓库、分支,以及 PR 状态——pending(未开 PR)、active(PR 打开中)或 merged(已合并),状态从 gh CLI 读取并带 60 秒缓存,避免频繁请求。加 --json 可输出稳定 schema 供脚本消费,--brief 则输出一行可 grep 的摘要。状态刷新逻辑见 internal/cli/pr_state.go。
一键开 PR:clawk pr 自动推送并跨仓库关联
clawk pr INFRA-123 # 每个有改动的仓库开一个 PR
clawk pr INFRA-123 --draft # 以草稿形式打开
clawk pr INFRA-123 --base develop
clawk pr 会对每个 phase 依次执行 git push -u origin <分支> 并通过 gh 创建 PR;PR 之间在描述里互相关联,评审者一眼就能看到完整的分阶段改动。它足够安全:
- 重复执行不会炸:分支已有 PR 时直接复用现有 PR;
- 无改动自动跳过:与 base 分支无差异的仓库不会开空 PR;
- push 冲突不中断:远端分叉时仍会尝试查找并更新已有 PR;
- PR 描述刻意留空,由你或沙箱里的 Agent 补写,就像人类开的 PR 一样自然。
命令实现见 internal/cli/pr.go。
合并之后:后续 worktree 自动避让已合并分支
当某个仓库的 PR 合并后,工单还需要在同一仓库继续改怎么办?再开一个 worktree 即可:
clawk worktree add INFRA-123 some-repo # 自动使用新分支 INFRA-123-2
clawk worktree rebase INFRA-123 some-repo # 变基到 origin/<默认分支>
clawk pr INFRA-123 # 为后续 PR 开工单
clawk 会检测 INFRA-123 分支的 PR 是否已合并(通过 gh pr view),若是则自动把新分支抬到 INFRA-123-2(再之后是 -3……)并从 origin/<默认分支> 切出——永不与已合并 PR 的分支名冲突;若分支仍在进行中(PR 未合并),则直接复用,不会反复生成新分支。rebase 会把未合并的后续 worktree 变基到刚合入代码之上,冲突时停下并提示你在 worktree 内 git rebase --continue。各仓库进度完全独立:一个可以走到第三个后续 PR,另一个还在等第一版评审。worktree 子命令见 internal/cli/worktree.go。
收尾:停止与销毁沙箱
clawk down INFRA-123 # 停止 VM,稍后 clawk attach INFRA-123 随时恢复
clawk destroy INFRA-123 # 删除 VM、worktree 与网络规则
记住一条规则:VM 是一次性的,你舍不得丢的东西都在宿主机上——仓库里的提交与分支、Agent 的对话历史与记忆都保留在宿主机(~/.clawk/namespaces/default/state/<name>/),destroy 对有未推送改动的 worktree 会先警告,-f 可强制。
从零开始:安装 clawk
clawk 需要 Apple silicon 上的 macOS 14+(Linux 为 firecracker 实验性支持),无需 Docker、qemu 或 sudo:
git clone https://gitcode.com/gh_mirrors/cl/clawk && cd clawk
make install
注意:clawk pr 与 status 的 PR 状态依赖 gh CLI 已安装并登录。
延伸阅读
- 票据模式完整流程:docs/ticket-mode.md
- 命令全集(up/down/snapshot 等生命周期):docs/commands.md
clawk.mod配置参考:docs/configuration.md- 项目架构与"VM 为什么是一等公民":ARCHITECTURE.md、DESIGN.md
- 核心源码:internal/cli/work.go、internal/cli/pr.go、internal/worktree/worktree.go
