rust-rpa 0.2.0-beta.3 → 0.2.0-beta.4

package/README.md

@@ -4,17 +4,19 @@
 
 ## 特性
 
-- 🚀 **高性能**: 使用 Rust 编写，追求极致速度和效率
+- 🚀 **高性能**: 使用 Rust 编写，napi-rs 绑定，追求极致速度和效率
 - 🔄 **跨平台**: 支持 Windows 和 macOS
 - 📦 **易于使用**: 简洁的面向对象 API，支持 TypeScript
 - ⚡ **非阻塞**: 异步操作不会阻塞 Node.js 事件循环
 - 🔒 **类型安全**: 完整的 TypeScript 类型定义
 - 🖱️ **输入自动化**: Mouse 和 Keyboard 类，完整的输入控制
-- 🪟 **窗口管理**: 基于 XCap 的窗口枚举和信息获取
+- 🪟 **窗口管理**: 基于 XCap 实现窗口枚举和信息获取
 - 🖥️ **多显示器支持**: Monitor 类，支持多显示器设置
-- 📸 **屏幕截图**: 支持全屏和窗口截图，多种图片格式
+- 📸 **屏幕截图**: 基于 XCap 实现全屏和窗口截图，多种图片格式（PNG/JPEG/BMP）
 - 🔑 **权限管理**: Permission 类，自动检测并弹出系统权限授权对话框
-- 🔍 **OCR 文字识别**: 基于 PP-OCRv5_mobile 模型，支持中英日文字识别及文字位置查找
+- 🔍 **OCR 文字识别**: 基于 PP-OCRv5_mobile 模型和 MNN 推理框架，支持中英日文字识别
+- 🎯 **模板匹配**: GPU 加速的图标查找功能，支持阈值和区域搜索
+- 🖼️ **图像处理**: 裁剪、缩放（Lanczos3）、灰度化等，支持 RGBA 原始数据访问
 
 ## 安装
 
@@ -50,13 +52,13 @@ rpa --help
 rpa permission --prompt
 
 # 列出所有窗口
-rpa window:list
+rpa window list
 
 # 将窗口置于最前
-rpa window:focus Chrome
+rpa window focus Chrome
 
 # 设置窗口位置和大小
-rpa window:bounds Chrome 100 100 800 600
+rpa window bounds Chrome 100 100 800 600
 
 # 截取主显示器
 rpa screenshot -o desktop.png
@@ -65,23 +67,44 @@ rpa screenshot -o desktop.png
 rpa screenshot --window Chrome -o chrome.png
 
 # 鼠标操作
-rpa mouse:position
-rpa mouse:move 500 300
-rpa mouse:click right
-rpa mouse:scroll 0 -3
+rpa mouse position
+rpa mouse move 500 300
+rpa mouse move-rel 100 50
+rpa mouse click right
+rpa mouse scroll 0 -3
 
 # 键盘操作
-rpa keyboard:type "Hello World"
-rpa keyboard:press enter
-rpa keyboard:press ctrl+c
+rpa keyboard type "Hello World"
+rpa keyboard press enter
+rpa keyboard press ctrl+c
 
 # 剪贴板
-rpa clipboard:read
-rpa clipboard:write "Hello"
-rpa clipboard:paste
+rpa clipboard read
+rpa clipboard write "Hello"
+rpa clipboard paste
+rpa clipboard paste-text "直接粘贴的文本"
+rpa clipboard paste-image screenshot.png
 
 # 列出所有显示器
-rpa monitor:list
+rpa monitor list
+
+# OCR 文字识别
+rpa monitor recognize-text
+rpa monitor find-text "确定"
+rpa window find-text Chrome "搜索"
+
+# 图片处理
+rpa image info screenshot.png
+rpa image crop screenshot.png 0 0 800 600 -o cropped.png
+rpa image find-text screenshot.png "文字"
+
+# 快捷命令（顶层）
+rpa click right
+rpa move 500 300
+rpa type "Hello"
+rpa press enter
+rpa paste
+rpa pause 1000
 ```
 
 所有命令支持 `--help` 查看详细用法，如 `rpa screenshot --help`。
@@ -150,41 +173,11 @@ async function main() {
 main();
 ```
 
