roam-code

roam-code：AI 编程Agent的本地代码智能层

一、项目起源与行业背景

当一个大语言模型在代码库中执行修改时，它真的「理解」这个项目吗？传统 AI 编程工具依赖海量的 API 调用来探索代码——一次搜索符号引用，一次查找依赖关系，再一次确认测试覆盖。METR 和 FrontierCode 的研究先后揭示了一个令人不安的结论：通过测试不等于值得合并，AI 生成代码的「看起来正确」与「实际安全」之间存在巨大鸿沟。

Cranot 开源的 roam-code 正是为填补这一鸿沟而生。这是一个完全本地运行的代码智能平台，专为 AI 编程 Agent 设计——在 Agent 修改代码之前，先给它提供结构化的代码图谱事实；在修改过程中，设立安全门控；在修改完成后，生成带有篡改可验证证据的 ChangeEvidence 数据包。整个过程零 API key、零云端依赖，代码永远不会离开开发者的机器。

二、核心功能与使用场景

1. 代码图谱构建（Code Graph）

roam-code 的核心是一个 SQLite -backed 的多维代码图谱数据库，覆盖 28 种编程语言。通过 tree-sitter 解析器提取符号表、调用关系、导入链、Git 历史、运行时踪迹、代码异味、克隆代码、安全流向和算法模式等九大类信息。这些图谱数据以 SQLite 文件（.roam/index.db）存储，完全本地化。

初始化仓库只需一行命令：roam init，首次索引一个中等规模仓库（约 200 个 Python 文件）耗时约 30 秒。索引完成后，所有后续查询响应时间在 0.5 秒以内，输出纯 ASCII 格式，支持 --json 和 --sarif 两种包装格式供 Agent 和 CI 系统消费。

2. Preflight 安全门控

修改前最关键的一步是执行 roam preflight <symbol>：系统会同时返回爆炸半径分析（blast radius）、受影响测试列表、复杂度评分和架构规则检查。这一步替代了原来需要 8 次 API 调用才能收集到的信息，将耗时从约 11 秒压缩到 0.5 秒以内，单次查询 token 消耗从约 15000 降至 3000。

3. MCP Server 集成

roam-code 同时是一个 Model Context Protocol（MCP）服务器，通过 pip install "roam-code[mcp]" 安装后，可无缝接入 Claude Code、Cursor 和 Continue 等主流 AI 编程工具。MCP server 提供 243 个工具端点（core preset 默认 16 个），覆盖代码导航、安全审计、影响分析、架构评估等场景。server.json 配置文件中明确定义了各 preset 的工具数量：core（16）、compliance（13）、debug（71）、refactor（72）、review（72）、architecture（73）、full（243）。

4. 可验证证据体系（ChangeEvidence）

roam-code 引入了一套完整的篡改可验证证据框架。AI 引导的每一次修改都可以编译成一个便携式数据包，包含 HMAC 链式运行账本、签名代码图谱证明和签名 PR 捆绑包，回答八个关键问题：谁执行了操作、什么权限存在、读取了什么上下文、修改了什么、什么可能被破坏、什么策略适用、什么被验证了、谁接受了风险。

这一设计与 PR Replay 的结构性变更/风险/策略轴线高度对齐，并将 MCP 响应边界的安全机制（HMAC 链接的策略决策收据）整合在内。

5. 命令行生态

项目定义了 267 条独立命令，涵盖代码导航、健康评分、复杂度分析、审计追踪、合规检查、安全分析等场景。部分命令支持 SARIF 输出格式（精确到 17 个命令），可直接接入 CI/CD 安全扫描管道。

三、技术架构解析

核心模块结构（src/roam/）：

项目采用模块化插件架构，主要分为：

• cli.py（67715 字节）：Click 框架实现的命令行入口，采用延迟加载策略（避免每次调用都加载 networkx 约 500ms 的初始化开销），定义了 241 个可调用命令名（含 7 个历史别名）。
• mcp_server.py（728909 字节）：MCP 协议服务端实现，集成 FastMCP，是项目体积最大的模块，支持 stdio 传输模式。
• agent_opt.py（48370 字节）：AI Agent 优化相关逻辑，处理上下文压缩和提示词优化。
• proof_bundle.py / proof_bundle_render.py：证据打包与渲染系统，生成可验证的证据文档。
• guard_*.py 系列：安全门控相关模块，包含 guard_rules（规则引擎）、guard_errors（错误定义）、guard_enums（枚举类型）、guard_log（审计日志）。

