@mearl/native-host 3.0.0-beta.7 → 3.0.0-beta.9

package/README.md

@@ -2,11 +2,11 @@
 
 Mearl 的 Native Messaging Host —— 桥接 Chrome 扩展与本地 socket 服务。
 
-浏览器扩展通过 `chrome.runtime.connectNative()` 拉起本进程；进程对内通过 CDP（Chrome DevTools Protocol）与浏览器交互，对外通过 **Unix Socket** 暴露给 `@mearl/client` 等本地调用方，并可作为云端链路的本地落点。
+浏览器扩展通过 `chrome.runtime.connectNative()` 启动本进程。宿主通过扩展或 CDP 与浏览器交互，通过本地 IPC 连接 `@mearl/client` 等调用方：macOS/Linux 使用 Unix socket，Windows 使用命名管道。Cloud Connector 使用同一宿主连接。
 
 ## 动态能力
 
-公开宿主支持基础设备模拟与 Aplus/RUM/ARMS 埋点协议解析，无需安装 preset。完整模拟、业务请求与专用事件解析、身份和特殊授权通过独立 Node 包动态接入；原动作入口、原 App ID 和授权进度保留。资源校验、更新/回滚和代码引用合同见 [Node 能力包](../../docs/node-capabilities.md)。当前整套 preset 的安装、默认值应用与网页一键入口仍待接通。
+宿主提供浏览器控制、设备模拟、插件执行和默认埋点解析。Node 能力包通过声明的 hook 提供处理器，资源、激活与回滚合同见 [Node 能力包](../../docs/node-capabilities.md)。Setup 与网页安装桥共用 [安装宿主](../../docs/preset-installation.md) 的协调流程。
 
 ## 安装与注册
 
@@ -213,8 +213,6 @@ CDP 会话层按浏览器端点身份保存 target 与虚拟 tabId 的映射，
 
 native-host 被清理或连接短暂中断时，文档实例在最后一次成功校验后的 30 秒租约内保留归属；无法确认文档的操作返回 `PLUGIN_PAGE_UNAVAILABLE`，不执行页面操作，也不把失败的对账响应当成实例缺失。重连后须校验原浏览器、文档和实例身份。已接收但尚未启动任务的事件可以继续排队；已发出的操作不自动重放。明确的导航、卸载、文档失效仍立即清理；长时间失联导致租约到期后清理旧实例，启用的激活规则可在宿主恢复时建立新实例。
 
-构建后运行 `pnpm verify:plugin-pages:cdp`，用独立无头 Chrome、临时插件注册目录与执行服务验收文档隔离、后台事件任务、分块结果、SPA、跨域 iframe、导航重建和宿主重启；多标签页关闭后重启时还核验原手动实例、tabId、documentId 与后台事件执行。默认使用 macOS Chrome，可通过 `MEARL_CHROME_PATH` 指定其他平台的 Chrome/Chromium 可执行文件。
-
 CDP 页面会话文件在同一连接标识切换浏览器身份、受控浏览器明确关闭或确认进程已退出时回收，持久激活规则保留。
 缺少可验证浏览器归属的旧会话文件保留到完整卸载；`cdp-targets` 的标签 ID 递增计数跨浏览器生命周期保留，避免旧请求误操作新标签。
 受控浏览器日志在启动前按 5 MiB 轮转，保留一份备份；无对应浏览器记录的日志保留 7 天，在宿主启动、浏览器查询或启动时清理。
