file-search

文件搜索技能

为 AI Agent 提供高效的命令行搜索工具。

工具选择指南

任务	使用	替代方案
在代码文件中搜索文本	rg (ripgrep)	grep、grep -r
按名称/路径查找文件	fd	find、ls -R
结构化/语法感知的代码搜索	sg (ast-grep)	正则表达式技巧
应用规则包（安全/代码检查、污点分析）	semgrep	基于正则表达式的 CI 检查
搜索 PDF、Office 文档和存档文件	rga (ripgrep-all)	手动提取
按语言统计代码行数	tokei	cloc、wc -l
统计带有复杂度指标的代码	scc	cloc、tokei

决策流程： 文本 → rg | 结构化 → sg | 规则包 → semgrep | 文件名 → fd | PDF/存档文件 → rga | 代码行数 → tokei/scc

快速示例

rg 'def \w+\(' -t py src/          # rg: text search in Python files
rg -c 'TODO' -t js | wc -l         # rg: count first, then drill down
sg --pattern 'console.log($$$)' --rewrite 'logger.info($$$)' --lang js  # sg: structural replace
fd -g '*.test.ts' --changed-within 1d  # fd: -g for compound suffixes (NOT -e)
fd -g '*_test.go' -X rg 'func Test'   # fd+rg: find files, verify contents
rga 'quarterly revenue' docs/       # rga: search inside PDFs/archives
tokei --sort code                   # tokei: language stats
scc --wide                          # scc: complexity + COCOMO

最佳实践

1. 从小范围开始。 指定类型（-t、--lang、-e）、范围目录，并先统计数量（rg -c）。
2. 排除干扰项（-g '!vendor/'、fd -E node_modules）。
3. 批量执行相互独立的查询。 使用 rg -e P1 -e P2 -e P3 合并模式（只遍历一次），或在一条消息中并行发起不同的工具调用 — 切勿使用串行的 && 链。
4. 使用 --json 进行程序化处理。
5. rg 与 fd 的类型规则不同。 rg -t ts 会包含 .tsx；fd -e ts 则不会。rg 中没有 -t tsx。

参见 references/search-strategies.md。

本地文件之外

如果本地搜索没有结果，而相关上下文位于 issue/PR/外部文档中，请转交处理（gh、Jira、WebFetch）。注释中的 issue 键可作为提示。

参见 references/remote-handoff.md。

参考资料

主题	文件
rg 标志、模式和用法示例	references/ripgrep-patterns.md
按语言划分的 ast-grep 模式	references/ast-grep-patterns.md
semgrep 规则和污点模式	references/semgrep-patterns.md
fd 标志、用法及 fd+rg 组合	references/fd-guide.md
rga 格式、用法和缓存	references/rga-guide.md
tokei 和 scc 用法	references/code-metrics.md
PreToolUse 提示（随插件提供）	references/enforcement-hook.md
搜索目标定位策略	references/search-strategies.md
远程上下文转交指南	references/remote-handoff.md
现代命令行工具对比（旧版→现代版，涵盖所有领域）	cli-tools SKILL.md#preferred-modern-tools