QQ 陪聊机器人 bluechonk/dsh-qqbot

dsh-qqbot

DeepSeek Harness 插件：把 QQ 私聊与群聊接进 dsh，AI 以「大肥鱼」的身份陪聊——不挂终端与文件工具，只说话。

能力

- 群友式陪聊：会话默认跑在插件自带的 qqchat 预设上，零工具（没有终端、没有文件读写），人格与说话风格由插件内置定义；支持用 /preset 切换到其他预设
- 自主接话：群里没人点名她时，由本地词法门控判断这条值不值得接——接不接最后由模型自己决定
- 沉默是常态：模型可以回 [skip] 表示这一轮不回复，不是每条都接
- 拟人节奏：回复带随机延迟（默认 1.2 秒起 + 每字 80ms + 抖动），不秒回
- 端内绑定：设置页「QQ 机器人」分区里扫码绑定、手动填写、换绑、解绑，全程不跳系统浏览器
- 提问卡片：模型需要确认时，在 QQ 里发带按钮的卡片，点按钮即作答
- 审批卡片：宿主触发审批时，QQ 里直接点「允许 / 拒绝」
- 富媒体理解：收到图片或视频会下载并分析；也能把文件发回 QQ
- 会话隔离：私聊与群聊各自独立；会话键含 appId，多账号天然不串
- 配置面板：访问控制、是否必须 @、流式开关、自主接话、回复节奏、模型与提示词覆盖，都在设置页里改

截图

群聊陪聊

私聊陪聊

扫码绑定

安装、更新、卸载

方式一：在「插件」页粘贴 GitHub 链接（推荐）

DSH 的「插件」页右上角有「+ 添加插件」，弹窗第一行写着「输入插件的包名、GitHub 仓库地址或本地目录路径」——把下面的链接粘进去点「安装」即可，界面会把它识别为「Git 仓库」：

https://github.com/bluechonk/dsh-qqbot

装完宿主会把包写进 profile 的 dependencies（值为 github:bluechonk/dsh-qqbot），并把它加进 dsh.profile.bundles；随后设置页导航里「QQ 机器人」就出现了。

从 GitHub 安装会现场跑一次构建（仓库通过 prepare 钩子在安装期编译 dist/ 与 lib/），第一次约 30 秒，之后走缓存。

方式二：插件市场索引（可浏览、可一键安装）

本仓库自带插件市场索引 market-index.json（指向本仓库的 git 源，锁定 commit）。启用市场 bundle 后，在 DSH「设置 → 插件」页的索引源输入框粘贴下面这条 GitHub 链接，Discover 标签里就会出现本插件，点「安装」即可：

https://raw.githubusercontent.com/bluechonk/dsh-qqbot/main/market-index.json

启用市场 bundle（一次性；注意版本要与当前 DSH 运行时兼容，不兼容时宿主会拒绝启用并提示对应版本）：

plugin_manager set_bundle --target "@deepseek-ai/dsh-experimental-plugin-market-bundle" --enabled true

方式三：工具与命令行

工具（对话里可用 plugin_manager 工具） plugin_manager install_bundle --target "https://github.com/bluechonk/dsh-qqbot"

命令行（转发给 profile 目录里的 pnpm）
dsh plugin --profile desktop add "https://github.com/bluechonk/dsh-qqbot"

装完先在「设置 → QQ 机器人」里扫码绑定，绑定成功即开始工作。

本地开发

从源码开发时，把仓库目录链接进 profile 的 node_modules，宿主按链接目标加载，改完重新构建并刷新页面即可生效：

dsh plugin --profile desktop add link:/path/to/dsh-qqbot

构建：

pnpm install
pnpm build # tsc（宿主半 → dist/）&& tsdown（浏览器半 → lib/client.js）

用 link: 而不是 file:：包管理器对 file: 目录依赖不跟踪内容变更，改完源码不会自动重新打包；link: 是软链，构建完即刻生效。

AI 助手安装

1. 先读本文件全文（尤其「已知限制」）。
2. 用 plugin_manager 的 install_bundle，target 传本仓库的 GitHub 地址。
3. 读安装结果：application 为 applied 才算装好；failed 时按 error.diagnostic 排查后重装同一个包，不要新建副本。
4. 用 cordis_inspect_query（Slots.listSubTree，根 settings.section）确认 dsh-qqbot 出现在列表里。
5. 绑定凭据：在「设置 → QQ 机器人」分区扫码，或手动填 AppID / AppSecret。

