GenericAgent Review Mode SOP 实战解析：用 /review 拉起会话内对抗性代码评审

GenericAgent Review Mode SOP 实战解析：用 /review 拉起会话内对抗性代码评审

【免费下载链接】GenericAgentSelf-evolving agent: grows skill tree from 3.3K-line seed, achieving full system control with 6x less token consumption项目地址: https://gitcode.com/GitHub_Trending/pc/GenericAgent

本文基于 GenericAgent 仓库的 memory/review_sop.md 及其配套实现，系统讲解内置的/review命令与 Review Mode SOP：一套运行在当前对话上下文中的对抗性代码评审协议。读完你将掌握该评审模式的触发方式、五步工作流、P0~P3 严重度分级、Verdict 决议规则、防误报八规则与措辞八规范，并理解其"不开 subagent / 不落盘 / 不打 sentinel"的会话内设计在源码层面是如何落地实现的。

一、Review Mode 是什么：会话内对抗性评审

GenericAgent 的 Review Mode（评审模式）是一个in-session adversarial code reviewer：当你在对话中发起评审时，主 agent 不切换到独立 subagent，而是在当前对话内直接拉起评审流程，审阅报告直接 echo 到对话，作为给用户的最终回答。

它的三个关键设计约束（见 review_sop.md 顶部引言）：

• 不开 subagent：评审复用当前 session 的上下文，不额外拉起子 agent；
• 不落盘：报告不写review.md文件，不产生磁盘产物；
• 不打 sentinel：报告末尾不打印[ROUND END]标记。

这条设计在源码中有明确佐证。主 agent 的正常输出路径会在文件末尾写入[ROUND END]（见 agentmain.py），而评审模式的 stub 兜底 prompt 里明确写着"不要写 review.md，不要打 [ROUND END]"（见 review_cmd.py），review_inline_prompt.txt的角色与边界一节也重复强调这一约束。

典型使用场景：作者刚写完一段代码 → 输入/review→ 主 agent 对自己的改动做对抗性 review，即审即得，不污染工作区。

二、何时使用与快速启动

触发条件

用户输入/review命令，或自然语言要求 "code review" 时启用。

快速启动命令表

/review help的用法文本由 review_cmd.py 的_help_text()生成，其中给出的示例包括：

• /review—— 默认审本次 uncommitted 改动
• /review 我刚改了 review_cmd.py 和 tuiapp_v2.py，关注 prompt 注入—— 按任务范围审
• /review 审 frontends 目录下所有改过的文件—— 按目录范围审

非 git 仓库：若当前目录不是 git 仓库，主 agent 会提示用户在下一句/review塞入具体路径或范围，本轮结束。

三、入口文件与命令分发链路

任意前端 (TUI / Streamlit / wechat / desktop) └─ frontends/review_cmd.py ← 命令分发，剥 "/review" 前缀，注入 user_request └─ memory/review_sop/review_inline_prompt.txt ← 完整 in-session 协议 └─ memory/code_review_principles.md ← 15 条好代码原则

分发实现：monkey-patch 统一接管

frontends/review_cmd.py 是/review的唯一命令入口，核心是两个函数：

• install()（review_cmd.py）：monkey-patchGenericAgent._handle_slash_cmd，统一接管/review。patch 逻辑按原始输入精确匹配'/review'或'/review '/'/review\t'前缀，其余命令原样交给原始分发函数；patched._review_patched = True标记保证 patch 幂等，重复 install 不会叠加。
• handle()（review_cmd.py）：接收已剥离/review前缀的纯参数文本，处理help/?/-h/--help后直接推送帮助文本；否则把参数注入 inline prompt 返回给主 agent。注意它不发任何donemessage——注释明确指出，一旦发送 done，前端if 'done': break + finally: agent.abort会误杀主 agent。

底层挂载点

