Big Indexer

BGI - Big Indexer

BGI 是一款面向大型代码库的静态架构分析工具。 它按行为角色对代码单元进行分组，并明确给出架构边界。 项目领域：bigindexer.com

通过 MCP Registry 使用

Big Indexer 已在 MCP Registry 中发布，名称为 io.github.ahmedxuhri/bigindexer。

pip install bigindexer==0.1.3
bgi mcp --graph bgi-graph.json --fuse-graph fuse-graph.json

验证：https://bigindexer.com/validation

此工具解决的问题

大多数架构图在规模扩大时会因以下两点而失效：

• 噪声边过多
• 巨型集群将无关组件合并在一起

BGI 旨在控制这两种情况，让输出在大型仓库中仍然可用。

可以用它做什么

1. “重构之前，边界应该划在哪里？”
   BGI 按行为角色对单元进行分组（COV 令牌 + DRS 聚类），从而让可能的组件边界清晰可见。
2. “哪些子系统之间的耦合存在风险？”
   BGI 会揭示集群之间的高耦合接缝和融合边界信号，让集成风险更容易被发现。
3. “如何将架构数据接入自动化流程？”
   BGI 会生成机器可读的产物（bgi-graph.json、fuse-graph.json），以及可选的人工可读上下文（bigindexer.md）。
4. “如何让 AI 的修改不那么随意？”
   MCP 工具（task_fingerprint、behavioral_twins、twin_context）会根据仓库内的行为模式为提示词提供依据。
5. “能否在 PR 上自动运行，作为实时示例？”
   可以——使用专用操作仓库 ahmedxuhri/bigindexer-pr-risk-bot，自动在 PR 中发表评论，提供影响范围、接缝和风险提示。

---

30 秒演示

在随附的示例仓库上运行 BGI：

git clone https://github.com/ahmedxuhri/bigindexer
cd bigindexer
pip install -e .
bgi scan tests/fixtures --lang python --out /tmp/bgi-example.json
head -50 /tmp/bgi-example.json

此仓库上的实际结果：

• 单元：12
• 边：14
• 集群：2
• 示例中的最大集群：6 个单元

生成的一条边如下：

{
  "source": "auth_module.py::AuthService::__init__",
  "target": "auth_module.py::AuthService::__del__",
  "key": "COV.INIT",
  "lock": "COV.TEARDOWN",
  "type": "HARD"
}

这很重要：你得到的不只是原始语法引用，还能获得可用于架构决策的行为关系和集群结构。

---

通俗术语表

BGI 术语	通俗解释
COV token	单元的行为标签（例如：FETCH、PERSIST、AUTHENTICATE）
Key-Lock edge	两个角色互补的单元之间的行为连接
DRS cluster	按行为角色进行的单元级分组。实际使用中大多发生在文件内部。文件级架构组件更适合通过 BGI 边图或 fuse-graph 边界信号来表示——参见外部基准测试
Fuse edge / fuse event	因集群增长达到上限而拒绝合并；视为边界信号
Spectral masks	限定允许匹配范围的规则（全局、目录、文件）

---

架构一览

Source files
   ->
Gate 1: fingerprint unit behavior (COV tokens)
   ->
Gate 2: create behavioral edges with scoped matching
   ->
Gate 3: cluster with hard size cap + boundary emission
   ->
Artifacts: bgi-graph.json, fuse-graph.json, bigindexer.md, optional routes/graphml/html

核心方法：

1. TOKEN-CENSUS - 按令牌频率对每个仓库分类。
2. SPECTRAL-MASKS - 根据令牌频率限制匹配范围。
3. FUSE-MAP - 限制集群增长，并记录被拒绝的合并。
4. MASK-4-GATE-3 - 将导入邻近性用作聚类信号。
5. WATER-CLOCK + .scm - 在 Gate 1 中使用单次遍历的查询提取路径。

---

BGI 与常见替代方案的不同之处

能力	LSP / SCIP 索引	调用图 + 通用社区检测	BGI
快速符号查找	强	中等	可用（Phase 6 索引）
行为令牌模型	否	通常没有	是
严格限制聚类范围	否	通常没有	是（单元级）
一等边界产物	否	通常没有	是（fuse-graph.json）
范围约束的边生成	有限	少见	是（谱掩码）

外部正面对比基准（在 BGI 的边上运行 Louvain，与在原始导入关系上运行 Louvain 对比，并以包布局评分）：BGI 的边在 Python 上表现更好（django F1 为 0.38，对比 0.29；MoJoFM 为 0.45，对比 0.34）；在 Go 上目前持平或较弱，原因是 tier-2 扫描器的跨文件边密度较低。完整结果和方法见 docs/VALIDATION_EVIDENCE.md。

---

证据（当前、可验证）

大型仓库规模证据

可比的 kubernetes 样本（go 可比模式，162,917 个单元）：

• Gate 1：141.964s
• Gate 2：67.261s（历史可比基线：138.869s）
• Gate 3：9.359s
• 总计：218.584s
• 最大集群：1.113%
• 融合事件：0

产物：output/validation/kubernetes-optionb-controlled-median-v21.json

质量保障证据（不止原始速度）

• Gate 2 范围安全测试会阻止无效的跨范围合并（见 tests/test_gate2.py）。
• Gate 3 测试会验证在没有导入证据时，不会发生旧命名空间过度合并（见 tests/test_gate3.py）。
• 当前完整测试套件状态：python3 -m pytest tests/ -x -q（项目基线目标仍然通过）。

