GitNexus status 报 scope-extraction-failed 怎么办：impact 下界报告与 --force 重解析-编程实验室

GitNexus status 报 scope-extraction-failed 怎么办：impact 下界报告与 --force 重解析

【免费下载链接】GitNexusGitNexus: The Zero-Server Code Intelligence Engine - GitNexus is a client-side knowledge graph creator that runs entirely in your browser. Drop in a git repository (Github, Gitlab, Azure, Local) or ZIP file, and get an interactive knowledge graph with a built in Graph RAG Agent. Perfect for code exploration项目地址: https://gitcode.com/GitHub_Trending/gi/GitNexus

当你在仓库里执行npx gitnexus status，看到incompleteReasons中出现"scope-extraction-failed"时，说明索引构建时有一批文件的 scope 提取（scope capture）在 worker 和 fallback 两趟之后仍然失败。这些文件本身解析成功了，但从它们发出的调用、继承、导入和访问边可能缺失——此时impact/context的结果只能作为下界（lower bound）使用，直到你完成重解析并通过验证。这篇文章给出从定位原因、到--force重建、到确认索引恢复完整的完整操作路径。

适用前提

按 RUNBOOK.md 的 Prerequisites，环境需要：

Node.js ≥ 20（gitnexus-web/package.json的engines声明）；
Git，且status必须在 Git 仓库目录内执行——非 Git 目录会直接返回not-git-repository；
已安装并构建 CLI（发布安装后任意路径可用npx gitnexus …；从gitnexus/本地构建开发则用node dist/cli/index.js …）。

第一步：用 status 确认是 scope-extraction-failed

在目标仓库根目录执行：

npx gitnexus status

如果索引存在不完整原因，输出中会出现这样一行（RUNBOOK 中的记录格式）：

Index incomplete reasons: ["scope-extraction-failed"]

需要机器可读结果时加--json，index.incompleteReasons字段列出原因数组，status字段区分up-to-date与stale。

scope-extraction-failed的确切含义（见 RUNBOOK.md 与 GUARDRAILS.md 的 "Scope extraction is incomplete" 条目）：解析继续完成了，但被报告数量的那些文件连主线程 fallback 也无法产出 scope capture，因此从这些文件起源的边可能不在图里。

注意区分同一个位置可能出现的另一个原因scope-extraction-unverified：它表示索引早于完整性回执（completeness receipt）机制，或其元数据不可读。每一个存量索引在被"会写入完整性回执的版本"分析过一次之前，都处于 unverified 状态。两者处理顺序不同——先按本文处理failed；如果你看到的是unverified，先重新 analyze，在验证完成之前不要把空的 impact 结果当作精确值。

理解影响范围：impact 为什么会变成下界报告

这个状态直接影响impact和context两个工具的可信度。按 MCP 工具说明（tools.ts），两者的结果都带有同一套 epistemic 封装：

epistemic: 'exact' | 'lower-bound'——lower-bound意味着图中确实存在该视图没有列出的调用方，计数只是下限（floor）；
causes.scopeExtractionFiles（单位：文件数）> 0——scope 提取在 fallback 趟之后仍然失败，这些文件的 scope 解析边缺失；
boundaries是对应的自然语言解释，供人阅读；分支判断应基于causes字段。

两点必须记住：

causes.scopeExtractionFiles为 0不能证明完整性——当epistemic是lower-bound时，旧索引或未验证索引根本没有实测文件数，0 只是没有测量；
这些字段依赖只有当前版本分析器才会写入的索引时元数据。对着旧索引，元数据缺失和"什么都没丢"无法区分，所以在信任任何 0 值或看似精确的结果之前，先重新gitnexus analyze。

CLI 侧不需要编辑器也能核对（RUNBOOK "CLI equivalents of MCP tools" 一节）：

npx gitnexus impact SomeSymbol --direction upstream --repo MyRepo npx gitnexus context SomeSymbol --repo MyRepo

（SomeSymbol/MyRepo换成你要查询的符号名和已注册仓库名。）

修复：--force 全量重建

在目标仓库根目录执行：

npx gitnexus analyze --force

--force触发全量图重建（RUNBOOK 将其用于"同 commit 但怀疑损坏"的情形，GUARDRAILS 将其作为 scope 提取不完整后的完整重建路径）。普通的npx gitnexus analyze也会按 GUARDRAILS 的建议先行尝试；--force是确认后的强制路径。

重建完成后再次验证：

npx gitnexus status

成功的判定标准就是文档给出的状态本身：incompleteReasons不再包含scope-extraction-failed（--json下index.incompleteReasons中无该值，且status为up-to-date）。随后对同一符号重跑impact，epistemic应不再是lower-bound、causes.scopeExtractionFiles归零——在重新验证前，仍应按下界对待旧结果。

如果原因仍然存在：检查 scope 提取警告

GUARDRAILS 给出的后续动作是：查看 scope-extraction 警告，定位那个不受支持或格式损坏的源文件；在受影响的源码被支持或修正之前，把 impact 计数当作下限（floors）处理。

警告与文件清单在代码中的来源：

警告由 scope-extractor-bridge.ts 上报，文本形如scope extraction failed for <filePath>: <reason>（<filePath>为仓库内文件路径，<reason>为具体原因，二者都是运行期实际值，非固定字符串）；
索引元数据持久化了一份摘要（scope-extraction-failures.ts）：total是失败文件的确切去重数，paths是至多 25 条（SCOPE_EXTRACTION_FAILURE_PATH_LIMIT）按字典序排序的仓库相对路径样本，超过时带truncated: true；
status的判定逻辑在 index-freshness.ts：只有完整性回执为 1 且失败总数大于 0 时才报告scope-extraction-failed。

也就是说：如果--force重建后原因仍在，警告文本和paths样本会告诉你具体是哪些文件、什么原因——这属于"该文件暂不受支持或源码有问题"的类别，不是靠再重建能消除的，修正或排除这些文件之前，下界语义持续生效。

已知边界

文档明确区分三种"不完整"语义：scope-extraction-failed是确认有文件缺失边；scope-extraction-unverified是没有测量值；scopeExtractionFiles: 0在lower-bound下不构成完整性证明。不要混用它们的结论。
--force会丢弃并全量重建索引；如果仓库此前生成了 embeddings，GUARDRAILS 声明普通analyze会保留它们，而--force在 embedding checkpoint 场景下会连同 checkpoint 一并丢弃（有警告），涉及向量检索的仓库重建前请先了解这一副作用（见 RUNBOOK "Embeddings" 一节）。
重建期间避免对同一仓库并发第二个analyze，LadybugDB 只允许单进程持有.gitnexus/lbug写。

完成status验证、impact的epistemic恢复exact之后，这个状态就闭环了；若警告指向不受支持的源文件，则按上文的边界说明继续以 under bound 对待相关结果。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考