Cranot/roam-code

Local codebase intelligence CLI + MCP server for AI coding agents: SQLite code graph, 28 languages, 287 commands, 246 MCP tools, change-safety gates, audit evidence, zero API keys.

📚 什么是 roam‑code

roam‑code 是一个基于 Python 的本地运行静态分析工具包，专为 代码代理（LLM 驱动的代码生成工具）设计。它构建了代码库中符号（函数、类、导入及其相互关系）的可搜索地图，使代理能够询问“谁调用了这个函数？”或“这个变更会影响哪些测试？”等问题，而无需逐个读取所有文件。

该工具 不进行任何远程模型调用；所有繁重工作都在您的机器上完成。它以 CLI（roam）形式提供，并可选地作为 MCP（Model-Control-Protocol）服务器运行，让代理可通过标准工具调用接口与之通信。

🔧 核心功能（如 README 所述）

功能	作用	使用方式
索引 / `roam init`	解析整个仓库，构建覆盖 28 种语言、287 个命令和 246 个 MCP 工具的符号图。	在仓库根目录运行 `roam init`（或使用 `roam index` 进行轻量构建）。
预飞行检查 (`roam preflight <symbol>`)	估算变更的爆炸半径（可能受影响的符号/文件数量），并报告相关测试、复杂度、耦合度等。	`roam preflight open_db` – 返回包含具体数字的风险评估结果。
健康摘要 (`roam health`)	提供代码结构、发现项和整体“健康评分”的快速概览。	索引完成后运行 `roam health`。
搜索 (`roam search <name>`)	在索引图中按名称查找符号。	`roam search handleSave`。
验证 (`roam verify …`)	对变更文件运行一系列静态检查：命名规范、导入有效性、复杂度、密钥泄露、惯用模式警告等。	`roam verify --auto`（自动为变更文件选择检查项）或使用更细粒度的标志。
MCP 服务器 (`roam-code[mcp]`)	通过网络套接字暴露相同查询，使基于 LLM 的代理可将其作为工具调用。	使用 `pip install "roam-code[mcp]"` 安装并启动服务器；代理可通过 MCP 调用 `roam` 命令。
Claude Code 钩子 (`roam hooks claude`)	自动将执行前上下文（调用者、最近变更）注入 Claude Code 提示词，并在模型完成后验证结果。	`roam hooks claude --write` 启用，`--uninstall` 移除。
Roam Guard	一个 PR 门禁，记录运行的检查、其结果，并在出现关键发现时阻止合并。	在 CI 中使用 `roam verify --auto`；可配置为在特定严重性下失败。
性能	索引为一次性成本；后续刷新非常快。基准测试（2026 年 5 月–7 月）显示，导航类查询的 LLM 轮次减少高达 80%，令牌数和成本大幅降低。	请参阅 README 中的详细基准表格获取具体数字。

🚀 通常采用方式

添加到仓库 – 在项目的虚拟环境中运行 pip install "roam-code[mcp]"。
创建索引 – 在仓库根目录运行 roam init（大型代码库首次运行可能需一分钟）。
连接你的代理 – 启用 MCP 服务器或 Claude 特定钩子，使 LLM 能在推理过程中请求 roam 数据。
在 CI 中运行检查 – 使用 roam verify --auto（或自定义检查集）在合并前强制执行“门禁”。
迭代 – 变更后，运行 roam preflight <symbol> 查看潜在影响，再提交。

📊 为何对 AI 辅助开发至关重要

本地化、隐私保护 – 无需 API 密钥，无遥测数据；分析完全在本地完成。
代理为中心 – 提供结构化、符号级别的上下文，LLM 可直接消费，减少通常所需的“搜索-打开文件”步骤。
语言无关 – 支持 28 种编程语言，适用于多语言单体仓库。
门禁机制 – 可作为 CI 流水线的一部分，防止高风险变更被合并，补充人工代码审查。

📦 快速入门（四个命令）

pip install "roam-code[mcp]"   # CLI + 可选 MCP 服务器
cd /path/to/your/repo
roam init                       # 构建索引与配置
roam health                     # 查看健康快照
roam preflight <symbol>         # 编辑前评估风险

TL;DR

roam‑code 是一个免费、开源的静态分析引擎，将代码库转化为符号及其关系的可搜索图。它让基于 LLM 的代码代理能提出精确、低令牌的问题，并可在 CI 中强制执行安全门禁——所有操作均无需将源代码发送到机器外部。