develop-userscripts

ユーザースクリプトの問題は、ページのロジックではなく、実行環境とメタデータの境界で発生することが多いです。まず実行環境を選び、必要最小限の権限をあらかじめ宣言してから、スクリプトが実際に動作する環境でデバッグしてください。

使用する場面

次のような場合に、このスキルを使用してください。

• Tampermonkey または ScriptCat のユーザースクリプトを作成、修正する場合
• 挿入タイミング、権限不足、CSP の回避策、更新チェック、または GM_* の動作をデバッグする場合
• 移植性のあるフォアグラウンドスクリプトと、ScriptCat 専用の @background または @crontab のどちらを使うか判断する場合
• ==UserConfig== を使って設定 UI を追加する場合
• ScriptCat の ==UserSubscribe== バンドルをパッケージ化する場合、または CloudCat 互換スクリプトを準備する場合

フル機能のブラウザー拡張機能の開発や、ユーザースクリプトマネージャー以外での一般的なブラウザー自動化には、このスキルを使用しないでください。

実行環境の選択

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 へのアクセス	明示的な @connect を指定した GM_xmlhttpRequest	ホストの指定漏れ、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 が不足している。
• 一般的なホスト指定では、@match より @include のほうが適切だと考える。
• ScriptCat のバックグラウンドスクリプトや cron スクリプト内で DOM API を使用する。
• 非同期の GM 処理が本当に完了する前に、ScriptCat のバックグラウンドスクリプトから戻る。
• ==UserScript== と ==UserSubscribe== のパッケージ化の概念を混同する。
• ==UserConfig== を誤った場所に配置したり、group.key 形式の名前を使わずに設定キーを読み込んだりする。
• Tampermonkey と ScriptCat で、ストレージ、通知、リクエストの挙動が同一だと思い込む。

References

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