前言¶

在 DeepSeek Harness（DSH）里跑多 Bot 团队时，每个角色通常有独立的长会话：历史、记忆文件、工具权限和工作区都绑在这条 session 上。若要从 QQ 私聊触达它们，常见做法是再写一个 QQ 机器人，用同样的 system prompt 调模型——这样会丢掉真实会话里的上下文，Web 端和 QQ 端也变成两套互不相干的对话。

下面介绍社区插件 dsh-qqbot-bridge（维护者 WuChangqing1），它把 QQ 官方 Bot 的私聊消息投递到 DSH 里该 Bot 已在运行的 session，并把回复回传到 QQ；不另开第二套 QQ 网关，也不复制 system prompt。

这是什么¶

dsh-qqbot-bridge 是 DSH 工作流类插件，当前版本 0.1.0（MIT 许可证，Node >=22.19.0）。定位一句话：Bridge QQ official-bot private chats into DeepSeek Harness agent sessions — same session, same memory, same permissions.

与「典型 QQ ⇄ LLM 桥接」的差异在于：通过 sessionController.resolveAgent(sessionId) 与 agent.followup(createUserMessage({ source })) 复用真实 session；Web UI 与 QQ 共用同一 session id；复用官方 @tencent-connect/dsh-qqbot 已建立的 websocket，本插件只消费 Cordis 服务、不自己连 socket；白名单 allowOpenIds: [] 表示拒绝所有人（fail-closed），被拒用户的 OpenID 仅被记录、不会自动放行；群聊默认关闭，群消息交回官方插件原链路处理。

工作原理概览¶

消息路径可概括为：

QQ 私聊 → @tencent-connect/dsh-qqbot（含本地 fork patch）→ dsh-qqbot-bridge
  → 白名单 / 命令路由 / 队列与去重 → 只读 state.json 取当前 session id
  → resolveAgent → followup → 同一 DSH session（msg.source.kind = 'qqbot-bridge'）
  → session/event 收集回复 → 分片回 QQ

官方 QQ 插件原先未暴露 Cordis 服务，外部插件无法共用连接或插入中间件；同一 AppID 再起网关会抢事件流。因此项目要求对 stock 包做最小本地 fork（patch 0001：在 middleware 链前插入可选 preHandlers，并 ctx.provide('qqbot', …)）。未使用该扩展点的宿主行为与原版一致。

核心功能¶

1. 会话级桥接：QQ 私聊进入对应 Bot 的真实 DSH session，保留历史、记忆、工具与工作区；会话滚动到新 part 时，每次发送前重读 state.json。
2. 多 Bot 路由：通过 QQ 内命令切换当前对话对象（见下文「典型用法」），路由持久化到 routing.json，按 OpenID 区分。
3. 安全默认：空白名单拒绝所有私聊；仅 v1 私聊，allowGroups: false。
4. 可观测：控制台日志与 bridge-status.json；插件注册 qqbotBridge Cordis 服务供运维查询；官方 /bot-ping、/bot-status 等命令仍可走原链路。
5. 配套脚本：自检、生成 fork、写入 Web profile、展示被拒 OpenID 等（见安装步骤）。

安装与启用¶

前置条件：已安装 DSH Web profile、官方 QQ 插件且已绑定 AppID，以及已在 DSH 中创建的团队 Bot。安装流程以仓库 README 为准，不是 dsh plugin add github:… 一行命令；需在克隆或下载项目目录后执行脚本（资料中禁止在此文重复 git clone，请从 GitHub 仓库 获取源码）。

先在项目根目录做自检（无额外运行时依赖）：

node scripts/run-tests.mjs
node scripts/audit-constraints.mjs
node scripts/verify-host-resolution.mjs

生成本地 fork 的 QQ 插件包（自动定位已安装的 stock 包，也可用 --from <dir>）：

node scripts/make-bridged-qqbot.mjs --out ../dsh-bridged-qqbot
(cd ../dsh-bridged-qqbot && pnpm install --prefer-offline)

将 Web profile 指向 fork 并挂载本桥接插件（建议先看 dry-run diff）：

node scripts/install-profile.mjs --fork ../dsh-bridged-qqbot --project . --dry-run
node scripts/install-profile.mjs --fork ../dsh-bridged-qqbot --project .

停止 DSH 后，在 profile 内安装依赖并重启：

cd ~/.dsh/profiles/web && pnpm install

启动后日志中应出现类似：

[qqbot-bridge] apply() entered (plugin v0.1.0)
[qqbot-bridge] allowOpenIds: 0 configured -- FAIL CLOSED, every QQ peer is refused
[qqbot-bridge] provided the "qqbotBridge" service
[qqbot-bridge] STARTED: transport=dsh-qqbot-bridge/qq | snapshot=...

白名单配置：先在 QQ 给 Bot 发一条私聊（会被拒绝），再查 OpenID 并写入 profile patch：

node scripts/show-openids.mjs

在 ~/.dsh/profiles/web/cordis.patch.yml 中为插件 qqbot-bridge 设置 allowOpenIds: ["YOUR_OPENID"]。DSH 支持配置热重载，一般无需重启。

配置项均在你的 profile patch 中，不在插件仓库内。资料中明确出现的字段示例：

- id: qqbot-bridge
  config:
    allowOpenIds: []        # 空数组表示拒绝所有人，仅添加可信 OpenID
    defaultBot: 管家         # 尚未切换过 Bot 的私聊用户默认对话对象
    allowGroups: false      # v1 仅私聊
    replyTimeoutMs: 600000  # 等待回复超时（毫秒）

典型用法（QQ 端）¶

在 QQ 发起的问题，可在 DSH Web UI 同一 session 中继续；反之亦然。

适用场景与注意¶

适合：已在 DSH 内维护多 Agent / 多 session 团队，希望用手机 QQ 私聊触达同一套记忆与权限，且愿意按文档对官方 QQ 插件做最小 fork 并改 Web profile 的开发者。

务必注意：

• 插件与 DSH 进程同权限运行；安装前请阅读源码与 MIT 许可证，确认 fork 与 profile 变更可接受。
• 默认 fail-closed，未配置 OpenID 时所有私聊会被拒，这是预期行为。
• peer 依赖包括 @deepseek-ai/cordis、@deepseek-ai/schemastery、@deepseek-ai/dsh-agent、@deepseek-ai/dsh-session 等（版本范围见仓库 package.json）。
• 社区目录 SkillHub 插件页 与 GitHub 为独立信息源，与 DeepSeek / 幻方无官方从属关系；星标与版本以仓库为准。

结尾¶

dsh-qqbot-bridge 解决的是「QQ 触达」与「DSH 真实 session」之间的断层：不复制 prompt、不双开网关，把私聊纳入已有 Agent 工作流。详情与测试说明见 GitHub：WuChangqing1/dsh-qqbot-bridge，目录页：SkillHub - dsh-qqbot-bridge。