# UiAutomationKit

**Repository Path**: rlmyfs/UiAutomationKit

## Basic Information

- **Project Name**: UiAutomationKit
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-27
- **Last Updated**: 2026-08-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# UiAutomationKit — 通用 Windows GUI 自动化测试技能

一套封装成 **技能（Skill）+ MCP 服务器** 的通用 Windows 桌面应用 UI 自动化工具箱。基于 **Windows UI Automation (UIA)**，适用于 Avalonia / WPF / WinForms 等任何暴露 UIA 的桌面程序。

能力：附加应用窗口、按 名称/AutomationId/控件类型 查找控件、点击/选中/开关/设值、下拉选择（含坐标点击版，解决 Avalonia 下拉不暴露的问题）、真实鼠标点击元素中心（应对 UIA 模式不生效/弹层控件）、轮询等待文本断言（`Wait-UiText`）、窗口截图、**录屏（MP4 H.264，可做宣传/演示视频，并支持对 公司名/IP/端口/序列号 自动打码脱敏）**、以及 **JSON 档案驱动的整条流程自动化**并产出报告——还可作为 **MCP 服务器** 暴露给 AI 客户端按需调用。

## 目录结构

```
ui-automation-skill/
└─ .trae/skills/ui-automation/          # 技能本体（可直接放进项目的 .trae/skills/ 使用）
   ├─ SKILL.md                          # 技能定义：AI 按任务挑选的工具清单与用法
   └─ UiAutomationKit/                  # 可复用工具包
      ├─ UiAutomationKit.psm1/.psd1     # 核心模块（PowerShell）
      ├─ Invoke-UiProfile.ps1           # JSON 档案驱动的测试运行器
      ├─ profiles/ScanValveDTC_sample.json  # 示例档案
      ├─ README.md                      # 工具包使用文档
      └─ mcp/                           # MCP 服务器（Python，stdio）
         ├─ ui_mcp_server.py
         ├─ mcp_op.ps1                  # PowerShell 引擎（one-shot 输出 JSON）
         ├─ README-MCP.md
         └─ mcp-config.sample.json      # MCP 注册示例
└─ demo/                                # 可选：完整脱敏宣传视频示例 + 示例档案
   ├─ DTCInitium_full_demo.mp4          # 真·连续屏录(录屏)的脱敏宣传片（示例产物）
   └─ demo_promo.json                   # 全功能宣传录制的可复用示例档案
```

## 快速上手（开箱即用）

**下载后一条命令装好：**
```powershell
powershell -ExecutionPolicy Bypass -File .\install.ps1
```
它会自动探测 Python、预装 mcp 依赖、生成可直接使用的 MCP 配置 `mcp.json`，并打印两种用法。

**装好后再跑一遍一键冒烟，验证能开箱即用：**
```powershell
powershell -ExecutionPolicy Bypass -File .\selfcheck.ps1
# 指定目标应用：powershell -ExecutionPolicy Bypass -File .\selfcheck.ps1 -ProcessName "你的应用"
```
全部 PASS 即说明模块导入/导出齐全、可附加窗口/取矩形/置顶/截图；见 `selfcheck/` 下的冒烟截图。

**方式A · 当 PowerShell 模块用（零配置，最快）：**
```powershell
Import-Module .\.trae\skills\ui-automation\UiAutomationKit\UiAutomationKit.psm1 -Force
$sess = New-UiSession -ProcessName "你的应用"     # 附加到运行中的应用
Show-UiWindow $sess                              # 提前台
$btn  = Find-UiElement $sess -Name "确定"        # 按名称找控件
Invoke-UiControl $btn[0]                         # 点击
Wait-UiText $sess -Text "加载成功" -TimeoutMs 10000   # 轮询断言文本出现
Save-UiScreenshot $sess -Path "shot.png"         # 截图
```

> 实战提示：WPF `ToggleButton` 的 `TogglePattern.Toggle()` 只翻转 `IsChecked`、**不触发 `OnClick`**，
> 绑定的命令/业务逻辑收不到通知——此时用 `Click-UiElementCenter $sess $btn[0]` 真实鼠标点击元素中心即可。
> WPF `Popup` 弹层内控件同理（独立 HWND，UIA 模式调用经常无效）。