_handle_slash_cmd是主 agent 的任务预处理钩子，原始实现在 agentmain.py（负责/session.x=...与/resume等内置命令），在 agentmain.py 的run()循环中于每轮任务开始前调用。各前端在启动时把/review注入该钩子：

• chatapp_common.py：from review_cmd import install as _install_review; _install_review(_GA)，所有基于chatapp_common的聊天前端共用此挂载点；
• tuiapp_v2.py：TUI 前端启动时review_cmd.install(_GA)；
• tui_v3.py：TUI 的命令面板直接调用review_cmd.handle(ag, arg, dq)，有 prompt 则作为普通任务提交，无 prompt 则把帮助文本渲染为 assistant 消息；
• tgapp.py：Telegram 前端引入handle_review_command。

Prompt 渲染与多语言

_render_prompt()（review_cmd.py）负责加载评审 prompt 模板并注入两个占位符：{user_request}（本轮请求）与{ga_root}（仓库根路径，供file_read使用）。它通过环境变量GA_LANG选择语言：GA_LANG=en时加载 review_inline_prompt.en.txt，否则加载 review_inline_prompt.txt。若模板文件缺失，会回退到_STUB_FALLBACK兜底提示，保证/review在任何情况下都不会静默失效。

四、三条铁律（reviewer 顶部硬约束，不可违反）

评审协议在 prompt 最顶部固定了三条不可违反的硬约束：

1. Review-only 只读评审—— 只做评审与报告。禁止修改源文件、调用file_write/file_patch/code_run改业务代码、在产出里写"我接下来去修一下"或暗示要动手。
2. Challenge the approach，不仅找 bug—— 先问"这条路本身对不对？"再问"实现有没有 bug？"：挖隐含假设，评估真实环境故障模式（Windows 路径 / 代理失活 / 并发写 / UTF-8 边界 / token 预算耗尽）。
3. 报告输出完即结束—— 不复述用户目标、不做 meta 评论、不承诺 follow-up；报告 markdown 直接 echo 到对话，不落盘 review.md、不打[ROUND END]。

这三条铁律在 review_inline_prompt.txt 的"角色与边界"一节中逐条展开，与 SOP 完全一致。

五、五步工作流（顺序执行，禁止跳读）

步骤 1：必读底料

file_read("memory/code_review_principles.md")—— 15 条好代码原则，每条 finding 必须能映射到其中一条。本轮/review只读取memory/review_sop/与memory/code_review_principles.md，不引用其他工作流 prompt（保证评审标准可预期、不串味）。

步骤 2：锁定审阅范围

按用户请求的优先级解析范围：

先把范围列出来发给用户确认，再开始file_read。锁定范围后不再 ask_user，而是在最终报告的Scope中列清楚实际审了什么。

步骤 3：逐文件 file_read

超过 800 行的文件分段读。优先看 diff 涉及的行，再看上下文与接口调用方。

步骤 4：回答 Q1-Q4 对抗性 framing

• Q1: Is this the right approach?—— 有没有更简单 / 更标准 / 更安全的实现路径？当前路径依赖了哪些隐含假设？
• Q2: What hidden dependencies could fail?—— OS / shell / 网络 / 并发 / 第三方 API 任一失效会怎样？
• Q3: What edge / hostile input breaks it?—— 空值、UTF-8 边界、Windows 路径、超长输入、并发写、过期 token、死代理。
• Q4: Is the failure mode observable & recoverable?—— 仅看日志能不能定位故障？能不能不动手就恢复？

每问至少要给出 1 条具体证据，不能空谈。

步骤 5：列 P0~P3 findings

遵守下述 §七 防误报八规则 + §八 措辞八规范，提交前过自检清单（§九 对应完整 prompt 的 §8 自检项）。

六、Severity / Verdict 速查

严重度分级（严格遵守，不要自创）

Verdict 决议规则

七、防误报八规则（成本低到高，任一答 No → 删 finding）