代码图谱引擎（src/roam/graph/）：

graph 子目录包含 19 个分析模块，是项目的算法核心：

• builder.py：图谱构建器，从 tree-sitter AST 中提取实体和关系
• pagerank.py：PageRank 算法识别代码库中的核心模块
• anomaly.py：异常检测，发现偏离正常结构的代码
• clone_detect.py：克隆代码检测
• cycles.py：循环依赖检测
• propagation.py：变更影响传播分析
• dark_matter.py：暗物质耦合检测，识别幽灵依赖
• spectral*.py：谱分析方法，识别代码结构特征

命令模块（src/roam/commands/）：

283 个命令文件覆盖了完整的代码分析场景，从基础的 cmd_affected.py（影响分析）、cmd_complexity.py（复杂度）到高级的 cmd_audit_trail_*.py（审计追踪验证）、cmd_article_12_check.py（合规检查）。每个命令对应一个独立的 Python 模块，通过 _command_utils.py 共享工具函数。

依赖体系：

核心依赖：click（CLI框架）、tree-sitter（AST解析）、networkx（图算法）
可选依赖（mcp）：fastmcp（MCP协议服务端）
可选依赖（semantic）：numpy、onnxruntime（语义分析）

tree-sitter 依赖被严格约束在 <1.6.3 版本（避免 1.6.3 的 cp312 wheel 安装问题）。项目要求 Python >= 3.10，支持 3.10 到 3.13 全系版本。

四、容器化部署

项目提供官方 Dockerfile，基于 python:3.12-slim-bookworm 镜像（选 bookworm 而非 alpine 是因为 tree-sitter 及其语言包的多架构 wheel 依赖 glibc，alpine 的 musl 会强制源码编译）。最终镜像体积控制在约 150MB。Dockerfile 包含以下关键设计：

• 非 root 用户运行（groupadd/useradd roam）
• 工作目录为 /workspace（适合作为容器内工作区挂载）
• 预装 git 和 ca-certificates（支持 git clone 仓库和 HTTPS 外部检查）
• 通过 pip install . 完成安装，最后执行 roam --version 烟雾测试

Dockerfile 还设置了 OCI 标准镜像标签（org.opencontainers.*），便于集成到容器镜像仓库和扫描工具。

五、Web UI 与交互方式

roam-code 不提供 Web UI，属于纯命令行工具。交互通过终端 CLI 和 MCP 协议两种方式进行：

• CLI 模式：直接执行 roam <command>，输出 ASCII 格式结果
• MCP 模式：作为 MCP 服务器运行，被 Claude Code/Cursor/Continue 等工具通过 stdio 调用

对于不熟悉命令行的用户，有一定的上手门槛。但对于 AI Agent 而言，这种结构化的文本输出反而是最理想的信息传递方式。

六、争议与局限性

1. Python 强依赖：核心依赖 tree-sitter 的语言包体积较大，在某些精简环境中安装可能遇到 wheel 不兼容问题。Dockerfile 的 bookworm 选择虽然保证了兼容性，但也增加了镜像体积。

2. 首次索引耗时：大型仓库（数千个文件）的首次 roam init 可能需要数分钟，对于频繁切换项目场景不够友好。

3. 完全本地化的代价：不依赖云端意味着无法利用云端算力进行更深层的语义分析（如跨仓库的依赖推理）。对于追求最高分析精度的场景，可能需要结合 LLM API 使用。

4. 证据体系的实际落地：HMAC 链式证据和 ChangeEvidence 数据包的设计理念超前，但目前 PR Replay 等工具仅部分支持其提出的「八问框架」，实际效果取决于生态整合进度。

七、行业意义与增长趋势

roam-code 代表了 AI 编程工具从「生成」向「验证」演进的重要趋势。随着 Claude Code、Cursor 等工具逐渐普及，如何确保 AI 生成代码的可验证性和安全性成为行业焦点。roam-code 通过将传统代码分析工具（SCC、Bandit、Cloc 等）的功能封装为 Agent 可消费的图谱查询，同时引入审计追踪机制，为这一方向提供了有价值的参考。

根据 GitHub 数据，项目已获得 485 颗星，在代码智能类工具中增长迅速。其 20 个 Topics 精准覆盖了 ai-agents、code-analysis、mcp-server 等高热度标签，预示着良好的社区关注度。

图1：roam-code 终端运行演示，展示了代码图谱查询的 ASCII 格式化输出效果