somethingSTRANGE/Vault-Search

# Vault 搜索工具 一个用于 Markdown 文件文件夹的模糊关键词搜索命令行工具。专为需要从终端搜索知识库的 AI 助手（如 Claude Code）设计，同时也可作为独立工具使用。 ## 功能 - **模糊搜索** — 即使查询词拼写错误或略有不同也能找到结果 - **别名扩展** — 将搜索词元映射到一组等效术语（同义词、专有名词变体） - **前置元数据别名提取** — 自动读取 Obsidian 的 `aliases:` 前置元数据，并在重建时将其接入查询扩展 - **范围过滤** — 限制索引和搜索范围到特定文件夹，并为常用搜索提供命名预设 - **前置元数据过滤** — 按 `type` 值或属性存在性过滤结果 - **拼写审计** — 在您的知识库中找出可能的拼写变体 - **快速脏检查** — 仅在文件发生变化时重建词列表 ## 结果排名机制 较长的连续短语匹配比单个词元匹配获得更高评分 — 搜索 "growl fm" 时，那些这些词在同一行上连续出现的文件会获得额外权重，如果 "growl fm radio" 所有三个词都连续出现则权重更高。精确匹配总是优先于模糊匹配。文件名中的匹配比内容中的匹配得分更高。仅有模糊匹配（对任何查询词元都没有精确命中）的文件在所有精确匹配结果之后回填列表。 ## 要求 - [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`) 在您的 PATH 中 - Windows x64（适用于预编译二进制文件）；其他平台需要从源代码构建 ## 安装 下载最新的发布二进制文件 (`vault-search.exe`) 并将其放置在 PATH 中的某个位置。 ## 用法 从知识库文件夹运行，或传递 `--vault` 明确指向它。 ### 搜索 ``` vault-search "query terms" [--top N] [--vault PATH] [--data PATH] [--rebuild] [--scope NAME] [--type VALUE] [--property NAME] [--pretty] [--light] [--no-ansi] ``` 在知识库中搜索与查询匹配的文件。每个词元在搜索前都会根据词列表进行模糊扩展，因此近似匹配会自动包含。前置元数据的 `aliases:` 属性在重建时提取并合并到查询扩展中。 | 选项 | 默认值 | 描述 | |---|---|---| | `--top N` | `10` | 结果的最大数量 | | `--vault PATH` | 当前目录 | 知识库文件夹的路径 | | `--data PATH` | 自动检测 | 数据目录（数据库和配置）的路径 | | `--rebuild` | — | 在搜索前强制重建词列表 | | `--scope NAME` | — | 命名的搜索范围预设（加载 `scope-.txt`） | | `--type VALUE` | — | 将结果过滤为前置元数据 `type` 与此值匹配的文件 | | `--property NAME` | — | 将结果过滤为设置了此前置元数据属性（任意值）的文件 | | `--pretty` | — | 以格式化表格形式渲染结果，而非纯结构化文本 | | `--light` | — | 在纯输出中使用浅色终端颜色（浅色背景上的深色文字） | | `--no-ansi` | — | 在纯输出中禁用 ANSI 颜色代码 | `--type` 和 `--property` 在取前 N 个结果之前应用，因此您始终会从匹配集中获得最多 N 个结果。 默认情况下，输出是适合机器解析的纯结构化文本（每个结果一个块）。当写入实际终端时，会自动应用 ANSI 颜色：文件路径高亮显示以便扫描，标签文字变暗。输出通过管道传输或重定向时，颜色会自动抑制。使用 `--no-ansi` 可在终端中强制使用纯输出，或使用 `--light` 切换到深色背景上的浅色方案。交互式运行时使用 `--pretty` 可获得格式化表格。 ### 拼写 ``` vault-search spellings [token] [--vault PATH] [--data PATH] [--threshold N] [--scope NAME] [--type VALUE] [--property NAME] [--pretty] ``` 不带词元时，审计整个词列表中可能的拼写错误 — 即那些出现频率低且与某个更常见词元相似的词元。带词元时，显示该特定词的所有相似变体。 | 选项 | 默认值 | 描述 | |---|---|---| | `--threshold N` | `20` | 将词元视为规范词元的最小频率 | | `--vault PATH` | 当前目录 | 知识库文件夹的路径 | | `--data PATH` | 自动检测 | 数据目录的路径 | | `--scope NAME` | — | 命名的搜索范围预设 | | `--type VALUE` | — | 按前置元数据 `type` 值过滤文件结果 | | `--property NAME` | — | 将文件结果过滤为具有此前置元数据属性的文件 | | `--pretty` | — | 以格式化表格形式渲染结果，而非纯结构化文本 | ### 重建 ``` vault-search rebuild [--vault PATH] [--data PATH] ``` 强制完全重建词列表索引并重新提取前置元数据别名，无论文件是否看起来已更改。 ### 范围 ``` vault-search scopes [--vault PATH] [--data PATH] ``` 列出可用的范围预设。显示默认的 `scope.txt` 和任何命名预设 (`scope-.txt`) 以及使用每个预设所需的确切标志。 ## 数据目录 vault-search 将其数据库和配置文件存储在知识库旁边的数据目录中。位置是自动检测的： 1. 如果提供了 `--data PATH` 2. 如果知识库包含 `.obsidian` 文件夹（Obsidian 知识库），则为 `.obsidian/tools/vault-search/` 3. 否则为知识库根目录下的 `.vault-search/` 数据目录包含两个子目录： - `config/` — 用户编辑的配置文件（见下文） - `db/` — SQLite 词列表索引（可重建；可安全删除） **Obsidian Sync 用户：** 请将 `db/` 文件夹从同步中排除 — 它很大且会自动重新生成。`config/` 文件夹应正常同步。 ## 配置 首次运行时，vault-search 会将带注释的存根文件写入 `config/` 目录。编辑它们以自定义行为。 ### `aliases.yaml` — 语义查询扩展 将搜索词元映射到等效术语列表。主词元始终被搜索；别名则额外添加。用于处理同义词、拼写变体或模糊匹配无法处理的多词短语。 ``` nightfall: - dusk - evening storm ``` ### `fm-aliases.yaml` — 自动生成的前置元数据别名 在每次重建期间从您 Markdown 文件的 `aliases:` 前置元数据属性自动生成。**请勿编辑** — 更改将被覆盖。文件名中的每个词元都被映射到其前置元数据别名列表中提取的词元。 ### `stopwords-extra.txt` — 停用词自定义 每行一个词。以 `#` 开头的行将被忽略。纯单词将添加到内置停用词列表中。在单词前加 `-` 可将其从内置列表中移除。 ``` # 添加自定义停用词： lorem # 移除内置停用词（例如，以便使角色名称可搜索）： -les ``` ### `scope.txt` — 文件夹包含/排除规则 控制哪些文件夹被索引和搜索。规则从上到下应用；最后匹配的规则生效。如果没有活动规则，则包含所有文件夹。 ``` # 排除所有内容，然后包含特定文件夹： -* +Projects +Areas # 进一步排除干扰性子文件夹： -Areas/Archive ``` #### 命名范围预设 创建额外的范围文件作为 `scope-.txt` 以定义可重复使用的搜索预设。在搜索时使用 `--scope ` 选择预设。默认的 `scope.txt` 始终用于重建；命名范围仅影响 ripgrep 搜索的文件夹。 ``` # config/scope-characters.txt -* +Areas/Characters ``` ``` vault-search "father" --scope characters --type profile ``` 使用 `vault-search scopes` 列出所有可用预设。 ## 工作原理 1. **脏检查** — 扫描文件修改时间；如果没有变化则跳过重建 2. **重建** — 将所有 `.md` 文件内容和文件名词化到 SQLite 词列表中，去除停用词；将前置元数据 `aliases:` 提取到 `fm-aliases.yaml` 3. **查询扩展** — 每个查询词元通过别名词典（用户和前置元数据）进行扩展并与词列表进行模糊匹配；所有候选项都被搜索 4. **范围** — 如果给出了命名的 `--scope`，则仅搜索该预设中定义的文件夹；否则应用默认的 `scope.txt` 5. **搜索** — ripgrep 在限定的文件夹范围内搜索扩展后的词集 6. **过滤** — `--type` 和 `--property` 在取前 N 个结果之前按前置元数据过滤结果 7. **排名** — 结果根据匹配质量（短语长度、精确 vs 模糊、文件名 vs 内容）进行评分并按顺序返回；参见上文的*结果排名机制*

标签：AI助手, Markdown处理, Obsidian集成, ripgrep, SQLite, 关键词匹配, 别名管理, 前言提取, 拼写检查, 文件过滤, 文档结构分析, 本地工具, 模糊搜索, 索引优化