Introduction

When the DeepSeek Harness agent handles cross-workspace file searches (such as “Where is the PDF I downloaded last night?” or “All .env files on the D drive”), conventional directory-tree-based search methods are highly inefficient. dsh-goz is a plugin designed for DSH that uses the goz engine to read the NTFS MFT (Master File Table) and build an in-memory filename index, completely bypassing directory tree traversal and enabling the agent to answer “where is a file?” in milliseconds.

Features and Principles

  1. Millisecond-level filename lookup across the full disk or a scoped directory: Based on the goz engine, this uses MFT indexing for fast retrieval.
  2. Tool interface: Provides two model-facing tools: search_file and goz_status.
  3. MFT indexing: Reads the NTFS MFT and indexes filenames, sizes, and timestamps, but does not include file contents.
  4. Bypasses the directory tree: It does not need to traverse the filesystem tree structure, resulting in very low retrieval overhead.

Installation and Enablement

Installation consists of two steps: installing the plugin package and installing the daemon. The latter requires administrator privileges.

  1. Install the plugin
    Install it in npm package form:
    dsh plugin --profile web add dsh-goz

For local debugging, you can use the link form:

    dsh plugin --profile web add link:C:/path/to/dsh-goz
  1. Install the daemon (the only manual step)
    The goz daemon requires administrator privileges to start the system service. Enter the vendor directory bundled with the plugin (for example, C:\Users\Administrator\Desktop\dsh\dsh-goz\vendor) and run the installation:
    .\gozd.exe install

After installation, `goz.exe` and `gozd.exe` are copied to the user directory and registered as a system service.
  1. Verify the installation
    Check the version and status:
    .\vendor\gozd.exe --version
    .\vendor\goz.exe --status

Or ask the agent directly in a dsh conversation.

Usage

The plugin registers two tools: search_file and goz_status.

search_file(query, scope?, max?)

Parameter Type Description
query string, required goz query syntax; must not be empty
scope string, optional Limits the search directory (mapped to -path); exceeding the whitelist triggers approval
max number, optional Result limit (mapped to -n); default 50, maximum 5000

Return value: Structured JSON containing query, total (total number of matches), returned (number actually returned), and results (file list).

Example query syntax:
* Filename substring: report matches QuarterlyReport.xlsx
* Wildcard: *.pdf
* Extension filtering: ext:pdf;docx (Note: multiple extensions must be separated by a semicolon; commas do not work)
* Path substring: path:C:\dsh
* Size filtering: size:>1mb

goz_status()

Checks whether the daemon is online and the health of the index.

Notes

  1. Syntax limitations: The exclusion operator !term is not yet implemented. The case: switch does not take effect in v0.1.1.
  2. Index contents: The goz index does not include file contents; it only includes filenames, sizes, and timestamps.
  3. Permission requirements: goz is a stateless CLI client, gozd.exe is a system service, and the daemon must be installed with administrator privileges.

Summary

dsh-goz solves the performance pain point of full-disk file lookup for DSH agents. By using MFT indexing, locating files across drive letters and with fuzzy filenames is reduced from “minutes” to the “millisecond range.”

  • GitHub: https://github.com/hfyydd/dsh-goz
  • Catalog page: https://www.skillhub.cn/plugins/hfyydd/dsh-goz