✨ 支持 @unwrap (#1213)

* feat: 支持 `@unwrap`

* 加 example js 加 monaco editor hint

* 修正代码及测试

* 修正 restoreJSCodeFromCompiledResource

* 加入 `embeddedPatternCheckerString` 让 `@unwrap` 可以在 `@exclude` 排除

* update test js

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* copilot suggestions

* 行尾有多余空格

* ✅ 添加 @unwrap 功能单元测试和 E2E 测试

- isScriptletUnwrap / compileScriptletCode 单元测试
- embeddedPatternChecker / embeddedPatternCheckerString 单元测试
- compileInjectionCode unwrap 分支单元测试
- unwrap E2E 测试（GM API 为 undefined、全局变量可访问）

* 💄 格式化 content/utils.test.ts（Prettier 自动修正）

---------

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: 王一之 <yz@ggnb.top>

Author: 3 people

e2e/gm-api.spec.ts

@@ -196,4 +196,21 @@ test.describe("GM API", () => {
     expect(failed, "Some content inject tests failed").toBe(0);
     expect(passed, "No test results found - script may not have run").toBeGreaterThan(0);
   });
+
+  test("Unwrap scriptlet tests (unwrap_e2e_test.js)", async ({ context, extensionId }) => {
+    const { passed, failed, logs } = await runTestScript(
+      context,
+      extensionId,
+      "unwrap_e2e_test.js",
+      TARGET_URL,
+      60_000
+    );
+
+    console.log(`[unwrap_e2e_test] passed=${passed}, failed=${failed}`);
+    if (failed !== 0) {
+      console.log("[unwrap_e2e_test] logs:", logs.join("\n"));
+    }
+    expect(failed, "Some unwrap scriptlet tests failed").toBe(0);
+    expect(passed, "No test results found - script may not have run").toBeGreaterThan(0);
+  });
 });

example/tests/unwrap_e2e_test.js

@@ -0,0 +1,67 @@
+// ==UserScript==
+// @name         Unwrap E2E Test
+// @namespace    https://docs.scriptcat.org/
+// @version      1.0.0
+// @description  E2E 测试 @unwrap 功能
+// @author       ScriptCat
+// @match        https://content-security-policy.com/*
+// @grant        GM_setValue
+// @unwrap
+// ==/UserScript==
+
+var __unwrap_e2e_global_var = "unwrap_success";
+
+(function () {
+  "use strict";
+
+  let testResults = {
+    passed: 0,
+    failed: 0,
+    total: 0,
+  };
+
+  function test(name, fn) {
+    testResults.total++;
+    try {
+      fn();
+      testResults.passed++;
+      console.log("%c✓ " + name, "color: green;");
+      return true;
+    } catch (error) {
+      testResults.failed++;
+      console.error("%c✗ " + name, "color: red;", error);
+      return false;
+    }
+  }
+
+  function assert(expected, actual, message) {
+    if (expected !== actual) {
+      var valueInfo = "期望 " + JSON.stringify(expected) + ", 实际 " + JSON.stringify(actual);
+      var error = message ? message + " - " + valueInfo : "断言失败: " + valueInfo;
+      throw new Error(error);
+    }
+  }
+
+  // ============ @unwrap 测试 ============
+  console.log("%c=== @unwrap E2E 测试开始 ===", "color: blue; font-size: 16px; font-weight: bold;");
+
+  // 测试1: GM API 在 unwrap 模式下为 undefined
+  test("GM 对象在 unwrap 模式下为 undefined", function () {
+    assert("undefined", typeof GM, "GM 应为 undefined");
+  });
+
+  test("GM_setValue 在 unwrap 模式下为 undefined", function () {
+    assert("undefined", typeof GM_setValue, "GM_setValue 应为 undefined");
+  });
+
+  // 测试2: 脚本代码在页面全局作用域执行
+  test("全局变量可在页面作用域访问", function () {
+    assert("unwrap_success", window.__unwrap_e2e_global_var, "全局变量应可访问");
+  });
+
+  // ============ 测试总结 ============
+  console.log("\n%c=== 测试结果总结 ===", "color: blue; font-size: 16px; font-weight: bold;");
+  console.log("总测试数: " + testResults.total);
+  console.log("%c通过: " + testResults.passed, "color: green; font-weight: bold;");
+  console.log("%c失败: " + testResults.failed, "color: red; font-weight: bold;");
+})();

