rag-rat

rag-rat

仓库对自身的了解。 rag-rat 是一个本地仓库智能索引和 MCP 服务，面向编码 Agent。它会将源文件保持为只读，仅写入自己的 SQLite 数据库，并为每条结果提供来源依据——当前源代码、代码图谱、git/GitHub 历史，以及可跨会话和 Agent 持久保存、锚定于源代码的仓库记忆。

探索实时 VS Code Lens 演示——无需安装。 它会在代码旁展示克隆代码类别、仓库记忆以及问题/决策背景；按下 Ctrl+Alt+R 可显示克隆代码叠加层。

每种编码环境都已有 grep 和文件读取功能。rag-rat 补上了它们所不具备的一层： 锚定于源代码的理由依据。它会将 Agent 即将修改的代码与其调用方、被调用方、 测试、git/GitHub 历史、过往决策、不变量、风险和重复代码信号关联起来，并为每条结果 标注置信度和覆盖范围，让 Agent 可以自行判断，而不是盲目信任。

sequenceDiagram
    participant Repo as Repository
    participant Engine as rag-rat engine
    participant Agent as Coding agent

    Repo->>Engine: Source · git/GitHub · repo memories
    Engine->>Engine: Index → graph → (opt) SCIP oracle → reconcile
    Agent->>Engine: where / why / who-calls / impact?
    Engine-->>Agent: source + call paths + papertrail + memories (with provenance)
    Agent->>Engine: record a finding
    Engine->>Repo: persist a source-anchored repo memory

为什么

• 依据明确，而非猜测。 每条结果都带有置信度标签、覆盖范围警告和 原始证据——因此，部分索引或含糊的关系会如实呈现。
• 仓库记忆。 类型化、锚定于源代码的注记（Invariant、Decision、Risk 等），可在重构后保留， 并在未来查询时自动呈现——这是 grep 无法提供的信号。它们 不是助手记忆，而是关于此仓库的本地版本化事实，锚定于源代码，任何未来的 Agent 都能通过证据检索。
• 真正的代码图谱。 使用 tree-sitter 分析 Rust、TypeScript/TSX、Kotlin、 C/C++、Python、Swift 和 Go 中的调用方/被调用方/导入关系；对于已配置的工具链，还可选用 编译器级 SCIP oracle，将关系升级为 Compiler 置信度，并为关键 符号排序。
• 以历史作为证据。 Git 历史、延迟分块 blame，以及缓存的 GitHub 问题/PR/评审 理由，全部可供查询。
• 问题提炼。 将每个已关闭的问题和已合并 PR 连同其修复 diff 提炼为类型化的 决策记录——包括根本原因、最终采用的方法（以及被否决的替代方案） 和结果；并通过对讨论串进行验证，将其作为关联符号的附带背景信息呈现。
• 融入现有 grep。 grep 增强 Hook 会注入你刚刚搜索的内容背后的 记忆和符号。
• 编写时标记克隆代码。 在 Write/Edit/MultiEdit 上的 PreToolUse Hook 会为你正在编写的 函数生成指纹，并在它们与仓库中已有代码完全重复或近似重复时发出警告——让 Agent 复用代码，而不是重新实现。它是只读的；索引尚未就绪时会静默跳过，因此绝不会阻止写入。

快速开始

对于 Claude Code、Codex 和 opencode，请安装插件。它会注册 MCP 服务、添加 钩子，并在首次运行时获取与版本匹配的 rag-rat 二进制文件，MCP 服务在启动时会将其暴露为 ~/.local/bin/rag-rat——参见 运行命令行（Claude Code 和 Codex 安装包还会添加 skills；在 opencode 上使用 npx @rag-rat/skills 添加它们）：

# Claude Code
claude plugin marketplace add cq27-dev/rag-rat
claude plugin install rag-rat@rag-rat

# Codex
codex plugin marketplace add cq27-dev/rag-rat
codex plugin add rag-rat@rag-rat

# opencode (add -g for a global install)
opencode plugin @rag-rat/plugin-opencode

