qq-operations

August 30, 2026 · View on GitHub

在 Windows 上可靠操控 QQ NT 桌面版（读消息 · 发消息 · 发文件 · 群文件 · 多会话陪聊）的 DeepSeek Harness（DSH）skill 与可独立运行的 PowerShell 脚本集。

Windows 10/11 · PowerShell 5.1+ · QQ NT 桌面版 · 零第三方依赖 · MIT

📌 本文档对应 v1.2.0。 ✨ 一句话卖点：AI 圈热门方向「CUA（电脑操作智能体）」的无障碍树解法——不截图、不猜坐标、点错了会自己停下。

一、这是干什么的？（30 秒看懂，不懂技术也够）

一句话：让你的 AI 助手学会用 QQ。

装了它以后，你不需要自己切到 QQ、不需要打字或点文件，直接对你电脑上的 AI 助手说人话就行，比如：

"帮我看看跟张三最近聊了什么" → AI 自动打开会话、读出最近消息，整理给你 "在 QQ 上跟李四说一声：明早十点开会" → AI 找到李四、确认没找错人、发出去、再检查一遍 "把桌面这个 Excel 发给张三" → AI 自动发文件并确认真的发出去了

它干活时一定按规矩来，这也是它和你手动操作最大的区别：

  1. 先跟你说一声："⏳ 我要操作你的 QQ 了，请先不要使用鼠标/键盘约 1 分钟"——因为它要借用你的屏幕，你一动鼠标它就可能点错（这是真实踩过的坑，所以写成了硬规则）；
  2. 确认找对了人再动手（检查聊天窗口头部的联系人名字，对不上就中止）；
  3. 发完回头再检查一遍，把结果如实告诉你。

你完全不需要懂"脚本""自动化""UI"这些词——你只需要会跟 AI 说话，并且这台电脑上登录了你的 QQ。

💡 想自己手动用也行：本包不依赖 DSH，把脚本文件夹单独拷出来就能用（见下文「九、安装」）。只是那部分需要会复制粘贴命令——先看第二节，判断你属于哪一类。

二、你该看哪几段？（按身份导航）

你属于……看这些就够
完全不懂技术，只想让 AI 操 QQ「安装」→ 装好后对 AI 说人话即可；其余不用读
会复制粘贴命令，想手动跑「快速开始」（照着抄）＋「先看这里：新手必踩的坑」
换新电脑 / QQ 升级之后「换机器 / 升级后的校准」
想搞懂原理、改参数、加功能「目录结构」+ docs/manual.md

它为什么稳？（给半技术读者的简短原理）

QQ NT 界面是 Chromium（浏览器内核）渲染的，但 Windows 的无障碍系统里每个控件都有固定的类名——输入框 qq-msg-editor、联系人头 chat-header__contact-name、发送按钮 发送。本包像戴了一副"透视眼镜"：不靠截图猜像素，而是直接"点名"控件、读取它实时坐标再操作。所以窗口移动、缩放、换 DPI 全都不影响，中文也不用 OCR（那是会认错字的）。硬要对比的话：

对比截图 + OCR 像素法本包（UIA 类名法）
定位原理逐字识别 → 猜坐标元素类名 → 实时坐标 → 中心点击
抗 DPI / 分辨率差（坐标直接失效）强（坐标每步现取）
抗窗口移动/缩放差强（EnumWindows 动态定位）
中文文本OCR 误读风险UIA 精确文本
失败模式悄悄点错头部校验 abort + 读回验证

架构

架构图

能力清单（均为实测行为）

  • 调用前机主提示：Agent 每次执行前先在会话内声明（「我要操作 QQ 了，请先别动鼠标」）——自动化依赖前台/键盘/剪贴板，机主抢焦点会瞬态失败（实测教训）
  • 自动处理窗口状态：会话未开 → 主面板搜索+点击重开；面板最小化/隐藏 → ShowWindow(9) 恢复
  • 双界面模式自动兼容：经典模式（独立聊天窗）与效率模式（聊天内嵌面板）由 Get-QQMode 自动识别，调用方无感
  • 特殊字符会话名（emoji / ㍿，窗口标题显示为 ?）：头部联系人兜底直命中
  • 收件人校验安全阀：chat-header__contact-name 与目标不符即中止，防发错人；发送前读回编辑器内容二次校验
  • 多会话合并窗口：标题只显示激活会话（张三等2个会话）——读写切换一律走 Open-Chat，顺序无关
  • 自检与换机校准：qq_check.ps1 10 项检查（含「面板唤醒兜底可用」）+ -SendTest 自动识别登录账号发给自己（换账号零配置）
  • 中文零乱码：消息/路径全部走剪贴板（Clipboard.SetText + ^v）
  • 长文本安全发送：支持 UTF-8 文件直读，不经过命令行参数

三、和 AI 圈热议的"电脑操作"（CUA）有什么关系？

近两年 AI 圈最热的方向之一就是 CUA（Computer-Using Agent，电脑操作智能体）——让 AI 像人一样用电脑：自己看屏幕、动鼠标、点按钮。大家都在问：AI 能不能替我在电脑软件里办事（比如 QQ 里收发消息）？——能，本包就是其中一个已落地、且更稳的实现。

