用途：zotero-rag 是在本地 Markdown 论文库（library/markdown/）上进行语义搜索的工具，基于句向量嵌入与 ChromaDB 向量库，让使用者按“意思”而不是精确关键词查找文献段落。
主要能力：
- 索引：从 library/markdown/ 构建或更新向量索引，支持增量索引（跳过未改动文件），也可用 --keys 指定引用键；索引存放在 library/.rag-index/，首次运行会下载 all-MiniLM-L6-v2 嵌入模型（约 80MB，由 sentence-transformers 缓存）。
- 搜索：按语义检索所有已索引文档，结果以 JSON lines 按相似度排序，可设置 --top-k 和 --min-score；每条结果含 chunk_id、citation_key、section_title、score、截断文本，以及来自 references.bib 的 title、author、year。
- 相似段落：用 similar <chunk_id> 查找与某段落相似的跨论文内容，用于发现主题关联。
- 上下文：用 context <chunk_id> 显示目标段落及同文档相邻段落，默认两侧各 2 个，可用 --window 调整。
- 状态与列表：status 显示文档数、段落数和最后修改时间；list 列出所有已索引文档及段落数。
- 移除：remove <citation_key> 从索引中删除某文档。
使用方式：命令统一为 uv run "$SKILL_DIR"/scripts/rag.py <子命令>。前置条件包括已安装 uv、论文已经过 ingest.py 处理（转换为 Markdown、整理文件并在 references.bib 中补充元数据），以及 references.bib 中带有 md_path 字段把引用键链接到 Markdown 文件。仅 references.bib 中登记的文件会被索引，未登记的散落 Markdown 文件在索引时会被标记为“unlinked”，需运行 ingest.py 注册。依赖 sentence-transformers、chromadb 由 uv 在首次运行时依据 PEP 723 内联元数据自动安装，无需手动安装。典型流程：先 ingest.py 导入论文，再运行 rag.py index，然后用 search 检索；新增论文后先 ingest 再更新索引；对已在 references.bib 中的论文补 PDF 时，用 ingest.py --file paper.pdf --citekey ExistingKey2022 --update，再更新索引。
适用场景：概念性或探索性的语义检索（即使原文未出现精确用词也能找到相关段落），以及通过 similar 和 context 做跨论文主题探索；与 grep 互补——精确关键词、作者名、方法名用 grep 检索 library/markdown/，作者、年份、期刊等元数据用 grep 检索 references.bib。
限制：只索引 references.bib 中登记的文件；分块按 ## 标题切分，无标题的文档回退到约 512 token 的固定分块；检索结果为截断文本，完整阅读需打开结果中的 source_file 路径。除上述内容外，其他功能与收费信息暂未提供。