example/tests/unwrap_test.js

@@ -0,0 +1,66 @@
+// ==UserScript==
+// @name         A Scriptlet for @unwrap test
+// @namespace    none
+// @version      2026-02-07
+// @description  try to take over the world!
+// @author       You
+// @match        https://*/*?test_unwrap*
+// @exclude      /test_\w+_excluded/
+// @grant        GM_setValue
+// @require      https://cdn.jsdelivr.net/npm/jquery@3.6.0/dist/jquery.min.js#sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK
+// @unwrap
+// ==/UserScript==
+
+// include: https://example.com/?test_unwrap_123
+// exclude: https://example.com/?test_unwrap_excluded
+
+var test_global_injection = "success";
+// User can access the variable "test_global_injection" directly in DevTools
+
+(function () {
+    const results = {
+        GM: {
+            expected: "undefined",
+            actual: typeof GM,
+        },
+        GM_setValue: {
+            expected: "undefined",
+            actual: typeof GM_setValue,
+        },
+        jQuery: {
+            expected: "function",
+            actual: typeof jQuery,
+        },
+    };
+
+    console.group(
+        "%c@unwrap Test",
+        "color:#0aa;font-weight:bold"
+    );
+
+    const table = {};
+    let allPass = true;
+
+    for (const key in results) {
+        const { expected, actual } = results[key];
+        const pass = expected === actual;
+        allPass &&= pass;
+
+        table[key] = {
+            Expected: expected,
+            Actual: actual,
+            Result: pass ? "✅ PASS" : "❌ FAIL",
+        };
+    }
+
+    console.table(table);
+
+    console.log(
+        allPass
+            ? "%cAll tests passed ✔"
+            : "%cSome tests failed ✘",
+        `font-weight:bold;color:${allPass ? "green" : "red"}`
+    );
+
+    console.groupEnd();
+})();

src/app/service/content/utils.test.ts

@@ -1,7 +1,16 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { compileScriptCode, compileScript, compileInjectScript, addStyle, addStyleSheet } from "./utils";
+import {
+  compileScriptCode,
+  compileScript,
+  compileInjectScript,
+  compileScriptletCode,
+  isScriptletUnwrap,
+  addStyle,
+  addStyleSheet,
+} from "./utils";
 import type { ScriptRunResource } from "@App/app/repo/scripts";
 import type { ScriptFunc } from "./types";
+import { RuleType, type URLRuleEntry } from "@App/pkg/utils/url_matcher";
 
 // 设置 console mock 来避免测试输出污染
 vi.spyOn(console, "error").mockImplementation(() => {});
@@ -518,4 +527,138 @@ describe("utils", () => {
       expect((returnedSheet as any).cssText).toBe(css);
     });
   });
