跳转至

EGM Goldfish 评审协议与解决引擎


概述

Goldfish 评审协议是 Elephant & Goldfish Model (EGM) 的验证引擎。它使用隔离的、零上下文的 AI 子代理(“Goldfish”)对草拟的设计规范进行压力测试,并依据严格的质量评分标准评估文档。

本文档规定:

  1. 多阶段评审流水线(/egm-review)。
  2. 评审编排驱动器(egm-review-loop)。
  3. 完整的分化评审角色目录。
  4. 与文档标准和评估评分标准的映射(resources/document_standards/)。
  5. 交互式解决引擎(egm-resolve)。

The Problem

编写 LLM 的自我评审存在严重的确认偏差。当同一个上下文窗口起草并评审一个计划时:

  1. 盲区持续存在:模型假设其记忆中持有的上下文在文本中是显而易见的,从而忽略未明说的假设和未定义的术语。
  2. 幻觉掩盖:讨论期间形成的无效 API 假设未经实际源代码检验。
  3. 过早批准实施:缺乏具体文件路径或测试策略的实施计划未经审查就被橡皮图章式批准。

Goldfish model 通过生成全新的、无状态的子代理来缓解这个问题,这些子代理只读取目标文档和明确引用的源文件。

评审流水线架构(/egm-review)

完整的评审流水线执行五个顺序评估阶段:

flowchart TD
    Start([Target Design Doc]) --> Step5["Step 5: Initial Strategic Review (Zoom Out + Inventive Catalyst)"]
    Step5 --> Gate5{Pass / Abort?}
    Gate5 -- Abort --> FixArch[Refactor Architecture]
    Gate5 -- Pass --> Step6[Step 6: Comprehension Test]
    Step6 --> Gate6{Gaps Found?}
    Gate6 -- Yes --> UpdateContext[Clarify Definitions / Context]
    Gate6 -- No --> Step7[Step 7: Critic Review]
    Step7 --> Loop7[egm-review-loop: design_critic + structural + style]
    Loop7 --> Resolve7[egm-resolve]
    Resolve7 --> Step8[Step 8: Intermediate Zoom Out Review]
    Step8 --> Gate8{YAGNI / Bloat Found?}
    Gate8 -- Yes --> PruneBloat[Prune Defensive Over-Engineering]
    Gate8 -- No / Resolved --> Step9[Step 9: Implementation Readiness Test]
    Step9 --> Loop9[egm-review-loop: implementation_readiness + codebase_details + style]
    Loop9 --> Resolve9[egm-resolve]
    Resolve9 --> Done([Ready for Human Peer Review])