安装后，批准该插件，以便其工具和钩子运行（opencode 加载插件时无需 批准步骤——那里无需任何操作）：

• Claude Code 在首次运行每个 rag-rat MCP 工具前都会询问——请选择 "Yes, don't ask again,"，或在 ~/.claude/settings.json 中通过 "permissions": { "allow": ["mcp__plugin_rag-rat_rag-rat__*"] } 预先允许它们（插件工具命名为 mcp__plugin_rag-rat_rag-rat__<tool>；使用 claude mcp add 手动添加的服务则使用 mcp__rag-rat__*）。

• Codex 在仓库内启动的首次 codex 会话中会显示 "Hooks need review" 提示 （该插件附带 grep 增强、克隆检查与会话摘要钩子，它们在沙箱之外运行）。选择 "Trust all and continue" 以启用它们。对于诸如 codex review 这类无人值守命令，还需在 ~/.codex/config.toml 中允许该插件的 MCP 工具，以免运行因 逐个工具的批准提示而停滞：

  [plugins."rag-rat@rag-rat".mcp_servers.rag-rat]
  default_tools_approval_mode = "approve"
  

  这会信任已安装的 rag-rat 插件暴露的所有当前及未来的 MCP 工具。仅当你信任该插件的来源和安装出处时 才启用它，然后重启 Codex。

然后打开仓库并提问：

在这个仓库中设置 rag-rat。

init-rag-rat skill 会扫描仓库、解释各项材料选择、预览 rag-rat.toml， 仅在确认后写入并建立索引，并提供设置保持索引 新鲜的 git 钩子。MCP 服务在未配置的仓库中会处于休眠状态启动；当设置完成后，重新连接它，使其 针对新索引以完全激活状态重启——在 Claude Code 中运行 /mcp 并重新连接 rag-rat；在 Codex 和 opencode 中，启动一个新会话。

然后让它投入工作——rag-rat 所构建的工作流见 试用。

npm install -g @rag-rat/bin
# or run it without installing:
npx @rag-rat/bin --help

cargo install rag-rat
# or from a checkout:
cargo install --path crates/rag-rat-cli --bin rag-rat

cargo install rag-rat --no-default-features --features model2vec

cd /path/to/your/repo
rag-rat init

npx @rag-rat/skills

claude mcp add --scope project rag-rat -- rag-rat mcp
codex  mcp add rag-rat -- rag-rat mcp

{
  "mcpServers": {
    "rag-rat": { "command": "rag-rat", "args": ["mcp"] }
  }
}

{ "permissions": { "allow": ["mcp__rag-rat__*"] } }

试用

仓库完成索引后，代码图谱、符号、Git 历史记录、语义搜索和克隆检测即可使用——第一次查询就能得到这些信息。仓库记忆起初是空的：Agent 通过 memory_create 记录发现后，记忆会逐渐积累，并自动出现在后续回答中。 （跟踪器议题/PR 的理由需要运行 rag-rat papertrail sync。）

向 MCP 客户端提问：

• “对我即将编辑的函数运行 impact_surface——查看它的调用方、被调用方、测试和近期提交。”
• “配置重载在哪里处理？”——使用混合 semantic_search 搜索源代码和文档。
• “这个仓库中哪些符号最关键？”——使用 important_symbols。
• “这个辅助函数是否重复实现了代码库中已有的内容？”——使用 find_clones（写入时钩子也会在你编写代码时发出警告）。
• “在 parse_config 上记录一条不变量：调度器启动后，重载不得进行内存分配。”——memory_create 会写入你的第一条仓库记忆；之后它会随每次 impact_surface / symbol_lookup 结果一起提供。

或者从命令行运行：

rag-rat query "where is config reload handled?"
rag-rat important-symbols --limit 20
rag-rat brief --mode spine
rag-rat clusters --limit 10
rag-rat tools impact-surface --symbol parse_config

Agent 工作循环

重点不在于工具目录，而在于 Agent 围绕编辑执行的工作循环：让它在修改代码时能参考调用方、测试、理由和先前实现，而不是靠猜测：