-### TypeScript
-
-```typescript
-import { Window, Monitor, Mouse, Keyboard } from 'rust-rpa';
-
-async function main(): Promise<void> {
-  try {
-    // 获取所有窗口
-    const windows = Window.all();
-    console.log(`Found ${windows.length} windows`);
-    
-    windows.forEach((win) => {
-      console.log(`${win.appName()}: ${win.title()}`);
-    });
-    
-    // 截图
-    const monitors = Monitor.all();
-    const image = await monitors[0].captureImage();
-    
-    // 输入控制
-    await Mouse.moveTo(100, 100);
-    await Keyboard.typeText('Hello!');
-  } catch (error) {
-    console.error('Error:', error);
-  }
-}
-
-main();
-```
-
 ## API
 
 ### Window 类
 
-窗口管理类，基于 XCap 实现。
+窗口管理类。
 
 #### 静态方法
 
@@ -222,9 +215,9 @@ const windows = Window.all();
 - `recognizeText(): Promise<TextRecognitionResult[]>` - 识别窗口截图中的文字（先截图 autoSize=true，再执行 OCR）
 - `findText(text, options?): Promise<TextRecognitionResult | null>` - 在窗口截图中查找指定文字，找到返回位置信息，未找到返回 null（先截图 autoSize=true，再执行 OCR）；`options.regions` 可指定查找区域列表以提升性能
 - `waitText(text, options?): Promise<TextRecognitionResult>` - 等待指定文字出现，超时抛出错误；`options.timeout` 指定等待时间（默认 3000ms），`options.regions` 可指定查找区域
-- `waitIcon(template, options?): Promise<MatchResult>` - 等待指定图标出现，超时抛出错误；`options.timeout` 指定等待时间（默认 3000ms），`options.regions` 可指定查找区域
+- `waitIcon(template, options?): Promise<MatchResult>` - 等待指定图标出现，超时抛出错误；`options.timeout` 指定等待时间（默认 3000ms），`options.regions` 可指定查找区域，`options.threshold` 可指定匹配阈值（默认 0.8）
 - `clickText(text, options?): Promise<void>` - 点击指定文字，先等待文字出现，然后点击文字中心点
-- `clickIcon(template, options?): Promise<void>` - 点击指定图标，先等待图标出现，然后点击图标中心点
+- `clickIcon(template, options?): Promise<void>` - 点击指定图标，先等待图标出现，然后点击图标中心点；`options.threshold` 可指定匹配阈值（默认 0.8）
 
 ### Monitor 类
 
@@ -256,9 +249,9 @@ const primary = monitors.find(m => m.isPrimary());
 - `recognizeText(): Promise<TextRecognitionResult[]>` - 识别显示器截图中的文字（先截图 autoSize=true，再执行 OCR）
 - `findText(text, options?): Promise<TextRecognitionResult | null>` - 在显示器截图中查找指定文字，找到返回位置信息，未找到返回 null（先截图 autoSize=true，再执行 OCR）；`options.regions` 可指定查找区域列表以提升性能
 - `waitText(text, options?): Promise<TextRecognitionResult>` - 等待指定文字出现，超时抛出错误；`options.timeout` 指定等待时间（默认 3000ms），`options.regions` 可指定查找区域
-- `waitIcon(template, options?): Promise<MatchResult>` - 等待指定图标出现，超时抛出错误；`options.timeout` 指定等待时间（默认 3000ms），`options.regions` 可指定查找区域
+- `waitIcon(template, options?): Promise<MatchResult>` - 等待指定图标出现，超时抛出错误；`options.timeout` 指定等待时间（默认 3000ms），`options.regions` 可指定查找区域，`options.threshold` 可指定匹配阈值（默认 0.8）
 - `clickText(text, options?): Promise<void>` - 点击指定文字，先等待文字出现，然后点击文字中心点
