dsh-find-file: A File Search Tool Immune to DSH Permissions

Introduction¶

The built-in glob tool in DeepSeek Harness (DSH) relies on ripgrep for searching. In Windows environments, when the scanned path (such as C:\Program Files) encounters system-level ACL permission restrictions, rg typically returns a non-zero exit code. This causes the entire search to be marked as failed, and all results already scanned may be discarded. When handling this Error: glob search failed, models easily misinterpret it as “the file does not exist”.

dsh-find-file solves this semantic gap. It registers a find_file agent tool that searches by filename wildcards. When it encounters an unreadable directory, it does not interrupt the search; instead, it skips the directory and records the errno. It ultimately returns a report containing partial results and coverage status.

What It Is¶

This is a plugin designed for DeepSeek Harness. It registers a pure Node.js file search tool as an agent. It has no runtime dependencies and requires Node.js version ≥ 20.

Installation and Enablement¶

Installation requires modifying the profile’s node_modules directory (by creating a junction) and updating the cordis.patch.yml configuration file.

One-Click Installation (Recommended)¶

Run the following commands in the project root directory to install the plugin into the desktop profile:

git clone https://github.com/Ronniealgo/dsh-find-file.git
cd dsh-find-file
powershell -ExecutionPolicy Bypass -File install.ps1

Manual Installation¶

If you need to customize the path or profile, perform the following steps manually:

1. Create a directory junction:

    New-Item -ItemType Junction -Path "$env:USERPROFILE\.dsh\profiles\desktop\node_modules\dsh-find-file" -Target "C:\path\to\dsh-find-file"

2. Append the following configuration at the end of the profile’s cordis.patch.yml:

    - insert:
        - id: find-file
          name: dsh-find-file
          config:
            maxResults: 50
            timeBudgetMs: 90000
            maxDepth: 64
            includeDirs: false

3. Restart DSH and enable the plugin in Settings.

Typical Usage¶

After installation, both the Agent tool and CLI command are available.

Agent Tool Invocation¶

Required parameters are root (search starting point) and pattern (filename pattern; supports * and ?).

{
  "root": "C:\\Users\\me\\AppData",
  "pattern": "pdftotext.exe",
  "maxResults": 100
}

Return example:

{
  "root": "C:\\Users\\me\\AppData",
  "pattern": "pdftotext.exe",
  "matches": [
    "C:\\Users\\me\\AppData\\Local\\Programs\\poppler\\Library\\bin\\pdftotext.exe"
  ],
  "matchedCount": 1,
  "dirsWalked": 14120,
  "symlinkSkipped": 3,
  "skippedCount": 2,
  "skipped": [
    { "path": "C:\\Users\\me\\AppData\\Local\\Temp\\ipc-lock", "code": "EPERM" }
  ],
  "complete": false,
  "incompleteReason": "permission-denied",
  "elapsedMs": 8421
}

CLI Invocation¶

node bin\find-file.mjs C:\Users\me\AppData pdftotext.exe --max-results 100

Semantics of complete¶

The core value of this plugin is explicitly distinguishing “search completed” from “search interrupted”.

• complete: true: Indicates that the entire tree under root was fully traversed within the budget. Only in this case can matchedCount: 0 serve as definitive evidence that “the file does not exist”.
• complete: false: Indicates that the search is incomplete, possibly due to permission restrictions, an exhausted time budget, or reaching the result limit. In this case, “not found” is not valid; you must narrow the scope or re-query.

Configuration¶

Default parameters are configured in the config block of cordis.patch.yml and can also be overridden during invocation.

Note: Unknown configuration keys will throw an error during loading. This is intentional by design to prevent silent failures.

Limitations¶

• Does not follow symbolic links: symlinks/junctions are skipped and counted in symlinkSkipped; the target directory is not entered.
• Filename matching only: path globs such as a/**/b are not supported; only filenames are matched using * and ?.
• Skip list cap: the skipped array records at most 30 error entries, but skippedCount accurately reflects the total count.
• Platform characteristics: mainly designed for Windows ACL scenarios and requires Node >= 20.

Comparison with the Built-in glob¶

Ecosystem Background¶

DeepSeek Harness follows the philosophy of “everything is a plugin”. This plugin has been included in the DSH Plugin Marketplace and dshfind.com, but this does not imply official endorsement.

• GitHub repository: https://github.com/Ronniealgo/dsh-find-file