dsh-roost
roost-qq/dsh-roost
Relie QQ à DeepSeek Harness par l'API officielle des bots. Une conversation QQ correspond à une session DSH persistante, avec permissions par locuteur, mémoire à trois couches, personas, messages proactifs planifiés et panneau. Liaison volontaire des openids aux numéros QQ pour garder la mémoire après changement d'AppID. L'assistant initial installe Roost et la connexion directe. Bot QQ Open Platform avec AppID/AppSecret requis. Tous les membres du groupe lié peuvent parler par défaut ; seul le propriétaire a tous les outils locaux.
Installer
dsh plugin --profile web add github:roost-qq/dsh-roostREADME
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/roost-qq/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。
💬 交流群
安装踩坑、用法讨论、人格与扩展的开发想法都欢迎来聊。提问时尽量带上版本号和相关日志。
群号:1130901545
致谢
角色设计参考了 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。
Plugins associés
dsh-purge
kingcharleslzy-ai/dsh-purge
dsh-web (dsh-ssh)
zhu1090093659/dsh-web
dsh-web (dsh-remote-web-ui)
zhu1090093659/dsh-web
dsh-web-ui (dsh-ssh)
zhu1090093659/dsh-web-ui