**方式B · 当 MCP 服务器用（供 AI/外部客户端调用）：**
`ui_mcp_server.py` **首次启动会自动把 `mcp==1.9.0` 装进本目录 `deps/`**，无需手动 pip。把 `install.ps1` 生成的 `mcp.json`（或手动配置）中 `mcpServers` 注册到你的 MCP 客户端即可，例如：
```json
{ "mcpServers": { "ui-automation": {
    "command": "<python-exe>",
    "args": ["<绝对路径>/ui_mcp_server.py"]
}}}
```
启动测试：`powershell -File .\.trae\skills\ui-automation\UiAutomationKit\mcp\start_server.ps1`

> 若 `install.ps1` 没运行，也可仅用**方式A（模块）**；或手动 `python -m pip install "mcp==1.9.0" --target .\.trae\skills\ui-automation\UiAutomationKit\mcp\deps` 后如方式B用。

## 作为技能使用（给 AI 用）

把本仓库的 `.trae/skills/ui-automation/` 放到你的项目 `.trae/skills/` 下，AI 即可按需求调用 `ui-automation` 技能里的工具函数做：点击、填值、下拉选择、截图、跑 JSON 流程。

## 作为 MCP 服务器使用（给外部客户端用）

`ui_mcp_server.py` 启动时会自动把 `mcp==1.9.0` 装进本目录 `deps/`（无需手动 pip）。在 MCP 客户端里注册 stdio 服务器即可：
- `command = <python-exe>`，`args = ["<本仓库路径>\...\UiAutomationKit\mcp\ui_mcp_server.py"]`。

注册后即可通过 MCP 工具（`list_windows / find_elements / click / set_text / set_toggle / select_combo / click_select_combo / screenshot / get_window_rect / run_profile`）由 AI 按需调用。详见 `UiAutomationKit/mcp/README-MCP.md`。

## 运行 JSON 流程（批量 + 报告）

```powershell
powershell -ExecutionPolicy Bypass -File .\.trae\skills\ui-automation\UiAutomationKit\Invoke-UiProfile.ps1 `
  -ProfilePath .\.trae\skills\ui-automation\UiAutomationKit\profiles\ScanValveDTC_sample.json -OutBase out
```

档案 `ScanValveDTC_sample.json` 的 `Steps` 支持动作键：`Click / SetToggle / SetText / Select / ClickSelect / WaitMs / Capture / Expect`，运行后生成 `report.md`。

## 特性 / 亮点

- **通用**：一套 PowerShell 模块 + Python MCP，跨 Avalonia/WPF/WinForms。
- **下拉选择两套方案**：UIA（ComboBox/ListItem/RadioButton）+ 坐标点击版（解决 Avalonia 下拉不暴露为 UIA ComboBox、选项不进 UIA 树的问题）。
- **UIA 模式失灵兜底**：`Click-UiElementCenter` 真实鼠标点击元素中心，覆盖 WPF Popup 弹层、ToggleButton 开关等 UIA 模式不触发业务逻辑的场景；`Wait-UiText` 轮询断言页面加载。
- **GPU 窗口截图**：用 PrintWindow(PW_RENDERFULLCONTENT) 配合前台化，对 Avalonia GPU 窗口也能截到画面。
- **幂等 & 可重跑**：`SetToggle State` 设目标态、`Expect` 轮询等待，脚本可重复运行。
- **自包含技能**：整体目录可拷到任意项目复用；也提供 MCP 服务器供外部 AI 调用。

## 说明与限制

- 仅支持 **Windows**，需有 `powershell`。
- 目标程序需已启动且有可见窗口。
- 坐标点击（`Select-UiComboByClick`/`ClickSelect`、`Send-UiClick`）基于窗口相对坐标，与窗口尺寸/DPI 相关，建议在固定窗口尺寸下使用。
- 截图/几何随窗口尺寸变化；敏感示例已脱敏。

## License

MIT License，见 [LICENSE](LICENSE)。