# QQ 机器人使用说明书

> 一句话：装好 DSH 插件 → 连上协议端（OneBot v11）→ 填主人 QQ → 在 QQ 里 @ 它就能用。
> 只想跑通看 1~3 节；功能怎么用看 4~5 节；人设怎么写看第 6 节；出问题看第 7 节。
> 📖 **文档入口**：[功能手册总览](README.md)。本文只讲「怎么用」；安装/升级/卸载看[安装与卸载](安装与卸载.md)，Windows 看[Windows 安装](Windows安装.md)，配置键看[配置参考](配置参考.md)，故障看[排错](排错.md)。

---

## 1. 准备什么

| 东西 | 要求 |
|---|---|
| **DSH**（DeepSeek Harness） | `>= 0.2.1-rc.2 < 0.3.0`，桌面版或 `dsh web` 都行 |
| **OneBot v11 协议端** | 任意实现（如 SnowLuma、OneBot 等）；需要开 **正向 WebSocket**（常见默认 3001）和 **HTTP API**（常见默认 3000） |
| **SnowLuma**（可选，本机在用） | v2.2.0，OneBot v11 实现（默认端口同 3001/3000）；**不启动 QQ**，注入已运行的 QQ 进程，且两个端口**强制 token**。接法见 §3 |
| **一个 QQ 号** | 建议用小号；协议端登录它，机器人用它收发消息 |

> 三样都在同一台电脑上最省事；协议端装在别的机器也行，地址填通即可。

---

## 2. 安装（最短路径）

```bash
dsh plugin --profile web add github:YUsaltyfish/dsh-onebot-qq   # ① 装插件
node bin/dsh-onebot-qq.mjs init                                # ② 建数据目录 + 默认人设（包目录执行）
dsh web                                                        # ③ 启动
```

> 数据目录默认 `~/.dsh/dsh-onebot-qq`（Windows：`%USERPROFILE%\.dsh\dsh-onebot-qq`）；包目录 = 源码仓库根或安装后的 `<profile>/node_modules/dsh-onebot-qq`。
> 装完验收：控制台「运维 → 一键诊断」无红叉。完整安装 / 首次配置 / 升级 / 卸载 / 回滚 → [安装与卸载](安装与卸载.md)；Windows → [Windows 安装](Windows安装.md)。

---

## 3. 连上 QQ（协议端：OneBot v11）

1. **协议端里**：开启**正向 WebSocket**（默认 `ws://127.0.0.1:3001`）与 **HTTP API**（默认 `http://127.0.0.1:3000`），有 token 记下来。
   - **通用**：在协议端自己的界面里登录 QQ（扫码/密码都行；本插件不代登录）。
   - **SnowLuma**：**不启动 QQ** —— 先自己开 QQ 用手机扫码登录，再启动 SnowLuma 让它注入（WebUI <http://127.0.0.1:5099>，初始账号 `admin`，密码在**全新数据目录首启日志里打印一次**）；OneBot 开 WS `3001` + HTTP `3000`，**两个端口都强制 `accessToken`**，抄下来填插件。
2. **插件里**：控制台「OneBot 连接」页填 WS / HTTP 地址（+ token）→「测试 OneBot 连接」；「群聊」页填**主人 QQ** → 保存自动连接（**任意 OneBot v11 协议端都填这里**；配置键是 `onebot.*`）。
3. **验收只看两排字**：内核 已连接 + QQ 已登录（断开/未登录先看协议端 WebUI，再点「运维 → 一键诊断」）。

> **和多数实现差在哪**（接 SnowLuma 前先看）：

| 差别 | 多数实现 | SnowLuma |
|---|---|---|
| 开 QQ | 协议端自带/拉起 QQ 客户端（注入方式各实现不同） | **不启动 QQ**：先手动开 QQ 登录，再注入运行中的进程（Linux 要 `cap_sys_ptrace` 或 root） |
| token | 可选 | **3000/3001 强制** `accessToken`，`wsToken` / `httpToken` 都要填 |
| 扫码 | 协议端自带 WebUI 扫码（端口见各实现文档） | 纯扫码，**没有 CLI / 二维码 API**：无头机器用 VNC/noVNC，或截图 QQ 登录窗口发布成网页二维码 |
| 掉线判定 | WebUI 看 QQ 在线 | `get_status` 的 `good=false` = 收发链路停滞（发得出收不进） |

