# 安装、升级与卸载

> 目标读者：第一次在 DSH 上装 `dsh-onebot-qq` 的人。按本文从零走一遍即可跑通；
> Windows 用户建议另看 [`docs/Windows安装.md`](Windows安装.md)（有更细的路径/真机验证步骤）。
> **协议端可换**：只要实现 OneBot v11 都能对接（如 SnowLuma、OneBot 等实现），见 §二。

## 一、前置组件

| 组件 | 要求 | 说明 |
|---|---|---|
| **Node.js** | >= 22 | `node --version` 应显示 `v22.x` 或更高 |
| **DSH** | >= 0.2.1-rc.2 < 0.3.0 | `dsh --version`；profile 机制至少是 0.2.x |
| **pnpm** | 随 DSH 装插件需要（`dsh plugin add` / GUI 安装走 pnpm） | `pnpm --version`；没有就先 `npm i -g pnpm` 或 `corepack enable` |
| **协议端（任选其一）**：任意 OneBot v11 实现 | 任意近期版本 | 开 **正向 WebSocket**（常见默认 3001）+ **HTTP API**（常见默认 3000）即可。token 可空还是必填看实现（**SnowLuma 强制带 accessToken**），分别填 `wsToken`/`httpToken` |
| **QQ 账号** | — | 机器人收发消息用的账号；建议用小号（主号有风控风险） |

安装 DSH（如还没有）：

```bash
npm install -g @deepseek-ai/dsh
dsh --version
```

> DSH 的安装方式以官方文档为准；`dsh web` 首次运行会自动创建 `web` profile
> （`$DSH_HOME/profiles/web`，`$DSH_HOME` 默认 `~/.dsh`）。

## 二、准备协议端（OneBot v11）

本插件只认 **OneBot v11**，协议端可以换，**任选一个实现**。判断标准只有一条：它能对外提供
**正向 WebSocket**（消息入口，常见默认 3001）与 **HTTP API**（发消息/取文件/查群，常见默认 3000）。

- **通用要求**（所有实现都一样）：启动协议端 → 登录 QQ → 开启这两个服务 → 拿到 token（若有）；
- **SnowLuma**（本机线上在用的实现，v2.x 跨平台、源码可见）：同样转 OneBot v11，但**不启动 QQ**，要自己拉起 QQ 再让它注入，且 **3000/3001 强制带 token** —— 细节见 §2.2。

### 2.1 安装并启动协议端（通用步骤）

1. 安装并启动你的 OneBot v11 协议端，按它自己的文档登录 QQ（扫码/账密都行）。
2. 在协议端里同时开启：
   - **正向 WebSocket 服务**：常见默认 `ws://127.0.0.1:3001`（消息入口）
   - **HTTP 服务 / HTTP API**：常见默认 `http://127.0.0.1:3000`（发消息、取文件、查群）
3. 如果协议端要求 token，记下来，稍后填进实例配置的 `onebot.wsToken` / `onebot.httpToken`。
   > **配置键是 `onebot.*`，可对接任意 OneBot v11 协议端**；旧版配置里的 `napcat.*` 仍能读（`loadConfig` 自动兼容），升级不用改文件。
4. 确认端口可访问：`curl http://127.0.0.1:3000` 应返回协议端的 API 响应（或 404，但 TCP 通）。

> **安全**：协议端一般默认只监听 `127.0.0.1`，**不要**把 OneBot WS/HTTP 直接暴露到公网；
> 需要远程访问就套 SSH 隧道/VPN。token 不要提交到任何仓库。

### 2.2 SnowLuma（本机在用的实现）

适用：想换协议端、别的实现（自带拉起 QQ 的那类）在你环境里不稳、或需要多账号。本文按 **v2.2.0** 写（已在本机 Linux 无头环境真机验证）。

**和多数实现的三个关键差别**（踩坑都在这）：

| | 多数实现 | SnowLuma |
|---|---|---|
| 谁启动 QQ | 它自己拉起并注入（注入方式各实现不同） | **它不启动 QQ**：用 `ptrace` 注入**已经在跑**的 QQ 进程 |
| OneBot 鉴权 | token 可空 | **3000/3001 强制 `accessToken`**（每个网络自动生成 32 字节） |
| 登录 | 协议端自带 WebUI 扫码（端口见各实现文档） | WebUI `:5099`；**必须看得见 QQ 窗口扫码**（没有 CLI、没有二维码 API） |