主流 CUA 的典型做法是「截图 + 视觉模型猜坐标」：AI 一边看画面、一边猜"按钮在哪"、一边模拟点击，再来一轮截图确认。听起来科幻，工程短板却很实：换 DPI 就"瞎"、窗口一动就点歪、中文靠 OCR 会认错字、每一步都可能悄悄点错——错了还不容易被发现。

本包走的是无障碍树（UI Automation）驱动的 CUA——学术界（如 Microsoft Magentic-UI）正在收敛的方向："看"的不是像素，而是操作系统给的控件身份证。

视觉型 CUA（主流）本包：无障碍树驱动 CUA
怎么"看"界面截图给视觉模型读取控件树（每个控件有固定类名：qq-msg-editor…）
怎么找按钮猜像素坐标点名控件 → 取实时坐标（每步现取，不缓存）
抗 DPI / 分辨率 / 缩放差（坐标直接失效）强
中文OCR 有误读风险控件文本精确
犯错时悄悄点错硬校验中止（头部不符即停）+ 读回验证（发完再审一遍）

直白地说：别的 AI 在"看着屏幕摸索"，你的 AI 在 QQ 里"知道自己正在干什么"——找对人、发出去、再检查，任何一步对不上就停，绝不将错就错。

📌 关系说明（避免误会）：本包是"工具层"（脚本 + skill 操作指令），接上 DeepSeek Harness 后由 AI 驱动，才构成完整的 CUA 闭环；也可以完全不接 AI、当作普通人可用的命令工具手动执行。

双模式示意

双模式

七、先看这里：新手必踩的坑（第一次用前必读）

  1. 永远不要按 ESC 来"清理"界面——ESC 会把整个 QQ 聊天窗口关掉，之后所有操作全部失效。想取消/清空请点界面上的按钮。
  2. 中文一律走剪贴板：脚本已内置（自动复制 → ^v 粘贴）。如果你自己写脚本，别用 SendKeys 打中文，会乱码。
  3. .ps1 文件必须保存为 UTF-8 带 BOM：Windows PowerShell 5.1 默认按 ANSI 读文件，中文会直接报"语法错误"。本包的文件已带 BOM；你手动编辑后，请用下面这行保存回去： 
    [IO.File]::WriteAllText($p, $c, (New-Object Text.UTF8Encoding $true))
  4. 自测只发给自己：qq_check.ps1 -SendTest 和 qq_send.ps1 的 -target 留空时，脚本会自动识别当前登录账号，发给自己——非常安全。⚠️ 「文件传输助手」在 2026-08 实测是他人账号伪装，严禁用它做自测。

八、快速开始（五条命令，按顺序跑）

以下命令均在 qq-operations 目录下执行；每一条都是完整流程，可以直接复制。

# ① 环境自检（只读；换机器第一步）
powershell -ExecutionPolicy Bypass -File scripts\qq_check.ps1

# ② 自检 + 发一条测试消息【给自己】（自动识别登录账号，安全）
powershell -ExecutionPolicy Bypass -File scripts\qq_check.ps1 -SendTest

# ③ 读最近 10 条（自动打开/切换会话；输出 [ME]/[THEM] 前缀）
. scripts\qq_lib.ps1; Read-Chat '联系人名' 10

# ④ 发消息（-target 留空 = 自动识别自己，安全自测；业务发送必须显式 -target）
powershell -ExecutionPolicy Bypass -File scripts\qq_send.ps1 -target '联系人名' -msg '内容'

# ⑤ 发文件 ——【两步走】① 剪贴板粘贴出文件卡片 ② 点击确认浮层「发送(1)」
powershell -ExecutionPolicy Bypass -File scripts\qq_send_file_paste.ps1 -file 'C:\path\文件.xlsx' -group '群名'
powershell -ExecutionPolicy Bypass -File scripts\qq_click_send1.ps1 -group '群名'

⚠️ 第⑤步为什么是两步：QQ 发文件时主「发送」按钮通常是禁用的（仅文本/AI 消息启用，实测 state=disabled），所以文件卡片必须先粘贴出来，再点确认浮层「发送(1)」（宽度 >100px 的那个，别点主发送钮）。只跑第一步 = 卡片出现但没发出去。

想做的事 → 对应的命令/文档

你想……入口
检查环境 / 换机器校准快速开始 ①（+ 「换机器」节）
发测试消息给自己快速开始 ②
读某人/某群最近消息快速开始 ③
发一条文本消息快速开始 ④
发一个文件快速开始 ⑤（两步）
一次读多个会话（轮询陪聊）manual.md §5
翻更早的历史消息（视口外）manual.md §6
读/下载群文件manual.md §8
长中文消息（避免命令行传参编码问题）写进 UTF-8 的 msg.txt，脚本内 ReadAllText 读取；详见 manual.md
出错/卡住了manual.md §10 常见失败与排查

发消息的完整内部流程（scripts/qq_send.ps1 已内置）：

