@zhin.js/adapter-icqq 6.0.0 → 6.0.1

package/src/endpoint.ts

@@ -4,7 +4,7 @@
  * 不再直接依赖 @icqqjs/icqq 协议库。
  * 登录由 `icqq login` 完成，本 Endpoint 只负责连接守护进程并收发消息。
  */
-import { formatCompact, Endpoint, Message, segment, SendContent, SendOptions, type QuotedMessagePayload,} from 'zhin.js';
+import { formatCompact, Endpoint, Message, segment, SendContent, SendOptions, expandInteractiveSegmentsInContent, type QuotedMessagePayload,} from 'zhin.js';
 import type {
   IcqqEndpointConfig,
   IcqqSenderInfo,
@@ -56,9 +56,12 @@ import {
 import { parseIcqqGetMsgResponse } from "./get-msg.js";
 import { enrichQuotedPayloadWithForward, isForwardPlaceholderPayload } from "./forward-msg.js";
 import {
-  enableTypingIndicator,
-  type ICQQTypingIndicatorManager,
-} from "./typing-indicator.js";
+  IcqqGuildCatalog,
+  isIcqqGuildIpcEvent,
+  normalizeIcqqGuildInboundMessage,
+  type NormalizedIcqqGuildInbound,
+} from "./icqq-guild.js";
+import type { IpcGuildMessageEventData } from "./protocol.js";
 
 export class IcqqEndpoint implements Endpoint<IcqqEndpointConfig, IcqqIpcMessageEvent> {
   $connected = false;
@@ -69,6 +72,8 @@ export class IcqqEndpoint implements Endpoint<IcqqEndpointConfig, IcqqIpcMessage
   friends = new Map<number, IpcFriendInfo>();
   /** 缓存的群列表 */
   groups = new Map<number, IpcGroupInfo>();
+  /** QQ 频道（guild）子频道缓存 */
+  readonly guildCatalog = new IcqqGuildCatalog();
 
   private subscriptions: Array<{ unsubscribe: () => Promise<void> }> = [];
   /** 事件去重：覆盖多端回流/服务端重复推送等场景 */
@@ -80,9 +85,6 @@ export class IcqqEndpoint implements Endpoint<IcqqEndpointConfig, IcqqIpcMessage
   /** 是否已有重连循环在跑（避免多次 schedule 叠套） */
   private reconnectRunning = false;
 
-  /** Typing Indicator 管理器 */
-  $typingIndicator?: ICQQTypingIndicatorManager;
-
   get $id() {
     return this.$config.name;
   }
@@ -113,50 +115,13 @@ export class IcqqEndpoint implements Endpoint<IcqqEndpointConfig, IcqqIpcMessage
 
     await this.rebindIpcSession();
 
-    // 根据配置自动启用 Typing Indicator
-    this.initTypingIndicator();
-
     this.logger.info(formatCompact( {
       机器人: this.$id,
       好友数: this.friends.size,
       群组数: this.groups.size,
-      思考提示: this.$typingIndicator ? '已启用' : '未启用',
     }));
   }
 
-  /**
-   * 初始化 Typing Indicator
-   * 根据配置自动启用或禁用
-   */
-  private initTypingIndicator(): void {
-    const typingConfig = this.$config.typingIndicator;
-
-    // 如果配置中明确设置为 false，则不启用
-    if (typingConfig?.enabled === false) {
-      this.logger.debug(formatCompact({
-        endpoint: this.$id,
-        typingIndicator: 'disabled_by_config',
-      }));
-      return;
-    }
-
-    // 启用 Typing Indicator
-    try {
-      this.$typingIndicator = enableTypingIndicator(this, typingConfig);
-      this.logger.debug(formatCompact({
-        endpoint: this.$id,
-        typingIndicator: 'enabled',
-        emoji: typingConfig?.defaultEmoji || '⏳',
-      }));
-    } catch (error) {
-      this.logger.warn(formatCompact({
-        endpoint: this.$id,
-        typingIndicator: 'failed',
-        error: error instanceof Error ? error.message : String(error),
-      }));
-    }
-  }
-
   /** 建立或恢复与守护进程的 IPC/RPC 会话（订阅、缓存列表） */
   private async rebindIpcSession(): Promise<void> {
     const uin = Number(this.$config.name);
@@ -268,6 +233,27 @@ export class IcqqEndpoint implements Endpoint<IcqqEndpointConfig, IcqqIpcMessage
         this.groups.set(g.group_id, g);
       }
     }