步骤（Linux 无头为例）：

1. 下发行包解压到一个专用目录（下文以 `<snowluma目录>` 指代）：**完整版自带 Node 24**（推荐）；`-lite` 版需要本机 Node `>=24.22.1`。
2. 起无头 X（有桌面的机器跳过）：`Xvfb :1 -screen 0 1280x800x24` + 一个窗口管理器（`openbox`/`fluxbox`，否则登录框可能无边框/无法聚焦）。
3. **先拉起 QQ**（必须和 SnowLuma 同一个 `DISPLAY`）：
   `<QQ安装目录>/qq --no-sandbox --disable-gpu --disable-software-rasterizer --disable-gpu-compositing`
4. 启动 SnowLuma：进 `<snowluma目录>` 后 `./launcher.sh`（完整版用内置 node）或 `node ./index.mjs`。
   - 首启会在日志里打印一次 WebUI 初始密码；也可用 `SNOWLUMA_WEBUI_BOOTSTRAP_PASSWORD` 预置；
   - 无人值守要同时设 `SNOWLUMA_ACCEPT_EULA=1` 与 `SNOWLUMA_ACCEPT_PRIVACY=1` 免交互接受协议。
5. 打开 `http://127.0.0.1:5099`（账号 `admin` + 上面的密码）→ 确认它已注入 QQ（`runtime.json` 里 `hookAutoLoad: true`，或 `SNOWLUMA_HOOK_AUTOLOAD=1`）→ 在 QQ 窗口里**手机扫码登录**。
   - 无头服务器看不见窗口：装 VNC/noVNC 看桌面，或把 QQ 登录窗口**截图发成网页二维码**（本机做法：定时截图 + 识别「当前二维码已过期」红字后自动点「刷新」，登录成功后撤页）。
6. 在 WebUI 的 OneBot 配置里确认 **HTTP 服务端 3000** 与 **正向 WS 服务端 3001** 都开着，复制这两个 `accessToken`。
7. **建议关掉自带 `#sl`**：`statusCommand.enabled = false`（`statusCommand` 默认开，群里发 `#sl` 会回版本/平台/运行时长；`swallow:false` 时**还会把这条消息继续下发给机器人** → 框架与机器人各回一句）。
8. 回 §四，在控制台把两个地址与两个 token 填进 `onebot.*`。

**Linux 前置与已知坑**：

- 注入靠 ptrace：用 root，或给 node 二进制授权 `setcap cap_sys_ptrace=ep "$(readlink -f "$(which node)")"`（换 Node 版本要重做）；`/proc/sys/kernel/yama/ptrace_scope=3` 会让注入彻底失效。
- **冻结 QQ 静默热更新**（hook 与 QQ 版本强绑定，静默升级会把 hook 打坏）：`echo "0.0.0.0 qqpatch.gtimg.cn" | sudo tee -a /etc/hosts`。
- 一条栈顺序不能反：`Xvfb → 窗口管理器 → QQ → SnowLuma`；长期跑用 systemd 一个 unit 全包（否则 SSH 一断全死）。
- 配置在**工作目录**的 `config/`：`onebot.json`（全局）、`onebot_<uin>.json`（账号级，登录后自动生成）、`runtime.json`（`webuiPort`/`hookAutoLoad`）。
- `get_file` 只覆盖**图片/语音缓存**，群文件/视频走别的动作 → 本插件入站群文件/视频的溯源可能降级（聊天不受影响）。

> **安全**：SnowLuma 的 WebUI（5099）与 OneBot（3000/3001）默认只听 `127.0.0.1`。要把 WebUI 放公网，请套 HTTPS 反代 + 鉴权，别裸奔（对比：不少实现的 WebUI 是明文且常无鉴权）。

## 三、安装本插件（三选一）

### 方式 A：DSH 插件管理器（推荐）

在 DSH Web 侧栏打开「插件」页 → 安装 bundle，支持：