+
+  describe.concurrent("isScriptletUnwrap", () => {
+    it.concurrent("@unwrap 为空值时返回 true", () => {
+      expect(isScriptletUnwrap({ unwrap: [""] })).toBe(true);
+    });
+
+    it.concurrent("@unwrap 为 true 时返回 true", () => {
+      expect(isScriptletUnwrap({ unwrap: ["true"] })).toBe(true);
+    });
+
+    it.concurrent("没有 @unwrap 时返回 false", () => {
+      expect(isScriptletUnwrap({})).toBe(false);
+    });
+
+    it.concurrent("@unwrap 为 false 时返回 false", () => {
+      expect(isScriptletUnwrap({ unwrap: ["false"] })).toBe(false);
+    });
+  });
+
+  describe.concurrent("compileScriptletCode", () => {
+    const createMockScriptRes = (
+      overrides: Partial<ScriptRunResource> = {},
+      scriptUrlPatterns: URLRuleEntry[] = []
+    ): { scriptRes: ScriptRunResource; scriptUrlPatterns: URLRuleEntry[] } => ({
+      scriptRes: {
+        uuid: "test-uuid",
+        name: "Unwrap Script",
+        namespace: "test.namespace",
+        type: 1,
+        status: 1,
+        sort: 0,
+        runStatus: "complete",
+        createtime: Date.now(),
+        checktime: Date.now(),
+        code: "console.log('unwrap');",
+        value: {},
+        flag: "test-flag",
+        resource: {},
+        metadata: { unwrap: [""] },
+        originalMetadata: {},
+        ...overrides,
+      },
+      scriptUrlPatterns,
+    });
+
+    it.concurrent("应该正确编译基本 unwrap 脚本", () => {
+      const patterns: URLRuleEntry[] = [
+        {
+          ruleType: RuleType.MATCH_INCLUDE,
+          ruleContent: ["https", "example.com", "*"],
+          ruleTag: "match",
+          patternString: "https://example.com/*",
+        },
+      ];
+      const { scriptRes } = createMockScriptRes({}, patterns);
+
+      const result = compileScriptletCode(scriptRes, scriptRes.code, patterns);
+
+      // 包含脚本代码
+      expect(result).toContain("console.log('unwrap');");
+      // 包含 sourceURL
+      expect(result).toContain("sourceURL=");
+      expect(chrome.runtime.getURL).toHaveBeenCalledWith("/Unwrap%20Script.user.js");
+      // 包含 flag 注册
+      expect(result).toContain("window['test-flag']=function(){};");
+      // 包含 URL 条件包裹 (if(...){...})
+      expect(result).toMatch(/^if\(/);
+      // 不包含沙箱封装
+      expect(result).not.toContain("with(arguments[0]||this.$)");
+      expect(result).not.toContain("return(async function(){");
+    });
+
+    it.concurrent("应该包含 require 资源", () => {
+      const patterns: URLRuleEntry[] = [
+        {
+          ruleType: RuleType.MATCH_INCLUDE,
+          ruleContent: ["*", "example.com", "*"],
+          ruleTag: "match",
+          patternString: "*://example.com/*",
+        },
+      ];
+      const { scriptRes } = createMockScriptRes(
+        {
+          metadata: {
+            unwrap: [""],
+            require: ["https://cdn.example.com/lib.js"],
+          },
+          resource: {
+            "https://cdn.example.com/lib.js": {
+              url: "https://cdn.example.com/lib.js",
+              content: "var libLoaded = true;",
+              base64: "",
+              hash: { md5: "t", sha1: "t", sha256: "t", sha384: "t", sha512: "t" },
+              type: "require",
+              link: {},
+              contentType: "text/javascript",
+              createtime: Date.now(),
+            },
+          },
+        },
+        patterns
+      );
+
+      const result = compileScriptletCode(scriptRes, scriptRes.code, patterns);
+
+      expect(result).toContain("var libLoaded = true;");
+      expect(result).toContain("console.log('unwrap');");
+    });
+
+    it.concurrent("应该包含 URL 条件检查代码", () => {
+      const patterns: URLRuleEntry[] = [
+        {
+          ruleType: RuleType.MATCH_INCLUDE,
+          ruleContent: ["https", "example.com", "*"],
+          ruleTag: "match",
+          patternString: "https://example.com/*",
+        },
+        {
+          ruleType: RuleType.MATCH_EXCLUDE,
+          ruleContent: ["https", "example.com", "admin/*"],
+          ruleTag: "match",
+          patternString: "https://example.com/admin/*",
+        },
+      ];
+      const { scriptRes } = createMockScriptRes({}, patterns);
+
+      const result = compileScriptletCode(scriptRes, scriptRes.code, patterns);
+
+      // 生成的代码应包含 embeddedPatternChecker 调用
+      expect(result).toContain("location.href");
+      // if 条件包裹
+      expect(result).toMatch(/^if\(/);
+    });
+  });
 });

