> 📜 用户协议（User Agreement）
> 1. 本 Skill 仅供学习与参考用途。使用本 Skill 产生的任何结果，由使用者自行承担全部责任；本 Skill 不提供任何明示或暗示的保证。
> 2. 涉及法律、财务、税务、投资、医疗等专业决策时，请务必咨询持证专业人士。
> 3. 本代码受版权法保护，未经授权复制、反向工程或商业利用将被追究法律责任。
<!-- user-agreement-injected -->
> ⚠️ 本内容仅供一般信息参考，不构成法律、财务、税务、投资或医疗建议。
> 涉及合同签署、报税、投资、诊疗等专业决策时，请务必咨询持证专业人士，并由使用者自行承担决策后果。
<!-- professional-disclaimer-injected -->
超高速代码搜索
> 递归搜索目录中的正则模式，自动忽略 .gitignore，比 grep 快 10 倍+
一、能力边界（一页纸速查卡）
适用对象（谁该用 / 谁不该用）
| 适用对象 | 典型场景 | 不适用对象 | 原因 |
|---|---|---|---|
| 开发者 | 在大型代码库中快速定位函数/变量/字符串 | 非技术用户 | 需要理解正则表达式基础 |
| DevOps | 在日志文件中过滤错误关键字 | 需要模糊语义搜索的用户 | 本工具是正则匹配，不支持语义理解 |
| 数据工程师 | 在数据文件中按模式提取行 | 需要跨文件关联分析的用户 | 本工具只做单文件行匹配，不做聚合分析 |
| 安全审计员 | 在代码中搜索敏感信息（如 API key 模式） | 需要全文翻译/总结的用户 | 本工具只搜索，不生成内容 |
| 技术文档作者 | 在文档中查找过时术语或链接 | 需要自然语言问答的用户 | 本工具是正则匹配，不支持语义理解 |
| 学生/学习者 | 在开源项目中学习代码结构 | 需要图形化界面操作的用户 | 本工具是命令行工具，无 GUI |
能做（10项核心能力）
- 按正则模式搜索：支持 PCRE2 正则语法，如
fn\s+\w+匹配函数定义 - 自动忽略规则：自动读取
.gitignore、.ignore、.rgignore，跳过隐藏文件与二进制文件 - 按文件类型过滤：
-t py只搜 Python，-T js排除 JS 文件 - 输出上下文：
-C 3显示匹配行前后 3 行，-A 2显示后 2 行 - 统计匹配计数：
-c输出每个文件的匹配行数，--count-matches输出总匹配次数 - 文件列表输出：
-l只输出包含匹配的文件名，-L输出不包含匹配的文件名 - 多目录搜索：可同时指定多个搜索路径，如
rg pattern dir1 dir2 - 替换预览：
--replace配合--passthru可预览替换效果（不实际写入） - 编码指定：
-E gbk指定文件编码，解决中文乱码问题 - JSON 结构化输出：
--json输出结构化结果，便于程序解析
不做（7项边界声明）
- 不做：不修改文件内容（
--replace仅预览，不写盘） - 不做：不搜索压缩包内部（
.zip、.tar.gz等需先解压） - 不做：不访问网络或远程仓库（仅本地文件系统）
- 不做：不支持模糊匹配或拼写纠错（严格正则语义）
- 不做：不保证跨平台行为一致（Windows 路径分隔符差异需注意）
- 不做：不执行搜索结果的后续操作（如自动替换、自动删除）
- 不做：不支持递归搜索符号链接目录（需加
-L选项）
边界场景判定表（明确能做/不做的具体场景）
| 用户请求 | 是否支持 | 说明与处理方式 |
|---|---|---|
| "搜索所有 .py 文件中的函数定义" | ✅ 支持 | 使用 rg -t py "def \w+" |
| "搜索日志文件中 ERROR 关键字" | ✅ 支持 | 使用 rg "ERROR" logs/ |
| "搜索代码中所有 TODO 注释" | ✅ 支持 | 使用 rg "TODO" -C 2 |
| "搜索包含 api_key 的文件" | ✅ 支持 | 使用 rg -l "api_key" |
| "统计匹配次数" | ✅ 支持 | 使用 rg -c "pattern" |
| "搜索并自动替换文件内容" | ❌ 不支持 | 本工具只搜索不修改，建议配合 sed 使用 |
| "搜索压缩包内的文件" | ❌ 不支持 | 需先解压再搜索 |
| "搜索远程 GitHub 仓库" | ❌ 不支持 | 仅支持本地文件系统 |
| "模糊搜索（如'类似'、'差不多'）" | ❌ 不支持 | 仅支持正则精确匹配 |
| "搜索并自动删除匹配文件" | ❌ 不支持 | 本工具不执行删除操作 |
| "搜索中文语义（如'找所有关于登录的代码'）" | ❌ 不支持 | 需提供具体关键字或正则模式 |
| "搜索图片/视频等二进制内容" | ❌ 不支持 | 默认跳过二进制文件，加 -a 可强制搜索但结果不可读 |
> 如果用户的需求超出以上边界，明确告知无法处理并说明原因，不强行执行。
二、触发方式（说大白话就能用）
触发词表（36类场景）
| 触发词 | 场景 |
|---|---|
| ripgrep | 通用场景 |
| rg搜索 | 通用场景 |
| 代码搜索 | 通用场景 |
| 正则搜索 | 通用场景 |
| grep替代 | 通用场景 |
| 搜代码 | 通用场景 |
| 找函数定义 | 特定场景：搜索函数/方法定义 |
| 排除node_modules搜索 | 特定场景：指定忽略目录 |
| 搜日志关键字 | 特定场景：在日志文件中搜索 |
| 按文件类型搜 | 特定场景：限定文件扩展名 |
| 搜出所有包含某词的文件 | 特定场景：只输出文件名 |
| 统计匹配次数 | 特定场景：计数统计 |
| 搜配置文件里的端口号 | 特定场景：搜索配置项 |
| 找API调用点 | 特定场景：搜索函数调用位置 |
| 查TODO注释 | 特定场景：搜索代码注释标记 |
| 搜敏感信息 | 特定场景：搜索密钥/密码模式 |
| 搜一下代码里哪里用了这个函数 | 特定场景：搜索函数调用位置 |
| 在logs文件夹里找ERROR关键字 | 特定场景：在日志文件中搜索 |
| 搜所有py文件里的TODO | 特定场景：限定文件类型搜索 |
| 找一下有没有包含api_key的文件 | 特定场景：只输出文件名 |
| 统计一下这个项目里有多少个FIXME | 特定场景：计数统计 |
| 搜的时候把node_modules排除掉 | 特定场景：指定忽略目录 |
| 看看这个函数在哪些地方被调用了 | 特定场景：搜索函数调用位置 |
| 帮我搜一下配置文件里所有端口号 | 特定场景：搜索配置项 |
| 搜一下代码里所有调用login的地方 | 特定场景：搜索函数调用位置 |
| 帮我找找项目里有没有硬编码的密码 | 特定场景：搜索敏感信息 |
| 搜一下所有TODO注释带上下文 | 特定场景：搜索代码注释标记 |
| 把项目里所有包含api_key的文件列出来 | 特定场景：只输出文件名 |
| 搜代码里所有报错的地方 | 特定场景：搜索错误关键字 |
| 找一下项目里所有import语句 | 特定场景：搜索导入语句 |
| 搜一下所有函数调用 | 特定场景：搜索函数调用模式 |
| 查一下这个变量在哪里定义的 | 特定场景：搜索变量定义 |
| 搜一下所有日志输出 | 特定场景：搜索日志语句 |
| 找找代码里所有TODO和FIXME | 特定场景：搜索注释标记组合 |
| 搜一下所有测试用例 | 特定场景：搜索测试代码 |
| 查一下配置文件里所有数据库连接 | 特定场景：搜索配置项 |
大白话触发示例（用户原话 → 触发动作）
| 用户可能会说 | 触发动作 |
|---|---|
| "帮我搜一下代码里哪里用了这个函数" | 启动搜索，提取函数名作为模式，默认全目录搜索 |
| "在 logs 文件夹里找 ERROR 关键字" | 启动搜索，指定目录为 logs，模式为 ERROR |
| "搜所有 .py 文件里的 TODO" | 启动搜索，加 -t py 过滤，模式为 TODO |
| "找一下有没有包含 api_key 的文件" | 启动搜索，加 -l 只输出文件名 |
| "统计一下这个项目里有多少个 FIXME" | 启动搜索，加 -c 统计每个文件匹配数 |
| "搜的时候把 node_modules 排除掉" | 启动搜索，自动加 -g '!node_modules' 排除规则 |
| "看看这个函数在哪些地方被调用了" | 启动搜索，模式为函数名，加 -C 2 显示上下文 |
| "帮我搜一下配置文件里所有端口号" | 启动搜索，模式为 port\s*[:=]\s*\d+，加 -t 按配置类型过滤 |
| "搜一下代码里所有调用 login 的地方" | 启动搜索，模式为 login\s*\(，加 -C 2 显示上下文 |
| "帮我找找项目里有没有硬编码的密码" | 启动搜索，模式为 password\s*=\s*['\"][^'\"]+['\"]，加 -i 忽略大小写 |
| "搜一下所有 TODO 注释，带上下文" | 启动搜索，模式为 TODO，加 -C 3 显示上下文 |
| "把项目里所有包含 api_key 的文件列出来" | 启动搜索，模式为 api_key，加 -l 只输出文件名 |
| "搜代码里所有报错的地方" | 启动搜索，模式为 error\|Error\|ERROR，加 -C 2 显示上下文 |
| "找一下项目里所有 import 语句" | 启动搜索，模式为 ^import\s，加 -t py 限定 Python 文件 |
| "搜一下所有函数调用" | 启动搜索，模式为 \w+\s*\(，加 -C 1 显示上下文 |
| "查一下这个变量在哪里定义的" | 启动搜索，模式为 变量名\s*=，加 -C 2 显示上下文 |
| "搜一下所有日志输出" | 启动搜索，模式为 logger\.\|log\.\|console\.log，加 -C 1 显示上下文 |
| "找找代码里所有 TODO 和 FIXME" | 启动搜索，模式为 TODO\|FIXME，加 -C 2 显示上下文 |
| "搜一下所有测试用例" | 启动搜索，模式为 test_\|def test\|it\(，加 -t py 或 -t js 过滤 |
| "查一下配置文件里所有数据库连接" | 启动搜索，模式为 db_\|database\|connection_string，加 -t 按配置类型过滤 |
三、标准流程（5分钟上手路径）
Step 1: 收集最小信息集
向用户确认以下关键信息（缺失则引导补采，不臆测）：
| 参数 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|
| 搜索模式（正则） | 必填 | 无 | 用户要匹配的内容，支持正则语法 |
| 搜索路径 | 选填 | 当前目录 | 指定搜索的根目录，默认 . |
| 文件类型过滤 | 选填 | 无 | 如 -t py、-t js，限定扩展名 |
| 排除规则 | 选填 | 自动读 .gitignore | 额外排除如 -g '!vendor' |
| 输出格式 | 选填 | 文件名:行号:内容 | 可选 -l 只列文件名，-c 统计计数 |
| 上下文行数 | 选填 | 0 | -C N 显示前后 N 行 |
| 编码指定 | 选填 | UTF-8 | -E gbk 等，解决中文乱码 |
| 大小写敏感 | 选填 | 敏感 | -i 忽略大小写 |
Step 2: 执行核心流程
- 解析输入：确认搜索模式、路径、过滤条件
- 构建命令：按以下规则组装 rg 命令：
- 基础：rg [选项] <模式> <路径>
- 文件类型：-t <类型>（如-t py）
- 排除：-g '!<glob>'（如-g '!node_modules'）
- 上下文：-C <行数>或-A <行数>/-B <行数>
- 只列文件名：-l
- 统计计数：-c或--count-matches
- 忽略大小写：-i
- 指定编码：-E <编码> - 执行搜索：运行命令并捕获输出
- 结果处理：
- 匹配结果 > 0：按输出格式整理结果
- 匹配结果 = 0：提示"未找到匹配项"，建议检查模式或扩大路径
- 命令执行失败：进入异常处理流程
Step 3: 输出与校验
- 结果整理：按用户要求的格式输出（文件名列表 / 带行号内容 / 统计计数）
- 自查清单：
- 是否遗漏了用户指定的过滤条件？
- 输出格式是否符合预期？
- 是否标注了匹配总数？
- 是否处理了编码问题？ - 二次确认：当匹配结果 > 100 条时，提示用户是否限制输出或按文件分组
四、异常处理（错误码体系）
| 错误码 | 场景 | 标准化话术 | 修正步骤 |
|---|---|---|---|
| E001 | 搜索模式为空 | "请提供要搜索的内容，例如：函数名、关键字或正则表达式" | 引导用户输入模式，示例：rg "TODO" . |
| E002 | 路径不存在 | "路径 {path} 不存在，请确认路径是否正确" | 检查路径拼写，或使用 rg pattern . 搜索当前目录 |
| E003 | 正则语法错误 | "正则表达式有误：{error_msg}，请检查括号和转义符" | 简化模式，或使用固定字符串搜索 -F 选项 |
| E004 | 权限不足 | "无法读取 {path}，权限不足，请检查文件权限" | 使用 sudo 或更换可读目录 |
| E005 | 匹配结果过多 | "匹配结果超过 1000 条，建议添加过滤条件或缩小搜索范围" | 建议加 -t 类型过滤，或 -g 排除目录 |
| E006 | 二进制文件干扰 | "检测到二进制文件，已自动跳过（可用 -a 强制搜索）" | 如需搜索二进制，加 -a 选项 |
| E007 | 编码问题 | "文件编码非 UTF-8，可能无法正确匹配（可用 -E 指定编码）" | 指定编码如 -E gbk，或转换文件编码 |
| E008 | 命令超时 | "搜索超过 30 秒，已中断。建议缩小搜索范围或增加排除规则" | 使用 -g '!node_modules' 排除大目录，或指定更精确路径 |
| E009 | 参数冲突 | "检测到参数冲突：{param1} 与 {param2} 不能同时使用" | 移除冲突参数，重新构建命令 |
| E010 | 输出文件无法写入 | "无法写入输出文件 {path}，请检查磁盘空间或权限" | 更换输出路径，或直接输出到终端 |
重试与降级策略（可执行配置示例）
| 场景 | 重试策略 | 降级策略 | 可执行配置示例 |
|---|---|---|---|
| 命令超时（>30s） | 自动重试 1 次，加 --max-filesize 5M 跳过超大文件 |
降级为分目录搜索，提示用户分批执行 | timeout 30 rg --max-filesize 5M "<模式>" <路径> \|\| rg -l "<模式>" <路径> |
| 内存不足 | 自动重试 1 次，加 -j 1 单线程执行 |
降级为只搜索文件名（-l），不输出内容 |
rg -j 1 "<模式>" <路径> \|\| rg -l "<模式>" <路径> |
| 权限错误 | 不重试，直接报错 | 提示用户更换目录或使用 sudo | rg "<模式>" <路径> 2>&1 \| grep -v "Permission denied" |
| 正则复杂度过高 | 自动重试 1 次，加 --no-pcre2 降级为默认正则引擎 |
降级为固定字符串搜索（-F） |
rg --no-pcre2 "<模式>" <路径> \|\| rg -F "<模式>" <路径> |
| 编码识别失败 | 自动重试 1 次，加 -E utf-8 强制指定 |
降级为二进制搜索（-a），提示用户手动处理 |
rg -E utf-8 "<模式>" <路径> \|\| rg -a "<模式>" <路径> |
| 磁盘空间不足 | 不重试，直接报错 | 提示用户清理磁盘或更换输出路径 | df -h <路径> \|\| rg "<模式>" <路径> > /dev/null |
五、常见问题（FAQ 速查）
新手常见错误
| 错误用法 | 错误原因 | 正确做法 |
|---|---|---|
rg "foo" "bar" |
两个参数都被当作模式，路径缺失 | 正确：rg "foo" . 或 rg "foo" bar/ |
rg foo -t py js |
-t 只接受一个类型，js 被当作路径 |
正确：rg foo -t py -t js 或 rg foo -t py -g '*.js' |
rg "foo" --ignore-case |
选项拼写错误（应为 -i 或 --ignore-case） |
正确：rg -i "foo" |
| 搜索时未排除 node_modules | 结果被大量第三方代码淹没 | 正确：rg "foo" -g '!node_modules' |
使用 grep 语法 |
如 rg "foo*" 期望通配符，但 * 在正则中表示重复 |
正确：rg "foo.*" 或使用 -F 固定字符串 |
| 搜索中文乱码 | 文件编码非 UTF-8 | 正确：rg "中文" -E gbk |
忘记加 -i 导致大小写不匹配 |
默认区分大小写 | 正确：rg -i "foo" |
使用 -t 时类型名拼写错误 |
如 -t py 写成 -t python |
正确：rg --type-list 查看所有支持的类型名 |
rg "foo" -g node_modules |
-g 默认是包含模式，不是排除 |
正确：rg "foo" -g '!node_modules' |
| 搜索时未加引号导致 shell 展开 | 如 rg foo* . 中 * 被 shell 展开 |
正确：rg "foo*" . 或 rg 'foo*' . |
高频问题
- Q1: 搜索速度如何？ → 百万行代码约 1-2 秒，比 grep 快 10 倍以上
- Q2: 会不会搜到 node_modules？ → 默认自动忽略 .gitignore 中的目录，也可手动加
-g '!node_modules' - Q3: 支持哪些正则语法？ → 默认支持 PCRE2 语法，比 grep 的 POSIX 语法更强大
- Q4: 如何只搜索特定类型文件？ → 使用
-t py、-t js等，或-g '*.py' - Q5: 如何排除多个目录？ → 使用多个
-g '!dir'参数，如-g '!node_modules' -g '!vendor' - Q6: 如何搜索隐藏文件？ → 默认跳过隐藏文件，加
--hidden可包含 - Q7: 如何搜索二进制文件？ → 默认跳过，加
-a强制搜索 - Q8: 如何输出到文件？ → 使用
> output.txt重定向，或--json输出结构化结果 - Q9: 如何搜索时忽略大小写？ → 加
-i或--ignore-case - Q10: 如何搜索整个单词？ → 使用
\b边界，如rg "\bfoo\b" - Q11: 如何搜索包含特殊字符的内容？ → 使用
-F固定字符串模式，如rg -F "a.b*c" - Q12: 如何查看所有支持的文件类型？ → 使用
rg --type-list查看完整列表 - Q13: 如何搜索时显示行号？ → 默认显示行号，如不需要可用
-N关闭 - Q14: 如何搜索时排除测试文件？ → 使用
-g '!test*'或-g '!*_test.go'等模式 - Q15: 如何搜索时包含符号链接？ → 默认跳过符号链接，加
-L可包含 - Q16: 如何搜索多个模式？ → 使用
-e参数，如rg -e "foo" -e "bar" . - Q17: 如何搜索时显示文件大小？ → 使用
--stats查看统计信息 - Q18: 如何搜索时按修改时间过滤？ → 配合
find命令，如find . -name "*.py" -mtime -7 | xargs rg "foo"
更多常见坑（补充）
| 坑点 | 现象 | 解决方案 |
|---|---|---|
| 路径含空格 | rg "foo" /path/with space/ 报错 |
给路径加引号：rg "foo" "/path/with space/" |
模式以 - 开头 |
rg -foo . 被解析为选项 |
使用 -- 分隔：rg -- -foo . |
搜索时未加 -t 导致匹配过多 |
结果包含大量非目标文件 | 加 -t py 或 -g '*.py' 限定类型 |
使用 -c 但期望总计数 |
-c 输出每个文件的计数，不是总数 |
使用 --count-matches 获取总匹配次数 |
搜索时未加 -i 导致漏匹配 |
大小写不一致导致漏掉结果 | 加 -i 忽略大小写 |
搜索时未加 -C 导致上下文缺失 |
无法判断匹配行上下文 | 加 -C 2 或 -C 5 显示上下文 |
搜索时未加 -E 导致中文乱码 |
中文文件编码非 UTF-8 | 加 -E gbk 或 -E shift_jis |
搜索时未加 --hidden 导致漏掉隐藏文件 |
隐藏文件未被搜索 | 加 --hidden 包含隐藏文件 |
搜索时未加 -L 导致漏掉符号链接 |
符号链接指向的文件未被搜索 | 加 -L 包含符号链接 |
搜索时未加 -a 导致漏掉二进制文件 |
二进制文件被跳过 | 加 -a 强制搜索二进制文件 |
六、进阶用法（深度按需）
6.1 参数化搜索（模板化命令）
以下为常用参数化模板，可直接替换占位符使用：
| 模板名称 | 命令模板 | 适用场景 |
|---|---|---|
| 基础搜索 | rg "<模式>" <路径> |
快速搜索 |
| 类型限定 | rg -t <类型> "<模式>" <路径> |
限定文件类型 |
| 上下文搜索 | rg -C <行数> "<模式>" <路径> |
查看上下文 |
| 排除目录 | rg -g '!<目录>' "<模式>" <路径> |
排除大目录 |
| 计数统计 | rg -c "<模式>" <路径> |
统计匹配数 |
| 文件名列表 | rg -l "<模式>" <路径> |
只列文件名 |
| 忽略大小写 | rg -i "<模式>" <路径> |
不区分大小写 |
| 编码指定 | rg -E <编码> "<模式>" <路径> |
处理非 UTF-8 |
| JSON 输出 | rg --json "<模式>" <路径> |
程序解析 |
| 多模式搜索 | rg -e "<模式1>" -e "<模式2>" <路径> |
同时搜多个模式 |
| 固定字符串搜索 | rg -F "<字符串>" <路径> |
搜索含特殊字符的字符串 |
| 全局搜索（含隐藏文件） | rg --hidden "<模式>" <路径> |
搜索隐藏文件 |
| 包含符号链接 | rg -L "<模式>" <路径> |
搜索符号链接指向的文件 |
| 最大文件大小限制 | rg --max-filesize <大小> "<模式>" <路径> |
跳过超大文件 |
| 多线程加速 | rg -j <线程数> "<模式>" <路径> |
大型代码库加速 |
6.2 扩展能力（与其他工具集成）
| 集成场景 | 命令示例 | 说明 |
|---|---|---|
配合 sed 替换 |
rg -l "<模式>" <路径> \| xargs sed -i 's/<模式>/<替换>/g' |
批量替换匹配内容 |
配合 xargs 处理 |
rg -l "<模式>" <路径> \| xargs wc -l |
统计匹配文件行数 |
配合 sort 排序 |
rg "<模式>" <路径> \| sort -t: -k2 -n |
按行号排序输出 |
配合 head 限制 |
rg "<模式>" <路径> \| head -n 20 |
只显示前 20 条结果 |
配合 awk 提取 |
rg "<模式>" <路径> \| awk -F: '{print $1}' |
提取文件名列 |
配合 git 搜索 |
git grep "<模式>" |
在 git 仓库中搜索 |
配合 jq 解析 JSON |
rg --json "<模式>" <路径> \| jq '.data.path' |
提取 JSON 字段 |
配合 fzf 交互选择 |
rg -l "<模式>" <路径> \| fzf |
交互式选择文件 |
配合 watch 实时监控 |
watch "rg -c '<模式>' <路径>" |
实时监控匹配数变化 |
配合 cron 定时任务 |
0 * * * * rg -l "<模式>" <路径> > /tmp/match.txt |
定时执行搜索 |
6.3 高级正则技巧
| 技巧 | 正则示例 | 说明 |
|---|---|---|
| 非贪婪匹配 | foo.*?bar |
匹配最短的 foo...bar |
| 捕获组 | (foo)\1 |
反向引用捕获组 |
| 前瞻断言 | foo(?=bar) |
匹配后面是 bar 的 foo |
| 后顾断言 | (?<=foo)bar |
匹配前面是 foo 的 bar |
| 交替匹配 | foo\|bar |
匹配 foo 或 bar |
| 字符类 | [a-z0-9_] |
匹配小写字母/数字/下划线 |
| 量词 | a{2,4} |
匹配 2-4 个 a |
| 转义字符 | \. |
匹配字面量点号 |
| 单词边界 | \bfoo\b |
匹配完整的单词 foo |
| 行首/行尾锚点 | ^foo / foo$ |
匹配行首/行尾 |
| Unicode 属性 | \p{Han} |
匹配中文字符 |
| 嵌套分组 | (foo(bar)?)+ |
匹配 foo 或 foobar 的重复 |
6.4 智能洞察（模式识别与质量评分）
在搜索完成后，自动执行以下智能分析步骤：
-
模式识别：
- 自动检测匹配结果的文件类型分布（如 60% 在 .py 文件，30% 在 .js 文件）
- 识别高频匹配文件（Top 5 文件），提示用户重点关注
- 检测匹配模式是否集中在特定目录（如 src/ 或 test/）
- 识别匹配模式的时间趋势（如最近修改的文件中匹配数是否增加） -
质量评分（0-100 分）：
- 搜索质量分：基于匹配结果的精确度（精确匹配占比）、覆盖率（目标文件命中率）- 精确匹配占比 > 80%：90-100 分
- 精确匹配占比 60-80%：70-89 分
- 精确匹配占比 < 60%：50-69 分
- 模式质量分：基于正则表达式的复杂度（过简可能误匹配，过繁可能漏匹配）
- 模式包含边界符（
\b、^、$）：90-100 分 - 模式包含字符类或量词：70-89 分
- 模式为纯字符串：50-69 分
- 结果可用性分：基于结果是否包含足够上下文、是否易于定位
- 结果包含上下文且按文件分组：90-100 分
- 结果包含行号但无上下文：70-89 分
- 结果仅为文件名列表：50-69 分
-
建议输出：
- 若匹配结果 > 500 条：建议添加过滤条件，如-t py或-g '!test'
- 若匹配结果 < 5 条：建议检查模式是否正确，或扩大搜索范围
- 若匹配集中在少数文件：建议检查这些文件是否包含重复代码
- 若匹配结果包含大量注释：建议加-g '!*.md'排除文档文件
- 若匹配结果包含大量测试文件：建议加-g '!test*'排除测试代码
- 若匹配结果包含大量第三方库：建议加-g '!vendor'或-g '!node_modules'
6.5 性能优化指南
| 场景 | 优化策略 | 预期效果 |
|---|---|---|
| 大型代码库（>100万行） | 加 -j 4 多线程，--max-filesize 5M 跳过超大文件 |
速度提升显著 |
| 搜索包含大量二进制文件 | 加 -a 强制搜索，或 -g '!*.bin' 排除 |
避免误匹配 |
| 搜索包含大量小文件 | 加 --sort path 按路径排序，便于结果分组 |
结果更有序 |
| 搜索包含符号链接 | 加 -L 包含符号链接，或 -g '!link*' 排除 |
控制搜索范围 |
| 搜索包含隐藏文件 | 加 --hidden 包含隐藏文件 |
覆盖更全面 |
| 搜索包含超大文件 | 加 --max-filesize 10M 跳过超大文件 |
避免卡顿 |
| 搜索包含大量目录 | 加 --max-depth 3 限制搜索深度 |
控制搜索范围 |
| 搜索包含大量重复文件 | 加 --no-messages 抑制错误输出 |
减少干扰 |
七、渐进式披露（分层次阅读路径）
第一层：快速上手（5分钟）
> 适合第一次使用 ripgrep 的用户
- 阅读 [一、能力边界] 了解工具能做什么
- 阅读 [三、标准流程] 掌握基本用法
- 尝试运行：
rg "TODO" .搜索当前目录 - 遇到问题查看 [五、常见问题] 中的新手错误表
第二层：进阶应用（30分钟）
> 适合需要提高搜索效率的用户
- 阅读 [六、进阶用法] 学习参数化模板
- 阅读 [五、常见问题] 避免常见错误
- 尝试运行：
rg -t py -C 2 "def " .搜索 Python 函数定义 - 尝试运行：
rg -l "api_key" . -g '!node_modules'列出包含 api_key 的文件 - 尝试运行：
rg -c "FIXME" .统计每个文件的 FIXME 数量
第三层：高级技巧（2小时）
> 适合需要深度定制搜索的用户
- 阅读 [六、进阶用法] 中的高级正则技巧
- 阅读 [六、进阶用法] 中的性能优化指南
- 阅读 [六、进阶用法] 中的智能洞察部分
- 尝试运行：
前置条件
- 无特殊环境要求
执行步骤
- 收集用户输入并确认格式
- 按功能逻辑处理输入内容
- 生成结果并校验完整性
输出
- 结构化文本结果，附处理说明
许可证
本 Skill 基于 MIT 许可证发布（详见项目源仓库 LICENSE 文件）。使用者可自由使用、修改与分发，但需保留版权声明与许可文本。<!-- professional-license-embedded -->
稳定性保障
- 大文件保护：超过 10MB 的文件自动跳过，避免内存耗尽；大文件分块流式读取
- 二进制识别：自动检测二进制文件并跳过（含 NUL 字节或无法解码的内容）
- 多编码支持：UTF-8 / GB18030 / Latin-1 自动 fallback，中文项目无乱码
- 多线程并行：默认 4 线程扫描，大目录搜索显著加速
- 退出码语义：0=有匹配，1=无匹配或错误，便于脚本集成
FAQ 与反模式
Q：为什么搜不到 node_modules 里的内容？
A：默认忽略噪音目录（node_modules/.git/dist/pycache 等），可用自定义目录遍历避免。
Q：支持中文搜索吗？
A：支持，自动处理 UTF-8/GBK 编码，正则模式可直接写中文。
Q：只搜特定文件类型？
A：用 -t py -t js 限定扩展名，或 --depth 限制目录深度。
反模式 ①：不忽略大小写搜 TODO 却想找 todo —— 用 -i 忽略大小写。
反模式 ②：在超大目录全量搜索无限制 —— 先用 --depth 或 -t 缩小范围。
反模式 ③：把搜索输出直接作为最终结论 —— 关键代码定位务必人工确认上下文。
安全声明
- 全流程本地执行，不上传任何用户数据到第三方服务。
- 不读取与任务无关的目录，不写入系统目录。
- 处理含个人信息的数据时，请自行遵守《个人信息保护法》等相关法规。
- 本 Skill 代码由 AI 辅助生成并经自检验证，以 MIT 协议开源，使用者自负使用后果。
