zotagent

zotagent

zotagent は Zotero ライブラリ用の CLI です。インデックス済みの添付ファイル（PDF／EPUB／HTML／TXT）と書誌メタデータの検索・取得、DOI、ウェブページ URL、識別子（ISBN／PMID／arXiv）、Semantic Scholar の paperId、JSON、または手動入力したフィールドによるアイテムの追加、Semantic Scholar を使った論文の参考文献と被引用文献の追跡、最近の Zotero アイテムの確認ができます。タスクコマンドは JSON を出力します（成功時は {ok: true, data, meta?}、失敗時は {ok: false, error, meta?} と終了コード 1）。

引用キー、アイテムキー、引用箇所のテキストを捏造しないでください。クエリに該当する結果がない場合は、そのように伝えてください。

3 つの検索レイヤー — 適切なものを選ぶ

コマンド	検索対象	適した用途
zotagent search "<q>" [--semantic] [--tag <tag>] [--collection-key <key>] [--limit n] [--min-score n]	インデックス済みの全文のみ — タイトルではなく本文（デフォルトは FTS5 キーワード検索。--semantic を指定すると qmd ベクトル検索。キーワード検索では、Zotero タグやコレクションのフィルターを任意で指定可能）	ライブラリ全体、またはタグやコレクションで絞り込んだ範囲から、あるトピックについて論じた箇所を見つける
zotagent search-in "<q>" --key <k> [--limit n]	1 つのアイテムのインデックス済み添付ファイルの全文	1 本の論文内で用語や引用符付きの語句を詳しく調べる
zotagent metadata ["<q>"] [metadata filters...] [--tag <tag>] [--collection-key <key>] [--field f] [--abstract] [--indexed] [--limit n]	書誌フィールド：タイトル／著者／年／ジャーナル／出版社／要約。Zotero タグやコレクションによる絞り込みも可能	メタデータやタイトルから論文を見つける、存在を確認する、itemKey を特定する

メタデータ検索の簡単なルール：

• 位置指定クエリ、フィールドフィルター（--author／--year／--title／--journal／--publisher）、またはその両方を指定できます。
• --field の対象となるのは位置指定クエリのみです。フィルターフラグは AND 条件で適用されます。
• --tag "PhD Thesis" は Zotero Web API から一致するトップレベルアイテムのキーを取得し、その後、ローカルの結果を絞り込みます。そのため、ワークフロー用タグは PDF 添付ファイルではなく親アイテムに付けてください。--tag を繰り返すと、タグは AND 条件になります。Zotero の読み取り API 設定が必要です。トップレベルアイテムが持つタグがない場合は、エラーではなく警告が返されます。ライブラリに該当項目がないと判断する前に、タグの綴りを確認してください。
• --collection-key ABCD1234 は、指定した Zotero コレクションに直接含まれるトップレベルアイテムに絞り込みます（zotero.org/<user>/collections/<key> の末尾に表示される 8 文字のキー）。--collection-key を繰り返すと複数のコレクションを統合して検索できます。--tag と組み合わせると、両方に一致する項目に絞り込めます。直接含まれるアイテムのみが対象で、サブコレクションは含まれません。Zotero の読み取り API 設定が必要です。不明なキーを指定すると COLLECTION_NOT_FOUND で失敗し、トップレベルアイテムがないコレクションの場合は警告が返されます。
• --abstract を指定すると、出力に要約テキストが含まれます（応答を簡潔に保つため、デフォルトでは省略されます）。要約テキストを検索するには、位置指定クエリと --field abstract を使います。
• 各結果には、共有全文インデックスから読み取った indexed／indexedFiles が示されます。これは search-in／fulltext でアイテムを読み取れるかどうかを示します。デバイスには依存しません。現在のマシンに添付ファイルが存在するかどうかは示されず、Zotero に file エントリーがあるだけでは該当しません。添付ファイルは sync で抽出されている必要があります。テキストレイヤーのないスキャンは、sync 後も indexed: false のままです。PDF が OCR 処理されるまでは、抽出エラーとして記録されます。--indexed を指定すると、インデックス済みのアイテムのみが残ります。
• metadata "Pratt 1985" は通常、空の結果を返します（年は OR 条件に含まれません）。代わりに --author "Pratt" --year "1985" のように分けて指定してください。
• CJK の著者名は、続けて書いても空白を入れても一致します。--author 余泳泽 と --author "余 泳泽" はどちらも、姓が余、名が泳泽の著者を検索します。

