@zhin.js/adapter-icqq 1.1.17 → 1.1.18

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # @zhin.js/adapter-icqq
 
+## 1.1.18
+
+### Patch Changes
+
+- 6345a38: feat(adapters): add per-adapter Console pages
+
+  Every platform adapter now ships a `pages/index` Console page backed by a shared
+  `createAdapterConsolePage` component and `createAdapterConsoleRpc` server helper:
+
+  - See running endpoints, test connectivity, and manage
+    `plugins.<adapter>.endpoints` (add/remove writes `.env` references) from the
+    Console instead of chat commands.
+  - Surface LoginAssist pending tasks (QR / slider / SMS / device) so ICQQ login no
+    longer requires the terminal.
+  - QQ moves its QR binding flow (`qq endpoint add`) into Console actions with
+    public/private selection.
+  - Pages are permission-gated by `<adapter>:read`; writes need `<adapter>:write`.
+
+- ff3efe7: feat(adapters): notify masters when ICQQ or QQ goes offline and support ICQQ re-login
+
+  - Add an explicit `notify` target to ICQQ and QQ endpoint config: when the
+    transport goes offline or login fails, send a short notice through another
+    adapter instance's Endpoint via `OutboundHost`.
+  - ICQQ automatically retries login after `system.offline.kickoff` when
+    `autoReconnect` is enabled, and exposes pending QR/slider/device challenges.
+  - Add `icqq login status|qr|confirm|code|retry` recovery commands. They can be
+    invoked from the QQ conversation that received the notice; `qr` returns the
+    login QR code as an image when the notifying platform supports it.
+  - `notify.id` also counts as the master identity for the related endpoint
+    management commands, so recovery can happen from the notified conversation.
+  - Document the new config and commands in the ICQQ/QQ READMEs and generated
+    configuration reference.
+
+- c58c589: Group deferred tools by their canonical plugin or MCP server instead of installation paths. Omit already represented delivered text and ledger facts only from the current model projection, preserving full history and restoring facts when their covering reply leaves the active context. Allow tools to declare a synchronous, read-only availability predicate before turn disclosure, with execution-time checks remaining authoritative.
+
+  Preserve every confirmed platform message identity across Agent replies and ICQQ split sends. Give each bubble its own stable single-message alias while retaining the reply's ordered association; preserve confirmed prefixes on partial delivery without retrying or inventing unknown message IDs.
+
+- Updated dependencies [6345a38]
+- Updated dependencies [ff3efe7]
+- Updated dependencies [c58c589]
+  - @zhin.js/adapter@1.1.25
+  - @zhin.js/client@1.1.21
+  - @zhin.js/core@1.1.53
+  - @zhin.js/im-contract@1.1.9
+  - @zhin.js/tool@1.1.12
+
 ## 1.1.17
 
 ### Patch Changes

package/README.md

@@ -173,6 +173,47 @@ ICQQ Agent 可按需加载 `icqq-conversation` 查询当前群／频道和 Bot
 
 `icqq-group-admin` 新增撤回他人消息与退群：前者保留群管发起权限、实时平台角色检查，无需逐次审批；退群仅主人可发起、每次审批，Bot 为群主时拒绝执行。引用／转发走统一发送链路，不支持跨会话转发。当前 guild-channel 接入仅提供身份查询，不能使用这些群／私聊操作。详见 [权限与能力说明](./PERMITS.md)。
 
