@mearl/client 2.22.0 → 2.22.1

package/README.md

@@ -150,6 +150,10 @@ stdout 在管道或重定向时默认输出紧凑 JSON，在交互终端默认
 需要同时读取全文时显式传 `includeBody:true`。省略正文时不返回 `postData` / `responseBody` 字段；
 未指定字段时默认返回正文。
 
+`send_request` 默认携带所选浏览器中匹配完整目标 URL 的未分区 Cookie，保留不同路径下的同名 Cookie；不额外拼入父站点的 host-only Cookie，也不猜测页面的 Cookie 分区。需要页面分区、页面签名或完整页面身份时，使用目标页面中的 `page_eval` 请求。
+响应中的 `Set-Cookie` 会更新原浏览器，后续调用可以使用刷新后的登录态；`withCookies:false` 同时关闭自动携带与响应回写。扩展由 Chrome 处理响应 Cookie；CDP 的 Node 请求在返回前通过原页面的浏览器连接回写，支持 HttpOnly、默认路径、过期时间和删除。CDP 响应存在 `Set-Cookie` 时附带 `cookieSync: { updatedCount, rejectedCount, failedCount }`，不返回 Cookie 值；无法确定分区的 Partitioned 响应 Cookie 计入拒绝数。同步失败不撤销已完成的 HTTP 操作，应检查状态而非直接重发业务请求。MTop 普通请求及流式请求使用相同的响应刷新机制。
+扩展的临时凭据注入仅匹配原始完整请求 URL，重定向由 Chrome 按新 URL 选择 Cookie。CDP 的 Node 请求（含 MTop 流式请求）不自动跟随重定向，避免将原 URL 的 Cookie 或签名传到其他地址。
+
 Mearl 默认聚合当前机器和已配置 cloud-server 下的浏览器，并通过 `browser_list` 返回的全局
 `browserId` 自动路由。以下覆盖参数仅在限定宿主或连接、传输排障时使用，因此不出现在默认 help：
 