キーワード構文 — search と search-in はどちらも、Trad→Simp に折りたたまれたインデックスに対して porter ステマーを使う SQLite FTS5 検索を実行します：

演算子	例	注記
完全一致フレーズ	"institutional change"	トークンが隣接している場合に一致します。複数語のフレーズを引用符で囲みます。単語の中に句読点が含まれる場合（COVID-19、U.S.、Olson's）、引用符なしでもフレーズとして一致します。
AND（デフォルト）	alpha beta	裸のトークンの間には暗黙的に適用されます。
OR	Acemoglu OR Robinson	大文字で記述する必要があります。小文字の or は演算子ではなく、リテラルの検索語です。
NOT	alpha NOT beta	右側の式を除外します。大文字のルールは同じです。-beta 形式はありません。検索語の前に - を付けると（-beta、- beta、-(a OR b)）、INVALID_ARGUMENT になります。また、末尾に AND／OR／NOT がある場合や、句読点のみのクエリも同様です。
近接	"土地" NEAR/20 "开发"	N トークン以内で一致します。順序は問いません。NEAR/<n> を使用してください。NEAR 単独や NEAR(...) は使えません。
前方一致ワイルドカード	Pete*	Pete で始まる任意のトークンに一致します。例：Peter、Petersen など。ワイルドカードは末尾にのみ指定できます。

search と search-in は、ほとんどのクエリをブロックごとの FTS に対して評価します。search-in は対象ドキュメントから一致したブロックを --limit まで返し、単一の引用符付きフレーズについてはマニフェストレベルのブロック横断スキャンも実行します。search は一致したアイテムごとに 1 行を返します。インデックス化された添付ファイルが複数あるアイテムは、それらすべての中で最もランキングの高いブロック（FTS5 bm25 に基づくもの）を通じて 1 回だけ表示されます。search --limit のデフォルトは 10 で、上限は 100 です（より大きな値を指定すると INVALID_ARGUMENT になります）。さらにページを進めるのではなく、クエリを絞り込むか、--tag／--collection-key で範囲を指定してください。search --semantic は約 40 件の候補ドキュメントからなる固定プールを使用するため、ライブラリ内に関連する資料がさらにある場合でも、--limit より少ない行しか返さないことがあります。

NEAR/<n> は最初に試す方法として最適です。 同じ箇所に出現する必要はあるものの、隣接しているとは限らない 2～3 個の基準語がある場合に使います。例："土地" NEAR/20 "利用"。通常、単純なキーワード検索より精度が高く、--semantic よりもはるかに高速です。

キーワード検索とセマンティック検索の使い分け：名前、基準語、引用、または --tag／--collection-key による範囲指定には、まずキーワード検索（完全一致フレーズ、OR、NEAR）を使います。表現が曖昧な場合や、概念的に近い資料を探す場合は --semantic に切り替えてください。--tag、--collection-key、--min-score は --semantic と併用できません。また、キーワード検索と同様に、--semantic は英字または数字を含まないテキストを受け付けず（INVALID_ARGUMENT）、セマンティック検索の score は順位を示す値（1、0.5、0.33、…）であり、関連度の値ではありません。そのため、セマンティック検索の結果は該当箇所を見て判断してください。NEAR/<n> は、1 つのキーワードではノイズに埋もれやすい OCR 処理済み資料やスキャン資料（中華民国時代の縦書き文献、古い地誌など）で特に役立ちます。

中国語の繁体字／簡体字の揺れの吸収：キーワード検索の search、search-in、metadata は、繁体字と簡体字のどちらでも照合します（汉字 ≡ 漢字）。どちらか一方の表記で十分です。引用符で囲まれていない CJK 文字列は、順序を保ったフレーズとして扱われます。会社 は 会社 のみに一致し、社会 には一致しません。ブロック内のどこにあっても両方の語を必須にするには、語をスペースで区切ります（国家 能力）。キーワード検索では合字や全角形式も正規化されるため（NFKC）、exemplifies で exemplifies が見つかり、1949年 で １９４９年 が見つかります。search --semantic は、ソーステキストに対する qmd 埋め込みを使用するため、正規化を行いません。返されるテキスト（passage、blocks、fulltext、expand）では、添付ファイルに保存された元の表記が保持されます。

