代码知识图谱构建工具

地层

Stratum是由开源CodeAtlas引擎驱动的托管团队上下文网关。CodeAtlas构建任何存储库的实时代码知识图，并通过MCP、CLI、HTTP API和React web UI将其暴露给人工智能编码代理，如Claude code、Codex、Cursor和Copilot兼容的工作流。

The live web UI: an interactive knowledge graph of a 500-file codebase (11.6k symbols, 36k edges), PageRank-sized and community-colored.

太长，读不下去了 --提供AI编码代理的全栈产品 持久、可衡量 代码库上下文。Python/FastAPI+React，一个多租户托管的控制平面 GitHub应用程序（OAuth+签名的webhooks）、后台同步工作程序和仪表板 那 措施 检索是否真的很好，而不仅仅是一个图表。

堆叠深度： 使用可选交叉编码器的两阶段检索 重新银行化(基准化，7种模式）·安全扫描→ GitHub安全选项卡中的SARIF · CycloneDX SBOM+SLSA构建来源 关于释放· 普罗米修斯 /metrics + 格拉法纳 (可观测性) · 基于属性的测试+CI性能回归保护 代理上下文馈送 这显示了你的特工实际检索到的内容。

问题

AI编码代理在执行实际工作之前浪费了60-80%的上下文窗口，将自己定位在代码库中。Stratum为团队提供了持久的共享CodeAtlas上下文，因此代理可以从第一个令牌智能导航，团队可以衡量该上下文是否真的改善了结果。

为什么选择Stratum/CodeAtlas

• 持久SQLite+FTS5图 --缩放超过1M符号，增量更新；不是公寓 graph.json 每次运行都重新序列化。
• 基于真正嵌入的语义搜索 --FAISS+句子转换，而不仅仅是关键字匹配。混合模式通过互易秩融合来混合FTS5+矢量。
• PageRank中心性 --呼叫者加权重要性，而不是基于程度的“上帝节点”启发式方法。加上标签传播社区、git流失热点和覆盖缺口。
• 30个MCP工具，39个CLI命令，6种导出格式 --该类别中最宽的试剂和终端表面。
• 完整的React web用户界面 --交互式力图、搜索、符号详细信息、分析选项卡——所有这些都由FastAPI层支持。只需一个命令即可启动： codeatlas ui.
• 24种语言通过树保姆 --Python、Types/TSX、Go、Rust、JavaScript、Java、Kotlin、C、C++、C#、Ruby、PHP、Scala、Bash、Lua、Elixir、Swift、Haskell、SQL、Zig、OCaml、Julia、PowerShell、Svelte。
• 托管网关基础 --本地开发Stratum控制平面，包括用户、团队、承载令牌、每个仓库图DB、GitHub App元数据、webhook重放/同步和 /hosted 仪表板。

建筑

flowchart LR
  A[Git repo] --> B[tree-sitter parsers<br/>24 languages]
  B --> C[(SQLite graph<br/>FTS5 · symbols · edges)]
  C --> D[FAISS embeddings]
  C --> E[PageRank · communities]
  C --> F[MCP server<br/>30 tools]
  C --> G[HTTP API · FastAPI]
  G --> H[React UI<br/>graph · eval · savings]
  I[GitHub App<br/>OAuth + signed webhooks] --> J[Background sync worker<br/>clone → index]
  J --> C
  K[Control plane<br/>users · teams · scrypt tokens] --> G
  G --> L[Remote MCP / context<br/>rate-limited · audience-scoped]

工程决策（简称）

• 作为产品表面的测量检索。 Recall@k/MRR/nDCG如图所示 仪表板，而不是隐藏在CLI标志中——楔形与仅图表工具。
• scrypt用于令牌哈希 （stdlib，盐渍，内存硬）而不是 bcrypt/argon2--强，不添加本地控制盘。
• 进程内线程池同步工作器 代替Celery/Redis——webhooks 快速退货，通过以下方式消除重复交付 X-GitHub-Delivery，它是 大小适合单个VPS MVP。
• SQLite+每个仓库图数据库 而不是Postgres——简单的操作和自然 每回购隔离；这是在多节点规模上重新审视的已知权衡。
• 完整的原理、瓶颈和故障模式： docs/ai-infra-case study.md.

截图

仪表盘 --文件/符号/关系、语言和符号类型细分以及按PageRank排列的顶级符号都位于代理查询的同一图上。

Stratum网关(/hosted) -托管控制平面：per-repo上下文API， 测量的代理检索评估，之前/之后 上下文节省、新鲜度/同步状态和GitHub应用程序连接——所有这些都是针对每个仓库、每个团队的。

爆炸半径差 --在两个git引用之间添加/删除/修改的符号。此处更改为 verify_token 在演示中，monorepo级联到 create_invoice 和 admin_overview.

托管的仪表板显示了仅图表工具所不显示的内容： 测量检索 质量 （召回/MRR条）， 代币储蓄前后, 爆炸半径 影响，以及 数据血缘 --所有回购。

测量结果

CodeAtlas附带了可重复的AI基础基准测试，而不仅仅是一个功能列表：

• 旗舰证明报告： benchmarks/flagship-report.md 将检索质量、确定性代理结果A/B、规模/性能和数据沿袭证明联系在一起。
• 检索V2报告：30个确定性本地任务，上下文包最佳模式，1.000recall@k1000 MRR，外加precision@k, nDCG@k、有用的上下文密度、编辑本地化召回和故障类别。
• 代理结果报告： benchmarks/agent-live/report.md 运行一个明确标记的 mock_agent A/B基准测试，其中CodeAtlas上下文变量通过验证，而仅提示基线失败。
• 规模报告： benchmarks/perf/report.md 在提交的本地运行中，索引3个本地repos/fixture，其中包含481个文件、11077个符号、33036个关系和约4856个符号/秒。
• 数据沿袭报告： benchmarks/data-lineage/report.md 提取dbt+Airflow+SQL沿袭并导出OpenLineage形状的JSON。
• 最新提交的本地烟雾报告：154个文件，3371个符号，10837个关系，1.000个符号recall@k在Apple Silicon开发机器上，0.978 MRR，约27%的上下文节省，约978个符号/秒。
• 最新提交的OSS套件报告：3个固定存储库，314个文件，7581个符号，21443个关系，0.778个文件recall@k，0.476多符号recall@k，0.578 MRR，节省约60%的上下文。
• 提交的OSS运行有意将语义/混合标记为回退；发布语义比较 --build-semantic --require-semantic 因此，回退数字不能被误认为是矢量搜索结果。
• benchmarks/report.md 生成自 codeatlas bench . --profile --eval-suite benchmarks/eval-suite.json --output benchmarks/report.md.
• benchmarks/eval-suite.json 包含30个黄金检索任务，涉及符号查找、影响分析、依赖关系跟踪、架构问题、上下文包检索和SQL沿袭。
• benchmarks/oss-eval-suite.json 跨固定添加45个确定性真实回购任务 requests, click，以及 rich 承诺 benchmarks/repos.lock.yml.
• benchmarks/agent-suite.json 定义了可选的实时代理A/B任务，将仅提示的基线运行与CodeAtlas上下文包运行进行比较；CI使用 --dry-run 因此不需要付费LLM或网络克隆。
• codeatlas eval --compare 将FTS/BM25、语义、混合、PageRank、图邻域和上下文包排名路径与召回率、精度、nDCG、MRR、延迟、未命中率和令牌节省指标进行比较。
• codeatlas agent-eval --dry-run 写入确定性 results.json, report.md，以及 failures.json；添加 --agent-adapter shell|codex|claude|aider|mock plus live options运行一个明确标记的A/B基准。
• codeatlas perf-report, codeatlas data-lineage，以及 codeatlas doctor --check ... 添加生产风格规模、血统和环境证明。
• 主办MVP基金会： codeatlas hosted bootstrap, register-repo，以及 sync 使用承载令牌、回购元数据、同步事件、每个回购图DB和 /hosted 仪表板。
• GitHub应用同步基础： codeatlas hosted github status, refresh-repos, webhook-test，以及 sync 验证Stratum应用程序配置，从夹具/令牌源刷新安装存储库，记录交付ID，克隆托管签出，激活GitHub存储库，并在CI中没有实时GitHub凭据的情况下触发每个存储库的图同步。
• 托管安全和远程上下文：仓库范围 /remote-mcp 验证 X-Stratum-Audience，提供上下文包和图摘要，并包括提示注入/秘密/供应商路径扫描结果。
• codeatlas context <query> --mode fts|semantic|hybrid|pagerank --build-semantic --budget 2000 --json 返回包含定义、调用者、被调用者、文件摘要、置信度标签和预算调整的代理就绪上下文包。
• docs/ai-infra-case-study.md 解释架构、权衡、瓶颈、故障模式以及基准测试如何改变实现选择。
• docs/startup-roadmap.md 将商业楔形构建为代理基础设施：任何编码代理的持久团队上下文、评估、安全性和可观察性。
• docs/hosted-mvp.md 显示了本地托管网关流以及在真正的OAuth、计费和远程MCP路由之前故意删除的部分。

codeatlas hosted bootstrap --hosted-db .codeatlas/hosted.db
codeatlas hosted register-repo --hosted-db .codeatlas/hosted.db --team default --path . --name codeatlas
codeatlas hosted sync --hosted-db .codeatlas/hosted.db --repo codeatlas
codeatlas ui --db .codeatlas/graph.db --hosted-db .codeatlas/hosted.db
stratum hosted github status --hosted-db .codeatlas/hosted.db
codeatlas hosted github refresh-repos --hosted-db .codeatlas/hosted.db --installation <installation-id>
codeatlas bench . --profile --eval-suite benchmarks/eval-suite.json --output benchmarks/report.md
codeatlas bench . --profile --eval-suite benchmarks/eval-suite.json --json --output benchmarks/results.json
codeatlas bench-suite --repos benchmarks/repos.lock.yml --suite benchmarks/oss-eval-suite.json --out benchmarks/oss --build-semantic --require-semantic
codeatlas agent-eval --suite benchmarks/agent-suite.json --repos benchmarks/repos.lock.yml --out benchmarks/agent --dry-run
codeatlas eval --suite benchmarks/eval-suite.json --db .codeatlas/graph.db --out benchmarks/retrieval-v2 --compare
codeatlas perf-report --repos benchmarks/local-repos.json --out benchmarks/perf --profile
codeatlas agent-eval --suite benchmarks/local-agent-suite.json --repos benchmarks/local-repos.json --out benchmarks/agent-live --agent-adapter mock --compare-baseline
codeatlas data-lineage --repo examples/data-pipeline --format openlineage -o benchmarks/data-lineage/openlineage.json

特征

• 多语言解析 --24种语言的树型AST解析（如上所示）。
• 知识图谱 --SQLite+FTS5，具有递归CTE图遍历（零基础设施）。
• 语义搜索 --使用句子变换器进行自然语言代码查询的FAISS向量搜索。
• 混合搜索 --将关键字（FTS5）和向量（FAISS）结果进行交互排名融合。
• 图分析 --PageRank、社区检测、循环检测、死代码、热点、覆盖缺口、最短路径、文件耦合。
• 交互式可视化 --React+反应力图web UI，以及独立的D3.js HTML导出。
• HTTP/JSON API --FastAPI层位于图形之上，用于定制前端和工具。
• 实时同步 --监视器文件监视器和GitHub webhook处理程序，用于增量更新。
• 变更影响分析 --Git感知差异分析，显示哪些符号和文件受到影响。
• MCP服务器 --30个工具通过模型上下文协议公开，供AI代理使用。
• 图形导出 --DOT（Graphviz）、JSON（D3.js）、Mermaid、GraphML、CSV和Cypher格式。
• 配置文件 --可选 codeatlas.toml 用于每个repo设置。

快速开始

pip install codeatlas

# Initialize a config file (optional)
codeatlas init

# Index a repository
codeatlas index /path/to/repo

# View graph statistics
codeatlas stats

# Search by keyword
codeatlas query "authentication"

# Search by natural language (requires sentence-transformers)
codeatlas query "where do we handle login errors" --semantic

# Inspect a specific symbol
codeatlas show UserService

# Run code quality audit (cycles, dead code, complexity)
codeatlas audit

# Visualize the graph in your browser
codeatlas viz --open

# Watch for file changes
codeatlas watch /path/to/repo

# Export the graph
codeatlas export --format dot -o graph.dot
codeatlas export --format json -o graph.json
codeatlas export --format mermaid -o diagram.md

# Launch the web UI (API + React frontend, one command)
codeatlas ui

Web用户界面

CodeAtlas附带了基于Vite、Tailwind和反作用力图构建的React+TypeScript前端。它与同一图形存储上的FastAPI层进行通信，因此CLI、MCP服务器和web UI都看到了相同的数据。

# Build the frontend once
cd frontend && npm install && npm run build && cd ..

# Serve API + UI on localhost:8080
codeatlas ui

# Or run them separately during development
codeatlas server --port 8080              # API only
cd frontend && npm run dev                # Vite dev server with /api proxy

UI表面：

• 仪表盘 --按PageRank、文件热点、语言和符号细分、统计数据列出的顶级符号
• 搜索 --全文+语义搜索，结果详细信息窗格显示签名、文档字符串、传入/传出引用
• 分析 --标签式界面，具有PageRank排名、热点识别、社区检测、覆盖差距分析
• 图 --具有种类/社区着色、图例和文件过滤的交互式力量导向可视化
• 符号 --详细的符号页面，包括签名、文件、文件位置、进出参考卡
• 差异 --比较两个git引用之间的符号（添加/删除/修改的列）
• 设置 -配置API凭据，触发增量/完整重新索引，查看版本信息

安装

# Core (parsing + graph + CLI)
pip install codeatlas

# With MCP server
pip install codeatlas[mcp]

# With semantic search
pip install codeatlas[search]

# Everything
pip install codeatlas[all]

支持的语言

配置

CodeAtlas可以配置为 codeatlas.toml 存储库根目录中的文件。生成一个：

codeatlas init

示例 codeatlas.toml:

[codeatlas]
exclude_dirs = [".git", ".venv", "node_modules", "__pycache__", "dist", "build"]

[codeatlas.parser]
max_file_size_kb = 500
include_extensions = [".py", ".ts", ".tsx", ".js", ".mjs", ".go", ".rs", ".java", ".kt", ".kts", ".cpp", ".cc", ".cxx", ".hpp", ".hxx", ".h", ".cs", ".rb", ".php", ".scala", ".sc", ".sh", ".bash", ".lua", ".ex", ".exs", ".swift", ".hs", ".lhs", ".sql", ".c", ".zig", ".ml", ".mli"]

[codeatlas.graph]
db_path = ".codeatlas/graph.db"

如果找不到配置文件，则使用合理的默认值。

忽略包含以下内容的文件 .gitignore / .codeatlas-ignore

CodeAtlas自动尊重回购 .gitignore （如果存在）。添加一个 .codeatlas-ignore 当你需要额外的规则或否定时，在repo根目录中 gitignore条目；其模式在gitignore规则和 可以覆盖它们。

地点a .codeatlas-ignore 存储库根目录中的文件以排除特定 从索引中删除文件或目录。语法镜像 .gitignore:

# Skip generated artifacts
dist/
build/
*.log

# Skip a specific file (but re-include one via negation)
src/generated/
!src/generated/manifest.ts

支持：评论(#)、空白线条、球形图案(*, **, ?), 仅目录模式(foo/)，和否定(!pattern).

关系信心

图中的每条边都标记了置信度，以便代理可以分辨 AST证明了除启发式猜测之外的事实：

codeatlas report 表面计数；原始统计数据也可通过以下方式获得 GraphStore.get_confidence_stats()导出的JSON边带有相同的标签： codeatlas export --format json 发射 {"source", "target", "kind", "confidence"}, 交互式可视化绘制了推断出的虚边和模糊边 点状排列，因此启发式猜测一目了然。

社区观点

通过 --communities 到 codeatlas export 或 codeatlas viz 运行标签 在图上传播，并包括 community_id 在每个节点上。在 交互式可视化，节点由社区和工具栏切换绘制 在社区着色和善良着色之间切换。

CLI命令

MCP服务器

启动MCP服务器，以便与Claude Code、Cursor或任何与MCP兼容的代理一起使用：

codeatlas serve

Claude代码配置

添加到您的Claude Code MCP设置中：

{
  "mcpServers": {
    "codeatlas": {
      "command": "codeatlas",
      "args": ["serve"]
    }
  }
}

可用的MCP工具（30）

图形可视化

生成代码库的交互式力导向图：

# Generate and open in browser
codeatlas viz --open

# Save to a specific file
codeatlas viz -o my-graph.html

# Filter to specific directory
codeatlas viz --file-filter src/core/

可视化功能：

• 使用D3.js进行强制布局
• 按符号类型（类、函数、接口等）对节点进行颜色编码
• 悬停以突出显示符号的直接连接
• 按名称筛选符号的搜索栏
• 用鼠标缩放和平移
• 拖动节点以重新排列

GitHub Webhook

对于推送时的自动图形更新：

codeatlas webhook /path/to/repo --port 9000 --secret YOUR_WEBHOOK_SECRET

然后将您的GitHub repo webhook配置为POST到 http://your-server:9000/webhook.

建筑

Source Files --> Tree-sitter AST --> Symbols + Relationships --> SQLite Graph
                                                                    |
                                                 +--------+---------+--------+
                                                 |        |         |        |
                                              FTS5     FAISS     Graph    D3.js
                                             Search   Vectors   Analysis   Viz
                                                 |        |         |        |
                                                 +--------+---------+--------+
                                                              |
                                                   CLI + MCP Server --> AI Agents

设计决策：

• SQLite over Neo4j：零基础设施，Python附带，FTS5用于关键字搜索，递归CTE用于图遍历
• pgvector上的FAISS：在没有数据库服务器的情况下本地运行
• 正则表达式上的树保姆：增量解析，处理所有边缘情况，跨语言一致性

发展

# Clone and set up
git clone https://github.com/AryanSaini26/CodeAtlas.git
cd CodeAtlas
python3.12 -m venv .venv
.venv/bin/pip install -e ".[all,dev]"

# Run tests with coverage (latest local gate: 1,175 tests, 89.15% coverage)
.venv/bin/pytest -v --cov=codeatlas --cov-report=term-missing

# Lint / format
.venv/bin/ruff check src tests
.venv/bin/ruff format src tests

# Benchmarks and eval comparison
codeatlas bench . --profile --eval-suite benchmarks/eval-suite.json --output benchmarks/report.md

释放

发布是通过GitHub Actions完全自动化的。要剪切新版本，请执行以下操作：

# Bump version, tag, and push — CI builds, publishes to PyPI,
# and attaches a CycloneDX SBOM + SLSA build provenance to the release.
git tag v1.1.0 && git push --tags

要求：

1. 在PyPI.org上为此回购配置了PyPI可信发布（不需要API令牌）
2. GITHUB_TOKEN 是自动的，不需要额外的秘密

许可证

麻省理工学院