深入解析 EGM Comprehension Goldfish:零假设"天真读者"文档审查器

原创2026-11-14 12:37:311,908 阅读
文章标签:AI 技能代码评审文档Agent 工作流

深入解析 EGM Comprehension Goldfish:零假设"天真读者"文档审查器

在 Elephant-Goldfish Model(EGM)的多智能体评审流水线中,agents/comprehension.md 定义了一位特殊的 Goldfish 审查者:它被刻意剥夺了全部项目背景,只能以一个"刚加入团队的新人"身份阅读文档。本文以该 persona 文件为骨架,逐条拆解它的强制约束、两种运行模式、五个审查步骤、输出契约,并结合仓库中的编排技能、适配层与测试用例,说明它在 /egm-review 流水线第 6 阶段为何不能被合成器替代、它的结论为何不能被作者"申辩"掉。读完你可以独立调用、调试并扩展这一审查器。

一、问题的起点:为什么需要一个"什么都不懂"的审查者

EGM 的整体设计动机写在 架构设计 中:当同一个 LLM 线程既访谈需求、又写设计、再写代码时,会话上下文会累积假设,模型倾向于验证自己的错误前提。EGM 的对策是把"有上下文的作者"与"无上下文的审查者"分离:

  • Elephant:持有项目历史、代码地图与需求的深度上下文代理,负责探索与起草。
  • Goldfish:在全新上下文中启动的零历史审查者,只拿着文档和被显式提供的阅读清单工作。

Comprehension Goldfish 是这支审查队伍里最极端的一位——它的价值不在于工程判断力,而在于它真的不知道。文档里凡是"团队都懂但没写出来"的东西,它都会暴露出来。它的 frontmatter 描述已经把这个定位写得很直白:

name: egm-comprehension
description: Naive Reader persona auditing documents with zero assumed institutional knowledge, flagging undefined terms, acronyms, and comprehension gaps.
license: Apache-2.0

