@zhin.js/adapter-kook 2.0.10 → 2.0.12

package/lib/outbound-sendable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbound-sendable.js","sourceRoot":"","sources":["../src/outbound-sendable.ts"],"names":[],"mappings":"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"}

package/lib/types.d.ts

@@ -18,6 +18,23 @@ export interface KookSenderInfo {
     isGuildOwner?: boolean;
     isAdmin?: boolean;
 }
+export interface KookTypingIndicatorConfig {
+    enabled?: boolean;
+    defaultEmoji?: string;
+    autoRemove?: boolean;
+    removeDelay?: number;
+    privateConfig?: {
+        type?: 'reaction' | 'message' | 'typing' | 'none';
+        emoji?: string;
+        message?: string;
+    };
+    /** 频道/群聊（KOOK channel 走 groupConfig 合并逻辑） */
+    groupConfig?: {
+        type?: 'reaction' | 'message' | 'typing' | 'none';
+        emoji?: string;
+        message?: string;
+    };
+}
 export interface KookBotConfig {
     context: "kook";
     name: string;
@@ -27,6 +44,8 @@ export interface KookBotConfig {
     max_retry?: number;
     ignore?: "bot" | "self";
     logLevel?: LogLevel;
+    /** AI 处理中提示（reaction 推荐：不打断会话） */
+    typingIndicator?: KookTypingIndicatorConfig;
 }
 export type KookRawMessage = PrivateMessageEvent | ChannelMessageEvent;
 //# sourceMappingURL=types.d.ts.map

package/lib/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,YAAY,EAAE,QAAQ,EAAE,CAAC;AAEzB,oBAAY,cAAc;IACxB,MAAM,IAAI;IACV,KAAK,IAAI;IACT,KAAK,IAAI;IACT,YAAY,IAAI;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,MAAM,MAAM,cAAc,GAAG,mBAAmB,GAAG,mBAAmB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,YAAY,EAAE,QAAQ,EAAE,CAAC;AAEzB,oBAAY,cAAc;IACxB,MAAM,IAAI;IACV,KAAK,IAAI;IACT,KAAK,IAAI;IACT,YAAY,IAAI;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE;QACd,IAAI,CAAC,EAAE,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;QAClD,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,6CAA6C;IAC7C,WAAW,CAAC,EAAE;QACZ,IAAI,CAAC,EAAE,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;QAClD,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,kCAAkC;IAClC,eAAe,CAAC,EAAE,yBAAyB,CAAC;CAC7C;AAED,MAAM,MAAM,cAAc,GAAG,mBAAmB,GAAG,mBAAmB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-kook",
-  "version": "2.0.10",
+  "version": "2.0.12",
   "description": "Zhin.js adapter for KOOK (开黑啦)",
   "type": "module",
   "main": "./lib/index.js",
@@ -40,10 +40,10 @@
     "@types/react-dom": "^19.2.3",
     "lucide-react": "^1.17.0",
     "typescript": "^6.0.3",
-    "@zhin.js/cli": "1.0.87",
-    "@zhin.js/host-api": "0.0.4",
+    "@zhin.js/cli": "1.0.88",
     "@zhin.js/contract": "1.0.1",
-    "zhin.js": "1.0.91"
+    "zhin.js": "1.0.93",
+    "@zhin.js/host-api": "0.0.4"
   },
   "peerDependencies": {
     "@zhin.js/client": "2.0.2",
@@ -51,7 +51,7 @@
     "@zhin.js/contract": "1.0.1",
     "@zhin.js/host-router": "0.0.3",
     "@zhin.js/logger": "0.1.70",
-    "zhin.js": "1.0.91"
+    "zhin.js": "1.0.93"
   },
   "peerDependenciesMeta": {
     "@zhin.js/client": {

package/src/bot.ts

@@ -11,6 +11,7 @@ import {
   GuildMember,
   parseGroupId,
 } from "kook-client";
+import { EventEmitter } from "node:events";
 import path from "path";
 import {
   Bot,
@@ -24,10 +25,45 @@ import {
 import type { KookBotConfig, KookSenderInfo, KookRawMessage } from "./types.js";
 import { KookPermission } from "./types.js";
 import type { KookAdapter } from "./adapter.js";
+import { InboundMessageDeduper } from "./kook-inbound.js";
+import {
+  enrichKookGatewayForPlugins,
+  formatKookNotice,
+  formatKookNoticeLog,
+  isKookNoticeGatewayEvent,
+  resolveKookSideEventDedupeKey,
+  type KookGatewayEvent,
+} from "./kook-side-events.js";
+import {
+  encodeKookMsgRef,
+  encodeKookReactionId,
+  isKookApiGoneResult,
+  isKookApiSuccess,
+  isKookMsgGoneError,
+  shouldStopDeleteAfterResponse,
+  kookDeleteApiPath,
+  kookReactionApiPath,
+  parseKookMsgRef,
+  parseKookReactionId,
+  plainKookMsgId,
+  resolveKookRoutes,
+  routeFromSceneType,
+  routeFromSendType,
+  type KookMsgRoute,
+} from "./kook-msg-route.js";
+import { materializeOutboundMedia } from "./outbound-media.js";
+import { uploadKookAsset } from "./kook-asset-upload.js";
+import { convertToKookSendable } from "./outbound-sendable.js";
 
 export class KookBot extends Client implements Bot<KookBotConfig, KookRawMessage> {
   $connected: boolean = false;
+  /** KOOK 平台 user_id，用于 @ 触发匹配（resolveBotAtIds） */
+  $platformUserId?: string;
   adapter: KookAdapter;
+  private readonly inboundDeduper = new InboundMessageDeduper();
+  private readonly onGatewayEvent = (raw: KookGatewayEvent) => {
+    this.handleGatewayEvent(raw);
+  };
 
   get $id(): string {
     return this.$config.name;
@@ -49,6 +85,41 @@ export class KookBot extends Client implements Bot<KookBotConfig, KookRawMessage
     });
     this.adapter = adapter;
     this.setupEventListeners();
+    this.hookGatewayReceiver();
+  }
+
+  /**
+   * 在 kook-client Receiver transform 之前拦截原始 gateway 事件（SDK 未实现 notice transform）
+   */
+  private hookGatewayReceiver(): void {
+    const receiver = this.receiver as import("node:events").EventEmitter;
+    receiver.prependListener("event", this.onGatewayEvent);
+  }
+
+  private handleGatewayEvent(raw: KookGatewayEvent): void {
+    try {
+      const enriched = enrichKookGatewayForPlugins(raw);
+      EventEmitter.prototype.emit.call(this.adapter, "kook.gateway", enriched);
+
+      if (!isKookNoticeGatewayEvent(raw)) return;
+
+      const dedupeKey = resolveKookSideEventDedupeKey(raw, "notice");
+      if (!this.inboundDeduper.shouldProcess(dedupeKey)) return;
+
+      const notice = formatKookNotice(raw, this.$config.name);
+      this.emitSideEvent("notice.receive", notice);
+      this.pluginLogger.info(formatKookNoticeLog(notice));
+    } catch (error) {
+      this.pluginLogger.error("处理 KOOK gateway 事件失败:", error);
+    }
+  }
+
+  private emitSideEvent(
+    event: "notice.receive" | "request.receive",
+    payload: unknown,
+  ): void {
+    this.adapter.emit(event, payload as never);
+    void this.adapter.plugin.dispatch(event, payload as never);
   }
 
   /**
@@ -59,6 +130,14 @@ export class KookBot extends Client implements Bot<KookBotConfig, KookRawMessage
     this.on("message", (msg: KookRawMessage) => {
       try {
         const message = this.$formatMessage(msg);
+        const atSegs = message.$content.filter((s) => s.type === 'at');
+        if (atSegs.length > 0) {
+          this.pluginLogger.debug(
+            `KOOK @解析: self_id=${this.$platformUserId ?? (this as { self_id?: string }).self_id ?? '?'}`
+            + ` at=${JSON.stringify(atSegs.map((s) => s.data))}`
+            + ` preview=${segment.raw(message.$content)}`,
+          );
+        }
         this.pluginLogger.debug(`KOOK 格式化消息: $content=${JSON.stringify(message.$content)}, $raw=${message.$raw}`);
         this.adapter.emit("message.receive", message);
         
@@ -139,7 +218,9 @@ export class KookBot extends Client implements Bot<KookBotConfig, KookRawMessage
       $timestamp: msg.timestamp,
       
       $recall: async () => {
-        await this.$recallMessage(message.$id);
+        await this.$recallMessage(message.$id, {
+          route: msg.message_type === 'channel' ? 'channel' : 'direct',
+        });
       },
       
       $reply: async (content: SendContent, quote?: string | boolean): Promise<string> => {
@@ -389,6 +470,16 @@ export class KookBot extends Client implements Bot<KookBotConfig, KookRawMessage
       throw error;
     }
   }
+  private buildAtElement(userId: string | number): MessageElement {
+    const id = String(userId);
+    return { type: 'at', data: { id, user_id: id, qq: id } };
+  }
+
+  private resolveAtUserId(data: Record<string, unknown>): string {
+    const raw = data.user_id ?? data.qq ?? data.id;
+    return raw == null ? '' : String(raw);
+  }
+
   private parseMarkdown(content: string): MessageElement[] {
     const elements: MessageElement[] = [];
     
@@ -420,7 +511,7 @@ export class KookBot extends Client implements Bot<KookBotConfig, KookRawMessage
       matches.push({
         index: match.index,
         length: match[0].length,
-        element: { type: "at", data: { id: userId } }
+        element: this.buildAtElement(userId),
       });
     }
 
@@ -497,7 +588,7 @@ export class KookBot extends Client implements Bot<KookBotConfig, KookRawMessage
           break;
           
         case "at":
-          elements.push({ type: "at", data: { id: segment.user_id } });
+          elements.push(this.buildAtElement(segment.user_id));
           break;
           
         case "image":
@@ -554,7 +645,14 @@ export class KookBot extends Client implements Bot<KookBotConfig, KookRawMessage
     try {
       await this.connect();
       this.$connected = true;
-      this.pluginLogger.info(`KOOK Bot ${this.$id} 连接成功`);
+      const selfId = (this as { self_id?: string | number }).self_id;
+      if (selfId != null) {
+        this.$platformUserId = String(selfId);
+      }
+      this.pluginLogger.info(
+        `KOOK Bot ${this.$id} 连接成功`
+        + (this.$platformUserId ? ` (platform_user_id=${this.$platformUserId})` : ''),
+      );
     } catch (error) {
       this.pluginLogger.error(`KOOK Bot ${this.$id} 连接失败:`, error);
       throw error;
@@ -566,6 +664,9 @@ export class KookBot extends Client implements Bot<KookBotConfig, KookRawMessage
  */
   async $disconnect(): Promise<void> {
     try {
+      const receiver = this.receiver as import("node:events").EventEmitter;
+      receiver.off("event", this.onGatewayEvent);
+      this.inboundDeduper.clear();
       (this as unknown as import('node:events').EventEmitter).removeAllListeners();
       await this.disconnect();
       this.$connected = false;
@@ -576,6 +677,13 @@ export class KookBot extends Client implements Bot<KookBotConfig, KookRawMessage
     }
   }
 
+  /**
+   * 上传媒体（覆盖 kook-client：其 FormData.append 不接受 Node Buffer）
+   */
+  override async uploadMedia(data: string | Buffer): Promise<string> {
+    return uploadKookAsset(this.request, data);
+  }
+
   /**
  * 发送消息
  */
@@ -583,12 +691,11 @@ export class KookBot extends Client implements Bot<KookBotConfig, KookRawMessage
     try {
       const { id, type, content } = options;
 
-      // 将消息段转换为 KOOK 格式
-      const elements: MessageElement[] = Array.isArray(content)
-        ? content.map(el => typeof el === 'string' ? { type: 'text' as const, data: { text: el } } : el)
-        : [typeof content === 'string' ? { type: 'text' as const, data: { text: content } } : content];
-
-      const kookContent = this.convertToKookFormat(elements);
+      const elements = await materializeOutboundMedia(this, content);
+      const kookContent = convertToKookSendable(
+        elements,
+        (els) => this.convertToKookFormat(els),
+      );
 
       // 根据消息类型发送
       let result: any;
@@ -598,7 +705,8 @@ export class KookBot extends Client implements Bot<KookBotConfig, KookRawMessage
         result = await (this as any).sendChannelMsg(id, kookContent);
       }
 
-      return result?.msg_id || "";
+      const route = routeFromSendType(type);
+      return encodeKookMsgRef(route, String(result?.msg_id ?? ''));
     } catch (error) {
       this.pluginLogger.error(`KOOK Bot ${this.$id} 发送消息失败:`, error);
       throw error;
@@ -606,18 +714,122 @@ export class KookBot extends Client implements Bot<KookBotConfig, KookRawMessage
   }
 
   /**
- * 撤回消息
+   * 撤回消息。支持 `kook:channel:msgId` 出站 ref，或入站 plain msgId + route/sceneType 提示。
    */
-  async $recallMessage(messageId: string): Promise<void> {
+  async $recallMessage(
+    messageIdOrRef: string,
+    hint?: { route?: KookMsgRoute; sceneType?: 'private' | 'group' | 'channel' },
+  ): Promise<void> {
+    const { route: encodedRoute, msgId } = parseKookMsgRef(messageIdOrRef);
+    const routeHint = encodedRoute ?? hint?.route ?? routeFromSceneType(hint?.sceneType);
     try {
-      await (this as any).deleteMsg(messageId);
-      this.pluginLogger.debug(`KOOK Bot ${this.$id} 撤回消息: ${messageId}`);
+      await this.deleteKookMsg(msgId, routeHint);
+      this.pluginLogger.debug(
+        `KOOK Bot ${this.$id} 撤回消息 (${routeHint ?? 'auto'}): ${msgId}`,
+      );
     } catch (error) {
       this.pluginLogger.error(`KOOK Bot ${this.$id} 撤回消息失败:`, error);
       throw error;
     }
   }
 
+  private async deleteKookMsg(msgId: string, routeHint?: KookMsgRoute): Promise<void> {
+    const routes = resolveKookRoutes('delete', routeHint);
+    let lastError: unknown;
+
+    for (const route of routes) {
+      try {
+        const result = await this.request.post(
+          kookDeleteApiPath(route),
+          { msg_id: msgId },
+        ) as { code?: number };
+        if (shouldStopDeleteAfterResponse(result, routes.length)) return;
+      } catch (err) {
+        if (isKookMsgGoneError(err)) return;
+        lastError = err;
+      }
+    }
+
+    return;
+  }
+
+  /**
+   * 为消息添加表情回应（TypingIndicator reaction 模式）
+   * @returns reactionId（含 channel/direct 路由），供 $removeReaction 使用
+   */
+  async $addReaction(
+    messageId: string,
+    emoji: string,
+    hint?: { sceneType?: 'private' | 'group' | 'channel' },
+  ): Promise<string> {
+    const msgId = plainKookMsgId(messageId);
+    const route = await this.mutateMsgReaction(
+      msgId,
+      emoji,
+      'add',
+      routeFromSceneType(hint?.sceneType),
+    );
+    return encodeKookReactionId(route, msgId, emoji);
+  }
+
+  /** 移除本 Bot 在消息上的表情回应 */
+  async $removeReaction(messageId: string, reactionId: string): Promise<void> {
+    const { route, emoji } = parseKookReactionId(reactionId);
+    await this.mutateMsgReaction(plainKookMsgId(messageId), emoji, 'delete', route);
+  }
+
+  private async mutateMsgReaction(
+    msgId: string,
+    emoji: string,
+    action: 'add' | 'delete',
+    routeHint?: KookMsgRoute,
+  ): Promise<KookMsgRoute> {
+    const routes = resolveKookRoutes(action, routeHint);
+    const body = { msg_id: msgId, emoji };
+    let lastError: unknown;
+
+    for (const route of routes) {
+      try {
+        const result = await this.request.post(
+          kookReactionApiPath(route, action),
+          body,
+        ) as { code?: number };
+        if (isKookApiSuccess(result)) {
+          this.pluginLogger.debug(
+            `KOOK Bot ${this.$id} ${action} reaction (${route}) on ${msgId}`,
+          );
+          return route;
+        }
+        if (action === 'delete' && shouldStopDeleteAfterResponse(result, routes.length)) {
+          const label = isKookApiGoneResult(result) ? 'already gone' : 'done';
+          this.pluginLogger.debug(
+            `KOOK Bot ${this.$id} delete reaction ${label} (${route}) on ${msgId}`,
+          );
+          return route;
+        }
+      } catch (err) {
+        if (action === 'delete' && isKookMsgGoneError(err)) {
+          this.pluginLogger.debug(
+            `KOOK Bot ${this.$id} delete reaction already gone (${route}) on ${msgId}`,
+          );
+          return route;
+        }
+        lastError = err;
+      }
+    }
+
+    if (action === 'delete') {
+      this.pluginLogger.debug(
+        `KOOK Bot ${this.$id} delete reaction noop on ${msgId}`,
+      );
+      return routeHint ?? 'channel';
+    }
+
+    throw lastError instanceof Error
+      ? lastError
+      : new Error(`KOOK ${action} reaction failed (msg_id=${msgId})`);
+  }
+
   /**
  * 将消息段转换为 KOOK KMarkdown 格式
  * 支持：文本、图片、@提及、表情、引用等
@@ -634,12 +846,13 @@ export class KookBot extends Client implements Bot<KookBotConfig, KookRawMessage
             // 图片：![alt](url)
             return `![${el.data.alt || '图片'}](${el.data.url || el.data.file})`;
 
-          case "at":
-            // @提及：(met)userId(met) 或 @all
-            if (el.data.id === "all") {
-              return "(met)all(met)";
+          case "at": {
+            const atId = this.resolveAtUserId(el.data as Record<string, unknown>);
+            if (atId === 'all') {
+              return '(met)all(met)';
             }
-            return `(met)${el.data.id}(met)`;
+            return `(met)${atId}(met)`;
+          }
 
           case "face":
             // 表情：(emj)表情名(emj)[表情ID]

package/src/kook-asset-upload.ts

@@ -0,0 +1,55 @@
+/**
+ * KOOK /v3/asset/create 上传（formdata-node 要求 Blob，不能直传 Node Buffer）。
+ */
+import { readFile } from "node:fs/promises";
+
+export interface KookAssetRequest {
+  post(
+    url: string,
+    data: FormData,
+    config?: { headers?: Record<string, string> },
+  ): Promise<{ data?: { url?: string }; message?: string }>;
+}
+
+function guessFilename(data: string | Buffer): string {
+  if (Buffer.isBuffer(data)) return "upload.png";
+  if (/^data:image\/png/i.test(data)) return "upload.png";
+  if (/^data:image\/jpe?g/i.test(data)) return "upload.jpg";
+  if (/^data:image\/gif/i.test(data)) return "upload.gif";
+  if (/^data:image\/webp/i.test(data)) return "upload.webp";
+  const base = data.replace(/^file:\/\//, "").split("/").pop();
+  return base?.includes(".") ? base : "upload.png";
+}
+
+async function toBuffer(data: string | Buffer): Promise<Buffer> {
+  if (Buffer.isBuffer(data)) return data;
+  if (data.startsWith("base64://")) {
+    return Buffer.from(data.slice(9), "base64");
+  }
+  if (/^data:[^/]+\/[^;]+;base64,/i.test(data)) {
+    return Buffer.from(data.replace(/^data:[^/]+\/[^;]+;base64,/, ""), "base64");
+  }
+  return readFile(data.replace(/^file:\/\//, ""));
+}
+
+export async function uploadKookAsset(
+  request: KookAssetRequest,
+  data: string | Buffer,
+): Promise<string> {
+  if (typeof data === "string" && /^https?:\/\//i.test(data)) {
+    return data;
+  }
+  const buffer = await toBuffer(data);
+  const form = new globalThis.FormData();
+  form.append("file", new globalThis.Blob([new Uint8Array(buffer)]), guessFilename(data));
+
+  const response = await request.post("/v3/asset/create", form, {
+    headers: { Accept: "application/json" },
+  });
+
+  const url = response.data?.url;
+  if (!url) {
+    throw new Error(`KOOK asset upload failed: ${response.message ?? "missing url"}`);
+  }
+  return url;
+}

package/src/kook-inbound.ts

@@ -0,0 +1,22 @@
+/**
+ * KOOK 入站侧事件去重（gateway notice / 系统消息）
+ */
+const DEDUPE_TTL_MS = 120_000;
+
+export class InboundMessageDeduper {
+  private readonly seen = new Map<string, number>();
+
+  shouldProcess(key: string): boolean {
+    const now = Date.now();
+    for (const [id, t] of this.seen) {
+      if (now - t > DEDUPE_TTL_MS) this.seen.delete(id);
+    }
+    if (this.seen.has(key)) return false;
+    this.seen.set(key, now);
+    return true;
+  }
+
+  clear(): void {
+    this.seen.clear();
+  }
+}

package/src/kook-msg-route.ts

@@ -0,0 +1,122 @@
+/**
+ * KOOK msg_id 路由：频道 / 私聊 API 路径不同，出站编码路由、入站/删除按路由命中。
+ */
+
+export type KookMsgRoute = 'channel' | 'direct';
+
+export function routeFromSceneType(
+  sceneType?: 'private' | 'group' | 'channel',
+): KookMsgRoute | undefined {
+  if (sceneType === 'private') return 'direct';
+  if (sceneType === 'group' || sceneType === 'channel') return 'channel';
+  return undefined;
+}
+
+export function routeFromSendType(type: 'private' | 'group' | 'channel'): KookMsgRoute {
+  return type === 'private' ? 'direct' : 'channel';
+}
+
+/** 出站 send 返回值，供 recall / typing 删除时走路由 */
+export function encodeKookMsgRef(route: KookMsgRoute, msgId: string): string {
+  return `kook:${route}:${msgId}`;
+}
+
+export function parseKookMsgRef(ref: string): { route?: KookMsgRoute; msgId: string } {
+  const parts = ref.split(':');
+  if (parts[0] === 'kook' && (parts[1] === 'channel' || parts[1] === 'direct') && parts.length >= 3) {
+    return { route: parts[1], msgId: parts.slice(2).join(':') };
+  }
+  return { msgId: ref };
+}
+
+export function plainKookMsgId(ref: string): string {
+  return parseKookMsgRef(ref).msgId;
+}
+
+export function resolveKookRoutes(
+  action: 'add' | 'delete',
+  routeHint?: KookMsgRoute,
+): KookMsgRoute[] {
+  if (action === 'delete' && routeHint) return [routeHint];
+  if (routeHint) return [routeHint, routeHint === 'channel' ? 'direct' : 'channel'];
+  return ['channel', 'direct'];
+}
+
+function isKookGoneText(text: string): boolean {
+  return text.includes('404')
+    || text.includes('该数据不存在')
+    || text.includes('没有权限操作')
+    || text.toLowerCase().includes('not found');
+}
+
+export function isKookMsgGoneError(err: unknown): boolean {
+  return isKookGoneText(err instanceof Error ? err.message : String(err));
+}
+
+/** KOOK 标准成功：code=0；少数接口 HTTP 200 省略 code */
+export function isKookApiSuccess(result: unknown): boolean {
+  if (result == null || typeof result !== 'object') return false;
+  const { code } = result as { code?: number };
+  if (code === 0) return true;
+  if (code === undefined) return true;
+  return false;
+}
+
+/** 明确的业务失败（可尝试另一路由） */
+export function isKookExplicitError(result: unknown): boolean {
+  if (result == null || typeof result !== 'object') return false;
+  const { code } = result as { code?: number };
+  return typeof code === 'number' && code !== 0;
+}
+
+/**
+ * delete 请求已返回且未抛错：是否停止（不再打第二条路由）。
+ * 仅当双路由且响应为明确错误码时，才继续尝试下一路由。
+ */
+export function shouldStopDeleteAfterResponse(
+  result: unknown,
+  routeCount: number,
+): boolean {
+  if (isKookApiSuccess(result) || isKookApiGoneResult(result)) return true;
+  if (routeCount === 1) return true;
+  return !isKookExplicitError(result);
+}
+
+/** KOOK 有时用 HTTP 200 + 非 0 code 表示目标已不存在 */
+export function isKookApiGoneResult(result: unknown): boolean {
+  if (!result || typeof result !== 'object') return false;
+  const { code, message } = result as { code?: number; message?: string };
+  if (code === 404) return true;
+  return isKookGoneText(message ?? '');
+}
+
+export function kookDeleteApiPath(route: KookMsgRoute): string {
+  return route === 'channel' ? '/v3/message/delete' : '/v3/direct-message/delete';
+}
+
+export function kookReactionApiPath(route: KookMsgRoute, action: 'add' | 'delete'): string {
+  const prefix = route === 'channel' ? '/v3/message' : '/v3/direct-message';
+  const suffix = action === 'add' ? 'add-reaction' : 'delete-reaction';
+  return `${prefix}/${suffix}`;
+}
+
+export function encodeKookReactionId(route: KookMsgRoute, msgId: string, emoji: string): string {
+  return `reaction:${route}:${msgId}:${emoji}`;
+}
+
+export function parseKookReactionId(reactionId: string): {
+  route?: KookMsgRoute;
+  emoji: string;
+} {
+  const parts = reactionId.split(':');
+  if (parts[0] === 'reaction' && (parts[1] === 'channel' || parts[1] === 'direct')) {
+    return {
+      route: parts[1],
+      emoji: parts.slice(3).join(':') || '⏳',
+    };
+  }
+  if (parts[0] === 'reaction' && parts.length >= 3) {
+    return { emoji: parts.slice(2).join(':') || '⏳' };
+  }
+  return { emoji: parts[parts.length - 1] ?? '⏳' };
+}