DSH HUB
HomePlugin StorePlugin PacksCommunityRankingsResourcesPublish Guide
Plugin source
Back to catalog

Na2Cr2O7 /

Na2Cr2O7/dsh-qq-automate

Verified

纯模拟无注入QQNT机器人框架。

★ 0 Stars0 Forks0 IssuesN/A Community rating0 Confirmed installs
View on GitHub
READMESource: main@c588caf6

dsh-qq-automate

下一代自动化QQNT机器人框架。纯模拟无注入。使用VLM+Kimetra实现QQ窗口的精确点击,读取消息和输出。

这得花不少token (实测 ≈2.31 元/小时 · Mimo-v2.6 Flash,50 分钟折算) (2.92 元/h · DeepSeek-v4.1 flash 12分钟,效果好非常多)。

[!warning] 框架稳定性取决于选择的VLM,确保选择的模型性能不低于DeepSeek-v4.1 flash。

[!info] 受限于VLM模型性能,该插件的效果差强人意。前提是你能忍耐比官方QQ机器人还慢的速度。 ¯\_(ツ)_/¯

与其他dsh控制电脑插件的不同

  • 专注于QQ > 默认情况下,只会截取QQ的窗口。降低token消耗。
  • 跨平台 > cross-capture+Kimetra+uniclip+jimp,在Windows、Linux(x11)均可使用。Linux(Wayland)只适用于KDE Plasma / Gnome 。Hyprland很抱歉未能在上面启动QQ,macOS没有苹果电脑无法测试非常抱歉。
  • 惰性启动 > 可选择的让AI进入休眠,等待红点出现提醒。

支持的情况

理论QQ桌面版能做的都能实现,取决于AI的智商。 ¯\_(ツ)_/¯

人设可能需要额外的插件完成。本插件遵守KISS原则[1] 。

[1] :遵守KISS原则 : 即目标是遵守KISS原则 KISS原则(Keep It Simple, Stupid)强调保持设计和实现的简单性,避免不必要的复杂性,以提升可读性、可维护性和用户体验。

安装

逐平台的完整步骤(含依赖、权限、常见问题)见 installation.md; 让 agent 自己装的流程见 installation-agent.md。 安装好后点击dsh左下角->设置->QQ自动化进行配置。

启动

打开接管后,选择工作区,然后输入:

QQ自动化,启动!请开始检查消息。遇到红点立刻回复。目前的QQ可能已有几个红点,红点检测函数只检查新出现的红点。请先一一查看决定是否回复,然后才可以调用等待红点函数,如果有提供。可以视情况玩梗

