@zhin.js/adapter-icqq 6.0.3 → 7.0.1

package/src/icqq-inbox.ts

@@ -0,0 +1,155 @@
+/**
+ * icqq IPC request/notice 事件 → 统一收件箱行（unified_inbox_request / unified_inbox_notice）。
+ *
+ * daemon 经 IpcEvent 推送 icqq client.em 分发的全部事件（见 protocol.ts），
+ * 好友/群请求（request.friend.add、request.group.add、request.group.invite）
+ * 与通知（notice.friend.*、notice.group.*）随事件流实时到达，无需轮询；
+ * endpoint 启动时补一次 GET_SYSTEM_MSG 拉取离线期间积存的待处理请求。
+ */
+import type { IpcSystemMessage } from './types.js';
+
+/** 行级公共前缀：adapter 槽 localName + endpoint live 名（uin）。 */
+export interface IcqqInboxBase {
+  readonly adapter: string;
+  readonly endpointId: string;
+}
+
+/** post_type=request / request.* 判定（OneBot 事件壳）。 */
+export function isIcqqRequestPayload(payload: unknown): boolean {
+  const postType = (payload as { post_type?: unknown } | null)?.post_type;
+  return typeof postType === 'string'
+    && (postType === 'request' || postType.startsWith('request.'));
+}
+
+/** post_type=notice / notice.* 判定。 */
+export function isIcqqNoticePayload(payload: unknown): boolean {
+  const postType = (payload as { post_type?: unknown } | null)?.post_type;
+  return typeof postType === 'string'
+    && (postType === 'notice' || postType.startsWith('notice.'));
+}
+
+/**
+ * request 事件载荷 → unified_inbox_request 行。
+ * platform_request_id 取 flag（审批回执句柄），缺省回退 seq；两者皆无则无法审批，丢弃。
+ */
+export function buildIcqqInboxRequestRow(
+  payload: Record<string, unknown>,
+  base: IcqqInboxBase,
+): Record<string, unknown> | null {
+  const userId = payload.user_id ?? payload.actor_id;
+  if (userId == null) return null;
+  const flag = asNonEmptyString(payload.flag);
+  const platformRequestId = flag ?? (payload.seq != null ? String(payload.seq) : '');
+  if (!platformRequestId) return null;
+  const requestType = asNonEmptyString(payload.request_type) ?? asNonEmptyString(payload.type);
+  const groupId = payload.group_id;
+  const isGroup = requestType === 'group' || groupId != null;
+  return {
+    adapter: base.adapter,
+    endpoint_id: base.endpointId,
+    platform_request_id: platformRequestId,
+    type: isGroup ? 'group' : (requestType ?? 'friend'),
+    scene_type: isGroup ? 'group' : null,
+    scene_id: String(groupId ?? userId),
+    sub_type: asNonEmptyString(payload.sub_type),
+    actor_id: String(userId),
+    actor_name: asNonEmptyString(payload.nickname),
+    comment: asNonEmptyString(payload.comment),
+    created_at: toMillis(payload.time),
+    resolved: 0,
+    resolved_at: null,
+    consumed: 0,
+    consumed_at: null,
+  };
+}
+
+/**
+ * notice 事件载荷 → unified_inbox_notice 行。
+ * 事件本身无稳定 id，platform_notice_id 由 time + actor + type 合成（配合去重）。
+ */
+export function buildIcqqInboxNoticeRow(
+  payload: Record<string, unknown>,
+  base: IcqqInboxBase,
+): Record<string, unknown> | null {
+  const noticeType = asNonEmptyString(payload.notice_type) ?? asNonEmptyString(payload.type);
+  if (!noticeType) return null;
+  const subType = asNonEmptyString(payload.sub_type);
+  const userId = payload.user_id;
+  const operatorId = payload.operator_id;
+  const groupId = payload.group_id;
+  const createdAt = toMillis(payload.time);
+  const actorId = operatorId ?? userId;
+  const platformNoticeId = asNonEmptyString(payload.notice_id)
+    ?? (payload.seq != null ? String(payload.seq) : undefined)
+    ?? `${createdAt}_${String(actorId ?? '')}_${noticeType}${subType ? `.${subType}` : ''}`;
+  const targetId = userId != null && String(userId) !== String(actorId ?? '') ? userId : undefined;
+  return {
+    adapter: base.adapter,
+    endpoint_id: base.endpointId,
+    platform_notice_id: platformNoticeId,
+    type: noticeType,
+    scene_type: groupId != null ? 'group' : null,
+    scene_id: String(groupId ?? userId ?? operatorId ?? ''),
+    sub_type: subType,
+    actor_id: actorId != null ? String(actorId) : null,
+    actor_name: asNonEmptyString(payload.nickname),
+    target_id: targetId != null ? String(targetId) : null,
+    target_name: null,
+    payload: safeJson(payload),
+    created_at: createdAt,
+    consumed: 0,
+    consumed_at: null,
+  };
+}
+
+/**
+ * GET_SYSTEM_MSG 返回项 → unified_inbox_request 行（启动时首次拉取）。
+ * friend 列表项 type 语义即好友请求；group 列表项 type 为 add/invite（记 sub_type）。
+ */
+export function buildIcqqSystemRequestRow(
+  message: IpcSystemMessage,
+  kind: 'friend' | 'group',
+  base: IcqqInboxBase,
+): Record<string, unknown> | null {
+  if (message.user_id == null) return null;
+  const platformRequestId = asNonEmptyString(message.flag)
+    ?? (message.seq != null ? String(message.seq) : '');
+  if (!platformRequestId) return null;
+  return {
+    adapter: base.adapter,
+    endpoint_id: base.endpointId,
+    platform_request_id: platformRequestId,
+    type: kind,
+    scene_type: kind === 'group' ? 'group' : null,
+    scene_id: String(kind === 'group' ? (message.group_id ?? message.user_id) : message.user_id),
+    sub_type: kind === 'group' ? (asNonEmptyString(message.type) ?? null) : null,
+    actor_id: String(message.user_id),
+    actor_name: asNonEmptyString(message.nickname),
+    comment: asNonEmptyString(message.comment),
+    created_at: toMillis(message.time),
+    resolved: 0,
+    resolved_at: null,
+    consumed: 0,
+    consumed_at: null,
+  };
+}
+
+function asNonEmptyString(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : null;
+}
+
+/** oicq 事件 time 为秒；缺失时回退当前时间。 */
+function toMillis(time: unknown): number {
+  const seconds = Number(time);
+  return Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : Date.now();
+}
+
+function safeJson(value: unknown): string {
+  try {
+    return JSON.stringify(value ?? {});
+  } catch {
+    return '{}';
+  }
+}

