@zhin.js/adapter-icqq 1.1.6 → 1.1.8

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @zhin.js/adapter-icqq
 
+## 1.1.8
+
+### Patch Changes
+
+- 9891e66: Endpoint 新增运行期 `selfUserId` 访问器与受保护的 `reportSelfUserId()`（`EndpointImplementation` 另可声明 `selfUserId`，`EndpointActivationContext` 提供 `reportSelfUserId`），并新增进程级 Peer Registry（`getProcessPeerRegistry()` / `createPeerRegistry()`）。账号仅在 generation active 后登记，回滚 / retire / stop 后移除；`EndpointIdentity` 保持不可变。ICQQ 在 `system.online` 上报 uin；OneBot11 ws/wss 从事件 `self_id` 与 `get_login_info` 上报；Sandbox 以配置的 bot id 作为合成账号。未上报的旧 Endpoint 不进入 Registry（fail closed），不会用配置 id 兜底。OneBot12 / napcat / milky 等其余适配器留待后续。
+
+  Peer Registry 使用登记序号（新 generation 胜出），旧实例在新实例登记后再次上报不会覆盖新条目；空值或非字符串的读取查询返回未命中而不抛错；OneBot11 在 stop 时清空 `selfUserId`。
+
+  登记序号在 Endpoint 激活时通过 `PeerRegistry.reserve()` 分配，新实例先上报、旧实例晚到的首次上报不会覆盖新条目。
+
+- 386150d: Unify command parameters, options, validation and help; provide IM middleware defaults, exact persistent delivery targets and owner-scoped atomic state. Derive plugin configuration types, defaults, validation and Console metadata from one declaration, preserve plugin ownership and generation admission, and keep process database, scheduler and outbound resources private to the root. Reject inline configuration in isolated plugins inside their own realm; isolated configuration uses schema.json.
+
+  Reject ambiguous optional/rest routes and undefined dynamic defaults, preserve optional parameter types and help handling, and validate Console edits with the Runtime configuration engine. Keep unrelated plugin entries cached during helper reloads, expose initial configuration metadata before login completes, and drain admitted Host operations while rejecting retired or failed-generation access.
+
+  Keep schedule activation and hot reload atomic, preserving published jobs when a candidate fails; preserve immutable database query branches and path-only command parameters. Report background unhandled rejections for the Runtime Process Host, observe ICQQ heartbeat and reconnect login failures through the SDK reconnect policy, and normalize inline image data URLs before ICQQ file or base64 delivery.
+
+- 4778587: 补齐 Console 安装配置闭环所需的精确配置路径、端点身份、平台就绪与验证计划失效语义，并保存历史消息的方向及实际投递诊断。
+
+  修复真实 ICQQ 入站目标保存了插件 owner 而非平台标识、导致提醒投递被身份校验拒绝的问题；无关插件配置变更保留原有适配器连接。
+
+  保证候选事件在当前代快照发布后准入，并避免安装过程中依赖文件变动提前中断插件管理操作。
+
+  明确 Adapter/MCP 客户端创建仅提供所属 owner 的配置与资源，跨 Feature 查询由当前 operation 上下文负责；入站诊断记录接收时刻，避免慢指令的回复在历史中先于指令。
+
+- Updated dependencies [9891e66]
+- Updated dependencies [bf52b40]
+- Updated dependencies [bf52b40]
+- Updated dependencies [bf52b40]
+- Updated dependencies [386150d]
+- Updated dependencies [9891e66]
+- Updated dependencies [9891e66]
+- Updated dependencies [4778587]
+- Updated dependencies [40537e3]
+- Updated dependencies [681abf3]
+- Updated dependencies [9891e66]
+- Updated dependencies [9891e66]
+  - @zhin.js/adapter@1.1.18
+  - @zhin.js/core@1.1.43
+  - @zhin.js/permission@1.1.5
+  - @zhin.js/feature-kit@1.1.4
+  - @zhin.js/agent-feature@1.1.5
+  - @zhin.js/skill@1.1.5
+  - @zhin.js/tool@1.1.5
+
+## 1.1.7
+
+### Patch Changes
+
+- Updated dependencies [5ab6307]
+  - @zhin.js/core@1.1.42
+
 ## 1.1.6
 
 ### Patch Changes

