@zaofan/dsh-qqbot

dsh plugin --profile web add @zaofan/dsh-qqbot

@zaofan/dsh-qqbot

 !Platform-blue)

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

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

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

中文 | [English](./README_EN.md) ｜ 📖 [用户手册](./docs/USER-GUIDE.md)（配置项 / 内置命令 / 自定义扩展 / 群管理 / 智能回复 / 架构…）

🐋 她能帮你……

一句话：把 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 分钟内聊过的算热，置顶的永不动），冷掉的会话自然被它越过。全程事件驱动、不轮询；宿主没起来、或聊天页没开着时天然不排序。

🖼️ 图能"直接看见"，多图还会自动拼成一张（v1.12.3，2026-11-06）

群友发的图会作为图片块直接进上下文，她不用调工具去读盘 —— "这张是什么"一轮就能答。

连着发好几张也不怕：插件按到达顺序攒进环形缓冲，竖向拼成一张长图随那条唤醒消息一起送进去（最新在最下），

已经拼过的图不会重复进上下文；当前模型不支持读图时自动跳过，不浪费 token。

🗜️ 分段压缩：只压尾巴，缓存不破（v1.12.4）

「无上下文模式」的第三种玩法：消息照常入站，只把「上回合结束 → 本回合开始」这段里多余的消息压成一行占位，

更早的历史一个字不动 —— 前缀稳定，服务商的 prefix cache 照样命中（命中价常常只有原价 1/10）。

实测连发 10 条、N=3，她上下文里就只剩 8、9、10；@ 她的消息永远不被压；还能设「价值分 ≥ X 的也保留」，把分值高、可能真在跟她说话的那几条单独保下来。

🖥️ 不碰配置文件，设置面板点点点

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

📦 干净又利落

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

📱 不用开电脑 —— 手机也能 7×24 挂着

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

📸 效果展示

图①：dsh 运行后台——思考过程、工具调用、Token 用量一目了然（配合「回复闸门 reply_gate」可让机器人自主判断该开口还是静默吃瓜）；

图②：QQ 群里的抓鬼游戏互动——该回就回、该藏就藏，角色扮演全自动；

图③：斗图实战——机器人用自己收藏的表情包接招回击，图、文分开两条连发。

图④：群管理·入群审批全流程——【群管·入群申请】事件注入 + 【审批轮询】双链路触发，AI 核对 openid 台账后自动放行；

图⑤：QQ 群内放行成功效果——小号申请入群被自动审批通过。

图⑥：设置中心——50 个内置扩展一览，每个都能单独开关、点齿轮改配置；

图⑦：扩展自注册设置面板——扩展用 qqbotSettingsPage 声明 schema，面板自动渲染出表单，值存成 JSON 供扩展读取。

---

---

正文图组：markdown 图片直接发

DSH 前端会把回复正文里的 markdown 图片渲染成图；本插件把同一段文本原样转发到 QQ ——

本地路径会自动上传成 qqbot-media 引用（读文件头补真实宽高，配额满 100 张自动删最早），不需要调用任何工具。

![干饭女王 #400px](D:/pics/a.jpg)

第一幕：本鲸宣布今晚不睡了

![何意味 #400px](D:/pics/b.jpg)

一行一张、连续几行就是图组（小剧场 / 分镜 / 图文并排），QQ 侧按顺序渲染成一屏。

DSH 前端 · QQ 群

 · 

配合表情包库最顺手：list_stickers 搜到图 → 把本地路径写进正文 → 图组直接出来，比连发 send_media 更像翻漫画。

失败策略：图传不上去时会原样留在文字里（不阻断本条，不会吞掉正文）。

---

交付文件直发：present → QQ 收到文件（v1.11.7+）

宿主自带 present 工具时，模型只要声明交付物（present(文件)），插件在轮末自动把文件发到当前会话 ——

正文里不用再写任何 [MEDIA:file|…] 标记。

• 订阅宿主的 deliverables/presented 事件（先于 turn/end 到达），逐个投递
• 单轮上限读 sendFile.maxFiles（默认 4），超出的只提示不发
• 某个文件发失败 → 聚合成一条「📎 已生成文件（未能直接发送）」文字提示，不阻断其余文件
• 自动去重：同一回合里被 present 直发的文件，正文里同路径的 [MEDIA:file|…] 标记会被剔除，不会一份文件发两遍
• 走的是与 send_media / [MEDIA:] 同一条发送嗓子（表情包闸门、已发送台账、失败降级都在那一层）

注意 QQ 侧限制：文件消息受主动消息频次约束（40093002），被动回复窗口过期时可能发不出去 —— 所以「失败降级成文字」是必须保留的兜底。

---

📦 扩展包与插件市场：把你的扩展分享给别人

单个 .mjs 是「扩展文件」，一个目录就是一个「扩展包」 —— 可以带工具、斜杠命令、封面、版本号，装进别人的面板里就是一张卡片。

市场索引在独立仓库：zaofan-make/dsh-qqbot-plugins。

目录结构

packs/你的插件id/              ← id 只能用字母数字-_（它就是安装后的目录名）
  qqbot-pack.json              ← 元信息，必填
  cover.png                    ← 可选，卡片封面（自动探测 cover.png/jpg/webp/gif）
  tools/xxx.mjs                ← 可选，给 AI 调用的工具
  commands/yyy.mjs             ← 可选，/斜杠命令

qqbot-pack.json：

{
  "name": "实用小工具",
  "author": "你的名字",
  "version": "1.0.0",
  "description": "一句话说明，会显示在卡片上",
  "homepage": "https://github.com/你/你的仓库",
  "tags": ["工具", "日常"]
}

name / author / version 必填，其余可选。

上传流程（不需要 token，也不会冲突）

# 1. fork + clone
git clone https://github.com/<你>/dsh-qqbot-plugins.git

# 2. 只加你自己的目录
mkdir -p packs/my-pack/tools packs/my-pack/commands

…(truncated)