@karinjs/adapter-qqbot 2.0.0 → 2.2.1

package/README.md

@@ -1,29 +1,6 @@
 # @karinjs/adapter-qqbot
 
-[![npm](https://img.shields.io/npm/v/@karinjs/adapter-qqbot?style=flat-square)](https://www.npmjs.com/package/@karinjs/adapter-qqbot)
-[![license](https://img.shields.io/npm/l/@karinjs/adapter-qqbot?style=flat-square)](./LICENSE)
-
-为 [Karin](https://github.com/KarinJS/Karin) 框架提供 QQ 官方机器人接入能力。
-
-> **2.0 已发布**：完整重写，对齐 QQ 开放平台 2026 年起的新事件协议
-> （`GROUP_MESSAGE_CREATE` 全量群聊消息 + `mentions` 数组），并适配
-> Markdown / Keyboard 全量开放后的发送方式。
-
----
-
-## 特性
-
-- 🌐 **完整事件支持**：群聊（@/全量）、单聊、频道、频道私信、按钮点击、机器人入退群、主动消息开关
-- 📨 **双发送通道**：自动选择「经典通道」（text + media）或「Markdown 通道」（msg_type=2 + keyboard），按消息内容与配置开关
-- 🔌 **双接入方式**：WebSocket（推荐，无需公网）/ Webhook（QQ 主动推送）
-- ♻️ **WebSocket Resume**：断网自动重连，携带 `session_id` / `seq` 通过 `op:6` 恢复，减少消息丢失
-- 🔑 **扫码登录**：插件首次启动自动二维码引导，授权后写回 `config.json`
-- 🧩 **按钮回调**：完整接入 `INTERACTION_CREATE`，自动 ack 并以普通消息事件投递给业务层
-- 🛡️ **签名校验**：webhook 入口自动用 ed25519 校验
-- 📐 **完整 TypeScript 类型**
-- 🧹 **零 1.x 残留**：不再依赖 Markdown 模板 / keyboard 模板 / 中转服务
-
----
+Karin 的 QQ 官方机器人适配器。
 
 ## 安装
 
@@ -31,59 +8,13 @@
 pnpm add @karinjs/adapter-qqbot
 ```
 
-> 要求 Node.js >= 18，Karin >= 1.15
-
----
-
-## 快速开始
+要求：Node.js >= 22、Karin >= 1.15
 
-### 方式 A：扫码登录（推荐）
+## 配置
 
-启动后没有任何已配置的 QQBot 时，控制台只打印一行提示：
-
-```
-  ==========================================
-  未检测到 QQBot 配置
-  请使用任意可用 bot（如 OneBot / Console 适配器）
-  对机器人发送指令： #QQ登录
-  扫码授权完成后会自动写入配置并完成初始化
-
-  ⚠ 注意：扫码授权会刷新该机器人的 secret，旧 secret 立即失效
-  ==========================================
-```
-
-按提示，在**任意已连接的 bot 适配器**（OneBot、Console、Discord …）下，给机器人发送：
-
-```
-#QQ登录       # 或 #qq登录 / #qqlogin / #QQLogin
-```
+首次启动没有 QQBot 配置时，使用**任意已连接的机器人**或在**控制台中**发送 `#QQ登录` 完成扫码授权。
 
-服务端控制台随后弹出 ASCII 二维码：
-
-```
-  ▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢
-  ▢ ASCII QR ▢▢▢▢▢▢▢
-  ▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢▢
-
-  请使用 QQ 扫描上方二维码，或在手机 QQ 打开链接：
-  https://q.qq.com/qqbot/openclaw/connect.html?task_id=...
-```
-
-手机 QQ 扫码授权后，插件自动：
-
-1. 从平台拉取 `appId` + 加密的 `secret`
-2. 本地 AES-256-GCM 解密
-3. 调 `/users/@me` 获取昵称
-4. 写入 `${karin-base}/@karinjs-adapter-qqbot/config/config.json`
-5. `watch` 回调自动初始化 bot，无需重启
-
-> 该指令同样可用于**新增账号**和**刷新已有账号的 secret**。
-
-### 方式 B：手动配置
-
-在 [QQ 开放平台](https://bot.q.qq.com/) 创建机器人，记录 `AppID` 与 `Secret`，然后编辑：
-
-`@karinjs/adapter-qqbot/config/config.json`：
+也可以访问 Karin WebUI 可视化编辑 或者 手动编辑：`@karinjs-adapter-qqbot/config/config.json`。
 
 ```json
 [
@@ -91,236 +22,162 @@ pnpm add @karinjs/adapter-qqbot
     "name": "我的机器人",
     "appId": "1234567890",
     "secret": "your-secret",
-    "prodApi": "https://api.sgroup.qq.com",
-    "sandboxApi": "https://sandbox.api.sgroup.qq.com",
-    "tokenApi": "https://bots.qq.com/app/getAppAccessToken",
     "sandbox": false,
     "qqEnable": true,
     "guildEnable": true,
     "guildMode": 0,
-    "regex": [{ "reg": "^/", "rep": "#" }],
-    "markdown": { "enable": false },
+    "proxy": {
+      "prodApi": "https://api.sgroup.qq.com",
+      "sandboxApi": "https://sandbox.api.sgroup.qq.com",
+      "tokenApi": "https://bots.qq.com/app/getAppAccessToken",
+      "prodWs": "wss://api.sgroup.qq.com/websocket/",
+      "sandboxWs": "wss://sandbox.api.sgroup.qq.com/websocket/"
+    },
     "keyboard": { "enable": true },
+    "markdown": { "enable": true },
     "event": { "type": 2 }
   }
 ]
 ```
 
-保存即生效（`watch` 自动重载）。
+- `event.type`: `0` 关闭、`1` Webhook、`2` WebSocket（默认）。
+- `guildMode`: `0` 公域，只收 @ 消息；`1` 私域，接收全部频道消息。
+- `proxy`: 自定义连接代理地址。`prodApi` / `sandboxApi` 作为 OpenAPI 根地址使用，后端拼接路径时会兼容末尾 `/`；`tokenApi` 是完整接口地址；`prodWs` / `sandboxWs` 是完整 WebSocket 网关地址，支持 `ws://` 和 `wss://`，路径和查询参数会按配置原样连接。
+- `markdown.enable`: 是否让普通文本和图片自动合并为 Markdown 消息，默认开启。关闭后普通图片会改为单独上传发送；插件显式传入的 `segment.markdown` 不受此开关影响。
 
----
+## 按钮
 
-## 配置项详解
+按钮一般和 Markdown 一起发送，常用有三种：
 
-| 字段 | 类型 | 默认 | 说明 |
-| --- | --- | --- | --- |
-| `name` | string | `""` | 机器人显示名（扫码登录会自动获取） |
-| `appId` | string | — | 机器人 AppID（**必填**） |
-| `secret` | string | — | 机器人 Secret（**必填**） |
-| `prodApi` | string | `https://api.sgroup.qq.com` | 正式环境 API 基址 |
-| `sandboxApi` | string | `https://sandbox.api.sgroup.qq.com` | 沙盒环境 API 基址 |
-| `tokenApi` | string | `https://bots.qq.com/app/getAppAccessToken` | access_token 获取接口 |
-| `sandbox` | boolean | `false` | 是否启用沙盒环境 |
-| `qqEnable` | boolean | `true` | 是否处理单聊 / 群聊 |
-| `guildEnable` | boolean | `true` | 是否处理频道消息 |
-| `guildMode` | `0` \| `1` | `0` | `0` 公域（只接 @ 消息）/ `1` 私域（所有消息） |
-| `regex` | object[] | `[{reg:"^/", rep:"#"}]` | 收到消息后对文本执行的正则替换 |
-| `keyboard.enable` | boolean | `true` | 是否将文本中的 URL **自动**转为 keyboard 按钮 |
-| `event.type` | `0` \| `1` \| `2` | `2` | 事件接收方式：0 关闭 / 1 webhook / 2 WebSocket |
+- 跳转按钮：点击后打开 `link`。
+- 指令按钮：点击后把 `data` 发送成一条普通消息。
+- 回调按钮：点击后不会在聊天框发消息，但适配器会下发一条 Karin 消息事件，消息内容就是 `data`。
 
----
+下面这个示例先发送一组按钮，然后分别接住“指令按钮”和“回调按钮”的点击结果：
 
-## 事件接收方式
-
-### WebSocket（推荐，`event.type: 2`）
+```ts
+import karin, { segment } from 'node-karin'
+
+export const buttonDemo = karin.command(/^按钮示例$/, async (e) => {
+  await e.reply([
+    segment.markdown('#### 按钮示例\n请选择一个操作：'),
+    segment.button([
+      { text: '打开文档', link: 'https://bot.q.qq.com/wiki/' },
+      { text: '发送指令', data: '按钮示例 帮助', enter: true },
+      { text: '回调确认', callback: true, data: '按钮示例 确认' },
+    ]),
+  ])
+})
+
+export const buttonHelp = karin.command(/^按钮示例 帮助$/, async (e) => {
+  await e.reply('这是指令按钮发送出来的消息。')
+})
+
+export const buttonConfirm = karin.command(/^按钮示例 确认$/, async (e) => {
+  await e.reply(`收到回调按钮：${e.msg}`)
+})
+```
 
-- 主动连接 QQ 官方 `wss://api.sgroup.qq.com/websocket/`
-- 无需公网 IP / HTTPS 证书
-- intents 自动探测，从最大权限位逐级回退到可用集合
-- **自动 Resume**：断网时记录 `session_id` / `seq`，下次连接走 `op:6` 让服务端补发丢失的事件；服务端拒绝 Resume 时降级 Identify
-- 指数退避重连：`1.5s × 2^n + jitter`，上限 30s
+如果你希望回复自动带上一组按钮，可以把按钮单独注册出来。下面这个分页示例会根据当前消息生成“上一页 / 下一页”：
 
-### Webhook（`event.type: 1`）
+```ts
+import karin, { segment } from 'node-karin'
 
-- QQ 主动推送 `POST /qqbot/webhook` 到你的服务
-- 自动处理 `op:13` 鉴权回调（签名回包）
-- 普通事件用 ed25519 校验签名
-- 需要公网 HTTPS：在 QQ 开放平台后台配置「统一回调地址」为 `https://your-domain/qqbot/webhook`
+const getPage = (msg = '') => Number(msg.match(/^菜单(?:\s+(\d+))?$/)?.[1] || 1)
 
----
+export const menuDemo = karin.command(/^菜单(?:\s+\d+)?$/, async (e) => {
+  const page = getPage(e.msg)
+  await e.reply(segment.markdown(`#### 菜单\n当前第 ${page} 页`))
+})
 
-## 发送通道
+export const menuKeyboard = karin.button(/^菜单(?:\s+\d+)?$/, (next, args) => {
+  const page = getPage(args?.e?.msg)
 
-**所有 QQ / 频道消息一律走 `msg_type=2` Markdown 通道**（官方已全量开放），不再
-按内容选择通道：
+  return segment.keyboard([
+    [
+      { text: '上一页', data: `菜单 ${Math.max(1, page - 1)}`, enter: true },
+      { text: '下一页', data: `菜单 ${page + 1}`, enter: true },
+    ],
+  ])
+})
+```
 
-- 文本 / `segment.at(...)` 通过 markdown content 渲染（at 用 `<qqbot-at-user id="..."/>` 内嵌标签）
-- 图片合并为 `![karin #宽px #高px](url)` 内嵌到同一条 markdown
-- `segment.button(...)` / `segment.keyboard(...)` 自动挂到 `keyboard.content.rows`，与 markdown 同条下发
-- 文本中 URL（开启 `keyboard.enable` 时）自动 `extractUrlButtons` 转 keyboard 按钮
-- 视频 / 语音 / 文件不能进 markdown，由 pipeline 自动以 `msg_type=7` 紧随 markdown 主消息**并发补发**
+简单理解：`karin.button` 是“自动追加按钮”的规则。适配器回复时会自动用 `buttonHandle(e.msg, { e })` 查找匹配规则，所以用户发送 `菜单 2`，就会命中 `/^菜单(?:\s+\d+)?$/`，按钮函数再通过 `args?.e?.msg` 算出当前页。
 
----
+自己调用 `buttonHandle` 时只记三点：
 
-## 按钮回调（INTERACTION_CREATE）
+- 参数一是匹配文本，通常填 `e.msg`，也可以是 `'菜单'`。
+- 参数二是给按钮函数的上下文，常用 `{ e }`；需要状态可以写 `{ e, page: 2 }`。
+- 一个规则里调用 `next()`，才会继续匹配后面的规则。
 
-收到按钮点击时，适配器：
+回调按钮的 `data` 会变成一条 Karin 消息内容，所以建议直接写成插件能识别的命令，例如 `按钮示例 确认`、`菜单 下一页`。
 
-1. 立即 `PUT /interactions/{id}` `code=0` 回 ack，防止客户端 loading
-2. 将事件转为对应场景的消息事件投递：
-   - `chat_type=0` → guild message
-   - `chat_type=1` → group message
-   - `chat_type=2` → friend message
-3. 消息 elements 结构：
+## 发送消息与资源文件
 
-```ts
-[
-  segment.at(selfId),       // 群 / 单聊场景自动补
-  segment.text(button_data),
-  segment.json('{"tag":"qqbot-button-click","button_id":"...","button_data":"...",...}'),
-  // srcReply 末尾自动追加 segment.pasmsg(id, 'event')
-]
-```
+适配器会尽量帮你发送图片、视频、语音和文件。推荐配置 `fileToUrl` 上传处理器，把本地文件、截图、Base64 等资源上传到你的图床、对象存储或 CDN，并返回一个 QQ 能访问的链接。
 
-业务层通过 `e.rawEvent.t === 'INTERACTION_CREATE'` 区分普通消息与按钮点击。
+配置 `fileToUrl` 后：
 
----
+- 本地图片可以正常嵌入 Markdown 消息。
+- 视频、语音和文件会优先使用你返回的链接发送，通常比直接上传给 QQ 更稳定。
+- 如果资源本身已经是 `http` / `https` 链接，适配器会直接使用它。
 
-## 群聊消息事件
+没有配置 `fileToUrl` 时：
 
-QQ 官方 2026 起的新版 `GROUP_MESSAGE_CREATE` 报文：
+- 单独发送图片、视频、语音、文件时，适配器会尝试直接交给 QQ 发送。
+- 较大的资源会使用 QQ 的大文件上传流程，优先保证消息能发出去。
+- 较大的图片或视频直接交给 QQ 发送时，QQ 客户端可能会把它显示成群文件，而不是图片或视频卡片；配置 `fileToUrl` 后通常可以避免这种显示问题。
+- 直接交给 QQ 只是兜底方案，生产环境仍然建议准备自己的文件服务。
 
-```json
-{
-  "op": 0, "t": "GROUP_MESSAGE_CREATE",
-  "d": {
-    "author": {
-      "id": "...", "member_openid": "...", "union_openid": "",
-      "username": "小布丁qwq", "bot": false
-    },
-    "content": " /分布 ",
-    "group_id": "...", "group_openid": "...",
-    "id": "ROBOT1.0_...",
-    "mentions": [
-      { "is_you": true, "scope": "single", "username": "方舟生存飞升", "...": "..." }
-    ],
-    "message_scene": { "ext": ["msg_idx=REFIDX_..."], "source": "default" },
-    "message_type": 0,
-    "timestamp": "2026-05-08T13:24:53+08:00"
-  }
-}
-```
+> **注意：Markdown 里的图片必须配置 `fileToUrl`。**
+>
+> 只要你发送的内容包含 Markdown，并且 Markdown 里有图片、本地生成图、Base64 图等资源，就必须配置 `fileToUrl`。因为 Markdown 里的图片只能写成 QQ 能访问的链接，适配器不能把 Markdown 文本里的图片自动当成附件上传。
 
-适配器行为：
+你可以在自己的 Karin 插件中编写并注册 `fileToUrl` Handler：
 
-- 当 `mentions[].is_you === true` 时，elements 头部自动补 `segment.at(self)`
-- `author.username` 写入 `sender.nick`
-- `cfg.regex` 应用到 content 拆分后的每个文本段
-- 原始报文完整保留在 `e.rawEvent`，业务层可访问 `mentions` / `message_scene` / `message_type`
+```js
+// plugins/karin-plugin-example/fileToUrl.js
+import karin, { common } from 'node-karin'
+import size from 'image-size'
 
----
+export const uploadResource = karin.handler('fileToUrl', async (args) => {
+  const { file, type, filename } = args
+  const buffer = await common.buffer(file)
 
-## 撤回 / 引用回复 / 被动消息
+  // 由你实现：上传到图床/对象存储，返回可公开访问的 URL。
+  const url = await uploadToYourStorage(buffer, filename || 'file.bin')
 
-- **撤回**：`bot.recallMsg(contact, messageId)` —— 自动按场景调用 `/v2/users` / `/v2/groups` / `/channels` / `/dms`
-- **引用回复**：传入 `segment.reply(messageId)`，仅附加在第一条消息上
-- **被动消息白名单**：
-  - 单聊 `event_id` 接受：`INTERACTION_CREATE` / `C2C_MSG_RECEIVE` / `FRIEND_ADD`
-  - 群聊 `event_id` 接受：`INTERACTION_CREATE` / `GROUP_ADD_ROBOT` / `GROUP_MSG_RECEIVE`
+  if (type !== 'image') return { url }
 
----
+  const dimension = size(buffer) // 获取图片宽高
+  return {
+    url,
+    width: dimension.width || 100,
+    height: dimension.height || 100
+  }
+})
+```
 
-## Web 配置面板
+> **注意：Handler 插件的 key 必须精确为 `fileToUrl`。**
+>
+> 图片必须返回 `{ url, width, height }`；其他资源返回 `{ url }`。
 
-Karin 内置 Web 面板可视化编辑 `config.json`，本插件提供以下控件：
+建议生产环境都配置 `fileToUrl`。这样图片、视频和文件都可以先上传到你自己的文件服务，再交给 QQ 发送，成功率和可控性都会更好。
 
-- 基础字段：name / appId / secret / prodApi / sandboxApi / tokenApi
-- 沙盒、QQ 场景、频道场景、频道私域模式开关
-- 正则规则列表（每行 `<regex> <replacement>`）
-- **URL 自动按钮** 开关（`keyboard.enable`）
-- 事件接收方式（关闭 / Webhook / WebSocket）
+## 事件
 
----
+- 支持 QQ 单聊、群聊、频道、频道私信和按钮回调。
+- 支持 `GROUP_MESSAGE_CREATE` 全量群消息和 `author.member_role` 身份字段。
+- 支持 `GROUP_MEMBER_ADD`、`GROUP_MEMBER_REMOVE` 群成员进退群事件。
+- 单聊同一 `msg_id` 最多回复 4 次；群聊规则保持官方限制。
 
 ## 开发
 
 ```bash
-git clone https://github.com/KarinJS/karin-plugin-adapter-qqbot.git
-cd karin-plugin-adapter-qqbot
 pnpm install
-pnpm dev          # tsx watch
-pnpm build        # tsc + tsdown
+pnpm build
 ```
 
-源码结构（2.0）：
-
-```
-src/
-├── connection/
-│   ├── routing.ts          express 路由聚合
-│   ├── webhook.ts          POST /qqbot/webhook
-│   ├── transport.ts        事件总线（appId → 业务）
-│   └── ws/
-│       ├── client.ts       单连接生命周期 + 心跳 + Resume
-│       ├── intents.ts      intents 探测与回退
-│       └── manager.ts      多 bot 连接管理
-├── core/
-│   ├── index.ts            createBot / destroyBot / initQQBotAdapter
-│   ├── api/                QQBotApi 门面 + http/messages/media/interaction/meta/builders
-│   ├── internal/axios.ts   access_token 缓存 + 自动刷新
-│   ├── adapter/
-│   │   ├── base.ts         AdapterQQBot
-│   │   ├── grouping.ts     消息归类
-│   │   ├── pipeline-qq.ts  QQ 单聊/群聊发送管线
-│   │   ├── pipeline-guild.ts 频道发送管线
-│   │   └── text-to-md.ts   URL→ 按钮、图片→ markdown
-│   ├── event/
-│   │   ├── dispatcher.ts   事件分发器
-│   │   ├── message.ts      群/单/频道/私信消息
-│   │   ├── notice.ts       入退群/好友/主动消息开关
-│   │   ├── interaction.ts  按钮回调
-│   │   └── conver.ts       报文 → karin elements
-│   └── onboard/
-│       ├── crypto.ts       AES-256-GCM 解密
-│       ├── portal.ts       q.qq.com 接口
-│       ├── qr.ts           终端二维码 + 轮询
-│       └── index.ts        runQrOnboard / needQrOnboard
-├── apps/                   karin app 插件
-│   └── login.ts            #QQ登录 指令
-├── types/                  事件、配置、opcode 类型
-└── utils/                  日志、配置读写、文本工具
-
-demo/                       示例 / 烟测 app（不进 npm 包，不自动加载）
-└── qqtest.ts               QQBot 2.0 真号烟测命令集合
-```
-
-### 调试
-
-WS 入站消息、bus 派发、dispatcher 路由等关键链路均通过 `logger.debug` 输出。
-诊断「事件收不到」类问题时，把 karin 的 `log.level` 改成 `debug` 即可看到完整链路。
-
----
-
-## 从 1.x 升级
-
-2.0 是破坏式重写，**不提供配置自动迁移**。需要手动调整：
-
-| 1.x | 2.0 |
-| --- | --- |
-| `markdown.mode: 0/1/2/3/4/5`（模式选择 / 模板） | 全部删除，永远默认走 markdown 通道 |
-| `event.wsUrl` / `event.wsToken` | 删除（中转方案已废弃） |
-| 新增 | `keyboard.enable: true`（默认，URL 自动转按钮） |
-
-完整改动详见 [CHANGELOG.md](./CHANGELOG.md) 2.0.0 段落。
-
----
-
-## 反馈
-
-- Issue：https://github.com/KarinJS/karin-plugin-adapter-qqbot/issues
-
----
-
 ## License
 
 MIT

package/dist/apps/cleanup.d.ts

@@ -0,0 +1,5 @@
+//#region src/apps/cleanup.d.ts
+/** 每 10 分钟清理一次过期的 getMsg/getHistoryMsg 本地缓存。 */
+declare const clearMessageCache: import("node-karin").Task | undefined;
+//#endregion
+export { clearMessageCache };

package/dist/apps/cleanup.js

@@ -0,0 +1,22 @@
+import { n as config } from "../config-B_Gc9JKZ.js";
+import { t as getMessageStore } from "../message-Dt4QkDYn.js";
+import karin from "node-karin";
+
+//#region src/apps/cleanup.ts
+/**
+* 判断是否有任意 QQBot 配置开启消息缓存。
+*
+* @returns true 表示需要注册消息缓存清理任务。
+*/
+const enabledMessageCache = () => {
+	return config().some((item) => item.messageCache.enable);
+};
+/** 每 10 分钟清理一次过期的 getMsg/getHistoryMsg 本地缓存。 */
+const clearMessageCache = enabledMessageCache() ? karin.task("qqbot 适配器消息缓存清理", "*/10 * * * *", async () => await getMessageStore().cleanupExpired(), {
+	name: "qqbot 适配器消息缓存清理任务",
+	log: false,
+	type: "skip"
+}) : void 0;
+
+//#endregion
+export { clearMessageCache };

package/dist/apps/login.d.ts

@@ -1,5 +1,3 @@
-import * as _$node_karin0 from "node-karin";
-
 //#region src/apps/login.d.ts
 /**
  * #QQ登录 指令
@@ -15,6 +13,6 @@ import * as _$node_karin0 from "node-karin";
  *
  * ⚠ 注意：扫码授权会刷新该 appId 的 secret，旧 secret 立即失效
  */
-declare const qqLogin: _$node_karin0.Command<keyof _$node_karin0.MessageEventMap>;
+declare const qqLogin: import("node-karin").Command<keyof import("node-karin").MessageEventMap>;
 //#endregion
 export { qqLogin };

package/dist/apps/login.js

@@ -1,6 +1,6 @@
-import { f as log } from "../config-H7LrvlNU.js";
-import { n as runQrOnboard } from "../onboard-BX8g8Wik.js";
-import karin$1, { segment } from "node-karin";
+import { m as log } from "../config-B_Gc9JKZ.js";
+import { n as runQrOnboard } from "../onboard-BXQ1cG8h.js";
+import karin, { segment } from "node-karin";
 
 //#region src/apps/login.ts
 /**
@@ -19,30 +19,79 @@ import karin$1, { segment } from "node-karin";
 */
 /** 互斥锁：避免并发扫码 */
 let busy = false;
-const qqLogin = karin$1.command(/^#(?:qq登录|qqlogin)$/i, async (e) => {
+/**
+* 判断触发 #QQ登录 的上游是否为 Karin 控制台适配器。
+* Console 适配器无法直接在聊天窗口展示二维码图片，因此需要额外打印终端二维码。
+*/
+const isConsoleAdapter = (bot) => {
+	const selfId = String(bot.selfId || "").toLowerCase();
+	const name = String(bot.adapter.name || "").toLowerCase();
+	const protocol = String(bot.adapter.protocol || "").toLowerCase();
+	return selfId === "console" || name === "console" || name.endsWith("/console") || protocol === "console";
+};
+/**
+* 记录一次回复返回的消息 ID，便于扫码流程结束后清理二维码、链接等临时信息。
+* @param result 回复返回值。
+* @param messageIds 已登记的消息 ID 集合。
+*/
+const trackReply = (result, messageIds) => {
+	const messageId = result?.messageId;
+	if (messageId && !messageIds.includes(messageId)) messageIds.push(messageId);
+};
+/**
+* 撤回扫码流程中发出的临时消息。
+* @param bot 触发登录的机器人实例。
+* @param contact 回复所在会话。
+* @param messageIds 需要撤回的消息 ID。
+*/
+const recallTrackedReplies = async (bot, contact, messageIds) => {
+	for (const messageId of messageIds) try {
+		await bot.recallMsg(contact, messageId);
+	} catch (err) {
+		log("warn", `[扫码登录] 撤回临时消息失败: ${messageId}`, err);
+	}
+	messageIds.length = 0;
+};
+const qqLogin = karin.command(/^#(?:qq登录|qqlogin)$/i, async (e) => {
 	if (busy) {
 		await e.reply("已有扫码授权在进行中，请稍候再试");
 		return;
 	}
 	busy = true;
+	const messageIds = [];
+	/**
+	* 发送并登记扫码流程的临时回复。
+	* @param elements 回复内容。
+	*/
+	const replyAndTrack = async (elements) => {
+		const result = await e.reply(elements);
+		trackReply(result, messageIds);
+		return result;
+	};
 	try {
-		await e.reply([segment.text("已开始 QQ 扫码登录授权\n⚠ 扫码完成会刷新该机器人的 secret，旧 secret 立即失效")]);
+		await replyAndTrack([segment.text("已开始 QQ 扫码登录授权\n⚠ 扫码完成会刷新该机器人的 secret，旧 secret 立即失效")]);
 		log("info", `[扫码登录] 由用户 ${e.userId} 触发`);
-		if (await runQrOnboard({ onQr: async ({ base64, url, refresh }) => {
-			const head = refresh === 0 ? "请使用手机 QQ 扫描二维码完成授权（二维码 60s 内有效，过期会自动刷新最多 3 次）：" : `上一张二维码已过期，已自动刷新（第 ${refresh}/3 次，仍为 60s 有效期）：`;
-			try {
-				await e.reply([
-					segment.text(head),
-					segment.image(base64),
-					segment.text(`或在手机 QQ 打开链接：\n${url}`)
-				]);
-			} catch (err) {
-				log("warn", "[扫码登录] 推送二维码失败:", err);
+		const ok = await runQrOnboard({
+			printTerminal: isConsoleAdapter(e.bot),
+			onQr: async ({ base64, url, refresh }) => {
+				const head = refresh === 0 ? "请使用手机 QQ 扫描二维码完成授权（二维码 60s 内有效，过期会自动刷新最多 3 次）：" : `上一张二维码已过期，已自动刷新（第 ${refresh}/3 次，仍为 60s 有效期）：`;
+				try {
+					await replyAndTrack([
+						segment.text(head),
+						segment.image(base64),
+						segment.text(`或在手机 QQ 打开链接：\n${url}`)
+					]);
+				} catch (err) {
+					log("warn", "[扫码登录] 推送二维码失败:", err);
+				}
 			}
-		} })) await e.reply("扫码授权成功，配置已保存，QQBot 实例正在初始化…");
+		});
+		await recallTrackedReplies(e.bot, e.contact, messageIds);
+		if (ok) await e.reply("扫码授权成功，配置已保存，QQBot 实例正在初始化…");
 		else await e.reply("扫码授权失败或超时，请重试 #QQ登录");
 	} catch (err) {
 		log("error", "[扫码登录] 异常:", err);
+		await recallTrackedReplies(e.bot, e.contact, messageIds);
 		await e.reply("扫码授权过程中发生异常，详情见服务端日志");
 	} finally {
 		busy = false;

package/dist/common-by1GpV0b.js

@@ -0,0 +1,49 @@
+import { common, logger } from "node-karin";
+import qrcode from "qrcode";
+import size from "image-size";
+import lodash from "node-karin/lodash";
+import GetUrls from "@karinjs/geturls";
+
+//#region src/utils/common.ts
+/** 睡眠 */
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** 随机数 */
+const random = (min, max) => lodash.random(min, max);
+/**
+* 伪事件日志（红字）
+*/
+const fakeEvent = (log) => {
+	logger.fatal(`${logger.red("[QQ Official Bot][虚假事件]")} ${log.replace(/\n/g, "\\n")}`);
+};
+/**
+* 提取文本中的 URL 列表
+* 中文不符合 URL 规范，先替换为 `|` 再扫描
+*/
+const handleUrl = (text, exclude = []) => {
+	const cleaned = text.replace(/[一-龥]/g, "|");
+	return GetUrls.getUrls(cleaned, {
+		exclude,
+		stripWWW: false,
+		normalizeProtocol: false,
+		removeQueryParameters: false,
+		removeSingleSlash: false,
+		sortQueryParameters: false,
+		stripAuthentication: false,
+		stripTextFragment: false,
+		removeTrailingSlash: false,
+		normalize: false
+	});
+};
+/**
+* 读取图片宽高
+*/
+const getImageSize = async (url) => {
+	const { width = 100, height = 100 } = size(await common.buffer(url));
+	return {
+		width,
+		height
+	};
+};
+
+//#endregion
+export { sleep as a, random as i, getImageSize as n, handleUrl as r, fakeEvent as t };