@weapp-vite/miniprogram-automator 1.2.23 → 1.4.0

package/README.md

@@ -16,6 +16,7 @@
 - 提供 `Launcher` 用于启动、连接和复用 DevTools 会话
 - 支持按平台选择自动化后端，默认微信，百度智能小程序提供轻量 TypeScript runtime
 - 支持截图、输入、滚动、点击、页面跳转等自动化操作
+- 对齐官方 0.13.0 的公开 `send()`、`CDP()` 和可等待断开接口
 - 默认输出现代 ESM 与完整类型声明
 - 内置二维码打印与解码辅助能力，便于配合登录、连接流程调试
 - 支持 headless 自动化启动入口
@@ -141,6 +142,93 @@ await miniProgram.flushConsole()
 
 先用 `addListener` 被动注册，再显式等待 `enableLog`，可以记录初始化期间的日志。`flushConsole()` 等待调用时已收到的错误属性检查完成；每次查询最多等待 1 秒，失败会在原参数上保留 `inspectionError`。断开连接时尚未完成的日志也会携带该诊断发布。只有宿主明确返回 CDP 命令不支持时才回退 SDK 格式；其他初始化错误仍然抛出。重复调用 `enableLog` 会刷新 Runtime 订阅，并保留已选择的格式。
 
+### 4.7 AppService 堆内存探测
+
+`getAppServiceHeapUsage({ timeout })` 通过现有 `App.CDPCommand` 调用 `Runtime.getHeapUsage`，默认超时 2500ms。支持时返回 `{ status: 'available', source: 'appservice-cdp-runtime', usedSize, totalSize }`，两个值均为字节。仅当宿主明确不支持该协议或方法时，返回 `status: 'unsupported'` 及 `protocol-unimplemented` / `method-not-found` 原因。
+
+```ts
+const heap = await miniProgram.getAppServiceHeapUsage({ timeout: 2_500 })
+if (heap.status === 'available') {
+  console.log({ usedBytes: heap.usedSize, allocatedBytes: heap.totalSize })
+}
+else {
+  console.log({ unsupported: heap.reason })
+}
+```
+
+空结果、缺失字段、字符串、负数、非有限数值或已用量超过分配量都会报错；连接超时与其他协议错误原样传播，不会转换为不支持或零内存。每次调用重新探测，不缓存旧会话的能力结果，也不主动触发 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. 主要导出
 
 | 导出                      | 说明                                     |
@@ -164,3 +252,11 @@ pnpm --filter @weapp-vite/miniprogram-automator typecheck
 
 - 仓库：https://github.com/weapp-vite/weapp-vite
 - `weapp-ide-cli`：[../weapp-ide-cli/README.md](../weapp-ide-cli/README.md)
+
+## 启动预算与取消
+
+微信 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

@@ -1,3 +1,4 @@
+import { OPERATION_TIMEOUT_CODE, OperationDiagnostics, OperationErrorCategory, OperationLifecycle, OperationStepOptions, classifyOperationError, isRecoverableOperationError, readWechatLoginState } from "./operation.mjs";
 import { EventEmitter } from "node:events";
 import WebSocket from "ws";
 import { Buffer } from "node:buffer";
@@ -31,13 +32,45 @@ declare function get(label?: string): SmartappLogger;
 declare function currentTimestamp(): number;
 declare function delay(ms: number): Promise<void>;
 //#endregion
