codegraph explore 噪音专题（CG-24 Epic）：从一次 60.7% 噪音响应到索引漂移与信封分配的测量驱动修复

本文基于 codegraph 仓库的 epic 报告 explore-noise-epic-cg24.md 展开：还原一次「agent 点名的符号无法渲染、12k 行生成的 .d.ts 文件占据 60.7% 输出信封」的真实故障，追踪其根因——增量同步索引与干净重建之间 4.3% 的边漂移（CG-33）——并逐一拆解由此 epic 交付的七个修复（CG-25/26/28/30/31/33/36）、遗留缺陷 CG-38 的后续闭环，以及五个被测量推翻而关闭的 issue。读完本文，你能掌握 codegraph codegraph_explore 响应的信封（envelope）预算分配机制、位移守卫与预留不变量、生成文件与声明文件的降噪策略，以及一套「先测量、再下结论」的确定性探针与回归验证工具体系。

一、报告现场：一次不可用的 explore 响应

2026-08-05 起，一个真实会话中的文字流式查询（prose flow query）返回了不可用的 codegraph_explore 响应：agent 点名的符号始终没有渲染出来，而一个 12k 行、由工具生成的 Cloudflare ambient-types 文件吃掉了 60.7% 的输出信封。诊断表的原始记录如下：

#  deliv%   bytes  reserved  score  pen  flags                file
1    1.0%     251    10,970   87.0  1.00 named entry central  <被点名的文件>
2   60.7%  15,043     6,484   49.0  1.00 entry central        worker-configuration.d.ts
4      —        —         —   19.9  1.00 dropped: budget      <第三个文件>

被点名的文件拿到 87.0 的分数和 10,970 字节的预留，最终却只交付 251 字符（1.0%）；而分数只有 49.0 的 worker-configuration.d.ts 反而占走了 15,043 字节。这一症状最终被证明不是 explore 的 bug，而是索引退化——epic 期间确实发现并修复了若干真实的 explore 缺陷，但没有一个导致了这次上报。

二、根因：索引漂移（CG-33）

完整的测量记录见 index-drift-cg33.md。在 codegraph 自身仓库上，一个长期增量同步维护的索引与同一工作树的干净全量重建相比，4.3% 的去重边（distinct (source, target, kind) 三元组）不一致，双向都存在，且绝大多数是 calls 边：重建版有而在线索引缺失 751 条，在线索引有而重建版没有（stale）476 条，合计 1,227 条。缺失边的种类分布为 calls=635、contains=38、references=34、instantiates=21、imports=13、extends=10。

为什么漂移会放大噪音

Explore 的文件排序基于 RWR（随机游走重启）图质量（graph mass），而图质量是相对的、归一化的：别处缺失的 call 边会抬高一个未受影响文件的质量份额。观测到的直接后果是——那个生成的 worker-configuration.d.ts 在漂移索引上的 graph mass 为 0.24750，干净重建后只有 0.13119（约 1.9×），对应分数 49.0 对 27.0。allocateExploreBudget 正是按这个质量分配信封的，于是漂移把本应低排的文件静默提升，挤掉了 agent 真正点名的文件。在一份干净重建的索引上，无需任何 explore 代码改动，同一个查询就能正确作答。

两个机制，都必须修

ReferenceResolver 把一条引用绑定到全项目范围内同名定义之一。漂移需要两个缺陷同时存在：

1. 范围（scope）。增量同步只重新解析位于变更文件内的引用。增删一个 pct 的定义会改变仓库里所有 pct(...) 引用的正确答案，包括同步根本不会碰的文件中的引用——而那些引用当初解析成功过一次，unresolved_refs 行已被删除，没有任何东西提示引擎回来重审。索引因此保留了对旧图正确的答案。
2. 平局裁决（tie-break）。当候选无法区分时，findBestMatch 保留第一个，而 getNodesByName 的 SQL 没有 ORDER BY——胜出者由 rowid 决定，即文件恰好被写入的顺序。全量索引按扫描序写入，同步则按文件变更逐条追加；同一棵代码树因此会因索引构建方式不同而解析出不同边，任何重解析都无法收敛。

