dsh-onebot-qq

dsh plugin --profile web add dsh-onebot-qq

dsh-onebot

[English](README.en.md) | 中文

给 DeepSeek Harness 加上 QQ 通道。A QQ channel for dsh.

本插件把 dsh 变成一个 QQ 机器人（OneBot 11 协议，兼容 NapCat / Lagrange / LLOneBot / go-cqhttp；

0.9.12 起新增兼容 SnowLuma 协议端——forward 模式对接其 wsServers（Bearer 头或 ?access_token=，零改动兼容），reverse 模式服务端同时接受 Bearer 头与 ?access_token= query 鉴权），

与 dsh-vision 同款的外部插件形态：**零 Python、纯 TS、

原生 Cordis 插件**，挂载进 dsh 宿主进程，不改任何核心代码。

用户(QQ) ←→ NapCat ←→ dsh-onebot 插件 ←→ dsh Agent（每个会话一个）
                        ├─ 反向 WS 服务器 / 正向 WS 客户端（自动重连）
                        ├─ 入站：CQ 解析、图片下载、语音转写(STT)、引用/合并转发展开
                        └─ 出站：单条/t2i 卡片发送、Markdown 剥离、[[qq_forward]]、图片/语音/视频/文件工具

架构

可交互版本（暗/亮主题切换 + 引导视图）：[docs/dsh-onebot-architecture.html](docs/dsh-onebot-architecture.html)；矢量版：[docs/dsh-onebot-architecture.svg](docs/dsh-onebot-architecture.svg)。

功能

类别 · 能力

连接 · 反向 WS（NapCat ws-reverse 拨入，默认端口 8643）或正向 WS（拨出，默认 ws://127.0.0.1:3001）；断线自动重连（2s→60s 退避）

入站 · 私聊/群聊、段数组优先解析（CQ 字符串回退）、CQ 反转义、@/回复触发检测（fail-closed；回复仅认机器人自己的消息）、图片四路解析（url/base64/file/hash）、大图自动压缩（长边 ≤inboundImageMaxPx，GIF 不压）、文件段双通道接收（CDN 直链 get_private_file_url + get_file base64/url 回退）、表情 id→emoji/卡片/戳一戳段类型、引用消息自动取原文（get_msg）、合并转发自动展开（get_forward_msg）

语音 · ffmpeg 转 16kHz WAV + whisper 转写（openai-whisper / whisper.cpp / 自定义命令）；非阻塞：语音消息先以 [语音] 占位进入回合（不阻塞回复），转写完成后以「（语音转写：…）」补递（默认超时 60s）；转写失败/超时保留 [语音] 占位

文字图 · t2i 卡片渲染器（@napi-rs/canvas）：标题/粗斜体/删除线/引用/列表/代码块/表格/行内 code 胶囊/彩色 emoji/中文标点禁则；与 Hermes 原版同款数值（800px/26px/禁则集合/右缘 790）

出站 · 正文 ≤ textImageThreshold（默认 150）字符单条发送、超过阈值渲染 t2i 文字图卡片（AstrBot 风格：标题/引用/列表/表格/代码块/彩色 emoji；渲染失败、PNG 超 outboundImageMaxBytes 或 <=0 禁用卡片时回退单条纯文本）、Markdown 剥离为 QQ 纯文本、[[qq_forward]] 合并转发（群/私聊）、实时中间消息（interimMessages：每条中间文本立即发出、实时可见；各自在 interimRecallMs（默认 90s）后自动单独撤回；回合结束时先把整轮中间消息渲染成一张 t2i 小结卡、立即撤回仍在屏幕上的原文、再发送最终回复——不用回合末合并转发，避免长回合「原文超 2 分钟撤不回+转发卡重复」；interimRecall: false 时降级为只发不撤（无小结卡、不撤回））、宿主「计划书/提问卡」自动中继（模型调用 exit_plan_mode 时把计划全文发到 QQ；ask_user_question QQ 桥接（0.9.11）：问题渲染成 QQ 选项卡、群友回复选项/答:/跳过 即回传答案，等待期内即时结算，300s 未答转 pending 后仍可回答，见「群聊权限分档与 ask_user_question 桥接」）、正在输入提示（set_input_status，仅私聊）

命令 · 斜杠命令（默认仅管理员；/help 群友可见成员视图）：/new 开新会话、/stop 停止生成、/steer <补充内容> 向运行中的任务补充指令（无运行任务时回用法提示；详见下方命令表与 newMessagePolicy 配置）、/model 查看或切换当前会话模型（--default 修改部署默认；无参输出两级序号列表，回复序号选 provider → 再回复序号选模型）、/workspace 查看或切换工作区（无参编号列表，回复序号即选）、/preset 查看或切换 agent 预设（无参编号列表，回复序号即选）、/session 查看可切回历史会话并按序号切回（/new、/workspace、/preset 切换下来的旧会话进列表，可来回切，历史上下文恢复）、/status 会话全景、/doctor [export [参考号] · test]（别名 /healthcheck）运行体检（export [参考号] 导出脱敏诊断包 qq-diagnostics-*.zip，文件名含触发参考号；test 一键自测收发链路）、/retry 重跑上一条、/id 会话标识、/ver 版本、/ocr 识别最近图片、/mode 切换出站模式（跨重启持久化）、/plan 计划模式、/permission 切换宿主权限预设（QQ 别名 w=工作区可写+需审批、f=全权+免审批；完整预设名照传，未知名由宿主报错并回显可用列表；无参查看当前与可用列表，序号按 available 顺序）、/goal 目标记录（跨重启持久化）、/silent [分钟] 临时免打扰（0.9.11 起，默认 30 分钟，再次 /silent 提前解除，见命令表）、/help 帮助（0.9.11 起群友可见成员视图，仅列群友可用的命令）；未知斜杠命令默认拦截并提示相近命令（unknownCommand: passthrough 改为透传给模型）