@@ -250,7 +248,7 @@ export default app => {
 
 事件 schema 保留为格式描述，后台处理器负责验证负载；宿主检查事件绑定、文档归属、大小和调度约束。事件负载最多 32 KiB，页面待确认队列 64 条；后台每事件默认待处理 32 条（最多 64），每实例活动事件最多 128，有限并发最多 8。历史最多 256 条及 384 KiB，游标缺口明确返回。Native Messaging 的请求与结果各按 192 KiB 分块并校验 SHA-256，单条页面业务消息/结果最多 24 MiB；浏览器与工具箱回复资源各有 32 MiB 总预算及 30 秒过期。
 
-SDK 使用 `PluginPageClient`。工具箱调用 `host.page.*`，或 `window.mearl.subscribe('page', { instanceId, cursor? }, listener)` 观察后台事件；`events` 接受 `cursor` 与 `waitMs`（0–25000），无新事件时可等待变化；工具箱订阅先读取快照，随后使用长轮询，退订只结束观察。内部 `page_runtime` 是文档适配协议，业务插件使用 `app.page()`。设计稿叠加已迁移，保存事件无需 Popup 转发。
+SDK 使用 `PluginPageClient`。工具箱调用 `host.page.*`，或 `window.mearl.subscribe('page', { instanceId, cursor? }, listener)` 观察后台事件；`events` 接受 `cursor` 与 `waitMs`（0–25000），无新事件时可等待变化；工具箱订阅先读取快照，随后使用长轮询，退订只结束观察。内部 `page_runtime` 是文档适配协议，业务插件使用 `app.page()`。设计稿叠加通过页面事件保存素材。
 
 激活通过 `app.page('activation', { enabled: true, matches, persistence: 'session' | 'persistent', frame, input })` 显式配置；实际范围是用户规则与声明范围的交集；自动激活实例在注入、SPA 导航及日常校验时复查该交集，离开范围即失效，手动挂载遵循插件声明范围。关闭规则清理实例，在途挂载由规则代次校验阻止。扩展 worker 重启后先与执行服务握手，核验 hostId、service epoch、安装、revision、browserSessionId、documentId 和 instanceId；同一所有者按服务端已接收位置续传未确认事件，确认位置只前进。连接 epoch 变化不改变业务事件序号。桥接暂时不可用时保留队列等待对账，租约过期后失效。
 
@@ -272,46 +270,7 @@ schema 是格式元数据，宿主不执行 JSON Schema 关键字校验；状态
 
 插件声明可用 URL 范围与激活入口，用户规则决定是否启用、匹配范围和跨重启保留。激活维护页面实例，业务命令由显式调用或事件触发。扩展、浏览器和执行服务分别重启时，通过握手对账实例及任务，防止重复恢复。
 
-### 实施进度和验收
-
-| 阶段 | 交付 | 状态 |
-| --- | --- | --- |
-| 执行基础 | 环境和调用身份、独立上下文、受管理执行器、后台命令接入、一次性 Agent 原始结果 | 已实现 |
-| 执行服务 | 用户级服务、租约、安装与 revision 快照、持久任务和大结果、SDK/CLI/MCP 任务入口 | 已实现 |
-| 页面能力 | 固定目标、运行实例、后台事件、激活规则及对应工具迁移 | 已实现（扩展与 CDP 共用宿主） |
-| 模型和状态 | Provider 能力声明、受管理模型任务、结构化结果、事务状态、现有工具迁移 | 已实现（Codex 只读 Agent） |
-| 故障恢复 | 原 revision 的检查点恢复、新 attempt、执行树核验、扩展/服务重启对账与激活重建 | 已实现（上述作用域） |
-| 子调用归属 | 独立子任务与 revision、专属服务、权限与文档约束、等待名额和取消树 | 已实现 |
-| 诊断和接口收口 | 有界元数据导出、SDK/CLI/MCP/工具箱/Python 对齐、错误语义及文档 | 已实现 |
-
-工具箱后台入口统一为 host.task.*，迭代管理、标签管理和图片压缩已同步迁移。普通同步命令仍在调用进程执行，后台命令使用执行器。工具箱分块资源和业务状态不能依赖某次后台命令进程继续存活。
-
-验收覆盖并发身份与服务初始化、上下文隔离、嵌套调用、入口限制、JS 阻塞终止、Python 上下文及取消、取消和完成竞态、挂起宿主调用、大文本和结构化结果、服务崩溃恢复、调用方断线、源码更新、事件缺口及结果校验。页面验收覆盖同文档并发初始化、连接代次与去重、事件合并、源码固定、导航取消、后台重启重发、激活停用竞态及双向资源完整性。模型与状态验收补充真实子进程中的大 Unicode 结果、结构化失败、独立队列、父子取消、Python 调用、CAS/TTL/迁移和页面失效写入竞态。恢复验收补充真实服务 SIGKILL、原 handler 不重放、并发 resume 去重、源码损坏、Python 恢复、子执行器未停、ACK 与对账交错、慢 dispose 和安装更换。真实 Chrome 已验证约 500 KB Unicode 文本双向分块、页面事件到实例状态的完整链路，以及执行服务 SIGKILL 后由激活规则重建新 epoch/实例并继续处理新事件。跨 revision 验收覆盖历史 schema 身份、显式单步迁移、版本固定、并发去重、输入兼容、宿主调用拦截和服务关闭清理。其他 Provider 和跨执行环境恢复保留在后续阶段。
-
-### 真实端到端验收
-
-根目录提供显式运行的验收脚本（不随单元测试访问真实模型）：
-
-```bash
-pnpm build
-pnpm verify:plugin-host:live \
-  --browser <全局浏览器ID> \
-  --model <当前账号支持的模型> \
-  --codex /absolute/path/to/codex \
-  --output /tmp/mearl-host-live-report.json
-```
-
-运行前须已连接支持页面运行时的 Chrome 扩展，并且没有现存任务服务；仅在确认服务空闲时通过 SDK 显式调用 `tasks.stopHost()`。脚本自己创建服务并记录 PID/OS 身份，崩溃测试只终止该进程，接纳前检查其他插件的活动任务和页面实例。Native Host 若抢先自动拉起替代服务，验收观察其恢复结果，但不停止不属于本轮创建的进程。
-
-`--codex` 显式指定与实际宿主一致的二进制，避免 PATH 中独立 CLI 与 App 内置运行时的版本、模型支持差异。需要已有文件认证，默认从当前 CODEX_HOME（或 ~/.codex）复制 auth.json 到受限临时目录，可用 `--codex-home` 指定认证来源；原配置和认证文件不修改。运行配置与工作目录均在 Skill 源码树之外，代码快照只包含测试入口和 SKILL.md。独立配置仅选择模型和推理强度，不继承用户 MCP/插件配置。
-
-验收使用真实本地 Codex 和后台测试页，检查结构化任务、页面事件→模型→持久状态→真实 DOM、turn 开始后的取消、执行期限、未知模型失败、导航取消父子任务和服务 SIGKILL 后的新实例。期限、导航与崩溃场景通过代理在真实 turn/start 成功后暂缓交付通知，报告明确标记故障注入；不依赖模型生成速度，也不将代理当作模拟模型。代理默认完整转发 RPC，输出内容不写入诊断。
-
-JSON 报告包含每项结果、耗时、任务/页面/执行代次证据、协议方法和失败原因。脚本分别清理任务、注册、页面、认证副本及本轮创建的服务；执行停止未确认时保留任务与代码记录，报告清理失败。Ctrl+C/SIGTERM 进入相同清理流程。默认单元测试验证代理的大文本转发、通知停滞和认证缺失时的早期清理，不发起真实模型请求。
-
-### 默认环境验收
-
-`pnpm verify:plugin-host:default --output /tmp/mearl-host-default.json` 使用调用环境原有的 Codex 运行时发现、配置、认证和默认模型，分别通过 SDK 与 PATH 中临时验收插件的 `proof` 业务命令 校验结构化结果、执行树停止和诊断。它不设置模型或二进制、不复制认证、不写用户配置；报告说明原环境是否已有 CODEX_HOME / MEARL_CODEX_PATH 覆盖。验收只清理自己创建的插件与任务，不停止共享服务。
+工具箱后台命令通过 `host.task.*` 执行。普通同步命令在调用进程执行，后台命令使用受管理执行器；长期资源通过状态、文件或资源通道保存。
 
 工具箱用户发起的页面 attach 在解析目标文档缺少站点权限时，复用宿主权限弹窗，批准后仅重试未派发的 resolve。页面心跳、已有实例消息与后台事件不弹窗，也不重放可能已产生效果的操作。扩展重载属于宿主操作，与当前网页的域权限独立。
 
@@ -350,7 +309,7 @@ pnpm typecheck  # 仅类型检查
 
 ## License
 
-ISC
+Apache-2.0
 
 模型列表可通过 SDK `PluginModelClient.list()` 或工具箱 `host.model.list` 查询。模型项携带可用时的 `reasoningEfforts` 和 `defaultReasoningEffort`，界面按模型支持范围提供思考级别。宿主合并并发发现请求，已有模型目录立即返回，过期后后台刷新；刷新失败保留可用目录并短暂退避，不创建推理会话。状态批量读取使用 `get-many` 和 `keys`（SDK `getMany`、工具箱 `host.state.getMany`），一次读取同一 revision 的最多 128 个键，含缺失键的 CAS version，结果上限 1 MiB。
 

package/dist/capability-contracts.d.ts

@@ -1,4 +1,4 @@
-import type { RequestCookie, RequestMetadata, ParsedSseEvent, RumEvent, SendProtocolRequestParams } from '@mearl/browser-core';
+import type { RequestCookie, RequestMetadata, ParsedSseEvent, RumEvent } from '@mearl/browser-core';
 /** Protocol-specific fields remain opaque to the HTTP host. */
 export interface ResolvedProtocolRequest {
     requestData: unknown;
@@ -20,7 +20,7 @@ export type ProtocolStreamCaptureStart = Omit<import('@mearl/browser-core').Requ
     url?: string;
 };
 export interface RequestProtocolCapability {
-    resolveRequest(data: SendProtocolRequestParams): ResolvedProtocolRequest;
+    resolveRequest(data: Record<string, unknown>): ResolvedProtocolRequest;
     prepareRequest(resolved: ResolvedProtocolRequest, cookies: readonly RequestCookie[], stream?: boolean): PreparedProtocolRequest;
     parseResponse(text: string): unknown;
     consumeResponse(response: Response, onReceive: (event: ParsedSseEvent) => void | Promise<void>): Promise<unknown>;

package/dist/cdp-backend/http-handlers.d.ts

@@ -2,7 +2,7 @@ import { type ResponseCookieSync } from './response-cookies.js';
 /**
  * CDP HTTP proxy / PROTOCOL request / API schema handlers.
  */
-import { type RequestMetadata, SendProtocolRequestParams, SendRequestParams } from '@mearl/browser-core';
+import { type RequestMetadata, SendRequestParams } from '@mearl/browser-core';
 import type { PageSession } from './cdp-session.js';
 export interface CdpProtocolStreamRequestMetadata {
     method: 'GET' | 'POST';
@@ -27,8 +27,8 @@ export interface CdpProtocolStreamCallbacks {
     onReceive: (data: unknown) => void | Promise<void>;
 }
 export declare function cdpSendRequest(session: PageSession, data: SendRequestParams): Promise<any>;
-export declare function cdpSendProtocolRequest(session: PageSession, data: SendProtocolRequestParams): Promise<any>;
-export declare function cdpSendProtocolStreamRequest(session: PageSession, data: SendProtocolRequestParams, callbacks: CdpProtocolStreamCallbacks): Promise<{
+export declare function cdpSendProtocolRequest(session: PageSession, data: Record<string, unknown>): Promise<any>;
+export declare function cdpSendProtocolStreamRequest(session: PageSession, data: Record<string, unknown>, callbacks: CdpProtocolStreamCallbacks): Promise<{
     success: true;
     response: unknown;
     requestData: unknown;