1. 编辑某个符号前，先调用 impact_surface。 一次调用即可返回当前源代码锚点、调用方和被调用方、相关测试、Git/GitHub 理由、与该符号 / 路径 / 调用路径关联的仓库记忆，以及置信度和覆盖率警告。
2. 阅读影响范围，然后编辑。 先前 Agent 记录的不变量、相隔三跳的调用方、固定行为的测试——都会在修改前呈现，而不是等修改后才发现。
3. 克隆检测钩子会在写入时发现重复代码。 如果新函数重新实现了已有代码，Write/Edit 钩子会指出这一点，并告知可复用的现有符号。
4. 记录你的发现。 如果编辑揭示了值得长期保留的不变量、决策或易错点，memory_create 会将其保存为带源代码锚点的仓库记忆——这样，下一个 Agent（或下一个会话）只需一次调用就能获取，而不必重新推导。

下面是精简版 impact_surface 回答（TOON——默认输出；此处已缩略）——每个字段都是证据，而非文字说明：

query:
  ref: "crates/config/src/config.rs::parse_config"
  resolution: syntactic
direct_semantic_callers[12]:
  - from_symbol: "crates/runtime/src/boot.rs::start"
    edge_kind: calls_name
    confidence: syntactic
    callsite:
      path: "crates/runtime/src/boot.rs"
      line: 88
    importance:
      label: local structural load
      score: 6.8
      bucket: high
tests_touching_symbol_path[4]:
  - path: "crates/config/src/config_tests.rs"
    reason: test_mentions_symbol_or_path
recent_commits_touching_symbol_path[1]:
  - evidence[1]: "a1b2c3d touched crates/config/src/config.rs: fix reload race during startup (#141)"
repo_memories:
  direct[2]:
    - kind: Invariant
      title: "Config reload must not allocate after the scheduler starts"
      confidence: high
      anchor_status: current
      binding_kind: symbol
    - kind: Decision
      title: "TOML over JSON5 for the config surface (#88)"
      anchor_status: current
      binding_kind: path
completeness_and_caveats:
  exact_graph_callers: 12
  memory_status:
    active: 2
    stale: 0
  caveats[1]: "Graph evidence is tree-sitter/syntactic, not compiler-grade name resolution."

下面是 Agent 在重复逻辑前看到的写入时克隆警告——钩子的原样输出：

▶ rag-rat clone check — code you're writing duplicates existing functions:
  • `normalize_path_for_lookup` (line 42) is ~91% similar to crates/index/src/paths.rs::canonicalize_lookup_path
Prefer reusing the existing function(s) over duplicating — impact_surface / symbol_lookup to inspect them.

工具

rag-rat 的工具目录通过 MCP 和原生命令行命令提供。完整目录和 JSON 架构见 docs/mcp-tools.md。运行 rag-rat tools --help 浏览所有工具，或运行 rag-rat tools <name> --help，根据规范架构查看参数。 现有的精选命令（如 query、brief、memory 和 dream）保持不变。你最常用到的工具包括：

• impact_surface —— 上述工作循环中的编码预检：一次调用即可获取调用方、被调用方、测试、git 历史、GitHub 记录，以及与某个符号相关的仓库记忆。记忆默认以紧凑、便于浏览的标题形式显示；传入 full_memories: true 可获取完整内容和绑定信息。
• semantic_search —— 对源代码和文档进行 BM25 + 向量混合检索，并根据当前源代码验证。每条结果都会报告 retrieval_mode；explain=true 可分解显示得分。
• symbol_lookup —— 精确／模糊符号解析；cfg／重载变体会归为一个逻辑符号。
• find_callers / trace_callees —— 反向／正向遍历调用图（默认过滤低信噪比的 std／宏噪声）。
• important_symbols —— 基于（支持 SCIP 的）PageRank 找出承载关键功能的符号，默认以当前差异为种子；见 docs/oracle.md。
• find_clones —— 查找完全重复和近似重复的函数，并按重构投资回报率排序（候选图会在后台预先计算，因此可扩展到大型仓库）。
• memory_create —— 记录以源代码为锚点的仓库记忆；dream 会提供维护任务清单，确保这些记忆保持准确（见下文的 #self-maintaining-memories）。

