@zaofan/dsh-qqbot

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

📦 仓库: gcry13067381632-jpg/dsh-qqbot（fork 自 tencent-connect/dsh-qqbot）

中文 | English

🐋 本 fork 增强版

一句话：让跑在 dsh 上的 QQ 机器人"活"起来——会存表情包、会挑图回你、到点主动开口、一个DSH还能同时开好几个不同性格的机器人号。

它是上游 @tencent-connect/dsh-qqbot 的增强 fork（改动不在上游源码里，升级/重装上游会被冲掉）。

装上之后，它能帮你……

🤳 群里的表情包，自动变成它的收藏 群里谁发了图，机器人自动存进本地图库（自动去重、分"待整理/收藏/回收站"）。你只要说一句"发个开心点的图"——它自己搜库、自己挑、自己发，还会挑场合出手（可配置：冷场不发、刷屏限量、同图不连发）。

⏰ 到点它会自己开口 设置里告诉它"每天早 9 点去群里说早安"，它就准点出现；跟它说"30 秒后提醒我去喝水"，它到点真会来催你。

🧑‍🤝‍🧑 一个电脑，多个人格同时在线 傲娇系、元气系、高冷系……想开几个开几个：每个号独立 AppID、独立人格、独立工作目录（图库/定时/闸门全分开，互不串号）。新号不用翻教程——Web 页点「扫码绑定」，手机 QQ 扫一下，凭据自动填好。

🧹 图库乱？让 AI 自己整理 一句话"看看收藏里哪些图还没写介绍"，它列出清单、自己补标签补描述，越用越懂你。

🖥️ 不用碰配置文件，全在设置面板点 机器人怎么回、能发什么图、什么时候主动说话、每个号用什么人格——都在一个面板里改，保存即生效（账号增减才需重启）。

📸 效果展示

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

给开发者的话

• QQ 会话内可直接调用的标准工具：发图/撤图/查库/打标/查未整理/定时（send_media/recall_message/list_stickers/sticker_tag/sticker_untagged/schedule_timer/schedule_cancel…），会话按账号精确路由
• 纯文本也能发图撤消息：让ai再回复里写 [MEDIA:image|图片路径或网址] 就自动变成真图发出去（voice/video/file 同理）；写 [RECALL] 撤回自己刚发的那条
• 会话归属、工作区挂载等宿主问题已按官方机制修好（移植上游 PR #21，幂等、全 fail-soft）

🛡️ 仓库不含任何机器人凭据、图库数据、日志与个人路径（发布前已清理）。AppID/AppSecret 请走环境变量或 Web 面板注入，不要提交进 git。

构建与部署

npm install                 # 安装依赖（peer 依赖由 dsh 宿主解析）
npm run build               # 或: node node_modules/typescript/lib/tsc.js -p tsconfig.json
npm run check:package       # 发布前自检(单包四项家当齐全)
pnpm pack                   # 打 tarball(供 dsh plugin add 安装)

安装到 dsh profile 见下方「安装」小节（同样支持 dsh plugin add 与扫码引导）。 仓库根的 install.ps1 提供 Windows 一键安装（自动 pack 到无空格目录 → add → 重启提示）。

---

架构

QQ 用户 → QQ WebSocket → dsh-im-qqbot → ctx.agents → dsh agent loop → LLM
                                 ↑                           │
                                 └── session/event ──────────┘
                                       (assistant reply → QQ sendMarkdown)

安装

⚠️ 必须装到 web profile（dsh web 设置面板的宿主）；装到别的 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 前，请用下面的方式二。

方式二：源码分发（当前推荐）

Windows（一键脚本）：

git clone https://github.com/gcry13067381632-jpg/dsh-qqbot.git
cd dsh-qqbot
.\install.ps1          # 自动 install/build → pack → add tarball → 输出重启指引

若系统禁止运行脚本，改用：powershell -ExecutionPolicy Bypass -File .\install.ps1

macOS / Linux（手动）：

git clone https://github.com/gcry13067381632-jpg/dsh-qqbot.git
cd dsh-qqbot
npm install && npm run build
pnpm pack --pack-destination /tmp
npx @deepseek-ai/dsh plugin --profile web add /tmp/zaofan-dsh-qqbot-0.4.0.tgz

💡 为什么打 tarball、而不是 add 源码目录？实测教训： ① 目录路径含空格时 Windows 会把参数在空格处拆碎（pnpm 报 - isn't supported）； ② add 目录 = pnpm link(junction)，插件无法按"代码位置"反推 profile → 扫码凭据落不了盘，只能走环境变量。

首次启动与绑定

启动 dsh web 后，若未配置凭据会自动进入扫码引导：终端输出二维码 → 手机 QQ 扫码绑定 → 凭据自动保存，重启不丢（设置面板里也可随时「扫码绑定」/改账号）。

提示：建议使用 0.4.0 以上版本扫码，支持点击链接在浏览器打开，避免部分终端二维码渲染错位的问题。

还没有 QQ 机器人？先注册一个（拿 AppID / AppSecret）

