@zhin.js/adapter-icqq 1.1.17 → 1.1.19

package/CHANGELOG.md

@@ -1,5 +1,88 @@
 # @zhin.js/adapter-icqq
 
+## 1.1.19
+
+### Patch Changes
+
+- 2c3610a: Move account lifecycle ownership into the generic Adapter base and let native Endpoints retain their SDK Client inheritance. Infer platform-specific operation Sessions from a single adapter registry while preserving command parameter, option, configuration and factory inference.
+
+  Bind message replies, management ports, login challenges and Agent cancellation to the captured account incarnation. Persist runtime account intent with encrypted, revision-checked Host storage; keep account management independent of Root process restarts. Require explicit operator confirmation before importing existing accounts, and give replacement accounts a new identity without inheriting previous Sessions.
+
+  Expose account save, start, stop, update and replacement through the existing adapter Console, with exact account ownership, truthful pending/unknown outcomes and no startup configuration or environment-file rewrites.
+
+  Complete the target migration across every adapter, the public authoring API, generators, examples and Console. This intentionally removes the old create factory, inheritable Endpoint/ClientEndpoint classes, Client descriptors and file-rewrite account management; plugin authors must use createAdapter, native Client inheritance and the single AdapterRegistry. Satori and OneBot12 require explicit platform/userId selection, and WeCom requires a separate agentId.
+
+  Verify opaque credential changes before the same configuration snapshot is committed. Drain admitted native callbacks across close/rollback, cancel target work on stop, and keep raw transport parsing, platform ACK timing and SDK native methods under their existing owners. Account metadata conceals credentials carried in URLs.
+
+- a9f4e48: PATCH COMPATIBILITY CUTOVER: this batch intentionally changes plugin APIs. The maintainer explicitly chose patch releases with declared version boundaries. Upgrade the complete tested dependency set; patch numbering does not promise compatibility with the removed interfaces.
+
+  The first planned floors are zhin.js 1.1.19, Core 1.1.54, Adapter 1.1.26, FeatureKit 1.1.10, Plugin Runtime 1.1.18, Runtime/Isolate 1.1.16 and Agent 1.1.45. Keep old-interface plugins with the earlier locked stack until they are migrated. Adapter's independent Feature API changes from 1.0.0 to 2.0.0; official consumers declare ^2.0.0. Existing Feature API admission rejects explicitly incompatible ranges; omitted API metadata keeps its existing behavior and does not certify compatibility. Runtime engine and patch-only release gates remain unchanged.
+
+  Use the native-Client Adapter target contract, canonical FeatureKit AdapterRegistry augmentation and named Endpoint control/management requests. Route message controls from canonical message/conversation refs; retain exact source authority and propagate caller/account/explicit-Root-stop cancellation. Replace removed Agent activity feedback exports with source-bound feedback. HMR pause/resume belongs to concrete plugin instances; plugins choose accepted-work policy without changing Controller commit/rollback authority. Cooperative worker/process control cancellation does not kill an isolate or reopen retired business admission.
+
+  Provide authenticated historical-data preview, exact selected binding, transactional application, authoritative inspection and explicit resumption, including active games. Preserve before-images and journals; never replay an unconfirmed effect, infer an account from an alias, or reuse historical permission grants. Owner V2 approvals remain inactive legacy data, while new writes use V3. Rollback requires matching software, lockfile and verified data; installing old code alone cannot read a new V3 approval file. Conflicting after-images are never overwritten.
+
+  See docs/plans/adapter-operation-version-boundaries.md and the Chinese/English upgrade guide for the complete version inventory, custom-plugin changes, acceptance and recovery sequence. These code and metadata changes do not authorize merging, publication, deployment, login, production migration or removal of installed workspace patches.
+
+- Updated dependencies [2c3610a]
+- Updated dependencies [a9f4e48]
+- Updated dependencies [f8505b0]
+  - @zhin.js/adapter@1.1.26
+  - @zhin.js/feature-kit@1.1.10
+  - @zhin.js/core@1.1.54
+  - @zhin.js/client@1.1.22
+  - @zhin.js/page@1.1.11
+  - @zhin.js/agent-feature@1.1.11
+  - @zhin.js/skill@1.1.11
+  - @zhin.js/tool@1.1.13
+  - @zhin.js/permission@1.1.10
+
+## 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

