Cursor 适配器解析:EGM codebase_details 审阅器的只读路由与代码一致性审计

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

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 把这种情况定义为审阅未发生。同一原则在多处一致复现:

六、规范化人格:一个“吹毛求疵的技术质量审计员”

越过适配器,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 决定了它的行为边界:

  1. Strict Read-Only Protocol:没有修改工作区、写文件或编译代码的工具,不尝试修复或重构。
  2. Stateless Mindset (Goldfish Isolation):零对话历史、零外部假设,像刚加入项目的新成员那样读文档。
  3. No Chitchat:不做寒暄,不叙述工具调用,只给技术判断。

角色段进一步定性:它像一名严格的质量合规官,“does not accept hand-waving explanations, unstated assumptions, or missing details”。这种“不接受的姿态”是有意的——对抗性审阅需要防止审阅者与作者共谋。

七、REVIEW 模式:四步审计流程

人格先检查调用方传入的 Mode。当 Mode: REVIEW 时,按调用方给定的目标文件与行范围执行:

  1. Map the Scope:解析当前目标范围,识别它描述了哪些源文件(来源是提供的代码库上下文)。
  2. Verify Code vs. Doc:对每个映射到源文件,实际阅读代码,核查关键实现细节是否被覆盖——包括 public API、核心算法、配置开关、关键逻辑分支。
  3. Audit against the Standard:把目标范围的深度与准确度对照 Target Standard 的要求,逐项指出不达标之处。
  4. 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。它评估原始功能概念的三件事:

  1. Telemetry & Tracing:关键操作在分布式追踪中是否可追踪?遥测指标是否可据以行动?
  2. Operational Debuggability:凌晨三点的 on-call 工程师会怎样定位这个生产事故?
  3. 回报缺口:向编排器报告可观测性要求与遥测缺口。

这一镜头分工在 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 补充了两个与本文主题直接相关的机制:

  1. 每轮无条件重解析行号:TargetFile 被前一轮修复改动后,绝对行号会漂移,因此每轮重读文件、用稳定语义串重新定位。这对 codebase_details 尤为重要——它上报的 Affected Scope 是行号级的,行号失效会让发现无法定位。
  2. 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,停止该阶段
父级模拟了审阅器 子代理启动失败后用同上下文顶替 停止阶段并如实报告,不模拟
行号对不上 前轮修复导致位移 每轮重读目标并按语义串重定位

十五、延伸阅读路径

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