工具 · qq_send_image（≤9 张，路径或 URL）、qq_send_voice、qq_send_video、qq_send_file、qq_send_segments（1–9 段纯文本分段气泡，每段 ≤500 字，见下文「分段发送」）、qq_send_forward、qq_napcat_api（14 个白名单 action）、qq_group_history（文件编辑工具 code_safe_edit 等已拆至独立插件 dsh-safe-edit，见下文「安全编辑」）

权限 · 管理员白名单（ONEBOT_ALLOWED_USERS）、dm/group 策略（open/allowlist/disabled）、群聊 @提及 gating、群聊权限分档（0.9.11：每条群消息前缀标注发言人档位·管理员/·成员；成员档位回合禁用全部 qq_* 工具，permissions.memberTools: all 可放开）、受限用户 [受限用户:仅问答] 软限制、出站敏感内容审计

会话 · 每个 QQ 会话一个持久 Agent（session id 稳定派生），重启后自动 resume；按 agentPreset/agentPresetGroup/workspacePath 挂载到 preset 与工作区；每轮结束 flush 落盘

运维 · 热加载：profile 层 patch 的 config 覆盖与 insert 新增/删除均热生效——插件 fiber 秒级原地重启（宿主进程不重启；代价：QQ 桥一次秒级重连、在途回合中断）；touch/内容未变不触发任何动作；bundle 自带 patch、仓库模板、部署副本的 patch 文件与根配置 cordis.yml 的改动不热生效；临时媒体 TTL 过期清理

提示词 · 自动注入 QQ 平台说明（纯文本输出、图片/语音标注 [图片]/[语音] 占位、工具与命令指引、ask_user_question QQ 桥接、禁宿主 Web 审批卡 exit_plan_mode）；按每个 QQ 会话 agent 自身作用域注入，Web 会话不可见

兼容性

项 · 要求

dsh · ≥ 0.1.5-rc.1（engines.dsh：0.1.5/0.1.6/0.1.7 全线 + 0.2.0 线 ≥0.2.0-rc.1；@deepseek-ai/* peer 依赖同范围，JsonValue 由 dsh-util-values 提供）

Node.js · ≥ 22

OneBot 11 实现 · NapCat / Lagrange / LLOneBot / go-cqhttp / SnowLuma（reverse 或 forward WebSocket）

可选依赖 · 语音转写需 ffmpeg + whisper CLI；t2i 文字图在 Linux 需 Noto CJK 字体

最后验证：2026-10-12（0.9.0 发版批次 W1–W3 五特性：v4 命令审计 / verify 体检脚本 / 排队插话+autoSteerPolicy / 超时补发 / 诊断参考号——npx tsc --noEmit 零错误、vitest 532 用例全绿；M0 安全语义保持：reverse 空 token 拒绝启动、默认仅监听 127.0.0.1 为 BREAKING 变更，见下方配置表说明）。

安装

前置：dsh（≥0.1.5-rc.1）在 PATH 上；NapCat 或其他 OneBot 11 实现已运行。

npm 安装（发布通道，与下方源码安装二选一，勿混装）

dsh plugin --profile web add dsh-onebot-qq

（或用 Web 界面的 Plugins 页安装。）随后：

1. 在 profile 目录 <DSH_HOME>/profiles/web/ 的 pnpm-workspace.yaml 中写入两行

（实测 pnpm 12 不读项目级 .npmrc，见 docs/npm-e2e-report.md D1）：

   autoInstallPeers: false
   hoist: false

——防止 pnpm 自动拉入 registry 上陈旧的 @deepseek-ai/* 独立副本。npm/pnpm 版本差异：

此配置仅 pnpm 12 用户必须（pnpm 12 已不读 .npmrc）；npm 用户无此问题——实测 npm 默认

peer 自动安装拉入的 registry 现版本满足 peer 范围（docs/npm-e2e-report.md §1 #2）。

运行期 peer 统一由宿主解析层完成：插件 import 的 @deepseek-ai/*

只要声明在该包 peerDependencies 里，就会被宿主拦截并重定向到宿主安装树的同一实例，

无需任何 npm override。

2. 把包内 cordis.patch.yml 模板的两行 insert 合并进 profile 层

<DSH_HOME>/profiles/web/cordis.patch.yml：主条目 name: 'dsh-onebot-qq'，

host-plane 行 name: 'dsh-onebot-qq/settings-remote'；config 覆盖须挂

patch 顶层同 id 行（详见模板头注释）。

3. 不要在 profile 的 package.json 手写任何 @deepseek-ai/* 依赖——手写副本会

覆盖宿主安装树成为拦截目标，造成版本错位双包。

4. 若安装被兼容门拒绝（dsh 版本不在 peer 范围内），按官方口径用

dsh plugin allow-version ... --accept-risk 显式豁免。

方式二：git clone 源码安装

git clone <repo> ~/dsh-plugins/dsh-onebot
cd ~/dsh-plugins/dsh-onebot
npm install --inclu

…(truncated)