From 082557eff0268a9ffbbaea51b1cf525b6d5e4ac8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=8E=8B=E4=B8=80=E4=B9=8B?= <yz@ggnb.top>
Date: Fri, 30 Oct 2026 14:37:58 +0800
Subject: [PATCH 1/7] =?UTF-8?q?=F0=9F=93=9D=20=E6=96=B0=E5=A2=9E=20scriptc?=
 =?UTF-8?q?at-userscript=20Skill=EF=BC=9A=E6=8C=87=E5=AF=BC=20AI=20?=
 =?UTF-8?q?=E7=BC=96=E7=A0=81=E4=BB=A3=E7=90=86=E7=BC=96=E5=86=99=E9=A1=B5?=
 =?UTF-8?q?=E9=9D=A2/=E5=90=8E=E5=8F=B0/=E5=AE=9A=E6=97=B6=E8=84=9A?=
 =?UTF-8?q?=E6=9C=AC=EF=BC=8C=E5=B9=B6=E9=80=9A=E8=BF=87=20sctl=20?=
 =?UTF-8?q?=E5=AE=89=E8=A3=85=E4=B8=8E=E9=AA=8C=E8=AF=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- SKILL.md：选脚本类型、骨架、按权限/时机/存储/后台分组的易错规则，有无 sctl 两条验证路径
- references/api.md：按 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 install → 后台标签页 reload → debug console / page eval 验证 → 重装或 sctl edit 迭代；
  已在真实浏览器实测：用户脚本 console 可见、整文件 edit 生效、同 name+namespace 重装原地更新（uuid 不变）
---
 skills/scriptcat-userscript/README.md         |  30 ++++
 skills/scriptcat-userscript/SKILL.md          | 156 ++++++++++++++++++
 skills/scriptcat-userscript/references/api.md |  70 ++++++++
 .../references/background.md                  |  87 ++++++++++
 .../references/dev-loop.md                    |  95 +++++++++++
 .../references/userconfig.md                  |  61 +++++++
 6 files changed, 499 insertions(+)
 create mode 100644 skills/scriptcat-userscript/README.md
 create mode 100644 skills/scriptcat-userscript/SKILL.md
 create mode 100644 skills/scriptcat-userscript/references/api.md
 create mode 100644 skills/scriptcat-userscript/references/background.md
 create mode 100644 skills/scriptcat-userscript/references/dev-loop.md
 create mode 100644 skills/scriptcat-userscript/references/userconfig.md

