rust-rpa 0.2.3 → 0.2.5

package/README.md

@@ -10,7 +10,8 @@
 - ⚡ **非阻塞**: 异步操作不会阻塞 Node.js 事件循环
 - 🔒 **类型安全**: 完整的 TypeScript 类型定义
 - 🖱️ **输入自动化**: Mouse 和 Keyboard 类，完整的输入控制
-- 🪟 **窗口管理**: 基于 XCap 实现窗口枚举和信息获取
+- 📑 **窗口管理**: 基于 XCap 实现窗口枚举和信息获取
+- 👁️ **窗口内容监听**: `Window.watchChanges()` 降采样差异检测，内容变化时再截图，低开销监听 UI 变化
 - 🖥️ **多显示器支持**: Monitor 类，支持多显示器设置
 - 📸 **屏幕截图**: 基于 XCap 实现全屏和窗口截图，多种图片格式（PNG/JPEG/BMP）
 - 🔑 **权限管理**: Permission 类，自动检测并弹出系统权限授权对话框
@@ -121,11 +122,13 @@ rpa pause 1000
 - `image-processing-demo.js` - 图像处理功能演示
 - `find-icon-demo.js` - 完整的 findIcon 功能演示
 - `find-icon-basic.js` - findIcon 基础用法示例
+- `window-watch-changes-demo.js` - 监听窗口内容变化（`watchChanges`），可选 `chrome` / `ding` / `qianniu`
 
 运行示例：
 ```bash
 node examples/permission-demo.js
 node examples/list-windows.js
+node examples/window-watch-changes-demo.js chrome
 ```
 
 ## 使用方法
@@ -202,6 +205,7 @@ main();
 - `setBounds(bounds)` - 设置窗口边界
 - `toJSON()` - 转为 JSON 对象
 - `captureImage(options?)` - 截图
+- `watchChanges(options?, callback)` - 监听窗口内容变化；返回 `WindowWatcher`（`stop()` / `isRunning()`），回调收到变化后的 `ImageData` 或 `null`（见 `sendImage` 选项）
 - `recognizeText(options?)` - OCR 识别文字
 - `findText(text, options?)` - 查找文字
 - `findIcon(template, options?)` - 查找图标