> 接 SnowLuma 建议关掉它自带的 `#sl` 状态指令（`statusCommand.enabled=false`）：默认开时群里发 `#sl` 框架会回一句，`swallow:false` 时还会把消息继续下发给机器人（各回一句）。另：`message_id` 是**非零有符号 int32（负值合法）**，引用/撤回用返回的真实 id；`get_file` 只覆盖图片/语音缓存，群文件/视频溯源可能降级。

---

## 4. 控制台一页一览

| 页面 | 干什么 |
|---|---|
| **总览** | 健康状态、新手引导、当前人设（点一下换人设） |
| **运维** | 测试连接、重连、内置离线自检、一键诊断、临时缓存清理与配置备份去重（先预演确认） |
| **群聊** | 主人 QQ、上文条数、基础命令开关；每个群的屏蔽/白名单/黑名单/主动接话/入群欢迎 |
| **OneBot 连接** | WS/HTTP 地址与 token、连接状态、测试按钮，以及 QQ 新会话默认模型选择（不改已有会话、记忆分析或全局默认；选不上时显示最近回退） |
| **消息设置** | 单条字数、长文卡片、引用规则、合批等待（等对方说完再答） |
| **主动接话** | 没人叫也偶尔接一句：频率、冷场判定、语境权重、连续对话 |
| **唤醒** | 门禁与唤醒总开关、免@唤醒词（填空+添加）、必须被叫、关键词冷却、被戳回一句 |
| **文件与图片** | 收文件总开关、什么时候下载、大小上限、单条数量上限、保留天数 |
| **人设与拆条** | 人设句池开关、人设目录、当前人设（填写=钉死并切换，与总览页人设标签同一事务）、拆条（概率/字数上下限/间隔/条数）、引用纪律 |
| **入群欢迎** | 欢迎语（固定句池 / 模型现写）、图片池、延迟、测试发送 |
| **生图** | 生图凭据（协议 / 地址 / 模型 / API Key）+ 冷却、超时、参考图目录 |
| **链接解析** | B 站/抖音等链接解析（可选，需要自备解析侧车，默认关） |
| **表情包** | 群表情自动收集、库上限、回话提醒开关与概率、每轮上限 |
| **其他** | 低频配置：门禁（屏蔽群/名单）、文件目录、发图白名单、头像缓存（主人 QQ 在「群聊」页） |
| **消息监测** | 添加/删除/启停/排序规则；监听内容、包含或整条匹配、生效群、附加指令、冷却；只读测试匹配 |
| **子插件** | 12 个子插件的总开关（和功能页里的开关同源，改哪边都一样） |
| **群记忆** | 每个群一篇 Markdown 记忆，可看/改（自动备份旧版） |

---

## 5. 日常怎么用

运维按钮开箱可用，无需本机扩展。「跑离线自检」不联网、不发 QQ、不写报告；需要联网排查或导出报告时才用「一键诊断」。清理临时文件只处理插件 `incoming` / `imagegen` 专用缓存中超过 24 小时且非在用的文件，不再启动时自动清理；配置备份去重只处理合法且字节完全相同的控制台备份，至少保留最新 3 份。两种删除动作都必须先预演，再确认本次清单；预演后变化的对象跳过。详细范围和令牌规则见[内置运维](<运维接口.md>)。

### 5.1 叫醒它

- **群里**：必须被叫才理 —— @ 它、引用它的消息、叫到唤醒词（默认「大肥鱼」）。
- **私聊**：永远算被叫。
- 唤醒词在「**唤醒**」页维护（输入框 + 添加按钮，点 × 删）；**人设文件自带的词也生效**（删它会改人设文件，控制台会提示）。

### 5.2 聊天 / 发图 / 长文

