@zhin.js/adapter-icqq 8.0.2 → 8.0.5

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # @zhin.js/adapter-icqq
 
+## 8.0.5
+
+### Patch Changes
+
+- 36c7400: Replace `AgentPromptBuildContext.commMessage` with an authenticated platform projection and make Agent prompt assembly consume canonical Turn identity. Platform contributors and prompt hooks no longer receive a classic IM `Message`.
+
+  Remove the unused Message field and active-context escape hatch from PromptController; turn scheduling is keyed only by canonical session identity.
+
+- Updated dependencies [6f9c366]
+- Updated dependencies [373a56b]
+- Updated dependencies [0de46a8]
+- Updated dependencies [c106ecc]
+- Updated dependencies [ca92e03]
+- Updated dependencies [b0f37ae]
+- Updated dependencies [ba08a2f]
+- Updated dependencies [b08f7fe]
+- Updated dependencies [daffd4c]
+- Updated dependencies [36c7400]
+- Updated dependencies [a9fa72e]
+- Updated dependencies [c8de3ef]
+- Updated dependencies [60f0fc8]
+- Updated dependencies [574c990]
+- Updated dependencies [d096f16]
+- Updated dependencies [3f29623]
+- Updated dependencies [2916852]
+- Updated dependencies [d047869]
+- Updated dependencies [162fa34]
+- Updated dependencies [e62561e]
+- Updated dependencies [3eeeb46]
+- Updated dependencies [85d0f82]
+- Updated dependencies [61bfc1c]
+- Updated dependencies [04bad47]
+- Updated dependencies [e40b048]
+- Updated dependencies [5a5b1bb]
+- Updated dependencies [f1708c3]
+- Updated dependencies [d254a81]
+- Updated dependencies [7123c47]
+- Updated dependencies [05befc1]
+- Updated dependencies [0663b6a]
+- Updated dependencies [f28f9b3]
+- Updated dependencies [9f340f7]
+- Updated dependencies [e53444f]
+- Updated dependencies [5eedd26]
+- Updated dependencies [92b0dd7]
+- Updated dependencies [f919b6f]
+- Updated dependencies [098e411]
+- Updated dependencies [e1b7c01]
+- Updated dependencies [9b94f87]
+- Updated dependencies [a7df753]
+  - @zhin.js/agent@1.1.5
+  - @zhin.js/im-contract@1.0.3
+  - @zhin.js/adapter@1.1.7
+  - @zhin.js/plugin-runtime@1.1.5
+  - @zhin.js/command@1.0.9
+  - @zhin.js/core@1.5.4
+  - zhin.js@6.0.4
+
+## 8.0.4
+
+### Patch Changes
+
+- f8c7a54: fix: im
+- Updated dependencies [f8c7a54]
+  - @zhin.js/logger@1.0.76
+  - @zhin.js/adapter@1.1.6
+  - @zhin.js/agent@1.1.4
+  - @zhin.js/command@1.0.8
+  - @zhin.js/core@1.5.3
+  - @zhin.js/im-contract@1.0.2
+  - @zhin.js/plugin-runtime@1.1.4
+  - zhin.js@6.0.3
+
+## 8.0.3
+
+### Patch Changes
+
+- Updated dependencies [afc0e66]
+- Updated dependencies [2e41ad5]
+- Updated dependencies [9f57124]
+  - @zhin.js/core@1.5.2
+  - @zhin.js/adapter@1.1.5
+  - @zhin.js/im-contract@1.0.1
+  - @zhin.js/plugin-runtime@1.1.3
+  - @zhin.js/command@1.0.7
+  - @zhin.js/agent@1.1.3
+  - zhin.js@6.0.2
+
 ## 8.0.2
 
 ### Patch Changes

package/README.md