+## Console 页面
+
+启动后打开 Console 的「ICQQ」页（地址 `/icqq`），可以：
+
+- 查看运行中的连接、点「测试连接」做连通性诊断；
+- 增删 `plugins.icqq.endpoints`（凭据写入 `.env`，配置里只保留 `${ENV}` 引用）；
+- 处理登录待办（扫码 / 滑块 / 设备确认等，来自 LoginAssist）；
+
+ICQQ 首次登录的二维码、滑块、设备确认会出现在「登录待办」里，不需要再回到终端确认。
+
+读取需要 `icqq:read`，写操作需要 `icqq:write`；管理员 full token 不受限。页面里的「添加 endpoint」等价于原来的 `icqq endpoint add`。
+
+## 掉线通知与重新登录
+
+配置 `notify` 后，ICQQ 被踢下线、登录失败或启动失败时，会通过另一个适配器实例给 master 发通知。例如用 QQ 官方机器人实例通知：
+
+```yaml
+qq:
+  # ... 已配置好的 QQ 官方机器人
+icqq:
+  master: 123456
+  autoReconnect: true   # 默认 true：被踢下线后自动重新登录
+  notify:
+    adapter: qq
+    endpoint: bot-1
+    kind: private
+    id: "${QQ_MASTER_OPENID}"   # master 在 QQ 官方机器人里的 openid
+```
+
+`autoReconnect: true` 时，被踢下线会自动重试登录；二维码/滑块/设备确认就绪后，通知会提示下一步。收到通知后可以直接在 QQ 里完成：
+
+| 命令 | 作用 |
+|------|------|
+| `icqq login qr` | 把 ICQQ 登录二维码发到当前会话（QQ 支持图片时） |
+| `icqq login confirm` | 扫码后确认继续登录 |
+| `icqq login code <内容>` | 提交滑块 ticket、短信验证码或设备确认内容 |
+| `icqq login status` | 查看在线状态与登录待办 |
+| `icqq login retry` | 强制重新触发登录 |
+
+命令只接受 master（顶层或 `endpoints[i].master`）或 `notify.id` 对应账号；两者都没配置时请用 Console 的 ICQQ 页面。没有配置 `notify` 时，掉线只写日志并在 Console 显示登录待办。
+
 ## 故障排查
 
 | 现象 | 排查 |
@@ -190,14 +231,14 @@ MIT
 
 发送成功回执只接受平台真实消息 ID。网络超时、断线、缺少消息 ID 的响应会报告 `deliveryUnknown`，框架不会自动重发；手动重发可能重复发送。
 
-ICQQ 原生分享和文件 API 可能已经成功，但只返回空值或文件 ID；这类结果不能当作可引用、可撤回的消息 ID。群聊和私聊的分享卡片发出后，适配器会读一次会话记录，找到机器人自己刚发出的卡片消息，用它的真实消息 ID 作为回执（记录有延迟时半秒后再读一次）。找不到时（以及临时会话、频道和文件）仍报告投递结果未知，不编造 ID。平台操作仍只执行一次。文件撤回应使用平台专用文件 API。
+ICQQ 原生分享和文件 API 可能已经成功，但只返回空值或文件 ID；这类结果不能当作可引用、可撤回的消息 ID。适配器不会根据时间和卡片类型从历史猜测本次分享的 ID；同一时刻的其他卡片也可能匹配。没有直接消息 ID 的部分保留为未知，平台操作仍只执行一次。文件撤回应使用平台专用文件 API。
 
 ### 独立元素按顺序拆分发送
 
 ICQQ 要求分享、文件、语音、视频、JSON 卡片和合并转发单独成条。一条消息里同时有文字和这些元素时（例如 Agent 回复“找到了：”加一张音乐分享卡片），适配器按原顺序拆成多条依次发送，引用只附在第一条普通消息上。
 
-- 回执的消息 ID 取第一条拿到 ID 的部分；所有部分都没有 ID（如单独一张分享）时，仍报告投递结果未知。
-- 第一条就失败时原样报告失败；后面的部分失败时报告 `partial_delivery`（结果未知），因为前面的部分已经送达，重发会重复。
+- 回执按发送顺序保留每部分的真实 ID 和原始段位置；没有 ID 的卡片或文件保留未知槽位，不把完整回复正文复制给每个 ID。所有部分都没有 ID（如单独一张分享）时，仍报告投递结果未知。
+- 第一条就失败时原样报告失败；后面的部分失败时报告 `partial_delivery`（结果未知），保留已完成部分的回执。前面的调用可能已被平台接收，重发可能重复。
 
 ## 语言
 

package/adapters/icqq/index.js

@@ -3,10 +3,12 @@ import { projectLocaleToken } from 'zhin.js/i18n';
 /**
  * Convention entry: discover `adapters/icqq/index.ts` → defineAdapter.
  */
-import { defineAdapter } from 'zhin.js/adapter';
+import { createAdapterOutageNotifier, defineAdapter } from 'zhin.js/adapter';
 import { loginAssistToken } from '@zhin.js/core/runtime';
