Cursor 适配器解析:EGM codebase_details 审阅器的只读路由与代码一致性审计
Cursor 适配器解析:EGM codebase_details 审阅器的只读路由与代码一致性审计
在 Elephant-Goldfish Model(EGM)中,codebase_details 是唯一一个以“代码现实”为审计对象的 Goldfish 审阅器:它不评价文笔,也不评价架构品味,只追问文档写的实现细节是否真实存在于代码库中。本文以 Cursor 运行时适配文件 .cursor-plugin/agents/codebase_details.md 为主线,讲清一个适配器如何用 18 行指令完成“路由 + 权限约束 + 失败语义”,再层层下探到它背后真正干活的规范人格文件 agents/codebase_details.md,最后回到 egm-review 第 9 阶段(实现就绪测试)中的真实调用链与验证手段。读完后你能独立判断:为什么这个适配器必须写 permissionMode、EGM_ROOT 为什么是任务值、什么情况下它必须返回“不完整审阅”而不是通过结论。
一、两文件分层:适配器只做路由,人格才定义审阅
EGM 的一个核心设计约束是:同一份审阅规则不按宿主复制多份。共享行为留在 skills/、agents/、resources/,每个宿主只提供一层“薄适配器”。docs/designs/additional-harnesses.md 明确要求适配器“必须读取共享人格文本,而不是维护第二份审阅规则副本”。
落到 codebase_details 上,就是两个文件分工:
| 文件 | 定位 | 内容重心 |
|---|---|---|
| .cursor-plugin/agents/codebase_details.md | Cursor 原生子代理注册文件(适配器) | YAML frontmatter 权限与模型字段、EGM_ROOT 路径协议、允许/禁止的操作、失败返回语义 |
| agents/codebase_details.md | 规范化人格(canonical persona) | 角色设定、REVIEW / BRAINSTORM 双模式、六类审计向量、输出格式 |
适配器全文只有 18 行正文,测试还专门断言了这一点:assert len(text.splitlines()) < 25 # Routing only, no copied persona rules.,见 tests/unit/test_cursor.py。而人格文件的 frontmatter 里只保留 name、description、license: Apache-2.0,不含任何宿主权限字段——权限是宿主的职责,不是人格的职责。
适配器的第一句就是硬约束:
Require an absolute EGM_ROOT in the task. Read EGM_ROOT/agents/codebase_details.md
first and follow that canonical persona. EGM_ROOT is a task value, not an
environment variable. Resolve resources/ against that root.
这三句分别对应三件事:调用方必须传绝对根路径;先读人格再干活;resources/ 必须以该根解析,而不是以当前工作目录或某个缓存目录解析。
二、frontmatter 六个字段:为什么 permissionMode 不是可选项
适配器的元数据块如下:
---
name: egm-codebase-details
description: Codebase details reviewer.
model: inherit
readonly: true
permissionMode: readonly
is_background: false
---
逐项说明:
name: egm-codebase-details:注册到宿主后的子代理类型名。它必须与共享人格 agents/codebase_details.md 的name完全一致,测试用assert config["name"] == frontmatter(persona)["name"]强制校验,避免出现“适配器叫 A、人格叫 A 的同名文件”这类漂移。description: Codebase details reviewer.:面向宿主选择器的简短描述,不含宣传词。model: inherit:继承父会话模型,不硬编码模型标识。项目文档提醒,真实运行时应显式选择模型并从任务记录中登记实际标识,而不是依赖默认值推断。readonly: true:面向 Cursor 本地 Agent 接口的文档化只读声明。permissionMode: readonly:面向宿主 CLI 插件加载器的实际生效字段。is_background: false:要求前台执行,父流程需要等待完成后再进入下一阶段。
关于 readonly 与 permissionMode 并存的原因,docs/cursor.md 记录得很直接:所选 CLI 的插件加载器读取 permissionMode,不读 readonly;早期的离线探针发现“仅声明 readonly: true”会注册成默认权限,补上 permissionMode 之后才得到只读注册结果。因此这两个字段不是冗余,而是覆盖两个不同接口层。
测试对字段集合做了封闭断言(多余字段即失败):
assert config["readonly"] is True
assert config["permissionMode"] == "readonly"
assert config["is_background"] is False
assert config["model"] == "inherit"
assert set(config) == {
"name", "description", "model", "readonly", "permissionMode", "is_background",
}
离线探针(tests/unit/test_cursor.py 中的 test_installed_cursor_native_loader)进一步要求:八个审阅器全部以 permissionMode == "readonly"、model == "inherit" 注册,且存在且仅存在一条 alwaysApply: true 的规则。但请注意证据边界——这只是原生解析结果,不等于运行时强制或交互式安装验证。
三、EGM_ROOT 路径协议:任务值、绝对路径、不依赖变量展开
适配器对路径的要求可以归纳成一张“可用与不可用”对照表:
| 规则 | 具体表述 | 反例 |
|---|---|---|
| 根路径来源 | 任务中显式提供绝对 EGM_ROOT |
假设存在环境变量 EGM_ROOT |
| 人格定位 | EGM_ROOT/agents/codebase_details.md |
项目里同名的 agents/codebase_details.md |
| 标准定位 | resources/ 相对该根解析 |
相对当前工作目录解析 |
| 读取范围 | 绝对目标路径 + 每一份被提供的标准 | 只读目标、跳过标准 |
| 上下文来源 | 仅任务内容 + 显式提供的 Goldfish 上下文 | 父会话历史、记忆、无关审阅结论 |
这套设计与同仓库其他宿主适配器形成对照:.claude-plugin/agents/codebase_details.md 用 ${CLAUDE_PLUGIN_ROOT} 变量展开,com.github.copilot/agents/egm-codebase-details.agent.md 用 <EGM_ROOT> 占位符并要求调用方给绝对路径,而 Cursor 版本刻意不依赖 Markdown 内的变量替换。.cursor-plugin/rules/egm.mdc 解释了原因:“This path mapping does not depend on variable substitution in Markdown.” 它还给出了根推导方式:对 EGM_ROOT/skills/<directory>/SKILL.md 向上回溯三层得到 EGM_ROOT,并用 EGM_ROOT/.cursor-plugin/plugin.json、EGM_ROOT/agents/、EGM_ROOT/resources/、EGM_ROOT/docs/cursor.md 四个存在性检查确认包完整性。
这也解释了为什么 .cursor-plugin/plugin.json 要把 agents 和 rules 指向 .cursor-plugin/ 下的专属目录,而不是让宿主去扫描共享的 agents/:
"skills": "./skills/",
"agents": "./.cursor-plugin/agents/",
"rules": "./.cursor-plugin/rules/"
共享的 agents/*.md 没有宿主字段,直接注册会带来权限不确定;显式路径把“原始人格”和“可注册适配器”隔离开。测试同样锁定这一点:assert set(manifest) == {"name","version","description","author","homepage","repository","license","skills","agents","rules","logo"},并检查 {p.stem for p in adapters.glob("*.md")} == set(REVIEWERS)。
四、只读边界:允许读什么,禁止做什么
适配器把权限收敛为四条否定式指令和一条肯定式指令:
- 不编辑文件:
Do not edit files - 不执行命令:
run shell commands - 不访问 MCP:
access MCP services - 不委派:
delegate - 只返回结论:
Return findings to the parent; the parent writes reports.
“父级写报告”不是风格偏好,而是产物归属的硬约定。.cursor-plugin/rules/egm.mdc 对应写明:“Keep drafting, synthesis, remediation, and report writes in the parent.” 所有产物(如 implementation_readiness_report.md)都由父流程写入用户工作目录,绝不写进已安装的插件包。
同时必须认识到隔离的边界:docs/cursor.md 明说原生只读模式“restricts writes; it is not a filesystem boundary”,提示词禁止 shell 与 MCP 也“not proven tool allowlists”。新会话只解决了父对话轮次泄漏,宿主注入的规则、仓库指令文件、记忆、MCP 与共享工作区文件仍需单独评估。这些都属于“未验证”,不能因为一次干净运行就写成通过。
五、失败语义:宁可“不完整”,不要“通过”
适配器最后一句是这套设计里最容易被忽略、也最关键的一句:
If required paths or reads are unavailable, return an incomplete review,
not a passing verdict.
它解决的是一个典型的代理失效模式:当人格文件缺失、目标路径错误或标准读不到时,模型倾向于“基于常识给一份看起来合理的报告”。EGM 把这种情况定义为审阅未发生。同一原则在多处一致复现:
- skills/egm-review-loop/SKILL.md:超时、失败或无报告的审阅器重试一次,仍失败则记为
not run,绝不按“零发现”计。 - agents/synthesizer.md:
not run与“没有发现问题”在报告表格中是两种状态。 - .cursor-plugin/rules/egm.mdc:
If a reviewer cannot start, read required files, or finish, stop the stage. ... Do not simulate a reviewer in the parent. - tests/unit/test_cursor.py:
assert "incomplete review" in text,把这句话变成回归测试契约。
六、规范化人格:一个“吹毛求疵的技术质量审计员”
越过适配器,agents/codebase_details.md 定义了真正的行为。它的 description 写得很克制但很明确:Pedantic Technical Quality Auditor verifying that documentation accurately and exhaustively matches actual codebase implementation and existing library reuse opportunities.
三条 Core Mandates 决定了它的行为边界:
- Strict Read-Only Protocol:没有修改工作区、写文件或编译代码的工具,不尝试修复或重构。
- Stateless Mindset (Goldfish Isolation):零对话历史、零外部假设,像刚加入项目的新成员那样读文档。
- No Chitchat:不做寒暄,不叙述工具调用,只给技术判断。
角色段进一步定性:它像一名严格的质量合规官,“does not accept hand-waving explanations, unstated assumptions, or missing details”。这种“不接受的姿态”是有意的——对抗性审阅需要防止审阅者与作者共谋。
七、REVIEW 模式:四步审计流程
人格先检查调用方传入的 Mode。当 Mode: REVIEW 时,按调用方给定的目标文件与行范围执行:
- Map the Scope:解析当前目标范围,识别它描述了哪些源文件(来源是提供的代码库上下文)。
- Verify Code vs. Doc:对每个映射到源文件,实际阅读代码,核查关键实现细节是否被覆盖——包括 public API、核心算法、配置开关、关键逻辑分支。
- Audit against the Standard:把目标范围的深度与准确度对照
Target Standard的要求,逐项指出不达标之处。 - Filter Test Files:忽略简单的单元测试文件,但对测试基础设施(mock、helper、基类)按生产代码同等标准审阅。
第 4 步的取舍值得展开:普通用例是“实现细节的消费者”,重复描述价值低;而 mock 与 helper 承载了测试语义与稳定性假设,属于必须被记录的基础设施。这条规则防止审阅器把大量篇幅花在逐个复述测试函数上。
八、六类审计向量
Audit Vectors 是这个审阅器最可复用的部分,本质是一份“文档与代码漂移”的分类法:
| 审计向量 | 判定内容 | 典型证据 |
|---|---|---|
| Missing Logic Detail | 代码中存在的函数、校验规则、算法在目标范围里缺失 | 新增的参数校验分支未被提及 |
| Unstated Assumptions | 硬编码常量、环境变量、系统依赖未文档化 | 端口、超时、重试次数写死在代码里 |
| Undocumented Edge Cases | catch 块、空值检查、重试上限、失败模式缺失 |
降级路径没有出现在文档中 |
| Test Infrastructure Neglect | 共享 mock 与测试 helper 的文档深度不足 | helper 的默认行为未说明 |
| Contradicts the Code | 文档描述的行为源码并不具备 | 文档说“幂等”,实现没有去重 |
| Non-Existent References | 被当作现状引用的文件、函数、端点、表实际不存在 | 引用了已删除的模块路径 |
其中 Contradicts the Code 被规定为必须上报为 🔴 Blocker,理由写得很清楚:every later reader inherits the false statement。错误陈述的传播成本远高于遗漏陈述,因此严重级别不按“看起来多严重”定,而按“被继承的后果”定。
Non-Existent References 附带一条必须遵守的证据核查要求:Check every one. 这与项目的反幻觉立场一致,也解释了为什么人格要求先读代码再给结论。
九、“计划中要新建的文件”不是缺陷
这是 codebase_details 里最容易误判、也最值得单独成节的规则:
**Proposed files are not findings.** An implementation plan lists files it will
create. Their absence is not a defect. Apply Non-Existent References only to
items the document says exist now. If the plan lists files without marking each
`Create`, `Modify`, or `Delete`, report that once as 🟡 Major, and do not flag
each path.
它把两类陈述严格区分开:
- 断言现状:文档说“当前由
foo.py处理”,而foo.py不存在 → 属于 Non-Existent References,必须上报。 - 计划变更:文档说“将新增
bar.py” → 文件不存在是正常状态,不得上报。
但若计划只给出一串路径,却不标注每个路径是 Create、Modify 还是 Delete,则只上报一次 🟡 Major,而不是逐路径刷屏。这条“报一次、不逐条”的约束直接对抗一种常见噪声:模型把同一根因拆成十几条 finding,稀释真正的阻塞项。它也与第 9 阶段引用的标准呼应:resources/document_standards/implementation-readiness-standard.md 要求“精确列出的仓库相对路径”,并明确该清单“suitable for enforcing a Phase 5 write allowlist”。
十、BRAINSTORM 模式:同一人格的可观测性镜头
Mode: BRAINSTORM 时,这个审阅器不再是文档校对员,而是 7 个构思镜头之一——Observability & SRE Debuggability Lens。它评估原始功能概念的三件事:
- Telemetry & Tracing:关键操作在分布式追踪中是否可追踪?遥测指标是否可据以行动?
- Operational Debuggability:凌晨三点的 on-call 工程师会怎样定位这个生产事故?
- 回报缺口:向编排器报告可观测性要求与遥测缺口。
这一镜头分工在 docs/designs/brainstorm.md 的 7-Lens 清单与 agents/synthesizer.md 的 Mode: BRAINSTORM 分支中被显式登记,codebase_details 对应的标题正是“Observability & SRE Debuggability Lens”。同一个文件、两种模式,靠一个 Mode 参数切换,避免为构思和审阅维护两套人格。
十一、输出格式:结构化但不设模板枷锁
REVIEW 模式下每条发现必须包含三要素:Severity(Blocker / Major / Nit)、Affected Scope(文件路径、API 或行号)、Discrepancy Description & Rationale(漂移说明与依据,包括通过代码搜索发现的既有库复用机会)。
BRAINSTORM 模式则要求四要素:Severity、Dimension(固定为 Observability & Operational SRE Debuggability)、Operational Risk、Mitigation Requirement(写入 Concepts Brief/PRD 的强制遥测要求)。
两者的共同点值得注意:严重级别是三档封闭枚举,与 agents/synthesizer.md 的归并分组(🔴 Blocker、🟡 Major、🟢 Nit)严格对齐。审阅器不写 Markdown 报告、不做去重、不做优先级排序——这些都属于合成器与父级职责,是职责分离的直接体现。
十二、在第 9 阶段的真实调用链
codebase_details 不单独行动,它是 egm-review 第 9 阶段(Implementation Readiness Test)三审阅器之一。根据 skills/egm-review/SKILL.md:
- 目标范围:
DetailedRange,即## Detailed Implementation Plan/## Implementation Plan/## Work Breakdown/## Implementation Steps之后的正文。 - 审阅器组合:
[egm-implementation-readiness, egm-codebase-details, egm-style]。 - 标准映射:
egm-implementation-readiness与egm-codebase-details都绑定implementation-readiness-standard。 - 产物:
implementation_readiness_report.md,由父级写入。 - 收敛:第 9 阶段同样受“单阶段最多 1 次重审”的上限约束。
驱动层 skills/egm-review-loop/SKILL.md 补充了两个与本文主题直接相关的机制:
- 每轮无条件重解析行号:
TargetFile被前一轮修复改动后,绝对行号会漂移,因此每轮重读文件、用稳定语义串重新定位。这对codebase_details尤为重要——它上报的Affected Scope是行号级的,行号失效会让发现无法定位。 - settled / fixed 区分:已争议或已记为“接受风险”的发现进入 settled 列表,新审阅器在相同范围提出同一问题不重新开启;而已应用修复的发现不算 settled,若同范围同问题再现,说明修复失败或被后续编辑重新引入,必须重开。这条规则防止“修复即结案”的假收敛。
同一人格还被同一份合成器清单用于构思扇出,因此在 tests/unit/test_harnesses.py 中 codebase_details 出现在 REVIEWERS 元组里,被打包脚本 scripts/pack_plugin.py 的 REQUIRED_SHARED 列表强制要求存在——任何遗漏都会让打包直接失败。
十三、安装、调用与验证
安装遵循 docs/cursor.md 的候选包流程。适配器依赖完整的运行时目录,因此必须整包拷贝,而不是只复制 skills/:
git diff --exit-code HEAD
egm_candidate="$HOME/.cursor/plugins/local/egm"
mkdir -p "$(dirname "$egm_candidate")"
mkdir "$egm_candidate" && {
cp -R .cursor-plugin skills agents resources docs LICENSE "$egm_candidate/" &&
git rev-parse HEAD > "$egm_candidate/.egm-source-sha"
}
这段命令的意图需要注意:拷入 .cursor-plugin、skills、agents、resources、docs、LICENSE,但不含根 plugin.json,从而显式选择 Cursor 格式的清单;拷贝保留相对布局,不含指向外部检出的符号链接;任意命令失败即停止并检查半成品。
调用时先给宿主根路径,再选技能:
EGM_ROOT: /absolute/path/to/cursor-package
Read /absolute/path/to/cursor-package/docs/cursor.md.
Run /egm-brainstorm for the requested feature.
随后在 Cursor 的斜杠菜单中选择已安装的技能;若某个技能未暴露,则直接读其绝对 skills/<directory>/SKILL.md 并在父上下文执行,不要自行发明斜杠命名空间。
离线验证命令:
pytest tests/unit/test_cursor.py
该测试套件实际覆盖四类契约:清单字段与目录存在性、每个适配器与人格的 name 一致性及字段封闭集、重定位包(路径含空格与 Unicode,见 fixture 中的 "Cursor candidate café")内所有资源的逐字节一致性、以及宿主规则与指南中的失败契约与产物契约(EGM artifact directory: <path>、Grok Bot remains a separate, unverified surface、No complete Cursor workflow trace parser is supplied)。
可选的本地加载器探针需要预先下载固定版本 bundle,并在 macOS/Linux 上按 SHA-256 校验:
EGM_CURSOR_BUNDLE="$HOME/.local/share/cursor-agent/versions/2026.10.01-e373342/index.js" \
pytest tests/unit/test_cursor.py
探针在进程内禁用网络与子进程,只调用插件加载器,不启动模型会话,也不修改已安装 CLI。因为私有加载器导出是版本相关的,改动版本 pin 前必须重新审计接口。
十四、验证状态与失败模式排查
docs/cursor.md 要求把三类结果分开记录,这是使用这套适配器时最需要建立的认知:
| Gate | 需要的证据 | 当前记录 |
|---|---|---|
| Installation | 交互式发现 + 实际读取已安装的人格、标准、指南 | 未验证;离线原生发现通过 |
| Workflow | 构思、草稿、审阅、产物、真实的人工批准暂停 | 未验证 |
| Isolation | 新子代理记录、必需读取、写入拒绝、每个审阅器完成 | 未验证 |
需要注意的是文档中的一处自我修订痕迹:早期探针记录“发现七个只读审阅器注册”,但同文另一处写明“八个审阅器全部注册为只读”,并注明那条历史记录未标明被试提交与安装包校验和,需对当前候选重跑。仓库里的适配器目录确实有 8 个文件,与 REVIEWERS 一致——因此以重跑结果为准,不要把历史数字当作当前事实。
实际使用中常见的失败模式与对应判据:
| 现象 | 根因 | 正确处理 |
|---|---|---|
| 审阅器能写文件或执行命令 | 只声明了 readonly,加载器未认 |
补齐 permissionMode: readonly,重跑离线发现 |
| 审阅器读了项目里同名文件 | 未按 EGM_ROOT 解析,或未要求绝对路径 |
在任务中传绝对 EGM_ROOT,人格从根下定位 |
| 标准目录找不到 | 只安装了 skills/ |
整包安装 skills agents resources docs |
| 报告结论“无问题”但路径全错 | 缺失读取被当成通过 | 视为 incomplete review,停止该阶段 |
| 父级模拟了审阅器 | 子代理启动失败后用同上下文顶替 | 停止阶段并如实报告,不模拟 |
| 行号对不上 | 前轮修复导致位移 | 每轮重读目标并按语义串重定位 |
十五、延伸阅读路径
- 适配器本体与权限字段:.cursor-plugin/agents/codebase_details.md
- 规范人格与双模式定义:agents/codebase_details.md
- Cursor 运行时规则与根推导:.cursor-plugin/rules/egm.mdc
- 清单与安装/验证指南:.cursor-plugin/plugin.json、docs/cursor.md
- 第 9 阶段编排与收敛规则:skills/egm-review/SKILL.md、skills/egm-review-loop/SKILL.md
- 报告归并与严重级别:agents/synthesizer.md
- 实现清单与文件边界标准:resources/document_standards/implementation-readiness-standard.md
- 离线契约测试:tests/unit/test_cursor.py、tests/unit/test_harnesses.py
- 多宿主设计背景:docs/designs/additional-harnesses.md、docs/designs/review.md