证据摘要

• 当前已发布的验证集：涵盖 5 个仓库和 3 个模型的 100 次评分运行。
• BGI-TWIN 上下文的完整 20 次发货后基准刷新（task → COV → top-3 twins + seam + rubric）已完成：可执行性 4.75/5（p04 子集：4.8/5），边界 1.0，幻觉 0。
• 独立模型复现现已完成：azure/gpt-4o（20 次运行）和 gemini/auto（20 次运行）。GPT-4o 可执行性为 4.85/5，Gemini 可执行性为 4.25/5，二者均无幻觉；Gemini 边界得分 0.95，反映出一次真实的 django/p02 遗漏。
• 仍缺少：在外部语料上进行的带标注精确率/召回率基准，以及使用同一带标注数据集与外部工具进行的正面对比定量基准。

---

语言支持层级（明确划分）

BGI 并非平等支持所有语言，而是分级支持：

1. 基于查询（.scm）：python、typescript、tsx、javascript、go、rust、java、csharp、php、ruby、kotlin、scala
2. Tree-sitter 扫描器 + 规则路径：c、lua、elixir
3. 按扩展名进行通用正则回退：swift、r、dart、bash、nim、zig、haskell、ocaml、fsharp、clojure、erlang、matlab、vb、crystal、cobol、groovy

请将此作为可靠性参考：基于查询和专用扫描器层级的支持强于通用回退。

**跨文件边密度说明：**以上语言层级描述的是解析器质量。另一个独立维度是跨文件行为边密度——扫描器生成多少关键锁对，用于关联不同文件中的单元。第 1 层（基于 .scm）语言会生成密集的跨文件边。目前，第 2 层扫描器支持的语言生成的跨文件边较稀疏，因为其词元主要由结构性词元（INTAKE/OUTPUT/CONDITIONAL/LOOP）构成，而 gate-2 会特意将这些词元的作用范围限制在同一文件内，以防产生 O(N²) 噪声。面向用户的 MCP 产品（边界检测、双生项检索、AI 助手上下文）仍适用于第 2 层语言——请参阅验证证据；但与导入图基线对比的簇恢复基准测试会反映这种密度差异。具体数据见 docs/VALIDATION_EVIDENCE.md。

---

局限性和非目标

1. BGI 属于静态分析；不会采集运行时跟踪信息。
2. 跨文件语义解析依赖启发式方法，并因语言而异。
3. 会衡量簇大小的健康度；尚未发布完整的外部精确率/召回率数据。
4. 共享主机基准测试会带来偏差；决策应使用受控环境下的中位数。

---

安装

pip install -e .

快速入门命令

# scan
bgi scan /path/to/repo --lang auto --out bgi-graph.json

# optional outputs
bgi scan /path/to/repo --lang auto \
  --fuse-graph fuse-graph.json \
  --routes routes.json \
  --graphml graph.graphml \
  --html

# incremental
bgi scan /path/to/repo --lang auto --incremental --cache .bgi-cache.json

# diff
bgi diff /path/before /path/after --lang auto --out diff.json

# run MCP server over generated artifacts
bgi mcp --graph bgi-graph.json --fuse-graph fuse-graph.json

MCP 使用示例模式（来自你的客户端提示词）：

Use MCP tool twin_context for:
"Add endpoint that validates input and persists data."
Return top twin candidate, seam suggestion, and rubric checklist.

---

遥测

BGI 提供默认关闭、选择加入的匿名遥测功能。启用方法：

export BGI_TELEMETRY=1
bgi mcp --graph bgi-graph.json --fuse-graph fuse-graph.json

启用后收集的内容：BGI 版本、操作系统、仓库大小范围，以及仓库 git 远程地址的 12 位哈希值（以便去重“同一仓库被查看两次”的情况，同时绝不会知道具体是哪个仓库）。绝不收集的内容：文件路径、源代码、仓库名称、用户身份或 IP 地址。完整的架构和禁用说明见 docs/TELEMETRY.md。

---

文档索引

• MEMORANDUM.md - 设计约定和不变量
• docs/LANGUAGE_SUPPORT.md - 语言实现详情
• docs/CONTRIBUTING_LANGUAGES.md - 语言贡献指南
• docs/INDEX_SCHEMA.md - 交互式索引架构
• docs/QUERY_PLANNER.md - 查询规划器评分
• docs/MCP_SETUP.md - MCP 服务设置和使用
• docs/MCP_WITH_CONTINUE.md - 5 分钟 Continue + BGI 操作指南
• docs/TELEMETRY.md - 选择加入遥测：收集内容及禁用方法
• https://bigindexer.com/validation - 公开验证证据
• docs/MCP_QUICKSTART_DEMO.md - 5 分钟演示操作指南
• docs/MCP_EXAMPLE_TRANSCRIPTS.md - 真实 MCP 工具调用示例
• docs/MCP_REAL_TRANSCRIPT.md - FastAPI 分析的未编辑记录
• scripts/mcp-demo.sh - 面向多个 CLI 和仓库的自动化演示脚本

许可证和版权

• 许可证：Apache License 2.0（LICENSE）
• 贡献者条款：在拉取请求中强制执行 Developer Certificate of Origin（DCO）

法律声明

Big Indexer 是 SUDO SOFTWARES LTD 的产品，该公司在英格兰和威尔士注册（公司编号 16976948）。 联系方式：[email protected] · https://bigindexer.com