# simple-rpa-win

**Repository Path**: qty_java/simple-rpa-win

## Basic Information

- **Project Name**: simple-rpa-win
- **Description**: 轻量级Windows自动化工具客户端，基于RPA技术实现桌面任务自动化，开源易用，适合个人与企业高效办公。
- **Primary Language**: C#
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-08
- **Last Updated**: 2026-07-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

Based on the code map provided, I can see this is a Windows desktop automation agent project using .NET 8.0. Let me create a comprehensive README based on the code structure and components identified:

# Simple RPA Win

简体中文 | [English](#english)

## 项目简介

Simple RPA Win 是一个基于 Windows 平台的桌面自动化代理程序（Agent），通过 WebSocket 协议提供远程控制能力。该项目利用 Microsoft UI Automation (UIA) 技术实现对 Windows 桌面应用程序的自动化控制，支持窗口管理、控件操作、OCR 文字识别等功能。

## 技术栈

- **.NET 8.0** - 运行时环境
- **FlaUI** - UI 自动化框架（支持 UIA2 和 UIA3）
- **Windows OCR** - 文字识别引擎
- **WebSocket** - 实时通信协议
- **ASP.NET Core** - 宿主框架

## 核心功能

### 1. 窗口管理

| 命令 | 说明 |
|------|------|
| `window.list` | 列出当前桌面会话中的顶级窗口 |
| `window.find` | 按标题关键词或进程名称查找窗口 |
| `window.activate` | 激活指定窗口 |
| `window.wait` | 等待窗口出现 |
| `window.minimize` | 最小化指定窗口 |
| `window.maximize` | 最大化指定窗口 |

### 2. 控件操作

| 命令 | 说明 |
|------|------|
| `tree.snapshot` | 获取指定窗口的控件树快照 |
| `element.find` | 按定位器查找控件 |
| `element.invoke` | 通过 InvokePattern 调用控件 |
| `element.click` | 点击控件（优先 Pattern，失败后坐标兜底）|
| `element.hover` | 移动鼠标到控件中心 |
| `element.setValue` | 写入控件值（优先 ValuePattern，失败后剪贴板兜底）|
| `element.getValue` | 读取控件值 |
| `element.getText` | 读取控件文本 |

### 3. 输入控制

| 命令 | 说明 |
|------|------|
| `input.type` | 向当前焦点输入文本 |
| `input.paste` | 向当前焦点粘贴文本 |
| `input.click` | 在屏幕坐标处左键单击 |
| `input.move` | 移动鼠标到屏幕坐标 |
| `input.doubleClick` | 在屏幕坐标处左键双击 |
| `input.rightClick` | 在屏幕坐标处右键单击 |
| `input.scroll` | 在屏幕坐标处滚动滚轮 |
| `input.hotkey` | 执行组合快捷键 |

### 4. 应用管理

| 命令 | 说明 |
|------|------|
| `process.list` | 列出当前系统进程 |
| `app.start` | 按可执行路径启动应用程序 |
| `app.kill` | 按进程名称终止应用程序 |
| `app.locate` | 自动搜索应用可执行文件路径 |
| `app.ensure` | 确保应用运行并激活到前台 |

### 5. OCR 识别

| 命令 | 说明 |
|------|------|
| `element.findText` | 通过 OCR 识别在窗口中查找文字，支持自动点击 |
| `ocr.recognizeWindow` | 对窗口区域进行全量 OCR 识别 |

### 6. 验证等待

| 命令 | 说明 |
|------|------|
| `verify.waitText` | 等待指定窗口控件树中出现文本 |
| `verify.waitElement` | 等待指定控件出现 |

### 7. 屏幕操作

| 命令 | 说明 |
|------|------|
| `screen.capture` | 截取当前桌面屏幕 |
| `screen.cleanup` | 删除截图目录中的所有截图文件 |

### 8. 文件操作

| 命令 | 说明 |
|------|------|
| `file.readText` | 受限读取文本文件内容 |

## 控件定位器

项目支持多种控件定位方式：

```csharp
public class ElementLocatorModel
{
    public string? WindowId { get; set; }        // 窗口 ID
    public string? WindowTitle { get; set; }      // 窗口标题
    public string? ElementId { get; set; }       // 元素 ID
    public string? RuntimeId { get; set; }      // 运行时 ID
    public string? AutomationId { get; set; }    // 自动化 ID
    public string? Name { get; set; }           // 控件名称
    public NameMatchKind NameMatch { get; set; } // 名称匹配方式
    public string? ControlType { get; set; }    // 控件类型
    public string? ClassName { get; set; }      // 类名
    public string? Path { get; set; }           // 路径
    public int? Index { get; set; }             // 索引
    public string? NearName { get; set; }       // 邻近名称
    public bool HoverBeforeFind { get; set; }   // 查找前悬停
}
```

## 配置说明

配置文件：`appsettings.json`

```json
{
  "Agent": {
    "ListenUrl": "http://127.0.0.1:5057",
    "DefaultMaxDepth": 8,
    "DefaultMaxElements": 500,
    "DefaultTimeoutMs": 10000,
    "ActionDelayMs": 150,
    "RestoreClipboardAfterPaste": true,
    "MaximumTextLength": 4000,
    "ScreenshotDirectory": "C:\\rag\\images",
    "LogDirectory": "C:\\rag\\logs",
    "UiaInitializationTimeoutMs": 8000,
    "WebSocketServerUrl": "",
    "WebSocketReconnectSeconds": 5,
    "WebSocketHeartbeatSeconds": 30
  }
}
```

### 配置项说明

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| ListenUrl | http://127.0.0.1:5057 | 本地监听地址 |
| DefaultMaxDepth | 8 | 控件树默认最大深度 |
| DefaultMaxElements | 500 | 控件树默认最大元素数 |
| DefaultTimeoutMs | 10000 | 默认超时时间（毫秒）|
| ActionDelayMs | 150 | 操作延迟时间 |
| ScreenshotDirectory | C:\rag\images | 截图保存目录 |
| LogDirectory | C:\rag\logs | 日志目录 |
| WebSocketServerUrl | - | WebSocket 服务器地址 |
| WebSocketReconnectSeconds | 5 | 重连间隔（秒）|
| WebSocketHeartbeatSeconds | 30 | 心跳间隔（秒）|

## 编译运行

### 环境要求

- Windows 10/11 或 Windows Server 2019+
- .NET 8.0 SDK
- Visual Studio 2022 或更高版本（推荐）

### 编译步骤

```bash
# 克隆项目
git clone https://gitee.com/qty_java/simple-rpa-win.git
cd simple-rpa-win

# 编译项目
dotnet build src/Simple.Automation.Agent/Simple.Automation.Agent.csproj -c Release
```

### 运行

```bash
# 运行代理程序
dotnet src/Simple.Automation.Agent/bin/Release/net8.0-windows/win-x64/Simple.Automation.Agent.dll
```

或直接运行编译后的可执行文件：
```
src\Simple.Automation.Agent\bin\Release\net8.0-windows\win-x64\Simple.Automation.Agent.exe
```

## 通信协议

代理程序通过 WebSocket 与客户端通信，支持以下消息格式：

### 请求消息

```json
{
  "type": "command",
  "id": "unique-id",
  "command": "window.list",
  "args": {}
}
```

### 响应消息

```json
{
  "type": "result",
  "id": "unique-id",
  "command": "window.list",
  "success": true,
  "message": "成功",
  "data": [...]
}
```

### 批量执行

```json
{
  "type": "batch",
  "payload": {
    "commands": [
      { "command": "app.start", "args": { "filePath": "notepad.exe" } },
      { "command": "window.wait", "args": { "titleKeyword": "无标题" } }
    ],
    "stopOnFailure": true,
    "minDelayMs": 0,
    "maxDelayMs": 2000
  }
}
```

## 项目结构

```
simple-rpa-win/
├── src/
│   └── Simple.Automation.Agent/
│       ├── Commands/                    # 命令处理
│       │   ├── CommandDispatcher.cs    # 命令分发器
│       │   └── Handlers/               # 命令处理器
│       ├── Common/
│       │   ├── Dtos/                   # 数据传输对象
│       │   ├── Errors/                 # 错误定义
│       │   └── Models/                 # 数据模型
│       ├── Infrastructure/
│       │   ├── Logging/                # 日志基础设施
│       │   ├── Uia/                   # UI 自动化基础设施
│       │   ├── WebSocket/              # WebSocket 客户端
│       │   └── Win32/                  # Win32 API 封装
│       ├── Services/
│       │   ├── Elements/               # 控件服务
│       │   ├── Input/                 # 输入服务
│       │   ├── Ocr/                   # OCR 服务
│       │   ├── System/                # 系统服务
│       │   ├── Verification/          # 验证服务
│       │   └── Windows/               # 窗口服务
│       ├── Options/                    # 配置选项
│       └── Program.cs                  # 入口程序
└── simple-rpa-win.sln
```

## 许可证

MIT License

---

## English

### Overview

Simple RPA Win is a Windows desktop automation agent that provides remote control capabilities via WebSocket protocol. It leverages Microsoft UI Automation (UIA) technology to automate Windows desktop applications, supporting window management, control operations, OCR text recognition, and more.

### Features

- **Window Management**: List, find, activate, minimize, maximize windows
- **Control Operations**: Find, click, hover, set/get value, invoke controls
- **Input Simulation**: Type, paste, click, move, scroll, hotkey
- **Application Management**: Start, kill, locate applications
- **OCR Recognition**: Text recognition using Windows OCR engine
- **Screen Capture**: Screenshot functionality

### Requirements

- Windows 10/11 or Windows Server 2019+
- .NET 8.0 SDK

### Build

```bash
dotnet build src/Simple.Automation.Agent/Simple.Automation.Agent.csproj -c Release
```

### License

MIT License