@zhin.js/adapter-icqq 8.0.3 → 8.0.6

package/CHANGELOG.md

@@ -1,5 +1,88 @@
 # @zhin.js/adapter-icqq
 
+## 8.0.6
+
+### Patch Changes
+
+- Updated dependencies [2d0a622]
+  - @zhin.js/command@1.0.10
+  - @zhin.js/adapter@1.1.7
+  - @zhin.js/core@1.5.5
+  - @zhin.js/agent@1.1.6
+  - zhin.js@6.0.5
+
+## 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

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.js

@@ -1,4 +1,4 @@
-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';
@@ -6,8 +6,8 @@ import { IcqqGuildCatalog, isIcqqGuildIpcEvent, normalizeIcqqGuildInboundMessage
 import { IpcClient } from './ipc-client.js';
 import { materializeOutboundBase64, resolveIcqqOutboundMediaMode, } from './outbound-media.js';
 import { Actions, formatInboundContent, formatOutboundBody, icqqInboundConversation, icqqOutboundTarget, } from './protocol.js';
-const logger = getLogger('icqq');
 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,7 +173,7 @@ 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({ conversation, payload }) {
         if (!this.ipc) {
@@ -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: `${conversation.kind}:${conversation.id}`,
-            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,
@@ -501,7 +485,7 @@ export class IcqqIpcEndpoint {
     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,
@@ -516,33 +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: `${conversation.kind}:${conversation.id}`,
-            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({
             conversation,
             message: { conversation, id: msg.id },
             content: msg.content,
             ...(msg.segments ? { segments: msg.segments } : {}),
             sender: msg.sender,
+            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',
+            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,
@@ -623,7 +605,11 @@ export class IcqqIpcEndpoint {
             }),
             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,
@@ -663,7 +649,7 @@ export class IcqqIpcEndpoint {
             }),
             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;

package/lib/icqq-inbox.js

@@ -27,7 +27,7 @@ export function buildIcqqInboxRequestRow(payload, base) {
     const isGroup = requestType === 'group' || groupId != null;
     return {
         adapter: base.adapter,
-        endpoint_id: base.endpointId,
+        endpoint_id: base.endpointKey,
         platform_request_id: platformRequestId,
         type: isGroup ? 'group' : (requestType ?? 'friend'),
         scene_type: isGroup ? 'group' : null,
@@ -63,7 +63,7 @@ export function buildIcqqInboxNoticeRow(payload, base) {
     const targetId = userId != null && String(userId) !== String(actorId ?? '') ? userId : undefined;
     return {
         adapter: base.adapter,
-        endpoint_id: base.endpointId,
+        endpoint_id: base.endpointKey,
         platform_notice_id: platformNoticeId,
         type: noticeType,
         scene_type: groupId != null ? 'group' : null,
@@ -92,7 +92,7 @@ export function buildIcqqSystemRequestRow(message, kind, base) {
         return null;
     return {
         adapter: base.adapter,
-        endpoint_id: base.endpointId,
+        endpoint_id: base.endpointKey,
         platform_request_id: platformRequestId,
         type: kind,
         scene_type: kind === 'group' ? 'group' : null,

package/lib/protocol.d.ts

@@ -199,7 +199,7 @@ export declare const Actions: {
 };
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface IcqqAdapterConfig {
-    readonly name?: string;
+    readonly id?: string;
     readonly autoReconnect?: boolean;
     readonly outboundMedia?: 'file' | 'base64';
     readonly rpc?: {
@@ -210,7 +210,7 @@ export interface IcqqAdapterConfig {
     /** Transitional: legacy root `endpoints[]` with `context: icqq`. */
     readonly endpoints?: ReadonlyArray<{
         readonly context?: string;
-        readonly name?: string;
+        readonly id?: string;
         readonly autoReconnect?: boolean;
         readonly outboundMedia?: 'file' | 'base64';
         readonly rpc?: {
@@ -222,7 +222,7 @@ export interface IcqqAdapterConfig {
 }
 export interface ResolvedIcqqConfig {
     readonly context: 'icqq';
-    readonly name: string;
+    readonly id: string;
     readonly autoReconnect: boolean;
     readonly outboundMedia?: 'file' | 'base64';
     readonly rpc?: {
@@ -244,7 +244,10 @@ export interface IcqqInboundMessage {
      * 与 content（CQ 原文纯文本视图）同源，随 gateway.receive 上送。
      */
     readonly segments?: readonly MessageSegment[];
-    readonly sender: string;
+    readonly sender: {
+        readonly id: string;
+        readonly name?: string;
+    };
     readonly channelType: 'private' | 'group' | 'channel';
     readonly metadata?: Record<string, unknown>;
 }
@@ -268,7 +271,7 @@ export declare function resolveIcqqConfig(config?: IcqqAdapterConfig): ResolvedI
  * 入站归一化 → ConversationRef：群临时会话（temp）映射为群容器内的 private
  * 会话（parent kind 'group'）；频道消息的所属 guild 进 `parent`（kind 'channel'）。
  */
-export declare function icqqInboundConversation(endpointId: string, input: {
+export declare function icqqInboundConversation(endpointKey: string, input: {
     readonly channelType: 'private' | 'group' | 'channel';
     readonly channelId: string;
     readonly channelParentGroupId?: string;

package/lib/protocol.js

@@ -188,9 +188,9 @@ export const Actions = {
 };
 export function resolveIcqqConfig(config = {}) {
     const entry = config.endpoints?.find((item) => item.context === 'icqq');
-    const name = pickCredential(config.name, entry?.name, process.env.ICQQ_ACCOUNT);
-    if (!/^\d+$/.test(name)) {
-        throw new TypeError('ICQQ adapter requires numeric name (QQ uin) via plugins.<key>.name or ICQQ_ACCOUNT');
+    const id = pickCredential(config.id, entry?.id, process.env.ICQQ_ACCOUNT);
+    if (!/^\d+$/.test(id)) {
+        throw new TypeError('ICQQ adapter requires numeric id (QQ uin) via plugins.<key>.id or ICQQ_ACCOUNT');
     }
     const autoReconnect = config.autoReconnect ?? entry?.autoReconnect ?? true;
     const outboundMedia = config.outboundMedia ?? entry?.outboundMedia;
@@ -200,7 +200,7 @@ export function resolveIcqqConfig(config = {}) {
         : undefined;
     return {
         context: 'icqq',
-        name,
+        id,
         autoReconnect,
         ...(outboundMedia ? { outboundMedia } : {}),
         ...(rpc ? { rpc } : {}),
@@ -210,8 +210,8 @@ export function resolveIcqqConfig(config = {}) {
  * 入站归一化 → ConversationRef：群临时会话（temp）映射为群容器内的 private
  * 会话（parent kind 'group'）；频道消息的所属 guild 进 `parent`（kind 'channel'）。
  */
-export function icqqInboundConversation(endpointId, input) {
-    const endpoint = { id: endpointId, adapter: endpointId.split('\0')[0] ?? endpointId };
+export function icqqInboundConversation(endpointKey, input) {
+    const endpoint = { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey };
     if (input.channelType === 'private' && input.channelParentGroupId) {
         return {
             endpoint,