配置

配置写在 profile 的 cordis.patch.yml 的 im-qqbot 条目里，也可以在设置页里改（改完自动重载）。

设置页可改的

| 配置 | 类型 | 默认值 | 说明 |
| settingsNs | string | im-qqbot | 实例命名空间（多机器人时每实例唯一，决定路由/数据目录） |
| botName | string | - | 实例显示名（页面上区分多个机器人） |
| enabled | boolean | true | 是否启用该实例（停用则不建连接、不响应消息） |
| requireMention | boolean | false | 群聊是否必须 @ 机器人才回应（自主接话开启时由判定接管） |
| streaming | boolean | false | 是否启用流式输出（群聊始终不启用） |
| showToolResults | boolean | false | 是否展示工具调用成功结果（错误始终展示） |
| debug | boolean | false | 调试模式 |
| rawEventLog | boolean | true | 把未知网关事件记录到 ~/.dsh-qqbot/raw-events.jsonl（用来探测平台是否推送某类事件，比如「戳一戳」） |
| middlewareLog | boolean | true | 把中间件链留痕记录到 ~/.dsh-qqbot/middleware-events.jsonl（丢弃/越权/合并/命令处理） |
| provider | string | - | LLM 服务商名称，留空继承宿主默认 |
| model | string | - | 模型名称，留空继承宿主默认 |
| reasoningEffort | off/low/medium/high/max | - | 思考强度，留空由宿主决定（qqchat 建议 off） |
| preset | string | qqchat | 插件级默认 preset（per-peer 切换优先，见 /preset） |
| groupPrompt | string | - | 群聊额外 system prompt |
| directPrompt | string | - | 私聊额外 system prompt |
| access.c2cMode | open/allowlist/disabled | open | 私聊访问模式 |
| access.c2cAllow | string[] | [] | 私聊白名单（user openid） |
| access.groupMode | open/allowlist/disabled | open | 群聊访问模式 |
| access.groupAllow | string[] | [] | 群聊白名单（group openid） |
| admin.enabled | boolean | true | 启用命令权限校验（关掉则所有人都能执行高权限命令，仅调试用） |
| admin.openids | string[] | [] | 管理员 openid 白名单（用 /whoami 查看自己的 openid） |
| proactive.enabled | boolean | true | 自主接话总开关 |
| proactive.minScore | number | 0.55 | 放行门槛（0~1） |
| proactive.cooldownMs | number | 120000 | 同群两次主动接话的最小间隔（ms） |
| proactive.maxPerHour | number | 6 | 同群每小时主动接话上限，0 = 不限制 |
| proactive.minLength | number | 6 | 参与判定的最短文本长度 |
| proactive.observer | boolean | true | 记录判定日志 |
| people.enabled | boolean | true | 群友档案（记住昵称、称呼、互动次数） |
| people.maxAliases | number | 2 | 注入提示时最多带几个别名 |
| antiRepeat.enabled | boolean | true | 防复读（把「你最近说过」前置给模型） |
| antiRepeat.historySize | number | 5 | 记住自己最近几条发言 |
| stickers.enabled | boolean | false | 表情包（需先导入图库，见 docs/表情包.md） |
| stickers.maxTextReplies | number | 3 | 连续多少条纯文字后才允许配一个表情 |
| stickers.cooldownMs | number | 600000 | 同一张表情的冷却时间（ms） |
| replyDelayMs | number | 1200 | 回复延迟基础值（ms），0 = 关闭 |
| replyDelayPerCharMs | number | 80 | 回复延迟每字增量（ms） |
| replyDelayJitterMs | number | 1500 | 回复延迟随机抖动上限（ms） |
| replyDelayMaxMs | number | 8000 | 回复延迟单次上限（ms），0 = 不封顶 |

需要改 patch 文件的

这些是调优类字段，日常不必动：

