@zhin.js/adapter-icqq 3.0.3 → 3.0.5

package/src/icqq-side-events.ts

@@ -0,0 +1,228 @@
+/**
+ * icqq IPC 非 message 入站：notice / request / meta（对齐 OneBot 与 @icqqjs/icqq EventMap）
+ * @see https://icqq.pages.dev/interfaces/EventMap.html
+ */
+import { Notice, Request, formatCompact } from "zhin.js";
+import type { NoticeType } from "zhin.js";
+import type { RequestType } from "zhin.js";
+import { Actions } from "./protocol.js";
+import type { IpcClient } from "./ipc-client.js";
+
+/** OneBot / icqq 守护进程推送的通用事件字段 */
+export interface IcqqIpcRawEvent {
+  post_type?: string;
+  time?: number;
+  self_id?: number;
+  notice_type?: string;
+  request_type?: string;
+  sub_type?: string;
+  meta_event_type?: string;
+  group_id?: number;
+  user_id?: number;
+  operator_id?: number;
+  flag?: string;
+  comment?: string;
+  [key: string]: unknown;
+}
+
+export function resolveIcqqEventPostType(
+  data: Record<string, unknown>,
+): string | undefined {
+  const pt = data.post_type;
+  if (typeof pt === "string" && pt !== "") return pt;
+  if (data.notice_type != null) return "notice";
+  if (data.request_type != null) return "request";
+  if (data.meta_event_type != null) return "meta_event";
+  return undefined;
+}
+
+export function isIcqqNoticePayload(data: unknown): data is IcqqIpcRawEvent {
+  if (!data || typeof data !== "object") return false;
+  const pt = resolveIcqqEventPostType(data as Record<string, unknown>);
+  return pt === "notice" || (typeof pt === "string" && pt.startsWith("notice."));
+}
+
+export function isIcqqRequestPayload(data: unknown): data is IcqqIpcRawEvent {
+  if (!data || typeof data !== "object") return false;
+  const pt = resolveIcqqEventPostType(data as Record<string, unknown>);
+  return pt === "request" || (typeof pt === "string" && pt.startsWith("request."));
+}
+
+export function isIcqqMetaPayload(data: unknown): data is IcqqIpcRawEvent {
+  if (!data || typeof data !== "object") return false;
+  const pt = resolveIcqqEventPostType(data as Record<string, unknown>);
+  return pt === "meta_event" || (typeof pt === "string" && pt.startsWith("system."));
+}
+
+/** 去重用：notice / request 无稳定 id 时组合键 */
+export function resolveSideEventDedupeKey(
+  data: IcqqIpcRawEvent,
+  kind: "notice" | "request" | "meta",
+): string {
+  if (data.flag != null && String(data.flag) !== "") {
+    return `${kind}:${data.flag}`;
+  }
+  const time = data.time ?? 0;
+  const type =
+    data.notice_type ?? data.request_type ?? data.meta_event_type ?? kind;
+  const scope = data.group_id ?? data.user_id ?? "";
+  const sub = data.sub_type ?? "";
+  return `${kind}:${time}_${type}_${scope}_${sub}`;
+}
+
+const NOTICE_TYPE_MAP: Record<string, NoticeType> = {
+  group_increase: "group_member_increase",
+  group_decrease: "group_member_decrease",
+  group_admin: "group_admin_change",
+  group_ban: "group_ban",
+  group_recall: "group_recall",
+  friend_recall: "friend_recall",
+  friend_add: "friend_add",
+  group_upload: "group_upload",
+  group_sign: "group_sign",
+  group_transfer: "group_transfer",
+  // icqq EventMap 命名 → Zhin NoticeType
+  "group.increase": "group_member_increase",
+  "group.decrease": "group_member_decrease",
+  "group.admin": "group_admin_change",
+  "group.ban": "group_ban",
+  "group.recall": "group_recall",
+  "friend.increase": "friend_add",
+  "friend.decrease": "friend_recall",
+  "friend.recall": "friend_recall",
+};
+
+function resolveNoticeZhinType(event: IcqqIpcRawEvent): NoticeType {
+  const raw = event.notice_type ?? "";
+  if (NOTICE_TYPE_MAP[raw]) return NOTICE_TYPE_MAP[raw];
+  if (raw === "notify") {
+    if (event.sub_type === "poke") {
+      return event.group_id != null ? "group_poke" : "friend_poke";
+    }
+    return `notify_${event.sub_type ?? "unknown"}` as NoticeType;
+  }
+  if (raw.startsWith("notice.")) {
+    const suffix = raw.slice("notice.".length).replace(/\./g, "_");
+    return (NOTICE_TYPE_MAP[suffix] ?? suffix) as NoticeType;
+  }
+  return raw as NoticeType;
+}
+
+function senderFromId(id: unknown, name?: string) {
+  if (id == null) return undefined;
+  const s = String(id);
+  return { id: s, name: name ?? s };
+}
+
+export function formatIcqqNotice(
+  event: IcqqIpcRawEvent,
+  botName: string,
+): ReturnType<typeof Notice.from<IcqqIpcRawEvent>> {
+  const $type = resolveNoticeZhinType(event);
+  const isGroup = event.group_id != null;
+  const channelId = String(
+    event.group_id ?? event.user_id ?? event.operator_id ?? "",
+  );
+  const tsSec = event.time ?? Math.floor(Date.now() / 1000);
+
+  return Notice.from(event, {
+    $id: resolveSideEventDedupeKey(event, "notice"),
+    $adapter: "icqq",
+    $bot: botName,
+    $type,
+    $subType: event.sub_type,
+    $channel: {
+      id: channelId,
+      type: isGroup ? "group" : "private",
+    },
+    $operator: senderFromId(event.operator_id),
+    $target: senderFromId(event.user_id),
+    $timestamp: tsSec * 1000,
+  });
+}
+
+function resolveRequestZhinType(event: IcqqIpcRawEvent): RequestType {
+  const rt = event.request_type ?? "";
+  if (rt === "friend" || rt.startsWith("friend")) return "friend_add";
+  if (rt === "group" || rt.startsWith("group")) {
+    return event.sub_type === "invite" ? "group_invite" : "group_add";
+  }
+  return rt as RequestType;
+}
+
+export function formatIcqqRequest(
+  event: IcqqIpcRawEvent,
+  botName: string,
+  ipc: IpcClient,
+): ReturnType<typeof Request.from<IcqqIpcRawEvent>> {
+  const $type = resolveRequestZhinType(event);
+  const isGroup = event.group_id != null;
+  const channelId = String(event.group_id ?? event.user_id ?? "");
+  const tsSec = event.time ?? Math.floor(Date.now() / 1000);
+  const flag = event.flag ?? resolveSideEventDedupeKey(event, "request");
+
+  const isFriend =
+    event.request_type === "friend" ||
+    (typeof event.request_type === "string" &&
+      event.request_type.startsWith("friend"));
+
+  return Request.from(event, {
+    $id: String(flag),
+    $adapter: "icqq",
+    $bot: botName,
+    $type,
+    $subType: event.sub_type,
+    $channel: {
+      id: channelId,
+      type: isGroup ? "group" : "private",
+    },
+    $sender: senderFromId(event.user_id) ?? { id: "", name: "" },
+    $comment: event.comment,
+    $timestamp: tsSec * 1000,
+    $approve: async (remark?: string) => {
+      const action = isFriend
+        ? Actions.HANDLE_FRIEND_REQUEST
+        : Actions.HANDLE_GROUP_REQUEST;
+      const params: Record<string, unknown> = {
+        flag: event.flag ?? flag,
+        approve: true,
+      };
+      if (remark) params.remark = remark;
+      if (!isFriend && event.sub_type) params.sub_type = event.sub_type;
+      const resp = await ipc.request(action, params);
+      if (!resp.ok) throw new Error(resp.error ?? "同意请求失败");
+    },
+    $reject: async (reason?: string) => {
+      const action = isFriend
+        ? Actions.HANDLE_FRIEND_REQUEST
+        : Actions.HANDLE_GROUP_REQUEST;
+      const params: Record<string, unknown> = {
+        flag: event.flag ?? flag,
+        approve: false,
+      };
+      if (reason) params.reason = reason;
+      if (!isFriend && event.sub_type) params.sub_type = event.sub_type;
+      const resp = await ipc.request(action, params);
+      if (!resp.ok) throw new Error(resp.error ?? "拒绝请求失败");
+    },
+  });
+}
+
+/** meta_event / system.*：返回是否建议在上线后刷新好友/群列表 */
+export function shouldRefreshListsOnMeta(event: IcqqIpcRawEvent): boolean {
+  if (event.meta_event_type === "lifecycle") {
+    const sub = event.sub_type;
+    return sub === "connect" || sub === "enable";
+  }
+  const pt = event.post_type ?? "";
+  if (pt === "system.online" || pt.endsWith(".online")) return true;
+  return false;
+}
+
+export function formatIcqqMetaLog(event: IcqqIpcRawEvent): string {
+  return formatCompact({
+    meta: event.meta_event_type ?? event.post_type ?? "meta",
+    sub_type: event.sub_type,
+    time: event.time,
+  });
+}

