第一次使用

本页在当前仓库里走完一个 ralph 需求并归档。另外两个入口（same / dispatch）在文末各用一句话说明。

第 0 步：确认入口可用

在业务仓库根目录打开对话（Codex / Claude / Grok / Qoder），试输入 $jj-ralph 或 /jj-ralph，出现补全即可。没有补全就先安装。

下面示例统一写 $jj-ralph，其他工具把前缀换成 /。

第 1 步：准备工作区

• 在要修改的仓库根目录打开对话
• 先切到该需求的功能分支；Agent 在当前分支上工作，不会自动切换分支

第 2 步：用一句话说需求

$jj-ralph 票面预览的关闭按钮点了没反应

不需要格式，不需要编号。想更具体也可以：

$jj-ralph 先改项目A：登录成功后密码过期要弹提示，只做登录成功那条路

第 3 步：接下来会发生什么

主对话是 team-lead：对齐需求、写派单、spawn 子代理；子代理做完带证据回报，写入 progress.md。spawn 前先在聊天里说明这一步在做什么。主对话不修改业务代码，也不执行 ralph_ops / jj ralph 命令行。

派遣宣告、占位、续接的规则见 skills/jj/references/assignment-spawn.md，本页不再重复。

步骤	Agent 在做什么	你会看到
对齐	确认目标和"怎样算做完"，写入短合同	.workflow/ralph/task-…/task_plan.md 出现，含目标与验收项
计划	列出要改的文件和步骤（给派单用）	task_plan.md 多出步骤
派单实施	每轮写一份 ASSIGNMENT-TASK（精确文件），description 以 [implementer] 开头；大功能另派 [reviewer]，小改与纯文案跳过	聊天里先说明这一步在做什么；assignments/；代码 diff；progress.md；reviews/…/findings.md：[OK] / [WARN] / [BLOCK]
你验收	审查通过后等你测	经你确认后对照验收项收口
归档	记录定稿	任务目录移入 .workflow/ralph/completed/，收到一段短报告

还会停下来等你：分析时或 MUST / 范围 / 验收事后仍确认不了（先问，不要凭猜测推进）、你说了"先不写代码"、要做不可逆的事（推送 / 合分支 / 删数据）。

第 4 步：怎样算真的做完了

不要只看聊天总结，看仓库：

1. git diff 或 git status——改动在不在、对不对
2. .workflow/ralph/completed/task-…/task_plan.md——验收项是不是都勾了
3. progress.md——有没有"验收不通过、退回去改"之类的记录

三样都对得上，才算做完。

第 5 步：做完之后的三条路

你想	示例说法	去哪一页
再改一点 / 加一点	「tip 应是 6px 不是 8px」——直接说，Agent 接着同一条任务改，不用编号	ralph
提交并合进 dev	$jj-end 或「收工」——ralph 自己不动 Git	end
把这个能力迁到项目B / 项目C	「交接到 项目B 项目C」——源仓要先提交	same

归档时，可复用结论会写入本机 ~/.jj-flow/memory/；全局知识库仅在你主动提出并经确认后写入。

另外两个入口，一句话

same——迁到别的同源项目

$jj-same 交接到 项目B 项目C

Agent 写下本轮交接任务、到每个目标仓调研，再带派单前缀派执行人按目标仓自己的写法改。分支不对会停下来问你。→ same

dispatch——多个项目一起派

$jj-dispatch 把 README 的装依赖改成 pnpm，预览分发到项目A、项目B、项目C

先看到预览表，你说批准 才真正派出去。源仓库没提交会被拦住。→ dispatch

四个入口的「算做完」对照

你在用	怎样算完
ralph	验收通过，任务目录进了 completed/
same	每个目标仓都改对了、验证过了；部分成功不算全部完成
dispatch	每个项目在调度记录里验收通过——但这 不等于 已经 push
end	代码已 push，并按需要合进 dev / main

最容易出错的三件事

1. 源仓库 还没 commit 就多项目派发 → 会被拦住
2. 分支不对 就迁移 → 改到错误分支
3. 调度显示"验收通过"就以为 已经上线 → 其实还没 push / 合分支

更多：常见踩坑、全部入口：命令总览、名词：术语