- **npm 包名**（发布到 registry 后）：`dsh-onebot-qq`
- **GitHub**：`github:YUsaltyfish/dsh-onebot-qq` 或 `git+https://github.com/YUsaltyfish/dsh-onebot-qq.git`
- **tarball URL**：`https://.../dsh-onebot-qq-0.1.1.tgz`
- **本地绝对目录**：`C:\path\to\dsh-onebot-qq` / `/path/to/dsh-onebot-qq`

也可以在会话里让 agent 调 `plugin_manager`：`action: install_bundle, target: <spec>`。
安装成功后插件管理器会把本包加入 profile 的 `dsh.profile.bundles` 并挂载。

### 方式 B：命令行（`dsh plugin`）

```bash
# GitHub
dsh plugin --profile web add github:YUsaltyfish/dsh-onebot-qq

# 本地 tgz（npm pack 产物）
dsh plugin --profile web add /abs/path/dsh-onebot-qq-0.1.1.tgz

# 本地目录（开发/内网；link: 不复制文件，改代码后需插件重载或重启，包内不得有私有文件）
dsh plugin --profile web add link:/abs/path/dsh-onebot-qq
```

装完确认依赖已在 profile 里：

```bash
dsh plugin --profile web why dsh-onebot-qq    # 应显示 dsh-onebot-qq 的依赖信息
```

`dsh plugin` 会通过 pnpm 修改 profile 的 `package.json`；装包后需要**重启 dsh-web**
（除非 profile 开了 HMR）。

### 方式 C：手动挂载（不用 bundle 机制）

把 [`examples/cordis.patch.yml`](../examples/cordis.patch.yml) 开头的 `insert` 块复制进
`$DSH_HOME/profiles/web/cordis.patch.yml`，**同时合并包根 `cordis.patch.yml` 的完整 `preset-qq-chat` 行**，并把相应包依赖加进 profile 的 `package.json`；不要只挂机器人行。重启后用新 QQ 会话核对实际工具面（shell / 文件 / 管理工具不应可用；全局工具见下节），不能只凭「插件已加载」判安全隔离成功。
**如果你已经按 A/B 装了 bundle，不要再用 insert**（会重复插入同一行）；改配置用该文件末尾的
「覆盖」写法（`- id: dsh-onebot-qq` + `config:`）。

### 可选：QQ 线工具门（挡住全局工具）

`dsh-onebot-qq` 的 `qq-chat` preset 只能裁掉 preset 里列出的工具；profile/bundle 层**全局注册**的工具（`dsh-ops` 的 `ops_*`、agent-team、MCP 资源、`working_directory`）仍会漏进 QQ 会话。想让 QQ 线只留聊天/联网/生图那一套，再装独立小插件 **`dsh-onebot-qq-opsgate`**：

```bash
# 必须在 dsh-onebot-qq 之后装（后层覆盖前层）
dsh plugin --profile web add github:YUsaltyfish/dsh-onebot-qq-opsgate
# 本地目录：dsh plugin --profile web add link:/abs/path/dsh-onebot-qq-opsgate
```

它只做一件事：覆盖 `preset-qq-chat` 这一行、在 plugins 列表末尾追加自己，然后在 **agent scope** 里 `ctx.tools.restrict({ deny })` 摘掉全局工具。

- **只影响 QQ 会话**，不碰网页 / 工作线 / 其他 preset；
- 全局工具是异步注册的：已注册的先挡住、未注册的每 500ms 重试，最多 90 秒；
- 必须在 profile bundles 里排在 `dsh-onebot-qq` **之后**；`dsh-onebot-qq` 升级后要同步它的 preset 副本（见其 README 的 `sync:preset`）；
- 不装也完全不影响聊天，只是工具面更大。

验证：重启后开一个 QQ 新会话，让它用 `ops_bash` / `spawn_teammate` 之类的主机工具——它应该根本不知道有这些工具。

## 四、首次配置（推荐：控制台新手向导）

> **不用先手改 JSON**。缺 `adminQq` 时插件进入「**待配置模式**」：控制台可用、工具已注册、但**不连协议端**，
> 日志会明确提示缺什么。在控制台填完保存后**自动连接**，不需要重启。
>
> **装完插件会自动做的（不用手工配）**：声明并启用内置 `qq-chat` preset（纯聊天 + 联网，裁掉 shell / 文件 / 任务 / 技能 / 插件管理类工具）→ 自动创建「QQ 聊天」工作区 → 首次启动自动投递默认人设「蓝色大肥鱼」→ 缺 QQ 号时进入待配置模式 + 新手向导 → 启动自检（控制台「运维 → 🧪 检查运行环境」）。宿主缺 `workspaceRegistry` / `agentPresets` 服务时自动降级（不归组 / 用默认工具面），补装对应 DSH 插件即可（见 §十）。

