ripwire 怎么用

0030 秒速览

先记住三句

• 它是 ripgrep 的近亲，目的不同：ripgrep 在代码里搜文本；ripwire 把代码结构压成一段给 AI 看的内容，少花 token、少跑弯路。
• 单二进制、零依赖：一个 ripwire 可执行文件，下载到本地就能跑，没有守护进程、没有索引服务、不用 API key。
• 接 AI 代理最省事的方式就一条命令：ripwire wrap claude，剩下的它自己接好 Claude Code / Cursor / Windsurf 等。

5 分钟就能跑起来的最小路径

1. 装一行命令（见 §04）。
2. 在自己仓库里跑 ripwire . --max-tokens=3000，得到一份「压缩过的项目地图」。
3. 把这条信息丢进 Claude / Cursor 的输入，让它基于地图回答、再去读具体文件。

关键数字

01它是什么 / 不是什么

它不是什么

• 不是 ripgrep 的竞品。ripgrep 是一把很快的「在文本里搜关键词」的瑞士军刀；ripwire 是给编码代理搭的「先用一张地图替它定位、再去读文件」的脚手架。名字里有 wire，意思是「在仓库与代理之间拉一根细线」。
• 不是一个通用搜索引擎。它没有「全文索引」也没有「向量索引」——它内部用的是 SCIP（语言无关的代码索引协议）加上几路启发式检索（命名、调用关系、复杂度、churn 频率等），按问题「拼」出一段上下文。
• 不是 IDE 插件。它本身是一个命令行（CLI）和一个 MCP 服务器（MCP，就是 Model Context Protocol，AI 代理用来「插外部工具」的标准协议，类似 USB-C）。VS Code / Cursor 直接通过 MCP 接入，不需要装插件。

它是什么

一句话定位，官方原文：

"The ripgrep of AI context. Give your coding agent a map before it reads the repo."
—— ripwire 仓库副标题

展开来说，它做的具体事有四件：

1. 结构化定位：给你一个仓库里所有函数、类、模块的清单——比「在 github 里 @ 它」便宜得多。
2. 调用图：谁调用了 foo、foo 又调用了谁、能生成 HTML 给你看（像 Django migrations 那个例子里那样）。
3. 质量评估：六个互相独立的「证据家族」（structural shape、lexical naming、syntactic-confusion idioms、git churn history、cross-file colocation、non-local mutable state）给一段代码从结构、命名、易混写法、变更频率、跨文件聚类、跨函数可变状态六个角度看「代码味儿」。
4. 代理护栏：用 --scan-skill 之类的命令扫描技能文件，把行为含糊、有越权风险的脚本捞出来提醒。

它的几个关键「零」，按官方介绍

• 零依赖：所有库都 vendored（内嵌进二进制），离线也能编译。
• 零配置：开箱即用，不需要 .ripwirerc，命令拿到就跑。
• 零状态：没有守护进程（daemon，没有常驻后台的程序）、没有索引服务、没有嵌入模型、不用 API key。

02七大家族

ripwire 的命令按用途分成七组（原文：「七家族」，共 179 个长标志）。这不只是记忆口诀——你打开 --help 看到的也是这个分组。

速查表（见 §07 也有完整版）

03装上

最小一条命令（macOS / Linux）

下面是 INSTALL.md 给出的官方安装方式，绝大多数情况下你只要敲这一行就够了：

# 下载脚本会自己挑适合你架构（arm64 / x86_64）的二进制
RIPWIRE_REPO=redhat-et/ripwire bash -c "$(curl -fsSL https://raw.githubusercontent.com/redhat-et/ripwire/main/scripts/install.sh)"
# 默认装到 ~/.local/bin，把这行加到你的 ~/.zshrc（或 ~/.bashrc）
export PATH="$HOME/.local/bin:$PATH"
ripwire --version     # 验证：应打印出 0.6.0 或更新的版本号

输出长得像 ripwire 0.6.0 (linux x86_64, build …) ，看到版本号就算装好了。

装完之后再跑一步「体检」

这步是 ripwire 自己推荐的、能挡掉 80% 安装问题的小命令：

ripwire . --doctor      # 检查二进制、skills 链接、hooks 是否就位

输出会说清楚「没问题 / 哪一步失败 / 怎么修」。先跑它再开始用，是最稳的姿势。

Apple Silicon（M 系列芯片）能用吗？