package/src/icqq-runtime-state.ts

@@ -0,0 +1,7 @@
+/**
+ * ICQQ 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
+ * 由 plugin.ts setup() provide，adapter create 与 `icqq endpoint` 命令共享（同一 owner generation）。
+ */
+import { defineEndpointRuntimeStateToken } from '@zhin.js/adapter';
+
+export const icqqRuntimeStateToken = defineEndpointRuntimeStateToken('icqq');

package/src/index.ts

@@ -20,6 +20,7 @@ export {
   IcqqIpcEndpoint,
   type CreateIcqqIpc,
   type IcqqEndpointOptions,
+  type IcqqInboxHooks,
   type IcqqIpcTransport,
 } from './endpoint.js';
 

package/src/ipc-client.ts

@@ -266,7 +266,7 @@ export class IpcClient {
     try {
       token = (await readFile(getTokenPath(uin), "utf-8")).trim();
     } catch {
-      throw new Error("无法读取认证 token，守护进程可能未运行");
+      throw new Error(`无法读取认证 token，守护进程可能未运行：请先执行 icqq login ${uin} 完成登录并启动守护进程`);
     }
 
     let rpcInfo: { host: string; port: number };
@@ -274,7 +274,7 @@ export class IpcClient {
       const raw = await readFile(getRpcPortPath(uin), "utf-8");
       rpcInfo = JSON.parse(raw);
     } catch {
-      throw new Error("RPC 未启用或守护进程未运行");
+      throw new Error(`RPC 未启用或守护进程未运行：请先执行 icqq login ${uin}，并确认守护进程已启用 RPC`);
     }
 
     return IpcClient.connectRpc({

package/src/outbound-media.ts

@@ -47,8 +47,9 @@ export function resolveIcqqOutboundMediaMode(
 }
 
 /**
- * file 模式：将 segment.data.base64 物化为本机路径。
- * base64 模式：不改动（由 toCqString 生成 base64://，供异机守护进程读取）。
+ * file 模式：将 segment.data.base64（legacy）或 canonical MediaRef
+ * （`data.media`，kind=base64）物化为本机路径，并把 media 改写为 path 引用。
+ * base64 模式：不改动（由 toCqString/formatOutboundBody 生成 base64://，供异机守护进程读取）。
  */
 export function materializeOutboundBase64(
   content: SendContent,
@@ -61,10 +62,22 @@ export function materializeOutboundBase64(
     if (typeof seg === "string") return seg;
     const { type, data } = seg as MessageSegment;
     const d = data as Record<string, unknown>;
-    const b64 = d.base64 ?? d.data;
-    if (typeof b64 !== "string" || !b64) return seg;
+    const media = d.media as
+      | { kind?: unknown; value?: unknown; mime_type?: unknown }
+      | undefined;
+    const mediaBase64 =
+      media && media.kind === "base64" && typeof media.value === "string" && media.value
+        ? media.value.replace(/^base64:\/\//, "")
+        : undefined;
+    const legacyBase64 = d.base64 ?? d.data;
+    const b64 =
+      mediaBase64 ??
+      (typeof legacyBase64 === "string" && legacyBase64 ? legacyBase64 : undefined);
+    if (!b64) return seg;
 
-    const mime = String(d.mime ?? d.mimeType ?? "");
+    const mime = String(
+      d.mime ?? d.mimeType ?? (typeof media?.mime_type === "string" ? media.mime_type : "") ?? "",
+    );
     if (type === "image" || type === "record" || type === "audio" || type === "video") {
       const filePath = spoolBase64ToFile(
         b64,
@@ -75,6 +88,11 @@ export function materializeOutboundBase64(
         type,
         data: {
           ...d,
+          media: {
+            kind: "path",
+            value: filePath,
+            ...(mime ? { mime_type: mime } : {}),
+          },
           file: filePath,
           url: filePath,
         },

package/src/protocol.ts

@@ -13,6 +13,7 @@
  */
 
 import { pickCredential } from '@zhin.js/adapter';
+import type { MessageSegment } from "zhin.js";
 
 /** CLI → Daemon 请求 */
 export type IpcRequest = {
@@ -313,6 +314,11 @@ export interface IcqqInboundMessage {
   readonly id: string;
   readonly target: string;
   readonly content: string;
+  /**
+   * 结构化段视图（canonical Segment，经 toCanonicalSegments 归一）。
+   * 与 content（CQ 原文纯文本视图）同源，随 gateway.receive 上送。
+   */
+  readonly segments?: readonly MessageSegment[];
   readonly sender: string;
   readonly channelType: 'private' | 'group' | 'channel';
   readonly metadata?: Record<string, unknown>;
@@ -422,16 +428,16 @@ export function formatOutboundBody(payload: unknown): string {
       case 'mention':
         return `[at:${item.data?.qq ?? item.data?.id ?? item.data?.target ?? ''}]`;
       case 'image':
-        return `[image:${item.data?.file || item.data?.url || base64Media(item.data) || ''}]`;
+        return `[image:${mediaRefValue(item.data) || item.data?.file || item.data?.url || base64Media(item.data) || ''}]`;
       case 'face':
         return `[face:${item.data?.id ?? ''}]`;
       case 'reply':
         return `[reply:${item.data?.message_id ?? item.data?.id ?? ''}]`;
       case 'record':
       case 'audio':
-        return `[record:${item.data?.file || item.data?.url || base64Media(item.data) || ''}]`;
+        return `[record:${mediaRefValue(item.data) || item.data?.file || item.data?.url || base64Media(item.data) || ''}]`;
       case 'video':
-        return `[video:${item.data?.file || item.data?.url || base64Media(item.data) || ''}]`;
+        return `[video:${mediaRefValue(item.data) || item.data?.file || item.data?.url || base64Media(item.data) || ''}]`;
       default:
         return String(item.data?.text ?? '');
     }
@@ -449,6 +455,22 @@ function base64Media(data: Record<string, unknown> | undefined): string | undefi
   return typeof b64 === 'string' && b64 ? `base64://${b64}` : undefined;
 }
 
+/**
+ * canonical MediaRef（`data.media`，见 built/segment-contract）→ CQ 媒体值：
+ * base64 → `base64://` 前缀（守护进程解码）；url/path 直出。
+ * file 模式下 materializeOutboundBase64 已把 base64 落盘并把 media 改写为 path 引用。
+ */
+function mediaRefValue(data: Record<string, unknown> | undefined): string | undefined {
+  const media = data?.media;
+  if (!media || typeof media !== 'object' || Array.isArray(media)) return undefined;
+  const { kind, value } = media as { kind?: unknown; value?: unknown };
+  if (typeof value !== 'string' || !value) return undefined;
+  if (kind === 'base64') {
+    return value.startsWith('base64://') ? value : `base64://${value}`;
+  }
+  return value;
+}
+
 /** 段对象判定：`{ type: string, data? }`（非数组 payload 的防御入口）。 */
 function isWireSegment(value: unknown): value is IcqqWireSegment {
   return typeof value === 'object'

package/src/types.ts

@@ -76,3 +76,19 @@ export interface IpcMemberInfo {
   last_sent_time?: number;
   shutup_time?: number;
 }
+
+/**
+ * GET_SYSTEM_MSG 归一后的待处理请求（@icqqjs/cli NormalizedSystemMessage）。
+ * friendRequests 与 groupRequests 均为该形状，按 flag 处理。
+ */
+export interface IpcSystemMessage {
+  type: string;
+  user_id?: number;
+  nickname?: string;
+  group_id?: number;
+  group_name?: string;
+  comment?: string;
+  flag?: string;
+  seq?: number;
+  time?: number;
+}