一、项目定位与设计目标

GitNexus 是一款面向 AI 编码代理的图驱动代码智能工具，其核心目标是将任意代码仓库预先解析为可查询的知识图谱，使 AI 代理在修改代码前即可获知完整的依赖、调用链与符号关系。gitnexus/package.json 将其描述为 "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI."，并通过 bin 字段暴露 gitnexus 可执行入口（dist/cli/index.js）以及 npm 包文件包含 dist、hooks、scripts、skills、vendor、web 等资源目录。

该项目的官方 README 明确指出："Three commands to give your AI agent full codebase awareness."，主入口命令 npx gitnexus analyze 一次性完成索引、Agent 技能安装、Claude Code 钩子注册以及 AGENTS.md / CLAUDE.md 上下文文件创建。仓库同时声明支持 Cursor、Claude Code、Antigravity（Google）、Codex、Windsurf、Cline、OpenCode 等多种 MCP 兼容工具，体现了"一次索引、多端消费"的产品定位。资料来源：gitnexus/package.json:1-40 资料来源：gitnexus/README.md:1-60

二、Monorepo 仓库结构与模块划分

GitNexus 顶层采用 monorepo 模式管理多个子包。根目录 package.json 名为 gitnexus-monorepo，并通过 gitnexus:refresh 与 gitnexus:full 脚本复用 gitnexus analyze 命令以维持自身索引的持续更新。资料来源：package.json:1-25

子包层面可分为以下几块：

gitnexus-shared/package.json 显式声明该包为 "Shared type definitions for GitNexus CLI and web" 并通过 exports 暴露主入口与测试助手子路径，确保 Node CLI 与未来浏览器侧共用同一组类型契约。资料来源：gitnexus-shared/package.json:1-25 资料来源：gitnexus-shared/src/scope-resolution/symbol-definition.ts:1-25

三、索引管道与图谱构建

根据 gitnexus/README.md 的 "How It Works" 章节，索引流程被划分为 6 个阶段：Structure（文件树遍历）、Parsing（Tree-sitter AST 抽取函数/类/方法/接口）、Resolution（语言感知的导入与调用解析，含字段与返回类型推断）、Clustering（功能社区聚类）、Processes（入口点到调用链的执行流追踪）以及 Search（BM25 + 语义向量混合索引）。最终结果落地为本地 .gitnexus/ 目录下的 LadybugDB 图数据库。

为了让这套管道在受限环境下也能工作，仓库直接 vendor 了 tree-sitter-c 与 tree-sitter-kotlin 等语法。tree-sitter-c/README.md 解释："tree-sitter-c is a required grammar whose own install script (node-gyp-build) compiles from source when no prebuild matches"，因此 GitNexus 自行构建 6 个平台架构的 prebuild 并 vendoring，以避免在无工具链 ARM 主机上安装失败。tree-sitter-kotlin/README.md 则说明了为何 pin 到 main 而非 npm tag：上游 0.3.8 不支持 fun interface 解析。资料来源：gitnexus/vendor/tree-sitter-c/README.md:1-15 资料来源：gitnexus/vendor/tree-sitter-kotlin/README.md:1-15

flowchart LR
    A[源码仓库] --> B[Structure<br/>文件树]
    B --> C[Parsing<br/>Tree-sitter AST]
    C --> D[Resolution<br/>类型/调用解析]
    D --> E[Clustering<br/>功能社区]
    E --> F[Processes<br/>执行流]
    F --> G[Search<br/>BM25+向量]
    G --> H[(.gitnexus/<br/>LadybugDB)]
    H --> I[MCP 工具]
    H --> J[CLI 查询]
    I --> K[AI 代理<br/>Cursor/Claude/...]
    J --> L[开发者终端]

四、MCP 服务暴露与外部集成