@@ -250,7 +254,7 @@ const result = await invokePlugin(
 
 MCP Server 通过固定工具 `plugin_invoke` 接受同样的 `plugin`、`command` 和 `input`，不会把插件子命令动态扩展成 MCP 工具。SDK 与 MCP 不接受任意入口路径；调用尚未注册的 `buc`、`authx` 或 `tdbank` 时，会通过匹配当前 client 版本的 setup 自动安装并重试一次。其他未注册名称返回 `PLUGIN_NOT_REGISTERED`。
 
-长命令使用本机持久任务服务。服务按注册目录隔离并自动启动，CLI、SDK、MCP 与工具箱共享任务记录；调用方退出不取消执行。服务重启后将未完成任务标记为 `interrupted`，不自动重放。后台任务固定接受时的源码快照、工作目录与环境；静态第三方 JS 依赖需要预先打包进 Skill，状态文件放在源码目录之外。
+长命令使用本机持久任务服务。服务按注册目录隔离并自动启动，CLI、SDK、MCP 与工具箱共享任务记录；调用方退出不取消执行。服务重启后将未完成任务标记为 `interrupted`，不自动重放。后台任务固定接受时的源码快照、工作目录与环境；第三方 JS 依赖应预先打包进 Skill，状态文件放在源码目录之外。快照只固定源码和相对资源，不预解析 JS 依赖；缺失依赖和语法错误由执行器加载代码时报告。
 
 ```ts
 import { PluginTaskClient } from '@mearl/client';
@@ -270,6 +274,8 @@ try {
 
 `wait` 超时或其 signal 中止只结束等待；`cancel(taskId)` 才取消执行。浏览器任务需显式传 `browser`，名称会在接受前解析为固定 ID。`get/list` 返回任务快照与结果引用，`list` 返回有界分页及 `nextCursor`；`events` 返回游标、缺口标记和最新快照，`subscribe` 封装长轮询。`result(taskId)` 分块读取并校验完整业务结果，最大 64 MiB；终态记录和结果保留 7 天。
 
+插件宿主握手与 `tasks.status()` 返回 `version/buildId`，构建标识用于定位运行代码，兼容性由握手中的协议版本决定。协议相同时，即使版本、构建标识不同或旧宿主未提供标识，任务、模型、页面和状态请求仍可继续使用现有服务，不中断活动任务或页面实例。需要切换到新构建时，确认没有活动任务及页面操作后调用 `tasks.stopHost()`，下次业务调用将启动当前构建；重新注册插件不会重启宿主。本地修改客户端或宿主代码后执行根目录 `pnpm build`，同步生成指纹并构建双方产物；仅运行 `tsc --watch` 不会更新构建指纹。
+
 任务能力由 SDK `PluginTaskClient` 与工具箱 `host.task.*` 使用。对外命令由具体插件按业务需要提供，CLI 使用 `mearl <plugin> <command>`，MCP 使用 `plugin_invoke`。任务、模型、状态、页面实例和宿主诊断不单独暴露为全局 CLI/MCP 命令。仅注册工具箱内部命令的插件不会列入 CLI 插件列表；直接运行其名称会提示工具的打开位置。工具页可用 `window.mearl.waitTask(taskId)`、`readTaskResult(taskId)`、`listTasks()`，范围限定为所属插件的工具箱任务。
 
 `tasks.diagnose({ taskId?, plugin?, instanceId?, includeErrorMessages?, includeLocalPaths? })` 读取当前调用范围内的有界诊断报告。默认不包含业务输入、提示词、进度正文、检查点数据、结果正文、完整 URL、环境变量和凭证，也省略错误消息及本地路径；后两项可显式选择包含。报告的 coverage 和历史 gap 表示采集范围及保留历史限制。
@@ -284,7 +290,15 @@ try {
 
 插件可选导出 `toolbox`，注册后会出现在扩展 Popup 的工具箱中。页面资源放在 Skill 目录内，注册时由
 Mearl 将入口 HTML 引用的本地 CSS、JavaScript 和图片内联为不可变页面包，不需要启动 HTTP 服务，
-也不要求普通 HTML/CSS/JS 页面自行构建：
+也不要求普通 HTML/CSS/JS 页面自行构建。
+
+右键工具箱中的工具可单独禁用或启用对应 Skill；禁用状态显示在标题右侧，工具页面和命令仍可使用。禁用将该目录的
+`SKILL.md` 重命名为 `SKILL.md.mearl-disabled`，启用时恢复，作用于共享此目录的所有 Agent；
+软链接安装会作用于源目录。已有会话可能仍保留已载入的 Skill，需要重启 Agent 或新建会话。
+工具箱内更新和重新安装会保留禁用状态；外部安装器的更新不受此状态管理，若出现两份清单，需先处理冲突。
+独立复制安装的同名 Skill 需分别禁用。没有 Skill 清单的普通插件不显示此开关。
+
+工具箱元数据示例：
 
 ```javascript
 export const toolbox = {
@@ -462,7 +476,7 @@ ISC
 
 ### 插件页面实例
 
-`PluginPageClient` 通过本地插件服务管理 attach/get/list/send/detach/events/activation。插件导出独立 `pageRuntime` 声明并用 `app.page()` 调用。扩展与纯 CDP 共用实例、事件、激活和文档运行时；实例绑定 documentId，同插件同文档的所有入口共享初始化，导航后旧实例失效，启用的激活规则负责重建。`frame` 接受 `main`、`business` 或 `page_frames` 返回的 frame ID（扩展为数字，CDP 为字符串）。外部 Provider 仍须明确声明 `page_runtime` 能力。
+`PluginPageClient` 通过本地插件服务管理 attach/get/list/send/detach/events/activation。插件导出独立 `pageRuntime` 声明并用 `app.page()` 调用。宿主用 Node 内置编译器检查 code 的表达式语法，不执行代码；代码必须在网页中求值得到自包含函数，非函数或外部引用错误在页面运行时报告。扩展与纯 CDP 共用实例、事件、激活和文档运行时；实例绑定 documentId，同插件同文档的所有入口共享初始化，导航后旧实例失效，启用的激活规则负责重建。`frame` 接受 `main`、`business` 或 `page_frames` 返回的 frame ID（扩展为数字，CDP 为字符串）。外部 Provider 仍须明确声明 `page_runtime` 能力。
 
 显式手动 `attach` 复用自动激活的实例时，实例转为手动归属，初始化与在途任务继续复用；随后收窄自动激活范围不会清理该实例。
 
@@ -476,7 +490,7 @@ try {
 } finally { pages.disconnect(); }
 ```
 
-后台事件声明 schema 和串行、latest 合并或有限并发策略，处理器用 `app.runtimeCommand()` 注册并通过 `context.page` 访问固定文档。文档绑定任务可用 `app.page('activation')` 只读查询本插件激活规则，不允许设置或关闭规则。页面消息/结果各上限 24 MiB，宿主自动分块并校验；事件负载上限 32 KiB。工具箱使用 `host.page.*`，UI 订阅实例历史与后台执行独立。完整契约见 [插件宿主能力](../native-host/README.md#页面运行时和事件)。
+后台事件声明 schema 和串行、latest 合并或有限并发策略；schema 是格式元数据，事件处理器负责验证负载。处理器用 `app.runtimeCommand()` 注册并通过 `context.page` 访问固定文档。文档绑定任务可用 `app.page('activation')` 只读查询本插件激活规则，不允许设置或关闭规则。页面消息/结果各上限 24 MiB，宿主自动分块并校验；事件负载上限 32 KiB。工具箱使用 `host.page.*`，UI 订阅实例历史与后台执行独立。完整契约见 [插件宿主能力](../native-host/README.md#页面运行时和事件)。
 
 Python 入口同样导出 `pageRuntime` 字典，其中 `code` 仍是运行于网页中的 JavaScript 函数字符串；后台初始化与事件处理器通过 `app.runtimeCommand(...)` 或其装饰器注册。`app.page(operation, payload)`、`context.page.send(message)` 和 `context.page.get()` 都是同步调用，后两者仅在绑定页面实例的处理器中可用。JS 和 Python 的 `context.page.send(message, {timeoutSec: 120})` 可指定单次响应超时（大于 0 且最多 300 秒，Python 使用字典）；`app.page("send", {instanceId, message, timeoutSec})` 和 SDK `pages.send(plugin, instanceId, message, {timeoutSec})` 同样支持。该设置不改变其他请求，任务取消和文档解绑仍立即中断执行，传输失败也会取消对应网页请求。runtime-only 命令不出现在公开命令帮助中，也不能由 CLI 或工具箱直接执行；声明在页面事件中的普通 `app.command` 仍保留公开调用能力。
 
@@ -496,7 +510,7 @@ try {
 } finally { models.disconnect(); }
 ```
 
-`start` 返回持久 taskId；`run` 的 signal 取消模型执行并等待清理。`app.model(request, { onProgress })` / `context.model(request, { onProgress })` 可订阅当前这一次调用的 `model.delta`，并发调用的回调互相隔离；Python 使用 `context.model(request, on_progress=callback)`。增量 `data` 含 `delta/index/partial`，可用时带 `itemId/phase`；按消息隔离、跳过 commentary，序号缺失时回退到最终结果。增量只供临时展示，最终结果来自成功 turn 的完整消息并经过宿主 schema 校验；临时显示必须在失败时撤回，不能直接作为缓存或业务成功依据。模型目录与执行通过 `PluginModelClient` 或插件上下文使用。工具页使用 `host.model.capabilities/list/start` 和 `waitTask`。
+`start` 返回持久 taskId；`run` 的 signal 取消模型执行并等待清理。`app.model(request, { onProgress })` / `context.model(request, { onProgress })` 可订阅当前这一次调用的 `model.delta`，并发调用的回调互相隔离；Python 使用 `context.model(request, on_progress=callback)`。增量 `data` 含 `delta/index/partial`，可用时带 `itemId/phase`；按消息隔离、跳过 commentary，序号缺失时回退到最终结果。增量只供临时展示，最终结果来自成功 turn 的完整消息；outputSchema 透传模型 Provider，宿主解析 JSON，插件负责验证结果结构与业务约束；临时显示必须在失败时撤回，不能直接作为缓存或业务成功依据。模型目录与执行通过 `PluginModelClient` 或插件上下文使用。工具页使用 `host.model.capabilities/list/start` 和 `waitTask`。
 
 插件入口声明状态集合，然后从命令上下文访问：
 
@@ -512,11 +526,11 @@ export default app => app.command('save', async (input, context) => {
 });
 ```
 
-SDK `PluginStateClient.get/getMany/list/transact` 与工具箱 `host.state.*` 共享集合。每次写入需 CAS，冲突后重新读取、合并再重试；`schemaVersion` 升级用显式迁移事务。浏览器会话/实例可声明 `cache` 或 `memory`，页面身份由宿主验证。`memory` 只保存在插件执行宿主进程中，支持同样的 CAS、schema、TTL 与分块值限制；刷新文档时保留浏览器会话范围，浏览器会话变化后隔离，执行宿主重启时清空。内存状态全宿主合计最多 128 MiB / 512 个集合命名空间，按需占用；单集合 `maxBytes` 最大 128 MiB，实例结束释放其内存。容量、TTL 和完整契约见[插件宿主能力](../native-host/README.md#状态和激活)。二进制资产继续使用文件或资源通道。
+SDK `PluginStateClient.get/getMany/list/transact` 与工具箱 `host.state.*` 共享集合。schema 保留为格式描述和版本身份，写入与迁移的数据由插件自行验证；宿主检查 JSON、大小、版本和事务约束。每次写入需 CAS，冲突后重新读取、合并再重试；`schemaVersion` 升级用显式迁移事务。浏览器会话/实例可声明 `cache` 或 `memory`，页面身份由宿主验证。`memory` 只保存在插件执行宿主进程中，支持同样的 CAS、格式版本、TTL 与分块值限制；刷新文档时保留浏览器会话范围，浏览器会话变化后隔离，执行宿主重启时清空。内存状态全宿主合计最多 128 MiB / 512 个集合命名空间，按需占用；单集合 `maxBytes` 最大 128 MiB，实例结束释放其内存。容量、TTL 和完整契约见[插件宿主能力](../native-host/README.md#状态和激活)。二进制资产继续使用文件或资源通道。
 
 ### 显式任务恢复
 
-插件声明 `taskRecovery`（每个命令的 checkpointVersion/schema）并注册 `app.recoveryCommand(command, handler)`，命令通过 `context.checkpoint(data, expectedSequence)` 保存最多 64 KiB 的恢复依据。检查点数据、版本、宿主 schemaHash、序号和事件与任务记录原子写入；写入必须 CAS。
+插件声明 `taskRecovery`（每个命令的 checkpointVersion/schema）并注册 `app.recoveryCommand(command, handler)`，命令通过 `context.checkpoint(data, expectedSequence)` 保存最多 64 KiB 的恢复依据。检查点数据、版本、宿主 schemaHash、序号和事件与任务记录原子写入；写入必须 CAS。schema 用于声明身份和格式兼容比较，检查点及迁移数据的结构由插件验证。
 
 `tasks.checkpoint(taskId)` 读取检查点；`tasks.resume(taskId, { environment?, revision? })` 为终态根命令建立新 attempt，保持旧任务终态，固定原安装、源码快照、输入、目录和路由。默认提交调用进程的新环境，旧环境不持久化。恢复入口读取 `context.recovery`，先核对外部操作状态；宿主不重放原 handler，也不保证外部提交与检查点原子。
 

package/dist/commands.d.ts

@@ -297,7 +297,7 @@ export declare const COMMANDS: readonly [{
         readonly type: "string";
         readonly description: "规则说明";
     }];
-    readonly notes: readonly ["扩展模式规则持久化；CDP 仅支持会话级 modifyHeaders 请求头 set，不支持响应头、initiatorDomains 或其他动作。Provider 是否支持以其能力声明为准。"];
+    readonly notes: readonly ["扩展模式规则持久化；CDP 仅支持会话级 modifyHeaders 请求头 set，不支持响应头、initiatorDomains 或其他动作。Provider 是否支持以其能力声明为准。", "扩展模式会检查规则请求 URL 和显式来源域名的访问权限；缺失时仍保存规则，返回 warnings 和 missingOrigins，不自动弹窗。可在请求规则页面授权，或按提示调用 request_domain_permission。复杂 URL 表达式无法完整推断域名时会提示手动检查。"];
     readonly examples: ["set_rule --payload '{\"actionType\":\"block\",\"filter\":\"^https://example\\\\.com/ads/.*\"}'", "set_rule --payload '{\"ruleId\":42,\"enabled\":false}'"];
 }, {
     readonly name: "get_rules";
@@ -1093,7 +1093,7 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "mtopEnv";
         readonly type: "\"default\" | \"prod\" | \"pre\"";
-        readonly description: "可选 MTop 页面接口环境；default 关闭环境改写，省略时保持当前设置。扩展模式全局生效，CDP 模式仅作用于目标 tab";
+        readonly description: "可选 MTop 页面接口环境；default 关闭环境改写，省略时保持当前设置。仅作用于目标 tab";
     }, {
         readonly name: "emulation";
         readonly type: "object";
@@ -1211,7 +1211,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "需要授权的域名，如 example.com";
     }];
-    readonly notes: readonly ["domain 使用纯主机名，不传 URL。仅在非 BUC send_request 报域权限缺失时申请，BUC 不使用浏览器域权限。", "弹窗等待用户选择，90 秒超时或关闭按拒绝处理；granted=true 后才重试原请求。"];
+    readonly notes: readonly ["domain 使用纯主机名，不传 URL。在非 BUC send_request 报域权限缺失，或 set_rule 提示缺少域名权限时申请；BUC 不使用浏览器域权限。", "弹窗等待用户选择，90 秒超时或关闭按拒绝处理；granted=true 后才重试原请求。"];
     readonly result: readonly ["返回 granted、domain，授权成功时包含 origin。"];
     readonly examples: ["request_domain_permission --payload '{\"domain\":\"example.com\"}'"];
 }, {

package/dist/commands.js

@@ -298,6 +298,7 @@ export const COMMANDS = [
         ],
         notes: [
             '扩展模式规则持久化；CDP 仅支持会话级 modifyHeaders 请求头 set，不支持响应头、initiatorDomains 或其他动作。Provider 是否支持以其能力声明为准。',
+            '扩展模式会检查规则请求 URL 和显式来源域名的访问权限；缺失时仍保存规则，返回 warnings 和 missingOrigins，不自动弹窗。可在请求规则页面授权，或按提示调用 request_domain_permission。复杂 URL 表达式无法完整推断域名时会提示手动检查。',
         ],
         examples: [
             `set_rule --payload '{"actionType":"block","filter":"^https://example\\\\.com/ads/.*"}'`,
@@ -1200,7 +1201,7 @@ export const COMMANDS = [
             {
                 name: 'mtopEnv',
                 type: '"default" | "prod" | "pre"',
-                description: '可选 MTop 页面接口环境；default 关闭环境改写，省略时保持当前设置。扩展模式全局生效，CDP 模式仅作用于目标 tab',
+                description: '可选 MTop 页面接口环境；default 关闭环境改写，省略时保持当前设置。仅作用于目标 tab',
             },
             {
                 name: 'emulation',
@@ -1352,7 +1353,7 @@ export const COMMANDS = [
             },
         ],
         notes: [
-            'domain 使用纯主机名，不传 URL。仅在非 BUC send_request 报域权限缺失时申请，BUC 不使用浏览器域权限。',
+            'domain 使用纯主机名，不传 URL。在非 BUC send_request 报域权限缺失，或 set_rule 提示缺少域名权限时申请；BUC 不使用浏览器域权限。',
             '弹窗等待用户选择，90 秒超时或关闭按拒绝处理；granted=true 后才重试原请求。',
         ],
         result: ['返回 granted、domain，授权成功时包含 origin。'],

package/dist/generated/browser-action-protocol.d.ts

@@ -534,7 +534,7 @@ export interface SetAppProfileParams {
     bridgeConfig?: AppBridgeConfig;
     /**
      * 可选 MTop 接口环境。default 关闭环境改写；省略时保持当前设置。
-     * 扩展模式与插件设置页共享并全局生效；CDP 模式仅作用于目标 tab。
+     * 仅作用于目标 tab，扩展模式与该 tab 的快捷设置共享。
      */
     mtopEnv?: MtopEnvironment;
     /**

package/dist/generated/plugin-host-build.d.ts

@@ -0,0 +1 @@
+export declare const PLUGIN_HOST_BUILD_ID = "1d85713299314f3ff82faecc749a025177411fdedd16949cee34e6712b93e1ef";

package/dist/generated/plugin-host-build.js

@@ -0,0 +1,2 @@
+// Generated by scripts/generate-plugin-host-build.mjs.
+export const PLUGIN_HOST_BUILD_ID = '1d85713299314f3ff82faecc749a025177411fdedd16949cee34e6712b93e1ef';

package/dist/plugin.d.ts

@@ -1 +1,2 @@
 export * from './plugins/sdk/plugin.js';
+export * from './plugins/skillManifest.js';

package/dist/plugin.js

@@ -1 +1,2 @@
 export * from './plugins/sdk/plugin.js';
+export * from './plugins/skillManifest.js';

package/dist/plugins/clients/pluginHostConnection.d.ts

@@ -16,6 +16,8 @@ export interface PluginHostClientOptions extends PluginHostConnectionOptions {
 }
 export interface HostStatus {
     protocolVersion: number;
+    version?: string;
+    buildId?: string;
     host: PluginExecutionHost;
     pid: number;
 }

package/dist/plugins/clients/pluginHostConnection.js

@@ -243,7 +243,9 @@ export class PluginHostConnection {
                     this.connection = undefined;
             });
         }
-        return (await this.connection).request(method, input, timeoutMs);
+        const connection = await this.connection;
+        // The handshake protocol defines compatibility; build identity is diagnostic metadata.
+        return connection.request(method, input, timeoutMs);
     }
     disconnect() {
         this.generation++;

package/dist/plugins/pluginRegistry.d.ts

@@ -1,7 +1,7 @@
 import { type AppProfileContribution } from '../generated/app-profile-definition.js';
 export declare class PluginError extends Error {
     readonly code: string;
-    constructor(code: string, message: string);
+    constructor(code: string, message: string, options?: ErrorOptions);
 }
 export interface PluginToolboxSandboxPage {
     type: 'sandbox';

package/dist/plugins/pluginRegistry.js

@@ -17,8 +17,8 @@ const RESERVED_NAMES = new Set([
 ]);
 export class PluginError extends Error {
     code;
-    constructor(code, message) {
-        super(`${code}: ${message}`);
+    constructor(code, message, options) {
+        super(`${code}: ${message}`, options);
         this.code = code;
     }
 }
@@ -405,8 +405,15 @@ export function findPluginRegistration(name) {
             ...(source ? { source } : {}),
         };
     }
-    catch {
-        throw new PluginError('PLUGIN_REGISTRY_INVALID', `无效的插件记录: ${file}`);
+    catch (cause) {
+        const reason = cause instanceof SyntaxError
+            ? 'JSON 格式错误'
+            : cause instanceof Error
+                ? cause.message
+                : '未知校验错误';
+        throw new PluginError('PLUGIN_REGISTRY_INVALID', `无效的插件记录: ${file} (${reason})`, {
+            cause,
+        });
     }
 }
 export function readPluginPageBundleChunk(name, hash, index) {

package/dist/plugins/runtime/pluginHostServer.js

@@ -1,3 +1,5 @@
+import { CLIENT_VERSION } from '../../runtimePaths.js';
+import { PLUGIN_HOST_BUILD_ID } from '../../generated/plugin-host-build.js';
 import { randomUUID } from 'node:crypto';
 import { createServer } from 'node:net';
 import { chmodSync, rmSync } from 'node:fs';
@@ -17,6 +19,8 @@ export async function startPluginHostServer(configuration = {}) {
     const owner = {
         pid: process.pid,
         protocolVersion: PLUGIN_TASK_PROTOCOL_VERSION,
+        version: CLIENT_VERSION,
+        buildId: PLUGIN_HOST_BUILD_ID,
         processIdentity: processIdentity(process.pid),
     };
     if (!claimRecord(paths.lease, owner))
@@ -103,6 +107,8 @@ export async function startPluginHostServer(configuration = {}) {
                 };
                 return {
                     protocolVersion: PLUGIN_TASK_PROTOCOL_VERSION,
+                    version: CLIENT_VERSION,
+                    buildId: PLUGIN_HOST_BUILD_ID,
                     host: manager.host,
                     pid: process.pid,
                 };
@@ -112,6 +118,8 @@ export async function startPluginHostServer(configuration = {}) {
             if (method === 'status')
                 return {
                     protocolVersion: PLUGIN_TASK_PROTOCOL_VERSION,
+                    version: CLIENT_VERSION,
+                    buildId: PLUGIN_HOST_BUILD_ID,
                     host: manager.host,
                     pid: process.pid,
                 };

package/dist/plugins/runtime/pluginPageManager.js

@@ -5,7 +5,6 @@ import { readFileSync, statSync } from 'node:fs';
 import { isAbsolute, join } from 'node:path';
 import { capturePluginRevision } from './pluginRevision.js';
 import { findPluginRegistration } from '../sdk/plugin.js';
-import { compilePluginPageSchema } from '../sdk/pluginPageDefinition.js';
 import { UnifiedClient, decodeBrowserTarget } from '../../unified.js';
 import { pluginHostPaths } from './pluginHostPaths.js';
 import { serializePluginExecutionError, pluginExecutionError } from './pluginExecutorProtocol.js';
@@ -726,9 +725,6 @@ export class PluginPageManager {
         const binding = record.runtime.events?.[name];
         if (!binding || Buffer.byteLength(JSON.stringify(input.payload ?? null)) > 32 * 1024)
             throw new Error('Page event is not declared or exceeds 32 KiB');
-        const validate = compilePluginPageSchema(binding.schema);
-        if (!validate(input.payload))
-            throw failure('PLUGIN_PAGE_EVENT_INVALID', 'Page event payload does not match its schema');
         const waiting = record.deliveries.filter(item => item.name === name && item.state === 'queued');
         if (binding.policy === 'latest') {
             for (const previous of waiting) {

package/dist/plugins/runtime/pluginRevision.js

@@ -2,12 +2,10 @@ import { createHash, randomUUID } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { claimRecord, readRecord, writeRecord } from '@mearl/daemon-core';
-import { isBuiltin } from 'node:module';
-import { parse } from 'acorn';
 import { pluginHostPaths } from './pluginHostPaths.js';
+import { skillManifestPath } from '../skillManifest.js';
 import { findPluginRegistration, PluginError } from '../pluginRegistry.js';
 const MAX_REVISION_BYTES = 64 * 1024 * 1024;
-const validatedSources = new Set();
 function within(root, file) {
     const path = relative(root, file);
     return path === '' || (!path.startsWith(`..${sep}`) && path !== '..' && !isAbsolute(path));
@@ -15,7 +13,7 @@ function within(root, file) {
 function sourceRoot(entry) {
     let candidate = dirname(entry);
     for (let depth = 0; depth < 6; depth++) {
-        if (existsSync(join(candidate, 'SKILL.md')))
+        if (skillManifestPath(candidate))
             return candidate;
         const parent = dirname(candidate);
         if (parent === candidate)
@@ -67,48 +65,6 @@ function readSources(root) {
     visit(root, new Set());
     return files;
 }
-function validateDependencies(files) {
-    const paths = new Set(files.map(file => file.path));
-    for (const file of files) {
-        if (!/\.[cm]?js$/.test(file.path))
-            continue;
-        const tree = parse(file.bytes.toString('utf8'), {
-            ecmaVersion: 'latest',
-            sourceType: 'module',
-            allowReturnOutsideFunction: true,
-        });
-        const check = (specifier) => {
-            if (typeof specifier !== 'string' || isBuiltin(specifier))
-                return;
-            if (!specifier.startsWith('./') && !specifier.startsWith('../'))
-                throw new PluginError('PLUGIN_SOURCE_NOT_SELF_CONTAINED', `后台任务需要自包含 Skill，请先打包依赖: ${file.path}: ${specifier}`);
-            const local = resolve('/source', dirname(file.path), specifier);
-            const normalized = relative('/source', local).split(sep).join('/');
-            if (!within('/source', local) ||
-                ![normalized, `${normalized}.js`, `${normalized}.json`, `${normalized}/index.js`].some(path => paths.has(path)))
-                throw new PluginError('PLUGIN_SOURCE_NOT_SELF_CONTAINED', `依赖不在 Skill 快照中: ${file.path}: ${specifier}`);
-        };
-        const visit = (node) => {
-            if (!node || typeof node !== 'object')
-                return;
-            if (['ImportDeclaration', 'ExportNamedDeclaration', 'ExportAllDeclaration'].includes(node.type))
-                check(node.source?.value);
-            if (node.type === 'ImportExpression')
-                check(node.source?.value);
-            if (node.type === 'CallExpression' &&
-                node.callee?.type === 'Identifier' &&
-                node.callee.name === 'require')
-                check(node.arguments[0]?.value);
-            for (const value of Object.values(node)) {
-                if (Array.isArray(value))
-                    value.forEach(visit);
-                else if (value && typeof value === 'object')
-                    visit(value);
-            }
-        };
-        visit(tree);
-    }
-}
 function fingerprint(files, entry) {
     return createHash('sha256')
         .update(JSON.stringify({ entry, files: files.map(file => [file.path, file.hash, file.executable]) }))
@@ -138,12 +94,6 @@ export function capturePluginRevision(plugin) {
     const relativeEntry = relative(root, entry).split(sep).join('/');
     const files = readSources(root);
     const revision = fingerprint(files, relativeEntry);
-    if (!validatedSources.has(revision)) {
-        validateDependencies(files);
-        if (validatedSources.size >= 64)
-            validatedSources.delete(validatedSources.values().next().value);
-        validatedSources.add(revision);
-    }
     const revisionRoot = join(paths.revisions, installation.installationId, revision);
     if (!existsSync(revisionRoot)) {
         const temporary = `${revisionRoot}.${randomUUID()}.tmp`;

package/dist/plugins/runtime/pluginStateStore.js

@@ -3,7 +3,6 @@ import { existsSync, readFileSync, readdirSync, statSync, rmSync } from 'node:fs
 import { join, sep } from 'node:path';
 import { pluginHostPaths } from './pluginHostPaths.js';
 import { writePluginHostFile } from './pluginHostFiles.js';
-import { compilePluginStateSchema } from '../sdk/pluginStateDefinition.js';
 function fail(code, message) {
     throw Object.assign(new Error(message), { code });
 }
@@ -316,7 +315,6 @@ export class PluginStateStore {
                 else
                     delete entry.expiresAt;
             }
-        const validate = compilePluginStateSchema(definition.schema);
         for (const operation of input.operations) {
             key(operation.key);
             if (names.has(operation.key) ||
@@ -328,9 +326,9 @@ export class PluginStateStore {
                 delete entries[operation.key];
                 continue;
             }
-            if (!validate(operation.value) ||
-                Buffer.byteLength(JSON.stringify(operation.value)) > 256 * 1024)
-                fail('PLUGIN_STATE_SCHEMA_INVALID', 'State value does not match the declared schema or exceeds 256 KiB');
+            const json = JSON.stringify(operation.value);
+            if (json === undefined || Buffer.byteLength(json) > 256 * 1024)
+                fail('PLUGIN_STATE_INVALID', 'State value must be JSON within 256 KiB');
             const ttl = operation.ttlMs ?? definition.ttlMs ?? 86400000;
             if (definition.storage === 'persistent' && operation.ttlMs !== undefined)
                 fail('PLUGIN_STATE_INVALID', 'Persistent state does not accept TTL');
@@ -342,9 +340,6 @@ export class PluginStateStore {
                 ...(definition.storage !== 'persistent' ? { expiresAt: now + ttl } : {}),
             };
         }
-        for (const entry of Object.values(entries))
-            if (!validate(entry.value))
-                fail('PLUGIN_STATE_SCHEMA_INVALID', 'Migration leaves entries incompatible with the target schema');
         const commit = {
             revision,
             schemaVersion: definition.schemaVersion,

package/dist/plugins/runtime/pluginTaskManager.js

@@ -1,7 +1,6 @@
 import { normalizeModelDiagnostic, diagnosticBinding } from './pluginDiagnostics.js';
 import { pluginModelCapabilities, normalizePluginModel, validatePluginModelResult, } from '../sdk/pluginModelDefinition.js';
 import { pluginRecoverySignature } from '../sdk/pluginRecoveryDefinition.js';
-import { compilePluginStateSchema } from '../sdk/pluginStateDefinition.js';
 import { createHash, randomUUID } from 'node:crypto';
 import { EventEmitter } from 'node:events';
 import { isAbsolute, join, relative, sep } from 'node:path';
@@ -482,8 +481,7 @@ export class PluginTaskManager {
             signal.throwIfAborted();
             if (!sourceDefinition ||
                 sourceDefinition.checkpointVersion !== record.checkpoint.version ||
-                digest(sourceDefinition.schema) !== record.checkpoint.schemaHash ||
-                !compilePluginStateSchema(sourceDefinition.schema)(record.checkpoint.data))
+                digest(sourceDefinition.schema) !== record.checkpoint.schemaHash)
                 throw error('PLUGIN_TASK_RECOVERY_UNAVAILABLE', 'Checkpoint does not match the retained recovery declaration');
             let checkpoint = structuredClone(record.checkpoint);
             let declarationHash = pluginRecoverySignature(sourceDefinition);
@@ -542,8 +540,6 @@ export class PluginTaskManager {
                         data: JSON.parse(json),
                     };
                 }
-                if (!compilePluginStateSchema(target.schema)(checkpoint.data))
-                    throw error('PLUGIN_TASK_CHECKPOINT_INVALID', 'Migrated checkpoint does not match the target schema');
             }
             signal.throwIfAborted();
             // Admission is synchronous after both immutable snapshots and execution ownership are verified.
@@ -809,8 +805,8 @@ export class PluginTaskManager {
                         if (declaration &&
                             payload.expectedDeclaration !== pluginRecoverySignature(declaration))
                             throw error('PLUGIN_RECOVERY_DECLARATION_CHANGED', 'Checkpoint declaration differs from the executing command');
-                        if (!declaration || !compilePluginStateSchema(declaration.schema)(data))
-                            throw error('PLUGIN_TASK_CHECKPOINT_INVALID', 'Checkpoint is undeclared or does not match its schema');
+                        if (!declaration)
+                            throw error('PLUGIN_TASK_CHECKPOINT_INVALID', 'Checkpoint is undeclared');
                         const current = this.store.read(taskId);
                         if (current.task.state !== 'running' ||
                             payload.expectedSequence !== (current.checkpoint?.sequence ?? 0))

package/dist/plugins/sdk/plugin.js

@@ -4,6 +4,7 @@ import { normalizePluginPageRuntime } from './pluginPageDefinition.js';
 import { loadPluginAppProfiles } from './pluginAppProfiles.js';
 export { invokePageEvalWithArgs } from '../../pageEvalArguments.js';
 import { readFileSync } from 'node:fs';
+import { skillManifestPath } from '../skillManifest.js';
 import { dirname, extname, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { Command } from 'commander';
@@ -22,7 +23,10 @@ export { assertPluginName, findPluginDirectoryEntry, findPluginEntry, findPlugin
 export { findOfficialPlugin, listOfficialPluginNames, OFFICIAL_PLUGIN_MANAGER, OFFICIAL_PLUGINS, } from '../officialPluginCatalog.js';
 function readPluginVersion(entry) {
     try {
-        const content = readFileSync(resolve(dirname(entry), '..', 'SKILL.md'), 'utf8');
+        const manifest = skillManifestPath(resolve(dirname(entry), '..'));
+        if (!manifest)
+            return undefined;
+        const content = readFileSync(manifest, 'utf8');
         const frontmatter = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1];
         const versionLine = frontmatter?.split(/\r?\n/).find(line => /^version:\s*/.test(line));
         return versionLine?.match(/^version:\s*["']?([^"'#\s]+)["']?\s*$/)?.[1];

package/dist/plugins/sdk/pluginModelDefinition.js

@@ -1,5 +1,4 @@
 import { CODEX_MODEL_CAPABILITY } from '@mearl/agent-runtime/capabilities';
-import { compilePluginStateSchema } from './pluginStateDefinition.js';
 export function pluginModelCapabilities() {
     return { providers: [CODEX_MODEL_CAPABILITY] };
 }
@@ -44,7 +43,6 @@ export function normalizePluginModel(value) {
             request.outputSchema.$async ||
             Buffer.byteLength(JSON.stringify(request.outputSchema)) > 64 * 1024)
             throw new Error('Invalid model output schema');
-        compilePluginStateSchema(request.outputSchema);
     }
     return JSON.parse(JSON.stringify(request));
 }
@@ -65,10 +63,6 @@ export function validatePluginModelResult(request, value) {
                 code: 'PLUGIN_MODEL_SCHEMA_INVALID',
             });
         }
-        if (!compilePluginStateSchema(request.outputSchema)(output))
-            throw Object.assign(new Error('Model result does not match the output schema'), {
-                code: 'PLUGIN_MODEL_SCHEMA_INVALID',
-            });
         return { ...result, output };
     }
     return result;

package/dist/plugins/sdk/pluginPageDefinition.d.ts

@@ -1,3 +1,2 @@
 import type { PluginPageRuntime } from '../../generated/plugin-pages.js';
 export declare function normalizePluginPageRuntime(value: unknown): PluginPageRuntime | undefined;
-export declare function compilePluginPageSchema(schema: Record<string, unknown>): import("ajv/dist/core.js").AnyValidateFunction<unknown>;

package/dist/plugins/sdk/pluginPageDefinition.js

@@ -1,7 +1,5 @@
-import { parse } from 'acorn';
-import { Ajv } from 'ajv';
+import { Script } from 'node:vm';
 import { isPluginPageMatchPattern } from '../../generated/plugin-pages.js';
-const validators = new WeakMap();
 export function normalizePluginPageRuntime(value) {
     if (value === undefined)
         return undefined;
@@ -16,12 +14,7 @@ export function normalizePluginPageRuntime(value) {
         Buffer.byteLength(runtime.code) > 384 * 1024 ||
         Buffer.byteLength(JSON.stringify(runtime)) > 448 * 1024)
         throw new Error('Invalid plugin pageRuntime declaration');
-    const program = parse(`(${runtime.code}\n)`, { ecmaVersion: 'latest' });
-    const statement = program.body[0];
-    if (program.body.length !== 1 ||
-        statement.type !== 'ExpressionStatement' ||
-        !['ArrowFunctionExpression', 'FunctionExpression'].includes(statement.expression?.type ?? ''))
-        throw new Error('pageRuntime.code must be a self-contained function expression');
+    new Script(`(${runtime.code}\n)`, { filename: 'plugin-page-runtime.js' });
     if (runtime.events !== undefined &&
         (!runtime.events ||
             typeof runtime.events !== 'object' ||
@@ -46,17 +39,8 @@ export function normalizePluginPageRuntime(value) {
                     event.maxPending > 64)) ||
             event.schema.$async)
             throw new Error(`Invalid page event binding: ${name}`);
-        compilePluginPageSchema(event.schema);
     }
     if (runtime.initialize !== undefined && !/^[a-z][a-z0-9-]*$/.test(runtime.initialize))
         throw new Error('Invalid page runtime initialize command');
     return JSON.parse(JSON.stringify(runtime));
 }
-export function compilePluginPageSchema(schema) {
-    let validate = validators.get(schema);
-    if (!validate) {
-        validate = new Ajv({ strict: true, allErrors: false }).compile(schema);
-        validators.set(schema, validate);
-    }
-    return validate;
-}

package/dist/plugins/sdk/pluginRecoveryDefinition.js

@@ -1,5 +1,4 @@
 import { createHash } from 'node:crypto';
-import { compilePluginStateSchema } from './pluginStateDefinition.js';
 export function normalizePluginTaskRecovery(value) {
     if (value === undefined)
         return;
@@ -22,7 +21,6 @@ export function normalizePluginTaskRecovery(value) {
             Array.isArray(definition.schema) ||
             definition.schema.$async)
             throw new Error('Invalid task checkpoint definition');
-        compilePluginStateSchema(definition.schema);
         if (definition.migrateFrom !== undefined) {
             if (!Array.isArray(definition.migrateFrom) ||
                 definition.migrateFrom.length < 1 ||
@@ -40,7 +38,6 @@ export function normalizePluginTaskRecovery(value) {
                     Array.isArray(source.schema) ||
                     source.schema.$async)
                     throw new Error('Checkpoint migrations require distinct older versions and schemas');
-                compilePluginStateSchema(source.schema);
                 versions.add(source.version);
             }
         }

package/dist/plugins/sdk/pluginStateDefinition.d.ts

@@ -1,4 +1,3 @@
 import type { PluginStateDeclaration } from '../../generated/plugin-state.js';
-export declare function compilePluginStateSchema(schema: Record<string, unknown>): import("ajv/dist/core.js").AnyValidateFunction<unknown>;
 export declare function normalizePluginState(value: unknown): PluginStateDeclaration | undefined;
 export declare function pluginStateSignature(collection: import('../../generated/plugin-state.js').PluginStateCollection): string;

package/dist/plugins/sdk/pluginStateDefinition.js

@@ -1,14 +1,4 @@
 import { createHash } from 'node:crypto';
-import { Ajv } from 'ajv';
-const validators = new WeakMap();
-export function compilePluginStateSchema(schema) {
-    let validate = validators.get(schema);
-    if (!validate) {
-        validate = new Ajv({ strict: true }).compile(schema);
-        validators.set(schema, validate);
-    }
-    return validate;
-}
 export function normalizePluginState(value) {
     if (value === undefined)
         return;
@@ -55,7 +45,6 @@ export function normalizePluginState(value) {
             throw new Error('State TTL must be between 1 ms and 7 days');
         if (collection.storage === 'persistent' && collection.ttlMs !== undefined)
             throw new Error('Persistent state does not accept TTL');
-        compilePluginStateSchema(collection.schema);
     }
     return declaration;
 }

package/dist/plugins/skillManifest.d.ts

@@ -0,0 +1,5 @@
+export declare const DISABLED_SKILL_MANIFEST = "SKILL.md.mearl-disabled";
+/** 保留的清单供工具运行时读取，但不参与 Agent 的 SKILL.md 发现。 */
+export declare function skillManifestPath(directory: string): string | undefined;
+export declare function getSkillEnabled(directory: string): boolean | undefined;
+export declare function setSkillEnabled(directory: string, enabled: boolean): void;

package/dist/plugins/skillManifest.js

@@ -0,0 +1,35 @@
+import { existsSync, lstatSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+export const DISABLED_SKILL_MANIFEST = 'SKILL.md.mearl-disabled';
+/** 保留的清单供工具运行时读取，但不参与 Agent 的 SKILL.md 发现。 */
+export function skillManifestPath(directory) {
+    for (const name of ['SKILL.md', DISABLED_SKILL_MANIFEST]) {
+        const file = join(directory, name);
+        if (existsSync(file))
+            return file;
+    }
+    return undefined;
+}
+export function getSkillEnabled(directory) {
+    const manifest = skillManifestPath(directory);
+    return manifest ? manifest === join(directory, 'SKILL.md') : undefined;
+}
+export function setSkillEnabled(directory, enabled) {
+    const active = join(directory, 'SKILL.md');
+    const disabled = join(directory, DISABLED_SKILL_MANIFEST);
+    const source = enabled ? disabled : active;
+    const destination = enabled ? active : disabled;
+    const sourceStatus = lstatSync(source, { throwIfNoEntry: false });
+    const destinationStatus = lstatSync(destination, { throwIfNoEntry: false });
+    if (sourceStatus && destinationStatus) {
+        throw new Error('Skill 清单存在冲突，请检查 SKILL.md 和 SKILL.md.mearl-disabled');
+    }
+    if (!sourceStatus) {
+        if (destinationStatus?.isFile())
+            return;
+        throw new Error('找不到 Skill 清单');
+    }
+    if (!sourceStatus.isFile())
+        throw new Error('Skill 清单必须是普通文件');
+    renameSync(source, destination);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "2.22.0",
+  "version": "2.22.1",
   "description": "Unified Mearl SDK & CLI for local and remote browsers",
   "type": "module",
   "main": "dist/index.js",
@@ -60,15 +60,13 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "acorn": "^8.16.0",
-    "ajv": "^8.18.0",
     "commander": "^15.0.0",
     "fastest-levenshtein": "^1.0.16",
     "ws": "^8.18.0",
-    "@mearl/daemon-core": "2.22.0",
-    "@mearl/cloud-types": "2.22.0",
-    "@mearl/provider": "2.22.0",
-    "@mearl/agent-runtime": "2.22.0"
+    "@mearl/cloud-types": "2.22.1",
+    "@mearl/daemon-core": "2.22.1",
+    "@mearl/provider": "2.22.1",
+    "@mearl/agent-runtime": "2.22.1"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",
@@ -76,7 +74,7 @@
     "typescript": "^5.8.3"
   },
   "scripts": {
-    "build": "node ../../scripts/generate-client-action-protocol.mjs --check && rm -rf dist/ && tsc && chmod +x dist/bin.js",
+    "build": "node ../../scripts/generate-client-action-protocol.mjs --check && node ../../scripts/generate-plugin-host-build.mjs && rm -rf dist/ && tsc && chmod +x dist/bin.js",
     "dev": "tsc --watch",
     "typecheck": "node ../../scripts/generate-client-action-protocol.mjs --check && tsc --noEmit",
     "test": "vitest run"