rust-rpa 0.2.6-beta.2 → 0.2.7

package/README.md

@@ -205,7 +205,7 @@ main();
 - `setBounds(bounds)` - 设置窗口边界
 - `toJSON()` - 转为 JSON 对象
 - `captureImage(options?)` - 截图
-- `watchChanges(options?, callback)` - 监听窗口内容变化；返回 `WindowWatcher`（`stop()` / `isRunning()`），回调无参数；`stableFrames` 选项可过滤光标闪烁等瞬态变化
+- `watchChanges(options?, callback)` - 监听窗口内容变化；返回 `WindowWatcher`（`stop()` / `isRunning()` / `changeOptions()`）；启动时先建基线**不**调回调，仅在检测到相对上一帧的变化时调用 `callback(info)`（`info` 含 `changeRatio` 变化比例和 `changedPixels` 估算变化像素数）；`regions` 可指定多个逻辑像素监控区域；`minChangedPixels` 可按原图逻辑像素数控制触发门槛；`minPixelDiff` 可设置单像素最小通道差异（默认 30）过滤截图噪声
 - `recognizeText(options?)` - OCR 识别文字
 - `findText(text, options?)` - 查找文字
 - `findIcon(template, options?)` - 查找图标
@@ -591,16 +591,32 @@ if (targetWindow) {
 
 ## 更新日志
 
-### 0.2.6
+### 0.2.7
 
 #### 新功能
 
-- **Window.watchChanges 新增 `stableFrames` 选项**: 支持过滤光标闪烁等瞬态变化，仅检测真实内容变化
-  - `stableFrames: 0`（默认）- 检测到变化即触发回调，最快响应
-  - `stableFrames: N` - 需连续 N 帧与上一帧相比均有变化才触发回调
-  - 过滤光标闪烁原理：光标闪烁 ON→OFF 一次变化、OFF→OFF 无变化则计数重置，无法连续 N 帧；而真实内容变化（新消息出现）会持续与旧基线不同，连续 N 帧均有变化
-  - 推荐 `stableFrames: 2` 可过滤大多数光标闪烁
-  - 示例：`window.watchChanges({ threshold: 0.02, stableFrames: 2 }, callback)`
+- **Window.watchChanges 新增 `minChangedPixels` 参数**: 支持按原图逻辑像素数控制变化触发，与 `threshold` 为 AND 关系
+  - `minChangedPixels: 0`（默认）- 不使用此条件，仅靠 `threshold` 控制
+  - `minChangedPixels > 0` - 估算的原图逻辑像素变化数须 >= 该值才触发回调
+  - 示例：`{ threshold: 0.001, minChangedPixels: 500 }` 表示变化比例超过 0.1% **且** 至少 500 个逻辑像素变化才触发
+- **Window.watchChanges 新增 `minPixelDiff` 参数**: 单像素最小通道差异（0-255），默认 30，用于过滤截图捕获噪声
+  - `minPixelDiff: 30`（默认）- R/G/B 任一通道差值 ≥ 30 才算“变化”，有效过滤截图噪声（通常差值 1-10）
+  - `minPixelDiff: 0` - 任意微小差异都计入（最敏感，但噪声也会触发）
+  - `minPixelDiff: 1` - 任意像素差异都计入（精确字节比较）
+  - 示例：`{ threshold: 0, minChangedPixels: 2, minPixelDiff: 30 }` 过滤噪声同时保持对光标闪烁等微小变化的灵敏度
+- **Window.watchChanges 回调参数改为对象**: `callback(info)`，`info` 为 `{ changeRatio, changedPixels }`，其中 `changeRatio` 为相邻两帧像素变化比例（约 0.0–1.0），`changedPixels` 为估算的原图逻辑像素变化数；**启动首帧不触发回调**（仅建基线）；两帧缓冲区长度不一致时 `changeRatio` 为 `1`、`changedPixels` 为 `4294967295`。
+
+### 0.2.6
+
+#### 行为调整
+
+- **Window.watchChanges 启动**：首帧仅建立对比基线，**不**调用 `callback`；仅在后续轮询检测到相对上一帧的变化时才触发回调。
+
+#### 破坏性变更
+
+- **Window.watchChanges 选项**: `region` 已改为 `regions`（`CaptureRegion` 数组），可指定多个监控区域；
+- **`WindowWatcher.changeOptions(options)`**: 可按字段合并更新当前监听参数（仅传入字段覆盖，未传字段保持原值），下一轮轮询起生效；若已 `stop()` 再调用会报错。
+- **`Window.watchChanges` 回调参数**: `callback(changeRatio)`，`changeRatio` 为相邻两帧在降采样图上的像素变化比例（约 0.0–1.0）；**启动首帧不触发回调**（仅建基线）；两帧缓冲区长度不一致时为 `1`。
 
 ### 0.2.5
 
@@ -636,7 +652,7 @@ if (targetWindow) {
 
 #### 新功能
 
-- **Window.watchChanges（窗口内容变化监听）**: 后台线程降采样对比相邻帧，超过阈值才截取完整窗口图并回调；支持 `threshold`、`from`（`window`/`screen`）、`region`、`captureSize`；返回 `WindowWatcher` 可 `stop()`。
+- **Window.watchChanges（窗口内容变化监听）**: 后台线程降采样对比相邻帧，超过阈值才触发回调；支持 `threshold`、`from`（`window`/`screen`）、`regions`（多区域，逻辑像素）；返回 `WindowWatcher`，可 `stop()`、`changeOptions()` 运行时改参。
 
 ### 0.2.3
 

package/index.d.ts

@@ -249,13 +249,6 @@ export interface CaptureImageOptions {
    */
   writeFilePath?: string | null
 }
-/** 截图目标尺寸（用于窗口变化监听） */
-export interface CaptureSizeJs {
-  /** 目标宽度（像素） */
-  width: number
-  /** 目标高度（像素） */
-  height: number
-}
 /** 窗口变化监听的选项 */
 export interface WindowWatchOptionsJs {
   /**
@@ -265,34 +258,52 @@ export interface WindowWatchOptionsJs {
    * - 大于 0.0 时，仅当像素变化比例超过阈值才触发回调
    */
   threshold?: number
-  /** 图片来源：'window'（默认）或 'screen' */
-  from?: 'window' | 'screen'
-  /** 仅在指定区域检测变化（逻辑像素） */
-  region?: CaptureRegion | null
-  /** 检测到变化后传递给回调的截图目标尺寸 */
-  captureSize?: CaptureSizeJs | null
   /**
-   * 变化确认帧数，默认 0
+   * 最小变化像素数（逻辑像素），默认 0（不使用）
    *
-   * - 0 表示检测到变化即触发回调（最快响应）
-   * - 大于 0 时，需连续 N 帧与上一帧相比均有变化才触发回调
+   * - 0 表示不使用此条件，仅靠 threshold 控制
+   * - 大于 0 时，估算的原图逻辑像素变化数须 >= 该值才触发回调
+   * - 与 threshold 为 AND 关系：两者均满足时才触发
+   */
+  minChangedPixels?: number
+  /**
+   * 单像素最小通道差异（0-255），默认 30，用于过滤截图噪声
    *
-   * 适用于过滤光标闪烁等瞬态变化：光标闪烁在 ON/OFF 间交替，
-   * ON→OFF 一次变化、OFF→OFF 无变化则计数重置，无法连续 N 帧；
-   * 而真实内容变化（如新消息出现）会持续与旧基线不同，
-   * 连续 N 帧均有变化，通过确认。
-   * 推荐 stableFrames=2 可过滤大多数光标闪烁。
+   * - 仅当像素的 R/G/B 任一通道差值 >= 该值才算“变化”
+   * - 设为 0 则任意微小差异都计入（最敏感，但噪声也会触发）
+   * - 设为 1 则任意像素差异都计入（精确字节比较）
    */
-  stableFrames?: number
+  minPixelDiff?: number
+  /** 图片来源：'window'（默认）或 'screen' */
+  from?: 'window' | 'screen'
+  /** 仅在指定多个区域检测变化（逻辑像素，相对窗口）；不填或空数组表示全窗口 */
+  regions?: Array<CaptureRegion> | null
+}
+/**
+ * 窗口内容变化回调信息
+ */
+export interface WindowChangeInfo {
+  /** 降采样相邻帧对比得到的像素变化比例，约 0.0–1.0；帧尺寸不一致时为 `1` */
+  changeRatio: number
+  /** 估算的原图逻辑像素变化数；帧尺寸不一致时为 `4294967295` (u32::MAX) */
+  changedPixels: number
 }
-/** 窗口内容变化监听的回调函数签名 */
-export type WindowChangeCallback = () => void
+/**
+ * 窗口内容变化回调（启动时先采一帧建基线，不调用本回调；之后仅在检测到相对上一帧的变化时调用）
+ * @param info 变化详情，含 `changeRatio`（变化比例）和 `changedPixels`（估算变化像素数）
+ */
+export type WindowChangeCallback = (info: WindowChangeInfo) => void
 /** 窗口变化监听器句柄，用于停止监听 */
 export interface WindowWatcher {
   /** 停止监听，释放底层资源 */
   stop(): void
   /** 检查是否仍在运行 */
   isRunning(): boolean
+  /**
+   * 在监听过程中合并更新选项（仅传入的字段会覆盖当前值，未传的字段保持不变）；
+   * 下一轮轮询起生效；若已调用 stop() 则抛出错误。
+   */
+  changeOptions(options: WindowWatchOptionsJs): void
 }
 /** 窗口尺寸信息 */
 export interface WindowSize {
@@ -1308,11 +1319,11 @@ export declare class Window {
   /**
    * 监听窗口内容变化，当检测到变化时触发回调函数
    * 
-   * 底层使用降采样差异检测，仅在窗口内容发生变化时才触发回调，
-   * 资源开销远低于定时轮询截图。
+   * 底层使用降采样差异检测；启动后首帧仅建立对比基线、**不**调用 callback，
+   * 之后仅在相对上一帧检测到变化时才触发回调，资源开销远低于定时轮询截图。
    * 
    * @param options 监听选项（可选）
-   * @param callback 变化时的回调函数（无参数）
+   * @param callback 检测到相对上一帧有变化时的回调；参数 `changeRatio` 为降采样帧上估算的像素变化比例（约 0–1）
    * @returns WindowWatcher 句柄，调用 stop() 可停止监听
    * 
    * @example
@@ -1320,34 +1331,38 @@ export declare class Window {
    * // 场景 1：监听窗口变化
    * const watcher = targetWindow.watchChanges(
    *   { threshold: 0.02, from: 'window' },
-   *   () => {
-   *     console.log('窗口内容发生了变化');
+   *   (info) => {
+   *     console.log('窗口内容发生了变化', info.changeRatio, info.changedPixels);
    *   }
    * );
    * ```
    * 
    * @example
    * ```javascript
-   * // 场景 2：仅监听窗口的特定区域
+   * // 场景 2：仅监听窗口内多个区域
    * const watcher = targetWindow.watchChanges(
-   *   { 
-   *     region: { x: 100, y: 200, width: 400, height: 300 },
+   *   {
+   *     regions: [
+   *       { x: 100, y: 200, width: 400, height: 300 },
+   *       { x: 0, y: 0, width: 200, height: 80 },
+   *     ],
    *   },
-   *   () => {
-   *     console.log('指定区域内容发生了变化');
+   *   (info) => {
+   *     console.log('指定区域内容发生了变化', info.changeRatio, info.changedPixels);
    *   }
    * );
    * ```
    * 
    * @example
    * ```javascript
-   * // 场景 3：忽略光标闪烁，仅检测真实内容变化
+   * // 场景 3：提高阈值减少微小变化触发
    * const watcher = targetWindow.watchChanges(
-   *   { threshold: 0.02, stableFrames: 2 },
-   *   () => {
-   *     console.log('窗口内容发生持久变化');
+   *   { threshold: 0.02 },
+   *   (info) => {
+   *     console.log('窗口内容发生持久变化', info.changeRatio);
    *   }
    * );
+   * watcher.changeOptions({ threshold: 0.05 });
    * ```
    */
   watchChanges(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rust-rpa",
-  "version": "0.2.6-beta.2",
+  "version": "0.2.7",
   "description": "Rust-based RPA automation library for Node.js",
   "type": "commonjs",
   "main": "index.js",
@@ -67,9 +67,9 @@
     "commander": "^14.0.3"
   },
   "optionalDependencies": {
-    "@alibot/rust-rpa-win32-x64-msvc": "0.2.6-beta.2",
-    "@alibot/rust-rpa-win32-ia32-msvc": "0.2.6-beta.2",
-    "@alibot/rust-rpa-darwin-x64": "0.2.6-beta.2",
-    "@alibot/rust-rpa-darwin-arm64": "0.2.6-beta.2"
+    "@alibot/rust-rpa-win32-x64-msvc": "0.2.7",
+    "@alibot/rust-rpa-win32-ia32-msvc": "0.2.7",
+    "@alibot/rust-rpa-darwin-x64": "0.2.7",
+    "@alibot/rust-rpa-darwin-arm64": "0.2.7"
   }
 }