@zhin.js/adapter-icqq 1.1.16 → 1.1.18

package/agents/icqq/system.md

@@ -1,7 +1,7 @@
 # ICQQ Platform Agent
 
-You are the icqq platform specialist. Interpret requests in the current icqq conversation and load only the narrowest private Skill needed for the task.
+You are the icqq platform specialist. Interpret requests in the current icqq conversation and load only the narrowest available Skill needed for the task.
 
-For your own group/guild role, current scene information or platform permissions, load `icqq-conversation` and query `conversation_info`. Sender roles describe the requester, not you. Do not infer your role from old session summaries or another endpoint account.
+Use the current Bot snapshot for your platform role. Load `icqq-conversation` and query `conversation_info` when the role is unknown or you need more scene or permission details. Sender roles describe the requester, not you. Do not infer your role from old session summaries or another endpoint account.
 
-For quoting, forwarding or recalling your own speech, load `icqq-messages`. Your own-message recall needs no group management role or per-call approval. For recalling another member's message or leaving a group, load `icqq-group-admin` and follow the tool-specific rules; only leaving requires fresh approval. All these message tools are restricted to the current conversation. Guild-channel limitations are explicit in `conversation_info`.
+Discover message and management operations from the current scene's Skill catalog; follow each tool's target, platform and approval rules. Recalling your own messages needs no group management role or per-call approval. Leaving a group requires fresh approval and is forbidden when you own the group. Do not load a Skill that is absent from the current catalog.

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');
+  },
+});

package/lib/console-spec.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ICQQ Console 页面元数据（浏览器与服务端共享；不要在这里 import 服务端代码）。
+ */
+import type { AdapterConsoleField } from 'zhin.js/adapter';
+export declare const icqqConsoleSpec: {
+    readonly adapterKey: "icqq";
+    readonly adapterDisplayName: "ICQQ";
+    readonly fields: readonly AdapterConsoleField[];
+    readonly docsUrl: "https://zhin.js.org/adapters/icqq";
+    readonly readPermission: "icqq:read";
+    readonly writePermission: "icqq:write";
+    readonly idPattern: RegExp;
+    readonly idHint: "ICQQ endpoint id 是 QQ 号（纯数字）";
+    readonly idHintI18n: {
+        readonly en: "ICQQ endpoint ID is the QQ number (digits only)";
+    };
+};

package/lib/console-spec.js

@@ -0,0 +1,11 @@
+export const icqqConsoleSpec = {
+    adapterKey: 'icqq',
+    adapterDisplayName: 'ICQQ',
+    fields: [],
+    docsUrl: 'https://zhin.js.org/adapters/icqq',
+    readPermission: 'icqq:read',
+    writePermission: 'icqq:write',
+    idPattern: /^\d+$/,
+    idHint: 'ICQQ endpoint id 是 QQ 号（纯数字）',
+    idHintI18n: { en: 'ICQQ endpoint ID is the QQ number (digits only)' },
+};

package/lib/console.d.ts

@@ -0,0 +1,8 @@
+/**
+ * ICQQ Console RPC：运行状态 + endpoint 增删（原 `icqq endpoint` 聊天命令）。
+ *
+ * 页面绑定 `pages/index`，读取 / 写入分别要求 `<adapter>:read` / `<adapter>:write`。
+ */
+import { type AdapterConsoleResources } from 'zhin.js/adapter';
+import type { PluginConsoleRpc } from 'zhin.js';
+export declare function createIcqqConsoleRpc(resources: AdapterConsoleResources, getConfig: () => unknown): PluginConsoleRpc;

package/lib/console.js

@@ -0,0 +1,16 @@
+/**
+ * ICQQ Console RPC：运行状态 + endpoint 增删（原 `icqq endpoint` 聊天命令）。
+ *
+ * 页面绑定 `pages/index`，读取 / 写入分别要求 `<adapter>:read` / `<adapter>:write`。
+ */
+import { createAdapterConsoleRpc } from 'zhin.js/adapter';
+import { icqqRuntimeStateToken } from './icqq-runtime-state.js';
+import { icqqConsoleSpec } from './console-spec.js';
+export function createIcqqConsoleRpc(resources, getConfig) {
+    const state = resources.use(icqqRuntimeStateToken);
+    return createAdapterConsoleRpc({
+        ...icqqConsoleSpec,
+        running: () => state.endpoints.values(),
+        getConfig,
+    }, resources);
+}

package/lib/endpoint.d.ts

@@ -1,8 +1,10 @@
 import { Client } from '@icqqjs/icqq';
-import { Endpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest, type EndpointTransportState } from 'zhin.js/adapter';
+import { Endpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest, type EndpointTransportState, type AdapterOutageNotifier } from 'zhin.js/adapter';
 import type { EndpointContentPort } from '@zhin.js/adapter';
 import { type LoginAssist } from '@zhin.js/core';
+import { type EndpointSendResult } from '@zhin.js/im-contract';
 import type { CapabilityId } from 'zhin.js';
+import type { IcqqLoginControl } from './icqq-login-control.js';
 import { type IcqqInboundMessage, type ResolvedIcqqConfig } from './protocol.js';
 import { ManagedIcqqClient } from './managed-client.js';
 export interface IcqqEndpointOptions {
@@ -10,20 +12,25 @@ export interface IcqqEndpointOptions {
     readonly config: ResolvedIcqqConfig;
     readonly loginAssist: LoginAssist;
     readonly locale?: import('zhin.js/i18n').Locale;
+    /** Out-of-band outage notifier; absent in tests/hosts without outbound. */
+    readonly notifier?: AdapterOutageNotifier;
 }
 export declare class IcqqEndpoint extends Endpoint<Client> {
     #private;
     readonly client: ManagedIcqqClient;
     readonly endpointName: string;
     readonly content: EndpointContentPort;
+    readonly loginControl: IcqqLoginControl;
     readonly management: EndpointManagement;
     readonly control: EndpointControl;
     constructor(options: IcqqEndpointOptions);
+    /** Force a login attempt (manual recovery command). */
+    relogin(): Promise<void>;
     get transportState(): EndpointTransportState;
     start(signal: AbortSignal): Promise<void>;
     open(): void;
     close(): Promise<void>;
     stop(): Promise<void>;
-    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<EndpointSendResult>;
     admit(msg: IcqqInboundMessage): Promise<void>;
 }