前言¶
DeepSeek Harness（DSH）把智能体开发收进本地 WebUI：工作区、会话、模型与权限都在同一进程里管理。实际开发时，人往往不在浏览器前——例如在通勤、临时用手机回一条消息，或希望把「审批一次 shell 操作」从桌面挪到即时通讯里完成。自建 Webhook 或第三方 IM 桥接通常还要处理鉴权、消息格式和与 DSH 会话状态的同步，维护成本不低。
下面介绍社区插件 dsh-qqbot-bridge（维护者 Jiangsubei，分类：客户端）。它走 QQ 开放平台官方 Bot API v2，用 QQ 单聊（C2C） 远程驱动 DSH 里已有的工作区与会话，不做群聊与频道。插件与 WebUI 同进程运行，列表与新建会话与侧边栏实时对齐。
这是什么¶
dsh-qqbot-bridge 是 DSH 的 QQ 官方机器人桥接插件：身份依赖 openid 与好友关系，不自研鉴权层。你在 QQ 里选工作区、选会话或直接发消息，等价于在 WebUI 里操作对应会话；Agent 的流式正文、Markdown、文件收发，以及审批与提问卡片，按 README 描述转发到 QQ 侧处理。
生态上，DSH 强调「一切皆插件」；插件目录站 skillhub.cn 为社区收录，与 DeepSeek / 幻方无官方从属关系。源码与说明见 GitHub：Jiangsubei/dsh-qqbot-bridge，npm 包名 dsh-qqbot-bridge（资料中版本 0.1.3），许可证 MIT。
核心功能¶
会话与工作区¶
- 远程控制已有会话：
/切换选工作区、/会话选会话，驱动 DSH 里已存在的会话；WebUI 可见的工作区与会话，QQ 侧可列出并接管。 - 全工作区覆盖：与 WebUI 侧边栏同一套可见性规则（例如隐藏已归档、隐藏 subagent 子会话等，以 README 为准）。
- 首次直发引导：安装后不做任何选择、直接发一条消息 → 在默认工作区
$DSH_HOME/workspace/default自动建会话并处理该消息（不会落到用户主目录）。 - 与 WebUI 同进程、状态实时同步：插件建的会话会出现在 WebUI 对应工作区分组里。
- 接管策略：优先复用 live agent；遇排他锁冲突立即如实回执，不抢锁、不降级。
消息与媒体¶
- 整回合正文流式输出：每个 step 的正文单独一条，不拼接、不丢步；可通过配置关闭流式、改用普通 Markdown 消息。
- Markdown 渲染：标题、表格、代码块、行内代码、图片等按 QQ 原生 Markdown 渲染。
- 文件与图片：Agent 可调用
send_file/send_image发回；入站附件自动落盘并注入会话（默认目录与大小上限见配置表）。
审批、提问与命令¶
- 审批与提问可远程作答：
approval/request、user-questions/request转发到 QQ，回复即可决策；超时 300 秒 fail-closed（按拒绝或未作答处理）。 - 命令系统：9 个中文命令加翻页子命令，回执纯文本；列表 10 条/页、跨页连续编号。
- WebUI 设置卡片：连接 / 行为 / 文件 / 命令四个分区；AppID/Secret 支持从 DSH 凭据库读取。
明确不做（README 原文）：群聊 / 频道 / 频道私信、记忆与人格、主动回复、表情回应、会话归档与删除、自研鉴权。机器人是被动回复模型：须由用户侧先发起单聊。
安装与启用¶
前置条件¶
- 已安装 DeepSeek Harness：
npm install -g @deepseek-ai/dsh。 - Node.js ≥ 20 与 pnpm。
- QQ 开放平台机器人（AppID / AppSecret），以及能与该机器人单聊的 QQ 号。
插件声明依赖：dsh ≥ 0.2.0（见 package.json）。
安装插件¶
推荐安装到 DSH 的 web profile（无需编译，秒级安装）：
dsh plugin --profile web add dsh-qqbot-bridge
或安装到全局默认环境：
dsh plugin add dsh-qqbot-bridge
本地开发若从源码 link，需先 pnpm install 与 pnpm build，再 dsh plugin --profile web add link:.；改 src/ 后必须重新 build，DSH 加载的是 dist/。
配置凭据¶
推荐写入 DSH 凭据库（与 DSH 其他密钥同一处，不落 settings.yaml）：
# ~/.dsh/.credentials.yaml
refs:
QQ_BOT_APP_ID: "<你的 AppID>"
QQ_BOT_SECRET: "<你的 AppSecret>"
也可在 WebUI 设置卡片填写 app_id / app_secret。解析优先级：环境变量 QQ_BOT_APP_ID / QQ_BOT_SECRET → .credentials.yaml 的 refs → 插件配置（前者优先）。
启动¶
dsh --profile web
WebUI 默认在 127.0.0.1:3080。启动后从 QQ 给机器人发一条消息即可建立使用链路。
典型用法¶
第一次发消息¶
- 直接发消息：不选工作区与会话，插件自动新建会话（回执只报工作区名），该条消息即会话的第一个 prompt。
- 选工作区：
/切换列出工作区 →/切换 <序号或名字>选中（会清空当前控制目标）。 - 选会话：
/会话列出当前工作区会话 →/会话 <序号>接管；之后普通消息在该会话中发送。
一个 openid 同时只有一个控制目标；换会话用 /会话，换工作区用 /切换。
常用命令（节选）¶
| 命令 | 说明 |
|---|---|
/状态 |
目标标题、工作区、模型、思考强度、权限档位、忙闲、上下文用量等 |
/新建 [路径] |
在当前选中工作区新建会话；受 allow_create_session 约束 |
/模型 [名称]、/思考 [强度]、/权限 [档位] |
查看或切换 |
/压缩 |
压缩当前会话历史（等价 DSH /compact） |
/停止 |
中断当前正在生成的回复 |
/帮助 |
命令清单 |
列表超过一页时，页脚会提示 /下一页、/上一页（跨页连续编号）。
审批：回复 y（或 README 列出的同义词）允许本次；n 拒绝；/取消 取消；超时 300 秒按拒绝。
提问：选择题回复序号（多选用逗号）；可回复自定义文本；/跳过、/取消；超时 300 秒视为未作答。
审批与提问只接管当前正被远程受控的会话；非受控会话仍由 WebUI 处理。
主要配置项¶
可在 WebUI 设置卡片调整，字段以 README 为准：
| 参数 | 说明 | 默认值 |
|---|---|---|
default_workspace |
默认工作区；留空则 $DSH_HOME/workspace/default |
'' |
stream_enabled |
是否走 QQ 流式消息 | true |
stream_throttle_ms |
流式分片节流（毫秒） | 1000 |
allow_create_session |
是否允许 QQ 侧新建会话（含直发自动建会话） | true |
media_dir |
入站附件目录（相对 $DSH_HOME 或绝对路径） |
qqbot/media |
media_max_bytes |
单文件落盘上限 | 209715200（200 MB） |
reply_max_chars |
命令回执最大字符数 | 1500 |
list_page_size |
列表分页大小 | 10 |
适用场景与注意¶
适合谁：已在用 DSH WebUI 管理多工作区、多会话，且希望用手机 QQ 单聊做轻量远程操控、看流式回复、收文件、回审批/提问的开发者。不适合需要群聊、频道或插件主动推送的场景。
安全与权限：插件与当前 dsh 进程同权，可触达该进程能访问的工作区与会话；安装前请阅读源码与 MIT 许可证，自行评估 AppSecret 与凭据存放方式。QQ 侧仅能控制你账号绑定的 openid 会话，但仍等同「远程桌面级」操作 DSH，勿把机器人开放给不可信联系人。
范围边界：仅单聊 C2C；不支持群聊/频道；不做会话归档与删除等 WebUI 部分能力在 QQ 侧的复刻。
结尾¶
dsh-qqbot-bridge 把 DSH 已有工作区与会话接到 QQ 官方 Bot API v2 单聊通道上：选工作区、选会话、流式 Markdown、文件与审批/提问远程作答，并与 WebUI 同进程同步。若你需要在 QQ 里管 DSH 而不是另搭一套 IM 桥，可按上文命令安装并配置凭据后，用 dsh --profile web 启动验证。