package/lib/endpoint.d.ts

@@ -4,14 +4,12 @@ import type { EndpointContentPort } from '@zhin.js/adapter';
 import { type LoginAssist } from '@zhin.js/core';
 import type { CapabilityId } from 'zhin.js';
 import { type IcqqInboundMessage, type ResolvedIcqqConfig } from './protocol.js';
+import { ManagedIcqqClient } from './managed-client.js';
 export interface IcqqEndpointOptions {
     readonly id: CapabilityId;
     readonly config: ResolvedIcqqConfig;
     readonly loginAssist: LoginAssist;
 }
-declare class ManagedIcqqClient extends Client {
-    cancelReconnect(): void;
-}
 export declare class IcqqEndpoint extends Endpoint<Client> {
     #private;
     readonly client: ManagedIcqqClient;
@@ -28,4 +26,3 @@ export declare class IcqqEndpoint extends Endpoint<Client> {
     send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     admit(msg: IcqqInboundMessage): Promise<void>;
 }
-export {};

package/lib/endpoint.js

@@ -1,4 +1,4 @@
-import { Client, parseGroupMessageId, } from '@icqqjs/icqq';
+import { parseGroupMessageId, } from '@icqqjs/icqq';
 import { inspect } from 'node:util';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { Endpoint, } from 'zhin.js/adapter';
@@ -7,11 +7,12 @@ import { EndpointDeliveryError } from '@zhin.js/im-contract';
 import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
 import { runIcqqLoginAssistStep } from './icqq-login-assist.js';
 import { IcqqContentResolver } from './content-resolver.js';
-import { InboundMessageDeduper, findIcqqNestedMessageSource, isIcqqBotMentioned, isIcqqMessagePostType, normalizeIcqqInboundMessage, messageLookupFromIcqqSource, resolveIcqqQuoteIdFromEvent, resolveIcqqInboundMedia, shouldSkipSelfInboundMessage, } from './icqq-inbound.js';
+import { InboundMessageDeduper, findIcqqNestedMessageSource, isIcqqBotMentioned, isIcqqMessagePostType, normalizeIcqqInboundMessage, messageLookupFromIcqqSource, resolveIcqqQuoteIdFromEvent, resolveIcqqInboundMedia, resolveIcqqSelfUserId, shouldSkipSelfInboundMessage, } from './icqq-inbound.js';
 import { isIcqqNoticePayload, isIcqqRequestPayload, } from './icqq-inbox.js';
 import { IcqqGuildCatalog, normalizeIcqqGuildInboundMessage, } from './icqq-guild.js';
 import { prepareIcqqOutboundMedia, resolveIcqqOutboundMediaMode, } from './outbound-media.js';
-import { formatInboundContent, formatOutboundBody, icqqInboundConversation, icqqOutboundTarget, } from './protocol.js';
+import { formatInboundContent, formatOutboundBody, normalizeIcqqImageMedia, icqqInboundConversation, icqqOutboundTarget, } from './protocol.js';
+import { ManagedIcqqClient } from './managed-client.js';
 const BOUND_EVENTS = [
     'message.private',
     'message.group',
@@ -30,14 +31,6 @@ const BOUND_EVENTS = [
     'system.login.error',
     'system.login.auth',
 ];
-class ManagedIcqqClient extends Client {
-    cancelReconnect() {
-        if (!this.login_timer)
-            return;
-        clearTimeout(this.login_timer);
-        this.login_timer = null;
-    }
-}
 export class IcqqEndpoint extends Endpoint {
     client;
     #logger;
@@ -132,13 +125,31 @@ export class IcqqEndpoint extends Endpoint {
     constructor(options) {
         super();
         const nativeConfig = resolveNativeClientConfig(options.config);
-        this.client = new ManagedIcqqClient(Number(options.config.id), nativeConfig);
+        this.client = new ManagedIcqqClient(Number(options.config.id), nativeConfig, (operation, error) => this.#handleBackgroundFailure(operation, error));
         this.#contentResolver = new IcqqContentResolver(this.client);
         this.content = this.#contentResolver.port;
         this.#logger = getAdapterLogger('icqq', options.config.id);
         this.#options = options;
         this.endpointName = options.config.id;
     }
+    #handleBackgroundFailure(operation, error) {
+        if (!this.#started || this.#stopped || this.#retiring)
+            return;
+        this.#logger.warn(formatCompact({
+            op: `icqq_${operation}_failed`, endpoint: this.endpointName,
+            error: error instanceof Error ? error.message
+                : error && typeof error === 'object' && 'message' in error && typeof error.message === 'string' ? error.message
+                    : typeof error === 'string' ? error : 'Unknown ICQQ SDK background failure',
+            ...(error && typeof error === 'object' && 'code' in error && typeof error.code === 'number' ? { code: error.code } : {}),
+        }));
+        if (operation === 'sso-heartbeat' && !this.client.isOnline())
+            return;
+        if (operation === 'login' && !this.#everOnline)
+            return;
+        // Delegate to the SDK's existing transport termination, offline event and
+        // reconn_interval policy. No account-level logout or second retry timer.
+        this.client.emit('internal.error.network', -2, `ICQQ ${operation} failed`);
+    }
     #ignoreReactionAck(action, task) {
         void Promise.resolve(task).catch((error) => {
             this.#logger.debug(formatCompact({
@@ -278,7 +289,7 @@ export class IcqqEndpoint extends Endpoint {
             throw new EndpointDeliveryError('endpoint_disconnected', 'icqq endpoint 未连接', 'not_sent');
         const mediaMode = resolveIcqqOutboundMediaMode(this.#options.config);
         const prepared = isIcqqSegmentPayload(payload)
-            ? prepareIcqqOutboundMedia(payload, mediaMode)
+            ? prepareIcqqOutboundMedia(normalizeIcqqImageMedia(payload), mediaMode)
             : { content: payload, dispose() { } };
         try {
             const message = formatOutboundBody(prepared.content);
@@ -513,6 +524,17 @@ export class IcqqEndpoint extends Endpoint {
             try {
                 this.#resolveStartOnline?.();
                 this.#options.loginAssist.cancelOwned(this.#loginAssistOwner, 'online');
+                try {
+                    // transport 重连不清除（账号不变）；stop/retire 由基类撤销登记。上报失败不影响上线流程。
+                    this.reportSelfUserId(resolveIcqqSelfUserId(this.client));
+                }
+                catch (error) {
+                    this.#logger.warn(formatCompact({
+                        op: 'icqq_report_self_user_id_failed',
+                        endpoint: this.endpointName,
+                        error: error instanceof Error ? error.message : String(error),
+                    }));
+                }
                 this.#logSystemEvent('online', event);
             }
             catch (error) {

package/lib/icqq-inbound.d.ts

@@ -134,6 +134,10 @@ export declare function unwrapIcqqEventPayload(event: {
 export declare function resolveIcqqInboundUserId(data: Record<string, unknown>): number | undefined;
 export declare function isIcqqMessagePostType(data: unknown): data is IcqqMessageEvent;
 export declare function shouldSkipSelfInboundMessage(data: IcqqMessageEvent): boolean;
+/** 登录后的机器人 QQ 号；仅正整数有效（mock/未登录的 0、NaN、空均视为未知）。 */
+export declare function resolveIcqqSelfUserId(client: {
+    uin?: number | string;
+}): string | undefined;
 /** 群临时会话私聊：icqq message_type=private & sub_type=group */
 export declare function isIcqqGroupTempPrivateMessage(data: IcqqMessageEvent): boolean;
 export declare function resolveChannelFromIcqqMessage(data: IcqqMessageEvent): {

package/lib/icqq-inbound.js

@@ -154,6 +154,16 @@ export function shouldSkipSelfInboundMessage(data) {
         return false;
     return Number(data.self_id) === Number(data.user_id);
 }
+/** 登录后的机器人 QQ 号；仅正整数有效（mock/未登录的 0、NaN、空均视为未知）。 */
+export function resolveIcqqSelfUserId(client) {
+    const raw = client?.uin;
+    if (typeof raw !== "number" && typeof raw !== "string")
+        return undefined;
+    if (typeof raw === "string" && !/^\d+$/.test(raw.trim()))
+        return undefined;
+    const uin = Number(raw);
+    return Number.isSafeInteger(uin) && uin > 0 ? String(uin) : undefined;
+}
 /** 群临时会话私聊：icqq message_type=private & sub_type=group */
 export function isIcqqGroupTempPrivateMessage(data) {
     const messageType = data.message_type ??

package/lib/managed-client.d.ts

@@ -0,0 +1,11 @@
+import { Client, type Config } from '@icqqjs/icqq';
+export type IcqqBackgroundOperation = 'sso-heartbeat' | 'login';
+/** Own SDK promises also invoked by timers that discard their return value. */
+export declare class ManagedIcqqClient extends Client {
+    #private;
+    constructor(uin: number, config: Config, onFailure: (operation: IcqqBackgroundOperation, error: unknown) => void);
+    sendSsoHeartBeat(): false | Promise<unknown>;
+    login(password?: string | Buffer): Promise<void>;
+    login(uin?: number, password?: string | Buffer): Promise<void>;
+    cancelReconnect(): void;
+}

package/lib/managed-client.js

@@ -0,0 +1,46 @@
+import { Client } from '@icqqjs/icqq';
+/** Own SDK promises also invoked by timers that discard their return value. */
+export class ManagedIcqqClient extends Client {
+    #onFailure;
+    constructor(uin, config, onFailure) {
+        super(uin, config);
+        this.#onFailure = onFailure;
+    }
+    sendSsoHeartBeat() {
+        const task = super.sendSsoHeartBeat();
+        if (task !== false)
+            this.#observe('sso-heartbeat', task);
+        return task;
+    }
+    login(uinOrPassword, password) {
+        const task = typeof uinOrPassword === 'number' || password !== undefined
+            ? super.login(typeof uinOrPassword === 'number' ? uinOrPassword : undefined, password)
+            : super.login(uinOrPassword);
+        this.#observe('login', task);
+        return task;
+    }
+    #observe(operation, task) {
+        // Observe the original promise instead of replacing it: explicit SDK
+        // callers still receive the rejection and may fail their own operation.
+        void task.catch(error => {
+            try {
+                this.#onFailure(operation, error);
+            }
+            catch {
+                try {
+                    this.logger.error('ICQQ background failure handler failed');
+                }
+                catch {
+                    // The rejection is already observed. A broken diagnostic sink must
+                    // not create another unhandled promise or expose the error payload.
+                }
+            }
+        });
+    }
+    cancelReconnect() {
+        if (!this.login_timer)
+            return;
+        clearTimeout(this.login_timer);
+        this.login_timer = null;
+    }
+}

package/lib/protocol.d.ts

@@ -1,6 +1,6 @@
 import type { Sendable } from '@icqqjs/icqq';
-import type { ConversationRef } from '@zhin.js/im-contract';
-import type { MessageSegment } from "zhin.js";
+import { type ConversationRef } from '@zhin.js/im-contract';
+import type { MessageSegment, SendContent } from "zhin.js";
 export type ActionResult = {
     id: string;
     ok: boolean;
@@ -238,6 +238,8 @@ export declare function resolveIcqqConfig(config: IcqqEndpointConfig): ResolvedI
  * 入站归一化 → ConversationRef：群临时会话（temp）映射为群容器内的 private
  * 会话（parent kind 'group'）；频道消息的所属 guild 进 `parent`（kind 'channel'）。
  */
+/** ICQQ 平台标识，与 Endpoint identity.adapter / clientAdapter 保持一致。 */
+export declare const ICQQ_ADAPTER_NAME: "icqq";
 export declare function icqqInboundConversation(endpointKey: string, input: {
     readonly channelType: 'private' | 'group' | 'channel';
     readonly channelId: string;
@@ -249,6 +251,8 @@ export declare function icqqInboundConversation(endpointKey: string, input: {
  * 群容器（parent kind 'group'）内的 private 会话即 ICQQ 群临时会话（temp）。
  */
 export declare function icqqOutboundTarget(conversation: ConversationRef): ParsedIcqqSendTarget;
+/** Normalize inline image bytes before either temporary-file or native-base64 delivery. */
+export declare function normalizeIcqqImageMedia(content: SendContent): SendContent;
 /**
  * Project canonical Zhin segments directly into the native ICQQ Sendable
  * algebra. ICQQ's direct client does not parse Zhin's historical `[image:x]`

package/lib/protocol.js

@@ -1,3 +1,4 @@
+import { isMediaRef } from '@zhin.js/im-contract';
 import { resolveIcqqMediaFile } from "./cq-message.js";
 export { resolveIcqqInboundMessageId } from "./icqq-inbound.js";
 /**
@@ -211,8 +212,10 @@ export function resolveIcqqConfig(config) {
  * 入站归一化 → ConversationRef：群临时会话（temp）映射为群容器内的 private
  * 会话（parent kind 'group'）；频道消息的所属 guild 进 `parent`（kind 'channel'）。
  */
+/** ICQQ 平台标识，与 Endpoint identity.adapter / clientAdapter 保持一致。 */
+export const ICQQ_ADAPTER_NAME = 'icqq';
 export function icqqInboundConversation(endpointKey, input) {
-    const endpoint = { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey };
+    const endpoint = { id: endpointKey, adapter: ICQQ_ADAPTER_NAME };
     if (input.channelType === 'private' && input.channelParentGroupId) {
         return {
             endpoint,
@@ -263,6 +266,24 @@ const ICQQ_STANDALONE_ELEMENTS = new Set([
     'share',
     'long_msg',
 ]);
+/** Normalize inline image bytes before either temporary-file or native-base64 delivery. */
+export function normalizeIcqqImageMedia(content) {
+    if (Array.isArray(content))
+        return content.map(normalizeIcqqImageMedia);
+    if (!isWireSegment(content) || content.type !== 'image')
+        return content;
+    const data = normalizeIcqqImageData(content.data);
+    return data === content.data ? content : { ...content, data };
+}
+function normalizeIcqqImageData(data) {
+    const media = data?.media;
+    if (!isMediaRef(media) || !/^data:/i.test(media.value))
+        return data;
+    const parsed = /^data:(image\/[^;,]+)(?:;[^;,]*)*;base64,([\s\S]+)$/i.exec(media.value);
+    if (!parsed)
+        throw new TypeError('ICQQ image data URL must contain base64 image data');
+    return { ...data, media: { ...media, kind: 'base64', value: parsed[2], mime_type: (media.mime_type ?? parsed[1]).toLowerCase() } };
+}
 /**
  * Project canonical Zhin segments directly into the native ICQQ Sendable
  * algebra. ICQQ's direct client does not parse Zhin's historical `[image:x]`
@@ -306,7 +327,7 @@ export function formatOutboundBody(payload) {
                 return { type: 'at', qq };
             }
             case 'image': {
-                const arg = resolveIcqqMediaFile(item.data);
+                const arg = resolveIcqqMediaFile(normalizeIcqqImageData(item.data));
                 if (!arg)
                     throw new TypeError('ICQQ image segment requires canonical data.media');
                 return { type: 'image', file: arg };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-icqq",
-  "version": "1.1.6",
+  "version": "1.1.8",
   "description": "Zhin.js ICQQ adapter — direct connection to @icqqjs/icqq",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,24 +34,24 @@
     "directory": "plugins/adapters/icqq"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.17",
-    "@zhin.js/agent-feature": "1.1.4",
-    "@zhin.js/core": "1.1.41",
-    "@zhin.js/feature-kit": "1.1.3",
+    "@zhin.js/adapter": "1.1.18",
+    "@zhin.js/agent-feature": "1.1.5",
+    "@zhin.js/core": "1.1.43",
+    "@zhin.js/feature-kit": "1.1.4",
     "@zhin.js/im-contract": "1.1.3",
     "@zhin.js/logger": "1.1.1",
-    "@zhin.js/permission": "1.1.4",
-    "@zhin.js/skill": "1.1.4",
-    "@zhin.js/tool": "1.1.4"
+    "@zhin.js/permission": "1.1.5",
+    "@zhin.js/skill": "1.1.5",
+    "@zhin.js/tool": "1.1.5"
   },
   "peerDependencies": {
     "@icqqjs/icqq": "^1.12.2",
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.17",
-    "@zhin.js/command": "^1.1.5",
-    "@zhin.js/core": "^1.1.41",
-    "@zhin.js/prompt-section": "^1.1.3",
-    "zhin.js": "^1.1.6"
+    "@zhin.js/adapter": "^1.1.18",
+    "@zhin.js/command": "^1.1.6",
+    "@zhin.js/core": "^1.1.43",
+    "@zhin.js/prompt-section": "^1.1.4",
+    "zhin.js": "^1.1.8"
   },
   "peerDependenciesMeta": {
     "@icqqjs/icqq": {
@@ -76,8 +76,8 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/prompt-section": "1.1.3",
-    "zhin.js": "1.1.6"
+    "@zhin.js/prompt-section": "1.1.4",
+    "zhin.js": "1.1.8"
   },
   "files": [
     "adapters",

package/src/endpoint.ts

@@ -34,6 +34,7 @@ import {
   messageLookupFromIcqqSource,
   resolveIcqqQuoteIdFromEvent,
   resolveIcqqInboundMedia,
+  resolveIcqqSelfUserId,
   shouldSkipSelfInboundMessage,
   type IcqqMessageEvent,
 } from './icqq-inbound.js';
@@ -52,12 +53,14 @@ import {
 import {
   formatInboundContent,
   formatOutboundBody,
+  normalizeIcqqImageMedia,
   icqqInboundConversation,
   icqqOutboundTarget,
   type IcqqInboundMessage,
   type ResolvedIcqqConfig,
 } from './protocol.js';
 import type { SystemMessage as IcqqSystemMessage } from './types.js';
+import { ManagedIcqqClient, type IcqqBackgroundOperation } from './managed-client.js';
 
 export interface IcqqEndpointOptions {
   readonly id: CapabilityId;
@@ -84,14 +87,6 @@ const BOUND_EVENTS = [
   'system.login.auth',
 ] as const;
 
-class ManagedIcqqClient extends Client {
-  cancelReconnect(): void {
-    if (!this.login_timer) return;
-    clearTimeout(this.login_timer);
-    this.login_timer = null;
-  }
-}
-
 export class IcqqEndpoint extends Endpoint<Client> {
   readonly client: ManagedIcqqClient;
   readonly #logger: ReturnType<typeof getAdapterLogger>;
@@ -193,7 +188,8 @@ export class IcqqEndpoint extends Endpoint<Client> {
   constructor(options: IcqqEndpointOptions) {
     super();
     const nativeConfig = resolveNativeClientConfig(options.config);
-    this.client = new ManagedIcqqClient(Number(options.config.id), nativeConfig);
+    this.client = new ManagedIcqqClient(Number(options.config.id), nativeConfig,
+      (operation, error) => this.#handleBackgroundFailure(operation, error));
     this.#contentResolver = new IcqqContentResolver(this.client);
     this.content = this.#contentResolver.port;
     this.#logger = getAdapterLogger('icqq', options.config.id);
@@ -201,6 +197,22 @@ export class IcqqEndpoint extends Endpoint<Client> {
     this.endpointName = options.config.id;
   }
 
+  #handleBackgroundFailure(operation: IcqqBackgroundOperation, error: unknown): void {
+    if (!this.#started || this.#stopped || this.#retiring) return;
+    this.#logger.warn(formatCompact({
+      op: `icqq_${operation}_failed`, endpoint: this.endpointName,
+      error: error instanceof Error ? error.message
+        : error && typeof error === 'object' && 'message' in error && typeof error.message === 'string' ? error.message
+        : typeof error === 'string' ? error : 'Unknown ICQQ SDK background failure',
+      ...(error && typeof error === 'object' && 'code' in error && typeof error.code === 'number' ? { code: error.code } : {}),
+    }));
+    if (operation === 'sso-heartbeat' && !this.client.isOnline()) return;
+    if (operation === 'login' && !this.#everOnline) return;
+    // Delegate to the SDK's existing transport termination, offline event and
+    // reconn_interval policy. No account-level logout or second retry timer.
+    this.client.emit('internal.error.network', -2, `ICQQ ${operation} failed`);
+  }
+
   #ignoreReactionAck(action: 'add' | 'remove', task: Promise<unknown> | unknown): void {
     void Promise.resolve(task).catch((error) => {
       this.#logger.debug(formatCompact({
@@ -335,7 +347,7 @@ export class IcqqEndpoint extends Endpoint<Client> {
     if (!this.#started) throw new EndpointDeliveryError('endpoint_disconnected', 'icqq endpoint 未连接', 'not_sent');
     const mediaMode = resolveIcqqOutboundMediaMode(this.#options.config);
     const prepared = isIcqqSegmentPayload(payload)
-      ? prepareIcqqOutboundMedia(payload, mediaMode)
+      ? prepareIcqqOutboundMedia(normalizeIcqqImageMedia(payload), mediaMode)
       : { content: payload, dispose() {} };
     try {
       const message = formatOutboundBody(prepared.content);
@@ -581,6 +593,16 @@ export class IcqqEndpoint extends Endpoint<Client> {
       try {
         this.#resolveStartOnline?.();
         this.#options.loginAssist.cancelOwned(this.#loginAssistOwner, 'online');
+        try {
+          // transport 重连不清除（账号不变）；stop/retire 由基类撤销登记。上报失败不影响上线流程。
+          this.reportSelfUserId(resolveIcqqSelfUserId(this.client));
+        } catch (error) {
+          this.#logger.warn(formatCompact({
+            op: 'icqq_report_self_user_id_failed',
+            endpoint: this.endpointName,
+            error: error instanceof Error ? error.message : String(error),
+          }));
+        }
         this.#logSystemEvent('online', event);
       } catch (error) {
         this.#logger.warn(formatCompact({

package/src/icqq-inbound.ts

@@ -282,6 +282,15 @@ export function shouldSkipSelfInboundMessage(
   return Number(data.self_id) === Number(data.user_id);
 }
 
+/** 登录后的机器人 QQ 号；仅正整数有效（mock/未登录的 0、NaN、空均视为未知）。 */
+export function resolveIcqqSelfUserId(client: { uin?: number | string }): string | undefined {
+  const raw = client?.uin;
+  if (typeof raw !== "number" && typeof raw !== "string") return undefined;
+  if (typeof raw === "string" && !/^\d+$/.test(raw.trim())) return undefined;
+  const uin = Number(raw);
+  return Number.isSafeInteger(uin) && uin > 0 ? String(uin) : undefined;
+}
+
 /** 群临时会话私聊：icqq message_type=private & sub_type=group */
 export function isIcqqGroupTempPrivateMessage(data: IcqqMessageEvent): boolean {
   const messageType =

package/src/managed-client.ts

@@ -0,0 +1,52 @@
+import { Client, type Config } from '@icqqjs/icqq';
+
+export type IcqqBackgroundOperation = 'sso-heartbeat' | 'login';
+
+/** Own SDK promises also invoked by timers that discard their return value. */
+export class ManagedIcqqClient extends Client {
+  readonly #onFailure: (operation: IcqqBackgroundOperation, error: unknown) => void;
+
+  constructor(uin: number, config: Config, onFailure: (operation: IcqqBackgroundOperation, error: unknown) => void) {
+    super(uin, config);
+    this.#onFailure = onFailure;
+  }
+
+  override sendSsoHeartBeat(): false | Promise<unknown> {
+    const task = super.sendSsoHeartBeat();
+    if (task !== false) this.#observe('sso-heartbeat', task);
+    return task;
+  }
+
+  override login(password?: string | Buffer): Promise<void>;
+  override login(uin?: number, password?: string | Buffer): Promise<void>;
+  override login(uinOrPassword?: number | string | Buffer, password?: string | Buffer): Promise<void> {
+    const task = typeof uinOrPassword === 'number' || password !== undefined
+      ? super.login(typeof uinOrPassword === 'number' ? uinOrPassword : undefined, password)
+      : super.login(uinOrPassword);
+    this.#observe('login', task);
+    return task;
+  }
+
+  #observe(operation: IcqqBackgroundOperation, task: Promise<unknown>): void {
+    // Observe the original promise instead of replacing it: explicit SDK
+    // callers still receive the rejection and may fail their own operation.
+    void task.catch(error => {
+      try {
+        this.#onFailure(operation, error);
+      } catch {
+        try {
+          this.logger.error('ICQQ background failure handler failed');
+        } catch {
+          // The rejection is already observed. A broken diagnostic sink must
+          // not create another unhandled promise or expose the error payload.
+        }
+      }
+    });
+  }
+
+  cancelReconnect(): void {
+    if (!this.login_timer) return;
+    clearTimeout(this.login_timer);
+    this.login_timer = null;
+  }
+}

package/src/protocol.ts

@@ -1,6 +1,6 @@
 import type { MessageElem, Sendable, ShareElem } from '@icqqjs/icqq';
-import type { ConversationRef } from '@zhin.js/im-contract';
-import type { MessageSegment } from "zhin.js";
+import { isMediaRef, type ConversationRef } from '@zhin.js/im-contract';
+import type { MessageSegment, SendContent } from "zhin.js";
 import { resolveIcqqMediaFile } from "./cq-message.js";
 
 export type ActionResult = {
@@ -333,13 +333,16 @@ export function resolveIcqqConfig(config: IcqqEndpointConfig): ResolvedIcqqConfi
  * 入站归一化 → ConversationRef：群临时会话（temp）映射为群容器内的 private
  * 会话（parent kind 'group'）；频道消息的所属 guild 进 `parent`（kind 'channel'）。
  */
+/** ICQQ 平台标识，与 Endpoint identity.adapter / clientAdapter 保持一致。 */
+export const ICQQ_ADAPTER_NAME = 'icqq' as const;
+
 export function icqqInboundConversation(endpointKey: string, input: {
   readonly channelType: 'private' | 'group' | 'channel';
   readonly channelId: string;
   readonly channelParentGroupId?: string;
   readonly guildId?: string;
 }): ConversationRef {
-  const endpoint = { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey };
+  const endpoint = { id: endpointKey, adapter: ICQQ_ADAPTER_NAME };
   if (input.channelType === 'private' && input.channelParentGroupId) {
     return {
       endpoint,
@@ -393,6 +396,22 @@ const ICQQ_STANDALONE_ELEMENTS = new Set([
   'long_msg',
 ] as const);
 
+/** Normalize inline image bytes before either temporary-file or native-base64 delivery. */
+export function normalizeIcqqImageMedia(content: SendContent): SendContent {
+  if (Array.isArray(content)) return content.map(normalizeIcqqImageMedia);
+  if (!isWireSegment(content) || content.type !== 'image') return content;
+  const data = normalizeIcqqImageData(content.data);
+  return data === content.data ? content : { ...content, data } as MessageSegment;
+}
+
+function normalizeIcqqImageData(data: Record<string, unknown> | undefined): Record<string, unknown> | undefined {
+  const media = data?.media;
+  if (!isMediaRef(media) || !/^data:/i.test(media.value)) return data;
+  const parsed = /^data:(image\/[^;,]+)(?:;[^;,]*)*;base64,([\s\S]+)$/i.exec(media.value);
+  if (!parsed) throw new TypeError('ICQQ image data URL must contain base64 image data');
+  return { ...data, media: { ...media, kind: 'base64', value: parsed[2]!, mime_type: (media.mime_type ?? parsed[1]!).toLowerCase() } };
+}
+
 /**
  * Project canonical Zhin segments directly into the native ICQQ Sendable
  * algebra. ICQQ's direct client does not parse Zhin's historical `[image:x]`
@@ -433,7 +452,7 @@ export function formatOutboundBody(payload: unknown): Sendable {
         return { type: 'at', qq };
       }
       case 'image': {
-        const arg = resolveIcqqMediaFile(item.data);
+        const arg = resolveIcqqMediaFile(normalizeIcqqImageData(item.data));
         if (!arg) throw new TypeError('ICQQ image segment requires canonical data.media');
         return { type: 'image', file: arg };
       }