# @fengye\_nobug/dsh-qq-bot 中文文档

规范地址：https://npmcn.com/package/%40fengye_nobug/dsh-qq-bot/

版本：0\.2\.12
npm 元数据更新时间：2026-11-02T05:19:28.543Z
中文译文更新时间：2026-11-14T14:29:01.838Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40fengye_nobug/dsh-qq-bot
原文对照：https://npmcn.com/package/%40fengye_nobug/dsh-qq-bot/?lang=original
项目主页：https://github.com/yunfengnobug/dsh-qq-bot#readme
源码仓库：https://github.com/yunfengnobug/dsh-qq-bot

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：741 kB，17 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：0 个
- peer 依赖：@deepseek-ai/cordis ^4\.0\.1，@deepseek-ai/dsh-llm \*，@deepseek-ai/dsh-tools \*，@deepseek-ai/schemastery \*
- 首次发布：2026-10-30T19:01:56.426Z
- 最新版本发布：2026-11-02T05:19:28.403Z
- 近 30 天下载量：2414（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

把 DSH 会话接到 QQ（OneBot/NapCat）的插件。白名单默认全关；被 @、叫到昵称或被戳一定叫醒，其余消息按可调概率抽样。Fork 自 sj244/dsh-qq-bridge（MIT）。

## 安装

```sh
npm install @fengye_nobug/dsh-qq-bot
```

也可以使用：`pnpm add @fengye_nobug/dsh-qq-bot`、`yarn add @fengye_nobug/dsh-qq-bot`、`bun add @fengye_nobug/dsh-qq-bot`

## README

# dsh-qq-bot

把已经在用的 DSH 会话接到 QQ 个人号。协议是 OneBot，常用实现是 NapCat。

Cordis 插件 id 是 `qq-bridge`。npm 包名是 `@fengye_nobug/dsh-qq-bot`。界面显示名是 dsh-qq-bot。

