shield_lock
JinDaGe
← Back to skills
extension
Category: Productivity & OfficeAPI key requirement unconfirmed

windows-file-search-runbook

在 Windows + Git Bash 上执行本地文件名索引与检索的操作流程：定位 ai-file-search 工具、用 D:/ 形式路径建立或刷新索引、执行关键词 / 本地 AI / 语义查询、AI 解析回退时拆分核心词并取交集，并始终保持只输出文件基本文件名。当用户要求查找本地文件或资料、检索某课程文档、为大目录建立或更新索引、换电脑启用本地文件检索，或本地查询返回 0 结果需要排障时使用。

personAuthor: ylyhf2026hubModelScope
downloadDownload package

Windows 本地文件名检索运行流程

适用范围

只枚举文件名：不读取文件内容、大小、时间戳或哈希；结果只输出基本文件名，不暴露路径；全程离线。

1. 定位工具

按顺序查找 scripts/ai-file-search.mjs，取第一个存在的位置作为 <工具目录>（含 scripts/ 的 ai-file-search 目录）：

  1. <工作区>/.qoder/skills/ai-file-search/
  2. <工作区>/ai-file-search/（可迁移副本）
  3. %USERPROFILE%/.qoder/skills/ai-file-search/

用 ls 或 Glob 确认存在。三处都没有时向用户询问工具位置，不要自行重写检索实现。之后所有命令都用绝对路径调用。

首次使用或换机先做环境检查：

node "<工具目录>/scripts/setup-environment.mjs"

提示缺 Python 包时再执行 --install：它只安装缺失的 openvino / openvino-genai，不升级已有包，也绝不下载模型。缺模型时按工具 README 的链接让用户手动下载，不要联网抓取。

2. 建立或刷新索引

node "<工具目录>/scripts/ai-file-search.mjs" init --root "D:/"
node "<工具目录>/scripts/ai-file-search.mjs" index --root "D:/"
node "<工具目录>/scripts/ai-file-search.mjs" index --root "D:/" --semantic

路径必须写成 D:/ 或 "D:/资料" 形式。写成 D:\（末尾反斜杠）会让 Git Bash 直接报 unexpected EOF while looking for matching '"'（Exit 2），命令根本不会执行，不要在这个写法上重试。

实测基线：整盘约 391,000 个文件名、约 50 秒、跳过约 190 个不可访问目录；大目录放在空闲时执行。索引库 <工具目录>/data/file-index.sqlite 含本机本地路径，属敏感数据：禁止复制到其他电脑或放进交付包，换机或换目录必须重建。

3. 查询

node "<工具目录>/scripts/ai-file-search.mjs" search --query "项目预算" --limit 30
node "<工具目录>/scripts/ai-file-search.mjs" search --query "找唐宋觉醒课程资料" --ai
node "<工具目录>/scripts/ai-file-search.mjs" search --query "唐宋觉醒创业课程" --semantic
  • 默认关键词查询：毫秒级（实测约 100 ms），优先使用。
  • --ai：本地模型把自然语言转成文件名词片段，实测约 8–10 秒。
  • --semantic：文件名向量召回，实测约 4 秒；需先用 index --semantic 或 semantic-index 生成向量索引；与 --ai 互斥。
  • 每次查询都核对输出首两行：Query parser: ... 与 Matched file names: N。
  • 索引不存在时脚本会报 No local index exists. Run init --root <directory> first.，先建索引再查询。

4. 零结果排障（按顺序执行）

  1. 先看 Query parser 字段。出现 local-keywords 说明本地模型解析失败并静默回退，此时 0 结果不代表没有匹配文件。
  2. 拆分核心词分别检索再取交集：把长请求拆成主题核心词逐个 search，取同时出现在各结果中的文件名。实测完整长句检索 0 命中，而核心词单独检索分别命中 1 条与 32 条，取交集后收敛到唯一目标文件。
  3. 检查模型解析出的词是否为整句或泛化短语。local-ai 不代表一定命中：若提取结果只有单个片段——整句或如「相关文档」这类泛化短语，而非 2–6 个短词片段——FTS 仍会 0 命中，改走第 2 条人工拆词。
  4. 把检索片段改成 3 个及以上字符：三元索引只对 3+ 字符走快速路径，1–2 字符退回 LIKE；用 xlsx 而不是 xl。
  5. 去掉泛化词：文件 / 文件夹 / 目录 / 文档 / 脚本 / file / script 等不参与检索，否则 AND 条件会把结果清空。
  6. 仍为 0 结果时，向用户确认目标目录是否已被索引覆盖，必要时对该目录重建索引，而不是直接回复「未找到」。

5. 输出与隐私约束

  • 只输出文件基本名称；不输出路径，不读取内容、大小、时间戳或哈希。
  • 相同文件名重复出现是预期的隐私取舍，不要为去重补充路径信息。
  • 不联网、不自动下载模型、不安装非缺失依赖；本地模型进程只接收用户查询文本。
  • 换机启用顺序：复制工具目录 → 用户手动下载模型 → setup-environment.mjs --install → 重建索引。

6. 验证清单

  • [ ] 索引输出包含 Indexed file names: N，N 与目标目录规模相符。
  • [ ] 查询输出包含 Query parser: 与 Matched file names: 两行。
  • [ ] 命中项均为基本文件名，无路径、无内容片段。
  • [ ] 0 结果时已按第 4 节排障，并说明回退与拆词过程中的实际命中数。