@weapp-vite/miniprogram-automator 1.3.0 → 1.5.0

package/README.md

@@ -16,6 +16,7 @@
 - 提供 `Launcher` 用于启动、连接和复用 DevTools 会话
 - 支持按平台选择自动化后端，默认微信，百度智能小程序提供轻量 TypeScript runtime
 - 支持截图、输入、滚动、点击、页面跳转等自动化操作
+- 对齐官方 0.13.0 的公开 `send()`、`CDP()` 和可等待断开接口
 - 默认输出现代 ESM 与完整类型声明
 - 内置二维码打印与解码辅助能力，便于配合登录、连接流程调试
 - 支持 headless 自动化启动入口
@@ -157,6 +158,77 @@ else {
 
 空结果、缺失字段、字符串、负数、非有限数值或已用量超过分配量都会报错；连接超时与其他协议错误原样传播，不会转换为不支持或零内存。每次调用重新探测，不缓存旧会话的能力结果，也不主动触发 GC。该指标仅覆盖 AppService JS 堆，不是 renderer/native 内存、进程 RSS、峰值或可归因的组件独占内存。实际可用性取决于连接的 DevTools/基础库，仍须在目标宿主确认；headless 不提供真实 IDE 堆证据。
 
+### 4.8 原始协议与 CDP
+
+`send(method, params?, { timeout }?)` 公开原始自动化协议入口，返回宿主原始结果；超时、断开和协议错误继续抛出。错误消息为对象时会序列化展示，错误对象保留原始协议信息。
+
+```ts
+const info = await miniProgram.send('Tool.getInfo', {}, { timeout: 3_000 })
+console.log(info)
+
+const cdp = miniProgram.CDP()
+await cdp.enable({ timeout: 3_000 })
+const protocol = await cdp.listProtocol()
+console.log(protocol)
+await cdp.sendCommand('Runtime', 'enable')
+const unsubscribe = cdp.onEvent((domain, event, params) => {
+  if (domain === 'Runtime' && event === 'consoleAPICalled') {
+    console.log(params)
+  }
+})
+try {
+  console.log(await cdp.sendCommand('Runtime', 'evaluate', {
+    expression: '40 + 2',
+    returnByValue: true,
+  }, { timeout: 3_000 }))
+}
+finally {
+  unsubscribe()
+}
+```
+
+同一连接的 `CDP()` 共享启用状态，并发启用只发起一次初始化，失败后可重试。`sendCommand` 和 `listProtocol` 自动等待启用；可选超时包含初始化所用时间。`onEvent` 返回可重复调用的取消订阅函数，断开连接自动移除本连接注册的监听。结构化日志和堆探测复用同一 CDP 通道；重复 `enableLog` 仍会刷新日志订阅。实际域、命令和结果由目标 DevTools 决定，可先用 `listProtocol()` 查询。
+
+### 4.9 触摸事件字段
+
+`touchstart`、`touchmove`、`touchend` 和 `dispatchEvent` 均接受标准字段 `changedTouches`，会将触点坐标和触点数组交给页面事件处理器。
+
+```ts
+const point = { identifier: 1, pageX: 40, pageY: 60, clientX: 40, clientY: 60 }
+await button?.touchstart({ touches: [point], changedTouches: [point] })
+await button?.touchend({ touches: [], changedTouches: [point] })
+await button?.dispatchEvent({ eventName: 'touchstart', touches: [point], changedTouches: [point] })
+```
+
+旧拼写 `changeTouches` 保留为 deprecated 别名，发送前统一转换为 `changedTouches`；同时传入时以 `changedTouches` 为准。
+
+### 4.10 异步断开与迁移
+
+`MiniProgram.disconnect()`、`Connection.dispose()` 和 `Transport.close()` 现在返回 `Promise<void>`。调用时立即拒绝未完成 RPC、停止事件订阅并终止本连接，Promise 等待 socket 实际关闭；独立关闭默认最多等待 2 秒。并发调用共享同次清理结果，超时会报告关闭未确认，后续可重新确认迟到的关闭。启动失败清理仍使用启动操作剩余的总预算。
+
+原来在同步清理回调或 `finally` 中直接调用 `disconnect()` 的代码，应迁移到可等待的调用链，返回或等待 Promise。`process.on('exit')` 无法等待异步清理，应在主动退出或信号处理流程中先 `await disconnect()`：
+
+```ts
+try {
+  console.log(await miniProgram.currentPage())
+}
+finally {
+  await miniProgram.disconnect()
+}
+```
+
+`disconnect()` 只断开连接；关闭受管项目窗口仍由持有窗口 owner 的会话 `close()` 负责。重连复用已有窗口的 endpoint，不重新启动 IDE。清理失败会抛出，调用方不能据此记录端口租约、窗口或快照已释放。
+
+headless provider 保留同名 `CDP()` 入口，调用会明确报告 `HEADLESS_PROTOCOL_UNSUPPORTED`，不提供 inspector 后端。原始 `send` 仅支持 `Tool.getInfo`、`App.getCurrentPage`、`App.getPageStack`、`App.callFunction`、`App.callWxMethod`；其他协议明确报不支持。headless 的异步断开释放独占运行时，其结果不能证明真实 IDE 窗口已关闭。
+
+### 4.11 Headless 原生控件边界
+
+`Launcher.launch({ platform: 'wechat', runtimeProvider: 'headless', projectPath })` 使用 simulator 的真实渲染树与原生事件模型。未禁用的 `button form-type="submit"` 可以触发表单默认提交，无需额外调用业务 submit 方法；`rich-text` 的结构化节点和 HTML 内容可以通过通用 `text()` 观察，更新和清空均反映在渲染结果中。
+
+一次原生分发在后续监听器同步失败时，仍等待此前已启动的异步处理。单一错误原样抛出；同步和异步处理同时失败时，以 `AggregateError.errors` 保留各错误，并以原同步错误作为 `cause`。
+
+表单保留组件/插槽归属，字段值来自当前渲染绑定；未绑定输入的宿主状态、自定义 `wx://form-field` 值导出、reset、真实 `formId` 上报不在此能力范围内。富文本内容保持惰性，不作为 WXML 执行；`attr('nodes')` 仍返回字符串表示。Headless 通过不等于微信 IDE 或真机通过，不能替代目标宿主验收。
+
 ## 5. 主要导出
 
 | 导出                      | 说明                                     |
@@ -186,3 +258,5 @@ pnpm --filter @weapp-vite/miniprogram-automator typecheck
 微信 DevTools 的 `launch` / `connect` 使用一次总 `timeout`（默认 30 秒）。路径准备、端口租约、HTTP 适配、WebSocket、版本与 App ready 均消耗剩余预算，自动重试不重置 deadline。可传 `signal` 取消；成功后连接归调用方管理。
 
 失败保留 `cause`，`error.operation` 包含阶段、最后成功阶段、耗时、剩余预算、尝试次数、未退出操作数量及本次资源清理状态。清理 `pending` 表示在预算内未确认退出，不能当作资源已释放。迟到连接只断开自身 WebSocket；启动器只终止持有句柄的 CLI 子进程，不据此认领 IDE 宿主或清理其他项目。无需在 App ready 后再固定等待五秒。
+
+启动失败还会附加捕获的 CLI stdout/stderr 尾部输出，最多保留 32,768 个字符，截断时明确标记，并隐藏凭据。输出诊断保留原始 `cause`、错误分类和总预算信息。

package/dist/index.d.mts

@@ -2,18 +2,13 @@ import { OPERATION_TIMEOUT_CODE, OperationDiagnostics, OperationErrorCategory, O
 import { EventEmitter } from "node:events";
 import WebSocket from "ws";
 import { Buffer } from "node:buffer";
-//#region src/smartapp/file.d.ts
 declare function mkdir(dir: string): Promise<void>;
 declare function rmdir(dir: string): Promise<void>;
 declare function wget(url: string, targetPath: string): Promise<void>;
 declare function changeProjectSwanJson(projectPath: string, values: Record<string, unknown>): Promise<void>;
-//#endregion
-//#region src/smartapp/image.d.ts
 declare function drawBorder(imageBuffer: Buffer): Promise<Buffer<ArrayBufferLike>>;
 declare function extract(imageBuffer: Buffer): Promise<Buffer<ArrayBufferLike>>;
 declare function border(imageBuffer: Buffer): Promise<Buffer<ArrayBufferLike>>;
-//#endregion
-//#region src/smartapp/log.d.ts
 /**
  * @file 百度智能小程序自动化日志工具。
  */
@@ -24,15 +19,11 @@ interface SmartappLogger {
 }
 declare function set(_dir: string, label?: string): SmartappLogger;
 declare function get(label?: string): SmartappLogger;
-//#endregion
-//#region src/smartapp/time.d.ts
 /**
  * @file 百度智能小程序自动化时间工具。
  */
 declare function currentTimestamp(): number;
 declare function delay(ms: number): Promise<void>;
-//#endregion
-//#region src/appServiceHeap.d.ts
 interface AppServiceHeapUsageOptions {
   /** 单次协议请求的超时预算，单位毫秒。 */
   timeout?: number;
@@ -47,44 +38,58 @@ type AppServiceHeapUsage = {
   source: 'appservice-cdp-runtime';
   reason: 'protocol-unimplemented' | 'method-not-found';
 };
-//#endregion
-//#region src/Transport.d.ts
+interface CDPCommandOptions {
+  /** 启用通道与执行命令共享的超时预算，单位毫秒。 */
+  timeout?: number;
+}
+type CDPEventListener = (domain: string, event: string, params: any) => void;
+interface CDPSession {
+  enable: (options?: CDPCommandOptions) => Promise<unknown>;
+  sendCommand: <T = any>(domain: string, method: string, params?: Record<string, unknown>, options?: CDPCommandOptions) => Promise<T>;
+  listProtocol: (options?: CDPCommandOptions) => Promise<any>;
+  onEvent: (listener: CDPEventListener) => () => void;
+}
 /** Transport 的实现。 */
 declare class Transport extends EventEmitter {
   private ws;
+  private closed;
+  private terminating;
+  private closing?;
   constructor(ws: WebSocket);
   send(message: string): void;
-  close(): void;
+  close(): Promise<void>;
 }
-//#endregion
-//#region src/Connection.d.ts
 interface SendOptions {
   timeout?: number;
 }
 interface ToolInfo {
   version?: string;
+  SDKVersion?: string;
 }
 /** Connection 的实现。 */
 declare class Connection extends EventEmitter {
   private transport;
   private disposed;
+  private disposing?;
   private callbacks;
   private useAppServicePageProtocol;
   private useAppServicePageMethod;
+  private useComponentCallerBridge;
   constructor(transport: Transport);
   send(method: string, params?: Record<string, any>, options?: SendOptions): Promise<any>;
-  dispose(): void;
+  dispose(): Promise<void>;
+  private closeTransport;
   /** 根据 DevTools 版本选择稳定的 Page 协议实现。 */
   configureToolInfo(info: ToolInfo): void;
   get prefersAppServicePageProtocol(): boolean;
   /** 页面方法调用独立选择协议，不影响节点查询及其组件作用域。 */
   get prefersAppServicePageMethod(): boolean;
+  /** 仅为实测存在跨上下文 token 错绑的 IDE 与基础库启用真实 caller 桥接。 */
+  get prefersComponentCallerBridge(): boolean;
   private onMessage;
   private onClose;
   static create(url: string, timeout?: number, signal?: AbortSignal): Promise<Connection>;
 }
-//#endregion
-//#region src/structuredConsole.d.ts
 interface ConsoleLogOptions {
   /** 使用 CDP 原始参数，并读取 Error 的非枚举数据属性；默认保留 SDK 日志格式。 */
   structured?: boolean;
@@ -105,8 +110,6 @@ interface StructuredConsoleEntry {
   args: ConsoleRemoteObject[];
   [key: string]: unknown;
 }
-//#endregion
-//#region src/Native.d.ts
 /** ISwitchTabOptions 的类型定义。 */
 interface ISwitchTabOptions {
   url: string;
@@ -128,8 +131,6 @@ declare class Native extends EventEmitter {
   private send;
   private sendNative;
 }
-//#endregion
-//#region src/Element.d.ts
 /** IElementOptions 的类型定义。 */
 interface IElementOptions {
   elementId: string;
@@ -156,6 +157,8 @@ interface ITouch {
 /** ITouchEventOptions 的类型定义。 */
 interface ITouchEventOptions {
   touches?: ITouch[];
+  changedTouches?: ITouch[];
+  /** @deprecated 请使用 changedTouches，发送时会自动转换旧字段。 */
   changeTouches?: ITouch[];
 }
 /** IEventOptions 的类型定义。 */
@@ -163,6 +166,8 @@ interface IEventOptions {
   eventName: string;
   $?: string;
   touches?: ITouch[];
+  changedTouches?: ITouch[];
+  /** @deprecated 请使用 changedTouches，发送时会自动转换旧字段。 */
   changeTouches?: ITouch[];
   detail?: Record<string, any>;
 }
@@ -178,7 +183,7 @@ declare class Element {
   protected nodeId: string | null;
   private videoId;
   private id;
-  private pageId;
+  protected pageId: number;
   private publicProps?;
   constructor(connection: Connection, options: IElementOptions, elementMap: ElementMap);
   $(selector: string, options?: ElementQueryOptions): Promise<Element | null>;
@@ -253,8 +258,6 @@ export declare class SliderElement extends Element {
 export declare class ContextElement extends Element {
   callContextMethod(method: string, ...args: any[]): Promise<any>;
 }
-//#endregion
-//#region src/Page.d.ts
 /** IPageOptions 的类型定义。 */
 interface IPageOptions {
   id: number;
@@ -343,8 +346,6 @@ declare class Page {
   private send;
   static create(connection: Connection, options: IPageOptions, pageMap: PageMap): Page;
 }
-//#endregion
-//#region src/MiniProgram.d.ts
 interface IScreenshotOptions {
   path?: string;
   timeout?: number;
@@ -376,8 +377,11 @@ declare class MiniProgram extends EventEmitter {
   private logEnabling?;
   private structuredLogs;
   private structuredConsole;
+  private readonly cdp;
   private pageMap;
   private nativeIns?;
+  private disconnecting?;
+  private closing?;
   constructor(connection: Connection);
   pageStack(): Promise<any>;
   navigateTo(url: string): Promise<Page>;
@@ -404,7 +408,8 @@ declare class MiniProgram extends EventEmitter {
   pageScrollTo(scrollTop: number): Promise<void>;
   close(): Promise<void>;
   remote(auto?: boolean): Promise<void>;
-  disconnect(): void;
+  disconnect(): Promise<void>;
+  private stopSubscriptions;
   /** 等待已接收的结构化日志完成 Error 属性检查并发布。 */
   flushConsole(): Promise<void>;
   enableLog(timeout?: number, options?: ConsoleLogOptions): Promise<void>;
@@ -445,13 +450,16 @@ declare class MiniProgram extends EventEmitter {
   private createPageFromPayload;
   private createPagesFromPayloads;
   private readAppFunctionPageStack;
-  private send;
+  /** 返回当前连接共享的 CDP 调试入口。 */
+  CDP(): CDPSession;
+  /** 发送原始自动化协议，沿用连接的请求超时及清理契约。 */
+  send(method: string, params?: Record<string, any>, options?: {
+    timeout?: number;
+  }): Promise<any>;
   private onLogAdded;
   private onBindingCalled;
   private onExceptionThrown;
 }
-//#endregion
-//#region src/smartapp/types.d.ts
 type SmartappDeviceType = 'android' | 'iOS' | 'web' | 'devtools' | 'simulator';
 type SmartappConnectType = 'usb' | 'wifi' | 'newBaiduCloud' | 'mtpaas';
 interface SmartappLaunchOptions {
@@ -495,8 +503,6 @@ interface ScreenshotOptions {
   path?: string;
   compressionLevel?: number;
 }
-//#endregion
-//#region src/smartapp/Element.d.ts
 declare class SmartappElement {
   private readonly element;
   selectors: string;
@@ -528,8 +534,6 @@ declare class SmartappElement {
   }): Promise<void>;
   screenshot(options?: ScreenshotOptions): Promise<Buffer<ArrayBuffer>>;
 }
-//#endregion
-//#region src/smartapp/Page.d.ts
 declare class SmartappPage {
   private readonly page;
   path: string;
@@ -540,8 +544,6 @@ declare class SmartappPage {
   setData(data: Record<string, unknown>): Promise<void>;
   callMethod(method: string, ...args: unknown[]): Promise<any>;
 }
-//#endregion
-//#region src/smartapp/App.d.ts
 declare class SmartappApp {
   private readonly miniProgram;
   appKey: string;
@@ -564,8 +566,6 @@ declare class SmartappApp {
   $x(_expression: string): Promise<never[]>;
   close(): Promise<void>;
 }
-//#endregion
-//#region src/smartapp/Device.d.ts
 declare class SmartappDevice {
   type: string;
   connectType: string;
@@ -597,15 +597,11 @@ declare class SmartappDevice {
   isInstall(): Promise<boolean>;
   close(): Promise<void>;
 }
-//#endregion
-//#region src/smartapp/index.d.ts
 declare function launch(options?: SmartappLaunchOptions & {
   wsEndpoint?: string;
 }): Promise<SmartappDevice>;
 declare function connect(options: Record<string, unknown>): Promise<SmartappDevice>;
 declare function devices(deviceType: string, _connectType?: string): Promise<SmartappDevicesResult>;
-//#endregion
-//#region src/platform.d.ts
 /**
  * @file 小程序自动化平台适配定义。
  */
@@ -621,8 +617,6 @@ export interface IExternalAutomatorModule {
 }
 export type NormalizedMiniprogramAutomatorPlatform = Exclude<MiniprogramAutomatorPlatform, 'baidu'>;
 export declare function normalizePlatform(platform?: MiniprogramAutomatorPlatform): NormalizedMiniprogramAutomatorPlatform;
-//#endregion
-//#region src/Launcher.d.ts
 export interface IConnectOptions {
   wsEndpoint: string;
   signal?: AbortSignal;
@@ -673,8 +667,6 @@ declare class Launcher {
   private connectTool;
   private resolveCliPath;
 }
-//#endregion
-//#region src/Automator.d.ts
 /** Automator 的实现。 */
 declare class Automator {
   Element: typeof Element;
@@ -690,8 +682,6 @@ declare class Automator {
   connect(options: IConnectOptions): Promise<unknown>;
   launch(options: ILaunchOptions): Promise<any>;
 }
-//#endregion
-//#region src/launcher/portLease.d.ts
 interface AutomatorPortLease {
   path?: string;
   port: number;
@@ -701,8 +691,6 @@ interface AutomatorPortLease {
  * @description 选择并短暂租约一个自动化端口，避免并发启动选择到同一端口。
  */
 export declare function acquireAutomatorPortLease(preferredPort?: number): Promise<AutomatorPortLease>;
-//#endregion
-//#region src/util.d.ts
 /** decodeQrCode 的方法封装。 */
 export declare function decodeQrCode(qrCode: string): Promise<string>;
 /** printQrCode 的方法封装。 */
@@ -711,8 +699,6 @@ export declare function printQrCode(content: string): Promise<void>;
 export declare function isPluginPath(p: unknown): boolean;
 /** extractPluginId 的方法封装。 */
 export declare function extractPluginId(p: unknown): string;
-//#endregion
-//#region src/index.d.ts
 export declare const SmartappAutomator: {
   connect: typeof connect;
   devices: typeof devices;
@@ -737,5 +723,4 @@ export declare const SmartappAutomator: {
     delay: typeof delay;
   };
 };
-//#endregion
-export { type AppServiceHeapUsage, type AppServiceHeapUsageOptions, Automator, type AutomatorPortLease, Connection, type ConsoleLogOptions, type ConsoleRemoteObject, Element, Launcher, MiniProgram, Native, OPERATION_TIMEOUT_CODE, OperationDiagnostics, OperationErrorCategory, OperationLifecycle, OperationStepOptions, Page, type StructuredConsoleEntry, Transport, classifyOperationError, isRecoverableOperationError, readWechatLoginState };
+export { type AppServiceHeapUsage, type AppServiceHeapUsageOptions, Automator, type AutomatorPortLease, type CDPCommandOptions, type CDPEventListener, type CDPSession, Connection, type ConsoleLogOptions, type ConsoleRemoteObject, Element, type IEventOptions, type ITouch, type ITouchEventOptions, Launcher, MiniProgram, Native, OPERATION_TIMEOUT_CODE, OperationDiagnostics, OperationErrorCategory, OperationLifecycle, OperationStepOptions, Page, type StructuredConsoleEntry, Transport, classifyOperationError, isRecoverableOperationError, readWechatLoginState };