2026年6月27日

Axon
给代码库建知识图谱，让 Coding Agent 真正"看懂"你的项目

714 Star 的 Python 工具，把代码库解析成知识图谱再通过 MCP 暴露给 AI Agent。从此 Agent 改代码前，先知道会炸哪里。

Axon

一句话说清楚

Axon 是一个代码智能引擎——它把你整个代码库解析成知识图谱，然后通过 MCP 协议暴露给 Claude Code、Cursor 这些 AI Agent。

你的 Agent 从此不再是"盲改代码"，而是改之前就知道：这个函数被谁调用了、改动会影响哪些模块、有没有死代码可以删。

它解决的真问题

用过 Claude Code 或 Codex 的人都有这个体验：Agent 改了一个函数的返回值，然后 CI 炸了。为什么？因为它根本不知道有 47 个地方依赖这个返回类型。

这不是 Agent 笨，是它天生的缺陷：

  • Agent 看的是"平文本" — 它 grep 一下找到直接调用者，但间接调用者、类型依赖、git 耦合关系全都看不到
  • 上下文窗口有限 — 即使 Agent 想读完整个项目，context window 也不够塞
  • LSP 帮不上忙 — LSP 提供补全和跳转，但不暴露调用图、影响范围、执行流
  • grep 给的是字符串，不是结构 — "找到所有 validate()" ≠ 知道哪些代码路径会经过 validate()

传统做法是人肉 review Agent 的 diff，但这不就回到了原点吗？

Axon 的解法：在索引阶段就把代码结构预计算好，Agent 每次 tool call 返回的都是完整、可操作的上下文。

12 阶段分析管线

Axon 的核心是一条 12 阶段的静态分析管线，跑一次就把代码库"透视"了：

阶段干什么
文件遍历按 .gitignore 规则扫描，识别支持的语言
结构提取构建文件/文件夹层级，建立 CONTAINS 关系
AST 解析tree-sitter 提取函数、类、方法、接口、枚举
Import 解析把 import 语句映射到实际文件（相对/绝对/裸模块）
调用追踪映射函数调用关系，带置信度分数，过滤 138 个语言内置函数
继承分析追踪 class 继承（EXTENDS）和接口实现（IMPLEMENTS）
类型分析提取参数、返回值、变量标注中的类型引用
社区检测Leiden 算法自动聚类，发现功能模块边界
执行流追踪框架感知的入口检测 + BFS 流程追踪
死代码检测多轮分析，理解装饰器、Protocol、override
变更耦合分析 6 个月 git 历史，找出总是同时改的文件
向量嵌入384 维向量，支持语义搜索（可跳过）

整个过程对大多数仓库 5 秒内完成，全本地运行，零云端依赖。

给 Agent 的 7 把武器

Axon 通过 MCP 暴露了 7 个工具，每个都直击 Agent 的痛点：

axon_query — 混合搜索

BM25 全文搜索 + 语义向量搜索 + 模糊匹配，三路融合。搜 "auth handler" 不是返回一堆文件名，而是按执行流分组的结果。Agent 一次调用就能理解"认证相关代码在哪里、怎么跑的"。

axon_context — 360° 全景

输入一个符号名，返回：谁调用了它、它调用了谁、类型引用关系、置信度标签、是不是死代码。相当于给 Agent 一张函数的"人际关系图"。

axon_impact — 爆炸半径

最实用的工具。准备改一个函数？它按深度分组告诉你影响范围：

  • Depth 1 — 直接调用者（改了必炸）
  • Depth 2 — 间接调用者（可能炸）
  • Depth 3+ — 传递影响（建议 review）

每条边都有置信度分数（1.0 精确匹配，0.8 接收者方法，0.5 模糊匹配），帮 Agent 排优先级。

axon_dead_code — 死代码扫描

不是简单的"零调用者"判断。它理解框架入口点、导出符号、构造器、dunder 方法、装饰器、Protocol 接口契约。不会把 __init__ 或 @app.route 标记为死代码。

axon_detect_changes — diff 到影响

输入一个 git diff，输出受影响的符号和执行流。PR review 时 Agent 可以自动知道"这次改动影响了哪些东西"。

axon_cypher — 图查询

直接写 Cypher 查询语句查知识图谱。高级用户可以做任意复杂的结构查询。

