develop-userscripts

用户脚本通常不是在页面逻辑上出问题，而是在运行时和元数据的边界上出问题。先选择运行时，提前声明最少权限，然后在脚本实际运行的环境中调试。

适用场景

在以下情况下使用此技能：

• 编写或修复 Tampermonkey 或 ScriptCat 用户脚本
• 调试注入时机、缺失权限、CSP 绕过方案、更新检查或 GM_* 行为
• 在可移植的前台脚本与仅限 ScriptCat 的 @background 或 @crontab 之间做出选择
• 使用 ==UserConfig== 添加配置界面
• 打包 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。
• 认为普通主机匹配时 @include 比 @match 更适合作为默认选择。
• 在 ScriptCat 后台脚本或定时任务脚本中使用 DOM API。
• ScriptCat 后台脚本在异步 GM 操作真正完成前就返回。
• 混淆 ==UserScript== 与 ==UserSubscribe== 的打包概念。
• 将 ==UserConfig== 放在错误位置，或读取配置键时未使用 group.key 名称。
• 认为 Tampermonkey 和 ScriptCat 的存储、通知或请求行为完全相同。

References

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