### 1. 建数据目录（推荐）

`dataDir` 默认是 `$DSH_HOME/dsh-onebot-qq`（Linux/macOS 通常是 `~/.dsh/dsh-onebot-qq`；
Windows 通常是 `%USERPROFILE%\.dsh\dsh-onebot-qq`）。用 CLI 一步建好目录、配置模板和默认人设：

```bash
# 在包目录（安装后是 <profile>/node_modules/dsh-onebot-qq）里执行：
node bin/dsh-onebot-qq.mjs init
# 自定义数据目录：
node bin/dsh-onebot-qq.mjs init --data-dir /srv/dsh-onebot-qq
```

`init` 会：建数据目录与全部子目录 → 写 `<dataDir>/config.json`（`adminQq: 0` 待填）→
把 `examples/qq-lines/*` 复制到 `<dataDir>/workspace`、`examples/personas/*` 复制到
`<dataDir>/personas` → **投递内置默认人设「蓝色大肥鱼」**（人设文件 + QQ 线投递文件，并把
`pluginConfig['persona-voice'].activePersona` 写进配置）。**不覆盖已有文件**（`--force` 只覆盖
`config.json`，且先备份；人设已存在时跳过）。

> 📁 命令里的相对路径以**包目录**为基准：源码仓库 = 仓库根；tgz 装进 profile 后是
> `$DSH_HOME/profiles/<profile>/node_modules/dsh-onebot-qq/`（Windows 同理在 `node_modules\dsh-onebot-qq\`）。
> 自定义数据目录时，除了 `init --data-dir`，还要让插件也读同一个目录（`DSH_QQ_DATA_DIR` 或 profile patch 的 `dataDir`）。

### 2. 启动 DSH Web（首次可以先启动）

```bash
dsh web          # 或 dsh --profile web
```

此时还没填 QQ 也没关系：插件以「待配置模式」挂载，浏览器打开 DSH Web 即可继续配置。
日志会提示：

```
[onebot-qq:kernel] 实例配置未完成（缺 adminQq）…控制台可继续配置
[onebot-qq:kernel] 内核就绪（契约 v1，插件 11/11，工具 10，命令 7）
```

（正常会看到「OneBot WS 已连接」；没配置/没连上时不会出现，属预期。）

### 3. 控制台「新手向导」（推荐路径）

打开 **设置 → QQ 控制台**：

| 位置 | 做什么 |
|---|---|
| **总览 → 新手向导** | 清单逐项 ✅/❌：配置文件、主人 QQ、协议端连接、人设、生图（可选），每项一句「怎么做」；未完成时顶部有醒目提示条 |
| **OneBot 连接**页（任意 OneBot v11 协议端都填这里） | 图文步骤说明 + `wsUrl` / `httpUrl` / token 输入（按钮在「运维」页：**「测试 OneBot 连接」**、**「重新连接 OneBot」**） |
| **生图**页 | **协议**（`openai-images` / `openai-chat`）、API 地址、模型（带建议下拉）、API Key（掩码）；「检查生图配置」按钮在「运维」页 |

> 人设**不用手动创建**：`init` 会投递，插件首次启动也会自动投递内置默认人设「蓝色大肥鱼」。

**填写顺序**：主人 QQ → 协议端地址/token（离开输入框即保存）→ 去「运维」点「测试 OneBot 连接」看返回（测的是已保存配置）。
保存后**自动连接**（无需重启），向导里协议端项变成 ✅ 后就可以在 QQ 里发消息了。
> 接 SnowLuma 时：两个 token **都必须填**（它强制鉴权），地址仍默认 `ws://127.0.0.1:3001` / `http://127.0.0.1:3000`。
生图不配置不影响聊天；配置后到「运维」用「检查生图配置」验证地址/Key/模型。

### 4. 手动方式（等价，仍支持）

