zotero-dev-rules

Zotero 開発ルール

Zotero はオープンソースの文献管理ツールです。開発者は、Web API （https://api.zotero.org）を使ったオンラインライブラリ、デスクトップクライアント向けのプラグイン／内部 JavaScript API、そして トランスレーター（JS スクレイパー／コンバーター）の 3 つの方法で拡張できます。引用は、 citeproc-js を介した CSL スタイルから生成されます。このスキルは https://www.zotero.org/support/dev を反映しているため、再取得することなく、Zotero の開発に関する質問に回答し、統合を構築できます。

このスキルを使う場面

• Web API を介して Zotero ライブラリの読み書きを行う場合（アイテム、コレクション、タグ、検索）。
• 添付ファイルのアップロード、ライブラリ全体または一部の同期、ストリーミング（WebSocket）更新、OAuth。
• Zotero プラグインの構築やデバッグ（ブートストラップ方式が導入された Zotero 7～10 時代。Zotero 10 の移行ノートを含む）。また、JavaScript API／JavaScript の実行を使ったクライアントのスクリプト作成。
• 新しいプラグインを作る前に、似た機能を持つ既存のオープンソースプラグインを見つけて（コードを調べるため）。
• トランスレーター（Web／インポート／エクスポート／検索）の作成や修正、および 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 を指定してください。デフォルトに頼らないでください。 キーは key= クエリパラメーターではなく、Zotero-API-Key ヘッダー（または Authorization: Bearer）で渡してください。
• すべての書き込みにはバージョンを含めてください（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() を使用し、バッチは1つのトランザクションでまとめてください。chrome://zotero/content/include.js を使って Zotero オブジェクトを取得してください。
• トランスレーター：メタデータブロック＋関数＋テストケースで構成します。detectWeb はタイプ／"multiple"／false を返し、item.complete() でアイテムを完了させてください。Promise ヘルパー（requestText/JSON/Document）を使用してください。 AGPL v3 ライセンスです。zotero/translators への PR で提出してください。Scaffold でテストしてください。
• 同期はバージョンベースです。ライブラリのバージョンは、単調増加する不透明な整数として扱ってください。差分の取得には ?format=versions と ?since= を使用し、3者間マージ用に未加工の JSON スナップショットを保存してください。同期中に Last-Modified-Version が変化した場合は、処理を最初からやり直してください。新しいローカルオブジェクトのバージョンは 0 です。
• 引用スタイルには CSL と citeproc-js を使用します。citation-style-language/styles リポジトリには、その CONTRIBUTING ガイドラインに従ってスタイルを提出してください。引用フォーマッターを独自に作成しないでください。