chatautox

开发文档 - chatautox

开发文档

本文档面向需要二次开发、扩展自动化能力的开发者，介绍 chatautox 中与 IM 客户端业务解耦的通用自动化子包 chatautox.auto。

商标与合规说明

chatautox 为独立项目，与腾讯及其产品（含「微信」「WeChat」）无任何隶属、合作或授权关系。

文档中出现的第三方产品名称、窗口标题、类名等，均为指称性引用——仅用于说明兼容性、枚举 UIA/Win32 技术参数，不构成商标使用、商业宣传或官方背书。使用者须自行遵守第三方平台用户协议及适用法律法规，详见 用户协议。

代码中的 WeChat 为 chatautox 内部 API 类名，与腾讯官方产品无关。示例里若出现 '微信' 等字符串，表示操作系统或目标程序返回的窗口标题字面量，请按实际环境替换，勿理解为品牌宣传用语。

模块定位

chatautox.auto 与 chatautox.wx、chatautox.ui 等 IM 客户端专用代码相互独立：

层级目录说明
IM 业务层chatautox.wx / chatautox.ui / chatautox.msgs封装 WeChat、Chat、Message 等高层 API
通用自动化chatautox.auto窗口查找、控件操作、流程编排，可用于任意 Windows 程序（会员版）
底层 UIAchatautox.uiaUIAutomation 封装

当你只需要调用 chatautox 高层 API（发消息、监听、朋友圈等），阅读 快速开始 和 核心概念 即可。

当你需要：

  • 对接其他 Windows 程序（非默认 IM 客户端）
  • 编写流程编排脚本（MacroEditor / control_browser 生成代码）
  • 扩展 chatautox 自身能力（自定义控件绑定、调试控件树）
  • 实现笔记/合并消息/小程序/文件下载等聊天场景操作

日常监听见 消息处理指南；控件级扩展见下文。

子模块一览

chatautox/auto/
├── winauto.py        # WinAuto — 核心窗口自动化（包入口 re-export）
├── macro_helper.py   # 函数式快捷接口（流程编排器生成代码）
├── uibase.py         # UICommand / AppWindow / ElementAction / ChatAction
├── window_handler.py # BoundWindow — 绑定窗口 + 媒体/文件/笔记/合并消息
├── note_parser.py    # read_note_window / NoteContentParser
├── popup_helper.py   # snapshot_hwnds / wait_new_toplevel
├── chatrecord_helper.py   # ChatRecordWnd 查找（msgs 内部使用）
├── miniapp_helper.py      # 小程序窗识别（msgs 内部使用）
├── image_preview_helper.py # 图片预览窗复制保存（msgs 内部使用）
└── winauto_content.py     # WinAuto 剪贴板/内容复制辅助

from chatautox import WinAuto 即可使用核心 API（会员版）。

快速选型

场景推荐模块
点击/输入/查找控件，一行搞定WinAuto
MacroEditor 生成的脚本macro_helper 或 WinAuto
绑定窗口后做截图、滚动、快捷键AppWindow（uibase）
保存图片、下载文件、读取笔记BoundWindow（window_handler）
笔记/图文混排一键复制解析WinAuto.copy_content()
查看当前剪贴板内容WinAuto.inspect_clipboard()
导出控件树调试WinAuto.dump_windows_controls
按属性定位单个控件WinAuto.find / wait_ctrl
批量获取会话/控件列表项WinAuto.get_list_items / get_sessions
同一流程里反复用同一控件/列表注册别名 → register / use()
读取聊天消息列表 / 识别好友或自己WinAuto — 消息列表
监听回调里消息类型怎么分发消息处理指南
支持哪些小程序Message类 — MiniAppMessage
可视化选控件control_browser
与内置 IM 客户端配合，指定已有 HWNDim_client() / 客户端构造 + WinAuto

绑定 HWND 后操作

查找窗口并构造 WinAuto 实例，即可进行底层控件操作：

from chatautox import WinAuto

# 窗口标题为 OS/目标程序返回值，按实际环境填写
TARGET_CLASS = 'YourMainWndClass'
TARGET_TITLES = ('目标应用', 'MyApp')

hwnd = WinAuto.find_main_hwnd(
    TARGET_CLASS,
    TARGET_TITLES,
    find_window_name=TARGET_TITLES[0],
)
auto = WinAuto(hwnd, mode='uia')
auto.activate()
auto.click(name='发送')

若使用 chatautox 内置 IM 高层 API，也可将查到的 hwnd 传入对应客户端构造函数，再与 WinAuto 配合使用。

操作模式

WinAuto 支持四种全局模式，可在构造时或单次调用时指定：

模式常量行为
autoMODE_AUTO自动降级：UIA → PostMessage → 物理鼠标
uiaMODE_UIA仅 UIA 控件 Invoke（需控件对象）
postMODE_POST仅 PostMessage 后台点击（不抢焦点）
mouseMODE_MOUSE仅物理鼠标/键盘
from chatautox import WinAuto, MODE_UIA, MODE_MOUSE

auto = WinAuto(hwnd, mode=MODE_UIA)        # 推荐：UIA 通用
auto = WinAuto(hwnd, mode=MODE_MOUSE)      # 物理鼠标/键盘
auto.click(name='确定')                     # 使用全局模式
auto.click(name='确定', mode=MODE_MOUSE)    # 单次覆盖
# auto = WinAuto(hwnd, mode=MODE_POST)      # 仅部分原生 ClassName 有效

调试控件树

开发新功能时，先导出目标窗口的 UIA 控件树，确认 Name、AutomationId、ClassName：

from chatautox import WinAuto

auto = WinAuto.from_main_hwnd('Notepad', '无标题 - Notepad', mode='uia')
windows = auto.dump_windows_controls(max_windows=30, max_lines=800)
WinAuto.print_windows_dump(windows)

也可配合项目内 control_browser 可视化调试面板使用。

文档导航

上一页 示例代码下一页 WinAuto 总览