也可以直接编辑 `<dataDir>/config.json`：

```json
{
  "version": 2,
  "adminQq": 10001,
  "onebot": {
    "wsUrl": "ws://127.0.0.1:3001",
    "wsToken": "",
    "httpUrl": "http://127.0.0.1:3000",
    "httpToken": ""
  }
}
```

| 键 | 必填 | 说明 |
|---|---|---|
| `adminQq` | ✅ | **主人 QQ 号**（唯一）；控制台新手向导填，或手改配置 |
| `onebot.wsUrl` | ✅ | OneBot 正向 WS 地址，如 `ws://127.0.0.1:3001` |
| `onebot.httpUrl` | ✅ | OneBot HTTP API 地址，如 `http://127.0.0.1:3000` |
| `onebot.wsToken` / `httpToken` | 视协议端 | 协议端开了鉴权才填（多数实现可选）；**SnowLuma 必填**（它强制生成 token） |
| `credentials.gptImage.*` | 可选 | 生图凭据（协议/地址/模型/Key）；也可用环境变量 |
| `dsh.agentPreset` | 可选 | **默认 `qq-chat`**：插件随包声明了这个 preset（纯聊天 + 联网，裁掉 shell / 文件 / 任务 / 技能 / 插件管理类工具），安装即用、无需手改 profile；留空时也会自动启用 |
| `dsh.workspaceTitle` | 可选 | QQ 工作区在 DSH 侧栏的显示名（默认「QQ 聊天」）；插件启动时按 `dsh.qqWorkspacePath` 自动创建或复用该工作区，QQ 会话都归到这里 |
| `archive.enabled` / `archive.dir` | 可选 | 聊天留档，默认开、写 `<dataDir>/logs/qq_chat` |

