dsh-onebot-qq

dsh-onebot-qq

DSH插件式的QQ机器人，经 OneBot v11 协议收发消息 —— 协议端可换：任意 OneBot v11 实现都行（本机线上在用的是 SnowLuma，另有 OneBot 等实现）。 微内核 + 可插拔子插件，Linux / Windows通用，装完在控制台填几项就能用。

先读：docs/README.md（功能手册总览：按「我要做什么」找文档 + 全部功能索引）。 日常用：docs/使用说明书.md（安装 → 连接 → 各功能怎么用 → 人设怎么写）。 想自己装：本文「安装」；只想让 DSH 帮你装：把 docs/安装与卸载.md（Windows 用 docs/Windows安装.md）整份甩给它。

特性

前置要求

安装

① 装插件（三选一）

# GitHub（推荐）
dsh plugin --profile web add github:YUsaltyfish/dsh-onebot-qq

# 本地 tgz（npm pack 产物）
dsh plugin --profile web add /abs/path/dsh-onebot-qq-0.1.1.tgz

# 本地目录（link 不复制源码；改代码后仍需插件重载或重启 DSH）
dsh plugin --profile web add link:/abs/path/dsh-onebot-qq

也可以在 DSH 桌面端的「设置 → 插件」里填 GitHub 仓库地址安装。

装完还要「建数据目录 → 启动 → 控制台新手向导连协议端」才算跑通：完整步骤、升级、卸载、回滚见 docs/安装与卸载.md；Windows 见 docs/Windows安装.md。

可选：想让 QQ 线连全局工具（ops_* / agent-team / MCP 资源）也挡住，再装配套的独立插件 dsh-onebot-qq-opsgate： dsh plugin --profile web add github:YUsaltyfish/dsh-onebot-qq-opsgate（必须装在 dsh-onebot-qq 之后）。 不装也能正常用，只是 QQ 会话的工具面更大，token消耗略微增加，可能导致群聊天时调用不该用的工具而产生风险。详见 docs/安装与卸载.md。

可选：「链接解析」需要自己准备解析侧车（独立小服务）；不装也不影响聊天，详见 解析侧车。

快速开始（4 步）

1. 协议端登录 QQ，开启 WebSocket（默认 ws://127.0.0.1:3001）与 HTTP（默认 http://127.0.0.1:3000），记下 token（多数实现可空，SnowLuma 必填）。
2. DSH 设置 →「QQ 控制台」→「OneBot 连接」页（任意 OneBot v11 协议端都填这里）填地址/token → 点「测试 OneBot 连接」。
3. 「群聊」页顶部填主人 QQ（必填）→ 保存后自动连接。
4. 在 QQ 里 @ 机器人（或私聊）→ 有回复即可用。

首次启动缺 adminQq 会进入「待配置模式」：控制台和工具可用、不连协议端，填完自动连接。

控制台与人设

• 控制台集成在 DSH 内置设置页，可配置程度高，含独立消息监测规则页；生效时机按字段区分，见 配置参考·热改说明。
• 内置运维：离线自检无需扩展；临时缓存清理和配置备份去重先预演再确认，限制范围并重验变化，见内置运维说明。
• 人设可以直接让 AI 照随包的 personas/_模板.md 写一份；优秀程度看用心程度，推荐让模型多用示范对话。

可选：解析侧车（链接解析）

link-parser 默认关闭：开启后将 B 站/抖音链接解析为视频、图集发到群里；缺侧车时交模型按链接文字处理。不装侧车不影响聊天与其余功能。

侧车是你自己部署的独立 HTTP 服务（本仓库不附带），负责媒体下载与合流，插件通过 HTTP 调用它；语言随意（Python / Node / Go），默认监听本机 3972，实现以下接口：

POST /parse —— 链接解析（link-parser 用）

// 请求
{ "url": "https://b23.tv/xxxx", "session": "会话标识（可忽略）", "limit": 9 }
// 响应
{
  "media":   [ { "path": "/tmp/xxx.mp4", "kind": "video", "size": 1234567 },
               { "path": "/tmp/y1.jpg",  "kind": "image", "size": 88000  } ],
  "skipped": [ { "reason": "too_big", "cover": "/tmp/cover.jpg" } ]   // 可选：跳过的原因 + 兜底封面
}

kind 取 video / image；path 必须是本机真实文件（插件直接读它发到 QQ）。视频没合流成功时，用 skipped[].cover 先发封面。

侧车本身需要装什么

• ffmpeg —— B 站 DASH 音视频合流等媒体处理，是否需要取决于侧车实现；
• 下载器 —— yt-dlp 或各平台自己的接口；抖音通常需要配 cookie，否则会 download_failed；
• 运行环境 —— Python 3 或 Node，随你顺手。

怎么开启与配置

• 地址留空 = 不解析；
• 换端口可改地址；跨机不只是改 IP：响应媒体路径必须通过共享挂载以一致绝对路径在 DSH 进程中可读。发到 OneBot 的本地文件引用还要求协议端可读同一路径（或其明确支持的路径映射）。当前没有自动跨机媒体上传/路径搬运，只有文本网络连通不代表媒体可用；勿把侧车暴露到公网；
• 侧车自己也要卡体积/时长（插件侧还有一道 maxBytes 上限，默认 100MB）。

文档

其余文档（Windows、配置参考、排错、运维接口）统一从 功能手册总览 进。

隐私

• 包内不含任何真实 QQ 号、群号、token、API Key 或服务器路径；示例都是占位值。
• 运行数据（配置、人设、表情库、群记忆、日志）都在你自己的数据目录，不进仓库、不进 npm 包。

License

MIT

---

⚠️ 请注意：本项目的主要贡献来自于蓝色大肥鱼——本人由于能力限制，仅通过不断“压力”大肥鱼来进行代码编写和部分细节调整。因此也诚邀同好者共同测试和维护。

[!WARNING] 本插件和文档由 AI 生成，内容仅供参考，请仔细甄别。