ralph — 当前仓库的五步任务闭环
ralph 是你在单个业务仓库里做需求、修缺陷、改样式的主力入口。你只需用一句话说出需求,Agent 就会按 “分析 → 计划 → 实施 → 验收 → 归档” 五步闭环推进,并把目标、验收标准、修改步骤和审查记录保存在仓库的 .workflow/ralph/ 目录下,让你随时可查、随时接着改。
| 宿主工具 | 调用写法 |
|---|---|
| Codex | $jj-ralph … |
| Claude Code / Grok / Qoder | /jj-ralph … |
一、适用场景与边界
什么时候用 ralph:
- 需求只涉及当前这一个仓库(无论是新增大功能、修一个报错,还是调几像素间距)。
- 希望改动有据可查:改了哪些文件、为什么这么改、测试和审查是怎么过的。
- 做完一轮后还可能继续微调(说一句“再改一下”就能自动续接同一任务)。
什么时候别用 ralph:
| 你想做的事 | 应该去哪个入口 | 原因说明 |
|---|---|---|
| 把 项目A 做好的功能搬到 项目B / 项目C | same · 跨仓同源迁移 | ralph 只改当前仓,不负责跨仓库代码迁移 |
| 一次改动要同时派给多个项目、统一审批和盯进度 | dispatch · 多仓统筹调度 | 多项目统筹属于控制项目与 dispatch 职责 |
代码改完了,想 git commit、push 并合并到 dev | end · Git 提交与合并 | ralph 绝不自动提交或推送 Git |
把新克隆的仓库登记进全局项目地图 ~/.jj-flow/map.md | init · 项目地图接入 | ralph 默认只在仓库内工作,不自动修改全局地图 |
二、开始前准备
- 在业务仓库根目录打开对话:确认当前工作目录是你要改的业务仓库(而不是只做调度的控制项目)。
- 先切换到功能分支:
ralph会在你当前所在的分支上修改代码,不会自动切换分支。 - 确认已安装入口:若输入
$jj-ralph或/jj-ralph无补全,请先查看 1 分钟安装与配置。
三、标准五步流程(你做什么 vs Agent 做什么)
无论需求大小,对话路径下的 ralph 仍走五步(小改动只是把分析和计划写得更简短,不会跳过步骤):
| 步骤 | 阶段名称 | Agent 会做什么 | 你需要做什么 |
|---|---|---|---|
| 第 1 步 | 对齐(ANALYZE) | 确认需求目标与验收项,写入 task_plan.md;若关键必做项、范围或验收条件不清晰,会先向你提问确认,绝不凭猜测推进 | 回答 Agent 的澄清问题(如有);如果你说了“先不写代码”,Agent 会在本步完成后停下等你审批 |
| 第 2 步 | 计划(PLAN) | 列出具体要修改的文件路径与分步计划(## Steps) | 无需操作(自动进入实施),或确认方案后说“开始做吧” |
| 第 3 步 | 派单实施与审查(DELIVER) | 按步骤写派单(ASSIGNMENT-TASK),调用实现子代理改代码并验证;若是较大功能,接着调用只读审查子代理(ASSIGNMENT-REVIEW)检查代码(纯文案或样式小改自动跳过审查) | 观察每轮进度汇报;如果审查发现 [BLOCK] 问题,告诉它“按审查改” |
| 第 4 步 | 用户验收(ACCEPT) | 代码与审查通过后,主动停下来等待你本地实测确认 | 在本地试用或查看 git diff,确认无误后回复“验收通过”,不满意则直接提修改意见 |
| 第 5 步 | 归档收尾(ARCHIVE) | 将任务目录移入 .workflow/ralph/completed/,更新 index.md 与 run.json,并将可复用经验提炼至本机 ~/.jj-flow/memory/ | 收到简短归档报告;按需调用 $jj-end 提交代码或 $jj-same 迁移到其他仓库 |
四、完整端到端实战示例
下面展示在 项目A 中完成“登录成功后密码过期弹窗提醒”的完整交互:
1. 发起需求与自动实施
text
你:
$jj-ralph 先改项目A:登录成功后如果密码过期要弹提示,只做登录成功那条路
Agent:
已创建任务 `.workflow/ralph/task-login-reminder/` 并写入 `task_plan.md`:
- Goal:在项目A 登录成功回调中检测 `password_expired` 并弹出改密提醒
- 验收:
1. 登录成功且 `password_expired=true` 时显示提醒弹窗
2. 点击「立即修改」跳转 `/account/password`
3. 补充并通过登录成功路径单元测试
- Steps:
- [ ] Step 1:更新 `src/views/login/LoginForm.vue` 与 `tests/login.spec.js`
正在派遣开发实现子代理执行 Step 1……
[implementer] 已完成 `LoginForm.vue` 弹窗逻辑与单测,测试通过。
正在派遣审查子代理对本次改动进行只读审查……
[OK] 审查通过:`LoginForm.vue` 判空与跳转逻辑清晰,未影响其他登录分支。
请你在本地验收效果。如果确认无误,请回复「验收通过」完成归档。2. 仓库中生成的任务目录结构
此时打开仓库的 .workflow/ralph/ 目录,你会看到清晰的文件结构:
text
.workflow/ralph/
├── index.md # 当前活跃任务与已完成任务总表
├── business-map.json # 仓库业务能力地图(自动维护)
├── task-login-reminder/ # 正在进行中的任务目录(归档前)
│ ├── task_plan.md # 【核心】目标(Goal)、验收标准、实施步骤(Steps)
│ ├── progress.md # 【核心】按日期追加的每轮执行进度与测试证据
│ ├── findings.md # 【核心】改动摘要、踩坑记录与可复用结论
│ ├── assignments/ # 每轮给子代理的精确派单(ASSIGNMENT-TASK / REVIEW / FIX)
│ └── .state/ # 机器状态文件(run.json、events.jsonl、reviews/REV-*.json)
└── completed/
└── task-login-reminder/ # 你确认验收后,整个任务目录自动迁入此处日常查看只需关注 task_plan.md 与 progress.md;.state/ 是机器状态账本,一般无需手动打开。
五、高频场景话术速查
场景 1:日常开新需求(大图、小改、结构化均可)
text
# 一句话提需求(没点名项目时默认就是当前仓库)
$jj-ralph 票面预览的关闭按钮点了没反应
# 直接贴截图指位置(包含「这里」即可)
$jj-ralph [截图] 这里要改一下:放到列表对应列的下面,标题去掉
# 样式或文案小改(分析与计划会自动写短,仍走五步,自动跳过代码审查)
$jj-ralph tip 的 bottom 从 4px 改成 6px
# 结构化字段写法(适合边界要求严格的场景)
$jj-ralph
当前项目=项目A
目标=登录后密码过期提醒
范围=仅登录成功路径
验收=出现提示且可跳转改密场景 2:只想先看分析方案,暂不改代码
如果你不确定改动影响面,想先看 Agent 的分析再决定动不动手:
text
# 第 1 步:要求先分析、先不写代码
$jj-ralph 先不写代码,先分析登录鉴权 token 刷新失败重登怎么做
# 第 2 步:看完它写的 task_plan.md 后,批准开工
$jj-ralph 我认可你的方案,开始做吧场景 3:中途卡住、换做法、暂停或打回重改
text
# 换一种实现策略
$jj-ralph 换策略:先只接 password_expired 字段,倒计时提示先不做
# 暂停等待外部依赖
$jj-ralph 先暂停,等产品给接口返回样例
# 验收不满意,打回重改(不会粗暴 git revert 你的代码)
$jj-ralph 验收不算,退回去改:弹窗关闭后还要清掉临时状态六、做完之后:续接修改、跨仓迁移与收工
哪怕任务已经归档进了 completed/,只要你提的还是同一件事,你都不需要记任务编号——直接说要改什么,Agent 会自动从 index.md 找回原任务继续改:
| 你的后续意图 | 直接在对话里怎么说 | Agent 的处理方式 |
|---|---|---|
| 微调细节 | 「tip 应是 6px 不是 8px」 或 「刚才那个再改一下」 | 自动定位同一条任务接着改,不新建碎片任务 |
| 追加同源范围 | 「关闭按钮也跟着下移 4px」 | 在原任务上扩展范围并重新走验收 |
| 中断后续跑 | 「继续」 或 「修完」 | 接着当前任务尚未走完的那一步继续执行 |
| 根据审查意见修复 | 「按审查改」 | 针对最新一条审查结论派发 ASSIGNMENT-FIX 修复,绝不另开一条名为 审查修复 / review-fix 的新任务 |
| 推翻刚才的做法 | 「改坏了,换个写法」 | 在同一任务内回退阶段、重写步骤后再实施 |
| 需求被取消 | 「这个先不做了,产品砍了」 | 标记为废弃(ABANDONED)并移入 completed/;日后说“还要做”仍可恢复 |
| 做另一件无关的新事 | 「另外做一件:新增导出报表按钮」 | 这时才会开启一条全新的 task-… 任务 |
| 沉淀到全局知识库 | 「写入知识库」 | 经你确认后,把本轮可复用结论写入 ~/.jj-flow/knowledge/ |
| 同步到兄弟仓库 | 「交接到 项目B 项目C」 | 先在源仓库提交 Git,然后转入 same · 跨仓同源迁移 |
| 提交代码并合入 dev | $jj-end 或 「收工」 | 转入 end · Git 提交与合并 完成 Git 推送与分支合并 |
内部机制与运维参考(供维护者与高级用户查阅)
- 主对话与子代理边界:对话路径下,主对话作为
team-lead负责读取.workflow/ralph/index.md与task_plan.md、编写派单并调用命名子代理(spawnjj-implementer与jj-reviewer),不在主对话直接修改业务代码,也不执行ralph_ops/jj ralph命令行。派遣宣告、占位与续接规则统一见skills/jj/references/assignment-spawn.md。 - 未确认需求停靠点(Checkpoint):当分析或实施过程中遇到 MUST / 范围 / 验收事后仍确认不了(先问,不要凭猜测推进)时,Agent 会停留在当前阶段询问用户,绝不把猜测当作规格放行。
- 强制归档收尾(MUST finalize):用户验收通过后 MUST finalize——把任务目录迁入
completed/、更新index.md并同步写入run.json。若只过验收门却未迁入completed/,状态检查会提示未完成收尾。 - 活跃任务提醒机制:当
index.md中进行中的任务超过 5 条、或任一任务超过 5 天未更新时,会触发「归档提示」;同一会话或同一需求出现并排的「审查修复」任务时,会触发「同需求提示」。这些提示只做温和提醒,不会擅自自动归档或删任务。 - 存量任务命令行维护:维护者可使用
jj ralph locate检索历史任务,或使用jj ralph remediate批量收尾滞后任务(详见 CLI 命令行参考)。历史记录中可能出现的task-login-reminder、CAP-login-reminder、DEL-password均为内部机器标识,日常对话无需输入。