OpenVINO 文件名语义检索

用本地 OpenVINO 嵌入模型为文件名生成向量，在本机 SQLite 上做余弦相似度语义检索，全程离线。适合文件名不含相同关键词但概念相近的查找；纯编号或含义模糊的文件名效果有限。

隐私边界

• 嵌入模型在建索引时只接收规范化文件名（NFKC、小写）；不接收路径、文件内容、时间戳、大小、权限或哈希。
• 查询结果只输出基本文件名，不暴露目录结构。
• 绝不自动下载模型：告知用户从 Hugging Face 官方仓库手动下载，例如 OpenVINO/Qwen3-Embedding-0.6B-int8-ov。
• 模型进程用无 Shell 的 execFile 启动；索引与查询不发起网络请求。

环境检查与嵌入模型路径

• 检查 Node.js（node:sqlite 需 22.5+）、Python、openvino 与 openvino-genai；已有包不安装不升级，只补缺失包。
• 嵌入模型放在技能目录内固定相对位置（如 models/Qwen3-Embedding-0.6B-int8-ov/）。环境检查必须以技能目录为基准解析该相对路径；相对路径被解析到技能目录之外是已出现的可移植性缺陷，报告缺失模型时定位必须准确。
• 模型目录至少直接包含 openvino_model.xml、openvino_model.bin、openvino_tokenizer.xml、openvino_tokenizer.bin、config.json、tokenizer_config.json，保留仓库目录结构。
• CPU 即可运行；缺失模型时明确报错并提示手动下载，不做任何下载动作。

向量索引构建

• 先完成文件名索引（FTS5 关键词层），再在其上构建向量：为每个规范化文件名生成向量（Qwen3-Embedding-0.6B 为 1024 维）。
• 向量以归一化 float32 BLOB 存入本机 SQLite 表（如 file_name_embeddings），字段含关联文件 ID、规范化文件名、向量；元数据表记录模型路径与向量维度。
• 模型变更（路径或维度不同）时全部向量重建。

增量更新

• 新增或改名的文件只生成必要的新向量，以规范化文件名识别变更，避免全量重嵌。
• 已删除文件的向量在索引同步后清除。
• 验证方式：新增和改名各只新增一条向量，删除后向量表无残留。

语义查询

• 将查询文本嵌入为单位向量，与同维度库内向量计算精确余弦相似度，保留 Top-K 基本文件名。
• 当前是精确向量比较，不是 HNSW/ANN；百万级文件名须实测查询延迟与内存后再评估近似索引。
• 语义相似不等于精确相关：已知文件名片段优先走关键词检索。

可移植交付验证

• 发布包只含脚本与文档，不含本机 SQLite 索引、真实文件路径或模型文件；data/ 在目标电脑首次运行时自行创建。
• 目标电脑自行建立索引，不复制其他电脑的索引数据库（其中可能含原机本地路径）。
• 端到端验证清单：
  1. 先做区分度探针：嵌入 2-3 个明显无关的文本（如“猫”与“量子力学”），两两余弦必须低于 0.8；若无关文本对的余弦都接近 1，说明嵌入输出退化、排序不可信，先排查根因再往下验。
  2. 建隔离测试集：少量空文件，取语义可区分的中文文件名。
  3. 建向量索引后核对向量条数等于文件数、维度一致。
  4. 用概念化自然语言查询，确认目标文件名排在首位（以第 1 项探针通过为前提）。
  5. 验证增量：新增、改名各只生成一条向量，删除后过期向量被清理。
  6. 回归关键词检索路径，性能不退化。
  7. 移走模型后运行环境检查，确认在技能目录内准确报告缺失且不自动下载。
  8. 删除全部测试产物，确认交付目录无索引数据、无模型。
• 性能验收分别测量首次嵌入、增量嵌入、语义查询 p50/p95 延迟、索引大小与内存峰值；只宣称已实测的指标。