前言¶

在 DSH 里做自动化或对话式助手时，常见需求是让模型能读 QQ 私聊和群消息、代你回复，或按规则自动应答。自己写 OneBot 客户端、维护会话映射和去重，工作量大且容易和宿主进程的状态打架。社区插件 mira_qqbot（维护者 Stella-Mira）走另一条路：用 OneBot v11 正向 WebSocket 连本机 NapCat（跑在你的 QQ 客户端里），把「你本人的 QQ」交给 DSH，并把协议能力收成 qq_* 工具；账号池、会话绑定、入站路由与 message_id 去重则交给同生态的 mira_account（1.18.0 起协议层与账号层刻意拆分）。下面介绍它是什么、能做什么，以及如何配置与使用。

这是什么¶

mira_qqbot 是 DSH 的 QQ 接管插件（协议层），当前版本 1.18.0（MIT）。在 SkillHub 社区目录中归类为 联网工具（目录页：https://www.skillhub.cn/plugins/Stella-Mira/mira_qqbot；源码：https://github.com/Stella-Mira/mira_qqbot）。

一句话定位：连 NapCat 的 OneBot 端点，向模型暴露 21 个 qq_* 工具，并可选地把入站消息投递给 agent（steer/queue、忙通告、超时、/stop 与 /new 等）。

硬依赖：安装 mira_qqbot 必须同时安装 mira_account。宿主需注入 tools、agents、workspaceRegistry、miraAccount；缺少 mira_account 时本插件 deliberately 不加载，工具不会出现，便于排查「起来了但发不出去」类问题。

配置与附件落盘位置（DSH_HOME 缺省为 ~/.dsh）：

$DSH_HOME/mira_config/mira_qqbot/
  config.json      schemaVersion 1；含 accessToken 时文件权限 600，且永不回显/不进日志
  files/           入站附件；可用 mediaDir 覆盖

核心功能¶

协议与账号分工¶

自 1.18.0 起，本插件只做 OneBot 连接、事件解析、媒体与 qq_* 工具；旧的 chatId → sessionId 本地表（<agentCwd>/data/meta.json）已删除，一律使用 mira_account 的绑定表。与 mira_account 的三条约定在 README 中写死：