1. Discrete & actionable—— 有具体可写的修复吗？"整体不够优雅"不算 finding；多个交织的小问题要拆开各自记录。
2. Introduced or exposed by this change—— 是本次改动引入或放大的吗？祖传 bug 不要翻；预存 bug 被本次改动放大 → 显式标pre-existing, exposed by this change。
3. Not an intentional design choice—— 不要把作者的有意取舍当 bug：刻意保留的兼容层、有意宽松的 try/except 兜底、风格选择都不是 bug。
4. Provably affected, not speculated—— 跨文件影响必须能指出哪一段调用栈会被破坏；纯臆想"这可能影响 X 模块"不写。
5. Evidence-anchored—— 行号、代码片段、复现命令至少一项；"看起来"、"应该"、"或许"全删。
6. No unstated assumptions—— 不要依赖未明说的"代码库应该这样"约定；如果 finding 需要先假设作者意图才成立 → 删。
7. Author would likely fix if made aware—— 作者看到会同意修吗？"100 万 QPS 才塌"这种极端假设不要塞进 P1。
8. Impact meaningful + proportionate rigor—— 影响必须涉及 accuracy / performance / security / maintainability 之一；同时不要超出代码库本身的严谨度（一次性脚本仓库不要强求 PR 级注释和输入校验）。

每条规则的展开详见 review_inline_prompt.txt 的 §5。

八、措辞八规范

1. Why-first—— 第一句给原因，不绕弯。
2. 严重度准确—— 不要把 P2 写得像 P0；触发条件苛刻就在 impact 里立刻点出。
3. 简洁——evidence/impact/fix各 ≤ 1 段；除非代码片段需要换行，散文里不硬换行。
4. 少贴大段代码——evidence中代码 ≤ 5 行；超过用file:line-line引用，不要粘贴。
5. 触发条件显式——impact第一句就讲清在什么场景 / 输入 / 环境下出问题（如"在 Windows 路径含中文时…"），不让读者自己脑补。
6. 不卑不亢—— 直陈事实，不带"显然""糟糕""太蠢"等情绪；也不带"非常感谢""做得很好"等开场白。
7. 即读即懂—— 核心结论放第一句；需要读两遍才能懂的 finding 重写。
8. 零奉承—— 不写 "Great work, but..."、"Thanks for the changes, however..."。

展开详见 review_inline_prompt.txt 的 §6。

九、输出协议（整段 echo，不落盘）

评审报告必须按以下结构整段输出到对话，markdown 直接 echo，不落盘：

## Scope <一行一个文件，绝对路径或仓库相对路径> ## Verdict PASS / CONDITIONAL / FAIL ## Summary 3-6 行散文：整体印象 + 最重要的 1-2 个风险。 ## Design Challenge (Q1-Q4) - **Q1 是不是对的方法**: <证据> - **Q2 隐藏依赖**: <证据> - **Q3 边缘 / 敌意输入**: <证据> - **Q4 故障可观测**: <证据> ## Findings (P0 → P3 顺序) - **[P0, conf=0.9] file:line-line** 标题（动词开头，≤ 80 字，第一句给原因） - **Evidence**: 代码片段 ≤ 5 行 或 file:N-M 引用 - **Impact**: 触发场景 + 后果（第一句必带场景） - **Fix**: 可直接照做的修复思路，≤ 1 段 - **Principle**: 对应 code_review_principles 第 N 条 ## Cross-file notes 跨文件耦合 / 命名一致性 / 状态机 / 并发问题。无则 `(none)`。 ## Regression tests 3-5 条具体测试点（输入 / 预期 / 边界）。

该结构在 review_inline_prompt.txt 的 §7 中有逐字段说明：Scope列出本轮审阅的全部文件；Verdict按 §4 决议规则给出；Summary控制在 3-6 行散文；Findings按 P0 → P3 排序，每条必须带confidence_score（真 bug ≥ 0.8，拿不准 < 0.5）与对应的Principle编号。

