Zotero Skill for DeepSeek Harness

让 DeepSeek Harness 直接操作你本机的 Zotero 文献库：检索论文、导出 BibTeX、给 LaTeX / Markdown 草稿插入引用，按需读取附件全文。

纯 Python 标准库实现，不需要 pip、MCP 服务或 Zotero 云端 API Key；默认只与本机 127.0.0.1:23119 通信。

特性

• 检索：按关键词搜索顶层条目，返回题名、作者、年份、item key 与 BibTeX key。
• 浏览：列出集合、标签、分组，或导出整个文献库清单。
• 引用：读取你指定的 .tex / .md 草稿，在唯一标记处插入 \cite{key} 或 Pandoc [@key]，并同步 references.bib。
• 安全写入：修改草稿或 .bib 前自动备份；.bib 按 key 去重，不重复追加。
• 按需读取：只有你明确要求时才读取附件路径或 PDF 全文，避免把本地路径和正文无谓地送进上下文。
• 导入：通过 Zotero Connector 导入 BibTeX / RIS，属于写库操作，脚本会用 --yes 显式确认。
• 每日收录：按你设定的主题，每天从 OpenAlex 抓取新论文，按期刊影响力、引用速度、相关度和新鲜度排序，自动导入指定分类；数量、开关、时间都由你决定。
• 不碰数据库：只走 Zotero 官方本地 API，不直接读写 zotero.sqlite。

安装

1. 准备

• Python 3.10+（Windows 上用 py -3 或 python，macOS / Linux 用 python3）
• 桌面版 Zotero（开发时验证于 Zotero 10.0.6）
• DeepSeek Harness

2. 装进 Harness

两种方式，任选其一。

方式 A：作为 DSH 插件安装（推荐）

仓库自带 dsh.bundle 清单，装成插件后 skill 自动出现在技能目录，不需要复制文件：

dsh plugin --profile <你的 profile> add github:Eason-0712/dsh-zotero-skill

也可以从本地检出安装（开发调试用）：

dsh plugin --profile <你的 profile> add "link:/path/to/dsh-zotero-skill"

卸载：dsh plugin --profile <你的 profile> remove dsh-zotero-skill。

方式 B：作为独立 skill 目录安装

# 仓库根目录下执行
python install.py

安装器默认复制到 $DSH_HOME/skills/zotero（未设置时 ~/.dsh/skills/zotero），目标已存在时不会覆盖。也可以手动把整个 zotero/ 目录复制过去，最终结构必须是 skills/zotero/SKILL.md。

项目级（只在某个仓库生效）：

python install.py --skills-dir .dsh/skills

想装到别的盘或自定义目录，用 --skills-dir 指定，再让 Harness 扫描该目录即可。

3. 打开 Zotero 本地 API

Zotero → 设置 → 高级 → 其他 → 勾选「允许此计算机上的其他应用程序与 Zotero 通信」。

也可以让脚本改配置（先完全退出 Zotero）：

python zotero/scripts/zotero.py enable --restart

它会备份 prefs.js 后写入 extensions.zotero.httpServer.localAPI.enabled，再启动 Zotero；不会强杀进程。

4. 验证

python zotero/scripts/zotero.py status --json

api_running: true、api_status: 200 即连通。

使用示例

在 Harness 里直接说：

检索我文献库中 transformer 相关的论文，给出作者、年份和 BibTeX 键。

读一下 /path/to/draft.md，把相关论断后面补上引用，并更新同目录的 references.bib。

把这篇论文的附件全文读出来，总结方法部分。

Skill 会自己决定调用哪些子命令，并在写文件前确认标记和备份。

每日自动收录

每天早上自动把新论文收进 Zotero，数量、主题、开关都由你决定。

开启

# 设定主题与数量（最多 30 篇），并在 Zotero 里先选中一个目标分类
python zotero/scripts/zotero.py daily-config --enable \
  --topics "transformer;large language model" --max 10 --mailto "you@example.com"

# 先看候选，不写库
python zotero/scripts/zotero.py daily --dry-run

# 真正导入
python zotero/scripts/zotero.py daily

关闭：daily-config --disable。关闭状态下 daily 只返回提示，加 --force 可临时跑一次。

定时

# 每天 08:00 自动运行（Windows 任务计划程序）
python zotero/scripts/zotero.py daily-schedule --time 08:00

# 删除定时任务
python zotero/scripts/zotero.py daily-schedule --remove

任务只在该 Windows 用户登录时触发；Zotero 没开着时脚本会尝试启动它并等待接口就绪。

排序依据

候选论文先按主题从 OpenAlex（免费、无需 API Key）检索最近 N 天，再按加权分数排序：

维度	默认权重	含义
期刊影响力	0.45	期刊近两年平均被引（OpenAlex 2yr_mean_citedness）
引用速度	0.30	年化被引次数，避免老论文靠累计引用刷分
主题相关度	0.15	OpenAlex 搜索相关度
新鲜度	0.10	越新越高，7 天窗口内自然衰减

同一期刊默认最多 3 篇（--max-per-venue），避免一天全是同一个刊物。已导入过的 DOI 会记录在 ~/.zotero-skill/state.json，不会重复推送。

配置项