引用する箇所

デフォルトでは言い換え、返された itemKey を使って Pandoc のソース形式で引用します。原文どおりの引用は、正確な表現が重要な場合（特徴的な語句、一次資料からの引用、定義）に限ります。むやみに引用すると、文書が逐語録になってしまいます。

引用に pageStart / pageEnd を含めないでください。これらは PDF ファイル内の位置を 1 から数えたものであり、論文や書籍に印刷されたページ番号ではありません。たとえば、pp. 1360–1380 と印刷された雑誌論文は pages 1–21 として返され、書籍では前付によって各ページの位置がずれるため、印刷された p. 96 が pageStart: 98 として返されることがあります。

• 言い換え：[@itemKey]
• 表現が重要な場合の逐語的な引用：... a "non-trivial role" [@itemKey]
• 文章内での参照：@itemKey says ...

ユーザー向けの文章では、charOffset やブロックインデックスを引用しないでください。charOffset は、より多くの文脈を取得するために expand に渡す値です。ブロックインデックスは blocks の出力に含まれますが、PDF/EPUB リーダーではいずれも使って移動できません。

引用をでっち上げないでください。返された passage が途中で切れているように見える場合（… マーカー）や、文字化けしている場合（OCR ノイズ、単語の途中で切れているなど）は、引用する前に expand を呼び出して、正確な範囲を取得してください。

一般的なワークフロー

該当箇所を探し、周辺の文脈を取得する

# Library-wide search — keyword by default; --semantic for fuzzy/conceptual queries
zotagent search "party secretary governance"
zotagent search "informal political networks in contemporary China" --semantic --limit 20
zotagent search "local fiscal capacity" --tag "PhD Thesis"

# Scope by Zotero collection key (8-char ID at the end of the collection URL).
# Repeatable for union; combine with --tag for an intersection.
zotagent search "local fiscal capacity" --collection-key ABCD1234
zotagent search "land reform" --collection-key ABCD1234 --tag "PhD Thesis"

# Drill into one paper. A bare surname catches both in-text "Acemoglu and
# Robinson 2012" and bibliography "Acemoglu, Daron. 2012".
zotagent search-in 'Acemoglu' --key CMJ3N8TL

# Expand around a returned hit. `--offset` is the `charOffset` from a search
# result; `--radius` is the half-window in characters (default 1000). Increase
# the radius when the search passage looks truncated or you need more context.
zotagent expand --key KG326EEI --offset 18432 --radius 1500
zotagent fulltext --key KG326EEI --clean

論文のメタデータを調べる

# Search selected fields with a positional query
zotagent metadata "aging in China" --field title --field abstract

# Narrow by specific metadata fields
zotagent metadata --author "Pratt" --year "1985"

# Use a year prefix for a range; `--year 198` matches the 1980s
zotagent metadata --author "Pratt" --year "198"

# Combine a positional query with a filter
zotagent metadata "imperial" --author "Pratt"

# Narrow to manually tagged Zotero items
zotagent metadata --tag "PhD Thesis"
zotagent metadata "land reform" --tag "PhD Thesis"

# Narrow to a Zotero collection (or intersect a collection with a tag)
zotagent metadata --collection-key ABCD1234
zotagent metadata "land reform" --collection-key ABCD1234 --tag "PhD Thesis"

# Keep only indexed items; include abstract text only when needed
zotagent metadata "dangwei shuji" --indexed
zotagent metadata "aging in China" --abstract

# Use a returned key with retrieval commands
zotagent fulltext --key KG326EEI --clean
zotagent blocks --key KG326EEI --limit-blocks 40    # paginated structured view; rarely needed

論文を Zotero に追加する

