Cranot/roam-code

## Roam 是什么？ Roam 是一个软件的结构化智能引擎。它预先将你的代码库索引到一个语义图中 —— 符号、依赖、调用图、架构层、git 历史和运行时追踪 —— 存储在本地 SQLite 数据库中。智能体通过 CLI 或 MCP 查询它，而不是反复 grep 文件和猜测结构。 与 LSP（绑定编辑器、特定语言）或 Sourcegraph（托管搜索）不同，Roam 提供架构级别的图查询 —— 离线、跨语言且紧凑。它超越了理解：Roam 通过预算门控治理架构，模拟重构结果，以零冲突保证编排多智能体集群，映射漏洞可达性路径，并实现无语法错误的图级别代码编辑。 ``` Codebase ──> [Index] ──> Semantic Graph ──> 152 Commands ──> AI Agent │ │ │ tree-sitter symbols comprehend 27 languages + edges govern git history + metrics refactor runtime traces + architecture orchestrate ``` ### 从这里开始 —— 涵盖约 80% 智能体工作流的 5 个动词 ``` pip install roam-code cd your-repo/ roam understand # 1. landing pad — what is this codebase? roam retrieve "where is auth?" # 2. graph-aware retrieval for free-form tasks roam context AuthService # 3. exact files+lines to read before changing roam preflight AuthService # 4. blast radius + tests + complexity check git diff | roam critique # 5. patch verifier — clones-not-edited, hot-path ``` 这就是完整的思维模型。其余的 CLI 接口 —— `taint`、`fleet`、`cga`、`simulate`、`mutate`、`partition`、`attest`、`eval-retrieve`、`oracle`、`py-types`、`py-modern`、`dark-matter`、`clones`、`propagation`、`fingerprint` 等 —— 是用于特定工作流的高级接口；你通常不需要用到它们中的大多数。 ### 问题所在 编程智能体探索代码库的效率很低：数十次的 grep/读取循环、高昂的 token 成本、缺乏结构化理解。Roam 用一次图查询取代了这一切： ``` $ roam context Flask Callers: 47 Callees: 3 Affected tests: 31 Files to read: src/flask/app.py:76-963 # definition src/flask/__init__.py:1-15 # re-export src/flask/testing.py:22-45 # caller: FlaskClient.__init__ tests/test_basic.py:12-30 # caller: test_app_factory ...12 more files ``` ### 终端演示  ### 核心命令 ``` $ roam understand # full codebase briefing $ roam context # files-to-read with exact line ranges $ roam retrieve "" # graph-aware spans for free-form natural-language tasks $ roam preflight # blast radius + tests + complexity + architecture rules $ roam critique # verify a patch (`git diff | roam critique`) $ roam health # composite score (0-100) $ roam diff # blast radius of uncommitted changes ``` ## v12 版本更新内容 ### v12.1 (开发中) -- 布尔预言机、IDOR 分类器、索引可移植性 + Django 桥接 - **`roam oracle `**: 面向智能体的 5 个布尔预言机 —— 1-token 的 是/否 回答（`symbol-exists`、`route-exists`、`is-test-only`、`is-reachable-from-entry`、`is-clone-of`）。直接对标 CKB v9.2 的 `symbolExists` 模式。MCP 工具：`roam_oracle_*`。 - **`roam_taint_classify` (仅限 MCP)**: LLM 增强的污点分类 —— 运行 `roam taint` 然后要求智能体自己的模型（通过 MCP 采样）将每个可达的发现标记为 IDOR/AUTHZ/SQLI/XSS 等，并附带置信度 + 推理过程。对标 Semgrep Multimodal —— 相同的 LLM 推理叙事，无需托管的 API 密钥。v12.1 为顺序执行；并发受限的 gather 将在 v12.2 中推出。 - **`roam index-export` / `roam index-import`**: 可移植、完整性检查的 tarball 格式，带有 manifest sha256 往返验证 + 可选的 cosign 签名。对标 Cursor 的“92% 相似代码库 = 复用队友的索引”而无需供应商云。防篡改（导入时 manifest 会验证 index.db 的 sha256）。 - **`roam eval-retrieve --emit-format coderag|beir`**: 用于公共排行榜提交的基准测试可移植 JSONL 输出。兼容 CodeRAG-Bench 的 `ctxs` 数组 + BEIR 风格的 trec_eval 运行文件。 - **Django 桥接**: 完整的隐式关系解析（admin→model、serializer→model、FK 传递、信号处理器、URL 配置、Celery 任务、DRF 路由）。从 `@LukasBerka/roam-code` 移植 —— 特别感谢 Lukas Berka。新增 schema 列：`framework_type`、`field_type`、`field_metadata`。后置解析器在图指标计算之后运行。 - **`worktree_git_env()`** (`git_utils.py`): `GIT_INDEX_FILE` 覆盖修复了当并行智能体在同级工作树中运行 Roam 时出现的 `.git/index.lock` 争用问题。已接入 `discovery.py`、`git_stats.py`、`changed_files.py`。从 `@river-mounts/roam-code-sf` 移植 —— 特别感谢 Sam Hannan。 ### v12.0 (发布于 2026-05-01) -- 检索底座 + 补丁验证器 - **`roam retrieve ""`**: 图感知上下文服务器。混合第一阶段 (FTS5) + 结构化重排器（个性化 PageRank + 克隆规范信号 + 词法基线）+ token 预算上限。返回带有理由标签的排名跨度（`pagerank=...`、`clone_cluster=...`、`fts=...`），以便调用者了解每个跨度*为什么*排在前面。MCP 工具：`roam_retrieve(task, budget, k, rerank, seed_files)`。 - **`roam critique`**: 基于图的补丁验证器。通过管道执行 `git diff | roam critique` 以获取按严重性排序的发现。杀手级信号是 **clones-not-edited**：对于每一个发生了更改且在 diff 之外存在持久化克隆兄弟的符号，我们会将该兄弟标记为可能遗漏的更改。加上爆炸半径的调用者计数发现。高严重性时以状态码 5 退出（可作为 CI 门控）。MCP 工具：`roam_critique(diff_text)`。 - **`roam clones --persist`**: 填充 `clone_pairs` 和 `clone_clusters` 表，以便下游消费者（critique、retrieve）可以在 O(1) 时间内查询克隆，而无需重新运行检测。 - `graph/pagerank.py` 中的 **`personalized_pagerank()`**: 带有空种子回退到全局 PR 的 NetworkX `personalization=` 包装器；为 retrieve 重排器偏向于与查询相关的节点进行排名。 - **`.roam/config.toml`** (新增): 零依赖的 TOML 加载器（stdlib `tomllib` → `tomli` → 树内子集解析器）。可调的 retrieve 权重（`alpha`/`beta`/`gamma`/`delta`/`epsilon`）、`tokens_per_line`、`lexical_baseline`、`first_stage_token_cap`、`default_budget`、`default_k`、`default_rerank`。 - **来自内部测试的 DX 修正**: `roam --detail ` 是规范的组级别标志；7 个命令中误导性的“use --detail”提示已被重写，以引导用户使用 `roam --detail `。在 `complexity`/`algo`/`rules` 上别名化了 `--top N`（在 `rules` 上 `--top 0` 表示无限制）。`roam fingerprint` 不再拒绝 ≥5,000 个符号的图（新的软警告阈值为 20k，硬上限为 100k）。 - **154 个 CLI 命令，120 个 MCP 工具**（`fleet`、`ask`、`cga`、`eval-retrieve` 仍仅限 CLI；v12 暴露了 `roam_retrieve`、`roam_critique`、`roam_fleet_plan`，加上 5 个 v12.1 布尔预言机（`roam_oracle_*`）、`roam_taint_classify`、`roam_pytest_fixtures` 和 `roam_hover` 作为 MCP 工具）。对于注重 token 预算的客户端，默认使用 35 工具的 `core` 预设。 ## v11 版本更新内容 ### v11.2 -- AST 克隆检测 + 调试产物规则 - **`roam clones`**: 通过子树哈希进行新的 AST 结构化克隆检测。使用 Jaccard 相似度评分、Union-Find 聚类和自动化重构建议查找 Type-2 克隆（控制流相同，标识符/字面量不同）。比基于度量的 `duplicates` 命令更精确。 - **9 条调试产物规则** (COR-560 至 COR-568): 检测 Python、JavaScript、TypeScript 和 Java 代码中遗留的 `print()`、`breakpoint()`、`pdb.set_trace()`、`console.log()`、`debugger` 和 `System.out.println()`。均使用 `ast_match` 类型并豁免测试文件。 - **140 个命令，102 个 MCP 工具**（在 v11.2.0 版本发布时）。 ### v11.1.2 -- SQL + Scala 一级支持，27 种语言 - **SQL DDL 提升至一级支持**，配备了专用的 `SqlExtractor` —— 表、列、视图、函数、触发器、schema、类型（枚举）、序列、ALTER TABLE ADD COLUMN。外键产生图边缘；视图和触发器引用源表。数据库 schema 项目现在可以使用 `roam health`、`roam layers`、`roam impact`、`roam coupling` 以及所有图命令。 - **Scala 提升至一级支持**，配备了专用的 `ScalaExtractor` —— 类、特征、对象、案例类、密封层次结构、val/var 属性、类型别名、导入和继承。完全支持 `extends` + `with` 特征混入解析。 - **27 种语言**，配备 16 个专用的一级提取器。 - 用于向官方 MCP Registry 提交的 `server.json`。 ### v11.1.1 -- 命令质量审计 - **全命令审计**: 审查了全部 152 个命令的实用性、重复性和测试覆盖率。修复了约 20 个 bug，新增 21 个测试文件（700+ 测试），更新了每个命令的 docstring 以添加相关命令的交叉引用。 - **Kotlin 通过新的基于 YAML 的声明式提取器架构提升至一级支持**。完全提取类、接口、枚举、对象、函数、方法和属性以及继承。 - **7 个新命令**: `roam congestion`、`roam adrs`、`roam flag-dead`、`roam test-scaffold`、`roam sbom`、`roam triage`、`roam ci-setup`。 - **CI 模板**: `roam ci-setup` 为 GitHub Actions、GitLab CI、Azure Pipelines、Jenkins 和 Bitbucket 生成流水线。 - **Bug 修复**: `intent` 中的 `--undocumented` 模式（错误的 DB 表）、`verify` 中的 `--changed` 标志（之前完全失效）、`visualize` 中的延迟加载违规（约 500ms 损耗）、`rules` 中的退出码不一致，在所有命令中强制执行 VERDICT-first 约定。 - **代码质量**: 移除了 15 个未使用的变量，清理了死代码（4 个孤立的 cmd 文件，2 个废弃的辅助函数），降低了 algo 检测器的误报率（循环中的正则表达式：从 7 降至 1，抑制了 list-prepend 的 deque），预编译了 6 个正则表达式以提升循环性能。 ### v11.0 -- 面向智能体优先工作流的 MCP v2 - 进程内 MCP 执行移除了每次调用的子进程开销。 - 4 个复合操作（`roam_explore`、`roam_prepare_change`、`roam_review_change`、`roam_diagnose_issue`）将多步骤的智能体工作流简化为单次调用。 - 基于预设的工具呈现（`core`、`review`、`refactor`、`debug`、`architecture`、`full`）在保持按需获取完整深度的同时，使智能体的默认工具选择保持精简。 - MCP 工具现在了结构化 schema 和更丰富的注解，以实现更安全的规划器行为。 - 默认核心上下文的 MCP token 开销从约 36K 降至 3K token 以下（减少约 92%）。 ### 性能与检索 - 符号搜索移至 SQLite FTS5/BM25：在索引队列中，典型搜索从数秒降至数十毫秒（实际效果因仓库大小和查询选择性而异 —— 有关方法请参见 `bench/retrieve/`）。 - 增量索引从 O(N) 的全边缘重建行为转变为 O(changed) 的更新。 - 数据库/运行时优化（`mmap_size`、更安全的大型图防护、批量写入）减少了较大仓库上首次运行和重新索引的摩擦。 ### CI、治理与交付 - GitHub Action 支持质量门控、SARIF 上传、持久性 PR 评论和缓存感知执行。 - CI 强化包括仅更改分析模式、趋势感知门控和 SARIF 上传前的防护措施（大小/结果上限 + 截断信号）。 - 智能体治理通过验证和 AI 质量工具（`roam verify`、`roam vibe-check`、`roam ai-readiness`、`roam ai-ratio`）得到了扩展，适用于管理智能体编写代码的团队。 ## 最佳适用场景 - **智能体辅助编程** —— 结构化答案减少了 token 使用量，优于原始文件探索 - **大型代码库（100+ 文件）** —— 图查询在大规模下优于线性搜索 - **架构治理** —— 健康评分、CI 质量门控、预算强制执行、适应度函数 - **安全重构** —— 爆炸半径、受影响的测试、更改前的安全检查、图级别编辑 - **多智能体编排** —— 以零冲突保证为并行智能体工作划分代码库 - **安全分析** —— 漏洞可达性映射、认证缺口、CVE 路径追踪 - **算法优化** —— 检测 O(n^2) 循环、N+1 查询和其他 21 种反模式并提供修复建议 - **后端质量** —— 认证缺口、缺失索引、过度获取模型、非幂等迁移、孤立路由、API 偏移 - **运行时分析** —— 将生产追踪数据叠加到静态图上进行热点检测 - **多仓库项目** —— 前后端之间的跨仓库 API 边缘检测 ### 何时不该使用 Roam - **实时类型检查** —— 使用 LSP（pyright、gopls、tsserver）。Roam 是静态且离线的。 - **小脚本（<10 个文件）** —— 直接阅读文件即可。 - **纯文本搜索** —— ripgrep 在原始字符串匹配方面更快。 ## 为什么使用 Roam **速度。** 一条命令取代 5-10 次工具调用（在典型工作流中）。任何查询均在 0.5 秒内完成。 **依赖感知。** 计算结构，而非字符串匹配。知道 `Flask` 有 47 个依赖者和 31 个受影响的测试。而 `grep` 只知道它出现了 847 次。 **为 LLM 优化的输出。** 纯 ASCII、紧凑缩写（`fn`、`cls`、`meth`）、`--json` 封装。专为智能体消费设计，而非人类装饰。 **完全本地运行。** 无需 API 密钥、遥测或网络调用。可在隔离网络环境中工作。 **算法感知。** 内置 23 种反模式目录。检测次优算法（二次循环、N+1 查询、无限递归）并建议带有 Big-O 改进和置信度分数的修复方案。接收器感知的循环不变量分析可将误报降至最低。 **为 CI 量身打造。** `--json` 输出、`--gate` 质量门控、GitHub Action、SARIF 2.1.0。 | | 不使用 Roam | 使用 Roam | |--|-------------|-----------| | 工具调用 | 8 | **1** | | 执行时间 | ~11s | **<0.5s** | | 消耗的 token | ~15,000 | **~3,000** | *在一个包含 200 个文件的 Python 项目 中测量。有关更多信息，请参见[基准测试](#performance)。*