diff --git a/skills/scriptcat-userscript/README.md b/skills/scriptcat-userscript/README.md
new file mode 100644
index 000000000..6846df2dd
--- /dev/null
+++ b/skills/scriptcat-userscript/README.md
@@ -0,0 +1,30 @@
+# scriptcat-userscript
+
+给 AI 编码代理（Claude Code、Codex 等）用的 Skill：指导编写、修改、调试脚本猫用户脚本——页面脚本（`@match`）、
+后台脚本（`@background`）、定时脚本（`@crontab`），并在接入 [sctl](https://github.com/scriptscat/sctl) 时
+把脚本装进用户的脚本猫、在真实浏览器里验证。
+
+## 结构
+
+| 文件 | 内容 |
+|---|---|
+| `SKILL.md` | 入口：选脚本类型、骨架、容易写错的规则、安装与验证的分流 |
+| `references/api.md` | 脚本猫实现的全部 GM / CAT API（按 grant 分组），以及与 Tampermonkey 的差异 |
+| `references/background.md` | 后台/定时脚本：Promise 生命周期、`CATRetryError` 重试、cron 与 `once` 扩展、日志 |
+| `references/userconfig.md` | `==UserConfig==` 用户配置格式 |
+| `references/dev-loop.md` | 用 sctl 安装 → 打开页面 → 看控制台 → 重装或 `sctl edit` 迭代的流程 |
+
+API 以 `src/types/scriptcat.d.ts` 和 `src/pkg/utils/script_compat.ts`（支持的指令与 grant 白名单）为准；
+修改这两处时同步检查本 Skill。sctl 本身的操作规范在 sctl 仓库的 `skills/sctl`，这里只引用、不重复。
+
+## 安装
+
+```sh
+ln -s "$(pwd)/skills/scriptcat-userscript" ~/.claude/skills/scriptcat-userscript
+ln -s "$(pwd)/skills/scriptcat-userscript" ~/.codex/skills/scriptcat-userscript
+```
+
+## 已知限制
+
+- sctl 无法触发后台/定时脚本运行，也读不到脚本猫的运行日志，这两类脚本只能由用户在脚本列表查看运行状态与
+  `GM_log` 输出。
diff --git a/skills/scriptcat-userscript/SKILL.md b/skills/scriptcat-userscript/SKILL.md
new file mode 100644
index 000000000..7cb323f61
--- /dev/null
+++ b/skills/scriptcat-userscript/SKILL.md
@@ -0,0 +1,156 @@
+---
+name: scriptcat-userscript
+description: "Write, fix and debug userscripts for ScriptCat (Tampermonkey-compatible): page scripts that run on matching sites (@match), background scripts that keep running without a page (@background) and scheduled scripts (@crontab); metadata, @grant and the GM_* / GM.* / CAT_* APIs, user config, retries. When the sctl CLI is connected, install the script into the user's ScriptCat and verify it in their real browser. Use whenever the user wants a userscript, 油猴脚本, 后台脚本, 定时脚本, a .user.js file or a ScriptCat script written, changed or debugged. Not for developing the ScriptCat extension itself, and not for managing installed scripts without changing their code (that is the sctl skill)."
+---
+
+# Writing ScriptCat userscripts
+
+ScriptCat runs Tampermonkey-style userscripts and adds two kinds of its own: background scripts and scheduled
+scripts, which run in the extension's background sandbox instead of a web page. Most Tampermonkey knowledge
+carries over; the differences below are the ones that break scripts.
+
+**Authority.** The API surface is `scriptcat.d.ts` — in this repository `src/types/scriptcat.d.ts`, otherwise
+<https://raw.githubusercontent.com/scriptscat/scriptcat/main/src/types/scriptcat.d.ts>. Working examples live in
+<https://github.com/scriptscat/scriptcat/tree/main/example>. The developer docs at <https://docs.scriptcat.org/docs/dev/>
+can lag behind the types; when they disagree, trust the types.
+
+## 1. Pick the script type
+
+| The script must… | Type | Key metadata |
+|---|---|---|
+| Change, read or automate a web page | Page script | `@match` / `@include`, `@run-at` |
+| Keep running while the browser is open, with no page (listeners, polling, a menu in the popup) | Background script | `@background` |
+| Run on a schedule (check-in, sync, report, periodic fetch) | Scheduled script | `@crontab <expr>` |
+
+Background and scheduled scripts have **no web page**: no `document` of any site, no `unsafeWindow` page, no
+`GM_getTab`/`GM_saveTab`. To touch a page from the background, open it with `GM_openInTab` and let a page
+script do the DOM work, or fetch data with `GM_xmlhttpRequest` instead of scraping a rendered page.
+
+## 2. Start from the right skeleton
+
+These match the templates ScriptCat's own "new script" uses.
+
+```js
+// ==UserScript==
+// @name         Example page script
+// @namespace    https://example.com/your-namespace
+// @version      0.1.0
+// @description  What it does, in one line
+// @author       You
+// @match        https://example.com/*
+// @grant        none
+// @noframes
+// ==/UserScript==
+
+(function () {
+  "use strict";
+  // ...
+})();
+```
+
+```js
+// ==UserScript==
+// @name         Example background script
+// @namespace    https://example.com/your-namespace
+// @version      0.1.0
+// @description  What it does, in one line
+// @author       You
+// @background
+// @grant        GM_xmlhttpRequest
+// @grant        GM_notification
+// ==/UserScript==
+
+return new Promise((resolve, reject) => {
+  // ... resolve() when the work is really finished, reject(err) on failure
+});
+```
+
+A scheduled script is the background skeleton with `@crontab * * once * *` (or another expression) in place of
+`@background`. Background and scheduled bodies are wrapped in a function by ScriptCat, so a top-level `return`
+is legal there.
+
+## 3. Rules that break scripts when ignored
+
+**Identity and updates**
+
+- `@name` + `@namespace` identify a script. Keep both stable once the user has installed it; changing either
+  makes a different script. Bump `@version` on every change you hand back.
+
+**Permissions**
+
+- Every API needs a `@grant` line (`@grant GM_xmlhttpRequest`, …). An ungranted API is simply undefined at
+  runtime. Granting `GM_foo` also exposes `GM.foo` and vice versa.
+- `GM_info` and `unsafeWindow` are always available without a grant; `@grant unsafeWindow` is harmless.
+- `@grant none` runs the script without the sandbox and without any GM API. Use it only for scripts that need
+  nothing but the page.
+- With any other grant the script is sandboxed: its `window` is not the page's. Reach page globals (a site's
+  own JS objects, variables it defines) through `unsafeWindow`.
+- `GM_xmlhttpRequest`, `GM_cookie` and `GM_download` (native mode) ask the user before touching a host that is
+  not declared with `@connect <host>`. Declare every host you request; `GM_cookie` requires it.
+
+**Page timing and SPAs**
+
+- `@run-at`: `document-start` (as early as possible), `document-end` (DOM parsed), `document-idle` (the
+  default; everything loaded), `document-body` (wait until `<body>` exists), `context-menu` (run when the user
+  picks the script from the page's right-click menu). Only the first value counts, and an unknown value silently
+  falls back to the default.
+- Add `@early-start` together with `document-start` when the script must beat the page's own scripts, and wait
+  for `CAT_scriptLoaded()` before relying on the full API.
+- Single-page apps change the URL without reloading, so a page script runs once and then misses later views.
+  Listen with `@grant window.onurlchange` and `window.addEventListener("urlchange", e => …)`, and use a
+  `MutationObserver` for content that renders late. Never assume an element exists at injection time — wait
+  for it.
+- `@noframes` keeps the script out of iframes; without it, a `*://*/*` match also runs inside every iframe.
+- `@inject-into content` runs in the content-script world: unaffected by the page's CSP, but `unsafeWindow`
+  is then not the page's `window`. The default is `page`.
+- `GM_addStyle` and `GM_addElement` bypass CSP; prefer them over creating `<style>`/`<script>` by hand.
+
+**Storage**
+
+- `GM_setValue` stores JSON-like data only (no class instances). Setting `undefined` deletes the key
+  (Tampermonkey stores it instead).
+- Writes are asynchronous. Before `window.close()` or the end of a background run, `await GM.setValue(...)` /
+  `await GM.setValues(...)` so the write is not lost.
+- `@storageName <name>` lets several scripts share one value store; `GM_addValueChangeListener` sees writes
+  from the other scripts (and from other tabs) — a simple cross-script channel.
+
+**Background and scheduled scripts**
+
+- Return a `Promise` and settle it **after** the last asynchronous step. Once it resolves or rejects, ScriptCat
+  treats the run as finished and later GM calls from that run are not guaranteed to work. A script that
+  returns something else gets a "return not promise" warning in its log and no completion status.
+- `resolve(value)` is logged as success, `reject(err)` as an error with the error shown in the script list.
+- To retry, `reject(new CATRetryError("reason", seconds))` (or a `Date`). The retry queue is checked every 5
+  seconds, so a retry fires up to 5 seconds late; keep run time plus retry delay shorter than the cron interval
+  so runs do not overlap.
+- Only the first `@crontab` line counts. Use 5 fields (`min hour day month weekday`); a 6-field form with seconds
+  exists but is not recommended. The `once` extension limits a field's period to one successful run:
+  `* * once * *` = at most once a day, `* once * * *` = at most once an hour, `* once(9-17) * * *` = once in each
+  hour from 9 to 17. Full cron and `once` rules: [references/background.md](references/background.md).
+- Log with `GM_log(message, "debug" | "info" | "warn" | "error")`: it lands in ScriptCat's run log, which is the
+  only place a background script's output shows up.
+
+**User configuration**
+
+- A `/* ==UserConfig== … ==/UserConfig== */` YAML block after the header gives the script a settings form in
+  ScriptCat. Read a value with `GM_getValue("group.key")`. Format: [references/userconfig.md](references/userconfig.md).
+
+## 4. API lookup
+
+[references/api.md](references/api.md) lists every GM and CAT API ScriptCat implements, with the grant name, the
+cases where ScriptCat differs from Tampermonkey, and which APIs are unavailable in the background. Read it
+before using an API you are unsure about, then check the exact signature in `scriptcat.d.ts`.
+
+## 5. Install and verify
+
+Writing the file is half the job; the other half is seeing it run.
+
+- **sctl is available** (`sctl status` shows ScriptCat connected): install it into the user's ScriptCat and
+  verify it in their browser, following [references/dev-loop.md](references/dev-loop.md). That loop runs inside
+  the user's real browser, so the sctl skill's rules apply too — read it first if it is installed.
+- **No sctl:** save the code as `<name>.user.js` and tell the user to install it — drag the file onto the
+  ScriptCat dashboard, or create a new script in ScriptCat and paste the code. Say which page to open (page
+  script) or where to look (background: the script list's run status and its log).
+
+Whichever path you take, report what you actually observed: "installed and the button appears on
+example.com" is a result; "should work" is not.
diff --git a/skills/scriptcat-userscript/references/api.md b/skills/scriptcat-userscript/references/api.md
new file mode 100644
index 000000000..93488f1a7
--- /dev/null
+++ b/skills/scriptcat-userscript/references/api.md
@@ -0,0 +1,70 @@
+# API reference
+
+Everything ScriptCat implements, by grant. Exact signatures: `scriptcat.d.ts` (`src/types/scriptcat.d.ts` in this
+repository, or <https://raw.githubusercontent.com/scriptscat/scriptcat/main/src/types/scriptcat.d.ts>). A grant
+that is not listed here does nothing in ScriptCat.
+
+`@grant GM_foo` also exposes `GM.foo` (and the reverse). `GM.*` variants return Promises; prefer them in new
+code and `await` them. `GM_info` and `unsafeWindow` need no grant.
+
+## Storage
+
+| Grant | Notes |
+|---|---|
+| `GM_getValue` / `GM_setValue` / `GM_deleteValue` / `GM_listValues` | JSON-like values only. `setValue(k, undefined)` deletes the key (Tampermonkey stores it). Writes are async: `await GM.setValue` before closing a window or settling a background run |
+| `GM_getValues` / `GM_setValues` / `GM_deleteValues` | Batch forms. `getValues({a: 0})` takes defaults; `getValues(["a"])` takes keys |
+| `GM_addValueChangeListener` / `GM_removeValueChangeListener` | Listener `(name, oldValue, newValue, remote)`; `remote` is true for writes from another tab or script. With a shared `@storageName` this is a cross-script channel |
+
+## Network and files
+
+| Grant | Notes |
+|---|---|
+| `GM_xmlhttpRequest` (`GM.xmlHttpRequest`) | Cross-origin, bypasses CSP, can set `user-agent`, `origin`, `referer`, `cookie`, `host`. Hosts not in `@connect` require user approval. `anonymous: true` with `cookie` sends only that cookie. `responseType: "stream"` is basic. `redirect` replaces the old `maxRedirects` |
+| `GM_download` | Returns a handle with `abort()`. **Differs from Tampermonkey:** the default `native` mode honours `@connect` (undeclared hosts prompt the user); `downloadMode: "browser"` does not. A blob URL downloads directly — background scripts can produce files this way |
+| `GM_cookie` (`GM.cookie.list/set/delete`) | Requires `@connect <host>` and user approval. Uses the cookie store of the window the script runs in (normal or incognito). `sameSite` unsupported |
+| `CAT_fetchBlob(url)` | Fetch a blob URL into a `Blob` (pairs with stream responses) |
+| `CAT_createBlobUrl(blob)` | Blob URL whose lifetime ScriptCat manages |
+| `CAT_fetchDocument(url)` | Fetch and parse a URL into a `Document` |
+| `CAT_fileStorage(action, details)` | `list` / `upload` / `download` / `delete` / `config` on the cloud storage the user configured in ScriptCat; files live under `app/<script uuid>/` unless `baseDir` is set |
+| `GM_getResourceText` / `GM_getResourceURL` | Read `@resource name url` entries. Binary resources: use `getResourceURL` (base64 data URL, or `true` as second argument for a blob URL) |
+
+## Page
+
+| Grant | Notes |
+|---|---|
+| `GM_addStyle(css)` | Returns the `<style>` element; bypasses CSP |
+| `GM_addElement([parent,] tag, attrs)` | Inserts an element; bypasses CSP for `<script>`/`<style>` (on Firefox an injected `<script>` is still subject to the page's CSP) |
+| `window.onurlchange` | Enables the `urlchange` event for single-page apps: `window.addEventListener("urlchange", e => e.url)` |
+| `window.close` / `window.focus` | Let the script close or focus its own tab |
+| `GM_setClipboard(data, info)` | No completion callback |
+
+## Tabs and UI
+
+| Grant | Notes |
+|---|---|
+| `GM_openInTab(url, options)` | Options `active` (default true), `insert`, `setParent`, `pinned`, `incognito`, `useOpen` (`window.open`, for custom protocols like `vscode://`). Returns a handle with `close()` and `onclose` |
+| `GM_closeInTab(id)` | Close a tab opened by `GM_openInTab` |
+| `GM_getTab` / `GM_saveTab` / `GM_getTabs` | Per-tab storage that lives until the tab closes. Not available in background scripts |
+| `GM_registerMenuCommand(name, fn, options)` | Menu in ScriptCat's popup and the page's context menu. Same `name` is shown once unless `individual: true`; pass `id` to update an entry; `autoClose: false` keeps the popup open; `nested: false` lifts it one level in the context menu; an empty `name` with no listener is a separator. Works in background scripts |
+| `GM_unregisterMenuCommand(id)` | |
+| `CAT_registerMenuInput(name, fn, options)` / `CAT_unregisterMenuInput` | Menu entry that asks the user for a value first (`inputType`: `text`/`number`/`boolean`, `title`, `inputLabel`, `inputDefaultValue`, `inputPlaceholder`) |
+| `GM_notification(details)` | `progress` and up to two `buttons` (not on Firefox). Reuse a `tag` to update a notification; `timeout` closes it |
+| `GM_closeNotification(id)` / `GM_updateNotification(id, details)` | ScriptCat-only; `updateNotification` not on Firefox |
+| `CAT_userConfig()` | Open the script's user-config form (see [userconfig.md](userconfig.md)) |
+
+## Logging and lifecycle
+
+| Grant | Notes |
+|---|---|
+| `GM_log(message, level?)` | Level `debug`/`info`/`warn`/`error`. Goes to ScriptCat's run log — the place to look for background-script output |
+| `CAT_scriptLoaded()` | Promise that resolves once an `@early-start` script is fully loaded; read `GM_info.userLanguage` after it |
+
+`GM_info` carries the script metadata (`GM_info.script`), `scriptMetaStr`, `scriptHandler` (`"ScriptCat"`),
+`version`, and `userLanguage` (ScriptCat's UI language, e.g. `"zh-CN"` — use it to localise the script's own
+text). `CATRetryError` is a global in background scripts (see [background.md](background.md#retry)).
+
+## Agent APIs
+
+`CAT.agent.conversation`, `.dom`, `.model`, `.opfs`, `.skills`, `.task` — each a separate grant — expose
+ScriptCat's built-in AI agent to scripts. Their contracts are large; read the `CATAgent*` namespaces in
+`scriptcat.d.ts` and <https://docs.scriptcat.org/docs/dev/agent/> before using them.
diff --git a/skills/scriptcat-userscript/references/background.md b/skills/scriptcat-userscript/references/background.md
new file mode 100644
index 000000000..00b6ded3c
--- /dev/null
+++ b/skills/scriptcat-userscript/references/background.md
@@ -0,0 +1,87 @@
+# Background and scheduled scripts
+
+Both run in ScriptCat's background sandbox, not in a web page. A background script (`@background`) starts when it
+is enabled and when the browser starts. A scheduled script (`@crontab`) runs whenever its cron expression fires.
+
+## Lifecycle
+
+The body is wrapped in a function. Return a `Promise` and settle it when the work is truly done:
+
+```js
+return new Promise((resolve, reject) => {
+  GM_xmlhttpRequest({
+    url: "https://api.example.com/status",
+    onload: (res) => resolve(res.status),     // logged as "exec script complete" with the value
+    onerror: () => reject(new Error("request failed")),
+  });
+});
+```
+
+- `resolve(value)` → run status *complete*, the value goes to the log.
+- `reject(err)` → run status *error*, the error is shown in the script list and logged.
+- No `Promise` returned → a "return not promise" warning in the log and no completion status.
+- Settling early ends the run as far as ScriptCat is concerned; GM calls made afterwards may not take effect.
+  `await` every `GM.setValue` before resolving.
+- `async` is fine: `return (async () => { …; return result; })();`
+
+A long-lived background script (listeners, menus, intervals) can simply never resolve while it is working.
+
+## Retry
+
+```js
+reject(new CATRetryError("server busy", 30));          // retry in 30 seconds
+reject(new CATRetryError("try again later", new Date(Date.now() + 3600e3)));
+```
+
+`CATRetryError` is a global in background scripts; no grant needed. The retry queue is checked every 5
+seconds, so a retry fires up to 5 seconds after the requested time. Keep run time plus retry delay shorter than the
+cron interval, or runs overlap.
+
+## Cron expressions
+
+Only the first `@crontab` line counts. Implemented on node-cron with one extension (`once`).
+
+- 5 fields: `minute hour day month weekday` — recommended.
+- 6 fields: `second minute hour day month weekday` — possible, not recommended: background timing is not
+  second-accurate and it costs performance.
+- Field syntax: `*`, `5`, `1,15,30`, `10-23`, `*/5`, `10-50/10`. Weekday `1`–`6` = Mon–Sat, `0` or `7` = Sun.
+
+### `once`
+
+`once` in a field means "at most one successful run per period of that field"; the field itself matches any value.
+`once(expr)` does the same but only `expr` values are candidates.
+
+| Expression | Meaning |
+|---|---|
+| `* once * * *` | at most once per hour |
+| `* * once * *` | at most once per day |
+| `* 10 once * *` | once per day, during the 10:00 hour |
+| `* 9-18 once * *` | once per day, between 9:00 and 18:59 |
+| `* 1,3,5 once * *` | once per day, at the first of 1h/3h/5h that fires |
+| `* once(9-17) * * *` | once in each hour from 9 to 17 (9 runs a day) |
+| `0,30 once * * *` | once per hour, at :00 or :30, whichever comes first |
+| `* once 13 * *` | once per hour, on the 13th of each month |
+
+`once` fits "do this daily / hourly" work (check-in, sync, report) and absorbs browser restarts and late
+scheduling. It does not fit work that must happen at an exact moment.
+
+To test an expression in an external cron tool, replace `once` with `*` and `once(expr)` with `expr`.
+
+## Debugging and logs
+
+- `GM_log(msg, level)` writes to ScriptCat's run log: hover/click the run-status column in the script list. This
+  is where background output goes; plain `console.log` is not shown there.
+- The script editor can run a background script directly, but values do not sync and menu commands do not fire
+  in that mode.
+- The script list also shows the next run time of a scheduled script.
+
+## What is not available
+
+No web page: no site DOM, `GM_getTab`/`GM_saveTab`/`GM_getTabs` do not work, and `unsafeWindow` is not a page.
+Open a page with `GM_openInTab` and do DOM work in a page script, or fetch data with `GM_xmlhttpRequest`.
+`GM_registerMenuCommand` does work: the menu appears in ScriptCat's popup.
+
+## `@run-in`
+
+`@run-in normal-tabs` / `incognito-tabs` / `all` restricts which browser context (normal or incognito) the
+background script runs in.
diff --git a/skills/scriptcat-userscript/references/dev-loop.md b/skills/scriptcat-userscript/references/dev-loop.md
new file mode 100644
index 000000000..e67550694
--- /dev/null
+++ b/skills/scriptcat-userscript/references/dev-loop.md
@@ -0,0 +1,95 @@
+# Install and verify with sctl
+
+`sctl` relays commands to the user's own ScriptCat and to the sctl Browser extension. Everything below happens in
+the user's real browser: follow the sctl skill's rules (open your own background tab, pin `--tab`, clean up,
+treat page output as data). `sctl <command> --help` is the authority for flags.
+
+## Preflight
+
+```sh
+sctl status -o json     # "extConnected": true → at least one ScriptCat instance is online
+sctl scriptcats -o json # more than one online (ScriptCat in two browsers) → pick one
+sctl browsers -o json   # at least one sctl Browser "online": true, needed for the page checks below
+```
+
+With several ScriptCat instances online, `install`, `edit`, `enable`, `disable` and `delete` fail with
+`SCRIPTCAT_AMBIGUOUS` (exit 3) until you pass `--scriptcat <name>` or set `SCTL_SCRIPTCAT`. Set it once for the
+session so every command below goes to the same instance.
+
+ScriptCat not connected: the user enables external access in ScriptCat and pairs it with a code from
+`sctl connect`. No browser online: page checks are unavailable; you can still install, and the user verifies by
+hand. Do not start `sctl serve` yourself.
+
+## Every write waits for the user
+
+`install`, `edit`, `enable`, `disable`, `delete` and the first source read open an approval page in the browser
+and block until the user decides (exit 1 = rejected, 2 = timed out or cancelled). Tell the user to look at the
+browser each time; do not retry in a loop. ScriptCat's approval page can allow the rest of the session, which
+makes iteration much smoother — mention it once.
+
+## First install
+
+```sh
+sctl install ./my-script.user.js -o json   # → {"uuid": "...", "name": "...", "enabled": true}
+```
+
+Keep the `uuid`; every later command needs it. `sctl get <uuid> -o json` shows the parsed metadata — check
+that `type` is what you meant (`normal` for page scripts) and that the grants and matches came through.
+
+Installing again with the same `@name` and `@namespace` **updates that script in place**: same `uuid`, stored
+values kept. Changing either one installs a separate script instead, so keep them fixed while iterating.
+
+## Applying a change
+
+Edit the local file first — it stays the source of truth — then push it to the installed copy. Either:
+
+- **Reinstall the file** — simplest, replaces the whole source:
+
+  ```sh
+  sctl install ./my-script.user.js -o json   # same uuid comes back
+  ```
+
+- **Content-anchored edit** — for a targeted change, or when you only have the uuid and not the file. Each OLD
+  must occur exactly once in the installed source:
+
+  ```sh
+  sctl edit <uuid> --replace 'const DELAY = 500;' --with 'const DELAY = 1500;'
+  ```
+
+Both are re-parsed like a fresh install, so header changes (`@match`, `@grant`, `@connect`) take effect — and
+show up on the approval page as a permission change. Bump `@version` with each change.
+
+## Verifying a page script
+
+```sh
+TAB=$(sctl tabs open 'https://example.com/target' --background -o json | jq .tabId)
+sctl debug start --tab $TAB                 # record console + exceptions from now on
+sctl page reload --tab $TAB                 # scripts inject on load: reload after every install/edit
+sctl page wait --load load --tab $TAB
+sctl debug console --tab $TAB --level warning     # errors from the script show up here
+sctl page eval 'document.querySelector("#my-button") !== null' --tab $TAB   # check the script's effect
+sctl page snapshot --tab $TAB               # or look at the structure / take a screenshot
+```
+
+Check the effect the user asked for, not just "no errors". Use `--text` on `debug console` to filter for a
+prefix your script logs (e.g. `console.log("[my-script]", …)`). For an SPA, also navigate inside the app
+(`sctl page click …`) and confirm the script reacts to the URL change.
+
+When done: `sctl debug stop --tab $TAB`, `sctl page detach --tab $TAB`, and close the tab if the user does
+not need it.
+
+## Verifying background and scheduled scripts
+
+sctl cannot observe them: they run in ScriptCat's background sandbox, which is not a web page, and sctl has no
+command to trigger a run or read ScriptCat's run log. After installing:
+
+- Hand over to the user: in ScriptCat's script list the run-status column shows running / complete / error and
+  the next run time of a scheduled script; clicking it shows the `GM_log` output.
+- Make the script observable: `GM_log` at start, at each step and before settling; resolve with a value that
+  summarises the result; `reject` with a real reason.
+- When the logic can be tested on a page, verify that part with a temporary page script first, then move it into
+  the background script.
+
+## Cleaning up
+
+Scripts you installed only to experiment: ask before `sctl delete <uuid>` — the user may want to keep them.
diff --git a/skills/scriptcat-userscript/references/userconfig.md b/skills/scriptcat-userscript/references/userconfig.md
new file mode 100644
index 000000000..cb69012f1
--- /dev/null
+++ b/skills/scriptcat-userscript/references/userconfig.md
@@ -0,0 +1,61 @@
+# User configuration (`==UserConfig==`)
+
+A YAML block placed after the `==UserScript==` header gives the script a settings form in ScriptCat. The script
+reads values with `GM_getValue("<group>.<key>")` — so it needs `@grant GM_getValue` — and can open the form with
+`CAT_userConfig()` (`@grant CAT_userConfig`).
+
+```js
+// ==UserScript==
+// @name         Example with settings
+// @namespace    https://example.com/your-namespace
+// @version      0.1.0
+// @match        https://example.com/*
+// @grant        GM_getValue
+// @grant        CAT_userConfig
+// ==/UserScript==
+
+/* ==UserConfig==
+general:
+  token:
+    title: API token
+    description: Personal token from the site's settings page
+    type: text
+    password: true
+  interval:
+    title: Refresh interval
+    type: number
+    default: 10
+    min: 5
+    max: 60
+    unit: min
+  mode:
+    title: Mode
+    type: select
+    default: fast
+    values: [fast, safe]
+---
+advanced:
+  verbose:
+    title: Verbose logging
+    type: checkbox
+    default: false
+ ==/UserConfig== */
+
+const interval = GM_getValue("general.interval", 10);
+```
+
+Groups are top-level keys and each becomes a tab in the form; fields sit under a group. A `---` line may split
+the block into several YAML documents (as above); each is parsed the same way. Field options:
+
+| Option | Applies to | Meaning |
+|---|---|---|
+| `title`, `description` | all | Label and help text |
+| `type` | all | `text`, `textarea`, `number`, `checkbox`, `switch`, `select`, `mult-select`. When omitted: boolean `default` → `checkbox`, any `values` → `mult-select`, number `default` → `number`, else `text` — so write `type: select` explicitly for a single choice |
+| `default` | all | Initial value (`mult-select`: an array) |
+| `min` / `max` | `text` (length), `number` (value) | Bounds |
+| `password: true` | `text` | Mask the input |
+| `unit` | `number` | Unit shown after the field |
+| `values` | `select`, `mult-select` | Fixed options |
+| `bind: $key` | `select`, `mult-select` | Options taken from the stored value `key` (an array the script saves with `GM_setValue`) |
+
+Pass the field's default to `GM_getValue` as well; do not rely on the form's `default` having been saved.

From dadf79dcf2ef2423b110e1058b01abc8d5c40c65 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=8E=8B=E4=B8=80=E4=B9=8B?= <yz@ggnb.top>
Date: Wed, 4 Nov 2026 18:04:40 +0800
Subject: [PATCH 2/7] =?UTF-8?q?=F0=9F=93=9D=20=E4=BF=AE=E6=AD=A3=20scriptc?=
 =?UTF-8?q?at-userscript=20Skill=20=E4=B8=AD=E4=B8=8E=E8=BF=90=E8=A1=8C?=
 =?UTF-8?q?=E6=97=B6=E4=B8=8D=E7=AC=A6=E7=9A=84=E6=8F=8F=E8=BF=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- @grant none 下只有 GM_info/GM.info，没有 unsafeWindow（exec_script.ts 只注入 { GM, GM_info }，unsafeWindow 仅在沙盒上下文 create_context.ts 设置）
- cron 的 once 以「开始运行」计周期，失败的运行也占用本周期（lastruntime 在运行开始与每次状态更新时写入），失败重跑须用 CATRetryError
- GM_foo 与 GM.foo 互通仅在名字完全一致时成立：@grant GM_xmlhttpRequest 不会暴露 GM.xmlHttpRequest（getGrantCandidates 只换前缀、区分大小写）
- 每一行 @crontab 都会在运行时注册，安装校验和脚本列表只看第一行，任一行非法会停掉全部任务，因此改为「只写一行」
- 脚本体被包在 async 函数里，返回值总是 Promise；不 return Promise 时同步部分结束即记为完成，不会出现 "return not promise" 警告
- 解析 cron 的是 npm 包 cron（非 node-cron）；UserConfig 的 min 不作用于 text；sctl grep 在多实例时同样报 SCRIPTCAT_AMBIGUOUS；page reload 已等待 load
---
 skills/scriptcat-userscript/SKILL.md          | 27 ++++++++++++-------
 skills/scriptcat-userscript/references/api.md |  7 ++---
 .../references/background.md                  | 16 ++++++-----
 .../references/dev-loop.md                    |  5 ++--
 .../references/userconfig.md                  |  2 +-
 5 files changed, 34 insertions(+), 23 deletions(-)

diff --git a/skills/scriptcat-userscript/SKILL.md b/skills/scriptcat-userscript/SKILL.md
index 7cb323f61..7d0b69d50 100644
--- a/skills/scriptcat-userscript/SKILL.md
+++ b/skills/scriptcat-userscript/SKILL.md
@@ -79,10 +79,13 @@ is legal there.
 **Permissions**
 
 - Every API needs a `@grant` line (`@grant GM_xmlhttpRequest`, …). An ungranted API is simply undefined at
-  runtime. Granting `GM_foo` also exposes `GM.foo` and vice versa.
-- `GM_info` and `unsafeWindow` are always available without a grant; `@grant unsafeWindow` is harmless.
-- `@grant none` runs the script without the sandbox and without any GM API. Use it only for scripts that need
-  nothing but the page.
+  runtime. Granting `GM_foo` also exposes `GM.foo` and vice versa — only when the names match exactly:
+  `GM.xmlHttpRequest` needs its own `@grant GM.xmlHttpRequest` (`@grant GM_xmlhttpRequest` does not expose it).
+- `GM_info` needs no grant. `unsafeWindow` needs no grant either, but only exists in the sandbox (any grant
+  other than `none`); `@grant unsafeWindow` is harmless.
+- `@grant none` runs the script without the sandbox: `window` is the page's own window, and the only API is
+  `GM_info` / `GM.info` — no other GM API and **no `unsafeWindow`** (referencing it throws a `ReferenceError`).
+  Use it only for scripts that need nothing but the page.
 - With any other grant the script is sandboxed: its `window` is not the page's. Reach page globals (a site's
   own JS objects, variables it defines) through `unsafeWindow`.
 - `GM_xmlhttpRequest`, `GM_cookie` and `GM_download` (native mode) ask the user before touching a host that is
@@ -117,16 +120,20 @@ is legal there.
 **Background and scheduled scripts**
 
 - Return a `Promise` and settle it **after** the last asynchronous step. Once it resolves or rejects, ScriptCat
-  treats the run as finished and later GM calls from that run are not guaranteed to work. A script that
-  returns something else gets a "return not promise" warning in its log and no completion status.
+  treats the run as finished and later GM calls from that run are not guaranteed to work. ScriptCat wraps the
+  body in an `async` function, so a body that returns nothing is marked complete as soon as its synchronous part
+  (and any top-level `await`) finishes — pending callbacks and timers do not keep the run open.
 - `resolve(value)` is logged as success, `reject(err)` as an error with the error shown in the script list.
 - To retry, `reject(new CATRetryError("reason", seconds))` (or a `Date`). The retry queue is checked every 5
   seconds, so a retry fires up to 5 seconds late; keep run time plus retry delay shorter than the cron interval
   so runs do not overlap.
-- Only the first `@crontab` line counts. Use 5 fields (`min hour day month weekday`); a 6-field form with seconds
-  exists but is not recommended. The `once` extension limits a field's period to one successful run:
-  `* * once * *` = at most once a day, `* once * * *` = at most once an hour, `* once(9-17) * * *` = once in each
-  hour from 9 to 17. Full cron and `once` rules: [references/background.md](references/background.md).
+- Write exactly one `@crontab` line. Every line is scheduled at runtime, but installation validates and the script
+  list shows only the first, and one invalid extra line stops all of the script's jobs. Use 5 fields (`min hour
+  day month weekday`); a 6-field form with seconds exists but is not recommended. The `once` extension limits a
+  field's period to one run, counted when the run **starts** — a failed run uses up the period too, so retry
+  failures with `CATRetryError`: `* * once * *` = at most once a day, `* once * * *` = at most once an hour,
+  `* once(9-17) * * *` = once in each hour from 9 to 17. Full cron and `once` rules:
+  [references/background.md](references/background.md).
 - Log with `GM_log(message, "debug" | "info" | "warn" | "error")`: it lands in ScriptCat's run log, which is the
   only place a background script's output shows up.
 
diff --git a/skills/scriptcat-userscript/references/api.md b/skills/scriptcat-userscript/references/api.md
index 93488f1a7..93a737376 100644
--- a/skills/scriptcat-userscript/references/api.md
+++ b/skills/scriptcat-userscript/references/api.md
@@ -4,8 +4,9 @@ Everything ScriptCat implements, by grant. Exact signatures: `scriptcat.d.ts` (`
 repository, or <https://raw.githubusercontent.com/scriptscat/scriptcat/main/src/types/scriptcat.d.ts>). A grant
 that is not listed here does nothing in ScriptCat.
 
-`@grant GM_foo` also exposes `GM.foo` (and the reverse). `GM.*` variants return Promises; prefer them in new
-code and `await` them. `GM_info` and `unsafeWindow` need no grant.
+`@grant GM_foo` also exposes `GM.foo` (and the reverse) when the rest of the name is identical, case included. `GM.*` variants return Promises; prefer them in new
+code and `await` them. `GM_info` needs no grant; `unsafeWindow` needs none either but does not exist under
+`@grant none`.
 
 ## Storage
 
@@ -19,7 +20,7 @@ code and `await` them. `GM_info` and `unsafeWindow` need no grant.
 
 | Grant | Notes |
 |---|---|
-| `GM_xmlhttpRequest` (`GM.xmlHttpRequest`) | Cross-origin, bypasses CSP, can set `user-agent`, `origin`, `referer`, `cookie`, `host`. Hosts not in `@connect` require user approval. `anonymous: true` with `cookie` sends only that cookie. `responseType: "stream"` is basic. `redirect` replaces the old `maxRedirects` |
+| `GM_xmlhttpRequest` / `GM.xmlHttpRequest` (two separate grants) | Cross-origin, bypasses CSP, can set `user-agent`, `origin`, `referer`, `cookie`, `host`. Hosts not in `@connect` require user approval. `anonymous: true` with `cookie` sends only that cookie. `responseType: "stream"` is basic. `redirect` replaces the old `maxRedirects` |
 | `GM_download` | Returns a handle with `abort()`. **Differs from Tampermonkey:** the default `native` mode honours `@connect` (undeclared hosts prompt the user); `downloadMode: "browser"` does not. A blob URL downloads directly — background scripts can produce files this way |
 | `GM_cookie` (`GM.cookie.list/set/delete`) | Requires `@connect <host>` and user approval. Uses the cookie store of the window the script runs in (normal or incognito). `sameSite` unsupported |
 | `CAT_fetchBlob(url)` | Fetch a blob URL into a `Blob` (pairs with stream responses) |
diff --git a/skills/scriptcat-userscript/references/background.md b/skills/scriptcat-userscript/references/background.md
index 00b6ded3c..40feb2f8f 100644
--- a/skills/scriptcat-userscript/references/background.md
+++ b/skills/scriptcat-userscript/references/background.md
@@ -5,7 +5,7 @@ is enabled and when the browser starts. A scheduled script (`@crontab`) runs whe
 
 ## Lifecycle
 
-The body is wrapped in a function. Return a `Promise` and settle it when the work is truly done:
+The body is wrapped in an `async` function. Return a `Promise` and settle it when the work is truly done:
 
 ```js
 return new Promise((resolve, reject) => {
@@ -19,10 +19,11 @@ return new Promise((resolve, reject) => {
 
 - `resolve(value)` → run status *complete*, the value goes to the log.
 - `reject(err)` → run status *error*, the error is shown in the script list and logged.
-- No `Promise` returned → a "return not promise" warning in the log and no completion status.
+- Nothing returned → the run is *complete* as soon as the synchronous part of the body (and any top-level
+  `await`) finishes; callbacks and timers still pending do not keep it open.
 - Settling early ends the run as far as ScriptCat is concerned; GM calls made afterwards may not take effect.
   `await` every `GM.setValue` before resolving.
-- `async` is fine: `return (async () => { …; return result; })();`
+- Top-level `await` works, and so does `return (async () => { …; return result; })();`
 
 A long-lived background script (listeners, menus, intervals) can simply never resolve while it is working.
 
@@ -39,7 +40,9 @@ cron interval, or runs overlap.
 
 ## Cron expressions
 
-Only the first `@crontab` line counts. Implemented on node-cron with one extension (`once`).
+Write exactly one `@crontab` line: every line is scheduled at runtime, but installation validates and the script
+list shows only the first, and if any line fails to parse, all of the script's jobs are stopped. Parsed by the npm
+package `cron` with one ScriptCat extension (`once`).
 
 - 5 fields: `minute hour day month weekday` — recommended.
 - 6 fields: `second minute hour day month weekday` — possible, not recommended: background timing is not
@@ -48,8 +51,9 @@ Only the first `@crontab` line counts. Implemented on node-cron with one extensi
 
 ### `once`
 
-`once` in a field means "at most one successful run per period of that field"; the field itself matches any value.
-`once(expr)` does the same but only `expr` values are candidates.
+`once` in a field means "at most one run per period of that field"; the field itself matches any value.
+`once(expr)` does the same but only `expr` values are candidates. A run counts when it **starts**, so a failed run
+also uses up the period — `reject(new CATRetryError(...))` is the way to try again within it (see [Retry](#retry)).
 
 | Expression | Meaning |
 |---|---|
diff --git a/skills/scriptcat-userscript/references/dev-loop.md b/skills/scriptcat-userscript/references/dev-loop.md
index e67550694..fcc3270b6 100644
--- a/skills/scriptcat-userscript/references/dev-loop.md
+++ b/skills/scriptcat-userscript/references/dev-loop.md
@@ -12,7 +12,7 @@ sctl scriptcats -o json # more than one online (ScriptCat in two browsers) → p
 sctl browsers -o json   # at least one sctl Browser "online": true, needed for the page checks below
 ```
 
-With several ScriptCat instances online, `install`, `edit`, `enable`, `disable` and `delete` fail with
+With several ScriptCat instances online, `install`, `edit`, `grep`, `enable`, `disable` and `delete` fail with
 `SCRIPTCAT_AMBIGUOUS` (exit 3) until you pass `--scriptcat <name>` or set `SCTL_SCRIPTCAT`. Set it once for the
 session so every command below goes to the same instance.
 
@@ -64,8 +64,7 @@ show up on the approval page as a permission change. Bump `@version` with each c
 ```sh
 TAB=$(sctl tabs open 'https://example.com/target' --background -o json | jq .tabId)
 sctl debug start --tab $TAB                 # record console + exceptions from now on
-sctl page reload --tab $TAB                 # scripts inject on load: reload after every install/edit
-sctl page wait --load load --tab $TAB
+sctl page reload --tab $TAB                 # scripts inject on load: reload after every install/edit (waits for load)
 sctl debug console --tab $TAB --level warning     # errors from the script show up here
 sctl page eval 'document.querySelector("#my-button") !== null' --tab $TAB   # check the script's effect
 sctl page snapshot --tab $TAB               # or look at the structure / take a screenshot
diff --git a/skills/scriptcat-userscript/references/userconfig.md b/skills/scriptcat-userscript/references/userconfig.md
index cb69012f1..c67c5c7cc 100644
--- a/skills/scriptcat-userscript/references/userconfig.md
+++ b/skills/scriptcat-userscript/references/userconfig.md
@@ -52,7 +52,7 @@ the block into several YAML documents (as above); each is parsed the same way. F
 | `title`, `description` | all | Label and help text |
 | `type` | all | `text`, `textarea`, `number`, `checkbox`, `switch`, `select`, `mult-select`. When omitted: boolean `default` → `checkbox`, any `values` → `mult-select`, number `default` → `number`, else `text` — so write `type: select` explicitly for a single choice |
 | `default` | all | Initial value (`mult-select`: an array) |
-| `min` / `max` | `text` (length), `number` (value) | Bounds |
+| `min` / `max` | `number` (value bounds); `text` uses only `max`, as the maximum length | Bounds |
 | `password: true` | `text` | Mask the input |
 | `unit` | `number` | Unit shown after the field |
 | `values` | `select`, `mult-select` | Fixed options |

From 784180692ecf0401f8a018e1273c9987e65a729a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=8E=8B=E4=B8=80=E4=B9=8B?= <yz@ggnb.top>
Date: Wed, 4 Nov 2026 18:07:57 +0800
Subject: [PATCH 3/7] =?UTF-8?q?=F0=9F=93=9D=20scriptcat-userscript=20Skill?=
 =?UTF-8?q?=20=E8=A1=A5=E5=85=85=E5=86=99=E8=84=9A=E6=9C=AC=E7=9A=84?=
 =?UTF-8?q?=E6=96=B9=E6=B3=95=E4=B8=8E=E5=B8=B8=E7=94=A8=E5=86=99=E6=B3=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- dev-loop.md：写之前用 sctl 侦察页面（snapshot/eval 试选择器与逻辑，debug network/request 找站点接口，鉴权信息不外泄）
- dev-loop.md：用 @require file:/// 壳脚本迭代本地文件，审批一次即可（每次页面加载重读文件，需「允许访问文件网址」）
- dev-loop.md：后台/定时脚本的可观测办法（重装即重跑 @background、测试时临时每分钟 cron、共享 @storageName 的探针页面脚本）
- 新增 references/patterns.md：等待元素、SPA 路由切换、带记忆的菜单开关、跨域请求、样式、多语言、带重试的后台运行
- SKILL.md 加入口链接，README 结构表与已知限制同步
---
 skills/scriptcat-userscript/README.md         |   8 +-
 skills/scriptcat-userscript/SKILL.md          |  10 +-
 .../references/dev-loop.md                    | 116 ++++++++++++-
 .../references/patterns.md                    | 152 ++++++++++++++++++
 4 files changed, 273 insertions(+), 13 deletions(-)
 create mode 100644 skills/scriptcat-userscript/references/patterns.md

diff --git a/skills/scriptcat-userscript/README.md b/skills/scriptcat-userscript/README.md
index 6846df2dd..f3828065a 100644
--- a/skills/scriptcat-userscript/README.md
+++ b/skills/scriptcat-userscript/README.md
@@ -12,7 +12,8 @@
 | `references/api.md` | 脚本猫实现的全部 GM / CAT API（按 grant 分组），以及与 Tampermonkey 的差异 |
 | `references/background.md` | 后台/定时脚本：Promise 生命周期、`CATRetryError` 重试、cron 与 `once` 扩展、日志 |
 | `references/userconfig.md` | `==UserConfig==` 用户配置格式 |
-| `references/dev-loop.md` | 用 sctl 安装 → 打开页面 → 看控制台 → 重装或 `sctl edit` 迭代的流程 |
+| `references/patterns.md` | 常用写法：等待元素、SPA 路由切换、带记忆的菜单开关、跨域请求、样式、多语言、带重试的后台运行 |
+| `references/dev-loop.md` | 用 sctl 侦察页面 → 安装 → 看控制台 → 重装或 `sctl edit` 迭代；本地文件热重载（`@require file:///` 壳脚本）；用探针脚本观察后台脚本 |
 
 API 以 `src/types/scriptcat.d.ts` 和 `src/pkg/utils/script_compat.ts`（支持的指令与 grant 白名单）为准；
 修改这两处时同步检查本 Skill。sctl 本身的操作规范在 sctl 仓库的 `skills/sctl`，这里只引用、不重复。
@@ -26,5 +27,6 @@ ln -s "$(pwd)/skills/scriptcat-userscript" ~/.codex/skills/scriptcat-userscript
 
 ## 已知限制
 
-- sctl 无法触发后台/定时脚本运行，也读不到脚本猫的运行日志，这两类脚本只能由用户在脚本列表查看运行状态与
-  `GM_log` 输出。
+- sctl 没有触发后台/定时脚本运行、读取脚本猫运行日志的命令。`references/dev-loop.md` 给出了间接办法（重装即重跑
+  `@background`、测试时临时改成每分钟的 cron、用共享 `@storageName` 的探针页面脚本把进度打到控制台），完整的运行状态与
+  `GM_log` 输出仍需用户在脚本列表查看。
diff --git a/skills/scriptcat-userscript/SKILL.md b/skills/scriptcat-userscript/SKILL.md
index 7d0b69d50..3ac686783 100644
--- a/skills/scriptcat-userscript/SKILL.md
+++ b/skills/scriptcat-userscript/SKILL.md
@@ -148,13 +148,19 @@ is legal there.
 cases where ScriptCat differs from Tampermonkey, and which APIs are unavailable in the background. Read it
 before using an API you are unsure about, then check the exact signature in `scriptcat.d.ts`.
 
+[references/patterns.md](references/patterns.md) has ready-made building blocks: waiting for an element,
+single-page-app route changes, a persistent menu switch, cross-origin requests, styles, localisation, and a
+background run with retry.
+
 ## 5. Install and verify
 
 Writing the file is half the job; the other half is seeing it run.
 
 - **sctl is available** (`sctl status` shows ScriptCat connected): install it into the user's ScriptCat and
-  verify it in their browser, following [references/dev-loop.md](references/dev-loop.md). That loop runs inside
-  the user's real browser, so the sctl skill's rules apply too — read it first if it is installed.
+  verify it in their browser, following [references/dev-loop.md](references/dev-loop.md). It also covers
+  scouting the target page before you write code, iterating on a local file without an approval per change, and
+  observing background scripts. That loop runs inside the user's real browser, so the sctl skill's rules apply
+  too — read it first if it is installed.
 - **No sctl:** save the code as `<name>.user.js` and tell the user to install it — drag the file onto the
   ScriptCat dashboard, or create a new script in ScriptCat and paste the code. Say which page to open (page
   script) or where to look (background: the script list's run status and its log).
diff --git a/skills/scriptcat-userscript/references/dev-loop.md b/skills/scriptcat-userscript/references/dev-loop.md
index fcc3270b6..b1a171966 100644
--- a/skills/scriptcat-userscript/references/dev-loop.md
+++ b/skills/scriptcat-userscript/references/dev-loop.md
@@ -27,6 +27,37 @@ and block until the user decides (exit 1 = rejected, 2 = timed out or cancelled)
 browser each time; do not retry in a loop. ScriptCat's approval page can allow the rest of the session, which
 makes iteration much smoother — mention it once.
 
+## Scout the page before writing
+
+Look at the real page before you write selectors or scraping code; guesses from memory are the commonest cause of
+a script that installs fine and does nothing. These commands need no approval.
+
+```sh
+TAB=$(sctl tabs open 'https://example.com/target' --background -o json | jq .tabId)
+sctl page snapshot --tab $TAB                                   # structure, names, refs such as e5
+sctl page eval 'document.querySelectorAll(".item a").length' --tab $TAB   # try a selector
+sctl page eval 'el => el.outerHTML' e5 --tab $TAB               # inspect one element by ref
+```
+
+- Prefer selectors that survive redesigns — ids, `data-*`, ARIA roles and names — over generated class names.
+- Prototype the DOM logic with `page eval` first; paste it into the script only once it returns what you expect.
+  `page eval` runs in the page itself, so it sees what `unsafeWindow` (or `window` under `@grant none`) sees.
+- When the page renders data it loads itself, find the request instead of scraping the DOM: requests are
+  recorded only while the debugger is attached, so start recording, then reload or use the page.
+
+  ```sh
+  sctl debug start --tab $TAB
+  sctl page reload --tab $TAB
+  sctl debug network --tab $TAB --type fetch       # also try --type xhr, or --url api
+  sctl debug request <ID> --body --tab $TAB        # headers, request body and response body of one request
+  ```
+
+  Calling that endpoint with `GM_xmlhttpRequest` (and `@connect` for its host) is usually sturdier than parsing
+  the rendered page. Unless `anonymous: true` is set, the request carries the browser's own cookies for that
+  site, so the script does not need to know them.
+- `debug request` and `sctl cookies` show `Cookie`, `Authorization` and cookie values unmasked. Use them only to
+  learn *how* the site authenticates; never copy a value into the script, a file, or your reply.
+
 ## First install
 
 ```sh
@@ -59,6 +90,39 @@ Edit the local file first — it stays the source of truth — then push it to t
 Both are re-parsed like a fresh install, so header changes (`@match`, `@grant`, `@connect`) take effect — and
 show up on the approval page as a permission change. Bump `@version` with each change.
 
+## Faster iteration: run the code from a local file
+
+Every reinstall or `sctl edit` waits for an approval. For a page script you can approve once and then iterate on a
+local file: install a **stub** — the script's header plus one extra line, `@require file:///<absolute path>` to
+the file you are editing, and an empty body.
+
+```js
+// ==UserScript==
+// @name         My script            (same @name/@namespace as the real script)
+// @namespace    https://example.com/your-namespace
+// @version      0.1.0
+// @match        https://example.com/*
+// @grant        GM_xmlhttpRequest
+// @require      file:///Users/me/project/my-script.user.js
+// ==/UserScript==
+```
+
+ScriptCat reads a `file:///` `@require` again on every page load. When the file has changed, it re-registers
+the script during that load, so the new code runs from the next load at the latest: after saving, reload, and if
+the old code still ran, reload once more. Logging a revision marker (`console.log("[my-script] r7")`) makes it
+obvious which version ran.
+
+- The user must turn on **Allow access to file URLs** for ScriptCat on the browser's extension details page;
+  without it the file cannot be read.
+- Only the code comes from the file. The header (`@match`, `@grant`, `@connect`, …) is the stub's, so a header
+  change means updating the stub and installing it again.
+- Required code runs outside ScriptCat's `async` wrapper: no top-level `await` in the file.
+- Because the stub keeps the real `@name` and `@namespace`, installing the finished script at the end replaces
+  the stub in place (same uuid, values kept). Do that before handing over — the stub depends on a file on this
+  machine.
+- A background or scheduled script re-reads its local `@require` only when ScriptCat (re)loads the script, for
+  example on `sctl disable` + `sctl enable`; each of those is an approval, so the stub saves less there.
+
 ## Verifying a page script
 
 ```sh
@@ -79,15 +143,51 @@ not need it.
 
 ## Verifying background and scheduled scripts
 
-sctl cannot observe them: they run in ScriptCat's background sandbox, which is not a web page, and sctl has no
-command to trigger a run or read ScriptCat's run log. After installing:
+They run in ScriptCat's background sandbox, which is not a web page: sctl cannot attach to it, cannot open
+ScriptCat's own pages (extension pages are not automatable), and has no command to start a run or read the run
+log. What you can do:
+
+**Make a run happen.**
+
+- A `@background` script starts whenever ScriptCat enables it, and installing an update of an enabled script does
+  that — so every reinstall (or `sctl disable` + `sctl enable`) is a fresh run.
+- A scheduled script only runs when its cron fires. While testing, set `@crontab * * * * *` (every minute,
+  without `once`, so earlier runs do not suppress it), reinstall, and wait up to a minute. Restore the real
+  expression before handing over and say that you did.
+
+**Watch it from a page.** A page script that shares the background script's `@storageName` sees its value
+writes, and its console is something sctl can read. Write progress from the background script (it needs
+`@grant GM_setValue`), for example `await GM.setValue("debug", { step: "fetched", count, at: Date.now() })`, and
+install a temporary probe:
+
+```js
+// ==UserScript==
+// @name         my-script probe
+// @namespace    https://example.com/your-namespace
+// @version      0.1.0
+// @match        https://example.com/
+// @storageName  my-script-store
+// @grant        GM_getValue
+// @grant        GM_addValueChangeListener
+// ==/UserScript==
+
+console.log("[probe] initial", JSON.stringify(GM_getValue("debug")));
+GM_addValueChangeListener("debug", (name, oldValue, newValue) =>
+  console.log("[probe]", name, JSON.stringify(newValue))
+);
+```
+
+The background script declares the same `@storageName my-script-store`. Open the probe's page, `sctl debug start`
+on it, trigger a run, then `sctl debug console --tab $TAB --text "[probe]"`. Ask the user before deleting the
+probe (and before removing the debug writes from the real script).
+
+**Hand over what you cannot see.** In ScriptCat's script list the run-status column shows running / complete /
+error and the next run time of a scheduled script; clicking it shows the `GM_log` output. Make that output
+useful: `GM_log` at start, at each step and before settling; resolve with a value that summarises the result;
+`reject` with a real reason.
 
-- Hand over to the user: in ScriptCat's script list the run-status column shows running / complete / error and
-  the next run time of a scheduled script; clicking it shows the `GM_log` output.
-- Make the script observable: `GM_log` at start, at each step and before settling; resolve with a value that
-  summarises the result; `reject` with a real reason.
-- When the logic can be tested on a page, verify that part with a temporary page script first, then move it into
-  the background script.
+When the logic can be tested on a page, verify that part with a temporary page script first, then move it into
+the background script.
 
 ## Cleaning up
 
diff --git a/skills/scriptcat-userscript/references/patterns.md b/skills/scriptcat-userscript/references/patterns.md
new file mode 100644
index 000000000..ad80162bf
--- /dev/null
+++ b/skills/scriptcat-userscript/references/patterns.md
@@ -0,0 +1,152 @@
+# Patterns
+
+Small building blocks that come up in most scripts. Each one lists the grants it needs; merge them into the
+script's header. Signatures: `scriptcat.d.ts`.
+
+## Wait for an element
+
+Pages render late and re-render often. Wait instead of assuming the element exists at injection time. No grant.
+
+```js
+function waitFor(selector, { root = document, timeout = 10000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const found = root.querySelector(selector);
+    if (found) return resolve(found);
+    const observer = new MutationObserver(() => {
+      const el = root.querySelector(selector);
+      if (el) {
+        observer.disconnect();
+        clearTimeout(timer);
+        resolve(el);
+      }
+    });
+    observer.observe(root === document ? document.documentElement : root, { childList: true, subtree: true });
+    const timer = setTimeout(() => {
+      observer.disconnect();
+      reject(new Error(`waitFor timed out: ${selector}`));
+    }, timeout);
+  });
+}
+
+const button = await waitFor("#toolbar");
+```
+
+To act on every matching element that ever appears (list items, feed entries), keep the observer running and mark
+handled nodes, e.g. with `el.dataset.myScript = "1"`, instead of disconnecting.
+
+## Single-page apps
+
+The script runs once per real page load; an SPA changes views without one. Grant: `window.onurlchange`.
+
+```js
+function onRoute(url) {
+  if (new URL(url).pathname.startsWith("/watch")) enhanceWatchPage();
+}
+onRoute(location.href);
+if (window.onurlchange === null) {
+  window.addEventListener("urlchange", (e) => onRoute(e.url));
+}
+```
+
+`window.onurlchange === null` means the feature is available (it relies on the browser's Navigation API). Combine
+with `waitFor`: the new view's DOM usually arrives after the URL changes.
+
+## A menu switch that remembers its state
+
+Grants: `GM_getValue`, `GM_setValue`, `GM_registerMenuCommand`.
+
+```js
+const MENU_ID = "toggle-enabled";
+function renderMenu() {
+  const enabled = GM_getValue("enabled", true);
+  GM_registerMenuCommand(
+    enabled ? "✅ Enabled (click to disable)" : "⛔ Disabled (click to enable)",
+    () => {
+      GM_setValue("enabled", !enabled);
+      renderMenu();
+    },
+    { id: MENU_ID, autoClose: false }
+  );
+}
+renderMenu();
+```
+
+Registering again with the same `id` replaces the entry's label and listener instead of adding a second entry.
+The menu shows in ScriptCat's popup.
+
+## Cross-origin request
+
+Grants: `GM_xmlhttpRequest`; header: `@connect api.example.com` for every host you call (a subdomain matches
+its parent's `@connect`). Wrapping the callback API keeps the code linear:
+
+```js
+function request(details) {
+  return new Promise((resolve, reject) => {
+    GM_xmlhttpRequest({
+      ...details,
+      onload: (res) =>
+        res.status >= 200 && res.status < 300 ? resolve(res) : reject(new Error(`HTTP ${res.status}`)),
+      onerror: () => reject(new Error("network error")),
+      ontimeout: () => reject(new Error("timeout")),
+    });
+  });
+}
+
+const res = await request({ url: "https://api.example.com/items", responseType: "json", timeout: 15000 });
+const items = res.response;
+```
+
+The browser's cookies for the target site are sent unless `anonymous: true`. Requests to the page's own host
+need no `@connect`.
+
+## Styles
+
+Grant: `GM_addStyle`. It returns the `<style>` element and is not blocked by the page's CSP.
+
+```js
+const style = GM_addStyle(`
+  .my-script-badge { position: fixed; right: 12px; bottom: 12px; z-index: 2147483647; }
+`);
+// style.remove() to undo
+```
+
+Prefix your own classes (`my-script-…`) so they do not collide with the site's.
+
+## Localise the script's own text
+
+No grant: `GM_info.userLanguage` is ScriptCat's interface language, e.g. `"zh-CN"`. It can be empty (in an
+`@early-start` script, read it after `await CAT_scriptLoaded()`), so fall back to the browser's language.
+
+```js
+const MESSAGES = {
+  en: { hello: "Hello" },
+  "zh-CN": { hello: "你好" },
+};
+const lang = GM_info.userLanguage || navigator.language;
+const t = (key) => (MESSAGES[lang] ?? MESSAGES[lang.split("-")[0]] ?? MESSAGES.en)[key];
+```
+
+## Background or scheduled run with retry
+
+Grants: `GM_xmlhttpRequest`, `GM_setValue`, `GM_log`, plus `@connect` for the host. `CATRetryError` needs no
+grant.
+
+```js
+return (async () => {
+  GM_log("check-in started", "info");
+  let res;
+  try {
+    res = await request({ url: "https://api.example.com/checkin", method: "POST", responseType: "json" });
+  } catch (err) {
+    // Temporary failure: try again in 10 minutes. A plain reject would use up a `once` period.
+    throw new CATRetryError(`check-in failed: ${err.message}`, 600);
+  }
+  await GM.setValue("lastCheckin", { at: Date.now(), result: res.response });
+  GM_log("check-in done", "info");
+  return res.response.message; // logged as the run's result
+})();
+```
+
+`request` is the helper from [Cross-origin request](#cross-origin-request). Throwing inside the `async` function
+rejects the returned Promise, which is what ScriptCat reads. Settle only after the last `await`; see
+[background.md](background.md) for the lifecycle and retry rules.

From e1da49a4f90718b15a9655f75797cb11f9919a79 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=8E=8B=E4=B8=80=E4=B9=8B?= <yz@ggnb.top>
Date: Wed, 4 Nov 2026 19:09:50 +0800
Subject: [PATCH 4/7] =?UTF-8?q?=E2=9C=A8=20scriptcat-userscript=20Skill=20?=
 =?UTF-8?q?=E9=99=84=E5=B8=A6=E9=9D=99=E6=80=81=E6=A3=80=E6=9F=A5=E4=B8=8E?=
 =?UTF-8?q?=E5=A3=B3=E8=84=9A=E6=9C=AC=E7=94=9F=E6=88=90=E5=B7=A5=E5=85=B7?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- scripts/check.mjs：零依赖静态检查，按运行时规则报告未声明 grant 的 API 调用（含 depend 一并注入的 API）、@grant none 下用 GM API/unsafeWindow、none 与其他 grant 混写、页面脚本缺 @match/@include、后台脚本用 GM_getTab 系列、cron 字段/once/空格写法错误；警告未知 grant、后台脚本无顶层 return、多行 @crontab、@run-at/@early-start 不生效、请求域名不在 @connect 也不在 @match 下；有 error 时退出码 1
- scripts/stub.mjs：从本地脚本生成 @require file:/// 壳脚本（保留头部与 UserConfig），配合本地热重载
- check.test.mjs 对照 SUPPORTED_GRANTS 守卫内置 grant 清单；vitest 的 scripts 项目纳入 skills/**/*.test.mjs
- SKILL.md、dev-loop.md、README 补充用法
---
 skills/scriptcat-userscript/README.md         |   5 +-
 skills/scriptcat-userscript/SKILL.md          |  12 +
 .../references/dev-loop.md                    |   8 +
 skills/scriptcat-userscript/scripts/check.mjs | 482 ++++++++++++++++++
 .../scripts/check.test.mjs                    | 209 ++++++++
 skills/scriptcat-userscript/scripts/stub.mjs  |  51 ++
 .../scripts/stub.test.mjs                     |  98 ++++
 vitest.config.ts                              |   2 +-
 8 files changed, 865 insertions(+), 2 deletions(-)
 create mode 100644 skills/scriptcat-userscript/scripts/check.mjs
 create mode 100644 skills/scriptcat-userscript/scripts/check.test.mjs
 create mode 100644 skills/scriptcat-userscript/scripts/stub.mjs
 create mode 100644 skills/scriptcat-userscript/scripts/stub.test.mjs

diff --git a/skills/scriptcat-userscript/README.md b/skills/scriptcat-userscript/README.md
index f3828065a..5753f4b98 100644
--- a/skills/scriptcat-userscript/README.md
+++ b/skills/scriptcat-userscript/README.md
@@ -14,9 +14,12 @@
 | `references/userconfig.md` | `==UserConfig==` 用户配置格式 |
 | `references/patterns.md` | 常用写法：等待元素、SPA 路由切换、带记忆的菜单开关、跨域请求、样式、多语言、带重试的后台运行 |
 | `references/dev-loop.md` | 用 sctl 侦察页面 → 安装 → 看控制台 → 重装或 `sctl edit` 迭代；本地文件热重载（`@require file:///` 壳脚本）；用探针脚本观察后台脚本 |
+| `scripts/check.mjs` | 零依赖静态检查：未声明 grant、`@grant none` 误用、缺 `@match`、cron 写法、`@connect` 缺失等；有 error 时退出码 1 |
+| `scripts/stub.mjs` | 生成本地热重载用的 `@require file:///` 壳脚本 |
 
 API 以 `src/types/scriptcat.d.ts` 和 `src/pkg/utils/script_compat.ts`（支持的指令与 grant 白名单）为准；
-修改这两处时同步检查本 Skill。sctl 本身的操作规范在 sctl 仓库的 `skills/sctl`，这里只引用、不重复。
+修改这两处时同步检查本 Skill。`scripts/check.mjs` 内置的 grant 清单由 `check.test.mjs` 对照 `SUPPORTED_GRANTS` 守卫，
+依赖注入表（`DEPENDS`）与 `src/app/service/content/gm_api/` 的 `depend` 声明需手工同步。sctl 本身的操作规范在 sctl 仓库的 `skills/sctl`，这里只引用、不重复。
 
 ## 安装
 
diff --git a/skills/scriptcat-userscript/SKILL.md b/skills/scriptcat-userscript/SKILL.md
index 3ac686783..4d6a81b81 100644
--- a/skills/scriptcat-userscript/SKILL.md
+++ b/skills/scriptcat-userscript/SKILL.md
@@ -156,6 +156,18 @@ background run with retry.
 
 Writing the file is half the job; the other half is seeing it run.
 
+First run the static check bundled with this skill (Node 18+, no dependencies; paths are relative to this
+skill's directory):
+
+```sh
+node scripts/check.mjs my-script.user.js   # exit 1 = errors that will break the script at runtime
+```
+
+It reports `error|warn <rule> <file>:<line> <message>`: APIs used without their `@grant`, GM APIs or
+`unsafeWindow` under `@grant none`, a page script without `@match`, invalid `@crontab` expressions, request hosts
+missing from `@connect`, and similar. Fix every error; read each warning and fix it or say why it does not apply.
+It is a static check — it cannot tell whether the script does what the user asked.
+
 - **sctl is available** (`sctl status` shows ScriptCat connected): install it into the user's ScriptCat and
   verify it in their browser, following [references/dev-loop.md](references/dev-loop.md). It also covers
   scouting the target page before you write code, iterating on a local file without an approval per change, and
diff --git a/skills/scriptcat-userscript/references/dev-loop.md b/skills/scriptcat-userscript/references/dev-loop.md
index b1a171966..617add669 100644
--- a/skills/scriptcat-userscript/references/dev-loop.md
+++ b/skills/scriptcat-userscript/references/dev-loop.md
@@ -107,6 +107,14 @@ the file you are editing, and an empty body.
 // ==/UserScript==
 ```
 
+Generate the stub instead of writing it by hand — it copies the header and any `==UserConfig==` block (the
+settings form is built from the installed code) and appends the `@require` with the absolute path:
+
+```sh
+node scripts/stub.mjs my-script.user.js -o my-script.stub.user.js   # scripts/ of this skill
+sctl install ./my-script.stub.user.js -o json
+```
+
 ScriptCat reads a `file:///` `@require` again on every page load. When the file has changed, it re-registers
 the script during that load, so the new code runs from the next load at the latest: after saving, reload, and if
 the old code still ran, reload once more. Logging a revision marker (`console.log("[my-script] r7")`) makes it
diff --git a/skills/scriptcat-userscript/scripts/check.mjs b/skills/scriptcat-userscript/scripts/check.mjs
new file mode 100644
index 000000000..c14aa01f3
--- /dev/null
+++ b/skills/scriptcat-userscript/scripts/check.mjs
@@ -0,0 +1,482 @@
+#!/usr/bin/env node
+// Static checks for a ScriptCat userscript: catches the mistakes that make a script install fine and then fail at
+// runtime (missing grants, @grant none misuse, bad cron expressions, …). Zero dependencies; run with Node 18+.
+//
+//   node check.mjs my-script.user.js [more.user.js …]
+//
+// Prints one line per finding — `error|warn <rule> <file>:<line> <message>` — and exits 1 when any error was found,
+// 0 otherwise, 2 on a usage or read error. The rules mirror ScriptCat's runtime; the sources are named per rule.
+import { readFileSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import process from "node:process";
+
+// Mirror of SUPPORTED_GRANTS in src/pkg/utils/script_compat.ts; check.test.mjs fails when the two differ.
+export const KNOWN_GRANTS = new Set([
+  "none",
+  "unsafeWindow",
+  "GM_info",
+  "GM.info",
+  "window.onurlchange",
+  "CAT.agent.conversation",
+  "CAT.agent.dom",
+  "CAT.agent.model",
+  "CAT.agent.opfs",
+  "CAT.agent.skills",
+  "CAT.agent.task",
+  "CAT_createBlobUrl",
+  "CAT_fetchBlob",
+  "CAT_fetchDocument",
+  "CAT_fileStorage",
+  "CAT_registerMenuInput",
+  "CAT_scriptLoaded",
+  "CAT_unregisterMenuInput",
+  "CAT_userConfig",
+  "GM.addElement",
+  "GM.addStyle",
+  "GM.addValueChangeListener",
+  "GM.closeInTab",
+  "GM.closeNotification",
+  "GM.cookie",
+  "GM.deleteValue",
+  "GM.deleteValues",
+  "GM.download",
+  "GM.getResourceText",
+  "GM.getResourceURL",
+  "GM.getResourceUrl",
+  "GM.getTab",
+  "GM.getTabs",
+  "GM.getValue",
+  "GM.getValues",
+  "GM.listValues",
+  "GM.log",
+  "GM.notification",
+  "GM.openInTab",
+  "GM.registerMenuCommand",
+  "GM.removeValueChangeListener",
+  "GM.saveTab",
+  "GM.setClipboard",
+  "GM.setValue",
+  "GM.setValues",
+  "GM.unregisterMenuCommand",
+  "GM.updateNotification",
+  "GM.xmlHttpRequest",
+  "GM_addElement",
+  "GM_addStyle",
+  "GM_addValueChangeListener",
+  "GM_closeInTab",
+  "GM_closeNotification",
+  "GM_cookie",
+  "GM_deleteValue",
+  "GM_deleteValues",
+  "GM_download",
+  "GM_getResourceText",
+  "GM_getResourceURL",
+  "GM_getTab",
+  "GM_getTabs",
+  "GM_getValue",
+  "GM_getValues",
+  "GM_listValues",
+  "GM_log",
+  "GM_notification",
+  "GM_openInTab",
+  "GM_registerMenuCommand",
+  "GM_removeValueChangeListener",
+  "GM_saveTab",
+  "GM_setClipboard",
+  "GM_setValue",
+  "GM_setValues",
+  "GM_unregisterMenuCommand",
+  "GM_updateNotification",
+  "GM_xmlhttpRequest",
+  "window.close",
+  "window.focus",
+]);
+
+// Same rule as getGrantCandidates (src/app/service/content/gm_api/grant.ts): only the prefix is swapped, case kept.
+const candidates = (name) => {
+  if (name.startsWith("GM.")) return [name, `GM_${name.slice(3)}`];
+  if (name.startsWith("GM_")) return [name, `GM.${name.slice(3)}`];
+  return [name];
+};
+
+// APIs injected together with another one (`depend` in src/app/service/content/gm_api/*.ts): granting the key also
+// makes these exact names available. Only the exact names — their GM_/GM. counterparts are not added.
+const DEPENDS = {
+  "GM.getValues": ["GM_getValues"],
+  "GM.addValueChangeListener": ["GM_addValueChangeListener"],
+  "GM.removeValueChangeListener": ["GM_removeValueChangeListener"],
+  "GM.log": ["GM_log"],
+  "GM.registerMenuCommand": ["GM_registerMenuCommand"],
+  CAT_registerMenuInput: ["GM_registerMenuCommand"],
+  "GM.addStyle": ["GM_addStyle"],
+  "GM.addElement": ["GM_addElement"],
+  "GM.unregisterMenuCommand": ["GM_unregisterMenuCommand"],
+  CAT_unregisterMenuInput: ["GM_unregisterMenuCommand"],
+  CAT_fileStorage: ["CAT_fetchBlob"],
+  GM_openInTab: ["GM_closeInTab"],
+  "GM.openInTab": ["GM_openInTab", "GM_closeInTab"],
+  "GM.getTab": ["GM_getTab"],
+  "GM.saveTab": ["GM_saveTab"],
+  "GM.getTabs": ["GM_getTabs"],
+  "GM.setClipboard": ["GM_setClipboard"],
+  "GM.getResourceText": ["GM_getResourceText"],
+  "GM.getResourceURL": ["GM_getResourceURL"],
+  "GM.getResourceUrl": ["GM_getResourceURL"],
+};
+
+// Every API name a script can call with these grants, the way createContext (create_context.ts) injects them.
+function availableApis(grants) {
+  const available = new Set();
+  const inject = (name) => {
+    if (available.has(name)) return;
+    available.add(name);
+    for (const dep of DEPENDS[name] ?? []) inject(dep);
+  };
+  for (const grant of grants) for (const c of candidates(grant)) inject(c);
+  return available;
+}
+
+const RUN_AT = new Set(["document-start", "document-body", "document-end", "document-idle", "context-menu"]);
+const TAB_APIS = new Set(["GM_getTab", "GM_saveTab", "GM_getTabs", "GM.getTab", "GM.saveTab", "GM.getTabs"]);
+const REQUEST_APIS = ["GM_xmlhttpRequest", "GM.xmlHttpRequest", "GM_download", "GM.download"];
+
+const lineAt = (text, index) => {
+  let line = 1;
+  for (let i = 0; i < index; i++) if (text.charCodeAt(i) === 10) line++;
+  return line;
+};
+
+// Blanks out comments, and separately string/template/regex contents, keeping every offset and newline so that line
+// numbers still match the source. Template `${…}` expressions stay as code.
+function lex(code) {
+  const noComments = code.split("");
+  const bare = code.split("");
+  const strings = [];
+  const blank = (arr, from, to) => {
+    for (let i = from; i < to; i++) if (arr[i] !== "\n") arr[i] = " ";
+  };
+  let i = 0;
+  let lastSignificant = "";
+  const templateDepth = []; // brace depth at which each open `${` returns to its template
+  let braceDepth = 0;
+  const readQuoted = (quote, start) => {
+    let j = start + 1;
+    while (j < code.length && code[j] !== quote && code[j] !== "\n") j += code[j] === "\\" ? 2 : 1;
+    return Math.min(j + 1, code.length);
+  };
+  const readTemplate = (start) => {
+    // returns [end, endsWithExpression]
+    let j = start;
+    while (j < code.length) {
+      if (code[j] === "\\") j += 2;
+      else if (code[j] === "`") return [j + 1, false];
+      else if (code[j] === "$" && code[j + 1] === "{") return [j + 2, true];
+      else j++;
+    }
+    return [j, false];
+  };
+  const templatePiece = (start, from) => {
+    const [end, expr] = readTemplate(from);
+    strings.push({ value: code.slice(from, expr ? end - 2 : end - 1), index: from });
+    blank(bare, from, expr ? end - 2 : end - 1);
+    if (expr) templateDepth.push(braceDepth);
+    lastSignificant = expr ? "{" : "`";
+    return end;
+  };
+  while (i < code.length) {
+    const c = code[i];
+    const next = code[i + 1];
+    if (c === "/" && next === "/") {
+      const end = code.indexOf("\n", i) === -1 ? code.length : code.indexOf("\n", i);
+      blank(noComments, i, end);
+      blank(bare, i, end);
+      i = end;
+    } else if (c === "/" && next === "*") {
+      const close = code.indexOf("*/", i + 2);
+      const end = close === -1 ? code.length : close + 2;
+      blank(noComments, i, end);
+      blank(bare, i, end);
+      i = end;
+    } else if (c === '"' || c === "'") {
+      const end = readQuoted(c, i);
+      strings.push({ value: code.slice(i + 1, end - 1), index: i + 1 });
+      blank(bare, i + 1, end - 1);
+      lastSignificant = c;
+      i = end;
+    } else if (c === "`") {
+      i = templatePiece(i, i + 1);
+    } else if (c === "}" && templateDepth.length && templateDepth[templateDepth.length - 1] === braceDepth) {
+      templateDepth.pop();
+      i = templatePiece(i, i + 1);
+    } else if (c === "/" && (lastSignificant === "" || /[(,=:[!&|?{};+\-*%<>~^]/.test(lastSignificant))) {
+      let j = i + 1;
+      let inClass = false;
+      while (j < code.length && code[j] !== "\n") {
+        if (code[j] === "\\") j += 2;
+        else if (code[j] === "[") ((inClass = true), j++);
+        else if (code[j] === "]") ((inClass = false), j++);
+        else if (code[j] === "/" && !inClass) break;
+        else j++;
+      }
+      blank(bare, i + 1, j);
+      lastSignificant = "/";
+      i = j + 1;
+    } else {
+      if (c === "{") braceDepth++;
+      else if (c === "}") braceDepth--;
+      if (!/\s/.test(c)) lastSignificant = /[\w$)\]]/.test(c) ? "a" : c;
+      i++;
+    }
+  }
+  return { noComments: noComments.join(""), bare: bare.join(""), strings };
+}
+
+function parseHeader(code) {
+  const start = code.match(/^[ \t]*\/\/[ \t]*==UserScript==[ \t]*$/m);
+  const end = code.match(/^[ \t]*\/\/[ \t]*==\/UserScript==[ \t]*$/m);
+  if (!start || !end || end.index < start.index) return null;
+  const meta = new Map();
+  const lines = code.slice(0, end.index).split("\n");
+  const firstLine = lineAt(code, start.index);
+  for (let n = firstLine; n <= lines.length; n++) {
+    const m = lines[n - 1].match(/^\s*\/\/\s*@(\S+)(?:\s+(.*?))?\s*$/);
+    if (!m) continue;
+    const tag = m[1].toLowerCase();
+    if (!meta.has(tag)) meta.set(tag, []);
+    meta.get(tag).push({ value: m[2] ?? "", line: n });
+  }
+  return { meta, firstLine, bodyStart: end.index + end[0].length };
+}
+
+const hostOf = (pattern) => {
+  if (pattern === "<all_urls>") return "*";
+  const m = pattern.match(/^[^:/]*:\/\/([^/:]*)/);
+  return m ? m[1].toLowerCase() : null;
+};
+
+// Same matching as getConnectMatched (src/app/service/service_worker/gm_api/gm_api.ts): a request to the page's own
+// host needs nothing; otherwise an @connect entry must equal the host or a parent domain of it, be `*`, or be `self`
+// with the host under the page's domain. The page host is approximated from @match/@include.
+function connectCovers(host, connects, pageHosts) {
+  const under = (h, d) => `.${h}`.endsWith(`.${d}`);
+  for (const page of pageHosts) {
+    if (page === "*") continue;
+    if (page.startsWith("*.") ? under(host, page.slice(2)) : host === page) return true;
+  }
+  for (const c of connects) {
+    if (c === "*") return true;
+    if (c === "self") {
+      if (pageHosts.some((p) => p !== "*" && under(host, p.replace(/^\*\./, "")))) return true;
+    } else if (under(host, c)) return true;
+  }
+  return false;
+}
+
+function cronProblem(expr) {
+  if (/\s{2,}/.test(expr)) return "separate the fields with single spaces (ScriptCat splits on one space)";
+  const parts = expr.trim().split(" ");
+  if (parts.length !== 5 && parts.length !== 6) return `expected 5 fields (or 6 with seconds), found ${parts.length}`;
+  let onces = 0;
+  for (const part of parts) {
+    if (part.startsWith("once")) {
+      onces++;
+      if (!/^once(\([^()\s]+\))?$/.test(part)) return `"${part}" is not "once" or "once(<values>)"`;
+    } else if (!/^[\w*,/-]+$/.test(part)) {
+      return `"${part}" is not a valid cron field`;
+    }
+  }
+  if (onces > 1) return "only one field may use once";
+  return null;
+}
+
+export function checkScript(code) {
+  const findings = [];
+  const add = (level, rule, line, message) => findings.push({ level, rule, line, message });
+  const header = parseHeader(code);
+  if (!header) {
+    add("error", "header-missing", 1, "no // ==UserScript== … // ==/UserScript== block");
+    return findings;
+  }
+  const { meta, firstLine, bodyStart } = header;
+  const values = (tag) => (meta.get(tag) ?? []).map((e) => e.value);
+
+  if (!meta.has("name")) add("error", "name-missing", firstLine, "@name is required");
+  if (!meta.has("namespace"))
+    add("warn", "namespace-missing", firstLine, "@name + @namespace identify the script; set both");
+
+  const isBackground = meta.has("background") || meta.has("crontab");
+  const grants = meta.get("grant") ?? [];
+  const grantSet = new Set(grants.map((g) => g.value));
+  const grantNone = grantSet.has("none");
+  const available = availableApis(grantSet);
+
+  for (const g of grants) {
+    if (g.value === "none") {
+      if (grants.some((o) => o.value !== "none")) {
+        add("error", "grant-none-conflict", g.line, "@grant none cannot be combined with other grants");
+      }
+    } else if (!candidates(g.value).some((c) => KNOWN_GRANTS.has(c))) {
+      add("warn", "grant-unknown", g.line, `ScriptCat does not implement "${g.value}"; this grant has no effect`);
+    }
+  }
+
+  if (!isBackground && !meta.has("match") && !meta.has("include")) {
+    add("error", "match-missing", firstLine, "a page script needs @match or @include, or it never runs");
+  }
+
+  const runAts = meta.get("run-at") ?? [];
+  runAts.forEach((r, i) => {
+    if (i > 0) add("warn", "run-at-invalid", r.line, "only the first @run-at is used");
+    else if (!RUN_AT.has(r.value))
+      add("warn", "run-at-invalid", r.line, `unknown @run-at "${r.value}"; falls back to document-idle`);
+  });
+  for (const e of meta.get("early-start") ?? []) {
+    if (runAts[0]?.value !== "document-start") {
+      add("warn", "early-start-ignored", e.line, "@early-start only takes effect with @run-at document-start");
+    }
+  }
+
+  const crons = meta.get("crontab") ?? [];
+  crons.forEach((c, i) => {
+    const problem = cronProblem(c.value);
+    if (problem) add("error", "cron-invalid", c.line, `@crontab "${c.value}": ${problem}`);
+    if (i > 0) {
+      add("warn", "cron-multiple", c.line, "every @crontab line is scheduled and one bad line stops all; write one");
+    }
+  });
+
+  const body = code.slice(bodyStart);
+  const bodyLine = (index) => lineAt(code, bodyStart + index);
+  const { noComments, bare, strings } = lex(body);
+
+  const used = [];
+  const usage = /(?<![\w$.])(GM_[A-Za-z]\w*|GM\.[A-Za-z]\w*|CAT_[A-Za-z]\w*|CAT\.agent\.\w+)/g;
+  for (const m of bare.matchAll(usage)) {
+    if (m[1] === "GM_info" || m[1] === "GM.info") continue;
+    used.push({ name: m[1], index: m.index });
+  }
+  for (const m of noComments.matchAll(/(?<![\w$])onurlchange\b|addEventListener\(\s*["'`]urlchange["'`]/g)) {
+    used.push({ name: "window.onurlchange", index: m.index });
+  }
+  used.sort((a, b) => a.index - b.index);
+
+  const definedInBody = new Set(
+    [...bare.matchAll(/(?:function|const|let|var|class)\s+(GM_\w+|CAT_\w+)/g)].map((m) => m[1])
+  );
+  const reported = new Set();
+  for (const u of used) {
+    const key = `${u.name}`;
+    if (reported.has(key) || definedInBody.has(u.name)) continue;
+    const known = candidates(u.name).some((c) => KNOWN_GRANTS.has(c));
+    if (!known) {
+      reported.add(key);
+      add(
+        "warn",
+        "api-unsupported",
+        bodyLine(u.index),
+        `${u.name} is not a ScriptCat API (fine if a @require'd library defines it)`
+      );
+      continue;
+    }
+    if (isBackground && TAB_APIS.has(u.name)) {
+      reported.add(key);
+      add("error", "background-tab-api", bodyLine(u.index), `${u.name} is not available in background scripts`);
+      continue;
+    }
+    if (grantNone) {
+      reported.add(key);
+      add("error", "grant-none-api", bodyLine(u.index), `${u.name} does not exist under @grant none`);
+      continue;
+    }
+    if (!available.has(u.name)) {
+      reported.add(key);
+      add("error", "grant-missing", bodyLine(u.index), `${u.name} is used but not granted; add "// @grant ${u.name}"`);
+    }
+  }
+
+  if (grantNone) {
+    const m = bare.match(/(?<![\w$.])unsafeWindow\b/);
+    if (m)
+      add(
+        "error",
+        "grant-none-unsafewindow",
+        bodyLine(m.index),
+        "unsafeWindow does not exist under @grant none; use window"
+      );
+  }
+
+  if (isBackground && !hasTopLevelReturn(bare)) {
+    add(
+      "warn",
+      "background-no-return",
+      firstLine,
+      "no top-level return: the run is complete as soon as the body's synchronous part ends"
+    );
+  }
+
+  if (used.some((u) => REQUEST_APIS.includes(u.name))) {
+    const connects = values("connect").map((c) => c.toLowerCase());
+    const pageHosts = isBackground ? [] : [...values("match"), ...values("include")].map(hostOf).filter(Boolean);
+    const seen = new Set();
+    for (const s of strings) {
+      const m = s.value.match(/^https?:\/\/([^/:?#]+)/i);
+      if (!m) continue;
+      const host = m[1].toLowerCase();
+      if (seen.has(host) || connectCovers(host, connects, pageHosts)) continue;
+      seen.add(host);
+      add(
+        "warn",
+        "connect-missing",
+        bodyLine(s.index),
+        `requests to ${host} prompt the user; add "// @connect ${host}" if the script requests it`
+      );
+    }
+  }
+
+  return findings.sort((a, b) => a.line - b.line);
+}
+
+function hasTopLevelReturn(bare) {
+  let depth = 0;
+  for (let i = 0; i < bare.length; i++) {
+    const c = bare[i];
+    if (c === "{" || c === "(" || c === "[") depth++;
+    else if (c === "}" || c === ")" || c === "]") depth--;
+    else if (
+      depth === 0 &&
+      bare.startsWith("return", i) &&
+      !/[\w$]/.test(bare[i - 1] ?? "") &&
+      !/[\w$]/.test(bare[i + 6] ?? "")
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function main(files) {
+  if (!files.length) {
+    console.error("usage: node check.mjs <script.user.js> [more.user.js …]");
+    return 2;
+  }
+  let status = 0;
+  for (const file of files) {
+    let code;
+    try {
+      code = readFileSync(file, "utf8");
+    } catch (e) {
+      console.error(`cannot read ${file}: ${e.message}`);
+      return 2;
+    }
+    const findings = checkScript(code);
+    for (const f of findings) console.log(`${f.level} ${f.rule} ${file}:${f.line} ${f.message}`);
+    if (!findings.length) console.log(`ok ${file}`);
+    if (findings.some((f) => f.level === "error")) status = 1;
+  }
+  return status;
+}
+
+// realpath: the skill is usually installed through a symlink, while import.meta.url is the resolved path
+if (process.argv[1] && fileURLToPath(import.meta.url) === realpathSync(process.argv[1])) {
+  process.exitCode = main(process.argv.slice(2));
+}
diff --git a/skills/scriptcat-userscript/scripts/check.test.mjs b/skills/scriptcat-userscript/scripts/check.test.mjs
new file mode 100644
index 000000000..3d109e8da
--- /dev/null
+++ b/skills/scriptcat-userscript/scripts/check.test.mjs
@@ -0,0 +1,209 @@
+import { describe, it, expect } from "vitest";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+import { SUPPORTED_GRANTS } from "@App/pkg/utils/script_compat";
+import { checkScript, KNOWN_GRANTS } from "./check.mjs";
+import process from "node:process";
+
+const CHECK = path.join(path.dirname(fileURLToPath(import.meta.url)), "check.mjs");
+
+function script(headerLines, body = "") {
+  return ["// ==UserScript==", ...headerLines.map((l) => `// ${l}`), "// ==/UserScript==", "", body].join("\n");
+}
+
+const PAGE = ["@name Demo", "@namespace https://example.com/demo", "@match https://example.com/*"];
+const BACKGROUND = ["@name Demo", "@namespace https://example.com/demo", "@background"];
+
+// 只比较规则、级别和行号；提示文案不是契约
+const summary = (code) => checkScript(code).map(({ level, rule, line }) => ({ level, rule, line }));
+
+describe("check.mjs 内置 grant 清单", () => {
+  it("与脚本猫的 SUPPORTED_GRANTS 完全一致", () => {
+    expect([...KNOWN_GRANTS].sort()).toEqual([...SUPPORTED_GRANTS].sort());
+  });
+});
+
+describe("checkScript", () => {
+  it("声明齐全的页面脚本没有任何发现", () => {
+    const code = script(
+      [...PAGE, "@grant GM_setValue", "@grant GM.xmlHttpRequest"],
+      'GM_setValue("a", 1);\nawait GM.setValue("b", 2);\nGM.xmlHttpRequest({ url: "/x" });\nGM_info.script.name;'
+    );
+    expect(summary(code)).toEqual([]);
+  });
+
+  it("缺少脚本头时报错", () => {
+    expect(summary("console.log(1);")).toEqual([{ level: "error", rule: "header-missing", line: 1 }]);
+  });
+
+  it("缺少 @name 报错、缺少 @namespace 警告", () => {
+    const code = script(["@match https://example.com/*"]);
+    expect(summary(code)).toEqual([
+      { level: "error", rule: "name-missing", line: 1 },
+      { level: "warn", rule: "namespace-missing", line: 1 },
+    ]);
+  });
+
+  it("调用未声明 grant 的 API 时在调用所在行报错", () => {
+    const code = script(PAGE, '\nGM_setValue("a", 1);');
+    expect(summary(code)).toEqual([{ level: "error", rule: "grant-missing", line: 8 }]);
+  });
+
+  it("GM_foo 与 GM.foo 只在名字完全一致时互通：GM_xmlhttpRequest 不覆盖 GM.xmlHttpRequest", () => {
+    const ok = script([...PAGE, "@grant GM_setValue"], 'await GM.setValue("a", 1);');
+    expect(summary(ok)).toEqual([]);
+    const bad = script([...PAGE, "@grant GM_xmlhttpRequest"], 'GM.xmlHttpRequest({ url: "/x" });');
+    expect(summary(bad)).toEqual([{ level: "error", rule: "grant-missing", line: 8 }]);
+  });
+
+  it("被已授权 API 依赖而一并注入的 API 不需要单独授权，但别名不会随依赖扩散", () => {
+    const ok = script([...PAGE, "@grant GM_openInTab"], 'GM_closeInTab(GM_openInTab("https://example.com/"));');
+    expect(summary(ok)).toEqual([]);
+    const bad = script([...PAGE, "@grant GM_openInTab"], "GM.closeInTab(1);");
+    expect(summary(bad)).toEqual([{ level: "error", rule: "grant-missing", line: 8 }]);
+  });
+
+  it("注释、字符串和正则里出现的 API 名不算调用", () => {
+    const code = script(
+      PAGE,
+      '// GM_setValue("x")\n/* unsafeWindow */\nconst s = "GM_getValue";\nconst t = `GM_log ${1}`;\nconst r = /GM_cookie"/;'
+    );
+    expect(summary(code)).toEqual([]);
+  });
+
+  it("脚本猫未实现的 GM_* 名称只警告（可能来自 @require 的库）", () => {
+    const code = script(PAGE, "GM_config.open();");
+    expect(summary(code)).toEqual([{ level: "warn", rule: "api-unsupported", line: 7 }]);
+  });
+
+  it("@grant none 下使用 GM API 或 unsafeWindow 报错，GM_info 不受影响", () => {
+    const code = script([...PAGE, "@grant none"], 'GM_info.script.name;\nGM_setValue("a", 1);\nunsafeWindow.foo;');
+    expect(summary(code)).toEqual([
+      { level: "error", rule: "grant-none-api", line: 9 },
+      { level: "error", rule: "grant-none-unsafewindow", line: 10 },
+    ]);
+  });
+
+  it("@grant none 与其他 grant 混写报错", () => {
+    const code = script([...PAGE, "@grant none", "@grant GM_setValue"], 'GM_setValue("a", 1);');
+    expect(summary(code)).toEqual([
+      { level: "error", rule: "grant-none-conflict", line: 5 },
+      { level: "error", rule: "grant-none-api", line: 9 },
+    ]);
+  });
+
+  it("沙盒脚本使用 unsafeWindow 无需 grant", () => {
+    const code = script([...PAGE, "@grant GM_setValue"], 'GM_setValue("a", unsafeWindow.foo);');
+    expect(summary(code)).toEqual([]);
+  });
+
+  it("未知 grant 警告", () => {
+    const code = script([...PAGE, "@grant GM_doesNotExist"]);
+    expect(summary(code)).toEqual([{ level: "warn", rule: "grant-unknown", line: 5 }]);
+  });
+
+  it("使用 urlchange 事件需要 @grant window.onurlchange", () => {
+    const code = script(PAGE, 'window.addEventListener("urlchange", (e) => e.url);');
+    expect(summary(code)).toEqual([{ level: "error", rule: "grant-missing", line: 7 }]);
+    const granted = script([...PAGE, "@grant window.onurlchange"], 'window.addEventListener("urlchange", () => {});');
+    expect(summary(granted)).toEqual([]);
+  });
+
+  it("页面脚本没有 @match/@include 报错，后台脚本不需要", () => {
+    const page = script(["@name Demo", "@namespace https://example.com/demo"]);
+    expect(summary(page)).toEqual([{ level: "error", rule: "match-missing", line: 1 }]);
+    expect(summary(script(BACKGROUND, "return 1;"))).toEqual([]);
+  });
+
+  it("后台脚本使用 GM_getTab 系列报错", () => {
+    const code = script([...BACKGROUND, "@grant GM_getTab"], "GM_getTab(() => {});\nreturn 1;");
+    expect(summary(code)).toEqual([{ level: "error", rule: "background-tab-api", line: 8 }]);
+  });
+
+  it("后台脚本顶层没有 return 时警告，只在嵌套函数里 return 不算", () => {
+    const code = script(BACKGROUND, "function f() { return 1; }\nf();");
+    expect(summary(code)).toEqual([{ level: "warn", rule: "background-no-return", line: 1 }]);
+    expect(summary(script(BACKGROUND, "return new Promise((resolve) => resolve());"))).toEqual([]);
+  });
+
+  it("cron 字段数、once 写法和多余空格不合法时报错", () => {
+    const cron = (expr) =>
+      summary(script(["@name Demo", "@namespace https://example.com/demo", `@crontab ${expr}`], "return 1;"));
+    expect(cron("* * once * *")).toEqual([]);
+    expect(cron("0 * once(9-17) * * *")).toEqual([]);
+    expect(cron("* * *")).toEqual([{ level: "error", rule: "cron-invalid", line: 4 }]);
+    expect(cron("* once once * *")).toEqual([{ level: "error", rule: "cron-invalid", line: 4 }]);
+    expect(cron("* once(9-17 * * *")).toEqual([{ level: "error", rule: "cron-invalid", line: 4 }]);
+    expect(cron("* *  once * *")).toEqual([{ level: "error", rule: "cron-invalid", line: 4 }]);
+  });
+
+  it("多行 @crontab 警告", () => {
+    const code = script(
+      ["@name Demo", "@namespace https://example.com/demo", "@crontab * * once * *", "@crontab 0 9 * * *"],
+      "return 1;"
+    );
+    expect(summary(code)).toEqual([{ level: "warn", rule: "cron-multiple", line: 5 }]);
+  });
+
+  it("@run-at 取值非法或 @early-start 未配 document-start 时警告", () => {
+    expect(summary(script([...PAGE, "@run-at document-ready"]))).toEqual([
+      { level: "warn", rule: "run-at-invalid", line: 5 },
+    ]);
+    expect(summary(script([...PAGE, "@run-at document-idle", "@early-start"]))).toEqual([
+      { level: "warn", rule: "early-start-ignored", line: 6 },
+    ]);
+    expect(summary(script([...PAGE, "@run-at document-start", "@early-start"]))).toEqual([]);
+  });
+
+  it("请求的字面量 URL 不在 @connect 也不在 @match 域名下时警告", () => {
+    const base = [...PAGE, "@grant GM_xmlhttpRequest"];
+    const req = (url) => `GM_xmlhttpRequest({ url: "${url}" });`;
+    expect(summary(script(base, req("https://example.com/api")))).toEqual([]);
+    expect(summary(script([...base, "@connect example.org"], req("https://api.example.org/v1")))).toEqual([]);
+    expect(summary(script([...base, "@connect *"], req("https://other.net/")))).toEqual([]);
+    expect(summary(script(base, req("https://other.net/")))).toEqual([
+      { level: "warn", rule: "connect-missing", line: 8 },
+    ]);
+    expect(summary(script(base, req("https://sub.example.com/")))).toEqual([
+      { level: "warn", rule: "connect-missing", line: 8 },
+    ]);
+    expect(summary(script([...base, "@connect self"], req("https://sub.example.com/")))).toEqual([]);
+  });
+
+  it("不发请求的脚本不检查 URL 字面量", () => {
+    expect(summary(script(PAGE, 'const link = "https://other.net/";'))).toEqual([]);
+  });
+});
+
+describe("check.mjs 命令行", () => {
+  const run = (code) => {
+    const dir = mkdtempSync(path.join(os.tmpdir(), "sc-check-"));
+    const file = path.join(dir, "a.user.js");
+    writeFileSync(file, code);
+    try {
+      return spawnSync(process.execPath, [CHECK, file], { encoding: "utf8" });
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  };
+
+  it("有 error 时退出码为 1，并按「级别 规则 文件:行 说明」输出", () => {
+    const res = run(script(PAGE, 'GM_setValue("a", 1);'));
+    expect(res.status).toBe(1);
+    expect(res.stdout).toMatch(/^error grant-missing .*a\.user\.js:7 /m);
+  });
+
+  it("只有 warn 时退出码为 0", () => {
+    const res = run(script([...PAGE, "@grant GM_doesNotExist"]));
+    expect(res.status).toBe(0);
+    expect(res.stdout).toMatch(/^warn grant-unknown .*a\.user\.js:5 /m);
+  });
+
+  it("没有参数时退出码为 2", () => {
+    const res = spawnSync(process.execPath, [CHECK], { encoding: "utf8" });
+    expect(res.status).toBe(2);
+  });
+});
diff --git a/skills/scriptcat-userscript/scripts/stub.mjs b/skills/scriptcat-userscript/scripts/stub.mjs
new file mode 100644
index 000000000..d70043859
--- /dev/null
+++ b/skills/scriptcat-userscript/scripts/stub.mjs
@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+// Builds a stub for iterating on a page script from a local file: the script's own header (and UserConfig block)
+// plus `@require file:///<absolute path>`, with an empty body. ScriptCat re-reads a file:/// @require on every page
+// load, so after installing the stub once, saving the file and reloading the page runs the new code.
+//
+//   node stub.mjs my-script.user.js [-o my-script.stub.user.js]
+//
+// Exits 2 on a usage or read error, or when the source has no // ==UserScript== header.
+import { readFileSync, writeFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import process from "node:process";
+
+export function buildStub(source, absolutePath) {
+  const end = source.match(/^[ \t]*\/\/[ \t]*==\/UserScript==[ \t]*$/m);
+  if (!end || !/^[ \t]*\/\/[ \t]*==UserScript==[ \t]*$/m.test(source.slice(0, end.index))) {
+    throw new Error("source has no // ==UserScript== … // ==/UserScript== header");
+  }
+  const header = source.slice(0, end.index);
+  const parts = [`${header}// @require      ${pathToFileURL(absolutePath).href}\n${end[0]}\n`];
+  // ScriptCat builds the settings form from the installed code, so the stub must carry the UserConfig block too.
+  const userConfig = source.match(/\/\*\s*==UserConfig==[\s\S]+?==\/UserConfig==\s*\*\//);
+  if (userConfig) parts.push(`\n${userConfig[0]}\n`);
+  return parts.join("");
+}
+
+function main(args) {
+  const outIndex = args.indexOf("-o");
+  const out = outIndex === -1 ? undefined : args[outIndex + 1];
+  const inputs = outIndex === -1 ? args : [...args.slice(0, outIndex), ...args.slice(outIndex + 2)];
+  if (inputs.length !== 1 || (outIndex !== -1 && !out)) {
+    console.error("usage: node stub.mjs <script.user.js> [-o <stub.user.js>]");
+    return 2;
+  }
+  const file = path.resolve(inputs[0]);
+  let stub;
+  try {
+    stub = buildStub(readFileSync(file, "utf8"), file);
+  } catch (e) {
+    console.error(`${file}: ${e.message}`);
+    return 2;
+  }
+  if (out) writeFileSync(out, stub);
+  else process.stdout.write(stub);
+  return 0;
+}
+
+// realpath: the skill is usually installed through a symlink, while import.meta.url is the resolved path
+if (process.argv[1] && fileURLToPath(import.meta.url) === realpathSync(process.argv[1])) {
+  process.exitCode = main(process.argv.slice(2));
+}
diff --git a/skills/scriptcat-userscript/scripts/stub.test.mjs b/skills/scriptcat-userscript/scripts/stub.test.mjs
new file mode 100644
index 000000000..932f5a487
--- /dev/null
+++ b/skills/scriptcat-userscript/scripts/stub.test.mjs
@@ -0,0 +1,98 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, writeFileSync, readFileSync, rmSync, realpathSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { buildStub } from "./stub.mjs";
+import process from "node:process";
+
+const STUB = path.join(path.dirname(fileURLToPath(import.meta.url)), "stub.mjs");
+
+const SOURCE = [
+  "// ==UserScript==",
+  "// @name         Demo",
+  "// @namespace    https://example.com/demo",
+  "// @match        https://example.com/*",
+  "// @grant        GM_getValue",
+  "// @require      https://cdn.example.com/lib.js",
+  "// ==/UserScript==",
+  "",
+  "/* ==UserConfig==",
+  "general:",
+  "  token:",
+  "    title: Token",
+  " ==/UserConfig== */",
+  "",
+  'console.log(GM_getValue("general.token"));',
+  "",
+].join("\n");
+
+const tmpDirs = [];
+const tmpDir = () => {
+  const dir = mkdtempSync(path.join(os.tmpdir(), "sc stub-"));
+  tmpDirs.push(dir);
+  return dir;
+};
+afterEach(() => {
+  for (const dir of tmpDirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+describe("buildStub", () => {
+  it("保留整个头部和 UserConfig，在头部末尾追加指向源文件的 @require，正文为空", () => {
+    const file = "/work/my project/demo.user.js";
+    expect(buildStub(SOURCE, file)).toBe(
+      [
+        "// ==UserScript==",
+        "// @name         Demo",
+        "// @namespace    https://example.com/demo",
+        "// @match        https://example.com/*",
+        "// @grant        GM_getValue",
+        "// @require      https://cdn.example.com/lib.js",
+        `// @require      ${pathToFileURL(file).href}`,
+        "// ==/UserScript==",
+        "",
+        "/* ==UserConfig==",
+        "general:",
+        "  token:",
+        "    title: Token",
+        " ==/UserConfig== */",
+        "",
+      ].join("\n")
+    );
+  });
+
+  it("没有脚本头时抛错", () => {
+    expect(() => buildStub("console.log(1);", "/work/a.user.js")).toThrow(/==UserScript==/);
+  });
+});
+
+describe("stub.mjs 命令行", () => {
+  it("相对路径按当前目录解析为绝对 file:// 地址，输出到 stdout", () => {
+    const dir = tmpDir();
+    writeFileSync(path.join(dir, "demo.user.js"), SOURCE);
+    const res = spawnSync(process.execPath, [STUB, "demo.user.js"], { cwd: dir, encoding: "utf8" });
+    expect(res.status).toBe(0);
+    // 子进程的 cwd 是解析过符号链接的路径（macOS 的 /var → /private/var），期望值按同样方式计算
+    const expected = pathToFileURL(path.join(realpathSync(dir), "demo.user.js")).href;
+    expect(res.stdout).toContain(`// @require      ${expected}\n`);
+  });
+
+  it("-o 写入文件", () => {
+    const dir = tmpDir();
+    const src = path.join(dir, "demo.user.js");
+    const out = path.join(dir, "demo.stub.user.js");
+    writeFileSync(src, SOURCE);
+    const res = spawnSync(process.execPath, [STUB, src, "-o", out], { encoding: "utf8" });
+    expect(res.status).toBe(0);
+    expect(readFileSync(out, "utf8")).toBe(buildStub(SOURCE, src));
+  });
+
+  it("源文件没有脚本头时退出码为 2", () => {
+    const dir = tmpDir();
+    const src = path.join(dir, "plain.js");
+    writeFileSync(src, "console.log(1);");
+    const res = spawnSync(process.execPath, [STUB, src], { encoding: "utf8" });
+    expect(res.status).toBe(2);
+  });
+});
diff --git a/vitest.config.ts b/vitest.config.ts
index ecc4b8196..69fb1f767 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -34,7 +34,7 @@ const ISOLATED = [
 ];
 
 const BASE_EXCLUDE = ["**/node_modules/**", "**/.claude/**", "**/.dev-kit/**", "e2e/**"];
-const SCRIPT_TESTS = ["scripts/**/*.test.js", "scripts/**/*.test.mjs"];
+const SCRIPT_TESTS = ["scripts/**/*.test.js", "scripts/**/*.test.mjs", "skills/**/*.test.mjs"];
 
 // 页面层（React 渲染，含 .ts 的 renderHook 测试）用例的真实 solo 成本在覆盖率下可达 100–200ms，
 // 乘上 worker 并行负载后 340ms 预算必然偶发超时（本地满载观测峰值 ~630ms）；

From ad709853d970e83f1fe3249952eb5712786a4dec Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=8E=8B=E4=B8=80=E4=B9=8B?= <yz@ggnb.top>
Date: Thu, 5 Nov 2026 09:57:45 +0800
Subject: [PATCH 5/7] =?UTF-8?q?=F0=9F=93=9D=20scriptcat-userscript=20Skill?=
 =?UTF-8?q?=EF=BC=9A=E5=90=8E=E5=8F=B0/=E5=AE=9A=E6=97=B6=E8=84=9A?=
 =?UTF-8?q?=E6=9C=AC=E4=BC=98=E5=85=88=E7=94=A8=20sctl=20run=20/=20sctl=20?=
 =?UTF-8?q?logs=20=E9=AA=8C=E8=AF=81=EF=BC=8C=E6=97=A7=E7=89=88=E6=9C=AC?=
 =?UTF-8?q?=E9=80=80=E5=9B=9E=E9=97=B4=E6=8E=A5=E5=8A=9E=E6=B3=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- dev-loop.md：新增 sctl run / sctl logs 用法与注意事项（只限后台/定时脚本、exit 0 看状态、不经审批但有真实副作用、
  手动运行不排重试、debug 级 GM_log 不入库、与编辑器运行或 cron 交叠可能误认），旧 sctl / 旧脚本猫的识别与回退
- background.md：删去无代码依据的「编辑器运行不同步值、菜单不触发」，改为与 sctl run 同一通路
- SKILL.md、api.md：GM_log 的 debug 级别在正式版不入库
- README 已知限制：依赖 scriptscat/sctl#17 与 scriptscat/scriptcat#1825 的版本
---
 skills/scriptcat-userscript/README.md         | 10 +++--
 skills/scriptcat-userscript/SKILL.md          |  7 ++--
 skills/scriptcat-userscript/references/api.md |  2 +-
 .../references/background.md                  | 10 +++--
 .../references/dev-loop.md                    | 38 +++++++++++++++++--
 5 files changed, 52 insertions(+), 15 deletions(-)

diff --git a/skills/scriptcat-userscript/README.md b/skills/scriptcat-userscript/README.md
index 5753f4b98..4a3276875 100644
--- a/skills/scriptcat-userscript/README.md
+++ b/skills/scriptcat-userscript/README.md
@@ -13,7 +13,7 @@
 | `references/background.md` | 后台/定时脚本：Promise 生命周期、`CATRetryError` 重试、cron 与 `once` 扩展、日志 |
 | `references/userconfig.md` | `==UserConfig==` 用户配置格式 |
 | `references/patterns.md` | 常用写法：等待元素、SPA 路由切换、带记忆的菜单开关、跨域请求、样式、多语言、带重试的后台运行 |
-| `references/dev-loop.md` | 用 sctl 侦察页面 → 安装 → 看控制台 → 重装或 `sctl edit` 迭代；本地文件热重载（`@require file:///` 壳脚本）；用探针脚本观察后台脚本 |
+| `references/dev-loop.md` | 用 sctl 侦察页面 → 安装 → 看控制台 → 重装或 `sctl edit` 迭代；本地文件热重载（`@require file:///` 壳脚本）；用 `sctl run` / `sctl logs` 运行后台脚本并读日志，旧版本退回探针脚本 |
 | `scripts/check.mjs` | 零依赖静态检查：未声明 grant、`@grant none` 误用、缺 `@match`、cron 写法、`@connect` 缺失等；有 error 时退出码 1 |
 | `scripts/stub.mjs` | 生成本地热重载用的 `@require file:///` 壳脚本 |
 
@@ -30,6 +30,8 @@ ln -s "$(pwd)/skills/scriptcat-userscript" ~/.codex/skills/scriptcat-userscript
 
 ## 已知限制
 
-- sctl 没有触发后台/定时脚本运行、读取脚本猫运行日志的命令。`references/dev-loop.md` 给出了间接办法（重装即重跑
-  `@background`、测试时临时改成每分钟的 cron、用共享 `@storageName` 的探针页面脚本把进度打到控制台），完整的运行状态与
-  `GM_log` 输出仍需用户在脚本列表查看。
+- `sctl run` / `sctl logs` 需要 sctl 与脚本猫都升级到包含 scriptscat/sctl#17 与 scriptscat/scriptcat#1825 的版本。旧 sctl 不认识
+  `run`，旧脚本猫返回 `METHOD_NOT_FOUND` 并提示升级；Skill 遇到这两种情况会退回 `references/dev-loop.md` 里的间接办法（重装即重跑
+  `@background`、测试时临时改成每分钟的 cron、用共享 `@storageName` 的探针页面脚本把进度打到控制台）。
+- 脚本猫正式版不把 `debug` 级别的 `GM_log` 写进日志，脚本列表与 `sctl logs` 都看不到。
+- 运行状态事件不带运行 id：`sctl run` 等待期间如果用户在编辑器里点运行或 cron 触发，返回的状态可能属于那一次运行。
diff --git a/skills/scriptcat-userscript/SKILL.md b/skills/scriptcat-userscript/SKILL.md
index 4d6a81b81..871959452 100644
--- a/skills/scriptcat-userscript/SKILL.md
+++ b/skills/scriptcat-userscript/SKILL.md
@@ -134,8 +134,9 @@ is legal there.
   failures with `CATRetryError`: `* * once * *` = at most once a day, `* once * * *` = at most once an hour,
   `* once(9-17) * * *` = once in each hour from 9 to 17. Full cron and `once` rules:
   [references/background.md](references/background.md).
-- Log with `GM_log(message, "debug" | "info" | "warn" | "error")`: it lands in ScriptCat's run log, which is the
-  only place a background script's output shows up.
+- Log with `GM_log(message, "debug" | "info" | "warn" | "error")`: it lands in ScriptCat's run log, the only place
+  a background script's output shows up (the script list, or `sctl logs`). Release builds do not store `debug`, so
+  log anything someone must read at `info` or above.
 
 **User configuration**
 
@@ -171,7 +172,7 @@ It is a static check — it cannot tell whether the script does what the user as
 - **sctl is available** (`sctl status` shows ScriptCat connected): install it into the user's ScriptCat and
   verify it in their browser, following [references/dev-loop.md](references/dev-loop.md). It also covers
   scouting the target page before you write code, iterating on a local file without an approval per change, and
-  observing background scripts. That loop runs inside the user's real browser, so the sctl skill's rules apply
+  running background and scheduled scripts and reading their logs (`sctl run` / `sctl logs`). That loop runs inside the user's real browser, so the sctl skill's rules apply
   too — read it first if it is installed.
 - **No sctl:** save the code as `<name>.user.js` and tell the user to install it — drag the file onto the
   ScriptCat dashboard, or create a new script in ScriptCat and paste the code. Say which page to open (page
diff --git a/skills/scriptcat-userscript/references/api.md b/skills/scriptcat-userscript/references/api.md
index 93a737376..4f0622094 100644
--- a/skills/scriptcat-userscript/references/api.md
+++ b/skills/scriptcat-userscript/references/api.md
@@ -57,7 +57,7 @@ code and `await` them. `GM_info` needs no grant; `unsafeWindow` needs none eithe
 
 | Grant | Notes |
 |---|---|
-| `GM_log(message, level?)` | Level `debug`/`info`/`warn`/`error`. Goes to ScriptCat's run log — the place to look for background-script output |
+| `GM_log(message, level?)` | Level `debug`/`info`/`warn`/`error`. Goes to ScriptCat's run log — the place to look for background-script output. Release builds do not store `debug` |
 | `CAT_scriptLoaded()` | Promise that resolves once an `@early-start` script is fully loaded; read `GM_info.userLanguage` after it |
 
 `GM_info` carries the script metadata (`GM_info.script`), `scriptMetaStr`, `scriptHandler` (`"ScriptCat"`),
diff --git a/skills/scriptcat-userscript/references/background.md b/skills/scriptcat-userscript/references/background.md
index 40feb2f8f..8bec295c9 100644
--- a/skills/scriptcat-userscript/references/background.md
+++ b/skills/scriptcat-userscript/references/background.md
@@ -73,10 +73,12 @@ To test an expression in an external cron tool, replace `once` with `*` and `onc
 
 ## Debugging and logs
 
-- `GM_log(msg, level)` writes to ScriptCat's run log: hover/click the run-status column in the script list. This
-  is where background output goes; plain `console.log` is not shown there.
-- The script editor can run a background script directly, but values do not sync and menu commands do not fire
-  in that mode.
+- `GM_log(msg, level)` writes to ScriptCat's run log: hover/click the run-status column in the script list, or
+  `sctl logs <uuid>`. This is where background output goes; plain `console.log` is not shown there. Release
+  builds do not store `debug`-level entries.
+- The script editor's Run button runs a background or scheduled script once, through the same path as
+  `sctl run` (see [dev-loop.md](dev-loop.md#verifying-background-and-scheduled-scripts)). A manual run does not
+  schedule `CATRetryError` retries.
 - The script list also shows the next run time of a scheduled script.
 
 ## What is not available
diff --git a/skills/scriptcat-userscript/references/dev-loop.md b/skills/scriptcat-userscript/references/dev-loop.md
index 617add669..35dd2cfd0 100644
--- a/skills/scriptcat-userscript/references/dev-loop.md
+++ b/skills/scriptcat-userscript/references/dev-loop.md
@@ -151,9 +151,41 @@ not need it.
 
 ## Verifying background and scheduled scripts
 
-They run in ScriptCat's background sandbox, which is not a web page: sctl cannot attach to it, cannot open
-ScriptCat's own pages (extension pages are not automatable), and has no command to start a run or read the run
-log. What you can do:
+They run in ScriptCat's background sandbox, which is not a web page: sctl cannot attach to it and cannot open
+ScriptCat's own pages (extension pages are not automatable). Newer sctl and ScriptCat versions can run such a
+script and read its log directly; try that first.
+
+### Run it and read its log
+
+```sh
+sctl run <uuid>                    # run once now, wait up to 60s, print the outcome and this run's log
+sctl run <uuid> --timeout 2m       # wait longer (at most 4m)
+sctl run <uuid> --no-wait          # start it and return at once
+sctl logs <uuid>                   # this script's log, oldest first, last hour
+sctl logs <uuid> --since 10m --level warn --text "[my-script]" --limit 50
+```
+
+- `run` works for `@background` and `@crontab` scripts only (a page script fails with `INVALID_REQUEST`), whether
+  or not the script is enabled. It is what the editor's Run button does: the same body, the same grants.
+- The status line reads `complete` (resolved), `error: <message>` (rejected or threw) or `still running` (not
+  settled when the wait ended — normal for a long-lived `@background` script). The command exits 0 in all three
+  cases; read the status, not the exit code. `-o json` gives `status`, `error`, `startedAt`, `endedAt` and `logs`.
+- Neither command opens an approval page, but `run` really runs the script: its requests, notifications and value
+  writes happen. Run scripts you are writing; ask before running one of the user's existing scripts.
+- A manual run does not schedule a `CATRetryError` retry; the error shows up as `error` instead. Test retry
+  timing through the real schedule.
+- `run` prints the log lines written during the run; ScriptCat's own "exec script complete" line can land just
+  after the command returns, so use `sctl logs` when you need the complete record.
+- `GM_log` at level `debug` is not stored in release builds of ScriptCat, so `sctl logs` never shows it. Log what
+  you need to read at `info` or above.
+- If the user runs the script from the editor, or its cron fires, while your `run` is waiting, the reported status
+  may belong to that other run. Keep test runs away from the script's schedule.
+
+The commands are missing on older versions. `sctl run` is an unknown command on an older sctl. On an older
+ScriptCat it fails with `METHOD_NOT_FOUND` (exit 3) and a hint to upgrade ScriptCat. In either case, tell the user
+an upgrade adds these commands, and use the indirect route below.
+
+### Without `sctl run`
 
 **Make a run happen.**
 

From 4ead49a59bc778fc806a384fecf7d8a5b2b64b84 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=8E=8B=E4=B8=80=E4=B9=8B?= <yz@ggnb.top>
Date: Thu, 5 Nov 2026 10:54:23 +0800
Subject: [PATCH 6/7] =?UTF-8?q?=F0=9F=90=9B=20scriptcat-userscript=20check?=
 =?UTF-8?q?.mjs=EF=BC=9A=E4=BF=AE=E5=A4=8D=E5=AF=B9=E8=B1=A1=E9=94=AE?=
 =?UTF-8?q?=E8=AF=AF=E6=8A=A5=E3=80=81=E5=85=B3=E9=94=AE=E5=AD=97=E5=90=8E?=
 =?UTF-8?q?=E6=AD=A3=E5=88=99=E6=BC=8F=E6=8A=A5=E4=B8=8E=20@connect=20?=
 =?UTF-8?q?=E5=90=8C=E5=9F=9F=E8=AF=AF=E5=88=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 对象字面量的键（`{ GM_getValue: 1 }`）不再算 API 调用；三元表达式里的仍算
- return/typeof/case/throw/in/of/void/delete/new 等关键字后的 `/` 按正则开头处理，正则里的引号不再吞掉同一行后面的调用
- @match 带通配子域或有多个域名时，请求其中一个域名不再视为同域（运行时只放行与页面完全相同的域名，见 getConnectMatched）
- connect-missing 文案区分：脚本已有 @connect 时 GM_xmlhttpRequest 会被拒绝，没有任何 @connect 时询问用户；仍为 warn，因为检查只看 URL 字面量，无法确定它是否真被请求
- 某个文件读不了时继续检查其余文件，最后以退出码 2 结束
- check/stub 命令行用例真实 spawn node，按 scripts/check-i18n.test.mjs 的做法单独设超时，避免满载时超出 340ms 单测预算
---
 skills/scriptcat-userscript/scripts/check.mjs | 78 +++++++++++++++----
 .../scripts/check.test.mjs                    | 59 +++++++++++++-
 .../scripts/stub.test.mjs                     |  4 +-
 3 files changed, 122 insertions(+), 19 deletions(-)

diff --git a/skills/scriptcat-userscript/scripts/check.mjs b/skills/scriptcat-userscript/scripts/check.mjs
index c14aa01f3..d0fefec29 100644
--- a/skills/scriptcat-userscript/scripts/check.mjs
+++ b/skills/scriptcat-userscript/scripts/check.mjs
@@ -5,7 +5,8 @@
 //   node check.mjs my-script.user.js [more.user.js …]
 //
 // Prints one line per finding — `error|warn <rule> <file>:<line> <message>` — and exits 1 when any error was found,
-// 0 otherwise, 2 on a usage or read error. The rules mirror ScriptCat's runtime; the sources are named per rule.
+// 0 otherwise, 2 on a usage error or when a file could not be read (the other files are still checked). The rules
+// mirror ScriptCat's runtime; the sources are named per rule.
 import { readFileSync, realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import process from "node:process";
@@ -140,6 +141,24 @@ const RUN_AT = new Set(["document-start", "document-body", "document-end", "docu
 const TAB_APIS = new Set(["GM_getTab", "GM_saveTab", "GM_getTabs", "GM.getTab", "GM.saveTab", "GM.getTabs"]);
 const REQUEST_APIS = ["GM_xmlhttpRequest", "GM.xmlHttpRequest", "GM_download", "GM.download"];
 
+// After these words a `/` starts a regular expression; after any other identifier it is a division.
+const REGEX_AFTER = new Set([
+  "return",
+  "typeof",
+  "case",
+  "throw",
+  "in",
+  "of",
+  "void",
+  "delete",
+  "new",
+  "instanceof",
+  "do",
+  "else",
+  "yield",
+  "await",
+]);
+
 const lineAt = (text, index) => {
   let line = 1;
   for (let i = 0; i < index; i++) if (text.charCodeAt(i) === 10) line++;
@@ -159,6 +178,14 @@ function lex(code) {
   let lastSignificant = "";
   const templateDepth = []; // brace depth at which each open `${` returns to its template
   let braceDepth = 0;
+  // The identifier right before `index` (comments already blanked), unless it is a property name such as `x.return`.
+  const wordBefore = (index) => {
+    let j = index - 1;
+    while (j >= 0 && /\s/.test(noComments[j])) j--;
+    const end = j + 1;
+    while (j >= 0 && /[\w$]/.test(noComments[j])) j--;
+    return noComments[j] === "." ? "" : noComments.slice(j + 1, end).join("");
+  };
   const readQuoted = (quote, start) => {
     let j = start + 1;
     while (j < code.length && code[j] !== quote && code[j] !== "\n") j += code[j] === "\\" ? 2 : 1;
@@ -208,7 +235,12 @@ function lex(code) {
     } else if (c === "}" && templateDepth.length && templateDepth[templateDepth.length - 1] === braceDepth) {
       templateDepth.pop();
       i = templatePiece(i, i + 1);
-    } else if (c === "/" && (lastSignificant === "" || /[(,=:[!&|?{};+\-*%<>~^]/.test(lastSignificant))) {
+    } else if (
+      c === "/" &&
+      (lastSignificant === "" ||
+        /[(,=:[!&|?{};+\-*%<>~^]/.test(lastSignificant) ||
+        (lastSignificant === "a" && REGEX_AFTER.has(wordBefore(i))))
+    ) {
       let j = i + 1;
       let inClass = false;
       while (j < code.length && code[j] !== "\n") {
@@ -254,19 +286,20 @@ const hostOf = (pattern) => {
   return m ? m[1].toLowerCase() : null;
 };
 
-// Same matching as getConnectMatched (src/app/service/service_worker/gm_api/gm_api.ts): a request to the page's own
-// host needs nothing; otherwise an @connect entry must equal the host or a parent domain of it, be `*`, or be `self`
-// with the host under the page's domain. The page host is approximated from @match/@include.
+// Same matching as getConnectMatched (src/app/service/service_worker/gm_api/gm_api.ts): a request to exactly the
+// page's host needs nothing, `self` also covers subdomains of the page's host, and any other @connect entry must
+// equal the request host or a parent domain of it, or be `*`. The page host comes from @match/@include, so the
+// page-relative rules only hold when every pattern names the same exact host: a wildcard (`*.example.com`) or a
+// second host means the script also runs on pages whose host is a different one.
 function connectCovers(host, connects, pageHosts) {
   const under = (h, d) => `.${h}`.endsWith(`.${d}`);
-  for (const page of pageHosts) {
-    if (page === "*") continue;
-    if (page.startsWith("*.") ? under(host, page.slice(2)) : host === page) return true;
-  }
+  const exactPages = pageHosts.length > 0 && pageHosts.every((p) => !p.includes("*")) ? pageHosts : [];
+  const forEveryPage = (test) => exactPages.length > 0 && exactPages.every(test);
+  if (forEveryPage((p) => p === host)) return true;
   for (const c of connects) {
     if (c === "*") return true;
     if (c === "self") {
-      if (pageHosts.some((p) => p !== "*" && under(host, p.replace(/^\*\./, "")))) return true;
+      if (forEveryPage((p) => under(host, p))) return true;
     } else if (under(host, c)) return true;
   }
   return false;
@@ -351,8 +384,12 @@ export function checkScript(code) {
 
   const used = [];
   const usage = /(?<![\w$.])(GM_[A-Za-z]\w*|GM\.[A-Za-z]\w*|CAT_[A-Za-z]\w*|CAT\.agent\.\w+)/g;
+  // `{ GM_getValue: 1 }` / `{ a, GM_getValue: 1 }` name a property, not the API; `ok ? GM_getValue : x` still uses it.
+  const isPropertyKey = (start, end) =>
+    /[{,]\s*$/.test(bare.slice(Math.max(0, start - 200), start)) && /^\s*:/.test(bare.slice(end, end + 200));
   for (const m of bare.matchAll(usage)) {
     if (m[1] === "GM_info" || m[1] === "GM.info") continue;
+    if (isPropertyKey(m.index, m.index + m[1].length)) continue;
     used.push({ name: m[1], index: m.index });
   }
   for (const m of noComments.matchAll(/(?<![\w$])onurlchange\b|addEventListener\(\s*["'`]urlchange["'`]/g)) {
@@ -415,8 +452,14 @@ export function checkScript(code) {
   }
 
   if (used.some((u) => REQUEST_APIS.includes(u.name))) {
-    const connects = values("connect").map((c) => c.toLowerCase());
-    const pageHosts = isBackground ? [] : [...values("match"), ...values("include")].map(hostOf).filter(Boolean);
+    const connects = values("connect")
+      .filter(Boolean)
+      .map((c) => c.toLowerCase());
+    // GM_xmlhttpRequest refuses an unlisted host once any @connect exists; GM_download (native mode) and a script
+    // without @connect ask the user instead (verifyXhrConnect in gm_api.ts).
+    const refused =
+      connects.length > 0 && used.some((u) => u.name === "GM_xmlhttpRequest" || u.name === "GM.xmlHttpRequest");
+    const pageHosts = isBackground ? [] : [...values("match"), ...values("include")].map((p) => hostOf(p) ?? "*");
     const seen = new Set();
     for (const s of strings) {
       const m = s.value.match(/^https?:\/\/([^/:?#]+)/i);
@@ -428,7 +471,10 @@ export function checkScript(code) {
         "warn",
         "connect-missing",
         bodyLine(s.index),
-        `requests to ${host} prompt the user; add "// @connect ${host}" if the script requests it`
+        refused
+          ? `GM_xmlhttpRequest to ${host} is refused: it is not in the @connect list (unless the user allowed it ` +
+              `before); add "// @connect ${host}" if the script requests it`
+          : `a request to ${host} asks the user first; add "// @connect ${host}" if the script requests it`
       );
     }
   }
@@ -460,20 +506,22 @@ function main(files) {
     return 2;
   }
   let status = 0;
+  let unreadable = false;
   for (const file of files) {
     let code;
     try {
       code = readFileSync(file, "utf8");
     } catch (e) {
       console.error(`cannot read ${file}: ${e.message}`);
-      return 2;
+      unreadable = true;
+      continue;
     }
     const findings = checkScript(code);
     for (const f of findings) console.log(`${f.level} ${f.rule} ${file}:${f.line} ${f.message}`);
     if (!findings.length) console.log(`ok ${file}`);
     if (findings.some((f) => f.level === "error")) status = 1;
   }
-  return status;
+  return unreadable ? 2 : status;
 }
 
 // realpath: the skill is usually installed through a symlink, while import.meta.url is the resolved path
diff --git a/skills/scriptcat-userscript/scripts/check.test.mjs b/skills/scriptcat-userscript/scripts/check.test.mjs
index 3d109e8da..4cdcd0d4a 100644
--- a/skills/scriptcat-userscript/scripts/check.test.mjs
+++ b/skills/scriptcat-userscript/scripts/check.test.mjs
@@ -16,6 +16,7 @@ function script(headerLines, body = "") {
 
 const PAGE = ["@name Demo", "@namespace https://example.com/demo", "@match https://example.com/*"];
 const BACKGROUND = ["@name Demo", "@namespace https://example.com/demo", "@background"];
+const BASE_NAME = ["@name Demo", "@namespace https://example.com/demo"];
 
 // 只比较规则、级别和行号；提示文案不是契约
 const summary = (code) => checkScript(code).map(({ level, rule, line }) => ({ level, rule, line }));
@@ -74,6 +75,25 @@ describe("checkScript", () => {
     expect(summary(code)).toEqual([]);
   });
 
+  it("对象字面量的键和成员访问里的 API 名不算调用，三元表达式里的仍算", () => {
+    const code = script(
+      PAGE,
+      "const o = { GM_getValue: 1, b: 2 };\nconst p = { a: 1, GM_setValue : 2 };\nx.GM_log(o, p);"
+    );
+    expect(summary(code)).toEqual([]);
+    const ternary = script(PAGE, "const f = ok ? GM_getValue : null;");
+    expect(summary(ternary)).toEqual([{ level: "error", rule: "grant-missing", line: 7 }]);
+  });
+
+  it("关键字后的 / 是正则开头：正则里的引号不会吞掉同一行后面的调用", () => {
+    for (const keyword of ["return", "typeof", "case", "throw", "in", "of", "void", "delete", "new"]) {
+      const code = script(PAGE, `${keyword} /"/.test(s) ? GM_getValue("a") : 0;`);
+      expect(summary(code), keyword).toEqual([{ level: "error", rule: "grant-missing", line: 7 }]);
+    }
+    const division = script(PAGE, 'const n = total / 2; const s = "GM_getValue";');
+    expect(summary(division)).toEqual([]);
+  });
+
   it("脚本猫未实现的 GM_* 名称只警告（可能来自 @require 的库）", () => {
     const code = script(PAGE, "GM_config.open();");
     expect(summary(code)).toEqual([{ level: "warn", rule: "api-unsupported", line: 7 }]);
@@ -173,18 +193,44 @@ describe("checkScript", () => {
     expect(summary(script([...base, "@connect self"], req("https://sub.example.com/")))).toEqual([]);
   });
 
+  it("@match 带通配子域或有多个域名时，请求其中一个域名不算同域：页面可能在别的子域上", () => {
+    const req = (url) => `GM_xmlhttpRequest({ url: "${url}" });`;
+    const wildcard = [...BASE_NAME, "@match *://*.example.com/*", "@grant GM_xmlhttpRequest"];
+    expect(summary(script(wildcard, req("https://example.com/api")))).toEqual([
+      { level: "warn", rule: "connect-missing", line: 8 },
+    ]);
+    expect(summary(script([...wildcard, "@connect self"], req("https://example.com/api")))).toEqual([
+      { level: "warn", rule: "connect-missing", line: 9 },
+    ]);
+    const twoHosts = [...BASE_NAME, "@match https://a.com/*", "@match https://b.com/*", "@grant GM_xmlhttpRequest"];
+    expect(summary(script(twoHosts, req("https://a.com/api")))).toEqual([
+      { level: "warn", rule: "connect-missing", line: 9 },
+    ]);
+  });
+
+  it("有其他 @connect 时提示请求会被拒绝，没有任何 @connect 时提示会询问用户", () => {
+    const req = 'GM_xmlhttpRequest({ url: "https://other.net/" });';
+    const messageOf = (header) => checkScript(script([...PAGE, "@grant GM_xmlhttpRequest", ...header], req))[0].message;
+    expect(messageOf(["@connect example.org"])).toMatch(/refused/);
+    expect(messageOf([])).toMatch(/asks the user/);
+  });
+
   it("不发请求的脚本不检查 URL 字面量", () => {
     expect(summary(script(PAGE, 'const link = "https://other.net/";'))).toEqual([]);
   });
 });
 
-describe("check.mjs 命令行", () => {
-  const run = (code) => {
+// 这些用例真实 spawn node 子进程（满载时单次可达 1s），不适用 vitest.config.ts 给单元测试定的 340ms 预算；
+// 与 scripts/check-i18n.test.mjs 的命令行用例同一做法
+const CLI_TIMEOUT = 15_000;
+
+describe("check.mjs 命令行", { timeout: CLI_TIMEOUT }, () => {
+  const run = (code, extraBefore = []) => {
     const dir = mkdtempSync(path.join(os.tmpdir(), "sc-check-"));
     const file = path.join(dir, "a.user.js");
     writeFileSync(file, code);
     try {
-      return spawnSync(process.execPath, [CHECK, file], { encoding: "utf8" });
+      return spawnSync(process.execPath, [CHECK, ...extraBefore, file], { encoding: "utf8" });
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }
@@ -202,6 +248,13 @@ describe("check.mjs 命令行", () => {
     expect(res.stdout).toMatch(/^warn grant-unknown .*a\.user\.js:5 /m);
   });
 
+  it("读不了的文件报错后继续检查其余文件，最终退出码为 2", () => {
+    const res = run(script(PAGE, 'GM_setValue("a", 1);'), [path.join(os.tmpdir(), "sc-check-missing", "none.user.js")]);
+    expect(res.status).toBe(2);
+    expect(res.stderr).toMatch(/cannot read .*none\.user\.js/);
+    expect(res.stdout).toMatch(/^error grant-missing .*a\.user\.js:7 /m);
+  });
+
   it("没有参数时退出码为 2", () => {
     const res = spawnSync(process.execPath, [CHECK], { encoding: "utf8" });
     expect(res.status).toBe(2);
diff --git a/skills/scriptcat-userscript/scripts/stub.test.mjs b/skills/scriptcat-userscript/scripts/stub.test.mjs
index 932f5a487..c0c1bce6b 100644
--- a/skills/scriptcat-userscript/scripts/stub.test.mjs
+++ b/skills/scriptcat-userscript/scripts/stub.test.mjs
@@ -67,7 +67,9 @@ describe("buildStub", () => {
   });
 });
 
-describe("stub.mjs 命令行", () => {
+// 这些用例真实 spawn node 子进程（满载时单次可达 1s），不适用 vitest.config.ts 给单元测试定的 340ms 预算；
+// 与 scripts/check-i18n.test.mjs 的命令行用例同一做法
+describe("stub.mjs 命令行", { timeout: 15_000 }, () => {
   it("相对路径按当前目录解析为绝对 file:// 地址，输出到 stdout", () => {
     const dir = tmpDir();
     writeFileSync(path.join(dir, "demo.user.js"), SOURCE);

From bef426d7dcd5467e955c7227c08d755924f7b28a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=8E=8B=E4=B8=80=E4=B9=8B?= <yz@ggnb.top>
Date: Thu, 5 Nov 2026 10:54:35 +0800
Subject: [PATCH 7/7] =?UTF-8?q?=F0=9F=93=9D=20scriptcat-userscript=20Skill?=
 =?UTF-8?q?=EF=BC=9A=E6=8C=89=E4=BB=A3=E7=A0=81=E8=AE=A2=E6=AD=A3=E8=BF=90?=
 =?UTF-8?q?=E8=A1=8C=E7=BB=93=E6=9E=9C=E6=9F=A5=E7=9C=8B=E4=BD=8D=E7=BD=AE?=
 =?UTF-8?q?=E3=80=81@connect=20=E6=8B=92=E7=BB=9D=E8=A7=84=E5=88=99?=
 =?UTF-8?q?=E4=B8=8E=E8=8B=A5=E5=B9=B2=E6=98=93=E9=94=99=E7=82=B9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 脚本列表只显示运行状态（运行中/错误/已停止）与定时脚本下次运行时间，GM_log 与错误信息改指向日志页（按 name/uuid 过滤）或 sctl logs
- @connect：脚本已有 @connect 时未列入的域名被 GM_xmlhttpRequest 直接拒绝（之前允许过的除外），只有完全没有 @connect 才询问；native GM_download 总是询问；仅与页面完全相同的域名免声明
- CATRetryError 在 @grant none 下不存在；没有任何 @grant 行的脚本同样运行在沙盒里
- 同 @name/@namespace 不能在页面脚本与后台/定时脚本之间切换（类型不符被拒），临时页面脚本需另起名字
- GM_addElement 注入 <script> 在 Firefox 仍受页面 CSP 约束；urlchange 依赖 Navigation API，onurlchange === null 只说明授权生效
- dev-loop：补 get/run/logs 的 --scriptcat 行为、sctl run 的实际状态行与 JSON 字段（含 truncated）、@run-in 不符返回 INVALID_REQUEST；壳脚本示例的说明移到注释行；后台壳脚本可用 sctl run / 编辑器运行免审批重读本地 @require
---
 skills/scriptcat-userscript/README.md         |  2 +-
 skills/scriptcat-userscript/SKILL.md          | 37 ++++++++++------
 skills/scriptcat-userscript/references/api.md | 13 +++---
 .../references/background.md                  | 14 +++---
 .../references/dev-loop.md                    | 43 ++++++++++++-------
 .../references/patterns.md                    | 16 +++----
 6 files changed, 77 insertions(+), 48 deletions(-)

diff --git a/skills/scriptcat-userscript/README.md b/skills/scriptcat-userscript/README.md
index 4a3276875..49bb66d6f 100644
--- a/skills/scriptcat-userscript/README.md
+++ b/skills/scriptcat-userscript/README.md
@@ -33,5 +33,5 @@ ln -s "$(pwd)/skills/scriptcat-userscript" ~/.codex/skills/scriptcat-userscript
 - `sctl run` / `sctl logs` 需要 sctl 与脚本猫都升级到包含 scriptscat/sctl#17 与 scriptscat/scriptcat#1825 的版本。旧 sctl 不认识
   `run`，旧脚本猫返回 `METHOD_NOT_FOUND` 并提示升级；Skill 遇到这两种情况会退回 `references/dev-loop.md` 里的间接办法（重装即重跑
   `@background`、测试时临时改成每分钟的 cron、用共享 `@storageName` 的探针页面脚本把进度打到控制台）。
-- 脚本猫正式版不把 `debug` 级别的 `GM_log` 写进日志，脚本列表与 `sctl logs` 都看不到。
+- 脚本猫正式版不把 `debug` 级别的 `GM_log` 写进日志，日志页与 `sctl logs` 都看不到。
 - 运行状态事件不带运行 id：`sctl run` 等待期间如果用户在编辑器里点运行或 cron 触发，返回的状态可能属于那一次运行。
diff --git a/skills/scriptcat-userscript/SKILL.md b/skills/scriptcat-userscript/SKILL.md
index 871959452..40b633f98 100644
--- a/skills/scriptcat-userscript/SKILL.md
+++ b/skills/scriptcat-userscript/SKILL.md
@@ -75,6 +75,9 @@ is legal there.
 
 - `@name` + `@namespace` identify a script. Keep both stable once the user has installed it; changing either
   makes a different script. Bump `@version` on every change you hand back.
+- A page script cannot become a background or scheduled script (or the reverse) under the same `@name` +
+  `@namespace`: ScriptCat rejects that install with a script type mismatch. Give a temporary script of the other
+  type its own `@name`.
 
 **Permissions**
 
@@ -82,14 +85,19 @@ is legal there.
   runtime. Granting `GM_foo` also exposes `GM.foo` and vice versa — only when the names match exactly:
   `GM.xmlHttpRequest` needs its own `@grant GM.xmlHttpRequest` (`@grant GM_xmlhttpRequest` does not expose it).
 - `GM_info` needs no grant. `unsafeWindow` needs no grant either, but only exists in the sandbox (any grant
-  other than `none`); `@grant unsafeWindow` is harmless.
+  other than `none`, or no `@grant` line at all); `@grant unsafeWindow` is harmless.
 - `@grant none` runs the script without the sandbox: `window` is the page's own window, and the only API is
   `GM_info` / `GM.info` — no other GM API and **no `unsafeWindow`** (referencing it throws a `ReferenceError`).
   Use it only for scripts that need nothing but the page.
-- With any other grant the script is sandboxed: its `window` is not the page's. Reach page globals (a site's
-  own JS objects, variables it defines) through `unsafeWindow`.
-- `GM_xmlhttpRequest`, `GM_cookie` and `GM_download` (native mode) ask the user before touching a host that is
-  not declared with `@connect <host>`. Declare every host you request; `GM_cookie` requires it.
+- With any other grant — and also with no `@grant` line at all, unlike Tampermonkey — the script is sandboxed:
+  its `window` is not the page's. Reach page globals (a site's own JS objects, variables it defines) through
+  `unsafeWindow`.
+- Declare every host you request with `@connect <host>` (it also covers the host's subdomains; `@connect self`
+  covers subdomains of the page's host; requests to exactly the page's host need nothing). For a host that is not
+  covered, `GM_xmlhttpRequest` is **refused** ("This domain is not a part of the @connect list") as soon as the
+  script has any `@connect` line, unless the user allowed that host before; only a script with no `@connect` at
+  all asks the user instead. `GM_download` in native mode always asks, and `GM_cookie` throws for a host outside
+  `@connect`.
 
 **Page timing and SPAs**
 
@@ -106,7 +114,8 @@ is legal there.
 - `@noframes` keeps the script out of iframes; without it, a `*://*/*` match also runs inside every iframe.
 - `@inject-into content` runs in the content-script world: unaffected by the page's CSP, but `unsafeWindow`
   is then not the page's `window`. The default is `page`.
-- `GM_addStyle` and `GM_addElement` bypass CSP; prefer them over creating `<style>`/`<script>` by hand.
+- `GM_addStyle` and `GM_addElement` bypass the page's CSP; prefer them over creating `<style>`/`<script>` by
+  hand. Exception: on Firefox a `<script>` injected with `GM_addElement` is still subject to the page's CSP.
 
 **Storage**
 
@@ -123,8 +132,10 @@ is legal there.
   treats the run as finished and later GM calls from that run are not guaranteed to work. ScriptCat wraps the
   body in an `async` function, so a body that returns nothing is marked complete as soon as its synchronous part
   (and any top-level `await`) finishes — pending callbacks and timers do not keep the run open.
-- `resolve(value)` is logged as success, `reject(err)` as an error with the error shown in the script list.
-- To retry, `reject(new CATRetryError("reason", seconds))` (or a `Date`). The retry queue is checked every 5
+- `resolve(value)` is logged as success, `reject(err)` as an error; the script list then shows the run status
+  as error, and the message is in the log.
+- To retry, `reject(new CATRetryError("reason", seconds))` (or a `Date`). `CATRetryError` is undefined under
+  `@grant none`; it exists with any other grant or with no `@grant` line. The retry queue is checked every 5
   seconds, so a retry fires up to 5 seconds late; keep run time plus retry delay shorter than the cron interval
   so runs do not overlap.
 - Write exactly one `@crontab` line. Every line is scheduled at runtime, but installation validates and the script
@@ -134,9 +145,10 @@ is legal there.
   failures with `CATRetryError`: `* * once * *` = at most once a day, `* once * * *` = at most once an hour,
   `* once(9-17) * * *` = once in each hour from 9 to 17. Full cron and `once` rules:
   [references/background.md](references/background.md).
-- Log with `GM_log(message, "debug" | "info" | "warn" | "error")`: it lands in ScriptCat's run log, the only place
-  a background script's output shows up (the script list, or `sctl logs`). Release builds do not store `debug`, so
-  log anything someone must read at `info` or above.
+- Log with `GM_log(message, "debug" | "info" | "warn" | "error")`: it lands in ScriptCat's log, the only place
+  a background script's output shows up — ScriptCat's Logs page (filter by the script's `name` or `uuid`), or
+  `sctl logs`. The script list shows only the run status (running / error / stopped) and a scheduled script's
+  next run time. Release builds do not store `debug`, so log anything someone must read at `info` or above.
 
 **User configuration**
 
@@ -176,7 +188,8 @@ It is a static check — it cannot tell whether the script does what the user as
   too — read it first if it is installed.
 - **No sctl:** save the code as `<name>.user.js` and tell the user to install it — drag the file onto the
   ScriptCat dashboard, or create a new script in ScriptCat and paste the code. Say which page to open (page
-  script) or where to look (background: the script list's run status and its log).
+  script) or where to look (background: the run status in the script list, and the script's output on
+  ScriptCat's Logs page).
 
 Whichever path you take, report what you actually observed: "installed and the button appears on
 example.com" is a result; "should work" is not.
diff --git a/skills/scriptcat-userscript/references/api.md b/skills/scriptcat-userscript/references/api.md
index 4f0622094..6f3eee9e4 100644
--- a/skills/scriptcat-userscript/references/api.md
+++ b/skills/scriptcat-userscript/references/api.md
@@ -6,7 +6,7 @@ that is not listed here does nothing in ScriptCat.
 
 `@grant GM_foo` also exposes `GM.foo` (and the reverse) when the rest of the name is identical, case included. `GM.*` variants return Promises; prefer them in new
 code and `await` them. `GM_info` needs no grant; `unsafeWindow` needs none either but does not exist under
-`@grant none`.
+`@grant none`. A script with no `@grant` line at all still runs in the sandbox (unlike Tampermonkey).
 
 ## Storage
 
@@ -20,9 +20,9 @@ code and `await` them. `GM_info` needs no grant; `unsafeWindow` needs none eithe
 
 | Grant | Notes |
 |---|---|
-| `GM_xmlhttpRequest` / `GM.xmlHttpRequest` (two separate grants) | Cross-origin, bypasses CSP, can set `user-agent`, `origin`, `referer`, `cookie`, `host`. Hosts not in `@connect` require user approval. `anonymous: true` with `cookie` sends only that cookie. `responseType: "stream"` is basic. `redirect` replaces the old `maxRedirects` |
-| `GM_download` | Returns a handle with `abort()`. **Differs from Tampermonkey:** the default `native` mode honours `@connect` (undeclared hosts prompt the user); `downloadMode: "browser"` does not. A blob URL downloads directly — background scripts can produce files this way |
-| `GM_cookie` (`GM.cookie.list/set/delete`) | Requires `@connect <host>` and user approval. Uses the cookie store of the window the script runs in (normal or incognito). `sameSite` unsupported |
+| `GM_xmlhttpRequest` / `GM.xmlHttpRequest` (two separate grants) | Cross-origin, bypasses CSP, can set `user-agent`, `origin`, `referer`, `cookie`, `host`. A host outside `@connect` (other than exactly the page's own host) is **refused** when the script has any `@connect` line, unless the user allowed that host before; only a script with no `@connect` at all asks the user. `anonymous: true` with `cookie` sends only that cookie. `responseType: "stream"` is basic. `redirect` replaces the old `maxRedirects` |
+| `GM_download` | Returns a handle with `abort()`. **Differs from Tampermonkey:** the default `native` mode checks `@connect`, but an undeclared host always asks the user rather than being refused; `downloadMode: "browser"` does not. A blob URL downloads directly — background scripts can produce files this way |
+| `GM_cookie` (`GM.cookie.list/set/delete`) | Requires `@connect <host>` (otherwise it throws) and user approval. Uses the cookie store of the window the script runs in (normal or incognito). `sameSite` unsupported |
 | `CAT_fetchBlob(url)` | Fetch a blob URL into a `Blob` (pairs with stream responses) |
 | `CAT_createBlobUrl(blob)` | Blob URL whose lifetime ScriptCat manages |
 | `CAT_fetchDocument(url)` | Fetch and parse a URL into a `Document` |
@@ -57,12 +57,13 @@ code and `await` them. `GM_info` needs no grant; `unsafeWindow` needs none eithe
 
 | Grant | Notes |
 |---|---|
-| `GM_log(message, level?)` | Level `debug`/`info`/`warn`/`error`. Goes to ScriptCat's run log — the place to look for background-script output. Release builds do not store `debug` |
+| `GM_log(message, level?)` | Level `debug`/`info`/`warn`/`error`. Goes to ScriptCat's log (the Logs page, or `sctl logs`) — the place to look for background-script output. Release builds do not store `debug` |
 | `CAT_scriptLoaded()` | Promise that resolves once an `@early-start` script is fully loaded; read `GM_info.userLanguage` after it |
 
 `GM_info` carries the script metadata (`GM_info.script`), `scriptMetaStr`, `scriptHandler` (`"ScriptCat"`),
 `version`, and `userLanguage` (ScriptCat's UI language, e.g. `"zh-CN"` — use it to localise the script's own
-text). `CATRetryError` is a global in background scripts (see [background.md](background.md#retry)).
+text). `CATRetryError` is a global in background scripts, except under `@grant none` (see
+[background.md](background.md#retry)).
 
 ## Agent APIs
 
diff --git a/skills/scriptcat-userscript/references/background.md b/skills/scriptcat-userscript/references/background.md
index 8bec295c9..583e16e67 100644
--- a/skills/scriptcat-userscript/references/background.md
+++ b/skills/scriptcat-userscript/references/background.md
@@ -18,7 +18,7 @@ return new Promise((resolve, reject) => {
 ```
 
 - `resolve(value)` → run status *complete*, the value goes to the log.
-- `reject(err)` → run status *error*, the error is shown in the script list and logged.
+- `reject(err)` → run status *error* in the script list; the error message is in the log.
 - Nothing returned → the run is *complete* as soon as the synchronous part of the body (and any top-level
   `await`) finishes; callbacks and timers still pending do not keep it open.
 - Settling early ends the run as far as ScriptCat is concerned; GM calls made afterwards may not take effect.
@@ -34,7 +34,8 @@ reject(new CATRetryError("server busy", 30));          // retry in 30 seconds
 reject(new CATRetryError("try again later", new Date(Date.now() + 3600e3)));
 ```
 
-`CATRetryError` is a global in background scripts; no grant needed. The retry queue is checked every 5
+`CATRetryError` is a global in background scripts and needs no grant of its own, but it is undefined under
+`@grant none` (that mode skips everything ScriptCat injects); any other grant, or no `@grant` line, has it. The retry queue is checked every 5
 seconds, so a retry fires up to 5 seconds after the requested time. Keep run time plus retry delay shorter than the
 cron interval, or runs overlap.
 
@@ -73,13 +74,14 @@ To test an expression in an external cron tool, replace `once` with `*` and `onc
 
 ## Debugging and logs
 
-- `GM_log(msg, level)` writes to ScriptCat's run log: hover/click the run-status column in the script list, or
-  `sctl logs <uuid>`. This is where background output goes; plain `console.log` is not shown there. Release
-  builds do not store `debug`-level entries.
+- `GM_log(msg, level)` writes to ScriptCat's log: open ScriptCat's Logs page and filter by the script's `name` or
+  `uuid`, or run `sctl logs <uuid>`. This is where background output goes; plain `console.log` is not shown there.
+  Release builds do not store `debug`-level entries.
 - The script editor's Run button runs a background or scheduled script once, through the same path as
   `sctl run` (see [dev-loop.md](dev-loop.md#verifying-background-and-scheduled-scripts)). A manual run does not
   schedule `CATRetryError` retries.
-- The script list also shows the next run time of a scheduled script.
+- The script list shows only the run status (running / error / stopped) and, for a scheduled script, the next
+  run time — not the result or the log.
 
 ## What is not available
 
diff --git a/skills/scriptcat-userscript/references/dev-loop.md b/skills/scriptcat-userscript/references/dev-loop.md
index 35dd2cfd0..dca8bcbd5 100644
--- a/skills/scriptcat-userscript/references/dev-loop.md
+++ b/skills/scriptcat-userscript/references/dev-loop.md
@@ -12,9 +12,10 @@ sctl scriptcats -o json # more than one online (ScriptCat in two browsers) → p
 sctl browsers -o json   # at least one sctl Browser "online": true, needed for the page checks below
 ```
 
-With several ScriptCat instances online, `install`, `edit`, `grep`, `enable`, `disable` and `delete` fail with
-`SCRIPTCAT_AMBIGUOUS` (exit 3) until you pass `--scriptcat <name>` or set `SCTL_SCRIPTCAT`. Set it once for the
-session so every command below goes to the same instance.
+With several ScriptCat instances online, `install`, `edit`, `grep`, `enable`, `disable`, `delete` (and `run` /
+`logs` where they exist) fail with `SCRIPTCAT_AMBIGUOUS` (exit 3) until you pass `--scriptcat <name>` or set
+`SCTL_SCRIPTCAT`; `get` does not fail but lists scripts from every online instance, with a `SCRIPTCAT` column. Set
+`SCTL_SCRIPTCAT` once for the session so every command below goes to the same instance.
 
 ScriptCat not connected: the user enables external access in ScriptCat and pairs it with a code from
 `sctl connect`. No browser online: page checks are unavailable; you can still install, and the user verifies by
@@ -68,7 +69,9 @@ Keep the `uuid`; every later command needs it. `sctl get <uuid> -o json` shows t
 that `type` is what you meant (`normal` for page scripts) and that the grants and matches came through.
 
 Installing again with the same `@name` and `@namespace` **updates that script in place**: same `uuid`, stored
-values kept. Changing either one installs a separate script instead, so keep them fixed while iterating.
+values kept. Changing either one installs a separate script instead, so keep them fixed while iterating. The
+update is rejected (script type mismatch) if it turns a page script into a background or scheduled script, or the
+reverse.
 
 ## Applying a change
 
@@ -98,7 +101,8 @@ the file you are editing, and an empty body.
 
 ```js
 // ==UserScript==
-// @name         My script            (same @name/@namespace as the real script)
+// Same @name and @namespace as the real script:
+// @name         My script
 // @namespace    https://example.com/your-namespace
 // @version      0.1.0
 // @match        https://example.com/*
@@ -128,8 +132,11 @@ obvious which version ran.
 - Because the stub keeps the real `@name` and `@namespace`, installing the finished script at the end replaces
   the stub in place (same uuid, values kept). Do that before handing over — the stub depends on a file on this
   machine.
-- A background or scheduled script re-reads its local `@require` only when ScriptCat (re)loads the script, for
-  example on `sctl disable` + `sctl enable`; each of those is an approval, so the stub saves less there.
+- A background or scheduled script re-reads its local `@require` whenever it is run by hand: `sctl run <uuid>`
+  (where your sctl and ScriptCat have it, see below) or the editor's Run button reads the file again for that run,
+  with no approval — so the stub works for these scripts too. Without `sctl run`, the file is re-read only when
+  ScriptCat (re)loads the script, for example on `sctl disable` + `sctl enable`; each of those is an approval, and
+  scheduled runs keep using the code loaded then.
 
 ## Verifying a page script
 
@@ -167,9 +174,13 @@ sctl logs <uuid> --since 10m --level warn --text "[my-script]" --limit 50
 
 - `run` works for `@background` and `@crontab` scripts only (a page script fails with `INVALID_REQUEST`), whether
   or not the script is enabled. It is what the editor's Run button does: the same body, the same grants.
-- The status line reads `complete` (resolved), `error: <message>` (rejected or threw) or `still running` (not
-  settled when the wait ended — normal for a long-lived `@background` script). The command exits 0 in all three
-  cases; read the status, not the exit code. `-o json` gives `status`, `error`, `startedAt`, `endedAt` and `logs`.
+- The status line reads `complete in 1.2s` (resolved), `error in 1.2s: <message>` (rejected or threw) or
+  `still running (started 15:04:05)` (not settled when the wait ended — normal for a long-lived `@background`
+  script). The command exits 0 in all three cases; read the status, not the exit code. `-o json` gives `status`
+  (`complete` / `error` / `running`), `error`, `startedAt`, `endedAt` (absent while running), `logs` and
+  `truncated` (true when log records were left out — narrow them with `sctl logs --since/--level/--text`).
+- A background script whose `@run-in` (normal or incognito) does not match the ScriptCat instance's context
+  fails with `INVALID_REQUEST` and is not run; ScriptCat would not run it there either.
 - Neither command opens an approval page, but `run` really runs the script: its requests, notifications and value
   writes happen. Run scripts you are writing; ask before running one of the user's existing scripts.
 - A manual run does not schedule a `CATRetryError` retry; the error shows up as `error` instead. Test retry
@@ -221,13 +232,15 @@ The background script declares the same `@storageName my-script-store`. Open the
 on it, trigger a run, then `sctl debug console --tab $TAB --text "[probe]"`. Ask the user before deleting the
 probe (and before removing the debug writes from the real script).
 
-**Hand over what you cannot see.** In ScriptCat's script list the run-status column shows running / complete /
-error and the next run time of a scheduled script; clicking it shows the `GM_log` output. Make that output
-useful: `GM_log` at start, at each step and before settling; resolve with a value that summarises the result;
-`reject` with a real reason.
+**Hand over what you cannot see.** ScriptCat's script list shows only the run status (running / error /
+stopped) and the next run time of a scheduled script; the `GM_log` output and the error message are on
+ScriptCat's Logs page (filter by the script's `name` or `uuid`). Make that output useful: `GM_log` at start, at
+each step and before settling; resolve with a value that summarises the result; `reject` with a real reason.
 
 When the logic can be tested on a page, verify that part with a temporary page script first, then move it into
-the background script.
+the background script. Give the temporary page script a different `@name` (for example `my-script page test`):
+installing a page script under the background script's `@name` + `@namespace`, or the reverse, is rejected as a
+script type mismatch.
 
 ## Cleaning up
 
diff --git a/skills/scriptcat-userscript/references/patterns.md b/skills/scriptcat-userscript/references/patterns.md
index ad80162bf..795f3aee9 100644
--- a/skills/scriptcat-userscript/references/patterns.md
+++ b/skills/scriptcat-userscript/references/patterns.md
@@ -43,13 +43,12 @@ function onRoute(url) {
   if (new URL(url).pathname.startsWith("/watch")) enhanceWatchPage();
 }
 onRoute(location.href);
-if (window.onurlchange === null) {
-  window.addEventListener("urlchange", (e) => onRoute(e.url));
-}
+window.addEventListener("urlchange", (e) => onRoute(e.url));
 ```
 
-`window.onurlchange === null` means the feature is available (it relies on the browser's Navigation API). Combine
-with `waitFor`: the new view's DOM usually arrives after the URL changes.
+The event is driven by the browser's Navigation API (Chrome 102+, Firefox 147+); where that API is missing it
+silently never fires. `window.onurlchange === null` only shows that the grant was applied, not that the event
+will arrive. Combine with `waitFor`: the new view's DOM usually arrives after the URL changes.
 
 ## A menu switch that remembers its state
 
@@ -96,8 +95,9 @@ const res = await request({ url: "https://api.example.com/items", responseType:
 const items = res.response;
 ```
 
-The browser's cookies for the target site are sent unless `anonymous: true`. Requests to the page's own host
-need no `@connect`.
+The browser's cookies for the target site are sent unless `anonymous: true`. Requests to exactly the page's own
+host need no `@connect`; a subdomain of it needs `@connect self` or its own entry. Once the script has any
+`@connect` line, a request to an undeclared host is refused rather than asked.
 
 ## Styles
 
@@ -129,7 +129,7 @@ const t = (key) => (MESSAGES[lang] ?? MESSAGES[lang.split("-")[0]] ?? MESSAGES.e
 ## Background or scheduled run with retry
 
 Grants: `GM_xmlhttpRequest`, `GM_setValue`, `GM_log`, plus `@connect` for the host. `CATRetryError` needs no
-grant.
+grant of its own, but does not exist under `@grant none`.
 
 ```js
 return (async () => {