追加時の情報源の優先順位：DOI → --doi（裸の DOI、doi:10.…、または doi.org のリンクを指定します。arXiv ID は --doi 10.48550/arXiv.<id> として使えます。PMID は PubMed で DOI に解決されます）。CNKI など、すでに抽出済みのメタデータ → --json。ウェブページ → ページ内の DOI（引用ブロック、メタタグなど）を探して --doi を使い、見つからない場合はメタデータを自分で抽出して --json または手動フィールドに指定します。ISBN → Open Library / Google Books のメタデータを --json または手動フィールドで指定し、--item-type book を使います。DOI がない論文 → s2 で検索し、その後 add --s2-paper-id を使います。

# Add by DOI (arXiv IDs have a DOI form)
zotagent add --doi "10.1111/dech.70058"
zotagent add --doi "10.48550/arXiv.2406.01234"

# Search Semantic Scholar, then add by paperId
zotagent s2 "state-owned enterprise governance" --limit 5
zotagent add --s2-paper-id <paperId>

# --s2-paper-id also takes a DOI, an arXiv id, or a prefixed identifier
zotagent add --s2-paper-id "10.1093/ajae/aaq063"
zotagent add --s2-paper-id "ARXIV:2106.15928"

# Manual fallback — authors go in Zotero "Last, First" form; repeat --author for multiple
zotagent add --title "Title of a paper" --author "Zhang, San" --year 2026 --publication "Journal of Important Studies"

# Add a book — pass --item-type, otherwise manual adds default to journalArticle
# (URL-only manual adds become webpage)
zotagent add --title "Fifty Years of Land Reform" --author "Hsiao, Cheng" --year 1980 --publication "China Land Policy Institute" --item-type book

# Add from pre-shaped JSON (best for CNKI)
zotagent add --json paper.json
zotagent add --json batch.json --collection-key COLL1234
your-extractor | zotagent add --json -

# Attach a local PDF as a linkMode=linked_file child (file stays on disk;
# no Zotero storage quota used). When the path is under attachmentsRoot,
# zotagent stores it as 'attachments:<rel>' for cross-device portability.
zotagent add --title "Paper" --author "Doe, Jane" --attach-file ~/Downloads/foo.pdf
# In --json mode, each item carries its own attachFile / attach-file field.
echo '{"itemType":"journalArticle","title":"...","attachFile":"/path/to/foo.pdf"}' | zotagent add --json -

--doi と併せて指定した手動フラグ（--title、--author、--year、--publication、--item-type）は、DOI レコードのフィールドを上書きします。また、--title はフォールバックとしても機能します。DOI の検索に失敗した場合、または Zotero が DOI レコードを受け付けない場合は、手動フィールドからアイテムが作成され、その旨が data.warnings に記載されます。--title を指定せずに DOI の検索に失敗すると、コマンドも失敗します。

add --json の入力フィールド — 必須なのは title のみです：itemType（デフォルトは journalArticle）；文字列で指定する authors（"Last, First" または "First Last"。"李华" のような単一トークンは1つの名前として扱われます）、または Zotero 形式の creators；date または year（数値も使用できます）；publicationTitle / publication / journal（アイテムの種類に応じて bookTitle、proceedingsTitle などに振り分けられます）；abstract；doi；文字列で指定する keywords または tags；url；accessDate；collections（キー1つ、またはキーの配列）；attachFile。その他の Zotero フィールド名（volume、issue、pages、publisher、place、ISBN、language、extra など）はそのまま渡されますが、そのアイテムの種類に該当するフィールドがない場合は、通知なく削除されます。エイリアスの一覧は README にあります。

add --json は、入力オブジェクトが1つの場合でも、常に data を配列として返します。個々のアイテムのエラーは {ok: false, error: ...} として該当箇所に返され、バッチの残りの処理は中断されません。解析、設定、空の入力に関するエラーでは、エンベロープ全体が失敗します。アイテム単位のエラーコード：INVALID_ITEM_TYPE — Zotero がその itemType を認識しません。種類を修正し、そのアイテムだけを再送信してください。INVALID_ATTACH_FILE — アイテムの添付ファイルのパスが不正です（下記を参照）。JSON_ITEM_FAILED — その他のエラー（ネットワーク、タイムアウト、レート制限、Zotero のエラーなど）です。メッセージに理由が記載されます。一時的な原因の場合は、そのアイテムのみ後で一度再試行する価値があります。 添付ファイルが作成されると、AddResult.attachmentItemKey が設定されます。不正な --attach-file パスは親アイテムが書き込まれる前に失敗するため、Zotero に孤立した引用が残ることはありません（アイテム単位の失敗コード：INVALID_ATTACH_FILE）。親アイテムの作成後に添付ファイルの POST が失敗した場合でも、親アイテムの itemKey は返され、失敗は警告として通知されます。上記に記載のないその他の add フラグ：--url, --url-date（別名 --access-date）、--collection-key。

