dsh-qqbot-bridge

dsh-qqbot-bridge

DeepSeek Harness × QQ 官方机器人插件 —— 用 QQ 单聊远程控制 DSH 里已有的所有工作区会话：流式输出、Markdown 渲染、文件收发、命令系统。

走 QQ 开放平台官方 Bot API v2，身份即 openid 与好友关系，不自研鉴权层；仅单聊 C2C，不做群聊/频道。

✨ 功能特性

• 远程控制 DSH 已有会话：/切换 选工作区、/会话 选会话，直接驱动 DSH 里已存在的会话
• 全工作区覆盖：WebUI 里能看到的工作区与会话，QQ 侧都能列出来接管
• 首次直发引导：装好插件后不做任何选择、直接发一条消息 → 自动在默认工作区 $DSH_HOME/workspace/default 建会话并处理该消息（不会落到用户主目录）
• 整回合正文流式输出：每个 step 的正文单独一条，不拼接、不丢步
• Markdown 渲染：标题/表格/代码块/行内代码/图片均按 QQ 原生 Markdown 渲染
• 文件与图片收发：Agent 可调 send_file / send_image 工具发回；入站附件自动落盘并注入会话
• 审批与提问可远程作答：approval/request / user-questions/request 转发到 QQ，回复即可决策（超时 300s fail-closed）
• 命令系统：9 个中文命令 + 翻页子命令，回执纯文本；10 条/页、跨页连续编号
• 与 WebUI 同进程、状态实时同步：插件建的会话会实时出现在 WebUI 侧边栏所属工作区分组里
• 接管不抢锁、绝不降级：优先复用 live agent；遇排他锁冲突立即如实回执
• WebUI 设置卡片：连接 / 行为 / 文件 / 命令 四个分区；AppID/Secret 支持从 DSH 凭据库读取

明确不做：群聊 / 频道 / 频道私信、记忆与人格、主动回复、表情回应、会话归档与删除、自研鉴权。

📦 安装

前置条件

• DeepSeek Harness：npm install -g @deepseek-ai/dsh
• Node.js ≥ 20 与 pnpm
• 一个 QQ 开放平台机器人（AppID / AppSecret），以及一个能与该机器人单聊的 QQ 号

安装方式

方式一：通过 DSH 插件管理一键安装（推荐）

# 推荐：安装到 DSH 的 web profile（无需编译，秒级安装）
dsh plugin --profile web add dsh-qqbot-bridge

# 或安装到全局默认环境
dsh plugin add dsh-qqbot-bridge

方式二：从源码克隆安装（本地开发 / link 模式）

git clone https://github.com/Jiangsubei/dsh-qqbot-bridge.git
cd dsh-qqbot-bridge
pnpm install
# 构建产物：DSH 通过 package.json main → dist/ 加载，必须先 build
pnpm build
# link 安装到 DSH 的 web profile
dsh plugin --profile web add link:.

配置凭据

推荐写进 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 给机器人发一条消息即可。机器人是被动回复模型：必须先由用户侧发起单聊。

⚠️ 改了 src/ 必须重新 pnpm build：link 部署时 DSH 加载的是 dist/。只改源码不构建，插件仍跑旧代码。

🚀 首次使用

1. 直接发消息：不做任何选择就发一条消息，插件会自动新建会话（回执只报工作区名），这条消息就是该会话的第一个 prompt。
2. 选工作区：/切换 列出所有工作区 → /切换 <序号或名字> 选中（会清空当前控制目标，防误发）。
3. 选会话：/会话 列出该工作区会话 → /会话 <序号> 接管，之后发消息就是在那个会话里说话。

一个 openid 同时只有一个控制目标；换会话用 /会话，换工作区用 /切换。

⚙️ 配置

参数	说明	默认值
app_id	QQ 机器人 AppID（留空则从环境变量 / refs.QQ_BOT_APP_ID 读取）	''
app_secret	QQ 机器人 AppSecret（建议留空，走 refs.QQ_BOT_SECRET）	''
default_workspace	默认工作区路径；留空则用 $DSH_HOME/workspace/default（首次用到时自动创建并注册）	''
stream_enabled	整回合正文走 QQ 流式消息（关闭则用普通 Markdown 消息）	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
status_show_usage	/状态 是否显示上下文用量	true

💬 命令

命令	说明
/会话 [序号]	列出 / 选择当前工作区的会话（列表项 = 序号 + 标题 + 相对活跃时间；最新在前）。可见性与 WebUI 侧边栏一致：隐藏已归档、隐藏 subagent 子会话、空白会话仅当前受控时可见；归档会话不可按序号/标题选中
/切换 [工作区]	列出 / 选择工作区作用域（支持序号 / 路径 / 标题）；切换会清空控制目标；列表里的「会话 N」不计归档
/新建 [路径]	在当前选中的工作区新建会话；未选中工作区则回退默认工作区；路径未注册会自动注册
/状态	目标标题 / 所属工作区 / 模型 / 思考强度 / 权限档位 / 忙闲 / 上下文用量
/压缩	压缩当前会话历史（等价 DSH 的 /compact）；先回「正在压缩…」、完成后追加结果；不可中断
/模型 [模型名或 供应商/模型]	查看 / 切换模型
/思考 [强度]	查看 / 切换思考强度
/权限 [档位]	查看 / 切换权限预设
/停止	中断当前会话正在生成的回复
/帮助	命令清单与用法
/下一页 /上一页	列表翻页（跨页连续编号）；不在 /帮助 中列出，仅当列表超过 1 页（>10 条）时随列表页脚提示

审批：收到「需要你批准一次操作」时，回复 y（或 是/允许/同意/批准/1/好/可以）→ 仅本次允许；n（或 否/拒绝/2/不）→ 拒绝；/取消 → 取消。超时 300 秒按拒绝处理。

提问：选择题回复序号（多选用逗号，如 1,3），也可直接回复自定义文本；/跳过 跳过当前题，/取消 放弃整次提问。超时 300 秒视为未作答。

审批 / 提问只接管当前正被远程受控的会话；非受控会话的审批 / 提问完整委派给 WebUI，互不干扰。受控会话的卡片只进 QQ（不进 WebUI）是预期行为。卡片按被动回复投递；仅当完全无锚点时降级为主动消息。文案不含 emoji。

🛠️ 开发

cd <本仓库目录>
pnpm install
pnpm build             # tsc + 客户端 UI 打包（dist/client.js）
pnpm test              # 先 build 再跑契约测试

📄 License

MIT