dsh-file-search
Advanced tools
File search plugin for DeepSeek Harness: grep-style content search (regex/literal, binary & size guards) and filename search (glob/regex). Read-only, zero runtime dependencies.
DeepSeek Harness 文件检索插件：search_files 提供 grep 式内容检索（正则/字面量、大小写与扩展名过滤、上下文行、反选，自动跳过二进制与大文件），find_files 按文件名 glob/正则检索，search_replace_preview 批量替换预览（只预览、不落盘）。只读、零运行时依赖。
npm install dsh-file-search
在目录下按模式检索文件内容，返回文件名、行号与命中行。
用户：这个项目里哪里用到了 TODO
检索：E:\projects\demo
模式：TODO
src/a.js
3: // TODO: 优化这里
18: const TODO_LIMIT = 10
docs/guide.md
7: 待办见 TODO 列表
匹配 2 个文件，共 3 处
已检索 12 个文件，跳过二进制 1 个
参数：
| 参数 | 说明 |
|---|---|
pattern | 检索模式，默认按正则；literal=true 时按字面量 |
path | 目录路径，默认当前目录 |
depth | 最大下钻层数，默认 5，上限 10 |
ignore | 忽略的目录名，逗号分隔，默认 node_modules,.git；空字符串表示不忽略 |
include | 仅检索这些扩展名，如 js,ts,md，默认全部 |
case_sensitive | 区分大小写，默认 false |
literal | 按字面量匹配（不解析正则元字符），默认 false |
max_size | 单文件大小上限（KB），默认 1024，上限 20480 |
max_results | 最多返回的匹配总数，默认 100，上限 1000 |
max_per_file | 单文件最多返回的匹配数，默认 50，上限 200 |
before | 上下文：命中行之前的行数（v0.2，默认 0，上限 10） |
after | 上下文：命中行之后的行数（v0.2，默认 0，上限 10） |
invert | 反选（v0.2）：输出不含模式的行（grep -v），默认 false |
自动跳过：含 NUL 字节的二进制文件、超过 max_size 的文件、符号链接。
上下文与聚合（v0.2）：传 before/after 后输出 grep 风格的上下文（命中行用 :、上下文行用 -，重叠区间自动合并）；结果末尾附「按文件命中数排序」的聚合统计。
用户：搜到 TODO 时把前后两行也带出来
search_files(path=".", pattern="TODO", before=2, after=2)
反选（v0.2）：invert=true 输出不含模式的行，适合找“哪行没跟规范”：
search_files(path="src", pattern="^import ", invert=true)
按文件名通配或正则查找文件。
用户：找一下所有测试文件
检索：E:\projects\demo
文件名模式：*.test.js（glob）
匹配 2 个文件：
src/a.test.js
src/util/b.test.js
参数：pattern（支持 *、?；regex=true 时按正则）、path、depth（默认 5）、ignore（默认 node_modules,.git）、regex、limit（默认 200）、show_size。
在目录下按正则或字面量查找并给出替换后的逐行对照（- 原行 / + 新行）。只预览、绝不落盘，实际替换请用编辑器或脚本执行。
用户：把全项目的 foo 批量换成 bar，先看看会改到什么
search_replace_preview(path=".", pattern="foo", replacement="bar", literal=true)
预览：E:\\projects\\demo
模式：foo → bar（字面量）
仅预览，未写入任何文件。
涉及 3 个文件、共 6 处：
文件：src/a.js（2 处）
第 1 行
- foo line
+ bar line
...
已检索 12 个文件，跳过二进制 1 个
参数：
| 参数 | 说明 |
|---|---|
pattern | 查找模式（必填，默认正则，literal=true 时按字面量） |
replacement | 替换串（必填，正则模式下支持 $1/$& 等引用）；空字符串表示删除匹配文本 |
path / depth / ignore / include | 同 search_files |
case_sensitive / literal | 同 search_files |
max_files | 最多预览的文件数，默认 20，上限 100 |
max_per_file | 单文件最多展示的替换行数，默认 10，上限 50 |
替换语义与 String.replace 一致；计数为匹配出现次数，展示行数受 max_per_file 限制（超出部分标注略）。
1. 定位关键字出现位置
用户：这个函数在哪些文件里被调用
search_files 传 pattern=函数名，一次列出文件与行号。
2. 只搜某一类文件
用户：只看 Markdown 里的链接
search_files 传 include=md，把检索范围收窄到文档。
3. 找 TODO / FIXME 等标记
用户：项目里还有哪些 TODO
search_files 传 pattern=TODO|FIXME（正则）一次扫全。
4. 按名字找文件
用户：找所有配置文件
find_files 传 pattern=*.config.js 或 *.json。
5. 搜代码时带出上下文
用户：这行报错是干什么的，把前后几行给我看看
search_files 传 before=3, after=3，一次拿到命中行及其上下文，不用再手动打开文件。
6. 找不合规的行（反选）
用户：哪些 import 没放在文件开头
search_files 传 pattern=^import + invert=true，列出不含该模式的行。
7. 批量改名/改文案前先预演
用户：把全项目的旧接口名换成新接口名，先看看影响面
search_replace_preview 给出逐行前后对照，确认无误后再用编辑器或脚本实际替换。
8. 精确字面量检索（避免元字符干扰）
用户：搜
a.b(这个字面量
search_files 传 literal=true，(、. 等不再被当作正则。
readdir / readFile / stat / lstat，不写入、不修改、不删除；search_replace_preview 顾名思义只输出前后对照预览，绝不写盘（测试含“预览后源文件未被修改”断言）。depth ≤ 10、max_results ≤ 1000、单文件匹配 ≤ 200、扫描条目 ≤ 20 万，超出即截断并标注 ⚠。path 目录内，不做目录外遍历。| 协作插件 | 集成方式 |
|---|---|
| dsh-regex-lab | 先在 regex-lab 用 test_regex 验证复杂正则，再用本插件批量检索 |
| dsh-folder-tree | 先用 render_tree 摸清结构，再用 search_files 精准检索目标目录 |
| dsh-line-ops | 检索命中后用 extract_lines 按行号抽取上下文 |
| dsh-todo-audit（二期 D13） | todo-audit 聚合 TODO/FIXME 统计，本插件负责自由模式检索 |
| dsh-fs-inspector | 检索前用 dir_size 掌握目录规模，判断是否需要收窄范围 |
| dsh-file-manager-cli | 本插件负责"找"（只读），实际改动交给 file-manager-cli |
search_files 新增 before/after 上下文行（grep -C 风格，重叠区间合并去重，命中 : / 上下文 -）search_files 新增 invert 反选（输出不含模式的行）search_replace_preview：批量替换预览（逐行 -/+ 对照、正则反向引用、只预览不落盘）search_files：正则/字面量内容检索 + 大小写/扩展名过滤 + 深度控制 + 忽略名单 + 二进制与大小上限跳过 + 多重结果上限find_files：文件名 glob/正则检索 + 大小展示 + 结果上限v0.2（已落地于 0.2.0）
search_files 支持上下文行（before/after，grep -C）invert（反选：输出不含模式的行）search_replace_preview：批量替换预览（只预览、不落盘）v0.3（展望）
.gitignore 自动推导忽略名单Q：为什么搜不到某些文件的内容？
常见原因：文件含 NUL 字节被判定为二进制而跳过；文件超过 max_size 上限；目录在 ignore 名单中；或深度超出 depth。摘要行会给出"跳过二进制/超限"的数量。
Q：pattern 默认是正则还是字面量？
默认正则。若要检索含 (、.、[ 等元字符的字面文本，请传 literal=true。
Q：正则写错了会怎样？ 会返回明确的"正则表达式无效"错误提示，不会静默失败。可先用 dsh-regex-lab 验证。
Q：结果被截断（出现 ⚠）怎么办？
说明命中数达到 max_results（或单文件 max_per_file）上限。可提高上限、收窄 include/depth，或缩小 path。
Q：能帮我批量替换文件内容吗？
本插件只提供 search_replace_preview 预览（绝不写盘），实际批量修改请用编辑器或脚本执行，或参考 dsh-diff-writer / dsh-file-manager-cli。
Q：invert 反选和普通检索有什么区别？
invert=true 输出的是不含模式的行（相当于 grep -v），适合找“漏掉规范”的行；命中数、上下文行、聚合统计的口径都按反选后的行计算。
Q：find_files 的 * 会跨目录吗？
不会。* 只匹配文件名内的任意字符，不跨越路径分隔符；目录层级由 depth 控制。
MIT
FAQs
File search plugin for DeepSeek Harness: grep-style content search (regex/literal, binary & size guards) and filename search (glob/regex). Read-only, zero runtime dependencies.
The npm package dsh-file-search receives a total of 172 weekly downloads. As such, dsh-file-search popularity was classified as not popular.
We found that dsh-file-search demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
The PHP Foundation says Chainguard broke a security embargo ahead of critical RCE patches, as leaks disrupted the coordinated release.
Security News
PHP releases emergency patches for two critical RCE vulnerabilities as agencies urge organizations to take unpatched sites offline.
Threat Research
/Security News
A supply chain attack compromised LiteLLM 1.107.0 on PyPI and Docker, spreading malware that steals cloud credentials, developer secrets, and AI provider keys.