{"repo": "agents365-ai/zotero-rag-cli", "files": {"README.md": {"0ce989bbbef94dcc96e55b3057460f0494338665": {"t": 1785674237.569848, "n": 10844, "h": "0f471fc371ea5f99", "c": "# rak — Zotero 文献库 RAG 语义检索\n\n[English](README_EN.md)\n\n`rak` 是基于 RAG 的 Zotero 语义检索工具。通过本地嵌入模型将论文向量化，支持语义搜索和混合检索，返回最相关的论文及匹配片段。\n\n## 核心理念\n\n**rak 只做一件事：语义检索。** 找到最相关的论文和匹配的文本片段，交给调用方（Claude Code / LM Studio / 人）决定下一步。\n\n```mermaid\ngraph LR\n    A[用户查询] --> B[rak 语义检索]\n    B --> C[论文元数据 + 匹配片段]\n    C --> D1[Claude Code<br/>直接分析总结]\n    C --> D2[LM Studio<br/>MCP 工具调用]\n    C --> D3[终端用户<br/>ask / chat 问答]\n```\n\n## 三种检索模式\n\nrak 提供三种检索模式，适用于不同场景：\n\n```mermaid\ngraph LR\n    Q[用户查询] --> E[Embedder 嵌入]\n    E --> VS[向量搜索<br/>理解语义]\n    VS --> R1[结果]\n```\n\n> **向量搜索**（默认）：将查询转化为向量，在 ChromaDB 中找语义最相似的论文。能理解同义词和跨语言表达，如 \"细胞命运决定\" 匹配 \"cell fate determination\"。\n\n```mermaid\ngraph LR\n    Q[用户查询] --> BM[BM25 搜索<br/>关键词匹配]\n    BM --> R2[结果]\n```\n\n> **BM25 关键词搜索**：在索引的全文内容（标题 + 摘要 + PDF 全文）中做关键词匹配和排序。根据词频和文档长度计算相关性 — 确保包含精确关键词（如 \"CRISPR-Cas9\"）的论文不被遗漏。\n\n```mermaid\ngraph LR\n    Q[用户查询] --> VS[向量搜索]\n    Q --> BM[BM25 搜索]\n    VS --> RRF[RRF 融合排序]\n    BM --> RRF\n    RRF --> R3[最终结果]\n```\n\n> **混合搜索**（`--hybrid`）：向量 + BM25 两路检索，通过 RRF（Reciprocal Rank Fusion）融合排序。兼顾语义理解和精确关键词，效果最好。\n\n| 模式 | 命令 | 优势 | 适用场景 |\n|------|------|------|----------|\n| **向量搜索** | `rak search \"query\"` | 理解语义和同义词 | 探索性查询 |\n| **BM25 搜索** | 混合搜索的内部组件 | 精确关键词，搜 PDF 全文 | — |\n| **混合搜索** | `rak search \"query\" --hybrid` | 语义 + 关键词，最准 | 推荐默认使用 |\n\n## 三种使用方式\n\n```mermaid\ngraph LR\n    S1[rak search] --> S2[返回论文标题 + 匹配片段] --> S3[Claude Code / 脚本解析]\n```\n\n```mermaid\ngraph LR\n    A1[rak ask] --> A2[检索论文] --> A3[LLM 生成回答]\n```\n\n```mermaid\ngraph LR\n    C1[rak chat] --> C2[检索论文] --> C3[多轮对话 + 上下文记忆]\n```\n\n| 模式 | 命令 | 给谁用 | 需要 LLM？ |\n|------|------|--------|:---:|\n| **搜索** | `rak search` | AI 助手 / 脚本 | 不需要 |\n| **问答** | `rak ask` | 人（终端快速提问） | 需要 |\n| **对话** | `rak chat` | 人（深入讨论） | 需要 |\n\n## 安装\n\n```bash\n# 推荐\nuv tool install zotero-rag-cli\n\n# 或者\npip install zotero-rag-cli\n\n# 如需 MCP Server（LM Studio / Cursor）\npip install zotero-rag-cli[mcp]\n```\n\n前置依赖：[`zot`](https://github.com/Agents365-ai/zotero-cli-cc)（Zotero CLI，用于获取文献数据）。\n\n## 快速开始\n\n```bash\n# 1. 索引（增量，自动提取 PDF 全文并分块）\nrak index\n\n# 2. 语义搜索\nrak search \"cell fate determination\"\n\n# 3. 混合搜索（语义 + BM25 关键词）\nrak search \"spatial transcriptomics\" --hybrid\n\n# 4. 终端问答（需要 LLM）\nrak ask \"单细胞聚类的主要方法有哪些？\"\n\n# 5. 查找相似论文（支持 key 或标题模糊匹配）\nrak similar ABC12345\nrak similar \"attention is all you need\"\n\n# 6. 多轮对话（需要 LLM）\nrak chat\n```\n\n## 数据流\n\n```mermaid\ngraph TD\n    Z[zot CLI] -->|\"zot --json list\"| I[rak index]\n    P[PDF 全文] --> I\n    I -->|嵌入 + 分块| V[(ChromaDB<br/>向量存储)]\n    I -->|全文| F[(SQLite FTS5<br/>关键词索引)]\n\n    Q[用户查询] --> E[Embedder]\n    E --> VS[向量搜索]\n    Q --> BS[BM25 搜索]\n    V --> VS\n    F --> BS\n    VS --> RRF[RRF 融合排序]\n    BS -->|\"--hybrid\"| RRF\n    RRF --> R[检索结果<br/>元数据 + 匹配片段]\n\n    R --> OUT1[CLI 输出 / JSON]\n    R --> OUT2[LLM 问答<br/>ask / chat]\n    R --> OUT3[MCP Server<br/>LM Studio 等]\n```\n\n## 命令详解\n\n### 索引\n\n```bash\nrak index                    # 增量索引（仅新增/变更）\nrak index --full             # 全量重建\nrak index --limit 500        # 限制项目数\n```\n\n自动从 `~/Zotero/storage/` 提取 PDF 和 Markdown 附件全文，长文档分割为重叠片段（512 词，64 词重叠）。\n\n### 嵌入模型\n\n默认使用 `all-MiniLM-L6-v2`，支持所有 [sentence-transformers](https://huggingface.co/models?library=sentence-transformers) 模型。切换模型后需重建索引：\n\n```bash\nrak config model_name BAAI/bge-m3\nrak clear --yes && rak index\n```\n\n常用模型推荐：\n\n| 模型 | 维度 | 大小 | 适用场景 |\n|------|------|------|----------|\n| `all-MiniLM-L6-v2` (默认) | 384 | 80MB | 英文论文，速度快 |\n| `all-mpnet-base-v2` | 768 | 420MB | 英文最佳质量 |\n| `BAAI/bge-small-en-v1.5` | 384 | 130MB | 英文，性价比高 |\n| `BAAI/bge-small-zh-v1.5` | 512 | 95MB | 中文论文优化 |\n| `BAAI/bge-m3` | 1024 | 2.2GB | 多语言，最强但较慢 |\n| `intfloat/multilingual-e5-small` | 384 | 470MB | 多语言轻量 |\n| `jinaai/jina-embeddings-v3` | 1024 | 2.3GB | 多语言，长文本支持（8192 tokens） |\n\n### API 嵌入模型\n\n也支持通过 API 使用远程嵌入模型（兼容 OpenAI `/v1/embeddings` 格式）：\n\n```bash\n# OpenAI\nrak config embedding_provider api\nrak config embedding_base_url https://api.openai.com/v1\nrak config embedding_api_key sk-your-key\nrak config model_name text-embedding-3-small\nrak clear --yes && rak index\n\n# 通义千问 (Qwen)\nrak config embedding_provider api\nrak config embedding_base_url https://dashscope.aliyuncs.com/compatible-mode/v1\nrak config embedding_api_key sk-your-key\nrak config model_name text-embedding-v3\nrak clear --yes && rak index\n\n# 本地 Ollama\nrak config embedding_provider api\nrak config embedding_base_url http://localhost:11434/v1\nrak config embedding_api_key not-needed\nrak config model_name nomic-embed-text\nrak clear --yes && rak index\n\n# 切回本地模型\nrak config embedding_provider local\nrak config model_name all-MiniLM-L6-v2\nrak clear --yes && rak index\n```\n\n### 搜索\n\n```bash\nrak search \"单细胞 RNA 测序方法\"\nrak search \"CRISPR off-target\" --hybrid\nrak search \"attention\" --limit 5\nrak search \"RNA-seq\" --collection \"My Papers\" --tag \"methods\"\nrak --json search \"spatial omics\"       # JSON 输出（含匹配片段）\n```\n\n`--json` 输出示例：\n\n```json\n[\n  {\n    \"key\": \"ABC123\",\n    \"title\": \"Attention Is All You Need\",\n    \"score\": 0.89,\n    \"source\": \"vector\",\n    \"snippet\": \"We propose a new simple network architecture...\"\n  }\n]\n```\n\n### 问答\n\n```bash\nrak ask \"关于细胞命运的主要发现是什么？\"\nrak ask \"比较 CRISPR 方法\" --context 10 --hybrid\n```\n\n### 对话\n\n```bash\nrak chat                                # 启动交互会话\nrak chat --hybrid --context 10          # 混合搜索 + 更多上下文\nrak chat --collection \"My Papers\"       # 限定 collection\n```\n\n对话内置命令：`/search <查询>` · `/context` · `/tokens` · `/help` · `/quit`\n\n### 导出\n\n```bash\nrak export \"single cell\" --format csv\nrak export \"CRISPR\" --format bibtex --output refs.bib\n```\n\n### 配置\n\n```bash\nrak config                              # 显示所有设置\nrak config llm_model deepseek-chat      # 设置 LLM 模型\nrak config llm_base_url https://api.deepseek.com\nrak config llm_api_key sk-xxx           # 设置 API Key\n```\n\n<details>\n<summary>LLM 配置示例</summary>\n\n```bash\n# DeepSeek（推荐云端）\nrak config llm_base_url https://api.deepseek.com\nrak config llm_model deepseek-chat\nrak config llm_api_key sk-your-key\n\n# OpenAI\nrak config llm_base_url https://api.openai.com/v1\nrak config llm_model gpt-4o\nrak config llm_api_key sk-your-key\n\n# 本地 Ollama（默认）\nrak config llm_base_url http://localhost:11434/v1\nrak config llm_model llama3\nrak config llm_api_key not-needed\n```\n\n</details>\n\n### 其他\n\n```bash\nrak status                  # 索引状态\nrak clear --yes             # 清除所有索引\nrak completion zsh           # Shell 补全\neval \"$(rak completion)\"    # 启用补全\n```\n\n## 在 Claude Code 中使用\n\n```mermaid\nsequenceDiagram\n    participant U as 用户\n    participant C as Claude Code\n    participant R as rak\n    participant Z as zot\n\n    U->>C: 帮我找 attention 相关的论文并总结\n    C->>R: rak --json search \"attention\"\n    R-->>C: [{key, title, score, snippet}, ...]\n    C->>C: 基于 snippet 直接总结\n    C-->>U: 总结结果 + 论文列表\n\n    U->>C: 我想看第一篇的详情\n    C->>Z: zot read ABC123\n    Z-->>C: 完整元数据 + 摘要\n    C-->>U: 论文详情\n```\n\nClaude Code 自身就是大模型，不需要 `rak ask` — 直接用 `rak search` 获取片段后自己分析。\n\n建议在 `~/.claude/CLAUDE.md` 中添加：\n\n```markdown\n### Zotero\n- 语义搜索用 `rak --json search`，精确搜索/CRUD 用 `zot`\n- `rak` 返回匹配片段（snippet），可直接分析，无需读全文\n```\n\n## MCP Server\n\n供 LM Studio / Cursor / Claude Desktop 等支持 MCP 的工具使用。\n\n```bash\npip install zotero-rag-cli[mcp]\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"rak\": {\n      \"command\": \"rak-mcp\"\n    }\n  }\n}\n```\n\n| 工具 | 功能 |\n|------|------|\n| `search_papers` | 语义/混合搜索，返回论文元数据 + 匹配片段 |\n| `search_papers_bm25` | 纯关键词搜索，无需加载嵌入模型 |\n| `similar_papers` | 根据 Zotero key 或标题查找相似论文 |\n| `ask_papers` | 基于论文上下文的 LLM 问答 |\n| `export_papers` | 导出搜索结果为 CSV 或 BibTeX |\n| `show_config` | 查看当前配置 |\n| `index_status` | 查看索引状态 |\n\n## 搭配 zot 使用\n\n```mermaid\ngraph LR\n    subgraph \"zot — CRUD\"\n        Z1[精确搜索]\n        Z2[阅读论文]\n        Z3[笔记 / 标签]\n        Z4[添加 / 删除]\n    end\n\n    subgraph \"rak — RAG 检索\"\n        R1[语义搜索]\n        R2[混合搜索]\n        R3[问答 / 对话]\n    end\n\n    Z1 -.->|\"互补\"| R1\n```\n\n| 工具 | 职责 | 适用场景 |\n|------|------|----------|\n| `zot` | Zotero CRUD（搜索、阅读、笔记、标签、导出） | 明确知道要找什么 |\n| `rak` | RAG 语义检索 + 问答 | 探索性搜索、AI 辅助分析 |\n\n## 选项速查\n\n| 选项 | 适用命令 | 说明 |\n|------|----------|------|\n| `--json` | 全局 | JSON 输出（含 snippet） |\n| `--hybrid` | search, ask, chat, export | 混合搜索 |\n| `--limit N` | search, similar, export | 结果数量 |\n| `--collection` | search, ask, chat, export | 按 collection 过滤 |\n| `--tag` | search, ask, chat, export | 按标签过滤（可重复，OR 逻辑） |\n| `--full` | index | 全量重建 |\n| `--context N` | ask, chat | 上下文论文数 |\n| `--llm-model` | ask, chat | LLM 模型 |\n| `--llm-url` | ask, chat | LLM 服务地址 |\n| `--format` | export | csv / bibtex |\n| `--output` | export | 输出文件 |\n\n## 同类工具对比\n\n| 特性 | **rak** | [zotero-mcp](https://github.com/54yyyu/zotero-mcp) | [cookjohn/zotero-mcp](https://github.com/cookjohn/zotero-mcp) | [ZoteroBridge](https://github.com/Combjellyshen/ZoteroBridge) |\n|---|:---:|:---:|:---:|:---:|\n| 语义搜索 | **✅** | ✅ | ✅ | ❌ |\n| 混合搜索（向量 + BM25） | **✅** | ❌ | ❌ | ❌ |\n| PDF 分块索引 | **✅** | ❌ | ❌ | ❌ |\n| 匹配片段返回 | **✅** | ❌ | ❌ | ❌ |\n| LLM 问答 | **✅** 本地/云端 | 云 API | 云 API | 云 API |\n| 多轮对话 | **✅** | ❌ | ❌ | ❌ |\n| 100% 本地可用 | **✅** | ❌ | ❌ | ❌ |\n| CLI 终端 | **✅** | ❌ | ❌ | ❌ |\n| MCP 协议 | **✅** | ✅ | ✅ | ✅ |\n| 增量索引 | **✅** | N/A | N/A | N/A |\n\n### 为什么选择 rak？\n\n> **唯一同时提供 CLI + MCP、本地语义检索 + 片段返回的 Zotero RAG 工具。**\n\n- **精准**：PDF 分块 + 混合搜索 + 返回匹配片段，而非整篇论文\n- **本地化**：嵌入、搜索全在本机，搜索模式无需 API Key\n- **灵活**：CLI 给终端和 Claude Code，MCP 给 LM Studio 和 Cursor\n- **隐私**：论文数据永不离开本机\n\n## TODO\n\n- [x] BM25 索引添加 `doc_id` 唯一性约束，防止重复插入导致评分膨胀\n- [x] 重命名 `get_by_metadata` → `get_ids_by_metadata`，明确接口语义\n- [x] 添加 `--verbose` 全局选项，启用 debug 级别日志输出便于排查问题\n- [x] `rak search --bm25` 纯关键词搜索模式，无需加载嵌入模型\n- [x] 索引进度条（Rich progress 替代 `Indexed 50/3038...`）\n- [x] MinerU / Docling PDF 解析支持：`rak config pdf_provider mineru` 或 `docling` 启用高质量 PDF 提取（表格/公式/排版保留），失败自动回退 PyMuPDF\n- [x] `rak similar KEY` 查找与指定论文相似的论文\n- [x] 智能分块：按段落/章节切分替代固定 512 词窗口\n- [x] 提升测试覆盖率：整体 67% → 79%，CLI 50% → 69%，新增 72 个测试\n- [x] 异步 PDF 提取：ThreadPoolExecutor 并行化索引中最慢的环节\n- [x] GitHub Actions CI：自动化测试 + tag 触发 PyPI 发布\n- [x] README 更新：文档化 MCP 工具及 v0.6.1 改进\n\n### 高级功能（未来考虑）\n\n> 超出核心语义搜索范围，待搜索基础稳固后评估。\n\n- [ ] `rak notes`：AI 生成论文摘要 — 从 ChromaDB 提取分块发送至 LLM，生成结构化总结（研究问题/方法/结论），缓存为 `~/Zotero/rak/notes/KEY.md`\n- [ ] `rak cluster`：基于嵌入向量相似度自动聚类论文（HDBSCAN）— 发现研究主题、识别空白、组织文献综述，TF-IDF 主题标签 + 可选 LLM 命名\n- [ ] Web UI：Streamlit 可视化搜索面板\n- [ ] 文档站搭建：MkDocs Material + GitHub Pages\n\n## 相关项目\n\n- **[zotero-cli-cc](https://github.com/Agents365-ai/zotero-cli-cc)** — Zotero CLI CRUD 工具（`rak` 的前置依赖）\n\n---\n\n## 支持作者\n\n<table>\n  <tr>\n    <td align=\"center\">\n      <img src=\"https://raw.githubusercontent.com/Agents365-ai/images_payment/main/qrcode/wechat-pay.png\" width=\"180\" alt=\"微信支付\">\n      <br>\n      <b>微信支付</b>\n    </td>\n    <td align=\"center\">\n      <img src=\"https://raw.githubusercontent.com/Agents365-ai/images_payment/main/qrcode/alipay.png\" width=\"180\" alt=\"支付宝\">\n      <br>\n      <b>支付宝</b>\n    </td>\n    <td align=\"center\">\n      <img src=\"https://raw.githubusercontent.com/Agents365-ai/images_payment/main/qrcode/buymeacoffee.png\" width=\"180\" alt=\"Buy Me a Coffee\">\n      <br>\n      <b>Buy Me a Coffee</b>\n    </td>\n  </tr>\n</table>\n\n## 许可证\n\nMIT\n"}}}}