前言¶
在 DSH 里跑 agent，常见做法是只在 Web 界面或 CLI 里对话。若希望同一个会话在 QQ 群里也能被 @、被昵称唤起，且仍沿用该会话已有的上下文，而不是为 QQ 单独开新会话、重新 priming，就需要在 OneBot/NapCat 与 DSH 之间做桥接，并控制「谁可以驱动模型、哪些消息只记录不调用」。
下面介绍社区插件 dsh-qq-bridge（维护者 sj244）：它把一个已存在的固定 DSH 会话接到 QQ（OneBot / NapCat 个人号），白名单 fail-closed，@ / 昵称 / 戳一戳必唤醒，其余消息可按概率抽样或只写入缓冲，唤醒时再摘要注入。插件分类为「联网工具」，当前版本 v0.1.3（MIT），仓库 sj244/dsh-qq-bridge。
这是什么¶
dsh-qq-bridge 是 DeepSeek Harness（DSH）的 Web 侧插件：通过配置 targetSessionId，QQ 入站消息注入指定会话；插件用 agents.get(id) 显式加载目标，取不到时用 agents.resume({ resumeSessionId })，不回退到其他会话。出站受「来源闸门」约束，默认只有被 QQ 唤醒那一轮里、[QQ]…[/QQ] 标记块内的文字才会发到群里，避免 DSH 界面里的技术说明和思考过程漏进 QQ。
项目自述为 vibecoding 产物；README 写明 M1–M8 已在真实 NapCat + 真实 QQ 上端到端跑通（Windows 真机）。它不接管审批、不在加载时自动下载或执行任何内容、也不做 QQ 官方机器人。
核心功能¶
固定会话与上下文¶
targetSessionId指向哪个会话，QQ 消息就进哪个会话，原有上下文继续可用。- 未唤醒期间的消息最多保留 200 条缓冲；真正唤醒时，取最近
recentChatLimit条（默认 8）拼成[QQ 未唤醒期间聊天记录] … [记录结束]附在当前消息前，投递成功后缓冲清空。
唤醒策略（省 token）¶
白名单为空数组时，任何来源都不能唤醒（fail-closed）。流程概览：
QQ 消息 ─┬─ 不在白名单 ─────────────────→ 丢弃（fail-closed）
├─ 在会话跟随窗口内 ───────────→ 唤醒（reason: listening）
├─ 群里 + atOnlyInGroup + 没 @ ─→ 丢弃
├─ 被 @ / 命中昵称 / 被戳我 ───→ 唤醒
├─ random() < wakeProbability ──→ 唤醒（默认 5%）
└─ 其余 ──────────────────────→ 只记录（零模型调用）
- 私聊白名单：
whitelist；群白名单：groupWhitelist。 - 群内若
atOnlyInGroup: true，未被 @ 的群消息完全不处理（跟随窗口检查排在该规则之前）。 - 模型可通过工具
qq_bridge_listen({ minutes: 5 })在同一群/同一私聊开跟随窗口（默认 5 分钟，上限 60）；窗口内普通消息也会唤醒，会产生实际调用费用。
出站与来源闸门¶
replyMode 控制出站方式：
| 值 | 行为 |
|---|---|
marker（默认） |
仅 [QQ]…[/QQ] 块内内容发出 |
tool |
用 qq_bridge_send 工具发送 |
always |
整轮回复都发出（旧行为） |
只有「被 QQ 唤醒的那一轮」生效；在 DSH 里与同一会话聊天时，标记块不会发到 QQ。超长（超过 replyMaxChars）则一条都不发。
图片、表情包与 NapCat¶
- 图片先缓存；唤醒时可用多模态模型转成文字填回原位置；登记为表情包后可按情绪或哈希复用，减少重复视觉调用。
- 非文本段（表情、语音、文件等）转为占位符，避免整条消息丢失；戳自己合成
[戳一戳]（戳的是我）并必唤醒。 - 插件可作为 WebSocket 客户端连接 NapCat 正向 WebSocket；
onebotUrl留空则完全不启用传输（默认，偏安全）。 - 会话内可调用
qq_bridge_napcat：查状态、下载并 sha256 校验发行包、写onebot11.json、启动 NapCat；不会在无人操作时自动下载或执行。
设置界面¶
昵称、白名单、概率、目标会话、出站方式、OneBot 地址、视觉模型等可在 设置 → 插件 → 插件配置 修改，保存即生效。accessTokenEnv 填环境变量名，token 由 DSH 凭据服务解析，不写入 cordis.patch.yml。
安装与启用¶
正式安装（资料原文命令）：
dsh plugin --profile web add github:sj244/dsh-qq-bridge
装完以及每次改插件代码后，需重启 dsh web 才会加载。
接入 OneBot 时，可在 profile 的 cordis.patch.yml 按 id 覆盖，或在设置界面修改，例如：
- id: qq-bridge
config:
onebotUrl: 'ws://127.0.0.1:3001'
accessTokenEnv: 'NAPCAT_ACCESS_TOKEN'
NapCat 侧需开 WebSocket 服务器（非 HTTP）。token 解析优先级：进程环境变量 → ~/.dsh/.credentials.yaml 的 refs: → 工作目录 .env；建连时重新解析，轮换 token 不必重启。
典型用法¶
- 安装插件并重启
dsh web，在插件配置里填写targetSessionId、白名单、昵称与wakeProbability（默认0.05）。 - 配置
onebotUrl与accessTokenEnv，确保 NapCat 正向 WS 可达；selfId可留空，连上后插件会get_login_info取得本号 QQ，过滤自消息防死循环。 - 若尚未部署 NapCat，在目标会话中按 README 顺序调用
qq_bridge_napcat：status→download（需代理时可设downloadProxy）→ 手动运行一次安装器 →configure→launch（首次仍须扫码登录 QQ）。 - 在群里 @ 机器人或命中昵称测试唤醒；默认出站用
[QQ]回复内容[/QQ]包裹要发到群里的句子。 - 需要连续聊几句时，由模型在合适时机调用
qq_bridge_listen，并注意窗口内每条消息都会唤醒。
开发期可用本地路径 dsh plugin --profile web add "<REPO>" 做 link 安装；README 说明了 Windows 下 @deepseek-ai 依赖 junction 的注意事项。
适用场景与注意¶
适合：已有固定 DSH 会话（例如长期「大肥鱼」人格或项目 agent），希望在小范围 QQ 群或私聊里以群友方式互动，且要严格限制谁可驱动、控制随机插话比例的场景。
不建议：公共大群长期无人值守；README 明确 NapCat 为第三方客户端，存在账号风控风险，是否启用由用户自行决定。
安全与权限：插件以当前 dsh 进程权限运行；安装前应阅读 源码与 LICENSE，理解白名单、出站闸门与「不提供审批桥接」等边界。卸载插件或退出 DSH 时，由 subprocess 托管的 NapCat 会一并结束。
DSH 生态强调「一切皆插件」；SkillHub 目录页 为社区站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-qq-bridge 解决的是「一个会话、两处入口」：QQ 侧可控唤醒与只记录，DSH 侧保留完整上下文与默认不出群的出站策略。进一步的设计与变更见仓库内 DESIGN.md、HANDOVER.md、CHANGELOG.md。
- 目录页：https://www.skillhub.cn/plugins/sj244/dsh-qq-bridge
- GitHub：https://github.com/sj244/dsh-qq-bridge
