全盘秒搜 keyblues/dsh-plugin-everything

dsh-plugin-everything

给 DeepSeek Harness 智能体加上「全盘秒级找文件」的能力：直接查询本机 voidtools Everything 的 NTFS 索引。

English: README.en.md

DSH 插件标识：本仓库是一个 DeepSeek Harness 插件（bundle），仓库 topic 为 dsh-plugin，package.json 中声明了 dsh.bundle.patch 与 dsh-plugin 关键词，并通过 engines.dsh 显式声明支持的 DSH 版本范围，可被 DSH 社区插件目录按 topic 检索收录。

它解决什么问题

Harness 里的 Agent 默认只能在工作区里逐个目录找文件，跨盘、找某个安装目录、找历史下载时很慢。本插件把 Everything 的索引能力暴露成模型工具：一次查询就能拿到全盘匹配的完整路径、大小和修改时间，查询耗时通常只有几毫秒。

前置条件

- Windows x64 上运行 DeepSeek Harness。
- 本机已安装 voidtools Everything 并保持运行（1.4 或更新；实测 1.4.1.1032）。索引保存在 Everything 进程内，插件通过 Everything SDK 的 IPC 读取结果，因此没有安装或没有运行 Everything 时无法工作。
- 不需要安装 Everything Service，也不需要开启 HTTP/ETP 服务器。
- Everything 未运行时，工具会返回明确提示；可在配置里打开 autoStart 让插件自动拉起它。

安装

最简：DSH 桌面端 → 插件 → 查看安装任务，在输入框里填 dsh-plugin-everything 即可。 安装器会从 npm registry 拉取最新版（当前 1.0.2），装完 everything_search / everything_status 立即出现，无需重启 Harness。

方式一：npm 包（推荐）

DSH 桌面端：插件 → 查看安装任务 → 输入 dsh-plugin-everything （指定版本写 dsh-plugin-everything@1.0.2）。

DSH 命令行（需先初始化 desktop profile，并在 Desktop 完全退出后执行）：

dsh plugin --profile desktop add dsh-plugin-everything

更新到最新版：重复执行一次上述 add。固定版本用 dsh-plugin-everything@<version>。

- npm 包页：<https://www.npmjs.com/package/dsh-plugin-everything>
- 查看最新版本：npm view dsh-plugin-everything version

方式二：GitHub Release / 本地 .tgz（离线、固定版本）

1. 从 Releases 下载 dsh-plugin-everything-1.0.2.tgz；
2. 在桌面端安装框直接填该文件的绝对路径（如 C:\Downloads\dsh-plugin-everything-1.0.2.tgz），或让 Agent 执行 plugin_manager install_bundle target=<tgz 路径>。
适合 npm 不可用、需要固定版本或离线安装的场景。

方式三：本地源码目录（开发 / 调试）

git clone https://github.com/keyblues/dsh-plugin-everything.git

在桌面端安装框填目录绝对路径，或让智能体执行 plugin_manager install_bundle target=<目录路径>。
修改代码后重新安装一次即可生效。

桌面端安装器支持的输入

| 输入 | 说明 |
| dsh-plugin-everything | npm 包名（推荐）：从 npm registry 安装最新版 |
| dsh-plugin-everything@1.0.2 | npm 包名 + 指定版本 |
| C:\Downloads\dsh-plugin-everything-1.0.2.tgz | 本地 Release 包 / .tgz 路径 |
| C:\path\to\everything-plugin | 本地目录（clone 的源码目录） |
| https://github.com/keyblues/dsh-plugin-everything | GitHub 仓库地址；安装时 pnpm 仍需直连 github.com，网络受限时会 ECONNRESET，可点界面上的「改用国内镜像」，或改用包名 / 本地路径 |

安装位置为 ~/.dsh/profiles/desktop，装完立即生效（工具直接出现，无需重启）。

卸载

让智能体执行 plugin_manager remove_bundle target=dsh-plugin-everything，或在 Settings → Plugins 中停用/移除。

提供的工具

| 工具 | 作用 |
| everything_search | 用 Everything 语法搜索全盘文件/文件夹，返回路径、大小、修改时间、命中总数 |
| everything_status | 检查 Everything 是否可达、客户端版本、索引条目数、SDK DLL 路径 |

everything_search 参数：

| 参数 | 类型 | 说明 |
| query | string（必填） | Everything 搜索表达式 |
| max | integer | 返回条数 1–500，默认取插件配置 maxResults（50） |
| sort | enum | name（默认）/ path / size / date-created / date-modified / recent |
| descending | boolean | 是否倒序，默认 false |

Everything 语法示例：

notepad.exe # 文件名包含 notepad.exe report 2024 ext:pdf # 2024 + PDF file:.md path:"C:\work" # 指定目录下的 markdown folder:node_modules # 文件夹名 C:\Windows\ notepad # 以反斜杠结尾 = 限定在此目录内 size:>10mb dm:today # 大于 10MB 且今天修改中文文件 # 中文/Unicode 文件名

完整语法见 Everything 搜索语法。

配置

安装后可在 profile 的 cordis.patch.yml（用户 patch 层）覆盖本插件行：

- id: everything
config:
maxResults: 50 # 默认返回条数（1-500） queryTimeoutMs: 10000 # 单次查询超时；超时会终止 SDK worker，下次查询自动重建 autoStart: false # Everything 未运行时是否自动启动 everythingPath: 'C:\Program Files\Everything\Everything.exe' sdkPath: '' # 留空使用插件自带的 native/Everything64.dll

autoStart: true 时，搜索遇到 IPC 不可用（Everything 未运行）会启动 everythingPath，等待约 2.5 秒后重试一次（仅当该 exe 存在）。

