前言¶
DeepSeek Harness（DSH）的插件化设计让开发者可以扩展各种输入输出方式。现有的 QQ 集成方案往往需要额外启动一个独立进程，会带来权限传递、会话隔离和生命周期管理上的复杂度。tbb051122/dsh-plugin-qq-bridge 把 QQ 作为一个普通的输入输出端接入 DSH，让 QQ 消息直接在 DSH 主进程中创建或恢复真实会话。
插件定位¶
这是一个运行在 DSH 主进程中的 QQ 官方机器人桥接插件。消息在 QQ 中发出时，会话在 DSH 主进程中启动或恢复，结果以文本、图片或文件的形式发回 QQ。插件复用了独立桥接版本的 QQ 协议层，只改变了执行侧的实现。
工作方式对比¶
| 独立桥接进程 | 本插件 | |
|---|---|---|
| 任务执行 | spawn dsh --profile qq --json |
ctx.agents.create() / resume() |
| 会话存放位置 | 只在该 CLI profile 中 | DSH 主进程的会话存储（GUI 可见） |
| 权限传递方式 | 子进程环境变量 | 按会话的权限预设 |
| 生命周期 | 需保持 start-bridge.cmd 运行 |
随 DSH 主进程 |
安装与启用¶
安装插件需要 DSH 主程序支持 agents、agentDefaultModel、agentPresets、permissionPresets、sessionTitle 和 workspaceRegistry 服务（桌面应用已提供）。
安装命令：
dsh plugin add github:tbb051122/dsh-plugin-qq-bridge
安装后必须重启 DSH 主程序，插件代码只在启动时加载。
配置¶
配置文件位于 <DSH_HOME>/qq-bridge/config.json，默认为 ~/.dsh/qq-bridge/config.json。可通过 QQ_BRIDGE_HOME 环境变量指向其他目录（用于测试）。
最小配置示例：
{
"appId": "your-app-id",
"appSecret": "your-app-secret",
"intents": 33554432,
"defaultCwd": "",
"allow": { "users": [], "groups": [] }
}
常用配置项说明：
| Key | 说明 |
|---|---|
appId, appSecret |
QQ 官方机器人凭证（来自 QQ 开放平台） |
sandbox |
使用 QQ 沙箱环境而非生产环境 |
intents |
消息订阅位掩码；33554432 为单聊消息，加上群聊位可监听群消息 |
defaultCwd |
新会话的工作目录；指向已注册的 DSH 工作区可在 GUI 中显示会话，留空则每会话使用独立目录 |
agentPreset |
使用的 Agent 预设名称，空则使用主机默认 |
permissionPreset |
权限预设：danger-full-access（默认，无人值守）、workspace-write 或 read-only |
attachWorkspace |
当 defaultCwd 为注册工作区时，将会话附加到该工作区 |
allow.users / allow.groups |
OpenID 白名单，空表示“锁定”，需用 /bind <code> 绑定 |
maxConcurrent, queueLimit |
并发执行数、排队限制 |
passiveWindowMs |
QQ 给予的被动回复时间窗口 |
taskTimeoutMs |
单任务超时 |
selfTestOnBoot |
首次启动时运行端到端自测，并将结果发到 QQ |
titlePrefix |
会话标题前缀（默认 QQ） |
命令¶
在 QQ 中可发送以下命令：
/help：帮助/id：显示当前会话 ID/bind <code>：绑定账号/new：新建会话/status：状态/stop：停止当前任务/ws：列出工作区/ws <name\|index>：切换到指定工作区/ws 0：返回默认目录/history [n]：历史记录（可选指定条数）
文件结构¶
插件写入的文件均位于 <QQ_BRIDGE_HOME>（默认 <DSH_HOME>/qq-bridge）：
config.json：配置state.json：会话映射、允许列表history/：按会话和工作区存储历史workspaces/：工作区链接索引tasks/：默认任务根目录logs/：日志
安全建议¶
默认 permissionPreset 为 danger-full-access，允许无人值守任务执行。如果机器人可被未信任的用户访问，建议设置为 workspace-write 或 read-only，并将 allow.users 限制为已知用户。
开发与自测¶
开发时可使用模拟模式：
node lib/cli.mjs --mock --once "hello"
运行自测：
node lib/cli.mjs --selftest
通过 QQ_BRIDGE_HOME 指向临时目录，避免模拟运行影响真实数据。
适用场景¶
适合需要在 QQ 中与 DSH 会话交互的场景，如客服机器人、群聊助手、个人知识库入口等。插件运行在 DSH 主进程内，会话与 GUI 中的其他会话共享存储和权限设置。
结语¶
tbb051122/dsh-plugin-qq-bridge 让 QQ 成为 DSH 会话的另一个输入输出端，会话直接在主进程中创建和恢复，无需额外进程管理。使用前请检查源码与许可证。
- 插件目录：https://www.skillhub.cn/plugins/tbb051122/dsh-plugin-qq-bridge
- GitHub 仓库：https://github.com/tbb051122/dsh-plugin-qq-bridge