索引完成后的图谱通过 Model Context Protocol（MCP）暴露给 AI 代理。gitnexus/src/server/mcp-http.ts 中 mountMCPEndpoints 将 MCP 处理器挂载到 Web 服务器的 /api/mcp 路由：app.all('/api/mcp', (req, res) => { void handler(req, res).catch(...) })，并返回 cleanup 闭包用于会话资源回收。gitnexus/src/server/api.ts 则负责把 MCP 端点与其它 Web UI 路由一同组装到 Express 应用中。资料来源：gitnexus/src/server/mcp-http.ts:1-25 资料来源：gitnexus/src/server/api.ts:1-25

为了让图谱能力对接到更多生态，gitnexus-shared 还提供了与 looptech-ai/understand-quickly 注册中心的集成原型。understand-quickly.ts 在运行时无依赖的前提下构造 repository_dispatch 事件，文档化的端点 UNDERSTAND_QUICKLY_DISPATCH_URL 与事件类型 UNDERSTAND_QUICKLY_EVENT_TYPE 硬编码以指向该注册仓库的工作流。同时，resilient-fetch.ts 提供带熔断与重试分类的 resilientFetch，用于在 GitHub 限流（429/Retry-After）或终端错误（401/403/404/422）下安全降级。资料来源：gitnexus-shared/src/integrations/understand-quickly.ts:1-30 资料来源：gitnexus-shared/src/integrations/resilient-fetch.ts:1-25

五、发布节奏与已知工程热点

发布方面，README 说明："When a pull request with non-documentation changes merges into main, an automated workflow also publishes a prerelease build under the rc dist-tag."，版本号遵循 X.Y.Z-rc.N 语义（社区上下文显示 1.6.8-rc.44 ~ rc.52 与 1.6.9-rc.9 已陆续发布）。社区 issue 也透露出几个常见故障模式：C++ 项目在 1.6.7 链接符号阶段卡死（#2243 引用 #1973）、离线 NPM 镜像下 FTS 功能不可用（#2184）、gitnexus wiki --lang chinese 触发 LadybugDB not initialized for repo "__wiki__"（#2225）。这些都集中在索引与初始化阶段，与上文管道中的 Resolution / Search 子阶段以及多仓库注册表维护直接相关。资料来源：gitnexus/README.md:1-120

See Also

• Indexing Pipeline（解析管道详解）
• MCP Tools Reference（MCP 工具参考）
• CLI Commands（CLI 命令清单）
• Supported Languages（支持语言矩阵）
• Troubleshooting & Known Issues（故障排查）

CLI 命令、配置与 MCP 服务器

GitNexus 的对外接口由 CLI 命令、MCP 服务器 与 MCP 工具/资源 三部分组成，覆盖代码库索引、查询、Wiki 文档生成与多仓库协同的全部场景。CLI 通过 npm 上的 gitnexus 包暴露主入口（资料来源：gitnexus/package.json:2-8），并依赖 LadybugDB 图数据库与 Tree-sitter 解析管线在本地完成所有计算。

CLI 命令参考

CLI 是用户与 GitNexus 交互的主入口。从 gitnexus/README.md 的命令清单可知，主命令分为索引、查询、Wiki 与多仓库（group）四类（资料来源：gitnexus/README.md:25-50）。

• 索引：gitnexus analyze 是核心入口，它会建立知识图、写入 AGENTS.md / CLAUDE.md、注册 Claude Code 钩子并安装 Agent Skills。在 npm 11.x 下若 npx 出现 Cannot destructure property 'package' of 'node.target' 错误，建议改用 pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus ... 形式执行。
• 查询：query（混合检索）、context <symbol>（360° 符号视图）、impact <symbol>（爆炸半径）、detect-changes（工作树 diff 影响映射）以及 cypher "<query>"（原生 Cypher 直查）这五个子命令与 MCP 工具一对一对应，可在不启动 MCP daemon 的情况下直接使用。
• Wiki：gitnexus wiki 生成由 LLM 驱动的文档，支持 --lang <lang> 与 --model <model> 两个常用选项。社区中报告的 Error: LadybugDB not initialized for repo "__wiki__"（参见 issue #2225）属于 Wiki 自身的初始化缺陷，并非 --lang 标志的语义错误。
• 多仓库：group create / add / remove / list / sync / contracts 子命令用于跨仓库的服务追踪；group add 的 <groupPath> 是层级路径（如 hr/hiring/backend），<registryName> 是来自 gitnexus list 的注册仓库名。