除此之外，还有仓库概览（repo_brief、repo_clusters）、历史记录与依据（history_for 可查询符号、路径、代码块或提交；history_search 可搜索提交、问题和评审讨论）、记忆检索（memory_search、memory_for_*）以及索引健康状态（index_status）。 维护与诊断工具——dream、heal_index、memory_doctor、图与编译器审计、记忆任务图——位于可选启用的 admin 和 graph 工具集（[mcp] toolsets）中，因此在需要之前，不会出现在任何 Agent 的工具列表里。所有工具均有文档说明，见 docs/mcp-tools.md。

仓库记忆

仓库记忆是一级本地证据——不是聊天记忆，也不是云端个性化信息。它们是关于此仓库的版本化、本地、以源代码为锚点的事实。每条记忆都有类型（Invariant、Decision、RejectedAlternative、Risk、BugPattern、PerformanceNote 等），并且以源代码为锚点：绑定到逻辑符号、具体符号、代码块、路径 + 范围、图边、调用路径、提交或 GitHub 引用。rag-rat 会将每个锚点跟踪为 current、relocated、stale、gone 或 unverified，并通过 memory_* 工具以及在 read_chunk、symbol_lookup、find_callers、trace_callees 和 impact_surface 中内联显示匹配的记忆。它们能让来之不易的上下文通过一次调用传递给下一个 Agent，而不是随之消失。

记忆也是一个带类型的图，而不只是一个扁平列表：memory_edge_add / memory_edges 使用关系（depends_on、relates_to、supersedes、derived_from、tracks）将它们连接起来——可以构成任务 DAG、决策之间的思维导图链接，也可以让任务 tracks 某个 GitHub 问题。完整工具列表： docs/mcp-tools.md。

自维护记忆

记忆会逐渐失效：代码在记忆所述内容之下发生变化，不变量被新规则取代，承载关键功能的函数发布时却完全没有记忆。dream 是让这一层保持准确的维护循环。它会重新计算一份按优先级排序的待处理清单，列出关于记忆本身的问题——每项都有稳定 ID，便于审查：

• 覆盖缺口 — 承载关键功能的符号（按与 important_symbols 相同的 PageRank 确定）没有对应记忆，因此下一个编辑它们的 Agent 将一无所获。
• 过时引用 — 记忆引用的路径或锚点已无法解析。

每次调用 dream 都会运行确定性问题检测。还有两个可选的模型处理阶段，仅在有待处理工作时，才会在临时远程 GPU（[llm.dream.remote]）上运行小型模型，进行更深入的分析：rag-rat dream --verify 会根据当前源代码实际情况重新判断每条记忆（代码是否已偏离记忆所述内容？）；--compact 会将冗长的记忆改写为更精炼的摘要。这些处理阶段产生并持久化的问题会再次通过 dream 呈现。

不会自动删除任何内容。人类或通过 MCP 运行的强大 Agent 可以使用 dream_review 逐项处理清单（对真实缺口执行 accept，对无关项执行 dismiss，对先前的判定执行 reset），判定结果会在后续运行中保留，已处理的问题不会再次出现。这与 CLI 中的 rag-rat dream / rag-rat dream <id> --accept|--dismiss|--reset 提供的是同一界面。

编译器级解析与排序

默认情况下，图是通过启发式方法构建的。启用可选的 SCIP oracle（rag-rat oracle run）后，边会升级为来自真实语言工具的 Compiler 层级，可找回 tree-sitter 遗漏的调用、标记外部边，并让 important_symbols 展示真正的上帝模块。对于 C/C++，scip-clang oracle 可以区分声明与定义，并强化宏密集型或多目标代码中的调用边和类型边——这决定了固件、内核、驱动程序和 SDK 的图是实用还是嘈杂。启用 [oracle] auto_run 后，MCP 服务会自行保持其最新状态（设有节流，且不会干扰文件监视器）。完整详情：docs/oracle.md。

