内容
GeryonMCP
> 我的电脑上运行的**免费·离线·CPU**文档搜索MCP服务器。
> 将公司内部的Wiki（如Confluence）数据存储在本地数据库中，无需付费AI或互联网即可进行搜索。
名字的由来：希腊神话中多头巨人 **Geryon** —— 一个将多个数据源整合在一起的搜索引擎。
## 特点
- **免费 · 离线 · CPU专用 · 内存16GB以内** —— 无需付费/在线推理调用。模型只需下载一次，完全离线运行。
- **关键词（BM25）+ cross-encoder重排序（ONNX）** —— 不依赖向量，获得精确的搜索结果。支持**中文、英文等多语言**（音译、技术术语交叉语言匹配）。
- **按元字段详细搜索**（`advanced_search`）—— 将标题、作者、空间、标签、日期作为独立字段组合。
- **多源联邦搜索** —— Confluence、Jira、Git（GitHub/GitLab/Bitbucket，**包括源代码、提交记录**）作为**独立数据源进行搜索并重新排序**（数据源无关的排名）。新的数据源可以通过插件添加（无需修改搜索代码）。
- **增量索引** —— 通过`manifest.last_change`，**仅索引变更部分**（数据源通用，无需重新调用API）。
- **分层存储 + 字典** —— 原始数据保留（Bronze）→ 精炼数据库（Silver）→ 个性化字典（Gold）。手动字典始终适用（可选），从数据中提取同义词的**自动引导是可选的**（默认关闭）。
- **MCP服务器** —— 直接连接到MCP客户端（如Claude Desktop、VS Code等）。
## 工作原理
```
原始Wiki ─[采集]→ 本地文件(Bronze) ─[加载·精炼]→ 本地数据库(Silver)
│
查询 ─[搜索]→ 关键词候选(BM25, 中文正则化全文搜索)
→ cross-encoder重排序(ONNX·int8) ← 准确度的关键
→ 结果 (向量搜索作为辅助/备用)
```
关键词搜索快速缩小范围，**重排序模型将正确答案提升到前面**。所有操作都在本地CPU上，无需外部调用。
## 核心设计（基于测量）
所有设计和取舍都基于**实际测量**，而非猜测。
- **中文友好分词** —— FTS5分词器和语法正则化确保中文BM25准确度。
- **cross-encoder重排序** —— fastembed ONNX（无需torch）·int8量化，在CPU上实现亚秒级性能。避免向量搜索的繁重计算，使用关键词+重排序实现再平衡。
- **最佳段落结合** —— 标题和正文匹配段落一起评估（分数最大化结合），恢复标题与正文不匹配的文档。
- **元数据噪声正则化** —— 正则化作者状态后缀（如`(Deactivated)`）和分类噪声，确保筛选和显示的一致性。
- **许可证安全** —— 重排序模型采用MIT许可证（允许商业使用）。
## 准备工作
1. **Python 3.10 或以上** —— 验证：`python3 --version` （如果没有，请从[python.org](https://www/downloads/) 或操作系统包管理器安装）
2. **uv**（快速安装工具）—— 请选择以下方式之一：
- macOS/Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh`
- Windows（PowerShell）: `irm https://astral.sh/uv/install.ps1 | iex`
- 或通用方式：`pip install uv`
- 即使没有uv，也可以使用`pip`安装（参考Quickstart步骤1的注释）
> 如果是首次使用，**仅需完成2-3步（安装、bootstrap、demo）**，即可在无需凭证的情况下体验搜索功能。实际的Wiki连接从第4步（令牌）开始。
## 快速入门
```bash
# 1) 安装
uv tool install . # 或：pip install -e .
# 2) 引导 — 自动下载模型 + 生成示例配置文件(.env)
geryon bootstrap
# 3) 无凭证体验搜索（虚拟数据）
geryon demo
# 4) 实际数据 — 采集(acquire) → 索引(ingest)
# 在第2步生成的.env文件中，填写 CONFLUENCE_URL / USERNAME / API_TOKEN（或运行 `geryon init`）
geryon acquire # 外部数据 → Bronze原始文件（默认为最近一个月，等幂/增量）
# --since 2026-01-01 --until 2026-03-31 指定日期范围 / --all 全部数据
geryon ingest --source confluence --path ./bronze/confluence # Bronze → 搜索数据库
geryon serve # 启动MCP服务器
```
> 采集(`acquire`)和索引(`ingest`)分开的原因和详细选项（增量/全量，重建，数据路径指定）请参考 [docs/DATA_PIPELINE.md](docs/DATA_PIPELINE.md)。如果只需要更换搜索逻辑，可以重新运行`ingest`（无需重新调用API）。
> **无需额外配置即可开始**：除了上述步骤外，无需额外输入任何内容。**同义词字典（~/.geryon/gold/dictionary.yaml）是可选的** —— 没有它，搜索功能仍然正常，可以在以后添加。自动同义词字典**默认关闭**（在确认数据适合性后，可以通过设置`GERYON_DICT_AUTO=1`启用）。所有环境变量都有合理的默认值，因此可以直接使用，无需调整。
`geryon demo` 输出示例：
```
查询: '不停机部署流程' → 服务器部署指南，数据备份流程
查询: '休假申请' → 休假政策
```
## Atlassian API 令牌 발급（实际Wiki连接时需要）
第4步`acquire`（采集）需要使用令牌代替密码。
1. 在浏览器中访问 **https://id.atlassian.com/manage-profile/security/api-tokens**
2. 点击 **Create API token** → 输入名称（例如geryon）→ 生成令牌 **复制**（请立即复制，之后无法查看）
3. 打开`.env`文件并填写：
```
CONFLUENCE_URL=https://<公司域名>.atlassian.net/wiki
CONFLUENCE_USERNAME=<登录邮箱>
CONFLUENCE_API_TOKEN=<复制的令牌>
```
（如果`.env`不存在，`geryon bootstrap`会从`.env.sample`创建）
## MCP 客户端注册
要在AI客户端（如Claude Desktop、VS Code等）中使用搜索功能，请在配置文件中注册。
**Claude Desktop** — 打开配置文件（`Settings → Developer → Edit Config`），添加以下内容：
```json
{
"mcpServers": {
"geryon": { "command": "geryon", "args": ["serve"] }
}
}
```
保存并重启客户端后，搜索工具（如`search`）将显示出来。
## 工具
| 工具 | 说明 |
|---|---|
| `search` | 综合搜索（关键词 + 重排序，同义词·个性化） |
| `advanced_search` | 按元字段详细搜索（标题·作者·空间·标签·日期） |
| `get_document` | 文档全文查询 |
| `get_related` | 相关文档（基于链接） |
| `browse` | 空间/层级列表 |
| `list_sources` | 已索引的数据源/空间列表 |
| `reindex` | 触发重新索引 |
> 在终端中直接执行相同的搜索：`geryon search "<查询>"`（表格/ `--json`）—— 与MCP工具使用相同的核心。
## 配置
所有选项都可以通过`.env`（或环境变量）调整。所有选项的完整列表请参考存储库中的`.env.sample`。如果`.env`文件不存在，`geryon bootstrap`将**在当前目录中创建`.env`，并使用内置模板填充**，**不会覆盖现有值**。
主要选项：`GERYON_RERANK_PASSAGE`（强化正文搜索开启/关闭），`GERYON_RERANK_POOL`（候选数量），`GERYON_RERANK_QUANTIZE`（int8加速），`GERYON_RERANK_MODEL`，`GERYON_LOG_LEVEL`。
## 命令行界面（CLI）
| 命令 | 说明 |
|---|---|
| `geryon bootstrap` | 下载模型 + 生成配置文件示例 |
| `geryon init` | 在`.env`中设置凭证·采集数据源（Confluence空间·Jira项目·Git仓库）（交互式/带标志） |
| `geryon demo` | 使用虚拟数据体验搜索（无需凭证） |
| `geryon sync --all` | 采集·索引 |
| `geryon search "<查询>"` | 在终端中直接搜索（表格/ `--json`）。与MCP `search` 使用相同的核心 |
| `geryon serve` | 启动MCP服务器 |
| `geryon status` / `health` | 状态·健康检查 |
## 文档
- **[docs/USER_MANUAL.md](docs/USER_MANUAL.md) — 用户手册（安装到运行的逐步指南）**
- [docs/INSTALL_WALKTHROUGH.md](docs/INSTALL_WALKTHROUGH.md) — 从安装到连接MCP的验证步骤指南（最近一个月数据，多语言支持）
- [docs/AIRGAP_INSTALL.md](docs/AIRGAP_INSTALL.md) — 离线环境（无互联网）安装和运行指南（离线轮询和模型导入，已验证）
- [docs/GOLDEN_AND_DICTIONARY.md](docs/GOLDEN_AND_DICTIONARY.md) — 精确测试集和同义词字典编写技巧（调查类型·往返翻译·中英音译）
- [docs/TEAM_DEPLOY.md](docs/TEAM_DEPLOY.md) — 团队部署（将搜索MCP附加到项目上，按项目索引）
- [docs/EXTENDING_SOURCES.md](docs/EXTENDING_SOURCES.md) — 添加新的数据源（扩展到Jira·GitHub等多个数据源）
- [docs/BEGINNER_GUIDE.md](docs/BEGINNER_GUIDE.md) — 初学者指南（概念和代码地图）
- [docs/PERFORMANCE.md](docs/PERFORMANCE.md) — 搜索流程和性能调优（重排序·候选池大小·int8）
- [CHANGELOG.md](CHANGELOG.md) — 更新日志 · [CONTRIBUTING.md](CONTRIBUTING.md) — 贡献指南
## 故障排除
| 症状 | 原因 | 解决方法 |
|---|---|---|
| `command not found: geryon` | 安装路径未注册 | 重新运行 `uv tool install .`，或使用 `python -m geryon.cli ...` 运行 |
| `command not found: uv` | 未安装uv | 参考“准备工作”，或使用 `pip install -e .` |
| `bootstrap`耗时较长 | 首次运行（数） | 正常运行使用缓存，快（离线运行） |
| 搜索结果 尚未索引 | 运行 `geryon demo认功能 → 使用真实数据需运行 `gery --all` |
| `Confluence 凭证未找到` | `.env`未配置 | 参考“Atlassian API 令牌 발급`.env` |
|提示“无原始数据” | 索引前 | 正常。索引后该提示将消失 |
|不足 | 内存小于16GB | 保持YON_RERANK_QUANTIZE=1`），降低 `GERYON_RERANK_POOL` |
## 限制和理念
离线、16GB是基本原则。我们不通过增加复杂弥补弱点，而是直接解决问题，并基于测量做出所有## 许可证
[MIT](LICENSE)