发消息流程

九、安装

方式 A：作为 DSH skill（推荐，非技术用户选这个）

git clone https://github.com/treers2/qq-operations.git
# Windows 下把 qq-operations 目录放到 ~/.dsh/skills/ 下即可
# （或：mklink /J %USERPROFILE%\.dsh\skills\qq-operations <克隆路径>）
# 重启 DSH，Agent 遇到 QQ 任务会自动加载本 skill 的权威流程

装好之后：你不需要再读下面的东西了。 直接对 AI 说"帮我读下 QQ 上跟张三的聊天" / "帮我在 QQ 群里发一句话"，它会自己处理（包括先提醒你别动鼠标）。

方式 B：独立运行（适合想手动跑脚本的人）

目录可放任意位置（所有脚本用 $PSScriptRoot 相对引用，无硬编码路径）：

cd qq-operations
powershell -ExecutionPolicy Bypass -File scripts\qq_check.ps1
# 之后直接用「快速开始」里的五条命令即可

十、换机器 / QQ 升级后的校准

所有可调参数集中在一个文件：scripts/qq_config.ps1（类名、按钮名、坐标、等待时长）。

  1. qq_check.ps1（只读）→ 查看 FAIL 项
  2. 类名/按钮名 FAIL → qq_recon.ps1 / qq_search_debug.ps1 dump 当前 UIA 结构 → 更新 qq_config.ps1
  3. 坐标失效（滚轮读历史 / 群文件另存为）→ 截图量测 → 更新 qq_config.ps1
  4. qq_check.ps1 -SendTest 收尾（发给登录账号本人）

排查三板斧：qq_check.ps1（定位断点）→ qq_recon.ps1（窗口/元素清单）→ qq_search_debug.ps1（面板搜索结果 dump）。 完整流程与踩坑记录见 docs/manual.md。

十一、目录结构

qq-operations/
├── SKILL.md                    # DSH skill：Agent 执行的权威流程 + 防坑清单
├── README.md
├── LICENSE                     # MIT
├── docs/
│   ├── manual.md               # 精简操作手册（窗口结构 / 流程 / 失败排查表）
│   └── assets/                 # 架构图与流程图
└── scripts/
    ├── qq_lib.ps1              # 核心库：窗口枚举 / UIA 查找 / Open-Chat / Read-Chat / 点击
    ├── qq_config.ps1           # 常量中心（唯一需要改动的配置文件）
    ├── qq_self.ps1             # 自动识别当前登录账号（自测目标）
    ├── qq_send.ps1             # 发消息（头部校验 + 内容校验 + 读回验证）
    ├── qq_check.ps1            # 环境自检（10 项）+ -SendTest
    ├── qq_recon.ps1            # 侦察：枚举窗口 / 面板搜索框 / 聊天窗元素
    ├── qq_search_debug.ps1     # 面板搜索调试（Open-Chat 失败时用）
    ├── qq_diag.ps1             # 枚举 QQ 全部可见窗口（诊断聊天窗状态）
    ├── qq_diag2.ps1            # Open-Chat 体检（头部校验 + 文件按钮）
    ├── qq_send_file_paste.ps1  # 剪贴板粘贴发文件（只注入卡片，不点主发送钮）
    ├── qq_click_send1.ps1      # 点击文件确认浮层「发送(1)」（宽>100px，勿点主发送钮）
    └── qq_open_contact.ps1     # 点击面板搜索结果直接打开会话（仅排障调试用）

十二、安全须知（务必阅读）

  • 仅操作本机已登录的本人账号：脚本代表该账号执行一切操作，请勿在他人账号环境运行
  • ⚠️ 「文件传输助手」可能是伪装账号（2026-08 实测为他人账号）：自测一律发给登录账号本人（qq_check.ps1 -SendTest/qq_send.ps1 留空 -target 即自动识别，已内置安全阀）
  • 收件人校验不可删除：qq_send.ps1 中头部校验是「防发错人」的最后防线
  • 不支持、也请勿扩展群发/营销功能：违反 QQ 用户规范，可能导致封号
  • 脚本会临时强制 QQ 前台、清空剪贴板：批量任务请安排在空闲时段
  • 发文件、下载群文件等敏感操作，建议接入人工确认后再批量

十三、兼容性与已知边界

  • 实测环境：Windows 11 中文版 · 2560×1600 @ 125% DPI · QQ NT 桌面版（2026-08）· PowerShell 5.1
  • 消息列表仅暴露视口内内容：读取历史需滚轮上滚 + 重读循环（见 manual.md §6）
  • QQ NT 仅对前台窗口构建完整 UIA 无障碍树（后台时树约 9 节点，找不到搜索框）：脚本在只读探测/识别账号前会自动唤起面板（Revive-QQPanel：恢复+置前+800ms 树重建等待+重试），属设计行为而非失败
  • 效率模式下读回消息可能出现重复条目（UIA 虚拟化渲染），按内容去重即可
  • 仅支持 Windows（依赖 user32.dll / UI Automation / PowerShell）

许可

MIT · © 2026 treers2