-- `clickIcon(template, options?): Promise<void>` - 点击指定图标，先等待图标出现，然后点击图标中心点
+- `clickIcon(template, options?): Promise<void>` - 点击指定图标，先等待图标出现，然后点击图标中心点；`options.threshold` 可指定匹配阈值（默认 0.8）
 
 ### ImageData 类
 
@@ -286,15 +279,15 @@ const primary = monitors.find(m => m.isPrimary());
 **图像处理**
 
 - `crop(x, y, width, height): Promise<ImageData>` - 裁剪图像
-- `resize(width, height): Promise<ImageData>` - 缩放图像（使用 Lanczos3 高质量算法）
-- `grayscale(): Promise<ImageData>` - 转换为灰度图（使用标准加权算法：0.299R + 0.587G + 0.114B）
-- `findIcon(template, options?): Promise<MatchResult>` - 查找模板图标（模板匹配）
-- `recognizeText(): Promise<TextRecognitionResult[]>` - 识别图片中的文字（OCR）
-- `findText(text): Promise<TextRecognitionResult | null>` - 查找指定文字，找到返回位置信息，未找到返回 null（OCR）
+- `resize(width, height): Promise<ImageData>` - 缩放图像
+- `grayscale(): Promise<ImageData>` - 转换为灰度图
+- `findIcon(template, options?): Promise<MatchResult>` - 查找模板图标
+- `recognizeText(): Promise<TextRecognitionResult[]>` - 识别图片中的文字
+- `findText(text): Promise<TextRecognitionResult | null>` - 查找指定文字
 
 **数据访问**
 
-- `getRawData(): Buffer` - 获取原始像素数据（RGBA 格式，每像素 4 字节）
+- `getRawData(): Buffer` - 获取原始像素数据
 - `metadata(): ImageMetadata` - 获取图片元信息
 
 **findIcon 参数：**
