roam-code：让 AI agent 改代码前先看见代码图
AI coding agent 最容易出问题的地方，往往不是它不会写一段局部代码，而是它不知道这段代码在整个仓库里牵着多少东西。
一个函数名搜出来十几个文件，agent 读了其中三四个就开始改；测试过了，但某个间接调用路径坏了；或者它根据字符串匹配判断影响范围，却漏掉了动态 import、调用图、架构分层和历史上经常一起改的文件。人类 reviewer 看这种 PR 时，真正想问的不是“测试有没有绿”，而是“它改之前到底看过什么，知道哪些风险，又验证了哪些东西”。
今天想记下的 Cranot/roam-code，就是围绕这个问题做的本地代码库智能层。它不是再包一层聊天 UI，而是把仓库预先索引进本地 SQLite，把符号、调用、imports、依赖、git 历史、runtime traces、smells、clones、安全流和算法模式变成 CLI 与 MCP 可以查询的结构化事实。agent 在改代码前可以先跑 roam preflight 看 blast radius，改完后再用 roam verify --auto 做范围化检查，并把过程整理成可带走的 evidence。
按 GitHub repository page、README、LICENSE、release page、git tags、浅克隆提交历史和 GitHub HTML metadata 在 2026-07-10 能核验的公开信息，Cranot/roam-code 当前有 495 stars、47 forks。仓库主语言是 Python，许可证是 Apache-2.0。仓库创建于 2026-02-09 10:11:37 UTC，GitHub pushed 时间在候选检索中显示为 2026-07-09 15:49:36 UTC，浅克隆看到的 main 最新提交时间是 2026-07-09 15:47:38 UTC。最新 GitHub release 是 v13.7.0，发布时间为 2026-07-08 07:58:08 UTC。
项目概览
| 属性 | 详情 |
|---|---|
| 仓库 | Cranot/roam-code |
| 定位 | 本地代码库智能层，面向 AI coding agent 的 preflight、verify 和 evidence |
| Stars | 495 |
| Forks | 47 |
| 主语言 | Python |
| 许可证 | Apache-2.0 |
| 仓库创建时间 | 2026-02-09 10:11:37 UTC |
| 最近 push | 2026-07-09 15:49:36 UTC |
| 最新 main 提交 | 2026-07-09 15:47:38 UTC |
| 最新版本 | v13.7.0 |
| 版本发布时间 | 2026-07-08 07:58:08 UTC |
| 核心能力 | SQLite code graph、CLI、MCP server、preflight、verify、ChangeEvidence、secret scrubbing |
它把“先理解仓库”变成一个本地步骤
roam-code 的 README 把安装路径压得很直接：pip install "roam-code[mcp]"，进入仓库后 roam init 建索引，再用 roam health 和 roam preflight <symbol> 看风险。它也支持 pipx install roam-code、uv tool install roam-code、从源码安装和 Docker。
这个设计的关键，不是多一个搜索命令，而是把 agent 常见的“边读边猜”前移成一个本地的代码图步骤。README 里强调它默认完全本地运行，不要求账号、API key 或云端登录。对有私有代码、客户代码、离线仓库的人来说，这一点比漂亮的 demo 更重要：代码事实先在本机变成索引，模型只在需要时拿到更小、更明确的上下文。
它的 preflight 也不是简单 grep。README 示例里展示的是围绕某个 symbol 的 blast radius、受影响测试、复杂度、耦合和约定检查。实际采用时不必迷信示例数字，但这个接口形状很实用：在 agent 动手前，先问“这个点改起来危险吗，危险来自哪里”。这比改完以后才靠 reviewer 追问要自然很多。
MCP tools 的价值在于约束任务边界
roam-code 对 MCP 的支持很重。README 当前写到 268 个命令、243 个 MCP tools，其中默认 core preset 有 16 个。它还在 src/roam/mcp-server-card.json 里描述了 stdio、SSE 和 streamable HTTP 等 transport，以及 code-intelligence、static-analysis、code-graph、security、attestation 这些类别。
数量本身不是重点。真正有用的是 preset 和模式边界：一个 agent 不应该在任何任务里都拿到全量工具。README 提到 MCP response 会做 secret scrubbing，并按 read_only、safe_edit、migration、autonomous_pr 这类模式做决策记录。这个方向和最近很多 agent 工具的痛点一致：工具越多，越需要把权限、证据和审计放回协议层，而不是只靠 prompt 里一句“请小心”。
如果你在 Claude Code、Cursor、Continue 或自己的 MCP harness 里接工具，roam-code 更像是一个本地代码库 sensor。它可以回答“谁调用了这个函数”“这个文件依赖谁”“这个改动的 blast radius 是什么”，也可以在改完后做 import、复杂度、重复、secret 泄露等检查。agent 不一定更聪明，但它至少少一些盲改。
verify 和 evidence 比单次搜索更有意思
很多代码搜索工具的终点是“找到相关文件”。roam-code 更值得关注的部分，是它把改前和改后的动作连起来。
roam verify --auto 会根据触碰到的文件选择检查项，比如 Python 编辑解锁 Python 相关检查，源码编辑触发命名、重复、import、复杂度、cycles、secret 等检查。它也提供 --diff-only、--changed-lines、baseline 和 new-only 这类参数，目标不是把老仓库所有债务一次性炸出来，而是把新改动放进可处理的范围。
README 里还反复提到 ChangeEvidence。我的理解是，这是把 agent 过程从“它说自己看过”改成“它能产出一包证据”：哪些上下文被读过，风险怎么判断，改了什么，做了哪些验证，哪些环节仍然缺失。这个想法还很早，但方向对。未来 reviewer 审 agent PR 时，很可能不会只看 diff 和测试结果，还会看 agent 的上下文使用记录和验证记录。
适合什么场景
第一类场景是中大型仓库里的局部修改。你知道要改某个函数或模块，但不确定影响范围。让 agent 先跑一次 preflight，再决定读哪些文件、跑哪些测试，比让它从 grep 开始自由探索更稳。
第二类场景是 agent PR 的自动复查。roam-code 可以作为改后 verify 层，盯住 import 幻觉、secret 泄露、复杂度上升、重复代码和局部架构问题。它不能代替 reviewer，但能把一些机器适合看的风险提前摆出来。
第三类场景是私有代码库的本地问答。因为它默认本地索引，不要求把代码发到第三方服务，所以适合对代码外传敏感的团队先试。你仍然要看清 MCP 客户端和模型侧会拿到哪些上下文，但至少底层代码图不需要先上云。
第四类场景是想给 agent 工作流补证据链的团队。尤其当你已经开始让 agent 批量处理 issue、重构或生成 PR 时，只保留聊天记录是不够的。结构化 evidence、签名或 HMAC-linked ledger 这类机制，可能会比自然语言总结更有审计价值。
需要注意的地方
第一，项目野心很大，也因此需要验证。README 里有很多 benchmark、evidence、security posture 和 tool count 的描述，但不同仓库、语言和 agent 的效果会差很多。真正采用前，应该拿自己的仓库做一组小的 A/B：同一类任务，有无 roam-code，比较阅读轮次、失败率、测试选择和 reviewer 负担。
第二，工具面很宽。243 个 MCP tools 听起来很强，但也意味着权限设计不能偷懒。建议从默认 core preset 和 read-only 模式开始，再逐步开放 verify、safe edit 或更高权限的命令。
第三，v13.7.0 虽然已经有密集 release 历史，但仓库创建于 2026-02-09，仍属于很新的工具。把它放进生产 CI 或强制 gate 前，先确认索引速度、误报、失败时的行为、缓存目录、跨平台路径和团队语言栈覆盖情况。
第四，GitHub 的 stars、forks 和 pushed time 会持续变化。这里记录的是 2026-07-10 写作时能看到的快照，后续阅读时以仓库页面为准。
小结
roam-code 有意思的地方，是它没有把 AI coding 问题简化成“给模型更多上下文”。它更像是在 agent 周围补一层本地代码事实、任务边界和改动证据：改之前看 blast radius，改之后跑范围化 verify，必要时把证据打包给 reviewer。
如果你已经在真实仓库里使用 coding agent，而且开始遇到“测试绿了但 reviewer 还是不放心”的问题，Cranot/roam-code 值得试一轮。它不保证 agent 写出的代码一定能合并，但它把“为什么这次改动值得信任”这件事，从口头承诺推进到了更可检查的工具输出里。