使用

作为 agent 工具（find_file）

工具注册后，必填参数只有两个：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.

作为 CLI

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 = 用法错误（参数或模式不合法）。

配置

四个 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`	目录名也参与匹配；匹配到的目录仍会被深入遍历

越界数值会被夹回范围内（不是报错）；类型错误和未知键抛错。
未知键抛错是刻意设计：patch 里把 maxResults 拼成 maxRsults，必须炸在加载时，而不是静默退回默认值。
caseInsensitive 不是 entry config 键；调用时可显式传，不传则按平台取默认——win32/darwin 不区分大小写，其余平台区分。CLI 对应 --case-sensitive。

dsh-find-file

Install

README

使用

作为 agent 工具（find_file）

作为 CLI

配置