新鲜度

rag-rat mcp 会运行后台文件监视器（默认启用；可通过 [watch] enabled = false 或 RAG_RAT_NO_WATCH=1 禁用），因此图和符号查询无需提交即可反映未提交的编辑。索引行会感知 Git 上下文：干净文件按 commit_sha 存储，已修改或未跟踪的文件存储在工作树覆盖层中，因此同一个数据库可以跨分支切换复用行，同时反映本地编辑。可选的 Git 钩子（rag-rat hooks install）会在检出、合并、改写或提交时保持索引最新。read_chunk 和搜索会根据当前源代码验证命中结果，并在返回前修复过时条目。

文件锁会确保每个工作树只有一个文件监视器，且同一时间只有一个写入者（在 NFS / WSL2 /mnt 挂载上不可靠）。

Editor Lens HTTP API

运行中的 rag-rat mcp 进程还会为每个工作树选举一个经过身份验证的 Lens HTTP 服务。它会将回环 URL 和 bearer token 发布到 .rag-rat/sockets/lens.json；在 Unix 系统上，凭据文件仅所有者可读。设置 RAG_RAT_NO_LENS=1 可禁用此嵌入式服务，或将 RAG_RAT_LENS_ORIGINS 设置为以逗号分隔的精确浏览器源允许列表。

当 HTTP API 需要独立的生命周期时，运行 rag-rat serve。回环服务会生成 token；客户端从发现文件中读取它。非回环绑定需要同时设置显式的 token 环境变量和至少一个受信任的浏览器源：

LENS_TOKEN="$(openssl rand -hex 32)" rag-rat serve \
  --bind 0.0.0.0 --token-env LENS_TOKEN --allow-origin https://lens.example.com

除预检请求外，每个请求都使用 Authorization: Bearer <token>。允许的源会进行精确匹配；绝不会发送通配符 CORS。内置监听器使用普通 HTTP，因此在通过不受信任的网络公开非回环服务之前，请先通过受信任的反向代理或隧道终止 TLS。

默认情况下，每个仓库的索引和记忆都存储在每台机器一个整合数据库中（$XDG_DATA_HOME/rag-rat/rag-rat.sqlite；可通过 RAG_RAT_DATA_DIR 覆盖），因此删除检出目录或运行 git clean -fdx 不再会丢失你编写的记忆。设置显式的 [index] database 可让仓库使用自己的文件（已弃用）；运行 rag-rat consolidate 可将现有的 .rag-rat/index.sqlite 导入全局存储——参见 docs/config/database.md。

输出格式

CLI 和 MCP 结果默认采用 TOON（Token-Oriented Object Notation），这是一种高效利用 token 的编码方式，可将统一行渲染为紧凑的 [N]{cols}: 表格（对于这类负载，比紧凑 JSON 小约 30%，实际使用中绝不会更大）。当需要由 JSON 解析器读取输出时，传入 --json（CLI，可放在任一位置），或启动 rag-rat mcp --json（MCP）。

嵌入后端

默认的本地嵌入器（FastEmbed）无需设置，但大型仓库或更强大的模型值得卸载处理。rag-rat 支持 OpenAI 兼容的 /v1/embeddings API，因此 [llm.embedding.remote] 配置块可以从 Ollama、vLLM 或 michaelfeil/infinity 提供嵌入——使用一个客户端，集中进行审计和安全保护。提供两种模式：

• 连接到你已运行的服务（设置 endpoint）。
• 临时运行——让内置 cookbook 配置 GPU 工作节点（Modal / RunPod），仅用于回填，之后将其关闭（设置 cookbook）；在配置中选择后端和 GPU 类别。

初始化流程会在短上下文模型可能截断较长代码块时发出警告，并引导你选择长上下文代码嵌入器；rag-rat 还会根据所选后端自动调整客户端并发数，以便测试找到吞吐量拐点。设置方法和所有可调参数见：docs/config.md。

