develop-userscripts

使用者腳本的問題通常出在執行時期與中繼資料的邊界，而不是頁面邏輯。先選擇執行時期，事先宣告最小權限，然後在腳本實際執行的環境中進行除錯。

使用時機

使用此技能於：

• 撰寫或修正 Tampermonkey 或 ScriptCat 使用者腳本
• 除錯注入時機、缺少權限、CSP 繞過、更新檢查或 GM_* 行為
• 決定使用可攜式前景腳本或 ScriptCat 專屬的 @background / @crontab
• 使用 ==UserConfig== 加入設定 UI
• 打包 ScriptCat 的 ==UserSubscribe== 套件或準備相容 CloudCat 的腳本

請勿將此技能用於完整的瀏覽器擴充功能開發或使用者腳本管理器以外的一般瀏覽器自動化。

執行時期選擇

digraph userscript_runtime {
    "需要頁面 DOM 或頁面上下文？" [shape=diamond];
    "需要持久或排程工作？" [shape=diamond];
    "需要將多個腳本安裝為一個套件？" [shape=diamond];
    "可攜式前景腳本" [shape=box];
    "ScriptCat 背景或 crontab 腳本" [shape=box];
    "ScriptCat 訂閱套件" [shape=box];

    "需要頁面 DOM 或頁面上下文？" -> "可攜式前景腳本" [label="是"];
    "需要頁面 DOM 或頁面上下文？" -> "需要持久或排程工作？" [label="否"];
    "需要持久或排程工作？" -> "ScriptCat 背景或 crontab 腳本" [label="是"];
    "需要持久或排程工作？" -> "需要將多個腳本安裝為一個套件？" [label="否"];
    "需要將多個腳本安裝為一個套件？" -> "ScriptCat 訂閱套件" [label="是"];
    "需要將多個腳本安裝為一個套件？" -> "可攜式前景腳本" [label="否"];
}

前置檢查

• 確認管理器與瀏覽器。在 Manifest V3 瀏覽器上，ScriptCat 可能需要啟用 Allow User Scripts 或瀏覽器開發者模式，腳本才能執行。
• 在撰寫程式碼前決定是頁面腳本還是背景腳本。ScriptCat 背景腳本無法操作 DOM。
• 從中繼資料開始，而非實作：@match、@grant、@connect、@run-at 以及任何更新網址。
• 一般頁面腳本優先使用可攜式 ==UserScript== 模式。僅在所需行為確實需要時，才切換為 ScriptCat 專屬標頭。

工作流程

1. 先選擇執行時期與中繼資料。
2. 宣告符合任務的最小權限範圍。
3. 根據所選的執行時期進行實作。
4. 在程式碼實際執行的環境中除錯。
   • 前景腳本：頁面主控台加上管理器日誌。
   • ScriptCat 背景腳本：先執行日誌，然後使用 background.html 進行真實環境除錯。
5. 使用正確的更新模型發布。
   • 一般腳本：保持 @version 準確，並僅在需要時加入 @updateURL 或 @downloadURL。
   • 訂閱套件：使用 ==UserSubscribe==、HTTPS 網址，以及訂閱層級的 @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。
• 將 @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