English | 中文
@zhourenke/dsh-tool-everything
为 DSH 模型提供 everything_search 工具：基于 Everything 的全盘极速文件搜索。
在 Windows 上调用 voidtools Everything 的索引，毫秒级搜遍整个磁盘（不局限于工作区），支持完整的 Everything 搜索语法（通配符、布尔、size:、content: 全文等）。
它擅长什么
- 全盘搜索：给个名字片段、类型、大小、日期就能定位文件
- 全文检索：
content: 按文件内容找文件（需限定目录，见下文）
- 元数据：可一并返回大小、创建/修改/访问时间、扩展名、属性
- 快：Everything 常驻后台维护 NTFS 索引，查询是索引查找，不是目录扫描
前置条件
| 需要 | 说明 |
|---|
| Windows | NTFS 卷（Everything 的索引基于 NTFS） |
| Everything | voidtools 官方免费软件，需安装并运行 |
| es.exe | Everything 的命令行客户端，需在 PATH 中 |
验证：
es -h
能看到 ES 帮助信息即就绪。
安装
dsh plugin --profile web add "github:zhourenke/dsh-tool-everything"
重启 DSH 后生效，模型即可调用 everything_search。
卸载：
dsh plugin --profile web remove @zhourenke/dsh-tool-everything
快速上手
在模型会话里直接说人话即可，例如：
- 「找 D 盘下 1GB 以上的文件」→
query: size:>1gb，path: D:\
- 「找 Projects 里包含 TODO 的文本文件」→
query: content:TODO，path: C:\Projects
- 「找 2024 年 7 月改过的所有 PDF」→
query: *.pdf dm:2024-07-01..2024-07-31
搜索语法速查
everything_search 直接接受 Everything 搜索语法。常用写法：
| 想找 | 查询 |
|---|
| 某类文件 | *.pdf |
| 名称含关键词 | report* 2024（多个词 = 都要满足） |
| 任一类（OR） | *.pdf | *.txt |
| 排除 | !*.tmp |
| 分组 | <*.mp3 | *.flac> |
| 按大小 | size:>1gb、size:500mb..2gb |
| 按时间 | dm:2024-01-01..2024-12-31、dm:today（dm: 修改 / dc: 创建 / da: 访问，写法相同） |
| 按路径 | path:C:\Projects ext:ts（路径含空格请用 path 参数） |
| 按属性 | attributes:H 隐藏文件、attributes:D 文件夹 |
| 精确短语 | "quarterly report" |
| 全文内容 | content:TODO（必须配合范围，见下） |
注意：Everything 的正则模式不支持 (...) 分组，请用顶层或运算，如 .*\.pdf$|.*\.txt$。
参数
| 参数 | 类型 | 默认 | 说明 |
|---|
query | string | — | 必填。Everything 搜索查询。 |
path | string | — | 只在这个目录（含子目录）里搜；含空格的路径用它最可靠；content: 搜索建议必填。 |
max_results | number | 50 | 最多返回多少条（1–100000）。要全量用 100000；一般查询用默认即可。 |
sort_by | string | 相关度/名称 | name、path、size、extension、date-created、date-modified、date-accessed。 |
sort_desc | boolean | false | 配合 sort_by 降序。 |
regex | boolean | false | 正则模式；不支持 (...) 分组。 |
match_case | boolean | false | 区分大小写。 |
match_whole_word | boolean | false | 整词匹配。 |
match_path | boolean | false | 在完整路径上匹配，而不只是文件名。 |
file_only | boolean | false | 只要文件（排除文件夹）。 |
folder_only | boolean | false | 只要文件夹（排除文件）。 |
attributes | string | — | 属性过滤，DIR 风格，只接受这些字母：R H S D A V N T L C O I E（常用：R 只读、H 隐藏、S 系统、D 目录、A 归档）；- 前缀表示排除（"R-H" = 只读且非隐藏）；可组合（"RHS" = 只读+隐藏+系统）。其它字母会被拒绝——es 对未知字母静默忽略，会返回未过滤的结果。 |
include_size | boolean | false | 返回大小（字节）。 |
结果长什么样
返回 total（匹配总数）、truncated（是否可能还有更多）、results[]。每条结果：
path：完整路径（日期、属性等已格式化为可读形式）；文件夹以 \ 结尾- 请求的元数据：
size（字节整数）、date_modified / date_created / date_accessed（2026-01-02 03:04:05 式）、extension（有扩展名返回如 js；无扩展名文件返回 ""；文件夹不输出该字段）、attributes（字母串）
warning：内容搜索范围被自动收窄时出现——读到它就说明结果不完整，应改用更具体的目录
默认同时匹配文件与文件夹；结果数顶到 max_results 时，插件会自动补一次计数查询把 total 取准。
内容搜索（content:）的规则
content: 全文搜索会遍历文件内容，范围过大可能卡死 Everything，因此有硬性护栏：
- 必须限定范围：通过
path 参数，或查询内联 path:...，二选一。完全没有范围会被直接拒绝。
- 广域范围会被收窄：对驱动器根目录（
C:\）、C:\Users（及其下一层）、C:\Documents and Settings（同理）、当前用户主目录搜索时，自动降级为只搜直接子级（一层，不递归），并在 warning 中说明。
- 推荐：搜内容时给具体目录，例如
content:secret_key + path: C:\Projects\MyApp。
- 范围要按文件数估，不能按路径形态估——守卫放行不等于便宜：上面那条判定只看路径的形状。像
~\.dsh 这种通过了守卫的目录，里面仍有整个 profile 的 node_modules 和 Chromium 的 CDP profile；实测这样一次 content: 查询一直跑到该次调用的超时上限（默认 20 分钟）才被宿主终止，之后 Everything 还持续占满一个核一段时间才安静下来。
给 Agent 的调用要点
- 工具名
everything_search；全盘搜索，不受工作区限制
- 默认最多 50 条、默认包含文件夹；要全量用
max_results: 100000，只要文件用 file_only: true
- 目录以
\ 结尾且没有 extension，凭这两点区分文件与文件夹
- 读到
warning 就调整：内容搜索范围被收窄了
- 搜内容必须先给一个具体目录
错误码
| 错误码 | 含义 |
|---|
ES_NOT_FOUND | es 或 cmd 不可用（Everything 未安装 / es.exe 不在 PATH） |
ES_FAILED | 执行失败（例如无范围的 content: 被拒绝） |
ES_RAW_OUTPUT_OVERFLOW | 输出过大；请缩小查询范围 |
ES_ABORTED | 调用被中止（超时或取消） |
已知限制（实测确认）
- Everything 未运行时搜索失败——先启动 Everything。
- 硬链接文件可能搜不到：Everything 的实时索引不收录新建的硬链接（pnpm 等包管理器装进
node_modules 的文件会这样），在 Everything 中执行 Force Rebuild 后出现。属 Everything 自身行为，非插件缺陷。
- 正则不支持分组；内联
path: 不支持含空格的路径（含空格一律用 path 参数）。
配置
| 键 | 默认 | 说明 |
|---|
timeoutMs | 1200000 | 单次搜索超时（毫秒） |
countTimeoutMs | 5000 | 附加计数查询的独立预算（毫秒）；超时就放弃精确总数，改报"可能还有更多"，已取到的列表不受影响 |
graceMs | 3000 | 超时后终止进程的宽限（毫秒） |
stderrMaxBytes | 65536 | 报错时截取的 stderr 上限（字节） |
rawOutputMaxBytes | 20000000 | 输出解析上限（字节） |
兼容性
在 v0.2.0-rc.2（2026-09）下测试通过。
在 v0.2.1-rc.2（2026-10）下测试通过。
插件列表里的名称、说明与图标来自包内的 locale/{en,zh}.json 与 icon.svg（DSH 0.1.7 起的显示元数据），因此不用激活插件就能看出它是做什么的。
许可证
MIT
