# dsh-QQbot 用户手册（完整版）

> 一句话概括：**让一个 AI 助手住进你的 QQ 群和私聊里**——它能看群消息、回答问题、执行工具、记事情、定时提醒、发图和文件。
>
> 这本手册写给「要用它的人」，不要求你懂代码。读完你会知道：它有哪些本事、每一步怎么操作、每个开关拧下去会发生什么、出问题怎么排查。
> 想了解安装构建/源码结构，请看 [README.md](./README.md)。

---

## 怎么读这本手册

| 如果你…… | 直接看 |
|---|---|
| 第一次用，想马上跑起来 | [第 1 章 五分钟上手](#1-五分钟上手) |
| 想知道它到底能干什么 | [第 2 章 一次消息的一生](#2-一次消息的一生先建立整体印象)、[第 3 章 功能详解](#3-功能详解) |
| 想知道有哪些命令 / 怎么用自然语言指挥它 | [第 4 章 聊天命令大全](#4-聊天命令大全)、[第 5 章 让 AI 帮你干活](#5-让-ai-帮你干活自然语言就够了) |
| 想在图形界面里管定时消息（文件工作台 / 设置页） | [3.6 定时消息的管理界面](#36-定时消息的管理界面设置页与文件工作台) |
| 要拧参数、调性格 | [第 6 章 设置页导览](#6-设置页导览)、[第 7 章 配置参数全解](#7-配置参数全解)、[第 8 章 参数关联性地图](#8-参数关联性地图) |
| 想照抄一套现成配置 | [第 10 章 场景配方](#10-场景配方照抄即可) |
| 出问题了 | [第 11 章 常见问题与排查](#11-常见问题与排查) |

---

## 1. 五分钟上手

### 1.1 先准备三样东西（只做一次）

1. **一个 QQ 官方机器人**：去 [QQ 开放平台](https://q.qq.com) 创建，拿到 `AppID` 和 `AppSecret`（相当于机器人的账号密码）。
2. **出口 IP 白名单**：在开放平台的开发设置里填好你这台机器的公网出口 IP。少了这一步，机器人**收得到消息但发不出回复**——这是新手最常见的坑。
3. **本机装好 dsh**：插件跑在 dsh（DeepSeek Harness）里。

> 消息接收走 WebSocket 长连接，是机器人**主动往外连** QQ 服务器，所以**不需要公网 IP、不需要域名、不需要配回调地址**。这也是它在自己电脑上就能跑的原因。

### 1.2 安装插件

```sh
dsh plugin --profile web add <本目录或 git 地址>
```

装好启动 dsh，左侧设置里会多出一个「**QQ 机器人**」。

> 如果装了 **文件工作台**（dsh-file-workbench）扩展，左侧 Activity Bar 会自动出现一个「**QQ 定时消息**」图标（时钟）——点开就是定时任务管理面板，用法见 [3.6](#36-定时消息的管理界面设置页与文件工作台)。无需任何开关，插件加载后自动注册；没装文件工作台时，也能在「设置 → QQ 机器人 → 机器人详情 → 定时消息」里管。

### 1.3 添加第一个机器人

1. 打开 **设置 → QQ 机器人**；
2. 点「**添加机器人**」；
3. 两种方式任选：
   - **扫码登录（推荐）**：手机 QQ 扫页面上的二维码，凭据由官方下发并自动保存，不用手抄密钥；
   - **手动填写**：填 AppID / AppSecret 保存。
4. 保存后机器人会**立刻连上**（热生效，不用重启 dsh）。列表卡片上能看到连接状态。

### 1.4 让它开口说话

- **群里用**：把机器人拉进群，**@ 它 + 问题**。
- **私聊用**：加机器人为好友，直接说话。
- **验证成功**：它回了你一句话，就说明整条链路通了。

> 试一句：`@机器人 用一句话介绍你自己`
> 再试一句：`@机器人 帮我记住：这个群每周五下午三点开会`（它会自动写进长期记忆）
> 再试一句：`@机器人 每天早上九点提醒大家写日报`（它会自动建定时任务）

---

## 2. 一次消息的一生（先建立整体印象）

理解这条流水线，后面所有配置你都能猜到它在哪一环起作用。

```
                         ┌──────────────── 群聊 ────────────────┐
你在 QQ 里发一句话  ───▶ │ ① 是不是 @ 我？                        │
                        │    是 → 直接处理（可以执行工具）         │
                        │    否 → 进入价值评分，够份量才插话       │
                        └───────────────┬───────────────────────┘
                         ┌──────────────┴────── 单聊 ───────────┐
                        │  直接处理（可以执行工具）                │
                        └──────────────┬────────────────────────┘
                                       ▼
                        ② 是命令吗？（以 / 开头）
                             是 → 直接答复，不进 AI（快）
                             否 → 继续
                                       ▼
                        ③ 组装上下文：历史群聊片段 + 长期记忆 + 权限设定 + 附件内容
                                       ▼
                        ④ 交给 DSH 会话（AI 思考，可调用工具）
                                       ▼
                        ⑤ 净化出站内容（去掉内部提示词/思考过程） → 分片 → 发送
                                       ▼
                        ⑥ 发送成功？ 否 → 剩余内容进「投递出箱」，每 60 秒重投一次
                                       ▼
                        ⑦ 全程写归档日志（~/.dsh/qqbot/archive/），事后可查
```

**记住三句话就够了**：

- **@ = 叫它干活**（能用工具）；**不 @ = 它自己判断该不该接话**（只聊天，不动工具）；
- **以 `/` 开头的是命令**，秒回，不走 AI；
- **发送失败不会丢**：会进「投递出箱」自动重试。

---

## 3. 功能详解

下面每节按「**是什么 → 有什么用 → 怎么用 → 举例 → 小提示**」组织。

### 3.1 三种跟它说话的方式

#### ① 群里 @ 它（最常用）

- **触发**：@ 机器人 + 内容。
- **行为**：必定回复；**可以执行工具**（查东西、跑脚本、发文件等）。
- **上下文**：默认附带最近 10 条群聊记录（`atContextMessages`，可调 0–50，0 = 不带），所以它知道你们刚才在聊什么。

```
你：@机器人 刚才那个报错是什么意思？
AI：你们 3 分钟前贴的日志里，第 4 行是 connect timeout……
```

> 小提示：附带的只是**文本**历史，不含历史消息里的图片/文件（当前消息自带的附件会看）。

#### ② 群里不 @ 它（它自己插话）

- **触发**：群里任何一条普通消息。
- **行为**：先做**价值评分**（0–10），达到 `valueThreshold`（默认 5）才回复；群聊与单聊能力完全一致，**同样可以调用工具、读写文件、执行命令**，用的是和 @/单聊相同的 Agent Preset。
- **用途**：让它在群里像个安静的群友，只在值得说话时开口，而不是每句都接——但它开口后照样能干活。

> 想让它更爱说话 → 把 `valueThreshold` 调低（如 3）；
> 想让它闭嘴只答 @ → 把 `groupFullReply` 关掉，或把阈值调到 9。

**@ 判定很聪明**：即使 QQ 平台的 @ 标记没传过来，它也会根据消息里的 `<@id>` 判断，并且**记住自己在这个群的 openid**。多个机器人同群时，能分清你 @ 的是哪一台。

#### ③ 私聊

- **触发**：给它发单聊消息（`allowC2c` 默认开启）。
- **行为**：直接进会话，可用工具；支持「正在输入」状态、语音回复（TTS）等单聊专属能力。

---

### 3.2 会话：一个群 = 一段连续的对话

同一个群（或同一个人）会**复用同一个会话**，所以它能记住刚才聊到哪——这是它有「上下文连贯」感觉的原因。

想翻篇就发：

```
/new
```

它会解绑当前会话，下一条消息开一个全新的。注意：**长期记忆不受影响**（记忆是单独存的，见下节）。

其他：

```
/session     # 看看当前绑的是哪个会话
/stop        # 它正在长任务里转圈？发这个让它停下
/steer 简短点 # 它正在干活时追加要求（不用等它做完）
```

---

### 3.3 长期记忆：跨会话的「小本子」

- **是什么**：每个群/单聊一个 Markdown 文件，放在 `~/.dsh/qqbot/memory/`。**人可以直接打开编辑**。
- **有什么用**：跨 `/new`、跨重启保留重要信息——项目背景、团队约定、你的偏好。
- **怎么写入**：不用手动——对话里说「记住……」它就自动记；也可以直接编辑 `~/.dsh/qqbot/memory/` 里对应的 `.md` 文件。
- **怎么查看/清空**：

```
/记忆          # 查看本聊天记住了什么
/清空记忆      # 清空本聊天的记忆
```

- **记录风格**：只存「内容本身」，不带日期、不带 emoji、不带 markdown 装饰——所以它读起来很干净，也不容易被模型学坏格式。

> 小提示：它是**按聊天隔离**的——A 群的记忆不会跑到 B 群。想临时关掉：bots.json 里设 `"memoryEnabled": false`。

---

### 3.4 看图、读文件、听语音

| 能力 | 默认 | 说明 |
|---|---|---|
| 入站多模态 `multimodalInbound` | 开 | 你发的图片/文件/语音会进上下文，视觉模型能看图 |
| 文件内容识别 `fileIngestion` | 开 | 文本类文件（txt/md/json/csv/代码等，≤1MB）自动下载并把正文给它读；二进制文件（docx/pdf 等）只报文件名 |
| 语音转写 `voiceTranscription` | `note` | 用它自带的平台转写文本，零配置 |
| 单聊语音回复 `ttsReply` | 关 | 开启后它在私聊里用语音回答你 |
| 正在输入 `typingIndicator` | 开 | 私聊时你看到「正在输入…」，回答发出就消失（QQ 只支持单聊） |

**语音的五档**（在 bots.json 里改）：

| 档位 | 需要额外配置 | 适合什么时候 |
|---|---|---|
| `off` | 无 | 不想处理语音 |
| `note`（默认） | 无 | 用平台自带转写，零成本 |
| `download` | 无 | 把音频地址给它，让它自己决定 |
| `asr` | `asrEndpoint` | 你有自己的转写服务 |
| `stt` | `sttBaseUrl` / `sttApiKey` / `sttModel` | 用 OpenAI 兼容接口（如 whisper），失败自动回退平台转写 |

---

### 3.5 定时消息：让它按时主动说话

**基础写法（四种触发）**：

```
/定时 每天 09:00 记得写日报          # 每天九点
/定时 间隔 30 起来动一动             # 每 30 分钟（最小 5 分钟）
/定时 cron 0 9 * * 1-5 站会提醒      # 标准 5 段表达式
/定时 在 2026-09-20 15:00 交周报     # 一次性，到点后自动删除
/定时 查看                           # 列出本聊天的定时任务
/定时 启用 2  /  /定时 禁用 2        # 启用 / 暂停第 2 条
/定时 取消 2                         # 取消第 2 条
```

> **启用不会补发**：重新启用只把任务排到**下一个触发点**，不会补发禁用期间错过的那几次。
> 因此每天 09:00 的任务若在 16:00 重新启用，第一次执行是**第二天 09:00**；
> 命令/设置页会回显「下次运行」时间，可据此确认开关已生效（想立刻看效果请用设置页的「测试」）。

**限定星期**：在 `/定时` 后加「每周X」，支持连续写法与区间。

```
/定时 每周一三五 下午 3:00 提醒交周报
/定时 每周一到周五 09:30 站会
/定时 工作日 09:00 打卡
/定时 周末 10:00 早安
```

**指定执行方式**：加「智能」走 AI 生成，加「脚本」执行命令。

```
/定时 智能 每天 20:00 总结今天群聊的重点
/定时 脚本 每天 08:00 python C:/scripts/report.py
```

**时间写法很宽容**：`09:30`、`9点30`、`下午3点`、`晚上8点`、`9月20日 15:00`、`2026-09-20 15:00` 都能识别（一律按上海时间）。

**更省事的方式——直接说人话**，AI 会自己建：

> 「每周一到周五早上九点半提醒大家站会」
> 「下周三下午三点提醒我交周报」
> 「每天早上八点跑一次那个脚本，把结果发我」

**AI 动态模式（`mode=ai`）**：内容不是一个死句子，而是一条**生成指令**，到点它现场生成再发。
> 例：「**每天早上总结昨天群聊的重点**」——每天的内容都不一样，这才是定时消息真正的威力。

AI 模式下的机器人知道「自己是在执行定时任务」，因此具备**静默能力**：当它判断本次确实没有值得发送的内容（例如昨天群里没聊、数据为空），会直接收手——**不发送、不消耗配额**，把「跳过」记入任务状态而非硬发一条废话。

**脚本模式（`mode=tool`）**：到点执行一条命令（如 `python C:/scripts/report.py`），把结果发到群里。
两种结果处理：

- `resultMode=raw`（默认）：**只发脚本输出本身**，不带任何说明文案、命令行、耗时等附加信息；
- `resultMode=ai`：把输出交给 AI 整理成一段简洁播报再发（输出很长、很技术化时推荐）。

**执行超时（`timeoutMs`）**：命令最长执行时间，默认 **120 秒**，超时会被强制终止。报表、爬取、批量导出等慢脚本可在设置页把「执行超时（秒）」调到最大 **600 秒**。

**环境变量（`env`）**：在设置页「环境变量」里按 `KEY=VALUE` 每行一条填写，会注入到命令进程，脚本用 `os.environ` / `process.env` 读取。适合传 API Key 等敏感值——**比写进命令行更安全**，因为命令行会出现在运行日志里。

**加工指令（`parsePrompt`，配合 `resultMode=ai`）**：不满意默认的「整理成简洁播报」，可以自定义「把数据处理成什么样再发」。
> 例：「只保留上涨的板块，按涨幅排序，每条一行，超过 5 条只发前 3 条」「提取其中的报错行，其余忽略」「翻译成一句话说给非技术同事听」。留空则用内置默认。

**发送门控（`gate`）**：投递前判定「这次值不值得发」，避免定时刷屏。

- `always`（默认）：取到就发；
- `nonempty`：结果为空/无实质内容时跳过；
- `changed`：与上次成功发送的内容一致时跳过（适合「有变化才播报」的行情、告警类任务）。

> 门控跳过同样**不投递、不占配额**，跳过原因会记录到任务上（界面上显示「上次跳过」）。

**任务契约（`goal` / `notifyWhen` / `verify`，ai 与 tool 模式通用）**：把「什么时候该发、发之前要不要再检查」交给语义判断，而不是死板的规则。

- `goal`——**任务目标**：一句话说明这条任务服务于什么判断（如「盯住竞品价格波动」），供 AI 分诊时理解意图；
- `notifyWhen`——**通知条件（自然语言）**：写明什么时候才值得打扰大家（如「只有涨幅超过 5%、或出现异常时才提醒」）。**不满足时本次静默不发、也不占配额**；
- `verify`——**发送前自校验**：开启后投递前再复核一次草稿是否满足上面的目标与通知条件，不达标就不发。tool 模式是**独立模型二次复核**（还能顺带润色），ai 模式是**强化自查**。

> 与门控的区别：`gate` 是机械规则（空不空、变没变），`notifyWhen` 是**语义判断**（"这次到底值不值得说"）。两者可以叠加使用。

> 例：「每天早上跑一次行情脚本，**只有出现涨停才提醒我**，否则别发」→ tool + `resultMode=ai` + `notifyWhen=出现涨停`。

**上限**：每个群/单聊默认 **15 条**（`scheduleMaxPerChat`，bots.json 可调；设 `0` = 不限）。

> 小提示：定时消息走的是**主动消息通道**，会消耗当日主动消息配额（默认 50/天）。排太多提醒时记得看 `/status`。

---

### 3.6 定时消息的管理界面（设置页与文件工作台）

`/定时` 命令适合**快速建一条**；要**看清、改细、批量管**，用图形界面更顺手。两个地方都能管，而且是**同一套界面**：

| 入口 | 怎么进 | 适合 |
|---|---|---|
| **文件工作台** | 装了文件工作台（dsh-file-workbench）扩展后，左侧 Activity Bar 自动出现「**QQ 定时消息**」图标（时钟），点开即是 | 一边写代码一边管；视图宽度自适应 |
| **设置页弹窗** | 设置 → QQ 机器人 → 机器人详情 → **定时消息** → 打开 | 集中配置 |

> 文件工作台入口**无需任何开关**：插件加载后会自动把视图注册进文件工作台的 Activity Bar（文件工作台全局若晚于本插件加载，插件会轮询等待最多约 30 秒）。装了文件工作台就有这个入口；没装则只在设置页里管，功能完全一致。

> **后台任务联动**：装了文件工作台时，定时消息的**新建 / 修改 / 删除 / 启用禁用 / 测试执行**，以及**每次到点的真实发送**（含被发送门控拦下的跳过、执行失败），都会自动登记进文件工作台底部状态栏的「后台任务」面板——点开任务按钮即可看到每次发送的时间、任务摘要与结果（成功 / 跳过原因 / 失败原因），统一可见、可追溯。设置页里操作只有界面内提示，不进任务面板。

**顶部「机器人」下拉**：选「**所有机器人**」看聚合列表；选某个机器人（带 ★ 的是主机器人）则只显示它名下的任务，此时**新增的任务也归它**。旁边是「刷新」。

**列表长什么样**

- 按「**群聊任务**」「**单聊任务**」分成两组，标题右侧是条数；**点标题即可折叠 / 展开**（任务多时很省地方）。
- 每条任务一行，右侧一排操作：

| 按钮 | 作用 |
|---|---|
| **查看** | 打开「执行逻辑详情」——把这条任务到点后的完整链路画成流程图（见下） |
| **测试** | **立刻跑一次**，不用等到触发时刻。它是**真的发一条**（内容会真的发出去），但**不计入主动消息配额**、不影响「下次运行」 |
| **启用 / 禁用** | 暂停或恢复；注意**禁用期间错过的时刻不会补发**（见 3.5） |
| **编辑** | 打开三步式表单修改 |
| **删除** | 红色按钮，与上面几个之间有一道分隔条，防误点 |

- 右上角是「**＋ 新增**」；底部一行汇总 `共 N 条`（设了每聊天上限时显示 `共 N 条 / 上限 M 条`），以及「刷新」。

**「查看」——执行逻辑详情（流程图）**

点「查看」后列表被详情页替换，按这条任务的**实际配置**逐节点画出「到点后怎么走」：

```
触发（每天 09:00 / 每 30 分钟 / cron / 一次性）+ 星期过滤
      ▼
是否启用？ ── 否 ──▶ 直接结束
      ▼ 是
接收对象（群聊 / 单聊 · 会话名）
      ▼
执行内容（直接发送文本 / AI 智能任务 / 执行命令）
      ▼
   〔仅命令任务〕结果处理（原样发 / AI 整理）→ 发送门控（无条件 / 非空 / 变化才发）
      ▼
通知条件（配了才出现）→ 发送前自校验（开了才出现）
      ▼
推送消息（附下次运行时间）
```

- **判断类节点**（是否启用、结果处理、门控、通知条件）用带「?」的卡片和「是 / 否」标记，与普通步骤区分开。
- **没配的环节不会画出来**——看到的节点数就等于实际启用的环节数。
- 点「返回」回到列表。

**新增 / 编辑：三步式表单**

表单按「**① 发送给谁 → ② 什么时候触发 → ③ 到点做什么**」纵向排列，一段一步，不会两列并排挤在一起：

1. **① 发送给谁**：范围（群聊 / 单聊）→ 接收对象。接收对象是从**消息归档**里拉出来的候选，点输入框就能选（群聊显示群 id，单聊显示用户 id 与昵称），也可以直接粘贴 openid。
2. **② 什么时候触发**：触发方式（每天 / 间隔 / cron / 一次性 at）→ 对应参数（时间、分钟数、cron 表达式或具体日期时间）→ **时区**（从下拉里选，**本机时区置顶**；不支持手输，避免写错）→「每天 / 间隔」还能再加一层**星期过滤**（周一~周日点选，或一键「每天 / 工作日 / 周末」）。
3. **③ 到点做什么**：执行方式三选一 —— **直接发送文本** / **AI 智能任务** / **执行命令**；选「执行命令」后，下面依次是命令、环境变量、执行超时、结果处理、发送门控、加工指令；最后是三者通用的**任务契约**（任务目标 / 通知条件 / 发送前自校验）。

> 命令任务还有第二种填法：不写命令，改填「**AI 脚本描述词**」（如「抓取某网页今日价格并输出一行文本」），保存后由 AI 在后台生成脚本。**生成期间任务不执行**；生成完成后自动按计划跑（已过的触发时刻不补跑）。

**界面本身的三点**

- **深色 / 浅色自动跟随**：配色全部走宿主主题令牌，切换宿主主题即时生效，不用重载。
- **跟随宿主语言**：文件工作台与设置页的文案都跟随宿主界面语言（中 / 英）自动切换。
- **面板宽度可拖拽**：布局按**面板实际宽度**自适应——拖窄会自动变紧凑、换行、把操作按钮落到内容下方；拖宽会放大间距。**任何宽度下都不会出现横向滚动条**。

**任务跑失败了怎么看**

命令执行失败时，任务行上会出现红字「上次错误」（含错误原因与命令的 stderr / stdout 输出）。文案过长会被收拢成几行，**点一下即可展开 / 收起全文**。常见原因是脚本路径不对、解释器不存在或权限不足。

> AI 脚本生成失败会显示「脚本生成失败」，此时任务不执行；重新保存描述词可让它重试。

---

### 3.7 主动发消息、发图、发文件、发语音

直接吩咐它，它会用工具发送（**都算主动消息配额**）：

> 「给这个群发一张猫咪图片」
> 「把 report.pdf 发到这个群」
> 「用语音跟大家说晚安」
> 「给张三发条消息，说明天会议改到十点」

群发到所有它见过的群：

```
/广播 今晚八点服务器维护，请提前保存
```

> 广播范围 = **它收到过消息的群**（没见过的群不在列表里）。广播同样消耗配额，配额用完会自动跳过并汇报「成功 N 个，跳过 M 个」。

---

### 3.8 群管理能力

| 能力 | 怎么配 | 效果 |
|---|---|---|
| **敏感词** `bannedWords` | 设置页可编辑 | 群消息（@ 和不 @ 都算）命中即**撤回原消息并跳过回复**；没撤回权限时只拦截回复 |
| **入群欢迎语** `welcomeEnabled` | bots.json | 有人进群/加好友自动打招呼，`{nick}` 会替换成对方昵称 |
| **🗑️ 表情撤回** `reactionRecall` | bots.json | 有人对它发的消息点 🗑️ 表情，它自动撤回那条 |
| **按钮审批** `approvalButtons` | bots.json（默认开） | 它要执行敏感操作时，先发「允许/拒绝」按钮，你点了才继续 |
| **撤回自己刚发的** | 命令 `/撤回` | 撤回本次运行期间它发的最后一条 |

---

### 3.9 对话权限（`/perm`）：给它立规矩

每个机器人有一份「默认权限文本」，会话开始时会作为硬性指令注入，它必须遵守。

```
/perm view                       # 看当前规矩
/perm set 本群禁止讨论客户隐私，遇到这类问题一律拒绝并提醒  # 立规矩
/perm clear                      # 清除
```

**谁能改？** 由 `permissionAdmins`（bots.json）决定：

- **名单为空（默认）= 任何人都能改**（开箱即用）；
- 配了名单 = 只有名单内的人能改；`"*"` = 全部人都能改。

> 权限文件就在 `~/.dsh/qqbot/permissions/<appId>/_default.md`，**直接编辑这个文件一样生效**。

---

### 3.10 多机器人

- 可以同时接入**多个机器人**，各自独立凭据、独立配置、各自同时在线；
- 同群里多台机器人**各自判断、各自回复、互不共享上下文**；
- 回复、定时消息、主动消息都由**来源机器人**发出（不会串台）；
- 设置页可指定「主机器人」：不指定机器人的操作默认作用于它。

> 典型用法：一个「正经干活」的机器人 + 一个「陪聊」的机器人，同群共存，性格不同。

---

### 3.11 安全与隐私

| 防护 | 默认 | 管什么 |
|---|---|---|
| 回复净化 `sanitizeReplies` | 开 | 发出前剥掉模型输出里的 `system-reminder`、`<think>` 等内部块，防止提示词和思考过程泄漏到群里 |
| SSRF 防护 `ssrfGuard` | 开 | 它发图/文件/语音时，拒绝内网地址和保留地址（含 DNS 解析后逐条校验） |
| 本地路径白名单 `localPathWhitelist` | 关 | 开启后它只能发工作区和插件数据目录内的文件 |
| 入站引用隔离 | 始终 | 你引用的历史原文注入上下文时，会标注为「外部未信任数据」 |

---

### 3.12 出问题时它怎么兜底

- **AI 报错会告诉你**：请求失败（余额不足、超时等）时它会回复 `⚠️ AI 回复出错：<原因>`，而不是沉默。同一聊天 60 秒内最多提示一次，不会刷屏。
- **发不出去会重试**：剩余内容进 `outbox.json`，每 60 秒重投一次，最多 5 次。
- **全程有日志**：`~/.dsh/qqbot/archive/` 按天记录收发，排查问题时翻它。

---

## 4. 聊天命令大全

> 命令都以 `/` 开头，**秒回、不消耗 AI**。以 `/` 开头但不是命令的，它会直接提示「未知命令」，不会误当成聊天内容。

| 命令 | 作用 | 例子 |
|---|---|---|
| `/help`、`/菜单` | 显示帮助 | `/help` |
| `/status` | 连接状态、收发计数、**主动消息配额用量**、群缓冲条数 | `/status` |
| `/new` | 开一个全新会话（不影响长期记忆） | `/new` |
| `/session` | 查看当前绑定的会话 id | `/session` |
| `/stop` | 停止当前正在跑的任务 | `/stop` |
| `/steer <指令>` | 给正在跑的任务追加要求 | `/steer 只用三句话回答` |
| `/记忆` | 查看本聊天的长期记忆 | `/记忆` |
| `/清空记忆` | 清空本聊天的长期记忆 | `/清空记忆` |
| `/撤回` | 撤回它最近发出的一条消息（限本次运行期间） | `/撤回` |
| `/广播 <内容>` | 向它见过的所有群群发 | `/广播 今晚维护` |
| `/定时 …` | 定时消息（见 3.5） | `/定时 每天 09:00 早报` |
| `/perm set\|view\|clear` | 对话权限管理 | `/perm view` |

**`/status` 输出怎么读**：

```
机器人: AppID 1020xxxx
凭据: 已配置（store）        ← store=来自保存的凭据；config/env/none 也可出现
工作区: C:\你的工作目录
收消息: 128 · 会话回复: 46 · 主动消息: 12 · 错误: 0
主动消息配额: 今日 12/50     ← 主动消息快用完时会看到
群上下文缓冲: 35 条
```

---

## 5. 让 AI 帮你干活（自然语言就够了）

你不用记工具名，直接说人话，它会挑合适的工具。下面是**它能做的事和你该怎么说**的对照：

| 你想干什么 | 直接这么说 | 它调用的工具 |
|---|---|---|
| 建定时提醒 | 「每天九点提醒我喝水」 | `qqbot_schedule_add` |
| 建智能定时任务 | 「每天早上总结昨天群聊重点」 | `qqbot_schedule_add`（`mode=ai`） |
| 定时任务改成跑脚本 | 「每天早上八点跑 C:/scripts/report.py 把结果发我」 | `qqbot_schedule_add`（`mode=tool`） |
| 看/删定时任务 | 「我们有哪些定时提醒？把第二条删了」 | `qqbot_schedule_list` / `_remove` |
| 改定时任务 | 「把第二条提醒从九点改成十点」 | `qqbot_schedule_update` |
| 暂停/恢复定时任务 | 「把第二条先停了」「恢复第二条」 | `qqbot_schedule_set` |
| 主动发消息 | 「给这个群发一句：会议室换到 302」 | `qqbot_send_message` |
| 发图片 | 「发张猫咪图」 | `qqbot_send_image` |
| 发文件 | 「把 report.pdf 发上来」 | `qqbot_send_file` |
| 发语音 | 「用语音说晚安」 | `qqbot_send_voice` |
| 记事情 | 「记住：这个群每周五下午三点开会」 | `qqbot_memory_add` |
| 查看记忆 | 「你都记住了什么？」 | `qqbot_memory_list` |
| 清空记忆 | 「把记住的东西都忘掉」 | `qqbot_memory_clear` |
| 敏感操作确认 | （它主动发「允许/拒绝」按钮，你点） | `qqbot_request_approval` |

> 小提示：它靠**当前聊天**判断「发给谁」，所以这些话要在目标群里说。在别的会话里说，它会提示「当前会话没有绑定 QQ 聊天」。

---

## 6. 设置页导览

**设置 → QQ 机器人**

1. **机器人列表**
   每张卡片显示：AppID（脱敏）、接入方式、是否主机器人、启用状态、连接状态。
   可操作：**设为主机器人 / 启用·停用 / 删除 / 点进详情**。

2. **添加机器人**
   两个 Tab：**扫码登录**（手机 QQ 扫码，自动落盘）｜**手动填写**（AppID / AppSecret）。

3. **机器人详情**
   - **连接状态**：在线/离线，可点「重试连接」；
   - **运行统计**：收发、回复、主动消息、错误累计（跨重启保留，可「复位」清零）；
   - **行为配置**：工作区、模型、Agent Preset、回复语言、引用方式、@ 上下文条数、双冷却、分片与回复上限、价值阈值、敏感词、主动消息配额等，**改完立即生效**（完整清单见 7.1）；
   - **定时消息**：打开完整的管理界面（与文件工作台**同源、界面一致**）——新增 / 编辑 / 删除 / 启用禁用 / 测试发送 / 查看执行逻辑流程图，默认每个群或单聊 15 条。用法见 [3.6](#36-定时消息的管理界面设置页与文件工作台)；
   - **消息归档**：按天查阅这个机器人收发的每一条消息。**左右两栏**——左边是「归档日期文件」（每天一个，带当天记录条数，可删除某天），右边是当天的记录时间轴：收到（对方说的）、回复（它答的）、主动（定时/广播发的）三类分别标色，左侧蓝色气泡是对方、右侧是它自己；与某条记录所属的会话也会标出来。记录很多时默认只显示最近一批，更早的仍在归档文件里；
   - **按群配置**：给特定群单独覆盖行为。

4. **按群配置（群覆盖）**
   选一个群 → 弹窗里改 → 保存即生效。可以改：群全量回复、价值阈值、@ 上下文条数、双冷却、分片、回复上限、Markdown、敏感词。
   `memoryEnabled` 不在界面上（仅 bots.json），但**你在界面上改别的字段并保存时，它已有的值不会丢**。

---

## 7. 配置参数全解

### 7.0 先搞清楚三件事

1. **配置存哪**：每机器人的配置在 `~/.dsh/qqbot/bots.json`，一个机器人一份。
2. **改完要不要重启**：**不用**，热生效。
3. **凭据优先级**（高 → 低）：
   ```
   secretEnv（DSH 凭据引用，优先级最高）
     > bots.json 里保存的凭据（扫码/手动写入）
     > 环境变量 QQBOT_APP_ID / QQBOT_APP_SECRET（兜底）
   ```

### 7.1 设置页可以直接改的（最常用）

> 下表每一项都能在 **设置 → QQ 机器人 → 机器人详情** 里直接改，改完立即生效。

| 参数 | 默认 | 通俗解释 | 什么时候改 |
|---|---|---|---|
| `workspacePath` | 启动目录 | AI 干活的工作目录 | 要让它读写某个项目目录时（可点「选择…」浏览文件夹） |
| `model` | 部署默认 | 指定用哪个模型，写法 `provider/model` | 要换模型或限制输出长度时 |
| `agentPreset` | `default` | 它的「人格与能力包」 | 想要不同性格/工具集时 |
| `groupFullReply` | `true` | 群里不 @ 它时，它是否可能插话 | 想让它**只在被 @ 时说话** → 关掉 |
| `respondToBots` | `false` | 是否回应别的机器人 | 一般别开（防机器人互相触发刷屏） |
| `valueThreshold` | `5` | 插话门槛（0 最吵 … 10 最安静） | 太吵 → 调高；太安静 → 调低 |
| `atContextMessages` | `10` | @ 它时附带的群聊历史条数 | 上下文太长/太短时调（0 = 不带） |
| `groupCooldownMs` | `60000` | 同一群里两次插话的最小间隔 | 群很热闹、它话太多 → 调大 |
| `senderCooldownMs` | `30000` | 同一个人两次被回复的最小间隔 | 防止它一直追着一个人答 |
| `replyChunkChars` | `1000` | 一条回复最多多少字，超了自动分片 | 想要更长/更短的单条消息时 |
| `maxRepliesPerMessage` | `5` | 一条消息最多回复几次（QQ 官方上限就是 5） | 想少回几条时 |
| `quoteReply` | `at` | 是否带引用卡片：`off` / `at` / `all` | 嫌引用卡片刷屏 → `off` |
| `quoteMaxChars` | `120` | 你引用别人时，原文注入上下文的字数上限 | 引用很长时调大 |
| `replyLocale` | `zh` | 它发给用户的**系统提示文案**语言（`zh` / `en`） | 面向英文用户时 |
| `welcomeMessage` | `欢迎 {nick}！@我即可与我对话。` | 新朋友加好友时的欢迎语，`{nick}` 会被替换 | 想换欢迎语时 |
| `bannedWords` | `[]` | 敏感词（逗号分隔），命中就撤回并跳过回复 | 群里有禁忌话题时 |
| `quotaPerDay` | `50` | 主动消息每天额度（0 = 不限）；**每个机器人独立计数**，互不挤占 | 定时/广播多 → 调大 |
| `groupOverrides` | `{}` | 按群覆盖配置（见 7.4） | 某个群要特殊对待时 |

### 7.2 只在 bots.json 里配的（进阶）

> 这些**设置页看不到**，改 `~/.dsh/qqbot/bots.json` 里对应机器人的 `config` 即可，同样热生效。

| 参数 | 默认 | 通俗解释 |
|---|---|---|
| `permissionPreset` | `default` | 会话权限档位 |
| `allowC2c` | `true` | 是否接受私聊 |
| `allowGroups` / `allowUsers` | `["*"]` | 群 / 用户白名单，`*` = 全部放行 |
| `groupBufferMax` | `50` | 每群缓存多少条消息用于评分和上下文（群特别活跃可调大） |
| `secretEnv` | 空 | AppSecret 的 DSH 凭据引用，**优先级高于明文密钥** |
| `scheduleMaxPerChat` | `15` | 每群/单聊定时消息上限（0 = 不限） |
| `proactiveFallback` | `false` | 被动回复失败时改用主动通道重发（**吃配额**，慎用） |
| `permissionInjection` | `true` | 是否把权限文本注入每次对话 |
| `permissionAdmins` | `[]` | 谁能改权限（空 = 任何人；`"*"` = 全部人） |
| `asrEndpoint` | — | 自定义语音转写接口（`voiceTranscription: "asr"` 时用） |
| `sttBaseUrl` / `sttApiKey` / `sttModel` | — / — / `whisper-1` | OpenAI 兼容转写（`stt` 模式用） |
| `ttsBaseUrl` / `ttsApiKey` / `ttsModel` / `ttsVoice` | — / — / `tts-1` / `alloy` | OpenAI 兼容语音合成（`ttsReply` 开时用） |

### 7.3 开关类（默认已帮你调好，一般不用动）

| 参数 | 默认 | 一句话 |
|---|---|---|
| `archiveEnabled` | 开 | 本地归档收发记录（排障用，建议一直开） |
| `memoryEnabled` | 开 | 长期记忆 |
| `fileIngestion` | 开 | 文本文件自动读内容 |
| `multimodalInbound` | 开 | 图片/附件进上下文（关掉的话 `fileIngestion` 也失效） |
| `markdownReply` | 开 | 优先用 Markdown 排版，被拒自动降级纯文本 |
| `welcomeEnabled` | 开 | 入群欢迎语（配 `welcomeMessage`，`{nick}` 是昵称占位） |
| `reactionRecall` | 开 | 🗑️ 表情撤回它的消息 |
| `sanitizeReplies` | 开 | 出站净化，防内部提示词泄漏 |
| `ssrfGuard` | 开 | 媒体链接防内网探测 |
| `typingIndicator` | 开 | 单聊「正在输入」 |
| `approvalButtons` | 开 | 敏感操作按钮确认 |
| `localPathWhitelist` | 关 | 限制只能发指定目录的文件（想要更严格可开） |
| `ttsReply` | 关 | 单聊语音回复（需配 TTS 服务，见 8.3） |
| `voiceTranscription` | `note` | 语音处理档位（见 3.4） |

### 7.4 按群覆盖（groupOverrides）

给某个群开小灶，覆盖机器人级设置（**群里设的优先**）：

| 可覆盖字段 | 机器人级对应 | 界面能改吗 |
|---|---|---|
| `groupFullReply` | 同名 | ✅ |
| `valueThreshold` | 同名（0–10） | ✅ |
| `atContextMessages` | 同名（0–50） | ✅ |
| `groupCooldownMs` / `senderCooldownMs` | 同名（0–30 分钟） | ✅ |
| `replyChunkChars` | 同名（200–4000） | ✅ |
| `maxRepliesPerMessage` | 同名（1–5） | ✅ |
| `markdownReply` | 同名 | ✅ |
| `bannedWords` | 同名（**叠加**：机器人级 + 群级同时生效） | ✅ |
| `memoryEnabled` | 同名 | ❌ 仅 bots.json（已有值不会被界面保存冲掉） |

> 数值越界会自动夹到合法范围，填错不会出事。

### 7.5 界面语言与回复语言（两套独立的 i18n）

这个插件有**两套彻底独立**的翻译表，互不影响：

| | 管什么 | 表在哪 | 谁决定语言 |
|---|---|---|---|
| **界面文案** | 设置页与文件工作台里所有按钮、标签、提示 | `src/client/i18n/dict.ts` | 跟随宿主 IDE 语言（自动） |
| **回复文案** | 它发到 QQ 里的系统提示（`/status`、`/定时` 等回显） | `src/shared/reply-i18n/dict.ts` | 每个机器人的 `replyLocale` |

两套表都是 **`cn` / `en` 两张独立字典，键为字段名**（如 `schedule.createdDaily`），代码里按字段名取值：

```ts
// 界面侧
import { t, fmt } from "./i18n/index.js";
t("common.cancel");                          // → "取消" / "Cancel"
fmt("sched.totalCount", 3);                  // → "共 3 条" / "3 in total"

// 回复侧（宿主发给 QQ 用户的文案）
import { tr } from "../../shared/reply-i18n.js";
tr("en", "schedule.createdDaily", "09:00", "喝水");
// → 'Scheduled: daily at 09:00 sending "喝水"'
```

要点：

- **字段名是唯一契约**。`cn` 和 `en` 的字段名集合必须完全一致，脚本会卡这一点。
- **插值用位置参数** `{0}` `{1}`，不再靠正则去猜中文串里的数字。两语言的占位符数量也必须一致。
- **未命中的字段名原样返回**，绝不因为漏翻而丢信息。
- **对用户可见的聊天内容（群友说的话、AI 生成的内容）不翻译**——那是数据，不是文案。
- **文件工作台视图会自行订阅语言切换**：在视图开着的时候切换界面语言，文案即时刷新，不需要重载或重启。

改文案只改字典文件；新增文案记得两张表都加。

---

## 8. 参数关联性地图

参数不是孤立的，拧一个动一串。下面是最常见的 8 组关系。

### 8.1 人格映射：谁在说话？

```
@ 消息 / 私聊 / 群聊不 @ 的消息  ──▶ agentPreset（统一人格，均能执行工具）
权限：permissionPreset（会话权限档）＋ /perm 文本（注入 prompt 顶部）
```

群聊与私聊现已能力完全一致：无论 @、单聊、还是群里不 @ 的闲聊，都走同一套 `agentPreset`，都可以调用工具、读写文件、执行命令。

### 8.2 群聊插话的四道闸门

```
消息 ─▶ ① groupFullReply 总开关 ─▶ ② valueThreshold 评分 ─▶ ③ 双冷却 ─▶ ④ 分片/条数上限 ─▶ 发出
        关=只有@才回                 0最吵…10最安静          同群 + 同人，各自计时       replyChunkChars / maxReplies
```

`@ 消息` **跳过①②**，但仍受③④约束。

### 8.3 语音相关参数一键对照

| 想实现 | 需要设置 |
|---|---|
| 听懂语音（零配置） | `voiceTranscription: "note"`（默认） |
| 听懂语音（自建服务） | `voiceTranscription: "stt"` + `sttBaseUrl` + `sttApiKey` + `sttModel` |
| 听懂语音（自定义接口） | `voiceTranscription: "asr"` + `asrEndpoint` |
| 私聊用语音回答我 | `ttsReply: true` + `ttsBaseUrl` + `ttsApiKey`（`ttsModel` / `ttsVoice` 可选） |
| 私聊显示「正在输入」 | `typingIndicator: true` |

### 8.4 主动消息与配额：哪些动作在花钱？

```
每天 50 条（quotaPerDay）会被这些消耗：
  定时消息 · 入群欢迎语 · /广播 · 出箱重投 · AI 主动发消息/图/文件/语音
```

- 用完当天就停，并会告警；`/status` 可查「今日 12/50」。
- `proactiveFallback` 一开，被动失败的回复也会来抢这份配额，**默认关是合理的**。
- 想要不限量：`quotaPerDay: 0`。

### 8.5 引用卡片的行为（实测结论，别乱改）

| 组合 | 结果 |
|---|---|
| 只发引用卡片 | ❌ 手机端同一条内容出现两次 |
| 只发 `msg_id` | ❌ 两端都不显示引用 |
| **引用卡片 + `msg_id` 同时发** | ✅ 有引用且只出现一次（当前做法） |

- 只有平台**明确拒绝**（HTTP 4xx）才降级成普通回复；超时/5xx 不算数，它会走出箱重试而不是重发（重发正是「出现两次」的根源）。
- `quoteMaxChars` 管的是**你引用别人**时原文的截断长度，跟它发出去的卡片无关。

### 8.6 文件链路

```
入站：multimodalInbound（总闸） ─▶ fileIngestion（文本文件读正文）
出站：localPathWhitelist（限制只能发哪些本地文件）
```

关掉 `multimodalInbound`，`fileIngestion` 自然也失效。

### 8.7 权限三层

```
permissionPreset（会话权限档）
      ＋
permissionInjection（开关）→ 注入 _default.md（/perm 管理的内容）到 prompt 顶部
      ＋
permissionAdmins（谁能改 _default.md）
```

### 8.8 安全四件套：关掉会怎样

| 参数 | 管的方向 | 关掉的风险 |
|---|---|---|
| `sanitizeReplies` | 出站文本 | 内部提示词/思考过程可能泄漏到群里 |
| `ssrfGuard` | 出站 URL | 可能被诱导访问内网地址 |
| `localPathWhitelist` | 出站文件 | 可能发送本机任意路径文件 |
| `approvalButtons` | 敏感操作 | 少一道人工确认 |

> 建议：**前两个保持开启**，第三、四个按需。

---

## 9. 存储布局（你的数据都在哪）

```
~/.dsh/qqbot/
├─ bots.json                 机器人库（凭据 + 行为配置）★唯一事实来源，可直接编辑
├─ global.json               全局配置：只有 adminToken
├─ credentials.json          终端登录的兜底凭据（权限 0600）
├─ schedules.json            全部定时消息
├─ outbox.json               投递出箱（失败待重投）
├─ memory/<聊天标识>.md      每个群/单聊的长期记忆（可直接编辑）
├─ archive/archive-YYYY-MM-DD.jsonl   收发归档，按天一个文件
├─ ref-index-<appId>.jsonl   引用索引（每机器人一份）
├─ self-openids/<appId>.json 机器人在各群的 openid 学习记录
├─ permissions/<appId>/_default.md    对话权限文本（可直接编辑）
├─ stats/<appId>.json        运行统计
└─ media/                    语音等媒体临时文件
```

**可以直接手工编辑的**：`bots.json`（改配置）、`memory/*.md`（改记忆）、`permissions/*/_default.md`（改权限）。改完即生效或下个会话生效。

---

## 10. 场景配方（照抄即可）

> 下面都是往 `bots.json` 里对应机器人的 `config` 里写。改完热生效。

### A. 「安静的群助手」——只在被 @ 时说话

```json
{ "groupFullReply": false }
```

### B. 「活跃群友」——偶尔插话，但别刷屏

```json
{ "groupFullReply": true, "valueThreshold": 7, "groupCooldownMs": 180000, "senderCooldownMs": 60000 }
```

### C. 「日报机器人」——每天定时播报

```json
{ "quotaPerDay": 100, "scheduleMaxPerChat": 20 }
```
然后在群里说：「每天早上九点半总结昨天的群聊重点」。

### D. 「严格合规群」——敏感词 + 权限约束

```json
{
  "bannedWords": ["客户名单", "内部价格"],
  "sanitizeReplies": true,
  "ssrfGuard": true,
  "localPathWhitelist": true,
  "approvalButtons": true
}
```
再发一条 `/perm set 本群禁止讨论客户隐私与内部价格，遇到即拒绝并提醒`。

### E. 「多机器人分工」——一个干活一个陪聊

- 机器人甲：`agentPreset` = 全能预设，负责 @ 干活；
- 机器人乙：`valueThreshold` 低一点、冷却稍长，负责日常插话（同样能干活，只是更克制）。

### F. 「超大群」——上下文更足、分片更细

```json
{ "atContextMessages": 20, "groupBufferMax": 100, "replyChunkChars": 700 }
```

---

## 11. 常见问题与排查

按「**症状 → 最可能的原因 → 怎么办**」排列。

| 症状 | 原因 | 怎么办 |
|---|---|---|
| 报 `invalid appid or secret`（100016） | 凭据被别处覆盖 / 填错 | 用扫码重新登录；或改用 `secretEnv` 凭据引用；检查 bots.json 里该机器人的凭据 |
| 群里 @ 它没反应 | 没连上 / 白名单 / 群设置 | ①设置页看重连状态，点「重试连接」；②确认群在 `allowGroups`；③QQ 群设置里「可获取的群聊消息范围」设为**全部** |
| 它能收消息但发不出回复 | **出口 IP 没进白名单** | 开放平台开发设置里补上出口 IP |
| 回复只发了一半 | 群被动回复窗口 5 分钟/5 次 | 让它分段回答；必要时开 `proactiveFallback`（吃配额） |
| 定时消息没发 | 进程没运行 / 配额用完 / 群没开主动发言 | ①进程要开着；②`/status` 看配额；③手机 QQ 群设置开启「机器人主动在群聊内发言」 |
| 主动消息发不出去 | 配额耗尽或没开主动发言 | 调 `quotaPerDay`；开群内主动发言权限；检查 IP 白名单 |
| 设置页提示会话功能不可用（`sessionEnabled: false`） | 缺 webhook 运行时 | 在 profile 的 `cordis.patch.yml` 里启用 `@deepseek-ai/dsh-webhook`（见 README） |
| 语音没转写 | 平台没下发转写文本 | 改用 `stt` 模式并配 `sttBaseUrl` / `sttApiKey` |
| 忘了之前说过的事 | 用了 `/new`，或记忆被关/被清 | `/记忆` 确认；确认 `memoryEnabled` 为 true |
| 它话太多 / 太安静 | 阈值与冷却不合适 | 太吵 → 调高 `valueThreshold`、加大 `groupCooldownMs`；太安静 → 反向调 |
| 英文界面下部分文字仍是中文 | 对话内容属于**数据**，不翻译 | 界面文案已全量国际化；AI 回复与聊天原文不做翻译。若**系统提示**（如 `/status` 回显）仍是中文，检查该机器人的 `replyLocale` 是否为 `en` |
| 设置页报 `transport failure for /qqbot-settings/...: HTTP 405` | 设置页 RPC 通道没挂上（请求穿透到了静态文件兜底） | 升级到修复版后**重启 dsh**；若仍报错，看启动日志里有无 `RPC 通道注册失败`。该问题是历史版本缺陷：注册接口依赖的上下文取不到 `webServer`，异常被吞掉 |
| 想看某条消息到底有没有发出去 | 翻归档 | 打开 `~/.dsh/qqbot/archive/archive-今天.jsonl` |
| 左侧 Activity Bar 里找不到「QQ 定时消息」图标 | 没装文件工作台（dsh-file-workbench）扩展 | 装好文件工作台扩展并重启 dsh 即可；不装也能在「设置 → QQ 机器人 → 机器人详情 → 定时消息」里管，功能完全相同 |
| 面板里看不到某条定时任务 | 顶部「机器人」作用域选的是指定机器人 | 把「机器人」下拉切到「**所有机器人**」看聚合列表，或切到该任务所属的机器人 |
| 新增 / 编辑表单里找不到想要的时区 | 时区只能从下拉选择（**已不支持手输**） | 下拉里含本机时区（**置顶**）+ 19 个常用时区。若任务里已保存了不在候选中的时区，界面会**原样保留为可选项**、不会静默改写 |
| 任务行上的红字被截断看不全 | 报错过长时默认收拢 | **点一下那段红字**即可展开，再点收起 |
| 命令任务报 `No such file or directory` | 命令字段里的路径写错了 | 打开该任务「编辑」，核对「要执行的命令」里的脚本路径。**不要手动往命令尾部敲字符**——脚本类任务建议改用「AI 脚本描述词」让 AI 生成命令，避免手写路径出错 |
| 任务显示「脚本生成失败」且不执行 | AI 生成脚本未成功（`genStatus=error`） | 打开「编辑」→ 重新保存（描述词可微调），任务状态会复位为待生成并重试 |
| 视图拖窄后按钮挤在一起 | 视图宽度小于阈值时会自动降级为纵向堆叠 | 这是**有意的自适应**；想横向排布就把视图拖宽到 560px 以上 |

**排障三板斧**：`/status` 看状态与配额 → 设置页看连接与统计 → 归档文件看逐条记录。

---

## 12. 名词小词典

| 词 | 意思 |
|---|---|
| **AppID / AppSecret** | 机器人的账号与密码，开放平台发的 |
| **openid** | QQ 里标识一个群或一个用户的 ID（不是 QQ 号） |
| **Preset（预设）** | 一套「人格 + 可用工具 + 权限」的组合包 |
| **被动回复** | 顺着用户消息回，5 分钟内有效，不占主动配额 |
| **主动消息** | 机器人主动往外发（定时、广播等），占每日配额 |
| **价值评分** | 给群消息打分（0–10），决定值不值得插话 |
| **会话（session）** | 一段连续对话；`/new` 可重开 |
| **长期记忆** | 跨会话保存在文件里的要点 |
| **投递出箱（outbox）** | 发送失败内容的暂存区，自动重投 |
| **群覆盖** | 针对单个群的个性化设置，优先于机器人级配置 |
| **文件工作台** | 装了 dsh-file-workbench 后出现的左侧 Activity Bar；本插件的「QQ 定时消息」管理视图就注册在这里（自动出现，无需开关） |
| **执行逻辑详情** | 点任务行「查看」后看到的那张流程图，逐节点展示该任务到点后的完整执行链路（触发 → 判断 → 执行 → 加工 → 发送） |
| **任务契约** | 三个用自然语言描述「什么时候该发、发前要不要再检查」的字段：任务目标 `goal`、通知条件 `notifyWhen`、发送前自校验 `verify` |

---

## 13. 已知边界（提前知道，少踩坑）

- 定时消息**调度精度 30 秒**，且**进程必须运行**才会触发。
- 脚本模式命令默认 **120 秒超时**（可在设置页调到最多 600 秒），超时会被强制终止。
- 一次性（`at`）任务**到点后自动删除**；若在触发时刻前被禁用、之后再启用而时刻已过，任务会被自动清理且**不会补发**。
- 群被动回复窗口 **5 分钟 / 5 次**，超长任务可能发不出去（可开 `proactiveFallback`，但吃配额）。
- 群聊历史上下文**只回放文本**，不含历史消息里的图片/文件（当前消息自带的附件会看）。
- 广播范围只包含它**收到过消息的群**。
- 消息进 DSH 会话是进程内 fire-and-forget：进程崩溃会丢未入会话的消息。
- 部分配置项**刻意不放在界面上**（默认合理、防误关），只能在 `bots.json` 改——清单见 7.2、7.3。
- **文件工作台入口无需 dsh 特定版本**：只要装了 dsh-file-workbench 扩展就会自动出现；不装则只在设置页里管，功能完全一致。
- 文件工作台视图**宽度自适应**：布局按视图容器的实际宽度自适应（而非窗口宽度）：拖窄会自动纵向堆叠、压缩间距，拖宽会放大间距，任何宽度下都不出现横向滚动条。
- 新增 / 编辑表单的**时区只能从下拉选择**（含本机时区 + 19 个常用时区），不支持手输 IANA 名称——这是刻意为之，手输极易写错且无法校验。
- **「测试」按钮是真的发一条**：内容会真的发到目标群 / 用户，但**不计入主动消息配额**、不改写「下次运行」、也不会删掉一次性任务；失败原因会写回任务行（红字）。
- 界面文案（含文件工作台视图）跟随**宿主**界面语言，与每个机器人的 `replyLocale`（发到 QQ 里的系统提示）是两套独立设置，见 7.5。

---

> 有新的使用场景或问题，欢迎补充到这本手册里。