axon_list_repos — 仓库列表

查看所有已索引的仓库和统计信息。

不只是 CLI — 可视化 Dashboard

一行命令 axon ui 启动交互式 Web Dashboard（localhost:8420），三个视图：

  • Explorer — Sigma.js + WebGL 的力导向图，点击任意节点看代码、调用者、被调用者、影响范围、社区归属。社区外壳叠加显示架构聚类
  • Analysis — 健康评分、耦合热力图、死代码报告、继承树、分支 diff
  • Cypher Console — 带语法高亮的 Cypher 查询编辑器，支持预设查询和历史

还有命令面板（Cmd+K）、快捷键、流程追踪动画、图谱小地图。支持 --watch 模式实时更新。

三步上手

# 1. 安装
pip install axoniq
# 或者用 uv（推荐）
uv add axoniq

# 2. 索引你的项目
cd your-project
axon analyze .

# 3. 可视化探索
axon ui

接入 Coding Agent

Claude Code

在项目根目录的 .mcp.json 里加：

{
  "mcpServers": {
    "axon": {
      "command": "axon",
      "args": ["serve", "--watch"]
    }
  }
}

或者一行命令：claude mcp add axon -- axon serve --watch

Cursor

在 MCP settings 里加同样的配置。

共享模式

axon host --watch   # 启动共享主机：UI + 多 MCP 客户端

--watch 用 Rust 写的文件监听器（watchfiles），500ms 去抖。文件级阶段（解析、import、调用、类型）即时触发，全局阶段（社区、流程、死代码）每 30 秒批量更新。

为什么这个设计聪明

Axon 最聪明的地方在于：把重活放在索引阶段，让 tool call 变得极轻。

传统做法：Agent 改代码 → grep 找调用者 → 漏了 → CI 炸。Agent 的 10 次搜索可能还漏掉间接依赖。

Axon 做法：索引时预计算好所有关系 → Agent 一次 tool call 拿到完整影响范围 → 安全修改。

三个核心收益：

  • 可靠性 — 上下文已经在 tool response 里了，不会因为多步探索漏掉代码
  • Token 效率 — 一次 tool call 替代 10 次搜索链，Agent 把 token 花在推理而不是找路
  • 小模型也能用 — 工具做了重活，即使是弱模型也能获得完整的架构视野

和其他方案对比

能力grep/ripgrepLSP硬塞上下文Axon
可视化图谱❌❌❌✅ Web Dashboard
全文搜索✅❌✅✅ BM25+向量混合
调用图❌部分看运气✅ 带置信度
死代码检测❌❌❌✅ 多轮框架感知
执行流追踪❌❌❌✅ 入口→流
影响分析❌❌❌✅ 深度分组
MCP 集成❌部分N/A✅ 完整 MCP
离线运行✅✅❌✅

当前限制

  • 语言支持有限 — 目前只支持 Python、TypeScript、JavaScript。Go、Rust、Java 还没覆盖
  • 静态分析的固有局限 — 动态调用（eval、反射、动态 import）追踪不到
  • 大仓库吃内存 — 向量嵌入阶段内存占用跟符号数正相关，超大项目可能需要 --no-embeddings
  • 无 License — 仓库目前没有声明开源许可证，商用需注意

适用场景

  • Agent 驱动开发 — Claude Code / Cursor 改代码前自动查影响范围，减少"改一处炸一片"
  • 代码考古 — 接手老项目，用图谱快速理解架构，不用翻几百个文件
  • PR Review — Agent 用 detect_changes 自动标注影响范围，review 更有底气
  • 重构安全网 — 重构前先跑 impact analysis，知道所有可能被波及的代码
  • 新人 onboarding — axon ui 看图谱比翻目录快 10 倍

总结

Axon 解决的是 Coding Agent 的"盲区"问题——Agent 能写代码但不理解代码结构。通过预计算知识图谱 + MCP 暴露，它让 Agent 在做修改决策时有了完整的结构视野。

714 Star 不算多，但这个方向非常对。随着 AI Agent 越来越多地参与实际编码，"Agent 需要代码结构理解"会成为刚需。Axon 目前是这个赛道里最完整的开源方案。

项目地址：github.com/harshkedia177/axon

PyPI：pypi.org/project/axoniq