dsh-qqbot

@zaofan/dsh-qqbot

-blue)

基于 deepseek-harness (dsh) 的 QQ Bot IM 插件增强 fork：将 QQ 消息平台作为 dsh agent 的前端协议驱动，并加入表情包图库、富媒体收发、定时任务、多实例人格、好感度系统、可视化设置面板等能力。

📦 仓库: zaofan-make/dsh-qqbot（fork 自 tencent-connect/dsh-qqbot；改动都在这一侧，升级/重装上游会被冲掉）

⭐ 用得顺手的话，麻烦点一下右上角的 Star —— 它是这个项目"有人在用"的唯一可见信号，也是继续更新的动力。

中文 | English ｜ 📖 用户手册（配置项 / 内置命令 / 自定义扩展 / 群管理 / 智能回复 / 架构…）

🐋 她能帮你……

一句话：把 dsh 的 QQ 机器人养成"活鱼"——会存表情包、会挑图回你、到点自己开口、记得住谁跟它亲疏远近，一台电脑还能同时养好几条性格不同的鲸鱼。

🤳 群里发的图，她偷偷全存进小图库 自动去重、分「待整理/收藏/回收站」；你说一句"发个开心点的图"，她自己搜库、自己挑、自己发，还会挑场合出手（冷场不发、刷屏限量、同图不连发）。

⏰ 到点她自己会开口 "每天早 9 点去群里说早安""30 秒后提醒我喝水"——她说到做到，准点冒泡。

🧑‍🤝‍🧑 一个电脑，N 条鲸鱼同时在线 每条号独立 AppID、独立人格、独立图库/定时/闸门，互不串号；Web 页「扫码绑定」手机一扫就上岗。

💗 她记得住谁亲谁疏（v1.5.1） 两个维度分开算：熟识度（她把你记得多牢——来过几天、说过多少、被点名、接话，慢变量）与好感度（她对你什么态度——随每次互动可升可降）。面板里一行一个人，还能一键导出 Excel 拿去分享。

• 判定用一个跑在本机的小模型读她的「思考（内心）」与「正文（说出口的话）」：心里不肯但话仍照顾 = 让步、心里亲近而嘴上冷淡 = 不算数（扣不扣看内心，不看表面）
• 好感度只影响"她愿不愿意自己开口"的松紧：负好感也只是少主动，绝不冷落、阴阳、攻击
• 群消息聚合时按「价值 × 好感」加权平均综合判断，不会被一句话钓走

💬 悬浮球 dock：她的随身控制台 设置面板右下角的小球，点开就是一整个操作台：💬 聊天（像 QQ 一样回放群/私聊记录，气泡+头像，图能放大、本地视频能播、SILK 语音转 mp3 直接听、文件出下载卡，还能在聊天框里直接发文字/插图/发文件——长文本自动拆条连发不被吞）；📥 入群审批、🔨 锤子（下面分 🔇 禁言 和 👢 踢人 两页；踢人用你自己的 QQ 号管群，扫码一次之后长期免扫，登录态与 AI 共享）；⚙️ 出站（适配主动：刚收到真人消息时前几条带引用回你、连发自动转独立消息，定时/后台推送不打扰）。

🛡️ 群主/群管好帮手 入群审批 + 禁言 + 查成员，全走官方接口，出错给"人话"（不是管理员/不能禁群主……都告诉你为什么）。

👢 踢人（v1.6.3） QQ 官方没有开放踢人接口，所以这一块走"你自己的 QQ 号 + 群官网"：面板 🔨 锤子 → 👢 踢人 里刷新二维码、手机扫一次就登（之后长期免扫）；登录态和 AI 共用 —— 你也可以直接在 QQ 里跟她说"把群里那个 X 踢了"。

🗂️ 归档了也会自己回家 不小心把她的会话点了「归档」藏进侧边栏深处？不用满世界找——那个会话下次在 QQ 里被消息触发时，会自己从归档里摘出来回到侧边栏（你主动归档的其它会话不受影响）。

🔝 QQ 一有动静，她的会话自己爬到最上面（v1.6.8） 侧边栏里正在跟你聊的那个会话，不该被别的压着 —— QQ 里一有消息、她真的回了话，对应会话就会自动插到「还热着」的那批之后（10 分钟内聊过的算热，置顶的永不动），冷掉的会话自然被它越过。全程事件驱动、不轮询；宿主没起来、或聊天页没开着时天然不排序。

🖥️ 不碰配置文件，设置面板点点点 怎么回、能发什么图、什么时候开口、什么人格——面板上改完保存即生效（只有增删账号才要重启）。还有 ✏️ 预设人格编辑器，直接在网页里改她的"性格文件"。

📦 干净又利落 发图/撤消息用纯文本就能驱动（回复里写 [MEDIA:image|路径] / [RECALL]）；仓库不含任何机器人凭据与隐私。

