[CodFrm]

Checklist / 检查清单

• Fixes mentioned issues / 修复已提及的问题
• Code reviewed by human / 代码通过人工检查
• Changes tested / 已完成测试

N/A — 无关联 issue。扩展运行时代码没有改动；附带的两个 Node 工具脚本有单测，验证方式见下方「验证」。

背景

AI 编码代理（Claude Code、Codex 等）写脚本猫脚本时，常按 Tampermonkey 的习惯来写，在脚本猫特有的地方出错：后台/定时脚本没有页面、Promise 生命周期、CATRetryError、once cron、==UserConfig==、@grant none 的语义等。sctl 已经能把脚本装进用户的真实浏览器，但代理还缺一套「侦察 → 编写 → 安装 → 验证 → 迭代」的固定流程，也缺一个能在安装前发现常见错误的工具。

本次改动

新增 skills/scriptcat-userscript/。这是一个 Agent Skill，不进入扩展构建产物。

• SKILL.md：入口，包括选脚本类型、脚本骨架（与「新建脚本」模板一致）、按权限/时机/存储/后台/用户配置分组的易错规则，以及有 sctl 和没有 sctl 两种情况下的验证分流。
• references/api.md：按 src/pkg/utils/script_compat.ts 的 grant 白名单列出已实现的 GM / CAT API，以及与 TM 的差异。
• references/background.md：Promise 生命周期、CATRetryError 重试、cron 与 once 扩展、日志。
• references/userconfig.md：==UserConfig== 格式，类型推断按 UserConfigPanel 的实际行为描述。
• references/dev-loop.md：sctl 安装与验证流程，另有三节：
  • 本地热重载：装一次带 @require file:///… 的壳脚本，之后改本地文件、reload 页面即生效，不必每次审批。
  • 写之前先侦察页面：用 page snapshot / page eval 找选择器、试跑逻辑；用 debug network / debug request --body 找站点接口，改用 GM_xmlhttpRequest。
  • 后台脚本可观测：通过共享 @storageName 的临时探针页面脚本把值打到 console；用 disable/enable 或临时 crontab 触发运行。
• references/patterns.md：常用写法（等待元素、SPA 路由、菜单开关持久化、跨域请求、样式注入、本地化、后台脚本 Promise + 重试）。
• scripts/check.mjs：零依赖静态检查。能发现未声明 grant 的 API 调用、@grant none 下使用 GM API 或 unsafeWindow、cron/once 写法错误、多行 @crontab、后台脚本使用标签页 API、请求的域名缺 @connect 等问题；有 error 时以 exit 1 退出。
• scripts/stub.mjs：从本地脚本生成热重载用的壳脚本。
• vitest.config.ts：把 skills/**/*.test.mjs 加进 scripts（node 环境）测试项目。

已知限制

• 后台/定时脚本的验证优先用 sctl run / sctl logs，依赖 ✨ 新增 sctl run / sctl logs：触发后台/定时脚本运行并读取脚本运行日志 sctl#17 与 ✨ 外部接入：支持 sctl 触发后台/定时脚本运行并读取脚本运行日志 #1825。旧版 sctl 不认识 run，旧版脚本猫返回 METHOD_NOT_FOUND；遇到这两种情况，Skill 退回探针脚本等间接办法。建议在 ✨ 外部接入：支持 sctl 触发后台/定时脚本运行并读取脚本运行日志 #1825 和 sctl#17 之后合并本 PR。
• 脚本猫正式版不把 debug 级别的 GM_log 写入日志，Skill 已提示把需要读取的内容记到 info 及以上。
• API 描述是手工镜像的。check.mjs 内置的 grant 清单有单测对照 SUPPORTED_GRANTS 守卫；伴随注入表（DEPENDS，抄自 gm_api 的 depend 声明）没有自动守卫，修改时需要手工同步（README 已注明）。
• check.mjs 靠文本匹配找 API 调用（会先去掉注释和字符串），不做完整的 JS 解析。
• 热重载的时机没有在真实浏览器里验证：文件变化后，当次页面加载可能仍注入旧代码，文档写的是「再 reload 一次」。

建议审查重点

