Skip to content

ralph — 当前仓库的五步任务闭环 ​

ralph 是你在单个业务仓库里做需求、修缺陷、改样式的主力入口。你只需用一句话说出需求,Agent 就会按 “分析 → 计划 → 实施 → 验收 → 归档” 五步闭环推进,并把目标、验收标准、修改步骤和审查记录保存在仓库的 .workflow/ralph/ 目录下,让你随时可查、随时接着改。

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

一、适用场景与边界 ​

什么时候用 ralph:

  • 需求只涉及当前这一个仓库(无论是新增大功能、修一个报错,还是调几像素间距)。
  • 希望改动有据可查:改了哪些文件、为什么这么改、测试和审查是怎么过的。
  • 做完一轮后还可能继续微调(说一句“再改一下”就能自动续接同一任务)。

什么时候别用 ralph:

你想做的事应该去哪个入口原因说明
把 项目A 做好的功能搬到 项目B / 项目Csame · 跨仓同源迁移ralph 只改当前仓,不负责跨仓库代码迁移
一次改动要同时派给多个项目、统一审批和盯进度dispatch · 多仓统筹调度多项目统筹属于控制项目与 dispatch 职责
代码改完了,想 git commit、push 并合并到 devend · Git 提交与合并ralph 绝不自动提交或推送 Git
把新克隆的仓库登记进全局项目地图 ~/.jj-flow/map.mdinit · 项目地图接入ralph 默认只在仓库内工作,不自动修改全局地图

二、开始前准备 ​

  1. 在业务仓库根目录打开对话:确认当前工作目录是你要改的业务仓库(而不是只做调度的控制项目)。
  2. 先切换到功能分支:ralph 会在你当前所在的分支上修改代码,不会自动切换分支。
  3. 确认已安装入口:若输入 $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、编写派单并调用命名子代理(spawn jj-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 均为内部机器标识,日常对话无需输入。

相关阅读 ​

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