这段元数据不是装饰。仓库的 frontmatter 单元测试 会遍历 agents/*.md,强制要求每个 persona 具备非空的 name 与 description;命名规范 还要求文件名使用 snake_case(comprehension.md)而 frontmatter 的 name 使用 egm- 前缀(egm-comprehension),因为这个 name 就是宿主在注册具名子代理时请求的子代理类型。

二、三条核心强制约束

persona 文件开头用 "Core Mandates (Universal Goldfish Context)" 一节,把所有 Goldfish 共享的纪律再申明一次,这三条直接决定了下游编排的正确性。

2.1 严格只读

"You are a strictly read-only agent. You have NO tools to modify the workspace, write files, or compile code. Do not attempt to fix or refactor any code."

这条约束在编排层被反复加固:skills/egm-review/SKILL.md 规定报告必须由调用方(Elephant 或合成器)写盘,审查者只返回自然语言结论。跨 harness 的适配文件同样把工具收窄为只读集合:

适配文件 工具/权限声明
.claude-plugin/agents/comprehension.md tools: [Read, Grep, Glob]、omitClaudeMd: true
.cursor-plugin/agents/comprehension.md readonly: true、permissionMode: readonly
com.github.copilot/agents/egm-comprehension.agent.md tools: [read, search]、include-custom-instructions: false

这些适配层只负责"工具与上下文裁剪",真正的评审逻辑统一回读到 agents/comprehension.md——Copilot 适配层明确写着必须读取 <EGM_ROOT>/agents/comprehension.md,"而不是用户项目里同名文件",以免被待审项目自己的约定污染。

2.2 无状态心智(Goldfish Isolation)

"You evaluate plans with zero conversational history or external assumptions. You must read the document as a naive team member or fresh reader who has just joined the project."

这不是修辞。Copilot 适配层进一步写明:"Do not retrieve parent history or memory." 并且只在阅读清单显式提供、且当前流程阶段要求时才允许读此前的审查报告。也就是说,这个审查者在物理上就拿不到"我们上周讨论过这个方案"的记忆。

2.3 不要闲聊

"Avoid conversational filler. Focus exclusively on technical rationale and findings. Do not narrate your tool usage."

这条约束是为了让它的输出可以直接被机器解析与合批。合成器的报告模板(见 agents/synthesizer.md)只接受"严重度 + 受影响范围 + 差异描述 + 理由"四段式结构,多余的寒暄会污染汇总。

三、角色设定:判定"可理解"的标准

Role 一节把标准写成了可执行的行为倾向:

"You expect explanations to be clear, logical, and self-contained. You do not accept hand-waving or vague descriptions, and you flag any concept that is not either defined inline or linked to external documentation."

拆开看是三条判定:

  1. 自包含(self-contained):读者只凭本文档就能建立完整心智模型。
  2. 拒绝含糊:不接受"系统会自动处理"这类没有解释机制的话术。
  3. 定义或链接二选一:每个自定义概念必须"就地定义"或"给出文档链接",二者皆无即为缺口。

注意第 3 条隐含了一个重要判据:链接也算合格。所以它不会强迫你把所有背景知识抄进文档,只要你提供可追溯的引用即可。

四、两种运行模式:BRAINSTORM 与 REVIEW

persona 的第一条指令是检查调用方传入的 Mode 参数。这是一个模式分派结构,同一份 persona 在不同阶段扮演不同角色。

4.1 Mode: BRAINSTORM —— 概念阶段的 UX 与人体工学镜头

在头脑风暴阶段,它不审文档,而是评估尚未成文的功能概念:

  1. API / CLI Ergonomics:提议的接口或工作流是否直觉?是否符合开发者惯例与生态既有实践?
  2. Cognitive Friction:错误信息是否可操作?概念是否引入了不必要的开发者复杂度?
  3. 反馈:把 UX 与人体工学意见回报给编排器。

这解释了为什么 skills/egm-brainstorm/SKILL.md 在七镜头并行审查里会把它列为 egm-comprehension:在 BRAINSTORM 模式下它是"UX & Developer Ergonomics"镜头,对应 brainstorm 设计文档 中的描述。合成器在 BRAINSTORM 模式下会为它挂上 UX & Ergonomics Brainstormer 之类的角色标题,以区别于 REVIEW 模式下的 Auditor/Reviewer/Critic 后缀。

4.2 Mode: REVIEW —— 文档审计五步法

这是主路径。persona 要求审查调用方指定的目标文件与行范围,并严格按以下顺序执行:

步骤 1:先复述(Paraphrase First)

"In your own words, write what the document proposes and how the existing system works, as the document describes it. If you cannot write a paraphrase of a section, report that section as a 🔴 Blocker. A list of undefined terms does not find a document whose terms are all defined but whose parts do not connect. The paraphrase does."

这是整份 persona 最有洞察力的一段设计。它给出了一个反例:术语全都定义过、但彼此接不上的文档,用"未定义术语检查"是抓不到的;而复述能抓到——因为你写不出一段通顺的复述,就说明逻辑链断了。

由此派生出一条硬规则:复述不出来的章节 = Blocker。

步骤 2:评估清晰度

在活动目标范围内阅读,评估解释的流向(flow)与清晰度,而不是逐句语法。

步骤 3:验证定义与链接

识别活动范围内引用的自定义术语、服务、系统、架构概念,逐个确认它满足其一:

  • 就地定义;
  • 在更早章节定义过;
  • 在本地术语表(glossary)中定义;
  • 附带指向其文档的链接。

步骤 4:自包含性回扫

"If a term is not defined within the active target scope, scan the rest of the target document to see if it was defined elsewhere before flagging it as a gap."

这一步是防误报的关键。在分阶段审查中,FeatureRange 与 DetailedRange 是分开送审的:定义可能落在另一个区间。所以必须先全文回扫,确认"真的哪里都没定义",才允许报缺口。

步骤 5:检查隐含前提

审计解释是否假定了读者已具备未言明的前置条件、依赖或副作用。典型例子:文档教你"执行某个工作流",却默认你已经完成了未写出的初始化步骤。

五、三条审计向量与误报边界

persona 把发现归纳为三类向量:

审计向量 含义 典型触发
Undefined or Unlinked Concepts 引用组件、工具或系统,却无简要定义也无文档链接 文中出现 MagicSync、InternalDB 之类内部命名
Assumed Workflow Prerequisites 描述如何执行任务,却假定读者已知未写出的准备步骤 "配置好后运行同步命令"但没说是哪个配置
Vague Explanations 使用不精确描述 "系统会自动处理",既没解释也没链接到"如何"处理

紧接着是一段极重要的范围纪律:

"You do not know this project. You do know software. Flag a term only when it is specific to this project, team, or design and is not defined. Do not flag general engineering terms."

翻译成人话:它不懂这个项目,但它懂软件。所以 HTTP、mutex、反向代理 这类通用工程词不该被报;只有"本项目、本团队、本设计特有且未定义"的词才算缺口。这条边界正是为了避免"天真读者"退化成"无知审查者"——后者会把整篇文档的每个技术名词都标红,产出无法收敛的噪声。

六、输出格式契约

6.1 REVIEW 模式的输出结构

输出必须是纯自然语言(不写文件),并固定以两段复述开头:

**What this proposes**
(2-5 句,用自己的话概括文档主张什么)

**How the existing system works, per this document**
(2-5 句,按本文档的描述概括现有系统如何运作)

persona 特意说明:"The author compares it with the intent. A wrong paraphrase is a finding."(作者拿它比对真实意图;复述错了本身就是一条发现)。这形成了一个巧妙的自我校验闭环:复述既是审查手段,也是可被作者反驳的产物。

随后每条发现固定三段:

  1. Severity:[Blocker | Major | Nit]
  2. Affected Scope:章节标题、概念术语或行号
  3. Discrepancy Description & Rationale:清晰度缺口或未言明假设的解释

6.2 BRAINSTORM 模式的输出结构

每条 UX 问题固定四段:Severity、Dimension(固定为 UX & Developer Ergonomics)、Usability Friction(不直觉的接口契约、含糊的错误行为、高认知负荷)、Ergonomic Requirement(对 Concepts Brief/PRD 的强制 UX/人体工学要求)。

注意 Ergonomic Requirement 这一项不是建议而是要求:它要求把 UX 结论变成可验收的约束条目,这与 skills/egm-brainstorm/SKILL.md 中 concepts_brief.md 的 Goals vs. Non-Goals 结构是配套的。

七、在五阶段评审流水线中的特殊地位:第 6 阶段

skills/egm-review/SKILL.md 定义的完整流水线包含:

阶段 名称 审查者
Stage 5 Initial Zoom Out egm-zoom-out + egm-inventive-catalyst
Stage 6 Comprehension Test egm-comprehension(直派)
Stage 7 Critic Review egm-design + egm-structural + egm-style
Stage 8 Intermediate Zoom Out egm-zoom-out
Stage 9 Implementation Readiness egm-implementation-readiness + egm-codebase-details + egm-style

Comprehension Test 的 Subflow 有三条不可违反的编排规则,全部写在 skills/egm-review/SKILL.md:

7.1 必须直派,不能经过合成器

"Spawn the egm-comprehension subagent at agents/comprehension.md on FeatureRange & DetailedRange with no document standard. Do not use the synthesizer: its report keeps only findings, and the author must see the paraphrase."

原因很实际:合成器的职责是"去重 + 归一化 + 只保留结论"(见 agents/synthesizer.md)。而复述恰恰是 Comprehension 的核心产物——它必须原样呈现给作者,否则作者无法判断"审查者误解了我"还是"我真的写糊了"。这是整条流水线里唯一强制绕过合成器的阶段。

7.2 不加载任何文档标准

"The test is self-containment, not detail. Do not apply re-implementation-standard.md: it asks for code-level detail, which the Zoom Out standard forbids in FeatureRange."

也就是说,Stage 6 的判据是自包含,不是详尽。如果给它套上 实现级标准,一份合格的架构文档会因为"缺少函数签名"而被打回,直接与 Stage 5/8 的 YAGNI 与 Zoom Out 标准冲突。仓库甚至为此写了专门的回归场景(见下文)。

7.3 报告必须保留复述,即使零发现

"Start with the two paraphrase headings verbatim, then the findings. Keep the paraphrase when there are no findings."

产出为 comprehension_report.md,随后进入 Stage 6 的三态检查点门:进入 Stage 7、先改文档(暂停后重跑)、暂停评审。

八、与 egm-resolve 的交互:不可被申辩的发现

EGM 的解决引擎允许作者对每条发现作出 PROPOSE FIX、CONTEST、ESCALATE、DECLINE 四种裁定。但对 Comprehension 的发现有一条专门禁令,写在 skills/egm-resolve/SKILL.md:

"Do not contest a comprehension gap. If a fresh reader could not follow the document, the document is missing context."

配套还有一条更一般的纪律:"Do not add context only to satisfy a reviewer. Add context when a human reader of the document needs it." 换言之——如果只有零上下文的子代理需要这段上下文,勉强补进去反而污染文档,应改用 ESCALATE 交给人类裁定;但如果真实的人类新读者也会看不懂,那就是文档缺陷,必须补。

这条规则让 Comprehension 的结论具有近似"不可反驳"的地位,因为反驳本身需要引用"审查者能读到的证据",而"我脑子里知道"不算证据。

九、跨 harness 的一致性如何被保证

同一份 persona 要在 Antigravity、Claude Code、Codex、Copilot CLI、Cursor、omp、Muse 等多个宿主上表现一致,仓库用三层机制兜底:

  1. persona 单点真源:所有适配层都回读 agents/comprehension.md,Copilot 适配层甚至明确警告"不要用用户项目里的同名文件"。
  2. 注册表校验:tests/unit/test_harnesses.py 维护了一份 REVIEWERS 清单(codebase_details、comprehension、design_critic、implementation_readiness、inventive_catalyst、structural、style、zoom_out),确保新宿主接入时不漏注册。
  3. 打包清单:scripts/pack_plugin.py 的 REQUIRED_SHARED 把 agents/comprehension.md 列为必需文件,缺失即构建失败,避免发布包里只剩适配壳子而没有 persona 本体。

此外,harnesses 文档 说明了"没有子代理工具的宿主必须停下来"这一硬性前提——因为与主代理同上下文评审,就不再是 Goldfish 评审了。

十、实战:如何触发与验证这一审查器

10.1 通过完整评审流水线触发(推荐)

在项目里准备一份设计文档(/egm-draft 产出的标准结构,含 ## Detailed Implementation Plan 边界头,见 draft 设计文档),然后:

/egm:egm-review docs/designs/webhooks.md

在 Claude Code 与 agy CLI 中使用 /egm: 前缀;在 Codex 中从 skill 选择器中选对应 EGM 技能。评审会依次跑完 5 个阶段,Stage 6 就是 Comprehension Test。

10.2 只跑第 6 阶段

Step 参数支持单阶段定位(5、6、7、8、9),因此可以直接指定:

/egm:egm-review docs/designs/webhooks.md
Step: 6

预期行为:直派 egm-comprehension、不加载任何文档标准、写出 comprehension_report.md 且首两段是逐字保留的复述标题。

10.3 通过 review-loop 直接点名单个审查者

若只想做一次轻量审计,可用 skills/egm-review-loop/SKILL.md 的参数化入口:Reviewers 中填短名 comprehension,它会映射到 agents/comprehension.md;Standards 为该审查者留空或指向自定义路径;GoldfishContext 传入阅读清单。

10.4 用仓库自带场景做回归验证

skills/egm-review/test_scenarios.yaml 里有三个直接针对该 persona 的确定化场景,可作为行为契约的活文档:

场景 ID 断言要点
comprehension_auditor_undefined_jargon 对 "The synchronizer will save data to InternalDB using MagicSync." 必须报出 MagicSync 或 InternalDB 未定义
comprehension_without_reimplementation_standard 被问"第 6 阶段用哪个文档标准"时,答案必须是"无标准/自包含",而非 re-implementation 标准
comprehension_report_keeps_paraphrase 即使零发现,comprehension_report.md 也必须包含复述(paraphrase)

本地跑相关单测(仓库使用 pytest,配置见 pyproject.toml):

python -m pytest tests/unit/test_frontmatter.py tests/unit/test_harnesses.py -q

这两组测试分别校验 persona 的 frontmatter 合法性与跨宿主 reviewer 注册完整性。

十一、使用边界与常见误区

  • 它不是"文档质量总检"。它只判断"新读者能否自洽地读懂";架构合理性归 egm-design,YAGNI 归 egm-zoom-out,文件路径与函数签名归 egm-codebase-details。
  • 它的 Blocker 不等于"文档很差"。复述失败通常意味着章节之间缺少承接句或缺少前置定义,属于结构性问题,修起来往往只需补一段衔接。
  • 零发现不代表通过。报告里必须保留复述;作者应比对复述与自己的真实意图,复述错位本身就是最高价值的发现。
  • 它需要新鲜上下文。若宿主无法创建隔离子代理,正确的做法是停止评审并告知用户,而不是在当前会话里"假装"跑一遍。
  • 它不会替你写修复。persona 是无工具只读的,任何修订都必须回到 Elephant 上下文,经 egm-resolve 分类后再落盘。

十二、小结

agents/comprehension.md 只有 69 行,但它精确刻画了一种在 AI 辅助设计中长期被忽视的角色:没有背景知识的读者。它用"先复述、再检查"的顺序把主观的"清晰度"变成可判定的产物;用"只标本项目特有术语"的边界防止噪声爆炸;用"不加载任何文档标准、不经合成器、不可被申辩"三条编排规则,保证这份最容易被稀释的审查结论原样抵达作者。理解这一 persona,也就理解了 EGM 整个评审体系的核心假设——上下文是作者的优势,也是作者的盲区。

登录后查看全文
elephant-goldfish-model