能。官方原文是「one self-contained binary for macOS and Linux (arm64 and x86-64)」。这里的两个词都指「CPU 指令集」（CPU 听懂的「机器语」格式）——arm64 是 Apple 自家 Mac 和多数移动设备用的（也叫 AArch64）；x86-64 是 Intel/AMD 的台式机 / 服务器用的（也写作 x86_64）。Apple Silicon 走 arm64 这条，上面那条命令直接装。

想离线装（公司内网 / 没代理）

从源码编译，所有依赖都内嵌（vendored），不需要联网拉库：

git clone https://github.com/redhat-et/ripwire.git
cd ripwire
cmake -S . -B build    # 需要 CMake 3.24+
cmake --build build -j  # 需要 C++23 编译器：clang 16+ / AppleClang 15+ / gcc 13+
./build/ripwire --version

想锁特定版本

把这条塞到环境变量里：

RIPWIRE_VERSION=v0.5.0 RIPWIRE_REPO=redhat-et/ripwire bash -c "$(curl -fsSL ...)"

以后想升级，再跑同一行（不设 RIPWIRE_VERSION 就拿最新版）就更新。

想跳过确认提示 / CPU 检查（非默认机器）

另外两个常被用到的安装变量：

• RIPWIRE_INSTALL_YES=1：跳过确认提示。
• RIPWIRE_SKIP_CPU_CHECK=1：跳过 x86-64-v3 CPU 检查。x86-64-v3 是 x86-64 指令集下的一个微架构版本（再加一些新指令），2015 年后的 Intel/AMD 基本都支持；如果你的机器更旧、或装了更老指令集的 Linux 发行版，配上这个变量可以绕过版本检查（旧机器上二进制仍然会先跑自检再装）。

环境变量速查

04起步四条命令

装好之后，README 里给出的 quickstart 长这样——四条命令覆盖四种最常见的「我想用它做什么」。

# 1) 给整库建一份「可喂给 AI 的地图」，按重要度排序，截到 3000 token 左右
ripwire . --max-tokens=3000

# 2) 带任务：「我在做 incremental cache invalidation」，挑出真正相关的部分
ripwire . --for="incremental cache invalidation"

# 3) 查某个函数的调用方（谁调过 someFunction）
ripwire . --callers=someFunction

# 4) 提交前的「测试门槛」自检
ripwire . --test-gate

命令 #1 是新手最该先跑的一条

它默认输出是一段结构化的仓库地图（struct / defs 之类），长度被压在 3000 token——刚好是大多数对话窗口（context window，就是模型一次能同时看到的最大文本量）的舒适上限。把这段输出原样贴在 Claude / Cursor 的输入里，再问「请用这段代码回答我的问题」，模型一开始就带着地图推理，比让它空进来读到满要省得多。

「reflex flags」——四个自动化场景的快捷旗

ripwire 还有四个被官方称作「reflex flags」的、专门面向代理工作流的旗：一敲就走。

05几个真正适合用它的场景

AI 代理进一个陌生仓库之前

让代理不直接从「Read every file」开始，而是先用 ripwire . --max-tokens=N 拿一份地图。这是 ripwire 的头号卖点。

PR review / 提交门禁

把 --test-gate 和 --quality-delta（看本次改动在六个证据家族上的变化）挂在 CI 上。CI 拒绝就需要修。

复盘一段历史变更

想知道「去年重构的那批函数现在被谁调用」，跑 --callers / --impact。

扫技能文件的安全风险

代理要执行一个 skill（技能，就是预先打包好的一套动作），先用 --scan-skill PATH 看它会不会做越权事。

调试一个不熟悉的库

把第三方库（比如 Django migrations）当作输入，传 --html=map.html，得到一张自包含的调用图，浏览器打开看：

ripwire path/to/django/db/migrations \
  --rank-by=rrf --top-k=120 \
  --color-by=cx --html=map.html
open map.html       # macOS 上直接打开

得到的图可以按「复杂度（cx）」「变更频率（churn）」「语言（lang）」「社区热度（community）」「是否被测试覆盖（tested）」五个维度上色。同一份图，换一维就看到不同的人间真相：

06接进 Claude Code / Cursor

最省事：ripwire wrap

这是给「我只想装上让它干活」的人留的入口。一行命令，ripwire 自己去认识你机器上已经装好的代理。

# 接 Claude Code（最常见的 Claude 官方 IDE 插件名）
ripwire wrap claude

# 或：自动扫描你机器上已装的代理（Claude Code / Cursor / Windsurf / Gemini / opencode / aider）
ripwire wrap --all

