mcpField
W
wiki-retrieve

wiki-retrieve

github.com/agricidaniel生产力15.9k302 次安装6 天前更新
代码仓库

关于 wiki-retrieve

为 Obsidian vault 中的 wiki 页面建立本地检索索引的技能，面向需要查找相关段落的用户。它结合上下文前缀、BM25 检索和可选重排，且不会改动规范笔记。

主要功能

  1. 01按段落切分页面并生成前缀
  2. 02构建本地 BM25 索引
  3. 03检索片段并按页面去重
  4. 04可选使用 Ollama 重排
  5. 05校验路径、哈希和索引完整性

适用场景

  1. 01从 wiki 页面查找相关段落
  2. 02在不调用模型的情况下执行词法检索
  3. 03对 BM25 候选结果进行重排
  4. 04检查索引状态并评估检索效果

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/agricidaniel/claude-obsidian --skill wiki-retrieve

安装后在 Claude Code 中输入/wiki-retrieve确认已加载。

详细介绍

检索相关段落

此扩展会从 wiki/ 提取搜索数据并写入 .vault-meta/。它不会更改规范笔记。始终显式传入所选知识库。

从此技能自身的位置解析已安装产品根目录，而不是从知识库或当前工作目录解析：

PRODUCT_ROOT=/absolute/path/to/installed/claude-obsidian
PREFIX="$PRODUCT_ROOT/scripts/contextual-prefix.py"
BM25="$PRODUCT_ROOT/scripts/bm25-index.py"
RETRIEVE="$PRODUCT_ROOT/scripts/retrieve.py"
RERANK="$PRODUCT_ROOT/scripts/rerank.py"
test -f "$PREFIX" && test -f "$BM25" && test -f "$RETRIEVE" && test -f "$RERANK"

流程

  1. contextual-prefix.py 按段落边界拆分页面，并保存原始块及简短的页面级前缀。
  2. bm25-index.py 基于上下文化文本，使用标准库构建本地 BM25 索引。
  3. retrieve.py 选出 BM25 候选项，可选择对其重新排序，排除无效记录，按页面去重，并返回路径和片段。
  4. 调用方读取返回的页面并进行综合；检索输出本身并非证据。

本地配置

先预览，再构建合成前缀，全程不进行网络外传：

python3 "$PREFIX" --vault "$VAULT" --all --no-llm --peek
python3 "$PREFIX" --vault "$VAULT" --all --no-llm
python3 "$BM25" --vault "$VAULT" build
python3 "$RETRIEVE" --vault "$VAULT" "wiki" --top 1 --no-rerank --explain

分块文件和索引文件均为可丢弃的运行时状态。增量前缀处理会跳过分块哈希、页面哈希以及提供方／模型配置文件仍匹配的记录。没有该配置文件的旧记录会在显式构建时重新生成。完整扫描会移除已删除页面对应的多余记录；前缀处理器会在更改分块集合之前使 BM25 索引失效，避免提供混有过期数据的索引。 前缀和 BM25 构建操作与所有其他写入操作共用知识库级变更锁；知识库正忙时，操作会安全失败，不会发布不完整的索引。

上下文前缀隐私

合成前缀仅使用本地 frontmatter 和页面文本。显式的 Anthropic API 配置可能会将页面正文发送到本机之外，并且需要用户同意、--allow-egress 以及已配置的 API 密钥。没有 Claude CLI 生成层，也没有隐式的子进程回退机制。切勿根据 API 密钥或已安装的二进制文件推断用户已同意。先预览涉及的数据范围，并说明将向哪个提供方发送哪些数据。

远程 Ollama 端点也需要明确批准和 --allow-remote-ollama；默认的重排器仅接受 localhost。

本地模型前缀是另一项需要显式启用的选项。使用已安装的精确 name:tag；不会启动服务器，也不会安装或拉取模型：

