dsh-find-file
不受权限墙影响的 DeepSeek Harness 文件查找器：注册 find_file 代理工具。与内置 glob 不同，部分失败不会丢弃结果——无法读取的目录会被跳过并报告，complete:false 会警告目录树未被完全覆盖。零运行时依赖。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:Ronniealgo/dsh-find-file#528d135a1f7b39c37fd87634131c98fd73149adcFind File 以 dsh-find-file 发布，当前版本为 0.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
给 DeepSeek Harness（DSH）注册一个 find_file agent 工具：按文件名通配符（*、?）在指定根目录下找文件，撞上权限墙不会整次作废——读不了的目录跳过并如实上报，结果里永远标明这次搜索是否完整。纯 Node 实现，零运行时依赖，Node ≥ 20。
同一棵树的两种命运：
树里有 1 个匹配，还有 2 个普通进程读不了的目录（Windows ACL）：
内置 glob → Error: glob search failed (exit 2): rg: ... 拒绝访问。 (os error 5)
已扫到的结果全部丢弃。"到底有没有？"——无从谈起。
find_file → matches: [ "C:\\...\\pdftotext.exe" ] ← 照常返回
skipped: [ { path: "...", code: "EPERM" }, … ]
complete: false, incompleteReason: "permission-denied"
DSH 内置 glob 工具把搜索委托给 ripgrep。在 Windows 上扫宽目录——C:\Program Files、用户主目录、盘根——几乎必然撞上系统级 ACL：C:\Program Files\WindowsApps 这类目录对普通进程就是拒绝访问，rg 以非零码退出，报错类似 Error: glob search failed (exit 2): rg: ... 拒绝访问。 (os error 5)。此时 glob 的行为是整次作废：只要 ripgrep 以 ≥2 的退出码结束，整条搜索连同已扫到的结果一起丢弃，模型拿到的只有这一条 Error。
真正的伤害在语义上：一次"因为权限失败"的搜索和一次"没找到"的搜索，在下游推理里很容易被混为一谈，于是"文件不存在"的错误结论就从一次失败的搜索里被顺手推出来了。本插件把"部分失败"当成一等结果：读不了的目录跳过（不中断搜索），连同 errno 一起写进结果；任何让覆盖不完整的因素——权限、时间预算、结果上限、深度上限——都会把 complete 置为 false 并给出 incompleteReason。这次搜索覆盖了多少、缺了哪一块，变成模型可以直接读到的事实，不用猜。
两种方式都只动两个位置：profile 的 node_modules 下建一个目录联接（junction），cordis.patch.yml 末尾加一行插件声明。
git clone https://github.com/Ronniealgo/dsh-find-file.git
cd dsh-find-file
powershell -ExecutionPolicy Bypass -File install.ps1 # 装进 desktop profile
powershell -ExecutionPolicy Bypass -File install.ps1 -Uninstall # 卸载
脚本只做两件事：把本目录 junction 进 %USERPROFILE%\.dsh\profiles\desktop\node_modules\dsh-find-file，并在该 profile 的 cordis.patch.yml 末尾追加 - insert: 块。每次改动前先写时间戳备份，-Uninstall 按同一算法把行删回去（备份保留，可逐字节还原）。-Profile 指定其它 profile，-DshHome 指定其它 DSH 主目录。
New-Item -ItemType Junction -Path "$env:USERPROFILE\.dsh\profiles\desktop\node_modules\dsh-find-file" -Target "C:\path\to\dsh-find-file"
%USERPROFILE%\.dsh\profiles\desktop\cordis.patch.yml 末尾追加（config: 可整体省略，四个键都有默认值）：- insert:
- id: find-file
name: dsh-find-file
config:
maxResults: 50
timeBudgetMs: 90000
maxDepth: 64
includeDirs: false
写错键名不会静默失效：未知配置键在插件加载时直接抛错（刻意设计，见「配置」）。
工具注册后，必填参数只有两个：root（搜索起点，目录或单个文件）和 pattern（纯文件名模式：* 匹配任意长度，? 恰好一个字符，其余按字面匹配；不允许路径分隔符——要找子目录里的东西，就把 root 指到那个子目录）。四个上限可选。
{
"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" },
{ "path": "C:\\Users\\me\\AppData\\Roaming\\VendorX\\protected", "code": "EACCES" }
],
"complete": false,
"incompleteReason": "permission-denied",
"elapsedMs": 8421,
"limits": {
"maxResults": 100,
"timeBudgetMs": 90000,
"maxDepth": 64,
"includeDirs": false,
"caseInsensitive": true
}
}
字段速览：matches 是绝对路径（按遍历顺序，封顶 maxResults）；dirsWalked 是成功读取的目录数；symlinkSkipped 是看到但未跟随的符号链接/junction 数；skipped 是读不了的目录清单，每条带 errno 代码（最多列 30 条，总数看 skippedCount）；limits 是这次调用实际生效的上限。
工具返回给模型的文本块永远以 VERDICT 行收尾，例如：
find_file: 1 match(es) · 14120 dirs walked · 8421 ms · search INCOMPLETE (permission-denied)
C:\Users\me\AppData\Local\Programs\poppler\Library\bin\pdftotext.exe
skipped 2 dir(s): C:\Users\me\AppData\Local\Temp\ipc-lock (EPERM); C:\Users\me\AppData\Roaming\VendorX\protected (EACCES)
symlinks/junctions not followed: 3
VERDICT: search incomplete — absence here is NOT proof of absence overall. Narrow the root or recheck before concluding.
node bin\find-file.mjs C:\Users\me\AppData pdftotext.exe --max-results 100
node bin\find-file.mjs C:\Users\me\Documents "*.pdf" --include-dirs --quiet
选项：--max-results N、--time-budget-ms N、--max-depth N、--include-dirs、--case-sensitive、--quiet（只打印匹配路径）。退出码：0 = 搜索完成（0 个匹配也算完成）；1 = 致命错误（root 访问不了）；2 = 用法错误（参数或模式不合法）。
complete: true——预算内把 root 下整棵树读完。只有这时，matchedCount: 0 才允许下结论「该文件在此 root 下不存在」。symlinkSkipped。这是刻意策略（Windows 上 junction 环会让天真的遍历永不终止），不算覆盖缺口，也不影响 complete。complete: false——搜索不完整，「没找到」不成立。incompleteReason 只有四个值：
permission-denied：有目录读不了，清单在 skipped；time-budget：时间预算用尽；result-limit：匹配数到达 maxResults；depth-limit：树比 maxDepth 深。complete: false 时先缩小 root 或放宽上限重查，再谈存在与否。四个 entry config 键（写进 cordis.patch.yml 的 config: 块），每次调用可用同名参数覆盖：
| 键 | 范围 | 默认 | 说明 |
|---|---|---|---|
maxResults | 1–1000 | 50 | 命中即停，标记 result-limit |
timeBudgetMs | 1000–600000 | 90000 | 毫秒墙钟预算，用尽即停，标记 time-budget |
maxDepth | 1–256 | 64 | root 下的目录层数，超过标记 depth-limit |
includeDirs | true / false | false | 目录名也参与匹配；匹配到的目录仍会被深入遍历 |
maxResults 拼成 maxRsults，必须炸在加载时，而不是静默退回默认值。caseInsensitive 不是 entry config 键；调用时可显式传，不传则按平台取默认——win32/darwin 不区分大小写，其余平台区分。CLI 对应 --case-sensitive。| 内置 glob | find_file | |
|---|---|---|
| 撞上读不了的目录 | 整次搜索作废，返回 Error: glob search failed (exit 2) | 跳过该目录继续搜，skipped 里记下 {path, code} |
| 已扫到的结果 | 全部丢弃 | 照常返回，complete: false 明示覆盖不完整 |
| 「没找到」的可信度 | 失败时无意义 | complete: true 且 0 匹配 ⇒ 确定不存在 |
| 部分覆盖的可见性 | 无 | incompleteReason 说明缺哪一类 |
| 匹配目标 | glob 模式匹配整条路径 | 纯文件名 * / ?（不许路径分隔符） |
| 运行时依赖 | ripgrep 二进制 | 无（node:fs/promises + node:path） |
npm test # 显式点名 4 个测试文件，零依赖，无需 npm install
npm run check # node --check 全部源文件
要求 Node ≥ 20。引擎（lib/walk.js）的文件系统与时钟是注入的，单测不碰真实磁盘；CLI 测试会真实拉起 bin/find-file.mjs。更完整的来龙去脉见 docs/MOTIVATION.md。
symlinkSkipped 计数明示）。a/**/b 这类路径 glob。skipped 清单最多 30 条（skippedCount 始终准确）；matches 封顶 maxResults。timeBudgetMs 兜底。