codeloom

"借助 codeloom，你的编程 agent 知道该阅读什么。"

AI 编程 agent 功能强大，但从根本上对代码库的结构一无所知。当你的 agent 修改 `validate_token()` 时，它完全不知道有 47 个调用方依赖于它的返回类型。当它搜索 "database connection" 时，它只能盲目地在每个文件中 grep。没有代码图谱，你的 agent 就像外科医生在没有 X 光的情况下进行手术，医术精湛但只能猜测内部的情况。 **codeloom** 从你的整个代码库构建可查询的代码图谱——从 **55 种语言和格式**中提取结构，包括每个函数、类、导入、调用和文档——并将其暴露给你的 AI agent。一次安装，你的 agent 就会停止盲目 grep，开始真正理解代码。 ## 快速开始 ``` pip install codeloom cd your-project/ codeloom install opencode # for OpenCode # 或：codeloom install claude # 用于 Claude Code ``` 然后告诉你的 agent： 就这样。当你的会话结束时，图谱会自动重建。无需额外的 token，无需额外的命令，一切 100% 在本地运行。 ## 改变了什么 | 之前 | 之后 | |---|---| | 只能找到精确的字符串，错失语义关联 | 通过向量 + 关键词 + 图谱找到概念相关的代码 | | 返回扁平的文件匹配列表 | 返回种子**以及展示它们如何连接的子图** | | 无法知道什么依赖于什么 | `codeloom impact "validate_token"`，瞬间找到所有 47 个调用方 | | Agent 盲目操作，猜测代码关系 | Agent 在进行修改前能看到全貌 | 每次搜索都会返回如下结果： ``` seeds: codeloom/core/pipeline.py:71 │ def run_pipeline(source_dir: Path, ...) -> PipelineResult: │ """Run the full code graph build pipeline.""" storage/store.py:20 │ class KnowledgeStore: edges: codeloom/core/pipeline.py:71 -calls-> storage/store.py:20 codeloom/core/pipeline.py:0 -defines-> codeloom/core/pipeline.py:71 ``` 种子告诉你相关代码在*哪里*。边告诉你它们*如何连接*。两者结合为你的 agent 提供了完整的信息，无需单独调用 Read。 ## 16 个 MCP 工具一览 三大类，一个 MCP 服务器。 ### 搜索 | 工具 | 功能描述 | |------|-------------| | `search` | 5 信号 HybridRAG，将向量 + 关键词 + 图谱 + 社区融合为一个排名 | | `search_keyword` | 仅限 FTS5 关键词 (BM25)，针对已知名称提供即时结果 | | `search_vector` | 仅限语义向量，查找概念相似的代码 | ### 分析 | 工具 | 功能描述 | |------|-------------| | `impact` | 影响范围分析，找出每个依赖于某 symbol 的调用方 | | `dependencies` | 上游依赖项，查找某个 symbol 运行所需的内容 | | `context` | 某个 symbol 的 360 度全景视图，包含元数据、社区、所有边、源代码片段 | | `detect_changes` | 将未暂存的 git 更改映射到受影响的图谱节点 | | `explain_flow` | 通过调用链追踪执行路径 | | `stats` | 节点/边数量、类型分布、超级节点统计 | | `communities` | 浏览功能集群 | | `node` | 通过模糊名称匹配获取特定 symbol 的详细信息 | ### 重构与管理 | 工具 | 功能描述 | |------|-------------| | `rename` | 查找所有位置和引用，实现安全的多文件重命名 | | `export_subgraph` | 将围绕某 symbol 的聚焦子图导出为 D3.js JSON | | `list_repos` | 列出带有陈旧状态的可用代码图谱 | | `build` | 构建或重建代码图谱 | | `watch` | 监视文件更改并自动重建 | 所有工具均可通过 MCP (stdin/stdout) 使用，无需 HTTP 服务器、网络或配置。 ## 语言与格式 ### 结构提取（函数、类、调用、导入） 针对 17+ 种核心语言提供完整的基于 tree-sitter tags.scm 的解析。所有 56 种语言均支持模块级索引、源代码片段和 embeddings——结构细节取决于可选的 `tree-sitter-` 包。 | | | | | | | | | |:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:| | Ada | C | C# | C++ | Common Lisp | Elixir | Fortran | Go | | Groovy | Haskell | Java | JavaScript | Julia | Kotlin | Lua | Nix | | Objective-C | OCaml | Perl | PHP | PowerShell | Python | R | Ruby | | Rust | Scala | Shell | Solidity | Swift | Terraform | TypeScript | Zig | | Assembly | | | | | | | | ### 文档与配置提取 | | | | | | | |:---:|:---:|:---:|:---:|:---:|:---:| | CMake | CSV | CSS | DjVu | Dockerfile | DOCX | | GraphQL | HCL | HTML | JSON | Make | Markdown | | ODP | ODS | ODT | Org | PDF | RST | | SQL | TOML | XLSX | XML | YAML | | 另外，通过 multilingual-e5-small embeddings 支持 **100 多种自然语言**的搜索查询。你可以使用任何语言进行搜索，并获取任何语言的结果。 ## AI Agent 集成 每个平台只需一条命令： | Agent | 安装命令 | |-------|---------| | **Claude Code** | `codeloom install claude` | | **OpenCode** | `codeloom install opencode` | | **Codex CLI** | `codeloom install codex` | | **Gemini CLI** | `codeloom install gemini` | | **Cursor IDE** | `codeloom install cursor` | | **Windsurf IDE** | `codeloom install windsurf` | | **Cline** | `codeloom install cline` | | **Aider CLI** | `codeloom install aider` | | **任何 MCP 客户端** | `claude mcp add codeloom -- codeloom mcp` | 每个 `install` 命令都会写入上下文规则，并在支持的平台上注册 hooks。对于 OpenCode，它还会安装一个插件，该插件会**在调用 grep/glob 之前自动注入图谱上下文**，你的 agent 无需主动请求即可获得结果。使用 `codeloom uninstall ` 进行卸载。 ## 功能特性 ### 搜索优先于 Grep 5 信号 HybridRAG 将代码向量搜索、文本向量搜索、图谱扩展、FTS5 关键词和社区信号融合为一个带子图边的排名结果集。`--kind`、`--file` 和 `--include-tests` 过滤器可以在不重新运行的情况下缩小结果范围。 ### 自信修改 在修改前运行 `impact` 以查找每个调用方。运行 `context` 获取完整的 symbol 概览、社区、所有关系以及源代码片段。修改后运行 `detect_changes` 查看哪些节点受到影响。 ### 自动上下文 OpenCode 插件会挂钩到 grep/glob 调用中，使用查询语句运行 `codeloom search`，并将结果直接注入到 agent 的会话中，图谱上下文会自动出现，无需显式调用。 ### 自动重建 Stop/SessionEnd hooks 通过 `git diff` 检测更改的文件并触发增量重建。锁文件可防止并发重建。完全无需人工干预，每次会话后图谱都能保持最新。 ### 增量与高速 SHA-256 内容哈希会跳过未更改的文件。热启动 PageRank 会重用之前的重要性得分。**并行提取** (ProcessPoolExecutor) 将全量构建速度提升了 24-64%。典型的增量构建：**无更改约 0.4 秒，有更改约 4 秒**，比全量构建快 95% 以上。**模型预热** (`--warmup`，默认开启) 会在 MCP 服务器启动时预加载 embedding 模型，从而使首次搜索极快——使用 `--no-warmup` 禁用可节省约 150MB RAM。 ### 100% 本地 + MIT 协议 没有云服务，没有 API 密钥，没有遥测。使用 SQLite + FAISS 进行存储，使用 sentence-transformers 进行 embedding。所有数据都保留在你的机器上。采用 MIT 许可协议，没有商业限制，没有许可摩擦。 ## 性能表现 基准测试在 2023 款 MacBook Pro (M2 Pro, 32GB RAM) 上进行。所有构建均使用 并行提取（默认：`os.cpu_count()` 个工作进程）。 ### codeloom 自身的代码库（约 3,500 行代码，90 个文件，1,300 个节点） | 操作 | 耗时 | |-----------|------| | 全量构建 | ~14s | | 增量构建（有更改） | ~4s | | 增量构建（无更改） | ~0.4s | | 冷搜索（双模型） | ~2.8s | | 冷搜索（`--fast`） | ~0.2s | | 热搜索 | ~0.08s | | 缓存搜索 | <1ms | ### 合成压力测试（不含 embeddings） | 数据集 | 文件数 | 节点数 | 构建时间 | 峰值内存 | |---------|-------|-------|-----------|-------------| | 微型 | 10 | 119 | **0.7s** | 14 MB | | 小型 | 100 | 4,109 | **2.3s** | 16 MB | | 中型 | 1,000 | 101,009 | **53.1s** | 393 MB | | 大型 | 5,000 | 205,009 | **164.9s** | 814 MB | 并行提取使构建速度提升了 24-64%。紧凑的节点存储 （路径驻留、跳过空属性、持久化后无内存占用的源代码片段）将峰值内存降低了 10-22%。详细 分析请参阅 `docs/SCALING.md`。 - **Embedding 模型**：约 180MB，下载一次后缓存于 `~/.codeloom/models/` - **数据库**：约 2MB (SQLite + FTS5 + FAISS 索引) ## 完整 CLI 参考 默认情况下，所有命令都会输出紧凑的文本（专为供 AI agent 读取而设计）。 ### CLI 命令 | 命令 | 描述 | |---------|-------------| | `build ` | 构建代码图谱 (`--incremental`, `--git`) | | `watch ` | 实时文件系统监视器 | | `search ` | 包含子图和代码片段的 5 信号 HybridRAG | | `search-keyword ` | 仅限 FTS5 关键词匹配 | | `search-vector ` | 仅限向量相似度匹配 | | `search-graph ` | 仅限图谱扩展（从向量种子进行 BFS） | | `search-community ` | 仅限社区集群匹配 | | `stats` | 图谱统计信息 | | `node ` | 支持模糊匹配的节点详细信息 | | `communities` | 列出或搜索社区 | | `query` | 交互式搜索 REPL | | `export` | 导出为 JSON、GraphML 或 D3.js | | `visualize` | 交互式 HTML 可视化 | | `install [agent]` | 为 AI agent 安装 codeloom 集成 | | `uninstall [agent]` | 为 AI agent 卸载 codeloom 集成 | | `doctor` | 检查安装健康状态 | | `clean` | 删除 `.codeloom/` 数据库 | | `mcp` | 启动 MCP 服务器 | | `help [command]` | 显示分类帮助和使用示例 | ### 仅供 MCP 使用的工具 这些可通过 `codeloom mcp` 使用——请参阅上方的 [MCP 工具部分](#15-mcp-tools-at-a-glance)： `impact` · `dependencies` · `context` · `detect_changes` · `rename` · `explain_flow` · `export_subgraph` · `list_repos` ## 环境要求 - Python 3.10+ - 约 180MB 磁盘空间用于存放 embedding 模型（首次使用时缓存） ``` # 可选：PDF、DOCX、XLSX、ODF 提取 pip install codeloom[docs] ``` ## 开发 ``` pip install -e ".[dev]" pytest ruff check codeloom/ ``` ## 许可协议 MIT 许可协议。详情请参阅 [LICENSE](LICENSE)。 ## 贡献 欢迎提交贡献！请查阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南。

标签：AI编程助手, MCP, SOC Prime, 云安全监控, 代码图谱, 开发工具, 本地优先, 逆向工具, 静态分析