dsh-qq-bridge

将 QQ 接入 DeepSeek Harness 的双向桥插件——通过 QQ 官方机器人 API v2（私聊 + 群聊）， 让你直接在 QQ 里驱动 DeepSeek Harness 的 Agent：每个 QQ 对话拥有独立、持久的隔离 Agent 会话， 像在 Web 里一样使用完整的工具链、模型切换与工作区。

✨ 特性

• 🔌 零依赖网关：QQ 官方 WebSocket 协议（token 预刷新 / 心跳假死检测 / 指数退避重连 / Resume 补发），仅用 Node 内置能力
• 🧊 隔离会话：每 QQ 对话 ↔ 一个持久 DSH Agent（agents.create/resume），历史按 (对话, 工作区) 隔离，重启自动恢复
• ⚡ steering 插嘴：任务运行中继续发消息，立即注入下一步骤（DSH 原生）
• 📚 完整命令体系：/help /status /model /thinking /new /sessions /resume /compact /stop /workspace + 键盘按钮
• 🔐 首访审批：未授权用户自动生成审批码，管理员一键授权（支持普通用户/管理员两级）
• 🖼️ 多媒体：图片直入视觉模型、语音 ASR/STT、TXT/PDF 有界提取；安全下载（SSRF 防护）
• 📤 出站文件：Agent 可调用 qq_send_local_file 把本地文件发回 QQ（白名单 + 硬链接/竞态防护）
• 🗂️ 多工作区：QQ 侧 /workspace 切换目录，会话历史按工作区隔离
• ✅ 实测可用：116 个单测 + 真实 QQ 沙箱文本闭环验证

移植自 pi-qq-bridge（Apache-2.0）： 宿主无关模块（网关/路由/命令/媒体/格式化）原样复用；宿主绑定层（会话创建/工具/命令）改为 DSH 官方 API。

---

架构

QQ 平台 WS 事件
  → src/gateway/qq-gateway.ts（状态机/心跳/重连/Resume）
  → src/router.ts（去重 → 白名单/审批 → 命令 | FIFO 队列 → 隔离会话）
  → src/session/qq-session.ts（DSH 适配：ctx.agents.create/resume + followup/whenIdle）
  → 最终文本 → src/reply-formatter.ts（Markdown 分块 → 降级纯文本）→ QQApi 发送

模块	说明
src/gateway/	token 管理 / WS 网关 / REST 发送与上传（宿主无关，原样移植）
src/session/	DSH 隔离会话：每 QQ 对话 ↔ 一个持久 DSH agent（sessionId qq-<hash>-<seq>，cwd = 桥工作区）；注册表懒创建/回收/工作区切换
src/router.ts	消息路由、steering 插嘴、回复预算（宿主无关）
src/commands/	QQ 侧命令、授权矩阵、审批码、键盘（宿主无关）
src/media/	附件安全下载/嗅探/提取/STT/出站媒体（宿主无关；图片经 ctx.attachments）
src/core/	配置（schemaVersion 4 严格校验）/ 类型 / 错误码（宿主无关）

关键宿主 API（详见 HOST-API.md）：

• 会话：ctx.agents.create({sessionId, meta:{cwd}, agentOptions, setup}) / ctx.agents.resume({resumeSessionId})
• 运行：agent.followup(createUserMessage(...)) + agent.whenIdle() + 事件摘要（官方范式，见 dsh-headless）
• 插嘴/中止：agent.steer / agent.cancel({kind:'user'})
• 模型：ctx.agentDefaultModel + installModelSelection；ctx.llm.listProviders/listModels
• 工具：ctx.tools.register(defineTool(...))（agent 作用域，QQ 会话专属 qq_send_local_file）
• 命令：ctx.commands.register（全局，Web UI 可见）
• 图片：ctx.attachments.saveImage → ImageBlock

---

安装

开发/冒烟（dev profile，不碰运行中的 GUI）

# 1. 插件依赖（typescript/@types/node + unpdf）
cd ~/dsh-qq-bridge && pnpm install

# 2. dev profile（已存在 ~/.dsh/profiles/dev，bundles: dsh-base + dsh-headless）
dsh plugin --profile dev add ~/dsh-qq-bridge

# 3. 冒烟：headless 任务 + 插件 overlay
dsh --profile dev --patch ~/dsh-qq-bridge/dev-overlay.yml 'Reply with exactly: OK'
# 验证：qqbotdsh/.boot-marker 出现（apply 已执行）

挂载到 web profile（正式使用；需重启 dsh web）

dsh plugin --profile web add ~/dsh-qq-bridge
# 编辑 ~/.dsh/profiles/web/cordis.patch.yml 追加：
#   - insert:
#       - id: dsh-qq-bridge
#         name: 'dsh-qq-bridge'
# 重启 dsh web（注意：这是你正在用的 GUI 服务器）

配置

cp config.example.json ~/.dsh/qq-bridge/config.json
chmod 600 ~/.dsh/qq-bridge/config.json
# 填入 appId / clientSecret；sandbox 保持 true

字段与 pi-qq-bridge 一致（schemaVersion 4）：allowUsers / allowGroups / workspaces / commands / sessions / replyFormat / progress / media / outboundMedia 等。

Windows 原生部署适配

在 Windows 原生（非 WSL）环境部署时注意以下三点（对应 PR #6/#8）：

1. 工作区避开 C:/Users/...（含 Temp）

Windows 的 windows-acl 沙箱要求临时目录（temp root）在会话工作区之外；若默认工作区落在 C:/Users/<user>（其子目录通常包含 Temp），会触发沙箱冲突 （temp root must be outside the workspace）。

解决：在配置里显式指定一个非 home 的工作区，插件会自动优先选用它作为 QQ 会话的默认工作区：

…