前言¶

在 DeepSeek Harness（DSH）里接 QQ，常见做法是单独装 @zaofan/dsh-qqbot 网关，再按需加 LLM 路由、工具插件。识图、短语音、读 B 站视频信息往往还要再配几套依赖和 Cordis patch。@yangfan1998/dsh-qqbot-plus（GitHub：FanFFF/dsh-qqbot-plus）把网关与上述能力打成 bundle：装一次，挂载现有 QQ 网关包，并注册一组可直接给智能体调用的工具。它不是 QQ 网关的 fork，网关仍可独立升级。

这是什么¶

维护者 FanFFF 在 npm 发布 @yangfan1998/dsh-qqbot-plus，当前版本 0.1.2，许可证 MIT，分类属于 DSH 社区目录中的 客户端 类插件。简介为：One-install DSH QQ bot bundle: gateway + vision + TTS + Bilibili。

bundle 会挂载 @zaofan/dsh-qqbot，并额外提供识图、Edge TTS、B 站读取等工具；配置通过 bundle 自带的 cordis.patch.yml 或 profile 覆盖完成，不包含 Web 设置页。

环境要求¶

安装前确认环境与凭据是否齐备：

核心功能¶

网关¶

bundle 插入 im-qqbot，底层仍是 @zaofan/dsh-qqbot（依赖版本 ^1.10.46）。与单独装网关相比，本包的价值在于 一次把工具与默认 patch 对齐，而不是替换网关实现。

工具一览¶

识图依赖 LLM 插件（如 llm-pi-ai）里已配置的、支持 image 的模型；不可用时 qqbot_describe_image 会自动禁用，不会拖垮整个插件。TTS 与 B 站工具在依赖缺失时返回明确错误，同样不会导致插件崩溃。

可选 QQ 扩展¶

包内提供 {dataRoot}/.qqbot-extensions 下的脚本，需手动复制到 QQ 机器人数据根（通常是 <im-qqbot.cwd>/dshqqbot）：

• bili-card-url.mjs（入站）：从小程序卡片 raw 数据提取 B 站 URL（只接受 URL，不接受裸 BV...）。
• abs-image-paths.mjs（出站）：发图前把 markdown 相对路径改为绝对路径。
• random-sticker.mjs（出站）：群聊回复后按概率补表情包（默认 15% 概率、同会话 10 分钟冷却）。

本包 不包含 QQ 凭据、人设、表情包图库、systemd/launchd 单元；部署方式由你自行决定。

安装与启用¶

方式一：从 npm 安装（推荐）¶

先把 bundle 加到指定 profile：

dsh plugin --profile <你的profile> add @yangfan1998/dsh-qqbot-plus

若 pnpm 报 ERR_PNPM_IGNORED_BUILDS（网关依赖 onnxruntime-node / protobufjs），在 profile 目录执行：

cd ~/.dsh/profiles/<你的profile>
pnpm approve-builds --all

部分 DSH 版本的插件管理器不会自动把 bundle 写入 package.json，需手动加入 dsh.profile.bundles：

{
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "@yangfan1998/dsh-qqbot-plus"
      ]
    }
  }
}

启动前确认组合树里网关与工具插件都已出现：

dsh --profile <你的profile> --dump-config | grep -A3 'id: im-qqbot'
dsh --profile <你的profile> --dump-config | grep -A3 'id: qqbot-plus'

方式二：本地 tarball¶

cd /path/to/dsh-qqbot-plus
npm pack
dsh plugin --profile <你的profile> add ./yangfan1998-dsh-qqbot-plus-0.1.0.tgz

（README 示例 tarball 文件名为 0.1.0 打包结果；以 npm pack 实际文件名为准。）

方式三：profile 里已有 QQ 网关¶

若已安装 @zaofan/dsh-qqbot，不要再把本包加入 dsh.profile.bundles，否则会重复插入 im-qqbot。应安装本包后，将包内 cordis.tools-only.yml 的 - insert: 段复制到你 profile 的 cordis.patch.yml。

配置凭据与工具参数¶

QQ AppID / AppSecret¶

bundle 的 patch 用 __FROM_ENV__ 读环境变量，也可直接写 profile 的 cordis.patch.yml：

export QQBOT_APPID=1905977275
export QQBOT_APP_SECRET=你的secret

或在 patch 中配置 im-qqbot 的 appId / appSecret（勿把真实密钥提交 Git）。若需接收非 @ 的群消息，还需在 QQ 机器人资料页开启「接收群消息/通知」。

覆盖 qqbot-plus 默认值¶

- id: qqbot-plus
  name: '@yangfan1998/dsh-qqbot-plus'
  config:
    vision:
      provider: zhipu
      model: aliyun/qwen3-vl-plus
      maxTokens: 1024
    tts:
      bin: edge-tts
      voice: zh-CN-XiaoyiNeural
      rate: '+5%'
      pitch: '+12Hz'
      maxChars: 500
    bilibili:
      timeoutMs: 20000
      danmakuLimit: 25
      commentLimit: 10
      replyLimit: 5

TTS 安装示例：

python3 -m pip install edge-tts

默认 mp3 输出目录为 downloads/tts。B 站字幕等可设：

export BILIBILI_SESSDATA=你的SESSDATA

典型用法¶

智能体在 QQ 会话中可按工具能力组合使用，例如：

1. 用户发图或给出图片 URL → 调用 qqbot_describe_image 做 OCR 或内容描述。
2. 需要语音回复 → tts_speak 生成 mp3，再通过 QQ 网关的 send_media(kind="voice") 发送。
3. 讨论 B 站链接 → bili_read 拉元数据、弹幕、评论；bili_search / bili_hot 做检索与热榜；bili_frames 仅作低分辨率画面概述。

复制 B 站卡片扩展后，入站消息可从小程序卡片自动解析出 B 站 URL，减少模型手工猜链接。

适用场景与注意¶

适合希望在 一个 profile 里快速打通 QQ 与识图、短 TTS、B 站信息读取的 DSH 开发者；已有成熟 @zaofan/dsh-qqbot 部署的，更适合走 tools-only patch，避免重复网关。

使用前请注意：

• 插件以 当前 DSH 进程权限 运行；安装前建议阅读 GitHub 仓库 源码与 MIT 许可证。
• B 站工具会访问 bilibili.com、b23.tv、api.bilibili.com；识图仅下载你传入的 http(s) 图片。
• tts.bin 指向外部可执行文件，勿指向不可信脚本。
• 包内不内置任何 API Key 或 Cookie；建议用专用 QQ 机器人账号运行。

DSH 生态强调「一切皆插件」；社区目录 skillhub.cn 为独立站点，与 DeepSeek / 幻方无官方从属关系。

结尾¶

@yangfan1998/dsh-qqbot-plus 把 QQ 网关与识图、Edge TTS、B 站工具收进同一 bundle，减少重复 patch 与依赖对齐成本；网关仍由 @zaofan/dsh-qqbot 维护，可按需单独升级。

• 目录页：https://www.skillhub.cn/plugins/FanFFF/dsh-qqbot-plus
• GitHub：https://github.com/FanFFF/dsh-qqbot-plus