Elephant-Goldfish Model 的 Copilot Comprehension 评审代理剖析:零上下文读者如何审计文档自包含性
Elephant-Goldfish Model 的 Copilot Comprehension 评审代理剖析:零上下文读者如何审计文档自包含性
在 Elephant-Goldfish Model(EGM)的多智能体评审体系里,“Comprehension Goldfish” 扮演一个刚加入项目、没有任何历史上下文的新读者,专门检查设计文档是否自包含。本文以 Copilot CLI 适配层中的 egm-comprehension.agent.md 为主线,拆解它的 frontmatter 契约、提示词约束、与 canonical persona 的绑定方式,以及它在 /egm-review 流水线第 6 阶段(Comprehension Test)中的真实调用链与离线验证手段。读完后你将能够独立配置、调试并验证这一评审代理,并理解它为何必须被“直接派发”而不是经过 synthesizer 汇总。
一、为什么要单独存在一个“理解力”评审者
EGM 的评审协议建立在这样一个判断上:同一个上下文窗口既起草又自审,会产生确认偏差——模型以为写在记忆里的背景在文档里也显而易见,于是未声明的前提、未定义的缩写被系统性放过。参见 docs/designs/review.md 中对自审风险的三点归纳。
Comprehension 评审者正是针对这一失效模式的补丁。它与其他七位 Goldfish 的关键差别在于:
| 维度 | Comprehension Goldfish | 其他评审者(如 design / structural / style) |
|---|---|---|
| 评判对象 | 文档是否“可被复述”、是否自包含 | 设计取舍、结构规范、文风与措辞 |
| 是否使用文档标准 | 不使用任何 resources/document_standards/* 标准 |
绑定 feature-spec / implementation-readiness 等标准 |
| 派发方式 | 主会话直接派发该 persona | 通常经 egm-synthesizer 并行调度后汇总 |
| 产出特殊性 | 必须先给出两段复述(paraphrase) | 仅输出 findings 列表 |
“直接派发”这一点在 skills/egm-review/SKILL.md 的 Comprehension Test 子流程中被明确写死:不要使用 synthesizer,因为它的报告只保留 findings,而作者必须看到复述内容。这也是理解 Copilot 适配版为何要单独维护一份 profile 的原因——它承载的是“不可被汇总器吞掉”的语义。
二、Copilot 适配层的最小契约:frontmatter 逐字段解读
com.github.copilot/agents/egm-comprehension.agent.md 的 YAML frontmatter 只有五个键,且这五个键是被测试逐个锁定的:
---
name: egm-comprehension
description: Document comprehension review using the canonical EGM persona. Experimental Copilot CLI adapter.
tools: [read, search]
include-custom-instructions: false
user-invocable: false
---
| 字段 | 取值 | 作用与影响 |
|---|---|---|
name |
egm-comprehension |
与 canonical persona 在 agents/comprehension.md 中的 name 完全一致;Copilot 侧注册后对外 ID 为 egm:egm-comprehension |
description |
英文描述,末尾标注 “Experimental Copilot CLI adapter.” | 供宿主展示与选择;明确其为实验性适配器,而非已认证集成 |
tools |
[read, search] |
只给只读与搜索能力,从宿主层面阻断写文件与命令执行 |
include-custom-instructions |
false |
要求委派出的子代理不继承自定义指令(该字段在 Copilot 上的实际强制力尚未验证,见 docs/copilot.md) |
user-invocable |
false |
评审者不允许被用户直接选为主会话,只能被入口代理委派 |
这套字段并非风格偏好,而是被 tests/unit/test_copilot_adapter.py 强制校验的:
for persona in REVIEWERS:
canonical = repo_root / f"agents/{persona}.md"
name = frontmatter(canonical)["name"]
profile = profiles / f"{name}.agent.md"
config = frontmatter(profile)
assert config["name"] == name
assert config["tools"] == ["read", "search"]
assert config["include-custom-instructions"] is False
assert config["user-invocable"] is False
assert set(config) == {
"name", "description", "tools", "include-custom-instructions",
"user-invocable",
}
注意最后一条断言:键集合必须精确等于这五项。这意味着给适配器新增任何 frontmatter 字段(例如自定义 model、mcp-servers)都会让 CI 失败。测试同时校验正文里必须出现 <EGM_ROOT>/agents/{persona}.md、必须包含 incomplete review 与 Do not retrieve parent history,并禁止出现 ${(即不得依赖未文档化的 Markdown 变量展开)。这正是 docs/copilot.md 强调的一点:profile 中的 <EGM_ROOT> 是任务传入的路径占位,不是环境变量插值。
三、正文的六条硬约束:代理被要求做什么
去掉 frontmatter 后,适配文档的正文只有十余行,但每条都是可判定的行为约束:
- 只使用被指派的任务与显式阅读清单。不得自行扩展阅读范围,避免把父会话的推理带进来。
- 必须由调用方提供绝对的 EGM 包根目录,并先读
<EGM_ROOT>/agents/comprehension.md,且明确要求“遵循那个 canonical persona,而不是用户项目里同名文件”。这是一条防劫持设计:如果用户工作区恰好存在agents/comprehension.md,适配器也不会误读。 - 捆绑标准解析到
<EGM_ROOT>/resources/document_standards/,目标文档与每个必需标准的绝对路径都由调用方给出。 - 读取目标文档、必需标准、以及被显式引用的源文件;任一必需路径缺失或不可读,就返回一份不完整的评审(incomplete review)。这一条把“静默降级”变成显式失败。
- 不得检索父历史或记忆;只有在阅读清单中显式给出、且 canonical 工作流阶段要求时,才允许读取此前的评审报告。
- 不得编辑文件、执行命令、委派子代理或使用 MCP 工具;把发现与读过的路径通过原生返回值交回调用方;报告由调用方撰写;不得凭自我报告宣称“独立验证”。
第 4 条与第 6 条合起来定义了责任边界:Comprehension 代理是纯函数式的“读 → 判 → 返回”,落盘与行号归一都留给主会话。这与 agents/synthesizer.md 中 “Artifact-First Delivery” 的职责划分一致,但 comprehension 连 artifact 都不写。
四、canonical persona:复述优先的审计方法
适配层只是外壳,真正的判定逻辑在 agents/comprehension.md。它先声明三条通用 Goldfish 规约:严格只读、金鱼式无状态、不寒暄不叙述工具调用;随后定义角色:
你表现得像一个刚加入项目的新团队成员或全新读者,没有任何历史上下文或未言明的项目知识。你期待解释清晰、有逻辑、自包含。你不接受含糊其辞,任何既未就地定义、也未链接到外部文档的概念都必须被标出。
4.1 REVIEW 模式的五步审计
针对文档审计(Mode: REVIEW),流程是有序的:
- 先复述(Paraphrase First):用自己的话写出“文档提出了什么”以及“按文档描述,现有系统如何工作”。如果某节无法复述,直接将该节报为 🔴 Blocker。文档对此给了一个很关键的论证:一份“术语全都定义了但各部分接不上”的文档,靠罗列未定义术语是发现不了的,而复述可以。
- 评估清晰度:在活动目标范围内判断解释的推进与连贯。
- 核实定义与链接:识别范围内的自定义术语、服务、系统与架构概念,逐一确认其已在文档中定义(就地、前文小节或本地术语表)或附带文档链接。
- 自包含性回扫:若某术语在活动范围外未定义,先扫描目标文档其余部分,确认它是否在别处定义过,再决定是否记为缺口——避免把“跨节定义”误报成缺失。
- 检查隐含前提:确认解释没有假定读者已知某个前置条件、依赖或副作用。
4.2 三类审计向量与一条重要的“不报”规则
审计向量被归纳为三类:
- 未定义或未链接的概念:引用组件、工具、系统却不给简短定义或文档链接。
- 被假定的流程前置:描述如何执行任务,却假定读者已知未言明的准备步骤。
- 含糊解释:使用不精确表述,例如“系统会自动处理”,却不解释或链接到如何处理。
紧接着是一条常被忽略的边界:
你不了解这个项目。你了解软件。只有当术语是本项目、本团队或本设计特有且未被定义时才标记它。不要标记通用工程术语。
这条规则直接决定了误报率。SLO、replication lag、idempotent 一类通用工程词汇不该被 comprehension 记为缺口;而 MagicSync、InternalDB 这类项目专有名词必须被标出——skills/egm-review/test_scenarios.yaml 中的 comprehension_auditor_undefined_jargon 场景就是用它作为判定基准。
4.3 BRAINSTORM 模式
同一个 persona 也被复用到构思阶段(Mode: BRAINSTORM)。此时它不审文档,而是评估原始功能概念的 UX 与开发者工效:
- API / CLI 工效:接口或流程是否直观,是否符合开发者惯例与生态既有做法。
- 认知摩擦:错误信息是否可操作,概念是否引入了不必要的复杂度。
在 skills/egm-brainstorm/SKILL.md 中,comprehension 是七位并行评审者之一,由 synthesizer 统一调度,产物汇总进 concepts_brief.md。注意这里的派发方式与 REVIEW 阶段不同——构思阶段允许汇总,评审阶段则必须直连。
五、输出格式:为什么 comprehension_report.md 前两段不能省
REVIEW 模式的输出格式要求先给两段复述,且标题固定:
- What this proposes(2–5 句)
- How the existing system works, per this document(2–5 句)
随后才是逐条 finding,每条包含三项:
1. Severity: [Blocker | Major | Nit]
2. Affected Scope: Section heading, concept term, or line numbers.
3. Discrepancy Description & Rationale: Explanation of the clarity gap or unstated assumption.
作者拿这两段复述去比对原意:复述错了,本身就是一条 finding。这是 comprehension 与普通“挑刺式”评审的根本区别——它先证明自己读懂了,再指出别人读不懂的地方。
这条格式要求在编排层被再次加固。skills/egm-review/SKILL.md 的 Comprehension Test 子流程规定:把完整评审结果写入 comprehension_report.md,以那两段复述标题原样开头,然后才是 findings;即使没有 findings 也要保留复述。对应的回归场景是 comprehension_report_keeps_paraphrase(skills/egm-review/test_scenarios.yaml)。
还有一个容易被误配的细节:该阶段不使用任何文档标准。comprehension_without_reimplementation_standard 场景要求模型回答 “no standard / self-containment”,理由是 re-implementation-standard.md 索要代码级细节,而高 altitude 的 feature range 恰恰禁止这种细节。这与本文开头那张对比表的第二行完全对应。
六、在 Copilot CLI 上真正跑起来
Copilot 适配目前是实验性的,docs/copilot.md 明确说明:工作流执行与评审者隔离尚未验证,且不代表支持 VS Code 内的 Copilot 或云端 agent。离线参考版本是 GitHub Copilot CLI 1.0.82。
6.1 前置校验
EGM_ROOT=/absolute/path/to/elephant-goldfish-model
git -C "$EGM_ROOT" rev-parse HEAD
copilot --version
COPILOT_OFFLINE=true copilot --plugin-dir "$EGM_ROOT" plugin list
最后一条命令必须把 egm 列在 external plugins 下。它只验证注册,不验证评审者执行。若需要隔离的用户配置,把 COPILOT_HOME 指向一个新目录——但这“不会禁用所有用户级 skill 或项目指令”,所以实测前应先检查宿主清单。
仓库根目录的 plugin.json 是唯一的身份来源(name: egm、version: 0.1.1),Copilot 专用 profile 全部位于 com.github.copilot/agents/。必须使用完整 checkout 并固定到候选 commit,且保持该 checkout 在会话期间不被改动;不要只复制 skills/ 或单独安装 profile 目录,因为 canonical persona 与标准运行时要按包根目录解析。
6.2 启动与首次请求
在获得明确的模型使用授权后,从目标项目目录启动:
copilot --plugin-dir "$EGM_ROOT" --add-dir "$EGM_ROOT" --agent egm:egm
首条消息必须给出绝对包根与所需 skill:
EGM package root: /absolute/path/to/elephant-goldfish-model
Read that package's docs/copilot.md and run egm-review.
Target document: /absolute/path/to/project/docs/designs/rate_limit.md
EGM artifact directory: .dev/docs
入口代理 com.github.copilot/agents/egm.agent.md 负责读取 <EGM_ROOT>/docs/copilot.md 与对应 skills/<skill>/SKILL.md,并用宿主的原生委派工具按命名空间 ID 选择评审者。必须使用 egm:egm 作为入口代理,这样宿主映射会在 skill 之前加载;直接拿某个评审者当主会话,并不能建立新的 Goldfish 上下文。
6.3 委派 comprehension 评审者
八位评审者的映射关系在 docs/copilot.md 中以表格给出,comprehension 对应 egm:egm-comprehension → agents/comprehension.md。派发时只需构造一个包含模式、目标、行范围、persona、标准与显式阅读清单的任务,例如:
Mode: REVIEW
Persona: egm-comprehension
EGM package root: /absolute/path/to/elephant-goldfish-model
Canonical persona: <EGM_ROOT>/agents/comprehension.md
Target: /absolute/path/to/project/docs/designs/rate_limit.md
Line ranges: FeatureRange 1..180; DetailedRange 181..420
Standards: none (self-containment test)
Reading list: the target above, plus the source files it explicitly references
Return: paraphrase under both headings, then findings with severity, scope, rationale
要点有四:
- 每次调用(含重复评审)都要新起一个原生子代理,不要把同一个 child 复用成第二轮。
- 不要转发会话、私有推理、记忆,或目标文档本应解释的答案——转发就等于破坏了这个评审者的全部价值。
- 只有第 8 阶段(Intermediate Zoom Out)才被允许在阅读清单里带上
zoom_out_report.md,其他历史发现一律不得检索。 - 必须等待每个原生子代理完成后再综合。子代理缺失、读取失败、超时或工具被拒,都使该阶段成为 incomplete;此时应停止并报告限制,绝不允许模拟子代理,或把“没有发现”当成通过。
七、离线验证:测试到底证明了什么
适配层的可验证性来自三组测试,它们都不调用模型。
7.1 契约与路径解析
tests/unit/test_copilot_adapter.py 会把整个运行时(skills、agents、resources、docs、com.github.copilot、.plugin 与根 plugin.json)复制到一个含空格与 Unicode 的临时目录(relocated EGM café),然后逐字节比对,并用正则抽取 profile 正文里所有 <EGM_ROOT>/... 引用,断言它们在搬迁后的包中真实存在:
for relative in re.findall(r"<EGM_ROOT>/([\w/.-]+)", text):
assert (copilot_package / relative).exists(), (profile.name, relative)
assert not (copilot_package / "com.github.copilot/skills").exists()
这解释了为什么正文里必须写 <EGM_ROOT>/agents/comprehension.md 这种路径形式:它是可被静态校验的资源契约,而不是散文式描述。
7.2 原生加载器发现(不发送 prompt)
设置 EGM_COPILOT_OFFLINE=1 且本机装有 1.0.82 时,测试会启动一个只返回 503 的本地 provider,用 --headless --stdio 拉起 CLI,并通过三个 SDK 协议操作取证:
session.create:创建一个会话(本地 provider 会拒绝一切请求)。session.agent.list:断言八个source: plugin记录,且每个 profile 的path、tools、userInvocable、mcpServers与 frontmatter 一致。对本文主角而言,即是tools == ["read", "search"]且userInvocable == false。session.skills.list:断言七个 skill 均enabled: true。session.destroy:销毁会话。
测试最后断言 provider_requests == [],即本地 provider 收到零个请求;gpt-4.1 只是会话元数据,没有模型真的执行。历史记录(2026-10-24)显示 1.0.82 能从挂载包中加载全部八个 profile 与七个 skill。
EGM_COPILOT_OFFLINE=1 pytest tests/unit
7.3 发现的边界
必须反复强调:发现不等于执行。上述测试不能证明 skill 会跑通、写入会被拒绝、上下文真的隔离;RPC 清单也不暴露 include-custom-instructions 的强制结果。要主张“支持”,需按 docs/copilot.md 把三类证据分开记录——安装(候选 SHA、包身份、资源完整性、已加载 profile)、工作流(宿主版本、模型标识、原生子代理的启动与完成、必需读取、产物路径、真实的人工审批暂停)、隔离(父会话独有标记、实际子上下文、注入指令、记忆与 MCP 暴露、对一次性夹具的写入尝试)。检查写入拒绝要看工具记录,评审者的口头承诺不构成强制。
八、常见配置错误与排查对照
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
子代理读到了用户项目里的 agents/comprehension.md |
未传绝对包根,或正文未按 <EGM_ROOT> 解析 |
在任务中显式给出 <EGM_ROOT>/agents/comprehension.md 绝对路径 |
| 报告里没有复述,只有 findings | 走到了 synthesizer 而没直连 comprehension | 改为直接派发 egm:egm-comprehension,并保留两段复述标题 |
| 复述缺失却仍返回“通过” | 把缺失的子代理当成了零发现 | 视为 incomplete,停止并报告限制 |
| 报了大量通用术语缺口 | 未遵守“只标记项目特有术语”规则 | 在任务中重申该边界,或核对 persona 是否被正确加载 |
| 路径含空格/中文时读取失败 | 传参时按空白拆分了路径 | 保留空格与 Unicode,整条绝对路径传参 |
| frontmatter 加了字段后 CI 变红 | 键集合被测试精确锁定 | 保持仅 name/description/tools/include-custom-instructions/user-invocable |
| 误开了 Stage 9 的评审 | 用了 Feature spec only 之外的预设去跑只读场景 |
明确 Step: 6 或 feature_spec,该预设会在 Stage 8 后干净停止 |
九、小结
egm-comprehension 的 Copilot 适配文件只有十几行,却是整个 EGM 隔离评审思想最凝练的落点:外壳负责边界(只读工具、不可被用户直呼、不继承指令、不碰父历史、不写文件),人格负责方法(先复述、再判清晰度、只标项目特有术语),编排层负责不被汇总吞掉(直连派发、保留复述、缺失即 incomplete)。三者中任何一环松动,这个“新读者”就会退化成又一个顺着作者思路点头的审稿人。把这三层分开配置、分开验证,才是把该适配器用对的前提。
延伸阅读可继续查看 agents/comprehension.md 的人格全文、skills/egm-review/SKILL.md 的五阶段编排、docs/copilot.md 的宿主限制说明,以及 tests/unit/test_copilot_adapter.py 的全部离线契约。