修复落在三处（详见 CG-33 报告）：

• getNodesByName 改为按 (file_path, start_line) 排序——这是代码本身的属性，与写入顺序无关。当前实现见 src/db/queries.ts：

  SELECT * FROM nodes WHERE name = ? ORDER BY file_path, start_line
  

• sync 返回一个 definitionDelta：本次同步改变了定义集合的那些名字，用 file\0name 配对在存储阶段前后采样求对称差得到，且按文件比较而非整批求名字集合——一个提交给新文件加入 collect、而无关的变更文件恰好也定义 collect 时，批级名字集合会互相抵消，这一类正是该修复首次测量中最大的残余。

• 对每个 delta 名字，resurrectStaleResolutionEdges 删除指向该名字符号、且来源位于未变更文件的解析边，再按创建它的引用（metadata.refName 印章）重新插入为引用行，交给既有的孤儿清扫按同步后的图重新解析——与重建的输入一致。急停开关：CODEGRAPH_NO_REBIND=1。

该设计刻意保守：误删是一条边的永久丢失，漏绑只是残余漂移。因此没有 refName 印章的边（合成的、或旧引擎构建的）绝不动手；同步已重新抽取的文件其边被跳过；每名字 500 条边的上限拒绝处理过于通用的名字。

回归证据（逐条重放真实提交后与干净重建对比）：

replay	基线（main）	仅加 ORDER BY	加 rebind 通道（已上线）
16 commits	48（24 缺失 / 24 stale）	20	0 — 收敛
80 commits	1,634（963 / 671）	890	361（359 / 2）

主动误导方向的 stale 边在 80 个提交里从 671 降到 2（降幅 99.7%）。代价方面：索引与同步墙钟时间不变；ORDER BY 使紧循环中每次未缓存名字查找慢 18%（237ms → 280ms / 10,127 次），但 ReferenceResolver 按名字做记忆化，墙钟不可见。剩余 361 条边中 357 条是同一个既有类别：push（260）、join（97）这类失败于索引期、因超过 500 条失败引用上限而被搁置的超通用名字——让同步去「制造」数千条跨语言垃圾边才是错的，因此有意保留。单元级回归由 sync-rebuild-convergence.test.ts 固化。

三、epic 交付总览

CG-24 epic 共交付四个 explore 修复、一个索引修复、一个后续缺陷的闭环，外加五个因测量与结论矛盾而关闭的 issue：

任务	内容
CG-30	约束超大 cluster 成员的越界幅度：超过 1.5× 预留后按整行开窗（windowing），而不是整块输出——或者当它比响应上限还大时，让文件被静默整体丢弃。
CG-31	给 cluster 渲染路径补上整文件 BUY 分支一直拥有的 owedBelow 位移守卫，只保留响应实际付得起的「下方欠账前缀」。
CG-26	补齐剩余三个洞：整文件分支完全没有位移守卫、区块开销按固定 200 计费而实际 300–500、owedPayableBelow 全有或全无。
CG-25	识别 Generated by <tool> by running <command> 横幅；要求两个 by 子句以保证精度，普通散文不会误匹配。
CG-28	对索引中无人依赖的纯声明文件施加降权；与生成文件惩罚不叠加（Math.min）；点名了某个声明符号则豁免其所在文件。
CG-33 / CG-35	增量同步与全量重建收敛，外加一个「禁用修复即失败」的回归套件。
CG-36	同一文件内排在前面的 cluster 不再独占预算：靠后的 cluster 被压缩进剩余空间，而不是整体丢弃——选择时一次、上限裁剪时再一次。套件全部 8 个饥饿（starvation）标志清零，源码净增 +1,012 字符。

六仓库确定性套件上的结果：没有仓库被截断，没有仓库丢失文件，okhttp 多交付一个文件，所有仓库落在 25,000 字符硬上限之内或恰好贴线。

下面按修复链条拆解每一项的关键数字。

