English | 中文

@zhourenke/dsh-tool-everything

模型可调用的 Everything 搜索工具 — everything_search — 基于 es.exe（Everything 命令行客户端），在 Windows 上实现极速文件搜索。

利用 voidtools 的 Everything 搜索引擎，在 NTFS 卷上实现近乎即时的文件搜索，支持完整的 Everything 搜索语法。

前置条件

• Windows（NTFS 卷）
• Everything by voidtools（免费，已安装并运行）
• es.exe — Everything 自带的命令行客户端，也可单独下载。必须能在 PATH 中找到。

验证安装：

es -h

应显示 ES 帮助信息。

安装

本插件是一个 DSH 配置文件包（profile bundle）。安装方式有两种：

方式一：从 GitHub 安装（推荐）

dsh plugin --profile web add "github:zhourenke/dsh-tool-everything"

该命令会从 GitHub 获取插件，安装到配置文件的 node_modules 中，并自动在 dsh.profile.bundles 中添加对应条目（DSH 的 reconcilePlugins 机制会检测到该包包含 dsh.bundle.patch，自动将其加入 bundle 列表）。然后重启 DSH 即可。

卸载：

dsh plugin --profile web remove @zhourenke/dsh-tool-everything

同样会自动从 dsh.profile.bundles 中移除。

此方式要求 dsh 版本支持 GitHub 包安装。如果遇到问题，请使用方式二。

方式二：手动放置

将插件文件夹直接放置到 DSH 配置文件的 node_modules 中，并手动注册。

找到你的 DSH 配置文件

# 列出所有可用的配置文件
Get-ChildItem "$env:USERPROFILE\.dsh\profiles" -Name

常见的配置文件：web、tui、headless。配置文件目录为 $env:USERPROFILE\.dsh\profiles\<名称>\。

第 1 步 — 把插件文件夹复制进配置文件

# 若作用域目录不存在则创建
$target = "$env:USERPROFILE\.dsh\profiles\<名称>\node_modules\@zhourenke"
New-Item -ItemType Directory -Force $target

# 复制整个插件文件夹（package.json、cordis.patch.yml、lib/ 等）
Copy-Item -Recurse C:\path\to\dsh-tool-everything "$target\"

复制后的目录必须包含 package.json（含 dsh.bundle.patch）、cordis.patch.yml 和 lib/。

第 2 步 — 注册 bundle

编辑 $env:USERPROFILE\.dsh\profiles\<名称>\package.json：

  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
+       "@zhourenke/dsh-tool-everything"
      ]
    }
  }

无需在 dependencies 中添加任何条目——DSH 启动时只按包名从配置文件的 node_modules 物理解析 bundle。

第 3 步 — 重启 DSH

下次启动 DSH 时插件会被加载。

验证安装

重启 DSH 后，让模型列出可用工具，或直接让它搜索一个已知文件。

使用方法

安装后，模型可以调用 everything_search 并传入任何 Everything 搜索查询：

示例

查询	说明
*.pdf	所有 PDF 文件
report* 2024	文件名以 "report" 开头且包含 "2024" 的文件
size:>1gb	大于 1GB 的文件
dm:2024-01-01..2024-12-31	2024 年内修改过的文件
ext:txt content:hello	包含 "hello" 的文本文件
C:\Projects\* ext:ts	C:\Projects 下的 TypeScript 文件
*.jpg dc:2024-06-01	2024 年 6 月 1 日创建的 JPEG 图片
!hidden	排除隐藏文件

参数

参数	类型	必填	默认值	说明
query	string	✅	—	Everything 搜索查询。支持通配符（*、?）、content:、size:、dm:、dc:、da:、ext:、path:、布尔运算符（|、!、<...>）及 Everything 搜索语法。
max_results	number	❌	50	最大返回结果数（1–100000）。需要穷举搜索时用 100000；一般建议用更窄的查询以保证速度。
path	string	❌	—	限制搜索目录。含空格的路径可用（C:\Program Files\MacType）。通过 Everything 的 path: 函数实现，而非 es 的 -path 参数。使用 content: 时必须提供此参数——无路径的 content 搜索会被拒绝，以防 Everything 引擎卡死。
regex	boolean	❌	false	启用正则搜索模式（-r）。注意：Everything 正则引擎不支持 (...) 分组——请用顶层交替，如 .*\.pdf$|.*\.txt$。
match_case	boolean	❌	false	区分大小写匹配（-i）。默认不区分。
match_whole_word	boolean	❌	false	仅匹配完整单词（-w）。
match_path	boolean	❌	false	匹配完整路径（-p）。
file_only	boolean	❌	false	仅搜索文件，排除文件夹（/a-d）。
folder_only	boolean	❌	false	仅搜索文件夹，排除文件（/ad）。
sort_by	string	❌	—	排序字段：name、path、size、extension、date-created、date-modified、date-accessed。
sort_desc	boolean	❌	false	设置 sort_by 后降序排序。
attributes	string	❌	—	属性过滤器，DIR 风格。字母含义：R 只读、H 隐藏、S 系统、D 目录、A 归档、V 设备、N 普通、T 临时、L 重解析点、C 压缩、O 离线、I 未索引内容、E 加密。前缀 - 表示排除："R-H" = 只读且非隐藏。组合："RHS" = 只读、隐藏且系统。
include_size	boolean	❌	false	显示文件大小。
include_date_modified	boolean	❌	false	显示最后修改日期（dm）。
include_date_created	boolean	❌	false	显示创建日期（dc）。
include_date_accessed	boolean	❌	false	显示最后访问日期（da）。
include_path	boolean	❌	false	显示完整路径和文件名（es -full-path-and-name）。
include_extension	boolean	❌	false	显示文件扩展名。
include_attributes	boolean	❌	false	显示文件属性，DIR 风格字母（A、HS、HSD 等）。

