メインコンテンツまでスキップ

選択コンテキスト

ユーザーが Zotero でアイテムを選択すると、プラグインは構造化された**選択コンテキスト（SelectionContext）**を構築する。これはユーザーが何を選択したか、および各選択アイテムがどの種別に属するかを記述する。このコンテキストは buildRequest フックの入力基盤として機能する。

選択種別​

選択されたアイテム種別の組み合わせに基づき、selectionContext.selectionType は以下のいずれかの値を返す。

種別説明
"parent"すべての選択アイテムが親アイテム（トップレベルアイテム）
"child"すべての選択アイテムが子アイテム（非トップレベルアイテム）
"attachment"すべての選択アイテムが添付ファイル
"note"すべての選択アイテムがノート
"mixed"選択アイテムが複数の種別の混在
"none"アイテムが選択されていない

コンテキストの構造​

selectionContext = {
  selectionType: "parent",       // 選択種別
  items: {
    parents: [ /* 親アイテムのリスト */ ],
    children: [ /* 子アイテムのリスト */ ],
    attachments: [ /* 添付ファイルのリスト */ ],
    notes: [ /* ノートのリスト */ ],
  },
  summary: {
    parentCount: 2,
    childCount: 0,
    attachmentCount: 0,
    noteCount: 0,
  },
  warnings: [],                  // 警告メッセージ
  sampledAt: "2026-01-15T...",   // コンテキスト作成日時
}

各アイテム種別には豊富なコンテキスト情報が含まれる。

親アイテム（ParentContext）​

親アイテムは Zotero ライブラリ内のトップレベルアイテムである（例：学術論文、書籍、ウェブページなど）。各親アイテムコンテキストには以下が含まれる。

{
  item: Zotero.Item,         // アイテムオブジェクト
  id: number,                // アイテム ID
  title: string,             // タイトル
  attachments: [             // このアイテムの子添付ファイル
    { type, filePath, mimeType, dateAdded, ... }
  ],
  notes: [                   // このアイテムの子ノート
    { id, content, ... }
  ],
  tags: string[],            // タグリスト
  collections: string[],     // 含まれるコレクション
  children: [                // その他の子アイテム
    { id, type, ... }
  ],
}

添付ファイル（AttachmentContext）​

添付ファイルはアイテムのファイル添付である（PDF、Markdown など）。各添付ファイルコンテキストには以下が含まれる。

{
  item: Zotero.Item,         // 添付ファイルアイテムオブジェクト
  id: number,                // アイテム ID
  filePath: string,          // ローカルファイルパス
  fileName: string,          // ファイル名
  mimeType: string,          // MIME タイプ（例："application/pdf"）
  dateAdded: Date,           // 追加日
  parentItem: {              // 所有者の親アイテム
    id: number,
    key: string,
    libraryID: number,
  },
  tags: string[],
  collections: string[],
}

ノート（NoteContext）​

{
  item: Zotero.Item,
  id: number,
  content: string,           // ノート内容（HTML）
  parentItem: { id, key, libraryID },
  tags: string[],
}

フックでの選択コンテキストの利用​

選択された添付ファイルの取得​

export function buildRequest({ selectionContext, runtime }) {
  const attachments = selectionContext.items.attachments;

  return {
    kind: "skillrunner.job.v1",
    create: { skill_id: "my-skill" },
    input: {
      files: attachments.map((attachment) => ({
        path: runtime.helpers.getAttachmentFilePath(attachment),
        name: runtime.helpers.getAttachmentFileName(attachment),
      })),
    },
  };
}

選択された親アイテムとその子コンテンツの取得​

export function buildRequest({ selectionContext, runtime }) {
  const parents = selectionContext.items.parents;

  for (const parent of parents) {
    const title = parent.item.getField("title");
    const attachments = parent.attachments;  // この親アイテム配下の添付ファイル
    const notes = parent.notes;              // この親アイテム配下のノート
  }

  // ...
}

選択種別を確認して動作を決定する​

export function preflight({ selectionContext }) {
  const { selectionType } = selectionContext;

  if (selectionType === "none") {
    // アイテムが選択されていない。スキップ
    return { kind: "skip", reason: "no selected items" };
  }

  if (selectionType === "attachment") {
    // ユーザーが添付ファイルのみを選択。添付ファイル処理ロジックを使用
  } else if (selectionType === "parent") {
    // ユーザーが親アイテムのみを選択。最初の該当添付ファイルを展開
  }

  return { kind: "continue", context: { selectionType } };
}

Attachment Candidate Planning​

{
  "inputs": {
    "member": {
      "kind": "attachment",
      "accepts": { "mime": ["application/pdf"] }
    },
    "grouping": { "mode": "each" }
  },
  "validateSelection": {
    "require": {
      "selection": {
        "counts": { "attachments": { "min": 1 } },
        "allowMixed": false
      }
    },
    "select": { "policy": "input-member", "source": "selected" },
    "filters": [
      { "kind": "source-file-exists", "phase": "availability" }
    ]
  }
}

require.selection reads the original SelectionContext once. The selector produces ordered candidates, attachment MIME compatibility runs before filters, and inputs.grouping creates immutable top-level units.

Workflows Without Selected Items​

Use member.kind: "selection", grouping.mode: "all", the selection selector, and trigger.requiresSelection: false. The selector then produces the complete empty SelectionContext as the single member. Selection requirements remain active and must not make the empty selection impossible.

Declarative Candidate Filters​

{
  "validateSelection": {
    "select": { "policy": "generated-note-candidates" },
    "filters": [
      {
        "kind": "generated-note-kinds-absent",
        "phase": "availability",
        "noteKinds": ["digest"]
      }
    ]
  }
}

validateSelection owns candidate production and filtering. inputs owns the execution member and grouping. Hooks consume the prepared unit and must not reconstruct selection planning.

次のステップ​