s2 の結果には、利用可能な場合 openAccessPdfUrl が含まれます。これを無料の PDF リンクとして、add の提案とともにユーザーに提示してください。

S2 のレート制限：1 リクエスト／秒です。Semantic Scholar のエンドポイント（s2、s2-refs、s2-citations、add --s2-paper-id）全体で累積されます。これらは順番に実行し、並列実行はしないでください。並列呼び出しは 429 になります。zotagent は 429 を自動で再試行するため（最大 2 回、Retry-After に従い、各待機時間は最大 10 秒）、たまに発生する競合は吸収されます。再試行が尽きると、コマンドは RATE_LIMITED で失敗します。この場合は再試行を増やすのではなく、実行速度を落としてください。通常、別々のツール呼び出しの間隔を空ければ十分で、スリープは不要です。4 つすべてのコマンドで、設定に semanticScholarApiKey が必要です。設定されていない場合は SEMANTIC_SCHOLAR_NOT_CONFIGURED で失敗します。これは設定の問題であり、再試行しても意味がありません。Semantic Scholar が認識しない識別子は PAPER_NOT_FOUND で失敗します。識別子を確認するか、s2 "<title>" でタイトルから論文を検索して、返された paperId を渡してください。同じ ID を再試行しても解決しません。

add --from-url／add --identifier は存在しますが、通常は設定されていないセルフホストの Zotero 翻訳サーバーを前提としています。そのため、TRANSLATION_SERVER_NOT_CONFIGURED が返ることを想定し、再試行するのではなく、上記のソース優先順位に従って別の方法に切り替えてください。translationServerUrl はサーバーが実際に稼働している場合にのみ設定してください（設定済みでもサーバーが停止していると、--doi も失敗します）。サーバーモードの詳細は README に記載されています。

論文の参考文献と被引用文献を調べる

引用関係をたどることは、文献レビューにおいて最も有力な発見の手がかりです。s2-refs はある論文が引用している論文（参考文献、つまり過去にさかのぼる方向）を返し、s2-citations はその論文を引用している論文（未来に向かう方向）を返します。

# Backward: what does this paper build on?
zotagent s2-refs "10.18653/v1/N18-1022" --limit 20

# Forward: who has cited it since?
zotagent s2-citations "DOI:10.18653/v1/N18-1022" --limit 20

# Page through a long bibliography — data.next is the offset for the next call
zotagent s2-refs 649def34f8be52c8b66281af98ae884c09aef38b --limit 50 --offset 50

# Quote URLs so the shell does not eat the ? and &
zotagent s2-refs "https://arxiv.org/abs/2106.15928" --limit 10

どちらも識別子を 1 つだけ受け取り、タイトルは受け付けません。40 文字の paperId、DOI、arXiv ID、接頭辞付き ID（DOI:、ARXIV:、PMID:、CorpusId:、URL:）、または doi.org／arxiv.org／semanticscholar.org の URL を指定できます。タイトルしかわからない論文の場合は、まず s2 "<title>" を実行し、返された paperId を渡してください。不正な識別子はローカルで INVALID_ARGUMENT として失敗し、リクエストは消費されません。

Semantic Scholar が引用関係を重要と判定した場合、行には isInfluential: true が設定されます。これは、参考文献が長い場合に役立つ順位付けのヒントです。行には意図的に要約が含まれません。要約を読むには、その行の paperId を add --s2-paper-id に渡してください（完全なレコードを取得します）。または、metadata でライブラリ内の論文を検索してください。Semantic Scholar にレコードがない項目は除外され、data.warnings に報告されます。