python3 "$PREFIX" --vault "$VAULT" --all --local-ollama --ollama-model installed:tag --peek
python3 "$PREFIX" --vault "$VAULT" --all --local-ollama --ollama-model installed:tag

前缀适配器会在发送页面文本前，验证服务器已禁用云功能，并核验本地模型身份。若预检不受支持或不可用，则仅为新增或已更改的分块回退到合成前缀；同一端点和模型生成的前缀会保留，因此短暂的服务中断不会更改未变更知识库的分块和 BM25 索引。这项要求可能会排除较旧的 Ollama 服务器。 重排和切片会在查询、页面、分块或嵌入缓存操作之前，执行相同的仅限本地验证。--allow-remote-ollama 批准的是端点，而非允许服务器委托给云端。 有关确切策略、云模型选择和验证限制，请参阅前缀提供方。重排器有其独立的模型和端点策略；选择本地前缀不会启用重排。

查询

对于严格只读的查询，请使用预构建的 BM25 索引：

python3 "$RETRIEVE" --vault "$VAULT" "$QUERY" --top 5 --no-rerank --explain

如果明确要求重排，请省略 --no-rerank。默认使用 Ollama 的多语言模型 nomic-embed-text-v2-moe（约 958 MB）；该产品绝不会自动拉取此模型。如需使用已安装的体积更小、面向英语的 v1.5 模型，请显式传入 --model nomic-embed-text。Nomic 模型使用 search_query: 作为查询前缀，使用 search_document: 作为候选文本前缀。Nomic v2 的输入上下文为 512 个 token，Ollama 默认会截断较长的嵌入输入；BM25 仍会对完整分块评分。嵌入缓存依据精确模型、已验证的摘要、输入方案和精确前缀输入的哈希进行区分。本地 Ollama 服务缺失、HTTP 回复格式错误、所选模型缺失、向量不可用，或任何候选项嵌入失败时，都会对完整结果集回退到原始 BM25 顺序；绝不会混用余弦相似度和 BM25 的分数尺度。

查询输入限制为 8,000 个规范化字符，结果数量必须介于 1 和 1,000 之间。查询超长或限制无效时，会返回可操作的用法错误，而不会表现为搜索成功但结果为空。未指定标签的模型请求只会匹配已安装的无标签名称或其 :latest 别名；其他标签必须显式指定。

需要时请使用直接诊断：

python3 "$BM25" --vault "$VAULT" stats
python3 "$BM25" --vault "$VAULT" query "$QUERY" --top 10
python3 "$RERANK" --vault "$VAULT" "$QUERY" --peek
python3 "$RERANK" --vault "$VAULT" "$QUERY" --model nomic-embed-text --peek

完整性规则

  • 仅接受相对分块路径和页面路径，且解析后的目标分别必须位于 $VAULT/.vault-meta/chunks/ 和 $VAULT/wiki/ 下。
  • 拒绝缺少哈希的旧版分块记录；在构建或提供缓存记录之前，要求分块正文、页面和索引的哈希均匹配。
  • 拒绝绝对路径、符号链接越界、页面缺失、分块 ID 不匹配、页面哈希已更改，以及过时的索引／分块哈希对。
  • 对完整候选集进行重排，然后按页面去重，最后应用 --top。
  • 空索引表示确实没有结果。索引缺失或损坏时，retrieve.py 会以退出码 10 退出，并提供稳定的重建命令；调用方会回退到标准的知识库查询／文本搜索路径，不会捏造匹配结果。
  • 除非可复现的特定知识库基准测试得出了相关数据，否则不要引用基准测试百分比。

使用 bench --queries FILE --vault VAULT，根据明确标注评估预构建索引。有关召回率、MRR、缺失标签和负例，请参阅离线检索评估。此测量过程为只读，不会静默重建索引，也不会调用模型。

检查点

留意缓存就绪状态和隐私边界，判断是否需要词法或语义排序，验证返回路径和来源的新鲜度，并通过衡量维护中的本地查询集所揭示的检索遗漏来逐步改进。

评论

支持 Markdown