@zhin.js/adapter-icqq 2.0.6 → 2.0.7

package/src/ipc-client.ts

@@ -0,0 +1,326 @@
+/**
+ * IPC/RPC 客户端 — 与 icqq 守护进程通信 (ported from @icqqjs/cli v1.4.4)
+ *
+ * IPC 模式（本地 Unix Socket）：
+ *   const client = await IpcClient.connect(uin);
+ *
+ * RPC 模式（远程 TCP）：
+ *   const client = await IpcClient.connectRpc({ host, port, token });
+ *
+ * 通信协议：JSON + 换行符。
+ * IPC 连接使用 Token 直传认证；RPC 使用 HMAC-SHA256 挑战-响应认证。
+ */
+import net from "node:net";
+import { createHmac, randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import type {
+  IpcRequest,
+  IpcResponse,
+  IpcEvent,
+  IpcMessage,
+} from "./protocol.js";
+
+function getIcqqHome(): string {
+  return path.join(os.homedir(), ".icqq");
+}
+
+function getSocketPath(uin: number): string {
+  return path.join(getIcqqHome(), String(uin), "daemon.sock");
+}
+
+function getTokenPath(uin: number): string {
+  return path.join(getIcqqHome(), String(uin), "daemon.token");
+}
+
+function getRpcPortPath(uin: number): string {
+  return path.join(getIcqqHome(), String(uin), "daemon.rpc");
+}
+
+export class IpcClient {
+  private socket: net.Socket;
+  private buffer = "";
+  private pending = new Map<
+    string,
+    { resolve: (v: IpcResponse) => void; reject: (e: Error) => void }
+  >();
+  private eventHandlers = new Map<string, (event: IpcEvent) => void>();
+  private _closed = false;
+
+  private constructor(socket: net.Socket, skipDataHandler = false) {
+    this.socket = socket;
+    if (!skipDataHandler) {
+      this.attachDataHandler();
+    }
+    this.socket.on("error", (err) => {
+      for (const { reject } of this.pending.values()) {
+        reject(err);
+      }
+      this.pending.clear();
+    });
+    this.socket.on("close", () => {
+      this._closed = true;
+      for (const { reject } of this.pending.values()) {
+        reject(new Error("连接已关闭"));
+      }
+      this.pending.clear();
+    });
+  }
+
+  get closed(): boolean {
+    return this._closed;
+  }
+
+  /** 注册数据处理 handler（RPC 模式延迟到 challenge 完成后调用） */
+  private attachDataHandler() {
+    this.socket.on("data", (chunk) => this.onData(chunk.toString()));
+  }
+
+  /**
+   * 通过 IPC（Unix Socket）连接守护进程并完成认证。
+   * @param uin - 目标账号的 QQ 号
+   * @returns 已认证的 IpcClient 实例
+   * @throws 守护进程未运行或认证失败时抛出错误
+   */
+  static async connect(uin: number): Promise<IpcClient> {
+    let token: string;
+    try {
+      token = (await readFile(getTokenPath(uin), "utf-8")).trim();
+    } catch {
+      throw new Error(
+        `无法读取认证 token，icqq 守护进程可能未运行。请先执行: icqq login`,
+      );
+    }
+
+    const client = await new Promise<IpcClient>((resolve, reject) => {
+      const sock = net.connect(getSocketPath(uin));
+      sock.on("connect", () => resolve(new IpcClient(sock)));
+      sock.on("error", (err) =>
+        reject(
+          new Error(
+            `无法连接 icqq 守护进程 (${getSocketPath(uin)}): ${err.message}。请先执行: icqq login`,
+          ),
+        ),
+      );
+    });
+
+    const authResp = await client.request("auth", { token });
+    if (!authResp.ok) {
+      client.close();
+      throw new Error("IPC 认证失败");
+    }
+    return client;
+  }
+
+  /**
+   * 通过 RPC（TCP）连接守护进程并完成 HMAC 挑战-响应认证。
+   *
+   * 流程：
+   *   1. 服务端连接后发送 { challenge: "<hex>" }
+   *   2. 客户端用 HMAC-SHA256(token, challenge) 生成 digest
+   *   3. 客户端发送 { action: "auth", params: { digest: "<hex>" } }
+   *   4. 服务端验证 digest，通过则认证成功
+   *
+   * token 不会明文传输，防止中间人嗅探。
+   *
+   * @param options.host - 远程主机地址
+   * @param options.port - 远程端口
+   * @param options.token - 认证 token（用于 HMAC 计算，不会明文传输）
+   */
+  static async connectRpc(options: {
+    host: string;
+    port: number;
+    token: string;
+  }): Promise<IpcClient> {
+    const { host, port, token } = options;
+
+    const client = await new Promise<IpcClient>((resolve, reject) => {
+      const sock = net.connect(port, host);
+      // skipDataHandler=true: 延迟注册 onData，避免与 challenge 读取冲突
+      sock.on("connect", () => resolve(new IpcClient(sock, true)));
+      sock.on("error", (err) =>
+        reject(
+          new Error(`无法连接 icqq RPC 服务 (${host}:${port}): ${err.message}`),
+        ),
+      );
+    });
+
+    // Wait for challenge from server, with proper buffering for TCP fragmentation
+    const challenge = await new Promise<string>((resolve, reject) => {
+      let challengeBuffer = "";
+      const timeout = setTimeout(() => {
+        client.socket.removeListener("data", onData);
+        client.close();
+        reject(new Error("RPC 挑战超时"));
+      }, 10000);
+
+      const onData = (chunk: Buffer) => {
+        challengeBuffer += chunk.toString();
+        const nlIdx = challengeBuffer.indexOf("\n");
+        if (nlIdx === -1) return; // 等待更多数据
+
+        clearTimeout(timeout);
+        client.socket.removeListener("data", onData);
+
+        try {
+          const msg = JSON.parse(challengeBuffer.slice(0, nlIdx)) as {
+            challenge?: string;
+          };
+          if (!msg.challenge) {
+            reject(new Error("RPC 服务端未发送挑战"));
+            return;
+          }
+          resolve(msg.challenge);
+        } catch {
+          reject(new Error("RPC 挑战解析失败"));
+        }
+      };
+      client.socket.on("data", onData);
+    });
+
+    // Challenge 阶段结束，注册正式的数据处理 handler
+    client.attachDataHandler();
+
+    // Compute HMAC digest and authenticate
+    const digest = createHmac("sha256", token)
+      .update(challenge)
+      .digest("hex");
+    const authResp = await client.request("auth", { digest });
+    if (!authResp.ok) {
+      client.close();
+      throw new Error(authResp.error ?? "RPC 认证失败");
+    }
+    return client;
+  }
+
+  /**
+   * 通过 RPC 连接守护进程（自动从 daemon.rpc 文件读取地址）。
+   * @param uin - 目标账号的 QQ 号
+   */
+  static async connectRpcByUin(uin: number): Promise<IpcClient> {
+    let token: string;
+    try {
+      token = (await readFile(getTokenPath(uin), "utf-8")).trim();
+    } catch {
+      throw new Error("无法读取认证 token，守护进程可能未运行");
+    }
+
+    let rpcInfo: { host: string; port: number };
+    try {
+      const raw = await readFile(getRpcPortPath(uin), "utf-8");
+      rpcInfo = JSON.parse(raw);
+    } catch {
+      throw new Error("RPC 未启用或守护进程未运行");
+    }
+
+    return IpcClient.connectRpc({
+      host: rpcInfo.host,
+      port: rpcInfo.port,
+      token,
+    });
+  }
+
+  private onData(data: string) {
+    this.buffer += data;
+    const lines = this.buffer.split("\n");
+    this.buffer = lines.pop()!;
+
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      try {
+        const msg = JSON.parse(line) as IpcMessage;
+        if ("event" in msg) {
+          const handler = this.eventHandlers.get(msg.id);
+          handler?.(msg as IpcEvent);
+        } else {
+          const p = this.pending.get(msg.id);
+          if (p) {
+            this.pending.delete(msg.id);
+            p.resolve(msg as IpcResponse);
+          }
+        }
+      } catch {
+        // ignore malformed JSON
+      }
+    }
+  }
+
+  /**
+   * 发送 IPC 请求并等待响应。
+   */
+  async request(
+    action: string,
+    params: Record<string, unknown> = {},
+    timeoutMs = 30000,
+  ): Promise<IpcResponse> {
+    if (this._closed) throw new Error("IPC 连接已关闭");
+    const id = randomUUID();
+    const req: IpcRequest = { id, action, params };
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`IPC 请求超时 (${timeoutMs}ms): ${action}`));
+      }, timeoutMs);
+
+      this.pending.set(id, {
+        resolve: (v) => {
+          clearTimeout(timer);
+          resolve(v);
+        },
+        reject: (e) => {
+          clearTimeout(timer);
+          reject(e);
+        },
+      });
+      this.socket.write(JSON.stringify(req) + "\n", (err) => {
+        if (err) {
+          clearTimeout(timer);
+          this.pending.delete(id);
+          reject(err);
+        }
+      });
+    });
+  }
+
+  /**
+   * 订阅消息推送。
+   * @returns 订阅句柄，包含 unsubscribe() 方法
+   */
+  subscribe(
+    action: string,
+    params: Record<string, unknown>,
+    onEvent: (event: IpcEvent) => void,
+  ): { id: string; unsubscribe: () => Promise<void> } {
+    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");
+        }
+      },
+    };
+  }
+
+  /** 关闭连接 */
+  close() {
+    this._closed = true;
+    this.eventHandlers.clear();
+    for (const { reject } of this.pending.values()) {
+      reject(new Error("连接已关闭"));
+    }
+    this.pending.clear();
+    this.socket.destroy();
+  }
+}