ok: true で results が空の場合、それは失敗ではなく実際の検索結果です。出版社によっては参考文献リストを Semantic Scholar に提供していないため、そのような論文に対する s2-refs は何も返しませんが、同じ論文に対する s2-citations は引き続き機能します。再試行はしないでください。逆方向を試すか、同じ論文に対して別の識別子を試してください。

最近追加または変更されたアイテムを一覧表示する

# Most recent 10 additions (default)
zotagent recent

# Top 20 most recently modified items
zotagent recent --limit 20 --sort modified

recent は Zotero Web API に直接アクセスするため（インデックスは不要）、add で作成したばかりのアイテムもすぐに表示されます。add が反映されたことの確認や、ライブラリの概要を把握するのに便利です。通常のトップレベルの書誌アイテムのみを返し、単独のノートと添付ファイルは除外されます。--limit の最大値は 100 です。

ローカルインデックスを確認または修復する

ユーザーから明示的に依頼されない限り、sync は実行しないでください。 実行中のデバイスに添付ファイル一式がすべて保存されているとは限りません（たとえば、attachmentsRoot 内の PDF がまだクラウド上のプレースホルダーだったり、ダウンロードの途中だったりする場合があります）。不完全なコピーから同期すると、共有インデックス／データファイルが書き換えられ、ほかのデバイスに反映される際に破損する可能性があります。インデックスが古いままかどうかは、更新するかどうかも含めてユーザーが判断することです。

# Counts, paths, and qmd status
zotagent status

# Rebuild / refresh local full-text indexes
zotagent sync

# Retry unchanged files that previously failed extraction
zotagent sync --retry-errors

# Tune heavy PDF extraction on large libraries
zotagent sync --pdf-concurrency 1 --pdf-batch-size 4 --pdf-timeout-ms 900000

# Surface suspicious extraction output before quoting heavily from a corpus
zotagent diagnose --limit 20

同期対象からの除外はローカルファイルではなく、Zotero のタグによって行います。Zotero でトップレベルのアイテムに zotagent:exclude タグを付けると、次回の sync ではそのアイテムが完全にスキップされ（抽出もインデックス作成も行われず）、ローカルインデックスから削除されます。タグ名は ~/.zotagent/config.json の excludeTag または ZOTAGENT_EXCLUDE_TAG 環境変数で変更できます。タグ付きアイテムを解決するには、Zotero 読み取り API の設定（zoteroLibraryId と zoteroApiKey）が必要です。diagnose を使って、OCR に失敗したスキャン、縦書き CJK の PDF、複数段組みの地名辞典などの候補を見つけ、タグを付けるか再 OCR してから再同期してください。

同期を拒否するケースは 3 つあり、いずれも何も変更する前に停止します。回避策を試すのではなく、ユーザーに報告してください。SYNC_DISABLED：このホストは読み取り専用（syncEnabled: false）に設定されています。別のマシンが管理するインデックスを共有しているか、設定値を読み取れない状態です（メッセージに対象の設定名が示されます）。この制限を回避するために設定を変更してはいけません。ZOTERO_TAG_LOOKUP_FAILED：設定済みの Zotero API でタグ付きアイテムを一覧表示できず、代わりに使える以前の検索結果も保存されていません（検索が一度成功すれば、保存された一覧を使ってオフラインで同期できます）。API に接続できるようになってから再試行してください。この制限を回避するために Zotero の認証情報を削除してはいけません。削除すると、縦書き PDF がすべて誤った読み順で再抽出されます。MASS_REMOVAL_REFUSED：書誌情報から添付ファイルを解決できなかったか、インデックス済みアイテムの 10% を超える数（かつ 50 件以上）が失われました。通常は書誌情報のエクスポートが途中で切れているか、attachmentsRoot が間違っています。削除が意図したものだった場合の対処方法は、メッセージに記載されています。

出力形式で注意すべき点