当前进度(#1 地基 + #2 工具 + #3 窗口截图 + #4 动作日志 + #5 设置页 + #6/#6H 惰性启动与技能 + #7 发言约定与工具模式 + #8 控制分层 + #9 X11 实测 + #10 KDE Wayland 适配 + #11 GNOME Wayland 适配 + #12/#13 缩放验证)

cross-capture 负责截图、Kimetra 负责合成鼠标键盘、uniclip 负责文字输入输出, 三者已接进 DSH Host 服务 qqAutomate;插件加载时不点击、不输入,所有真实动作都由显式工具触发。

  • 截图:Windows 走原生 PowerShell 回退(上游 0.0.3 的 Windows 分支有解析 bug, 见 note.md);Linux X11 的窗口截图走 python3-xlib + Pillow;全屏/区域 优先 maim(cross-capture),缺 maim 时同样回退到 Pillow。
  • 输入:Kimetra 懒加载,统一毫秒单位。Linux X11 上 /dev/uinput 不可写时自动切到 Xlib XTEST(无需 root),覆盖指针、点击、滚轮、组合键。
  • 文字:uniclip 写剪贴板 → Ctrl/Cmd+V 粘贴,不逐字符注入。

工具(18 个)

工具 作用
full_screenshot 全屏截图,图片直接随结果返回,并给出截图原点
screenshot_qq 截标题为 QQ 的主窗口,返回图片 + 窗口左上角
screenshot_qq_extra 截标题为 QQ(窗口) 的独立聊天窗口
screenshot_region 按桌面坐标截一块矩形区域(省 token,宽高 32–4000)
screen_upload_file_dialog Windows 文件上传对话框(标题 请选择);其他平台退回全屏
screenshot_by_name 按标题截任意窗口,支持 exact / contains
qq_windows 列出可见顶层窗口:标题、pid、矩形、最小化/前台
qq_focus_window 恢复并置前标题匹配的窗口,返回前台状态
qq_wait_for_red_dot 惰性启动:休眠等待 QQ 新红点,返回红点裁剪图与坐标
mouse_move 移动鼠标到桌面坐标
mouse_click 可选先移动再点击/双击,左/右/中键
mouse_drag 从起点拖到终点,可设置拖动时长和终点按住停留
scroll 上下滚动,可指定位置
send_hotkey 发送按键或组合键(ctrl+shift+t、enter…)
send_text 剪贴板粘贴文字,submit=true 追加回车
clipboard 读写系统剪贴板(get 最多返回 8000 字)
qq_automate_status 依赖/后端/实拍/原生输入自检(deep=true)
qq_chat_policy 按白名单/黑名单约定判断某聊天是否应发言

流程约定:先 full_screenshot 或 screenshot_qq 看清界面 → 按截图坐标 mouse_click / mouse_move → 聚焦输入框后 send_text。窗口截图返回的 originX/originY 是窗口左上角,窗口内坐标 + 左上角 = 桌面坐标。

窗口截图:Windows 用 PrintWindow,默认不抢前台,被别的窗口挡住也能截;Linux X11 用窗口矩形裁剪屏幕,会返回 blockers(遮挡它的窗口)并在结果里警告。两平台都因此 存在“窗口不在前台时直接点击会落到上层窗口”的问题。要交互时给 screenshot_qq 传 focus=true,或先聚焦窗口;结果里的 foreground 会明确告诉你当前状态。

截图清理(#16)

截图是高频产物,所以每次落盘后都会按上限删最旧的(只删插件自己写的 png/jpg):

配置项 默认 说明
shotsMaxFiles 200 保留最多多少张
shotsMaxMB 200 保留最多多少 MB

设置页有「截图清理」卡片,显示当前张数/占用,并提供「立即清理旧截图」按钮 (GET/POST /qq-automate/shots)。

动作日志(#4)

每次 QQ 自动化工具结算后,Host 追加一条 user/message,source 为 { kind: 'qq-automate', form: 'notice', summary }:

  • 不新增 SessionEventType(外部插件追加未知事件会让会话无法重开);
  • Client 半 client.js 注册一个 exclusive 的 Chat Definition,把这类消息 渲染成带 QQ 徽标的 qq-action 行,而不是 Chat 默认隐藏的普通 Context;
  • 它仍是普通会话消息,所以模型在下一步也能看到;直接 append、不经过 inbox,不会唤醒新回合;
  • 模型推理本身已经由 assistant 的 reasoning block 显示为「思考」行,这里不重复注入;
  • 这些日志会进入下一次模型请求,带来额外 token 开销;后续可在设置页加开关。

设置页(#5)

「设置 → QQ 自动化」提供:

  • 强制确认模态框:启用必须点「启用并接管电脑」,在模态框里勾选风险确认后才能提交; 服务端还会校验 confirm: 'take-over',脚本无法直接开启。
  • 接管状态:启用后显示「已接管电脑」,可点「立即停止控制」即时停用(不需要确认)。
  • 模型选择:从 Host 的 LLM 目录列出可用模型,默认项为「使用 DSH 默认模型」;选择的模型先持久化, 留给后续独立 QQ 控制会话使用,当前自动化仍使用 DSH 当前会话模型。
  • 截图缩放:100% / 75% / 50%,用 jimp 缩放后交付图片;截图结果会带上 scale 和「桌面坐标 = 原点 + 图片坐标 / scale」的换算提示。
  • 惰性启动:开启后注册 qq_wait_for_red_dot;关闭时该工具不出现。详见下一节。
  • 工具模式:安全模式只开放截图/等待/鼠标移动/剪贴板;完全模式额外开放点击、拖拽、滚动、 快捷键、文字输入。切到完全模式要单独确认,每次以完全模式启用接管也要再次确认。
  • 发言约定:配置关 / 白名单 / 黑名单,名单每行一个聊天名称;这是与 AI 的约定, 不是技术强制,模型发言前应调用 qq_chat_policy 检查。

配置存于 profile 的插件行,Host 通过 /qq-automate/config 读写并校验白名单键。 未启用时,除 qq_automate_status / qq_chat_policy 外的自动化工具不会注册给模型; 启用/停用后会即时重载工具集。

设置页会校验 Host 端版本;如果显示「设置接口暂时不可用」,通常表示客户端已更新但 Host 还跑着 旧模块——到「插件」里停用再启用 dsh-qq-automate,或重启 DSH,然后点「重试」。

惰性启动(#6)

启用接管并打开「惰性启动」后,模型可以调用:

qq_wait_for_red_dot(timeoutSeconds=120, intervalSeconds=2, minArea=20)
  • 调用时先抓一张 QQ 主窗口基线,之后每秒/每几秒抓一帧;
  • 启动先做一遍纯颜色扫描:之前没点掉的未读红点不会出现在差分里,但对模型来说是没处理的活; 所以开头用纯颜色找一遍,探到就返回 existing: true(不是新消息),先处理完再等新的;
  • 对两帧做差分,只保留新增/变化且接近 QQ 红点色 RGB 247,76,48 的像素;
  • 对候选做 8 邻域连通域,按 minArea 过滤单个彩色像素、按 maxArea(默认 1500)过滤大块;
  • 只扫会话列表那一列(默认窗口宽度 4.5%–34%),聊天区里新出现的橙色/偏红图片(实测炸鸡图)不会再被当成红点; 可用 scan 参数覆盖,includeExisting=false 可跳过启动扫描;
  • 检测到后返回红点附近裁剪图、窗口内坐标、桌面坐标和完整截图路径;
  • 会等界面稳定再报坐标:红点出现的瞬间 QQ 常把该会话顶到列表上方,当帧坐标会过期; 检测到后会最多等约 0.9s 到「连续两帧几乎一致」,再用稳定帧重新算一次位置, 重排过就在结果里注明「从 (x1,y1) 修正为 (x2,y2)」并给出 movedPx;
  • 超时返回 detected=false,模型可以再次调用继续休眠等待;
  • 静态红图标、红包图标、红色文字不会触发(基线里已经存在)。
  • 窗口移动/改变大小时会重置基线,避免把窗口位移误判成红点。

Windows 用 PrintWindow,QQ 被遮挡也能取帧;Linux X11 是裁屏幕,QQ 被遮挡时可能把遮挡窗口的 新红色变化算进来,建议让 QQ 保持可见。工具本身不抢前台。

技能(#6H)

skills/ 下的 12 个操作手册注册为 DSH 运行时技能;模型通过 skill 工具按需加载:

技能 用途
qq-automation-basics 总则:先截图、悬停看提示、主题差异
qq-interface 主窗口布局、聊天列表、搜索、QQ 空间入口
qq-chat-window 聊天窗口四个区域
qq-chat-name 私聊/群聊/机器人/VIP 判定
qq-chat-content 消息区、时间、文件、转发、多选、右键菜单
qq-input 输入框定位、Shift+Enter 换行、Enter 发送
qq-input-toolbar 工具栏各按钮与安全边界
qq-upload 上传图片/文件的对话框流程
qq-emoji 打开表情面板、翻页/搜索、发送表情
qq-qzone 打开 QQ 空间并发布内容
qq-contact 联系人窗口、分类过滤、点卡片看详细资料
qq-temp-windows 聊天记录 / 空间 / 设置等临时窗口:标题不固定,怎么找、怎么截、怎么关

注册在 lib/skills.js(新增技能必须在这里登记,只放目录不会被发现),用 ctx.inject(['skills']) 等待技能服务就绪;正文里的 assets/... 会在注册时改写成绝对路径,模型可直接 read_image 查看。

发言约定与工具模式(#7)

白名单/黑名单是约定,不是强制拦截:

  • 设置页选择关 / 白名单 / 黑名单,名单每行一个聊天名称,精确匹配、忽略大小写;
  • Host 把当前约定注入系统提示(白名单/黑名单非关时),要求模型发言前确认聊天名称并调用 qq_chat_policy(chat="名称");
  • qq_chat_policy 返回 allowed、matched、reason,allowed=false 时按约定不要发送;
  • 插件不会在 send_text 处硬性阻断,因为当前没有可靠的“当前聊天身份”来源。

工具模式作用于所有 agent 的全部工具,不只是本插件:

  • 安全模式:对全局工具应用危险名单,并注册执行 guard:
    • 桌面输入:computer_click / computer_type / computer_key / computer_scroll / computer_clipboard、其他插件的 cu_* 动作工具;
    • 编排/插件管理:subagent / workflow / plugin_manager / spawn_*;
    • 定时任务修改、job_kill、本插件的点击/拖拽/按键/输入工具;
    • 保留 bash / pwsh / write / edit 等 DSH 基础开发工具。
  • tools.restrict 只能隐藏全局工具;preset/scoped 工具仍可能出现在列表里,但执行 guard 会拒绝。
  • 完全模式:解除上述限制,所有工具(包括其他插件/DSH 提供的)都可执行;
  • 切换到完全模式必须经过带勾选的模态框,服务端校验 confirmFullMode: true;
  • 完全模式的配置会持久化,但每次启用接管仍要再次勾选确认,避免“开过一次就永久危险”。

补充指令(#18)

“AI 太乖、不会主动探索”——这类问题不该靠改技能硬编码解决,所以设置页加了一个 补充指令输入框(extraPrompt,最多 2000 字,默认空):

  • 内容会作为独立段落注入每次会话的系统提示(## QQ 自动化:用户补充指令), 留空则不注入,不占 token;
  • 附带一个「填入探索模板」按钮,一键写入类似:

    允许打开聊天记录、联系人资料、QQ 空间、表情面板、设置等页面来了解界面和功能, 看完回到 QQ 主页并关掉临时窗口;只有明确需要回复时才发消息,不要主动打扰无关联系人。

  • 注入的文字末尾会自动补一句“与「启用确认」「安全模式」冲突的部分不生效”, 防止它被用来绕过接管确认。

控制分层(#8)

参考 dsh-computer-use-pro 的“先定位目标、再看画面、最后输入”,本插件固定为三层:

  1. 窗口/几何层:qq_windows 列标题/pid/矩形/最小化/前台,qq_focus_window 恢复并置前; screenshot_by_name 返回窗口左上角与尺寸。
  2. 视觉层:screenshot_qq / screenshot_qq_extra / full_screenshot 给模型看画面; QQ 的元素语义仍由模型从截图理解。
  3. 输入层:mouse_click / mouse_drag / send_hotkey / send_text 等,动作前可先聚焦并核对坐标。

平台能力:

能力 Windows Linux X11 KDE Wayland GNOME Wayland macOS
窗口列表/聚焦 是 是(Xlib) 是(KWin 脚本,含原生窗口) 是(Window Calls 扩展,含原生窗口) 明确报错
后台窗口截图 是(PrintWindow) 否,裁屏幕 否,spectacle 截整屏 否,gnome-screenshot 截整屏 未实现
遮挡检测 是 是(blockers) 否,occlusion: unknown 否,occlusion: unknown 未实现
鼠标 Kimetra Kimetra / XTEST XTEST(只到 XWayland 客户端) XTEST(只到 XWayland 客户端) 未实测
键盘/文字 Kimetra Kimetra / XTEST Kimetra(uinput) Kimetra(uinput) 未实测
无障碍树 未使用 未使用 未使用 未使用 未使用
分数缩放 DPI 感知 物理像素 150%/200% 已适配(逻辑→物理换算) 整数/分数缩放均可用(pixelScale 折算) —

不继承参考插件的平台覆盖承诺:Windows、Linux X11 已完整实测;KDE Wayland 的截图/窗口/鼠标已适配, 键盘要 /dev/uinput 权限(见 linuxDesktops.md);其余 Wayland/macOS 不做“已经支持”的暗示。 也没有接入 UIA/AT-SPI:windowCapabilities().accessibility 明确为 none,避免把窗口几何误称为无障碍语义。

Linux 依赖

# X11:截图(可缺,缺了走 Pillow 回退)+ XTEST 输入回退 + 剪贴板
sudo apt install maim python3-xlib python3-pil xclip
# KDE Wayland:截图(Xlib 的 ImageGrab 在 Wayland 只会拿到白屏)
sudo apt install spectacle
# KDE Wayland 的键盘/文字:需要 /dev/uinput 权限
echo 'KERNEL=="uinput", GROUP="input", MODE="0660"' | sudo tee /etc/udev/rules.d/99-kimetra.rules
sudo usermod -aG input "$USER"   # 之后完整注销再登录,并重启 dsh web(旧进程拿不到新组)
  • 有 /dev/uinput 写权限时 Kimetra 仍是首选;没有也不需要 root,XTEST 回退自动生效。
  • 只缺 maim 不影响窗口截图和输入,qq_automate_status(deep=true) 会显示实际后端。
  • Wayland 不是“装了就能用”:KDE 下窗口层走 KWin 脚本、截图走 spectacle、鼠标走 XTEST, 但 XTEST 的键盘不会送到应用,文字/组合键必须靠 uinput。逐项配置与实测见 linuxDesktops.md。

实测记录(#9,LMDE 7 / KDE Plasma / X11 / QQNT 3.2.33): 窗口列表与 wmctrl -lG 逐条一致;qq_focus_window 置前后回读 foreground:true;screenshot_qq 的 origin 与桌面 坐标对齐(窗口部分移出屏幕时返回 clipped:true,被遮挡时 blockers 指名遮挡窗口); XTEST 下移动后能读回精确坐标,单击/双击/右键/滚轮/组合键/拖拽(+200/+100 精确位移)与 剪贴板粘贴均正常;工具注册与动作日志也确认可见。/dev/uinput 为 root:root 0600, 全程走的就是 XTEST 回退路径。踩到的坑(QQ 隐藏到托盘后强行 windowmap 会白屏、 frameless 标题栏不能当双击靶子等)记在 note.md。

实测记录(#10,KDE Plasma 6.3.6 / Wayland / 同一台机器): XDG_SESSION_TYPE=wayland 且 XWayland 在跑;全屏截图切到 spectacle(整屏 + 本地裁剪),窗口列表/聚焦切到 KWin 脚本 (原生 Wayland 与 XWayland 窗口都能列出来、workspace.activeWindow 能置前),鼠标点击/滚轮 走 XTEST 正常,遮挡无法检测(occlusion: unknown)。键盘实测不生效:QQ 搜索框/输入框、 xmessage 的 Return 都收不到 XTEST 按键,因此 send_hotkey/send_text 在 Wayland 会明确报错 并给出 udev 授权步骤,而不是静默失败。

npm install
# 在 DSH 里用 plugin_manager / 插件市场安装本目录,或:
#   install_bundle target = 本仓库绝对路径

简表:

平台 额外依赖 备注
Windows 无 截图走 PowerShell + System.Drawing,输入走 Kimetra
Linux X11 maim python3-xlib python3-pil xclip XTEST 输入无需 root
KDE Wayland spectacle xclip + /dev/uinput 权限 窗口层用 KWin 脚本
GNOME Wayland gnome-screenshot + Window Calls 扩展 + /dev/uinput 分数缩放已支持

安装后可在插件列表中看到「QQ 自动化」。自检:

node scripts/selftest.mjs --deep
lib/capture.js       截图门面(平台分派)
lib/capture-win32.js Windows 原生截图(DPI 感知、虚拟屏、不抢焦点)
lib/window-win32.js  Windows 按窗口截图(PrintWindow + 窗口矩形)
lib/window-win32-ops.js Windows 窗口列表/聚焦
lib/x11.js           X11 回退门面(窗口/截图/指针/XTEST)
lib/x11_helper.py    python3-Xlib + Pillow 的实际实现
lib/window.js        窗口截图/列表/聚焦的平台分派
lib/input.js         输入门面(Kimetra / XTEST 回退)
lib/clipboard.js     uniclip 剪贴板读写
lib/keys.js          组合键解析与粘贴快捷键
lib/attach.js        截图 → 宿主 attachments 图片块
lib/png.js           PNG 宽高解析
lib/doctor.js        依赖、后端、目录、实拍、原生输入自检
lib/tools.js         模型可见工具面
lib/action-log.js    动作 → 会话 notice
lib/config.js        配置默认值与白名单校验
lib/config-routes.js 设置页 GET/POST /qq-automate/config
lib/image.js         截图缩放抽象层(jimp)
lib/red-dot.js       红点差分、颜色过滤与连通域
lib/skills.js        技能注册与 assets 绝对路径改写
client.js            Chat 动作日志行 + QQ 自动化设置页
—/ 5

No ratings yet

Verified DSH bundle

Commit c588caf67b8c

Community comments

No comments yet. Be the first to write one.

DSH HUB

A community index for DSH plugins. Not an official GitHub or DeepSeek AI product.

CommunityResourcesAPIAbout