+import { outboundHostToken } from 'zhin.js';
 import { IcqqEndpoint } from "../../lib/endpoint.js";
 import { icqqRuntimeStateToken } from "../../lib/icqq-runtime-state.js";
+import { icqqLoginControlToken } from "../../lib/icqq-login-control.js";
 import { resolveIcqqConfig, } from "../../lib/protocol.js";
 export { IcqqEndpoint } from "../../lib/endpoint.js";
 export default defineAdapter({
@@ -44,11 +46,17 @@ export default defineAdapter({
             id: config.id,
             mode: 'direct',
         });
-        return new IcqqEndpoint({
+        const outbound = context.has?.(outboundHostToken) ? context.use(outboundHostToken) : undefined;
+        const endpoint = new IcqqEndpoint({
             id: context.id,
             loginAssist: context.use(loginAssistToken),
             locale: context.use(projectLocaleToken),
             config,
+            notifier: createAdapterOutageNotifier(outbound, config.notify),
         });
+        if (context.has?.(icqqLoginControlToken)) {
+            context.use(icqqLoginControlToken).set(config.id, endpoint.loginControl);
+        }
+        return endpoint;
     },
 });

package/adapters/icqq/index.ts

@@ -2,10 +2,12 @@ import { projectLocaleToken } from 'zhin.js/i18n';
 /**
  * Convention entry: discover `adapters/icqq/index.ts` → defineAdapter.
  */
-import { defineAdapter } from 'zhin.js/adapter';
+import { createAdapterOutageNotifier, defineAdapter } from 'zhin.js/adapter';
 import { loginAssistToken } from '@zhin.js/core/runtime';
+import { outboundHostToken } from 'zhin.js';
 import { IcqqEndpoint } from '../../src/endpoint.js';
 import { icqqRuntimeStateToken } from '../../src/icqq-runtime-state.js';
+import { icqqLoginControlToken } from '../../src/icqq-login-control.js';
 import {
   resolveIcqqConfig,
   type IcqqEndpointConfig,
@@ -55,11 +57,17 @@ export default defineAdapter<IcqqEndpointConfig>({
       id: config.id,
       mode: 'direct',
     });
-    return new IcqqEndpoint({
+    const outbound = context.has?.(outboundHostToken) ? context.use(outboundHostToken) : undefined;
+    const endpoint = new IcqqEndpoint({
       id: context.id,
       loginAssist: context.use(loginAssistToken),
       locale: context.use(projectLocaleToken),
       config,
+      notifier: createAdapterOutageNotifier(outbound, config.notify),
     });
+    if (context.has?.(icqqLoginControlToken)) {
+      context.use(icqqLoginControlToken).set(config.id, endpoint.loginControl);
+    }
+    return endpoint;
   },
 });

package/commands/icqq/login/code/index.js

@@ -0,0 +1,28 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from 'zhin.js/command';
+import { icqqLoginControlToken, icqqLoginForbidden, isIcqqLoginOperator, pendingTaskLabel, pickIcqqLoginControl, } from '../definition.js';
+export default defineCommand({
+    description: '提交 ICQQ 滑块/短信/设备验证内容',
+    descriptionI18n: { en: 'Submit an ICQQ slider, SMS or device verification value' },
+    async execute({ args, config, input, use }) {
+        if (!isIcqqLoginOperator(config, input))
+            return icqqLoginForbidden();
+        const controls = use(icqqLoginControlToken);
+        // One endpoint: the whole argument is the code. Multiple: first arg selects the UIN.
+        const requested = controls.size > 1 ? args[0] : undefined;
+        const value = (controls.size > 1 ? args.slice(1) : args).join(' ').trim();
+        const picked = pickIcqqLoginControl(controls, requested);
+        if (!picked.control)
+            return picked.text ?? 'ICQQ 适配器还没有启动';
+        if (!value) {
+            return '请把验证内容放在命令后面，例如 `icqq login code 123456` 或 `icqq login code <ticket>`。';
+        }
+        const task = picked.control.pending()
+            .find((item) => item.type === 'slider' || item.type === 'device' || item.type === 'sms' || item.type === 'other');
+        if (!task)
+            return '当前没有滑块/短信/设备验证待办；发送 `icqq login qr` 查看二维码。';
+        if (!picked.control.submit(task.id, value))
+            return '登录待办已失效，请重新触发 `icqq login qr`。';
+        return `已提交 ICQQ ${task.endpointKey} 的${pendingTaskLabel(task.type)}内容，正在验证。`;
+    },
+});

package/commands/icqq/login/code/index.ts

@@ -0,0 +1,30 @@
+import { defineCommand } from 'zhin.js/command';
+import {
+  icqqLoginControlToken,
+  icqqLoginForbidden,
+  isIcqqLoginOperator,
+  pendingTaskLabel,
+  pickIcqqLoginControl,
+} from '../definition.js';
+
+export default defineCommand({
+  description: '提交 ICQQ 滑块/短信/设备验证内容',
+  descriptionI18n: { en: 'Submit an ICQQ slider, SMS or device verification value' },
+  async execute({ args, config, input, use }) {
+    if (!isIcqqLoginOperator(config, input)) return icqqLoginForbidden();
+    const controls = use(icqqLoginControlToken);
+    // One endpoint: the whole argument is the code. Multiple: first arg selects the UIN.
+    const requested = controls.size > 1 ? args[0] : undefined;
+    const value = (controls.size > 1 ? args.slice(1) : args).join(' ').trim();
+    const picked = pickIcqqLoginControl(controls, requested);
+    if (!picked.control) return picked.text ?? 'ICQQ 适配器还没有启动';
+    if (!value) {
+      return '请把验证内容放在命令后面，例如 `icqq login code 123456` 或 `icqq login code <ticket>`。';
+    }
+    const task = picked.control.pending()
+      .find((item) => item.type === 'slider' || item.type === 'device' || item.type === 'sms' || item.type === 'other');
+    if (!task) return '当前没有滑块/短信/设备验证待办；发送 `icqq login qr` 查看二维码。';
+    if (!picked.control.submit(task.id, value)) return '登录待办已失效，请重新触发 `icqq login qr`。';
+    return `已提交 ICQQ ${task.endpointKey} 的${pendingTaskLabel(task.type)}内容，正在验证。`;
+  },
+});

package/commands/icqq/login/confirm/index.js

@@ -0,0 +1,20 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from 'zhin.js/command';
+import { icqqLoginControlToken, icqqLoginForbidden, isIcqqLoginOperator, pickIcqqLoginControl, } from '../definition.js';
+export default defineCommand({
+    description: '确认已完成 ICQQ 扫码登录',
+    descriptionI18n: { en: 'Confirm the ICQQ QR login was scanned' },
+    async execute({ args, config, input, use }) {
+        if (!isIcqqLoginOperator(config, input))
+            return icqqLoginForbidden();
+        const picked = pickIcqqLoginControl(use(icqqLoginControlToken), args[0]);
+        if (!picked.control)
+            return picked.text ?? 'ICQQ 适配器还没有启动';
+        const task = picked.control.pending().find((item) => item.type === 'qrcode' || item.type === 'auth');
+        if (!task)
+            return '当前没有等待确认的扫码登录；发送 `icqq login qr` 获取二维码。';
+        if (!picked.control.submit(task.id, 'ok'))
+            return '登录待办已失效，请重新发送 `icqq login qr`。';
+        return `已提交 ICQQ ${task.endpointKey} 的扫码确认，正在登录。`;
+    },
+});

package/commands/icqq/login/confirm/index.ts

@@ -0,0 +1,21 @@
+import { defineCommand } from 'zhin.js/command';
+import {
+  icqqLoginControlToken,
+  icqqLoginForbidden,
+  isIcqqLoginOperator,
+  pickIcqqLoginControl,
+} from '../definition.js';
+
+export default defineCommand({
+  description: '确认已完成 ICQQ 扫码登录',
+  descriptionI18n: { en: 'Confirm the ICQQ QR login was scanned' },
+  async execute({ args, config, input, use }) {
+    if (!isIcqqLoginOperator(config, input)) return icqqLoginForbidden();
+    const picked = pickIcqqLoginControl(use(icqqLoginControlToken), args[0]);
+    if (!picked.control) return picked.text ?? 'ICQQ 适配器还没有启动';
+    const task = picked.control.pending().find((item) => item.type === 'qrcode' || item.type === 'auth');
+    if (!task) return '当前没有等待确认的扫码登录；发送 `icqq login qr` 获取二维码。';
+    if (!picked.control.submit(task.id, 'ok')) return '登录待办已失效，请重新发送 `icqq login qr`。';
+    return `已提交 ICQQ ${task.endpointKey} 的扫码确认，正在登录。`;
+  },
+});

package/commands/icqq/login/definition.js

@@ -0,0 +1,65 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * `icqq login` recovery commands.
+ *
+ * They are registered by the ICQQ plugin but can be invoked from any connected
+ * adapter (typically the QQ instance that delivered the outage notice), so the
+ * master can fetch the QR image and confirm/send verification codes without the
+ * Console or terminal.
+ */
+import { icqqLoginControlToken } from "../../../lib/icqq-login-control.js";
+export { icqqLoginControlToken };
+/** Master = framework master(s), or the configured outage-notify conversation id(s). */
+export function isIcqqLoginOperator(config, input) {
+    const cfg = (config ?? {});
+    const masters = new Set();
+    const collect = (value) => {
+        if (value === undefined || value === null)
+            return;
+        const text = String(value).trim();
+        if (text)
+            masters.add(text);
+    };
+    collect(cfg.master);
+    collect(cfg.notify?.id);
+    if (Array.isArray(cfg.endpoints)) {
+        for (const endpoint of cfg.endpoints) {
+            collect(endpoint.master);
+            collect(endpoint.notify?.id);
+        }
+    }
+    // Login control is account-sensitive: without an explicit master/notify target,
+    // refuse chat recovery and leave it to the authenticated Console page.
+    if (masters.size === 0)
+        return false;
+    const senderRaw = input?.sender;
+    const senderId = (typeof senderRaw === 'object' && senderRaw?.id) ? String(senderRaw.id).trim() : '';
+    return senderId !== '' && masters.has(senderId);
+}
+export function pickIcqqLoginControl(controls, requested) {
+    const wanted = requested?.trim();
+    if (wanted) {
+        const control = controls.get(wanted);
+        return control ? { control } : { text: `找不到 ICQQ endpoint「${wanted}」` };
+    }
+    if (controls.size === 0)
+        return { text: 'ICQQ 适配器还没有启动' };
+    if (controls.size === 1) {
+        const control = [...controls.values()][0];
+        return control ? { control } : { text: 'ICQQ 适配器还没有启动' };
+    }
+    return { text: `有多个 ICQQ endpoint，请指定 QQ 号：${[...controls.keys()].join('、')}` };
+}
+export function icqqLoginForbidden() {
+    return '仅 master 或 notify 目标账号可以操作 ICQQ 登录';
+}
+export function pendingTaskLabel(type) {
+    switch (type) {
+        case 'qrcode': return '二维码';
+        case 'slider': return '滑块验证';
+        case 'device': return '设备确认';
+        case 'sms': return '短信验证';
+        case 'auth': return '登录确认';
+        default: return '登录验证';
+    }
+}

package/commands/icqq/login/definition.ts

@@ -0,0 +1,72 @@
+/**
+ * `icqq login` recovery commands.
+ *
+ * They are registered by the ICQQ plugin but can be invoked from any connected
+ * adapter (typically the QQ instance that delivered the outage notice), so the
+ * master can fetch the QR image and confirm/send verification codes without the
+ * Console or terminal.
+ */
+import { icqqLoginControlToken, type IcqqLoginControl } from '../../../src/icqq-login-control.js';
+
+export { icqqLoginControlToken };
+
+/** Master = framework master(s), or the configured outage-notify conversation id(s). */
+export function isIcqqLoginOperator(config: unknown, input: unknown): boolean {
+  const cfg = (config ?? {}) as {
+    master?: unknown;
+    notify?: { id?: unknown };
+    endpoints?: readonly { master?: unknown; notify?: { id?: unknown } }[];
+  };
+  const masters = new Set<string>();
+  const collect = (value: unknown) => {
+    if (value === undefined || value === null) return;
+    const text = String(value).trim();
+    if (text) masters.add(text);
+  };
+  collect(cfg.master);
+  collect(cfg.notify?.id);
+  if (Array.isArray(cfg.endpoints)) {
+    for (const endpoint of cfg.endpoints) {
+      collect(endpoint.master);
+      collect(endpoint.notify?.id);
+    }
+  }
+  // Login control is account-sensitive: without an explicit master/notify target,
+  // refuse chat recovery and leave it to the authenticated Console page.
+  if (masters.size === 0) return false;
+  const senderRaw = (input as { sender?: { id?: unknown } } | null | undefined)?.sender;
+  const senderId = (typeof senderRaw === 'object' && senderRaw?.id) ? String(senderRaw.id).trim() : '';
+  return senderId !== '' && masters.has(senderId);
+}
+
+export function pickIcqqLoginControl(
+  controls: ReadonlyMap<string, IcqqLoginControl>,
+  requested?: string,
+): { control?: IcqqLoginControl; text?: string } {
+  const wanted = requested?.trim();
+  if (wanted) {
+    const control = controls.get(wanted);
+    return control ? { control } : { text: `找不到 ICQQ endpoint「${wanted}」` };
+  }
+  if (controls.size === 0) return { text: 'ICQQ 适配器还没有启动' };
+  if (controls.size === 1) {
+    const control = [...controls.values()][0];
+    return control ? { control } : { text: 'ICQQ 适配器还没有启动' };
+  }
+  return { text: `有多个 ICQQ endpoint，请指定 QQ 号：${[...controls.keys()].join('、')}` };
+}
+
+export function icqqLoginForbidden(): string {
+  return '仅 master 或 notify 目标账号可以操作 ICQQ 登录';
+}
+
+export function pendingTaskLabel(type: string): string {
+  switch (type) {
+    case 'qrcode': return '二维码';
+    case 'slider': return '滑块验证';
+    case 'device': return '设备确认';
+    case 'sms': return '短信验证';
+    case 'auth': return '登录确认';
+    default: return '登录验证';
+  }
+}

package/commands/icqq/login/qr/index.js

@@ -0,0 +1,53 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from 'zhin.js/command';
+import { icqqLoginControlToken, icqqLoginForbidden, isIcqqLoginOperator, pickIcqqLoginControl, } from '../definition.js';
+const QR_IMAGE = /^data:image\/[a-z0-9.+-]+;base64,(.+)$/iu;
+export default defineCommand({
+    description: '获取 ICQQ 登录二维码（发给当前会话）',
+    descriptionI18n: { en: 'Fetch the ICQQ login QR code into this conversation' },
+    async execute({ args, config, input, use }) {
+        if (!isIcqqLoginOperator(config, input))
+            return icqqLoginForbidden();
+        const picked = pickIcqqLoginControl(use(icqqLoginControlToken), args[0]);
+        if (!picked.control)
+            return picked.text ?? 'ICQQ 适配器还没有启动';
+        const control = picked.control;
+        const findQr = () => control.pending().find((task) => task.type === 'qrcode' || task.type === 'auth');
+        let task = findQr();
+        if (!task) {
+            const other = control.pending().find((item) => item.type !== 'qrcode' && item.type !== 'auth');
+            if (other) {
+                const url = typeof other.payload.url === 'string' ? other.payload.url : '';
+                return `ICQQ ${other.endpointKey} 当前是${other.type === 'slider' ? '滑块验证' : '登录验证'}，请打开 ${url || '验证页面'}，`
+                    + '完成后回复 `icqq login code <内容>`。';
+            }
+            try {
+                await control.relogin();
+            }
+            catch {
+                // The SDK may still deliver a QR challenge asynchronously.
+            }
+            task = findQr();
+            if (!task)
+                return '已触发重新登录，请 5 秒后再发送 `icqq login qr` 获取二维码。';
+        }
+        const raw = typeof task.payload.image === 'string' ? task.payload.image : '';
+        const base64 = QR_IMAGE.exec(raw)?.[1];
+        if (!base64) {
+            return `ICQQ ${task.endpointKey} 当前是 ${task.type === 'qrcode' ? '二维码' : '登录确认'}待办，但没有可发送的图片；请打开 Console 的 ICQQ 页面完成。`;
+        }
+        return [
+            {
+                type: 'text',
+                data: {
+                    text: `ICQQ ${task.endpointKey} 登录二维码（约 3 分钟有效）。\n`
+                        + '用手机 QQ 扫码，完成后回复 `icqq login confirm`。',
+                },
+            },
+            {
+                type: 'image',
+                data: { media: { kind: 'base64', value: base64, mime_type: 'image/png' } },
+            },
+        ];
+    },
+});

package/commands/icqq/login/qr/index.ts

@@ -0,0 +1,55 @@
+import { defineCommand } from 'zhin.js/command';
+import {
+  icqqLoginControlToken,
+  icqqLoginForbidden,
+  isIcqqLoginOperator,
+  pickIcqqLoginControl,
+} from '../definition.js';
+
+const QR_IMAGE = /^data:image\/[a-z0-9.+-]+;base64,(.+)$/iu;
+
+export default defineCommand({
+  description: '获取 ICQQ 登录二维码（发给当前会话）',
+  descriptionI18n: { en: 'Fetch the ICQQ login QR code into this conversation' },
+  async execute({ args, config, input, use }) {
+    if (!isIcqqLoginOperator(config, input)) return icqqLoginForbidden();
+    const picked = pickIcqqLoginControl(use(icqqLoginControlToken), args[0]);
+    if (!picked.control) return picked.text ?? 'ICQQ 适配器还没有启动';
+    const control = picked.control;
+    const findQr = () => control.pending().find((task) => task.type === 'qrcode' || task.type === 'auth');
+    let task = findQr();
+    if (!task) {
+      const other = control.pending().find((item) => item.type !== 'qrcode' && item.type !== 'auth');
+      if (other) {
+        const url = typeof other.payload.url === 'string' ? other.payload.url : '';
+        return `ICQQ ${other.endpointKey} 当前是${other.type === 'slider' ? '滑块验证' : '登录验证'}，请打开 ${url || '验证页面'}，`
+          + '完成后回复 `icqq login code <内容>`。';
+      }
+      try {
+        await control.relogin();
+      } catch {
+        // The SDK may still deliver a QR challenge asynchronously.
+      }
+      task = findQr();
+      if (!task) return '已触发重新登录，请 5 秒后再发送 `icqq login qr` 获取二维码。';
+    }
+    const raw = typeof task.payload.image === 'string' ? task.payload.image : '';
+    const base64 = QR_IMAGE.exec(raw)?.[1];
+    if (!base64) {
+      return `ICQQ ${task.endpointKey} 当前是 ${task.type === 'qrcode' ? '二维码' : '登录确认'}待办，但没有可发送的图片；请打开 Console 的 ICQQ 页面完成。`;
+    }
+    return [
+      {
+        type: 'text',
+        data: {
+          text: `ICQQ ${task.endpointKey} 登录二维码（约 3 分钟有效）。\n`
+            + '用手机 QQ 扫码，完成后回复 `icqq login confirm`。',
+        },
+      },
+      {
+        type: 'image',
+        data: { media: { kind: 'base64', value: base64, mime_type: 'image/png' } },
+      },
+    ];
+  },
+});

package/commands/icqq/login/retry/index.js

@@ -0,0 +1,21 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from 'zhin.js/command';
+import { icqqLoginControlToken, icqqLoginForbidden, isIcqqLoginOperator, pickIcqqLoginControl, } from '../definition.js';
+export default defineCommand({
+    description: '重新触发 ICQQ 登录',
+    descriptionI18n: { en: 'Trigger an ICQQ login attempt again' },
+    async execute({ args, config, input, use }) {
+        if (!isIcqqLoginOperator(config, input))
+            return icqqLoginForbidden();
+        const picked = pickIcqqLoginControl(use(icqqLoginControlToken), args[0]);
+        if (!picked.control)
+            return picked.text ?? 'ICQQ 适配器还没有启动';
+        try {
+            await picked.control.relogin();
+            return `已触发 ICQQ ${picked.control.endpointId} 重新登录；需要扫码时发送 \`icqq login qr\`。`;
+        }
+        catch {
+            return `ICQQ ${picked.control.endpointId} 重新登录失败，请稍后重试或查看日志。`;
+        }
+    },
+});

package/commands/icqq/login/retry/index.ts

@@ -0,0 +1,23 @@
+import { defineCommand } from 'zhin.js/command';
+import {
+  icqqLoginControlToken,
+  icqqLoginForbidden,
+  isIcqqLoginOperator,
+  pickIcqqLoginControl,
+} from '../definition.js';
+
+export default defineCommand({
+  description: '重新触发 ICQQ 登录',
+  descriptionI18n: { en: 'Trigger an ICQQ login attempt again' },
+  async execute({ args, config, input, use }) {
+    if (!isIcqqLoginOperator(config, input)) return icqqLoginForbidden();
+    const picked = pickIcqqLoginControl(use(icqqLoginControlToken), args[0]);
+    if (!picked.control) return picked.text ?? 'ICQQ 适配器还没有启动';
+    try {
+      await picked.control.relogin();
+      return `已触发 ICQQ ${picked.control.endpointId} 重新登录；需要扫码时发送 \`icqq login qr\`。`;
+    } catch {
+      return `ICQQ ${picked.control.endpointId} 重新登录失败，请稍后重试或查看日志。`;
+    }
+  },
+});

package/commands/icqq/login/status/index.js

@@ -0,0 +1,31 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from 'zhin.js/command';
+import { icqqLoginControlToken, icqqLoginForbidden, isIcqqLoginOperator, pendingTaskLabel, pickIcqqLoginControl, } from '../definition.js';
+export default defineCommand({
+    description: '查看 ICQQ 掉线状态与登录待办',
+    descriptionI18n: { en: 'Show ICQQ offline status and pending login tasks' },
+    async execute({ args, config, input, use }) {
+        if (!isIcqqLoginOperator(config, input))
+            return icqqLoginForbidden();
+        const picked = pickIcqqLoginControl(use(icqqLoginControlToken), args[0]);
+        if (!picked.control)
+            return picked.text ?? 'ICQQ 适配器还没有启动';
+        const state = picked.control.state();
+        const lines = [
+            `ICQQ ${state.endpointId}: ${state.online ? '在线' : '离线'}（${state.transportState}）`,
+        ];
+        if (state.pending.length === 0) {
+            lines.push('没有待处理的登录验证。');
+        }
+        else {
+            lines.push('待处理：');
+            for (const task of state.pending) {
+                const url = typeof task.payload.url === 'string' ? task.payload.url : undefined;
+                lines.push(`- ${pendingTaskLabel(task.type)}（${task.id}，endpoint ${task.endpointKey}）`
+                    + (url ? `：${url}` : ''));
+            }
+            lines.push('二维码：`icqq login qr`；完成扫码后：`icqq login confirm`；滑块/短信：`icqq login code <内容>`。');
+        }
+        return lines.join('\n');
+    },
+});

package/commands/icqq/login/status/index.ts

@@ -0,0 +1,34 @@
+import { defineCommand } from 'zhin.js/command';
+import {
+  icqqLoginControlToken,
+  icqqLoginForbidden,
+  isIcqqLoginOperator,
+  pendingTaskLabel,
+  pickIcqqLoginControl,
+} from '../definition.js';
+
+export default defineCommand({
+  description: '查看 ICQQ 掉线状态与登录待办',
+  descriptionI18n: { en: 'Show ICQQ offline status and pending login tasks' },
+  async execute({ args, config, input, use }) {
+    if (!isIcqqLoginOperator(config, input)) return icqqLoginForbidden();
+    const picked = pickIcqqLoginControl(use(icqqLoginControlToken), args[0]);
+    if (!picked.control) return picked.text ?? 'ICQQ 适配器还没有启动';
+    const state = picked.control.state();
+    const lines = [
+      `ICQQ ${state.endpointId}: ${state.online ? '在线' : '离线'}（${state.transportState}）`,
+    ];
+    if (state.pending.length === 0) {
+      lines.push('没有待处理的登录验证。');
+    } else {
+      lines.push('待处理：');
+      for (const task of state.pending) {
+        const url = typeof task.payload.url === 'string' ? task.payload.url : undefined;
+        lines.push(`- ${pendingTaskLabel(task.type)}（${task.id}，endpoint ${task.endpointKey}）`
+          + (url ? `：${url}` : ''));
+      }
+      lines.push('二维码：`icqq login qr`；完成扫码后：`icqq login confirm`；滑块/短信：`icqq login code <内容>`。');
+    }
+    return lines.join('\n');
+  },
+});