| 配置 | 类型 | 默认值 | 说明 |
| appId / appSecret | string | - | QQ 机器人凭据（绑定后自动写入） |
| cwd | string | - | Agent 工作目录（设置页只读展示） |
| textChunkLimit | number | 4500 | 单条消息最大字符数 |
| sessionIdleTimeout | number | 1800000 | 会话闲置回收时长（ms） |
| maxQueue | number | 20 | 并发队列最大长度 |
| processingTimeoutMs | number | 1800000 | 单次处理超时（ms） |
| askTimeoutMs | number | 300000 | 待答问题超时（ms） |
| historyLimit | number | 10 | 群历史缓冲条数 |
| media.enabled | boolean | true | 富媒体理解开关 |
| media.maxMB | number | 200 | 富媒体下载上限（MB） |
| media.ttlHours | number | 24 | 富媒体存活时长（小时），0 = 永不过期 |
| vision.enabled | boolean | false | 视觉理解开关 |
| vision.provider / vision.model | string | - | 视觉模型 provider 与 model |
| sendFile.restrictPaths | boolean | true | 附件发送的路径白名单 |
| sendFile.extraRoots | string[] | [] | 额外允许访问的根目录 |

自主接话

proactive.enabled 打开后，群里没点名她的消息会先过一道本地判定（零 token，不调模型）：

| 特征 | 影响 |
| 疑问句式、求助词、提到「肥鱼 / 鲸鱼」 | 加分 |
| 灌水噪声（「哈哈」「666」「打卡」…） | 减分 |
| 这条 @ 的是别人 | 减分（那轮对话的方向是别人） |
| 过短、纯表情 | 直接不接 |

过了判定才会唤醒模型；模型还会再判一次，插话不自然就回 [skip] 沉默。

判定日志落在 ~/.dsh-qqbot/proactive-scores.jsonl，每行一条（含分数、理由、是否被冷却拦住），据此调 minScore 即可。

注意：「没被 @」本身不扣分——那正是她该主动接话的常态。扣分的是「这句 @ 的是别人」。

配置存放位置

profile <DSH_HOME>/profiles/<profile>/cordis.patch.yml # im-qqbot 条目本地数据 <HOME>/.dsh-qqbot/ # 判定日志、启动留痕、模型偏好

内置命令

| 命令 | 说明 | 权限 |
| /new（别名 /reset /clear） | 开始新会话（清空上下文） | 主人 |
| /compact | 压缩会话历史（摘要替换旧记录，保留上下文） | 主人 |
| /model | 查看或切换模型 | 主人 |
| /preset | 查看或切换 preset（默认 qqchat，切换会重建会话） | 主人 |
| /stop | 中止当前生成 | 主人 |
| /bot-status | 查看当前会话状态 | 主人 |
| /whoami | 查看自己的 openid 与权限 | 所有人 |
| /bot-ping | 网络延迟检测（返回传输与处理耗时） | 所有人 |
| /bot-version | 查看版本信息 | 所有人 |
| /bot-help（别名 /help） | 查看所有指令（按权限过滤，含别名） | 所有人 |

群聊里命令必须 @ 机器人（SDK 的要求）；私聊直接发即可。
命令名打错或没注册的 /xxx 不会报错，会退化成普通聊天——所以觉得「命令没生效」时，先看 ~/.dsh-qqbot/middleware-events.jsonl 有没有 kind=handled：没有就是没被识别。

命令默认仅限主人——不显式标注的命令都要求管理员权限，避免新增命令时忘记加校验导致意外开放。

主人身份靠 admin.openids 白名单配置：平台不告诉机器人谁是创建者（QQ 机器人 API 没有 owner 概念），所以必须显式配置。第一次配置：

1. 在群里发 /whoami，机器人回复你的 openid
2. 把那串 id 填进 admin.openids（设置页或 cordis.patch.yml）
3. 重启 DSH

填之前，高权限命令对所有人关闭（安全默认），拒绝文案里会提示上面这几步。

多个机器人

一个 dsh 可以同时接多个 QQ 机器人：在 profile 的 cordis.patch.yml 里加多行插件行， 每行一个唯一 settingsNs。

- id: im-qqbot
config:
settingsNs: im-qqbot
botName: 工作号 appId: '1905526094' appSecret: ''
- id: im-qqbot-2
config:
settingsNs: im-qqbot-2
botName: 摸鱼号 appId: '1905526095' appSecret: ''

也可以完全在页面上操作：设置 → QQ 机器人 → 实例列表里「＋ 添加机器人」、停用/启用、删除，点某个实例的「设置」切换要编辑的配置。

要点：

