axon (Harshkedia177)

轴突

](https://pypi.org/project/axoniq/) ](https://pepy.tech/projects/axoniq)  ](https://github.com/harshkedia177/axon) 

代码库的知识图——直观地探索它，或者让你的AI代理查询它。

将任何代码库索引到结构化知识图中——每个依赖关系、调用链、集群和执行流。通过一个 交互式web仪表板 使用力导向图可视化，或通过 MCP工具 因此，AI代理在每次工具调用中都能充分理解结构。

$ axon analyze .

Walking files...               142 files found
Parsing code...                142/142
Tracing calls...               847 calls resolved
Analyzing types...             234 type relationships
Detecting communities...       8 clusters found
Detecting execution flows...   34 processes found
Finding dead code...           12 unreachable symbols
Analyzing git history...       18 coupled file pairs
Generating embeddings...       623 vectors stored

Done in 4.2s — 623 symbols, 1,847 edges, 8 clusters, 34 flows

然后直观地探索你的代码库：

axon ui                      # Opens interactive dashboard at localhost:8420

三个视图，一个命令：

• 探索者 --交互式力导向图（Sigma.js+WebGL）。单击任何节点以查看其代码、调用者、被调用者、影响半径和社区。社区船体覆盖图一目了然地显示了建筑集群。
• 分析 --健康评分、耦合热图、死代码报告、继承树、分支差异——你的代码库健康在一个仪表板上。
• 密码控制台 --使用语法高亮显示、预设和历史记录对图形编写并运行Cypher查询。

加：命令面板(Cmd+K)、键盘快捷键、流跟踪动画、图形小地图和监视模式激活时由SSE驱动的实时重新加载。

______________________________________________________________________

问题

您的AI代理编辑 UserService.validate()它不知道47个函数依赖于该返回类型，3个执行流通过它，以及 payment_handler.py 80%的时间都在变化。

打破改变船。

这是因为AI代理使用平面文本。他们为调用者提供帮助，忽略间接调用者，并且不了解代码是如何编写的 *连接的*上下文窗口是有限的。LSP不公开调用图。滑鼠给你的是绳索，而不是结构。

代理人需要 知识图谱 --没有更多的文本。

______________________________________________________________________

Axon如何解决这个问题

大多数代码智能工具都会给代理提供原始文件，并希望它读得足够多。Axon采取了不同的方法： 索引时的预计算结构 因此，每次工具调用都会返回完整的、可操作的上下文。

一个12阶段的管道在你的仓库上运行一次。之后：

• axon_impact("validate") 在一次调用中返回所有47个受影响的符号，按深度分组（将中断/可能中断/回顾），并带有置信度得分
• axon_query("auth handler") 返回按执行流分组的混合排名结果，而不是名称匹配的简单列表
• axon_context("UserService") 返回调用者、被调用者、类型引用、社区成员资格和死代码状态——全貌

三个好处：

1. 可靠性 --上下文已经在工具响应中。没有可能遗漏代码的多步骤探索。
2. 代币效率 --一个工具调用，而不是10个查询搜索链。代理将令牌用于推理，而不是导航。
3. 民主化模式 --即使是较小的模型也能获得完全的架构清晰度，因为工具可以完成繁重的工作。

零云依赖。 一切都在本地运行——解析、图存储、嵌入、搜索。没有API密钥，没有数据离开您的机器。

______________________________________________________________________

太长，读不下去了

pip install axoniq            # 1. Install
cd your-project && axon analyze .  # 2. Index (one command, ~5s for most repos)
axon ui                       # 3. Explore visually at localhost:8420

对于AI代理 --添加到 .mcp.json 在项目根目录中：

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

对于开发者 --亲自探索图表：

axon ui                      # Interactive dashboard (standalone or attaches to running host)
axon ui --watch              # Live reload on file changes
axon host --watch            # Shared host: UI + multi-session MCP

______________________________________________________________________

所得

直观地探索您的代码库

Web用户界面

一个完整的交互式仪表板——不需要终端或扩展。一个命令：

axon ui                           # Launch at localhost:8420
axon ui --watch                   # Live reload on file changes
axon ui --port 9000               # Custom port
axon ui --dev                     # Dev mode (Vite HMR on :5173)

附加： 命令面板(Cmd+K)、键盘快捷键、图形小地图、流动轨迹和冲击波纹动画、启用观察模式时由SSE驱动的实时重新加载。

UI由带有完整REST API的FastAPI服务器支持-请参阅 API终点 在......下面

查找任何内容——按名称、概念或拼写错误

混合搜索（BM25+矢量+模糊）

融合了三种搜索策略 Reciprocal Rank Fusion：RRF（相互排名融合）:

• BM25全文搜索 --通过KuzuDB FTS快速精确匹配名称和关键字
• 语义向量搜索 --通过384个dim嵌入进行概念查询（BAAI/bge-small-en-v1.5）
• 模糊名称搜索 --Levenshtein回退拼写错误和部分匹配

结果按照测试文件降序（0.5倍）和源函数/类提升（1.2倍）进行排名，然后 按执行流分组 因此，代理可以在单个调用中看到架构上下文。

在改变之前，先知道什么会坏

深度分组影响分析

当你要更改一个符号时，Axon会通过调用图、类型引用和git耦合历史向上游跟踪。结果按可操作性的深度分组：

• 深度1 --直接来电者（将中断）
• 深度2 --间接呼叫者（可能中断）
• 深度3+ --传递性（回顾）

每个边缘都有一个置信度得分（1.0=精确匹配，0.8=接收者方法，0.5=模糊），这样你就可以优先考虑要审查的内容。

查找要删除的内容

死码检测

不仅仅是“零调用者”——一种理解你的框架的多通道分析：

1. 初始扫描 --标记没有来电的符号
2. 豁免 --入口点、导出、构造函数、测试代码、dunder方法， __init__.py 符号、装饰功能， @property 方法
3. 超控通行证 --联合国标志覆盖非死基类方法的方法
4. 协议一致性 --在符合协议的类上取消标记方法
5. 协议存根 --取消标记Protocol类（接口契约）上的所有方法

了解代码的运行方式，而不仅仅是它的位置

执行流跟踪

使用框架感知模式检测入口点：

• python: @app.route, @router.get, @click.command, test_* 功能， __main__ 块
• JavaScript/TypeScript：Express处理程序、导出函数、， handler/middleware 模式

然后通过调用图跟踪每个入口点的BFS执行流，将流分为社区内或跨社区。

无需阅读文档即可查看您的架构

社区发现

使用 莱顿算法 （igraph+leidenalg）自动发现功能簇。每个社区都会得到一个凝聚力得分和自动生成的标签。代理可以问“这个符号属于哪个集群？”并在不阅读任何设计文档的情况下得到答案。

查找git知道的隐藏依赖项

更改耦合（Git历史记录）

分析6个月的git历史，找出静态分析遗漏的依赖关系：

coupling(A, B) = co_changes(A, B) / max(changes(A), changes(B))

耦合强度>=0.3和3+共同更改的文件将被链接。这些会出现在影响分析中——所以当你改变 user.py，代理人也知道要检查 user_test.py 和 auth_middleware.py.

始终保持最新

观看模式

基于Rust的文件观察器（观察文件）支持的实时重新索引：

$ axon watch
Watching /Users/you/project for changes...

[10:32:15] src/auth/validate.py modified -> re-indexed (0.3s)
[10:33:02] 2 files modified -> re-indexed (0.5s)

文件本地阶段（解析、导入、调用、类型）在发生更改时立即运行。全局阶段（社区、流程、死代码）每30秒批处理一次。

结构差异，而非文本差异

分支比较

使用git工作树在符号级别比较分支（无需隐藏）：

$ axon diff main..feature

Symbols added (4):
  + process_payment (Function) -- src/payments/stripe.py
  + PaymentIntent (Class) -- src/payments/models.py

Symbols modified (2):
  ~ checkout_handler (Function) -- src/routes/checkout.py

Symbols removed (1):
  - old_charge (Function) -- src/payments/legacy.py

清晰的调用图

噪声滤波

内置块列表（138个条目）自动过滤语言内置(print, len, isinstance)，JS/TS全局变量(console, setTimeout, fetch)，React挂钩(useState, useEffect)，以及调用图中的常见stdlib方法。您的图表显示 *你的* 代码的关系，而不是来自 list.append().

______________________________________________________________________

管道

Axon通过12个连续的分析阶段建立了对结构的深入理解：

______________________________________________________________________

MCP集成

Axon公开了其作为MCP服务器的全部智能。只需设置一次，你的AI代理就可以永远对你的代码库有结构上的理解。

设置

克劳德代码 --添加到 .mcp.json 在项目根目录中（或运行 claude mcp add axon -- axon serve --watch):

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