@@ -5,7 +5,7 @@ ICQQ Plugin Runtime 适配器 — 进程内直接使用 [@icqqjs/icqq](https://g
 ## 功能特性
 
 - 群聊 / 私聊 / 群临时会话 / QQ 频道消息
-- 入站：ICQQ Client 原始事件经 `Endpoint.emit(...)` 唯一入口上送；文本与图片 / 语音 / 视频 / 文件统一归一为 canonical `Segment` + `MediaRef`
+- 入站：ICQQ Client 原始事件经 `endpoint[endpointSpec].events` 唯一入口上送；文本与图片 / 语音 / 视频 / 文件统一归一为 canonical `Segment` + `MediaRef`
 - 出站：canonical Segment 直接投影为 ICQQ 原生 `Sendable`，再由 `sendGroupMsg` / `sendPrivateMsg` / …发送
 - 群聊 reaction：`control.addReaction` / `removeReaction`（协议 ACK 失败不阻塞后续发送）
 - Agent 工具：按职责拆分在 `agents/icqq/skills/icqq-*/tools/`，只在对应 Skill 激活后披露
@@ -97,9 +97,9 @@ export default defineHandler({
 })
 ```
 
-`client` 就是当前账号的真实 ICQQ SDK 实例，不是 Endpoint facade。未知扩展事件可显式使用
+原生 Handler 参数中的 `client` 就是当前账号的真实 ICQQ SDK 实例，`event` 保留同一原生事件对象、原型和方法。消息操作的 `session.endpoint`、`session.event` 与 `session.adapter` 分别提供同一个实际 Endpoint、原始消息事件和所属 Adapter。未知扩展事件可显式使用
 `event: '*'`；此时 Client 类型保持完整，事件 payload 为 `unknown`。普通消息回复仍应走
-`Message.$reply`；群管理、请求审批与 ICQQ 专属查询可直接调用当前事件的 `client`。
+`Message.$reply`；群管理、请求审批与 ICQQ 专属查询可直接调用当前 Session 的 Endpoint。
 
 Command context 的 `$client` 是按需读取的 getter：
 
@@ -140,16 +140,16 @@ export default defineAgentTool({
 
 `adapter` 缺失时 `$client` 静态类型为 `unknown`；声明后若实际 operation 不属于 ICQQ，
 运行时会在执行前拒绝。Client 只能在当前 operation 内使用。task、schedule 或 Host 等脱离
-IM turn 的场景，才使用 `icqqClient.get(context, endpointId)` 显式选择账号。
+IM turn 的场景，应通过 Host 提供的显式账号作用域操作，不能缓存旧 Client 或从另一个可写目录选择账号。
 
 ## 架构
 
 - `plugin.ts` + `adapters/icqq/index.ts`：Plugin Runtime 入口与 `defineAdapter` 声明
-- `src/endpoint.ts`：组合 ICQQ `Client`，只协调账号 transport、Zhin lifecycle 与各能力端口
+- `src/endpoint.ts`：继承真实 ICQQ `Client`，只协调账号 transport、Zhin lifecycle 与各能力端口
 - `src/content-resolver.ts`：保存已观察消息，并按深度和条数限制递归展开合并转发
 - `src/icqq-inbound.ts`：把 ICQQ 原生消息归一为 Zhin 入站消息
 - `src/protocol.ts`：配置解析、会话映射与出站目标转换
-- `src/client.ts`：向插件作者暴露 ICQQ `Client` / `EventMap` 类型注册
+- `src/client.ts`：从原生 SDK 推导事件类型，并将实际 `IcqqAdapter` 注册到唯一 `AdapterRegistry`
 - Agent 工具：`agents/icqq/skills/icqq-*/tools/<name>/index.ts`；权限说明见 `PERMITS.md`
 
 阅读适配器实现时从 `endpoint.ts` 看能力装配，再进入对应能力文件。包外代码只从
@@ -163,7 +163,7 @@ IM turn 的场景，才使用 `icqqClient.get(context, endpointId)` 显式选择
 - ICQQ 的语音、视频、文件是独立消息元素；它们与其他段混发时适配器会明确拒绝，避免协议栈静默丢段。
 - 入站语音 / 视频在 Endpoint 持有原生 Client 时解析可下载 URL；解析失败则保留真实平台引用，不伪造或丢弃媒体。
 - **Console 社交/群管 RPC 已接线**：endpoint 把好友/群/群成员列表、请求审批和群管操作归一化为冻结的 `EndpointManagement`。Host 只消费该语义端口。
-- 好友/入群请求与通知：经 the unified `Endpoint.emit(...)` ingress 分发到 `handlers`（`notice.receive` / `request.receive`）；审批走 `Request.$approve` / `EndpointManagement.approveRequest`。Console `request.list` 优先读 `management.listRequests()`（`getSystemMsg`），不再写入 `unified_inbox_request/notice`。
+- 好友/入群请求与通知：经 the unified `endpoint[endpointSpec].events` ingress 分发到 `handlers`（`notice.receive` / `request.receive`）；审批走 `Request.$approve` / `EndpointManagement.approveRequest`。Console `request.list` 优先读 `management.listRequests()`（`getSystemMsg`），不再写入 `unified_inbox_request/notice`。
 - `system.*`（登录扫码等）分发到 `system.receive`。
 - **登录辅助**：`system.login.qrcode|slider|device|auth` 经 `loginAssistToken`（`LoginAssist`）挂起待办；刷新后可用 Console `login.list` / `login.submit` 或终端 stdin 继续（对齐 icqq 官方 stdin 流程）。`system.online` / `login.error` 会清理该 endpoint 待办。
 
@@ -173,6 +173,51 @@ ICQQ Agent 可按需加载 `icqq-conversation` 查询当前群／频道和 Bot
 
 `icqq-group-admin` 新增撤回他人消息与退群：前者保留群管发起权限、实时平台角色检查，无需逐次审批；退群仅主人可发起、每次审批，Bot 为群主时拒绝执行。引用／转发走统一发送链路，不支持跨会话转发。当前 guild-channel 接入仅提供身份查询，不能使用这些群／私聊操作。详见 [权限与能力说明](./PERMITS.md)。
 
+## Console 页面
+
+启动后打开 Console 的「ICQQ」页（地址 `/icqq`），可以：
+
+- 查看运行中的连接、点「测试连接」做连通性诊断；
+- 在账号库保存、修改、启动、停止、替换或删除该 Adapter 的账号；新增仅保存，不创建 SDK Client，需手动启动；
+- 处理登录待办（扫码 / 滑块 / 设备确认等，来自 LoginAssist）；
+
+ICQQ 首次登录的二维码、滑块、设备确认会出现在「登录待办」里，不需要再回到终端确认。
+
+读取需要 `icqq:read`，写操作需要 `icqq:write`；管理员 full token 不受限。页面里的「添加 endpoint」等价于原来的 `icqq endpoint add`。
+
+首次修改启动配置里的既有账号前，管理员必须核对清单并确认一次迁移。原 canonical 身份与历史保留，完整账号配置加密进入 Host 数据库；此后账号管理只写数据库，不修改启动文件或 `.env`，不重启进程。没有持久化账号端口的环境可使用静态配置连接，动态写操作明确不可用。
+
+启停意图在进程重启后恢复。停止或删除会取消并关闭目标账号的在途操作，其他账号继续运行；删除保留历史。已启动账号的连接配置更新先关闭旧 incarnation，再仅重连该账号；平台身份变化按替换处理，分配新内部身份、保留旧历史，新账号不继承旧 Session、个人设置或启动意图。提交结果未知时先刷新核实，不自动重复 CAS 或平台操作。
+
+## 掉线通知与重新登录
+
+配置 `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 +235,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

@@ -1,13 +1,10 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { projectLocaleToken } from 'zhin.js/i18n';
+import { IcqqAdapter } from "../../lib/adapter.js";
 /**
  * Convention entry: discover `adapters/icqq/index.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { loginAssistToken } from '@zhin.js/core/runtime';
-import { IcqqEndpoint } from "../../lib/endpoint.js";
-import { icqqRuntimeStateToken } from "../../lib/icqq-runtime-state.js";
-import { resolveIcqqConfig, } from "../../lib/protocol.js";
+import {} from "../../lib/protocol.js";
 export { IcqqEndpoint } from "../../lib/endpoint.js";
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
@@ -37,18 +34,5 @@ export default defineAdapter({
             },
         },
     },
-    create(context) {
-        const config = resolveIcqqConfig(context.config);
-        // 注册到插件运行时状态（icqq endpoint list 的"运行中"数据源）
-        context.use(icqqRuntimeStateToken).endpoints.set(config.id, {
-            id: config.id,
-            mode: 'direct',
-        });
-        return new IcqqEndpoint({
-            id: context.id,
-            loginAssist: context.use(loginAssistToken),
-            locale: context.use(projectLocaleToken),
-            config,
-        });
-    },
+    createAdapter: context => new IcqqAdapter(context),
 });

package/adapters/icqq/index.ts

@@ -1,25 +1,15 @@
-import { projectLocaleToken } from 'zhin.js/i18n';
+import { IcqqAdapter } from '../../src/adapter.js';
 /**
  * Convention entry: discover `adapters/icqq/index.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { loginAssistToken } from '@zhin.js/core/runtime';
-import { IcqqEndpoint } from '../../src/endpoint.js';
-import { icqqRuntimeStateToken } from '../../src/icqq-runtime-state.js';
 import {
-  resolveIcqqConfig,
   type IcqqEndpointConfig,
 } from '../../src/protocol.js';
 
 export { IcqqEndpoint } from '../../src/endpoint.js';
 export type { IcqqEndpointOptions } from '../../src/endpoint.js';
 
-declare module '@zhin.js/core' {
-  interface AdapterEndpoints {
-    icqq: import('../../src/endpoint.js').IcqqEndpoint;
-  }
-}
-
 export default defineAdapter<IcqqEndpointConfig>({
   capabilities: ['inbound', 'outbound'],
   operations: ['recall', 'reaction'],
@@ -48,18 +38,5 @@ export default defineAdapter<IcqqEndpointConfig>({
       },
     },
   },
-  create(context) {
-    const config = resolveIcqqConfig(context.config);
-    // 注册到插件运行时状态（icqq endpoint list 的"运行中"数据源）
-    context.use(icqqRuntimeStateToken).endpoints.set(config.id, {
-      id: config.id,
-      mode: 'direct',
-    });
-    return new IcqqEndpoint({
-      id: context.id,
-      loginAssist: context.use(loginAssistToken),
-      locale: context.use(projectLocaleToken),
-      config,
-    });
-  },
+  createAdapter: context => new IcqqAdapter(context),
 });

package/commands/icqq/endpoint/definition.js

@@ -1,33 +1,11 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { messages as t } from "../../../lib/i18n.js";
-import { createEndpointCommands, endpointConfigurationStoreToken } from 'zhin.js/adapter';
+import { createEndpointCommands } from 'zhin.js/adapter';
 import { defineCommand } from 'zhin.js/command';
-import { icqqRuntimeStateToken } from "../../../lib/icqq-runtime-state.js";
 export const icqqEndpointCommands = createEndpointCommands({
     adapterKey: 'icqq',
     adapterDisplayName: 'ICQQ',
-    running: (use) => use(icqqRuntimeStateToken).endpoints.values(),
     describeEntry: (_entry, locale) => t(locale, 'direct'),
-    addDescription: '登记 ICQQ endpoint（重启 zhin 生效）',
-    addDescriptionI18n: { en: 'Register an ICQQ endpoint; restart zhin to apply' },
-    bindFlow: async ({ id, use, locale, formatCommand }) => {
-        if (!id) {
-            const command = formatCommand?.('icqq endpoint add');
-            return command ? t(locale, 'addUsage', { command }) : t(locale, 'uinRequired');
-        }
-        if (!/^\d+$/.test(id)) {
-            return t(locale, 'uinInvalid');
-        }
-        try {
-            const { filePath } = await use(endpointConfigurationStoreToken).add({
-                adapterKey: 'icqq',
-                entry: { id },
-                environment: {},
-            });
-            return t(locale, 'endpointAdded', { id, file: filePath });
-        }
-        catch (error) {
-            return t(locale, 'endpointAddFailed', { error: error instanceof Error ? error.message : String(error) });
-        }
-    },
+    addDescription: '保存 ICQQ 账号；保存后需手动启动',
+    addDescriptionI18n: { en: 'Save an ICQQ account; start it explicitly after saving' },
 }, defineCommand);

package/commands/icqq/endpoint/definition.ts

@@ -1,32 +1,11 @@
 import { messages as t } from '../../../src/i18n.js';
-import { createEndpointCommands, endpointConfigurationStoreToken } from 'zhin.js/adapter';
+import { createEndpointCommands } from 'zhin.js/adapter';
 import { defineCommand } from 'zhin.js/command';
-import { icqqRuntimeStateToken } from '../../../src/icqq-runtime-state.js';
 
 export const icqqEndpointCommands = createEndpointCommands({
   adapterKey: 'icqq',
   adapterDisplayName: 'ICQQ',
-  running: (use) => use(icqqRuntimeStateToken).endpoints.values(),
   describeEntry: (_entry, locale) => t(locale, 'direct'),
-  addDescription: '登记 ICQQ endpoint（重启 zhin 生效）',
-  addDescriptionI18n: { en: 'Register an ICQQ endpoint; restart zhin to apply' },
-  bindFlow: async ({ id, use, locale, formatCommand }) => {
-    if (!id) {
-      const command = formatCommand?.('icqq endpoint add');
-      return command ? t(locale, 'addUsage', { command }) : t(locale, 'uinRequired');
-    }
-    if (!/^\d+$/.test(id)) {
-      return t(locale, 'uinInvalid');
-    }
-    try {
-      const { filePath } = await use(endpointConfigurationStoreToken).add({
-        adapterKey: 'icqq',
-        entry: { id },
-        environment: {},
-      });
-      return t(locale, 'endpointAdded', { id, file: filePath });
-    } catch (error) {
-      return t(locale, 'endpointAddFailed', { error: error instanceof Error ? error.message : String(error) });
-    }
-  },
+  addDescription: '保存 ICQQ 账号；保存后需手动启动',
+  addDescriptionI18n: { en: 'Save an ICQQ account; start it explicitly after saving' },
 }, defineCommand);

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 { icqqLoginControls, 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, project, owner }) {
+        if (!isIcqqLoginOperator(config, input))
+            return icqqLoginForbidden();
+        const controls = icqqLoginControls({ project, owner });
+        // 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 {
+  icqqLoginControls,
+  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, project, owner }) {
+    if (!isIcqqLoginOperator(config, input)) return icqqLoginForbidden();
+    const controls = icqqLoginControls({ project, owner });
+    // 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 { icqqLoginControls, 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, project, owner }) {
+        if (!isIcqqLoginOperator(config, input))
+            return icqqLoginForbidden();
+        const picked = pickIcqqLoginControl(icqqLoginControls({ project, owner }), 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 {
+  icqqLoginControls,
+  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, project, owner }) {
+    if (!isIcqqLoginOperator(config, input)) return icqqLoginForbidden();
+    const picked = pickIcqqLoginControl(icqqLoginControls({ project, owner }), 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 { icqqLoginControls } from "../../../lib/icqq-login-control.js";
+export { icqqLoginControls };
+/** 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 { icqqLoginControls, type IcqqLoginControl } from '../../../src/icqq-login-control.js';
+
+export { icqqLoginControls };
+
+/** 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 '登录验证';
+  }
+}