<identity>
Enhanced code search with ripgrep binary. NOTE: Prefer `pnpm search:code` for discovery/ranking and smaller output payloads; prefer raw `rg` for fastest exact literal matching.
</identity>
<capabilities>
- **DEPRECATED**: Use `pnpm search:code "query"` instead (hybrid ripgrep + embeddings)
- Raw ripgrep access for advanced regex patterns (PCRE2 with -P flag)
- Custom file type definitions via .ripgreprc
- Integration with .gitignore and custom ignore patterns
</capabilities>
<identity>
基于ripgrep二进制的增强型代码搜索工具。注意：如需发现/排序功能和更小的输出负载，优先使用`pnpm search:code`；如需最快的精确字面匹配，优先使用原生`rg`命令。
</identity>
<capabilities>
- **已废弃**：请改用`pnpm search:code "query"`（混合ripgrep + 向量嵌入）
- 原生ripgrep访问，支持高级正则模式（带-P标志的PCRE2）
- 通过.ripgreprc自定义文件类型定义
- 与.gitignore和自定义忽略模式集成
</capabilities>
⚡ RECOMMENDED: Hybrid Lazy Code Search (Instant, No Batch Indexing)
⚡ 推荐：混合惰性代码搜索（即时响应，无需批量索引）
Use the hybrid lazy search system for day-to-day code discovery:
- Instant: search works immediately with no warm-up indexing pass
- No upfront indexing: Search immediately with no multi-hour batch index build
- Lazy embeddings: Semantic vectors update incrementally in background as files are edited
- Hybrid scoring: Reciprocal Rank Fusion (RRF) combines text matches + semantic similarity
日常代码发现工作请使用混合惰性搜索系统：
- 即时响应：搜索无需预热索引，立即生效
- 无前置索引：无需耗时数小时的批量索引构建，可立即搜索
- 惰性嵌入：语义向量在文件编辑时于后台增量更新
- 混合评分：采用Reciprocal Rank Fusion (RRF) 结合文本匹配与语义相似度
Search code instantly (ripgrep-based)
即时搜索代码（基于ripgrep）
pnpm search:code "authentication logic"
pnpm search:code "export class User"
pnpm search:code "import react"
pnpm search:code "authentication logic"
pnpm search:code "export class User"
pnpm search:code "import react"
View project structure
查看项目结构
Get file content with line numbers
获取带行号的文件内容
pnpm search:file src/auth.ts 1 50
pnpm search:file src/auth.ts 1 50
Search Mode Contract (Deterministic)
搜索模式约定（确定性）
| Mode | Use when | Latency tendency | Determinism | Output/token impact |
| -------------------------------- | ------------------------------------------------- | ------------------------------ | ----------- | ------------------------------- | -------------------- |
|
| Concept discovery, unknown implementation paths | Fast | High | Compact ranked output |
|
pnpm search:code "ast:pattern"
| Structural pattern intent (AST shape) | Moderate | High | Compact + structure-aware |
|
| System map: entrypoints, dependencies, boundaries | Fast | High | Very low |
|
| Exact symbol/literal lookup and anchor checks | Fastest | Highest | Potentially large unless scoped |
|
| Non-code assets (pdf/docs/archive) | Slower than
| High | Can be high noise |
|
| Manual narrowing and selection | Interactive | Operator-dependent | Good human triage UX |
Required selection behavior:
- Agents must default to for discovery.
- Agents must use before edits/refactors to validate exact anchors.
- Agents should use only for explicitly structural requests.
- stays optional for human-in-the-loop workflows; do not require it for automation.
| 模式 | 使用场景 | 延迟趋势 | 确定性 | 输出/Token影响 |
|---|
| 概念发现、未知实现路径探索 | 快 | 高 | 紧凑的排序输出 |
pnpm search:code "ast:pattern"
| 结构化模式匹配（AST形状） | 中等 | 高 | 紧凑且感知结构的输出 |
| 系统映射：入口点、依赖关系、边界 | 快 | 高 | 输出量极低 |
| 精确符号/字面量查找和锚点校验 | 最快 | 最高 | 除非限定范围，否则输出量可能很大 |
| 非代码资产（PDF/文档/归档文件） | 比慢 | 高 | 可能存在大量噪声 |
| 手动筛选和选择 | 交互式 | 依赖操作者 | 良好的人工筛选体验 |
必须遵循的选择规则：
- Agent进行发现工作时，默认使用
- 编辑/重构前，必须使用验证精确锚点
- 仅在明确需要结构匹配时使用模式
- 仅用于人工介入的工作流，自动化流程中不强制要求
Interactive Narrowing with fzf (Operator UX)
结合fzf进行交互式筛选（操作者体验）
When result sets are large, use
to interactively narrow
/
output.
rg + fzf + file preview
rg + fzf + 文件预览
rg --line-number --no-heading --color=always "auth|token|session" .
| fzf --ansi --delimiter ":"
--preview "bat --color=always --style=numbers --highlight-line {2} {1}"
rg --line-number --no-heading --color=always "auth|token|session" . \
| fzf --ansi --delimiter ":" \
--preview "bat --color=always --style=numbers --highlight-line {2} {1}"
rga (documents/archives) + fzf
rga（文档/归档）+ fzf
rga --line-number --no-heading --color=always "invoice|receipt|policy" .
| fzf --ansi --delimiter ":"
--preview "bat --color=always --style=numbers --line-range=:300 {1}"
Advanced interactive ripgrep launcher pattern:
```bash
: | rg_prefix='rg --column --line-number --no-heading --color=always --smart-case' \
fzf --ansi --disabled \
--bind 'start:reload:$rg_prefix ""' \
--bind 'change:reload:$rg_prefix {q} || true'
Usage contract:
- Use for operator selection/narrowing, not as a replacement for search backends.
- Keep as default for agent discovery/ranking workflows.
- Use / + for interactive triage and manual result picking.
Structural + interactive workflow (human triage):
rga --line-number --no-heading --color=always "invoice|receipt|policy" . \
| fzf --ansi --delimiter ":" \
--preview "bat --color=always --style=numbers --line-range=:300 {1}"
高级交互式ripgrep启动器模式：
```bash
: | rg_prefix='rg --column --line-number --no-heading --color=always --smart-case' \\
fzf --ansi --disabled \\
--bind 'start:reload:$rg_prefix ""' \\
--bind 'change:reload:$rg_prefix {q} || true'
使用约定：
- 用于操作者选择/筛选，而非替代搜索后端
- Agent发现/排序工作流中，默认使用
- 交互式筛选和手动结果选择使用/ +
结构化+交互式工作流（人工筛选）：
Structural candidates (ast-grep)
结构化候选（ast-grep）
ast-grep -p 'function $NAME($$$) { $$$ }' --lang javascript --files-with-matches .
ast-grep -p 'function $NAME($$$) { $$$ }' --lang javascript --files-with-matches .
Narrow candidates interactively
交互式筛选候选
ast-grep -p 'function $NAME($$$) { $$$ }' --lang javascript --files-with-matches .
| fzf --ansi --delimiter ":"
--preview "bat --color=always --style=numbers --line-range=:220 {}"
ast-grep -p 'function $NAME($$$) { $$$ }' --lang javascript --files-with-matches . \
| fzf --ansi --delimiter ":" \
--preview "bat --color=always --style=numbers --line-range=:220 {}"
- Pre-prompt hook analyzes repository structure using ripgrep (~0.5s)
- executes fast text matching via ripgrep
- Optional semantic embeddings add similarity-based ranking
- Post-edit hook incrementally embeds only changed files
- RRF merges text and semantic rankings into a single ordered result set
- 预提示钩子使用ripgrep分析仓库结构（约0.5秒）
- 通过ripgrep执行快速文本匹配
- 可选的语义嵌入添加基于相似度的排序
- 编辑后钩子仅增量嵌入已更改的文件
- RRF将文本匹配和语义排序合并为单一有序结果集
Optional binary overrides (normally auto-detected)
可选二进制覆盖（通常自动检测）
RG_BIN=/path/to/rg
AST_GREP_BIN=/path/to/ast-grep
RGA_BIN=/path/to/rga
FZF_BIN=/path/to/fzf
RG_BIN=/path/to/rg
AST_GREP_BIN=/path/to/ast-grep
RGA_BIN=/path/to/rga
FZF_BIN=/path/to/fzf
Disable semantic search (text-only, fastest)
禁用语义搜索（仅文本，速度最快）
Enable semantic search (requires LanceDB)
启用语义搜索（需要LanceDB）
Disable daemon transport (direct CLI execution)
禁用守护进程传输（直接CLI执行）
Auto-prewarm daemon on startup
启动时自动预热守护进程
HYBRID_DAEMON_PREWARM=true
HYBRID_DAEMON_PREWARM=true
Daemon idle timeout in ms (default 600000)
守护进程空闲超时（毫秒，默认600000）
HYBRID_DAEMON_IDLE_MS=600000
HYBRID_DAEMON_IDLE_MS=600000
Daemon + Prewarm Runbook
守护进程+预热操作手册
Start, verify, prewarm
启动、验证、预热
pnpm search:daemon:start
pnpm search:daemon:status
pnpm search:daemon:prewarm
pnpm search:daemon:start
pnpm search:daemon:status
pnpm search:daemon:prewarm
Search (daemon path)
搜索（通过守护进程）
pnpm search:code "authentication logic"
pnpm search:code "authentication logic"
pnpm search:daemon:stop
Expected latency profile on this repository:
- Cold daemon first query (no prewarm): ~1.35s avg
- First query after prewarm: ~0.40s avg
- Warm repeated daemon queries: ~0.18-0.19s
- Direct mode (`HYBRID_SEARCH_DAEMON=off`): ~0.73s avg for repeated CLI calls
pnpm search:daemon:stop
本仓库的预期延迟表现：
- 冷启动守护进程首次查询（未预热）：平均约1.35秒
- 预热后首次查询：平均约0.40秒
- 预热后重复查询：约0.18-0.19秒
- 直接模式（`HYBRID_SEARCH_DAEMON=off`）：重复CLI调用平均约0.73秒
Comparison with Batch Indexing
与批量索引的对比
| Approach | Startup | First Search | Memory | Disk |
|---|
| Old Batch Indexing | 2+ hours | Instant after index | 8-16GB | 2-5GB |
| Hybrid Lazy Search | 0 seconds | ~0.5s | <500MB | <100MB |
| 方法 | 启动时间 | 首次搜索速度 | 内存占用 | 磁盘占用 |
|---|
| 旧批量索引 | 2小时以上 | 索引完成后即时响应 | 8-16GB | 2-5GB |
| 混合惰性搜索 | 0秒 | 约0.5秒 | <500MB | <100MB |
Measured Performance and Output (This Repo)
实测性能与输出（本仓库）
Using the same 5 queries on this repository:
| Mode | Avg Latency | Avg Output Bytes | Best Use Case |
|---|
| () | ~227ms | ~461 bytes | Fast discovery with compact output |
| () | ~734ms | ~512 bytes | Semantic/concept queries |
| Raw literal search | ~35ms | ~2478 bytes | Exact symbol/literal lookup |
Interpretation:
- Raw is fastest for exact literal/symbol lookups
- Hybrid search returns significantly smaller output payloads (often lower token pressure)
- Embeddings improve semantic recall, but add latency
在本仓库中使用相同的5个查询测试：
| 模式 | 平均延迟 | 平均输出字节数 | 最佳使用场景 |
|---|
| （） | ~227ms | ~461字节 | 快速发现，输出紧凑 |
| （） | ~734ms | ~512字节 | 语义/概念查询 |
| 原生字面搜索 | ~35ms | ~2478字节 | 精确符号/字面量查找 |
结论：
- 原生是精确字面量/符号查找的最快方式
- 混合搜索返回的输出负载显著更小（通常Token压力更低）
- 向量嵌入提升语义召回率，但会增加延迟
Decision Rule (Practical)
实用决策规则
- Query is conceptual/natural language (
"auth flow for refresh tokens"
- You need ranked results and concise context for agent prompts
- You want lower output volume by default
- Query is an exact symbol/literal (, , exact export names)
- You need the fastest possible lookup time
- You need advanced regex/PCRE2 behavior
- 查询为概念性/自然语言（如
"auth flow for refresh tokens"
- 需要排序结果和用于Agent提示的简洁上下文
- 默认希望输出量更小
- 查询为精确符号/字面量（如、、精确导出名称）
- 需要最快的查找速度
- 需要高级正则/PCRE2特性
Measured by File Size (This Repo)
按文件大小实测（本仓库）
Sample size: 4 small files (0.5-5KB), 4 large files (30-109KB), literal token queries.
| Bucket | off | on | | |
|---|
| Small files | ~230ms / ~2707B | ~600ms / ~2965B | ~34ms / ~17075B | ~15ms / ~1156B |
| Large files | ~228ms / ~2354B | ~475ms / ~2847B | ~35ms / ~17811B | ~15ms / ~6564B |
Takeaways:
- is fastest and best for targeted file-level checks.
- remains fastest for repo-wide literal scans, but emits much larger output payloads.
- has steadier latency across file sizes and typically lower output volume for prompt usage.
样本：4个小文件（0.5-5KB），4个大文件（30-109KB），字面量Token查询。
| 文件分类 | 关闭 | 开启 | | |
|---|
| 小文件 | ~230ms / ~2707B | ~600ms / ~2965B | ~34ms / ~17075B | ~15ms / ~1156B |
| 大文件 | ~228ms / ~2354B | ~475ms / ~2847B | ~35ms / ~17811B | ~15ms / ~6564B |
结论：
- 是针对目标文件检查的最快方式。
- 仍是仓库范围字面量扫描的最快方式，但会产生大得多的输出负载。
- 在不同文件大小下的延迟更稳定，且通常输出量更小，适合提示使用。
Real-World Scenario Playbook (Tested Patterns)
真实场景使用指南（已测试模式）
Use these scenario patterns to choose the right search path quickly.
Scenario 1: Incident Triage (Unknown Root Cause)
场景1：事件排查（未知根因）
Goal: find likely hotspots for a production symptom quickly without flooding context.
目标：快速找到生产问题的可能热点，避免上下文过载。
1) Start broad and semantic
1) 先进行宽泛的语义搜索
pnpm search:code "task status not updating after completion"
pnpm search:code "任务完成后状态未更新"
2) Pivot to exact symbol checks once candidates appear
2) 出现候选结果后，转向精确符号校验
pnpm search:code "TaskUpdate("
Pattern:
- Start with `search:code` for intent-level recall.
- Narrow with literal/symbol queries once candidate files are identified.
pnpm search:code "TaskUpdate("
模式：
- 先用`search:code`进行意图级召回
- 确定候选文件后，使用字面量/符号查询缩小范围
Scenario 2: Fast Exact Lookup (You Know the Identifier)
场景2：快速精确查找（已知标识符）
Goal: locate exact definitions/usages as fast as possible.
Repo-wide exact literal (stable example in this repo)
仓库范围精确字面量（本仓库稳定示例）
rg -F "TaskUpdate(" -g ".cjs" -g ".js" -g "*.ts" .
rg -F "TaskUpdate(" -g ".cjs" -g ".js" -g "*.ts" .
Single-file exact lookup (fastest path)
单文件精确查找（最快路径）
rg -F "spawnSync" .claude/skills/skill-creator/scripts/create.cjs
Pattern:
- Use raw `rg -F` for exact symbol searches, especially for large files or known paths.
rg -F "spawnSync" .claude/skills/skill-creator/scripts/create.cjs
模式：
- 对于精确符号搜索，尤其是大文件或已知路径，使用原生`rg -F`
Scenario 3: Safe Refactor Prep
场景3：安全重构准备
Goal: enumerate callsites before renaming or behavior changes.
1) Gather broad callsites
1) 收集所有相关调用点
pnpm search:code "TaskUpdate completed status workflow"
pnpm search:code "TaskUpdate completed status workflow"
2) Confirm exact callsites and edge usage
2) 确认精确调用点和边缘用法
rg -F "TaskUpdate(" -g ".cjs" -g ".js" -g "*.ts"
Pattern:
- Hybrid first to find semantic variants.
- Raw `rg` second for deterministic callsite inventory.
rg -F "TaskUpdate(" -g ".cjs" -g ".js" -g "*.ts"
模式：
- 先用混合搜索找到语义变体
- 再用原生`rg`进行确定性调用点盘点
Scenario 4: Security Audit Sweep
场景4：安全审计扫描
Goal: detect risky patterns and confirm exact high-confidence matches.
Concept discovery (broad)
概念发现（宽泛）
pnpm search:code "command injection shell true spawn"
pnpm search:code "command injection shell true spawn"
Exact dangerous usage checks
精确危险用法校验
rg -F "shell: true" -g ".cjs" -g ".js"
rg -F "spawnSync(" -g ".cjs" -g ".js"
Pattern:
- Hybrid surfaces related risky code.
- Exact `rg` validates actionable matches for remediation.
rg -F "shell: true" -g ".cjs" -g ".js"
rg -F "spawnSync(" -g ".cjs" -g ".js"
模式：
- 混合搜索找出相关风险代码
- 精确`rg`验证可修复的匹配项
Scenario 5: Architecture Onboarding (New Contributor/Agent)
场景5：架构入门（新贡献者/Agent）
Goal: understand structure before making changes.
Focused concept entry points
聚焦概念入口点
pnpm search:code "routing guard task lifecycle"
pnpm search:code "memory scheduler session context"
Pattern:
- Use structure first, then concept search by subsystem intent.
pnpm search:code "routing guard task lifecycle"
pnpm search:code "memory scheduler session context"
模式：
- 先查看结构，再按子系统意图进行概念搜索
Scenario 6: Token-Constrained Agent Workflow
场景6：Token受限的Agent工作流
Goal: minimize prompt/context bloat while maintaining retrieval quality.
目标：在保持检索质量的同时最小化提示/上下文膨胀。
Keep semantic off by default for speed and concise output
默认关闭语义搜索，追求速度和简洁输出
HYBRID_EMBEDDINGS=off pnpm search:code "workflow task completion guard"
HYBRID_EMBEDDINGS=off pnpm search:code "workflow task completion guard"
Enable semantic only when lexical matches are weak
仅在词汇匹配效果差时启用语义搜索
HYBRID_EMBEDDINGS=on pnpm search:code "why task completion silently fails"
Pattern:
- Default to `HYBRID_EMBEDDINGS=off`.
- Turn on embeddings only for intent-heavy or poor lexical queries.
- If `HYBRID_EMBEDDINGS=off` returns no hits, re-run immediately with `HYBRID_EMBEDDINGS=on`.
HYBRID_EMBEDDINGS=on pnpm search:code "why task completion silently fails"
模式：
- 默认使用`HYBRID_EMBEDDINGS=off`
- 仅针对意图性强或词汇匹配效果差的查询开启向量嵌入
- 如果`HYBRID_EMBEDDINGS=off`无结果，立即用`HYBRID_EMBEDDINGS=on`重新运行
Reusable Query Patterns
可复用查询模式
- Concept query:
"authentication flow refresh token validation"
- Mixed query:
"TaskUpdate completed status"
- Exact query: (prefer when speed is critical)
- Structure query: use before large edits
- File drill-down:
pnpm search:file <path> <startLine> <endLine>
Only use raw ripgrep (below) for:
- Advanced PCRE2 regex patterns (lookahead/lookbehind)
- Custom file type filtering not supported by
- Pipeline integration with other CLI tools
<instructions>
<execution_process>
- 概念查询：
"authentication flow refresh token validation"
- 混合查询：
"TaskUpdate completed status"
- 精确查询：（追求速度时优先用）
- 结构查询：在大型编辑前使用
- 文件钻取：
pnpm search:file <path> <startLine> <endLine>
仅在以下情况使用原生ripgrep：
- 高级PCRE2正则模式（正向/反向预查）
- 不支持的自定义文件类型过滤
- 与其他CLI工具集成的流水线操作
<instructions>
<execution_process>
This skill provides access to ripgrep (rg) via the
npm package, which automatically downloads the correct binary for your platform (Windows, Linux, macOS). Enhanced file type support for modern JavaScript/TypeScript projects.
Binary Source:
npm package (cross-platform, auto-installed)
- Automatically handles Windows, Linux, macOS binaries
- No manual binary management required
Optional Config:
(if present, automatically used)
本技能通过
npm包提供ripgrep（rg）访问，该包会自动为你的平台（Windows、Linux、macOS）下载正确的二进制文件。增强了对现代JavaScript/TypeScript项目的文件类型支持。
- 自动处理Windows、Linux、macOS二进制文件
- 无需手动管理二进制文件
Why Use This Over Built-in Grep Tool?
为何选择本工具而非内置Grep？
| Feature | Ripgrep Skill | Built-in Grep Tool |
|---|
| ES Module Support | ✅ .mjs, .cjs, .mts, .cts | ❌ Limited |
| Performance | ✅ 10-100x faster | ⚠️ Slower on large repos |
| Gitignore Respect | ✅ Automatic | ⚠️ Manual filtering needed |
| Binary File Detection | ✅ Automatic | ❌ None |
| PCRE2 Advanced Regexes | ✅ With flag | ❌ Limited |
| Custom Config | ✅ .ripgreprc support | ❌ None |
| 特性 | Ripgrep 技能 | 内置Grep工具 |
|---|
| ES模块支持 | ✅ .mjs, .cjs, .mts, .cts | ❌ 支持有限 |
| 性能 | ✅ 快10-100倍 | ⚠️ 大型仓库中速度较慢 |
| Gitignore支持 | ✅ 自动识别 | ⚠️ 需要手动过滤 |
| 二进制文件检测 | ✅ 自动识别 | ❌ 无 |
| PCRE2高级正则 | ✅ 带-P标志支持 | ❌ 支持有限 |
| 自定义配置 | ✅ 支持.ripgreprc | ❌ 无 |
Quick Start Commands
快速开始命令
Search for pattern in all files
在所有文件中搜索模式
node .claude/skills/ripgrep/scripts/search.mjs "pattern"
node .claude/skills/ripgrep/scripts/search.mjs "pattern"
Search specific file types
搜索特定文件类型
node .claude/skills/ripgrep/scripts/search.mjs "pattern" -tjs
node .claude/skills/ripgrep/scripts/search.mjs "pattern" -tts
node .claude/skills/ripgrep/scripts/search.mjs "pattern" -tjs
node .claude/skills/ripgrep/scripts/search.mjs "pattern" -tts
Case-insensitive search
不区分大小写搜索
node .claude/skills/ripgrep/scripts/search.mjs "pattern" -i
node .claude/skills/ripgrep/scripts/search.mjs "pattern" -i
Search with context lines
显示匹配上下文行
node .claude/skills/ripgrep/scripts/search.mjs "pattern" -C 3
node .claude/skills/ripgrep/scripts/search.mjs "pattern" -C 3
Quick Search Presets
快速搜索预设
Search JavaScript files (includes .mjs, .cjs)
搜索JavaScript文件（包含.mjs, .cjs）
node .claude/skills/ripgrep/scripts/quick-search.mjs js "pattern"
node .claude/skills/ripgrep/scripts/quick-search.mjs js "pattern"
Search TypeScript files (includes .mts, .cts)
搜索TypeScript文件（包含.mts, .cts）
node .claude/skills/ripgrep/scripts/quick-search.mjs ts "pattern"
node .claude/skills/ripgrep/scripts/quick-search.mjs ts "pattern"
Search all .mjs files specifically
仅搜索所有.mjs文件
node .claude/skills/ripgrep/scripts/quick-search.mjs mjs "pattern"
node .claude/skills/ripgrep/scripts/quick-search.mjs mjs "pattern"
Search .claude directory for hooks
在.claude目录中搜索钩子
node .claude/skills/ripgrep/scripts/quick-search.mjs hooks "pattern"
node .claude/skills/ripgrep/scripts/quick-search.mjs hooks "pattern"
Search .claude directory for skills
在.claude目录中搜索技能
node .claude/skills/ripgrep/scripts/quick-search.mjs skills "pattern"
node .claude/skills/ripgrep/scripts/quick-search.mjs skills "pattern"
Search .claude directory for tools
在.claude目录中搜索工具
node .claude/skills/ripgrep/scripts/quick-search.mjs tools "pattern"
node .claude/skills/ripgrep/scripts/quick-search.mjs tools "pattern"
Search .claude directory for agents
在.claude目录中搜索Agent
node .claude/skills/ripgrep/scripts/quick-search.mjs agents "pattern"
node .claude/skills/ripgrep/scripts/quick-search.mjs agents "pattern"
Search all files (no filter)
搜索所有文件（无过滤）
node .claude/skills/ripgrep/scripts/quick-search.mjs all "pattern"
node .claude/skills/ripgrep/scripts/quick-search.mjs all "pattern"
JavaScript files (includes .js, .mjs, .cjs)
JavaScript文件（包含.js, .mjs, .cjs）
TypeScript files (includes .ts, .mts, .cts)
TypeScript文件（包含.ts, .mts, .cts）
Config files (.yaml, .yml, .toml, .ini)
配置文件（.yaml, .yml, .toml, .ini）
Markdown files (includes .md, .mdc)
Markdown文件（包含.md, .mdc）
Word boundary search
单词边界搜索
Smart case (case-insensitive unless uppercase present)
智能大小写（存在大写字母时区分大小写，否则不区分）
rg "pattern" -S # Already default in .ripgreprc
rg "pattern" -S # 已在.ripgreprc中设置为默认
rg "pattern.*\n.*another" -U
rg "pattern.*
.*another" -U
PCRE2 lookahead/lookbehind
PCRE2正向/反向预查
rg -P "foo(?=bar)" # Positive lookahead
rg -P "foo(?!bar)" # Negative lookahead
rg -P "(?<=foo)bar" # Positive lookbehind
rg -P "(?<!foo)bar" # Negative lookbehind
rg -P "foo(?=bar)" # 正向预查
rg -P "foo(?!bar)" # 负向预查
rg -P "(?<=foo)bar" # 正向后查
rg -P "(?<!foo)bar" # 负向后查
rg "pattern" -g "!node_modules/"
rg "pattern" -g "!.git/"
rg "pattern" -g "!node_modules/"
rg "pattern" -g "!.git/"
Include only specific directories
仅包含特定目录
rg "pattern" -g ".claude/**"
rg "pattern" -g ".claude/**"
Exclude specific file types
排除特定文件类型
rg "pattern" -Tjs # Exclude JavaScript
rg "pattern" -Tjs # 排除JavaScript文件
Search hidden files
搜索隐藏文件
Search binary files
搜索二进制文件
Show 3 lines before and after match
显示匹配前后3行
Show 2 lines before
显示匹配前2行
Show 2 lines after
显示匹配后2行
Show only filenames with matches
仅显示包含匹配的文件名
Show count of matches per file
显示每个文件的匹配次数
Show line numbers (default in .ripgreprc)
显示行号（.ripgreprc中已设为默认）
PCRE2 Advanced Patterns
PCRE2高级模式
Enable PCRE2 mode with
for advanced features:
Lookahead and Lookbehind
预查与后查
Find "error" only when followed by "critical"
仅查找后面跟有"critical"的"error"
rg -P "error(?=.*critical)"
rg -P "error(?=.*critical)"
Find "test" not followed by ".skip"
查找后面不跟有".skip"的"test"
Find words starting with capital after "Dr. "
查找"Dr. "后面的大写开头单词
rg -P "(?<=Dr. )[A-Z]\w+"
rg -P "(?<=Dr\. )[A-Z]\w+"
Find function calls not preceded by "await "
查找前面没有"await "的函数调用
rg -P "(?<!await )\b\w+("
rg -P "(?<!await )\b\w+\("
Find repeated words
查找重复单词
Find matching HTML tags
查找匹配的HTML标签
Match IPv4 or IPv6
匹配IPv4或IPv6
rg -P "(\d{1,3}.){3}\d{1,3}|([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}"
rg -P "(\d{1,3}\.){3}\d{1,3}|([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}"
Integration with Other Tools
与其他工具集成
With fzf (Interactive Search)
与fzf集成（交互式搜索）
Search and interactively select file
搜索并交互式选择文件
Search pattern and open in editor
搜索模式并在编辑器中打开
rg "pattern" -l | fzf | xargs code
rg "pattern" -l | fzf | xargs code
Set ripgrep as grep program in .vimrc
在.vimrc中设置ripgrep为grep程序
set grepprg=rg\ --vimgrep\ --smart-case\ --follow
set grepprg=rg\ --vimgrep\ --smart-case\ --follow
Pipeline with Other Commands
与其他命令流水线集成
Search and count unique matches
搜索并统计唯一匹配项
rg "pattern" -o | sort | uniq -c
rg "pattern" -o | sort | uniq -c
Search and replace preview
搜索并替换预览
rg "old" -l | xargs sed -i 's/old/new/g'
rg "old" -l | xargs sed -i 's/old/new/g'
Performance Optimization
性能优化
Tips for Large Codebases
大型代码库技巧
- Use file type filters: is faster than searching all files
- Exclude large directories:
- Use literal strings when possible: (disables regex)
- Enable parallel search: Ripgrep uses all cores by default
- Use .gitignore: Ripgrep respects .gitignore automatically
- 使用文件类型过滤器：比搜索所有文件更快
- 排除大型目录：
- 尽可能使用字面量字符串：（禁用正则）
- 启用并行搜索：Ripgrep默认使用所有核心
- 使用.gitignore：Ripgrep会自动遵循.gitignore规则
Ripgrep is typically:
- 10-100x faster than grep
- 5-10x faster than ag (The Silver Searcher)
- 3-5x faster than git grep
Ripgrep通常：
- 比grep快10-100倍
- 比ag（The Silver Searcher）快5-10倍
- 比git grep快3-5倍
Custom Configuration
自定义配置
The optional
file at
(if present) contains:
Extended file types
扩展文件类型
--type-add=js:.mjs
--type-add=js:.cjs
--type-add=ts:.mts
--type-add=ts:.cts
--type-add=md:.mdc
--type-add=config:.yaml
--type-add=config:.yml
--type-add=config:.toml
--type-add=config:*.ini
--type-add=js:.mjs
--type-add=js:.cjs
--type-add=ts:.mts
--type-add=ts:.cts
--type-add=md:.mdc
--type-add=config:.yaml
--type-add=config:.yml
--type-add=config:.toml
--type-add=config:*.ini
--smart-case
--follow
--line-number
--smart-case
--follow
--line-number
Framework-Specific Patterns
框架特定模式
Searching .claude Directory
搜索.claude目录
rg "PreToolUse|PostToolUse" .claude/hooks/
rg "PreToolUse\|PostToolUse" .claude/hooks/
rg "^# " .claude/skills/ -tmd
rg "^# " .claude/skills/ -tmd
Find agent definitions
查找Agent定义
rg "^name:" .claude/agents/ -tmd
rg "^name:" .claude/agents/ -tmd
Find workflow steps
查找工作流步骤
rg "^### Step" .claude/workflows/ -tmd
rg "^### Step" .claude/workflows/ -tmd
Common Agent Studio Searches
Agent Studio常用搜索
Find all TaskUpdate calls
查找所有TaskUpdate调用
rg "TaskUpdate(" -tjs -tts
rg "TaskUpdate\(" -tjs -tts
Find all skill invocations
查找所有技能调用
Find all memory protocol sections
查找所有内存协议章节
rg "## Memory Protocol" -tmd
rg "## Memory Protocol" -tmd
Find all BLOCKING enforcement comments
查找所有BLOCKING强制注释
rg "BLOCKING|CRITICAL" -C 2
</execution_process>
<best_practices>
1. **Use file type filters** (`-tjs`, `-tts`) for faster searches
2. **Respect .gitignore** patterns (automatic by default)
3. **Use smart-case** for case-insensitive search (default in config)
4. **Enable PCRE2** (`-P`) only when advanced features needed
5. **Exclude large directories** with `-g "!node_modules/**"`
6. **Use literal search** (`-F`) when pattern has no regex
7. **Binary automatically managed** via `@vscode/ripgrep` npm package
8. **Use quick-search presets** for common .claude directory searches
</best_practices>
</instructions>
<examples>
<usage_example>
**Search for all TaskUpdate calls in the project:**
```bash
node .claude/skills/ripgrep/scripts/search.mjs "TaskUpdate" -tjs -tts
Find all security-related hooks:
bash
node .claude/skills/ripgrep/scripts/quick-search.mjs hooks "security|SECURITY" -i
Search for function definitions with PCRE2:
bash
node .claude/skills/ripgrep/scripts/search.mjs -P "^function\s+\w+\(" -tjs
</usage_example>
</examples>
rg "BLOCKING|CRITICAL" -C 2
</execution_process>
<best_practices>
1. **使用文件类型过滤器**（`-tjs`, `-tts`）以加快搜索速度
2. **遵循.gitignore**规则（默认自动生效）
3. **使用智能大小写**进行不区分大小写搜索（配置中已设为默认）
4. **仅在需要高级特性时启用PCRE2**（`-P`）
5. **用`-g "!node_modules/**"`排除大型目录**
6. **当模式无正则时使用字面量搜索**（`-F`）
7. **二进制文件由`@vscode/ripgrep` npm包自动管理**
8. **对于.claude目录的常见搜索，使用快速搜索预设**
</best_practices>
</instructions>
<examples>
<usage_example>
**搜索项目中所有TaskUpdate调用：**
```bash
node .claude/skills/ripgrep/scripts/search.mjs "TaskUpdate" -tjs -tts
查找所有安全相关钩子：
bash
node .claude/skills/ripgrep/scripts/quick-search.mjs hooks "security|SECURITY" -i
使用PCRE2搜索函数定义：
bash
node .claude/skills/ripgrep/scripts/search.mjs -P "^function\\s+\\w+\\(" -tjs
</usage_example>
</examples>
The search scripts use
npm package which automatically:
- Detects your platform (Windows, Linux, macOS)
- Downloads the correct binary during
- Handles all architecture variants (x64, ARM64, etc.)
No manual binary management required - the npm package handles everything automatically.
- 检测你的平台（Windows、Linux、macOS）
- 在时下载正确的二进制文件
- 处理所有架构变体（x64、ARM64等）
无需手动管理二进制文件 - npm包会自动处理所有事宜。
- - Built-in Claude Code grep (simpler, less features)
- - File pattern matching
- - 内置Claude Code grep（更简单，功能更少）
- - 文件模式匹配
Memory Protocol (MANDATORY)
内存协议（强制要求）
Before starting:
Read
.claude/context/memory/learnings.md
After completing:
- New pattern ->
.claude/context/memory/learnings.md
- Issue found ->
.claude/context/memory/issues.md
- Decision made ->
.claude/context/memory/decisions.md
ASSUME INTERRUPTION: If it's not in memory, it didn't happen.
开始前：
阅读
.claude/context/memory/learnings.md
完成后：
- 新模式 ->
.claude/context/memory/learnings.md
- 发现问题 ->
.claude/context/memory/issues.md
- 做出决策 ->
.claude/context/memory/decisions.md
假设会被中断：如果未记录到内存中，就视为未发生。
",