review — 独立只读代码审查与结论落盘
review 用于对当前仓库的代码改动发起一次独立、只读的代码审查。它会根据改动范围生成审查派单(ASSIGNMENT-REVIEW),调用专门的只读审查子代理(jj-reviewer)从类型安全、空值处理、接口契约和回归风险等维度检查代码,绝不直接修改你的业务代码。
- 如果当前有活跃的
ralph任务,审查结果会同时写入该任务的findings.md与.state/reviews/REV-*.json,作为验收门禁的正式凭据。 - 如果当前没有
ralph任务,它也能直接审查当前工作区或最新HEAD提交,直接在对话里向你汇报结论(不会为了审查去硬建一个空任务)。
| 宿主工具 | 调用写法 |
|---|---|
| Codex | $jj-review … |
| Claude Code / Grok / Qoder | /jj-review … |
一、适用场景与边界
什么时候用 review:
ralph任务改完代码后,想做一次正式的只读代码审查并留存记录。- 平时自己手写了一段代码或刚完成一次 commit,还没建
ralph任务,想让只读审查员帮忙挑挑毛病。 - 你已经在外部工具做完了代码审查,想把现成的审查结论归一化保存到当前
ralph任务账本里。
什么时候别用 review:
| 你想做的事 | 应该去哪个入口 | 原因说明 |
|---|---|---|
| 让 Agent 把审查发现的缺陷改掉 | ralph · 单仓任务闭环 | review 严格只读;要修复问题请对 ralph 说 「按审查改」 |
把多个项目的整体调度标为 VERIFIED | dispatch · 多仓统筹调度 | 跨项目调度状态由 dispatch 汇总管理 |
二、开始前准备
- 无需记任务编号:当你在对话里说
$jj-review时,Agent 会优先读取.workflow/ralph/index.md里的活跃任务;如果没有活跃任务,则自动审查当前工作区或最新提交。 - 可指定审查范围(可选):你可以说“审一下刚才的改动”、“审一下最新 commit”,或者点名具体文件路径。
- 可贴入外部审查结果(可选):如果你手头已有审查意见文本或文件路径,直接贴在对话里,Agent 会如实标记为你提供的来源并记录归档。
三、标准执行流程与结论等级
发送 $jj-review 后,Agent 会按以下流程执行并给出明确结论:
- 确定绑定任务与范围:检查
.workflow/ralph/index.md是否有进行中的任务,锁定本轮修改的具体文件清单(若本轮只有纯文案或样式调整,会自动提示跳过审查)。 - 派发只读审查员:编写
ASSIGNMENT-REVIEW派单,调用只读子代理jj-reviewer(若同一任务此前已审过,后续复审只看相对上一轮的增量改动delta,不重复全仓扫描)。 - 输出三档结论并落盘:
| 对话可见结论 | 对应门禁状态 | 含义与后续动作 |
|---|---|---|
[OK] | PASS | 审查通过:未发现实质性缺陷,可直接进入用户验收或归档。 |
[WARN] | PASS(附带提醒) | 基本通过但有低风险建议:不阻断进入用户验收,你可以视情况决定是否顺手微调。 |
[BLOCK] | NEEDS_CHANGES / BLOCKED | 存在必须修复的缺陷:不能当作验收通过!Agent 会列出具体文件、行号与修改意见,等待你说 「按审查改」。 |
四、完整端到端实战示例
示例 1:审查发现缺陷([BLOCK])→ 修复后增量复审([OK])
text
你:
$jj-review 审一下刚才的密码过期提醒改动
Agent(第 1 轮审查 · 发现阻塞项):
[BLOCK] 登录成功回调未处理 `res.data` 为空时的解构异常,存在空指针报错风险。
1. src/views/login/LoginForm.vue:42 未对 `res?.data?.password_expired` 做可选链判空
修改意见:改为 `Boolean(res?.data?.password_expired)`,并补充空响应单元测试。
审查记录已写入 `.workflow/ralph/task-login-reminder/.state/reviews/REV-1.json`。
如需修复,请直接回复「按审查改」。
你:
$jj-ralph 按审查改
Agent(派发修复后自动增量复审):
已在原任务 `task-login-reminder` 上完成修复并针对增量改动复审:
[OK] 已补充 `res?.data` 可选链判空与空响应单测,原阻塞项已消除。示例 2:无活跃任务时,单独审查当前工作区改动
text
你:
$jj-review 审一下当前工作区的改动
Agent:
当前无活跃 ralph 任务,已对工作区修改的 2 个文件进行独立只读审查(不新建任务目录):
[OK] `src/utils/format.ts` 与 `tests/format.spec.ts` 边界处理完整,无回归风险。五、常用说法速查
text
# 审查当前正在做的任务或刚才的改动
$jj-review 审一下刚才的改动
$jj-review 审一下最新任务的改动
# 指定审查最新一次 Git 提交
$jj-review 审一下当前 commit 的登录提醒改动
# 把已有的外部审查意见记录到当前任务中
$jj-review 把刚才宿主审查结论记到最新任务六、做完之后怎么衔接?
| 审查结果 | 下一步怎么做 |
|---|---|
出现 [BLOCK] 需要修改代码 | 直接对 ralph 说 「按审查改」(会在原任务上继续修复,不会新建碎片任务) |
拿到 [OK] 或 [WARN] | 完成本地验收归档后,调用 $jj-end 提交并合并代码 |
| 发现审查的文件范围不对 | 直接指出正确的 commit 哈希或文件路径,让它重新审查一次 |
七、文件记录在哪里?
- 有活跃
ralph任务时:text.workflow/ralph/<任务目录>/ ├── findings.md # 人类可读的审查发现与修复记录 └── .state/ ├── run.json # 更新任务的审查门禁状态 └── reviews/REV-1.json # 结构化审查报告(含范围、结论与问题列表) - 无活跃
ralph任务时:仅在对话中直接返回审查结论,不在仓库里创建多余的任务目录。
内部机制与协议约束(供维护者与高级用户查阅)
- 主对话作为
team-lead,不会在主会话里自己充当审查员,也不调用宿主自带的/review扫描全仓无关脏文件,而是编写精确限定task_paths的ASSIGNMENT-REVIEW并调用jj-reviewer子代理(推理力度固定为high)。 - 派遣宣告、占位与
resume_from增量续接规则见skills/jj/references/assignment-spawn.md,本页不再重复。