+
+    await this.guildCatalog.syncAll(this.ipc).catch((e: unknown) => {
+      this.logger.warn(formatCompact({
+        op: "sync_guilds",
+        endpoint: this.$id,
+        ok: false,
+        error: e instanceof Error ? e.message : String(e),
+      }));
+    });
+  }
+
+  /** Console：列出 guild 子频道（含 parent.guild） */
+  getGuildChannelList(): ReturnType<IcqqGuildCatalog["getGuildChannelList"]> {
+    return this.guildCatalog.getGuildChannelList();
+  }
+
+  resolveConsoleChannelNames(
+    channelId: string,
+    guildId?: string,
+  ): { channelName?: string; parentName?: string } {
+    return this.guildCatalog.resolveConsoleChannelNames(channelId, guildId);
   }
 
   // ── 断开 ───────────────────────────────────────────────────────────
@@ -275,12 +261,6 @@ export class IcqqEndpoint implements Endpoint<IcqqEndpointConfig, IcqqIpcMessage
   async $disconnect(): Promise<void> {
     this.intentionalDisconnect = true;
 
-    // 停止所有 Typing Indicator
-    if (this.$typingIndicator) {
-      await this.$typingIndicator.stopAll().catch(() => {});
-      this.$typingIndicator = undefined;
-    }
-
     this.ipc?.setOnRemoteDisconnect(null);
     for (const sub of this.subscriptions) {
       await sub.unsubscribe().catch(() => {});
@@ -301,6 +281,23 @@ export class IcqqEndpoint implements Endpoint<IcqqEndpointConfig, IcqqIpcMessage
       return;
     }
 
+    if (event.event === Actions.RELOAD_GUILDS) {
+      void this.guildCatalog.syncAll(this.ipc).catch((e: unknown) => {
+        this.logger.warn(formatCompact({
+          op: "reload_guilds",
+          endpoint: this.$id,
+          ok: false,
+          error: e instanceof Error ? e.message : String(e),
+        }));
+      });
+      return;
+    }
+
+    if (isIcqqGuildIpcEvent(event.event)) {
+      this.handleGuildMessageEvent(event);
+      return;
+    }
+
     const payload = unwrapIcqqIpcEventPayload(event);
     if (!payload || typeof payload !== "object") {
       if (process.env.ICQQ_IPC_LOG_RAW === "1") {
@@ -393,6 +390,80 @@ export class IcqqEndpoint implements Endpoint<IcqqEndpointConfig, IcqqIpcMessage
     );
   }
 
+  private handleGuildMessageEvent(event: IpcEvent): void {
+    const payload = event.data;
+    if (!payload || typeof payload !== "object") return;
+    const data = payload as IpcGuildMessageEventData & Record<string, unknown>;
+    const normalized = normalizeIcqqGuildInboundMessage(data);
+    if (!normalized) return;
+
+    this.guildCatalog.upsertFromInbound(data);
+
+    if (!this.inboundDeduper.shouldProcess(`guild:${normalized.messageId}`)) {
+      return;
+    }
+
+    void this.dispatchGuildInboundMessage(normalized);
+  }
+
+  private async dispatchGuildInboundMessage(
+    normalized: NormalizedIcqqGuildInbound,
+  ): Promise<void> {
+    const message = this.$formatGuildMessage(normalized);
+    this.adapter.emit("message.receive", message);
+    this.logger.debug(
+      `${this.$id} recv channel(${message.$channel.id}):${segment.raw(message.$content)}`,
+    );
+  }
+
+  private $formatGuildMessage(
+    normalized: NormalizedIcqqGuildInbound,
+  ): ReturnType<typeof Message.from<IpcGuildMessageEventData>> {
+    const senderInfo: IcqqSenderInfo = {
+      id: normalized.userId,
+      name: normalized.nickname,
+    };
+
+    const result = Message.from(normalized.raw, {
+      $id: normalized.messageId,
+      $adapter: "icqq" as const,
+      $endpoint: this.$config.name,
+      $sender: senderInfo,
+      $channel: {
+        id: normalized.channelId,
+        type: "channel",
+        parent: { type: "guild", id: normalized.guildId },
+      },
+      $content: normalized.content,
+      $raw: normalized.rawMessage,
+      $timestamp: normalized.timestampMs,
+      $recall: async () => {
+        await this.$recallMessage(result.$id);
+      },
+      $reply: async (
+        content: SendContent,
+        quote?: boolean | string,
+      ): Promise<string> => {
+        if (!Array.isArray(content)) content = [content];
+        if (quote) {
+          content.unshift({
+            type: "reply",
+            data: { id: typeof quote === "boolean" ? result.$id : quote },
+          });
+        }
+        return await this.adapter.sendMessage({
+          context: "icqq",
+          endpoint: this.$config.name,
+          id: normalized.channelId,
+          type: "channel",
+          parent: { type: "guild", id: normalized.guildId },
+          content,
+        });
+      },
+    });
+    return result;
+  }
+
   private handleNoticeEvent(event: IcqqIpcRawEvent): void {
     const dedupeKey = resolveSideEventDedupeKey(event, "notice");
     if (!this.inboundDeduper.shouldProcess(dedupeKey)) {
@@ -657,7 +728,8 @@ export class IcqqEndpoint implements Endpoint<IcqqEndpointConfig, IcqqIpcMessage
 
   async $sendMessage(options: SendOptions): Promise<string> {
     const outboundMedia = resolveIcqqOutboundMediaMode(this.$config);
-    const qrcodeContent = options.content;
+    const expanded = expandInteractiveSegmentsInContent(options.content);
+    const qrcodeContent = expanded;
     const content = materializeOutboundBase64(qrcodeContent, outboundMedia);
     const message = buildIcqqIpcMessageImpl(content);
 
@@ -685,6 +757,22 @@ export class IcqqEndpoint implements Endpoint<IcqqEndpointConfig, IcqqIpcMessage
         action = Actions.SEND_GROUP_MSG;
         params = { group_id: Number(options.id), message };
         break;
+      case "channel": {
+        const guildId =
+          options.parent?.type === "guild" ? options.parent.id : undefined;
+        if (!guildId) {
+          throw new Error(
+            'channel 发送需要 parent: { type: "guild", id: guild_id }',
+          );
+        }
+        action = Actions.GUILD_SEND_MSG;
+        params = {
+          guild_id: guildId,
+          channel_id: options.id,
+          message,
+        };
+        break;
+      }
       default:
         throw new Error(`不支持的频道类型: ${options.type}`);
     }

package/src/icqq-guild.ts

@@ -0,0 +1,157 @@
+/**
+ * ICQQ guild (QQ 频道) catalog sync, inbound normalize, Console channel list.
+ */
+import type { MessageSegment } from "zhin.js";
+import { Actions, type IpcGuildMessageEventData } from "./protocol.js";
+import type { IpcClient } from "./ipc-client.js";
+import { parseCqMessage } from "./cq-message.js";
+import { toCanonicalSegments } from "./segment-mapper.js";
+
+export interface IcqqGuildChannelEntry {
+  channel_id: string;
+  channel_name: string;
+  guild_id: string;
+  guild_name: string;
+}
+
+export interface NormalizedIcqqGuildInbound {
+  messageId: string;
+  channelId: string;
+  guildId: string;
+  guildName: string;
+  channelName: string;
+  userId: string;
+  nickname: string;
+  content: MessageSegment[];
+  rawMessage: string;
+  timestampMs: number;
+  raw: IpcGuildMessageEventData;
+}
+
+export class IcqqGuildCatalog {
+  private readonly channels = new Map<string, IcqqGuildChannelEntry>();
+  private readonly guilds = new Map<string, { guild_id: string; guild_name: string }>();
+
+  clear(): void {
+    this.channels.clear();
+    this.guilds.clear();
+  }
+
+  async syncAll(ipc: IpcClient): Promise<void> {
+    const listResp = await ipc.request(Actions.GUILD_LIST);
+    if (!listResp.ok) return;
+
+    const guildRows = Array.isArray(listResp.data) ? listResp.data : [];
+    for (const row of guildRows) {
+      const rec = row as Record<string, unknown>;
+      const guild_id = String(rec.guild_id ?? rec.id ?? "");
+      if (!guild_id) continue;
+      const guild_name = String(rec.guild_name ?? rec.name ?? guild_id);
+      this.guilds.set(guild_id, { guild_id, guild_name });
+
+      const chResp = await ipc.request(Actions.GUILD_CHANNELS, { guild_id });
+      if (!chResp.ok || !Array.isArray(chResp.data)) continue;
+      for (const ch of chResp.data) {
+        const chRec = ch as Record<string, unknown>;
+        const channel_id = String(chRec.channel_id ?? chRec.id ?? "");
+        if (!channel_id) continue;
+        const channel_name = String(chRec.channel_name ?? chRec.name ?? channel_id);
+        this.channels.set(channel_id, {
+          channel_id,
+          channel_name,
+          guild_id,
+          guild_name,
+        });
+      }
+    }
+  }
+
+  upsertFromInbound(data: IpcGuildMessageEventData): void {
+    const guild_id = String(data.guild_id ?? "");
+    const channel_id = String(data.channel_id ?? "");
+    if (!guild_id || !channel_id) return;
+    const guild_name = String(data.guild_name ?? guild_id);
+    const channel_name = String(data.channel_name ?? channel_id);
+    this.guilds.set(guild_id, { guild_id, guild_name });
+    this.channels.set(channel_id, {
+      channel_id,
+      channel_name,
+      guild_id,
+      guild_name,
+    });
+  }
+
+  getGuildChannelList(): Array<{
+    id: string;
+    name: string;
+    parent: { type: "guild"; id: string; name: string };
+  }> {
+    return Array.from(this.channels.values()).map((entry) => ({
+      id: entry.channel_id,
+      name: entry.channel_name,
+      parent: {
+        type: "guild" as const,
+        id: entry.guild_id,
+        name: entry.guild_name,
+      },
+    }));
+  }
+
+  resolveConsoleChannelNames(
+    channelId: string,
+    guildId?: string,
+  ): { channelName?: string; parentName?: string } {
+    const entry = this.channels.get(channelId);
+    if (entry) {
+      return { channelName: entry.channel_name, parentName: entry.guild_name };
+    }
+    if (guildId) {
+      const guild = this.guilds.get(guildId);
+      return guild ? { parentName: guild.guild_name } : {};
+    }
+    return {};
+  }
+}
+
+export function isIcqqGuildIpcEvent(eventName: string | undefined): boolean {
+  return typeof eventName === "string" && eventName.startsWith("message.guild");
+}
+
+export function normalizeIcqqGuildInboundMessage(
+  data: IpcGuildMessageEventData & Record<string, unknown>,
+): NormalizedIcqqGuildInbound | null {
+  if (data.type !== "guild") return null;
+  const guildId = String(data.guild_id ?? "");
+  const channelId = String(data.channel_id ?? "");
+  if (!guildId || !channelId) return null;
+
+  const userId = String(data.tiny_id ?? data.user_id ?? "");
+  const nickname = String(data.nickname ?? userId);
+  const rawMessage = String(data.raw_message ?? "");
+  const timestampMs =
+    typeof data.time === "number" ? data.time * 1000 : Date.now();
+  const messageId =
+    data.message_id != null && String(data.message_id) !== ""
+      ? String(data.message_id)
+      : data.seq != null
+        ? String(data.seq)
+        : `${data.time ?? 0}_${userId}_${channelId}`;
+
+  const parsed = parseCqMessage(rawMessage);
+  const canonical = toCanonicalSegments(parsed);
+  const content: MessageSegment[] = canonical.length > 0 ? canonical : [{ type: "text", data: { text: rawMessage } }];
+
+  return {
+    messageId,
+    channelId,
+    guildId,
+    guildName: String(data.guild_name ?? guildId),
+    channelName: String(data.channel_name ?? channelId),
+    userId,
+    nickname,
+    content,
+    rawMessage,
+    timestampMs,
+    raw: data,
+  };
+}

package/src/icqq-inbound.ts

@@ -3,6 +3,7 @@
  */
 import { Message, type MessageSegment, type QuotedMessagePayload } from "zhin.js";
 import { parseCqMessage } from "./cq-message.js";
+import { toCanonicalSegments } from "./segment-mapper.js";
 import { extractForwardResidFromJsonElement } from "./forward-msg.js";
 import type { GroupRole } from "./types.js";
 
@@ -292,12 +293,22 @@ export function icqqElementsToSegments(
           out.push({ type: "text", data: { text: String(el.text) } });
         }
         break;
-      case "at":
+      case "at": {
+        const atId = String(el.qq ?? el.user_id ?? "");
+        const name =
+          typeof el.name === "string"
+            ? el.name
+            : typeof el.nickname === "string"
+              ? el.nickname
+              : undefined;
         out.push({
           type: "at",
-          data: { qq: String(el.qq ?? el.user_id ?? "") },
+          data: name
+            ? { qq: atId, user_id: atId, id: atId, name }
+            : { qq: atId, user_id: atId, id: atId },
         });
         break;
+      }
       case "face":
         out.push({ type: "face", data: { id: Number(el.id) } });
         break;
@@ -584,7 +595,7 @@ function mergeReplyFromRawMessage(
   const quoteFromRaw = Message.quoteIdFromContent(fromRaw);
   if (!quoteFromRaw) return content;
   return [
-    { type: "reply", data: { id: quoteFromRaw, message_id: quoteFromRaw } },
+    { type: "reply", data: { message_id: quoteFromRaw } },
     ...content.filter((s) => s.type !== "reply"),
   ];
 }
@@ -599,7 +610,7 @@ function mergeReplyFromSource(
     resolveQuoteIdFromIcqqSource(findIcqqNestedMessageSource(data));
   if (!quoteId) return content;
   return [
-    { type: "reply", data: { id: quoteId, message_id: quoteId } },
+    { type: "reply", data: { message_id: quoteId } },
     ...content.filter((s) => s.type !== "reply"),
   ];
 }
@@ -617,7 +628,7 @@ export function resolveInboundContent(
   } else {
     content = [{ type: "text", data: { text: "" } }];
   }
-  return mergeReplyFromSource(content, data);
+  return toCanonicalSegments(mergeReplyFromSource(content, data));
 }
 
 export function normalizeIcqqInboundMessage(

package/src/index.ts

@@ -31,14 +31,6 @@ declare module "zhin.js" {
 export * from "./types.js";
 export { IcqqEndpoint } from "./endpoint.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/segment-mapper.ts

@@ -0,0 +1 @@
+export { toCanonicalSegments, fromCanonicalSegments } from 'zhin.js';

package/src/tools/index.ts

@@ -1,11 +1,11 @@
 /**
  * ICQQ 平台特有工具注册 — 通过 IPC 调用守护进程 Actions
  *
- * 通用群管理工具由 createGroupManagementTools() 自动生成;
+ * 通用群管理工具由 createSceneManagementTools() 自动生成;
  * 本模块注册 ICQQ 独有的扩展工具。
  */
 import type { ToolFeature } from "zhin.js";
-import { createGroupManagementTools } from "zhin.js";
+import { createSceneManagementTools } from "zhin.js";
 import type { IcqqAdapter } from "../adapter.js";
 import { Actions } from "../protocol.js";
 
@@ -17,8 +17,8 @@ export function registerTools(
   const disposers: (() => void)[] = [];
 
   // ── 通用群管工具 ───────────────────────────────────────────────────
-  const groupTools = createGroupManagementTools(icqq, "icqq");
-  disposers.push(...groupTools.map((t) => toolService.addTool(t, pluginName)));
+  const sceneTools = createSceneManagementTools(icqq, "icqq");
+  disposers.push(...sceneTools.map((t) => toolService.addTool(t, pluginName)));
 
   // ── 设置头衔 ───────────────────────────────────────────────────────
   disposers.push(
@@ -39,7 +39,7 @@ export function registerTools(
         },
         platforms: ["icqq"],
         tags: ["icqq"],
-        permissions: ["platform(icqq,group_owner)"],
+        permissions: ["platform(icqq,scene_owner)"],
         execute: async (args: Record<string, any>) => {
           const endpoint = icqq.endpoints.get(args.endpoint_id);
           if (!endpoint) throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
@@ -73,7 +73,7 @@ export function registerTools(
         },
         platforms: ["icqq"],
         tags: ["icqq"],
-        permissions: ["platform(icqq,group_admin)"],
+        permissions: ["platform(icqq,scene_admin)"],
         execute: async (args: Record<string, any>) => {
           const endpoint = icqq.endpoints.get(args.endpoint_id);
           if (!endpoint) throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
@@ -135,7 +135,7 @@ export function registerTools(
         },
         platforms: ["icqq"],
         tags: ["icqq"],
-        permissions: ["platform(icqq,group_admin)"],
+        permissions: ["platform(icqq,scene_admin)"],
         execute: async (args: Record<string, any>) => {
           const endpoint = icqq.endpoints.get(args.endpoint_id);
           if (!endpoint) throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
@@ -199,7 +199,7 @@ export function registerTools(
         },
         platforms: ["icqq"],
         tags: ["icqq"],
-        permissions: ["platform(icqq,group_owner)"],
+        permissions: ["platform(icqq,scene_owner)"],
         execute: async (args: Record<string, any>) => {
           const endpoint = icqq.endpoints.get(args.endpoint_id);
           if (!endpoint) throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
@@ -393,7 +393,7 @@ export function registerTools(
         },
         platforms: ["icqq"],
         tags: ["icqq"],
-        permissions: ["platform(icqq,group_admin)"],
+        permissions: ["platform(icqq,scene_admin)"],
         execute: async (args: Record<string, any>) => {
           const endpoint = icqq.endpoints.get(args.endpoint_id);
           if (!endpoint) throw new Error(`Endpoint ${args.endpoint_id} 不存在`);

package/src/types.ts

@@ -17,46 +17,6 @@ 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;
-  };
-}
-
 /**
  * Endpoint 配置：支持本地 IPC 和远程 RPC 两种连接模式。
  *
@@ -81,11 +41,6 @@ export interface IcqqEndpointConfig {
    * 默认 true；设为 false 则断开后仅将 `$connected` 置为 false，需手动重连。
    */
   autoReconnect?: boolean;
-  /**
-   * Typing Indicator 配置
-   * 用于在 AI 处理消息时提示用户正在处理中
-   */
-  typingIndicator?: TypingIndicatorConfig;
   /**
    * 出站图片/语音/视频：file=本机临时文件路径（需与 icqq 守护进程同机可读）；
    * base64=经 CQ `base64://` 交给守护进程解码（Zhin 与 icqq 异进程/异机时用，配置 rpc 时默认 base64）。