sillytavern-runtime-debug

SillyTavern ランタイムデバッグ

共通のコミュニケーション

TW の平易な表現とガイダンスのルールを適用してください。用語は初出時に説明し、ユーザーが選択した新人／入门／熟练／老手のレベルを維持してください。また、どのレベルでも必要な変更やバグについて説明してください。Soul モードや文章モードによって、この基本ルールが無効になることはありません。

プラグインのランタイム

この Skill がプラグイン、クラウドホスト、またはリモートマシンで実行される場合は、開始時にプラグイン実行契約を読み、ホスト固有のコマンドを実行する前に、ホスト、ツール、永続化に関する確認事項を適用してください。この Skill の対象範囲、認可、受け入れ条件を維持してください。

関連するホストやデプロイのガイダンスには、sillytavern-runtime-debug ルートで $consult-tavernweave-library を使用してください。書き込みやホストの変更を行う前に A0 を追加し、参照したガイドの助言と、名前を指定した実際の SillyTavern インスタンスから収集した証拠を明確に分けてください。

実際の対象 SillyTavern インスタンスから得た証拠をもとに、ランタイムのバグを解決してください。オフラインの HTML プレビューは開発の参考にはなりますが、インポートの挙動、メッセージのレンダリング、拡張機能の注入、iframe へのアクセス、イベントのタイミング、永続化、MVU の更新を立証するものではありません。

ワールドブックの選択と、状態から次のリクエストへの挙動については、 E07 の分離チェックと観察記録を使用してください。 まずプレーンテキストのターンから始め、選択したテンプレート／MVU／UI のケースだけを追加してください。 同梱の静的フィクスチャとレシート検証ツールだけでは、実際のホストでの成功を立証できません。

ランタイムの境界を担当する

ライブ環境での再現、ブラウザーの実行、ランタイムからの直接的な証拠の取得、受け入れの完了を担当してください。埋め込み UI の設計やソースの実装は担当しないでください。

ライブテストで UI ソースの欠陥が見つかった場合は、最小限の再現手順、失敗しているレイヤー、必要な受け入れ基準を sillytavern-embedded-ui に報告してください。再ビルドされた成果物を受け取ったら、その正確なリビジョンを確認し、必要に応じて再インポートして、同じランタイムテストマトリクスを再開してください。UI Skill のオフラインまたは静的な証拠だけで、ランタイムの受け入れを完了してはいけません。

ドライバーの機能契約を使用する

必要な機能を安全に提供できるブラウザードライバーを使用してください。アプリ内ブラウザー、接続済みのユーザーブラウザー、Playwright、WebDriver、CDP のいずれでも構いません。ワークフローを特定の製品やツールのプレフィックスに固定しないでください。

開始前に、ドライバーがテストに必要な操作を実行できることを確認してください。

• 対象の SillyTavern ページを開く、または接続する。
• トップドキュメントを調査し、フレームを列挙する。
• フレームのコンテキストとともに、コンソールのエラーと警告を収集する。
• トップドキュメントと、選択した同一オリジンのフレームで、読み取り専用の JavaScript を評価する。
• 属性、テキスト、ジオメトリ、計算済みスタイルを調査する。
• クリック、入力、選択、スクロール、キー入力を行う。
• ビューポートサイズを変更する、または狭いレイアウトをエミュレートする。
• 視覚的な証拠が有用な場合は、スクリーンショットを撮影する。

機能が不足している場合は、テストを調整するか、その不足を明記してください。スクリーンショットがコンソールの状態を証明する、あるいはトップフレームでの評価が iframe の状態を証明するかのように装ってはいけません。

リアルタイム開発チェーンを検証する

プロジェクトでソースウォッチャーと Tavern Helper のリアルタイム編集を併用している場合は、各リンクを個別に検証します。

source edit -> successful rebuild -> expected development output changed
            -> listener connected -> intended iframe reloaded -> new behavior observed

sillytavern-card-pipeline から、ウォッチャーのコマンド、出力先、ビルド成功の記録を取得します。インストールされている Tavern Helper のバージョンから、リスナーの制御方法と接続状態を確認してください。別のバージョンの設定ラベル、URL、ポートを前提にしないでください。続いて、次の操作を行います。