MCP 服务器、工具与资源

MCP 服务器默认通过 stdio 与 AI 代理通信，HTTP 形态由 gitnexus/src/server/mcp-http.ts 提供（资料来源：gitnexus/src/server/mcp-http.ts:14-30）：它把流式 HTTP 处理器挂载到 Express 的 /api/mcp 路由上，并在请求失败时返回 code: -32000 的 JSON-RPC 错误。mountMCPEndpoints 同时返回一个 cleanup 函数，由 Web UI 服务器在关闭时调用以释放会话资源。

MCP 工具集与 README 中的 CLI 工具表保持同构：

当仅有一个索引仓库时，repo 参数可省略；多个仓库共存时必须显式指定。MCP 资源（gitnexus://repos、gitnexus://repo/{name}/context、.../clusters、.../cluster/{name}、.../processes、.../process/{name}、.../schema）则提供仓库统计、聚类与进程轨迹的只读视图。

索引管线与配置约束

CLI 在执行 analyze 时会驱动一条多阶段管线，阶段枚举定义在 gitnexus-shared/src/pipeline.ts（资料来源：gitnexus-shared/src/pipeline.ts:5-20）：extracting → structure → parsing → imports → calls → heritage → scopeResolution → communities → processes → enriching → complete，每阶段都会向 UI 推送 phase / percent / message / stats 进度。管线的产出是 LadybugDB 图数据库，NODE_TABLES 与 REL_TYPES 在 gitnexus-shared/src/lbug/schema-constants.ts 集中声明（资料来源：gitnexus-shared/src/lbug/schema-constants.ts:8-50），并被 gitnexus-shared 同时复用于 CLI 与 Web，以保证两端数据兼容。

语言支持由 gitnexus-shared/src/languages.ts 的 SupportedLanguages 枚举统一管理（资料来源：gitnexus-shared/src/languages.ts:5-30）。成熟度按 gitnexus-shared/src/scope-resolution/language-classification.ts 分为 production 与 experimental 两档（资料来源：gitnexus-shared/src/scope-resolution/language-classification.ts:30-60）：Vue 与 Cobol 目前为实验性，C++ 属于生产档——这与 issue #2243 报告的 C++ 符号链接卡顿是同一档位上的功能问题，索引 C++ 工程时需要关注。

可选的注册中心集成通过 UNDERSTAND_QUICKLY_TOKEN 环境变量开启（资料来源：gitnexus-shared/src/integrations/understand-quickly.ts:25-40），仅在用户提供 token 时才会向 looptech-ai/understand-quickly 派发 sync-entry 事件；该模块刻意保持纯函数实现，避免在共享包中引入 Node 专属依赖。gitnexus-shared 的导出由 gitnexus-shared/src/index.ts 集中管理（资料来源：gitnexus-shared/src/index.ts:1-30）。

常见故障与版本通道

• FTS 无法使用（issue #2184）：在仅有 NPM 镜像的离线环境安装 [email protected] 时，@ladybugdb/core 的原生构建可能缺失，导致全文本索引不可用。可改用 pnpm 显式允许构建，或临时切换到 npm install -g gitnexus@rc 获取最新预发布版本。
• C++ 符号链接卡顿（issue #2243 / #1973）：在 imports / calls 阶段，复杂头文件关系可能消耗大量时间。重现时建议先用 gitnexus query 抽样验证，必要时清理 .gitnexus/ 重新建立索引。
• analyze 写入面不可关闭（issue #1265）：当前没有 flag、环境变量或哨兵文件来跳过 CLAUDE.md / AGENTS.md / .gitignore / skills 的改写，对这些文件有版本管理要求的团队应先在 analyze 之外备份。
• 预发布通道：每次非文档类 PR 合入 main 后会自动发布 X.Y.Z-rc.N 到 rc dist-tag，例如 1.6.9-rc.9，可通过 npm install -g gitnexus@rc 或 npx gitnexus@rc analyze 验证新功能。稳定版仍发布在 latest 上（资料来源：gitnexus/README.md:115-135）。

