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