sohilladhani/codesynapse

AI 编程工具能很好地回答关于单个文件的问题。但它们无法对*架构*进行推理 —— 类层次结构、调用链、变更的影响范围，以及哪个模块负责哪个概念。`grep` 和文件搜索返回的是噪音，而不是有效信号。 Codesynapse 解决了这个问题。它从你的源代码构建结构化知识图谱（节点 = 类、函数、文件；边 = 调用、继承、实现、包含），将多个模块的图谱合并为一个全局图谱，并公开了由混合 BM25 + 稠密向量搜索支持的 **32 个 MCP 工具**。使用 Claude Code 或 Cursor 的每次会话都从完整的图谱上下文开始 —— 不再是一张白纸。 完全在本地运行。无需 GPU，无需云 API，无需额外基础设施。 ## 演示 ## 为什么选择 codesynapse？ | | Python graphify | graphify-rs | semble | code-review-graph | codegraph | cbm | Sourcegraph Cody | continue.dev | **codesynapse** | |---|---|---|---|---|---|---|---|---|---| | **语言** | Python | Rust | Python | Python | TypeScript | C | Cloud | VS Code ext. | **Rust** | | **MCP 工具** | ✗ | ✗ | 2 | 30 | 10 | ~8 | ✗ | ✗ | **32** | | **结构化图谱** | 部分 | 通用 KG | ✗ | ✓ | ✓ | ✓ | ✓ | ✗ | **✓** | | **影响范围** | ✗ | ✗ | ✗ | ✓ | ✓ | ✗ | ✓ | ✗ | **✓** | | **混合 BM25 + 稠密** | ✗ | 仅 BM25 | ✓ | 可选 | ✗ (FTS5) | ✗ | ✓ | ✗ | **✓** | | **完全本地** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | **✓** | | **无需云 API** | ✓ | ✓ | ✓ | ✗ (语义) | ✓ | ✓ | ✗ | ✗ | **✓** | | **多模块图谱** | ✗ | ✗ | ✗ | ✓ | ✓ | ✗ | ✓ | ✗ | **✓** | | **跨模块层次结构** | ✗ | ✗ | ✗ | ✗ | ✓ | ✗ | ✓ | ✗ | **✓** | | **消除文件读取** | — | — | — | — | 100% | 部分 | — | — | **100%** | | **默认无遥测** | ✓ | ✓ | ✓ | ✓ | ✗ (可选择退出) | ✓ | ✗ | ✗ | **✓ (可选择加入)** | | **运行时** | Python | Rust | Python | Python | Node.js | C 二进制 | Cloud | Node.js | **Rust 二进制** | **[codegraph](https://github.com/Tgedin/codegraph)** 是最接近的替代方案 —— TypeScript，本地运行，10 个 MCP 工具，支持影响范围，多模块。主要差距在于：仅支持词法 FTS5 搜索（无稠密嵌入），因此同义词和概念查询会漏掉 BM25+dense RRF 能捕捉到的结果。**[cbm (codebase-memory-mcp)](https://github.com/DeusData/codebase-memory-mcp)** 是一个带有 SQLite 图存储的 C 二进制程序 —— 冷启动索引快（无需嵌入过程），但没有混合搜索，且每次查询需要多次读取文件（观察到为 8–10 次，而 codesynapse 为 0 次）。**semble** 使用相同的 Model2Vec + BM25 + RRF 搜索技术栈，但仅支持搜索 —— 没有结构化图谱，没有影响范围，没有层次结构。**code-review-graph** 具有图谱 + MCP，但它是 Python 编写的，并且需要云 API 才能进行语义搜索。**graphify-rs** 是原始 Python graphify 工具的 Rust 重写版 —— 通用知识图谱，非原生 MCP 或专注于代码智能。 Codesynapse 是 [Python graphify](https://github.com/safishamsi/graphify) 的 Rust 重写版，具有完整的 MCP 集成、结构化图谱分析且零云依赖。 ## 基准测试 在真实的开源代码库（redis、tokio、django-framework）上测量。Docker 环境，`--cpus=4 --memory=8g`，3 次运行的中位数。完整的方法论和各问题得分：[BENCHMARKS.md](BENCHMARKS.md)。 竞争对手：[codegraph](https://github.com/Tgedin/codegraph)（TypeScript, SQLite FTS5），[cbm/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)（C, SQLite 图存储, 无嵌入）。 **索引速度** —— 冷启动索引时间： | 代码库 | codesynapse | codegraph | cbm | |------|-------------|-----------|-----| | redis (C, ~700 文件) | **3.8s** | 60.8s | 5.9s | | tokio (Rust, ~900 文件) | **4.6s** | 36.8s | 2.0s | | django-framework (Python, ~2k 文件) | **17.5s** | 306s | 12.4s | codesynapse 的索引速度**比 codegraph 快 8–17 倍**。cbm 在索引方面比 codesynapse 快，因为它跳过了嵌入过程 —— 但这意味着每次查询都需要多次读取文件（观察到为 8–10 次），而 codesynapse 查询返回零文件读取。 **查询准确率**（Claude 评分，0–10 分制，针对答案符号名称未出现在问题中的问题 —— 例如“什么处理访问控制？” → `IsAuthenticated`）： | | codesynapse | codegraph | cbm | baseline | |---|---|---|---|---| | 平均分 | **8.9** | 9.0 | 8.7 | 8.6 | | 每次查询文件读取次数 | **0** | 0 | 8–10 | — | 各工具之间的得分具有可比性。codesynapse 的优势在于运营：零文件读取意味着每次会话的 token 成本更低，并且在大型代码库中不会出现上下文膨胀。codegraph 的纯词法搜索（SQLite FTS5）在同义词查询上应该会遇到困难，但 Claude 通过后续的工具调用进行了弥补 —— 因此两者通过不同的路径达到了相似的分数。 ## 工作原理 ``` flowchart TD A[("Source code\n(any repo)")] -->|parallel tree-sitter AST\n30+ languages| B["per-module graph.json"] B -->|global_add — prefix node IDs, merge| C[("global-graph.json\n~/.codesynapse/")] C -->|embed_global_graph\npotion-code-16M · CPU-only · mtime-gated| D[("embeddings.json\n~/.codesynapse/")] C & D --> E[["MCP server\n32 tools · hybrid BM25 + dense RRF"]] E --> F["Claude Code · Cursor · OpenCode\nCodex CLI · Hermes · Kiro · any MCP client"] style A fill:#f6f8fa,stroke:#57606a,color:#24292f style B fill:#ddf4ff,stroke:#54aeff,color:#0550ae style C fill:#dafbe1,stroke:#4ac26b,color:#1a7f37 style D fill:#fff8c5,stroke:#d4a72c,color:#4d2d00 style E fill:#ede9fe,stroke:#8957e5,color:#512a97 style F fill:#ffeef8,stroke:#bf3989,color:#6e1e5c ``` **关键设计选择：** | 决策 | 原因 | |---|---| | 混合 BM25 + 稠密 RRF | BM25 精确处理符号名称；稠密向量弥补了同义词的差距。RRF 融合了两者的优点。 | | Model2Vec `potion-code-16M` | 静态嵌入 —— 查询时无前向传播，约 1.5ms 查询速度，纯 CPU 运行，模型仅 64 MB。 | | Sled 嵌入式数据库 | 零依赖，基于文件，按节点 ID 快速随机访问。无需服务器进程。 | | Tree-sitter AST 提取 | 覆盖 30 多种语言的语法。无需语言服务器或构建系统。 | | 单模块 → 全局合并 | 支持跨模块的影响范围和层次结构，而无需将所有模块加载到内存中。 | | 基于 Mtime 限制的嵌入重建 | 仅当 `global-graph.json` 较新时才重新生成嵌入。对于未更改的图谱零开销。 | ## 语言支持 | 分组 | 语言 | |---|---| | **系统级** | Rust, C, C++, Go, Zig, Fortran, Verilog | | **JVM** | Java, Kotlin, Scala, Groovy | | **Web / 前端** | JavaScript, TypeScript, Svelte, Vue, PHP | | **脚本** | Python, Ruby, Lua, Bash, PowerShell | | **移动 / Apple** | Swift, Objective-C, Dart | | **函数式** | Haskell, Elixir, Racket, Julia | | **其他** | SQL, C#, CMake, Pascal | ## 安装 **前置条件：** - 约 500 MB 可用磁盘空间（图存储 + 模型，在首次 `setup` 时下载） - 首次运行需要互联网连接（仅用于模型下载） **选项 A —— 单行命令** Linux / macOS: ``` curl -fsSL https://raw.githubusercontent.com/sohilladhani/codesynapse/master/install.sh | sh ``` Windows (PowerShell): ``` irm https://raw.githubusercontent.com/sohilladhani/codesynapse/master/install.ps1 | iex ``` 或者从 [发布页](https://github.com/sohilladhani/codesynapse/releases/latest) 下载特定的二进制文件： | 平台 | 二进制文件 | |---|---| | Linux x86_64 | `codesynapse-linux-x86_64` | | macOS Apple Silicon | `codesynapse-macos-aarch64` | | Windows x86_64 | `codesynapse-windows-x86_64.exe` | ``` chmod +x codesynapse-* sudo mv codesynapse-* /usr/local/bin/codesynapse ``` **选项 B —— 包管理器** macOS (Homebrew): ``` brew tap sohilladhani/codesynapse brew install codesynapse ``` Windows (Scoop): ``` scoop bucket add cs https://github.com/sohilladhani/scoop-codesynapse scoop install codesynapse ``` Nix: ``` nix run github:sohilladhani/codesynapse # run directly nix profile install github:sohilladhani/codesynapse # install permanently ``` 或者添加到你的 flake： ``` inputs.codesynapse.url = "github:sohilladhani/codesynapse"; # 然后：inputs.codesynapse.packages.${system}.default ``` **选项 C —— 从源码构建** 需要 Rust 稳定版工具链（[安装](https://rustup.rs)）： ``` cargo install codesynapse-cli ``` ## 快速开始 ``` # 1. 向 Claude Code 和/或 Cursor 注册 MCP server（自动检测两者） codesynapse setup # 其他客户端（如果未自动检测到）： codesynapse opencode install # OpenCode codesynapse codex install # Codex CLI codesynapse hermes install # Hermes Agent codesynapse kiro install # Kiro # 2. 索引一个 repository codesynapse module add myrepo /path/to/your/repo # 3. 重启你的 AI 客户端 # 4. 提出架构问题——这 32 个 MCP tools 现在已可用 ``` 就是这样。从这一点开始，诸如*“什么处理身份验证令牌过期？”*或*“显示 UserService 的影响范围”*之类的查询将直接从图谱中获取答案 —— 而不是通过文件搜索。 **添加更多仓库：** ``` codesynapse module add backend /path/to/backend codesynapse module add frontend /path/to/frontend # Graph 会进行合并——跨 module 查询将自动生效 ``` **代码更改后刷新：** ``` codesynapse module refresh myrepo ``` **列出已索引模块：** ``` codesynapse module list ``` **移除模块：** ``` codesynapse module remove myrepo # 从 global graph 中清理其 nodes 并将其注销 ``` **使用 git 保持图谱最新（可选）：** ``` codesynapse hook install # installs a post-merge git hook — auto-refreshes on pull ``` ## MCP 工具 涵盖六个类别的 32 个工具，可从 Claude Code、Cursor 或任何兼容 MCP 的客户端调用。 | 类别 | 工具 | |---|---| | **图谱搜索** | `codesynapse_query_vector`, `codesynapse_query_semantic`, `codesynapse_blast_radius`, `codesynapse_blast_radius_scored`, `codesynapse_blast_radius_multi`, `codesynapse_hierarchy`, `codesynapse_list_graphs`, `codesynapse_module_summary`, `codesynapse_build` | | **代码阅读** | `codesynapse_resolve`, `codesynapse_outline`, `codesynapse_read`, `codesynapse_read_method`, `codesynapse_read_with_callees` | | **导航** | `codesynapse_find_callers`, `codesynapse_find_usages` | | **图谱分析** | `codesynapse_query_graph`, `codesynapse_get_node`, `codesynapse_get_neighbors`, `codesynapse_get_community`, `codesynapse_god_nodes`, `codesynapse_graph_stats`, `codesynapse_shortest_path`, `codesynapse_find_all_paths`, `codesynapse_weighted_path`, `codesynapse_community_bridges`, `codesynapse_diff`, `codesynapse_pagerank`, `codesynapse_detect_cycles`, `codesynapse_smart_summary`, `codesynapse_find_similar` | | **可观测性** | `codesynapse_stats` | 完整的参数说明和示例：[docs/MCP-TOOLS.md](docs/MCP-TOOLS.md) **在 Claude Code 中的常见查询：** ``` "What handles auth token expiry?" → codesynapse_query_vector "Show blast radius of UserService" → codesynapse_blast_radius "What does UserRepository extend?" → codesynapse_hierarchy "Read the validate() method" → codesynapse_read_method "Who calls PaymentService.charge()?" → codesynapse_find_callers ``` ## 配置 将 `codesynapse.toml` 放在你的项目根目录下。所有字段均为可选。 ``` # 导出 graph 的输出目录（默认：codesynapse-out/） output = "codesynapse-out" # 跳过对 doc/paper 文件的 LLM 提取（默认：false） no_llm = false # 仅索引 source code，跳过 docs 和 papers（默认：false） code_only = false # 导出格式："json"、"html"、"graphml"、"obsidian" formats = ["json", "html"] # 用于 docs/papers 语义提取的 LLM config（可选） [llm] provider = "anthropic" # "anthropic" | "openai" | any OpenAI-compatible model = "claude-sonnet-4-20250514" api_key = "sk-..." # or set ANTHROPIC_API_KEY / OPENAI_API_KEY env var base_url = "https://..." # optional, for OpenAI-compatible providers # 自定义 model 路径（默认：由 codesynapse setup 自动解析） [embeddings] model_path = "./models/potion-code-16M" ``` ## 仓库布局 ``` codesynapse/ ├── codesynapse-core/ # Extraction, graph, embedding, global graph ├── codesynapse-cli/ # CLI binary (module add/refresh/list, build, setup) ├── codesynapse-mcp/ # MCP server — 32 tools, JSON-RPC over stdio ├── codesynapse-serve/ # BM25 + dense hybrid search engine ├── codesynapse-tui/ # Terminal UI ├── codesynapse-grpc/ # gRPC server ├── codesynapse-graphql/ # GraphQL API ├── codesynapse-wasm/ # WebAssembly bindings ├── models/ │ └── potion-code-16M/ # Static embedding model (downloaded by setup) ├── tests/ # Integration tests └── docs/ ├── ARCHITECTURE.md └── MCP-TOOLS.md ``` 运行时数据位于 `~/.codesynapse/`： ``` ~/.codesynapse/ ├── global-graph.json # Merged graph (all modules) ├── embeddings.json # node_id → Vec dense embeddings ├── modules.conf # name|/path module registry ├── global-manifest.json # Per-module hash + metadata ├── tool_stats.jsonl # MCP tool call log ├── models/potion-code-16M/ └── modules//graph.json ``` ## 卸载 **从所有 AI 客户端中移除：** ``` # 重新运行 setup，并从 setup 写入的 config 文件中手动移除该条目： # Claude Code: ~/.claude.json (key: mcpServers.codesynapse) # Cursor: ~/.cursor/mcp.json (key: mcpServers.codesynapse) # Windsurf: ~/.codeium/windsurf/mcp_config.json # OpenCode: ~/.config/opencode/opencode.json ``` **移除特定模块：** ``` codesynapse module remove myrepo ``` **彻底清理**（移除所有已索引的数据）： ``` rm -rf ~/.codesynapse/ ``` ## 手动 MCP 设置 如果 `codesynapse setup` 未能自动检测到你的客户端，请手动此条目： **Claude Code** (`~/.claude.json`): ``` { "mcpServers": { "codesynapse": { "type": "stdio", "command": "codesynapse", "args": ["mcp"] } } } ``` **Cursor** (`~/.cursor/mcp.json`): ``` { "mcpServers": { "codesynapse": { "type": "stdio", "command": "codesynapse", "args": ["mcp"] } } } ``` 对于其他客户端，请将相同的 `command`/`args` 对传递给它们的 MCP 服务器配置。 ## CLI 技能（无 MCP 的备用方案） 如果 MCP 被你组织的网络策略阻止，codesynapse 为 Claude Code 提供了 CLI 技能，并为 Cursor 提供了规则文件。你的 AI 客户端将直接通过 shell 调用 `codesynapse`，而不是使用 MCP 协议。 **Claude Code** —— 复制到你的项目中： ``` mkdir -p /path/to/your/project/.claude/skills cp -r integrations/claude-code/skills/codesynapse-cli /path/to/your/project/.claude/skills/ ``` **Cursor** —— 复制到你的项目中： ``` mkdir -p /path/to/your/project/.cursor/rules cp integrations/cursor/rules/codesynapse-cli.mdc /path/to/your/project/.cursor/rules/ ``` `integrations/` 目录随仓库一同发布。复制后请重启你的客户端。 ## pi 扩展 对于 [pi](https://github.com/pi-ai/pi) 用户，请安装 codesynapse 扩展： ``` pi install npm:codesynapse-pi ``` 这将配置好 12 个精选的 codesynapse 工具，并自动将图谱感知注入到每个 pi 会话中。 ## 故障排除 **MCP 服务器未连接** - 验证 `codesynapse` 是否在你的 PATH 中：`which codesynapse` - 重新运行 `codesynapse setup` —— 它会重新写入客户端配置 - 设置完成后重启你的 AI 客户端 **图谱查询没有结果** - 检查模块是否已索引：`codesynapse module list` - 重新构建全局图谱：`codesynapse build` - 确保模型已下载：`codesynapse setup`（首次运行时下载 `potion-code-16M`） **代码更改后结果过时** - 刷新模块：`codesynapse module refresh myrepo` - 或者安装 git hook 以进行自动刷新：`codesynapse hook install` **`codesynapse setup` 提示没有嵌入模型** `codesynapse setup` 会自动下载模型。如果失败： 1. 检查你的互联网连接并重新运行 `codesynapse setup` 2. 从 HuggingFace 手动下载： https://huggingface.co/minishlab/potion-code-16M/resolve/main/model.safetensors https://huggingface.co/minishlab/potion-code-16M/resolve/main/tokenizer.json https://huggingface.co/minishlab/potion-code-16M/resolve/main/config.json 将这三个文件放在 `~/.codesynapse/models/potion-code-16M/` 中，然后重新运行 `codesynapse setup`。 **图谱查询缓慢** - 启动后的第一次查询较慢 —— 嵌入需要从磁盘加载 - 后续查询速度很快（约 1.5 毫秒编码 + BM25 + 余弦相似度计算） ## 遥测 遥测默认**关闭**。如果你想帮助改进 codesynapse，请显式启用它： ``` codesynapse telemetry on # opt in codesynapse telemetry off # opt out + delete local queue ``` 启用后，codesynapse 会发送匿名的每日汇总数据：工具名称、调用次数以及粗略的 token 节省量区间。不包含查询内容、文件路径、源代码和 IP 地址。完整的数据契约请参见 [TELEMETRY.md](TELEMETRY.md)。 ## 贡献 欢迎贡献。在提交 PR 之前，请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。 - **Bug 报告：** 使用 [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) - **功能请求：** 使用 [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) - **代码：** 提交前请运行 `cargo test --workspace` 和 `cargo clippy --workspace -- -D warnings` 本项目遵循 [Contributor Covenant](CODE_OF_CONDUCT.md) 行为准则。 ## 许可证 MIT —— 详见 [LICENSE](LICENSE)。

标签：AI编程助手, MCP服务, Rust, SOC Prime, 代码分析, 凭证管理, 可视化界面, 开发工具, 网络流量审计, 通知系统