四、信封分配链上的修复：CG-30 → CG-31 → CG-26

这三份 A/B 记录应顺序阅读：explore-oversize-member-ab-cg30.md → explore-displacement-guard-ab-cg31.md → explore-reservation-invariant-ab-cg26.md。

CG-30：约束超大 cluster 成员

rank #1 的文件可以花掉远超其预算的字节，把下方文件的继承份额吃光。在 django 上，基线版让 django/db/models/query.py 在 3,669 的预算上交付 7,784 字符（2.12×），下方 django/contrib/admin/filters.py 只继承到 2,271 的可花份额；加上 1.5× 开窗上限后，前者收敛到 5,464（1.49×），后者拿到 8,057，响应在同样五个文件上多出 2,104 字符真实源码。fixture __tests__/fixtures/oversize-member-ts 展示了缺陷的另一面：一个成员比整个响应上限还大时，文件直接消失（基线版 quarterly.ts 被 budget-clusters 丢弃），修复后交付 4,004 字符。由 explore-oversize-member.test.ts（9 个用例，4 个在 main 上失败）固化。

CG-31：cluster 路径的位移守卫

CG-30 之后，cluster 渲染路径仍会在硬性上限之前读取「还剩下什么」，而不是「还欠下方文件什么」——整文件 BUY 分支一直拒绝这种交换（owedBelow），cluster 路径却可以。修复后的确定性测量：django 20,033 → 20,791、excalidraw 18,776 → 20,204、okhttp 15,628 → 19,034（+3,406）、tokio 20,340 → 21,521；gin 与 alamofire 逐字节一致（对照仓应有的表现）。四个截断仓库各多交付一个文件。由 explore-displacement-guard.test.ts（11 个用例，3 个在基线上失败）固化。

值得记录的是测量迫使的两处纠偏：第一版守卫「把下方全部欠账都押后」押过头了——在饱和响应里尾段反正会被上限丢弃，为将被丢弃的文件保留的字节是无人收到的字节（实测 django −2,319、tokio −1,298），于是 owedPayableBelow 改为只押后按 rank 顺序「响应还付得起的前缀」；另一处是最终截断切在最后一个文件区块头部、把整段区块连同尾注一起丢掉，改为先丢尾注（epilogue）。

CG-26：端到端预留不变量

不变量是：每个被接纳（admitted）的文件在动用任何结转（carry-forward）余量之前，至少拿到自己的预留额。CG-26 补上三个洞：

1. 整文件分支没有位移守卫。BUY 分支的 fit 测试读 totalChars + fileContent.length + FILE_OVERHEAD <= renderCeiling，而上限属于所有尚未到达的文件；实测 okhttp 的 CallServerInterceptor.kt 以 8,499 字符顶着 5,964 的融资上限交付，rank-6 文件颗粒无收。两个分支现在都对真实渲染结果与 fundedHeadroom 做 fit 测试，整体放不下的渲染降级到 cluster 化而不是跳过文件。
2. 区块开销按固定 200 计费，而真实头部（路径 + 最多 maxSymbolsInFileHeader 个符号名）为 300–500。这个少计不是舍入误差，而是「用不存在的字节许下承诺」：okhttp 在 24,400 的上限上分出了 26,601 字符，最终截断扔掉了整个已渲染区块。现在区块按真实成本计费。
3. owedPayableBelow 全有或全无。最后一个文件的整额预留放不下时就一点不留；修复后在余量仍值一个区块（MIN_CHARS）时保留剩余部分。

同时，epilogue 不再被整体丢弃：它被拆成「由真实字符串定长的地板（floor）」+「按优先级逐条装入剩余空间的弹性尾部」，renderCeiling 变为 hardCeiling − floor。最终结果：六仓库无一截断、无一丢文件，okhttp 多一个文件；两个「负增长」（okhttp −164、excalidraw −552）恰是反向修正——基线版是超额填充后被截断夺走 epilogue，现在账目精确，字节让位给点名未覆盖文件的指针列表。由 explore-reservation-invariant.test.ts（14 个用例，3 个在 CG-31 版上失败）固化，并用 probe-suite-envelope.mjs 复现。

