Wiki Hybrid Search

知识库混合检索

向量通道（Ollama + bge-m3）和关键词通道（jieba 分词 + 子串匹配）做 RRF 融合。向量通道用于语义相似，关键词通道用于字面召回。

外部依赖

这些依赖不是 Codex 自带能力，执行前必须按当前环境确认：

• Python 3：运行 wiki_search.py。
• Python 包（必装）：requests、jieba、numpy。
• Python 包（可选）：faiss-cpu — 向量索引加速，>1000 页时推荐安装。
• Python 包（可选）：sentence-transformers — 本地批量向量化，绕过 Ollama HTTP 开销。
• 向量后端（二选一）：
• Ollama（默认）：ollama pull bge-m3，通过 HTTP API 调用。
• 本地模型：pip install sentence-transformers，设置 EMBED_BACKEND=local，首次使用自动下载 BAAI/bge-m3。
• SQLite：使用 Python 标准库 sqlite3；命令行 sqlite3 只在手动清库时需要。

缺失处理：

• 缺 requests/jieba/numpy：pip install requests jieba numpy。
• 缺 faiss-cpu：自动回退到 numpy 暴力扫描，功能不受影响，大库会慢一些。
• 缺 sentence-transformers：只影响 EMBED_BACKEND=local 模式，默认 Ollama 模式不需要。
• 缺 Ollama / bge-m3：设 EMBED_BACKEND=local 改用本地模型；或只用关键词通道。
• 缺 Python：本 skill 的脚本无法运行，改用当前平台搜索工具临时查找。

路径

• 脚本：/scripts/wiki_search.py
• 数据库：${KB_ROOT}/.state.db 的 wiki_embeddings + wiki_keywords 表
• FAISS 索引（可选）：${KB_ROOT}/.wiki_faiss.index + .wiki_faiss_map.json
• 索引对象：${KB_ROOT}/wiki/ 下的 .md 文件，跳过 index.md
• 跨平台命令参考：[../../references/platform-commands.md](../../references/platform-commands.md)

执行流程

Step 1: 确认环境

确认：

1. KB_ROOT 已设置并指向知识库根目录。
2. Python 3 可运行。
3. requests、jieba、numpy 可导入。
4. 向量后端就绪：

• 默认（EMBED_BACKEND=ollama）：Ollama 在线且 ollama list 包含 bge-m3。
• 本地（EMBED_BACKEND=local）：sentence-transformers 可导入，首次运行自动下载模型。

macOS/Linux 与 Windows PowerShell 的检查命令见 [../../references/platform-commands.md](../../references/platform-commands.md)。

Step 2: 建立索引

首次使用或 wiki 文件更新后运行：

python /scripts/wiki_search.py index

• 按 content_hash 增量更新，未改动页面会跳过。
• 每页按段落切成约 500 字符 chunk，每个 chunk 一个向量。
• 输出类似：N 新增/更新, M 跳过, E 错误。

如果待处理页面超过 20 个或预计耗时超过 5 分钟，按当前平台选择后台运行命令，见 [../../references/platform-commands.md](../../references/platform-commands.md) 的“后台运行索引”。

Step 3: 搜索

python /scripts/wiki_search.py search "查询词"

输出格式：

查询: 查询词
向量通道: N 条 | 关键词通道: M 条 | 融合后: K 条
 1. [0.0483] wiki/concepts/RAG检索增强生成.md  (vec+kw)
 2. [0.0321] wiki/entities/claudecode-wiki-skills.md  (vec)

• vec：向量通道命中。
• kw：关键词通道命中。
• vec+kw：双通道命中，排序会被 boost。

向量通道失败时，脚本会警告并继续使用关键词通道。搜索脚本完全失败时，用当前平台的全文搜索命令临时检索：macOS/Linux 用 grep，Windows PowerShell 用 Select-String，具体命令见跨平台参考。

Step 4: 去重检查（可选）

python /scripts/wiki_search.py dedup

• sim > 0.85：高度重复，保留内容更丰富的版本，合并关联页面。
• sim > 0.65：相似度较高，人工判断是否合并。

与 design-shi-wiki 集成

• 入库后：调用 index 增量向量化新页面。
• 体检时：可选调用 dedup 检查重复页面。
• 回答知识库问题时：先 search 找相关页面，再读全文回答。

故障处理

向量通道返回空

结果仍可能来自关键词通道。需要恢复向量通道时：

1. 确认 Ollama 运行。
2. 运行 ollama list，确认包含 bge-m3。
3. 如缺失，运行 ollama pull bge-m3。
4. 重新 index。

关键词通道返回空

可能是查询词太短，jieba 分词后只剩单字。换更长的查询词。

ModuleNotFoundError

• requests 缺失：pip install requests
• jieba 缺失：pip install jieba

向量维度不匹配

原因通常是换了向量模型，旧向量和新向量维度不一致。清除旧向量后全量重建：

sqlite3 "/.state.db" "DELETE FROM wiki_embeddings"
python /scripts/wiki_search.py index

Windows PowerShell 中把 /.state.db 换成 $env:KB_ROOT\.state.db。

反模式

• 不要跳过 index 直接期待向量搜索有结果。
• 不要每次 search 都 index；只在文件变更后增量更新。
• 不要把 Ollama/bge-m3 当作 Codex 自带能力。
• 不要在缺少向量通道时放弃搜索；先用关键词通道或临时全文搜索。

向量索引加速（FAISS）

安装 faiss-cpu 后，index 命令会自动在 ${KB_ROOT}/ 下生成 .wiki_faiss.index 和 .wiki_faiss_map.json。search 优先使用 FAISS 索引（~1ms），未安装或索引不存在时自动回退到 numpy 暴力扫。

索引策略按数据量自动选择：

• < 1000 chunks：IndexFlatIP（精确，SIMD 加速）
• ≥ 1000 chunks：IndexIVFFlat（近似最近邻，聚类数 = √n）

本地向量化后端（sentence-transformers）

设置 EMBED_BACKEND=local 后，向量化使用 sentence-transformers 本地加载 BAAI/bge-m3，绕过 Ollama HTTP API。

优势：

• 批量编码：index 时按 batch_size=32 批量处理，比 Ollama 逐条 HTTP 快 10-20x
• 无需 Ollama 服务：适合 Ollama 未安装或不方便启动的环境
• GPU 加速：如有 CUDA，sentence-transformers 自动使用 GPU

注意：

• 首次使用自动从 HuggingFace 下载模型（~1.1GB），需要网络
• 模型常驻内存（~2GB），适合批量 index；单次 search 启动开销较大
• 两个后端生成的向量不完全一致（Ollama 和 sentence-transformers 的推理精度略有差异），切换后端后建议全量重建索引

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: montewaltrip188-hash
• Source: montewaltrip188-hash/claudecode-wiki-skills
• License: MIT

Install and usage instructions live in the source repository linked above.