提交前自检清单（对应完整 prompt 的 §8）

• code_review_principles.md已 file_read
• 每个待审文件都至少 file_read 一次
• Design Challenge4 个字段都有具体证据，不是空话
• 每条 finding 通过防误报八规则（discrete / introduced / not-intentional / provably-affected / evidence-anchored / no-unstated-assumptions / would-fix / impact-meaningful）
• 每条 finding 通过措辞八规范（why-first / accurate / brief / no-big-code / scenario-explicit / matter-of-fact / immediately-graspable / no-flattery）
• confidence_score老实给：真 bug → ≥ 0.8；拿不准 → < 0.5
• Verdict 与决议规则一致
• 没有奉承 / 开场白 / 复述用户目标 / 承诺修复

十、评审标准底料：15 条好代码原则

评审的每条 finding 都必须能映射到 code_review_principles.md 中定义的 15 条好代码原则之一。该文件是评审标准化的核心，主张"好的代码不是'能跑就行'，而是在长期演化中保持压缩性、局部性、可组合性与可证伪性"，15 条原则概括为：

1. 模块边界清晰（依赖方向稳定，指向抽象而非细节）
2. 局部可推理（看一个文件就能判断行为、代价与失败模式）
3. 可组合（小组件自然组合成大能力，接口一致、正交）
4. 变化半径小（改一个需求，改动集中、可预测）
5. 复杂度线性增长（新功能增量近似线性，重复少）
6. 约束写进代码（不变量写进类型 / 接口 / 校验 / 状态机）
7. 可测试、可观测（依赖可注入，日志指标能定位因果链）
8. 一致且不意外（命名 / 错误处理 / 资源管理 / 并发模型全局一致）
9. 自解释，注释极简（注释只出现在真正难以一眼看懂处）
10. 代码极简，视觉均匀（没有废话，行长度大致平均）
11. 函数式倾向，减少副作用（但不教条，以整体简单为目标）
12. 功能越多，代码应该越短（新功能复用已有结构而非堆砌）
13. 为未来的接入性设计（天然留有干净的调用入口）
14. Let it crash——按失败半径决定防御策略（大半径显式报错，零半径静默放过）
15. 篇幅分布跟着功能分布走（主功能占大部分，兜底压到最短）

文件末尾还提供了一段"快速自检"四问：能否不看全局安全地改局部？是否有清晰核心抽象让新功能主要是加实现？变化点是收敛在边界还是散落各处？出故障时能快速定位责任模块吗？四问皆"是"即为好代码。评审者正是以这套标准作为 finding 的Principle字段引用依据。

十一、扩展点

• 自定义评审条目：编辑 memory/code_review_principles.md，reviewer 启动时整段注入，即可自定义评审侧重；
• 触发更换：要把/review改成别的命令，只需改动 frontends/review_cmd.py 的install()一处——所有前端通过统一的_handle_slash_cmd挂载点接管，单点修改即全局生效。

小结

Review Mode SOP 为 GenericAgent 提供了一套轻量、零副作用、可复用的会话内对抗性评审机制：/review命令经 review_cmd.py 统一接管后，主 agent 在当前对话内按 review_inline_prompt.txt 的协议完成"读底料 → 锁范围 → 读文件 → Q1-Q4 对抗性 framing → 列 findings"五步评审，并遵循 P0~P3 严重度分级、Verdict 决议、防误报八规则与措辞八规范，最终按固定结构把报告 echo 到对话。其"不开 subagent、不落盘、不打 sentinel"的约束既避免了评审过程对工作区和对话状态机的污染，也把评审延迟压到最低——这正是它适合作为开发过程中高频自检工具的原因。

【免费下载链接】GenericAgentSelf-evolving agent: grows skill tree from 3.3K-line seed, achieving full system control with 6x less token consumption项目地址: https://gitcode.com/GitHub_Trending/pc/GenericAgent