@zhin.js/adapter-icqq 8.0.2 → 8.0.5

package/src/protocol.ts

@@ -13,6 +13,7 @@
  */
 
 import { pickCredential } from '@zhin.js/adapter';
+import type { ConversationRef } from '@zhin.js/im-contract';
 import type { MessageSegment } from "zhin.js";
 import { resolveCqMediaArg } from "./cq-message.js";
 
@@ -272,7 +273,7 @@ export 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?: {
@@ -283,7 +284,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?: {
@@ -296,7 +297,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?: {
@@ -313,14 +314,14 @@ export interface IcqqWireSegment {
 
 export interface IcqqInboundMessage {
   readonly id: string;
-  readonly target: string;
+  readonly conversation: ConversationRef;
   readonly content: string;
   /**
    * 结构化段视图（canonical Segment，经 toCanonicalSegments 归一）。
    * 与 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>;
 }
@@ -333,10 +334,10 @@ export type ParsedIcqqSendTarget =
 
 export function resolveIcqqConfig(config: IcqqAdapterConfig = {}): ResolvedIcqqConfig {
   const entry = config.endpoints?.find((item) => item.context === 'icqq');
-  const name = pickCredential(config.name, entry?.name, process.env.ICQQ_ACCOUNT);
-  if (!/^\d+$/.test(name)) {
+  const id = pickCredential(config.id, entry?.id, process.env.ICQQ_ACCOUNT);
+  if (!/^\d+$/.test(id)) {
     throw new TypeError(
-      'ICQQ adapter requires numeric name (QQ uin) via plugins.<key>.name or ICQQ_ACCOUNT',
+      'ICQQ adapter requires numeric id (QQ uin) via plugins.<key>.id or ICQQ_ACCOUNT',
     );
   }
   const autoReconnect = config.autoReconnect ?? entry?.autoReconnect ?? true;
@@ -347,58 +348,66 @@ export function resolveIcqqConfig(config: IcqqAdapterConfig = {}): ResolvedIcqqC
     : undefined;
   return {
     context: 'icqq',
-    name,
+    id,
     autoReconnect,
     ...(outboundMedia ? { outboundMedia } : {}),
     ...(rpc ? { rpc } : {}),
   };
 }
 
-/** Gateway reply target: `private:uid` / `group:gid` / `temp:gid:uid` / `channel:guild:channel`. */
-export function formatInboundTarget(input: {
+/**
+ * 入站归一化 → ConversationRef：群临时会话（temp）映射为群容器内的 private
+ * 会话（parent kind 'group'）；频道消息的所属 guild 进 `parent`（kind 'channel'）。
+ */
+export function icqqInboundConversation(endpointKey: string, input: {
   readonly channelType: 'private' | 'group' | 'channel';
   readonly channelId: string;
   readonly channelParentGroupId?: string;
   readonly guildId?: string;
-}): string {
+}): ConversationRef {
+  const endpoint = { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey };
   if (input.channelType === 'private' && input.channelParentGroupId) {
-    return `temp:${input.channelParentGroupId}:${input.channelId}`;
+    return {
+      endpoint,
+      kind: 'private',
+      id: input.channelId,
+      parent: { kind: 'group', id: input.channelParentGroupId },
+    };
   }
   if (input.channelType === 'channel' && input.guildId) {
-    return `channel:${input.guildId}:${input.channelId}`;
+    return {
+      endpoint,
+      kind: 'channel',
+      id: input.channelId,
+      parent: { kind: 'channel', id: input.guildId },
+    };
   }
-  return `${input.channelType}:${input.channelId}`;
+  return { endpoint, kind: input.channelType, id: input.channelId };
 }
 
-export function parseSendTarget(target: string): ParsedIcqqSendTarget {
-  const trimmed = target.trim();
-  if (trimmed.startsWith('temp:')) {
-    const rest = trimmed.slice(5);
-    const [groupId, userId] = rest.split(':');
-    if (!groupId || !userId) throw new TypeError(`Invalid icqq temp target: ${target}`);
-    return { kind: 'temp', groupId: Number(groupId), userId: Number(userId) };
-  }
-  if (trimmed.startsWith('channel:')) {
-    const rest = trimmed.slice(8);
-    const idx = rest.indexOf(':');
-    if (idx <= 0) throw new TypeError(`Invalid icqq channel target: ${target}`);
+/**
+ * 出站：从 ConversationRef 派生 IPC action 路由。
+ * 群容器（parent kind 'group'）内的 private 会话即 ICQQ 群临时会话（temp）。
+ */
+export function icqqOutboundTarget(conversation: ConversationRef): ParsedIcqqSendTarget {
+  if (conversation.kind === 'private' && conversation.parent?.kind === 'group') {
     return {
-      kind: 'channel',
-      guildId: rest.slice(0, idx),
-      channelId: rest.slice(idx + 1),
+      kind: 'temp',
+      groupId: Number(conversation.parent.id),
+      userId: Number(conversation.id),
     };
   }
-  if (trimmed.startsWith('private:')) {
-    return { kind: 'private', userId: Number(trimmed.slice(8)) };
+  if (conversation.kind === 'private') {
+    return { kind: 'private', userId: Number(conversation.id) };
   }
-  if (trimmed.startsWith('group:')) {
-    return { kind: 'group', groupId: Number(trimmed.slice(6)) };
+  if (conversation.kind === 'group') {
+    return { kind: 'group', groupId: Number(conversation.id) };
   }
-  // Bare numeric id → private (common reply path)
-  if (/^\d+$/.test(trimmed)) {
-    return { kind: 'private', userId: Number(trimmed) };
+  const guildId = conversation.parent?.kind === 'channel' ? conversation.parent.id : undefined;
+  if (!guildId) {
+    throw new TypeError(`Invalid icqq channel conversation (missing guild parent): ${conversation.id}`);
   }
-  throw new TypeError(`Invalid icqq send target: ${target}`);
+  return { kind: 'channel', guildId, channelId: conversation.id };
 }
 
 export function formatOutboundBody(payload: unknown): string {