- 直接说话即可；太长会自动分段或打成一张合并转发卡片（「消息设置」页调阈值）。
- **等对方说完再答**（「消息设置 → 合批等待」，默认 5 秒）：私聊连发几条会合并成一整轮再回答；群里被 @ 后，等待期内的其他聊天/补发的正文会并进这一轮。等待期内群里又来一次 @，当前这轮立即开始回答、新 @ 另起一轮（机器人正在回答时新消息直接排队）。
- **识别合批内图片**（「消息设置」，默认开）：本轮每条消息里的图片按消息顺序、图片顺序加载并映射，群里等待期间并入的非唤醒消息也包括在内；单图失败保留占位，其余图片继续。关闭后只加载首条消息的图片，后续仅留占位。引用图沿用各事件原来的处理。多图会增加视觉输入成本，但开关不改变唤醒、等待或排队规则。
- **群上文图片**（「群聊 → 上文图片入站」，默认关）：开 = 群友先发的图会随「入站条数上限」窗口一起进模型（表情包不算），它不会再答「图没送到」；数量与入站条数同步封顶，长边缩到 768px 省 token。窗口里没图 = 零开销。
- 让它发本地图片：图片放到**数据目录或系统临时目录**（白名单在「其他」页），然后叫它发。只发图，**不能发文件**（QQ 侧限制）。

### 5.3 收文件

- 默认 **「被叫到时才下」**：群里没人叫它的文件不落盘，不占磁盘。想全收就在「文件与图片」页改成「过门禁的消息都下」。
- 限制：单个文件默认 **20MB**、单条消息最多 **5 个**、落盘文件保留 **7 天**后启动时自动清理。
- 落盘目录在「其他」页「文件」组；收到的文件路径会写进它的提示里。
- 注意：QQ 线是纯聊天 preset（没有文件/终端工具），它知道文件在哪但默认读不了文件内容；需要读内容要另配工具或让它把文件发到别处处理。

### 5.4 生图 / 图生图