> 示例里的 `10001` 只是占位，**必须换成你自己的 QQ 号**。
> 手改配置后需要**重启 dsh-web** 生效；控制台保存会热应用支持的参数；资源边界/启动项的生效时机见 [配置参考](配置参考.md#热改说明)。

### 5. 自检

```bash
node bin/dsh-onebot-qq.mjs doctor
# 离线/不探测端口：
node bin/dsh-onebot-qq.mjs doctor --no-net
```

✅/⚠️/❌ 清单里**有 ❌ 就退出码 1**。常见 ❌：配置不存在、`adminQq` 未填、协议端 URL 未填；
人设项会检查 `personas/` 目录与当前投递文件（缺失只是 ⚠️，不影响聊天）。当前 CLI 的 doctor / persona 仅按 `<dataDir>/config.json`、`personas/`、`workspace/` 默认布局工作；`--data-dir` 不能表示自定义 configPath / personaDir / qqWorkspacePath。自定义布局请在控制台按运行路径检查与切换，不要据 CLI 结果断言运行目录已修改。

### 6. 人设

`init` 已自动投递默认人设「蓝色大肥鱼」（没有 symlink 权限时自动用复制模式）。之后：

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

插件首次启动也会自动投递（`init` 与启动二选一即可）。想换/加人设、写句池与唤醒词，见 [`使用说明书 §6`](使用说明书.md#6-人设怎么写)。

## 五、启动与验收

首次配置完成后（控制台保存后自动连接），验收四步（缺一不可）：

1. **服务 active**：`dsh web` 正常运行，日志无 ERROR；
2. **连接有证据**：日志有「OneBot WS 已连接」（连 SnowLuma 也是这句）+ 内核就绪，或控制台「测试 OneBot 连接」返回 ok；
3. **真实请求**：私聊机器人发一句话，QQ 能收到回复；群里 @ 机器人发一句话，同样能回；
4. **能力抽检**：`/status` 能回；控制台能打开并热改一个开关（如表情包概率）；`send_image` 能发一张
   `<dataDir>/workspace` 下的图（路径在白名单内）。

无 QQ 环境时：在**源码仓库根**执行 `node --test`（含假协议端端到端）可验证离线内核链路，不能代替真实 QQ / Windows 真机验收。安装包不含 `test/`，其中零用例退出成功不算完整测试通过。

> 只想快速判断装好没有（最小 3 条）：控制台「🧪 检查运行环境」必需项全绿 · 侧栏出现「QQ 聊天」工作区（配置里 `agentPreset = qq-chat`）· 私聊发一句有回复。

> 🩺 **卡住了先跑一键诊断**：设置 → QQ 控制台 →「运维」→ **一键诊断 / 导出运维报告**。
> 它会生成一份脱敏报告并告诉你保存位置，可以直接把报告路径交给 DSH 本体修复（详见
> [排错 §〇 一键诊断](排错.md#〇第一步一键诊断推荐先做)）。

## 六、升级

1. **先备份**：`<dataDir>` 整个目录（配置 + 人设 + 表情库 + 会话状态）复制一份即可。
2. 插件管理器：对 `dsh-onebot-qq` 点「更新」（内部 = 卸载旧版 + 安装新版）；或命令行：
   ```bash
   dsh plugin --profile web remove dsh-onebot-qq
   dsh plugin --profile web add github:YUsaltyfish/dsh-onebot-qq
   ```
3. 重启 dsh-web。数据目录与实例配置**不受升级影响**；新增配置键走 schema 默认值，
   删除/改名的键按版本 CHANGELOG 处理。
4. 若装了 `dsh-onebot-qq-opsgate`，也一起升级，并重新同步它的 preset 副本（其 README 的 `sync:preset`）。
5. **从旧版（包名 `dsh-qq-bot`）升级**：新版默认数据目录是 `$DSH_HOME/dsh-onebot-qq`，
   但旧目录存在时会**自动沿用**，不需要搬配置；profile 里的依赖/bundle 名改由安装命令处理。

## 七、卸载

```bash
# 插件管理器：选中 dsh-onebot-qq → Remove；或命令行：
dsh plugin --profile web remove dsh-onebot-qq
```

- 卸载**不会**删除数据目录（QQ 号/群表/人设/表情库/记忆都还在）。确认不要了再手动删
  `<dataDir>`（默认 `$DSH_HOME/dsh-onebot-qq`）。
- 若手动挂过 patch，记得把 `cordis.patch.yml` 里的 `dsh-onebot-qq` 行删掉，再重启。

## 八、回滚

- **preset / 工作区异常**：在实例 `config.json` 把 `dsh.agentPreset` 留空（或改回 `qq-chat`），保存后重启一下即可恢复默认装配。
- **插件回滚**：`dsh plugin --profile <profile> remove dsh-onebot-qq`（数据目录保留，可随时装回旧版本）。

## 九、权限与凭据

- `init` 会尽量设置 `config.json` 为 `0600`、数据目录为 `0700`（Windows 上 chmod 基本无效）。
  Windows 可用：
  ```powershell
  icacls "$env:USERPROFILE\.dsh\dsh-onebot-qq\config.json" /inheritance:r /grant:r "$env:USERNAME:(R,W)"
  ```
- 生图凭据优先放环境变量（DSH 进程的环境）：`QQ_IMAGEGEN_API_KEY`、`QQ_IMAGEGEN_BASE_URL`、
  `QQ_IMAGEGEN_MODEL`；实例配置 `credentials.gptImage` 可作后备（注意 0600）。
- 协议端 token 只放在实例配置里（`onebot.wsToken`/`httpToken`），不要写进 profile patch、不要提交 git。

## 十、极端情况（自定义极简 profile）

宿主若**完全没有** `workspaceRegistry` / `agentPresets` 服务（只有自己拼的极简 profile 才会遇到）：插件会自动降级（QQ 会话不归组 / 用默认工具面）并提示补装。由 DSH 执行（装完重启）：

```bash
dsh plugin --profile <profile> add @deepseek-ai/dsh-workspace
dsh plugin --profile <profile> add @deepseek-ai/dsh-agent-preset-registry
```

## 十一、装不上/起不来？

**先跑一键诊断**（控制台 运维 → 🩺 一键诊断）拿到脱敏报告；没有控制台时用 CLI
`node bin/dsh-onebot-qq.mjs doctor`。详见 [排错](排错.md)。最快的三个入口：

```bash
node bin/dsh-onebot-qq.mjs doctor          # 环境与配置
dsh --profile web --dump-config     # profile 里插件行是否挂上
curl -s http://127.0.0.1:3000       # 协议端 HTTP 通不通（任意 OneBot v11 实现都一样）
```