前言¶
DeepSeek Harness 的智能体在处理跨工作区的文件查找（如“昨晚下载的 PDF 在哪”或“D 盘所有 .env 文件”）时，常规基于目录树的搜索方式效率极低。dsh-goz 是一个为 DSH 设计的插件，利用 goz 引擎读取 NTFS 的 MFT（主文件表）建立内存文件名索引，完全绕过目录树遍历，让 agent 能够毫秒级回答“某个文件在哪里”。
功能与原理¶
- 全盘/限定目录按文件名毫秒级定位：基于 goz 引擎，通过 MFT 索引快速检索。
- 工具接口：提供
search_file和goz_status两个面向模型（model-facing）的工具。 - MFT 索引：读取 NTFS MFT，索引包含文件名、大小、时间，但不包含文件内容。
- 绕过目录树：无需遍历文件系统树结构，检索开销极低。
安装与启用¶
安装分为插件包安装和 daemon 安装两个步骤，后者需要管理员权限。
- 安装插件
使用 npm 包形式安装：
dsh plugin --profile web add dsh-goz
如果是本地调试，可使用 link 形式：
dsh plugin --profile web add link:C:/path/to/dsh-goz
- 安装 daemon（唯一的人工步骤）
goz 的 daemon 需要管理员权限启动系统服务。进入插件自带的vendor目录（例如C:\Users\Administrator\Desktop\dsh\dsh-goz\vendor），执行安装：
.\gozd.exe install
安装后，`goz.exe` 和 `gozd.exe` 会被复制到用户目录并注册为系统服务。
- 验证安装
检查版本和状态：
.\vendor\gozd.exe --version
.\vendor\goz.exe --status
或在 dsh 对话中直接询问 agent。
使用方式¶
插件注册了两个工具：search_file 和 goz_status。
search_file(query, scope?, max?)¶
| 参数 | 类型 | 说明 |
|---|---|---|
query |
string, 必填 | goz 查询语法，非空 |
scope |
string, 可选 | 限定搜索目录（映射 -path），超出白名单会触发审批 |
max |
number, 可选 | 结果上限（映射 -n），默认 50，最大 5000 |
返回值：结构化 JSON，包含 query、total（完整匹配数）、returned（实际返回数）、results（文件列表）。
示例查询语法：
* 文件名子串：report 匹配 QuarterlyReport.xlsx
* 通配符：*.pdf
* 扩展名过滤：ext:pdf;docx（注意：多扩展名必须用分号分隔，逗号无效）
* 路径子串：path:C:\dsh
* 大小过滤：size:>1mb
goz_status()¶
检查 daemon 是否在线及索引健康状态。
注意事项¶
- 语法限制：排除运算符
!term尚未实现。使用case:开关在 v0.1.1 中不生效。 - 索引内容：goz 索引不含文件内容，仅限文件名/大小/时间。
- 权限要求：goz 是无状态 CLI 客户端，gozd.exe 是系统服务，daemon 需要管理员权限安装。
总结¶
dsh-goz 解决了 DSH agent 在全盘文件查找上的性能痛点，通过 MFT 索引将跨盘符、模糊文件名的定位从“数分钟”降低到“毫秒级”。
- GitHub: https://github.com/hfyydd/dsh-goz
- 目录页: https://www.skillhub.cn/plugins/hfyydd/dsh-goz
