SuperAPI AI 工具集

userscript-development

编程与开发

查看项目

更新于 11-11 20:02

技能介绍

用途 该技能面向 .user.js 用户脚本的开发、审查、故障排查与浏览器测试。默认目标为 Tampermonkey 与 Violentmonkey;若未指定目标,需记录这一假设。Safari Userscripts 与 Greasemonkey 视为独立目标。浏览器自动化在此仅作为测试驱动,不适用于定时爬虫或浏览器扩展的后台/标签页管理功能。

主要能力

  • 检查项目并确定验收用例:读取项目的代理指令、元数据校验器、脚本、测试夹具和近期验证记录,确定目标 URL、管理器/浏览器版本、frame 范围、触发方式、预期结果以及撤销 UI 改动的方法。
  • 建立元数据与执行边界:保留脚本标识与 URL 范围,将所需能力映射到已声明的 grant,区分 DOM 访问与页面 JavaScript 访问。
  • 使增强功能适应页面生命周期:分离持久外壳与路由相关状态,使协调逻辑幂等,约束观察器,使过期的异步工作失效。
  • 验证实际输出:对阅读器/导出器,克隆后再清理、排除自有 UI、保留快照并如实报告部分结果。
  • 运行聚焦的自动化测试:从语法与项目检查开始,在本地夹具中复现交互;浏览器测试涉及浏览器安装、测试页面、确定性的 GM shim、截图、下载与测试矩阵。
  • 在需要时用真实管理器验证:持久 Chromium 上下文、通过管理器 UI 安装、发现扩展 ID、Firefox 限制、差分/共存测试。仅 shim 通过不算完成此步。
  • 准备交付物:已分发脚本变更需提升版本号;用仓库工具重新生成索引;验证原始安装 URL 与依赖版本。

使用方式 默认从小型纯 JavaScript IIFE 与可直接安装的 .user.js 起步;当依赖或项目要求合理时再引入打包器,并保留项目现有构建体系与 API 风格。已安装的技能视为只读,示例需复制到工作项目后再安装依赖或运行,输出也保留在工作项目中。从用户选定的工作项目运行项目命令,先检查其 package 脚本与布局。内置浏览器示例需要 Node 20+ 与项目固定的 Playwright,二者均不是用户脚本运行时依赖;真实管理器测试还需相应官方扩展产物与隔离的浏览器配置文件。

测试分层

  • 语法/元数据/纯函数:验证解析、声明的能力与转换。
  • Chromium + Firefox 夹具配 GM shim:验证 DOM、键盘、路由、UI、输出与模拟的 GM 调用;不覆盖真实 grant、沙箱、管理器存储与更新。
  • 本地 HTTP 夹具上的真实管理器:验证安装、匹配、执行、存储与管理器集成;不覆盖任意站点及其他浏览器/管理器版本。
  • 仅参考扩展/仅脚本/两者并存:验证原生基线、预期差异、键盘与 UI 共存。
  • 指定的真实站点冒烟测试:验证该站点当前 DOM 上的命名交互。

注意事项 同步的应用标志不能阻止观察器反馈,变更回调稍后到达,写入前应比较期望的 DOM 值;尾随防抖在流式页面上可能永远得不到执行。DOM 观察器不是导航观察器,仅 URL 的路由变化可能没有 DOM 变更。控制台实验成功不保证页面上下文;新 grant 可能改变执行上下文;document-start 只是请求的时机。@require 的使用者也要承担依赖的 grant,静态正则扫描可能漏掉辅助函数与动态访问中的调用。一次 init-script 调用可保持 shim → 依赖 → 脚本顺序,分开注册则无相对顺序保证。无头环境下剪贴板成功不等于系统剪贴板验证。CSS 隔离不等于键盘隔离,Shadow DOM 事件可能重定向到宿主。两个已安装副本可能看起来像生命周期缺陷,需确认脚本 ID、版本、管理器以及是否同时运行 URL 安装与本地跟踪副本。GM_* 与 GM.* 在可用性、命名、返回值与时机上可能不同,缺失 API 的 await 仍是失败。

内置资源 首次搭建浏览器测试时,将 assets/fixture.html(带输入与可替换 main 的本地 SPA 测试页)、assets/fixture-tools.user.js(可安装的计数器/菜单演示)、assets/fixture.test.mjs(Node 测试运行器 + Chromium/Firefox、显式 GM shim、路由隔离、DOM 与存储断言、截图、清理)以及 assets/.gitignore 一并复制到项目的测试示例目录;它们展示夹具契约而非通用 shim。

交付模板 交付时报告:变更内容(脚本/文件、用户可见行为、版本前后)、目标(管理器与浏览器版本、URL/frame 范围)、权限/依赖(新增或变更的能力及原因)、检查项(静态/纯函数、浏览器夹具、真实管理器、参考对比、真实站点,各含命令与结果或未验证原因)、证据(测试页、报告、截图、输出路径)、安装/更新(产物/原始 URL、依赖与版本考虑)以及剩余限制(具体未测试行为,不推断通过)。

适用场景与限制 适用于 .user.js 的开发、审查、排障与浏览器测试,尤其是 SPA 变更、快捷键、注入 UI、焦点与清理场景。浏览器自动化仅用作测试驱动;Safari Userscripts 与 Greasemonkey 需单独处理;真实管理器测试依赖官方扩展产物与隔离配置文件,若环境受限,应完成独立检查并记录确切未验证用例。