实现架构

Agent tool call
│
▼
index.js ── worker_threads ──▶ sdk-worker.cjs
（工具注册/配置/超时） │ koffi (N-API FFI) ▼
native/Everything64.dll (官方 Everything SDK)
│ WM_COPYDATA IPC
▼
Everything.exe 的 NTFS 索引

- SDK：使用官方 Everything SDK 的 Everything64.dll（原样取自 Everything-SDK.zip），调用 Everything_SetSearchW / Everything_QueryW / Everything_GetResult 等导出函数，结构化拿到路径、大小与 FILETIME，不做文本解析。
- FFI：Harness Host 是 Electron 44 / Node 24 运行时（Node-API 10），普通 Node 原生扩展 ABI 不匹配，因此使用 N-API FFI 模块 koffi 3.3.4（以及 win32-x64 预编译二进制）。
- Worker 隔离：SDK 的 Everything_QueryW(true) 内部会无限等待 Everything 的 IPC 回复；查询放在 worker 线程并设超时，避免卡死 Harness 的 Host 事件循环。超时后终止 worker，下一次查询自动重建。
- 插件为自包含 bundle：koffi 与 SDK DLL 都随包分发，安装时不需要联网、不需要编译。

DSH 版本支持

| 项目 | 说明 |
| 声明范围（engines.dsh） | >=0.2.1-rc.2 <0.3.0-0 |
| 实测版本 | DeepSeek Harness 0.2.1-rc.3（Desktop：Electron 44.7 / Node 24.21 / Node-API 10） |
| 契约一致性依据 | @deepseek-ai/dsh-app-boot、dsh-tools、dsh-plugin-manager、dsh-package-manifest 在 0.2.1-rc.2 与 rc.3 的发布产物逐字节一致；插件用到的扩展点（bundle patch、ctx.tools.register 的 ToolDefinition、插件显示元数据、安装与版本校验）在这两个版本间没有差异 |
| 不在范围内 | 0.2.0 及更早（核心包 API 不同，未验证）；0.3.0 及以后（DSH 仍为 developer preview，需重新验证后再放宽） |

npm 上 DSH 的 latest 标签当前是 0.2.1-rc.2，Desktop 运行时是 0.2.1-rc.3，都在声明范围内。

DSH 会在两处强制执行该声明（0.2.1 的 app-boot / plugin-manager 已内置）：

- 安装时：本地路径 / registry 包在 pnpm 运行前检查，不满足直接以 incompatible-version 拒绝；tarball / git spec 在安装后判定并回滚。
- 启动时：不兼容的 bundle 会被跳过（skippedBundles）、不兼容的插件行会被禁用，插件模块不会被 import。

确实需要冒险运行时，用精确版本豁免（不会放宽声明的范围）：

dsh plugin --profile desktop allow-version dsh-plugin-everything@1.0.2 --dsh-version <运行时版本> --accept-risk

或在插件管理器里调用 set_version_exemption（需用户明确接受风险）。DSH 升级后，请先确认本插件是否已发布兼容版本，再重启或重新安装。

兼容性与限制

- 仅 Windows x64；非 Windows 或 32 位环境下工具会返回明确错误。
- 依赖本机 Everything 客户端运行；Everything 1.4.1 实测通过，1.5 alpha 未实测。
- 搜索结果是 Everything 的索引快照，刚创建/移动的文件可能有秒级延迟。
- 结果包括 $Recycle.Bin、WinSxS 等系统目录；需要时用 !$Recycle.Bin 等语法排除。

验证记录

- install_bundle 安装返回 application: applied、enabled: true、无 warning。
- 真实查询：notepad.exe（18 命中）、中文文件名、path:/file:/folder:/ext: 语法、size 倒序、截断计数、空结果、max 越界钳制均通过。
- 异常路径：SDK DLL 缺失时返回可读的 SDK_LOAD_FAILED 错误，Host 不崩溃。
- 版本声明：engines.dsh 在 0.2.1-rc.3 上安装校验通过；构造的 engines.dsh: ">=99.0.0" 探针包被 DSH 以 incompatible-version 拒绝，证明声明确实生效。
- 打包校验：npm pack 产物解包后，worker + DLL + koffi 可独立加载查询。
- 显示资源：中英文 locale 标题/描述与 icon.svg 已导出并随包分发；GUI 内的图标渲染需要人工确认（自动化环境无浏览器控制）。

发布流程（维护者）

npm 发布由 .github/workflows/publish.yml 自动完成，已配置
npm Trusted Publishing（GitHub Actions OIDC，无需长期 token）：

package: dsh-plugin-everything
workflow: publish.yml
repository: keyblues/dsh-plugin-everything
permissions: publish, stage publish
trust id: 3aa47032-1bb5-4253-a6d6-7f92ca5b19ce

发版步骤：

1. 修改 package.json 的 version 与 CHANGELOG
git commit -am "chore(release): vX.Y.Z"
git tag vX.Y.Z
2. 推送 tag 触发发布
git push origin main --tags

Actions 会自动 npm pack → npm publish（带 provenance）→ 创建/更新 GitHub Release 并上传 .tgz。也可在 Actions 页面手动 Run workflow，发布 package.json 里的当前版本。

备用方式（无 OIDC 环境）：本地 npm login 后执行 npm publish --access public（需要 2FA）。

许可

- 本插件代码：MIT
- Everything SDK（native/Everything64.dll）：MIT，Copyright (C) 2016 David Carpenter / voidtools
- koffi / @koromix/koffi-win32-x64：MIT，Copyright (C) Niels Martignène
- 完整声明见 THIRD_PARTY_NOTICES.md。