五、从源头降噪：CG-25 与 CG-28

CG-25：识别生成横幅

触发整个 epic 的 worker-configuration.d.ts 是 Wrangler 生成的环境类型文件。修复是让 generated-detection.ts 识别 Generated by <tool> by running <command> 形态的横幅（如 Wrangler 的 Generated by Wrangler by running `wrangler types` (hash: …)）。精度靠要求两个 by 子句保住，普通散文不会误匹配。CG-28 的 A/B 量化了这个惩罚的分量：同一个 fixture、同一批查询、唯一变量是 --variant strip-banner 删掉横幅注释——worker-configuration.d.ts 在 flow-queue 查询上从「rank #1、46.1% 信封、整文件 7,390 字符」变成「被点名进 not-shown 指针列表、0 字符」。结论：这个文件靠生成惩罚一个机制就够了，不需要新规则。

CG-28：声明专用文件的条件降权

CG-25 只覆盖「带横幅」的生成文件。测量（explore-declaration-only-cg28.md，fixture 为 tests/fixtures/ambient-decls-ts）发现一个无横幅、纯手写的环境声明文件照样能拿到 pen 1.00，在 flow-upload 查询上排 rank #1、吃掉 50.7% 交付源码，并把问题真正关心的入口文件 src/routes/upload.ts 挤出响应。

修复是一个条件降权：AMBIENT_DECLARATION_RANK_PENALTY = 0.5（见 src/mcp/tools.ts），同时乘在 score 与 graph mass 上，仅对 QueryBuilder.getAmbientDeclarationPathsAmong 标记的文件生效。四个条件全部要求：

1. 声明 ≥1 个符号；
2. 所有声明符号都是类型层的（interface、type_alias、enum、enum_member、namespace）；
3. 不产生任何 calls/instantiates 边；
4. 文件外没有任何东西指向它。

条件 2 和 4 都是被测量逼出来的，不是口味问题：