唤醒、出站、图片、NapCat 和全部设置项见 [`DESIGN.md`](https://npmcn.com/package/%40fengye_nobug/dsh-qq-bot/DESIGN.md)。变更见 [`CHANGELOG.md`](https://npmcn.com/package/%40fengye_nobug/dsh-qq-bot/CHANGELOG.md)。

## 简介

消息进入你指定的会话，回答可以发回 QQ。白名单默认全关。被 @、叫到昵称或被戳时会叫醒；其余消息按概率抽样。群白名单可以由主人在 QQ 里用整句命令修改。

## 功能

-   接到一个已有会话，或按群、按私聊各记一条会话。
-   白名单留空时，任何群和私聊都不会叫醒。
-   被 @、命中昵称、被戳一定叫醒。其余按 `wakeProbability`（默认 `0.05`）抽样，没抽中只记录。
-   发回 QQ 的内容由 `replyMode` 决定。在 DSH 界面里聊同一个会话时，正文不会进群。
-   图片先落盘，叫醒时写成文字。表情包可以登记后再发。半角方括号里的 `[表情名]` 会变成 QQ 系统表情。
-   设置卡片在 **设置 → 插件 → 插件配置 → QQ 桥接**。可以检查更新；有新正式版时一键安装，并重启面板。
-   可以按需下载、配置、启停 NapCat。加载插件时不会自己下载或执行。

不做审批桥接，也不走 QQ 官方机器人。

## 安装

日常安装用 npm 上已经发出的版本。仓库源码如果比已发布的版本新，不要直接装 main。

```sh
dsh plugin --profile web add @fengye_nobug/dsh-qq-bot@0.2.5
```

registry 里还没有这一版时：

```sh
dsh plugin --profile web add github:yunfengnobug/dsh-qq-bot#v0.2.5
```

装完重启 dsh-web。

环境：DSH 0.1.5-rc.3，或 0.2.0 及以后；Node ≥ 22；NapCat 的 OneBot v11 正向 WebSocket。

`cordis.patch.yml` 里 `qq-bridge` 的 `name` 写成 `@fengye_nobug/dsh-qq-bot`。写成 `dsh-qq-bot` 或 `dsh-qq-bridge` 时插件挂不上，设置接口是 HTTP 404。

不要和另一个 Cordis id 也是 `qq-bridge` 的 QQ 插件一起挂，它们会抢同一条 OneBot。已经装着 `dsh-qq-bridge` 时，先卸掉再装上面的包，然后重启。profile 里按 `id: qq-bridge` 写的覆盖可以留着；其中的 `name` 同样写成 `@fengye_nobug/dsh-qq-bot`。

升级的几条路径、开发期怎么链到本地目录，见 [`DESIGN.md`](https://npmcn.com/package/%40fengye_nobug/dsh-qq-bot/DESIGN.md) 的「使用细节」。

## 配置

白名单默认全关。先在设置卡片里填「哪些群可以叫醒」或「哪些私聊可以叫醒」，保存后再去 @。不要把真实群号、QQ 号写进仓库。

群白名单仍按群号填写。连上之后，卡片里每个群号旁边会显示当前群名和头像。没连上，或暂时查不到，就只显示群号，保存不受影响。

DSH 0.2 的卡片把值写进 `$DSH_HOME/qq-bridge-settings.json`。这份文件比 `cordis.patch.yml` 优先，保存后马上生效，重启还在。只改 `cordis.patch.yml` 要重启。

主人 QQ 在设置卡片里就叫「主人 QQ」（`ownerWhitelist`，默认 `[]`）。只有这些号能在 QQ 里改群白名单。**留空 = 这些命令不会生效。** 多个号用逗号分开。保存后下一条消息就生效。只改 `cordis.patch.yml` 要重启；设置文件里已有同名键时，以设置文件为准。

`accessTokenEnv` 填凭据引用名（一个环境变量名）。token 由 DSH 凭据服务解析，不要写进配置文件。每次建连重新解析。

| 键 | 默认 | 效果 |
| --- | --- | --- |
| `targetSessionId` | 空 | `single` 时接到哪个会话。留空 = 不接到任何会话 |
| `sessionScope` | `single` | `perGroup` 时每个群、每个私聊各一条会话 |
| `maxRecentTurns` | `40` | 每个会话最多留几轮。QQ 一轮结束并空闲后，更早的内容会尽量压缩掉。用的是这条会话自己的压缩（标准人设里就有）。人设没有时再看会话作用域和宿主。已经超限却找不到压缩，或这次压缩没有改动会话时，记一条警告。`0` = 不限制 |
| `nicknames` | `244`、`小助手` | 听到这些名字就叫醒 |
| `wakeProbability` | `0.05` | 没点名时的叫醒概率 |
| `whitelist` | `[]` | 哪些私聊可以叫醒。留空 = 都不叫醒 |
| `groupWhitelist` | `[]` | 哪些群可以叫醒。留空 = 都不叫醒。卡片里查到群名时，群号旁边有名字和头像 |
| `ownerWhitelist` | `[]` | 卡片里叫「主人 QQ」。留空 = 不能在 QQ 里改群白名单 |
| `onebotUrl` | 空 | NapCat 正向 WebSocket。留空 = 不连接 |
| `atOnlyInGroup` | `false` | 打开后，群里没被 @ 就不处理 |
| `replyMode` | `marker` | 群里发出去的是哪一段：只发「发给群」里的那段 |

其余键见 [`DESIGN.md`](https://npmcn.com/package/%40fengye_nobug/dsh-qq-bot/DESIGN.md)。

## 使用

在群里 @ 机器人，或叫出昵称。白名单没填时不会醒。

主人改群白名单时，整句必须就是命令，前面可以加一个 `/`。多出来的字不当命令。不是主人时按普通聊天处理：不改配置，也没有单独的拒绝回复。还没进白名单的群，主人仍能在群里直接加。调试工具模拟的消息不会改白名单。

| 在哪 | 整句 | 作用 |
| --- | --- | --- |
| 群里 | `白名单 加`、`白名单 加本群` | 把当前群加进群白名单 |
| 群里 | `白名单 删`、`白名单 删本群` | 把当前群移出 |
| 群或私聊 | `白名单 加 群号`、`白名单 删 群号` | 按写明的群号加或删 |
| 群或私聊 | `白名单`、`白名单 列表` | 回复现在有几个群 |
| 私聊 | `白名单 加`（没写群号） | 不改配置，提示要写群号 |

删到一个群都不剩时，回复会说明现在任何群都不会叫醒。保存方式和设置卡片相同。

`replyMode` 为 `marker` 时，模型把要发到群里的话放进 `[QQ]…[/QQ]`。会话跟随、表情包和戳一戳见 [`DESIGN.md`](https://npmcn.com/package/%40fengye_nobug/dsh-qq-bot/DESIGN.md)。

## 更新

设置卡片里先点「检查更新」。有新正式版时点「更新到 vX.Y.Z」。优先从 npm 安装；这一版还没发到 npm 时，改从 GitHub 下载。装完会自己重启 dsh-web。设置还在，不改 NapCat。刷新页面后，登录口令可能会变。

0.2.12 起，重启后如果 `$DSH_HOME/.agent-presets/dsh-qq-bridge/skills/qq-session-reply-style/references/reply-style.md` 里还有 “Emoji are welcome when they make the answer friendlier.”，会删掉这一句。「Avoid Markdown formatting. Use plain text.」还在，其它行不动，也不另写禁用表情的规矩。这份文件本来没有时不会新建。不用删掉整个人设目录。已经读进当前会话的旧规则，要等下次再读这份说明，或另开一条会话。

「检查更新」和「启动时检查一次」只询问，不会安装。

维护者发版：

1.  改 `package.json` 的 `version`。
2.  在 [`CHANGELOG.md`](https://npmcn.com/package/%40fengye_nobug/dsh-qq-bot/CHANGELOG.md) 顶部写这一版。
3.  推到 `main`。

推到 `main` 后，Actions 在 npm 上还没有 `@fengye_nobug/dsh-qq-bot` 的这一版时才发布，并补 tag `vX.Y.Z` 和 GitHub Release。`NPM_TOKEN` 放在仓库 Actions Secrets，不写进仓库。

## 许可

MIT。详见 [`LICENSE`](https://npmcn.com/package/%40fengye_nobug/dsh-qq-bot/LICENSE)。本插件基于 sj244 的 dsh-qq-bridge（MIT）。

## 常见问题

### @fengye\_nobug/dsh-qq-bot 是什么？

把 DSH 会话接到 QQ（OneBot/NapCat）的插件。白名单默认全关；被 @、叫到昵称或被戳一定叫醒，其余消息按可调概率抽样。Fork 自 sj244/dsh-qq-bridge（MIT）。

### 如何安装 @fengye\_nobug/dsh-qq-bot？

在项目目录运行 npm install @fengye\_nobug/dsh-qq-bot，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@deepseek-ai/cordis（^4\.0\.1）、@deepseek-ai/dsh-llm（\*）、@deepseek-ai/dsh-tools（\*）、@deepseek-ai/schemastery（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @fengye\_nobug/dsh-qq-bot 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/fengye\_nobug\_\_dsh-qq-bot 是否存在。

### @fengye\_nobug/dsh-qq-bot 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @fengye\_nobug/dsh-qq-bot 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @fengye\_nobug/dsh-qq-bot 可以商用吗？

@fengye\_nobug/dsh-qq-bot 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @fengye\_nobug/dsh-qq-bot 的下载量有多少？

根据 npm 官方下载统计，@fengye\_nobug/dsh-qq-bot 在 2026/10/15 – 2026/11/13 这 30 天内被下载 2,414 次，日均约 80 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @fengye\_nobug/dsh-qq-bot 还在维护吗？

最新版本 0\.2\.12 发布于 2026/11/02（12 天前）；至今共发布 10 个版本，其中过去 12 个月发布了 10 个；首次发布于 2026/10/31。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。