# QQ 机器人功能手册 · 总览与导航

> 这是 `dsh-onebot-qq` 管线的**唯一文档入口**。按「你现在要做什么」往下找；细节都在下面对应的手册里。
>
> **适用**：插件 v0.1.2 ｜ DSH `>= 0.2.1-rc.2 < 0.3.0` ｜ Node ≥ 22 ｜ Linux / Windows（CI）；macOS 尚无 CI / 真机验收证据
>
> 一分钟看懂它是什么：

```text
QQ 客户端 ↔ 协议端（OneBot v11） ↔ 本插件（DSH 进程内：微内核 + 12 个子插件） ↔ DSH（模型 / 会话 / 控制台）
```

安装后只有一处入口要记：**DSH 设置 →「QQ 控制台」**（含消息监测专页；常规配置下次读取/轮次生效，资源与启动项见 [热改说明](配置参考.md#热改说明)）。

---

## 一、30 秒上手路线

```text
① 装插件         dsh plugin --profile web add github:YUsaltyfish/dsh-onebot-qq
② 建数据目录     node bin/dsh-onebot-qq.mjs init      （首次启动也会自动投递默认人设）
③ 启动           dsh web                              （首次缺配置会进「待配置模式」）
④ 连 QQ          控制台「新手向导」填主人 QQ + 协议端地址 → 自动连接
⑤ 试一句         QQ 里 @ 它 / 私聊发一句话 → 有回复即成功
```

- **Linux / macOS**：完整步骤看 [安装与卸载](安装与卸载.md)，日常功能看 [使用说明书](使用说明书.md)。
- **Windows**：一路看 [Windows 安装](Windows安装.md)（从装 Node 到真机验证），功能部分同样看 [使用说明书](使用说明书.md)。
- **只想让 AI 帮你装**：把 [安装与卸载](安装与卸载.md) 或 [Windows 安装](Windows安装.md) 整份丢给 DSH，让它照着做。

---

## 二、按任务找文档

### 2.1 想用功能

| 我想…… | 看这里 |
|---|---|
| 叫醒它（@ / 引用 / 唤醒词 / 私聊） | [使用说明书 §5.1](使用说明书.md#51-叫醒它) |
| 聊天、长文分段、让它发本地图片 | [使用说明书 §5.2](使用说明书.md#52-聊天--发图--长文) |
| 收群文件 / 私聊文件（什么时候下载、大小限制） | [使用说明书 §5.3](使用说明书.md#53-收文件) |
| 生图 / 图生图 / 取群友头像 | [使用说明书 §5.4](使用说明书.md#54-生图--图生图)、[§5.5](使用说明书.md#55-头像) |
| 表情包（自动收图、让它发表情） | [使用说明书 §5.6](使用说明书.md#56-表情包) |
| 入群欢迎（固定句池 / 模型现写） | [使用说明书 §5.7](使用说明书.md#57-入群欢迎) |
| 群记忆（看 / 改 / 自动积累） | [使用说明书 §5.8](使用说明书.md#58-群记忆) |
| 解析 B 站 / 抖音链接（可选） | [使用说明书 §5.9](使用说明书.md#59-链接解析可选) |
| 消息监测（规则匹配、附加指令、测试匹配） | [使用说明书 §5.10.1](使用说明书.md#5101-消息监测匹配消息并附加处理指令) |
| 主动接话（话题接话 / 冷场找话） | [使用说明书 §5.10](使用说明书.md#510-主动接话可选) |
| 权限、门禁、屏蔽群、黑白名单 | [使用说明书 §5.11](使用说明书.md#511-权限与门禁) |
| 斜杠命令（`/help` `/status` `/reset` …） | [使用说明书 §5.11](使用说明书.md#511-权限与门禁) |
| 写 / 换人设，句池与唤醒词 | [使用说明书 §6](使用说明书.md#6-人设怎么写) |
| 控制台 16 个页面分别干什么 | [使用说明书 §4](使用说明书.md#4-控制台一页一览) |

### 2.2 想安装 / 配置 / 排障

| 我想…… | 看这里 |
|---|---|
| 从零安装、升级、卸载 | [安装与卸载](安装与卸载.md) |
| Windows 从零到跑通 + 真机验证清单 | [Windows 安装](Windows安装.md) |
| 首次配置 / 连协议端 / 新手向导 | [安装与卸载 §四](安装与卸载.md#四首次配置推荐控制台新手向导) |
| 换协议端（任意 OneBot v11 实现 ↔ SnowLuma） | [安装与卸载 §二](安装与卸载.md#二准备协议端onebot-v11) |
| 接了 SnowLuma 之后的问题 | [排错 §二·二](排错.md#二二接了-snowluma-之后) |
| 手动改 `config.json`，查某个键的默认值 | [配置参考](配置参考.md) |
| 加装「QQ 线工具门」（挡掉全局工具） | [安装与卸载 §三](安装与卸载.md#可选qq-线工具门挡住全局工具) |
| 出问题：连不上 / 不回消息 / 图片发不出 | [排错](排错.md) |
| 内置离线自检、临时缓存清理、配置备份去重 | [内置运维](<运维接口.md>) |

### 2.3 想改代码 / 了解实现

| 我想…… | 看这里 |
|---|---|
| 加一个子插件 / 给模型加工具 | [开发指南 §六~§九](开发指南.md) |
| 看懂内核装配、五阶段管线、代码红线 | [开发指南 §一~§五、§十一](开发指南.md) |

---

## 三、功能总览（一个能力一行）

> 12 个子插件全部可单独开关（控制台「子插件」页）；可选模块按各自配置启用，链接解析另需侧车。

| 能力 | 一句话用法 | 控制台页 | 详解 |
|---|---|---|---|
| **唤醒与门禁** | 群里默认被叫才回（@ / 引用 / 唤醒词）；私聊永远回 | 唤醒、群聊 | [§5.1](使用说明书.md#51-叫醒它) |
| **收文件 / 发图** | 文件「被叫到才下载」（20MB / 5 个 / 留 7 天）；发图只认白名单目录 | 文件与图片、其他 | [§5.2](使用说明书.md#52-聊天--发图--长文) [§5.3](使用说明书.md#53-收文件) |
| **生图 / 图生图** | 直接说「画一只…」；改图就发图 / 引用图再说「改成…」 | 生图 | [§5.4](使用说明书.md#54-生图--图生图) |
| **群友头像** | 说「用他的头像画…」→ 自动取公开头像当参考图 | 其他（头像组） | [§5.5](使用说明书.md#55-头像) |
| **本机图片 / 参考图** | 说「用那张参考图 / 上次那张」→ 先调 `list_images` 列图，再挑一张当参考 | 生图 | [§5.4](使用说明书.md#54-生图--图生图) |
| **表情包** | 收表情可开关（默认只读不写索引）；回话时按概率提醒它顺手带一张 | 表情包 | [§5.6](使用说明书.md#56-表情包) |
| **入群欢迎** | 每组可勾；欢迎语用固定句池（零 token）或模型现写 | 入群欢迎 | [§5.7](使用说明书.md#57-入群欢迎) |
| **群记忆** | 每群/每私聊一篇 Markdown；只按每日整理实际互动，逐会话维护稳定记忆、近期经历与约定，超预算保留待办 | 群记忆 | [§5.8](使用说明书.md#58-群记忆) |
| **链接解析**（可选） | B 站 / 抖音链接自动发媒体；需自备解析侧车 | 链接解析 | [§5.9](使用说明书.md#59-链接解析可选) |
| **主动接话**（可选） | 群私聊共用1–4小时正常随机窗、4–10小时未回窗及退避；群逐群允许、私聊明确名单，内容依人设 | 主动接话、群聊 | [§5.10](使用说明书.md#510-主动接话可选) |
| **权限 / 门禁** | 主人 QQ（只在「群聊」页）决定脱敏豁免与命令权限；门禁支持屏蔽群、黑白名单 | 群聊、其他 | [§5.11](使用说明书.md#511-权限与门禁) |
| **斜杠命令** | `/help` 任何人；`/status` `/reset` `/resetall confirm` `/cancel` `/quota` `/history [N]` 仅主人 | — | [§5.11](使用说明书.md#511-权限与门禁) |
| **防刷屏**（可选） | 同一个人同一句话刷屏 → 冷却回一句，零 token | 唤醒 | [配置参考 §五](配置参考.md#五子插件配置pluginconfigid) |
| **私聊好友门禁**（可选） | 私聊只回好友（好友列表拉取失败时放行） | 其他 | [配置参考 §五](配置参考.md#五子插件配置pluginconfigid) |
| **聊天留档** | 文本/媒体进出都留档到 `logs/qq_chat/`（默认开） | 其他 | [配置参考](配置参考.md#archive) |
| **QQ 控制台** | 含消息监测规则页、配置热改（原子写 + 备份 + 失败回滚） | 全部 | [§4](使用说明书.md#4-控制台一页一览) |
| **工具门**（可选插件） | 摘掉漏进 QQ 会话的全局工具（`ops_*` / agent-team / MCP） | — | [安装与卸载 §三](安装与卸载.md#可选qq-线工具门挡住全局工具) |
| **子插件扩展** | 新建 `plugins/<id>/index.js` 即自动发现，坏一个不影响其他 | 子插件 | [开发指南](开发指南.md) |

---

## 四、文档地图（哪份是什么，唯一真相在哪）

| 文档 | 定位 | 什么时候读 | 权威性 |
|---|---|---|---|
| **文档总览（本页 `docs/README.md`）** | 总览、任务索引、功能总览 | 第一次来 / 忘了某功能在哪 | 只做导航，不写细节 |
| [使用说明书](使用说明书.md) | **功能怎么用**：日常操作、人设、控制台 | 装机之后天天用 | 功能行为的唯一真相 |
| [安装与卸载](安装与卸载.md) | 安装 / 首次配置 / 升级 / 卸载 / 回滚 | 部署与升级时 | 安装流程的唯一真相 |
| [Windows 安装](Windows安装.md) | Windows 从零到跑通、真机验证、已知限制 | Windows 部署 | Windows 专属细节的唯一真相 |
| [配置参考](配置参考.md) | 全部配置键、默认值、路径规则、热改 | 想手动改 JSON / 查默认值 | 配置键的唯一真相 |
| [排错](排错.md) | 一键诊断、日志、常见故障现象 → 处理 | 出问题先看 | 故障处理的唯一真相 |
| [开发指南](开发指南.md) | 实现契约 + 子插件 SDK、五阶段、红线 | 读代码 / 加功能前 | 实现契约与扩展方式的唯一真相 |
| [内置运维](<运维接口.md>) | 离线自检、临时缓存清理与配置备份去重 | 检查环境 / 腾出缓存空间 | 内置维护范围与预演确认规则 |

> 本机维护记录与补丁属于**部署机私有资料**，**不在本仓库**（不随插件发布 / 不进 npm 包）。

**文档纪律（防止再次散架）**

1. **一个主题只有一份**：功能写在「使用说明书」，安装写在「安装与卸载」，键写在「配置参考」；别的文档只放链接，不抄整段。
2. **改功能 → 同一次改动里改对应文档**；新增配置键 → 补「配置参考」；新增命令/工具 → 补「使用说明书」与「开发指南」。
3. 文档里只写**占位符**（`10001`、`~/...`、`https://example.invalid`），不写真实 QQ 号 / 群号 / token / 机器路径。
4. 历史文档（旧 standalone 时代的《QQ机器人功能手册》）**已作废**，不要按旧文里的旧桥接路径、旧进程名（`onebot-dsh-bridge`）操作。

**旧称对照**（读旧文档 / 维护记录时用）

| 旧称 | 现在 |
|---|---|
| 桥接 / bridge / standalone | 插件内核（`dsh-onebot-qq`，in-process；旧独立进程已废弃） |
| qq-lines 工作区 | `<dataDir>/workspace`（QQ 线工作区） |
| 回话模式页 | 控制台「主动接话」页（配置 `pacing.reply`） |

---

## 五、三条推荐阅读路径

- **新用户（只想用）**：本页 §一 → [安装与卸载](安装与卸载.md) → [使用说明书](使用说明书.md) §3–§5 → 需要时查 [配置参考](配置参考.md)。
- **Windows 用户**：[Windows 安装](Windows安装.md) → [使用说明书](使用说明书.md) → [排错 §五](排错.md#五windows-权限与-symlink) / [Windows 安装 §十二](Windows安装.md#十二windows-专属排查)。
- **开发者 / 维护者**：[开发指南](开发指南.md) → [配置参考](配置参考.md) + [运维接口](运维接口.md)。

> 找不到答案时：先看 [排错 §〇 一键诊断](排错.md#〇第一步一键诊断推荐先做)，把生成的脱敏报告交给 DSH 排查。