See Also

• 知识图管线与数据结构：gitnexus-shared/src/lbug/schema-constants.ts
• 语言识别与扩展名映射：gitnexus-shared/src/language-detection.ts
• 共享类型与集成导出：gitnexus-shared/src/index.ts

概述与定位

GitNexus 的「语言解析、Tree-sitter 与作用域解析引擎」是知识图谱索引流水线的核心。它位于 Structure → Parsing → Resolution → Clustering → Processes 多阶段管线中，负责将任意源代码文件转换为可查询的图谱节点与边。整条流水线使用本地 LadybugDB 存储，产出 .gitnexus/ 索引目录。引擎拆分为两个独立的共享包（gitnexus-shared 持有语言枚举、作用域类型、最终化算法；gitnexus/ 持有 CLI 与 Tree-sitter 加载器），目的是让 CLI 与未来浏览器端共享同一份语义建模逻辑。

资料来源：gitnexus/README.md:39-53

支持的语言与检测机制

SupportedLanguages 枚举是整条管线的「语言真理之源」，CLI 在解析阶段、Web 在语法高亮阶段都依赖它。该枚举当前覆盖 16 种语言，区分 production 与 experimental 两档分级：

language-detection.ts 中的 EXTENSION_MAP 是穷尽映射，新增枚举成员而未补全映射时，TypeScript 会在编译期报错。同时该模块记录了 Ruby 的无扩展名文件名（Rakefile、Gemfile 等）作为兜底，确保这类文件被正确归类。Web 端的 getSyntaxLanguageFromFilename 将语言枚举映射到 Prism 高亮标识符，CLI 与 Web 共享同一份检测逻辑。

资料来源：gitnexus-shared/src/languages.ts:7-25、gitnexus-shared/src/language-detection.ts:14-30、gitnexus-shared/src/scope-resolution/language-classification.ts:1-25

Tree-sitter 语法集成与预构建策略

GitNexus 大量 vendoring Tree-sitter 语法（gitnexus/vendor/tree-sitter-*），并对每个语法维护了双轨加载策略：

1. NPM 路径：优先使用上游发布的 prebuilds/ 二进制，node-gyp-build 在 require 时按平台挑选。
2. 源码路径：当宿主工具链可用但无匹配 prebuild 时，build-tree-sitter-grammars.cjs 现场编译 native binding。

对于 tree-sitter-kotlin 这种上游只发布源码、不发布 prebuild 的情况，GitNexus 直接将 parser.c、scanner.c、binding.gyp、src/ vendoring 到仓库内，并自建 .github/workflows/build-tree-sitter-prebuilds.yml 跨平台交叉编译二进制，再随版本一起分发。Swift（0.7.1）与 Dart 也走相同路径。vendored 语法通过 vendor/tree-sitter-kotlin/package.json 中的 _vendoredBy 元数据明确标注来源与 ABI 版本。

关键的工程取舍：tree-sitter-kotlin 不带 scripts.install 钩子，目的是规避历史 issue #836 与 #1728；加载由 vendored-grammars.ts 通过绝对路径指向 vendor/ 下的源文件，而不是复制到 node_modules/（issue #2111）。这样即便 npm install 阶段被跳过，运行时仍可定位 native binding。

资料来源：gitnexus/vendor/tree-sitter-kotlin/README.md:1-15、gitnexus/vendor/tree-sitter-kotlin/package.json:1-8、gitnexus/vendor/tree-sitter-swift/README.md:1-25、gitnexus/vendor/tree-sitter-dart/README.md:1-12

作用域解析引擎

TypeRef 与作用域建模

作用域解析的根类型是 TypeRef（类型引用）和 Scope（词法作用域），二者构成 SemanticModel 的脊柱。

