dsh-qq-bridge
精選清單收錄維護狀態: 活躍sj244/dsh-qq-bridge
把已存在的固定 DSH大肥魚 會話接到 QQ(OneBot/NapCat)並保留原上下文:白名單 + @/暱稱必喚醒 + 機率喚醒,其餘只記錄,讓大肥魚成為你的群友;也可以把 agent 扔進群裡當群友玩(不建議公共群)。 / Bridge one existing DSH session to QQ via OneBot/NapCat, keeping its context — fail-closed whitelist, @/nickname wake, configurable-probability wake.
$ dsh plugin add dsh-qq-bridge10
星數
6
Fork
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。
不做的三件事:
- 不接管审批(见无人值守边界)。
- 不在插件加载时下载或执行任何内容。
- 不做 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 按以下优先级逐层查找:
- 进程环境变量:
$env:NAPCAT_ACCESS_TOKEN = '…' ~/.dsh/.credentials.yaml的refs:段- 工作目录下的
.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 前做三件事:
- 建好数据目录。默认是
<安装目录>/qqdata,可用napcatDataDir改。 - 用
setx把NAPCAT_QQ_DATA_DIR写进用户级持久环境变量(HKCU\Environment)。 只设在启动进程的环境里,经Start-Process -Verb RunAs提权后会丢失,隔离目录保持为空。 写入失败只记 warn,不阻断启动。 - 同时把变量放进子进程环境(
env),覆盖不提权的路径。
更多「整合與分享」外掛
dsh-notification
作者 omdsh-dev
DeepSeek Harness 桌面通知外掛,任務完成時提醒,可按結果與關鍵詞規則控制。
dsh-lark-bot
作者 plutokeating
DeepSeek Harness (dsh) 接入飛書/Lark bot,掃碼即用:流式卡片、專案工作區、並行任務、多角色 Agent、跨會話通知、對話內模型/金鑰管理與安全網守護(dsh 崩潰後飛書仍可自救)。A scan-to-connect bridge bot connecting DeepSeek Harness (dsh) into Feishu/Lark: streaming cards, workspaces, parallel tasks, multi-role agents, cross-session notify, in-chat model/key management, and a safety-net guardian.
dsh-session-notification
作者 dingyi222666
為 Deepseek Harness 提供會話完成等四種狀態的通知響應,支援瀏覽器提示和提示詞
dsh-chatgpt-web
作者 wlv-zedd
將標準 ChatGPT Web 直接橋接到 DeepSeek Harness 的 DSH ChatGPT Free 外掛。
