フック

フック（Hooks）を使うと、生成パイプライン上のイベントに応じてスクリプトを実行できます。コンテキストの変更、レスポンスの加工、生成の制御などが可能になります。フックは、引数を 1 つのオブジェクトとして受け取ります。

フックは api.v1.hooks.register で登録します。フック名とコールバック関数を渡すと、対応イベント発生時にコールバックが呼ばれます。1 つのスクリプトにつき、同じフック名のコールバックは 1 つだけ登録できます（同じフックを再登録すると置き換えられます）。

利用できるフック

onGenerationRequested

ユーザーがテキスト生成を実行したとき、最初に呼ばれるフックです。まだ生成は開始されておらず、コンテキストも構築されていません。生成を止めて独自フローに切り替えたり、後続フックのための準備をしたりできます。このタイミングでの生成設定の変更は、これから行われる生成に反映されます。

onBeforeContextBuild

コンテキスト構築の直前に呼ばれます。生成時だけでなく、コンテキストビューアーのオープンなど、他の理由でもコンテキストは構築されます。dryRun パラメータで、生成に使われるコンテキストかどうかを判別できます。ロアブック、メモリなどのコンテキスト要素を一時的に変更/無効化して、構築に反映させたいときに便利です。

onContextBuilt

コンテキストが構築されるたびに呼ばれます（生成時とは限りません）。dryRun で用途を判別できます。生成に使われるメッセージ配列を、返り値として差し替えることでコンテキストを改変できます。

注意：このフックは、OpenAI 互換の completions エンドポイントを使うモデルで生成する場合にのみ発生します。

onResponse

生成リクエストのレスポンスデータを受信したときに呼ばれます。返り値として変更後のテキストを返すことで、エディターに入る内容を加工できます。必要なら token id や logprobs も差し替え可能です（エディター側の logprobs 機能を維持したい場合など）。

text / logprobs / tokenIds はいずれも配列で渡され、同じ index の要素同士が対応します。

ストリーミングが有効な場合、1 回の生成につき onResponse が複数回呼ばれます。スクリプトを書くときは、基本的に「常にストリーミングされる」と想定して扱うのがおすすめです。最後の呼び出しでは final が true になります（ただし、生成エラー時など final が来ない場合もあります）。

応答の一部（または全部）を「まだ見ていない扱い」にして次回に持ち越したい場合、返り値オブジェクトの seenData を設定できます。数値を指定すると、その数だけが「既に見た」と扱われ、残りは次の onResponse で再送されます。final が true の場合は seenData に関わらず上流へ送られます。

注意：このフックは、OpenAI 互換の completions エンドポイントを使うモデルで生成する場合にのみ発生します。

onGenerationEnd

生成が正常終了したとき、またはキャンセルされたときに呼ばれます。呼び出し時点では生成は完全に終わっており、エディターはアンロックされ、生成ブロックも解除されています。

onScriptsLoaded

すべてのスクリプトが読み込まれて初期化された後、1 回だけ呼ばれます。トップレベルで実行すると失敗しやすい処理（例：buildContext の呼び出しなど）は、ここで行うのがおすすめです。

onLorebookEntrySelected

ロアブックでエントリまたはカテゴリが選択されるたびに呼ばれます。選択されたエントリ/カテゴリの id が渡されます。主に、選択対象に応じて lorebookPanel の UI 拡張を更新したいときに使います。

onTextAdventureInput

テキストアドベンチャーの入力欄から送信されたときに呼ばれます。返り値としてテキストを変更でき、空文字を返すと何も追加しないようにできます。stopGeneration を true にすると生成を停止できます。

onHistoryNavigated

undo/redo/retry/履歴ノードへのジャンプなど、ユーザーまたはスクリプトがドキュメント履歴を移動したときに呼ばれます。履歴変化に合わせた状態の巻き戻し/更新などに使えます。

onDocumentConvertedToText

ドキュメントがテキスト形式へ変換されるたびに呼ばれます（多くは生成コンテキスト構築のため）。返り値としてセクションを変更し、コンテキスト用テキストを加工できます。reason には変換理由（例：‘context’）が入ります。

フックの実行順

フックは「ユーザースクリプト」画面に表示されている順序で実行されます。アカウントスクリプトが先に順番に実行され、その後に ストーリースクリプトが順番に実行されます。

フック伝播の制御

stopFurtherScripts

stopFurtherScripts を true にすると、このスクリプト以降のスクリプトに対してフックが呼ばれなくなります。

stopGeneration

onGenerationRequested / onContextBuilt / onResponse では、stopGeneration を true にすると生成を即座に停止/キャンセルできます。その場合、どのスクリプトについても以降のフックは呼ばれません。

参考