package/src/index.ts

@@ -32,6 +32,14 @@ declare module "zhin.js" {
 export * from "./types.js";
 export { IcqqBot } from "./bot.js";
 export { IcqqAdapter } from "./adapter.js";
+export {
+  ICQQTypingIndicatorManager,
+  createICQQTypingIndicatorManager,
+  startICQQTypingIndicator,
+  enableTypingIndicator,
+  type ICQQTypingIndicatorConfig,
+} from "./typing-indicator.js";
+export type { TypingIndicatorConfig } from "./types.js";
 
 const plugin = usePlugin();
 const { provide, useContext, addCommand, root } = plugin;

package/src/ipc-client.ts

@@ -38,6 +38,40 @@ function getRpcPortPath(uin: number): string {
   return path.join(getIcqqHome(), String(uin), "daemon.rpc");
 }
 
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object"
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function isChatMessageEvent(
+  event: IpcEvent,
+  type: "private" | "group",
+  id: number,
+): boolean {
+  if (!event.event.startsWith("message.")) return false;
+  const data = asRecord(event.data);
+  if (!data) return false;
+
+  const msgType = String(data.message_type ?? "");
+  if (msgType !== type) return false;
+
+  if (type === "private") {
+    const from = Number(data.from_id ?? data.user_id);
+    return Number.isFinite(from) && from === id;
+  }
+
+  const groupId = Number(data.group_id);
+  return Number.isFinite(groupId) && groupId === id;
+}
+
+function isGuildChannelMessageEvent(event: IpcEvent, channelId: string): boolean {
+  if (!event.event.startsWith("message.guild")) return false;
+  const data = asRecord(event.data);
+  if (!data) return false;
+  return String(data.channel_id ?? "") === channelId;
+}
+
 export class IpcClient {
   private socket: net.Socket;
   private buffer = "";
@@ -260,8 +294,15 @@ export class IpcClient {
       try {
         const msg = JSON.parse(line) as IpcMessage;
         if ("event" in msg) {
-          const handler = this.eventHandlers.get(msg.id);
-          handler?.(msg as IpcEvent);
+          const event = msg as IpcEvent;
+          if (event.id === "*") {
+            for (const handler of this.eventHandlers.values()) {
+              handler(event);
+            }
+          } else {
+            const handler = this.eventHandlers.get(event.id);
+            handler?.(event);
+          }
         } else {
           const p = this.pending.get(msg.id);
           if (p) {
@@ -275,6 +316,18 @@ export class IpcClient {
     }
   }
 
+  /**
+   * 注册 icqq 事件回调。
+   * 新版守护进程在认证后会自动广播事件（event.id = "*"）。
+   */
+  onEvent(onEvent: (event: IpcEvent) => void): () => void {
+    const id = randomUUID();
+    this.eventHandlers.set(id, onEvent);
+    return () => {
+      this.eventHandlers.delete(id);
+    };
+  }
+
   /**
    * 发送 IPC 请求并等待响应。
    */
@@ -313,31 +366,38 @@ export class IpcClient {
   }
 
   /**
-   * 订阅消息推送。
+   * @deprecated 兼容旧调用方式：服务端已自动推送事件，type/id 过滤在客户端完成。
    * @returns 订阅句柄，包含 unsubscribe() 方法
    */
   subscribe(
-    action: string,
+    _action: string,
     params: Record<string, unknown>,
     onEvent: (event: IpcEvent) => void,
   ): { id: string; unsubscribe: () => Promise<void> } {
+    let off: () => void;
+    if (params.type === "private" || params.type === "group") {
+      const chatType: "private" | "group" = params.type;
+      const sessionId = Number(params.id);
+      off = Number.isFinite(sessionId) && sessionId > 0
+        ? this.onEvent((event) => {
+          if (isChatMessageEvent(event, chatType, sessionId)) onEvent(event);
+        })
+        : this.onEvent(onEvent);
+    } else if (params.type === "guild" && params.id != null && params.id !== "") {
+      const channelId = String(params.id);
+      off = this.onEvent((event) => {
+        if (isGuildChannelMessageEvent(event, channelId)) onEvent(event);
+      });
+    } else {
+      off = this.onEvent(onEvent);
+    }
+
     const id = randomUUID();
-    this.eventHandlers.set(id, onEvent);
-    const req: IpcRequest = { id, action, params };
-    this.socket.write(JSON.stringify(req) + "\n");
 
     return {
       id,
       unsubscribe: async () => {
-        this.eventHandlers.delete(id);
-        if (!this._closed) {
-          const unsub: IpcRequest = {
-            id: randomUUID(),
-            action: "unsubscribe",
-            params,
-          };
-          this.socket.write(JSON.stringify(unsub) + "\n");
-        }
+        off();
       },
     };
   }

package/src/protocol.ts

@@ -29,16 +29,10 @@ export type IpcEvent = {
 
 export type IpcMessage = IpcResponse | IpcEvent;
 
-/** 收到的消息事件数据 */
-export interface IpcMessageEventData {
-  type: "group" | "private";
-  from_id: number;
-  user_id: number;
-  nickname: string;
-  raw_message: string;
-  time: number;
-  group_id?: number;
-}
+export type { IcqqIpcMessageEvent } from "./icqq-inbound.js";
+
+/** 从 IPC 入站 payload 解析可用于引用/撤回的消息 ID */
+export { resolveIcqqInboundMessageId } from "./icqq-inbound.js";
 
 /** Guild 消息事件数据 */
 export interface IpcGuildMessageEventData {

package/src/types.ts

@@ -17,6 +17,46 @@ export interface IcqqSenderInfo {
   title?: string;
 }
 
+/**
+ * Typing Indicator 配置
+ */
+export interface TypingIndicatorConfig {
+  /** 是否启用（默认 true） */
+  enabled?: boolean;
+  /** 默认表情（默认 '⏳'） */
+  defaultEmoji?: string;
+  /** 是否在完成后自动移除（默认 true） */
+  autoRemove?: boolean;
+  /** 自动移除延迟，毫秒（默认 5000） */
+  removeDelay?: number;
+  /** 私聊配置 */
+  privateConfig?: {
+    /** 提示类型 */
+    type: 'message' | 'reaction';
+    /** 消息内容（type='message' 时使用） */
+    message?: string;
+    /** 表情符号（type='reaction' 时使用） */
+    emoji?: string;
+    /** 是否自动移除 */
+    autoRemove?: boolean;
+    /** 自动移除延迟 */
+    removeDelay?: number;
+  };
+  /** 群聊配置 */
+  groupConfig?: {
+    /** 提示类型 */
+    type: 'message' | 'reaction';
+    /** 消息内容（type='message' 时使用） */
+    message?: string;
+    /** 表情符号（type='reaction' 时使用） */
+    emoji?: string;
+    /** 是否自动移除 */
+    autoRemove?: boolean;
+    /** 自动移除延迟 */
+    removeDelay?: number;
+  };
+}
+
 /**
  * Bot 配置：支持本地 IPC 和远程 RPC 两种连接模式。
  *
@@ -41,6 +81,11 @@ export interface IcqqBotConfig {
    * 默认 true；设为 false 则断开后仅将 `$connected` 置为 false，需手动重连。
    */
   autoReconnect?: boolean;
+  /**
+   * Typing Indicator 配置
+   * 用于在 AI 处理消息时提示用户正在处理中
+   */
+  typingIndicator?: TypingIndicatorConfig;
 }
 
 /** IPC 返回的好友信息 */