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 ≥ 20gitnexus-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]需要机器可读结果时加--jsonindex.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意味着图中确实存在该视图没有列出的调用方计数只是下限floorcauses.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 MyRepoSomeSymbol/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。随后对同一符号重跑impactepistemic应不再是lower-bound、causes.scopeExtractionFiles归零——在重新验证前仍应按下界对待旧结果。如果原因仍然存在检查 scope 提取警告GUARDRAILS 给出的后续动作是查看 scope-extraction 警告定位那个不受支持或格式损坏的源文件在受影响的源码被支持或修正之前把 impact 计数当作下限floors处理。警告与文件清单在代码中的来源警告由 scope-extractor-bridge.ts 上报文本形如scope extraction failed for filePath: reasonfilePath为仓库内文件路径reason为具体原因二者都是运行期实际值非固定字符串索引元数据持久化了一份摘要scope-extraction-failures.tstotal是失败文件的确切去重数paths是至多 25 条SCOPE_EXTRACTION_FAILURE_PATH_LIMIT按字典序排序的仓库相对路径样本超过时带truncated: truestatus的判定逻辑在 index-freshness.ts只有完整性回执为 1 且失败总数大于 0 时才报告scope-extraction-failed。也就是说如果--force重建后原因仍在警告文本和paths样本会告诉你具体是哪些文件、什么原因——这属于该文件暂不受支持或源码有问题的类别不是靠再重建能消除的修正或排除这些文件之前下界语义持续生效。已知边界文档明确区分三种不完整语义scope-extraction-failed是确认有文件缺失边scope-extraction-unverified是没有测量值scopeExtractionFiles: 0在lower-bound下不构成完整性证明。不要混用它们的结论。--force会丢弃并全量重建索引如果仓库此前生成了 embeddingsGUARDRAILS 声明普通analyze会保留它们而--force在 embedding checkpoint 场景下会连同 checkpoint 一并丢弃有警告涉及向量检索的仓库重建前请先了解这一副作用见 RUNBOOK Embeddings 一节。重建期间避免对同一仓库并发第二个analyzeLadybugDB 只允许单进程持有.gitnexus/lbug写。完成status验证、impact的epistemic恢复exact之后这个状态就闭环了若警告指向不受支持的源文件则按上文的边界说明继续以 under bound 对待相关结果。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考