dsh-qqbot-buddy
把 DeepSeek Harness(dsh) 接到 QQ 官方机器人平台的插件。自带独立管理控制台: 多机器人隔离、配置档与作用域绑定、可管理的工具与技能、SQLite + FTS5 长期记忆与知识库、 群友库与人格卡,并提供群日报、语音(TTS / ASR)以及卡片 / 转发 / 引用的结构化渲染。
| 版本 | 发布通道 | 运行环境 | dsh | 许可证 |
|---|---|---|---|---|
1.0.0-rc.1 |
npm latest + next(预发布 RC) |
Node.js ≥ 24 | 0.2.2 – 0.2.x |
MIT |
现在还是预发布(RC):配置项与接口仍会调整,升级前请先备份数据目录(见 数据与备份)。
latest与next当前都指向1.0.0-rc.1:装不带标签也行,@next则始终是最新预发布构建。
快速开始
# 1) 装进某个 dsh profile(不写 --profile 时默认 web)
dsh plugin --profile web add dsh-qqbot-buddy # = @latest
dsh plugin --profile web add dsh-qqbot-buddy@next # 要最新预发布时用这个
# 2) 重启 dsh,控制台随插件一起启动
dsh web
# 3) 取 token 登录控制台
cat ~/.dsh-qqbot/v2/console-token.txt # → http://127.0.0.1:6198
- 控制台「机器人」页新建机器人,填 QQ 开放平台的
appId/appSecret,保存后启动; - 在 QQ 里 @ 机器人或私聊发一句,确认链路通了;
- 想调人设、回复策略、工具与技能,去「配置档」页;想给某个群单独一套策略, 在「机器人 → 详情 → 配置档绑定」里按 scope 绑定。
功能特性
| 模块 | 说明 |
|---|---|
| 独立控制台 | 随插件进程启动的 Web 管理台(默认 127.0.0.1:6198),token 登录、SSE 实时事件、无需额外部署前端或数据库;深 / 浅色主题(跟随系统 / 浅色 / 深色,顶栏一键切换,首屏不闪);与 dsh Web 双向入口(控制台顶栏「dsh Web ↗」;dsh Web 会话头部「…」菜单里的「QQBot 大屏」) |
| 多机器人 | 每个 bot 独立工作目录 <workspace>/bots/<botId>,凭据、会话、日志互不影响;同一进程可管多个 bot |
| 配置档 + 绑定 | 三层策略:默认值 → global → profile;绑定决定「哪个群用哪份配置」(精确 scope > 类型通配 > bot 通配 > 默认档)。切换配置档不丢记忆 |
| 提示词管理 | 人设卡、人格卡、口头禅、能力边界、工具指引;控制台提供提示词拼合预览:有 live 会话时展示模型真正收到的分段与字符数,没有时回退模拟拼合 |
| 工具与技能 | 发现宿主全部工具与技能,按配置档白名单 / 黑名单放行(真正生效);装配三态(已装载 / 已声明 / 索引中)+ 常驻 / 按需档位,按需装载不占 schema;技能白名单按配置档过滤模型侧目录,支持 /tools、/skills、/heal 排查 |
| 长期记忆 | SQLite + FTS5,按用户原话召回(多词自动回退),支持自动提炼(每 N 轮)与手动提炼 |
| 消息流水 | 两层:触发轮次(messages,供记忆 / 检索)+ 全量群消息(flow_messages,门控前落库,含没 @ 的旁观发言);两层保留期分别可配 |
| 群日报 | 定时(默认 23:30)按群生成日报并主动发送;内置纸刊 / 深色两套卡片模板 + 自定义模板插槽(<dataDir>/templates/<名字>/index.html);控制台可实时预览、切氛围(模型选择 / 随机 / 指定)、一键应用模板、直接安装模板;/daily 手动生成 |
| 关系增量 | 每日按互动调整群友 affinity(-2..2),带证据校验、冷却与周上限,写审计 |
| 知识库 | 文本 / URL 入库,标题与小标题可检索,文档列表查看;FTS5 trigram + LIKE 双通道 |
| 群友库 | 记录 openid / 昵称 / 备注 / 画像;发言人自动注入、被 @ 的人懒加载,避免整库注入 |
| 人格卡 / 表情包 | 本地图片登记、emotion 标签、每日配额;人格卡可切换与独立编辑 |
| 图片能力 | 视觉理解(贴图描述)、生成 / 改图结果自动补发到 QQ,不需要人工提醒 |
| 语音 | TTS 供应商按 默认音色 / 音色克隆 / 文字设计 分块配置(Edge、MiMo、MiniMax、DeepSeek、百炼、OpenAI 兼容、自定义 HTTP、本地命令),支持试听;入站 QQ 语音可接 ASR(DeepSeek 官方 / MiMo / OpenAI 兼容 / 本地 faster-whisper),失败回退 QQ 自带识别 |
| 模型中心 | 一页按 tab 管理 LLM / 视觉 / 语音(TTS)/ 语音识别(ASR)/ 更多类型插槽;LLM 路由按配置档生效,视觉可选「跟随 LLM 内联图片」或独立模型,TTS / ASR 供应商是全局配置、配置档只选用哪个 |
| 数据自包含 | 默认数据目录 ~/.dsh-qqbot/v2,单文件 SQLite;备份 = 拷数据目录 + workspace |
界面预览
README 保持纯文本(npm 上的说明也不需要图),控制台实拍截图集中放在 界面预览(docs/SCREENSHOTS.md):
- 总览:机器人运行状态、工具档位、配置规模、SSE 事件流与最近事件;
- 配置档:15 个设置分节收敛成 5 个组 tab(对话与人设 / 模型与语音 / 能力与权限 / 记忆与数据 / 群日报);
- 提示词预览:按真实顺序看每一段来源、范围与字符数;
- 工具与技能:宿主发现清单、装配三态、常驻 / 按需档位、白名单与黑名单;
- 模型中心:LLM / 视觉 / 语音(TTS)/ 语音识别(ASR)/ 更多类型插槽;
- 群日报模板:内置模板 + 自定义模板的实时预览与氛围切换;
- 记忆与知识库、深色主题、dsh Web 会话菜单入口。
群日报卡片的做法:模板就是一个读 window.__CARD_DATA__ 的 index.html,随包自带 minimal 最简示例;
声明了 visuals 的模板还能按当天氛围自动换插画(素材由模板自己的 meta.json 声明,渲染前内联成 data URI),
渲染失败自动降级为纯文本。
安装
环境要求
- Node.js 24 或更高(
node --version;用了内置node:sqlite) - 已安装 dsh(
dsh --version可用)且是 0.2.x;其它版本 dsh 会拒绝加载,需要dsh plugin --profile <名字> allow-version显式放行 - 一个 QQ 官方机器人应用的
appId/appSecret,并在平台开启需要的群 / 私聊权限
方式一:npm(推荐)
# 装到默认 web profile
dsh plugin --profile web add dsh-qqbot-buddy@next
# 或装到指定 profile
dsh plugin --profile qqbot add dsh-qqbot-buddy@next
# 也可以用自带安装器:校验 profile、登记 bundle、自检一条龙
npx -y --package=dsh-qqbot-buddy@next dsh-qqbot-buddy-install --profile qqbot --spec dsh-qqbot-buddy@next
dsh plugin add 会自动把声明了 dsh.bundle 的包登记进该 profile 的 dsh.profile.bundles,
所以第一步之后重启 dsh 就已经生效,不需要手工改配置。
方式二:从 GitHub 安装(不需要 npm 账号)
仓库的默认分支就是 v2,所以下面这些命令拿到的就是最新开发版:
npx -y github:Ethereal-ljq/dsh-qqbot-buddy # 装到默认 web profile
npx -y github:Ethereal-ljq/dsh-qqbot-buddy --profile qqbot # 装到指定 profile
npx -y github:Ethereal-ljq/dsh-qqbot-buddy --dry-run # 只看会做什么
想锁定分支也可以写全
github:Ethereal-ljq/dsh-qqbot-buddy#v2。
方式三:源码 / 本地开发安装
git clone https://github.com/Ethereal-ljq/dsh-qqbot-buddy.git # 默认分支即 v2
cd dsh-qqbot-buddy
npm --prefix web ci # 首次构建前端依赖
npm run console:build # 产物在 web/dist(发布包自带,运行期不需要 node_modules)
npm run install:local # 等价 node scripts/install.mjs --local --spec .
--local会把仓库作为纯文件副本装进 profile(不依赖仓库的node_modules), 与线上安装包行为一致,适合调试插件本体。
首次启动
- 重启 dsh(例如重新执行
dsh web);控制台会随插件一起起来。 - 打开
http://127.0.0.1:6198,token 在<dataDir>/console-token.txt(默认~/.dsh-qqbot/v2/console-token.txt;端口与监听地址可在 profile 的 patch 配置里改)。 - 「机器人」页新建机器人 → 填
appId/appSecret→ 保存后启动。 - 在 QQ 里 @ 或私聊发一条消息,确认链路正常。
- 按需在「配置档」页调人设 / 回复 / 模型 / 工具策略;要按群区分就在机器人详情里做绑定。
升级
dsh plugin --profile web add dsh-qqbot-buddy@next # 装最新预发布版
# 重启 dsh
数据库迁移在插件启动时自动执行(user_version 校验收缩在 lib/core/migrations.js);
升级前建议先备份数据目录与 workspace,回滚就是把备份放回去再装回旧版本。
卸载
dsh plugin --profile web remove dsh-qqbot-buddy
卸载不会删数据:~/.dsh-qqbot/v2(数据库、token、模板)与 <workspace>/bots 需要手动清理。
数据与备份
<dataDir>/ 默认 ~/.dsh-qqbot/v2
├── buddy.db SQLite:配置档 / 记忆 / 知识库 / 群友库 / 表情包 / 日报 / 审计
├── console-token.txt 控制台登录 token
├── templates/<名字>/ 自定义日报模板(含 meta.json 与 assets)
└── tts-media/ TTS 试听与合成产物
<workspaceRoot>/ 默认 dsh 启动目录
└── bots/<botId>/ 每个机器人的独立 agent 工作目录(会话、媒体、生成物)
- 记忆、知识库、群友库、表情包、人格卡按 bot 共享:切换配置档不丢数据、也不会串档;
- 备份:停 bot 后拷
<dataDir>与<workspaceRoot>/bots;恢复:原样放回后重启 dsh。
配置模型
生效设置 = 默认值 → global 层 → profile 层(后者覆盖前者)
Peer 绑定 = 精确 scope(群 openid / 私聊 openid)> 类型通配(group / c2c)> bot 通配 > 默认配置档
voice.*/asr.*的供应商与凭据是全局配置(一次配好所有配置档复用), 其余(含admin.*管理员门控、daily.*群日报)都是配置档级 —— 同一个群换配置档就换策略。- 配置档页:编辑某个配置档的策略,15 个分节按 5 个组 tab 展示,并提供提示词预览;
- 群日报页:预览卡片模板(真实渲染 + 氛围三模式)、应用模板与氛围、安装 / 删除自定义模板;
- 模型页:按 tab 集中管理 LLM / 视觉 / 语音 / 语音识别,细节见 模型中心说明;
- 机器人页:机器人列表 + 详情抽屉(启停 / 重启、配置档绑定、重置会话、基础信息)。
多个 bot 共用同一份进程与数据库结构,但 bot 级配置、数据与会话完全隔离。
QQ 聊天命令
| 命令 | 说明 | 权限 |
|---|---|---|
/help |
命令列表与管理员门控状态 | 公开 |
/ping |
连通性测试 | 公开 |
/status |
回复频率、人设 / 会话与统计 | 公开 |
/id |
查看自己的昵称、openid 与管理员身份 | 公开 |
/tools |
工具清单:已开启 / 未开启分组 + 原因 | 公开 |
/skills |
技能清单:已开启 / 未开启分组 + 原因 | 公开 |
/daily |
立刻生成今天的群日报并回复 | 管理员 |
/heal |
重新挂载工具(修「这轮没挂工具」) | 管理员 |
/new /reset /clear |
开启新会话(旧会话进入可恢复列表) | 管理员 |
/resume |
恢复上一个被 /new 替换的会话 |
管理员 |
/stop |
停止当前正在生成的回复 | 管理员 |
管理员门控在「配置档 → 命令与权限(能力与权限组)」里配 openid 名单后生效; 名单为空且门控开启时不强制(便于本地调试,公网 / 大群建议填名单)。
工具与技能白名单语义
mode=allow且列表非空:只放行列表内工具 / 技能(宿主工具、插件工具、技能目录统一判定);mode=allow且列表为空:回退到能力开关;mode=deny:除黑名单外放行,但仍受能力开关约束;黑名单优先于白名单;- 策略在创建新会话时应用:改完发个
/new、重启 bot,或在控制台重置会话。
自定义卡片模板
内置只有 journal(纸刊)与 dark(深色);其它模板走「自定义插槽」,不用改代码、也不用重发版:
# npm 安装的用户:直接调包里的脚本(<profileDir> 换成实际 profile 目录)
node <profileDir>/node_modules/dsh-qqbot-buddy/scripts/install-template.mjs minimal
# 在仓库里开发时
npm run template:install -- minimal # 随包自带的最简示例模板
npm run template:install -- ./my-template # 安装任意本地模板目录
- 模板目录约定:
<dataDir>/templates/<名字>/index.html,可选meta.json({label, description, visuals})与assets/; 模板里的相对资源(assets/...)会在渲染前自动内联,拷到临时目录不会断图。 - 也可以不碰命令行:控制台「群日报」页右上角「新增模板」直接选模板目录安装(或粘贴单文件 HTML),装完立即预览。
- 模板名只允许
[A-Za-z0-9_-],与内置同名会被忽略;模板加载失败时保留已有报告并降级为纯文本。 meta.json可以声明 visuals 插画槽(槽位 / 素材 / 氛围 / 组合):控制台的氛围按钮、预览插画、 日报提示词里的可选清单都从这份声明来,增删素材只改 meta + 文件,不用动宿主代码。
架构
QQ 开放平台 (WebSocket)
│
▼
┌────────────────────────────────────────────────────┐
│ dsh 进程 │
│ │
│ dsh-qqbot-buddy 插件 │
│ ├── qq/ 网关、中间件、门控、命令、卡片渲染 │
│ ├── host/ bot 运行时:agent / 会话 / 工具 / │
│ │ 技能 / 召回 / 提示词拼合 │
│ ├── core/ SQLite、配置档、记忆、知识库、群友库、 │
│ │ 人格卡、表情包、TTS / ASR、报告 │
│ ├── reports/ 群日报生成、模板渲染、定时与关系增量 │
│ ├── tools/ agent 工具(记忆 / 知识 / 群友 / 文件)│
│ ├── console/ 独立 HTTP 控制台 + SSE + REST API │
│ └── client.js dsh Web 客户端半(会话头部菜单) │
│ │
│ dsh 宿主服务:agents / sessions / llm / tools │
│ systemPrompt / skills / attachments │
└────────────────────────────────────────────────────┘
│
▼
~/.dsh-qqbot/v2/buddy.db + <workspace>/bots/<botId>/
插件只通过 dsh 的官方服务接入(agent、tools、systemPrompt、skills、attachments),不修改宿主实现;
工具按配置档策略在 agent scope 动态挂载,技能由插件自带 provider 过滤后提供给 dsh-tool-skill。
排障
| 现象 | 先看 |
|---|---|
| 控制台打不开 / 登录被锁 | 端口与监听地址、console-token.txt、用户手册 §9.1 |
| 插件没激活、启动报 incompatible | dsh 版本是否 0.2.x;dsh plugin allow-version 放行 |
| 机器人启动失败 | QQ 凭据与平台权限;控制台机器人详情的失败原因 |
| 模型说「未知工具」/ 像在臆造 | 工具三态与白名单、/tools、/heal |
| 搜不到知识 / 回复不带知识 | 知识库检索参数与召回验证,用户手册 §9.5 |
更完整的排障在用户手册 §9 排障。
开发与测试
npm test # 789 例单元测试(node --test)
npm run verify:standalone # 独立环境安装验收:npm pack → 全新 DSH_HOME → 起实例 → 控制台 / dsh Web 全链路
npm run console:build # tsc 严格检查 + vite 构建控制台(产物 web/dist)
npm run console:dev # 控制台前端开发模式(代理到 6198)
npm run verify:recall # 真机验证记忆 / 知识库自动注入(需要控制台在线)
node scripts/dev-console.mjs # 只启动控制台后端(不连 QQ)
# 真实 dsh 集成测试(隔离 DSH_HOME,不需要 QQ 凭据)
DSH_HOME=$PWD/.work/integration/dsh-home QQBOT_E2E=1 node --test test/e2e/real-dsh.test.js
主要目录:
lib/
├── index.js 插件入口:配置、服务装配、控制台 / 机器人生命周期
├── config-schema.js dsh 部署级配置(dataDir / workspaceRoot / console …)
├── client.js dsh Web 客户端半(会话头部「QQBot 大屏」菜单项)
├── qq/ QQ 协议层(网关 / 中间件 / 发送 / 门控 / 命令 / 卡片)
├── host/ bot 运行时(agent 装配、会话、工具策略、技能 provider、召回)
├── core/ SQLite store、配置档、记忆、知识库、群友库、人格卡、表情包、TTS / ASR
├── reports/ 群日报服务、模板渲染、定时调度、关系增量
├── tools/ 注册给 agent 的插件工具与能力目录
└── console/ 控制台 HTTP 服务与 REST API
web/ 控制台前端(React + TypeScript + Vite,产物 web/dist)
custom/templates/ 随包的自定义模板示例(minimal,纯 HTML/CSS)
docs/ 用户手册、设计契约、传输层契约、模型中心说明
scripts/ 安装器、独立安装验收、探针与冒烟脚本
版本与发布
- 分支:
v2是默认分支,也是唯一的开发线(1.0.0-alpha.x都在这里)。 v1 线(v0.21.0及之前)已归档为v1-legacy分支与v1-archive标签,只读保留,不再更新。 - 发布通道:发布先落在
next(package.json里publishConfig.tag),跑完独立安装验收后再把同一个版本 提升为latest:npm dist-tag add dsh-qqbot-buddy@<版本> latest。所以latest永远是「验证过的最新版」,next用来放刚发布、还没验收的构建。 - 兼容范围:
engines.dsh声明支持的 dsh 版本,engines.node声明 Node 下限; dsh 在加载前会先校验,不匹配时给出可读的拒绝信息(可用dsh plugin allow-version显式豁免)。 - 发布包:
lib/、web/dist/(已构建)、custom/templates/、docs/、scripts/、cordis.patch.yml、README.md、CHANGELOG.md、LICENSE;不带测试与源码依赖(内部 PLAN 文档也不进包)。 - 变更记录:CHANGELOG.md;发布流程(版本号、构建、验收、打标)见 docs/RELEASE.md。
文档
- 用户手册:安装、控制台、配置档、记忆 / 知识库、备份与迁移、排障
- 模型中心:LLM / 视觉 / TTS / ASR 的供应商与配置档选择
- 设计契约:模块边界、会话映射、记忆召回、工具 / 技能策略
- 传输层契约:QQ 网关、被动回复、媒体发送、错误码
- 界面适配:与 dsh Web 的入口与主题适配记录
- 冒烟报告:真实环境验证记录与已知限制
已知限制
- 被动回复窗口:QQ 群聊默认只能引用收到消息的
msgId做被动回复,主动消息需要平台权限; 因此群聊回复会尽量引用触发消息,超时 / 多轮场景以平台实际能力为准。 - 单连接:同一
appId只能建立一条 WebSocket 连接,不要与其它框架同时跑同一个机器人。 - 技能白名单粒度:
glob与grep同属宿主 fs-search 插件,不能单独开关(放行任一即两者可见)。 - 前端产物:控制台前端已随包提供;改前端源码需要重新
npm run console:build并重新发布。 - 模型 / 渠道:模型与图片生成渠道由 dsh 宿主的模型配置决定,本插件不内置模型。
No comments yet. Be the first to write one.