ディレクトリに戻る

dsh-qq-bridge

キュレーションリスト掲載メンテナンス: 活発

sj244/dsh-qq-bridge

既存のDSHセッションをOneBot/NapCat経由でQQへ接続するブリッジ。元のコンテキストを保ち、ホワイトリスト、メンション・ニックネーム呼び出し、確率呼び出しに対応します。

GitHub で見る
$ dsh plugin add dsh-qq-bridge

インストール方法

dsh には中央のインストールコマンドはありません。このプラグインのエントリ(README に記載)をプロファイルまたはパッチ設定に追加し、再起動します。

インストールの仕組み

10

スター

6

フォーク

JavaScript

言語

MIT

ライセンス

2026-09-29

作成日

2026-11-12

最終プッシュ

README

dsh-qq-bridge

English · Connect one fixed DSH session to QQ (OneBot / NapCat) and keep its context — no new session, no re-priming. A fail-closed whitelist gates who may drive it; @-mentions, nicknames and pokes always wake the model; everything else is only recorded (zero model calls) until a configurable sampling probability hits or the model opens a short follow-up window. Ships a settings card in Settings → Plugins → Plugin configuration, and can download, configure and launch NapCat for you.

把一个已有的 DSH 会话接到 QQ(OneBot / NapCat 个人号),提供类似 QQ 群友的交互感受。

dsh plugin --profile web add github:sj244/dsh-qq-bridge

Created with DSH itself — this is a vibecoding project. / 这是个 vibecoding 项目。本项目由 DSH 写成。

  • 设计:DESIGN.md | 里程碑与真机实录:HANDOVER.md | 变更:CHANGELOG.md
  • 当前版本 v0.1.3(维护性更新,见 CHANGELOG.md)
  • M1–M8 全部完成,已在真实 NapCat + 真实 QQ 上端到端跑通(Windows 真机)

目录

功能 | 安装 | 唤醒策略 | 接入 QQ | NapCat 一键托管 | 出站 | 消息与图片 | 表情包 | 设置界面 | 注入的系统提示 | 无人值守边界 | 上下文上限 | 工具一览 | 已知限制 | 测试 | 路线

功能

  • 注入固定会话:targetSessionId 指向哪个会话,QQ 的消息就注入哪个会话,该会话原有的上下文继续使用。 目标会话由插件显式加载(agents.get(id),取不到时用 agents.resume({ resumeSessionId })),不回退到别的会话。
  • 按概率唤醒,节省 token:被 @、命中昵称、被戳时会话必须唤醒。其余消息按概率抽样(默认 5%)。 没有抽中的消息只记录,不调用模型。详见唤醒策略。
  • 出站受来源闸门限制:出站有标记块和工具 2 种方式,由 replyMode 切换。2 种方式都只对“被 QQ 唤醒的那一轮”生效。 在 DSH 界面里与同一个会话聊天时,正文不会漏进群里。
  • 图片可见:图片先落盘缓存。唤醒时由多模态模型写成文字。文字填回图片原来的位置。
  • 表情包:群友发的图可以登记成表情包,之后按情绪或哈希再发出去。登记过的图不再调用多模态模型。 详见表情包。
  • 有设置卡片:昵称、白名单、概率、目标会话、出站方式、OneBot 地址、视觉模型等都在 设置 → 插件 → 插件配置 里修改,保存即生效。
  • NapCat 自助托管:插件可以按需下载、校验、解包、写配置、启停 NapCat。

不做的三件事:

  1. 不接管审批(见无人值守边界)。
  2. 不在插件加载时下载或执行任何内容。
  3. 不做 QQ 官方机器人,走 OneBot 个人号。

安装

正式安装(从 GitHub):

dsh plugin --profile web add github:sj244/dsh-qq-bridge

开发期(修改本仓库代码时用 link 安装):

dsh plugin --profile web add "<REPO>"   # <REPO> = 本仓库在你机器上的绝对路径

注意:link: 安装的依赖解析可能失败。dsh plugin add <本地目录> 安装的是符号链接, Node 按真实路径解析依赖,而 DSH 的包位于 ~/.dsh/profiles/node_modules/@deepseek-ai, 从工作区向上找不到该目录,插件 import 因此失败。解决办法是在插件目录里挂一个 junction:

New-Item -ItemType Junction `
  -Path "<REPO>\node_modules\@deepseek-ai" `
  -Target "$env:USERPROFILE\.dsh\profiles\node_modules\@deepseek-ai"

装完、以及每次修改插件代码之后,都要重启 dsh web 才会加载。

唤醒策略

QQ 消息 ─┬─ 不在白名单 ─────────────────→ 丢弃(fail-closed)
         ├─ 在会话跟随窗口内 ───────────→ 唤醒(reason: listening)
         ├─ 群里 + atOnlyInGroup + 没 @ ─→ 丢弃
         ├─ 被 @ / 命中昵称 / 被戳我 ───→ 唤醒
         ├─ random() < wakeProbability ──→ 唤醒(默认 5%)
         └─ 其余 ──────────────────────→ 只记录(零模型调用)
  • 白名单 fail-closed:whitelist(私聊)、groupWhitelist(群)为空数组时,任何来源都不能唤醒会话。
  • 必须唤醒:被 @、正文命中 nicknames、被戳一戳([戳一戳](戳的是我))。
  • 概率唤醒:wakeProbability,默认 0.05。
  • 只记录:未唤醒的消息进入“最近聊天缓冲”,不调用模型。缓冲最多保留 200 条。 下一次真正唤醒时,取最近 recentChatLimit 条(默认 8)拼成 [QQ 未唤醒期间聊天记录] … [记录结束], 附在该条消息前。摘要表头写明最近几条,并注明没进摘要的条数(“更早的 N 条已省略”); 该条数按真实丢失量算,即缓冲快照里的条目数减去摘要行数,窗口外的旧条目也计入。 该条数大于 99 时不写数字,改写成“更早的大量消息已省略”(不让巨大的数字进上下文)。 投递成功后,唤醒那一刻缓冲里的条目全部删除,避免重复占用 token。 没进摘要的旧条目也一起删掉,不会留到下一次唤醒。 只有投递期间新到的消息留在缓冲里,等下一次唤醒。
  • 投递方式(delivery):auto(默认)在目标会话正忙时插话(steer,下一个 step 边界塞入),空闲时排队; followup 永远排成独立一轮;steer 总是插话。
  • 群内二次闸门:atOnlyInGroup: true 时,群消息没有被 @ 就完全不处理。