src/app/service/content/utils.ts

@@ -4,6 +4,7 @@ import type { ScriptLoadInfo } from "../service_worker/types";
 import { DefinedFlags } from "../service_worker/runtime.consts";
 import { sourceMapTo } from "@App/pkg/utils/utils";
 import { ScriptEnvTag } from "@Packages/message/consts";
+import { embeddedPatternCheckerString, type EmbeddedURLRuleEntry, type URLRuleEntry } from "@App/pkg/utils/url_matcher";
 
 export type CompileScriptCodeResource = {
   name: string;
@@ -66,6 +67,31 @@ export function getScriptRequire(scriptRes: ScriptRunResource): CompileScriptCod
   return resourceArray;
 }
 
+/**
+ * 构建unwrap脚本运行代码
+ * @see {@link ExecScript}
+ * @param scriptRes
+ * @param scriptCode
+ * @returns
+ */
+export function compileScriptletCode(
+  scriptRes: ScriptRunResource,
+  scriptCode: string,
+  scriptUrlPatterns: URLRuleEntry[]
+): string {
+  scriptCode = scriptCode ?? scriptRes.code;
+  const requireArray = getScriptRequire(scriptRes);
+  const requireCode = requireArray.map((r) => r.content).join("\n;");
+  // 在window[flag]注册一个空脚本让原本的脚本管理器知道并记录脚本成功执行
+  const reducedPatterns = scriptUrlPatterns.map(({ ruleType, ruleContent }) => ({
+    ruleType,
+    ruleContent,
+  })) satisfies EmbeddedURLRuleEntry[];
+  const urlCondition = embeddedPatternCheckerString("location.href", JSON.stringify(reducedPatterns));
+  const codeBody = `if(${urlCondition}){\n${requireCode}\n${scriptCode}\nwindow['${scriptRes.flag}']=function(){};\n}`;
+  return `${codeBody}${sourceMapTo(`${scriptRes.name}.user.js`)}\n`;
+}
+
 /**
  * 构建脚本运行代码
  * @see {@link ExecScript}
@@ -241,6 +267,10 @@ export function isEarlyStartScript(metadata: SCMetadata): boolean {
   return metadataBlankOrTrue(metadata, "early-start") && metadata["run-at"]?.[0] === "document-start";
 }
 
+export function isScriptletUnwrap(metadata: SCMetadata): boolean {
+  return metadataBlankOrTrue(metadata, "unwrap");
+}
+
 export function isInjectIntoContent(metadata: SCMetadata): boolean {
   return metadata["inject-into"]?.[0] === "content";
 }

src/app/service/service_worker/runtime.ts

@@ -32,8 +32,10 @@ import type { CompileScriptCodeResource } from "../content/utils";
 import {
   compileInjectScriptByFlag,
   compileScriptCodeByResource,
+  compileScriptletCode,
   isEarlyStartScript,
   isInjectIntoContent,
+  isScriptletUnwrap,
   trimScriptInfo,
 } from "../content/utils";
 import LoggerCore from "@App/app/logger/core";
@@ -755,9 +757,15 @@ export class RuntimeService {
 
   // 从CompiledResource中还原脚本代码
   async restoreJSCodeFromCompiledResource(script: Script, result: CompiledResource) {
-    const earlyScript = isEarlyStartScript(script.metadata);
+    // 如果是 Scriptlet (unwrap) 脚本，需要另外的处理方式
+    if (isScriptletUnwrap(script.metadata)) {
+      const scriptRes = await this.script.buildScriptRunResource(script);
+      if (!scriptRes) return "";
+      return compileScriptletCode(scriptRes, scriptRes.code, result.scriptUrlPatterns);
+    }
+
     // 如果是预加载脚本，需要另外的处理方式
-    if (earlyScript) {
+    if (isEarlyStartScript(script.metadata)) {
       const scriptRes = await this.script.buildScriptRunResource(script);
       if (!scriptRes) return "";
       return compileInjectionCode(scriptRes, scriptRes.code, result.scriptUrlPatterns);