• passage はヒット箇所を中心とする短い文字範囲で、最大約 500 トークンです。先頭または末尾の … は、返された範囲の外にもテキストがあるか、トークン上限に達したことを示します。より長い範囲を取得するには、expand --key <k> --offset <charOffset> を呼び出し、より大きな --radius を指定してください。
• charOffset は添付ファイルごとではなく、アイテム全体を基準にします。 複数のインデックス済み添付ファイルを持つアイテムでは、オフセットは統合された Markdown 内で単調に増加し、添付ファイル間には # Attachment: <name> の区切りが入ります。検索結果の charOffset をそのまま expand に渡してください。
• --key は itemKey または citationKey を受け付けます。先頭の @ の有無は問いません（そのため Pandoc の @citekey をそのまま貼り付けられます）。出力でアイテムを識別するキーは常に itemKey のみです。citationKey は入力として受け付けられますが、出力には含まれないため、後続の呼び出しには itemKey を使用してください。
• 章のキーを指定した search-in では見つからないことがあります。 SEARCH_IN_FAILED: No indexed attachment found は通常、その章の PDF が親の巻の中でのみインデックス化されていることを意味します。metadata で親を調べてから、親のキーを指定して search-in を実行し、見出しで該当する章を探してください。論文集や会議録でよく見られます。
• search-in は範囲を絞った一致を返し、search はアイテムごとに 1 つの抜粋を返します。 search-in の結果の大半は、単一ブロックの FTS 一致です。引用符で囲んだ語句 1 つがブロックをまたぐ場合は、マニフェストレベルの完全一致スキャナーが検出できます。search の結果は、その文書に一致があり、代表的な抜粋が 1 つ示されていることを意味します。ユーザーが「この論文に X と書いてありますか」や「この論文のどこに Y が出てきますか」と尋ねた場合は、search-in を使用してください。
• search-in --limit は、返される一致ブロック数の上限を設定します。 通常はデフォルトの 10 で十分です。すでに 1 つの文書に範囲を絞っているためです。順位の低い一致も調べるには上限を増やしてください。返されたブロックがユーザーの意図に合わない場合は、クエリを変更してください。

インデックスの鮮度

search / search-in / blocks / expand / fulltext はローカルインデックスを読み取ります。INDEX_EMPTY は、インデックスにドキュメントがないことを意味します。メッセージにある案内をユーザーに伝えてください。sync を実行するか、同期を行うホストからインデックスをコピーするかが示されています。自分で sync を実行しないでください。search / search-in が、キーワードインデックスは「別の zotagent バージョンで構築されています」と警告する場合は、警告にある案内をユーザーに伝えてください。sync で再構築するか、同期が無効なホストではホスト間で zotagent のバージョンを一致させる必要があります（一致するまでは検索結果に該当項目が含まれない場合があります）。自分で sync を実行しないでください。--semantic による SEMANTIC_INDEX_MISMATCH は、このホストの埋め込みモデルがインデックス内のものとは異なるベクトルを計算することを意味します。そのため、セマンティック検索の結果は不確かになります。ユーザーに伝えてください（修正が必要なホストはメッセージに記載されています）。そのうえで、キーワード検索に切り替えてください。--tag / --collection-key を指定したときに、該当項目について「ここでは検索可能なテキストがありません」という警告が出る場合、各グループの理由が示されます。タグによる除外、抽出の失敗、ファイルの欠落、未対応の種類、ローカルインデックスにない場合です。最後のグループだけは、同期すれば解決します。metadata / add / s2 / s2-refs / s2-citations / recent はローカルインデックスがなくても動作します（その場合、metadata はすべての項目について indexed: false と報告し、インデックスカタログが空であると警告します）。add の後、新しい論文は次回の sync まで全文検索できません。

Zotero の編集と、CLI が返さないフィールド

zotagent はローカルインデックスとローカルの書誌エクスポートを読み取り、書き込み操作として行うのは add による項目の作成だけです。個々の項目の全フィールド（DOI、巻、ページ、URL、タグ、コレクション、日付）、コレクションキーとタグ一覧の取得、およびすべての編集（フィールドの変更、タグの追加や削除、コレクションへの登録、ノートの添付、項目のゴミ箱への移動）には、Zotero API を直接使用してください。こうした呼び出しを初めて行う前に、references/zotero-web-api.md を読んでください。認証情報の扱い、送信しなかったフィールドが編集によって消去されないようにする読み取り・変更・書き込みのルール、および削除時の確認手順が記載されています。

ここに記載されていないコマンドやフラグが必要な場合は、zotagent help を実行してください。