阶段分解

  1. 步骤 5:初始战略评审(高度与矛盾检查):
    • 目标:完整文档。
    • 角色人设:zoom_out(怀疑派架构师),inventive_catalyst(Inventive Catalyst)。
    • 标准:zoom-out-standard.md(针对 zoom_out)、内联模式目录(针对 inventive_catalyst)。
    • 重点:验证问题框架,拒绝投机性功能(YAGNI),识别技术矛盾,建议模式解决方案,并在投入详细评审流程之前验证对现有基础设施的复用。
  2. 步骤 6:理解力测试(自包含检查):
    • 目标:FeatureRange 与 DetailedRange 的比较。
    • 角色人设:comprehension(天真读者)。
    • 标准:基线自包含性。
    • 重点:在零先验上下文的情况下阅读文档;识别缺失的先决条件、未解释的缩写和概念空白。
  3. 步骤 7:批评者评审(对抗性压力测试):
    • 目标:FeatureRange(高层架构)。
    • 角色人设:design_critic、structural、style。
    • 标准:feature-spec-standard.md(适用于 design_critic 和 structural)。
    • 重点:探测单点故障(SPOFs)、扩展限制、故障模式和边界情况。
  4. 步骤 8:中期 Zoom Out 评审(批评者后修剪):
    • 目标:完整文档。
    • 角色人设:zoom_out(怀疑派架构师)。
    • 标准:zoom-out-standard.md。
    • 重点:增量审计,重点关注在理解力测试和批评者评审期间引入的补充、修改和防御性缓解措施。在任务规划之前清除投机性复杂性和 YAGNI 元素,同时避免重新标记在步骤 5 中已接受的决策。
  5. 步骤 9:实施就绪度测试(可操作性检查):
    • 目标:DetailedRange(## Detailed Implementation Plan)。
    • 角色人设:implementation_readiness、codebase_details、style。
    • 标准:implementation-readiness-standard.md(适用于 implementation_readiness 和 codebase_details)。
    • 重点:验证所有触及的文件是否都作为具有明确理由的、相对于仓库的显式写入边界列出;API 签名是否与当前代码库现实匹配;以及是否存在逐步测试计划。

审阅者角色目录

所有审阅者角色的提示词均位于 agents/ 目录下:

Persona 文件 角色名称 核心职责
agents/zoom_out.md 怀疑派架构师 审计过度工程、YAGNI 和不必要的复杂性。搜索代码库中已有的工具,以避免重复造轮子。
agents/comprehension.md 新手读者 假定不具备任何先验知识。识别未定义的术语、隐含的系统上下文和缺失的架构图。
agents/design_critic.md 分析式设计评论员 评估系统可靠性、规模限制、运维风险、故障恢复以及权衡取舍的合理性。
agents/implementation_readiness.md 技术负责人审计员 确保实施计划包含无歧义、确定性的指令、完整的文件列表和验证步骤。
agents/codebase_details.md 代码库审计员 将所引用的路径、类和函数签名与实时源代码进行交叉核对,以防止漂移和虚构的 API。
agents/structural.md 版式验证员 强制标准的标题层级、表格格式和文档模板符合性。
agents/style.md 技术文案编辑 去除对话式填充内容,强制事实性、客观的语气,校准防御性注意事项(DROP / CALIBRATE / RELOCATE / KEEP),并确保遵循简洁的技术写作标准。
agents/inventive_catalyst.md Inventive Catalyst 应用 TRIZ 原则来识别技术矛盾、虚假妥协和基于模式的解决方案。
agents/synthesizer.md 审阅综合器 并行启动多个审阅者,对发现进行去重,格式化文件链接,并编写合并后的报告产物。

文档标准与评分细则(resources/document_standards/)

审阅者根据共享运行时资源中列出的版本化标准来评估草稿。请阅读实际标准以了解其要求。上面的阶段划分将每次审阅映射到其对应的标准;它并不取代那些评分细则。


交互式解决引擎(egm-resolve)

当 Goldfish 审阅者完成其审计后,Elephant Resolution Engine 会读取扁平化的发现列表并管理交互式分类处置。

1. 评估与分类

对于每一条发现,Elephant 会判断:

  • PROPOSE FIX:评论有效。生成精确的替换字符串或结构性编辑。
  • CONTEST:评论无效或基于误解。引用具体的代码库证据来维护当前文本。
  • ESCALATE:评论无效,但只有被审阅文件之外的知识才能反驳它。由用户决定。Elephant 不会添加只有零上下文审阅者才需要的上下文。
  • DECLINE:该发现是一个小问题。它会被记录,但不会被修复。

争辩必须引用审阅者能够阅读到的证据。理解缺失不能作为争辩对象,而且若无争辩,严重级别不可更改。

2. 用户分类处置模式

工程师通过四种交互模式审阅 goldfish_review_report.md:

  • Auto Accept:批量应用所有 PROPOSE FIX 建议,并跳过 CONTEST 项。
  • Interactive Breakdown:按顺序逐项进行聊天式讲解,并提供详细解释和推翻能力。
  • Artifact Comments:对产物进行内联评论,由 Elephant 解析并应用。(推荐)
  • Wildcard Requests:暂停审阅以回答临时问题或运行探索性命令,然后再恢复分类处置。

3. 迭代与检查点门控

应用修复后,该循环会呈现一个强制性检查点,询问用户是再运行一轮审阅还是完成工作流。被争辩或未修复而被记录的发现会在各轮之间保持已定论状态。如果后续审阅再次提出某条已修复的发现,该发现会重新打开。当一轮的审阅结果中不包含任何未解决的 Blocker 或 Major 发现时,该轮即为干净。该过程在连续两轮干净之后结束,或者当工程师停止循环时结束。当达到 5 轮,或当出现的新发现本可通过还原先前修复来解决时,循环会询问工程师:接受、继续,还是返回起草阶段。

实施文件

文件路径 类型 目的与存在理由
skills/egm-review/SKILL.md 技能定义 编排多阶段审阅流水线的入口点(Zoom Out $\rightarrow$ Comprehension $\rightarrow$ Critic $\rightarrow$ Intermediate Zoom Out $\rightarrow$ Readiness)。
skills/egm-review/TEST.md 单元测试 验证测试场景,用于测试 /egm-review 多阶段流程和检查点门控。
skills/egm-review/test_scenarios.yaml 评估基准 评估模型审查精确率和召回率的基准测试套件。
skills/egm-review-loop/SKILL.md 技能定义 核心审查驱动程序,管理异步子代理的生成与发现结果的收集。
skills/egm-review-loop/TEST.md 单元测试 验证测试场景,测试 goldfish 审查循环的派发。
skills/egm-review-loop/test_scenarios.yaml 评估基准 评估 goldfish 审查循环派发的基准测试套件。
skills/egm-resolve/SKILL.md 技能定义 Elephant 解析引擎,管理 CONTEST 与 PROPOSE FIX 的分类及自动修复。
skills/egm-resolve/TEST.md 单元测试 用于验证发现分类和解析循环的验证测试场景。
skills/egm-resolve/test_scenarios.yaml 评估基准 评估模型解析和修复建议准确性的基准测试套件。
agents/*.md 角色提示词 面向全部 8 位 Goldfish 审查者和 Synthesizer 的系统提示词指令。
resources/document_standards/*.md 文档标准 用于功能规格、实现就绪性和简洁性的评估量规和标准。

参考资料

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 el/elephant-goldfish-model