键	默认	说明
enabled	false	总开关
max_items	10	每次导入上限，最大 30
days_back	7	回溯天数，1–30
topics	[]	研究主题，分号分隔
max_per_venue	3	同一期刊上限
include_preprints	false	是否纳入预印本
min_venue_score	0	期刊 2 年被引下限，过滤水刊
weights	见上表	各维度权重
mailto	""	OpenAlex 礼貌池联系邮箱
schedule_time	08:00	定时任务时间

配置和状态都在 ~/.zotero-skill/，可用 ZOTERO_SKILL_CONFIG_DIR 改位置。注意：这里用的是 OpenAlex 的期刊被引指标，不是 JCR 影响因子；两者不等价，别把分数当 IF 用。

命令

命令	作用
status	检查本地 API、Connector、版本
inventory	列出条目
collections / tags / groups	列出集合、标签、分组
search <query>	关键词检索，--with-bibtex-keys 附带引用键
export-bibtex	导出 BibTeX（--item-key 单篇，--out 写文件）
sync-bib	导出整库到 references.bib
citations	按样式渲染引用文本（如 --style apa）
cite	在草稿标记处插入引用并同步 .bib
children / fulltext / file-url	附件、全文、文件路径
selected-target	查看 Connector 当前选中的库/集合
import-bibtex / import-ris	经 Connector 导入（需 --yes）
daily	按主题抓取并按分数导入新论文（--dry-run 预览）
daily-config	查看/修改每日收录配置
daily-schedule	创建/删除 Windows 每日定时任务
probe	探测各 API 路由可用性
enable / disable / restart	管理本地 API 开关与启动

所有命令加 --json 输出机器可读结果。

目录结构

.
├── package.json                     # dsh.bundle 清单，dsh plugin add 靠它识别
├── cordis.patch.yml                 # 插件挂载行
├── lib/index.js                     # 向 ctx.skills 注册内置 skill 的 provider
├── zotero/
│   ├── SKILL.md                     # skill 入口，Harness 读取它来发现技能
│   ├── references/
│   │   ├── deepseek-harness.md      # 安装、连接排查、环境变量
│   │   └── local-api-routes.md      # 本地 API 与 Connector 路由
│   └── scripts/zotero.py            # 全部功能，仅标准库
├── test/provider.test.mjs           # provider 的 Node 测试
├── tests/test_zotero.py             # 模拟 API 的 Python 单元测试
├── install.py                       # 复制式安装器（方式 B）
├── LICENSE
└── NOTICE.md

装成插件后，lib/index.js 在 apply() 里注册一个 rank 600 的 provider，直接读包内的 zotero/SKILL.md。相比复制到 ~/.dsh/skills，升级只需 dsh plugin 更新，也不会有两份副本不同步的问题。

设计取舍

• 只读本地 API：检索、导出、全文都走 /api/；该接口本身只读，写操作交给 Connector。
• 写文件前备份：cite 会先校验草稿和标记，再备份草稿与 .bib；sync-bib / export-bibtex --out 会覆盖目标文件，所以 Skill 要求先确认路径。
• 本机请求绕过代理：localhost、127.0.0.1、::1 直连，避免系统代理吞掉本机请求；非回环地址才走代理配置。
• UTF-8：Windows 控制台下的中文 JSON 与路径不会乱码。
• 不强制结束 Zotero：需要改配置时要求先正常退出，避免 prefs.js 被覆盖。

测试

python -m unittest discover -s tests -v   # Python 侧
node --test test/*.test.mjs               # 插件 provider

测试用临时文件和模拟 API，不读写真实文献库。GitHub Actions 会在 Ubuntu / Windows 与 Python 3.10 / 3.13 上跑 Python 测试，并在 Node 20 / 22 上跑 provider 测试。

已知限制

• Word 里的 Zotero 动态引用域不在能力范围内；脚本不会用替换文本的方式伪装成已插入引用。
• 远端 / WSL / 容器里 127.0.0.1 指向的是运行环境本身，不在同一台机器上时无法直接连到桌面 Zotero。
• enable / disable 只改本机 prefs.js，对远端 Zotero 无效。
• 本地 API 的能力随 Zotero 版本变化，遇到 403 / 404 先检查开关和版本。
• 每日收录依赖 OpenAlex 的网络访问；离线或被限流时会跳过本次抓取，不会写坏文献库。
• 收录只导入题录与摘要，不下载 PDF；需要全文时再按需获取。
• 期刊指标来自 OpenAlex，与 JCR 影响因子不是同一套数据，仅用于相对排序。
• 定时任务只在该 Windows 用户登录时运行；机器关机或睡眠时当次会跳过。

来源与许可

本项目改编自 OpenAI 的 Zotero 插件 0.1.2（MIT）：保留了其 zotero.py 与本地 API 路由说明，并针对独立运行、DeepSeek Harness、Windows 和本机代理环境做了修改。

• 原始版权与许可全文见 LICENSE
• 来源与改动范围见 NOTICE.md
• 本项目不是 OpenAI、DeepSeek 或 Zotero 官方发布的适配版本

English

A DeepSeek Harness skill for the local Zotero library: search items, export BibTeX, add citations to LaTeX/Markdown drafts, read attachment full text on demand, and fetch a ranked daily digest of new papers in your topics from OpenAlex.

Install by copying zotero/ to ~/.dsh/skills/zotero (or run python install.py), enable Zotero's local API, then ask your agent to search your library. For the daily digest, run zotero.py daily-config --enable --topics "..." and optionally daily-schedule --time 08:00. Adapted from OpenAI's Zotero plugin 0.1.2 under the MIT license.