dsh-qq-rooms

来源与致谢：本项目衍生自 dsh-qq-bridge （作者 Yuuyuko-uu，MIT）。 src/transport.js 中的消息段解析、标记剥离、卡片抽取、正文图、转发展开等函数移植自原项目并做了修改； 房间模型、白/黑名单、群策略、插件装配为本项目新写。 本项目是独立的第三方项目，不是原项目的官方分支；插件 id（qq-rooms）与配置格式均不同， 不能与原版同时启用。原项目版权声明见 LICENSE。

DSH 的 QQ 房间插件：聊天即房间，不用再手动把 QQ 会话绑到 DSH 会话。

• 私聊一人一间，群一群一间，第一条消息自动建房，之后复用（进程重启后 resume）
• 白名单直接聊；陌生人先问主人；主人拒绝后进黑名单，以后不再询问
• 群默认不接；接入后只回「@ 我 / 引用我」，主人在群里免 @
• 收图、发图、合并转发、卡片解析、语音转写（可选外部命令）
• 工具档：访客 / 群 / 单房三级设置；访客和群房默认全禁，只有主人私聊不受限，改完保存即时生效
• 房间、白名单、审批消息都显示昵称，群房显示群名；启动时自动补全
• 设置页「通到 QQ」：状态徽章、分段页签、滑动开关、粘性保存条；日志落盘，一键打开目录

消息走 OneBot 11 HTTP（NapCat / SnowLuma 都行），入站以 WebSocket 上报为主、HTTP 轮询补漏。

安装

前提：本机已经跑着一个 OneBot 11 后端，并且开了

• HTTP 服务（默认 http://127.0.0.1:3000）
• WebSocket 上报（默认 ws://127.0.0.1:3001，陌生私聊只能靠它发现）

dsh plugin --profile desktop add github:Yukolike/dsh-qq-rooms

装完重启一次 DSH，然后 设置 → 通到 QQ。

不需要构建：仓库就是可运行源码（main 指向 src/host.js），没有依赖、没有编译步骤。 dsh plugin add 会直接 clone 并用源码运行；GitHub Release 里的 Source code 包就是完整安装包。

与 dsh-qq-bridge 不兼容：两个都启用会双发。请只留一个。

配置

项	默认	说明
总开关	关	关 = 一句都不发
试运行	开	开 = 只记账，不真发
主人	空	管理员的 QQ 号；审批、加群、重置只认这个号
NapCat 地址	http://127.0.0.1:3000	OneBot HTTP
接口令牌	空	后端开了鉴权才填
事件地址	ws://127.0.0.1:3001	留空 = 不连事件源（只剩轮询）
事件令牌	空	可空
房间工作区	空	新房间的 cwd；空 = ~/.dsh/qq-rooms
模型	deepseek-account/deepseek-flash	provider/model
访客工具	none	访客房间的默认工具档：none / safe / standard
群工具	none	群房间的默认工具档；群成员不可信，默认全禁；单群可在「房间」页覆盖
房间工具	空	按房间覆盖上一条：「设置 → 房间」里每一间访客私聊和群房都有一个下拉；保存即生效，不用重启、不用等下一句
只发 [QQ] 块	关	开 = 只发正文里 [QQ]…[/QQ] 中间那段

配置文件在 ~/.dsh/qq-rooms-config.json，状态在 ~/.dsh/qq-rooms-state.json。

日志不再显示在设置页里，直接落盘到 ~/.dsh/qq-rooms-logs/plugin.log（超过 2MB 轮转成 plugin.1.log）；设置页「操作」里点 打开日志目录 就能在资源管理器里打开。

设置页

「设置 → 通到 QQ」分四个页签：

• 总览：开关、主人、连接（地址 / 令牌 / 轮询）、房间默认（模型、工作区、访客工具 / 群工具）
• 访客：等你拍板（同意 / 拒绝）、白名单（可直接输入 QQ 号加入，自动查昵称）、黑名单（解除）
• 群：接群、每个群的模式（只回点名 / 听所有人）与静音
• 房间：每间房的昵称 / 群名、会话状态（活着 / 睡着 / 已归档）、单房工具档、重置上下文

