dsh-find-file：DSH 权限免疫的文件搜索工具

前言¶

DeepSeek Harness（DSH）内置的 glob 工具依赖 ripgrep 进行搜索。在 Windows 环境下，当扫描路径（如 C:\Program Files）遇到系统级 ACL 权限限制时，rg 通常返回非零退出码。这会导致整次搜索被判定为失败，已扫描到的结果会被全部丢弃。模型在处理这种 Error: glob search failed 时，极易将其误判为“文件不存在”。

dsh-find-file 解决了这个语义断层问题。它注册了一个 find_file agent 工具，按文件名通配符搜索。遇到不可读的目录时，它不会中断搜索，而是跳过该目录并记录 errno，最终返回一个包含部分结果和覆盖状态的报告。

是什么¶

这是一个为 DeepSeek Harness 设计的插件，将一个纯 Node.js 实现的文件搜索工具注册为 agent。它不依赖任何运行时库，要求 Node.js 版本 ≥ 20。

安装与启用¶

安装过程涉及修改 profile 的 node_modules 目录（建立联接）和更新 cordis.patch.yml 配置文件。

一键安装（推荐）¶

在项目根目录下执行以下命令，将插件安装到桌面 profile：

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

手动安装¶

如果需要自定义路径或 profile，需手动操作：

1. 建立目录联接（Junction）：

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

2. 在 profile 的 cordis.patch.yml 末尾追加配置：

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

3. 重启 DSH，在设置中启用插件。

典型用法¶

安装完成后，Agent 工具和 CLI 命令均可使用。

Agent 工具调用¶

必填参数为 root（搜索起点）和 pattern（文件名模式，支持 * 和 ?）。

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

返回示例：

{
  "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 调用¶

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

complete 的语义¶

该插件的核心价值在于明确区分“搜索完成”和“搜索中断”。

• complete: true：表示在预算内完整遍历了 root 下的树。只有在这种情况下，matchedCount: 0 才能作为“文件不存在”的确凿证据。
• complete: false：表示搜索不完整，可能是遇到了权限墙、时间预算耗尽或达到结果上限。此时“没找到”不成立，必须缩小范围或重查。

配置¶

在 cordis.patch.yml 的 config 块中配置默认参数，调用时也可覆盖。

注意：未知配置键会在加载时直接抛错，这是刻意设计，防止静默失效。

限制说明¶

• 不跟随符号链接：遇到 symlink/junction 会被跳过并计入 symlinkSkipped，不会进入目标目录。
• 仅文件名匹配：不支持 a/**/b 这类路径 glob，只匹配文件名（*、?）。
• 跳过清单上限：skipped 数组最多记录 30 条错误信息，但 skippedCount 会准确反映总数。
• 平台特性：主要针对 Windows ACL 场景设计，依赖 Node >= 20。

与内置 glob 的对比¶

生态背景¶

DeepSeek Harness 理念为“一切皆插件”。本插件已收录至 DSH 插件市场 及 dshfind.com，但不代表官方背书。

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