• 若只要求「无可调用且不发起调用」，语料库扫描会命中 1.1%–18.0% 的文件，包括 okhttp 的 SocketPolicy.kt、Alamofire 的伞文件 Alamofire.swift、django 全部 500+ 个 conf/locale/*/formats.py 常量表——都是真实源码。要求全部符号类型层后，命中率降到 0%–4%。
• 没有条件 4，规则会同时标记 displacement-ts fixture 里的 src/pipeline/types.ts——纯接口、无实现、结构上与 ambient shim 相同，但它带着 13 条入站 import 和 21 条引用，是 pipeline 查询答案的一部分；降权它会直接破坏 CG-31 的位移守卫测试。ambient shim 的特征是零入站边：按名字可达，但不挂在任何东西上。这个区别图里本来就有。

两个安全阀：查询点名了某个已声明类型时，其所在文件豁免、按全权重参与排序（只认 shape-precise token，避免「the file body」这类散文词误豁免一个 Body 接口——namedSeedIds 天然只含可调用，所以需要单独一个集合）；生成惩罚与声明惩罚用 Math.min 合并而非相乘，避免一个文件因同一属性被双重计费（0.3 × 0.5 = 0.15 会把真相关的文件直接削出答案）。

回归面：六仓库套件在新构建与干净基线构建间逐字节一致；语料库命中率 django/okhttp/gin/alamofire 0.00%、tokio 0.12%、vscode 0.53%、excalidraw 0.74%，命中的是 global.d.ts、vite-env.d.ts、css.d.ts、未引用的 vendored 头文件与测试 fixture——正是目标形态。另有一条边界说明：.pyi 不在 codegraph 的索引扩展名之列，Python stub 根本不会进入图，因此 issue 前提中关于 Python stub 的那一三分量当前不会发生。

六、遗留缺陷的后续：CG-38 —— 大文件尾部的点名符号从不渲染

epic 收尾时留了一个开放缺陷，其完整记录见 explore-tail-render-cg38.md。

症状：在一个 1,414 行的 Svelte store 上，queueMessage（L1087）与 flushQueuedMessages（L1102）在任何查询形态下都不出现在响应里——哪怕它们的文件以 score 127 拿下 rank #1、占 67.3% 信封。返回的却是 L70 处同词干的 QueuedMessage 接口（查询 token 的模糊近匹配）。受控二分（固定索引、遍历 epic 每个合并点换引擎）证明这不是 epic 引入的回归：pre-epic 引擎在这里渲染 12 行，CG-36 版渲染 463 行，两个符号在所有版本里都缺席。此前「epic 造成了回归」的说法是错的——它比较的是两个不同索引上的运行。

两个独立成因，都是陈年旧账：

1. buildFlowFromNamedSymbols 在点名符号不构成调用链时，把点名符号的 IDENTITY（节点 id 集合）连同叙事一起丢弃了。而正是这个集合负责把点名定义注入其文件 cluster 并排上 importance 9——「保证点名符号渲染」的全部机制。两个互为兄弟闭包的函数互不调用，恰好触发这条空路径。修复是把两个输出分离：现在空叙事走 identityOnly() 返回（见 src/mcp/tools.ts 的 return identityOnly()），且只对 shape-precise token（camelCase / PascalCase / snake_case / 限定名，与 gather 路径同一判定）生效——有叙事时散文本身就是佐证，无佐证时只有无歧义的符号引用能升级，英文单词碰巧精确匹配某个可调用对象拿不到 importance 9。
2. 上限裁剪按源码顺序切。shrinkCluster 其实保住了这两个符号（输出块跨 1022–1121），但裁剪产物 26,297 字符超过 16,532 的 cap，windowToCeiling 按源码顺序填充、越过第一个超限时丢弃其后所有东西——大文件的尾部因此永远最先被砍，而点名符号恰恰最可能在尾部。修复是让 windowToCeiling 接收 focusLines 列表（spine 下一跳调用点 + 所有 importance ≥ 9 的成员，上限 6 条，见 src/mcp/tools.ts）：先尝试全上限填充，只有 focus 行确实未被覆盖时才押后 40%；保留额在多个未覆盖 focus 行间均分并结转，而不是按源码顺序贪心发放——贪心会在低一层复现同样的 bug。

为什么它躲过了整个 epic：epic 的探针只测量信封份额、饥饿、源码总量与文件数，没有任何探针回答「agent 点名的符号是否渲染了」。补上这一环的是 probe-named-symbol.mjs——按符号、二值判定：该符号的定义行是否在响应渲染的行集合里（名字本身证明不了什么，它出现在区块头符号列表和调用点里，无论函数体是否发出）。fixture tests/fixtures/tail-render-ts 复现了报告的几何形态（L70 的同词干诱饵接口、跨约 92% 文件、把所有符号并入单 cluster 的 L104 工厂闭包、L1088/L1096/L1102 的目标符号，外加一个 2,500 行的生成 .d.ts 供 ranker 惩罚），由 explore-named-symbol-render.test.ts 作为常设门禁（7 个符号检查 × 3 种查询形态，main 上 7/7 失败、修复后 7/7 通过）。

七、被测量关闭的五个 issue

epic 的另一半故事是：五个 issue 因测量与结论矛盾而被关闭——五个都是「有人（人或 agent）读了代码、提出了可信机制」然后被证伪的：

任务	为什么关闭
CG-32	点名的文件「没有渲染在第一位」。漂移假象；干净索引上它渲染在第一位并占 89%。
CG-34	「分配器为低分文件过度预留」。基于 runner 的诊断提单、没核对数字。该文件从未过度预留（两臂都是 4,314）——它是过度花费，即 CG-31。
CG-27	给 ENVELOPE_KINDS 加 function/method 测出来是大幅回归：rank #1 从 7,539 交付字符跌到 397，11 个内部闭包 7 个变 0 个。包裹范围本来就把文件聚成一个 cluster，shrinkCluster 已在内部做逐符号排序。谨慎版是噪音（9 个查询 69 对 68）。
CG-29	散文查询与符号查询的差距。测量后方向反转：prose 在 django 上与 symbol 持平、在 okhttp 上多交付 63% 源码。最初的观察本身是漂移。
CG-37	与 CG-36 重复，提单时没看到后者。

八、方法论教训：便宜的测量比自信的診断更值钱

epic 报告把「真正学到的东西」浓缩为一条：一个自信的診断价值不如一个便宜的测量。上述每个 issue 的提出者都读过代码、都给出了可信机制，五个是错的；活下来的那些，是因为确定性探针与它们不一致，而探针胜出。

两个花了真实时间的具体陷阱（现已在工具中设防）：

• .codegraph/graph.db 不存在——索引文件是 .codegraph/codegraph.db。对拼错的路径运行 sqlite3 会创建一个空数据库而不是报错，空 schema 读起来恰好像一个陈旧的迁移前索引。这一陷阱当时直接产生了一个错误根因。diff-index-drift.mjs 因此在打开数据库前检查 existsSync。
• ab-new-vs-baseline.sh 会在运行中途把引擎检出到基线 ref。在它运行期间产生的提交会捕获基线源码、并悄悄回滚正在被测的修复。这在 CG-30 期间真实发生过。相信任何 A/B 结果之前，先检查 changed: 行。

以及一条值得保留的测量纪律：比较集合，而不是总数。引发这一切的漂移在原始边行数上只有 +0.7%（39,845 对 40,122），因为它双向存在、净额抵消；在去重边三元组上则是 4.3%。任何漂移探测器都必须比较边集合。

九、复现与回归验证

整套结论都可以用仓库内的只读工具复现：

# CG-33 漂移测量（先快照，再重建，再 diff；exit 0 = 收敛，1 = 漂移）
cp .codegraph/codegraph.db /tmp/live.db          # 快照必须在重建之前
node dist/bin/codegraph.js index .               # 全量重建
node scripts/agent-eval/diff-index-drift.mjs /tmp/live.db .codegraph/codegraph.db

要复现回归（而非测量在线索引），按 CG-33 报告的方法逐提交重放 sync 再与最终树的干净重建对比；单元级版本即 sync-rebuild-convergence.test.ts。

其余常设探针与门禁：

工具 / 测试	验证对象
probe-file-spend.mjs	每文件预留 vs 交付的「成对」饥饿扫描（高分文件未花完 + 低分文件超支才报警），有旗标即 exit 1
probe-suite-envelope.mjs	六仓库确定性信封扫描（25,000 硬上限约束）
probe-named-symbol.mjs	点名符号的定义行是否在渲染行内（CG-38 的缺口）
probe-decl-only.mjs	CG-28 声明降权（支持 --variant strip-banner 量化 CG-25 价值）
tests/explore-cluster-starvation.test.ts + starved-cluster-ts / dense-header-ts	CG-36 文件内 cluster 饥饿与「密度不得压过重要性」的反向配重
tests/explore-declaration-only.test.ts + ambient-decls-ts	CG-28 四条件降权与点名豁免
tests/explore-named-symbol-render.test.ts + tail-render-ts	CG-38 尾部点名符号渲染

十、小结

CG-24 epic 的完整因果链可以压缩成三句话：上报的 explore 症状源于索引漂移（增量同步的解析范围 + 无排序的平局裁决），重建即愈；epic 期间按测量发现并修复的 explore 缺陷（信封越界、位移守卫、预留不变量、生成/声明文件降噪、cluster 内饥饿）各自有确定性探针与失败于基线的回归测试背书；而被证伪的五个 issue 则示范了「先跑便宜探针、再相信机制」的调试纪律。对维护者的直接启示是：探索类检索系统的排序建立在归一化的相对信号上，任何底层边集的不收敛都会被排序放大成用户可见的噪音——因此「索引是否收敛」本身成了必须被持续测量的性质，而 sync-rebuild-convergence.test.ts 与 diff-index-drift.mjs 就是这道常设的防线。