zotero-dev-rules

Zotero 开发规则

Zotero 是一款开源参考文献管理器。开发者可以通过三种方式扩展它：用于在线文库的 Web API （https://api.zotero.org）、用于桌面客户端的 插件 / 内部 JavaScript API，以及 转换器（JS 抓取器/转换器）。引文采用 CSL 样式，通过 citeproc-js 生成。本技能对应 https://www.zotero.org/support/dev，让你无需重新获取资料即可回答 Zotero 开发相关问题并构建集成。

何时使用此技能

• 通过 Web API 读取或写入 Zotero 文库（条目、分类、标签、搜索）。
• 附件上传、完整或部分同步、流式（WebSocket）更新、OAuth。
• 构建或调试 Zotero 插件（Zotero 7–10 引导式架构；包含 Zotero 10 迁移说明）；通过其 JavaScript API /「运行 JavaScript」脚本化操作客户端。
• 构建新插件前，查找功能类似的现有开源插件（以研究其代码）。
• 编写或修复转换器（网页/导入/导出/搜索），并在 Scaffold 中测试。
• 创建或编辑 CSL 引文样式；使用 citeproc-js / citeproc-node。

参考索引 — 加载所需文件

文件	涵盖内容
references/web-api.md	基础 URL、身份验证/API 密钥、版本控制、读取请求、写入请求、批处理、文件上传、条目类型/字段、同步算法、流式 API、OAuth
references/client-and-plugins.md	内部 JavaScript API（Zotero.Items/Item/Search/DB/Notifier）、运行 JavaScript、插件开发（Zotero 7 引导式架构/清单）、Zotero 10 迁移说明、客户端编码入口
references/translators.md	转换器元数据块、detectWeb/doWeb/doImport/doExport/doSearch、抓取辅助工具（text/attr/ZU）、HTTP 请求、调用其他转换器、Scaffold/测试
references/citation-styles.md	CSL、citeproc-js / citeproc-node、样式仓库、样式编辑、类型映射
references/plugin-gallery.md	zotero-chinese 插件商店注册表快照（按标签分类的 137 个插件 + 已弃用列表）——查找功能类似的开源插件，并在构建前研究其代码

速查表 — Web API

# Read (public library needs no key). HTTPS only. Always pin the version.
curl -H "Zotero-API-Version: 3" -H "Zotero-API-Key: <KEY>" \
  "https://api.zotero.org/users/<userID>/items?format=json&limit=25"

# Library prefix: /users/<userID> or /groups/<groupID>
# Common params: format=json|atom|bib|keys|versions, include=bib,citation, q=, itemType=, tag=,
#                sort=, direction=, limit=1..100 (def 25), start=, since=<version>
# Response headers: Last-Modified-Version, Total-Results, Link (rel=next/last), Backoff
# Rate limits: honor Backoff; on 429 wait per Retry-After.

# Write (key with write access). Up to 50 objects/request. Must carry a version.
curl -X POST -H "Zotero-API-Key: <KEY>" -H "Content-Type: application/json" \
  -H "If-Unmodified-Since-Version: <libVersion>" \
  -d '[{"itemType":"book","title":"..."}]' \
  "https://api.zotero.org/users/<userID>/items"
# PUT replaces (omitted fields cleared); PATCH merges (only changed fields). 412 = version mismatch.

// Client internal JS API (Run JavaScript / plugin). Most DB/disk/network calls are async.
let item = new Zotero.Item('journalArticle');
item.setField('title', 'Example');
item.setCreators([{ creatorType: 'author', firstName: 'Jane', lastName: 'Doe' }]);
await item.saveTx();                               // async, own transaction
let items = ZoteroPane.getSelectedItems();         // window scope

关键端点：/itemTypes /itemFields /itemTypeFields?itemType= /itemTypeCreatorTypes?itemType= /creatorFields /items/new?itemType= · 完整架构：https://api.zotero.org/schema。

严格规则

• 始终使用 Zotero-API-Version: 3 固定 API 版本（生产环境）——绝不依赖默认值。 通过 Zotero-API-Key 请求头（或 Authorization: Bearer）传递密钥，不要使用 key= 查询参数。
• 每次写入都必须携带版本信息（If-Unmodified-Since-Version 请求头或每个对象的 version）。 缺少时 → 428；不匹配时 → 412 Precondition Failed（重新获取、合并、重试）。批次最多 50 个对象。
• 遵守速率限制：主动遵循 Backoff 请求头；遇到 429 时等待 Retry-After 指定的时间并降低请求频率。
• mtime 的单位是毫秒，不是秒。文件上传分为 3 个步骤（授权 → S3 → 注册）； 新附件使用 If-None-Match: *，替换附件使用 If-Match: <previous-md5>。
• 客户端 JS API 是异步的：对 saveTx() / getAsync() / Zotero.DB.executeTransaction(...) 使用 await。 单次保存使用 saveTx()；批量操作放在一个事务中。通过 chrome://zotero/content/include.js 获取 Zotero 对象。
• 转换器：包含元数据块 + 函数 + 测试用例；detectWeb 返回类型 / "multiple" / false；使用 item.complete() 完成条目。使用 Promise 辅助函数（requestText/JSON/Document）。 采用 AGPL v3 许可证；通过 PR 提交到 zotero/translators。在 Scaffold 中测试。
• 同步基于版本：将文库版本视为不透明的单调递增整数；使用 ?format=versions + ?since= 进行差异比较，保存未经修改的 JSON 快照以进行三方合并；如果同步期间 Last-Modified-Version 发生变化，则重新开始本轮同步。本地新对象的版本从 0 开始。
• 引文样式使用 CSL + citeproc-js；按照 citation-style-language/styles 仓库的 CONTRIBUTING 指南提交样式——不要自行编写引文格式化程序。