qq-operations

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

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

为什么这一套能稳定工作

QQ NT 的界面由 Chromium/Electron 渲染，但控件完整暴露在 UI Automation 树中。本包以 UIA 类名定位—— 输入框 qq-msg-editor、头部联系人 chat-header__contact-name、消息气泡 message-container*、发送按钮 发送—— 每次操作重新枚举窗口、读取元素现行坐标，绝不缓存句柄，也不依赖屏幕像素。

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

架构

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

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

双模式示意

快速开始

# ① 环境自检（只读；换机器第一步）
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 留空 = 发给自己，用于安全自测；业务发送必须显式指定）
powershell -ExecutionPolicy Bypass -File scripts\qq_send.ps1 -target "联系人名" -msg "内容"

# ⑤ 发文件（剪贴板卡片 + 确认浮层）
powershell -ExecutionPolicy Bypass -File scripts\qq_send_file_paste.ps1 -file "C:\path\文件.xlsx" -group "群名"

发消息的完整内部流程（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 的权威流程

方式 B：独立运行

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

cd qq-operations\scripts
powershell -ExecutionPolicy Bypass -File 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            # 环境自检（9 项）+ -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)」
    └── 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）
• 效率模式下读回消息可能出现重复条目（UIA 虚拟化渲染），按内容去重即可
• 仅支持 Windows（依赖 user32.dll / UI Automation / PowerShell）

许可

MIT · © 2026 treers2