# @cmnyhh/qdash-neo 中文文档

规范地址：https://npmcn.com/package/%40cmnyhh/qdash-neo/

版本：0\.1\.11
npm 元数据更新时间：2026-10-27T11:43:41.917Z
中文译文更新时间：2026-11-10T04:15:45.753Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cmnyhh/qdash-neo
原文对照：https://npmcn.com/package/%40cmnyhh/qdash-neo/?lang=original

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

- 包体积（解压后）：920 kB，52 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：0 个
- peer 依赖：@deepseek-ai/cordis ^4\.0\.1，@deepseek-ai/dsh-llm \*，@deepseek-ai/dsh-agent \*，@deepseek-ai/dsh-session \*，@deepseek-ai/dsh-schemastery \*
- 首次发布：2026-10-27T04:56:11.613Z
- 最新版本发布：2026-10-27T11:43:41.726Z
- 近 30 天下载量：2442（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

QQ DSH : OneBot v11 : + ctx.agents + session/event + 活动 :

## 安装

```sh
npm install @cmnyhh/qdash-neo
```

也可以使用：`pnpm add @cmnyhh/qdash-neo`、`yarn add @cmnyhh/qdash-neo`、`bun add @cmnyhh/qdash-neo`

## README

![qdash-neo](https://npmcn.com/package/%40cmnyhh/qdash-neo/src/console/public/assets/brand-logo.png)

# qdash-neo

将 QQ 群聊与私聊接入 DSH 的聊天机器人插件

官方插件：[qdash-neo-plugins](https://github.com/cmnyhh/qdash-neo-plugins) （语音 TTS、插件开发规范）

本项目不是独立的机器人框架，而是 [DSH](https://github.com/deepseek-ai/dsh) 的插件。它复用 DSH 的模型、会话、工具与权限体系：收到的 QQ 消息直接进入一次对话，回复由模型自行决定是否发出。

## 功能

-   支持群聊与私聊，通过白名单控制可触发的用户
-   **由模型自行决定是否发言**：不发言时不会产生任何输出，不依赖概率拦截
-   `@`、称呼名字、拍一拍均可唤醒
-   图片识别（需支持视觉的模型）
-   长期记忆：记录交谈过的人与事，每日自动生成总结
-   角色卡：可指定人设，语气与发言频率均由角色卡定义
-   内置控制台，修改配置无需重启宿主；首次访问时自行设定口令
-   群管理（踢人）为可选项，按 QQ 号白名单校验，默认关闭
-   语音：发语音库里现成的音频；装 `@cmnyhh/qdash-neo-plugin-voice` 后还能把一句话现说出来
-   **可扩展**：插件能注册工具、存自己的数据、加控制台页、挂自定义判定器

## 快速开始

### 1\. 环境要求

-   Node.js 22+
-   DSH 0.2.x
-   OneBot v11 实现（NapCat、Lagrange.OneBot、LLOneBot 均可）

### 2\. 安装

**推荐在 DSH 控制台里装**：打开控制台 → **插件** → **安装**，输入包名 `@cmnyhh/qdash-neo`，确认后重启宿主。

命令行等价：

```bash
dsh plugin --profile web add @cmnyhh/qdash-neo
```

两种方式做的事一样：装进 profile 的 `node_modules`，并登记到它的 `dsh.profile.bundles`。插件自带 `dsh.bundle.patch`，DSH 会自己应用它的 `cordis.patch.yml`，不需要再改任何配置文件。

> **不要用 `--patch` 启动参数加载它。**
> 
> `npx dsh --profile web --patch node_modules/.../cordis.patch.yml` 这种写法能用，但每次启动都会**重新注入**一次。后果是控制台的插件管理里卸载不掉——点卸载会报「其他配置仍在使用这个组合包的组件」，而那个"其他配置"就是启动参数本身，只能去改 systemd 的 `ExecStart`。
> 
> 走插件安装（控制台或 `dsh plugin add`）才是正常途径：插件归 profile 管，能直接停用和卸载。

**卸载**：控制台里点卸载，或者

```bash
dsh plugin --profile web remove @cmnyhh/qdash-neo
```

数据不会跟着删：`$DSH_HOME/storages/qdash-neo.db`（含 `-wal` / `-shm`）需要手动清理。

### 3\. 配置

打开控制台 `http://127.0.0.1:7800/`（用户名 `admin`）。首次访问会要求**自行设定**控制台口令，之后用它登录；也可在 `cordis.patch.yml` 里预置 `console.password` 跳过这一步。

至少需要填写以下三项：

| 位置 | 内容 |
| --- | --- |
| 连接 | `onebot.wsUrl`：OneBot 的 WebSocket 地址，如 `ws://127.0.0.1:3001` |
| 连接 | `onebot.token`：OneBot 的 access token（未配置则留空） |
| 触发权限 | `policy.whitelist`：允许私聊的 QQ 号 |

使用群聊时，还需在 `policy.groupWhitelist` 中填写群号。

### 4\. 验证

在私聊中发送一条消息即可。

## 发言判断机制

这是本项目与多数 QQ 机器人的主要差异：**默认不会回应每条消息**。

| 情况 | 行为 |
| --- | --- |
| 被 `@`、被称呼名字、被拍一拍 | 一定会回应 |
| 有人提问（即使未 `@`） | 大概率回应 |
| 他人之间的对话、模型不熟悉的话题 | 由模型判断，多数情况下不参与 |

判断依据写在通用提示词中，**不依赖**回复概率拦截：该消息是否针对自己、此时介入是否合宜。

**发言频率由角色卡决定**。通用提示词只负责判断维度，性格特征写入角色卡；如需调整活跃程度，修改角色卡即可，无需改动插件。

## 配置

以下配置均可在控制台修改，保存后立即生效（标注「需重启」的除外）。常用项如下：

| 配置 | 默认值 | 说明 |
| --- | --- | --- |
| `agent.model` | `deepseek-v4.1-flash` | 使用的模型 |
| `agent.reasoningEffort` | `high` | 思考强度 |
| `policy.groupTrigger` | `agent` | 群消息触发方式：`agent` 每条交由模型判断 / `mention` 仅回应 `@` / `judge` 先用小模型筛选 |
| `policy.replyChance` | `0.95` | 通过触发判断后的再次抽样概率，`1` 表示不抽样 |
| `memory.enabled` | `true` | 长期记忆 |
| `proactive.enabled` | `false` | 允许模型排期后主动发言（默认关闭，详见下文） |
| `voice.enabled` | `false` | 允许发送语音（默认关闭，详见下文） |
| `tools.qqAdmin` | `false` | 群管理能力，**开启后还需配置 `tools.adminOwners` 方可生效** |

### 主动发言

默认**关闭**。开启后，模型可在认为「稍后值得再说」时安排一次延后评估（`[[LATER:30]]`）；到期后重新判断，可以选择不发言。

夜间时段为硬性限制：`proactive.quietHours` 默认 `23:00–07:00`，该时段内即使排期到期也不会唤起。另有 `proactive.maxPerDay` 限制每日次数。

### 语音

默认**关闭**，分为两层：

**底座（主包自带）**：将音频文件（`.mp3` / `.silk`）放入 `voice.dir`（默认 `<DSH_HOME>/qdash-voice`），模型即可通过 `qq_send_voice` 发送。仅允许库内文件，并受体积与频率上限约束。

**TTS（需另装插件）**：`@cmnyhh/qdash-neo-plugin-voice` 提供 `qq_speak({ text })`，将文本合成为语音。该插件仅负责产出音频文件；发送、路径校验、限流与落库仍由主包完成。

```bash
npm i @cmnyhh/qdash-neo-plugin-voice
```

开启后由模型**自行判断**使用文字还是语音：多数情况下使用文字；语音仅用于「一两句话即可说完、语气比字面更重要」的场合，例如道晚安、调侃、感慨。

TTS 支持三种接口形式，在插件的 `cordis.patch.yml` 中配置（`tts.protocol`）：

| 值 | 请求 | 适用 |
| --- | --- | --- |
| `openai` | `POST {endpoint}`，body 为 `{model, input, voice, response_format}` | 兼容 `/v1/audio/speech` 的服务 |
| `gpt-sovits` | `POST {endpoint}`，body 为原生 `/tts` 接口格式 | 本地 GPT-SoVITS（另需填写 `refAudioPath` / `promptText`） |
| `custom` | 由 `bodyTemplate` 替换 `{{text}}` 生成 | 非标准端点 |

合成结果按内容与音色缓存，相同文本不会重复合成。TTS 不可用时，模型会改用文字表达相同内容，不会因此丢失回复。

## 远程访问控制台

控制台默认只监听 `127.0.0.1:7800`，**本机以外不可达**。这是有意的：它能改白名单、OneBot 凭据和群管理权限。

需要远程访问时，用下面两种方式之一，**不要**直接把 `console.host` 改成 `0.0.0.0`（等于把改配置的入口暴露到公网）。

### 方式一：SSH 隧道

```bash
ssh -L 7800:127.0.0.1:7800 user@your-server
```

然后在**自己电脑**的浏览器打开 `http://127.0.0.1:7800/`。不需要改任何配置。

### 方式二：反向代理

以 nginx 为例：

```nginx
location /qdash-neo/ {
    proxy_pass http://127.0.0.1:7800/;          # 结尾的 / 会剥掉前缀
    proxy_set_header Host $host;                 # 必须传：Host 白名单靠它
    proxy_set_header X-Forwarded-Proto $scheme;  # 必须传：HTTPS 下 cookie 才带 Secure
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
```

然后访问 `https://example.com/qdash-neo/`。

`console.allowedHosts` 默认是 `['*']`（放行任意 Host），所以反代**不需要额外配置**。

**`X-Forwarded-Proto` 必须传**：少了它在 HTTPS 下 cookie 不带 `Secure`，浏览器可能拒存，表现是「登录成功但立刻跳回登录页」。

**`X-Forwarded-For` 也要传**：登录失败限流按来源 IP 计数。反代之后所有请求的来源都是 `127.0.0.1`，不传这个头的话，一个人输错几次就会把**所有人**锁在外面。

> `allowedHosts` 这层原本防的是 DNS rebinding（恶意站点把自己的域名解析到 `127.0.0.1`）。默认全开是为了免配置，代价由两道兜住：控制台有口令，且首次设置的提交会校验 `Origin`。如果你有固定域名，把它填进去可以恢复这层防护。

## 常见问题

**发言过少？** 先查看控制台中的会话记录。若 `withheld` 持续增长，说明模型已生成内容但未调用发送工具，属于「决定不发言」，并非故障。如需提高活跃度，请修改角色卡。

**发言过多？** 降低 `policy.replyChance`（硬性限制），或在角色卡中明确说明发言偏好。

**无法识别图片？** 需要支持视觉的模型，请将 `agent.model` 改为相应模型。

**控制台无法访问？** 默认仅监听 `127.0.0.1:7800`，本机以外不可达。这是有意的，见上文「远程访问控制台」（SSH 隧道或反向代理）。

**更换 `DSH_HOME` 后配置丢失？** 数据库随 `DSH_HOME` 迁移。数据库使用 SQLite WAL 模式，迁移时需同时复制 `.db`、`-wal`、`-shm` **三个文件**；仅复制 `.db` 会导致数据丢失。

## 致谢

本项目受 [qq-bridge](https://github.com/Derpyu520/qq-bridge) 很多启发，在此致谢。

## 许可

MIT

## 常见问题

### @cmnyhh/qdash-neo 是什么？

QQ DSH : OneBot v11 : \+ ctx\.agents \+ session/event \+ 活动 :

### 如何安装 @cmnyhh/qdash-neo？

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

### @cmnyhh/qdash-neo 支持 TypeScript 吗？

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

### @cmnyhh/qdash-neo 支持 ESM 还是 CommonJS？

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

### @cmnyhh/qdash-neo 需要什么版本的 Node\.js？

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

### @cmnyhh/qdash-neo 可以商用吗？

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

### @cmnyhh/qdash-neo 的下载量有多少？

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

### @cmnyhh/qdash-neo 还在维护吗？

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