clawk票据模式全解析:一条命令为多仓库创建worktree并自动开出关联PR

原创2026-10-17 16:01:021,352 阅读

clawk票据模式全解析:一条命令为多仓库创建worktree并自动开出关联PR

clawk 是一款为编程 Agent 提供一次性 Linux VM 的开源工具,其票据模式(ticket mode)让你用一条 clawk work INFRA-123 命令,就能为一个工单自动创建 VM 沙箱、为每个仓库开出以工单号命名的 git worktree 分支,最后再用一条 clawk pr 自动推送并跨仓库开出关联 PR——多仓库改动的重复劳动一次搞定。

clawk 票据模式演示:一条命令启动一次性 Linux VM 并附加 Agent,网络放行名单拦截未知请求,clawk attach 随时恢复会话

为什么需要 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

这一条命令依次完成四件事:

  1. 读模板:解析 clawk.mod 的 sandbox 块并快照;
  2. 建沙箱:启动一个以工单号命名的 VM 沙箱,仓库以只读挂载之外的 worktree 形式引入;
  3. 开 worktree:为 includes 中的每个仓库创建 git worktree,分支名即工单号(已存在则复用,绝不覆盖);
  4. 附加 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 已安装并登录。

延伸阅读

登录后查看全文
clawk