检索质量

搜索质量可以衡量，而非凭猜测。rag-rat 自带提交回放评估工具（rag-rat eval --replay）：每个近期提交都会成为一个用例——提交说明作为查询，涉及的文件作为标准答案集——并根据搜索找回这些文件的效果进行评分。它会报告 recall@3（正确的代码块是否出现在前三次读取中？）、recall@10 和 MRR@10；CI 会在 main 上通过 Bencher 跟踪趋势，从而在回归随版本发布之前发现它。

在比较嵌入模型、更改分块方式、启用 int8 向量存储（减小磁盘占用）或调整远程后端时，可以使用它——你可以证明更改没有牺牲召回率，而不是寄希望于此。（rag-rat eval 需要使用 --features eval 构建；发布的二进制文件中不包含它。）

基准测试

主要工作负载是为整个 Linux 内核（v7.0，约 6.3 万个 C/H 文件、914 万条图边）建立索引。 完整数据——墙上时间、吞吐量、峰值 RSS、磁盘占用、未解析边分类——见 docs/benchmarks.md。性能按每次推送跟踪，并按每个 PR 设门槛；实时历史记录见 bencher.dev/perf/rag-rat/plots（配置说明： docs/bencher.md）。

安全性

MCP 服务提供只读源代码工具。它绝不会执行 shell 命令，也不会写入你的源文件。它只会写入已配置的 SQLite 索引——包括建立索引、迁移、维护、协调、仓库记忆操作，以及自动修复过期索引期间。GitHub 同步是显式操作，使用 gh api；常规查询工具仅读取本地缓存。

本地与远程嵌入

使用默认的本地嵌入器时，数据不会离开本机——建立索引和查询都完全在本地进行。配置 [llm.embedding.remote] 后端才会将文本发送到本机之外，涉及两种情况：建立索引时选取的分块文本，以及每次语义搜索的查询文本（搜索会嵌入你的查询，以便将其与已建立索引的向量进行比较）。CONNECT 后端会针对配置的 endpoint 嵌入两者；临时后端则会针对本地 query_endpoint 嵌入查询。

端点的类型决定了这有多重要：

• 你自己的服务（自托管 Ollama / vLLM / infinity）——文本会留在你控制的基础设施中。
• 临时 Modal / RunPod 工作器（食谱中的方案）是提供临时计算资源的服务商，运行的是你的开源嵌入器，而不是会利用输入训练的数 据服务。两者都通过 SOC 2 Type II 认证，会对传输中和静态数据进行加密、隔离租户，并在回填后销毁机器及其存储——这属于数据处理方关系，对于专有代码而言是合理的，就像使用云虚拟机一样。
• 你无法控制的第三方嵌入 API 才是需要认真阅读条款的情况（数据保留、是否利用输入进行训练）。

无论使用哪种后端，都应采取合理的卫生措施：从索引目标中排除机密信息、生成文件和供应商目录，以免它们被分块或嵌入；并避免在查询文本中包含机密信息。详情见： docs/config.md。

平台支持

rag-rat 可在 Linux、macOS 和 Windows 上构建和测试。每个 PR 和每次推送到 main 都会覆盖 Linux；macOS 和 Windows 则在发布时进行测试，因此 cargo install rag-rat 可以在这三个平台上构建和链接。Android（aarch64，bionic）也是发布目标——每次发布都会附带预构建二进制文件，并发布到 @rag-rat/bin，因此 npx @rag-rat/bin 可在 Termux 上运行；请参阅快速入门。 SQLite 是捆绑的（通过 rusqlite 从源码编译），因此无需系统库前置条件，但每个平台都需要 C 工具链：Linux 自带；macOS 上请安装 Xcode Command Line Tools（xcode-select --install）；Windows 上请安装包含 C++ 工作负载的 Visual Studio Build Tools（MSVC）。需要 Rust 1.98+；工作区将该稳定版本作为依赖项的基准（捆绑的 SQLite 构建本身至少需要 Rust 1.95，才能使用 cfg_select!）。