1. 打开 QQ 开放平台，用 QQ 号登录；
2. 进入「机器人」→「创建机器人」，填好名称、头像、简介；
3. 创建完成后在机器人详情页拿到 AppID 与 AppSecret；
4. 在 dsh Web → 设置 →「QQ 机器人」→「账号与预设」里填入并保存 （或设为环境变量 QQBOT_APPID / QQBOT_SECRET）；
5. 按需在平台开通单聊/群聊消息权限（群聊一般需要提交用途审核）。

💡 更省事：机器人建好即可，首次启动直接扫码绑定，不用手抄凭据。

开发者：--patch 开发模式

export QQBOT_APPID="你的AppID" QQBOT_SECRET="你的AppSecret"
npx @deepseek-ai/dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml

QQ 远程审批(可选)

当 Agent 的工具要访问工作区之外的位置时,dsh 会触发权限审批。开启后,机器人把审批请求发到 QQ(任务发起者的会话),你直接在 QQ 里放行/拒绝:

⚠️ DSH 权限申请 工具：pwsh 原因：需要访问工作区外路径

允许本次操作：/approve A1B2C3 拒绝本次操作：/deny A1B2C3 仅本次有效，120 秒后自动拒绝。

启用(二选一;保存即对新审批请求生效,无需重启):

• Web 设置面板:设置 →「QQ 机器人」→ ⑤ QQ 远程审批 → 勾选开启;
• 或 cordis.patch.yml 的实例 config 加两行后重启:

- id: im-qqbot
  config:
    enableApprovals: true          # 默认 false
    approvalTimeoutMs: 120000      # 等待时长, 超时自动拒绝

安全边界:验证码一次性;仅"任务发起者本人 + 同一会话"可批(群聊里其他人看到验证码也无效);只授权当前这一次操作;Agent 取消或 dsh 退出自动取消。

思路来源: wang-22-code/dsh-qqbot-bridge 的 QQ 审批设计(宿主 dsh approval/request 标准事件,官方 dsh-acp / Web 审批弹窗同款机制)。

配置项

配置	类型	默认值	说明
appId	string	必填	QQ Bot AppID（或通过 QQBOT_APPID 环境变量）
appSecret	string	必填	QQ Bot AppSecret（或通过 QQBOT_SECRET 环境变量）
provider	string	deepseek-official	LLM 提供商名称
model	string	deepseek-chat	模型名称
preset	string	-	Agent preset id
cwd	string	process.cwd()	Agent 工作目录
requireMention	boolean	true	群聊是否需要 @bot 才触发
groupPrompt	string	-	群聊额外 system prompt
directPrompt	string	-	私聊额外 system prompt
textChunkLimit	number	4500	单条消息最大字符数
sessionIdleTimeout	number	1800000	会话闲置超时(ms)，默认 30 分钟
debug	boolean	false	调试模式

内置命令

命令	说明
/bot-reset	重置当前会话（清除上下文）
/bot-model	查看或切换模型
/bot-status	查看当前会话状态
/bot-help	查看所有指令

核心模块

src/
├── index.ts                    # Cordis 插件入口（async apply）
├── config.ts                   # 配置 Schema
├── types.ts                    # 全局类型定义
├── setup.ts                    # 凭据绑定（扫码）
├── transport/                  # 传输层
│   ├── inbound.ts              # QQ 入站消息 → agent.followup()
│   ├── outbound.ts             # session/event → QQ sendMarkdown
│   ├── outbound-buffer.ts      # 流式缓冲
│   └── chunker.ts              # Markdown 文本切分
├── session/                    # 会话管理层
│   ├── session-manager.ts      # QQ peer → Agent 映射
│   └── idle-evictor.ts         # 闲置回收
├── model/                      # 模型路由层
│   ├── model-resolver.ts       # 路由解析
│   ├── prefs-store.ts          # per-peer 偏好持久化
│   └── settings-reader.ts      # settings.yaml 只读
├── shared/                     # 共享工具
│   ├── utils.ts                # 通用函数
│   ├── scope.ts                # scope/peer 提取
│   └── send-helper.ts          # 分块发送
├── commands/                   # 斜杠命令
└── typings/                    # 外部模块声明

会话路由

sessionKey: qqbot:${appId}:${scope}:${peerId}，由 SHA-256 确定性派生 SessionId，重启后可恢复。

解析策略：进程内复用 → 持久化恢复 → 全新创建。

设计原则

• 纯 Cordis 插件 — 遵循 dsh "Plugins, not loop changes" 原则
• 声明式依赖 — inject = ['agents']，不直接耦合其他插件
• 会话隔离 — 每个 QQ 私聊用户/群聊各一个独立 Agent
• Preset 支持 — 可通过 agent-presets 服务挂载预设（工具集、prompt 等）
• 闲置回收 — 超时自动 dispose Agent，防止内存泄漏
• Markdown 输出 — 回复以 Markdown 格式发送，支持代码块/表格感知切分

本地开发

# 安装依赖
pnpm install

# 构建
pnpm build

# 开发模式（watch）
pnpm dev

# 用 --patch 方式调试
export QQBOT_APPID="xxx" QQBOT_SECRET="xxx"
npx @deepseek-ai/dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml

License

MIT