1. 現在の出力の識別情報と対象 iframe の識別情報を記録する。
2. ソース編集後、ビルドが正常に完了するまで待つ。
3. リスナーによって再読み込みされたことを確認する。そうでない場合は、明示されている手動での更新／再バインド手順を実行する。
4. 成果物の識別情報、フレームの置き換わり、プロジェクトが提供するリビジョンマーカー、またはその他の直接的なシグナルを使って、ビルド済みの出力が現在実行されていることを確認する。
5. 再読み込み後のランタイムから、コンソール、DOM、操作、データの証拠を収集する。

コンパイルに失敗した場合、またはリスナーが切断された場合、ページでは最後にビルドに成功した成果物が引き続き実行されている可能性があります。新しいソースをテスト済みとして扱わず、古い成果物が実行されている可能性があることを報告してください。ライブリロードは反復を高速化しますが、リリース受け入れテストの代わりにはなりません。選択したテストマトリクスを、実際に本番用にビルドした成果物に対して、新規インポート、チャット、またはバインドを行ったうえで再実行してください。バインドが必要かどうかは、機能のライフサイクルに従って判断します。

テスト境界を定める

再現する前に、次の情報を記録します。

• SillyTavern のバージョンと関連する拡張機能のバージョン。
• 対象のキャラクター／カードの識別情報と成果物のリビジョン。
• 宣言されている主要なカードタイプ、機能フラグ、ランタイム依存関係の一覧、選択されているリージョン別ローダー。
• 現在のチャットの識別情報、選択中の開始時スワイプ、メッセージ数。
• ブラウザー、ビューポート、ズーム、カラースキーム、デバイスクラス。
• 成果物が新たにインポートされたものか、すでに存在していたものか。
• チャット、ワールドブック、変数、設定、アカウントの状態を変更する可能性がある操作。

インストール先のパス、ポート、起動設定、アカウントの状態、キャラクターファイルの場所、iframe ID を前提にしないでください。実行中の環境から特定してください。API キー、Cookie、認証データ、非公開の拡張機能設定をログに記録しないでください。

変更する前に再現する

1. 状態の保持が重要な場合は、ユーザーから報告された状態を起点にします。
2. 操作前に、最小限のコンソール基準データを記録します。
3. 再現可能な操作を一度に一つだけ実行します。
4. 表示結果、DOM の状態、計算済みスタイル、フレームの状態、新たに出力されたコンソール情報を記録します。
5. もう一度繰り返し、決定的な不具合とタイミングや古い状態に起因する挙動を区別します。

インポートに依存するコードでは、ビルド済みの正確な成果物が読み込まれていることを確認します。SillyTavern のインポート UI、またはユーザーが許可した別の可逆な手段を優先してください。インストール先のデータディレクトリ内のファイルを上書きする方法を、デバッグの標準手順にしないでください。

新しい成果物やバインドスクリプトを反映させる場合、その機能が既存チャットの再バインドを明示的にサポートしていない限り、新しいチャットでテストしてください。古いメッセージの DOM、キャッシュされたスクリプト、開始ページのガード、永続化された設定によって、結果が隠れてしまう可能性があります。

ランタイムを把握する

セレクターを推測するのではなく、フレームと所有関係を簡潔に整理します。

top SillyTavern document
  -> chat message container and rendered message body
  -> message-owned iframe, if present
  -> long-lived Tavern Helper script iframe, if present
  -> card-created nested iframe, if present
  -> host-mounted control panel or popup, if present

各フレームについて、安定した識別根拠、オリジン、アクセス可否、所有するメッセージまたはスクリプト、関連するグローバル変数を記録します。セマンティックセレクターまたは data-* セレクターを優先してください。生成された ID、メッセージインデックス、フレームの順序は不安定なものとして扱います。

同一オリジンへのアクセスには、ガードを設けてください。

function readableFrame(frame) {
  try {
    return frame.contentWindow && frame.contentDocument
      ? frame.contentWindow
      : null;
  } catch {
    return null;
  }
}

クロスオリジンでアクセスできない場合は、対応していればドライバーの対象フレームを切り替えるか、文書化されたブリッジを使用してください。調査を簡単にするために、サンドボックスやセキュリティ制御を弱めないでください。

レイヤーごとに診断する

最も早く観測できる入力から最終的な UI まで、不具合が発生しているチェーンをたどります。

artifact/import
  -> card fields and regex
  -> message text and rendering
  -> Tavern Helper or extension frame
  -> optional global initialization
  -> variable/worldbook/message data
  -> DOM binding and event refresh
  -> layout, interaction, and persistence