有几项维护便利功能按设计仅支持 Unix 或 Linux，在其他平台上会静默降级——不会影响索引、查询或 MCP 接口的任何功能：

• 运行中 MCP 服务的热升级（SIGUSR1 原地重新执行）仅支持 Unix。Windows 上请重启 rag-rat mcp 以使用新二进制文件。
• 集群自动升级（新二进制文件就绪时通知其他运行中的服务）仅支持 Linux——它会遍历 /proc——在其他平台上则不执行任何操作。
• grep 增强钩子在 Linux 和 macOS 上使用常驻 Unix 套接字监听器（并按会话去重）；在 Windows 上则回退为每次直接针对索引执行只读查询，效果相同，但不会跨调用去重。

命令

运行 CLI

本 README 和 docs/ 中的命令均写作 rag-rat <command>。

使用插件时，rag-rat 是 ~/.local/bin/rag-rat（Windows： %USERPROFILE%\.local\bin\rag-rat.cmd）：MCP 服务会在首次启动时让该 shim 指向与插件版本匹配的二进制文件，并在插件更新时同步更新。与 Claude Code 的安装程序类似，它不会修改你的 shell 配置文件或 PATH。如果找不到 rag-rat，说明 ~/.local/bin 不在 PATH 中——将 export PATH="$HOME/.local/bin:$PATH" 添加到你的 shell 配置文件，或运行 ~/.local/bin/rag-rat doctor；其中的 cli 部分会给出适用于你系统的确切修复方法。该 shim 绝不会替换它未创建的 rag-rat；设置 RAG_RAT_NO_PATH_SHIM=1 可将其关闭。

不使用插件时，安装 CLI：npm install -g @rag-rat/bin 或 cargo install rag-rat。

最后的办法，如果两种方式都不可用，可通过 npx 运行与 MCP 服务所用版本一致的版本（index_status 工具的 version 字段）：

npx -y @rag-rat/bin@<version> <command>

请固定版本：未固定版本的 npx @rag-rat/bin 会运行最新版本，而该版本会将索引迁移到一种旧版插件的服务无法打开的架构。Git 钩子会用这种方式固定版本，并自行跟进插件更新。

rag-rat init                       # guided first-run setup
rag-rat index [--changed|--discover|--full]
rag-rat doctor
rag-rat query "semantic recall"    # add --json for JSON
rag-rat important-symbols --limit 20
rag-rat brief --mode spine|churn|god_modules|refactor_candidates
rag-rat clusters --limit 10
rag-rat oracle run | status        # compiler-grade resolution (docs/oracle.md)
rag-rat models list | install <model>
rag-rat reconcile --changed-first --max-seconds 60 --batch-size 64
rag-rat papertrail sync            # add --full to force a historical healing pass
rag-rat memory list | show <id> | doctor | rebind <id>    # inspect / re-anchor repo memories
rag-rat dream [--verify|--compact] [<id> --accept|--dismiss|--reset]   # memory-maintenance worklist
rag-rat consolidate                # import a legacy per-repo index into the global store
rag-rat hooks install              # git maintenance hooks
rag-rat gc                         # prune rows for dead git contexts
rag-rat eval [--json|--update-baseline]   # CI search-quality gate; requires a `--features eval` build (absent from the released binary)
rag-rat serve                      # authenticated editor Lens HTTP API
rag-rat tools <name>               # invoke any tool directly; see `tools --help`
rag-rat mcp                        # start the STDIO server

发布与许可证

发布由 release-plz 自动完成（这三个 crate 会同步发布；参见 docs/releasing.md）。rag-rat 采用 MIT 许可证，详见 LICENSE。

相关先行工作

rag-rat 的克隆检测设计受到 SourcererCC 可扩展的 token 包候选生成、NiCad 对规范化近似克隆检测的阐述、GumTree 支持移动的 AST 差异分析，以及用于模板提取的反统一／最一般化概括的启发。计划中的片段级挖掘和复制粘贴错误启发式方法受到 CP-Miner 的启发。