Mode d’emploi
- Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
- Consultez le document original pour les outils, identifiants et environnements requis.
- Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/scriptscat/scriptcat --skill scriptcat-userscriptAvant de commencer
- L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
- Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.
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.
// ==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";
// ...
})();// ==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+@namespaceidentify 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
- Every API needs a
@grantline (@grant GM_xmlhttpRequest, …). An ungranted API is simply undefined at
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_infoneeds no grant.unsafeWindowneeds no grant either, but only exists in the sandbox (any grant
other than none, or no @grant line at all); @grant unsafeWindow is harmless.
@grant noneruns the script without the sandbox:windowis 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 — and also with no
@grantline 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
@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-starttogether withdocument-startwhen 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.
@noframeskeeps the script out of iframes; without it, a*://*/*match also runs inside every iframe.@inject-into contentruns in the content-script world: unaffected by the page's CSP, butunsafeWindow
is then not the page's window. The default is page.
GM_addStyleandGM_addElementbypass 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
GM_setValuestores JSON-like data only (no class instances). Settingundefineddeletes 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_addValueChangeListenersees writes
from the other scripts (and from other tabs) — a simple cross-script channel.
Background and scheduled scripts
- Return a
Promiseand 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. 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; 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 aDate).CATRetryErroris 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
@crontabline. 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.
- 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
- 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.
4. API lookup
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.
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.
First run the static check bundled with this skill (Node 18+, no dependencies; paths are relative to this skill's directory):
node scripts/check.mjs my-script.user.js # exit 1 = errors that will break the script at runtimeIt 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 statusshows ScriptCat connected): install it into the user's ScriptCat and
verify it in their browser, following 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 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.jsand 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 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.