インポートと成果物

• インポートしたキャラクターの名前、バージョン、ペイロードのリビジョンが想定どおりであることを確認します。
• インポートした成果物から、キャラクター固有の正規表現と Tavern Helper スクリプトを再度一覧化します。必須のスキーマ、ローダー、バインディング、ワールドブック、ホスト拡張機能がすべて存在し、宣言されたポリシーに従って有効になっていることを確認します。
• 地域別の代替グループで、意図したメンバーが有効になっており、意図しない二重有効化がないことを確認します。
• 初回メッセージ、別の挨拶、またはマウントの動作をテストする際は、新しいチャットを使用します。
• ビルドの失敗と、古いインポート済み成果物を区別します。

ランタイム依存関係とリモートローダー

• すべての host_required 拡張機能または機能を、適切なフレームとスコープで調べます。スクリプトがパッケージに含まれていても、ホストが存在する証拠にはなりません。
• カードで指定された、パッケージに含まれる国内版／グローバル版 MVU Zod スクリプトをすべて確認し、有効状態がマニフェストまたはパッケージ化されたベースラインと一致することを確認します。次に、選択したスクリプトのリモートモジュールとスキーマ登録ヘルパーが、実際に Tavern Helper のコンテキストで実行されることを確認します。パッケージを無断でインストールしたり、別のプロバイダーに置き換えたりしないでください。
• remote_runtime では、要求された URL／ref、プライマリ／フォールバックの試行、ネットワーク障害、モジュール例外、期待される準備完了機能を記録します。
• HTTP の成功は、あくまで転送が成功した証拠として扱います。モジュールが実行され、期待されるグローバル変数、登録、DOM マーカー、イベント、またはその他の準備完了シグナルが公開されたことを確認します。
• 国内版／グローバル版などの regional_alternative ローダーでは、選択したメンバーと宣言されたフォールバックをテストします。一方を通すためだけに両方を有効にしないでください。
• development_only パッケージをプレイヤーのセットアップやランタイム障害の報告に含めないでください。

コンソールと例外

• トップドキュメントと関連フレームのエラーおよび警告を記録します。
• 下流で発生した null 参照のノイズだけでなく、最初の根本原因となるエラーを記録します。
• メッセージ、スタック、フレーム、時刻を基準に、繰り返されるフレームフックの出力を重複排除します。
• 拒否された Promise、CSP の失敗、ネットワークエラー、構文エラーを保持します。

DOM とスタイル

• 実際の対象要素、その祖先要素、所属するフレームを調べます。
• 生のクラス名トークン、安定した属性、計算済みの display／position／サイズ／overflow、バウンディングボックスを比較します。
• SillyTavern のメッセージサニタイズやクラス名の名前空間化によって、静的コンテンツが変更されたか確認します。
• ホストのサニタイズ処理後に注入された DOM には、静的なメッセージ HTML と同じクラス変換が適用されない場合があることに注意してください。
• 長文、空のデータ、非表示状態、入れ子のスクロール、ポップアップのクリッピングをテストします。

ランタイムデータ

• オプションのグローバル変数は、文書化された初期化手順を通じて待機します。
• 意図された正確なスコープ（現在のメッセージ、最新のメッセージ、チャット、キャラクター、スクリプト、またはグローバル）から読み取ります。
• MVU では、対象のメッセージ階層にある stat_data を調べ、書き込みが完了したと決めつけずにライフサイクルイベントを監視します。
• ワールドブックでは、変更後に対象のブックとバインディングを再度読み込みます。トースト通知だけで成功と判断しないでください。

操作

• メソッドを直接呼び出すだけでなく、実際のポインター操作やキーボード操作をテストします。
• フォーカスの移動、無効状態、二重送信の防止、Escape／閉じる操作、入力内容の保持を確認します。
• チャットの切り替え、スワイプ、編集、再レンダリングの後に、リスナーやシングルトンのマウントが消えたり重複したりしていないことを確認します。

可逆的なランタイムプロトタイプを使用する

一時的な DOM または JavaScript のプロトタイプは、原因の切り分けに役立つことがあります。明確に診断目的に限定してください。

• 変更を小さくし、元に戻せるようにします。
• 注入または変更した内容を正確に記録します。
• テストに必要であり、ユーザーが許可した場合を除き、永続的なユーザーデータを書き込まないでください。
• 一時的な ID、リスナー、スタイル、値を削除するか、ページを再読み込みします。
• プロトタイプを納品する修正として扱わないでください。