📱 不用开电脑 —— 手机也能 7×24 挂着 配合社区的 dsh-mobile-apk（dsh 安卓壳 APK：WebView UI + 内嵌 Termux 运行时快照，解压即跑），把 dsh 和这只鲸鱼一起装进手机，就是一台随身在线的 QQ 机器人 —— 不用为了挂机常开一台电脑。（安卓上通常没有 ONNX 运行时，记得在设置里勾上「程序兜底（不依赖小模型）」，见下方说明。）

📸 效果展示

图①：dsh 运行后台——思考过程、工具调用、Token 用量一目了然（配合「回复闸门 reply_gate」可让机器人自主判断该开口还是静默吃瓜）； 图②：QQ 群里的抓鬼游戏互动——该回就回、该藏就藏，角色扮演全自动； 图③：斗图实战——机器人用自己收藏的表情包接招回击，图、文分开两条连发。

图④：群管理·入群审批全流程——【群管·入群申请】事件注入 + 【审批轮询】双链路触发，AI 核对 openid 台账后自动放行； 图⑤：QQ 群内放行成功效果——小号申请入群被自动审批通过。

🔌 用户扩展：想自己加功能，不用改插件源码

这是给"想自己加东西"的用户准备的接口 —— 往 {数据根}/.qqbot-extensions/ 里丢一个 .mjs 就是一个扩展。

插件自带的能力、示例、文档全都白送，你只管写业务逻辑。

先把边界说清楚：她现有的功能 —— **表情包图库、到点开口、好感度系统、群管理（禁言/踢人）、

悬浮球面板、智能回复闸门……这些是插件内置的**（写在插件源码里，随插件升级一起更新）。

扩展是另一回事：你的 .mjs 放在自己的数据目录里，不改插件源码、升级插件也不会被覆盖。

两者的关系是：能力一样，位置不同 —— 扩展拿到的那套能力包（发消息 / 发图 / 进她上下文 /

调官方 API / 持久化 / 身份…）就是插件内部模块在用的同一套封装，所以你写的东西不是"外挂"，

只是长在同一条链上的另一个模块。

🧩 六套扩展点，挑一个放进去就行

你想做的事 · 放哪个目录 · 什么时候跑 让 AI 主动调用某个工具 · tools/ · LLM 调它的时候 加一条 /我的命令 · commands/ · 用户敲这条命令 卡片按钮点了要做事 · botplay/ · 有人点按钮 启动时恢复任务 / 起定时器 / 预取 · hooks/ · 插件启动时跑一次 管每一条消息的命运 · inbound/ · 每条消息都过一遍 管每一条出站消息 / 补发媒体 · outbound/ · 每条要发出去的消息都过一遍

🧰 一套能力包，六套通用（不用为每套各记一套 API）

await env.text('hi') / env.markdown('# 标题') / env.markdownCard(md, keyboard)
await env.image(src) / voice / video / file            // src 可传 URL 或本地路径
env.at(openid)                                        // 群里 @ 人
await env.api('/v2/users/@me')                        // ★ 官方 API：自带 token 与缓存，不用管 appId/secret
env.store.load() / env.store.save(obj)                // ★ 持久化：升级插件不丢
await env.appendSilent('...')  // ★ 进她上下文、不唤醒
await env.appendWake('...')    // ★ 进上下文并唤醒一轮
env.user / env.owners / env.peer · env.log() · env.kernel（全权限遥控器）· await env.restart()

🚦 入站扩展独有：一条消息的"处置权"

消灭 annihilate（不进群历史/不进上下文/不占冷却）
改写 rewrite（早挂点连群历史一起改）
强制入站 forceWake（跳过 @门控/价值评分/群冷却）
覆盖 @判定 decide · 静默进上下文 silentInto · 用户维禁言 muteUser 系列
只读视图 message.{text,sender,scope,groupId,isOwner,mentions,quoted,platform}

🛡️ 四条保命件 —— 你的脚本出问题，也搞不坏群

主人白名单最高优先（不可被静默/封） · 强唤醒优先于静默 · 熔断（扩展失控自动停手） · 审计 + 可撤销（每次动作一行，带轮转） · 单个扩展抛错只告警并放行，永远不会吞掉消息

🎬 还有

• 示例自动铺：插件启动时把自带示例只补不覆盖地铺进你的扩展目录 —— 装上就有一份能跑的样板
• 改完即生效：/tools-reload 一下就行（扩展命令需重启）
• 📘 写扩展前先读：docs/extension-contract.md —— 五套扩展点、能力包全表、

入站操控、安全红线、常见坑，一份写全

🎁 白送的扩展示例：装上就有能跑、能抄的样板

插件启动时会把这些示例只补不覆盖地铺进你的扩展目录 —— 不用自己从零写。

让她多会几样本事（AI 能自己调用的工具）

