qq-operations

Readme

# qq-operations

> 在 Windows 上可靠操控 **QQ NT 桌面版**（读消息 · 发消息 · 发文件 · 群文件 · 多会话陪聊）的
> [DeepSeek Harness](https://github.com/deepseek-ai/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](docs/manual.md) |

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

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

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

## 架构

![架构图](docs/assets/architecture.png)

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

- **调用前机主提示**：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、当作普通人可用的命令工具手动执行。

## 双模式示意

![双模式](docs/assets/dualmode.png)

---

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

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

---

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

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

```powershell
# ① 环境自检（只读；换机器第一步）
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](docs/manual.md) |
| 翻更早的历史消息（视口外） | [manual.md §6](docs/manual.md) |
| 读/下载群文件 | [manual.md §8](docs/manual.md) |
| 长中文消息（避免命令行传参编码问题） | 写进 UTF-8 的 `msg.txt`，脚本内 `ReadAllText` 读取；详见 [manual.md](docs/manual.md) |
| 出错/卡住了 | [manual.md §10 常见失败与排查](docs/manual.md) |

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

![发消息流程](docs/assets/flow-send.png)

---

## 九、安装

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

```powershell
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` 相对引用，无硬编码路径）：

```powershell
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](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](docs/manual.md)）
- QQ NT 仅对**前台**窗口构建完整 UIA 无障碍树（后台时树约 9 节点，找不到搜索框）：脚本在只读探测/识别账号前会自动唤起面板（`Revive-QQPanel`：恢复+置前+800ms 树重建等待+重试），属设计行为而非失败
- 效率模式下读回消息可能出现重复条目（UIA 虚拟化渲染），按内容去重即可
- 仅支持 Windows（依赖 user32.dll / UI Automation / PowerShell）

## 许可

[MIT](LICENSE) · © 2026 treers2