有改动时底部浮出保存条；「操作」里有保存、测试一句（绕过总开关与试运行）、打开日志目录、刷新。令牌显示为 ********，原样保存不会覆盖它。

昵称和群名在启动后自动补全（问 get_stranger_info / get_group_info），收到新消息时也会更新。

「重置上下文」= 归档旧会话 + 删映射：历史还在，但侧栏不再显示；下条消息会新建会话，并自动登记到「房间工作区」对应的 workspace。

主人指令（只在自己的私聊里生效）

同意 [号]          进白名单（以后直接聊）
拒绝 [号]          进黑名单（以后不再问你）
解除 10001         移出黑名单（下次会重新问）
放行 10001         直接进白名单

接群 123456789 [mention|all]
退群 123456789
静音 123456789 2h
取消静音 123456789

房间               列出所有房间
重置 群:123456789  归档会话，下次消息重建

指令必须整条消息匹配，日常聊天不会被误吃。

群策略

• 默认：一个群都不接，未加入的群消息直接丢弃，也不会来问你
• mention（默认）：只处理 @ 我 / 引用我的消息；at all 不算
• all：所有消息都进，交给模型判断
• 主人在群里说话：无视模式直接进
• 成员白/黑名单：members.allow 为空表示不限制，deny 优先
• 群房间的工具默认全禁（群工具 = none）；要让某个群能跑工具，在「房间」页给那一行单独选档，保存即生效。群房是共享的，限制作用于整个群的 agent，不区分发言者。

发表情包

在 [QQ] 块里写 ![随便起个名](https://raw.githubusercontent.com/Yukolike/dsh-qq-rooms/HEAD/_stickers/文件名)，插件会读本地文件、以 base64 发出去，markdown 不会泄露到 QQ。

相对路径按 图片根目录 → 房间工作区 → 进程 cwd → ~/.dsh 依次查找；也可以直接用绝对路径或 http(s) 链接。

安全

• 访客 / 群房间默认不能调工具：建房后 agent.ctx.tools.restrict({ allow: ['<占位工具>'] }) 只放行一个占位工具，none 再用 agent.ctx.tools.guard() 把执行全拒掉。只有「主人的私聊」不受限；群房按 群工具（默认 none）走。
• 为什么不直接「零工具」：DeepSeek 要求请求里至少有一个非 deferred 工具，而中途新增的工具是 deferred 的。别的插件注册在 agent 自己 scope 上的工具（例如 dsh-fish-memory 的 remember）restrict 遮不住（官方语义：masks intersect, scoped registrations stay visible）。零工具时第二轮起整个请求会 400（tools: at least one tool must have defer_loading=false）。所以留一个占位工具让请求合法，执行由 guard 拒绝。
• 访客工具 可设 none（默认：占位工具也不许执行）/ safe（只留 todo_write，可以真的记账）/ standard（不限制，不推荐）。
• 可以实时换档：每一间访客私聊或群房在「房间」页单独选档，或改全局默认，点保存就当场生效——不需要重启 DSH，也不需要对方再发一条。换档时先 dispose 掉旧限制再装新的（restrict 的多次调用是相交的，只加不撤会越限越死，standard 也放不开）。
• 这是 agent 级运行时掩码，不是 profile 隔离；房间工作区 仍建议指向空目录。
• 默认总开关关、试运行开，装完不会立刻发消息。
• 设置页接口只认「本人」：插件挂在 webServer 上的地址不会自动带 DSH 的登录校验，所以每个请求先过宿主的信任检查；拿不到检查、或检查本身出错一律放行，只有宿主明确回 401/403 才拒。
• 令牌只回遮罩：/state 里的 令牌 / 事件令牌 是 ********；设置页把它原样存回来不会覆盖真令牌，清空才会删掉。
• /save 只收设置项：房间（运行时建立）与 访客 / 黑名单（走审批接口）不接受前端回传，免得拿着旧页面一保存就把新建的房间冲掉。

开发

node --test tests/*.test.mjs

测试使用假 ctx / 假 fetch，不需要 DSH 或 QQ 后端。当前覆盖 84 项。

来源

src/transport.js 的部分纯函数（标记剥离、卡片抽取、正文图、消息段解析）移植自 dsh-qq-bridge（MIT）。房间、策略、装配、白/黑名单为本项目实现。

License

MIT