光标 --添加到MCP设置中：

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

可选新功能：

axon host --watch

这将为UI和多个MCP客户端启动一个共享主机。 axon setup --claude / axon setup --cursor 仍然打印标准配置。

这 --watch 标志允许实时重新索引——图形会在您编辑代码时更新。

工具

每个工具响应都包括 下一步提示 引导代理人完成自然调查工作流程：

query   -> "Next: Use context() on a specific symbol for the full picture."
context -> "Next: Use impact() if planning changes to this symbol."
impact  -> "Tip: Review each affected symbol before making changes."

资源

______________________________________________________________________

API终点

web UI由FastAPI服务器支持。所有端点都在 /api:

Cypher查询在服务器端经过验证——写入关键字(CREATE, DELETE, DROP等）在删除评论后被拒绝。

______________________________________________________________________

如何比较

______________________________________________________________________

支持的语言

______________________________________________________________________

安装

# With pip
pip install axoniq

# With uv (recommended)
uv add axoniq

# With Neo4j backend support
pip install axoniq[neo4j]

需要 Python 3.11+。包含web UI（前端+后端），无需Node.js或额外安装。

源自源头

git clone https://github.com/harshkedia177/axon.git
cd axon
uv sync --all-extras
uv run axon --help

要在更改后重建前端（需要Node.js 18+）：

cd src/axon/web/frontend
npm install && npm run build

______________________________________________________________________

CLI参考

axon analyze [PATH]          Index a repository (default: current directory)
    --full                   Force full rebuild (skip incremental)
    --no-embeddings          Skip vector embedding generation (faster indexing)

axon status                  Show index status for current repo
axon list                    List all indexed repositories (auto-populated on analyze)
axon clean                   Delete index for current repo
    --force / -f             Skip confirmation prompt

axon query QUERY             Hybrid search the knowledge graph
    --limit / -n N           Max results (default: 20)

axon context SYMBOL          360-degree view of a symbol
axon impact SYMBOL           Blast radius analysis
    --depth / -d N           BFS traversal depth (default: 3)

axon dead-code               List all detected dead code
axon cypher QUERY            Execute a raw Cypher query (read-only)

axon watch                   Watch mode — live re-indexing on file changes
axon diff BASE..HEAD         Structural branch comparison

axon host                    Shared host for UI + HTTP MCP (default: localhost:8420)
    --port / -p PORT         Port to serve on (default: 8420)
    --watch / --no-watch     Enable live file watching
    --dev                    Dev mode — proxy to Vite dev server for HMR
    --no-open                Don't auto-open browser

axon ui                      Launch the web UI (default: localhost:8420)
    --port / -p PORT         Port to serve on (default: 8420)
    --watch / -w             Enable live file watching with auto-reindex
    --dev                    Dev mode — proxy to Vite dev server for HMR
    --no-open                Don't auto-open browser
    --direct                 Force standalone mode even if a shared host exists

axon setup                   Print MCP configuration JSON
    --claude                 For Claude Code
    --cursor                 For Cursor

axon mcp                     Start the MCP server (stdio transport)
axon serve                   Start the MCP server
    --watch, -w              Enable live file watching with auto-reindex
axon --version               Print version

______________________________________________________________________

示例工作流

“我需要重构User类——什么会中断？”

# See everything connected to User
axon context User

# Check blast radius — grouped by depth
axon impact User --depth 3

# Find files that always change with user.py
axon cypher "MATCH (a:File)-[r:CodeRelation]->(b:File) WHERE a.name = 'user.py' AND r.rel_type = 'coupled_with' RETURN b.name, r.strength ORDER BY r.strength DESC"

“我们应该清理死代码吗？”

axon dead-code

“主要执行流程是什么？”

axon cypher "MATCH (p:Process) RETURN p.name, p.properties ORDER BY p.name"

“代码库的哪些部分耦合最紧密？”

axon cypher "MATCH (a:File)-[r:CodeRelation]->(b:File) WHERE r.rel_type = 'coupled_with' RETURN a.name, b.name, r.strength ORDER BY r.strength DESC LIMIT 20"

______________________________________________________________________

知识图谱模型

节点

关系

节点ID格式

{label}:{relative_path}:{symbol_name}

Examples:
  function:src/auth/validate.py:validate_user
  class:src/models/user.py:User
  method:src/models/user.py:User.save

______________________________________________________________________

建筑

Source Code (.py, .ts, .js, .tsx, .jsx)
    |
    v
+----------------------------------------------+
|         Ingestion Pipeline (12 phases)        |
|                                               |
|  walk -> structure -> parse -> imports        |
|  -> calls -> heritage -> types                |
|  -> communities -> processes -> dead_code     |
|  -> coupling -> embeddings                    |
+----------------------+-----------------------+
                       |
                       v
              +-----------------+
              | KnowledgeGraph  |  (in-memory during build)
              +--------+--------+
                       |
          +------------+------------+
          v            v            v
     +---------+ +---------+ +---------+
     | KuzuDB  | |  FTS    | | Vector  |
     | (graph) | | (BM25)  | | (HNSW)  |
     +----+----+ +----+----+ +----+----+
          +------------+------------+
                       |
              StorageBackend Protocol
                       |
           +-----------+-----------+
           v           v           v
     +----------+ +----------+ +----------+
     |   MCP    | |  Web UI  | |   CLI    |
     |  Server  | | (FastAPI | | (Typer)  |
     | (stdio)  | |  + React)| |          |
     +----+-----+ +----+-----+ +----+-----+
          |             |            |
     Claude Code    Browser      Terminal
     / Cursor      (developer)  (developer)

技术栈

存储

一切都生活在当地：

your-project/
+-- .axon/
    +-- kuzu/          # KuzuDB graph database (graph + FTS + vectors)
    +-- meta.json      # Index metadata and stats

添加 .axon/ 到你的 .gitignore.

全球注册处 ~/.axon/repos/ 自动填充 axon analyze，使 axon list 发现您机器上的所有索引存储库。

存储层被抽象为 StorageBackend 协议——默认为KuzuDB，可选Neo4j后端可通过 pip install axoniq[neo4j].

______________________________________________________________________

发展

git clone https://github.com/harshkedia177/axon.git
cd axon
uv sync --all-extras

# Run tests
uv run pytest

# Lint
uv run ruff check src/

# Run from source
uv run axon --help

# Frontend development (React + Vite with HMR)
cd src/axon/web/frontend
npm install
npm run dev                  # Vite dev server on :5173
# In another terminal:
uv run axon ui --dev         # Backend on :8420, proxies to Vite

______________________________________________________________________

许可证

麻省理工学院

______________________________________________________________________

建造于 @哈斯克迪亚177