配置

键	默认值	说明
timeoutMs	1200000	工具调用的超时时间（毫秒）。
graceMs	3000	超时后的进程终止宽限期（毫秒）。
stderrMaxBytes	65536	错误输出诊断截取上限（字节）。
rawOutputMaxBytes	20000000	标准输出解析上限（字节）。

工作原理

1. 模型调用 everything_search，传入查询和可选参数。
2. 插件通过 DSH 子进程接口执行 cmd /c chcp 65001>nul & es -json ...。
3. es.exe 查询 Everything 服务（已索引所有 NTFS 卷），返回 JSON 格式结果。
4. 插件解析 JSON，转换 FILETIME 日期和属性位掩码，格式化结果并返回给模型。

为什么用 cmd /c chcp 65001？

在中文 Windows（及其他 CJK 区域）上，es.exe 按系统 ANSI 代码页（GB2312/CP936）输出文件名，而 DSH 子进程接口按 UTF-8 解码子进程 stdout——所有非 ASCII 路径都会乱码。chcp 65001 在 es 运行前把控制台代码页切到 UTF-8，es 输出 UTF-8 字节即可正确解码。已端到端验证：不加它时，D:\驱动镜像 会变成 D:\。

转义策略

查询被嵌入到一条 cmd /c 命令字符串中，所有 shell 特殊字符（包括空格）都用 caret（^，cmd 的转义符）转义：

• size:>1gb → size:^>1gb（不会被当作重定向）
• *.pdf | *.txt → *.pdf^ ^|^ *.txt（保持一次 OR 搜索，不是管道）
• Windows11 25H2.iso → Windows11^ 25H2.iso（保持多词查询）

查询绝不用引号：es 会把引号原样传给 Everything，其中 "..." 表示精确短语搜索，会静默返回 0 结果。

path 参数被折叠进查询作为 Everything 的 path: 函数前缀（path:C:\Program^ Files\MacType *.ini）。这刻意避开了 es 的 -path 参数：含空格的 -path 值需要引号，而 Node.js 在 Windows 上的命令行引号处理会破坏拼接在 cmd /c 字符串内的引号（\"），导致 cmd 解析失败。path: 函数在 caret 转义后能正确处理含空格的路径。

es 参数顺序很关键

es 从左到右严格解析选项，且对其搜索模式开关是贪婪的：-r（正则）和 -i/-w/-p（大小写/全词/匹配路径）必须是最后一个选项，紧跟查询之前。任何出现在它们之后的选项（-size、-n、-sort）都会被当作搜索文本的一部分，静默返回 0 结果。因此插件按 显示列 → -n → 过滤 → 排序 → -i -w -p → -r → 查询 的顺序构造命令。

已处理的输出怪癖

• -size 与 -r 组合时，es 会把 JSON 多包一层数组（[[{...}]]）；解析器会解开一层。
• -attribs 输出数字位掩码（32 = 归档）；插件会转换为 DIR 风格字母（A、HS、HSD 等）。
• FILETIME 日期（自 1601 年起 100 纳秒间隔）会转换为 ISO-8601 格式。

由于 Everything 维护实时索引，即使跨数百万个文件，搜索也近乎即时——对于大范围搜索，比文件系统的 glob 或 grep 快得多。

Content 搜索安全保护

content: 通过系统 iFilter 读取文件内容，在扫描数百万文件时会卡死 Everything。插件提供两层保护：

• 无路径 → 拒绝：content: 未附带 path 参数（或 query 中未包含 path:）时，插件拒绝搜索并返回 ES_FAILED，提示模型缩小范围。
• 广域路径 → 自动限制：content: 针对驱动器根目录（如 C:\）、Users 树（C:\Users、C:\Users\任意用户名）、当前用户主目录，或这些路径的通配符变体（如 C:\*）时，自动通过 Everything 的 parent: 函数限制为仅搜索直接子级（一层深度，不递归子目录），并在结果中附加警告。

使用 content: 时请务必指定具体路径，如 path:C:\Specific\Folder。通配符模式 C:\* 也会被识别为广域路径并受到限制。

错误码

错误码	说明
ES_NOT_FOUND	cmd 或 es 命令未安装或不在 PATH 中。
ES_FAILED	命令执行失败（非零退出码、启动失败、输出格式错误）。未提供 path 参数的 content 搜索也会被拒绝，返回此错误码。
ES_RAW_OUTPUT_OVERFLOW	输出超出捕获上限；请缩小查询范围。
ES_ABORTED	工具调用被中止（超时或取消）。

已知限制

• Everything 正则引擎不支持 (...) 分组——.*\.(pdf|txt)$ 返回空；请用 .*\.pdf$|.*\.txt$。
• es 必须在 PATH 中；插件不探测固定安装路径。
• path 值同时包含空格和 &|<>^() 等 shell 字符时可能无法精确传递；此类目录名在 Windows 上极为罕见。
• content: 必须搭配 path 参数使用——无路径的 content 搜索（或在驱动器根目录、Users 树、用户主目录等广域路径上搜索）会让 Everything 通过系统 iFilter 读取每个文件，导致程序卡死。插件会拒绝裸 content: 搜索（返回 ES_FAILED），并自动将广域路径限制为仅搜索直接子级。

许可证

MIT