wecom_it_smart_desk/deliverables/desktop-automation/desktop-automation/SKILL.md

name, description, agent_created

name	description	agent_created
desktop-automation	Windows 桌面自动化技能——通过模拟键盘鼠标操作控制桌面应用程序，适用于无法通过 API 或协议直接交互的软件（如微信PC版、钉钉、企业内部系统等）。核心能力包括窗口管理、鼠标点击移动拖拽、键盘输入快捷键、屏幕截图、OCR 文字识别、图像匹配定位。典型场景：导出微信聊天记录为图文 HTML、自动填表、批量文件操作、桌面软件自动化测试。当用户请求模拟操作桌面软件、自动点击、键盘鼠标控制、导出聊天记录、操控微信钉钉等桌面 GUI 自动化任务时触发此技能。	true

Desktop Automation

Overview

通过 PyAutoGUI + uiautomation + win32gui 组合方案，在 Windows 上实现桌面应用程序的 全自动化操作。覆盖从窗口定位、鼠标键盘模拟、屏幕截图到 OCR 文字识别的完整链路，支持将 操作过程和结果编译为图文 HTML 报告。

技术栈分层：

层级	工具	用途
窗口控制	win32gui / pygetwindow	查找、激活、移动窗口
UI 控件	uiautomation	精准定位按钮/输入框/列表等控件
鼠标键盘	pyautogui	坐标级点击、移动、拖拽、键盘输入
截图识别	Pillow + PaddleOCR	屏幕截图 + 中英文 OCR
剪贴板	pyperclip	中文文本输入（绕过 pyautogui 编码问题）

Safety Rules (MUST READ)

桌面自动化会直接操控用户电脑，执行前必须遵守以下规则：

1. 确认前置条件：确保目标应用已打开并处于可操作状态（如微信已登录）
2. 坐标依赖性：pyautogui 基于屏幕绝对坐标，分辨率/DPI 缩放变化会导致点击偏移。 优先使用 uiautomation 控件定位，pyautogui 坐标作为兜底
3. 安全中断：所有脚本内置 FAILSAFE=True，将鼠标快速移至屏幕四角可紧急终止
4. 操作前截图：执行关键操作前先截图，便于回溯和调试
5. 用户确认：涉及发送消息、删除文件等不可逆操作前，必须向用户确认
6. DPI 适配：Windows 高 DPI（150%/200%）下需调用 pyautogui.size() 校准坐标

Quick Start

1. 环境初始化

首次使用时运行环境检测脚本，安装缺失依赖：

python scripts/init_env.py

该脚本会检测并安装：pyautogui, uiautomation, Pillow, paddleocr, pygetwindow, pyperclip, opencv-python

2. 核心自动化引擎

scripts/desktop_auto.py 提供通用桌面自动化 API：

from desktop_auto import DesktopAuto

auto = DesktopAuto()

# 窗口管理
auto.find_window("微信")           # 查找窗口
auto.activate_window("微信")        # 激活并前置窗口
auto.get_window_rect("微信")        # 获取窗口位置和大小

# 鼠标操作
auto.click(x=500, y=300)           # 绝对坐标点击
auto.click_relative(dx=50, dy=0)   # 相对当前位置点击
auto.double_click(x=500, y=300)    # 双击
auto.right_click(x=500, y=300)     # 右键
auto.drag(start, end, duration=0.5) # 拖拽
auto.scroll(clicks=-3)             # 向下滚动3格

# 键盘操作
auto.type_text("你好世界")          # 中文输入（通过剪贴板）
auto.press_key("enter")            # 单键
auto.hotkey("ctrl", "c")           # 组合键
auto.press_key("ctrl+shift+esc")   # 快捷键

# 截图
auto.screenshot("fullscreen.png")            # 全屏截图
auto.screenshot_region(rect, "region.png")   # 区域截图
auto.screenshot_window("微信", "wechat.png")  # 窗口截图

# 图像匹配定位
pos = auto.locate_on_screen("button.png")    # 找图返回坐标
if pos:
    auto.click(pos.x, pos.y)

# 等待
auto.wait(2)                                # 等待2秒
auto.wait_for_image("loaded.png", timeout=10) # 等待图片出现

3. 微信聊天记录导出

scripts/wechat_export.py 专门用于导出微信聊天记录：

python scripts/wechat_export.py --contact "张三" --count 100 --output ./output

参数说明：

• --contact：好友或群聊名称（模糊匹配）
• --count：要导出的消息条数（默认50）
• --output：输出目录（默认 ./wechat_export）
• --scroll-pause：每次滚动间隔秒数（默认1.5，过快会漏消息）
• --ocr：是否启用 OCR 文字识别（默认开启）
• --screenshot：是否保存截图（默认开启）

导出流程：

1. 激活微信窗口 → 搜索联系人 → 打开聊天窗口
2. 滚动到顶部（加载历史消息）→ 逐步向下滚动截图
3. 对每张截图执行 OCR → 解析消息结构（发送者/时间/内容）
4. 消息去重 → 编译为 HTML 报告

4. HTML 报告编译

scripts/html_compiler.py 将截图和 OCR 结果编译为图文 HTML：

from html_compiler import ChatHTMLCompiler

compiler = ChatHTMLCompiler(output_dir="./output")
compiler.add_messages(messages)     # 添加结构化消息
compiler.add_screenshots(screenshots)  # 添加截图
compiler.compile("chat_report.html")    # 生成 HTML

生成的 HTML 特性：

• 仿微信聊天气泡样式（绿色=自己，白色=对方）
• 时间线分组显示
• 图片消息内嵌展示
• 支持搜索和过滤
• 响应式布局，移动端可读

Workflow Decision Tree

根据任务类型选择执行路径：

用户请求
├── 导出微信聊天记录 → scripts/wechat_export.py
├── 操控其他桌面软件 → scripts/desktop_auto.py (通用API)
├── 自动填表/录入 → desktop_auto.py (控件定位优先)
├── 批量截图监控 → desktop_auto.py (screenshot + scroll)
└── 其他 GUI 自动化 → desktop_auto.py + 自定义逻辑

Script Index

脚本	用途	入口
scripts/init_env.py	环境检测与依赖安装	python scripts/init_env.py
scripts/desktop_auto.py	核心自动化引擎（通用API）	from desktop_auto import DesktopAuto
scripts/wechat_export.py	微信聊天记录导出	python scripts/wechat_export.py [options]
scripts/html_compiler.py	HTML 图文报告编译器	from html_compiler import ChatHTMLCompiler

References

• references/automation_guide.md — 详细 API 参考、坐标定位策略、DPI 适配指南、常见问题
• references/wechat_patterns.md — 微信 PC 版 UI 结构分析、控件定位模式、已知坑点

Assets

• assets/template.html — HTML 报告模板（聊天气泡样式）

Limitations

1. 仅支持 Windows：win32gui 和 uiautomation 为 Windows 专用库
2. 坐标敏感：分辨率/DPI 变化需重新校准坐标；优先使用控件定位
3. OCR 准确率：PaddleOCR 中文准确率约 95%，特殊符号/表情可能误识别
4. 微信版本依赖：微信 UI 更新可能导致控件结构变化，需适配
5. 不可后台运行：pyautogui 需要目标窗口在前台可见
6. 安全限制：不可操作需要管理员权限的 UAC 弹窗（需用户手动确认）