+//#region src/appServiceHeap.d.ts
+interface AppServiceHeapUsageOptions {
+  /** 单次协议请求的超时预算，单位毫秒。 */
+  timeout?: number;
+}
+type AppServiceHeapUsage = {
+  status: 'available';
+  source: 'appservice-cdp-runtime';
+  usedSize: number;
+  totalSize: number;
+} | {
+  status: 'unsupported';
+  source: 'appservice-cdp-runtime';
+  reason: 'protocol-unimplemented' | 'method-not-found';
+};
+//#endregion
+//#region src/cdp/index.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;
+}
+//#endregion
 //#region src/Transport.d.ts
 /** 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
@@ -46,24 +79,31 @@ interface SendOptions {
 }
 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): Promise<Connection>;
+  static create(url: string, timeout?: number, signal?: AbortSignal): Promise<Connection>;
 }
 //#endregion
 //#region src/structuredConsole.d.ts
@@ -138,6 +178,8 @@ interface ITouch {
 /** ITouchEventOptions 的类型定义。 */
 interface ITouchEventOptions {
   touches?: ITouch[];
+  changedTouches?: ITouch[];
+  /** @deprecated 请使用 changedTouches，发送时会自动转换旧字段。 */
   changeTouches?: ITouch[];
 }
 /** IEventOptions 的类型定义。 */
@@ -145,6 +187,8 @@ interface IEventOptions {
   eventName: string;
   $?: string;
   touches?: ITouch[];
+  changedTouches?: ITouch[];
+  /** @deprecated 请使用 changedTouches，发送时会自动转换旧字段。 */
   changeTouches?: ITouch[];
   detail?: Record<string, any>;
 }
@@ -160,7 +204,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>;
@@ -358,8 +402,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>;
@@ -381,10 +428,13 @@ declare class MiniProgram extends EventEmitter {
   restorePluginWxMethod(pluginId: string, method: string): Promise<void>;
   evaluate(appFunction: AutomatorCallable | string, ...args: any[]): Promise<any>;
   evaluateWithOptions(appFunction: AutomatorCallable | string, options?: EvaluateOptions, ...args: any[]): Promise<any>;
+  /** 探测并读取 AppService JS 堆；明确不支持时返回原因，连接故障与无效响应继续抛出。 */
+  getAppServiceHeapUsage(options?: AppServiceHeapUsageOptions): Promise<AppServiceHeapUsage>;
   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>;
@@ -392,7 +442,7 @@ declare class MiniProgram extends EventEmitter {
   exposeFunction(name: string, bindingFunction: AutomatorCallable): Promise<void>;
   checkVersion(timeout?: number): Promise<void>;
   /**
-   * @description 等待小程序 App 域协议可用，避免返回半就绪自动化会话。
+   * @description 等待原生协议返回真实页面标识和路径，避免返回半就绪自动化会话。
    */
   waitForAppReady(timeout?: number): Promise<void>;
   screenshot(options?: IScreenshotOptions): Promise<string | undefined>;
@@ -425,7 +475,12 @@ 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;
@@ -605,11 +660,13 @@ export declare function normalizePlatform(platform?: MiniprogramAutomatorPlatfor
 //#region src/Launcher.d.ts
 export interface IConnectOptions {
   wsEndpoint: string;
+  signal?: AbortSignal;
   timeout?: number;
   platform?: MiniprogramAutomatorPlatform;
 }
 /** ILaunchOptions 的类型定义。 */
 export interface ILaunchOptions {
+  signal?: AbortSignal;
   platform?: MiniprogramAutomatorPlatform;
   cliPath?: string;
   connectType?: string;
@@ -669,6 +726,17 @@ declare class Automator {
   launch(options: ILaunchOptions): Promise<any>;
 }
 //#endregion
+//#region src/launcher/portLease.d.ts
+interface AutomatorPortLease {
+  path?: string;
+  port: number;
+  release: () => Promise<void>;
+}
+/**
+ * @description 选择并短暂租约一个自动化端口，避免并发启动选择到同一端口。
+ */
+export declare function acquireAutomatorPortLease(preferredPort?: number): Promise<AutomatorPortLease>;
+//#endregion
 //#region src/util.d.ts
 /** decodeQrCode 的方法封装。 */
 export declare function decodeQrCode(qrCode: string): Promise<string>;
@@ -705,4 +773,4 @@ export declare const SmartappAutomator: {
   };
 };
 //#endregion
-export { Automator, Connection, type ConsoleLogOptions, type ConsoleRemoteObject, Element, Launcher, MiniProgram, Native, Page, type StructuredConsoleEntry, Transport };
+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 };