• TypeRef 持有按源码原样书写的名称（rawName）与声明点的 ScopeId，刻意推迟解析时点。其 source 字段枚举了注解来源：annotation、parameter-annotation、return-annotation、self、assignment-inferred、constructor-inferred、receiver-propagated。typeArgs 字段为 V2 泛型预留，V1 忽略。
• Scope.id 形状为 scope:{filePath}#{startLine}:{startCol}-{endLine}:{endCol}:{kind}，保证跨重解析稳定，且经过 interned。
• SymbolDefinition 携带 templateArguments（如 ['User']、['T*']）与不透明的 templateConstraints（C++ 的 enable_if_t 或 C++20 requires 子句），并通过 ownerId 把方法/构造器/属性链接回所属类/结构体。isExplicit 与 isDeleted 用于 C++ 重载排序，删除的函数仍参与选择但被选中时抑制边发射。

资料来源：gitnexus-shared/src/scope-resolution/types.ts:1-30、gitnexus-shared/src/scope-resolution/symbol-definition.ts:1-20

流水线数据流

flowchart LR
  A[文件树] --> B[language-detection<br/>确定 SupportedLanguages]
  B --> C[tree-sitter 解析<br/>AST + 节点类型]
  C --> D[per-file 提取<br/>ParsedImport + SymbolDefinition]
  D --> E[finalize 算法<br/>SCC + 定点链接]
  E --> F[SemanticModel<br/>Scope + 边 + 绑定]
  F --> G[LadybugDB 图谱<br/>.gitnexus/]

finalize 跨文件算法

finalize-algorithm.ts 实现了「跨文件最终化」：输入是各文件的 ParsedImport[] 与 SymbolDefinition[]，输出是带 targetModuleScope 与 targetDefId 的 ImportEdge[]，并按 SCC 凝聚暴露给调用方做并行处理。

• SCC 感知：先对文件级 import 图跑 Tarjan SCC，再按逆拓扑顺序处理（叶子优先），同一 SCC 内跑有界定点（N = |edges in SCC|），循环导入会收敛而不死锁，畸形输入由 cap 兜底。
• 语言无关：目标解析、通配符展开、绑定优先级都通过 resolveImportTarget / expandsWildcardTo / mergeBindings 三个钩子注入，对应 LanguageProvider 表面。
• 非绑定导入规则：dynamic-unresolved 边原样透传，由后续阶段处理。

资料来源：gitnexus-shared/src/scope-resolution/finalize-algorithm.ts:1-30

已知问题与社区反馈

社区中与本子系统相关的高频问题集中在 C++ 与跨平台安装场景：

• C++ 符号链接卡死（issue #2243 关联 #1973）：在 1.6.7 版本上解析 C++ 头文件时 finalize 阶段疑似未命中 SCC cap，导致长时间挂起。这是 finalize-algorithm.ts 中 N = |edges in SCC| 上界在大型模板/头文件图上偏紧的直接表现。
• FTS 安装与离线环境（issue #2184）：Debian + 离线 NPM 镜像环境下 npm install [email protected] 缺失 FTS native 资源。Tree-sitter 预构建缺失会触发源码编译路径，进而要求 python3/make/g++ 工具链，与 vendoring 文档中的兜底假设一致。
• LadybugDB 未初始化（issue #2225）：gitnexus wiki --lang chinese 在 __wiki__ 仓库上失败，根因是 LadybugDB 实例未先于 wiki 子命令被初始化。

资料来源：issue #2243、issue #2184、issue #2225()

See Also

• Indexing Pipeline Overview — 解析之前的 Structure 阶段与之后的 Clustering / Processes 阶段
• MCP Tools & Resources — 通过 query / context / impact 工具消费作用域解析结果
• Build & Vendoring Strategy — 详细说明 prebuild 工作流与 vendoring 决策树

存储层、嵌入与 Wiki 生成

GitNexus 把仓库解析成一棵代码知识图谱后持久化到 LadybugDB 中；查询时通过 BM25 + 语义 + RRF 的混合检索定位相关过程与符号；最后通过 gitnexus wiki 命令调用 LLM 直接在图之上生成结构化文档。本页覆盖存储层、嵌入与混合检索、Wiki 生成三个子系统的设计、行为与已知故障模式。

存储层：LadybugDB

节点表与关系表

