Skip to content

dispatch — 多项目统筹预览、审批与调度 ​

当一个需求需要同时改动多个关联项目,且你希望**“先看清每个仓库打算在什么分支改 → 由你统一批准 → 再并行派发并集中盯进度”**时,使用 dispatch。

它会把每个项目的审批状态、任务进度和验收凭据记录在本机统筹账本(~/.jj-flow)中,哪怕中途关掉窗口,下次说一句“继续”就能无缝接上。

宿主工具调用写法
Codex$jj-dispatch …
Claude Code / Grok / Qoder/jj-dispatch …

一、适用场景与边界 ​

什么时候用 dispatch:

  • 一次需求涉及 2 个及以上项目,需要统一预览各仓库分支状态、统一审批后再执行。
  • 希望有一份全局进度表,清楚知道哪个项目已经 VERIFIED(验收通过)、哪个项目还在改或需要返工。

什么时候别用 dispatch:

你想做的事应该去哪个入口原因说明
只改当前这一个仓库ralph · 单仓任务闭环单仓直接用 ralph 最快,无需开启多仓调度账本
把项目A 刚做完的功能直接迁往项目B,不需要先走多仓审批表same · 跨仓同源迁移轻量跨仓直接用 same 即可
各仓库已经改完验收,想把代码推送到远端并合入 devend · Git 提交与合并dispatch 只管统筹与验收,绝不自动 git push 或合分支

二、开始前准备 ​

  1. 源仓库必须已经 git commit:如果是把源仓库做好的改动分发到其他项目,源仓库未提交时会在派发阶段被直接拦截。
  2. 在任意业务仓对话中即可发起:你不需要专门新建一个“控制仓库”,在任一关联项目的对话窗口里直接调用 $jj-dispatch 即可。
  3. 准备好明确说“批准”:预览表出来后,必须由你本人明确回复“批准”或“可以派”,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 / PS = 绑定当前会话、在功能分支直接改(不同仓可并行);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/),与单仓开发保持完全一致。

相关阅读 ​

基于 MIT 协议发布 · 以持久文件与 Git 证据驱动的多项目研发工作流