文献库检索 yanglin7723/zotero-library

zotero-library

让你的 AI 智能体（DSH / Claude Code / Codex 等）直接读懂你的 Zotero 文献库：元数据搜索、PDF 全文检索、笔记与高亮、按页取正文、一键生成 APA 7 / GB/T 7714 / BibTeX 引用。

零依赖、只读、离线可用。不需要 Zotero 客户端开着，不需要 API key，不需要 zot / rak。

它解决什么问题

Zotero 里的 1000 篇文献，对 AI 来说原本是一堆不可见的 PDF。装了本技能之后，你只要说：

「我库里关于培养阴性 PJI 的文献有哪些？」
「这篇里我做过哪些标注？」
「把这几篇按 GB/T 7714 生成参考文献。」
「帮我找找我笔记里提过 IL-10 的地方。」

智能体就能直接检索、读取、引用你的真实文献库，而不是靠幻觉编造。

| 能力 | 命令 |
| 元数据搜索（标题/作者/摘要/期刊/标签/DOI/年份） | zotlib search |
| PDF 正文全文检索（返回页码 + 命中片段） | zotlib fulltext |
| 条目详情 + 你自己的笔记与 PDF 高亮/批注 | zotlib read |
| 按页提取 PDF 正文 | zotlib text --pages 1-3 |
| 引用：APA 7 / GB-T-7714 / BibTeX / RIS / CSL-JSON | zotlib cite / zotlib export |
| 分类、标签、最近添加、关联文献、统计 | zotlib collections / tags / recent / related / stats |

与 zotero-cli（zot + rak）的区别

| | 本技能 | zot/rak 方案 |
| 依赖 | 无（只要 Node ≥ 22.5） | 需另装 zot、rak，rak 还要下载嵌入模型建索引 |
| Zotero 运行时 | ✅ 自动读数据库快照 | 部分命令受锁影响；新版 Zotero 表结构变化可能报错 |
| 全文检索 | ✅ 用 Zotero 自带全文索引，带页码 | 依赖自建索引 |
| 笔记/标注/引用 | ✅ 内置 | 部分支持 |
| 语义搜索 | ❌（关键词 + 全文） | ✅ rak 向量检索 |

两者可以共存：日常查询用本技能（快、稳、零配置），需要语义相似度时再用 rak。

一键安装

从 GitHub 安装（推荐，任选其一）

方式 1：agent skill 管理器（一条命令装进 ~/.agents/skills）
npx skills add yanglin7723/zotero-library -g

方式 2：clone 后跑安装器（会探测数据目录、创建 zotlib 命令、自检）
git clone https://github.com/yanglin7723/zotero-library.git
cd zotero-library
powershell -ExecutionPolicy Bypass -File .\install.ps1 # Windows
./install.sh # macOS / Linux

安装器会做四件事：

1. 检查 Node ≥ 22.5；
2. 自动探测你的 Zotero 数据目录（读 Zotero 首选项 prefs.js，支持自定义数据目录如 D:\Zotero）；
3. 把技能复制到 ~/.agents/skills/zotero-library/（DSH / Claude Code 的技能目录）；
4. 在技能目录下创建 bin/zotlib 命令、加入 PATH，并跑一遍自检。

装完新开一个会话，对智能体说「用 zotero-library 技能查一下我的文献库」即可。

常用参数：

.\install.ps1 -DataDir "D:\Zotero" # 手动指定 Zotero 数据目录 .\install.ps1 -SkipPathUpdate # 不自动把技能 bin 目录加进 PATH .\install.ps1 -NoShim # 不创建 zotlib 命令

卸载

.\uninstall.ps1 # 移除技能与 zotlib 命令 .\uninstall.ps1 -PurgeConfig # 同时清掉 ~/.zotero-library 下的配置与缓存

手动安装（无安装器）

1. 复制到技能目录
mkdir -p ~/.agents/skills/zotero-library
cp -r SKILL.md scripts references package.json ~/.agents/skills/zotero-library/

2. 试运行（自动探测 Zotero 数据目录）
node ~/.agents/skills/zotero-library/scripts/zotero.mjs doctor

3. 指定数据目录（自动探测失败时）
node ~/.agents/skills/zotero-library/scripts/zotero.mjs config set-data-dir "D:\Zotero"

使用示例

zotlib doctor # 环境自检 zotlib stats # 库统计 zotlib search "periprosthetic joint infection" --limit 5 zotlib fulltext "biofilm formation" --limit 3 # 正文命中 + 页码 zotlib read P667P3EP # 含笔记与高亮 zotlib text P667P3EP --pages 1-2 zotlib cite P667P3EP --style gb7714 zotlib export --collection "06 课题-培养阴性PJI（凝血-炎症）" --style bibtex zotlib recent --days 7

输出默认 JSON（适合智能体），人读加 --format text：

zotlib search "PJI" --format text

数据目录优先级：--data-dir > 环境变量 ZOTERO_DATA_DIR > ~/.zotero-library/config.json > Zotero 首选项 > 常见路径。

工作原理

Agent ──▶ zotlib（Node，零依赖） │ ├─ 自动探测 Zotero 数据目录（prefs.js / 常见路径） ├─ 直接打开 zotero.sqlite（Zotero 已关闭时） ├─ Zotero 运行中 → 复制 db+wal 到缓存目录做快照再读（绕开排他锁） ├─ 元数据：items / itemData / creators / tags / collections ├─ PDF 全文：<storage>/<attachmentKey>/.zotero-ft-cache（Zotero 自己的全文索引） └─ 笔记与标注：itemNotes / itemAnnotations

- 快照按 (size, mtime) 校验，源数据没变就复用，命令耗时通常 0.2–0.6 秒。
- 只使用 SQLite 只读连接与只读文件访问。

安全与隐私

- 只读：没有写库代码路径，不会改动你的 Zotero 数据。
- 全本地：不发网络请求、不需要任何密钥；配置里只有数据目录路径。
- 不复制文献库：只有 Zotero 运行时的临时快照（~/.zotero-library/cache/，可随时删）。
- 需要联网的是你的智能体本身，与这个技能无关。

兼容性

| 项 | 要求 |
| Node.js | ≥ 22.5（使用内置 node:sqlite；推荐 24 LTS） |
| Zotero | 7 / 8 / 9 / 10 本地库（不需要 Zotero 客户端运行；需要本机已安装过并生成数据库） |
| 系统 | Windows / macOS / Linux |
| 依赖 | 无第三方 npm 包 |

已知限制

- 只读，不支持写标签/分类/笔记（请用 Zotero 客户端操作）。
- 语义搜索（“意思相近的论文”）不在范围内，需要时配合 rak。
- 没有 Zotero 全文索引的 PDF（新加入、未打开过）只能用 read 看元数据；text 会提示你去索引。
- 群组库（group library）条目可以读取，但命令暂未提供按 group 过滤。

开发与测试

node test/smoke.mjs # 单元测试 +（有本地库时）真实库集成测试
node scripts/zotero.mjs doctor --json

配套技能

- zotero-dsh（另一个方向，同为本地技能）：把 DSH 接进 Zotero —— 在 PDF 里选中文字直接问 AI、术语翻译走大模型。
两者互补：zotero-library 让 AI 读你的库，zotero-dsh 让你在 Zotero 里用 AI。

License

MIT