@trim21/personal-pi-extensions 0.1.654 → 0.1.658

package/README.md

@@ -11,6 +11,7 @@
 | [opencode 工具集](#opencode-工具集)       | 小写 `read`/`edit`/`write`/`grep`/`glob`/`bash`/`todowrite`/`question`                        |
 | [Claude Code 工具集](#claude-code-工具集) | 大写 `Read`/`Edit`/`Write`/`Grep`/`Glob`/`Bash`/`TodoWrite`/`AskUserQuestion`                 |
 | [工具启用配置](#工具启用配置)             | `personalExtensions`：按模型选文件 IO 工具集、通配禁用/启用工具                               |
+| [codemode](#codemode)                     | 模型写一段 JS，在 QuickJS 沙箱里批量/串行调用其它工具，只有脚本输出进上下文                   |
 | [bwrap](#bwrap)                           | 基于 bubblewrap 的 OS 级沙箱（内置两套工具集）：文件系统隔离 + 多档网络策略                   |
 | [写保护（内置）](#写保护内置)             | 写工具内置：限制文件写入在 workspace 内，外部写入需审批                                       |
 | [LSP（内置）](#lsp内置)                   | 文件工具内置 LSP 诊断 + `lsp-rename`/`lsp-inspect`/`lsp-find-definition`/`lsp-find-reference` |
@@ -26,6 +27,30 @@
 
 ---
 
+## codemode
+
+`codemode` 让模型写一段 JavaScript（作为 async 函数体，`await` 与 `return` 都可用），在
+进程内的 worker 线程里用 QuickJS wasm VM 执行。VM 里没有 node、文件系统、网络、timer
+或模块加载，脚本唯一的出口是 `tools.<name>(args)`。
+
+- **嵌套调用经工具总线**：`tools.Read({ file_path })` 最终执行的是 `Read` 工具自己的
+  `execute`，所以工具的审批照常生效（写工作区外会弹 write-guard，Bash 沙箱外执行会弹
+  自己的提权确认）。codemode 不额外加确认层：脚本里连发十次写操作就是十次工具自己的
+  审批（需要审批的那些）。
+- **可调用集合** = 总线上实际注册的工具减去 `codemode` 自身，执行时再与当前 active
+  列表求交，所以 `personalExtensions.disabledTools`、pi 的 `defaultTools` / `--tools`、
+  子代理的工具白名单都同样约束脚本。
+- **只有脚本输出进上下文**：`text(value)` / `console.log(...)` 与 `return` 值进入工具结果，
+  中间的工具调用与它们的返回内容不会（也不在会话记录里留下工具调用条目）。
+- **脚本接口**：`tools` / `ALL_TOOLS` / `text` / `image` / `exit` / `console.*` /
+  `store(key, value)` / `load(key)`；首行可选 `// @options: {"timeout_ms": 30000,
+"max_output_tokens": 10000}`。默认没有超时，靠调用方中止或 `timeout_ms` 结束。
+- **store** 写在会话的自定义 entry 上（跟随分支），输出超过 `max_output_tokens` 时头尾
+  截断并把全文落到 `$TMPDIR/pi-codemode-*.txt`。
+- **构建**：worker 入口是 esbuild 产物 `src/codemode/worker.js`（随仓库提交，
+  `pnpm run build:codemode-worker` 重新生成，pre-commit 会自动跑）；`quickjs-wasi` 的
+  wasm 在注册工具时编译一次，之后每次执行复用。
+
 ## 工具启用配置
 
 所有工具由单一扩展入口 `src/index.ts` 注册（`package.json` 的 `pi.extensions` 只列

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.654",
+  "version": "0.1.658",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [
@@ -27,7 +27,8 @@
     "sandbox": "jiti bin/sandbox.ts",
     "aft-search": "jiti bin/aft-search.ts",
     "build:holder": "esbuild src/bwrap/holder.ts --format=esm --target=node24 --outfile=src/bwrap/holder.js",
-    "prepare": "husky"
+    "prepare": "husky",
+    "build:codemode-worker": "esbuild src/codemode/worker.ts --bundle --packages=external --format=esm --target=node24 --outfile=src/codemode/worker.js"
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": ">=0.84.1",
@@ -96,6 +97,7 @@
     "lodash-es": "^4.18.1",
     "minimatch": "^10.2.6",
     "octokit": "^5.0.5",
+    "quickjs-wasi": "^3.6.2",
     "turndown": "^7.2.0",
     "undici": "^8.0.0",
     "vscode-languageserver-protocol": "^3.18.4",

package/src/codemode/declarations.ts

@@ -0,0 +1,103 @@
+/**
+ * 把工具的参数 schema 渲染成脚本侧的 TypeScript 声明：写进 codemode 的工具描述里，
+ * 模型据此知道脚本里能写 `await tools.Read({ file_path: "..." })`。
+ *
+ * 只处理本仓库工具实际用到的形状（object / array / string / number / boolean /
+ * union / enum），其余退化成 `unknown`——宁可少给类型，也不要编出错类型。
+ */
+
+import type { ScriptTool } from "./protocol.js";
+
+interface ToolLike {
+  name: string;
+  description?: string;
+  parameters?: unknown;
+}
+
+type JsonSchema = Record<string, unknown>;
+
+function isSchema(value: unknown): value is JsonSchema {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function literal(value: unknown): string {
+  return typeof value === "string" ? JSON.stringify(value) : String(value);
+}
+
+/** 工具名作为属性访问：非法标识符用引号形式。 */
+function propertyName(name: string): string {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
+}
+
+function renderType(schema: unknown, indent: string): string {
+  if (!isSchema(schema)) {
+    return "unknown";
+  }
+  if (Array.isArray(schema.enum) && schema.enum.length > 0) {
+    return schema.enum.map((value) => literal(value)).join(" | ");
+  }
+  if (Array.isArray(schema.anyOf) && schema.anyOf.length > 0) {
+    return schema.anyOf.map((option) => renderType(option, indent)).join(" | ");
+  }
+
+  switch (schema.type) {
+    case "string": {
+      return "string";
+    }
+    case "number":
+    case "integer": {
+      return "number";
+    }
+    case "boolean": {
+      return "boolean";
+    }
+    case "null": {
+      return "null";
+    }
+    case "array": {
+      return `Array<${renderType(schema.items, indent)}>`;
+    }
+    case "object": {
+      const properties = isSchema(schema.properties) ? schema.properties : {};
+      const required = new Set(Array.isArray(schema.required) ? (schema.required as string[]) : []);
+      const entries = Object.entries(properties);
+      if (entries.length === 0) {
+        return "Record<string, unknown>";
+      }
+      const lines = entries.map(([key, value]) => {
+        const optional = required.has(key) ? "" : "?";
+        return `${indent}  ${propertyName(key)}${optional}: ${renderType(value, `${indent}  `)};`;
+      });
+      return `{\n${lines.join("\n")}\n${indent}}`;
+    }
+    default: {
+      return "unknown";
+    }
+  }
+}
+
+/** 单个工具在脚本里的签名（`tools` 的一个成员）。 */
+function renderToolMember(tool: ToolLike): string {
+  const summary = tool.description?.split("\n", 1)[0]?.trim();
+  const doc = summary ? `/** ${summary} */\n  ` : "";
+  return `${doc}${propertyName(tool.name)}(args: ${renderType(tool.parameters, "  ")}): Promise<unknown>;`;
+}
+
+/** 给脚本用的工具清单（名字 + 说明）。 */
+export function toScriptTools(tools: readonly ToolLike[]): ScriptTool[] {
+  return tools.map((tool) => ({ name: tool.name, description: tool.description }));
+}
+
+/** 渲染脚本侧的声明：`declare const tools: {...}` 与全局辅助函数。 */
+export function renderDeclarations(tools: readonly ToolLike[]): string {
+  const members = tools.map((tool) => `  ${renderToolMember(tool)}`).join("\n");
+  return [
+    `declare const tools: {\n${members}\n};`,
+    "declare const ALL_TOOLS: Array<{ name: string; description?: string }>;",
+    "declare function text(value: unknown): void;",
+    "declare function image(value: unknown): void;",
+    "declare function exit(): void;",
+    "declare function store(key: string, value: unknown): void;",
+    "declare function load(key: string): unknown;",
+  ].join("\n");
+}

package/src/codemode/prelude.ts

@@ -0,0 +1,298 @@
+/**
+ * codemode 脚本侧的 prelude：在 QuickJS VM 里先于脚本求值，构建脚本能看到的全部
+ * 能力（`tools` / `ALL_TOOLS` / `text` / `image` / `exit` / `console` / `store` /
+ * `load`），并把宿主桥接封在闭包里——脚本拿不到 `bridge` 本身。
+ *
+ * 值与参数过桥时都是 JSON 文本，本侧负责 parse/stringify；异步调用用一个 pending
+ * 表把 id 映射到 promise，由宿主在结果到达时 settle。
+ *
+ * 求值结果是一个函数 `(bridge, toolsJson, storeJson) => { settle, run, stalled }`。
+ * `bridge(kind, a, b, c)`：
+ * - `"call"`（id, name, argsJson）
+ * - `"output"`（"text", text）/（"image", data, mimeType）
+ * - `"done"`（ok, valueJsonOrErrorJson, writesJson）
+ */
+
+/** `store()` 单个值的 JSON 上限（字符数）。 */
+export const MAX_STORE_VALUE_CHARS = 256 * 1024;
+/** 全部 store 值的 JSON 上限（字符数）。 */
+export const MAX_STORE_TOTAL_CHARS = 1024 * 1024;
+
+const IMAGE_HELPER_EXPECTS =
+  "image expects a non-empty image URL string, an object with image_url, or a raw MCP image block";
+
+export const PRELUDE_SOURCE = String.raw`(function (bridge, toolsJson, storeJson) {
+	"use strict";
+	const stringify = JSON.stringify;
+	const parse = JSON.parse;
+	const promiseThen = Promise.prototype.then;
+	const ErrorCtor = Error;
+	const TypeErrorCtor = TypeError;
+	const pending = new Map();
+	let nextId = 1;
+	let finished = false;
+	// exit() 用它解开脚本栈：成功结果已经报过了。
+	const EXIT = Object.freeze({});
+
+	function done(ok, payload, writes) {
+		if (finished) return;
+		finished = true;
+		bridge("done", ok, payload, writes);
+	}
+
+	function serialize(value) {
+		return value === undefined ? undefined : stringify(value);
+	}
+
+	// QuickJS 的 stack 只有帧，没有 "Name: message" 头；补上并去掉本 prelude 的帧，
+	// 读起来与 Node 的报错一致。
+	function errorText(error) {
+		const head = error.message ? error.name + ": " + error.message : String(error.name);
+		const frames =
+			typeof error.stack === "string"
+				? error.stack.split("\n").filter((line) => line.trim() && !line.includes("codemode-prelude.js"))
+				: [];
+		return [head, ...frames].join("\n");
+	}
+
+	function format(value) {
+		if (typeof value === "string") return value;
+		if (value instanceof ErrorCtor) return errorText(value);
+		try {
+			const json = stringify(value);
+			return json === undefined ? String(value) : json;
+		} catch {
+			return String(value);
+		}
+	}
+
+	function describeError(error) {
+		if (error instanceof ErrorCtor) {
+			return stringify({ name: error.name, message: error.message, stack: errorText(error) });
+		}
+		return stringify({ message: format(error) });
+	}
+
+	function caller(name) {
+		return (args) =>
+			new Promise((resolve, reject) => {
+				let json;
+				try {
+					json = serialize(args);
+				} catch (error) {
+					reject(error);
+					return;
+				}
+				const id = nextId++;
+				pending.set(id, { resolve, reject });
+				bridge("call", id, name, json);
+			});
+	}
+
+	const tools = Object.create(null);
+	const allTools = [];
+	for (const { name, jsName, description } of parse(toolsJson)) {
+		const fn = caller(name);
+		// 两个名字归一化成同一个标识符时，第一个赢
+		if (!(jsName in tools)) {
+			tools[jsName] = fn;
+			allTools.push(Object.freeze({ name: jsName, description }));
+		}
+		if (!(name in tools)) tools[name] = fn;
+	}
+	Object.freeze(tools);
+	Object.freeze(allTools);
+
+	// key -> JSON 文本；容量按 key 与 JSON 的字符数计
+	const stored = new Map(Object.entries(parse(storeJson)));
+	const writes = new Map();
+	let storedChars = 0;
+	for (const [key, json] of stored) storedChars += key.length + json.length;
+
+	function checkKey(name, key) {
+		if (typeof key !== "string") throw new TypeErrorCtor(name + "() key must be a string");
+	}
+
+	function store(key, value) {
+		checkKey("store", key);
+		const previous = stored.has(key) ? key.length + stored.get(key).length : 0;
+		if (value === undefined) {
+			stored.delete(key);
+			storedChars -= previous;
+			writes.set(key, undefined);
+			return;
+		}
+		let json;
+		try {
+			json = stringify(value);
+		} catch (error) {
+			throw new TypeErrorCtor("store(" + stringify(key) + ") value is not JSON-serializable: " + format(error));
+		}
+		if (json === undefined) {
+			throw new TypeErrorCtor("store(" + stringify(key) + ") value is not JSON-serializable");
+		}
+		if (json.length > ${MAX_STORE_VALUE_CHARS}) {
+			throw new RangeError("store(" + stringify(key) + ") value exceeds ${MAX_STORE_VALUE_CHARS} characters of JSON");
+		}
+		const next = storedChars - previous + key.length + json.length;
+		if (next > ${MAX_STORE_TOTAL_CHARS}) {
+			throw new RangeError("store is full: stored values would exceed ${MAX_STORE_TOTAL_CHARS} characters of JSON");
+		}
+		stored.set(key, json);
+		storedChars = next;
+		writes.set(key, json);
+	}
+
+	function load(key) {
+		checkKey("load", key);
+		const json = stored.get(key);
+		return json === undefined ? undefined : parse(json);
+	}
+
+	function serializeWrites() {
+		const entries = [];
+		for (const [key, json] of writes) entries.push(json === undefined ? [key] : [key, json]);
+		return stringify(entries);
+	}
+
+	Object.defineProperty(globalThis, "store", { value: store, enumerable: true });
+	Object.defineProperty(globalThis, "load", { value: load, enumerable: true });
+
+	// 原始值转字符串，其余 JSON 化
+	function outputText(value) {
+		if (value === undefined || value === null || (typeof value !== "object" && typeof value !== "function")) {
+			return String(value);
+		}
+		const json = stringify(value);
+		return json === undefined ? String(value) : json;
+	}
+
+	function text(value) {
+		let rendered;
+		try {
+			rendered = outputText(value);
+		} catch (error) {
+			throw new TypeErrorCtor(error instanceof ErrorCtor ? error.message : String(error));
+		}
+		if (!finished) bridge("output", "text", rendered);
+	}
+
+	function imageUrl(value) {
+		if (typeof value === "string") return value;
+		if (typeof value !== "object" || value === null || Array.isArray(value)) {
+			throw new TypeErrorCtor(${JSON.stringify(IMAGE_HELPER_EXPECTS)});
+		}
+		if (value.image_url !== undefined) {
+			if (typeof value.image_url !== "string") throw new TypeErrorCtor(${JSON.stringify(IMAGE_HELPER_EXPECTS)});
+			return value.image_url;
+		}
+		if (typeof value.type !== "string") throw new TypeErrorCtor(${JSON.stringify(IMAGE_HELPER_EXPECTS)});
+		if (value.type !== "image") {
+			throw new TypeErrorCtor('image only accepts MCP image blocks, got "' + value.type + '"');
+		}
+		if (typeof value.data !== "string" || value.data === "") throw new TypeErrorCtor("image expected MCP image data");
+		if (value.data.toLowerCase().startsWith("data:")) return value.data;
+		const mimeType = typeof value.mimeType === "string" && value.mimeType ? value.mimeType : "application/octet-stream";
+		return "data:" + mimeType + ";base64," + value.data;
+	}
+
+	function image(value) {
+		const url = imageUrl(value);
+		if (url === "") throw new TypeErrorCtor(${JSON.stringify(IMAGE_HELPER_EXPECTS)});
+		const colon = url.indexOf(":");
+		const scheme = colon === -1 ? "" : url.slice(0, colon).toLowerCase();
+		if (scheme === "http" || scheme === "https") {
+			throw new TypeErrorCtor("remote image URLs are not supported in tool outputs. Pass a base64 data URI instead");
+		}
+		const comma = url.indexOf(",");
+		const header = comma === -1 ? [] : url.slice(colon + 1, comma).split(";");
+		if (scheme !== "data" || comma === -1 || header.slice(1).every((part) => part.toLowerCase() !== "base64")) {
+			throw new TypeErrorCtor("invalid image output. Pass a base64 data URI instead");
+		}
+		if (!finished) bridge("output", "image", url.slice(comma + 1), header[0] || "application/octet-stream");
+	}
+
+	function exit() {
+		let writesJson;
+		try {
+			writesJson = serializeWrites();
+		} catch (error) {
+			done(false, describeError(error));
+			throw EXIT;
+		}
+		done(true, undefined, writesJson);
+		throw EXIT;
+	}
+
+	const console = {};
+	for (const level of ["log", "info", "warn", "error", "debug"]) {
+		console[level] = (...args) => {
+			if (!finished) bridge("output", "text", args.map(format).join(" "));
+		};
+	}
+	Object.freeze(console);
+
+	Object.defineProperty(globalThis, "tools", { value: tools, enumerable: true });
+	Object.defineProperty(globalThis, "ALL_TOOLS", { value: allTools, enumerable: true });
+	Object.defineProperty(globalThis, "console", { value: console, enumerable: true });
+	Object.defineProperty(globalThis, "text", { value: text, enumerable: true });
+	Object.defineProperty(globalThis, "image", { value: image, enumerable: true });
+	Object.defineProperty(globalThis, "exit", { value: exit, enumerable: true });
+
+	return {
+		settle(id, ok, payload) {
+			const entry = pending.get(id);
+			if (!entry) return;
+			pending.delete(id);
+			if (!ok) {
+				entry.reject(new ErrorCtor(payload));
+				return;
+			}
+			let value;
+			try {
+				value = payload === undefined ? undefined : parse(payload);
+			} catch (error) {
+				entry.reject(error);
+				return;
+			}
+			entry.resolve(value);
+		},
+		run(fn) {
+			let promise;
+			try {
+				promise = fn(tools, console);
+			} catch (error) {
+				done(false, describeError(error));
+				return;
+			}
+			promiseThen.call(
+				promise,
+				(value) => {
+					let json;
+					try {
+						json = serialize(value);
+					} catch (error) {
+						done(false, describeError(error));
+						return;
+					}
+					done(true, json, serializeWrites());
+				},
+				(error) => {
+					done(false, describeError(error));
+				},
+			);
+		},
+		stalled() {
+			if (finished || pending.size > 0) return false;
+			done(
+				false,
+				stringify({
+					name: "Error",
+					message:
+						"The script is waiting on a promise that can never settle: no tool call is pending, and timers do not exist here.",
+				}),
+			);
+			return true;
+		},
+	};
+})`;

package/src/codemode/protocol.ts

@@ -0,0 +1,156 @@
+/**
+ * codemode 主线程 ↔ worker 线程的消息类型（结构化克隆，不是字符串协议）。
+ *
+ * 每次执行起一个新的 worker：主线程把注册时编好的 wasm 模块连同脚本、可调用工具、
+ * 初始 store 一起发过去，worker 里建 QuickJS VM 跑脚本，脚本的嵌套调用与输出回传，
+ * 主线程执行工具后把结果发回去。超时/中止由主线程 `worker.terminate()` 负责，因此
+ * 不需要取消消息。
+ *
+ * worker 边界两侧都做 typebox 校验：worker 里跑的是模型写的代码，回传的消息同样
+ * 当外部输入对待。
+ */
+
+import { type TSchema, Type } from "typebox";
+import { Value } from "typebox/value";
+
+// ── 消息 schema ──────────────────────────────────────────────────────────────
+
+const outputItemSchema = Type.Union([
+  Type.Object({ type: Type.Literal("text"), text: Type.String() }),
+  Type.Object({ type: Type.Literal("image"), data: Type.String(), mimeType: Type.String() }),
+]);
+
+const toolDeclSchema = Type.Object({
+  name: Type.String(),
+  description: Type.Optional(Type.String()),
+});
+
+const startSchema = Type.Object({
+  t: Type.Literal("start"),
+  code: Type.String(),
+  tools: Type.Array(toolDeclSchema),
+  store: Type.Record(Type.String(), Type.Unknown()),
+});
+
+const resultSchema = Type.Union([
+  Type.Object({
+    t: Type.Literal("result"),
+    id: Type.Number(),
+    ok: Type.Literal(true),
+    value: Type.Unknown(),
+  }),
+  Type.Object({
+    t: Type.Literal("result"),
+    id: Type.Number(),
+    ok: Type.Literal(false),
+    error: Type.String(),
+  }),
+]);
+
+const callSchema = Type.Object({
+  t: Type.Literal("call"),
+  id: Type.Number(),
+  name: Type.String(),
+  args: Type.Unknown(),
+});
+
+const outputSchema = Type.Object({
+  t: Type.Literal("output"),
+  items: Type.Array(outputItemSchema),
+});
+
+const scriptErrorSchema = Type.Object({
+  kind: Type.Union([
+    Type.Literal("script"),
+    Type.Literal("timeout"),
+    Type.Literal("aborted"),
+    Type.Literal("sandbox"),
+  ]),
+  name: Type.Optional(Type.String()),
+  message: Type.String(),
+  stack: Type.Optional(Type.String()),
+});
+
+const storeWritesSchema = Type.Object({
+  set: Type.Record(Type.String(), Type.Unknown()),
+  delete: Type.Array(Type.String()),
+});
+
+const doneSchema = Type.Union([
+  Type.Object({
+    t: Type.Literal("done"),
+    ok: Type.Literal(true),
+    value: Type.Unknown(),
+    writes: storeWritesSchema,
+  }),
+  Type.Object({
+    t: Type.Literal("done"),
+    ok: Type.Literal(false),
+    error: scriptErrorSchema,
+    writes: storeWritesSchema,
+  }),
+]);
+
+const hostMessageSchema = Type.Union([startSchema, resultSchema]);
+const workerMessageSchema = Type.Union([callSchema, outputSchema, doneSchema]);
+
+/** worker 启动数据：注册时编译好的 wasm 模块（结构化克隆可以带它跨线程）。 */
+export interface WorkerBootstrap {
+  wasm: object;
+}
+
+// ── 类型 ─────────────────────────────────────────────────────────────────────
+
+export type CodemodeOutputItem =
+  { type: "text"; text: string } | { type: "image"; data: string; mimeType: string };
+
+export type ScriptErrorKind = "script" | "timeout" | "aborted" | "sandbox";
+
+export interface ScriptError {
+  kind: ScriptErrorKind;
+  name?: string;
+  message: string;
+  stack?: string;
+}
+
+/** 脚本侧的 store 写入：`set` 是覆写的键值，`delete` 是被删除的键。 */
+export interface StoreWrites {
+  set: Record<string, unknown>;
+  delete: string[];
+}
+
+export interface ScriptTool {
+  name: string;
+  description?: string;
+}
+
+export type HostMessage =
+  | { t: "start"; code: string; tools: ScriptTool[]; store: Record<string, unknown> }
+  | { t: "result"; id: number; ok: true; value: unknown }
+  | { t: "result"; id: number; ok: false; error: string };
+
+export type WorkerMessage =
+  | { t: "call"; id: number; name: string; args: unknown }
+  | { t: "output"; items: CodemodeOutputItem[] }
+  | { t: "done"; ok: true; value: unknown; writes: StoreWrites }
+  | { t: "done"; ok: false; error: ScriptError; writes: StoreWrites };
+
+export type DecodeResult<T> = { ok: true; frame: T } | { ok: false; error: string };
+
+function decode<T>(schema: TSchema, value: unknown): DecodeResult<T> {
+  if (!Value.Check(schema, value)) {
+    const preview = JSON.stringify(value).slice(0, 200);
+    return { ok: false, error: `unexpected message shape: ${preview}` };
+  }
+  return { ok: true, frame: value as T };
+}
+
+/** 校验主线程发给 worker 的消息。 */
+export function decodeHostMessage(value: unknown): DecodeResult<HostMessage> {
+  return decode<HostMessage>(hostMessageSchema, value);
+}
+
+/** 校验 worker 发回主线程的消息。 */
+export function decodeWorkerMessage(value: unknown): DecodeResult<WorkerMessage> {
+  return decode<WorkerMessage>(workerMessageSchema, value);
+}