@yangfan1998/dsh-qqbot-plus

DeepSeek Harness 的 QQ 机器人整合包：装一次，带网关、识图、语音和 B 站工具。

@yangfan1998/dsh-qqbot-plus 会挂载 @zaofan/dsh-qqbot 网关，并额外提供：

• qqbot_describe_image — 图片理解 / OCR
• tts_speak — Edge TTS 语音（mp3）
• bili_read / bili_search / bili_hot / bili_frames — B 站视频、弹幕、评论、缩略图理解

它是 bundle，不是 QQ 网关的 fork。网关仍然是 @zaofan/dsh-qqbot，可以独立升级。

当前版本：0.1.2。已发布到 npm；本地也可以 npm pack 后安装。

---

环境要求

项目	要求
Node.js	>= 22.13
DeepSeek Harness	>= 0.2.1-alpha.2
QQ 机器人	QQ 开放平台的 AppID + AppSecret
识图模型	支持图片输入的 LLM 路由（默认 zhipu/aliyun/qwen3-vl-plus）
TTS（可选）	edge-tts 可执行文件在 PATH，或配置 tts.bin
B 站（可选）	公开数据不需要 Key；BILIBILI_SESSDATA 可解锁字幕

---

安装

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

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

如果 pnpm 报 ERR_PNPM_IGNORED_BUILDS（QQ 网关依赖的 onnxruntime-node / protobufjs）：

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

然后把这个 bundle 加进 profile 的 package.json（部分 DSH 版本的插件管理器不会自动追加）：

{
  "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
# 生成 yangfan1998-dsh-qqbot-plus-0.1.0.tgz

dsh plugin --profile <你的profile> add ./yangfan1998-dsh-qqbot-plus-0.1.0.tgz

方式三：已经有 QQ 网关的 profile

这个包默认会插入 im-qqbot。如果你已经装了 @zaofan/dsh-qqbot，不要把本包加入 dsh.profile.bundles，否则会出现重复的 im-qqbot。

改为：安装本包后，把 cordis.tools-only.yml 里的 - insert: 段复制到你 profile 自己的 cordis.patch.yml。

---

配置凭据

bundle 的 cordis.patch.yml 使用 __FROM_ENV__ 读取 appId / appSecret。

方式 A：环境变量

export QQBOT_APPID=1905977275
export QQBOT_APP_SECRET=你的secret

方式 B：直接写 profile patch

编辑 profile 的 cordis.patch.yml 里的 im-qqbot 行：

- id: im-qqbot
  name: '@zaofan/dsh-qqbot'
  config:
    appId: '1905977275'
    appSecret: '你的secret'

不要把真实密钥提交到 Git。

如果想让机器人接收非 @ 的群消息，群主还需要在 QQ 机器人资料页开启“接收群消息/通知”。

---

工具配置

bundle 自带安全默认值。覆盖时改 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

识图

只要你的 LLM 路由里有支持 image 输入的模型即可。模型必须在 llm-pi-ai（或其他 LLM 插件）的 provider 配置里存在。

模型不可用时，qqbot_describe_image 会自动禁用；不会拖垮整个插件。

语音

tts_speak 调用外部 edge-tts，默认把 mp3 写到 downloads/tts。

python3 -m pip install edge-tts
# 或者指向已有 venv：
# tts.bin: /path/to/venv/bin/edge-tts

edge-tts 不可用时，工具会返回明确错误，不会让插件崩溃。

B 站

公开视频的元数据、弹幕、评论不需要 Cookie；字幕通常需要登录：

export BILIBILI_SESSDATA=你的SESSDATA

B 站会限流匿名请求；工具内部做了节流，并缓存匿名 buvid3 Cookie。

---

工具列表

工具	用途
qqbot_describe_image	看一张本地图片或 URL；OCR、表格、截图、照片
tts_speak	用 Edge TTS 生成短语音 mp3；再用 send_media(kind="voice") 发出
bili_read	视频元数据、弹幕、热评（含楼中楼）、可选字幕
bili_search	按标题/关键词搜 B 站，返回 BV 和匹配度
bili_hot	B 站热门榜
bili_frames	视频缩略图拼图 → 视觉模型概述；分辨率低，不要当事实

---

可选扩展

包内带了两个 {dataRoot}/.qqbot-extensions 扩展：

• extensions/inbound/bili-card-url.mjs — 从 QQ 小程序卡片的 raw 数据里提取 B 站 URL。只接受 URL，不接受裸 BV...，因为 QQ message id 里可能刚好包含假 BV。
• extensions/outbound/abs-image-paths.mjs — 发图前把 markdown 里的相对图片路径改成绝对路径。
• extensions/outbound/random-sticker.mjs — 回复发完后按概率从正式图库补一张表情包；只作用于群聊，默认 15% 概率、同一会话 10 分钟冷却。

复制到 QQ 机器人的数据根：

DATA_ROOT="/path/to/qqbot/data-root"   # 通常是 <im-qqbot.cwd>/dshqqbot
PKG_DIR="$(node -e "console.log(require.resolve('@yangfan1998/dsh-qqbot-plus'))" | xargs dirname)"

mkdir -p "$DATA_ROOT/.qqbot-extensions/inbound" "$DATA_ROOT/.qqbot-extensions/outbound"
cp "$PKG_DIR/extensions/inbound/bili-card-url.mjs" "$DATA_ROOT/.qqbot-extensions/inbound/"
cp "$PKG_DIR/extensions/outbound/abs-image-paths.mjs" "$DATA_ROOT/.qqbot-extensions/outbound/"

abs-image-paths 默认用 process.cwd() 解析相对路径；如果宿主 cwd 和 im-qqbot.cwd 不一致，设置 QQBOT_CWD。

random-sticker 可调：

QQBOT_STICKER_PROB=0.15          # 每次回复补图概率
QQBOT_STICKER_COOLDOWN_MIN=10    # 同一会话最短间隔（分钟）

它只从 {dataRoot}/lib/library 或 {dataRoot}/表情包/lib/library 里选图，不会用候选区/回收站的图。

---

不包含什么

• 不包含 QQ AppID / AppSecret / API Key / Cookie
• 不包含人设或群守则（自带你的）
• 不包含表情包图库（第三方素材授权问题）
• 不包含 Web 设置页；通过 cordis.patch.yml 或环境变量配置
• 不包含 launchd / systemd 服务文件；部署方式由你决定

---

安全说明

• B 站工具会访问 bilibili.com、b23.tv 和 api.bilibili.com。
• 识图工具只下载你传入的 http(s) 图片，不扫描任意文件。
• tts_speak 会用配置的 edge-tts 可执行文件执行文本参数；不要把 tts.bin 指向不可信脚本。
• 本包不内置任何凭据。建议用专门的 QQ 机器人账号运行。

---

发布检查

• npm pack 后在全新测试 profile 安装
• 确认 im-qqbot + qqbot-plus 都激活
• 用真实图片验证 qqbot_describe_image
• 用 edge-tts 验证 tts_speak
• 用公开 BV 验证 bili_read
• 更新 package.json 里的版本/作者/仓库
• npm publish（需要 npm 账号和 2FA）
• 推到自己的 GitHub 仓库（不要复用别人的凭据）
• 加 dsh-plugin topic，提交到 DSH 插件市场

---

许可证

MIT，见 LICENSE。