@@ -587,6 +591,42 @@ if (targetWindow) {
 
 ## 更新日志
 
+### 0.2.5
+
+#### 改进
+
+- **Window.watchChanges 优化**: `threshold` 参数默认值改为 `0.0`，并优化为 `0` 时跳过图像对比
+  - `threshold: 0`（默认）- 跳过像素对比，每次轮询直接触发回调，最低延迟
+  - `threshold > 0` - 执行降采样对比，变化比例超过阈值才触发回调
+  - 适用于已知窗口会变化、需要立即获取截图的场景
+
+### 0.2.5
+
+#### 新功能
+
+- **findText / waitText / clickText 新增 `index` 参数**: 支持选择第几个匹配的文字结果
+  - `index` 默认为 `0`，返回第一个匹配结果
+  - 正数表示第 n 个（从 0 开始）：`index: 1` 返回第二个
+  - 负数表示倒数第 n 个：`index: -1` 返回最后一个，`index: -2` 返回倒数第二个
+  - 超出匹配数量范围时返回 `null`
+  - 适用场景：页面中存在多个相同文字，需要点击特定位置
+  - 示例：`findText('确定', { index: 1 })` 查找第二个「确定」，`clickText('确定', { index: -2 })` 点击倒数第二个「确定」
+
+#### 类型定义更新
+
+- `FindTextOptions` 新增 `index?: number` 字段
+- `WindowFindTextOptions` 新增 `index?: number` 字段
+- `MonitorFindTextOptions` 新增 `index?: number` 字段
+- `WindowWaitOptions` 新增 `index?: number` 字段
+- `MonitorWaitOptions` 新增 `index?: number` 字段
+- `WaitOptions` 新增 `index?: number` 字段
+
+### 0.2.4
+
+#### 新功能
+
+- **Window.watchChanges（窗口内容变化监听）**: 后台线程降采样对比相邻帧，超过阈值才截取完整窗口图并回调；支持 `threshold`、`from`（`window`/`screen`）、`region`、`captureSize`、`sendImage`；返回 `WindowWatcher` 可 `stop()`。
+
 ### 0.2.3
 
 #### 修复

package/index.d.ts

@@ -60,6 +60,8 @@ export interface FindTextOptions {
   regions?: Array<MatchRegion>
   /** 排除文字，若同一行中包含此文字则排除该匹配结果 */
   notText?: string
+  /** 匹配索引，默认为 0（第一个匹配）。负数表示倒数：-1 最后一个，-2 倒数第二个 */
+  index?: number
 }
 /** 文字查找选项（Window 专用） */
 export interface WindowFindTextOptions {
@@ -73,6 +75,8 @@ export interface WindowFindTextOptions {
    * - `'screen'`：截取窗口所在显示器的整屏
    */
   from?: 'window' | 'screen'
+  /** 匹配索引，默认为 0（第一个匹配）。负数表示倒数：-1 最后一个，-2 倒数第二个 */
+  index?: number
 }
 /** 文字查找选项（Monitor 专用） */
 export interface MonitorFindTextOptions {
@@ -80,6 +84,8 @@ export interface MonitorFindTextOptions {
   regions?: Array<MatchRegion>
   /** 排除文字，若同一行中包含此文字则排除该匹配结果 */
   notText?: string
+  /** 匹配索引，默认为 0（第一个匹配）。负数表示倒数：-1 最后一个，-2 倒数第二个 */
+  index?: number
 }
 /** 文字识别选项（ImageData 使用） */
 export interface RecognizeTextOptions {
@@ -118,6 +124,8 @@ export interface WindowWaitOptions {
    * - `'screen'`：截取窗口所在显示器的整屏
    */
   from?: 'window' | 'screen'
+  /** 匹配索引，默认为 0（第一个匹配）。负数表示倒数：-1 最后一个，-2 倒数第二个（仅用于 waitText/clickText） */
+  index?: number
 }
 /** 等待选项（Monitor 专用） */
 export interface MonitorWaitOptions {
@@ -129,6 +137,8 @@ export interface MonitorWaitOptions {
   threshold?: number
   /** 排除文字，若同一行中包含此文字则排除该匹配结果（仅用于 waitText/clickText） */
   notText?: string
+  /** 匹配索引，默认为 0（第一个匹配）。负数表示倒数：-1 最后一个，-2 倒数第二个（仅用于 waitText/clickText） */
+  index?: number
 }
 /** 等待选项（兼容旧代码，与 WindowWaitOptions 相同） */
 export interface WaitOptions {
@@ -146,6 +156,8 @@ export interface WaitOptions {
    * - `'screen'`：截取窗口所在显示器的整屏
    */
   from?: 'window' | 'screen'
+  /** 匹配索引，默认为 0（第一个匹配）。负数表示倒数：-1 最后一个，-2 倒数第二个（仅用于 waitText/clickText） */
+  index?: number
 }
 /** 图标匹配结果 */
 export interface MatchResult {
@@ -237,6 +249,40 @@ export interface CaptureImageOptions {
    */
   writeFilePath?: string | null
 }
+/** 截图目标尺寸（用于窗口变化监听） */
+export interface CaptureSizeJs {
+  /** 目标宽度（像素） */
+  width: number
+  /** 目标高度（像素） */
+  height: number
+}
+/** 窗口变化监听的选项 */
+export interface WindowWatchOptionsJs {
+  /**
+   * 变化检测的灵敏度阈值 (0.0-1.0)，默认 0.0
+   *
+   * - 0.0 表示跳过对比，每次轮询都触发回调（最敏感，最低延迟）
+   * - 大于 0.0 时，仅当像素变化比例超过阈值才触发回调
+   */
+  threshold?: number
+  /** 图片来源：'window'（默认）或 'screen' */
+  from?: 'window' | 'screen'
+  /** 仅在指定区域检测变化（逻辑像素） */
+  region?: CaptureRegion | null
+  /** 检测到变化后传递给回调的截图目标尺寸 */
+  captureSize?: CaptureSizeJs | null
+  /** 是否在回调中传递截图图像，默认 true */
+  sendImage?: boolean
+}
+/** 窗口内容变化监听的回调函数签名 */
+export type WindowChangeCallback = (image: ImageData | null) => void
+/** 窗口变化监听器句柄，用于停止监听 */
+export interface WindowWatcher {
+  /** 停止监听，释放底层资源 */
+  stop(): void
+  /** 检查是否仍在运行 */
+  isRunning(): boolean
+}
 /** 窗口尺寸信息 */
 export interface WindowSize {
   /** 窗口宽度 */
@@ -1248,6 +1294,64 @@ export declare class Window {
    * ```
    */
   clickIcon(template: ImageData, options?: WindowWaitOptions | null): Promise<ClickResult>
+  /**
+   * 监听窗口内容变化，当检测到变化时自动截取最新截图并传递给回调函数
+   * 
+   * 底层使用降采样差异检测，仅在窗口内容发生变化时才截取完整图像，
+   * 资源开销远低于定时轮询截图。
+   * 
+   * @param options 监听选项（可选）
+   * @param callback 变化时的回调函数，sendImage=true 时接收 ImageData，否则接收 null
+   * @returns WindowWatcher 句柄，调用 stop() 可停止监听
+   * 
+   * @example
+   * ```javascript
+   * // 场景 1：需要获取变化后的截图
+   * const watcher = targetWindow.watchChanges(
+   *   { threshold: 0.02, from: 'window' },
+   *   (image) => {
+   *     console.log(`窗口变化，新截图: ${image.width}x${image.height}`);
+   *     sendToExternalService(image);
+   *   }
+   * );
+   * ```
+   * 
+   * @example
+   * ```javascript
+   * // 场景 2：只需要知道窗口有变化，不需要截图（更低开销）
+   * const watcher = targetWindow.watchChanges(
+   *   { sendImage: false },
+   *   (image) => {
+   *     console.log('窗口内容发生了变化');
+   *     onWindowChanged();
+   *   }
+   * );
+   * ```
+   * 
+   * @example
+   * ```javascript
+   * // 场景 3：仅监听窗口的特定区域
+   * const watcher = targetWindow.watchChanges(
+   *   { 
+   *     region: { x: 100, y: 200, width: 400, height: 300 },
+   *     captureSize: { width: 800, height: 600 },
+   *     sendImage: true
+   *   },
+   *   (image) => {
+   *     processScreenshot(image);
+   *   }
+   * );
+   * 
+   * // 停止监听
+   * setTimeout(() => {
+   *   watcher.stop();
+   * }, 60000);
+   * ```
+   */
+  watchChanges(
+    options: WindowWatchOptionsJs | null | undefined,
+    callback: WindowChangeCallback
+  ): WindowWatcher
 }
 /** Clipboard 类 - 剪贴板控制 */
 export declare class Clipboard {

package/index.js

@@ -10,12 +10,24 @@ const { join } = require('path')
 // 自动设置 OCR 模型路径，指向包内的 models/ 目录
 // 优先使用用户自定义路径（通过环境变量 RPA_OCR_MODELS），否则使用包内路径
 if (!process.env.RPA_OCR_MODELS) {
-  const packageModelsDir = join(__dirname, 'models')
-  if (existsSync(packageModelsDir)) {
-    process.env.RPA_OCR_MODELS = packageModelsDir
+  // electron打包后路径
+  const dirs = process.resourcesPath ? [
+    join(process.resourcesPath, 'app.asar.unpacked', 'node_modules', 'rust-rpa', 'models'),
+    // 备用路径：app/node_modules/rust-rpa/models
+    join(process.resourcesPath, 'app', 'node_modules', 'rust-rpa', 'models'),
+    join(process.resourcesPath, 'node_modules', 'rust-rpa', 'models'),
+  ] : [];
+  dirs.push(join(process.cwd(), 'node_modules', 'rust-rpa', 'models'))
+  dirs.push(join(__dirname, 'models'));
+  for (const dir of dirs) {
+    if (existsSync(dir)) {
+      process.env.RPA_OCR_MODELS = dir
+      break
+    }
   }
 }
 
+
 const { platform, arch } = process
 
 let nativeBinding = null

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rust-rpa",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "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.3",
-    "@alibot/rust-rpa-win32-ia32-msvc": "0.2.3",
-    "@alibot/rust-rpa-darwin-x64": "0.2.3",
-    "@alibot/rust-rpa-darwin-arm64": "0.2.3"
+    "@alibot/rust-rpa-win32-x64-msvc": "0.2.5",
+    "@alibot/rust-rpa-win32-ia32-msvc": "0.2.5",
+    "@alibot/rust-rpa-darwin-x64": "0.2.5",
+    "@alibot/rust-rpa-darwin-arm64": "0.2.5"
   }
 }