schema-constants.ts 是 CLI 与 Web 之间唯一共享的 schema 真相来源——CLI 使用原生 LadybugDB 绑定，Web 使用 WASM，两者必须对表名与关系名保持一致，否则数据无法跨表面互操作。资料来源：gitnexus-shared/src/lbug/schema-constants.ts:1-50

知识图谱由一组固定的节点表与一个统一的 CodeRelation 关系表构成。节点表覆盖了主流语言的结构元素：

• 基础结构：File、Folder、Module、Section
• 面向对象：Class、Interface、Trait、Impl、Struct、Record、Delegate
• 可调用单元：Function、Method、Constructor
• 类型声明：Enum、Union、Typedef、TypeAlias、Annotation、Template
• 值与作用域：Variable、Const、Static、Property、Namespace
• 元数据：Community、Process、Route、Tool

BasicBlock 是为污点分析/PDG（#2080）预埋的控制流底层节点，目前保持 inert 直到 M1 (#2081) 开始发射 block。关系表统一命名为 CodeRelation，类型包括 CONTAINS、DEFINES、IMPORTS、CALLS、EXTENDS、IMPLEMENTS、HAS_METHOD、HAS_PROPERTY、ACCESSES、METHOD_OVERRIDES（OVERRIDES 是旧版兼容别名，保留至所有历史索引迁移完毕）。

适配器、连接池与持久化

存储层的运行时组件各司其职：

• lbug-adapter.ts —— 与原生 LadybugDB 交互的主要适配层
• pool-adapter.ts —— 连接池封装，复用昂贵的原生句柄
• wal-checkpoint-driver.ts —— 控制 WAL 与 checkpoint 节奏，避免 WAL 持续增长
• csv-generator.ts —— 把图内容物导出为 CSV，便于外部分析工具对接

完整的 DDL 仍保留在 CLI 与 Web 各自的 schema.ts 中——CLI 走原生 binding 而 Web 走 WASM，DDL 文本不能共享——但表名与关系名通过 schema-constants.ts 中的 NODE_TABLES/REL_TYPES 常量保持一致。资料来源：gitnexus/src/core/lbug/schema.ts

嵌入与混合检索

query 工具（同时通过 MCP 暴露为同名工具）执行"过程分组"的混合检索：先 BM25 全文本召回，再语义向量召回，最后用 Reciprocal Rank Fusion (RRF) 融合两个排序。hybrid-search.ts 是该管线的实现文件。资料来源：gitnexus/src/core/search/hybrid-search.ts

在多仓库场景下，工具的 repo 参数成为必填字段；在只索引一个仓库时则可省略。context 工具围绕符号生成 360° 视图（按引用类型分类），impact 工具按深度与置信度分组计算 blast radius，二者都建立在 LadybugDB 之上、以 Cypher 查询完成。资料来源：gitnexus/README.md

Wiki 生成

gitnexus wiki 命令调用 LLM（默认 gpt-4o-mini）直接从知识图谱生成结构化文档：

gitnexus wiki                 # 默认模型与语言
gitnexus wiki --model <m>     # 自定义 LLM 模型
gitnexus wiki --lang chinese  # 指定输出语言

资料来源：gitnexus/README.md

端到端数据流

flowchart LR
    A["gitnexus analyze"] --> B["LadybugDB<br/>知识图谱"]
    B --> C["hybrid-search<br/>BM25+Sem+RRF"]
    B --> D["gitnexus wiki"]
    D --> E["LLM<br/>gpt-4o-mini"]
    E --> F["结构化 Wiki"]
    C --> G["MCP 工具<br/>query/context/impact"]

已知故障模式

社区报告的明确 bug（#2225）显示，--lang chinese 等参数触发 Wiki 生成时，工具会以仓库名 __wiki__ 初始化一个虚拟图实例并调用 initLbug，但部分代码路径可能跳过初始化或检查时机过早，从而抛出 Error: LadybugDB not initialized for repo "__wiki__". Call initLbug first.。该问题在主分支修复前可手动重新运行 gitnexus analyze 以确保底层图实例存在。资料来源：issue #2225

