mioku-plugin-chat 2.5.0 → 2.6.0

package/manage/queue-processor.ts

@@ -2,7 +2,7 @@ import type { MiokiContext } from "mioki";
 import type { AIInstance } from "mioku";
 import type { ChatConfig, TargetMessage } from "../types";
 import type { ChatDatabase } from "../db";
-import type { HumanizeEngine } from "../humanize";
+import type { HumanizeEngine, ChatConfigProvider } from "../humanize";
 import type { SkillSessionManager } from "./skill-session";
 import type { GroupStructuredHistoryManager, StructuredUserInput } from "./group-structured-history";
 import { buildStructuredUserInputFromEvent } from "./group-structured-history";
@@ -35,7 +35,8 @@ export class QueueProcessor {
   private dynamicDelayQueues = new Map<string, DynamicDelayQueueData>();
 
   private ctx: MiokiContext;
-  private cfg: ChatConfig;
+  private configProvider: ChatConfigProvider;
+  private defaultConfig: ChatConfig;
   private db: ChatDatabase;
   private humanize: HumanizeEngine;
   private aiInstance: AIInstance;
@@ -60,7 +61,8 @@ export class QueueProcessor {
 
   constructor(pluginCtx: ChatPluginContext) {
     this.ctx = pluginCtx.ctx;
-    this.cfg = pluginCtx.config;
+    this.configProvider = pluginCtx.configProvider;
+    this.defaultConfig = pluginCtx.defaultConfig;
     this.db = pluginCtx.db;
     this.humanize = pluginCtx.humanize;
     this.aiInstance = pluginCtx.aiInstance;
@@ -147,14 +149,15 @@ export class QueueProcessor {
       content: mergedContent, messageId: firstMsg.messageId, timestamp: Date.now(),
     };
 
+    const cfg = this.configProvider(groupId);
     const botRole = await getBotRole(groupId, this.ctx, selfId);
-    const botNickname = this.cfg.nicknames[0] || this.ctx.pickBot(selfId).nickname || "Bot";
+    const botNickname = cfg.nicknames[0] || this.ctx.pickBot(selfId).nickname || "Bot";
     const { groupName, memberCount } = await this.getGroupInfoData(this.ctx, groupId, selfId, String(groupId));
-    const { history } = await this.getGroupHistoryMessages(groupId, groupSessionId, this.ctx, this.cfg.historyCount, this.db, selfId, this.buildHistoryMediaOptions(this.aiInstance, this.cfg));
+    const { history } = await this.getGroupHistoryMessages(groupId, groupSessionId, this.ctx, cfg.historyCount, this.db, selfId, this.buildHistoryMediaOptions(this.aiInstance, cfg));
 
     const toolCtx = this.buildToolContext({
       ctx: this.ctx, event: firstMsg.event, groupSessionId, groupId, userId: firstMsg.userId,
-      config: this.cfg, aiService: this.aiService, db: this.db, botRole, humanize: this.humanize, targetMessage, selfId,
+      config: cfg, aiService: this.aiService, db: this.db, botRole, humanize: this.humanize, targetMessage, selfId,
     });
 
     this.sessionManager.getOrCreate(groupSessionId, "group", groupId);
@@ -162,18 +165,18 @@ export class QueueProcessor {
 
     const result = await this.runWithRateLimitGuard(
       () => this.runChat(this.aiInstance, toolCtx, history, targetMessage, {
-        config: this.cfg, groupName, memberCount, botNickname, botRole, aiService: this.aiService, isGroup: true,
+        config: cfg, groupName, memberCount, botNickname, botRole, aiService: this.aiService, isGroup: true,
         memoryContext: contexts.memoryContext, topicContext: contexts.topicContext, expressionContext: contexts.expressionContext,
         replyContext: { type: "review", targetUser: targetMessage.userName, targetMessage: targetMessage.content },
         reviewMessages: { contents: mergedContents, userNames, messageIds },
       }, this.humanize, this.skillManager, {
-        manager: this.groupStructuredHistory, ttlMs: this.cfg.groupStructuredHistoryTtlMs, currentUserInputs: structuredUserInputs,
+        manager: this.groupStructuredHistory, ttlMs: cfg.groupStructuredHistoryTtlMs, currentUserInputs: structuredUserInputs,
       }),
       { userId: targetMessage.userId, groupId, label: "dynamic-delay" },
     );
     if (!result) return;
 
-    await this.sendAIResponse({ ctx: this.ctx, groupId, messages: result.messages, config: this.cfg, sentIndices: toolCtx.sentMessageIndices }, selfId);
+    await this.sendAIResponse({ ctx: this.ctx, groupId, messages: result.messages, config: cfg, sentIndices: toolCtx.sentMessageIndices }, selfId);
     this.startCooldownTimer(groupSessionId, groupId, selfId);
   }
 
@@ -191,8 +194,10 @@ export class QueueProcessor {
       const queuedContents: string[] = [];
       const structuredUserInputs: StructuredUserInput[] = [];
 
+      const cfg = this.configProvider(groupId);
+
       for (const item of queue) {
-        const { text: extractedText, multimodal } = extractContent(item.event, this.cfg, this.ctx);
+        const { text: extractedText, multimodal } = extractContent(item.event, cfg, this.ctx);
         const content = multimodal ? JSON.stringify(multimodal) : extractedText;
         if (content) {
           queuedContents.push(content);
@@ -219,32 +224,32 @@ export class QueueProcessor {
       };
 
       const botRole = await getBotRole(groupId, this.ctx, selfId);
-      const botNickname = this.cfg.nicknames[0] || this.ctx.pickBot(selfId).nickname || "Bot";
+      const botNickname = cfg.nicknames[0] || this.ctx.pickBot(selfId).nickname || "Bot";
       const toolCtx = this.buildToolContext({
         ctx: this.ctx, event: null, groupSessionId, groupId, userId: targetMessage.userId,
-        config: this.cfg, aiService: this.aiService, db: this.db, botRole, humanize: this.humanize, targetMessage, selfId,
+        config: cfg, aiService: this.aiService, db: this.db, botRole, humanize: this.humanize, targetMessage, selfId,
       });
 
-      const { history } = await this.getGroupHistoryMessages(groupId, groupSessionId, this.ctx, this.cfg.historyCount, this.db, selfId, this.buildHistoryMediaOptions(this.aiInstance, this.cfg));
+      const { history } = await this.getGroupHistoryMessages(groupId, groupSessionId, this.ctx, cfg.historyCount, this.db, selfId, this.buildHistoryMediaOptions(this.aiInstance, cfg));
       const contexts = await this.getHumanizeContexts(this.humanize, groupSessionId, targetMessage.userName, history, targetMessage.userId);
       const { groupName, memberCount } = await this.getGroupInfoData(this.ctx, groupId, selfId);
 
       const result = await this.runWithRateLimitGuard(
         () => this.runChat(this.aiInstance, toolCtx, history, targetMessage, {
-          config: this.cfg, groupName, memberCount, botNickname, botRole: toolCtx.botRole, aiService: this.aiService, isGroup: true,
+          config: cfg, groupName, memberCount, botNickname, botRole: toolCtx.botRole, aiService: this.aiService, isGroup: true,
           memoryContext: contexts.memoryContext, topicContext: contexts.topicContext, expressionContext: contexts.expressionContext,
           replyContext: { type: "comment", targetUser: targetMessage.userName, targetMessage: targetMessage.content },
         }, this.humanize, this.skillManager, {
-          manager: this.groupStructuredHistory, ttlMs: this.cfg.groupStructuredHistoryTtlMs, currentUserInputs: structuredUserInputs,
+          manager: this.groupStructuredHistory, ttlMs: cfg.groupStructuredHistoryTtlMs, currentUserInputs: structuredUserInputs,
         }),
         { userId: targetMessage.userId, groupId, label: "queue" },
       );
       if (!result) return;
 
-      await this.sendAIResponse({ ctx: this.ctx, groupId, messages: result.messages, config: this.cfg, sentIndices: toolCtx.sentMessageIndices }, selfId);
+      await this.sendAIResponse({ ctx: this.ctx, groupId, messages: result.messages, config: cfg, sentIndices: toolCtx.sentMessageIndices }, selfId);
       await this.sendEmoji(this.ctx, groupId, result.emojiPath, selfId);
       const now = Date.now();
-      this.saveBotMessages(groupId, groupSessionId, result.messages, now, this.cfg, this.db, this.ctx, selfId);
+      this.saveBotMessages(groupId, groupSessionId, result.messages, now, cfg, this.db, this.ctx, selfId);
       this.sessionManager.touch(groupSessionId);
       this.ctx.logger.info(`[Queue] group ${groupSessionId} done`);
     } catch (err) {

package/manage/rate-limiter.ts

@@ -1,12 +1,24 @@
-import type { AIRequestLimitConfig, DynamicDelayConfig } from "../types";
+import type { AIRequestLimitConfig, ChatConfig, DynamicDelayConfig } from "../types";
+
+const DEFAULT_DYNAMIC_DELAY: DynamicDelayConfig = {
+  enabled: true,
+  interactionWindowMs: 60_000,
+  baseDelayMs: 30_000,
+  maxDelayMs: 300_000,
+};
+
+const DEFAULT_AI_REQUEST_LIMITS: AIRequestLimitConfig = {
+  userRpm: 3,
+  groupRpm: 6,
+  windowMs: 60_000,
+};
+
+export type ChatConfigProvider = (groupId?: number) => ChatConfig;
 
 export class RateLimiter {
-  // 用户触发记录：userId -> timestamp[]
   private userTriggers: Map<number, number[]> = new Map();
-  // 用户最近消息：userId -> {content, timestamp}[]
   private userMessages: Map<number, { content: string; timestamp: number }[]> =
     new Map();
-  // 群组最后响应时间：groupId -> timestamp
   private groupLastResponse: Map<number, number> = new Map();
   private groupInteractions: Map<number, Map<number, number[]>> = new Map();
   private userAiRequests: Map<number, number[]> = new Map();
@@ -17,14 +29,13 @@ export class RateLimiter {
   private readonly dedupWindowMs: number;
   private readonly groupCooldownMs: number;
   private readonly cleanupTimer: ReturnType<typeof setInterval>;
-  private readonly dynamicDelayConfig: DynamicDelayConfig;
-  private readonly aiRequestLimitConfig: AIRequestLimitConfig;
-  // 外部注入的队列长度获取函数
+  private getConfig: ChatConfigProvider;
   private getQueueLengthFn: ((groupId: number) => number) | null = null;
 
-  /**
-   * 设置队列长度获取函数
-   */
+  setConfigProvider(provider: ChatConfigProvider): void {
+    this.getConfig = provider;
+  }
+
   setQueueLengthGetter(fn: (groupId: number) => number): void {
     this.getQueueLengthFn = fn;
   }
@@ -34,28 +45,27 @@ export class RateLimiter {
     windowMs?: number;
     dedupWindowMs?: number;
     groupCooldownMs?: number;
-    dynamicDelay?: DynamicDelayConfig;
-    aiRequestLimits?: AIRequestLimitConfig;
   }) {
     this.maxTriggersPerWindow = options?.maxTriggersPerWindow ?? 5;
     this.windowMs = options?.windowMs ?? 60_000;
     this.dedupWindowMs = options?.dedupWindowMs ?? 30_000;
     this.groupCooldownMs = options?.groupCooldownMs ?? 1_000;
-    this.dynamicDelayConfig = options?.dynamicDelay ?? {
-      enabled: true,
-      interactionWindowMs: 60_000,
-      baseDelayMs: 30_000,
-      maxDelayMs: 300_000,
-    };
-    this.aiRequestLimitConfig = options?.aiRequestLimits ?? {
-      userRpm: 3,
-      groupRpm: 6,
-      windowMs: 60_000,
-    };
+    this.getConfig = () => ({
+      dynamicDelay: DEFAULT_DYNAMIC_DELAY,
+      aiRequestLimits: DEFAULT_AI_REQUEST_LIMITS,
+    }) as unknown as ChatConfig;
 
     this.cleanupTimer = setInterval(() => this.cleanup(), 300_000);
   }
 
+  private getDynamicDelay(groupId?: number): DynamicDelayConfig {
+    return this.getConfig(groupId)?.dynamicDelay ?? DEFAULT_DYNAMIC_DELAY;
+  }
+
+  private getAiRequestLimits(groupId?: number): AIRequestLimitConfig {
+    return this.getConfig(groupId)?.aiRequestLimits ?? DEFAULT_AI_REQUEST_LIMITS;
+  }
+
   canProcess(
     userId: number,
     groupId: number | undefined,
@@ -63,7 +73,6 @@ export class RateLimiter {
   ): boolean {
     const now = Date.now();
 
-    // 群组冷却检查
     if (groupId) {
       const lastResponse = this.groupLastResponse.get(groupId);
       if (lastResponse && now - lastResponse < this.groupCooldownMs) {
@@ -71,14 +80,12 @@ export class RateLimiter {
       }
     }
 
-    // 用户频率检查
     const triggers = this.userTriggers.get(userId) ?? [];
     const recentTriggers = triggers.filter((t) => now - t < this.windowMs);
     if (recentTriggers.length >= this.maxTriggersPerWindow) {
       return false;
     }
 
-    // 重复消息检查
     const messages = this.userMessages.get(userId) ?? [];
     const recentSame = messages.find(
       (m) => m.content === content && now - m.timestamp < this.dedupWindowMs,
@@ -86,34 +93,29 @@ export class RateLimiter {
     return !recentSame;
   }
 
-  /**
-   * 记录已处理的消息
-   */
   record(userId: number, groupId: number | undefined, content: string): void {
     const now = Date.now();
 
-    // 记录触发
     const triggers = this.userTriggers.get(userId) ?? [];
     triggers.push(now);
     this.userTriggers.set(userId, triggers);
 
-    // 记录消息（只保留最近 3 条）
     const messages = this.userMessages.get(userId) ?? [];
     messages.push({ content, timestamp: now });
     if (messages.length > 3) messages.shift();
     this.userMessages.set(userId, messages);
 
-    // 记录群组响应
     if (groupId) {
       this.groupLastResponse.set(groupId, now);
     }
   }
 
   recordInteraction(groupId: number, userId: number): void {
-    if (!this.dynamicDelayConfig.enabled) return;
+    const dynamicDelay = this.getDynamicDelay(groupId);
+    if (!dynamicDelay.enabled) return;
 
     const now = Date.now();
-    const windowMs = this.dynamicDelayConfig.interactionWindowMs;
+    const windowMs = dynamicDelay.interactionWindowMs;
 
     let groupUsers = this.groupInteractions.get(groupId);
     if (!groupUsers) {
@@ -129,7 +131,7 @@ export class RateLimiter {
 
   canRunAIRequest(userId?: number, groupId?: number): boolean {
     const now = Date.now();
-    const { userRpm, groupRpm, windowMs } = this.aiRequestLimitConfig;
+    const { userRpm, groupRpm, windowMs } = this.getAiRequestLimits(groupId);
 
     if (typeof userId === "number") {
       const userRequests = (this.userAiRequests.get(userId) ?? []).filter(
@@ -154,7 +156,7 @@ export class RateLimiter {
 
   recordAIRequest(userId?: number, groupId?: number): void {
     const now = Date.now();
-    const windowMs = this.aiRequestLimitConfig.windowMs;
+    const { windowMs } = this.getAiRequestLimits(groupId);
 
     if (typeof userId === "number") {
       const userRequests = (this.userAiRequests.get(userId) ?? []).filter(
@@ -175,9 +177,8 @@ export class RateLimiter {
 
   getInteractionCount(groupId: number): number {
     const now = Date.now();
-    const windowMs = this.dynamicDelayConfig.interactionWindowMs;
+    const { interactionWindowMs: windowMs } = this.getDynamicDelay(groupId);
 
-    // 优先使用队列长度作为互动人数计算
     if (this.getQueueLengthFn) {
       const queueLength = this.getQueueLengthFn(groupId);
       if (queueLength > 0) {
@@ -185,7 +186,6 @@ export class RateLimiter {
       }
     }
 
-    // 回退到 groupInteractions 统计
     const groupUsers = this.groupInteractions.get(groupId);
     if (!groupUsers) return 0;
 
@@ -200,12 +200,13 @@ export class RateLimiter {
   }
 
   calculateDelay(groupId: number): number {
-    if (!this.dynamicDelayConfig.enabled) return 0;
+    const dynamicDelay = this.getDynamicDelay(groupId);
+    if (!dynamicDelay.enabled) return 0;
 
     const interactionCount = this.getInteractionCount(groupId);
     if (interactionCount <= 1) return 0;
 
-    const { baseDelayMs, maxDelayMs } = this.dynamicDelayConfig;
+    const { baseDelayMs, maxDelayMs } = dynamicDelay;
     const delay = (interactionCount - 1) * baseDelayMs;
     return Math.min(delay, maxDelayMs);
   }
@@ -257,46 +258,21 @@ export class RateLimiter {
       }
     }
 
-    const aiWindowMs = this.aiRequestLimitConfig.windowMs;
-    for (const [userId, requests] of this.userAiRequests) {
-      const valid = requests.filter(
-        (timestamp) => now - timestamp < aiWindowMs,
-      );
-      if (valid.length === 0) {
-        this.userAiRequests.delete(userId);
-      } else {
-        this.userAiRequests.set(userId, valid);
-      }
-    }
-
-    for (const [groupId, requests] of this.groupAiRequests) {
-      const valid = requests.filter(
-        (timestamp) => now - timestamp < aiWindowMs,
-      );
-      if (valid.length === 0) {
-        this.groupAiRequests.delete(groupId);
-      } else {
-        this.groupAiRequests.set(groupId, valid);
-      }
-    }
-
-    if (this.dynamicDelayConfig.enabled) {
-      const windowMs = this.dynamicDelayConfig.interactionWindowMs;
-      for (const [groupId, groupUsers] of this.groupInteractions) {
-        let hasActiveUser = false;
-        for (const [userId, timestamps] of groupUsers) {
-          const valid = timestamps.filter((t) => now - t < windowMs);
-          if (valid.length === 0) {
-            groupUsers.delete(userId);
-          } else {
-            groupUsers.set(userId, valid);
-            hasActiveUser = true;
-          }
-        }
-        if (!hasActiveUser) {
-          this.groupInteractions.delete(groupId);
+    for (const [groupId, groupUsers] of this.groupInteractions) {
+      const windowMs = this.getDynamicDelay(groupId).interactionWindowMs;
+      let hasActiveUser = false;
+      for (const [userId, timestamps] of groupUsers) {
+        const valid = timestamps.filter((t) => now - t < windowMs);
+        if (valid.length === 0) {
+          groupUsers.delete(userId);
+        } else {
+          groupUsers.set(userId, valid);
+          hasActiveUser = true;
         }
       }
+      if (!hasActiveUser) {
+        this.groupInteractions.delete(groupId);
+      }
     }
   }
 
@@ -309,4 +285,4 @@ export class RateLimiter {
     this.userAiRequests.clear();
     this.groupAiRequests.clear();
   }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mioku-plugin-chat",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "AI 智能聊天插件",
   "main": "index.ts",
   "type": "module",

package/runtime/chat-runtime.ts

@@ -12,7 +12,7 @@ import { executeChatRuntimeRequest } from "../core/chat-turn";
 
 export function createChatRuntime(
   pluginCtx: ChatPluginContext,
-  getConfig: () => Promise<ChatConfig>,
+  getConfig: (groupId?: number) => Promise<ChatConfig>,
 ): ChatRuntime {
   return {
     async requestInformation(

package/types.ts

@@ -219,6 +219,29 @@ export interface ChatConfig {
   retention: RetentionConfig;
 }
 
+/**
+ * 每群单独的开关覆盖
+ * 不填写的开关回退到全局默认；私聊会话不使用此覆盖
+ */
+export interface ChatGroupOverrides {
+  emoji?: { enabled?: boolean };
+  expression?: { enabled?: boolean };
+  retention?: { enabled?: boolean };
+  memory?: { enabled?: boolean };
+  topic?: { enabled?: boolean };
+  planner?: { enabled?: boolean };
+  audio?: { enabled?: boolean };
+  searxng?: { enabled?: boolean };
+  webReader?: { enabled?: boolean };
+  dynamicDelay?: { enabled?: boolean };
+  enableMarkdownScreenshot?: boolean;
+  enableMediaRecognition?: boolean;
+}
+
+export type ChatGroupsFile = {
+  groups: Record<string, ChatGroupOverrides>;
+};
+
 /**
  * 会话类型
  */

package/utils/group-config.ts

@@ -0,0 +1,70 @@
+import type { ChatConfig, ChatGroupOverrides } from "../types";
+
+const OVERRIDABLE_SUB_OBJECTS = [
+  "emoji",
+  "expression",
+  "retention",
+  "memory",
+  "topic",
+  "planner",
+  "audio",
+  "searxng",
+  "webReader",
+  "dynamicDelay",
+] as const;
+
+const OVERRIDABLE_BOOLEAN_FIELDS = [
+  "enableMarkdownScreenshot",
+  "enableMediaRecognition",
+] as const;
+
+/**
+ * 把每个群的覆盖配置浅合并到全局配置上
+ * - 子对象（如 emoji）只覆盖其中存在的字段，未填字段继承全局
+ * - 顶层布尔字段（enableMarkdownScreenshot 等）若覆盖中存在则整体替换
+ * - 缺失字段、格式异常的覆盖会被静默忽略
+ */
+export function mergeGroupOverrides(
+  base: ChatConfig,
+  overrides: ChatGroupOverrides | undefined | null,
+): ChatConfig {
+  if (!overrides || typeof overrides !== "object") return base;
+  if (typeof base !== "object" || base === null) return base;
+
+  const result: ChatConfig = { ...base };
+  const resultMap = result as unknown as Record<string, unknown>;
+  const overridesMap = overrides as Record<string, unknown>;
+
+  for (const key of OVERRIDABLE_SUB_OBJECTS) {
+    const overrideSub = overridesMap[key];
+    if (overrideSub && typeof overrideSub === "object") {
+      const baseSub = (base as unknown as Record<string, unknown>)[key];
+      if (baseSub && typeof baseSub === "object") {
+        resultMap[key] = {
+          ...(baseSub as Record<string, unknown>),
+          ...(overrideSub as Record<string, unknown>),
+        };
+      }
+    }
+  }
+
+  for (const key of OVERRIDABLE_BOOLEAN_FIELDS) {
+    const value = overridesMap[key];
+    if (typeof value === "boolean") {
+      resultMap[key] = value;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * 从 sessionId（如 "group:123"）提取群号，个人会话返回 undefined
+ */
+export function extractGroupIdFromSession(sessionId: string): number | undefined {
+  if (!sessionId || typeof sessionId !== "string") return undefined;
+  if (!sessionId.startsWith("group:")) return undefined;
+  const raw = sessionId.slice("group:".length);
+  const parsed = parseInt(raw, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}

package/utils/message.ts

@@ -14,7 +14,10 @@ import {
   type HistoryMediaProcessingOptions,
   type MediaMessageSegment,
 } from "../core/media/history-media";
-import { getImageTag } from "../core/media/image-analyzer";
+import {
+  calculateImageHash,
+  normalizeImageUrl,
+} from "../core/media/image-analyzer";
 
 const HISTORY_MEDIA_CONCURRENCY = 8;
 
@@ -217,11 +220,14 @@ interface HistoryFormatContext {
   db:
     | {
         getImageByUrl?(url: string): ImageRecord | null;
+        getImageByHash?(hash: string): ImageRecord | null;
+        saveImage?(image: ImageRecord): void;
       }
     | undefined;
   historyMediaOptions: HistoryMediaProcessingOptions;
   botUin: number;
   memberNameCache: Map<string, string>;
+  hashLookupCache: Map<string, string | null>;
 }
 
 async function resolveMemberName(
@@ -286,7 +292,7 @@ function buildReplyAnnotation(source: any, ctx: HistoryFormatContext): string |
   if (sourceUserId == null && !sourceText && !sourceNickname) return null;
 
   const idStr = sourceId != null ? String(sourceId) : "?";
-  let displayName = sourceNickname;
+  let displayName: string | undefined;
   if (sourceUserId != null) {
     displayName = ctx.memberNameCache.get(String(sourceUserId)) || String(sourceUserId);
   }
@@ -296,6 +302,49 @@ function buildReplyAnnotation(source: any, ctx: HistoryFormatContext): string |
   return `↪ reply to #${idStr} ${displayName}: "${text}"`;
 }
 
+async function getImageTagWithHashCache(
+  imageUrl: string,
+  db: NonNullable<HistoryFormatContext["db"]>,
+  ctx: HistoryFormatContext,
+): Promise<string> {
+  const exact = db.getImageByUrl?.(imageUrl);
+  if (exact) return `[${exact.type}:${exact.description}]`;
+
+  const normalized = normalizeImageUrl(imageUrl);
+  if (normalized && normalized !== imageUrl) {
+    const hit = db.getImageByUrl?.(normalized);
+    if (hit) return `[${hit.type}:${hit.description}]`;
+  }
+
+  let hash = ctx.hashLookupCache.get(`hash:${imageUrl}`);
+  if (hash === undefined) {
+    hash = (await calculateImageHash(imageUrl)) || null;
+    ctx.hashLookupCache.set(`hash:${imageUrl}`, hash);
+  }
+  if (!hash) return "[image]";
+
+  const byHash = db.getImageByHash?.(hash);
+  if (byHash) {
+    try {
+      db.saveImage?.({
+        hash: byHash.hash,
+        url: normalized || imageUrl,
+        type: byHash.type,
+        description: byHash.description,
+        emotion: byHash.emotion,
+        character: byHash.character,
+        filePath: byHash.filePath,
+        createdAt: byHash.createdAt,
+      });
+    } catch {
+      // best-effort URL caching for next call
+    }
+    return `[${byHash.type}:${byHash.description}]`;
+  }
+
+  return "[image]";
+}
+
 async function formatHistoryMessage(
   msg: any,
   ctx: HistoryFormatContext,
@@ -359,15 +408,30 @@ async function buildMessageContent(
   if (atContent) parts.push(atContent);
   if (textContent) parts.push(textContent);
 
-  for (const imageSeg of msg.message.filter((seg: any) => seg.type === "image")) {
-    const imageUrl = imageSeg.url || imageSeg.data?.url;
-    if (imageUrl) {
-      parts.push(
-        db?.getImageByUrl
-          ? getImageTag(String(imageUrl), db as any)
-          : "[image]",
-      );
-    }
+  const imageSegments = msg.message.filter((seg: any) => seg.type === "image");
+  if (imageSegments.length > 0 && db?.getImageByUrl) {
+    const imageTags = await Promise.all(
+      imageSegments.map(async (seg: any) => {
+        const imageUrl = seg.url || seg.data?.url;
+        if (!imageUrl) return "[image]";
+
+        const cached = ctx.hashLookupCache.get(imageUrl);
+        if (cached !== undefined) {
+          return cached;
+        }
+
+        const tag = await getImageTagWithHashCache(
+          String(imageUrl),
+          db as any,
+          ctx,
+        );
+        ctx.hashLookupCache.set(imageUrl, tag);
+        return tag;
+      }),
+    );
+    for (const tag of imageTags) parts.push(tag);
+  } else if (imageSegments.length > 0) {
+    for (const _ of imageSegments) parts.push("[image]");
   }
 
   for (const videoSeg of msg.message.filter(
@@ -393,7 +457,7 @@ async function buildMessageContent(
   }
 
   for (const cardSeg of msg.message.filter((seg: any) =>
-    ["xml", "json", "lightapp", "ark"].includes(cardSeg.type),
+    ["xml", "json", "lightapp", "ark"].includes(seg.type),
   )) {
     const cardData =
       cardSeg.data?.data || cardSeg.data?.xml || cardSeg.data || cardSeg.xml || "";
@@ -530,6 +594,7 @@ export async function getGroupHistory(
 
     const botUin = selfId;
     const memberNameCache = new Map<string, string>();
+    const hashLookupCache = new Map<string, string | null>();
 
     for (const m of messages) {
       const uid = m?.user_id;
@@ -544,6 +609,7 @@ export async function getGroupHistory(
       historyMediaOptions,
       botUin,
       memberNameCache,
+      hashLookupCache,
     };
 
     const formattedResults = await mapWithConcurrency(