目录

**入门指南:** [Roam 是什么？](#what-is-roam) · [v11 版本更新内容](#whats-new-in-v11) · [最佳适用场景](#best-for) · [为什么使用 Roam](#why-use-roam) · [安装](#install) · [快速开始](#quick-start) **使用 Roam:** [命令](#commands) · [演练](#walkthrough-investigating-a-codebase) · [AI 编程工具](#integration-with-ai-coding-tools) · [MCP 服务器](#mcp-server) **运维指南:** [CI/CD 集成](#cicd-integration) · [SARIF 输出](#sarif-output) · [面向团队](#for-teams) **参考资料:** [语言支持](#language-support) · [性能表现](#performance) · [工作原理](#how-it-works) · [Roam 对比](#how-roam-compares) · [常见问题](#faq) **更多内容:** [局限性](#limitations) · [故障排除](#troubleshooting) · [更新 / 卸载](#update--uninstall) · [开发](#development) · [贡献](#contributing)

## 安装 ``` pip install roam-code # 推荐：isolated environment pipx install roam-code # 或 uv tool install roam-code # From source pip install git+https://github.com/Cranot/roam-code.git ``` 需要 Python 3.9+。适用于 Linux、macOS 和 Windows。 ### Docker (基于 alpine) ``` docker build -t roam-code . docker run --rm -v "$PWD:/workspace" roam-code index docker run --rm -v "$PWD:/workspace" roam-code health ``` ## 快速开始 ``` cd your-project roam init # indexes codebase, creates config + CI workflow roam understand # full codebase briefing ``` 首次索引对于 200 个文件大约需要 5 秒，对于 1,000 个文件大约需要 15 秒。后续运行为增量执行，几乎是即时的。 **下一步操作：** - **设置你的 AI 智能体：** `roam describe --write`（自动检测 CLAUDE.md、AGENTS.md、.cursor/rules 等 —— 详见[集成指南](#integration-with-ai-coding-tools)） - **探索：** `roam health` → `roam weather` → `roam map` - **添加到 CI：** `roam init` 已生成一个 GitHub Action

在 Roam 本身上尝试

``` git clone https://github.com/Cranot/roam-code.git cd roam-code pip install -e . roam init roam understand roam health ```

## 支持工具

Claude Code • Cursor • Windsurf • GitHub Copilot • Aider • Cline • Gemini CLI • OpenAI Codex CLI • MCP • GitHub Actions • GitLab CI • Azure DevOps

## 命令 **从这 5 个动词开始。** [5 个核心命令](#core-commands)涵盖了约 80% 的智能体工作流：`understand`、`context`、`retrieve`、`preflight`、`critique`。剩余的 149 个命令是用于特定工作流的详细接口（taint、fleet、cga、oracle、eval 等） —— 它们由智能体按需调用，无需记忆。这是有意为之的设计；在底层，规范接口是 **154 个命令分为 7 个类别**，但你不需要在开始时就了解这些。

完整命令参考

### 入门指南 | 命令 | 描述 | |---------|-------------| | `roam index [--force] [--verbose]` | 构建或重建代码库索引 | | `roam index-export [--sign] [--key K] [--keyless]` | 将已索引的 `.roam/index.db` 导出为经过签名和完整性检查的 tarball。对标 Cursor 的“复用队友的索引”而无需供应商云。 | | `roam index-import [--force] [--cosign-bundle B] [--cosign-key K]` | 导入可移植的索引包。验证 manifest sha256 + 可选的 cosign 签名；不带 `--force` 将拒绝覆盖。 | | `roam watch [--interval N] [--debounce N] [--webhook-port P] [--guardian]` | 长期运行的索引守护进程：轮询/Webhook 触发的刷新，加上可选的持续架构守护快照和 JSONL 合规产物 | | `roam init` | 引导式上手：创建 `.roam/fitness.yaml`、CI 工作流、运行索引、显示健康状况 | | `roam hooks [--install] [--uninstall]` | 管理 git 钩子，用于自动执行 roam 索引更新和健康门控 | | `roam doctor` | 诊断安装和环境：验证 tree-sitter 语法、SQLite、git 和配置健康状况 | | `roam reset [--hard]` | 重置 roam 索引和缓存数据。`--hard` 移除所有 `.roam/` 产物 | | `roam clean [--all]` | 移除过期或孤立的索引条目，无需完全重建 | | `roam understand` | 完整的代码库简报：技术栈、架构、关键抽象、健康状况、约定、复杂度概述、入口点 | | `roam onboard` | `understand` 的别名 | | `roam tour [--write PATH]` | 自动生成的上手指南：顶级符号、阅读顺序、入口点、语言分布。`--write` 保存为 Markdown | | `roam describe [--write] [--force] [-o PATH] [--agent-prompt]` | 为 AI 智能体自动生成项目描述。`--write` 自动检测智能体的配置文件。`--agent-prompt` 返回一个紧凑的（<500 token）系统提示 | | `roam agent-export [--format F] [--write]` | 根据项目分析（`AGENTS.md` + 供应商特定的叠加层）生成智能体上下文包 | | `roam minimap [--update] [-o FILE] [--init-notes]` | 用于智能体配置注入的紧凑型带注释代码库快照：技术栈、带注释的目录树、按 PageRank 排列的关键符号、需要避免触及的高扇入符号、热点、约定。基于哨兵的就地更新 | | `roam config [--set-db-dir PATH] [--semantic-backend MODE]` | 管理 `.roam/config.json`（DB 路径、排除项、可选的 ONNX 语义设置） | | `roam map [-n N] [--full] [--budget N]` | 项目骨架：文件、语言、入口点、按 PageRank 排列的顶级符号。`--budget` 将输出上限设为 N 个 token | | `roam schema [--diff] [--version V]` | JSON 封装 schema 版本控制：查看、比较和验证输出 schema | | `roam mcp [--list-tools] [--transport T]` | 启动 MCP 服务器、检查可用工具，并将 roam 暴露给编程智能体 | | `roam mcp-setup ` | 为 AI 平台生成 MCP 配置片段：claude-code、cursor、windsurf、vscode、gemini-cli、codex-cli | | `roam ci-setup [--platform P] [--write]` | 生成 CI/CD 流水线配置，附带 SARIF + 质量门控 | | `roam adrs [--status S] [--limit N]` | 发现架构决策记录 (ADR)，链接到受影响的代码模块，显示状态和覆盖率 | ### 日常工作流 | 命令 | 描述 | |---------|-------------| | `roam file [--full] [--changed] [--deps-of PATH]` | 文件骨架：所有定义及其签名、认知负荷指数、健康评分 | | `roam symbol [--full]` | 符号定义 + 调用者 + 被调用者 + 指标。支持 `file:symbol` 消歧 | | `roam context [--task MODE] [--for-file PATH]` | AI 优化的上下文：定义 + 调用者 +被调用者 + 需要读取的文件及行范围 | | `roam hover ` | 单行架构摘要：类型、位置、爆炸半径级别、顶级调用者、顶级被调用者。上限约为 200 个 token，专为 IDE 悬停面板设计 | | `roam retrieve [--budget N] [--k N] [--seed-files PATH]` | 针对自由格式任务的图感知上下文：FTS5 + 结构化重排 (PageRank + 克隆) + token 预算 | | `roam critique [--input DIFF] [--intent TEXT] [--high-callers N]` | 对照图验证补丁：未编辑的克隆 + 爆炸半径 + 意图与语义 diff 对比。通过管道传入 `git diff`。高严重性时以退出码 5 退出。 | | `roam fleet plan [--n-agents N] [--adapter raw\|composio\|copilot]` | 图感知规划器：Louvain 分区 + 共变 + PageRank 锚点 → 为 Composio/Copilot CLI/raw 生成 `.roam-fleet.json`。 | | `roam ask [--list] [--explain] [--recipe NAME]` | 针对 12 种方案注册表的单短语意图分类器 —— 组合 preflight/retrieve/critique/fleet/understand/diagnose/trace/trends/hotspots/debt/taint/dead/coupling 以涵盖最常见的工作流。 | | `roam taint [--rules-dir PATH] [--rule NAME] [--ci]` | 图可达污点分析，带有 OpenVEX-correct VEX 证明。YAML 规则包（5 条启动规则：Python 命令注入 / SQLi / 路径遍历、JS XSS / SSRF）。 | | `roam cga emit [--include-taint] [--sign --key]` | Code Graph Attestation —— 带有 `roam-code.dev/CodeGraph/v1` 断言、Merkle 根 + 边缘包摘要的 in-toto v1 声明。`--include-taint` 嵌入来自 `roam taint` 的 OpenVEX 格式的可达性声明。`--sign` 使用 cosign 签名（如不存在则优雅跳过）；`roam cga verify` 往返验证断言摘要和 cosign 签名。 | | `roam eval-retrieve [--tasks FILE] [--sweep] [--min-recall-at-20 N] [--emit-format coderag\|beir]` | `roam retrieve` 的 Recall@K 评估工具 —— 根据 JSONL 真值文件进行测量。可作为 CI 门控。`--emit-format coderag` 写入兼容 CodeRAG-Bench 的运行文件，用于公共排行榜提交。 | | `roam oracle ` | 面向智能体的布尔预言机 —— 1-token 的 是/否 回答。子命令：`symbol-exists`、`route-exists`、`is-test-only`、`is-reachable-from-entry`、`is-clone-of`。 | | `roam search [--kind KIND]` | 按名称模式查找符号，根据 PageRank 排名 | | `roam grep [-g glob] [-n N]` | 带有封闭符号上下文注释的文本搜索 | | `roam deps [--full]` | 一个文件导入了什么以及什么导入了它 | | `roam trace [-k N]` | 带有耦合强度和枢纽检测的依赖路径 | | `roam impact ` | 爆炸半径：如果符号发生更改会破坏什么（加权个性化 PageRank） | | `roam diff [--staged] [--full] [REV_RANGE]` | 未提交更改或提交范围的爆炸半径 | | `roam pr-risk [REV_RANGE]` | PR 风险评分（0-100，乘法模型）+ 结构扩散 + 建议的审查者 | | `roam pr-diff [--staged] [--range R] [--format markdown]` | 结构化 PR diff：度量增量、边缘分析、符号更改、足迹。不是文本 diff —— 而是图增量 | | `roam api-changes [REV_RANGE]` | API 更改分类器：破坏性/非破坏性更改、严重性以及受影响的契约 | | `roam semantic-diff [REV_RANGE]` | 结构化更改摘要：添加/移除/修改的符号及已更改的调用边缘 | | `roam test-gaps [REV_RANGE]` | 已更改符号的测试缺口检测：哪些发生了更改以及哪些仍缺少测试覆盖 | | `roam affected [REV_RANGE]` | Monorepo/包影响分析：哪些组件受到了更改的影响 | | `roam attest [REV_RANGE] [--format markdown] [--sign]` | 携带证明的 PR 认证：将爆炸半径、风险、破坏性更改、适应度、预算、测试、影响捆绑到一个可验证的产物中 | | `roam annotate ` | 将持久化笔记附加到符号（跨会话的智能体记忆） | | `roam annotations [--file F] [--symbol S]` | 查看已保存的注释 | | `roam diagnose [--depth N]` | 根本原因分析：通过 z-score 标准化风险对嫌疑对象进行排名 | | `roam preflight ` | 复合更改前检查：爆炸半径 + 测试 + 复杂度 + 耦合 + 适应度 | | `roam guard ` | 紧凑的子智能体预检包：定义、1 跳调用者/被调用者、测试文件、破坏风险评分和层信号 | | `roam agent-plan --agents N` | 将分区分解为依赖排序的智能体任务，附带合并排序和交接 | | `roam agent-context --agent-id N [--agents M]` | 生成每个智能体的执行上下文：写入范围、只读依赖和接口契约 | | `roam syntax-check [--changed] [PATHS...]` | 对已更改文件和多智能体判断工作流进行 tree-sitter 语法完整性检查 | | `roam verify [--threshold N]` | 提交前的 AI 代码一致性检查，涵盖命名、导入、错误处理和重复信号 | | `roam verify-imports [--file F]` | 导入幻觉防火墙：根据已索引的符号表验证所有导入，通过 FTS5 模糊匹配建议更正 | | `roam triage list\|add\|stats\|check` | 安全发现抑制工作流：管理 `.roam-suppressions.yml`（SAFE/ACKNOWLEDGED/WONT-FIX 状态生命周期） | | `roam safe-delete ` | 安全删除检查：SAFE/REVIEW/UNSAFE 判定 | | `roam test-map ` | 将符号或文件映射到其测试覆盖范围 | | `roam adversarial [--staged] [--range R]` | 对抗性架构审查：根据更改生成有针对性的挑战 | | `roam plan [--staged] [--range R] [--agents N]` | 智能体工作规划器：将更改分解为有序的、感知依赖的步骤 | | `roam closure [--rename] [--delete]` | 最小更改合成：安全重命名/删除所需触及的所有文件 | | `roam mutate move\|rename\|add-call\|extract` | 图级别代码编辑：移动符号、在代码库中重命名、添加调用、提取函数。默认为干运行 | ### 代码库健康状况 | 命令 | 描述 | |---------|-------------| | `roam health [--no-framework] [--gate]` | 综合健康评分（0-100）：缠结比、上帝组件、瓶颈、层级违规的加权几何平均值。`--gate` 从 `.roam-gates.yml` 运行质量门控检查（失败时以退出码 5 退出） | | `roam smells [--file F] [--min-severity S]` | 代码坏味道检测：15 个确定性检测器（大脑方法、上帝类、特性依恋、散弹式修改、数据泥团等）及每个文件的健康评分 | | `roam dashboard` | 统一的单屏项目状态：健康状况、热点、风险、所有权和 AI 腐化指标 | | `roam vibe-check [--threshold N]` | AI 腐化审计器：8 种模式分类法及复合风险评分和优先发现项 | | `roam ai-readiness` | 0-100 评分，衡量此代码库对 AI 编程智能体的支持程度 | | `roam ai-ratio [--since N]` | 使用提交行为信号统计估算的 AI 生成代码比例 | | `roam trends [--record] [--days N] [--metric M]` | 带有迷你图和趋势增量的历史指标快照 | | `roam complexity [--bumpy-road] [--include-tooling]` | 每个函数的认知复杂度（兼容 SonarSource，三角形嵌套惩罚） + Halstead 指标（容量、难度、工作量、bug数） + 圈复杂密度 | | `roam py-types [--detail] [--include-tests] [--ci --min-coverage N]` | Python 类型注解健康状况：完整注解的公共函数百分比、``Any`` 的使用情况、旧版 ``typing.Optional/Dict/List``（PEP 585/604 现代化候选项）、每个文件最严重的违规者。可通过 ``--ci --min-coverage N`` 作为 CI 门控（低于阈值时以退出码 5 退出）。默认排除测试文件 | | `roam py-modern [--detail]` | 现代 Python 采用信号：统计海象运算符 (PEP 572)、match 语句 (PEP 634)、PEP 604 ``X \| None``、PEP 585 ``dict[…]``、PEP 695 类型别名、f-strings 与 ``.format()`` 的使用情况。报告类型现代化百分比和 f-string 采用百分比以评估迁移进度 | | `roam pytest-fixtures [SYMBOL] [--max-depth N]` | pytest fixture 链清单。不带 SYMBOL 时，打印项目范围的 fixture 数量和按依赖数量排名的顶级 fixture。带有 fixture 或测试名称时，遍历隐式的 fixture 参数依赖图以显示每个测试传递性需要什么。通过 ``conftest.py`` 链进行解析 | | `roam algo [--task T] [--confidence C] [--profile P]` | 算法反模式检测：23 种模式目录可检测次优算法（O(n^2) 循环、N+1 查询、二次字符串构建、分支递归、循环不变量调用）并建议带有 Big-O 改进的更好方法。通过调用次数 + 运行时追踪进行置信度校准、证据路径、影响评分、感知框架的 N+1 包以及感知语言的修复模板。别名：`roam math` | | `roam n1 [--confidence C] [--verbose]` | 隐式 N+1 I/O 检测：发现在集合上下文中触发延迟加载 DB 查询的 ORM 模型计算属性（`$appends`/访问器）。与预先加载配置交叉引用。支持 Laravel、Django、Rails、SQLAlchemy、JPA | | `roam over-fetch [--threshold N] [--confidence C]` | 检测序列化过多字段的模型：没有 `$hidden`/`$visible` 的大型 `$fillable`、绕过 API Resources 直接返回的控制器、较差的暴露与隐藏比 | | `roam missing-index [--table T] [--confidence C]` | 查找非索引列上的查询：将 `WHERE`/`ORDER BY` 子句、外键和分页查询与迁移定义的索引进行交叉引用 | | `roam weather [-n N]` | 按变动量与复杂度的几何平均值（百分位标准化）排名的热点 | | `roam debt [--roi]` | 带有 SQALE 修复成本和可选重构 ROI 估算的、按热点加权的技术债务优先级排序 | | `roam fitness [--explain]` | 来自 `.roam/fitness.yaml` 的架构适应度函数 | | `roam alerts` | 健康状况恶化趋势检测（Mann-Kendall + Sen's slope） | | `roam forecast [--symbol S] [--horizon N] [--alert-only]` | 预测指标何时将超出阈值：基于快照历史的 Theil-Sen 回归 + 按变动量加权的每个符号的风险 | | `roam budget [--init] [--staged] [--range R]` | 架构预算强制执行：每个 PR 对健康状况、循环、复杂度的增量限制。CI 门控（违规时以退出码 5 退出） | | `roam bisect [--metric M] [--range R]` | 架构 git 二分查找：找到导致特定指标下降的提交 | | `roam ingest-trace [--otel\|--jaeger\|--kin\|--generic]` | 引入运行时追踪数据用于热点叠加 | | `roam hotspots [--runtime] [--discrepancy]` | 运行时热点分析：查找静态分析遗漏但在运行时关键的符号 |

roam algo — 算法反模式目录 (23 种模式)

`roam algo` 根据包含 23 种模式的目录扫描每个已索引的函数，按感知运行时的影响分数对发现进行排名，并显示可用的确切 Big-O 改进。发现包括语义证据路径、精度元数据以及感知语言的提示/修复： ``` $ roam algo VERDICT: 8 algorithmic improvements found (3 high, 4 medium, 1 low) Ordering: highest impact first Profile: balanced (filtered 0 low-signal findings) Nested loop lookup (2): fn resolve_permissions src/auth/rbac.py:112 [high, impact=86.4] Current: Nested iteration -- O(n*m) Better: Hash-map join -- O(n+m) Tip: Build a dict/set from one collection, iterate the other fn find_matching_rule src/rules/engine.py:67 [high, impact=78.1] Current: Nested iteration -- O(n*m) Better: Hash-map join -- O(n+m) Tip: Build a dict/set from one collection, iterate the other String building (1): meth build_query src/db/query.py:88 [high, impact=74.0] Current: Loop concatenation -- O(n^2) Better: Join / StringBuilder -- O(n) Tip: Collect parts in a list, join once at the end Branching recursion without memoization (1): fn compute_cost src/pricing/calc.py:34 [medium, impact=49.5] Current: Naive branching recursion -- O(2^n) Better: Memoized / iterative DP -- O(n) Tip: Add @cache / @lru_cache, or convert to iterative with a table ``` **完整目录 — 23 种模式：** | 模式 | 检测到的反模式 | 更好的方法 | 改进效果 | |---------|----------------------|-----------------|-------------| | 嵌套循环查找 | `for x in a: for y in b: if x==y` | Hash-map join | O(n·m) → O(n+m) | | 成员测试 | `if x in list` in a loop | Set lookup | O(n) → O(1) 每次检查 | | 排序 | 冒泡 / 选择排序 | 内置排序 | O(n²) → O(n log n) | | 已排序数据中的搜索 | 已排序序列上的线性扫描 | Binary search | O(n) → O(log n) | | 字符串构建 | `s += chunk` in loop | `join()` / StringBuilder | O(n²) → O(n) | | 去重 | 嵌套循环去重 | `set()` / `dict.fromkeys` | O(n²) → O(n) | | 最大 / 最小 | 手动追踪循环 | `max()` / `min()` | 习惯用法 | | 累加 | 手动累加器 | `sum()` / `reduce()` | 习惯用法 | | 按键分组 | 手动键存在性检查 | `defaultdict` / `groupingBy` | 习惯用法 | | 斐波那契 | 朴素递归 | 迭代法 / `@lru_cache` | O(2ⁿ) → O(n) | | 指数运算 | 循环乘法 | `pow(b, e, mod)` | O(n) → O(log n) | | GCD | 手动循环 | `math.gcd()` | O(n) → O(log n) | | 矩阵乘法 | 朴素三重循环 | NumPy / BLAS | 相同的渐近复杂度，通过 SIMD 约提速 1000× | | 忙等待 | `while True: sleep()` 轮询 | 事件 / 条件变量 | O(k) → O(1) 唤醒 | | 循环中的正则表达式 | `re.match()` 每次迭代编译一次 | 预编译模式 | O(n·(p+m)) → O(p + n·m) | | N+1 查询 | 循环中每个项目的 DB / API 调用 | 批量 `WHERE IN (...)` | n 次往返 → 1 次 | | 列表前端操作 | `list.insert(0, x)` in loop | `collections.deque` | O(n) → O(1) 每次操作 | | 排序选择 | `sorted(x)[0]` 或 `sorted(x)[:k]` | `min()` / `heapq.nsmallest` | O(n log n) → O(n) 或 O(n log k) | | 重复查找 | 循环内的 `.index()` / `.contains()` | 预构建的 set / dict | O(m) → O(1) 每次查找 | | 分支递归 | 不带缓存的朴素 `f(n-1) + f(n-2)` | `@cache` / 迭代 DP | O(2ⁿ) → O(n) | | 二次字符串构建 | 跨多个作用域的 `result += chunk` | `parts.append` + 最后 `join` | O(n²) → O(n) | | 循环不变量调用 | 循环体内的 `get_config()` / `compile_schema()` | 提取到循环前 | 每次迭代的代价 → O(1) | | 字符串反转 | 手动逐字符循环 | `s[::-1]` / `.reverse()` | 习惯用法 | **过滤：** ``` roam algo --task nested-lookup # one pattern type only roam algo --confidence high # high-confidence findings only roam algo --profile strict # precision-first filtering roam algo --task io-in-loop -n 5 # top 5 N+1 query sites roam --json algo # machine-readable output roam --sarif algo > roam-algo.sarif # SARIF with fingerprints + fixes ``` **置信度校准：** `high` = 强烈的结构信号（无限循环 + 高调用者/运行时影响 + 模式已确认）；`medium` = 模式匹配但存在不确定性；`low` = 仅为启发式信号。 **配置文件：** `balanced`（默认）、`strict`（精确度优先）、`aggressive`（呈现更多候选者）。

roam minimap — 用于智能体配置的带注释代码库快照

`roam minimap` 生成一个紧凑块（技术栈、带注释的目录树、关键符号、热点、约定），包裹在哨兵注释中，用于就地智能体配置更新： ``` $ roam minimap **Stack:** Python · JavaScript · YAML ``` .github/ (CI + Action) benchmarks/ (agent-eval + oss-eval) src/ roam/ bridges/ base.py # LanguageBridge registry.py # register_bridge, detect_bridges commands/ (137 cmd files) # is_test_file, get_changed_files db/ connection.py # find_project_root, batched_in schema.py graph/ builder.py # build_symbol_graph, build_file_graph pagerank.py # compute_pagerank, compute_centrality languages/ (21 files) # ApexExtractor output/ formatter.py # to_json, json_envelope cli.py # cli, LazyGroup mcp_server.py tests/ (186 files) ` ` ` **关键符号** (PageRank): `open_db` · `ensure_index` · `json_envelope` · `to_json` · `LanguageExtractor` **谨慎触及** (扇入 >= 15): `to_json` (116 调用者) · `json_envelope` (116 调用者) · `open_db` (105 调用者) · `ensure_index` (100 调用者) **热点** (变动量与复杂度): `cmd_context.py` · `csharp_lang.py` · `cmd_dead.py` **约定:** snake_case 函数, PascalCase 类 ``` **Workflow:** ```bash roam minimap # print to stdout roam minimap --update # replace sentinel block in CLAUDE.md in-place roam minimap -o docs/AGENTS.md # target a different file roam minimap --init-notes # scaffold .roam/minimap-notes.md for project gotchas ``` 哨兵对 `` / `` 在每次运行时会被替换 —— 周围的内容保持不变。将项目特定的注意事项添加到 `.roam/minimap-notes.md`，它们将出现在每次后续输出中。 **树注释** 来自每个文件按扇入度排名的顶级导出符号。非源码根目录（`.github/`、`benchmarks/`、`docs/`）会立即折叠。大型子目录（例如 `commands/`、`languages/`）会在深度 2+ 处折叠并带有文件计数。

### 架构 | 命令 | 描述 | |---------|-------------| | `roam clusters [--min-size N]` | 社区发现与目录结构对比。模块性 Q 分数 (Newman 2004) + 每个集群的电导 | | `roam spectral [--depth N] [--compare] [--gap-only] [--k K]` | 谱二分法：带有代数连通性间隙判定的 Fiedler 向量分区树 | | `roam layers` | 拓扑依赖层 + 向上违规 + 基尼均衡 | | `roam dead [--all] [--summary] [--clusters]` | 带有安全性判定 + 置信度评分（60-95%）的未引用导出符号 | | `roam flag-dead [--config FILE] [--include-tests]` | 功能开关死代码检测：带有过期分析的陈旧 LaunchDarkly/Unleash/Split/自定义标志 | | `roam fan [symbol\|file] [-n N] [--no-framework]` | 扇入/扇出：连接最多的符号或文件 | | `roam risk [-n N] [--domain KW] [--explain]` | 领域加权风险排名 | | `roam why [name2 ...]` | 角色分类（Hub/Bridge/Core/Leaf）、可达性、关键性 | | `roam split ` | 内部符号分组及隔离百分比和提取建议 | | `roam entry-points` | 带有协议分类的入口点目录 | | `roam patterns` | 架构模式识别：Strategy、Factory、Observer 等 | | `roam visualize [--format mermaid\|dot] [--focus NAME] [--limit N]` | 生成 Mermaid 或 DOT 架构图。通过 PageRank 进行智能过滤、集群分组、循环高亮 | | `roam effects [TARGET] [--file F] [--type T]` | 副作用分类：DB 写入、网络 I/O、文件系统、全局修改。通过调用图追踪直接和传递性影响 | | `roam dark-matter [--min-cochanges N]` | 检测无法由导入/调用边缘解释的隐藏共变耦合 | | `roam simulate move\|extract\|merge\|delete` | 反事实架构模拟器：在内存中测试重构想法，在编写代码前查看度量增量 | | `roam orchestrate --agents N [--files P]` | 多智能体集群分区：以零冲突保证拆分代码库供并行智能体工作 | | `roam partition [--agents N]` | 多智能体分区清单：冲突风险、复杂度和建议的所有权分配 | | `roam fingerprint [--compact] [--compare F]` | 拓扑指纹：跨仓库提取/比较架构特征 | | `roam cut [--depth N]` | 最小图割：找到移除后会断开组件连接的关键边缘 | | `roam safe-zones` | 基于图的包容边界 | | `roam coverage-gaps` | 没有通往门控符号路径的未受保护入口点 | | `roam duplicates [--threshold T] [--min-lines N]` | 语义重复检测器：具有不同边缘情况处理的、功能等效的代码集群 | | `roam clones [--threshold T] [--min-lines N] [--scope P]` | AST 结构化克隆检测：通过子树哈希查找 Type-2 克隆（比 `duplicates` 更精确） | ### 探索 | 命令 | 描述 | |---------|-------------| | `roam module ` | 目录内容：导出、签名、依赖、内聚性 | | `roam sketch [--full]` | 目录的紧凑结构骨架 | | `roam uses ` | 所有消费者：调用者、导入者、继承者 | | `roam owner ` | 代码所有权：谁拥有一个文件或目录 | | `roam coupling [-n N] [--set]` | 时间耦合：一起更改的文件对（NPMI + lift） | | `roam fn-coupling` | 跨文件的函数级时间耦合 | | `roam bus-factor [--brain-methods]` | 每个模块的知识流失风险 | | `roam doc-staleness` | 检测陈旧的 docstring | | `roam docs-coverage` | 公共符号文档覆盖 + 陈旧文档 + 按 PageRank 排名的缺失文档热点列表 | | `roam suggest-refactoring [--limit N] [--min-score N]` | 根据复杂度、耦合、变动、坏味道、覆盖缺口和债务排名的主动重构建议 | | `roam plan-refactor [--operation auto\|extract\|move]` | 带有爆炸半径、测试缺口、层级风险和基于模拟的策略预览的有序重构计划 | | `roam test-scaffold [--write] [--framework F]` | 从符号数据生成测试文件/函数/导入骨架（pytest、jest、Go、JUnit、RSpec） | | `roam conventions` | 自动检测命名风格、导入偏好。标记异常值 | | `roam breaking [REV_RANGE]` | 破坏性更改检测：移除的导出、签名更改 | | `roam affected-tests ` | 将反向调用图追踪到测试文件 | | `roam relate ` | 显示两个符号之间的关系：共享调用者、最短路径、共同祖先 | | `roam endpoints [--routes] [--api]` | 枚举所有 HTTP/API 端点定义，并呈现它们以供审查或跨仓库匹配 | | `roam metrics ` | 统一的生命体征：复杂度、扇入/扇出、PageRank、变动、测试覆盖、死代码风险 —— 尽在一次调用中 | | `roam search-semantic ` | 混合语义搜索：BM25 + TF-IDF + 可选的本地 ONNX 向量（通过 `--backend` 选择）及框架/库包 | | `am intent [--staged] [--range R]` | 文档到代码链接：将文档匹配到符号，检测偏移 | | `roam x-lang [--bridges] [--edges]` | 跨语言边缘浏览器：检查桥接解析的连接 | ### 报告与 CI | 命令 | 描述 | |---------|-------------| | `roam report [--list] [--config FILE] [PRESET]` | 复合预设：`first-contact`、`security`、`pre-pr`、`refactor`、`guardian` | | `roam describe --write` | 生成智能体配置（自动检测：CLAUDE.md、AGENTS.md、.cursor/rules 等） | | `roam auth-gaps [--routes-only] [--controllers-only] [--min-confidence C]` | 查找缺少身份验证或授权的端点：身份验证中间件组之外的路由、没有 `$this->authorize()` / `Gate::allows()` 检查的 CRUD 方法。感知字符串的 PHP 花括号解析 | | `roam orphan-routes [-n N] [--confidence C]` | 检测没有前端消费者的后端路由：解析路由定义，在前端搜索 API 调用引用，报告没有路由映射的控制器方法 | | `roam migration-safety [-n N] [--include-archive]` | 检测非幂等迁移：缺少 `hasTable`/`hasColumn` 守卫、没有 `IF NOT EXISTS` 的原始 SQL、没有存在性检查的索引操作 | | `roam api-drift [--model M] [--confidence C]` | 检测 PHP 模型的 `$fillable`/`$appends` 字段与 TypeScript 接口属性之间的不匹配。自动转换 snake_case/camelCase 以进行比较。单仓库；跨仓库计划在 `roam ws api-drift` 中支持 | | `roam codeowners [--unowned] [--owner NAME]` | CODEOWNERS 覆盖率分析：已拥有/未拥有的文件、顶级拥有者和所有权风险 | | `roam drift [--threshold N]` | 所有权偏移检测：声明的所有权与观察到的维护活动对比 | | `roam suggest-reviewers [REV_RANGE]` | 通过所有权、近期性、广度和影响信号推荐审查人 | | `roam simulate-departure ` | 知识流失模拟：如果关键贡献者离开会破坏什么 | | `roam dev-profile [--developer NAME] [--since N]` | 开发者生产力概况：每位贡献者的提交模式、专业化、影响力和知识集中度 | | `roam secrets [--fail-on-found] [--include-tests]` | 带有掩码、熵检测、环境变量抑制、修复建议和可选 CI 门控失败的秘密扫描 | | `roam vulns [--import-file F] [--reachable-only]` | 漏洞扫描：引入 npm/pip/trivy/osv 报告，自动检测格式，可达性过滤，SARIF 输出 | | `roam path-coverage [--from P] [--to P] [--max-depth N]` | 查找零测试保护的关键调用路径（入口 -> 汇聚点）。建议最佳测试插入点 | | `roam capsule [--redact-paths] [--no-signatures] [--output F]` | 导出经过脱敏的结构图（无代码主体），用于外部的架构审查 | | `roam rules [--init] [--ci] [--rules-dir D]` | 用于治理的插件 DSL：通过 `.roam/rules/` YAML 定义的用户路径/符号/AST 规则（支持 `$METAVAR` 捕获） | | `roam check-rules [--severity S] [--fix]` | 评估内置和用户定义的治理规则（10 条内置规则：no-circular-imports、max-fan-out 等） | | `roam vuln-map --generic\|--npm-audit\|--trivy F` | 引入漏洞报告并匹配到代码库符号 | | `roam vuln-reach [--cve C] [--from E]` | 漏洞可达性：从入口点到易受攻击调用的确切路径 | | `roam supply-chain [--top N]` | 依赖风险仪表盘：锁定覆盖率、风险评分、供应链健康状况 | | `roam sbom [--format cyclonedx\|spdx] [--no-reachability] [-o FILE]` | 富含每个依赖项调用图可达性的 SBOM 生成（CycloneDX 1.5 / SPDX 2.3） | | `roam congestion [--window N] [--min-authors N]` | 开发者拥堵检测：每个文件的并发作者、协调风险评分 | | `roam invariants [--staged] [--range R]` | 从代码库结构中发现架构契约（不变量） | ### 多仓库工作区 | 命令 | 描述 | |---------|-------------| | `roam ws init [--name NAME]` | 从同级仓库初始化工作区。自动检测前端/后端角色 | | `roam ws status` | 显示工作区仓库、索引老化时间、跨仓库边缘数量 | | `roam ws resolve` | 扫描 REST API 端点并将前端调用与后端路由匹配 | | `roam ws understand` | 统一的工作区概览：每个仓库的统计 + 跨仓库连接 | | `roam ws health` | 带有跨仓库耦合评估的整个工作区健康报告 | | `roam ws context ` | 跨仓库增强上下文：跨仓库查找符号 + 显示 API 调用者 | | `roam ws trace ` | 通过 API 边缘追踪跨仓库路径 | ### 全局选项 | 选项 | 描述 | |--------|-------------| | `roam --json ` | 带有一致封装的结构化 JSON 输出 | | `roam --compact ` | 高效利用 token 的输出：TSV 表、最小 JSON 封装 | | `roam --sarif ` | 用于 dead、health、complexity、rules、secrets、algo、py-types、py-modern 的 SARIF 2.1.0 输出（GitHub/CI 集成） | | `roam health --gate` | CI 质量门控。读取 `.roam-gates.yml` 阈值。失败时以退出码 5 退出 |

## 演练：调查代码库

以 Flask 为例的 10 步演练（点击展开）

以下是如何使用 Roam 来了解你从未见过的项目。以 Flask 为例： **第 1 步：上手并获取全局视角** ``` $ roam init Created .roam/fitness.yaml (6 starter rules) Created .github/workflows/roam.yml Done. 226 files, 1132 symbols, 233 edges. Health: 78/100 $ roam understand Tech stack: Python (flask, jinja2, werkzeug) Architecture: Monolithic — 3 layers, 5 clusters Key abstractions: Flask, Blueprint, Request, Response Health: 78/100 — 1 god component (Flask) Entry points: src/flask/__init__.py, src/flask/cli.py Conventions: snake_case functions, PascalCase classes, relative imports Complexity: avg 4.2, 3 high (>15), 0 critical (>25) ``` **第 2 步：深入关键文件** ``` $ roam file src/flask/app.py src/flask/app.py (python, 963 lines) cls Flask(App) :76-963 meth __init__(self, import_name, ...) :152 meth route(self, rule, **options) :411 meth register_blueprint(self, blueprint, ...) :580 meth make_response(self, rv) :742 ...12 more methods ``` **第 3 步：谁依赖于此？** ``` $ roam deps src/flask/app.py Imported by: file symbols -------------------------- ------- src/flask/__init__.py 3 src/flask/testing.py 2 tests/test_basic.py 1 ...18 files total ``` **第 4 步：查找热点** ``` $ roam weather === Hotspots (churn x complexity) === Score Churn Complexity Path Lang ----- ----- ---------- ---------------------- ------ 18420 460 40.0 src/flask/app.py python 12180 348 35.0 src/flask/blueprints.py python ``` **第 5 步：检查架构健康状况** ``` $ roam health Health: 78/100 Tangle: 0.0% (0/1132 symbols in cycles) 1 god component (Flask, degree 47, actionable) 0 bottlenecks, 0 layer violations === God Components (degree > 20) === Sev Name Kind Degree Cat File ------- ----- ---- ------ --- ------------------ WARNING Flask cls 47 act src/flask/app.py ``` **第 6 步：获取符号的 AI 就绪上下文** ``` $ roam context Flask Files to read: src/flask/app.py:76-963 # definition src/flask/__init__.py:1-15 # re-export src/flask/testing.py:22-45 # caller: FlaskClient.__init__ tests/test_basic.py:12-30 # caller: test_app_factory ...12 more files Callers: 47 Callees: 3 ``` **第 7 步：更改前的安全检查** ``` $ roam preflight Flask === Preflight: Flask === Blast radius: 47 callers, 89 transitive Affected tests: 31 (DIRECT: 12, TRANSITIVE: 19) Complexity: cc=40 (critical), nesting=6 Coupling: 3 hidden co-change partners Fitness: 1 violation (max-complexity exceeded) Verdict: HIGH RISK — consider splitting before modifying ``` **第 8 步：分解大文件** ``` $ roam split src/flask/app.py === Split analysis: src/flask/app.py === 87 symbols, 42 internal edges, 95 external edges Cross-group coupling: 18% Group 1 (routing) — 12 symbols, isolation: 83% [extractable] meth route L411 PR=0.0088 meth add_url_rule L450 PR=0.0045 ... === Extraction Suggestions === Extract 'routing' group: route, add_url_rule, endpoint (+9 more) 83% isolated, only 3 edges to other groups ``` **第 9 步：理解为什么某个符号很重要** ``` $ roam why Flask url_for Blueprint Symbol Role Fan Reach Risk Verdict --------- ------------ ---------- -------- -------- -------------------------------------------------- Flask Hub fan-in:47 reach:89 CRITICAL God symbol (47 in, 12 out). Consider splitting. url_for Core utility fan-in:31 reach:45 HIGH Widely used utility (31 callers). Stable interface. Blueprint Bridge fan-in:18 reach:34 moderate Coupling point between clusters. ``` **第 10 步：生成文档并设置 CI** ``` $ roam describe --write Wrote CLAUDE.md (98 lines) # auto-detects: CLAUDE.md, AGENTS.md, .cursor/rules, etc. $ roam health --gate Health: 78/100 — PASS ``` 十条命令。完整的视图：结构、依赖、热点、健康状况、上下文、安全检查、分解和 CI 门控。

## 与 AI 编程工具集成 Roam 旨在供编程智能体通过 shell 命令调用。智能体无需反复 grep 和读取文件，只需运行一条 `roam` 命令即可获取结构化输出。 **智能体的决策顺序：** | 情景 | 命令 | |-----------|---------| | 第一次接触一个仓库 | `roam understand` 然后 `roam tour` | | 需要修改一个符号 | `roam preflight `（爆炸半径 + 测试 + 适应度） | | 调试失败 | `roam diagnose `（根本原因排名） | | 需要读取文件 | `roam context `（文件 + 行范围） | | 需要查找一个符号 | `roam search ` | | 需要文件结构 | `roam file ` | | PR 前检查 | `roam pr-risk HEAD~3..HEAD` | | 如果我更改了 X 会破坏什么？ | `roam impact ` | | 检查 N+1 查询 | `roam n1`（隐式延迟加载检测） | | 检查认证覆盖范围 | `roam auth-gaps`（路由 + 控制器） | | 检查迁移安全性 | `roam migration-safety`（幂等性守卫） | **最快的设置方式：** ``` roam describe --write # auto-detects your agent's config file roam describe --write -o AGENTS.md # or specify an explicit path roam describe --agent-prompt # compact ~500-token prompt (append to any config) roam minimap --update # inject/refresh annotated codebase minimap in CLAUDE.md ``` **智能体没有正确使用 Roam？** 如果你的智能体忽略了 Roam 并回退到 grep/read 探索，它可能没有获取到指令。运行： ``` roam describe --write # writes instructions to your agent's config (CLAUDE.md, AGENTS.md, etc.) ``` 如果你已经有一个配置文件并且不想覆盖它： ``` roam describe --agent-prompt # prints a compact prompt — copy-paste into your existing config roam minimap --update # injects an annotated codebase snapshot into CLAUDE.md (won't touch other content) ``` 这会教导智能体在每种情况下使用哪条 Roam 命令（例如，更改前使用 `roam preflight`、读取文件使用 `roam context`、调试使用 `roam diagnose`）。

复制粘贴智能体指令

``` ## Codebase navigation This project uses `roam` for codebase comprehension. Always prefer roam over Glob/Grep/Read exploration. Before modifying any code: 1. First time in the repo: `roam understand` then `roam tour` 2. Find a symbol: `roam search ` 3. Before changing a symbol: `roam preflight ` (blast radius + tests + fitness) 4. Need files to read: `roam context ` (files + line ranges, prioritized) 5. Debugging a failure: `roam diagnose ` (root cause ranking) 6. After making changes: `roam diff` (blast radius of uncommitted changes) Additional: `roam health` (0-100 score), `roam impact ` (what breaks), `roam pr-risk` (PR risk), `roam file ` (file skeleton). Run `roam --help` for all commands. Use `roam --json ` for structured output. ```

各工具对应的存放位置

| 工具 | 配置文件 | |------|-------------| | **Claude Code** | 项目根目录下的 `CLAUDE.md` | | **OpenAI Codex CLI** | 项目根目录下的 `AGENTS.md` | | **Gemini CLI** | 项目根目录下的 `GEMINI.md` | | **Cursor** | `.cursor/rules/roam.mdc`（添加 `alwaysApply: true` frontmatter） | | **Windsurf** | `.windsurf/rules/roam.md`（添加 `trigger: always_on` frontmatter） | | **GitHub Copilot** | `.github/copilot-instructions.md` | | **Aider** | `CONVENTIONS.md` | | **Continue.dev** | `config.yaml` 规则 | | **Cline** | `.clinerules/` 目录 |

Roam 与原生工具对比

| 任务 | 使用 Roam | 使用原生工具 | |------|----------|-----------------| | "什么调用了这个函数？" | `roam symbol ` | LSP / Grep | | "我需要读取哪些文件？" | `roam context ` | 手动追踪（5+ 次调用） | | "修改 X 安全吗？" | `roam preflight ` | 多次手动检查 | | "展示一下这个文件的结构" | `roam file ` | 直接阅读文件 | | "了解项目架构" | `roam understand` | 手动探索 | | "如果我更改了 X 会破坏什么？" | `roam impact ` | 没有直接的对等物 | | "要运行哪些测试？" | `roam affected-tests ` | Grep 导入（会遗漏间接调用） | | "是什么导致了这个 bug？" | `roam diagnose ` | 手动调用链追踪 | | "用于 CI 的代码库健康评分" | `roam health --gate` | 没有对等物 |

## MCP 服务器 Roam 包含一个[模型上下文协议](https://modelcontextprotocol.io/)服务器，用于与支持 MCP 的工具直接集成。 ``` pip install "roam-code[mcp]" roam mcp ``` 完整预设中提供 103 个工具、10 个资源和 5 个提示。大多数工具为只读索引查询；带有副作用的工具已明确注释。 **MCP v2 亮点 (v11)：** - 进程内 MCP 执行（每次调用无子进程 shell-out） - 基于预设的工具呈现（`core`、`review`、`refactor`、`debug`、`architecture`、`full`） - 将多步探索/审查流程折叠为一次调用的复合工具 - 结构化输出 schema + 工具注解，以实现更安全的规划器行为 **MCP 原生增强 (v12)：** - **采样驱动压缩** -- 对 `roam_explore`、`roam_understand`、`roam_health` 或 `roam_repo_map` 传入 `summarize=True`。服务器会要求客户端自己的 LLM（无需 API 密钥）将完整的封装压缩成简短的简报，输出从约 50 KB JSON 降至约 1-2 KB 纯文本。当客户端不支持采样时会优雅降级。 - **服务器端会话记忆** -- `roam_context`、`roam_explore` 和 `roam_retrieve` 现在会记住你在当前会话中触及的符号，并在无需你通过每次调用传入 `recent_symbols` 的情况下自动偏向排名。显式参数优先级更高。 - **阶段感知进度** --roam_init`、`roam_reindex` 和 `roam_orchestrate` 向客户端流式传输真实的 `discover -> parse -> extract -> resolve -> graph -> metrics` 进度，取代了旧的 5/100 占位符。 - **符号与路径补全** -- 新的 `roam_complete(prefix, kind, limit)` 工具仅从 FTS5 索引返回名称（比 `roam_search_symbol` 成本更低）。还为支持 `completion/complete` 的客户端安装了协议级别的处理程序。 - **响应式资源失效**（可选） -- 设置 `ROAM_MCP_WATCH=1`，服务器将监视工作树，在文件更改时运行增量重新索引，并为 `roam://health`、`roam://summary` 等发出 `notifications/resources/updated`，以便订阅的客户端无需轮询即可看到最新数据。 **默认预设：** `core`（25 个工具：24 个核心工具 + `roam_expand_toolset` 元工具）。 ``` # 默认 roam mcp # Full toolset ROAM_MCP_PRESET=full roam mcp # Legacy compatibility (同 full preset) ROAM_MCP_LITE=0 roam mcp ``` 核心预设工具：`roam_affected_tests`、`roam_batch_get`、`roam_batch_search`、`roam_complete`、`roam_complexity_report`、`roam_context`、`roam_dead_code`、`roam_deps`、`roam_diagnose`、`roam_diagnose_issue`、`roam_diff`、`roam_expand_toolset`、`roam_explore`、`roam_file_info`、`roam_health`、`roam_impact`、`roam_pr_risk`、`roam_preflight`、`roam_prepare_change`、`roam_review_change`、`roam_search_symbol`、`roam_syntax_check`、`roam_trace`、`roam_understand`、`roam_uses`。

MCP 工具列表（全部 120 个）

| 工具 | 描述 | |------|-------------| | `roam_understand` | 完整的代码库简报（支持 `summarize=True` 进行采样压缩） | | `roam_health` | 健康评分（0-100）+ 问题（支持 `summarize=True`） | | `roam_repo_map` | 项目骨架（支持 `summarize=True`） | | `roam_preflight` | 更改前的安全检查 | | `roam_search_symbol` | 按名称查找符号 | | `roam_complete` | 符号/路径/命令的前缀补全（由 FTS5 支持） | | `roam_context` | 用于修改符号的待读取文件 | | `roam_hover` | 单行架构摘要 —— 类型、爆炸半径级别、顶级调用者、顶级被调用者 | | `roam_retrieve` | 针对自由格式任务的图感知上下文（FTS5 + 结构化重排 + token 预算） | | `roam_critique` | 对照图验证补丁（未编辑的克隆 + 爆炸半径） | | `roam_fleet_plan` | 规划多智能体集群 —— 图感知分区生成 .roam-fleet.json | | `roam_oracle_symbol_exists` | 布尔预言机：是否存在任何具有此名称的符号？ | | `roam_oracle_route_exists` | 布尔预言机：是否有任何 HTTP 路由处理器匹配此 URL 路径？ | | `roam_oracle_is_test_only` | 布尔预言机：此符号的所有调用者是否都在测试文件中？ | | `roam_oracle_is_reachable_from_entry` | 布尔预言机：BFS 能否从任何入口点到达此符号？ | | `roam_oracle_is_clone_of` | 布尔预言机：此符号是否参与了持久化的克隆集群？ | | `roam_taint_classify` | 通过 MCP 采样的 LLM 增强污点分类（IDOR/AUTHZ/SQLI/...） | | `roam_taint` | 静态污点分析 —— 带有 OpenVEX-correct 发现的图可达 BFS | | `roam_sbom` | CycloneDX 1.7 / SPDX 2.3 SBOM 输出，带可选 AIBOM 扩展 (EU AI Act) | | `roam_cga_emit` | 发出 Code Graph Attestation（in-toto v1），可选 cosign 签名 | | `roam_cga_verify` | 验证 CGA 声明 —— 重新推导 Merkle + 边缘摘要，检查 cosign 签名 | | `roam_trace` | 两个符号之间的依赖路径 | | `roam_impact` | 更改符号的爆炸半径 | | `roam_file_info` | 包含所有定义的文件骨架 | | `roam_pr_risk` | 挂起更改的风险评分 | | `roam_breaking_changes` | 检测 refs 之间的破坏性更改 | | `roam_affected_tests` | 查找受更改影响的测试 | | `roam_dead_code` | 列出未引用的导出 | | `roam_complexity_report` | 每个符号的认知复杂度 | | `roam_py_types` | Python 类型注解健康状况（% 公共类型化、Any、旧版 typing） | | `roam_py_modern` | 现代 Python 采用（海象、match、PEP 604/585/695、f-strings） | | `roam_pytest_fixtures` | pytest fixture 链 —— 按依赖数量排名的顶级 fixture，或按符号的依赖遍历 | | `roam_tour` | 自动生成的上手指南 | | `roam_diagnose` | 用于调试的根本原因分析 | | `roam_visualize` | 生成 Mermaid 或 DOT 架构图 | | `roam_algo` | 带有感知语言提示的算法反模式检测 | | `roam_ws_understand` | 统一的多仓库工作区概览 | | `roam_ws_context` | 跨仓库增强的符号上下文 | | `roam_pr_diff` | 结构化 PR diff：度量增量、边缘分析、符号更改 | | `roam_budget_check` | 根据架构预算检查更改 | | `roam_effects` | 副作用分类（DB 写入、网络、文件系统） | | `roam_attest` | 捆绑所有证据的携带证明 PR 认证 | | `roam_capsule_export` | 导出经过脱敏的结构图（无代码主体） | | `roam_path_coverage` | 查找关键未经测试的调用路径（入口 -> 汇聚点） | | `roam_forecast` | 预测指标何时将超出阈值 | | `roam_simulate` | 反事实架构模拟器 | | `roam_orchestrate` | 多智能体集群分区 | | `roam_fingerprint` | 拓扑指纹比较 | | `roam_mutate` | 图级别代码编辑（移动/重命名/提取） | | `roam_dark_matter` | 隐藏的共变耦合检测 | | `roam_closure` | 用于重命名/删除的最小更改合成 | | `roam_adversarial_review` | 对抗性架构 |----------|-----------|---------|------------|-------------| | Python | `.py` `.pyi` | 类、函数、方法、装饰器、变量 | 导入、调用、继承 | 扩展、`__all__` 导出 | | JavaScript | `.js` `.jsx` `.mjs` `.cjs` | 类、函数、箭头函数、CJS 导出 | 导入、require()、调用 | 扩展 | | TypeScript | `.ts` `.tsx` `.mts` `.cts` | 接口、类型别名、枚举 + 所有 JS 特性 | 导入、调用、类型引用 | 扩展、实现 | | Java | `.java` | 类、接口、枚举、构造函数、字段 | 导入、调用 | 扩展、实现 | | Go | `.go` | 结构体、接口、函数、方法、字段 | 导入、调用 | 嵌入结构体 | | Rust | `.rs` | 结构体、特征、实现、枚举、函数 | use、调用 | impl Trait for Struct | | C / C++ | `.c` `.h` `.cpp` `.hpp` `.cc` | 结构体、类、函数、命名空间、模板 | includes、调用 | 扩展 | | C# | `.cs` | 类、接口、结构体、枚举、记录、方法、构造函数、属性、委托、事件、字段 | using 指令、调用、`new`、属性 | 扩展、实现 | | PHP | `.php` | 类、接口、特征、枚举、方法、属性 | 命名空间 use、调用、静态调用、`new` | 扩展、实现、use (traits) | | Visual FoxPro | `.prg` | 函数、过程、类、方法、属性、常量 | DO、SET PROCEDURE/CLASSLIB、CREATEOBJECT、`=func()`、`obj.method()` | DEFINE CLASS ... AS | | YAML (CI/CD) | `.yml` `.yaml` | GitLab CI：作业、模板锚点、阶段。GitHub Actions：工作流名称、作业、可重用工作流。通用：顶层键 | `extends:`、`needs:`、`!reference`、`uses:` | — | | HCL / Terraform | `.tf` `.tfvars` `.hcl` | `resource`、`data`、`variable`、`output`、`module`、`provider`、`locals` 条目 | `var.*`、`module.*`、`data.*`、`local.*`、资源交叉引用 | — | | Vue | `.vue` | 通过 `