ScriptCat：构建下一代浏览器自动化平台的技术架构解析

ScriptCat：构建下一代浏览器自动化平台的技术架构解析

【免费下载链接】scriptcatScriptCat, a browser extension that can execute userscript; 脚本猫，一个可以执行用户脚本的浏览器扩展项目地址: https://gitcode.com/gh_mirrors/sc/scriptcat

在浏览器生态中，用户脚本管理器长期扮演着桥梁角色，连接着网页原生能力与用户自定义需求。然而，传统脚本管理器在架构设计、执行模型和扩展性方面存在诸多限制。ScriptCat作为新一代浏览器扩展，通过创新的多进程架构、统一的消息通信层和模块化服务设计，重新定义了用户脚本管理器的技术范式，为开发者提供了更强大的自动化能力。

架构解析：基于Manifest V3的分布式系统设计

ScriptCat采用Manifest V3规范构建，这一选择决定了其核心架构的分布式特性。与传统的单进程扩展不同，MV3将扩展功能分散到多个隔离的JavaScript执行环境中，这要求ScriptCat必须设计为一个协同工作的分布式系统。

五层上下文模型

ScriptCat定义了五个独立的执行上下文，每个上下文承担特定职责，通过消息传递进行协作：

1. Service Worker（服务工作者）- 位于src/service_worker.ts，作为系统的中央枢纽，拥有chrome.*特权API访问权限，负责脚本的CRUD操作、权限验证、资源缓存和路由分发。

2. Content Script（内容脚本）- 位于src/content.ts，作为Service Worker和页面脚本之间的桥梁，运行在隔离的内容脚本环境中，确保安全边界。

3. Inject Script（注入脚本）- 位于src/inject.ts，运行在页面主世界中，拥有unsafeWindow访问权限，直接执行用户脚本。

4. Offscreen Document（离屏文档）- 位于src/offscreen.ts，提供DOM能力的后台环境，处理Blob操作、剪贴板访问、DOM解析等需要DOM API的功能。

5. Sandbox（沙箱）- 位于src/sandbox.ts，运行在离屏文档内的iframe中，负责后台脚本和定时脚本的隔离执行。

这种分层架构的关键优势在于安全性隔离与功能专一性。每个上下文只能访问特定范围的API，通过最小权限原则降低安全风险。例如，只有Inject Script可以直接操作页面DOM，而Service Worker则专注于系统级管理。

统一消息通信层

ScriptCat的核心创新在于packages/message模块，它抽象了不同传输协议，提供了统一的RPC和发布/订阅API。这一设计使开发者无需直接处理底层浏览器API的复杂性。

// 消息传输层抽象 interface Message { send(action: string, params: any): Promise<any>; connect(): MessageConnect; } // RPC调用示例 const value = await client.do("value/getScriptValue", { uuid });

系统支持多种传输机制：

• ExtensionMessage：基于chrome.runtime.sendMessage，用于Service Worker与其他上下文通信
• CustomEventMessage：基于DOM CustomEvent，用于Content Script与Inject Script通信
• WindowMessage：基于window.postMessage，用于Offscreen与Sandbox通信

这种设计使得服务可以基于接口（Server/Group/Client/IMessageQueue）而非具体实现进行开发，极大提高了代码的可测试性和可维护性。

能力矩阵：模块化功能架构

ScriptCat的功能体系可以分解为几个核心模块，每个模块都有明确的职责边界：

服务层设计模式

ScriptCat采用构造函数依赖注入（DI）模式构建服务层，每个服务通过构造函数接收其依赖项，在init()方法中注册消息处理器：

