anismabaziz/saurix

# Saurix [](https://pypi.org/project/saurix/) [](https://pypi.org/project/saurix/) [](https://opensource.org/licenses/MIT) [](https://pypi.org/project/saurix/) Saurix 是一个交互式知识图谱引擎，可将复杂的代码库转化为可查询、可视化的 3D 地图。它旨在成为现代 AI 编码助手的**符号智能层**。 ## 为什么 AI 助手要选择 Saurix？ Saurix 通过提供优于关键字搜索的结构化代码表示，解决了 LLM 的“上下文窗口”问题： - **结构感知**：理解 `CALLS`、`INHERITS` 和 `IMPORTS` 关系，而不仅仅是原始文本。 - **上下文效率**：Agent 可以查询特定的子图，只接收它们所需的架构上下文，从而大幅减少 token 使用量。 - **爆炸半径分析**：内置的 `impact` 分析允许 Agent 在进行更改之前计算建议更改的传递副作用。 - **原生 MCP 支持**：基于 **Model Context Protocol** 构建，允许 AI Agent 将仓库图谱视为其自身记忆的扩展。 有关 AI Agent 如何使用这些功能的分步演练，请参阅 [docs/agent-lifecycle.md](docs/agent-lifecycle.md)。 ## 1) 核心使命 - **知识提取**：将本地或 GitHub 仓库转化为符号和关系的结构化图谱。 - **Agent 基础设施**：为自主 Agent 提供高级工具 (MCP) 以导航复杂的架构。 - **快速导航**：在几毫秒内回答有关依赖项、调用者和影响分析的问题。 - **模块化架构**：为跨语言和工具的可扩展性而构建。 ## 2) 架构 Saurix 遵循整洁的、领域驱动的模块化结构，专为扩展性和符号智能而设计。有关 Saurix 如何索引、存储和查询代码的详细分解，请参阅 [docs/architecture.md](docs/architecture.md)。 ## 设置与安装 1. **安装 Saurix**： pip install saurix 2. **初始化任意项目**： cd /path/to/your/project saurix init *此命令将为您的项目建立索引，一步创建本地 3D 仪表板（`saurix.html`）并生成您的 MCP 配置。* ### 运行 MCP 服务器 将图谱工具暴露给 AI Agent（例如 Claude Desktop、Cursor）： ``` saurix-mcp ``` ## 4) 交互式命令 | 命令 | 描述 | | ---------------- | ----------------------------------------------------- | | `init` | 当前项目的零配置安装 | | `index ` | 为本地路径或 GitHub URL 建立索引 | | `stats` | 显示图谱统计信息和提取覆盖率 | | `find ` | 按名称或 ID 模糊搜索符号 | | `callers ` | 列出调用目标的符号 | | `path ` | 查找两个符号之间的最短有向路径 | | `impact ` | 评估更改的爆炸半径 | | `visual` | 生成混合 2D/3D 知识图谱可视化 | | `export` | 导出为 GraphML 或 Neo4j CSV | ## 5) AI Agent 集成 (MCP) Saurix 针对基于 Agent 的工作流进行了优化。它提供的工具可帮助 Agent 理解： 1. **上下文发现**：`find_symbol` 和 `related_files`。 2. **行为映射**：`callers` 和 `path_between`。 3. **风险评估**：`impact_of_symbol`。 使用 `saurix-mcp` 入口点配置您的 Agent。配置完成后，AI 客户端（例如 Claude Desktop）将自动管理服务器的生命周期——在需要时在后台启动它，并在应用程序关闭时停止它。无需手动在终端中执行。 ## 6) 开发 ### 运行测试 ``` uv run pytest ``` ### 测试 MCP 服务器 您可以使用 **MCP Inspector** 测试 MCP 集成，而无需完整的 IDE： 1. **安装 Inspector**：`npm install -g @modelcontextprotocol/inspector` 2. **运行服务器**：`npx @modelcontextprotocol/inspector uv run saurix-mcp` 3. **交互**：打开 `http://localhost:5173`，点击 **Connect**，并使用 **Call Tool** 标签页。 有关分步设置（Claude Desktop、Cursor、OpenCode），只需在您的项目文件夹中运行 `saurix init` 即可。 _Saurix 为自主编码时代而生。_