Zotero Library Agent

概要

Zotero Library Agent は Host Bridge の有界オンデマンドタスク表面です。AI エージェントが有限のリクエストに対して Zotero ライブラリを操作できるようにします — アイテムの検査、コンテキストの取得、文献および合成データの読み取り、Workflow の実行、承認済み変更の適用、ファイル転送、証拠の受け渡し — 常駐ライブラリ保守サービスになることなく。

Host Bridge は 3 つの表面を公開し、それぞれ異なる役割を持ちます：

表面	役割	使用タイミング
CLI Bundle（zotero-bridge）	インストール、接続、低レベルコマンド契約	Host Bridge 機能への直接 CLI アクセスが必要な場合
Library Agent	有界タスクルーティング、証拠受け渡し、監査可能な結果	意図ルーティングと完了証拠が必要な有限リクエストがある場合
Librarian Profile（Hermes）	常駐インデックス、定期保守、継続的ライブラリサービス	永続的なローカルインデックス、cron ジョブ、継続的監視が必要な場合

Library Agent が提供するもの

• タスクルーティング：コマンドテーブルの完全なスキャンを必要とせず、現在の意図を最小の一致コマンドファミリにルーティングします。
• Journey リファレンス：7 つの詳細な Journey マニュアルが特定のタスクカテゴリをカバーし、それぞれ分岐、ニアミス、証拠要件、承認境界、回復パスを指定します。
• 証拠受け渡し：決定的な形状検証とアーティファクトダイジェスト計算を備えたポータブルな証拠バンドル。
• 権限境界：Host Bridge を唯一の制御パスとして強制し、Zotero ストレージへの直接アクセスやバックグラウンドサービス動作を防止します。
• 有界操作：各タスクは、要求された結果とその証拠が観測可能になった時点で完了します — 送信確認や準備された受け渡しだけでは完了とはみなされません。

有界タスクフロー

1. 接続の確認：ロードされた CLI と Host Bridge プロファイルを検証します。zotero-bridge surface identity --json を実行し、パッケージ化されたマニフェストと比較してリポジトリの releaseSetId を確認します。
2. 意図のルーティング：タスクルーティングリファレンスを読み、リクエストを満たす最小のコマンドファミリを選択します。
3. 一致する Journey の読み込み：タスクカテゴリに完全に一致する 1 つの Journey マニュアルを読みます。
4. 証拠の保持：現在の Host ファクト、返されたハンドル、ローカルアーティファクト、承認状態を個別の証拠として保持します。
5. 実行または送信：Workflow の場合、Workflow 実行リファレンスに従います。Workflow オプションを受け付けない実行モードでオプションを送信しないでください。
6. 構築と検証：バンドルされたヘルパーを使用して最終証拠バンドルを構築・検証します。

要求された結果とその証拠が観測可能になった時点でタスクは完了します。

Journey カテゴリ

Library Agent には 7 つの Journey マニュアルが含まれ、それぞれ特定のタスクドメインをカバーします：

Journey	範囲
現在のコンテキストとライブラリ読み取り	指示的選択、検索と一覧、アイテム詳細、ノート、添付ファイルの証拠
ノート、添付ファイル、準備状態	ノートチャンクとペイロード、注釈、PDF/Markdown/分析の準備状態、生成された添付ファイル
合成研究コンテキスト	トピック、引用グラフビュー、インデックス、リゾルバ、アーティファクト、スキーマ、アテンションキュー
Host 所有 Workflow	Workflow の説明、要件、検証、送信、監視、権限、インタラクション、Product 証拠
Agent 所有受け渡し	Agent 所有バンドル実行、結果検証、apply-back、レシート回復
具体的な書き戻し	プレビュー済み変更、セマンティック書き込みコマンド、承認、ライブ検証
Product とファイル	ローカルパス、登録済みファイル、Dashboard Product、ダウンロード、添付ファイル配信

各 Journey は、正確なペイロードや結果フィールドが必要な場合、バンドルされた zotero-bridge CLI コマンドカードを参照します。

権限とセキュリティ境界

Library Agent は意図しない Zotero 変更を防ぐため厳格な境界を強制します：

• Host Bridge のみ：Host Bridge を唯一の Zotero および Zotero Agents 制御パスとして扱います。Zotero データベース、ストレージディレクトリ、プラグイン内部、ブラウザ状態を直接読み書きしないでください。
• 有界作業：Library Agent をバックグラウンドライブラリサービスに変えないでください。現在のリクエストに対して有界な作業を行い、結果または必要なユーザー判断が得られた時点で制御を返します。
• 無人書き込み禁止：スケジュールされたまたは無人の書き込みを行わないでください。現在のユーザーリクエストと Host Bridge の承認がすべての変更または apply-back を管理します。
• 古い仮定禁止：キャッシュエントリ、生成された参照、証拠バンドルをライブの Zotero 事実として扱わないでください。鮮度が重要な場合は Host Bridge を通じて現在の事実を確認してください。

証拠受け渡し

Library Agent はタスクの継続性のためにポータブルな証拠バンドルを生成します。証拠バンドルには以下が含まれます：

• ステータス：completed、canceled、failed
• 要約：タスクローカルな簡潔な知見
• 証拠ファイル（オプション）：ヘルパーによって構築・検証された証拠バンドル。他のエージェントやタスクが消費可能
• 診断情報（オプション）：構造化された診断情報

バンドルされたヘルパーを使用して証拠バンドルを構築・検証します：

python scripts/zotero_library_agent.py evidence build --input evidence-input.json --output evidence.json
python scripts/zotero_library_agent.py evidence validate --input evidence.json

ヘルパーは決定的な形状を検証し、アーティファクトダイジェストを計算し、Workflow バンドルを検査します。エージェントはコマンド選択、解釈、証拠の十分性、およびレビュー済みアクションの承認について引き続き責任を負います。

失敗処理

• 失敗を報告する際、構造化されたエラーコードとハンドルフィールドを保持します。
• エラーが古い構文または同一性を示す場合にのみコマンドまたはオブジェクトを再発見します。代替ハンドルを推測しないでください。
• 操作がファイルハンドルまたは出力パスを返す場合、証拠または apply-back 入力として使用する前に宣言されたファイルを検証します。
• 必要な権限、入力、またはユーザー意図が欠けている場合、境界で停止し、正確に欠けている判断を表明します。

統合

Library Agent はすべての Zotero アクセスに Host Bridge に依存します。Library Agent を使用する前に：

1. Host Bridge が稼働中であることを確認します（Zotero → 設定 → Zotero Agents → Host Bridge → 起動 / エンドポイントを表示）。
2. zotero-bridge CLI をインストールします（Host Bridge 設定パネルの CLI をインストール ボタンを使用）。
3. エンドポイント URL と Bearer トークンで接続プロファイルを構成します。詳細な設定は Host Bridge の構成 を参照してください。

次のステップ

• Host Bridge — zotero-bridge CLI と Host Bridge 機能の完全なリファレンス
• Hermes Profiles — ローカルインデックスと定期保守を備えた常駐ライブラリサービス
• Workflows — すべての組み込みおよびカスタム Workflow の概要
• MCP Server — MCP 互換クライアント向けの代替プロトコルインターフェース