@@ -5,8 +5,8 @@ ICQQ Plugin Runtime 适配器 — 通过 [@icqqjs/cli](https://github.com/icqqjs
 ## 功能特性
 
 - 群聊 / 私聊 / 群临时会话 / QQ 频道消息
-- 入站：`messageGatewayToken`（IPC 事件订阅）
-- 出站：`send({ target, payload })` → `send_group_msg` / `send_private_msg` / …
+- 入站：`messageGatewayToken`（IPC 事件订阅），归一为 `gateway.receive({ conversation, message, content, ... })`
+- 出站：`send({ conversation, payload })` → `send_group_msg` / `send_private_msg` / …（conversation kind/id/parent 路由）
 - Agent 工具：`agent/tools/`（戳一戳、群管、好友列表等）保留
 - Console Endpoint 管理：`src/endpoint.ts` 显式实现 `EndpointManagement`（好友/群/群成员列表、请求审批、删好友、踢人、禁言、设管理），Console 使用 `endpoint.friends` / `endpoint.groups` / `endpoint.group_members` 等规范 RPC
 
@@ -48,14 +48,14 @@ plugins:
 
 先执行 `icqq login`，再启动 Zhin。
 
-## Send target
+## Send conversation
 
-| 类型 | target |
-|------|--------|
-| 私聊 | `private:uin` |
-| 群聊 | `group:gid` |
-| 群临时会话 | `temp:gid:uin` |
-| 频道 | `channel:guildId:channelId` |
+| 类型 | conversation |
+|------|--------------|
+| 私聊 | `{ kind: 'private', id: uin }` |
+| 群聊 | `{ kind: 'group', id: gid }` |
+| 群临时会话 | `{ kind: 'private', id: uin, parent: { kind: 'group', id: gid } }` |
+| 频道 | `{ kind: 'channel', id: channelId, parent: { kind: 'channel', id: guildId } }` |
 
 ## 架构
 

package/adapters/icqq.js

@@ -26,8 +26,8 @@ export default defineAdapter({
         // Console loginAssist + host-router routes deferred.
         const config = resolveIcqqConfig(context.config);
         // 注册到插件运行时状态（icqq.endpoint list 的"运行中"数据源）
-        context.use(icqqRuntimeStateToken).endpoints.set(config.name, {
-            name: config.name,
+        context.use(icqqRuntimeStateToken).endpoints.set(config.id, {
+            id: config.id,
             mode: config.rpc ? 'rpc' : 'ipc',
         });
         const inbox = resolveInboxHooks(context);

package/adapters/icqq.ts

@@ -42,8 +42,8 @@ export default defineAdapter<IcqqAdapterConfig>({
     // Console loginAssist + host-router routes deferred.
     const config = resolveIcqqConfig(context.config);
     // 注册到插件运行时状态（icqq.endpoint list 的"运行中"数据源）
-    context.use(icqqRuntimeStateToken).endpoints.set(config.name, {
-      name: config.name,
+    context.use(icqqRuntimeStateToken).endpoints.set(config.id, {
+      id: config.id,
       mode: config.rpc ? 'rpc' : 'ipc',
     });
     const inbox = resolveInboxHooks(context);

package/lib/endpoint.d.ts

@@ -1,7 +1,7 @@
 /**
  * IcqqIpcEndpoint — lifecycle, outbound, IPC subscribe/admit for ICQQ daemon.
  */
-import type { EndpointControl, EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
+import type { EndpointControl, EndpointInstance, EndpointManagement, EndpointSendRequest } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import { type IcqqInboundMessage, type IpcEvent, type IpcResponse, type ResolvedIcqqConfig } from './protocol.js';
@@ -48,10 +48,7 @@ export declare class IcqqIpcEndpoint implements EndpointInstance {
     open(): void;
     close(): void;
     stop(): Promise<void>;
-    send({ target, payload }: {
-        readonly target: string;
-        readonly payload: unknown;
-    }): Promise<string>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     private static readonly EMOJI_MAP;
     private getEmojiId;
     /** Activity-feedback / OutboundHost reaction surface. */

package/lib/endpoint.js

@@ -1,13 +1,13 @@
-import { formatCompact, getLogger } from '@zhin.js/logger';
+import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
 import { registerIcqqAgentEndpoint } from './icqq-agent-deps.js';
 import { InboundMessageDeduper, findIcqqNestedMessageSource, isIcqqBotMentioned, isIcqqMessagePostType, normalizeIcqqInboundMessage, quotedPayloadFromIcqqSource, resolveIcqqQuoteIdFromEvent, shouldSkipSelfInboundMessage, unwrapIcqqIpcEventPayload, } from './icqq-inbound.js';
 import { buildIcqqInboxNoticeRow, buildIcqqInboxRequestRow, buildIcqqSystemRequestRow, isIcqqNoticePayload, isIcqqRequestPayload, } from './icqq-inbox.js';
 import { IcqqGuildCatalog, isIcqqGuildIpcEvent, normalizeIcqqGuildInboundMessage, } from './icqq-guild.js';
 import { IpcClient } from './ipc-client.js';
 import { materializeOutboundBase64, resolveIcqqOutboundMediaMode, } from './outbound-media.js';
-import { Actions, formatInboundContent, formatInboundTarget, formatOutboundBody, parseSendTarget, } from './protocol.js';
-const logger = getLogger('icqq');
+import { Actions, formatInboundContent, formatOutboundBody, icqqInboundConversation, icqqOutboundTarget, } from './protocol.js';
 export class IcqqIpcEndpoint {
+    #logger;
     #options;
     #createIpc;
     name;
@@ -48,8 +48,9 @@ export class IcqqIpcEndpoint {
     /** 是否已有重连循环在跑（避免多次 schedule 叠套） */
     #reconnectRunning = false;
     constructor(options) {
+        this.#logger = getAdapterLogger('icqq', options.config.id);
         this.#options = options;
-        this.name = options.config.name;
+        this.name = options.config.id;
         this.#createIpc = options.createIpc ?? defaultCreateIpc;
     }
     async request(action, params) {
@@ -66,19 +67,13 @@ export class IcqqIpcEndpoint {
         try {
             await this.#bindIpcSession();
             this.#unregisterAgent = registerIcqqAgentEndpoint(this.name, this);
-            logger.info(formatCompact({
-                op: 'connect',
-                endpoint: this.name,
-                mode: this.#options.config.rpc ? 'rpc' : 'ipc',
-                friends: this.friends.size,
-                groups: this.groups.size,
-            }));
+            this.#logger.info(`connected (${this.#options.config.rpc ? 'rpc' : 'ipc'}) | friends: ${this.friends.size} | groups: ${this.groups.size}`);
         }
         catch (error) {
             await this.stop();
             // Startup connect failures are surfaced once (with stack) by AdapterIndex;
             // keep this at debug to avoid a duplicate error-level log.
-            logger.debug(`Failed to connect ICQQ IPC: ${error instanceof Error ? error.stack ?? error.message : String(error)}`);
+            this.#logger.debug(`Failed to connect ICQQ IPC: ${error instanceof Error ? error.stack ?? error.message : String(error)}`);
             throw error;
         }
     }
@@ -117,10 +112,9 @@ export class IcqqIpcEndpoint {
                 const jitter = Math.floor(Math.random() * 400);
                 const delayMs = base + jitter;
                 // 首次断开 WARN，后续重试静默为 DEBUG，避免刷屏
-                const disconnectLog = attempt === 0 ? logger.warn.bind(logger) : logger.debug.bind(logger);
+                const disconnectLog = attempt === 0 ? this.#logger.warn.bind(this.#logger) : this.#logger.debug.bind(this.#logger);
                 disconnectLog(formatCompact({
                     op: 'disconnect',
-                    endpoint: this.name,
                     ok: false,
                     delay_ms: delayMs,
                     attempt: attempt + 1,
@@ -130,18 +124,12 @@ export class IcqqIpcEndpoint {
                     break;
                 try {
                     await this.#bindIpcSession();
-                    logger.info(formatCompact({
-                        op: 'reconnect',
-                        endpoint: this.name,
-                        ok: true,
-                        attempts: attempt + 1,
-                        friends: this.friends.size,
-                        groups: this.groups.size,
-                    }));
+                    this.#logger.info(`reconnected after ${attempt + 1} attempt(s)`
+                        + ` | friends: ${this.friends.size} | groups: ${this.groups.size}`);
                     break;
                 }
                 catch (error) {
-                    const retryLog = attempt === 0 ? logger.warn.bind(logger) : logger.debug.bind(logger);
+                    const retryLog = attempt === 0 ? this.#logger.warn.bind(this.#logger) : this.#logger.debug.bind(this.#logger);
                     retryLog(formatCompact({
                         op: 'reconnect',
                         endpoint: this.name,
@@ -185,9 +173,9 @@ export class IcqqIpcEndpoint {
         // 置空 ipc：start 前 / stop 后的 request() 走防御性报错而非 TypeError
         this.ipc = undefined;
         this.#started = false;
-        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.name }));
+        this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
-    async send({ target, payload }) {
+    async send({ conversation, payload }) {
         if (!this.ipc) {
             throw new Error(`icqq endpoint ${this.name} 未连接（IPC 未初始化或已停止），无法发送消息`);
         }
@@ -196,7 +184,7 @@ export class IcqqIpcEndpoint {
             ? materializeOutboundBase64(payload, mediaMode)
             : payload;
         const message = formatOutboundBody(content);
-        const parsed = parseSendTarget(target);
+        const parsed = icqqOutboundTarget(conversation);
         let action;
         let params;
         switch (parsed.kind) {
@@ -227,15 +215,11 @@ export class IcqqIpcEndpoint {
         }
         const resp = await this.ipc.request(action, params);
         if (!resp.ok) {
+            this.#logger.warn(`send failed ${conversation.kind}:${conversation.id} | ${resp.error} | ${truncatePreview(typeof message === 'string' ? message : String(message), 80)}`);
             throw new Error(`发送消息失败: ${resp.error}`);
         }
         const messageId = String(resp.data?.message_id ?? `sent_${Date.now()}`);
-        logger.debug(formatCompact({
-            op: 'icqq_send',
-            endpoint: this.name,
-            target,
-            messageId,
-        }));
+        this.#logger.info(`send ${conversation.kind}:${conversation.id} | id: ${messageId} | ${truncatePreview(typeof message === 'string' ? message : String(message), 80)}`);
         return messageId;
     }
     // ── 消息回应（activity-feedback / typing reaction）────────────────────
@@ -265,7 +249,7 @@ export class IcqqIpcEndpoint {
                 id: emojiId,
             });
             if (!resp.ok) {
-                logger.warn(formatCompact({
+                this.#logger.warn(formatCompact({
                     op: 'add_reaction',
                     endpoint: this.name,
                     message_id: messageId,
@@ -276,7 +260,7 @@ export class IcqqIpcEndpoint {
                 }));
                 return null;
             }
-            logger.debug(formatCompact({
+            this.#logger.debug(formatCompact({
                 op: 'add_reaction',
                 endpoint: this.name,
                 message_id: messageId,
@@ -287,7 +271,7 @@ export class IcqqIpcEndpoint {
             return emojiId;
         }
         catch (error) {
-            logger.warn(formatCompact({
+            this.#logger.warn(formatCompact({
                 op: 'add_reaction',
                 endpoint: this.name,
                 message_id: messageId,
@@ -307,7 +291,7 @@ export class IcqqIpcEndpoint {
                 id: emojiId,
             });
             if (!resp.ok) {
-                logger.warn(formatCompact({
+                this.#logger.warn(formatCompact({
                     op: 'remove_reaction',
                     endpoint: this.name,
                     message_id: messageId,
@@ -318,7 +302,7 @@ export class IcqqIpcEndpoint {
                 }));
                 return;
             }
-            logger.debug(formatCompact({
+            this.#logger.debug(formatCompact({
                 op: 'remove_reaction',
                 endpoint: this.name,
                 message_id: messageId,
@@ -328,7 +312,7 @@ export class IcqqIpcEndpoint {
             }));
         }
         catch (error) {
-            logger.warn(formatCompact({
+            this.#logger.warn(formatCompact({
                 op: 'remove_reaction',
                 endpoint: this.name,
                 message_id: messageId,
@@ -345,7 +329,7 @@ export class IcqqIpcEndpoint {
         try {
             const resp = await this.request(Actions.RECALL_MSG, { message_id: messageId });
             if (!resp.ok) {
-                logger.warn(formatCompact({
+                this.#logger.warn(formatCompact({
                     op: 'recall_message',
                     endpoint: this.name,
                     message_id: messageId,
@@ -354,7 +338,7 @@ export class IcqqIpcEndpoint {
                 }));
                 return;
             }
-            logger.debug(formatCompact({
+            this.#logger.debug(formatCompact({
                 op: 'recall_message',
                 endpoint: this.name,
                 message_id: messageId,
@@ -362,7 +346,7 @@ export class IcqqIpcEndpoint {
             }));
         }
         catch (error) {
-            logger.warn(formatCompact({
+            this.#logger.warn(formatCompact({
                 op: 'recall_message',
                 endpoint: this.name,
                 message_id: messageId,
@@ -499,13 +483,14 @@ export class IcqqIpcEndpoint {
     }
     /** Test / internal: admit when open. */
     admit(msg) {
+        const conversation = msg.conversation;
         if (!this.#open) {
-            logger.debug(formatCompact({
+            this.#logger.debug(formatCompact({
                 op: 'icqq_inbound_skip',
                 reason: 'endpoint_closed',
                 endpoint: this.name,
                 id: msg.id,
-                target: msg.target,
+                target: `${conversation.kind}:${conversation.id}`,
             }));
             return;
         }
@@ -515,34 +500,31 @@ export class IcqqIpcEndpoint {
             content: msg.segments,
             rawMessage: msg.content,
         });
-        logger.debug(formatCompact({
-            op: 'icqq_inbound_admit',
-            endpoint: this.name,
-            id: msg.id,
-            target: msg.target,
-            sender: msg.sender,
-            channelType: msg.channelType,
-            mentioned: mentioned || undefined,
-            preview: msg.content.slice(0, 80),
-            segments: summarizeSegmentTypes(msg.segments),
-        }));
+        this.#logger.info(`recv ${conversation.kind}:${conversation.id}`
+            + (msg.sender ? ` from ${msg.sender.name ?? msg.sender.id}` : '')
+            + (mentioned ? ' (mentioned)' : '')
+            + ` | ${truncatePreview(msg.content, 80)}`);
+        const quoteId = msg.metadata?.quote_id;
+        const { quote_id: _dropQuoteId, ...restMetadata } = msg.metadata ?? {};
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target: msg.target,
+            conversation,
+            message: { conversation, id: msg.id },
             content: msg.content,
             ...(msg.segments ? { segments: msg.segments } : {}),
             sender: msg.sender,
-            id: msg.id,
+            endpointId: this.name,
+            ...(mentioned ? { mentioned: true } : {}),
+            ...(quoteId ? { replyTo: { id: String(quoteId) } } : {}),
             metadata: Object.freeze({
-                endpoint: this.name,
                 channelType: msg.channelType,
-                ...msg.metadata,
-                ...(mentioned ? { mentioned: true } : {}),
+                ...restMetadata,
             }),
         }).catch((err) => {
-            logger.warn(formatCompact({
-                op: 'icqq_gateway_receive_failed',
-                target: msg.target,
+            this.#logger.warn(formatCompact({
+                op: 'recv',
+                endpoint: this.name,
+                target: `${conversation.kind}:${conversation.id}`,
+                ok: false,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });
@@ -585,7 +567,7 @@ export class IcqqIpcEndpoint {
             return;
         const data = payload;
         if (shouldSkipSelfInboundMessage(data)) {
-            logger.debug(formatCompact({
+            this.#logger.debug(formatCompact({
                 op: 'icqq_inbound_skip',
                 reason: 'self',
                 endpoint: this.name,
@@ -596,7 +578,7 @@ export class IcqqIpcEndpoint {
         }
         const normalized = normalizeIcqqInboundMessage(data);
         if (!normalized) {
-            logger.debug(formatCompact({
+            this.#logger.debug(formatCompact({
                 op: 'icqq_inbound_skip',
                 reason: 'normalize_failed',
                 endpoint: this.name,
@@ -606,7 +588,7 @@ export class IcqqIpcEndpoint {
             return;
         }
         if (!this.#inboundDeduper.shouldProcess(normalized.messageId)) {
-            logger.debug(formatCompact({
+            this.#logger.debug(formatCompact({
                 op: 'icqq_inbound_skip',
                 reason: 'dedupe',
                 endpoint: this.name,
@@ -616,14 +598,18 @@ export class IcqqIpcEndpoint {
         }
         this.admit({
             id: normalized.messageId,
-            target: formatInboundTarget({
+            conversation: icqqInboundConversation(String(this.#options.id), {
                 channelType: normalized.channelType,
                 channelId: normalized.channelId,
                 channelParentGroupId: normalized.channelParentGroupId,
             }),
             content: formatInboundContent(normalized.rawMessage),
             segments: normalized.content,
-            sender: normalized.userId,
+            sender: {
+                id: normalized.userId,
+                name: normalized.nickname || undefined,
+                ...(normalized.senderRole ? { roles: [normalized.senderRole] } : {}),
+            },
             channelType: normalized.channelType,
             metadata: buildIcqqQuoteMetadata(data, {
                 nickname: normalized.nickname,
@@ -637,7 +623,7 @@ export class IcqqIpcEndpoint {
             return;
         const normalized = normalizeIcqqGuildInboundMessage(payload);
         if (!normalized) {
-            logger.debug(formatCompact({
+            this.#logger.debug(formatCompact({
                 op: 'icqq_inbound_skip',
                 reason: 'guild_normalize_failed',
                 endpoint: this.name,
@@ -646,7 +632,7 @@ export class IcqqIpcEndpoint {
         }
         this.#guildCatalog.upsertFromInbound(normalized.raw);
         if (!this.#inboundDeduper.shouldProcess(`guild:${normalized.messageId}`)) {
-            logger.debug(formatCompact({
+            this.#logger.debug(formatCompact({
                 op: 'icqq_inbound_skip',
                 reason: 'dedupe',
                 endpoint: this.name,
@@ -656,14 +642,14 @@ export class IcqqIpcEndpoint {
         }
         this.admit({
             id: normalized.messageId,
-            target: formatInboundTarget({
+            conversation: icqqInboundConversation(String(this.#options.id), {
                 channelType: 'channel',
                 channelId: normalized.channelId,
                 guildId: normalized.guildId,
             }),
             content: formatInboundContent(normalized.rawMessage),
             segments: normalized.content,
-            sender: normalized.userId,
+            sender: { id: normalized.userId, name: normalized.nickname || undefined },
             channelType: 'channel',
             metadata: {
                 guildId: normalized.guildId,
@@ -674,7 +660,7 @@ export class IcqqIpcEndpoint {
     /** 收件箱行公共前缀：adapter 槽 localName + endpoint live 名（uin）。 */
     #inboxBase() {
         const id = String(this.#options.id);
-        return { adapter: id.split('\0').pop() ?? id, endpointId: this.name };
+        return { adapter: id.split('\0').pop() ?? id, endpointKey: this.name };
     }
     #recordInboxRequest(payload) {
         const hooks = this.#options.inbox;
@@ -729,7 +715,7 @@ export class IcqqIpcEndpoint {
             }
         }
         catch (error) {
-            logger.debug(formatCompact({
+            this.#logger.debug(formatCompact({
                 op: 'inbox_pull_system_msg',
                 endpoint: this.name,
                 error: error instanceof Error ? error.message : String(error),
@@ -773,22 +759,8 @@ function toNumericId(value, label) {
     }
     return n;
 }
-function summarizeSegmentTypes(segments) {
-    if (!segments?.length)
-        return undefined;
-    return segments
-        .map((segment) => {
-        if (typeof segment.type === 'string')
-            return segment.type;
-        if (segment.type && typeof segment.type === 'object' && 'name' in segment.type) {
-            return String(segment.type.name);
-        }
-        return '?';
-    })
-        .join(',');
-}
 async function defaultCreateIpc(config) {
-    const uin = Number(config.name);
+    const uin = Number(config.id);
     if (config.rpc) {
         return IpcClient.connectRpc(config.rpc);
     }

package/lib/icqq-agent-deps.d.ts

@@ -14,12 +14,12 @@ export interface IcqqAgentEndpoint {
     request(action: string, params?: Record<string, unknown>): Promise<IpcResponse>;
 }
 export interface IcqqAgentDeps {
-    getEndpoint: (endpointId: string) => IcqqAgentEndpoint;
+    getEndpoint: (endpointKey: string) => IcqqAgentEndpoint;
     getAdapter?: () => {
         getEndpoint: (id: string) => IcqqAgentEndpoint;
     };
 }
-export declare function registerIcqqAgentEndpoint(endpointId: string, endpoint: IcqqAgentEndpoint): () => void;
+export declare function registerIcqqAgentEndpoint(endpointKey: string, endpoint: IcqqAgentEndpoint): () => void;
 /** Optional override used by tests / transitional callers. Pass `null` to clear. */
 export declare function setIcqqAgentDeps(deps: IcqqAgentDeps | null): void;
 export declare function getIcqqAgentDeps(): IcqqAgentDeps;

package/lib/icqq-agent-deps.js

@@ -4,11 +4,11 @@
  */
 const endpoints = new Map();
 let override = null;
-export function registerIcqqAgentEndpoint(endpointId, endpoint) {
-    endpoints.set(endpointId, endpoint);
+export function registerIcqqAgentEndpoint(endpointKey, endpoint) {
+    endpoints.set(endpointKey, endpoint);
     return () => {
-        if (endpoints.get(endpointId) === endpoint) {
-            endpoints.delete(endpointId);
+        if (endpoints.get(endpointKey) === endpoint) {
+            endpoints.delete(endpointKey);
         }
     };
 }
@@ -16,10 +16,10 @@ export function registerIcqqAgentEndpoint(endpointId, endpoint) {
 export function setIcqqAgentDeps(deps) {
     override = deps;
 }
-function lookup(endpointId) {
-    const registered = endpoints.get(endpointId);
+function lookup(endpointKey) {
+    const registered = endpoints.get(endpointKey);
     if (!registered)
-        throw new Error(`Endpoint ${endpointId} 不存在`);
+        throw new Error(`Endpoint ${endpointKey} 不存在`);
     return registered;
 }
 export function getIcqqAgentDeps() {

package/lib/icqq-endpoint-commands.js

@@ -4,7 +4,7 @@
  * ICQQ 的凭据由外部守护进程（@icqqjs/cli）按账号持有（~/.icqq/<uin>/），
  * 其 IPC/RPC 协议是「按 uin 连接 + auth + 账号级 action」，没有 add-account /
  * 触发 login 的 action——扫码登录只能经 `icqq login <uin>` CLI 完成。
- * 因此 add 不走 kv 凭据录入，而是 bindFlow：校验 uin、把 { name: '<uin>' }
+ * 因此 add 不走 kv 凭据录入，而是 bindFlow：校验 uin、把 { id: '<uin>' }
  * 追加到 plugins.icqq.endpoints，并引导用户先完成守护进程登录。
  */
 import { addEndpointToConfig, createEndpointCommands } from '@zhin.js/adapter';
@@ -16,17 +16,17 @@ export const icqqEndpointCommands = createEndpointCommands({
     running: (use) => use(icqqRuntimeStateToken).endpoints.values(),
     describeEntry: (entry) => (entry.rpc ? 'rpc（远程守护进程）' : 'ipc（本地守护进程）'),
     addDescription: '登记 ICQQ endpoint（uin 需先经 icqq login 完成扫码登录；重启 zhin 生效）',
-    bindFlow: ({ name }) => {
-        if (!name) {
+    bindFlow: ({ id }) => {
+        if (!id) {
             return '用法：icqq.endpoint add <uin>（uin 为纯数字 QQ 号，且需先执行 icqq login <uin> 完成扫码登录）';
         }
-        if (!/^\d+$/.test(name)) {
+        if (!/^\d+$/.test(id)) {
             return 'icqq endpoint 名必须是纯数字 QQ 号（uin）';
         }
         try {
-            const filePath = addEndpointToConfig('icqq', { name });
-            return (`✅ endpoint「${name}」已追加到 ${filePath} 的 plugins.icqq.endpoints。\n` +
-                `⚠️ 请确保已执行 icqq login ${name} 启动守护进程并完成扫码登录；重启 zhin 后生效。`);
+            const filePath = addEndpointToConfig('icqq', { id });
+            return (`✅ endpoint「${id}」已追加到 ${filePath} 的 plugins.icqq.endpoints。\n` +
+                `⚠️ 请确保已执行 icqq login ${id} 启动守护进程并完成扫码登录；重启 zhin 后生效。`);
         }
         catch (error) {
             return `添加失败：${error instanceof Error ? error.message : String(error)}`;

package/lib/icqq-inbox.d.ts

@@ -10,7 +10,7 @@ import type { IpcSystemMessage } from './types.js';
 /** 行级公共前缀：adapter 槽 localName + endpoint live 名（uin）。 */
 export interface IcqqInboxBase {
     readonly adapter: string;
-    readonly endpointId: string;
+    readonly endpointKey: string;
 }
 /** post_type=request / request.* 判定（OneBot 事件壳）。 */
 export declare function isIcqqRequestPayload(payload: unknown): boolean;