另一个相关问题（#1973 / #2243）是 C++ 仓库的"符号链接"在 analyze 阶段会卡住——通常发生在 finalize 阶段的 SCC 修复点循环中，与符号解析层的硬封顶迭代次数相关，根因仍在调查中。资料来源：issue #2243

See Also

• 知识图谱摄入与符号解析：Scope Resolution & Finalize Algorithm
• MCP 工具与服务器：MCP Server & Local Backend
• 命令行使用：CLI Commands Reference

Pitfall Log / 踩坑日志

项目：abhigyanpatwari/GitNexus

摘要：发现 29 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：Install FTS feature。

1. 安装坑 · 来源证据：Install FTS feature

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Install FTS feature
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/abhigyanpatwari/GitNexus/issues/2184 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：Tree-sitter 0.25 upgrade readiness

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Tree-sitter 0.25 upgrade readiness
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/abhigyanpatwari/GitNexus/issues/2194 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

3. 配置坑 · 来源证据：Cpp, still stuck while linking symbols in 1.6.7

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Cpp, still stuck while linking symbols in 1.6.7
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/abhigyanpatwari/GitNexus/issues/2243 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

4. 安装坑 · 失败模式：installation: Error: LadybugDB not initialized for repo "__wiki__". Call initLbug first.

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Error: LadybugDB not initialized for repo "__wiki__". Call initLbug first.
• 对用户的影响：Developers may fail before the first successful local run: Error: LadybugDB not initialized for repo "__wiki__". Call initLbug first.
• 证据：failure_mode_cluster:github_issue | https://github.com/abhigyanpatwari/GitNexus/issues/2225 | Error: LadybugDB not initialized for repo "__wiki__". Call initLbug first.

5. 安装坑 · 失败模式：installation: Install FTS feature

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Install FTS feature
• 对用户的影响：Developers may fail before the first successful local run: Install FTS feature
• 证据：failure_mode_cluster:github_issue | https://github.com/abhigyanpatwari/GitNexus/issues/2184 | Install FTS feature

6. 安装坑 · 失败模式：installation: Release Candidate v1.6.8-rc.43

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Release Candidate v1.6.8-rc.43
• 对用户的影响：Upgrade or migration may change expected behavior: Release Candidate v1.6.8-rc.43
• 证据：failure_mode_cluster:github_release | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.8-rc.43 | Release Candidate v1.6.8-rc.43

7. 安装坑 · 失败模式：installation: Release Candidate v1.6.8-rc.44

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Release Candidate v1.6.8-rc.44
• 对用户的影响：Upgrade or migration may change expected behavior: Release Candidate v1.6.8-rc.44
• 证据：failure_mode_cluster:github_release | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.8-rc.44 | Release Candidate v1.6.8-rc.44

8. 安装坑 · 失败模式：installation: Release Candidate v1.6.8-rc.45

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Release Candidate v1.6.8-rc.45
• 对用户的影响：Upgrade or migration may change expected behavior: Release Candidate v1.6.8-rc.45
• 证据：failure_mode_cluster:github_release | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.8-rc.45 | Release Candidate v1.6.8-rc.45

9. 安装坑 · 失败模式：installation: Release Candidate v1.6.8-rc.46

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Release Candidate v1.6.8-rc.46
• 对用户的影响：Upgrade or migration may change expected behavior: Release Candidate v1.6.8-rc.46
• 证据：failure_mode_cluster:github_release | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.8-rc.46 | Release Candidate v1.6.8-rc.46

10. 安装坑 · 失败模式：installation: Release Candidate v1.6.8-rc.47

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Release Candidate v1.6.8-rc.47
• 对用户的影响：Upgrade or migration may change expected behavior: Release Candidate v1.6.8-rc.47
• 证据：failure_mode_cluster:github_release | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.8-rc.47 | Release Candidate v1.6.8-rc.47

11. 安装坑 · 失败模式：installation: Release Candidate v1.6.8-rc.48

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Release Candidate v1.6.8-rc.48
• 对用户的影响：Upgrade or migration may change expected behavior: Release Candidate v1.6.8-rc.48
• 证据：failure_mode_cluster:github_release | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.8-rc.48 | Release Candidate v1.6.8-rc.48