# Codex CLI 走另一条路
bash skills/install.sh --codex

上面两条命令做了什么：ripwire 把它的 MCP 服务器注册到你选的那个代理里，让代理在需要「读仓库之前先建地图」的时候自动调用 ripwire——你不用再手动命令。

它支持的代理名单（官方）

截至 0.6.0：Codex、Claude Code、Cursor、Windsurf、Gemini、opencode、aider——共 7 个生态接入点（README 原文：「Codex, Claude Code, Cursor, Windsurf, Gemini, opencode, aider」）。

装完不知道有没有装对？

ripwire wrap --all --dry-run   # 看会发生什么而不真改
ripwire . --doctor           # 检查 skill / hook 状态

07flags 速查（一页纸）

179 个长标志没法背，下面这张表把「家族 / 干啥的 / 常见搭配 / 别当什么用」四列摆齐。删掉这一节，读者以后还得重读 §02–§06 才能找到某个东西——这是上手件，留着。

08它和 ripgrep 到底差在哪

这里很多新手会搞混——名字里都带 rip、都是命令行、都要在仓库里跑。下面这张对照表把它们的边界划清。删掉这一节，读者下次在工具选择时刻还是会按"看着像所以差不多"判断，照着那判断要踩一次坑。

它们各自适合什么

09几个常见坑与边界

坑 1：以为它是索引服务

它没有守护进程，每次索引是临时的（一次 0.25–0.45 秒）。这意味着同一个仓库连跑两条命令，会重新索引两次。如果你要在 CI 里跑多次，把它放进 shell 脚本的同一行管道或单独步骤里，别用循环逐个调——索引的开销会叠加。

坑 2：以为 token 越多越好

把 --max-tokens 拉到 8000、9000 听起来信息更多，但超出现实对话窗口的内容模型读不到一半——浪费钱。3000 是经验值。任务复杂再用 --pack-task 分阶段。

坑 3：把 --quality-panel 当 CI 红线

六个证据家族每一个都有其视角。CI 拒过一次就合并失败？把六个家族的阈值调得合适；新代码首次过 review 时往往是名声最大的时候。

坑 4：以为 --scan-skill 是「恶意代码扫描器」

它扫的是 ripwire 支持的 skill 文件写法——比如是否含糊地请求权限、是否声明了边界。它不替代安全团队的代码审计。

边界 1：不支持 Windows

官方原文只覆盖 macOS 和 Linux（arm64 + x86-64）。Windows 用户要么跑 WSL2，要么等到官方加。

边界 2：动态调用 / 反射被低估

SCIP 与类似的静态分析（只读代码不运行代码的那种）对动态派发（运行时才决定调哪个函数那种情况）天然不可见。--impact 在 Python / Ruby / JS 这种反射重的语言里会有盲区——解决办法是跑 --from-trace，把运行时的 trace 喂给它。

边界 3：版本号变了命令语义就要重新核

179 个长标志意味着你不能背名字。装新版之后先跑 --doctor 再用熟悉的命令；README 也明说「--help 是权威来源」。

10最小例子：把 Claude Code 接到一个本地仓库

下面这段是个能完整走通的最小流程——装 ripwire → 接 Claude Code → 在 Claude 里先让它读仓库地图、回答问题。复制就能跑。

前置

• macOS 或 Linux（含 Apple Silicon 的 Mac）
• 已经装上 Claude Code（命令行）
• 能在终端里 curl 到 raw.githubusercontent.com

三步

一条命令看效果（不用 Claude）

cd your-project-repo
ripwire . --max-tokens=3000 | head -80      # 看仓库地图长什么样
ripwire . --callers=parseConfig             # 查 parseConfig 的调用方
ripwire . --html=map.html --color-by=churn # 生成变更热点图
open map.html   # macOS 上浏览器打开

挂到 CI 里

# CI 步骤（伪代码）
- run: RIPWIRE_REPO=redhat-et/ripwire bash -c "$(curl -fsSL ...)"
- run: ripwire . --test-gate
- run: ripwire . --quality-delta --base=origin/main

11常见问题

99一句话总结

98参考来源

• redhat-et/ripwire — 仓库主页（0.6.0 概述、七大家族、品牌 tagline "The ripgrep of AI context"）
• INSTALL.md（预编译安装命令、六个环境变量、离线构建步骤）
• README.md（Quickstart 四条命令、reflex flags、--quality-panel 六证据家族原文、--html 调用图示例）
• scripts/install.sh（安装脚本本体）