前言¶
DeepSeek Harness (DSH) 是一个基于 Cordis 框架的智能体运行环境。dsh-adapter-qq 是其官方 QQ 机器人适配器插件，旨在解决开发者需要在移动端或桌面端 QQ 与 DSH Agent 进行深度交互（如全量编码、Shell 执行、子代理规划）的需求。
不同于常见的逆向协议实现，该插件基于 QQ 官方 OpenAPI v2 构建。它将 DSH 的 Web UI 能力与 QQ 单聊窗口打通，实现对话、执行与审批的实时同步。
核心功能¶
该插件主要提供以下能力：
- 基于 QQ OpenAPI v2 的 C2C 单聊适配：使用 WebSocket Gateway 长连接接收消息，HTTP API 发送消息，无需第三方逆向协议，连接稳定合规。
- 实时双向同屏同步：在 QQ 中提问，Web UI 实时展现；在 Web UI 中操作，QQ 端实时推送进展。
- 双向审批联动：遇到超权限操作（如文件修改）时，审批卡片同时推送到 QQ 与 Web UI。支持在 QQ 端一键点击“允许”或“拒绝”，两端立即结算。
- 交互式操作板：在聊天中生成按钮面板，支持一键切换会话、选择预设、切换权限，无需繁琐输入。
- 全局自定义快捷菜单：启动后自动通过官方 API 注册底部快捷菜单，提供会话列表、状态与快捷管理入口。
- 动态预设与权限管理：预设列表从 DSH 运行时动态获取，支持在会话中即时切换权限级别（只读、工作区写入、全系统）。
- 原生 Web UI 配置：配置项嵌入 DSH Web UI 原生设置页，安全字段自动脱敏。
安装与前置要求¶
安装前请确保环境满足以下条件：
- Node.js: 版本 >= 18
- 依赖库:
@deepseek-ai/cordis(^4.0.0) 和@deepseek-ai/schemastery(^3.18.0) - QQ 凭证: 需准备 QQ 开放平台的
AppID和AppSecret
安装命令如下：
dsh plugin --profile web add dsh-adapter-qq
配置项¶
安装后，进入 DSH Web UI 的 设置 (Settings) 页面，展开 【QQ 机器人 (QQ Bot)】 卡片进行配置。主要配置项包括：
appId: 填写 QQ 开放平台的 Bot AppID。clientSecret: 填写 AppSecret（密文遮罩）。sandbox: 是否连接沙箱环境（测试期间建议勾选）。userOpenid: 绑定的专属用户 OpenID（留空将在收到首条消息时自动绑定）。defaultPreset: 新建会话默认 Agent 预设（如standard）。defaultCwd: 新建会话默认工作目录。autoRegisterMenu: 启动后自动注册底部快捷菜单。markdown: 消息回复优先使用 Markdown 渲染。syncToolCalls: 是否同步推送工具调用执行进度。toolCallAggregateWindowMs: 工具调用聚合推送窗口时间（毫秒）。
交互指令¶
在 QQ 单聊窗口中，可直接发送以下指令或在底部菜单/操作板中点击按钮：
| 指令 | 功能说明 |
|---|---|
/sessions |
查看工作区层级树形会话列表，支持按键切换 |
/new |
启动新建会话向导，选择工作区或目录 |
/switch <序号或ID> |
切换当前活跃会话 |
/current |
查看当前会话详细信息 |
/model |
查看模型列表，支持一键切换 |
/effort |
查看或切换思考等级（off/low/medium/high/xhigh/max） |
/stats |
查看会话统计（轮次、步数、LLM耗时、缓存命中率等） |
/preset |
查看或切换 Agent 预设 |
/permission |
查看或切换权限模式（只读、工作区写入、全系统） |
/cancel / /stop |
中止当前 Agent 运行 |
/approve / /reject |
批准或拒绝待审批请求 |
/menu |
手动同步底部快捷菜单 |
/help |
显示帮助菜单与操作板 |
注意事项¶
- 权限运行：插件以当前 DSH 进程的权限运行，涉及系统操作或文件修改时需注意权限配置。
- 许可证：遵循 MIT 许可证。
- 网络环境：若使用代理软件（如 Clash），需确保
bots.qq.com与*.qq.com直连，避免 DNS 解析失败。
总结¶
dsh-adapter-qq 是 DeepSeek Harness 生态中连接 QQ 生态的关键插件。它通过官方 API 提供了稳定、合规的 C2C 交互方式，并实现了与 Web UI 的深度双向绑定，适合需要在移动端或即时通讯场景下使用 DSH 编码与执行能力的开发者。
文档与源码：
* 技能目录：https://www.skillhub.cn/plugins/jixishi/dsh-adapter-qq
* GitHub 仓库：https://github.com/jixishi/dsh-adapter-qq