1. 「**生图**」页填 **协议 / API 地址（到 /v1）/ 模型 / API Key**（也可用环境变量 `QQ_IMAGEGEN_*`，环境变量优先）。
2. 协议怎么选：中转站支持 `/images/generations` → 选 **OpenAI 兼容 /images/***；只给 chat 出图 → 选 **OpenAI 兼容 chat/completions**。同步/异步（提交后回任务号的）中转站**都能用**，不用另选协议：只回 `task_id` 时会自动轮询取图，超时不超过「生图超时」。
3. 用法：直接说「画一只…」；改图就发图/引用图再说「改成…」。**质量/尺寸档位默认关闭**（当前上游不接收 `quality` / `size`）：不指定画质和尺寸，由上游按自己的默认出图；想用「2K、16:9、高质量」这类档位，先到「生图」页打开「质量/尺寸档位」—— 打开后工具分别传 `resolution:"2k"`、`aspect_ratio:"16:9"`、`quality:"high"`，默认 **1K + low**，明确要画质/精细用 `medium`、明确要高质量/高清才用 `high`（2K 不自动升档）；比例仅支持 `16:9 / 9:16 / 3:4 / 4:3 / 1:1 / 21:9`。档位关闭时不指定比例就由上游决定，工具参数传了也不生效。

   档位打开时的比例/尺寸表：

   | 比例 | 1K | 2K |
   |---|---|---|
   | 1:1 | 1024×1024 | 2048×2048 |
   | 16:9 | 1536×864 | 3072×1728 |
   | 9:16 | 864×1536 | 1728×3072 |
   | 3:4 | 864×1152 | 1728×2304 |
   | 4:3 | 1152×864 | 2304×1728 |
   | 21:9 | 1568×672 | 3136×1344 |

   这里1K/2K是预设档名，2K将同一比例的1K宽高各翻倍；全部保持精确比例且两边是16的倍数。
4. 规则：普通用户共享全局冷却（默认60秒），主人发起的生图/改图自动免冷却，身份由本轮入站消息确定，不按目标群或模型自报判断；混合成员合批不享受豁免。主人请求仍更新共享冷却，且所有人同一时间只执行一个生图任务。失败它会自己说一句就结束（**不会自动重试**，避免重复扣费）；「在画了」同一会话30秒内只说一次。

> **额外请求字段**：不同平台的生图接口参数不一样（比如 sensenova／商汤默认给图加水印、要关得传 `watermark: false`；有的中转站还有 `quality`／`style`）。控制台「生图」页的「额外请求字段（JSON）」就是给这个用的：填 `{"watermark": false}` 关水印；留空不追加平台字段。档位打开时 `quality` 和 `size` 由工具选择优先，不能在这里覆盖；档位关闭时工具不发这两个字段，这里写的同名键会原样上送。写错 JSON 会直接报错、不会把图发出去。

**本机图片怎么找**：QQ 线没有文件工具，它看不到本机目录。要它用本机的图（角色参考图、之前生成的图、群友发来的图）当参考时，它自己会先调 `list_images` 查清单（角色参考图 / QQ 工作区 / QQ 发来的文件 / 头像缓存，带尺寸），再挑一张传给 `generate_image`。你也可以直接说文件名。

### 5.5 头像

让它「看看/用某某的头像画…」——它会按 QQ 号取公开头像缓存到数据目录（缓存时长在「其他」页「头像」组），直接当图生图参考图用。

### 5.6 表情包

**默认是「只读」**：库开着、能挑图发，但**不收新图、不写索引**（「收表情（会写索引）」开关默认关）。

要用采集就打开「表情包 → 收表情（会写索引）」：开了才会把群里的新表情收进库、更新 `index.json`、记录使用次数。控制台「表情包」页顶部会显示当前库有多少张、多少张带标签。

⚠️ 索引是插件内存里的副本，**运行中直接改 `index.json` 会被写回覆盖**。手工搬实例/改索引时先停 DSH 再操作；控制台修改库目录则在串行任务边界切库，已排队任务保留原目的库（见 [热改说明](配置参考.md#热改说明)）。不需要采集时保持采集开关关闭。

采集规则：哈希去重、默认跳过 GIF、单张 1KB~2MB、上限 200 张（满了跳过新图）；回话时按概率提醒它「顺手带一张」（**群聊和私聊都会提醒**），一轮最多 1 张。

提醒出现后它会把 `sticker:"关键词"` 直接塞进「发正文」那次工具调用里（比单独调一次 `send_sticker` 省一步，实际发出率明显更高）；如果这一轮它还是忘了，工具的返回里会再轻推一次（最多两次）。

### 5.7 入群欢迎

1. 「**群聊**」页每张群卡片勾「允许入群欢迎」（或在「入群欢迎」页填群号；填 `*` = 所有群）。
2. 「**入群欢迎**」页写欢迎语：固定句池（零 token）或模型现写；可放图片池、调延迟（秒）/同人同群冷却（分钟），点「测试发送」预览。模型欢迎只在该欢迎轮成功发送后撤销固定兜底，发送前装饰不算成功；卸载回收延迟/兜底计时器。

### 5.8 群记忆

群和私聊各一篇：群是 `<数据目录>/qq-memory/<群号>.md`，私聊是 `<数据目录>/qq-memory/private/<QQ号>.md`（分目录防撞名）。控制台「群记忆」页能看、能改；保存前备份旧版到 `.revisions/` 并按配置清理。左栏 🔔/🔕 单独开关该会话记忆：关掉后不读、不积累，自动和手动都跳过，已有内容仍可查看、编辑或删除。🗑 将正文与历史版本一起移到 `.trash/…-时间戳/`（可手动恢复），不退群、不改群配置。

**只按日整理实际互动**：每天 `04:00`、时区 `Asia/Shanghai`（可改），只处理本机器人真正参与的群聊/私聊互动，不把旁观闲聊写成共同经历；首次启用不回灌启动前的旧聊天。逐会话维护稳定记忆、近期经历（默认保留 14 天）和未完成约定。整理时按 60 条/8000 字切成小块逐段回忆，尽量勤记；超过 3 天的旧条目会按概率随机淡忘（约定不丢）。聊天输入不设条数/字数上限；上限只约束**记忆文件本体**（`maxBytes`，默认 24000 字节）。整理结果超限会自动退回重做一次，仍超才留待办，不会为了塞进去而丢弃内容。

主面板可改自动处理开关、每日时间和时区。「记忆整理专用模型（后台任务）」可按提供商分组搜索当前 DSH 宿主列出的模型，也可选择「沿用 DSH 默认模型」。保存时提供商和模型成对提交，仅影响记忆整理，不改变 QQ 聊天模型或 DSH 默认模型。目录暂不可读取时可手填 ID；如果宿主不支持后台专用模型，手填也不会绕过运行时校验。旧选择不在目录时会保留并标注不可用。列出不代表额度或连通性正常，调用失败不会静默换模型。

关掉自动处理仍能点「立即处理」（会调用模型，不向 QQ 发消息）。页面显示上轮待办（不含尚未扫描的新互动）、上次结果、最近更新会话、下次时间和最近错误；保留天数、历史版本等工具配置在「高级配置」。旧版「间隔积累」模式已移除，控制台不再提供该选项；旧配置里残留的相关键会被忽略。过长的记忆保存在 `.revisions/`、处理回执目前不会自动清理。键名见[配置参考 §五](<配置参考.md#group-memoryorder-90群记忆>)。

注意：① 全局「群记忆」开关只停读取，不停后台处理；停自动处理用自动处理开关，停某个会话的读取与处理用 🔔/🔕。② 手改保存期间如果后台已更新文件，会提示冲突；先刷新看清再保存。可在「稳定记忆 / 近期记忆 / 约定与承诺」三个标题下按 `- [编号] 文本` 编辑；保存时按正文重新生成页脚、自动补齐缺失分节，不需要手写元数据。控制台读取只显示可读正文（隐藏页脚与更新时间）。处理进度单独存放，不写进记忆文件。③ 有意义的共同虚构经历可记为虚构经历，不当现实事实；纯玩笑、角色设定也不能变成人物现实画像。

### 5.9 链接解析（可选）

默认关。要开需要自己跑一个解析侧车（默认 `127.0.0.1:3972`），在「链接解析」页填地址并打开开关。
> 侧车要实现什么接口（`POST /parse` 的请求/响应格式）、需要装 ffmpeg 与下载器等，见仓库 README 的「可选：解析侧车」一节。

- 链接一出现就解析，**不用 @**；发媒体之外，如果这条同时还在跟它说话，会继续交给模型回一句。
- **视频类会拆条发**：QQ 客户端把视频当独立消息，所以视频单独一条、说明文字（标题/作者/时长）另起一条；图文/图集仍是「说明 + 图片」一条。这是协议端的硬限制（SnowLuma 等严格实现会直接拒绝混发）。
- 失败一律降级：侧车没起 / 超时 / 媒体太大 → 只在日志记一句，消息照旧当普通消息处理（不会把话吞掉）。

### 5.10 主动接话（可选）

「**主动接话**」页统一管理群聊和私聊：开总开关后，群目标仍在「**群聊**」页逐群勾「允许主动接话」；私聊目标在同一主动接话页逐个输入 QQ，点「＋」或回车添加为标签，点「×」移除；自动去重，错误号码当场提示。名单默认空，删空就停止私聊主动，不会主动联系全部好友。

群聊和私聊只用一套随机间隔：正常默认在 **1–4 小时**抽下一次机会，主动发出后没有回应则改抽 **4–10 小时**；持续未回逐步扩大为 8–20、12–24 小时，之后保持 12–24 小时随机窗（默认上限 24 小时），不变成每天固定整点签到。正常最短/最长、未回最短/最长、退避上限都在同页相邻五项中修改，单位小时，支持 0.5。最短不能大于最长；需要提高最短先提高最长，需要提高窗上界超过退避上限则先提高上限。修改间隔或免打扰策略会重新安排一次，刷新页面不会重抽。没有想说的可以不发，正在聊天或合批等待时不抢话。

内容依当前人设和原会话上下文，可以分享小事、关心、吐槽、接旧话或按已建立关系亲近，不固定抽取风格模板，也不因主动功能自动把普通好友变成伴侣。记忆按每个会话原来的开关读取，不跨线取材。

总开关关闭时群私聊都停；关闭「冷场找话」也暂停私聊定时找话，群有新消息的话题候选仍遵守同一随机机会。旧每小时次数、群/私聊独立间隔与快速档位按钮已被这一套随机窗替代。每个会话的下次机会和未回复次数持久保存到 `<数据目录>/state/proactive.json`，旧私聊状态迁入其中；重启不会清零或批量补发。私聊真人新消息算回应；群里只有明确叫它、@它或引用它等指向机器人的互动才算回应，**普通群发言不是对它的回应**，不能重置未回退避。现有「连续对话」仍只用于群，参数独立，不自动扩展到私聊。

默认**北京时间23:00–08:00免打扰**：这期间群主动接话、冷场找话、群续聊与私聊主动都暂停；你主动发消息仍正常回复。夜间跳过的机会不排队，早上不会一到8点集中问候；仍按机会间隔和退避判断。发送前会复查时间，生成途中跨入免打扰的主动消息、后续拆条与媒体也会被拦下。可在同页「免打扰」展开修改开关、起止时间与时区，起止相同代表全天免打扰。

### 5.10.1 消息监测：匹配消息并附加处理指令

在「消息监测」页点「添加规则」，填写监听内容、匹配方式、生效群聊和附加指令，保存后生效；每条可启停、删除、上移/下移调整优先级。总开关可在本页或子插件页关闭。只监测明确填写的群，群列表为空不生效，不自动覆盖所有群；本版不提供私聊规则。

- **包含关键词**：消息正文包含监听文本即匹配；不使用正则、区分大小写。
- **整条匹配**：消息正文去首尾空白后与监听文本完全一致。例如监听`#sl`，` #sl `命中，`谁发一下#sl`不命中。
- **附加指令**：例如“该消息出现时，艾特罗伦斯”。指令以控制台监测标记附加，不伪装成发送者原话；模型沿用原会话、人设与现有发送工具处理。群名片可能重名或变化，@重要对象建议在指令中明确正确号码，不猜不存在的人。
- **首条匹配**：按规则顺序选首条，不叠加互相冲突的指令；首条处于冷却时不跳到后面的规则。默认每条规则、每个群30秒冷却，可修改；重复触发不会延长冷却。
- **原链路不复制**：先门禁，再监测匹配，沿用合批/忙碌排队；已被@或普通唤醒也只进一轮。合批后的指令标明对应消息ID。普通群友命中不会变主人，屏蔽/黑白名单仍有效；已被命令等截获的消息不再进入监测。
- **不属于主动找话**：监测是人类消息触发，不受小时随机机会与主动免打扰限制；正常队列与发送限制仍生效。机器人自己的消息和notice不触发，避免循环。

「测试匹配」输入群号和文字，检查已保存规则的首条匹配及附加指令，不调用模型、不发QQ、不占冷却；未保存草稿不参与。协议端若吞掉`#sl`等命令不再上报，插件看不到也无法监测，需在协议端确认消息透传。模型执行有语境与工具能力限制，本功能不是保证固定回复的确定性自动化。

### 5.11 权限与门禁

- **主人 QQ**：主人私聊豁免脱敏、群里「主人指令」、配置类命令都按它认。
- **门禁**（「其他」页，或直接在群卡片上改，同一份配置）：
  - 屏蔽群：整群不理；
  - 群内黑名单：这些人发的不回、不留档，优先级最高；
  - 群内白名单：该群只有名单内 + 主人能叫得动；
  - 全局允许用户：所有群 + 私聊一起限制（空 = 不限制）。
- **可选：QQ 线工具门**：如果桌面/profile 里装了全局工具插件（dsh-ops / agent-team 等），可加装 `dsh-onebot-qq-opsgate` 把 `ops_*`、团队、MCP 资源类工具从 QQ 会话里摘掉（只影响 QQ 线）；装法见 [安装与卸载](安装与卸载.md)。

**斜杠命令**（零 token；`/help` 任何人可用，其余仅主人）：

| 命令 | 权限 | 说明 |
|---|---|---|
| `/help` | 任何人 | 列出已注册命令（动态生成） |
| `/status` | 主人 | 连接 / 会话 / 插件状态 |
| `/reset` | 主人 | 重置**当前**这条 QQ 线会话 |
| `/resetall confirm` | 主人 | 重置所有 QQ 线会话（必须带 `confirm`） |
| `/cancel` | 主人 | 中止当前正在进行的回复 |
| `/quota` | 主人 | 查模型线路额度（需实例接入额度数据源，没有会明确提示） |
| `/history [N]` | 主人 | 拉本群最近 N 条记录进上下文（默认 50、上限 500；≈2.9K→7.6K token） |

---

## 6. 人设怎么写

### 6.1 一套人设 = 三个文件

| 文件 | 内容 |
|---|---|
| `<名字>.md` | **是谁、怎么说话**：身份、口头禅、必守、情绪反应、示范对话 |
| `<名字>.lines.txt` | **句池**：被戳/被叫/生图时的短句，一行一句，按 `# 节名` 分节 |
| `<名字>.wake.txt` | **唤醒词**：一行一个，群里说到就唤醒（不用 @） |

放在数据目录的 `personas/` 下；控制台「总览」点人设即可切换，或命令行：

```bash
node bin/dsh-onebot-qq.mjs persona use 蓝色大肥鱼
```

### 6.2 最省事的写法：让 AI 照模板写

模板随包提供，首次启动会投递到 `personas/_模板.md`。直接跟 DSH 说：

> 「照 `personas/_模板.md` 给我写一套人设，叫 XXX，性格是……」

### 6.3 写什么 / 不写什么

- **写**：身份、口吻、必守规矩（像真人那样说话）、几句示范对话。
- **不写**：工具怎么调、系统纪律、怎么收文件——那些是 DSH 和插件的事，不随人设变。

### 6.4 句池格式（`<名字>.lines.txt`）

```
## poke
戳我干嘛~
## callAck
在呢在呢
## imageBusy
画不过来啦，等会儿
```

节名用 `## ` 开头（`#` 开头是注释）；可用节名：`poke`（被戳）、`callAck`（被叫）、`imageAck` / `imageBusy` / `imageFail`（生图相关）等；没有的节会回落到 `_default.lines.txt` 或内置兜底，不会哑火。

### 6.5 唤醒词注意

一行一个（也支持逗号分隔）；**别放太泛的词**（比如单独一个「鱼」）——每命中一次就是一轮模型调用。自带唤醒词可以在控制台「唤醒」页点 × 删除（会改人设文件）。

---

## 7. 出问题先看这几条

> 完整排障手册见 [排错](排错.md)：先在控制台「运维」点 **🩺 一键诊断**，拿到脱敏报告再对号入座。

| 现象 | 先检查 |
|---|---|
| 收不到消息 / 不回 | 协议端 WS+HTTP 地址与 token（SnowLuma 两个都要）、「群聊」页是否屏蔽了该群、群里是否真的叫了它 |
| 状态一直断开 | 协议端里 QQ 是否在线（SnowLuma 看 `get_status.good`，`false` = 发得出收不进）；「运维 → 重新连接 OneBot」→「一键诊断」 |
| 生图报「未配置凭据」 | 「生图」页协议/地址/模型/Key；环境变量是否覆盖成空 |
| 生图失败后没再试 | 设计如此：失败只回一句，不自动重试（防重复扣费） |
| 文件没下载 | 默认「被叫才下」；确认这条消息是否叫到它，或去「文件与图片」页改策略 |
| 想卸载/回滚 | 见 [安装与卸载 §七、§八](安装与卸载.md)（备份文件形如 `config.json.bak-console-*`） |

---

## 8. 还需要的文档

全部文档入口见 [功能手册总览](README.md)（按「我要做什么」排）。常用直达：安装 / 升级 / 卸载 → [安装与卸载](安装与卸载.md)；配置键与默认值 → [配置参考](配置参考.md)；故障 → [排错](排错.md)；Windows → [Windows 安装](Windows安装.md)；想加功能 / 改代码 → [开发指南](开发指南.md)。