@@ -372,6 +365,7 @@ interface CaptureImageOptions {
 #### 静态方法
 
 - `Mouse.moveTo(x, y, duration?): Promise<void>` - 移动鼠标到指定坐标。**duration** 可选，移动动画持续时间（秒），默认为 0（瞬间移动）。如果设置 > 0，鼠标将以平滑动画的方式移动到目标点，动画过程中会触发 mouseMove 事件
+- `Mouse.moveRel(dx, dy, duration?): Promise<void>` - 相对移动鼠标。**dx** X 轴偏移量（正数向右，负数向左）；**dy** Y 轴偏移量（正数向下，负数向上）；**duration** 可选，移动动画持续时间（秒），默认为 0
 - `Mouse.click(button?): Promise<void>` - 点击鼠标。**button** 可选，可用枚举 `MouseButton.Left` / `MouseButton.Right` 或字符串 `'left'` / `'right'` 等，默认左键
 - `Mouse.doubleClick(button?): Promise<void>` - 双击鼠标，button 同上
 - `Mouse.down(button?): Promise<void>` - 按下鼠标按钮，button 同上
@@ -595,6 +589,7 @@ const { Mouse, MouseButton, Keyboard, Key } = require('rust-rpa');
 // 鼠标操作
 await Mouse.moveTo(100, 200);              // 瞬间移动鼠标
 await Mouse.moveTo(100, 200, 0.5);         // 平滑动画移动，持续 0.5 秒
+await Mouse.moveRel(50, 30);               // 相对移动（从当前位置向右 50、向下 30）
 await Mouse.click(MouseButton.Left);       // 左键点击
 await Mouse.click(MouseButton.Right);      // 右键点击
 await Mouse.doubleClick();                 // 双击
@@ -711,107 +706,6 @@ interface TextRecognitionResult {
 }
 ```
 
-> **注意**: OCR 功能需要预先下载模型文件到 `models/` 目录下。模型文件分别为:
-> - `PP-OCRv5_mobile_det.mnn` — 文字检测模型（4.7M）
-> - `PP-OCRv5_mobile_rec.mnn` — 文字识别模型（16M）
-> - `ppocr_keys_v5.txt` — 字符集
-
-
-
-// 方式 1: 从截图获取图片
-const monitors = Monitor.all();
-const screenshot = await monitors[0].captureImage();
-
-// 方式 2: 从文件加载图片
-const image = await ImageData.fromFile('input.png');
-
-// 方式 3: 从 Buffer 加载图片
-const buffer = fs.readFileSync('input.png');
-const imageFromBuffer = await ImageData.fromBuffer(buffer);
-
-// 缩放图片
-const resized = await image.resize(800, 600);
-
-// 裁剪图片
-const cropped = await image.crop(100, 100, 400, 300);
-
-// 转换为灰度图
-const grayscale = await image.grayscale();
-
-// 保存图片（自动根据扩展名识别格式）
-await resized.toFile('output.png');      // 保存为 PNG
-await grayscale.toFile('gray.jpg');      // 保存为 JPEG
-await cropped.toFile('cropped.bmp');     // 保存为 BMP
-
-// 转换为 Buffer（用于进一步处理）
-const pngBuffer = await image.toPng();
-fs.writeFileSync('screenshot.png', pngBuffer);
-
-const jpegBuffer = await image.toJpeg();
-fs.writeFileSync('screenshot.jpg', jpegBuffer);
-
-// 获取原始像素数据
-const rawData = image.getRawData();  // Buffer，RGBA 格式
-console.log(`Data size: ${rawData.length} bytes`);
-console.log(`First pixel: R=${rawData[0]}, G=${rawData[1]}, B=${rawData[2]}, A=${rawData[3]}`);
-
-// 获取图片元信息
-const meta = image.metadata();
-console.log(`Size: ${meta.width}x${meta.height}`);
-console.log(`Channels: ${meta.channels}, Data: ${meta.dataSize} bytes`);
-
-// 链式操作
-const processed = await ImageData.fromFile('input.png')
-  .then(img => img.resize(800, 600))
-  .then(img => img.grayscale())
-  .then(img => img.crop(100, 100, 400, 300));
-await processed.toFile('processed.png');
-
-// 查找图标（模板匹配）
-const template = await ImageData.fromFile('icon.png');
-
-// 使用默认参数（threshold=0.8，全图搜索）
-const result = await image.findIcon(template);
-
-if (result.found) {
-  console.log(`找到匹配！`);
-  console.log(`  相似度: ${(result.score * 100).toFixed(2)}%`);
-  console.log(`  位置: (${result.x}, ${result.y})`);
-} else {
-  console.log('未找到匹配');
-}
-
-// 自定义阈值
-const result1 = await image.findIcon(template, { threshold: 0.9 });
-
-// 在指定区域内查找
-const result2 = await image.findIcon(template, {
-  threshold: 0.8,
-  regions: [
-    { x: 0, y: 0, width: 800, height: 600 }  // 只在左上角区域搜索
-  ]
-});
-```
-
-更多示例请查看 `examples/` 和 `test/` 目录：
-
-```bash
-# 运行截屏示例
-node examples/screenshot-demo.js
-
-# 运行窗口列表示例
-node examples/list-windows.js
-
-# 运行剪贴板示例
-node examples/clipboard-demo.js
-
-# 运行图像处理示例
-node examples/image-processing-demo.js
-
-# 运行测试
-npm test
-```
-
 ## 平台支持
 
 | 平台 | 架构 | 状态 | 备注 |
@@ -882,6 +776,17 @@ npm test
   - `Monitor.waitIcon(template, options?)` - 等待指定图标出现，超时抛出错误
   - `Monitor.clickText(text, options?)` - 点击指定文字
   - `Monitor.clickIcon(template, options?)` - 点击指定图标
+- **Mouse 类增强**: 新增 `moveRel()` 方法
+  - `Mouse.moveRel(dx, dy, duration?)` - 基于当前鼠标位置进行相对移动
+  - 支持可选的 `duration` 参数实现平滑动画移动
+- **CLI 命令增强**: 新增多个便捷命令
+  - `rpa mouse move-rel <dx> <dy>` - 相对移动鼠标
+  - `rpa clipboard paste-text` / `rpa clipboard paste-image` - 粘贴文本/图片并自动恢复剪贴板
+  - `rpa image find-text` / `rpa image recognize-text` - 图片 OCR 操作
+  - 顶层快捷命令: `rpa click`, `rpa move`, `rpa type`, `rpa press`, `rpa paste`, `rpa pause`
+- **npm 包优化**: 子模块迁移至 `@alibot` scoped package
+  - 更清晰的包命名空间管理
+  - 自动同步子模块版本与主包版本
 
 #### BREAKCHANGE
 
@@ -889,15 +794,13 @@ npm test
   - 现在默认自动将图像缩放到逻辑像素尺寸，与 `getBounds()`/`getSize()` 返回的坐标一致
   - 如需物理像素图像，需显式传入 `autoSize: false`
   - 影响范围：所有依赖截图尺寸的逻辑（OCR、模板匹配等）现在默认使用逻辑坐标
+  - rpa部分命令简化
 
 #### 技术详情
 
-- 使用 `ocr-rs` crate 提供 PaddleOCR 功能
 - 使用 MNN 推理框架，提供高性能本地推理
 - 支持 GPU 加速（如果可用）
-- 模型文件需要自行下载放置在 `models/` 目录
-
-## 更新日志
+- OCR 模型内置于 npm 包中，开箱即用
 
 ### 0.1.7
 

package/bin/rpa.js

@@ -153,6 +153,13 @@ mouse.command('move').description('移动鼠标到指定坐标')
     console.log(c.green(`鼠标已移动到 (${x}, ${y})`));
   });
 
