ロアブック API

ロアブック API は、ロアブックのエントリとカテゴリをプログラム的に管理するための API です。スクリプトから、ロアブック内容の作成・読み取り・更新・削除ができます。エントリ/カテゴリの作成・変更・削除を行うメソッドは lorebookEdit 権限が必要です。

ロアブックの構造

エントリ（Entries）

ロアブックエントリは、アクティベーションキーに一致したときに、生成コンテキストへ挿入される情報です。各エントリには、いつ/どうやって発動するかを制御する設定があります。

エントリは一意の ID で識別されます。ID はスクリプト側で自由に指定できますが、重複を避けるため api.v1.uuid() で生成するのがおすすめです。同じ ID のエントリを 2 つ作ろうとするとエラーになります。

カテゴリ（Categories）

カテゴリは、エントリを整理するための入れ物です。ロアブック UI 上で関連項目をまとめて見やすくします。

カテゴリも一意の ID で識別されます。こちらも api.v1.uuid() の利用がおすすめです。同じ ID のカテゴリを 2 つ作ろうとするとエラーになります。

ロアブック内容を読む

全エントリを取得

api.v1.lorebook.entries で全エントリを取得できます。

let allEntries = await api.v1.lorebook.entries();
for (let entry of allEntries) {
  api.v1.log(`Entry: ${entry.displayName}`);
}

特定エントリを取得

ID 指定で 1 件取得するには api.v1.lorebook.entry を使います。

let entry = await api.v1.lorebook.entry('entry-id-here');
if (entry) {
  api.v1.log(`Found entry: ${entry.displayName}`);
}

全カテゴリを取得

api.v1.lorebook.categories で全カテゴリを取得できます。

let allCategories = await api.v1.lorebook.categories();
for (let category of allCategories) {
  api.v1.log(`Category: ${category.name}`);
}

特定カテゴリを取得

ID 指定で 1 件取得するには api.v1.lorebook.category を使います。

let category = await api.v1.lorebook.category('category-id-here');
if (category) {
  api.v1.log(`Found category: ${category.name}`);
}

ロアブック内容を作成する

エントリを作成

新しいエントリを作成するには api.v1.lorebook.createEntry を使います。ID を指定しない場合は自動生成されます。

let entryId = await api.v1.lorebook.createEntry({
  text: 'Galena, the Witch of the Tower. Galena\'s eyes are obscured by a translucent ribbon...',
  displayName: 'Galena, the Witch of the Tower',
  keys: ['Galena', 'witch', 'ribbon', 'tower'],
  enabled: true
});
api.v1.log(`Created entry with ID: ${entryId}`);

カテゴリを作成

新しいカテゴリを作成するには api.v1.lorebook.createCategory を使います。ID を指定しない場合は自動生成されます。

let newCategory = await api.v1.lorebook.createCategory({
  name: 'Locations',
  enabled: true
});
api.v1.log(`Created category with ID: ${newCategory.id}`);

ロアブック内容を更新する

エントリを更新

既存エントリを更新するには api.v1.lorebook.updateEntry に、エントリ ID と更新したいフィールドを渡します。

await api.v1.lorebook.updateEntry('entry-id-here', {
  text: 'Galena, the Retired Witch of the Tower. Galena now...',
  enabled: false
});

指定したフィールドのみ更新され、他は変更されません。

カテゴリを更新

カテゴリを更新するには api.v1.lorebook.updateCategory を使います。

await api.v1.lorebook.updateCategory('category-id-here', {
  name: 'World Locations',
  enabled: false
});

ロアブック内容を削除する

エントリを削除

api.v1.lorebook.removeEntry でエントリを削除できます。

await api.v1.lorebook.removeEntry('entry-id-here');

カテゴリを削除

api.v1.lorebook.removeCategory でカテゴリを削除できます。

await api.v1.lorebook.removeCategory('category-id-here');

カテゴリを削除しても、その中のエントリは削除されません。カテゴリ未所属になります。

選択中エントリに応じた処理

ロアブックでのエントリ/カテゴリ選択は onLorebookEntrySelected フックで受け取れます。選択に応じた UI 表示や処理に便利です。

api.v1.hooks.register('onLorebookEntrySelected', async ({ entryId, categoryId }) => {
  if (entryId) {
    let entry = await api.v1.lorebook.entry(entryId);
    api.v1.log(`Selected entry: ${entry?.displayName}`);
  } else if (categoryId) {
    let category = await api.v1.lorebook.category(categoryId);
    api.v1.log(`Selected category: ${category?.name}`);
  }
});

参考