# Wiki Hybrid Search

> 知识库混合检索（向量 + jieba 关键词 RRF 融合）。触发词：「搜索知识库」「查一下wiki」「混合检索」「RRF」「语义搜索」「知识库搜索」「找一下」「搜一下知识库」。当用户想搜索知识库内容、查找相关页面、或提到语义搜索/混合检索/RRF 时触发。

- **Type:** Skill
- **Install:** `agentstack add skill-montewaltrip188-hash-claudecode-wiki-skills-wiki-hybrid-search`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [montewaltrip188-hash](https://agentstack.voostack.com/s/montewaltrip188-hash)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [montewaltrip188-hash](https://github.com/montewaltrip188-hash)
- **Source:** https://github.com/montewaltrip188-hash/claudecode-wiki-skills/tree/main/core/wiki-hybrid-search

## Install

```sh
agentstack add skill-montewaltrip188-hash-claudecode-wiki-skills-wiki-hybrid-search
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 知识库混合检索

向量通道（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 文件更新后运行：

```text
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: 搜索

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

输出格式：

```text
查询: 查询词
向量通道: 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: 去重检查（可选）

```text
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`

### 向量维度不匹配

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

```text
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](https://github.com/montewaltrip188-hash)
- **Source:** [montewaltrip188-hash/claudecode-wiki-skills](https://github.com/montewaltrip188-hash/claudecode-wiki-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-montewaltrip188-hash-claudecode-wiki-skills-wiki-hybrid-search
- Seller: https://agentstack.voostack.com/s/montewaltrip188-hash
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.