ahmedxuhri/bigindexer

# BGI - Big Indexer [](https://glama.ai/mcp/servers/ahmedxuhri/bigindexer) [](https://pypi.org/project/bigindexer/) [](https://github.com/ahmedxuhri/bigindexer/blob/master/LICENSE) [](https://bigindexer.com/validation) [](https://bigindexer.com/demo) [](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.ahmedxuhri/bigindexer) [](https://github.com/ahmedxuhri/bigindexer-pr-risk-bot) 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 token + DRS 聚类）对单元进行分组，使得可能的组件边界清晰可见。 2. **“哪些子系统耦合存在风险？”** BGI 呈现了集群之间的高耦合接缝和融合边界信号，从而更容易发现集成风险。 3. **“我们如何将架构数据接入自动化流程？”** BGI 输出机器可读的产物（`bgi-graph.json`、`fuse-graph.json`）以及可选的人类上下文（`bigindexer.md`）。 4. **“我们如何让 AI 的修改不再那么随机？”** MCP 工具（`task_fingerprint`、`behavioral_twins`、`twin_context`）将 prompt 锚定在仓库内的行为模式上。 5. **“我能将其作为实例在 PR 上自动运行吗？”** 可以——使用专用的 action 仓库 [`ahmedxuhri/bigindexer-pr-risk-bot`](https://github.com/ahmedxuhri/bigindexer-pr-risk-bot)，自动在 PR 中评论影响范围、接缝和风险提示。 ## 30 秒演示 在内置的 fixture 仓库上运行 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 边界信号来表达——参见[外部基准测试](docs/VALIDATION_EVIDENCE.md#external-benchmark-vs-louvain) | | **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** - 对每个仓库的 token 频率进行分类。 2. **SPECTRAL-MASKS** - 根据 token 频率限制匹配范围。 3. **FUSE-MAP** - 限制集群增长并记录拒绝的合并。 4. **MASK-4-GATE-3** - 使用 import 邻近度作为聚类信号。 5. **WATER-CLOCK + `.scm`** - Gate 1 中的单遍查询提取路径。 ## BGI 与常见替代方案的区别 | 功能 | LSP / SCIP index | Call-graph + 通用社区发现 | BGI | |---|---|---|---| | 快速符号查找 | 强 | 中 | 可用（Phase 6 index） | | 行为 token 模型 | 否 | 通常否 | **是** | | 硬边界聚类 | 否 | 通常否 | **是**（单元级） | | 一级边界产物 | 否 | 通常否 | **是（`fuse-graph.json`）** | | 范围约束的边生成 | 有限 | 罕见 | **是（spectral masks）** | 外部正面基准测试（基于 BGI 边的 Louvain 对比基于原始 import 的 Louvain，根据包布局进行评分）：BGI 的边在 Python 上胜出（django F1 0.38 对比 0.29，MoJoFM 0.45 对比 0.34），目前由于在二层扫描器上跨文件边密度较低，在 Go 上表现为平局或落后。完整结果和方法论详见 [docs/VALIDATION_EVIDENCE.md](docs/VALIDATION_EVIDENCE.md#external-benchmark-vs-louvain)。 ## 证据（当前可验证） ### 大型仓库规模证据 可比的 kubernetes 样本（`go` 可比模式，162,917 个单元）： - Gate 1：`141.964s` - Gate 2：`67.261s`（历史可比基线：`138.869s`） - Gate 3：`9.359s` - 总计：`218.584s` - 最大集群：`1.113%` - Fuse events：`0` 产物：`output/validation/kubernetes-optionb-controlled-median-v21.json` ### 质量保障证据（超越原始速度） - Gate 2 范围安全测试会阻止无效的跨范围合并（参见 `tests/test_gate2.py`）。 - Gate 3 测试验证在没有 import 证据的情况下，不会发生遗留命名空间的过度合并（参见 `tests/test_gate3.py`）。 - 当前全套测试状态：`python3 -m pytest tests/ -x -q`（项目基线目标依然是通过）。 ### 证据总结 - 当前发布的验证集：跨 5 个仓库和 3 个模型的 **100 次评分运行**。 - BGI-TWIN 上下文（`task → COV → top-3 twins + seam + rubric`）完整的 20 次发布后基准测试刷新已完成：可操作性 **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` 遗漏。 - 仍缺失：外部语料库上标记的 precision/recall 基准测试，以及在相同标记数据集上与外部工具的正面定量基准测试。 ## 语言支持层级（明确说明） 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` 请将此作为可靠性信号：基于查询的层和专用扫描器层比通用回退更强。 **跨文件边密度注意事项：**上述语言层级描述的是解析器质量。另一个独立维度是*跨文件行为边密度*——即扫描器产生的、链接不同文件中单元的 key-lock 对的数量。第一层（基于 `.scm`）语言会产生密集的跨文件边。第二层扫描器支持的语言目前产生的跨文件边较为稀疏，因为它们的 token 组合由结构性 token（INTAKE/OUTPUT/CONDITIONAL/LOOP）主导，而 Gate-2 有意将其范围限制在同一文件内，以防止 O(N²) 噪声。用户可见的 MCP 产品（边界检测、孪生检索、AI 助手上下文）在二层语言上仍然有效——请参见验证证据——但针对 import-graph 基线的集群恢复基准测试反映了这一密度差距。具体数字详见 [docs/VALIDATION_EVIDENCE.md](docs/VALIDATION_EVIDENCE.md#external-benchmark-vs-louvain)。 ## 局限性与非目标 1. BGI 是**静态分析**；它不摄入运行时追踪数据。 2. 跨文件的语义解析是启发式的，且依赖于具体语言。 3. 目前已测量集群规模的健康状况；但尚未发布完整的外部 precision/recall。 4. 共享主机基准测试会引入方差；决策应使用受控的中位数结果。 ## 安装 ``` pip install -e . ``` ## 快速开始命令 ``` # scan bgi scan /path/to/repo --lang auto --out bgi-graph.json # 可选输出 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 # 在生成的 artifacts 上运行 MCP server bgi mcp --graph bgi-graph.json --fuse-graph fuse-graph.json ``` 示例 MCP 使用模式（来自您的客户端 prompt）： ``` 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 remote 的 12 字符哈希值（这样我们就能对“同一仓库被多次查看到”进行去重，而无需知道具体是哪个仓库）。绝不会收集的内容：文件路径、源代码、仓库名称、用户身份或 IP 地址。完整的 schema 和禁用说明详见 [`docs/TELEMETRY.md`](docs/TELEMETRY.md)。 ## 文档导航 - `MEMORANDUM.md` - 设计契约和不变式 - `docs/LANGUAGE_SUPPORT.md` - 语言实现细节 - `docs/CONTRIBUTING_LANGUAGES.md` - 语言贡献指南 - `docs/INDEX_SCHEMA.md` - 交互式 index schema - `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`） - 贡献者条款：在 pull request 上强制执行开发者原产地证书（`DCO`）

标签：MCP, Python, 代码重构, 无后门, 架构分析, 逆向工具, 错误基检测, 静态代码分析