Tampermonkey 用户脚本开发
用户脚本是运行在浏览器中的脚本，用于修改网页内容或自动化网页任务。本技能资料面向“编写与调试 Tampermonkey 用户脚本”的场景，供用户在需要用户脚本时使用。
一、用途 用户脚本用于改变或自动化网站行为，脚本在浏览器内部运行。资料说明其基本定位：修改页面、自动化任务。
二、快速上手模板 资料提供两种模板。
- 简单 JavaScript 脚本（不使用 GM.* API）：使用 ==UserScript== 头部块，包含 @name、@namespace、@version、@description、@author、@match、@grant none、@run-at document-idle，脚本主体为 IIFE 并启用 'use strict'。
- 现代 async/await 写法（推荐在使用 GM.* API 时使用）：头部 @grant 声明 GM.getValue、GM.setValue，主体为 async IIFE，可用 await 调用 GM.* API，示例中通过 await GM.getValue('myKey', 'default') 读取设置并输出日志。 TypeScript：可添加 @types/tampermonkey 以获得完整类型安全，具体见资料中的 typescript.md。
三、头部标签要点 资料列出关键标签：@name（必填，支持 :locale 国际化）、@namespace（推荐，唯一标识命名空间）、@version（必填，自动更新所需，用于版本比较）、@description（推荐）、@match（必填，或用 @include，指定运行 URL）、@grant（按需，声明 API 权限，无 GM_* API 时用 none）、@run-at（可选，注入时机，默认 document-idle）、@run-in（可选，v5.3+，限制普通/隐身标签页或 Firefox 容器）。完整头部文档见 header-reference.md。
四、URL 匹配速查 精确域名：@match https://example.com/；所有子域名：@match https://.example.com/；HTTP 与 HTTPS：@match ://example.com/；排除路径：@exclude https://example.com/admin/。高级模式（正则、@include、特定路径）见 url-matching.md。
五、@grant 权限速查 资料以“需求—授权”对应方式列出：持久化存储用 GM_setValue + GM_getValue；跨域请求用 GM_xmlhttpRequest + @connect 域名；添加自定义 CSS 用 GM_addStyle；访问页面 window 用 unsafeWindow；显示通知用 GM_notification；添加菜单命令用 GM_registerMenuCommand；检测 URL 变化（SPA）用 window.onurlchange；批量读写设置（v5.3+）用 GM.getValues + GM.setValues；静音/取消静音标签页音频用 GM_audio。禁用沙箱（除 GM_info 外无 GM_*）用 @grant none；跨域请求需 @connect，例如 @connect api.example.com、@connect *.googleapis.com。完整权限指南见 header-reference.md。
六、@run-at 注入时机 资料列出：document-start（DOM 存在前，用于拦截资源、尽早修改全局变量）、document-body（body 存在时，早期 DOM 操作）、document-end（DOMContentLoaded 时，多数脚本适用，DOM 就绪）、document-idle（DOMContentLoaded 之后，默认，安全默认值）、context-menu（右键菜单触发，用户触发的操作）。
七、常见模式 资料列出常用模式摘要，完整实现见 patterns.md：等待元素（基于 Promise 的 MutationObserver，目标选择器出现时 resolve，可配置超时）；SPA URL 变化检测（使用 window.onurlchange 授权或拦截 History API）；跨域请求（用 GM_xmlhttpRequest 配合 @connect 域名白名单，另见 http-requests.md）；添加自定义样式（用 GM_addStyle 重设页面样式或隐藏元素，另见 api-dom-ui.md）；持久化设置（用 GM_setValue/GM_getValue 存储偏好，并通过 GM_registerMenuCommand 暴露开关，另见 api-storage.md）；DOM 变更观察（用 MutationObserver 监听动态添加内容，含防抖变体）；元素操作（注入 HTML、移除/隐藏元素、页面文本替换）；键盘快捷键（简单处理器及支持修饰键的快捷键管理器）；数据提取（将表格数据提取为数组/对象，收集并过滤页面链接）；错误处理（try/catch 安全包装与指数退避的异步重试）；TypeScript 用户脚本（类型安全，见 typescript.md）。
八、外部资源 @require 加载外部脚本，可用 sha256 校验，也可使用内置库 tampermonkey://vendor/jquery.js；@resource 预加载并注入外部 CSS，配合 GM_getResourceText 与 GM_addStyle 使用。
九、TypeScript 支持 安装类型定义：npm install --save-dev @types/tampermonkey。示例头部声明 @grant GM.getValue、GM.xmlHttpRequest 与 @connect api.example.com，脚本内使用 await GM.getValue<string>('key', 'default')，并用 Tampermonkey.ScriptInfo 类型读取 GM_info。使用打包工具（esbuild、Vite、webpack）构建为单个 .user.js 输出文件；完整项目配置（tsconfig 与打包器配置）见 typescript.md。
十、限制 资料明确列出用户脚本不能做的事：访问本地文件（不能读写电脑上的文件）；在页面脚本之前运行（在隔离沙箱模式下，页面脚本先运行）；访问跨域 iframe（浏览器安全限制）；跨机器持久化（GM 存储仅限本地各浏览器）；绕过所有 CSP（部分极严格 CSP 无法绕过）；未经许可注入（在 Chrome 和 Edge 中，用户必须在扩展详情页开启“允许用户脚本”开关，或旧版浏览器中开启开发者模式，脚本才能运行，脚本本身无法请求或绕过该限制；若脚本始终不运行，应先检查此项，见 common-pitfalls.md 第 15 条）。多数限制有变通方法，见 common-pitfalls.md。
十一、生成用户脚本时的要求 资料要求始终在回复中包含：说明（1—2 句，脚本做什么）；完整用户脚本（含全部头部的完整代码块）；安装方式（“复制/粘贴到 Tampermonkey 仪表盘”或“另存为 .user.js”）；可自定义点（选择器、超时等可安全修改项）；所用权限（哪些 @grant 及原因）；浏览器支持（仅 Chrome、仅 Firefox 或通用）。
十二、交付前检查清单 关键项（必须通过）：无硬编码 API 密钥、令牌或密码；@match 具体（非 :///*）；所有外部 URL 使用 HTTPS；DOM 插入前对用户输入做清洗。重要项（应当通过）：包裹在启用 'use strict' 的 IIFE 中；所有 @grant 均为必要；@connect 覆盖所有外部域名；异步操作有错误处理；DOM 操作前有空值检查。建议项：@version 遵循语义化版本（X.Y.Z）；在 Chrome 和 Firefox 均可工作；注释解释非显而易见代码。完整安全清单见 security-checklist.md。
十三、参考文件索引 资料按需加载的参考文件包括：核心类——header-reference.md（头部语法与全部 @标签示例）、url-matching.md（@match、@include、@exclude 模式）、patterns.md（常见实现模式与代码）、sandbox-modes.md（安全/隔离执行上下文）；API 类——api-sync.md（GM_* 同步函数，基于回调）、api-async.md（GM.* 基于 Promise 的 API，新脚本优先）、api-storage.md、http-requests.md、web-requests.md（GM_webRequest 拦截，Firefox）、api-cookies.md、api-dom-ui.md、api-tabs.md、api-audio.md；质量类——common-pitfalls.md、debugging.md、browser-compatibility.md、security-checklist.md、version-numbering.md、typescript.md。