• 会自己联网搜：一句话就能搜索并把结果整理回来，不用你接搜索接口
• 会替你给别人发消息：指个群名或人名她就发；认不准只回候选、绝不瞎发
• 会在群里发起投票：选项、票数、到点结束结算，一张卡搞定
• 会跨会话遥控：列出你所有工作区与会话、给某个会话递话、临时开一个新会话（能指定工作区与人设、派初始任务）、

盯住子会话把结果回灌过来并转进 QQ

让她在卡片上"有状态"

• 签到统计：谁签过、签了几次、只有主人能看、结束自动公布名单 —— 按钮点下去真的记账

让她开机就干活（不用任何人触发）

• 启动就跑一次：打日志、计数落盘（跨重启累加）；
• 注册监听并自己收尾：演示怎么挂监听、怎么在卸载时清理干净

让她管"每条消息的命运"

• 引用子会话不叫醒她：群里引用一条"子会话转发"的消息，不会被当成在叫她；
• 一个"辅导员"全套样板：删广告、刷屏禁言、把手机号之类的敏感内容改掉、有人喊救命时优先叫醒她

—— 默认只观察不动手，先看日志确认规则合不合意，再放开

示例是给人看和抄的：会真动手的那个（辅导员）不会自动铺，要自己拷过去 ——

示例不该在你没读过它之前就自己跑起来。

🆚 官方 Bot 方案 vs onbot / NapCat 等第三方协议端

本插件走的是腾讯官方 QQ 机器人开放平台（AppID + AppSecret + 官方 SDK）， 不是"模拟 QQ 客户端协议"那条路。两者差别不小，先把话说清楚：

· 本插件（官方 Bot API） · 第三方协议端（onbot / NapCat / Lagrange…） 登录方式 · 填 AppID / AppSecret 即可，不扫码、不登录你的真人 QQ 号 · 扫码登录你的个人 QQ 号，常掉线、要保活 账号安全 · ✅ 完全不碰你的个人号，无封号风险 · ⚠️ 有封号风险：协议模拟违反 QQ 用户协议，腾讯明确禁止 稳定性 · ✅ 官方接口，腾讯自己在维护；变更会提前公告 · ⚠️ 协议一变就挂，得等签名服务（qsign 之类）跟进 资源占用 · ✅ 极低：纯 HTTP + WebSocket，无浏览器、无协议端常驻 · ⚠️ 高：要挂 QQ 客户端 / 协议端，内存几百 MB 起 低配 / 手机部署 · ✅ 能跑：安卓 Termux、树莓派、1 核 1G 的小机器都行（见下方「📱 装到手机上」） · ⚠️ 难：协议端对架构/内存有要求，安卓上尤其折腾 隐私 · ✅ 只与腾讯官方通信，没有中间人 · ⚠️ 要经过第三方协议实现 功能范围 · ⚠️ 受官方开放范围限制（例：踢人接口官方没开放） · ✅ 全功能

关于"功能受限"，本插件的态度：官方没开放的，能补就补、不能补就明说 —— 例如踢人：官方接口至今未开放，插件用 🔨 锤子 面板让你用自己的号走群官网接口把这块补上 （扫码一次、之后长期免扫，登录态还会和 AI 共享，详见下文）。

一句话：想要安全、省心、还能塞进手机或小机器，就选官方 Bot 方案；

只有当你非要第三方协议端的"全家桶"、并且愿意承担封号风险时，才另说。

安装

## ⚠️ 必须装到 web profile

本插件的前端设置面板（dock 球 + 「设置 → QQ 机器人」整页）只在 `web` profile 里生效。

装到别的 profile 会得到一个 没有设置面板的裸环境 —— dock 球和设置页都不会出现，

表现为"插件装了但看不到任何界面"。

正常使用 `dsh web` 的用户不用关心（dsh web 默认就是 web profile，插件页/插件市场装机也落在它上面）。

只有手动指定过 --profile 的场景才需要注意。

也不要 add @tencent-connect/dsh-qqbot——那会装上游官方版（无本 fork 增强功能）。

✅ 单包自含，装一个就全有：QQ 机器人 + Web 可视化设置面板（host 桥 + 设置页 UI）都打包在

这一个包内——装完它，dsh Web「设置」里就会出现「QQ 机器人 (im-qqbot)」面板（多账号时每个实例各一页），

无需再单独安装 dsh-qqbot-settings。

方式一（发布到 npm 后）：一条命令

npx @deepseek-ai/dsh plugin --profile web add @zaofan/dsh-qqbot

尚未发布到 npm 前，请用下面的方式二。

⚠️ 从 GitHub 直装（`github:zaofan-make/dsh-qqbot`）需要编译产物 `dist/`，而仓库不提交 `dist`。

包已声明 prepare 脚本，pnpm 安装时会自动编译；