Understand-Anything 基准测试中的结果语义设计：如何区分「分析不支持」与「执行失败」

Understand-Anything 基准测试中的结果语义设计如何区分「分析不支持」与「执行失败」【免费下载链接】Understand-AnythingGraphs that teach graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.项目地址: https://gitcode.com/GitHub_Trending/un/Understand-Anything本篇围绕 Understand-Anything 仓库中大型仓库基准测试large-repo benchmark的一项设计文档展开当某个文件没有任何已注册的分析器、或某个解析器缺少可选的调用图call-graph能力时基准报告应当把它记为「跳过」skipped而不是「失败」failed。读完后你将理解该仓库如何在不改动报告 schema 1.0.0 的前提下把「能力缺失」从完整性故障中剥离出来使报告状态从failed回归degraded退出码 0并能沿着PluginRegistry→analyzeFileWithOutcomes→ 完整性汇总这条调用链核对源码级实现与测试证据。问题背景一次「假失败」的复现设计文档 benchmark-unsupported-outcomes-design.md 描述的起点是一个具体的故障现象对 Understand-Anything 仓库自身做全量基准复现时报告被判定为failed尽管所有被报告的「分析失败」本质上都是——文件类型没有任何注册的分析器unsupported file或已选中的解析器不具备可选的调用图能力unavailable optional call-graph capability。根因在于一次「契约返回值」被误标PluginRegistry的getPluginForFile(path)在契约上就允许返回null表示该路径没有注册插件但旧的结果映射器把这个契约性的null折叠成了运行时失败。而基准的完整性检查integrity check本身工作正常——它忠实地把被错误标记的failed计入了结构失败数进而把整份报告拖入failed状态。设计文档对此的表述很直白这是 mapper 的错而不是 integrity 检查的错。文档给出了复现运行的定量证据指标数值说明扫描文件数457全仓库运行扫描行数126,169全仓库运行结构「失败」数20全部 20 个均因没有注册分析器调用图「失败」数18全部 18 个均因没有调用图能力已注册解析器真实失败0没有任何一个注册过的解析器真的报错「零真实失败」这个结论是整个语义重设计的依据既然失败全部源于能力缺失那么正确的表达应当是「跳过」而不是「失败」。三个候选方案与取舍设计文档评估了三种方案这种「列出备选 说明否决理由」的结构值得在设计文档写作中借鉴。方案一复用现有 skipped 路径但加入能力感知选定核心思路在分析之前先查询注册表支持情况capability-aware。文件若没有注册分析器走已存在且已测试的filesSkipped字段记账报告因此是degraded、退出码 0代码/脚本类解析器如果只有结构能力、没有可选的调用图 API则记录一次「跳过的调用图」一旦解析器被选中后抛出异常、返回非法最终值或产生损坏输出则仍然判定为 failed——即能力一经宣告失败就是真失败。该方案的收益在设计文档中明确列出保持报告 schema 1.0.0 不变、保持仓库规模总量scanner totals完整、复用已有测试覆盖的 degraded 报告路径。方案二在 schema 新版本中加入显式 unsupported 计数器否决设想是新增structureUnsupported与能力级计数器。表达力更强但代价是把一个本应局部的补丁扩大成 schema 版本化 迁移工作——而既有的 skipped 字段已经足以建模所需行为。从文档的取舍逻辑看这是一个典型的「现有数据模型够用就不加版本」的保守决策。方案三扫描阶段排除不支持的扩展名否决设想是让 scanner 直接忽略所有不支持的扩展名。文档列出三条否决理由隐藏了有用的仓库规模信息scanner totals 会变小需要维护一份脆弱的重复 allowlist与语言注册表形成双份事实来源;根本解决不了「已支持解析器上的可选能力探测」问题——调用图能力的缺失与扩展名无关。选定行为Selected behavior逐条解读设计文档用六条行为规范锁定语义这里逐条结合仓库实现解读1. 扫描总量继续包含所有发现的文件。扫描器对文件的支持判定与结构分析的支持判定解耦.xyz这类无分析器的文件照常进入文件数与行数统计保证基准的「规模证据」属性不被能力缺口侵蚀。2.getPluginForFile(path)返回null时该路径计入filesSkipped不产出结构结果。这一条的契约源头在 registry.tsgetPluginForFile(filePath: string): AnalyzerPlugin | null { const langConfig this.languageRegistry.getForFile(filePath); if (!langConfig) return null; return this.getPluginForLanguage(langConfig.id); }即两层都可能返回null语言注册表不认识该扩展名或语言认识但没有插件注册到它。设计文档要求的就是这个契约性的null必须在基准语义中被显式消费而不是被下游当异常处理。3. 结构能力与调用图能力分别记账。若选中的解析器支持结构但不支持调用图提取结构结果记succeeded调用图记skipped。这条对应的实现细节见下节的analyzeFileWithOutcomes。4. 能力一经宣告失败即真失败。「Once a parser advertises a capability, an exception, missing final value, or malformed output is a real failure.」这是防作弊条款不能因为引入了 skipped 语义就顺手把解析器抛异常、返回undefined、返回结构体缺字段这类真故障也吞成 skipped。5. 只含「不支持跳过」的运行是degraded而非failed退出码 0。这一条最终落到了基准运行器的状态判定逻辑中large-repo-benchmark.mjs 中的顺序是if (hasFailedIntegrity(report.integrity)) { report.status failed; report.error One or more deterministic integrity checks failed; exitCode 1; } else if ( report.warnings.length 0 || report.integrity.filesSkipped 0 ) { report.status degraded; exitCode 0; } else { report.status ok; exitCode 0; }注意filesSkipped 0只触发degraded分支而hasFailedIntegritylarge-repo-benchmark.mjs判定的故障项里只有structureFailures 0、callGraphFailures 0、批次缺失/重复/畸形等硬故障——filesSkipped根本不在失败判定列表中。这正是「跳过不触发完整性失败」在汇总层的落点。6. Markdown 与 JSON 报告保持相同的 schema 版本与成对完整性规则。即不引入新字段报告 schema 1.0.0large-repo-report-1.0.0.schema.json原样保留pairId、digest、锁定的成对写入机制deliverBenchmarkReports均不受影响。源码级实现三个文件如何落地这套语义1. 能力感知的结果映射analyzeFileWithOutcomes纯映射逻辑独立在 extract-structure-result.mjs 中注释写明它是从 CLI 入口拆出来的便于单测不 import shebang 脚本。关键路径在 L132-L151export function analyzeFileWithOutcomes(registry, file, content) { const wantsCallGraph file.fileCategory code || file.fileCategory script; const selectedPlugin typeof registry.getPluginForFile function ? registry.getPluginForFile(file.path) : registry; if (selectedPlugin null) { return { analysis: null, callGraph: null, structureOutcome: skipped, callGraphOutcome: skipped, }; } const supportsFullAnalysis typeof selectedPlugin?.analyzeFileFull function; const supportsSeparateCallGraph typeof selectedPlugin?.extractCallGraph function; // ...三个要点与设计文档一一对应先查注册表getPluginForFile返回null时两个 outcome 都是skipped对应行为条款 2调用图是「想要才要」wantsCallGraph只对code/script类别为真docs/config 类文件即使解析器宣告了analyzeFileFull也不会走 full 路径测试用例「uses separate structure analysis for non-code files even when full analysis is advertised」专门验证fullCalls 0能力探测决定调用图命运supportsSeparateCallGraph为假时调用图 outcome 初始化为skipped而非failed对应行为条款 3。而「真失败」防线同样落在这一函数内analyzeFileFull抛异常、返回null/undefined、structure不通过isValidStructuralAnalysis必需字段functions/classes/imports/exports缺失或条目畸形、callGraph不通过isValidCallGraph均分别映射为structureOutcome: failed或callGraphOutcome: failed且两者独立判定full 结果里结构非法但调用图合法时会出现structureOutcome: failedcallGraphOutcome: succeeded的混合结果。2. CLI 入口把 skipped 归入filesSkippedextract-structure.mjs 的主循环L110-L119const { analysis, callGraph, structureOutcome, callGraphOutcome } analyzeFileWithOutcomes(registry, file, content); if (structureOutcome skipped) { filesSkipped.push(file.path); continue; } analysisOutcomes.structure[structureOutcome] 1; analysisOutcomes.callGraph[callGraphOutcome] 1;注意被跳过的路径不产生 result、不计入任何 outcome 计数所以输出中filesAnalyzed results.length的不变量基准侧summarizeStructureOutput会校验这一点天然成立而filesSkipped里的每个路径仍会被基准的pathCounts统计保证「每个被扫描文件在结构阶段都有交代」的完整性检查missing/duplicate/unexpected structure paths不因跳过而误报。输出契约脚本头部注释与 L127-L133 一致{ scriptCompleted: true, filesAnalyzed: 0, filesSkipped: [], analysisOutcomes: { structure: { succeeded: 0, failed: 0 }, callGraph: { succeeded: 0, failed: 0, skipped: 0 } }, results: [] }3. 基准侧的汇总与状态判定基准运行器 large-repo-benchmark.mjs 中summarizeStructureOutputL1257 起把每个批次的输出折算成filesAnalyzed / filesSkipped / structureSucceeded / structureFailed / callGraphSucceeded / callGraphFailed / callGraphSkipped其中complete的判定条件是「无畸形 且structureFailed 0且callGraphFailed 0且路径账目全平」——callGraphSkipped不参与 complete 判定这与设计文档「missing optional call-graph capability is also skipped」完全一致。随后buildBenchmarkIntegrityL1423 起把各批次汇总为integrity块structureCoverage只按「成功 /成功失败」计算skipped 不计入分母。验证标准red/green 测试与全量基准的验收口径设计文档的 Verification 一节给出了可执行的验收标准仓库中的测试文件 test_extract_structure_outcomes.test.mjs 已按此落地RED→GREEN 用例 1注册表getPluginForFile()返回null期望两个 outcome 均为skippedL333-L352RED→GREEN 用例 2选中的解析器只有analyzeFile无analyzeFileFull也无extractCallGraph期望结构succeeded、调用图skippedL354-L382既有异常测试继续有效「records advertised full-analysis exceptions as failures」等用例证明抛异常、返回undefined、畸形条目测试覆盖 30 种畸形结构条目与 6 种畸形调用图条目仍映射为failed——即行为条款 4 的回归防线。除此之外配套测试还包括 test_large_repo_report_schema.test.mjs 与 test_large_repo_benchmark.test.mjs后者覆盖 normal、empty、degraded、partial-failed 四类报告对 schema 1.0.0 的符合性。全量基准的最终验收目标来自设计文档对干净的 Understand Anything worktree运行产出的成对报告须满足——结构失败 0调用图失败 0失败批次 0状态非failed预期为degraded因为filesSkipped 0。发布流程与修复后的真实报告设计文档的 Publication 一节约定修复提交并推送后把生成的 Markdown 与 JSON 报告贴到 PR #587且评论必须说明「TensorFlow 未在本地运行因为其仓库规模与资源需求超出本次本地验证的实际范围」。仓库内已存在该次发布的实证样本 understand-anything-pr587-full-sample.md配套 JSON 见 understand-anything-pr587-full-sample.json修复后报告的头部指标是MetricValueStatusdegradedFiles / Lines459 / 127,155Structure coverage1Files skipped20Failed batches0Schema version1.0.0与修复前复现运行457 文件 / 126,169 行相比文件数与行数略有差异属正常——两次运行对应的 worktree 提交点不同关键在于状态从「被 38 个能力缺失型失败拖入failed」变为「20 个文件记入filesSkipped、状态degraded、退出码 0」。这正对应 large-monorepo.md 中对外文档的同步更新「没有注册结构解析器的文件会计入filesSkipped并产生 degraded 报告缺少可选调用图能力同样记为跳过解析器宣告能力之后的异常或非法结果仍是完整性失败」。关键语义速查结合 large-monorepo.md 的退出码表与本次设计完整决策链可以压缩成一张表情形structureOutcomecallGraphOutcome报告影响getPluginForFile返回null无注册分析器skippedskipped计入filesSkipped无 result状态degraded退出码 0code/script 文件解析器无analyzeFileFull/extractCallGraph按analyzeFile结果判定skipped调用图不计失败解析器抛异常 / 返回非法值 / 输出畸形failedfailed独立判定触发hasFailedIntegrity状态failed退出码 1全部成功且无跳过——状态ok退出码 0从这次设计可以看到 Understand-Anything 基准体系的一条工程原则完整性检查宁严勿松但对「能力缺失」必须给出独立的、可审计的出口——把null的契约语义在调用点显式消费掉而不是让下游用失败来猜测它的含义。相关文件清单供继续深入设计文档 2026-07-17-benchmark-unsupported-outcomes-design.md、实施计划 2026-07-17-benchmark-unsupported-outcomes.md、CLI 入口 benchmark-large-repo.mjs、基准运行器 large-repo-benchmark.mjs、映射层 extract-structure-result.mjs、CLI 与结果记账 extract-structure.mjs、注册表 registry.ts。【免费下载链接】Understand-AnythingGraphs that teach graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.项目地址: https://gitcode.com/GitHub_Trending/un/Understand-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考