Cranot/roam-code

roam-code 是一个本地代码分析工具包，旨在为 AI 编程代理提供对代码库的可重用理解。它会构建项目符号、连接和模式的索引，并将其公开为代理在工作时可调用的命令和 MCP 工具。

功能特色

• 本地索引代码：解析源代码、提取函数/类、解析引用，并将所有内容存储在 SQLite 数据库中。
• 提供现成检查（静态分析、模式检测、影响分析）：在您的机器上运行，无需任何模型调用或云服务。
• 与代理集成：通过 MCP (Model Context Protocol) 或 CLI，让代理可以查询索引、检查代码并评估变更，无需从头重建分析。

核心命令（“核心五项”）

• roam understand – 项目概览以及从何处开始阅读。
• roam context <symbol> – 显示定义以及调用它的代码与它所调用的代码。
• roam retrieve "<task>" – 针对“追踪登录流程”等问题寻找相关代码。
• roam preflight <symbol> – 预测变更可能产生的影响（相关代码、测试）。
• roam critique – 审查补丁中可能遗漏的相关代码（通过 git diff 管道传入）。

运作原理

• 发现文件、解析它们（使用 tree-sitter）、提取符号、解析引用，并将模型存储在 SQLite 中。
• 图形分析、Git 历史记录和检测器规则提供不同类型的观察结果。
• 静态检查仅使用本地运算；您代理的模型使用量是分开的。
• 随着代码变更，使用 roam index 重新整理索引。

集成

• 通过 MCP 连接（服务器命令为 roam mcp）或让代理直接调用 CLI。
• 跨 8 个预设集的 258 个 MCP 工具（默认 core 包含 17 个）。
• 可生成 CI 配置（GitHub、GitLab 等）并为 39 个命令生成 SARIF 输出。
• 可选的 Claude Code 钩子可增加编译时上下文与编辑后验证。

隐私与成本

• 完全在您的机器上运行；不会自动上传源代码、索引或遥测数据。
• 免费且开源 (Apache 2.0)。本地分析无需 API 密钥。
• 付费层级（PR Replay、Roam Review、Roam Cloud）均为按需提供或仍在规划中；免费 CLI 将保持完全功能。

限制

• 静态分析可能不完整；结果仅供参考，非绝对证明。
• 并非 LSP、ripgrep 或测试运行器的替代品，而是与它们互补。
• 提取深度因语言而异；识别出的文件扩展名并不代表完整的语义覆盖。

适用场景 最适合代理工作流程中的重复存储库调查、实现选择、重构规划与变更检查。