入站：不维护本地 session 映射；已绑定 peer 由本插件 route 投递（支持 per-peer queue、忙通告、超时）；未绑定走 miraAccount.inbound() 与账号 inboundPolicy。
出站：qq_send_* 经 miraAccount.send；发送成功会把该会话登记为该 peer 的 taker（反向绑定）。
错误：工具统一返回 {ok:false,error:{code,message,hint}}，平台侧常见码包括 delivery/failed、binding/conflict、account/*、config/*。

连接层支持 WebSocket 指数退避重连（reconnectMinMs / reconnectMaxMs）、单次 API 调用超时（callTimeoutMs），以及断线期间的 积压策略（backlog.policy：drop / latest_n / replay）。

qq_* 工具集（21 个）¶

模型侧主要通过这些工具操作 QQ（前缀均为 qq_）：

类别	工具
状态与角色	`qq_status`、`qq_role`
资料与列表	`qq_get_login_info`、`qq_get_friend_list`、`qq_get_group_list`、`qq_get_group_member_list`、`qq_get_stranger_info`
发送	`qq_send_private_msg`、`qq_send_group_msg`、`qq_send_msg`、`qq_send_media_file`、`qq_send_voice`
接收与历史	`qq_recv_messages`、`qq_get_msg`、`qq_get_group_msg_history`
管理与审批	`qq_delete_msg`、`qq_set_group_ban`、`qq_set_group_kick`、`qq_set_group_whole_ban`、`qq_handle_friend_request`、`qq_handle_group_request`
逃生舱	`qq_api`（通用 OneBot action）

qq_recv_messages 使用环形缓冲（默认上限 bufferSize: 500），按 since 增量拉取；入站去重在 mira_account 投递路径完成，缓冲本身保留原始事件视图。

自动应答与群策略¶

reply.* 配置块控制是否把入站消息投给 agent（reply.enabled）、人设与规则提示词、私聊白名单（reply.privateWhitelist）、群内 @/关键词触发（reply.groupAccess、reply.trigger.*）、消息合并窗口（reply.mergeWindowMs）、agent 超时（reply.agentTimeoutMs）以及 /new、/stop 命令文案。默认入站投递方式为 steer（插话），可按 peer 在 delivery.byPeer 中改为 queue。

安装与启用¶

README 与仓库 未给出 单独的 dsh plugin add … 一行命令；安装方式请以 SkillHub 目录页 与当前 DSH 版本的插件管理文档为准，源码仓库为 https://github.com/Stella-Mira/mira_qqbot。不要只装本插件：须一并启用 mira_account，并在 $DSH_HOME/mira_config/mira_account/accounts.json 登记 QQ 账号（例如 {"id":"qq-main","platform":"qq","enabled":true,"inboundPolicy":"create"}）。

1. 部署 NapCat 与 OneBot WebSocket¶

插件不替你做 QQ 登录；需要本机 NapCat 暴露 OneBot v11 正向 WebSocket。仓库自带脚本（用法见脚本头部注释）：

bash scripts/setup-napcat.sh            # 部署/配置 OneBot WS
bash scripts/start-napcat.sh            # 按 napcat.conf 启动

Linux/macOS 可用 setup-napcat.sh / start-napcat.sh；Windows 使用 setup-napcat.ps1，启动脚本在原生环境下需 Git Bash 或 WSL。核心目标是把 ws 地址 与 access_token（若启用）记下来，填进下面配置文件。

2. 编写 config.json¶

首次加载会在 $DSH_HOME/mira_config/mira_qqbot/config.json 生成仅含 schemaVersion 与 _hint 的模板。必填项包括 wsUrl（如 ws://127.0.0.1:3001）；为空时工具会直接返回 config/missing，本插件不会自动探测端口。accountId 应对应 mira_account 里登记的 id；若账号池只有一个 QQ 账号且留空，会 warn 一次并使用该账号；多个 QQ 账号且未指定则会报 config/missing 并列出候选。

最小可用示例（来自 README，请把 agentCwd 换成你的 DSH 工作空间路径）：

{
  "schemaVersion": 1,
  "wsUrl": "ws://127.0.0.1:3001",
  "accessToken": "",
  "accountId": "qq-main",
  "reply": { "enabled": true, "agentPreset": "stella", "agentCwd": "<您的 workspace>" }
}

accessToken 为空字符串是合法值（NapCat 未开鉴权时）；非空时只通过 OneBot Authorization 头发送，不会出现在日志或 qq_status 返回值中。

3. 重启 DSH 并自检¶

重启宿主后，在 agent 会话中调用 qq_status：期望 connected: true，且 config.wsUrlConfigured 等为 true。若缺 wsUrl，qq_status 本身会返回 config/missing（而不是空状态对象）。插件自带 smoke 测试（不连真实 NapCat）：

cd mira_qqbot && node test/smoke.mjs

期望末行：==== ALL PASS（219 项断言）====，退出码 0。

典型用法¶

用 qq_status 确认链路¶

连接正常时，qq_status 会汇总连接态、selfId、绑定行、队列长度、断线积压计数、忽略原因（白名单/群未触发等）以及 legacyConfigKeys（若 profile 里仍保留 1.17 时代的 autoReply.* 键）。缺配置时优先读 error.code 与 hint，例如 wsUrl 未填时按 hint 编辑 config.json。

模型主动发消息¶

统一入口 qq_send_msg：纯数字 QQ 号走私聊，group:群号 走群聊。发送类工具默认按纯文本发出（会对 [ ] & 做 CQ 实体转义）；确需 CQ 码（如 [CQ:at,qq=…]）时传 cq: true。成功时返回含 messageId 与 binding 的对象；若 peer 已被其他会话占用，会返回 binding/conflict，hint 说明可用 force:true 接管或 observer:true 旁听。

拉取缓冲中的入站¶

关闭自动应答（reply.enabled: false）或只想由模型轮询时，使用 qq_recv_messages，以返回的 maxSeq 作为下次的 since。hasMore / truncated 为 true 时继续拉，避免跳过中间消息。

从 1.17 升级¶

若你曾使用旧版本地 meta.json 映射，需按 README「迁移（1.17.0 → 1.18.0）」备份 profile 与 meta，登记 mira_account 账号，把 autoReply.* 键迁到 reply.*，并用 tool_shared/migrate/bindings.mjs 把旧绑定写入 mira_account。升级后群触发、白名单与默认投递方式（steer 相对旧版 followup）有文档化的语义变化，升级前应对照 README 中的对照表。

适用场景与注意¶

适合谁：已在 DSH 中开发 agent，希望用真实 QQ 号（非独立 Bot 账号）收发消息、查好友/群/成员、处理好友/加群申请，并需要与 mira_account 统一的绑定与多会话模型。

运行权限：插件随 当前 DSH 进程 运行，能访问进程可见的文件与环境；安装前请阅读源码与 MIT 许可证，自行评估 NapCat、OneBot 与 QQ 使用条款带来的风险。

配置与安全：accessToken 与账号凭证文件应限制权限；勿在不可信环境暴露 OneBot WebSocket 端口。reply.privateWhitelist 与 reply.trustedUsers 语义不同：前者管私聊是否应答，后者主要影响提示词中的【识别名单】。

生态说明：DSH 主张「一切皆插件」；SkillHub 目录是社区站点，与 DeepSeek / 幻方无官方从属关系。

结尾¶

mira_qqbot 把 NapCat + OneBot v11 收成 DSH 内的 qq_* 工具，并与 mira_account 分工处理绑定与路由；配好 wsUrl 与账号池后，可用 qq_status 验连接，用发送/接收工具或 reply.* 自动应答完成日常 QQ 自动化。

目录页：https://www.skillhub.cn/plugins/Stella-Mira/mira_qqbot
GitHub：https://github.com/Stella-Mira/mira_qqbot

mira_qqbot：通过 OneBot v11 把 QQ 接到 DeepSeek Harness

前言¶

这是什么¶

核心功能¶

协议与账号分工¶

qq_* 工具集（21 个）¶

自动应答与群策略¶

安装与启用¶

1. 部署 NapCat 与 OneBot WebSocket¶

2. 编写 config.json¶

3. 重启 DSH 并自检¶

典型用法¶

用 qq_status 确认链路¶

模型主动发消息¶

拉取缓冲中的入站¶

从 1.17 升级¶

适用场景与注意¶

结尾¶

精选优惠券

mira_qqbot：通过 OneBot v11 把 QQ 接到 DeepSeek Harness

前言¶

这是什么¶

核心功能¶

协议与账号分工¶

qq_* 工具集（21 个）¶

自动应答与群策略¶

安装与启用¶

1. 部署 NapCat 与 OneBot WebSocket¶

2. 编写 config.json¶

3. 重启 DSH 并自检¶

典型用法¶

用 qq_status 确认链路¶

模型主动发消息¶

拉取缓冲中的入站¶

从 1.17 升级¶

适用场景与注意¶

结尾¶

精选优惠券

相关文章