会话跟随

真人聊天不会每句话都 @。第一次被 @ 之后,是否继续收听由模型自己决定:

调用 作用
qq_bridge_listen({ minutes: 5 }) 开一个窗口(默认 5 分钟,上限 60)
窗口打开期间 同一目的地(同一个群 / 同一个私聊)的普通消息也唤醒目标会话,不必再 @
qq_bridge_listen({ off: true }) 关掉;到期也会自动失效
  • 只影响那个目的地,别的群 / 私聊不受影响。
  • 警告:窗口打开时,每条消息都会唤醒,产生实际费用。默认 5 分钟、上限 60 分钟。 这条规则已经写进注入的系统提示(“别无脑常开”)。
  • 窗口检查排在 atOnlyInGroup 之前。否则群里开启跟随后,消息会被“没 @ 就丢弃”掐断。

接入 QQ(OneBot / NapCat)

插件作为 WebSocket 客户端主动连接 NapCat 的“正向 WebSocket”服务,收发都走这一条连接。

# 在 profile cordis.patch.yml 里按 id 覆盖,或直接在设置界面改
- id: qq-bridge
  config:
    onebotUrl: 'ws://127.0.0.1:3001'
    accessTokenEnv: 'NAPCAT_ACCESS_TOKEN'
  • onebotUrl 留空 = 完全不启用传输(默认值,安全)。
  • NapCat 侧要开一个 WebSocket 服务器(不是 HTTP 服务器),并允许本机连接。
  • selfId 留空即可:连上后插件自动调用 get_login_info 取得自身的 QQ 号,用于过滤自身消息, 防止回复死循环,同时忽略 message_sent 事件。

配置 access_token(不得明文写入配置)

accessTokenEnv 填的是凭据引用名(一个环境变量名)。token 本身由 DSH 的凭据服务解析, 不写入 cordis.patch.yml,也不进入日志或状态文件。token 按以下优先级逐层查找:

  1. 进程环境变量:$env:NAPCAT_ACCESS_TOKEN = '…'
  2. ~/.dsh/.credentials.yaml 的 refs: 段
  3. 工作目录下的 .env

解析在每次建连时重新执行,不缓存。轮换 token 不需要重启。

NapCat 一键托管

插件可以按需从官方 GitHub Releases 下载、校验、解包、写配置、启停 NapCat,不预先打包 NapCat。

在会话里调用 qq_bridge_napcat 工具,按以下顺序执行:

步骤 调用 说明
1 { action: "status" } 查看 QQ 是否已安装、NapCat 是否存在、代理是否配置、端口是否正确、隔离数据目录在哪
2 { action: "download" } 取最新发行包 → sha256 校验 → 解包到 napcatInstallDir
3 手动运行一次安装器 见下文;这一步插件无法执行
4 { action: "configure" } 写 <dataDir>/NapCat/config/onebot11.json,把正向 WS 端口和 token 配好(不用打开 WebUI)
5 { action: "launch" } 启动 NapCat(首次仍需扫码登录)

安装目录可以是 OneKey 根,也可以是 OneKey 根下的 NapCat.Shell 子目录;两种布局都能识别。

数据目录必须隔离:NapCat 注入的那份 QQ 会按注册表 HKLM\SOFTWARE\WOW6432Node\Tencent\QQNT 的 Install= 找到桌面版 QQ 的数据目录并共用。 共用时 QQ 内核不触发初始化回调,登录核心永远不就绪(NapCat issue #2135):WebUI 可打开、 报 coreReady:false、没有二维码、OneBot 端口不监听、loginError 为空。

NapCat 4.18.42 起读取环境变量 NAPCAT_QQ_DATA_DIR,设置后注入 QQ 的数据目录被隔离 (4.18.37 不支持)。插件在 launch 前做三件事:

  1. 建好数据目录。默认是 <安装目录>/qqdata,可用 napcatDataDir 改。
  2. 用 setx 把 NAPCAT_QQ_DATA_DIR 写进用户级持久环境变量(HKCU\Environment)。 只设在启动进程的环境里,经 Start-Process -Verb RunAs 提权后会丢失,隔离目录保持为空。 写入失败只记 warn,不阻断启动。
  3. 同时把变量放进子进程环境(env),覆盖不提权的路径。

GitHub で README 全文を読む →

DSH Plugins は DeepSeek Harness プラグインの独立したコミュニティ ディレクトリです。DeepSeek との提携・公認はありません。サードパーティ製プラグインはセキュリティ監査を受けていません。インストール前にソースコードをご確認ください。

DeepSeek Harnessの新着プラグインを毎週お届け。スパムはありません。