dsh-roost
Manifest valid★ 26DSH 插件:让 AI 通过 Roost 住进 QQ —— 官方接口,不用 hook 客户端
dsh-roost
给 QQ 机器人接上 DSH 的全部能力:工具、记忆、上下文压缩、主动搭话。
零依赖,装在 DSH 里:权限、记忆、人格、扩展、排期都在侧栏面板里点着配。
| 🛡️ 官方接口,不碰风控 | 🎚️ 逐条权限,不整群一刀切 | 🧠 三层记忆,跨重启不丢 | 🔌 四步一键接入 |
|---|---|---|---|
| 走 QQ 开放平台 + 外接协议直连,不 hook 客户端 | 每句先判身份再收工具,认不出一律最低档 | 事实 / 日记 / 知识图谱,凌晨自动巩固 | 首次启动向导 + 一键直连自动生成密钥和端口 |

侧栏「概览」页:最上面是接入进度与一键启动,接着是六格状态(托管会话 / 今日 Token / 排队并发 / 缓存命中 / 最近一轮 / 工具挂载)、近 7 天用量、8 周活跃度、Token 构成与耗时拆分、会话卡片与筛选,最后是快捷、端口与最近动态。所有用量只统计 dsh-roost 自己创建的会话。换图要求见 docs/images/README.md。
它做什么
给每个 QQ 会话建一个长期存在的 DSH 会话——一个群、一个私聊各对应一个,断线重连、重启之后映射还在。之后的每一轮:
- 认人:判断这句话是谁说的,按档位收好这一轮能用的工具
- 交给 DSH:把消息送进对应会话,等 AI 说完;工具、记忆、上下文压缩、人格都由 DSH 提供
- 送回去:通过框架外接协议回话,分几段说、配图、发语音、要不要收尾,都由模型自己调工具决定
能力从哪来,一眼看清:
| 你要的能力 | 由谁提供 |
|---|---|
| 收发 QQ 消息、语音 ASR、引用 / 合并转发、切段、防吵(冷却 / 配额 / 认领) | Roost 框架的外接协议 roost-host/1 |
| 会话、工具(文件 / 命令)、三层记忆、上下文压缩、人格 | DSH |
| 会话映射、逐条权限、侧栏面板、一键接入、主动搭话与排期 | dsh-roost |
为什么值得接:让 QQ 消息直接进 DSH 会话之后,AI 不只能聊天,还能用 DSH 的工具(文件、命令)、三层记忆、上下文压缩——这是这一层接入存在的全部理由。
数据怎么走(链路图)
QQ ⇄ Roost 内核 ⇄ 外接协议事件流 / RPC ⇄ dsh-roost ⇄ DSH 会话 ⇄ DeepSeek
协议帧、方法表与鉴权见 Roost 仓库的 docs/宿主协议v1.md。本仓库只做客户端。
只支持 QQ;通道抽象已备好,但还没接第二个平台。需要多平台可以看 AstrBot 或 Koishi。
特性
| 能力 | 一句话 |
|---|---|
| 🗨️ 一个 QQ 会话 = 一个 DSH 会话 | 映射存盘,断线重连、重启之后会话不丢 |
| 🧭 首次启动向导 | 新装和升级都要走一遍;四步引导 + 一键直连,密钥和端口自动生成,直连自测通过才算完成 |
| 🔐 逐条权限判定 | 每一句都告诉 AI「谁在说、什么档位」,并按档位收本地工具 |
| 🧠 三层记忆 | 跨群 / 本群事实 + 日记(三级衰减 + 关键词 / 向量检索)+ 知识图谱 |
| 🛠️ 记忆工具 | memory_search / memory_note,让模型主动翻旧账 |
| 🌙 凌晨巩固 | 打分、升降级、到期压缩、抽三元组、提取约定,不花白天的额度 |
| 🌅 觉醒 | 约定 / 想你 / 随性三类机会打分,到点「问她要不要说」,不是硬发 |
| 💬 对话收尾 | 记一句「收在哪 / 下次怎么接」,不发言、不动记忆;刚说完晚安 90 分钟内不重复冒出 |
| 🗣️ 发言走工具 | qq_send / qq_close 由模型自己调,调几次就是几条独立消息,不是一段文本被动切段 |
| 📎 能发文件 | qq_send_file,可选路径白名单;发之前先问对面支不支持,一轮一个、200MB 上限、超 5MB 自动分片 |
| 📣 能 @ 人 | at 参数;[昵称 (openid)] 由宿主拼,模型不碰 id 语法,降级时会告诉它为什么 |
| 📝 频道发帖 | qq_post_thread:往频道的一个论坛版块里发一篇有标题的帖子(不是发消息),每天几篇、窗口内随机;发出去要过审核,面板分「已提交 / 已上线 / 没看到」三态;只有主人能在面板里指定版块,模型改不了目标 |
| 🗜️ 上下文压缩 | 群 85% / 私聊 75% 时开新会话 + 摘要开场,压缩前的缓存命中率记进面板 |
| 📱 侧栏面板 | 七个一级分组:概览 / 人设 / 表达 / 群与频道 / 能力 / 扩展 / 系统,都在 DSH 里点着配;菜单显隐与顺序、强调色、动效在「概览 → 个性化」;接入与账号迁移从按钮打开整页 |
| 🧬 人格四段式 | 性格 / 开场白 / 说话示例 / 世界书;世界书命中才注入,聊几十轮人设也不被冲淡 |
| 🔄 人格库一键更新 | 独立仓库 dsh-roost-personas 推个 commit,面板点一下就拿到,不用发版;只覆盖没改过的 |
| ⬆️ 本体自更新 | 设置页查最新版一键装,失败回滚 package.json + lock;符号链接装的开发机自动禁用 |
| 🧩 扩展 + 可调设置 | 扩展是标准 MCP server;在 plugin.json 声明字段后,面板直接按声明画表单,值宿主代存、密钥单独存且不回显,改完重启生效 |
| 🎭 双人格 preset | 私聊 roost-private / 群聊 roost-social 各一套提示词 |
| 🖼️ 表情包 | 图丢进目录就能用,文件名或侧车 .tags 当标签;分类 + sticker_pick 按需取图,加图不冲提示词缓存 |
| 🔊 语音合成(选装,默认关) | 五种 provider,tts.speed 一份共用;不配就完全静默,配好模型才能用 <<say: 内容>> |
| 🔑 账号迁移 | 把 QQ号 / 群号和 openid 对上,换 AppID 后旧记忆照样读得到;绑定完全自愿、非必需 |
20 条特性的完整说明、配置全文、五种语音 provider 的字段、表情包侧车语法、账号改写备份路径、面板明细等,全部在 使用手册(特性逐条说明)。
快速开始
你需要:DSH 桌面版 / Web 组合(要有 sessionController 和 agents)、Node 22+、一个 QQ 开放平台机器人(AppID / AppSecret)。Roost 不用提前准备 —— 首次启动向导里会装。
1. 装插件
DSH 插件市场里输入包名 dsh-roost,或命令行:
dsh plugin --profile web add dsh-roost
从源码装也行:git clone https://github.com/tdcq9594/dsh-roost.git(零依赖,不用 npm install)。
2. 找到入口
装好后首次打开面板会强制走一遍「首次接入向导」:新装和老版本升级都会弹,因为这一版移除了 ai-chat 中间层,老配置的接入方式已不存在,不重接就是哑的。四步:接入说明 → 确认 Roost 装好并启动 → 一键直连 → 自测完成。完成必须由后端真跑一次直连自测,前端点「完成」只是发请求,不能自己宣布成功。老版本 Roost 没有外接协议时可以「暂时跳过」进面板去升级,概览页会一直提示。
之后在 DSH 侧栏「Roost → 接入」 是六步路径,能自动的都自动做掉:
| 步 | 做什么 | 自动? |
|---|---|---|
| 1 | 装 Roost(下载解压,零依赖) | ✅ 点一下 · 已装过可点「已装过?」填路径绑定 |
| 2 | 启动 Roost | ✅ 点一下(没填凭据也能起,正好用来扫码) |
| 3 | 扫码 / 填 AppID、AppSecret | ✋ 开放平台拿;存完自动重启 Roost 让新凭据生效 |
| 4 | 一键直连(推荐) | ✅ 点一下:自动开协议、生成密钥、读回真实端口 |
| 5 | 去群里说句话 | ✋ 开放平台开「接收所有消息」+ 机器人进群 |
| 6 | 配置主人 | ✅ 点一下,直接跳到 Roost 面板的「主人与群组」 |
顶上的「一键就绪」把 1、2、4 连着做完,卡在 3 就停下来提示你扫码或填。每一步也能单独点,跳着点不会把东西搞坏(每步先检测前置条件)。第 2 步「启动」之后,旁边按钮直接打开 Roost 的 WebUI(带上面板密钥)。
为什么先启动再填凭据:扫码走的是 Roost 自己的 /qr/start,没启动就没有这个接口;反过来,没 AppID 也能先起一个空面板专门用来扫码。这个顺序以前是反的,两边互相等死。
下载地址:优先 GitHub Release(自动补 v 前缀、自动查最新版),拿不到就回退 npm 包。装到哪:默认 ~/.dsh/dsh-roost/roost,可在设置里改 setup.roostDir。
3. 升级
面板「设置」页顶部就是更新:本体和人格库都能查最新版、一键装。本体走 DSH 自己的 pluginManager,装完提示重启;人格库更新不用发版。开发机(符号链接装的)会自动禁用自更新。
装完没回话?先看 常见问题 里「两边地址和密钥要对上」那一条。
安全与隐私
| 关注点 | 实际情况 |
|---|---|
| 不是插件沙箱 | 权限层约束的是「AI 这一轮能调哪些工具」,不是「插件代码能做什么」。dsh-roost 作为 DSH 插件运行在你的账户下,拥有与本机同等的文件、命令和网络权限。真要隔离只能靠外部进程 + 系统级沙箱,本项目没有做。详见 手册 · 权限。 |
| 数据都在本机 | 配置、记忆、日记、图谱、人格、表情包默认在 ~/.dsh/dsh-roost/,可用 DSH_ROOST_DATA 改目录;不上传、不共享。备份 zip 也只写到你自己指定的位置。 |
| 绑定 QQ 号完全自愿 | QQ 官方接口不提供 QQ号 / 群号,本项目不会获取、推算或抓取;号码只来自本人主动提供。不绑定不影响任何功能,昵称候选只提示不自动绑。详见 手册 · 账号迁移。 |
| 语音会发文本给谁 | 本地 sherpa 完全离线;微软 edge 会把要念的文本发到微软服务器;OpenAI 兼容 / 小米 MiMo 发给你自己填的上游。不配 TTS 就完全静默。 |
| 密钥 | server.token 是固定服务(/v1 控制面、TTS)的共享密钥;roostHost.token 是外接协议的 bearer 凭证,两者都别贴进 issue 或截图。 |
文档
| 文档 | 内容 |
|---|---|
| 使用手册 | 配置全文、五种语音 provider、权限页、面板明细、账号迁移、备份、表情包、目录结构、开发测试 |
| 接入说明 | 接入链路与排障(旧版 /inbound 契约已废弃,见文首说明) |
| 自驱引擎 | 实验功能,默认关:面板入口、配置段、账本 |
| 聊天内切人格指令 | persona.command,默认关 |
| 人格迁移规范 | 社区角色卡转成本仓人格文件的规则 |
| 参与贡献 | 本地跑起来、PR 前五步检查、代码约定 |
设计方案、调研、与其它项目的对照、阶段进度与交接记录不入库,归档在开发机 D:\WorkBuddy\_archive\ 下,需要时查 git 历史。
常见问题
装好了但一句都不回 / 全部 401
先看概览 → 直连状态:seq 不动就是事件没进来,state=error 会带出具体原因(常见是 Roost 没开外接协议、token 对不上、依赖 ws 没装)。固定服务的 server.token 不对会让 /capabilities、/tts 返 401;端口被占用时会自动顺延(lease.js),以启动日志和面板为准,不是固定 17321。还没走完首次接入向导的话,先走完它。详见 手册 · 配置。
「逐条权限」是不是把插件关进沙箱了
不是。它只约束「AI 这一轮能调哪些工具」,插件代码本身运行在你账户下,拥有与本机同等的文件、命令和网络权限。见 安全与隐私。
DeepSeek 抽风 / 502 了怎么办
模型服务挂了插件救不了。网关 502 时补重试能救回一部分,整体挂掉只能等它恢复;这种时候插件回一句「模型服务那边暂时抽风了」,不会把内部报错糊给你。可以先点面板「概览」里的跑一次自测——它不经过 QQ,直接跑一轮 DSH 对话,能区分是「会话建不起来」还是「QQ 那半边没通」。
表情包发出去为什么不是收藏表情
是普通图片消息,对方收到的是图,不会进他的「表情」收藏夹——协议层的限制,插件改不了。另外超过 20MB 会被降级成文件发送。详见 手册 · 表情包。
不绑定 QQ 号 / 群号会有影响吗
完全没有影响。官方只给 openid,本项目不会猜、不会抓;绑定只为换 AppID 之后还能读到旧记忆,且任何绑定都可随时解绑。详见 手册 · 账号迁移。
语音要钱 / 要 API Key 吗
本地 sherpa 和微软 edge 都不用 Key(前者完全离线,后者把文本发到微软服务器);OpenAI 兼容和 GPT-SoVITS 用你自己的服务;小米 MiMo 需要一个 API Key。默认 tts.enabled: false,不配就完全静默。详见 手册 · 配置。
装不上 / 七步卡住了看哪
第 3 步的 AppID / AppSecret 要去 QQ 开放平台拿,第 6 步要开「接收所有消息」并让机器人进群——这两步是手动的。其余步骤都能单点点,跳着点不会搞坏(每步先检测前置条件)。下载优先 GitHub Release,拿不到才回退 npm 包。日志在面板「排障」页,按级别筛。
怎么升级 / 换电脑
升级走面板「设置」顶部「更新」;换电脑用面板「备份」页的「导出备份(zip)」,新机器在那页「导入备份(zip)」后下次启动才换上,可以取消反悔;也可以用命令行 node scripts/backup.mjs export|import|cancel。详见 手册 · 一键备份。
参与贡献
欢迎提 issue、改文档、修 bug。本地怎么跑、PR 前要过哪五步检查、代码约定,都写在 CONTRIBUTING.md。
致谢
角色设计参考了 Aurabot(dsh-aurabot-qq):一个 QQ 会话对一个 DSH 会话、人格独占系统提示词、安全默认、按会话挂东西、用 agent.followup + sessions.flush 投递、从 session/event 取回复。这些思路让我们少走了不少弯路,在此致谢。
QQ 侧依托自家的 栖 Roost,通过它的外接协议 roost-host/1 直连,不再经过任何中间插件;许可也沿用 Roost 的 AGPL-3.0-only。
和 Aurabot 的对比
传输层完全不同:Aurabot 走 OneBot(SnowLuma,hook 本机 QQ 客户端),这里走 QQ 官方接口 + 框架自有外接协议。所以 Aurabot 里那批 OneBot 特有的东西(数字 QQ 号、base64 语音段)这里一个都不需要。首次启动向导参考了 Aurabot 的 setupDone 机制,但用递增版本号让老用户升级也必须重走。
一句话:传输层我们更稳(官方接口),对话体验它更成熟。 只想用现成的,先去试试 Aurabot。
已知限制
- 只支持 QQ(
channel.current恒为roost),通道抽象已备好但还没接第二个平台 - 语音靠官方 ASR(
asr_refer_text),没有本地语音模型;TTS 音色在面板「表达」页设置 - 面板的配置正文仍是 JSON 直编辑(不是逐字段表单),代价是要看得懂结构——所以配了分节说明;「权限」页那批(档位、功能开关、次数限制、分群例外)已经是可点的
- 模型服务挂了插件救不了:网关整体挂掉时只能等它自己恢复
- 表情包发出去是普通图片消息,不是 QQ 收藏表情(协议层限制)
- 排队只存内存:进程重启时正在排的那条会丢;面板暂时看不到队列长度(
stats()已备好) - 巩固不进队列:
memory.consolidateChat配成私聊 openid 时,撞上正在跑的一轮仍会失败(次日补跑)
旧版 README 的章节导航(链接保留,内容已迁到使用手册)
配置
见 使用手册 · 配置(含五种语音 provider 的全部字段)。
权限:AI 知道是谁在说话
见 使用手册 · 权限。
面板
见 使用手册 · 面板。
账号迁移(v1.0.0)
见 使用手册 · 账号迁移。
一键备份(换电脑)
见 使用手册 · 一键备份。
表情包
见 使用手册 · 表情包。
目录结构
见 使用手册 · 目录结构。
开发与测试
许可
沿用 Roost 的许可:GNU Affero General Public License v3.0 only(AGPL-3.0-only)。允许商业使用与收费分发,但分发或通过网络提供服务时必须同样以 AGPL-3.0-only 开源并提供完整对应源码。全文见 LICENSE。
Versions
| Latest version | Published | Size |
|---|---|---|
| 1.3.11 | — | — |
| 1.3.12 | — | — |
| 1.3.13 | — | — |
| 1.3.14 | — | — |
| 1.3.15 | — | — |
| 1.0.3 | — | — |
| 1.0.4 | — | — |
| 1.0.5 | — | — |
| 1.0.6 | — | — |
| 1.0.7 | — | — |
| 1.0.8 | — | — |
| 1.0.9 | — | — |
| 1.1.0 | — | — |
| 1.1.1 | — | — |
| 1.1.2 | — | — |
| 1.1.3 | — | — |
| 1.1.4 | — | — |
| 1.1.5 | — | — |
| 1.2.0 | — | — |
| 1.3.0-beta.1 | — | — |
Comments
Loading…