dispatch — 多项目统筹预览、审批与调度
当一个需求需要同时改动多个关联项目,且你希望**“先看清每个仓库打算在什么分支改 → 由你统一批准 → 再并行派发并集中盯进度”**时,使用 dispatch。
它会把每个项目的审批状态、任务进度和验收凭据记录在本机统筹账本(~/.jj-flow)中,哪怕中途关掉窗口,下次说一句“继续”就能无缝接上。
| 宿主工具 | 调用写法 |
|---|---|
| Codex | $jj-dispatch … |
| Claude Code / Grok / Qoder | /jj-dispatch … |
一、适用场景与边界
什么时候用 dispatch:
- 一次需求涉及 2 个及以上项目,需要统一预览各仓库分支状态、统一审批后再执行。
- 希望有一份全局进度表,清楚知道哪个项目已经
VERIFIED(验收通过)、哪个项目还在改或需要返工。
什么时候别用 dispatch:
| 你想做的事 | 应该去哪个入口 | 原因说明 |
|---|---|---|
| 只改当前这一个仓库 | ralph · 单仓任务闭环 | 单仓直接用 ralph 最快,无需开启多仓调度账本 |
| 把项目A 刚做完的功能直接迁往项目B,不需要先走多仓审批表 | same · 跨仓同源迁移 | 轻量跨仓直接用 same 即可 |
各仓库已经改完验收,想把代码推送到远端并合入 dev | end · Git 提交与合并 | dispatch 只管统筹与验收,绝不自动 git push 或合分支 |
二、开始前准备
- 源仓库必须已经
git commit:如果是把源仓库做好的改动分发到其他项目,源仓库未提交时会在派发阶段被直接拦截。 - 在任意业务仓对话中即可发起:你不需要专门新建一个“控制仓库”,在任一关联项目的对话窗口里直接调用
$jj-dispatch即可。 - 准备好明确说“批准”:预览表出来后,必须由你本人明确回复“批准”或“可以派”,Agent 才会真正派发写入任务。
三、标准执行流程(6 步完成多仓统筹)
| 步骤 | 阶段名称 | 具体发生什么 |
|---|---|---|
| 第 1 步 | 只读预览(PREVIEW) | Agent 扫描所有目标仓库的当前分支、是否有未提交改动、工作模式与基线动作,输出一张只读预览表(此时不改任何代码)。 |
| 第 2 步 | 人工审批(APPROVE) | 你核对预览表中的目标分支;若有标记为 NEEDS_CONFIRM 的仓库,顺带确认分支处理方式,然后回复**“批准”**。 |
| 第 3 步 | 正式派发(DISPATCH) | 将各项目任务绑定到会话,并在每个目标仓库初始化各自的 .workflow/ralph/task-…/ 任务目录。 |
| 第 4 步 | 各仓实施(HANDOFF) | 自动衔接 same 流程:先去各目标仓只读调研,再派发实现子代理按各仓原生规范修改代码(不同仓库可并行,同一仓库串行)。 |
| 第 5 步 | 只读审查与验证(REVIEW) | 对每个改完的目标仓库执行测试与只读代码审查;若审查发现问题(NEEDS_CHANGES),自动进入下一轮修复。 |
| 第 6 步 | 逐仓验收(VERIFIED) | 只有当某个目标仓库同时具备**真实 Git 提交、通过的审查记录、真实会话绑定与沙箱证明(attestation)**四项凭据时,才标记为 VERIFIED。 |
四、完整端到端实战示例
假设你要把“README 依赖安装命令统一改为 pnpm 并补充引擎约束”分发到 项目A、项目B、项目C:
第 1 轮:发起预览,查看分支状态表
text
你:
$jj-dispatch 把 README 的装依赖说明统一改成 pnpm,预览分发到项目A、项目B、项目C
Agent:
## PREVIEW(只读预览,尚未派发)
- 交付编号:DEL-20261013-pnpm
- 拟派任务:项目A (development + review)、项目B (development + review)、项目C (development + review)
| 项目 | 拟用分支 | 当前分支 | 未提交改动 | 模式 | 基线动作 | 建议动作 |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| 项目A | feat/readme-pnpm | feat/readme-pnpm | 无 | S | 保持当前分支 | 可直接派发 |
| 项目B | feat/readme-pnpm | master | 无 | S | CREATE_FROM_LOCAL_MASTER | 从本地 master 新建分支 |
| 项目C | feat/readme-pnpm | feat/old-task | 无 | S | NEEDS_CONFIRM | 请确认是否切到 feat/readme-pnpm |
请确认:是否批准以上任务清单?并请确认项目C 是否切换到 `feat/readme-pnpm`?如何看懂预览表里的“模式”与“基线动作”?
| 列名称 | 常见取值 | 通俗解释 |
|---|---|---|
模式(proposed_mode) | S(默认) / W / P | S = 绑定当前会话、在功能分支直接改(不同仓可并行);W = 创建独立 worktree 隔离目录;P = 每个写任务单开独立子会话(仅在你显式要求时启用)。详见 宿主平台与工作模式。 |
基线动作(base_action) | FF_LOCAL_MASTER / CREATE_FROM_LOCAL_MASTER / NEEDS_CONFIRM / BLOCKED | 说明目标仓分支怎么准备:快进本地 master、从本地 master 新建功能分支、需要你拍板确认,或因脏文件阻塞暂不可派。 |
第 2 轮:你批准后,自动派发与汇总验收
text
你:
批准,项目C 切到 feat/readme-pnpm
Agent:
已记录你的批准,正在并行派发项目A、项目B、项目C 的调研与实施子代理……
(各仓库依次完成修改、测试、Git 提交与只读审查)
## 调度汇总(DEL-20261013-pnpm)
- 整体状态:VERIFIED(3/3 项目已验收通过)
- 项目A:VERIFIED · 分支 `feat/readme-pnpm @ 91a4b2c` · 审查 PASS
- 项目B:VERIFIED · 分支 `feat/readme-pnpm @ 44e8d1f` · 审查 PASS
- 项目C:VERIFIED · 分支 `feat/readme-pnpm @ 77c0a9e` · 审查 PASS
提示:`VERIFIED` 代表本地提交与审查凭据已齐备,尚未推送远端。如需推送并合入 `dev`,请在对应仓库调用 `$jj-end`。五、常用说法速查
text
# 1. 把当前仓库刚做好的能力预览分发到多个目标仓
$jj-dispatch 分发当前任务到 项目B和项目C
# 2. 直接描述多项目任务并要求先看预览
$jj-dispatch 把 README 装依赖改成 pnpm,预览分发到项目A、项目B、项目C
# 3. 看完预览表后正式批准
$jj-dispatch 批准
# 4. 中断后恢复查看进度或接着跑
$jj-dispatch 继续
# 5. 安全回退某次多项目交付
$jj-dispatch 开始回退 刚才那个 pnpm 的交付六、做完之后:推送上线与安全回退
| 你接下来想做的事 | 具体做法 |
|---|---|
推送远端并合并到 dev | 调度状态显示 VERIFIED 不等于已经 git push。请到各项目对话中输入 $jj-end 完成远端收工。 |
| 回退某个项目的交付 | 直接说 「回退刚才那个交付」。Agent 会先更新调度账本,再只读探测各仓“是否已推送、是否已合并”,列出选项让你点选(本地未推送通常用 reset,已推送/已合并通常用 revert),绝不会背着你擅自改写 Git。 |
| 中途修改了需求范围 | 只要任务集合或读写权限发生变化,系统会自动要求重新预览并由你再次批准,不会拿旧批准继续派发。 |
七、文件记录在哪里?
- 全局统筹层(
~/.jj-flow/):保存DEL-*调度控制面记录、任务回执(receipt)、沙箱证明(attestation)与全局任务索引。 - 各仓库实施层(
<项目根>/.workflow/ralph/task-…/):每个目标仓库内部拥有自己完整的ralph任务目录(含task_plan.md、progress.md、assignments/),与单仓开发保持完全一致。