+mouse.command('move-rel').description('相对移动鼠标')
+  .argument('<dx>', 'X 轴偏移量').argument('<dy>', 'Y 轴偏移量')
+  .action(async (dx, dy) => {
+    await Mouse.moveRel(+dx, +dy);
+    console.log(c.green(`鼠标已相对移动 (${dx}, ${dy})`));
+  });
+
 mouse.command('click').description('点击鼠标')
   .argument('[button]', '按钮 (left/right/middle)', 'left')
   .option('--double', '双击')

package/index.d.ts

@@ -45,6 +45,8 @@ export interface WaitOptions {
   regions?: Array<MatchRegion>
   /** 等待超时时间（毫秒），默认 3000 */
   timeout?: number
+  /** 匹配阈值 (0.0-1.0)，低于此值视为未找到，默认 0.8（仅用于 waitIcon/clickIcon） */
+  threshold?: number
 }
 /** 图标匹配结果 */
 export interface MatchResult {
@@ -196,6 +198,13 @@ export declare class Mouse {
    * @param duration - 可选，移动动画持续时间（秒）。默认为 0，表示瞬间移动。如果设置 > 0，鼠标将以平滑动画的方式移动到目标点
    */
   static moveTo(x: number, y: number, duration?: number | null): Promise<void>
+  /**
+   * 相对移动鼠标
+   * @param dx - X 轴偏移量（正数向右，负数向左）
+   * @param dy - Y 轴偏移量（正数向下，负数向上）
+   * @param duration - 可选，移动动画持续时间（秒）。默认为 0，表示瞬间移动
+   */
+  static moveRel(dx: number, dy: number, duration?: number | null): Promise<void>
   /** 点击鼠标按钮。button 可选，可用 MouseButton.Left / 'left' 等，默认左键 */
   static click(button?: MouseButtonType | null): Promise<void>
   /** 双击鼠标按钮。button 取值同 click */

package/package.json

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