class ScriptService { constructor( private readonly systemConfig: SystemConfig, private readonly group: Group, // RPC命名空间 "script/*" private readonly mq: IMessageQueue, // 广播总线 private readonly valueService: ValueService, private readonly resourceService: ResourceService, private readonly scriptDAO: ScriptDAO // 数据访问 ) {} init() { this.group.on("getAllScripts", this.getAllScripts.bind(this)); this.group.on("install", this.installScript.bind(this)); // ... 约20个处理器 } }

这种设计模式的优势在于：

1. 可测试性：依赖项可以通过接口注入，便于单元测试
2. 松耦合：服务之间通过接口而非具体实现交互
3. 生命周期管理：初始化逻辑集中在init()方法中，避免构造函数副作用

实战场景：技术架构的实际应用

场景一：跨上下文GM API调用

当用户脚本调用GM_xmlhttpRequest时，ScriptCat的执行流程展示了其架构优势：

// 用户脚本发起请求 GM_xmlhttpRequest({ method: "GET", url: "https://api.example.com/data", onload: (response) => console.log(response.responseText) }); // 执行流程： // 1. Inject Script -> Content Script (CustomEventMessage) // 2. Content Script -> Service Worker (ExtensionMessage) // 3. Service Worker进行权限验证 (@PermissionVerify.API) // 4. 构建DNR规则 (declarativeNetRequest) // 5. 执行实际网络请求 // 6. 通过MessageConnect流式返回数据

这一流程涉及三个不同的执行上下文和两种消息传输机制，但通过统一的抽象层，对开发者完全透明。

场景二：后台脚本的隔离执行

@background脚本的执行路径展示了ScriptCat的隔离设计：

Service Worker → Offscreen Document → Sandbox iframe ↓ ↓ ↓ 权限检查 DOM环境准备 脚本执行包装 ↓ ↓ ↓ 脚本元数据 BgExecScriptWarp with(){}沙箱

后台脚本在沙箱iframe中执行，通过BgExecScriptWarp提供受控的setTimeout/setInterval实现，支持CATRetryError语义，确保长时间运行脚本可以被优雅地终止和重试。

场景三：定时任务的精确调度

@crontab脚本的调度机制结合了cron表达式解析和消息广播：

// 沙箱中的cron调度器 const cronJobs = new Map<string, CronJob[]>(); // 解析cron表达式 const job = new CronJob(cronExpression, () => { // 通过MessageQueue广播执行事件 this.mq.publish("cronExecute", { scriptUuid, timestamp }); }); // 服务端接收广播并触发脚本执行 this.mq.subscribe("cronExecute", async (data) => { const script = await this.scriptDAO.get(data.scriptUuid); await this.executeBackgroundScript(script); });

生态整合：与现代开发工具链的融合

构建系统集成

ScriptCat采用Rspack作为构建工具，支持现代前端开发工作流：

# 开发模式 pnpm run dev # 生产构建 pnpm run build # 打包发布 pnpm run pack

构建配置位于rspack.config.ts，支持：

• 按上下文分包的代码分割策略
• 开发/生产环境差异化配置
• 路径别名映射（@App → src,@Packages → packages）
• 资源复制和HTML模板生成

测试体系设计

ScriptCat建立了完整的测试金字塔：

1. 单元测试（Vitest + jsdom）- 基于@Packages/chrome-extension-mock模拟浏览器API，MockMessage模拟消息总线
2. 集成测试- 测试服务间协作和数据流
3. 端到端测试（Playwright）- 真实浏览器环境测试

测试代码与实现代码相邻放置，遵循TDD（测试驱动开发）原则：

// 与服务代码同目录的测试文件 describe("ScriptService", () => { it("应该正确安装脚本", async () => { const mockMessage = new MockMessage(); const service = new ScriptService(/* 依赖注入 */); await service.init(); const result = await client.do("script/install", scriptData); expect(result).toBeDefined(); }); });

开发者工具支持

ScriptCat内置了完整的开发者体验优化：

1. ESLint集成-packages/eslint模块提供用户脚本的语法检查
2. TypeScript支持- 完整的类型定义位于src/types/scriptcat.d.ts
3. Monaco编辑器- 内置代码编辑器支持语法高亮和智能补全
4. 热重载开发- 开发模式下支持实时重载

进阶路线：从使用者到贡献者

第一阶段：基础使用与脚本开发

1. 环境搭建：通过Chrome Web Store安装ScriptCat，或从源码构建：

   git clone https://gitcode.com/gh_mirrors/sc/scriptcat cd scriptcat npm install npm run build

2. 脚本编写：从简单脚本开始，逐步掌握GM API使用模式：

   // ==UserScript== // @name 示例脚本 // @namespace http://example.com // @match https://*.example.com/* // @grant GM_getValue // @grant GM_setValue // @grant GM_xmlhttpRequest // ==/UserScript== (function() { 'use strict'; // 使用GM API进行数据存储 const storedValue = GM_getValue('myKey', 'default'); GM_setValue('myKey', 'updatedValue'); // 发起网络请求 GM_xmlhttpRequest({ method: 'GET', url: 'https://api.example.com/data', onload: function(response) { console.log('响应数据:', response.responseText); } }); })();

3. 调试技巧：利用浏览器开发者工具的扩展面板进行调试，查看脚本执行日志和错误信息。

第二阶段：架构理解与高级功能

1. 多上下文通信：深入理解ScriptCat的消息传递机制，掌握RPC和发布/订阅模式的应用场景。

2. 后台脚本开发：学习@background和@crontab脚本的编写，理解沙箱执行环境的特点。

3. 自定义GM API：通过@GMContext.API装饰器扩展ScriptCat的功能API。

第三阶段：源码贡献与架构演进

1. 代码规范：遵循项目中的ESLint规则，特别是require-last-error-check规则，确保正确处理chrome.runtime.lastError。

2. 测试驱动开发：为新增功能编写测试用例，确保代码质量。

3. 架构扩展：按照现有模式添加新功能：

   • 新实体：继承Repo<T>基类
   • 新服务：构造函数注入依赖，在init()中注册处理器
   • 新消息：使用现有Group和MessageQueue

未来展望：浏览器自动化的技术演进

技术趋势与架构适应

随着Web平台的发展，ScriptCat的架构设计需要考虑以下趋势：

1. WebAssembly集成：为计算密集型脚本提供WASM执行环境，提升性能。

2. Service Worker演进：随着Service Worker API的丰富，ScriptCat可以更深度地集成浏览器原生能力。

3. 跨平台兼容：当前架构已经考虑了Chrome和Firefox的差异，未来需要适配更多浏览器平台。

4. 性能优化：通过更精细的代码分割和懒加载策略，减少扩展的内存占用。

生态系统建设

ScriptCat的技术架构为生态系统扩展提供了坚实基础：

1. 插件系统：基于现有消息总线和服务发现机制，可以构建插件系统，允许第三方扩展功能。

2. 脚本市场：利用现有的脚本存储和同步机制，构建脚本分发平台。

3. 开发者工具：基于Monaco编辑器构建更强大的脚本开发环境，集成调试和性能分析工具。

安全与隐私增强

作为浏览器扩展，安全始终是首要考虑：

1. 权限粒度细化：当前基于@grant的权限系统可以进一步细化，支持更细粒度的访问控制。

2. 脚本签名验证：引入脚本签名机制，确保脚本来源可信。

3. 执行环境隔离：进一步加强沙箱机制，防止脚本间的相互影响。

结语：技术驱动的浏览器自动化未来

ScriptCat通过创新的架构设计，解决了传统用户脚本管理器在安全性、扩展性和可维护性方面的局限性。其分布式系统设计、统一消息通信层和模块化服务架构，不仅为当前功能提供了坚实基础，也为未来扩展预留了充足空间。

对于技术团队而言，ScriptCat的架构提供了宝贵的参考价值：如何在浏览器扩展的限制下构建可维护的复杂系统，如何平衡安全隔离与功能集成，如何设计可测试的异步通信模型。这些设计决策体现了现代软件工程的最佳实践。

随着浏览器能力的不断扩展和Web标准的演进，ScriptCat的技术架构将继续演进，为用户提供更强大、更安全、更易用的浏览器自动化能力。无论是个人用户简化日常操作，还是企业团队构建复杂的自动化工作流，ScriptCat都提供了一个可靠的技术基础。

ScriptCat的技术架构体现了现代浏览器扩展开发的最佳实践，通过分层设计和模块化架构，在安全性和功能性之间取得了良好平衡。

对于开发者来说，理解ScriptCat的架构不仅有助于更好地使用这一工具，也为构建类似的复杂浏览器扩展提供了宝贵经验。从消息通信模式到服务层设计，从数据持久化策略到跨上下文协作，ScriptCat的每一个设计决策都值得深入研究和借鉴。

浏览器自动化正在从简单的页面操作脚本，演变为复杂的分布式应用系统。ScriptCat站在这一演进的前沿，通过扎实的技术架构，为下一代浏览器自动化平台奠定了坚实基础。随着技术的不断发展，我们有理由相信，基于类似架构的浏览器扩展将在未来发挥更加重要的作用，成为连接用户需求与Web能力的关键桥梁。

【免费下载链接】scriptcatScriptCat, a browser extension that can execute userscript; 脚本猫，一个可以执行用户脚本的浏览器扩展项目地址: https://gitcode.com/gh_mirrors/sc/scriptcat