develop-userscripts

Userscript の問題は通常、ページロジックではなく、ランタイムとメタデータの境界で発生します。ランタイムを最初に選択し、必要な最小限の権限を事前に宣言した上で、スクリプトが実際に動作する環境でデバッグしてください。

使用する場合

このスキルは以下の場合に使用してください:

• Tampermonkey または ScriptCat の userscript を記述または修正する
• インジェクションのタイミング、権限不足、CSP 対策、更新チェック、または GM_* の動作をデバッグする
• ポータブルなフォアグラウンドスクリプトと ScriptCat 専用の @background または @crontab のどちらを使うか決定する
• ==UserConfig== でコンフィグ UI を追加する
• ScriptCat の ==UserSubscribe== バンドルをパッケージ化するか、CloudCat 互換スクリプトを準備する

ブラウザ拡張機能の完全な開発や、userscript マネージャー以外の一般的なブラウザ自動化には使用しないでください。

ランタイムの選択

digraph userscript_runtime {
    "Need page DOM or page context?" [shape=diamond];
    "Need persistent or scheduled work?" [shape=diamond];
    "Need to install many scripts as one package?" [shape=diamond];
    "Portable foreground script" [shape=box];
    "ScriptCat background or crontab script" [shape=box];
    "ScriptCat subscription package" [shape=box];

    "Need page DOM or page context?" -> "Portable foreground script" [label="yes"];
    "Need page DOM or page context?" -> "Need persistent or scheduled work?" [label="no"];
    "Need persistent or scheduled work?" -> "ScriptCat background or crontab script" [label="yes"];
    "Need persistent or scheduled work?" -> "Need to install many scripts as one package?" [label="no"];
    "Need to install many scripts as one package?" -> "ScriptCat subscription package" [label="yes"];
    "Need to install many scripts as one package?" -> "Portable foreground script" [label="no"];
}

プリフライト

• マネージャーとブラウザを確認してください。Manifest V3 ブラウザでは、スクリプトが実行される前に ScriptCat が Allow User Scripts またはブラウザ開発者モードを必要とする場合があります。
• コードを書く前に、ページスクリプトとバックグラウンドスクリプトのどちらかを決定してください。ScriptCat バックグラウンドスクリプトは DOM に触れることができません。
• 実装ではなくメタデータから始めてください: @match、@grant、@connect、@run-at、および任意の更新 URL。
• 通常のページスクリプトにはポータブルな ==UserScript== パターンを使用してください。ScriptCat 専用ヘッダーに切り替えるのは、リクエストされた動作が実際にそれらを必要とする場合のみです。

ワークフロー

1. ランタイムとメタデータを最初に選択します。
2. タスクに適合する最小限の権限を宣言します。
3. 選択したランタイムに対して実装します。
4. コードが実際に動作する場所でデバッグします。
   • フォアグラウンドスクリプト: ページコンソールおよびマネージャーログ。
   • ScriptCat バックグラウンドスクリプト: 実行ログを最初に確認し、その後、実際の環境でのデバッグのために background.html を使用します。
5. 正しい更新モデルで公開します。
   • 通常のスクリプト: @version を正確に保ち、必要な場合にのみ @updateURL または @downloadURL を追加します。
   • サブスクリプションバンドル: ==UserSubscribe==、HTTPS URL、およびサブスクリプションレベルの @connect を使用します。

クイックリファレンス

目的	デフォルトの選択	注意点
ページ UI、DOM スクレイピング、ページパッチ	ポータブル ==UserScript==	@match、@grant、@run-at、CSP に敏感なインジェクション
クロスオリジン API アクセス	GM_xmlhttpRequest (明示的な @connect 付き)	ホストの不足、Cookie 動作の差異、ユーザー認可
長時間実行ワーカー	ScriptCat @background	DOM なし、非同期作業の場合は Promise を返す必要あり
スケジュール済みタスク	ScriptCat @crontab	最初の @crontab のみ有効、5 フィールド cron を優先、間隔の重複を回避
ユーザー編集可能な設定	==UserConfig== と GM_getValue	ブロックの配置と group.key ネーミング
サイレントバンドルインストールと更新	==UserSubscribe==	HTTPS、user.sub.js、サブスクリプション connect が子スクリプトをオーバーライド

よくある間違い

• スクリプトが実際に使用する API の @grant が不足している。
• GM_xmlhttpRequest または GM_cookie で使用されるホストの @connect が不足している。
• @include を通常のホスト対象のデフォルトとして @match より良いと考えている。
• ScriptCat バックグラウンドまたは cron スクリプト内で DOM API を使用している。
• 非同期 GM 作業が真に完了する前に ScriptCat バックグラウンドスクリプトから戻っている。
• ==UserScript== と ==UserSubscribe== パッケージング概念を混在させている。
• ==UserConfig== を間違った場所に配置したり、group.key 名なしでコンフィグキーを読み取っている。
• Tampermonkey と ScriptCat のストレージ、通知、またはリクエスト動作が同じであると仮定している。

参考資料

• references/metadata-and-api-map.md
• references/scriptcat-extensions.md