• SKILL.md 第 3 节和 background.md 中关于 @grant none、once、多行 @crontab、返回值语义的描述（这几处是对照代码修正过的）。
• check.mjs 的规则：哪些按 error 报、哪些按 warn 报。
• references/dev-loop.md 中 sctl 命令和退出码是否与 sctl v0.3.0 一致。

验证

基于 base 6c0459b8…head bef426d7，git diff --stat 只涉及 skills/scriptcat-userscript/ 下 11 个文件和 vitest.config.ts（1 行）。

• npx vitest run skills/scriptcat-userscript：30/30 通过。npx vitest run --project scripts：87/87 通过。
• npx eslint skills/scriptcat-userscript/scripts vitest.config.ts、npx prettier --check skills/scriptcat-userscript vitest.config.ts：通过。
• 冒烟：用两个故意写错的脚本跑 check.mjs，上述各类错误都报出来了，exit 1；stub.mjs 输出的头部保留原有元数据并追加 @require file:///…。
• 事实核对（对照 origin/main 源码，部分用一次性 vitest 探针实测，探针没有提交）：
  • @grant none 下 unsafeWindow 为 undefined（exec_script.ts:56 只注入 GM/GM_info）。
  • once 按 lastruntime 门控，运行开始时就写入，失败的运行也算一次（sandbox/runtime.ts:148,200）。
  • 每一行 @crontab 都会被注册（sandbox/runtime.ts:270）。
  • 正文总被包在 async function 里，所以「return not promise」分支不会触发。
  • @grant GM_xmlhttpRequest 不会带出 GM.xmlHttpRequest：grant.ts 只互换前缀，而且区分大小写。
• sctl 对齐：对照 sctl v0.3.0 的 docs/cli.md 与 skills/sctl（多实例 --scriptcat / SCRIPTCAT_AMBIGUOUS 退出码 3，tabs open --background 返回 {"tabId"}，edit --replace/--with）。
• 相对链接：skills/ 下全部链接和锚点都能解析。
• 隐私扫描：没有内网地址、个人邮箱或凭据。
• ad709853 只改了 Markdown：prettier 通过，skills/ 下相对链接都能解析。sctl run / sctl logs 的命令、参数、输出、退出码，以及 debug 级别不入库这一点，都来自 ✨ 外部接入：支持 sctl 触发后台/定时脚本运行并读取脚本运行日志 #1825 / sctl#17 的真实验证（隔离的 daemon 加无头 Chromium）。
• 未做：
  • 没有在真实浏览器里重跑 dev-loop 和热重载流程。
  • 完整的 tsc --noEmit 没跑：本地 worktree 的依赖缺 fake-indexeddb（migrate.test.ts），与本改动无关；vitest.config.ts 不在 tsconfig 范围内。

审查修复（2026-11-05）

又做了一轮独立审查，并对照代码订正：

• bef426d7：
  • 脚本列表只显示 运行中 / 错误 / 已停止 和下次运行时间；运行输出和错误要看“日志”页或 sctl logs。
  • @connect：脚本只要声明了任何 @connect，未列出的域名就会被拒绝，只有完全没写 @connect 时才会询问用户。
  • @grant none 下没有 CATRetryError。
  • 同名脚本在页面脚本和后台脚本之间切换类型会被拒绝。
  • 不写 @grant 也运行在沙盒里。
  • onurlchange 依赖 Navigation API。
  • GM_addElement 在 Firefox 下的 CSP 例外，与 api.md 保持一致。
  • sctl run 的输出文案和 run-in 报错；壳脚本示例；后台壳脚本用 sctl run 迭代（重新读取本地文件这一点来自代码，未在浏览器里验证）。
• 4ead49a5 check.mjs：
  • 修复对象键误报和关键字后正则字面量的漏报。
  • @match 通配时，不再把请求当成同域。
  • 某个文件读取失败后，继续检查其余文件。
  • 起子进程的命令行用例沿用 scripts/check-i18n.test.mjs 的 15 秒超时。

验证（head bef426d7）：Skill 测试 35/35 通过，eslint 和 prettier 通过，相对链接和锚点检查通过；两处误报/漏报都用探针复现过，修复后结果正确。