- settingsNs 必须唯一。重复会让两个实例互相覆盖配置与数据，而且症状是静默的，所以启动时会校验，冲突直接拒绝启动并报错
- 每个实例的本地数据（群友档案、表情包、判定日志）按 settingsNs 分目录——多个机器人是不同的「人」，对群友的称呼与亲疏各自独立
- 会话按 appId 隔离，两个机器人加到同一个群不会串会话
- enabled: false 停用某实例：不建连接、不响应消息，配置保留
- 默认实例（settingsNs: im-qqbot）不可删除

细节见 docs/多机器人.md。

内部机制

- Host 半挂在同源路由 /qqbot/im-qqbot/（绑定状态、扫码、手动填写、配置读写），只接受本机同源请求
- Client 半注册 settings.section（order 7，标签「QQ 机器人」）与右侧栏页签「QQ 机器人绑定」；未绑定时右侧栏自动弹出引导页
- 入站：historyBuffer 挂在门控之前，群消息全量入内存历史（未点名她的也进）；mentionGate 只标记不拦，拦截交给 proactiveGate
- 判定分两层：L1 本地词法门控（零 token）挡掉明显不值得的；L2 模型在回合内自己决定说不说
- 出站：session/event → sendMarkdown，发送前走拟人延迟；回复恰为 [skip] 则不发送
- 会话键 qqbot:${appId}:${kind}:${peerId}，私聊与群天然隔离
- 全部视觉用 --dsw-alias- 令牌，不硬编码颜色

细节见 docs/内部机制.md。

版本线

本插件是自用的，版本固定走 0.1.x：0.x 的语义就是「初始开发、不承诺兼容性」——配置项、接口、界面都还可能再改。按 SemVer 的用法：

- 0.1.0 → 0.1.1 → 0.1.2：同一版设计内的修复与小改；
- 0.2.0：换一版设计（配置格式或接口不兼容），届时需迁移既有配置；
- 什么时候才升 1.0.0：有别人开始依赖本插件的配置格式与接口时，才需要给出稳定性承诺。

宿主自身的版本兼容（跨 DSH 升级）不由本插件的版本号决定，而由 engines.dsh / peerDependencies 声明与宿主的版本豁免机制管。

已知限制

- 支持多个 QQ 机器人（在 profile patch 里加多行插件行，每行一个 settingsNs）；增删启停见 docs/多机器人.md。单实例行为与之前逐字一致
- 主动开口受平台配额限制：QQ 的被动回复只有约 5 分钟窗口，超时只能走「主动消息」，而主动消息有按群按月的配额。所以「冷场起话题」只做到判断时机 （features/idle-topic/），真正发消息待配额确认
- 表情包默认关闭且仓库不含任何素材（版权归原作者）：功能与发送链路都已实现，但需自备图片并按 docs/表情包.md 建图库；另需机器人具备发送图片的权限
- 群聊不支持流式输出（QQ 的群消息没有流式接口），私聊才支持
- 图片能看了：群里发的图片会作为多模态输入直接附给模型（不再只给一行文件路径）。
模型不支持图片输入时自动退回「只给路径」，不会让整轮失败。
qqbot_describe_image 工具是另一条路，需要开 vision.enabled 且预设带工具—— qqchat 是零工具预设，所以默认走附图这条路
- 设置页文案硬编码中文，暂未接入 i18n
- 依赖 QQ 开放平台的群消息推送策略：机器人只能收到平台推给它的消息
- 拟人化能力全部未在真实群聊实测过（判定逻辑有单测覆盖）：照 docs/验收清单.md 走一遍即可确认

开发

pnpm install
pnpm build # tsc + tsdown
pnpm typecheck:client # 浏览器半的类型检查（主 tsconfig 不覆盖 src/client）
pnpm test # vitest：397 个用例

文档：

- docs/README.md —— 文档总索引（含排查入口）
- docs/版本控制.md —— 分支模型、提交规范、推送门禁
- docs/内部机制.md —— 架构与实现要点
- docs/自主接话.md —— 判定与开口的设计
- docs/拟人化路线图.md —— 拟人化能力清单与规划
- docs/多机器人.md —— 多账号接入方案
- docs/验收清单.md —— 人工验收步骤

许可证

MIT

本项目基于 tencent-connect/dsh-qqbot（MIT）改造，原始版权声明保留在 LICENSE。