前言¶
在 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', …)）。未使用该扩展点的宿主行为与原版一致。
核心功能¶
- 会话级桥接：QQ 私聊进入对应 Bot 的真实 DSH session，保留历史、记忆、工具与工作区；会话滚动到新 part 时，每次发送前重读
state.json。 - 多 Bot 路由：通过 QQ 内命令切换当前对话对象（见下文「典型用法」），路由持久化到
routing.json，按 OpenID 区分。 - 安全默认：空白名单拒绝所有私聊；仅 v1 私聊，
allowGroups: false。 - 可观测：控制台日志与
bridge-status.json；插件注册qqbotBridgeCordis 服务供运维查询；官方/bot-ping、/bot-status等命令仍可走原链路。 - 配套脚本：自检、生成 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 端）¶
| 命令 | 作用 |
|---|---|
/管家 /设计师 /程序员 /聊天 |
切换当前对话的 Bot（按 OpenID 持久化） |
/团队 |
列出团队 |
/当前 |
显示当前正在对话的 Bot |
| 其他文本 | 发给当前 Bot，回复经桥接回到 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。