package/src/protocol.ts

@@ -0,0 +1,242 @@
+/**
+ * IPC 协议类型定义与 Action 常量 (ported from @icqqjs/cli)
+ *
+ * CLI 与守护进程通过 Unix Domain Socket 通信，
+ * 使用 JSON + 换行符（\n）分隔的文本协议。
+ */
+
+/** CLI → Daemon 请求 */
+export type IpcRequest = {
+  id: string;
+  action: string;
+  params: Record<string, unknown>;
+};
+
+/** Daemon → CLI 响应 */
+export type IpcResponse = {
+  id: string;
+  ok: boolean;
+  data?: unknown;
+  error?: string;
+};
+
+/** Daemon → CLI 事件推送 */
+export type IpcEvent = {
+  id: string;
+  event: string;
+  data: unknown;
+};
+
+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;
+}
+
+/** Guild 消息事件数据 */
+export interface IpcGuildMessageEventData {
+  type: "guild";
+  guild_id: string;
+  guild_name: string;
+  channel_id: string;
+  channel_name: string;
+  nickname: string;
+  tiny_id: string;
+  raw_message: string;
+  time: number;
+  seq: number;
+}
+
+/**
+ * 所有 IPC 操作常量 (from @icqqjs/cli)
+ */
+export const Actions = {
+  PING: "ping",
+
+  // ── 列表查询 ──
+  LIST_FRIENDS: "list_friends",
+  LIST_GROUPS: "list_groups",
+  LIST_GROUP_MEMBERS: "list_group_members",
+  LIST_BLACKLIST: "list_blacklist",
+  LIST_FRIEND_CLASSES: "list_friend_classes",
+
+  // ── 信息查询 ──
+  GET_FRIEND_INFO: "get_friend_info",
+  GET_GROUP_INFO: "get_group_info",
+  GET_GROUP_MEMBER_INFO: "get_group_member_info",
+  GET_STRANGER_INFO: "get_stranger_info",
+  GET_STATUS: "get_status",
+  GET_SELF_PROFILE: "get_self_profile",
+
+  // ── 消息发送 ──
+  SEND_PRIVATE_MSG: "send_private_msg",
+  SEND_GROUP_MSG: "send_group_msg",
+
+  // ── 消息操作 ──
+  RECALL_MSG: "recall_msg",
+  GET_MSG: "get_msg",
+  HISTORY_PRIVATE: "history_private",
+  HISTORY_GROUP: "history_group",
+  MARK_READ: "mark_read",
+  DELETE_MSG: "delete_msg",
+
+  // ── 个人设置 ──
+  SET_NICKNAME: "set_nickname",
+  SET_GENDER: "set_gender",
+  SET_BIRTHDAY: "set_birthday",
+  SET_SIGNATURE: "set_signature",
+  SET_DESCRIPTION: "set_description",
+  SET_AVATAR: "set_avatar",
+  SET_ONLINE_STATUS: "set_online_status",
+
+  // ── 群设置 ──
+  SET_GROUP_NAME: "set_group_name",
+  SET_GROUP_AVATAR: "set_group_avatar",
+  SET_GROUP_CARD: "set_group_card",
+  SET_GROUP_TITLE: "set_group_title",
+  SET_GROUP_ADMIN: "set_group_admin",
+  SET_GROUP_REMARK: "set_group_remark",
+
+  // ── 群管理 ──
+  GROUP_MUTE: "group_mute",
+  GROUP_MUTE_ALL: "group_mute_all",
+  GROUP_KICK: "group_kick",
+  GROUP_QUIT: "group_quit",
+  GROUP_INVITE: "group_invite",
+  GROUP_POKE: "group_poke",
+  GROUP_ANNOUNCE: "group_announce",
+  GROUP_SIGN: "group_sign",
+  GROUP_ESSENCE_ADD: "group_essence_add",
+  GROUP_ESSENCE_REMOVE: "group_essence_remove",
+  GROUP_ALLOW_ANONY: "group_allow_anony",
+  GROUP_MUTED_LIST: "group_muted_list",
+  GROUP_AT_ALL_REMAIN: "group_at_all_remain",
+
+  // ── 好友操作 ──
+  FRIEND_POKE: "friend_poke",
+  FRIEND_LIKE: "friend_like",
+  FRIEND_DELETE: "friend_delete",
+  FRIEND_REMARK: "friend_remark",
+  FRIEND_CLASS: "friend_class",
+
+  // ── 系统消息/请求 ──
+  GET_SYSTEM_MSG: "get_system_msg",
+  HANDLE_FRIEND_REQUEST: "handle_friend_request",
+  HANDLE_GROUP_REQUEST: "handle_group_request",
+
+  // ── 好友分组 ──
+  ADD_FRIEND_CLASS: "add_friend_class",
+  DELETE_FRIEND_CLASS: "delete_friend_class",
+  RENAME_FRIEND_CLASS: "rename_friend_class",
+
+  // ── 群文件系统 ──
+  GFS_LIST: "gfs_list",
+  GFS_INFO: "gfs_info",
+  GFS_MKDIR: "gfs_mkdir",
+  GFS_DELETE: "gfs_delete",
+  GFS_RENAME: "gfs_rename",
+  GFS_STAT: "gfs_stat",
+  GFS_MOVE: "gfs_move",
+  GFS_DOWNLOAD: "gfs_download",
+
+  // ── 其他功能 ──
+  IMAGE_OCR: "image_ocr",
+  RELOAD_FRIEND_LIST: "reload_friend_list",
+  RELOAD_GROUP_LIST: "reload_group_list",
+  CLEAN_CACHE: "clean_cache",
+  GET_GROUP_SHARE: "get_group_share",
+
+  // ── 群管理扩展 ──
+  GROUP_SET_JOIN_TYPE: "group_set_join_type",
+  GROUP_SET_RATE_LIMIT: "group_set_rate_limit",
+  GROUP_MUTE_ANONY: "group_mute_anony",
+  GROUP_ANON_INFO: "group_anon_info",
+
+  // ── 好友操作扩展 ──
+  ADD_FRIEND: "add_friend",
+  SEND_TEMP_MSG: "send_temp_msg",
+
+  // ── 漫游表情 ──
+  GET_ROAMING_STAMP: "get_roaming_stamp",
+  DELETE_STAMP: "delete_stamp",
+
+  // ── 文件传输 ──
+  SEND_PRIVATE_FILE: "send_private_file",
+  SEND_GROUP_FILE: "send_group_file",
+  FRIEND_RECALL_FILE: "friend_recall_file",
+  GFS_UPLOAD: "gfs_upload",
+
+  // ── 群消息表态 ──
+  GROUP_SET_REACTION: "group_set_reaction",
+  GROUP_DEL_REACTION: "group_del_reaction",
+
+  // ── 转发消息 ──
+  GET_FORWARD_MSG: "get_forward_msg",
+  MAKE_FORWARD_MSG: "make_forward_msg",
+
+  // ── 频道系统 ──
+  GUILD_LIST: "guild_list",
+  GUILD_INFO: "guild_info",
+  GUILD_CHANNELS: "guild_channels",
+  GUILD_MEMBERS: "guild_members",
+  GUILD_SEND_MSG: "guild_send_msg",
+  GUILD_RECALL_MSG: "guild_recall_msg",
+
+  // ── 用户文件操作 ──
+  GET_FILE_INFO: "get_file_info",
+  GET_FILE_URL: "get_file_url",
+  GET_AVATAR_URL: "get_avatar_url",
+  GET_GROUP_AVATAR_URL: "get_group_avatar_url",
+
+  // ── 屏蔽群成员消息 ──
+  SET_SCREEN_MEMBER_MSG: "set_screen_member_msg",
+
+  // ── 群文件转发 ──
+  GFS_FORWARD: "gfs_forward",
+  GFS_FORWARD_OFFLINE: "gfs_forward_offline",
+
+  // ── 重载列表 ──
+  RELOAD_BLACKLIST: "reload_blacklist",
+  RELOAD_STRANGER_LIST: "reload_stranger_list",
+  RELOAD_GUILDS: "reload_guilds",
+
+  // ── 在线状态查询 ──
+  GET_STATUS_INFO: "get_status_info",
+
+  // ── 密钥/工具 ──
+  GET_CLIENT_KEY: "get_client_key",
+  GET_PSKEY: "get_pskey",
+  UID2UIN: "uid2uin",
+  UIN2UID: "uin2uid",
+
+  // ── 视频/加好友设置 ──
+  GET_VIDEO_URL: "get_video_url",
+  GET_ADD_FRIEND_SETTING: "get_add_friend_setting",
+
+  // ── 频道扩展 ──
+  GET_FORUM_URL: "get_forum_url",
+  GUILD_CHANNEL_SHARE: "guild_channel_share",
+
+  // ── 获取图片/语音 URL ──
+  GET_PIC_URL: "get_pic_url",
+  GET_PTT_URL: "get_ptt_url",
+
+  // ── 消息订阅 ──
+  SUBSCRIBE: "subscribe",
+  UNSUBSCRIBE: "unsubscribe",
+
+  // ── Webhook ──
+  SET_WEBHOOK: "set_webhook",
+  GET_WEBHOOK: "get_webhook",
+
+  // ── 系统通知 ──
+  SET_NOTIFY: "set_notify",
+  GET_NOTIFY: "get_notify",
+} as const;