12. 安装坑 · 失败模式：installation: Release Candidate v1.6.8-rc.49

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Release Candidate v1.6.8-rc.49
• 对用户的影响：Upgrade or migration may change expected behavior: Release Candidate v1.6.8-rc.49
• 证据：failure_mode_cluster:github_release | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.8-rc.49 | Release Candidate v1.6.8-rc.49

13. 安装坑 · 失败模式：installation: Release Candidate v1.6.8-rc.50

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Release Candidate v1.6.8-rc.50
• 对用户的影响：Upgrade or migration may change expected behavior: Release Candidate v1.6.8-rc.50
• 证据：failure_mode_cluster:github_release | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.8-rc.50 | Release Candidate v1.6.8-rc.50

14. 安装坑 · 失败模式：installation: Release Candidate v1.6.8-rc.51

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Release Candidate v1.6.8-rc.51
• 对用户的影响：Upgrade or migration may change expected behavior: Release Candidate v1.6.8-rc.51
• 证据：failure_mode_cluster:github_release | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.8-rc.51 | Release Candidate v1.6.8-rc.51

15. 安装坑 · 失败模式：installation: Release Candidate v1.6.8-rc.52

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Release Candidate v1.6.8-rc.52
• 对用户的影响：Upgrade or migration may change expected behavior: Release Candidate v1.6.8-rc.52
• 证据：failure_mode_cluster:github_release | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.8-rc.52 | Release Candidate v1.6.8-rc.52

16. 安装坑 · 来源证据：Add Laravel Blade Template Support

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add Laravel Blade Template Support
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/abhigyanpatwari/GitNexus/issues/1853 | 来源类型 github_issue 暴露的待验证使用条件。

17. 安装坑 · 来源证据：Error: LadybugDB not initialized for repo "__wiki__". Call initLbug first.

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Error: LadybugDB not initialized for repo "__wiki__". Call initLbug first.
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/abhigyanpatwari/GitNexus/issues/2225 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

18. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/abhigyanpatwari/GitNexus | host_targets=mcp_host, claude_code, claude, cursor

19. 配置坑 · 来源证据：impact callgraph mode fails when agent appends omitted optional line as 0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：impact callgraph mode fails when agent appends omitted optional line as 0
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/abhigyanpatwari/GitNexus/issues/2279 | 来源类型 github_issue 暴露的待验证使用条件。

20. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/abhigyanpatwari/GitNexus | README/documentation is current enough for a first validation pass.

21. 运行坑 · 来源证据：Group bridge.lbug in-process read-only reopen fails on Windows

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Group bridge.lbug in-process read-only reopen fails on Windows
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/abhigyanpatwari/GitNexus/issues/2274 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

22. 维护坑 · 来源证据：feat(taint): Java source/sink model slice

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：feat(taint): Java source/sink model slice
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/abhigyanpatwari/GitNexus/issues/2261 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

23. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/abhigyanpatwari/GitNexus | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/abhigyanpatwari/GitNexus | no_demo; severity=medium

25. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/abhigyanpatwari/GitNexus | no_demo; severity=medium

26. 安全/权限坑 · 来源证据：Cross-repo trace: cross-file named HTTP handlers resolve to file-level, not symbol-precise

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Cross-repo trace: cross-file named HTTP handlers resolve to file-level, not symbol-precise
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/abhigyanpatwari/GitNexus/issues/2275 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

27. 运行坑 · 失败模式：performance: Cpp, still stuck while linking symbols in 1.6.7

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: Cpp, still stuck while linking symbols in 1.6.7
• 对用户的影响：Developers may hit a documented source-backed failure mode: Cpp, still stuck while linking symbols in 1.6.7
• 证据：failure_mode_cluster:github_issue | https://github.com/abhigyanpatwari/GitNexus/issues/2243 | Cpp, still stuck while linking symbols in 1.6.7

28. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/abhigyanpatwari/GitNexus | issue_or_pr_quality=unknown

29. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/abhigyanpatwari/GitNexus | release_recency=unknown