ソースを修正した後は、成果物を再ビルドして再インポートし、プロトタイプコードが存在しないクリーンなランタイム状態から再現します。

長時間かかる操作とタイムアウトへの対処

長時間かかる処理は、操作フェーズと観測フェーズに分けます。

1. まず操作を1つ実行します。
2. ドライバーの呼び出しが戻るか、タイムアウトするまで待ちます。
3. チャットの識別情報、メッセージ数、マウントの有無、準備状態など、負荷の低い読み取り専用のマーカーを確認します。
4. 成功したかどうかは、元の呼び出しの戻り値だけでなく、観測された状態から判断します。

副作用が成功した後に、ドライバーがタイムアウトすることがあります。逆に、呼び出しが正常に完了しても、レンダリングや永続化の完了が保証されるわけではありません。

受け入れマトリクス

変更に該当する行を選び、合格／不合格の根拠を記録します。

項目	必要な根拠
インポート	想定したアーティファクトが選択され、そのスクリプト／正規表現／バインディングが存在する
依存関係	ホスト機能、埋め込み要件、リモート実行、地域の選択が台帳と一致する
新規チャット	手動で注入しなくても、最初のメッセージまたは初期マウントが表示される
コンソール	新たな原因となるエラーや未処理の拒否がない
DOM	要素数、所有関係、属性が正しく、マウントが重複していない
スタイル	計算後の寸法、表示、オーバーフロー、クラス変換が正しい
インタラクション	クリック、キーボード、フォーム、閉じる操作、繰り返し操作で意図した状態になる
データ	正しいフロア／スコープが変更され、再読み込みで永続化を確認でき、無関係なデータは維持される
ライフサイクル	再読み込み、スワイプ、編集、チャット切り替え、再レンダリングで動作が漏れたり失われたりしない
レスポンシブ	狭いビューポートと広いビューポートの両方で動作し、長い CJK テキストやコントロールが切れない
セキュリティ	信頼できないテキストが実行されず、シークレットやプライベートな設定が公開されない

ランタイムの作業は、ソースからビルドしたアーティファクトが、選択した実際の SillyTavern チェックに合格した場合にのみ完了とします。オフラインテストは補足根拠として報告に記載し、実環境での確認の代わりにしないでください。

メッセージコンテンツページと MVU 表示

メッセージコンテンツページでは、メッセージテキスト、マウント、解析、表示内容を通じて、実際の出力ルールと受信者を追跡します。前後の文章、境界の欠落や不完全さ、項目の繰り返し、モデルが生成した不活性なテキストのケースを選択します。ボタンがローカルナビゲーションなのか、許可された送信なのかを確認します。メッセージの作成は成功しても生成に失敗した場合は、再試行によってプレイヤーのメッセージが重複しないことを確認します。

MVU ステータスバーでは、実際のフロア／スコープ、イベント駆動の更新、ライフサイクルのクリーンアップを確認します。表示される 0、false、空、無効な値を、それぞれのフィールドの意味と照合します。コレクションの変更や選択項目の削除を確認し、適切な表示状態を維持します。読み取り専用の更新でゲーム状態を初期化、修復、書き込みしてはいけません。宣言されたテスト用スコープと許可されたデータを使用し、実際のセーブデータを変更してテストケースを作らないでください。

変更されたアーティファクトに関係するケースのみを使用します。共有のフロントエンド品質基準に照らして観測したレイアウトを記録します。ただし、参照サイトとの比較をホスト環境での受け入れ確認として扱わないでください。プロトコルまたは UI の不具合は実装担当者に差し戻します。保守対象のアーティファクトの代わりに、コンソール上のコピーへパッチを適用してはいけません。

レポート

以下を記載します。

• 最小限の再現手順
• 失敗したレイヤーと根本原因、および直接的な根拠
• バージョン、アーティファクトの識別情報、ブラウザー、ビューポート
• 検出されたカードの種類と機能、および埋め込み、ホスト、リモート、地域別、オプション、開発専用の依存関係の状態
• UI ソースの変更が必要だった場合は、実装担当者への引き継ぎと、再ビルド／インポート後のアーティファクトの状態
• 合格したチェック
• デバイス、アカウント、拡張機能、ドライバーの機能が利用できないため、引き続き実施できないチェック