package/src/routes.ts

@@ -0,0 +1,83 @@
+/**
+ * ICQQ HTTP 路由注册 — 通过 IPC 查询守护进程数据
+ */
+import type { Router } from "@zhin.js/http";
+import type { Plugin } from "zhin.js";
+import type { IcqqAdapter } from "./adapter.js";
+import { Actions } from "./protocol.js";
+
+export function registerRoutes(
+  router: Router,
+  icqq: IcqqAdapter,
+  _root: Plugin,
+) {
+  router.get("/api/icqq/bots", async (ctx) => {
+    try {
+      const bots = Array.from(icqq.bots.values());
+      if (bots.length === 0) {
+        ctx.body = { success: true, data: [], message: "暂无ICQQ机器人实例" };
+        return;
+      }
+      const result = await Promise.all(
+        bots.map(async (bot) => {
+          try {
+            const base: Record<string, unknown> = {
+              name: bot.$config.name,
+              connected: bot.$connected || false,
+              groupCount: bot.groups.size,
+              friendCount: bot.friends.size,
+              status: bot.$connected ? "online" : "offline",
+              lastActivity: new Date().toISOString(),
+            };
+
+            // 尝试从守护进程获取详细状态
+            if (bot.$connected && bot.ipc && !bot.ipc.closed) {
+              try {
+                const statusResp = await bot.ipc.request(
+                  Actions.GET_STATUS,
+                  {},
+                  5000,
+                );
+                if (statusResp.ok && statusResp.data) {
+                  const stat = statusResp.data as Record<string, unknown>;
+                  base.receiveCount = stat.recv_msg_cnt ?? 0;
+                  base.sendCount = stat.sent_msg_cnt ?? 0;
+                }
+              } catch {
+                // status 查询超时，忽略
+              }
+            }
+
+            return base;
+          } catch {
+            return {
+              name: bot.$config.name,
+              connected: false,
+              groupCount: 0,
+              friendCount: 0,
+              status: "error",
+              error: "数据获取失败",
+            };
+          }
+        }),
+      );
+      ctx.body = {
+        success: true,
+        data: result,
+        timestamp: new Date().toISOString(),
+      };
+    } catch (error) {
+      ctx.status = 500;
+      ctx.body = {
+        success: false,
+        error: "ICQQ_API_ERROR",
+        message: "获取机器人数据失败",
+        details:
+          process.env.NODE_ENV === "development"
+            ? (error as Error).message
+            : undefined,
+        timestamp: new Date().toISOString(),
+      };
+    }
+  });
+}