dsh-file-search

DeepSeek Harness 文件检索插件：search_files 提供 grep 式内容检索（正则/字面量、大小写与扩展名过滤，自动跳过二进制与大文件），find_files 按文件名 glob/正则检索。只读、零运行时依赖。

• 源码：https://github.com/geeklei/dsh-plugins/tree/main/dsh-file-search
• npm：https://www.npmjs.com/package/dsh-file-search

安装

npm install dsh-file-search

使用说明

search_files —— 内容检索（grep 式）

在目录下按模式检索文件内容，返回文件名、行号与命中行。

用户：这个项目里哪里用到了 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 |

自动跳过：含 NUL 字节的二进制文件、超过 max_size 的文件、符号链接。

find_files —— 文件名检索

按文件名通配或正则查找文件。

用户：找一下所有测试文件

检索：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。

典型场景

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. 精确字面量检索（避免元字符干扰）

用户：搜 a.b( 这个字面量

search_files 传 literal=true，(、. 等不再被当作正则。

安全边界

• 只读：仅执行 readdir / readFile / stat / lstat，不写入、不修改、不删除；测试含"调用后文件数不变"的只读性断言。
• 二进制保护：读取内容前检测 NUL 字节，命中即按二进制跳过，避免把可执行文件、图片等当文本误报，也避免无效解码。
• 大小上限：单文件默认不超过 1 MB（可调，上限 20 MB），超限文件跳过并计数，防止大文件拖慢检索。
• 符号链接一律跳过：不跟随软链接/junction，避免环路与越界遍历。
• 多重上限：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 |

版本说明

• 0.1.0（2026-09-23）：初始版本。
  • search_files：正则/字面量内容检索 + 大小写/扩展名过滤 + 深度控制 + 忽略名单 + 二进制与大小上限跳过 + 多重结果上限
  • find_files：文件名 glob/正则检索 + 大小展示 + 结果上限
  • 符号链接跳过、无权限降级、只读保证

RoadMap

v0.2（计划）

• search_files 支持上下文行（before/after，grep -C）
• 支持 invert（反选：输出不含模式的行）
• 结果按文件聚合统计（每文件命中数排序）
• 新增 search_replace_preview：批量替换预览（只预览、不落盘）

v0.3（展望）

• 支持 .gitignore 自动推导忽略名单
• 大目录并发检索，缩短全量扫描耗时
• 命中高亮标记（可配置）

FAQ

Q：为什么搜不到某些文件的内容？ 常见原因：文件含 NUL 字节被判定为二进制而跳过；文件超过 max_size 上限；目录在 ignore 名单中；或深度超出 depth。摘要行会给出"跳过二进制/超限"的数量。

Q：pattern 默认是正则还是字面量？ 默认正则。若要检索含 (、.、[ 等元字符的字面文本，请传 literal=true。

Q：正则写错了会怎样？ 会返回明确的"正则表达式无效"错误提示，不会静默失败。可先用 dsh-regex-lab 验证。

Q：结果被截断（出现 ⚠）怎么办？ 说明命中数达到 max_results（或单文件 max_per_file）上限。可提高上限、收窄 include/depth，或缩小 path。

Q：能帮我批量替换文件内容吗？ 不能，本插件严格只读。批量修改可参考 dsh-diff-writer / dsh-file-manager-cli。

Q：find_files 的 * 会跨目录吗？ 不会。* 只匹配文件名内的任意字符，不跨越路径分隔符；目录层级由 depth 控制。

源码与发布地址

• 源码：https://github.com/geeklei/dsh-plugins/tree/main/dsh-file-search
• npm：https://www.npmjs.com/package/dsh-file-search

许可证

MIT