chatccc 0.2.215 → 0.2.217

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chatccc",
-  "version": "0.2.215",
+  "version": "0.2.217",
   "description": "Feishu bot bridge for Claude Code",
   "license": "Apache-2.0",
   "type": "module",

package/src/__tests__/feishu-avatar.test.ts

@@ -2,7 +2,8 @@ import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import sharp from "sharp";
 
 const mockConfig = {
   cursor: {
@@ -68,14 +69,18 @@ function mockAvatarFetch(uploadedNames: string[], usageResponse: Response): void
   }));
 }
 
-function mockAvatarUploadOnlyFetch(uploadedNames: string[]): ReturnType<typeof vi.fn> {
-  const fetchMock = vi.fn(async (url: string | URL | Request, init?: RequestInit) => {
-    const urlText = String(url);
-    if (urlText === "https://open.feishu.test/im/v1/images") {
-      const form = init?.body as FormData;
-      const image = form.get("image") as File;
-      uploadedNames.push(image.name);
-      return new Response(JSON.stringify({ code: 0, data: { image_key: "img_test" } }), { status: 200 });
+function mockAvatarUploadOnlyFetch(
+  uploadedNames: string[],
+  uploadedImages: Buffer[] = [],
+): ReturnType<typeof vi.fn> {
+  const fetchMock = vi.fn(async (url: string | URL | Request, init?: RequestInit) => {
+    const urlText = String(url);
+    if (urlText === "https://open.feishu.test/im/v1/images") {
+      const form = init?.body as FormData;
+      const image = form.get("image") as File;
+      uploadedNames.push(image.name);
+      uploadedImages.push(Buffer.from(await image.arrayBuffer()));
+      return new Response(JSON.stringify({ code: 0, data: { image_key: "img_test" } }), { status: 200 });
     }
     if (urlText === "https://open.feishu.test/im/v1/chats/chat_1") {
       return new Response(JSON.stringify({ code: 0 }), { status: 200 });
@@ -197,7 +202,7 @@ describe("Codex avatar usage battery", () => {
     }
   });
 
-  it("uses provided Codex usage without fetching usage again", async () => {
+  it("uses provided Codex usage without fetching usage again", async () => {
     const homeDir = await mkdtemp(join(tmpdir(), "chatccc-avatar-home-"));
     const userDataDir = await mkdtemp(join(tmpdir(), "chatccc-avatar-data-"));
     const uploadedNames: string[] = [];
@@ -220,7 +225,65 @@ describe("Codex avatar usage battery", () => {
       await rm(homeDir, { recursive: true, force: true });
       await rm(userDataDir, { recursive: true, force: true });
     }
-  });
+  });
+
+  it("isolates Fast and standard Codex avatars in the upload cache", async () => {
+    const homeDir = await mkdtemp(join(tmpdir(), "chatccc-avatar-home-"));
+    const userDataDir = await mkdtemp(join(tmpdir(), "chatccc-avatar-data-"));
+    const uploadedNames: string[] = [];
+    mockAvatarUploadOnlyFetch(uploadedNames);
+
+    try {
+      const { setChatAvatar } = await loadFeishuApiWithHome(homeDir, userDataDir);
+      await setChatAvatar("tenant-token", "chat_1", "codex", "idle", {
+        codexUsage: null,
+        fastMode: false,
+      });
+      await setChatAvatar("tenant-token", "chat_1", "codex", "idle", {
+        codexUsage: null,
+        fastMode: true,
+      });
+
+      expect(uploadedNames).toEqual([
+        "avatar_codex_idle.jpg",
+        "avatar_codex_idle_fast.jpg",
+      ]);
+      const cacheRaw = await readFile(join(userDataDir, "state", "avatar-image-keys.json"), "utf-8");
+      const cache = JSON.parse(cacheRaw) as Record<string, string>;
+      expect(cache["codex:idle:plain"]).toBe("img_test");
+      expect(cache["codex:idle:plain:fast-champagne-frame-v1"]).toBe("img_test");
+    } finally {
+      await rm(homeDir, { recursive: true, force: true });
+      await rm(userDataDir, { recursive: true, force: true });
+    }
+  });
+
+  it("renders a thick champagne frame above the Codex badge in Fast mode", async () => {
+    const homeDir = await mkdtemp(join(tmpdir(), "chatccc-avatar-home-"));
+    const userDataDir = await mkdtemp(join(tmpdir(), "chatccc-avatar-data-"));
+    const uploadedNames: string[] = [];
+    const uploadedImages: Buffer[] = [];
+    mockAvatarUploadOnlyFetch(uploadedNames, uploadedImages);
+
+    try {
+      const { setChatAvatar } = await loadFeishuApiWithHome(homeDir, userDataDir);
+      await setChatAvatar("tenant-token", "chat_1", "codex", "idle", {
+        codexUsage: null,
+        fastMode: true,
+      });
+
+      expect(uploadedNames).toEqual(["avatar_codex_idle_fast.jpg"]);
+      const { data, info } = await sharp(uploadedImages[0]).raw().toBuffer({ resolveWithObject: true });
+      const pixelOffset = (149 * info.width + 200) * info.channels;
+      const [red, green, blue] = data.subarray(pixelOffset, pixelOffset + 3);
+      expect(red).toBeGreaterThan(220);
+      expect(green).toBeGreaterThan(150);
+      expect(blue).toBeLessThan(180);
+    } finally {
+      await rm(homeDir, { recursive: true, force: true });
+      await rm(userDataDir, { recursive: true, force: true });
+    }
+  });
 
   it("returns both usage windows and available reset credit expiries", async () => {
     const homeDir = await mkdtemp(join(tmpdir(), "chatccc-avatar-home-"));

package/src/__tests__/feishu-message-ingress.test.ts

@@ -0,0 +1,138 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+  FeishuMessageLedger,
+  createAckFirstEventHandler,
+} from "../feishu-message-ingress.ts";
+
+const tempDirs: string[] = [];
+
+async function createLedger(maxEntries = 5): Promise<FeishuMessageLedger> {
+  const dir = await mkdtemp(join(tmpdir(), "chatccc-feishu-ingress-"));
+  tempDirs.push(dir);
+  return new FeishuMessageLedger(join(dir, "messages.json"), maxEntries);
+}
+
+afterEach(async () => {
+  await Promise.all(tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+});
+
+describe("createAckFirstEventHandler", () => {
+  it("returns before starting the asynchronous event worker", async () => {
+    let scheduled: (() => void) | undefined;
+    const schedule = vi.fn((task: () => void) => {
+      scheduled = task;
+    });
+    const worker = vi.fn(async () => {});
+    const onError = vi.fn();
+    const handler = createAckFirstEventHandler(worker, onError, schedule);
+
+    await expect(handler({ message: "test" })).resolves.toBeUndefined();
+    expect(schedule).toHaveBeenCalledOnce();
+    expect(worker).not.toHaveBeenCalled();
+
+    scheduled?.();
+    await vi.waitFor(() => expect(worker).toHaveBeenCalledWith({ message: "test" }));
+    expect(onError).not.toHaveBeenCalled();
+  });
+
+  it("reports detached worker failures without rejecting the SDK callback", async () => {
+    const error = new Error("worker failed");
+    const onError = vi.fn();
+    const handler = createAckFirstEventHandler(
+      async () => {
+        throw error;
+      },
+      onError,
+      (task) => task(),
+    );
+
+    await expect(handler({})).resolves.toBeUndefined();
+    await vi.waitFor(() => expect(onError).toHaveBeenCalledWith(error));
+  });
+});
+
+describe("FeishuMessageLedger", () => {
+  it("rejects an already accepted message after a process restart", async () => {
+    const first = await createLedger();
+    await first.load();
+
+    expect(await first.accept({
+      messageId: "om_001",
+      chatId: "oc_chat",
+      createTime: 100,
+    })).toBe("accepted");
+
+    const restarted = new FeishuMessageLedger(first.filePath, 5);
+    await restarted.load();
+
+    expect(await restarted.accept({
+      messageId: "om_001",
+      chatId: "oc_chat",
+      createTime: 100,
+    })).toBe("duplicate");
+  });
+
+  it("rejects a unique old event after restoring the chat high-water mark", async () => {
+    const first = await createLedger();
+    await first.load();
+
+    expect(await first.accept({
+      messageId: "om_new",
+      chatId: "oc_chat",
+      createTime: 200,
+    })).toBe("accepted");
+
+    const restarted = new FeishuMessageLedger(first.filePath, 5);
+    await restarted.load();
+
+    expect(await restarted.accept({
+      messageId: "om_old",
+      chatId: "oc_chat",
+      createTime: 100,
+    })).toBe("stale");
+  });
+
+  it("accepts distinct messages with the same create timestamp", async () => {
+    const ledger = await createLedger();
+    await ledger.load();
+
+    expect(await ledger.accept({
+      messageId: "om_001",
+      chatId: "oc_chat",
+      createTime: 100,
+    })).toBe("accepted");
+    expect(await ledger.accept({
+      messageId: "om_002",
+      chatId: "oc_chat",
+      createTime: 100,
+    })).toBe("accepted");
+  });
+
+  it("keeps only the configured number of recent message IDs", async () => {
+    const ledger = await createLedger(2);
+    await ledger.load();
+
+    await ledger.accept({ messageId: "om_001", chatId: "oc_chat", createTime: 100 });
+    await ledger.accept({ messageId: "om_002", chatId: "oc_chat", createTime: 200 });
+    await ledger.accept({ messageId: "om_003", chatId: "oc_chat", createTime: 300 });
+
+    const restarted = new FeishuMessageLedger(ledger.filePath, 2);
+    await restarted.load();
+
+    expect(await restarted.accept({
+      messageId: "om_001",
+      chatId: "oc_other",
+      createTime: 100,
+    })).toBe("accepted");
+    expect(await restarted.accept({
+      messageId: "om_003",
+      chatId: "oc_chat",
+      createTime: 300,
+    })).toBe("duplicate");
+  });
+});

package/src/__tests__/orchestrator.test.ts

@@ -681,9 +681,21 @@ describe("handleCommand WeChat processing ack", () => {
 
     await handleCommand(platform, "/fast on", "feishu-codex", "ou-user", Date.now(), "p2p");
     expect(getEffectiveFastModeForTool("codex", "sid-codex-fast")).toBe(true);
+    expect(platform.setChatAvatar).toHaveBeenLastCalledWith(
+      "feishu-codex",
+      "codex",
+      "idle",
+      { fastMode: true },
+    );
 
     await handleCommand(platform, "/fast off", "feishu-codex", "ou-user", Date.now(), "p2p");
     expect(getEffectiveFastModeForTool("codex", "sid-codex-fast")).toBe(false);
+    expect(platform.setChatAvatar).toHaveBeenLastCalledWith(
+      "feishu-codex",
+      "codex",
+      "idle",
+      { fastMode: false },
+    );
     card = JSON.parse(
       vi.mocked(platform.sendRawCard).mock.calls.at(-1)?.[1] ?? "{}",
     ) as { elements?: Array<{ tag: string; text?: { content: string } }> };

package/src/__tests__/sim-platform.test.ts

@@ -73,9 +73,10 @@ describe("SimulatedPlatform", () => {
   });
 
   it("纯函数 formatDelayNotice 正常工作", () => {
-    const notice = SimulatedPlatform.formatDelayNotice(Date.now() - 20 * 60 * 1000, "测试消息");
-    expect(notice).toBeDefined();
-    expect(notice).toContain("延迟送达");
+    const notice = SimulatedPlatform.formatDelayNotice(Date.now() - 20 * 60 * 1000, "测试消息");
+    expect(notice).toBeDefined();
+    expect(notice).toContain("延迟送达");
+    expect(notice).not.toContain("因服务离线");
     // 近期消息不触发
     expect(SimulatedPlatform.formatDelayNotice(Date.now(), "test")).toBeNull();
   });

package/src/agent-delegate-task.ts

@@ -3,7 +3,13 @@ import { resolve } from "node:path";
 import { sessionPrefixForTool, toolDisplayName, ts } from "./config.ts";
 import { setDefaultCwd } from "./config.ts";
 import type { PlatformAdapter } from "./platform-adapter.ts";
-import { initClaudeSession, recordSessionRegistry, resumeAndPrompt, saveSessionTool } from "./session.ts";
+import {
+  getEffectiveFastModeForTool,
+  initClaudeSession,
+  recordSessionRegistry,
+  resumeAndPrompt,
+  saveSessionTool,
+} from "./session.ts";
 import { bindChatToSession } from "./session-chat-binding.ts";
 import { sessionChatName } from "./session-name.ts";
 
@@ -64,7 +70,11 @@ export async function delegateAgentTask(input: DelegateAgentTaskInput): Promise<
       `下面会自动把任务作为第一句话发送给 ${toolLabel}。`,
     "green",
   ).catch(() => {});
-  input.platform.setChatAvatar(chatId, input.tool, "new").catch(() => {});
+  const fastMode = getEffectiveFastModeForTool(input.tool, sessionId);
+  const avatarUpdate = fastMode
+    ? input.platform.setChatAvatar(chatId, input.tool, "new", { fastMode: true })
+    : input.platform.setChatAvatar(chatId, input.tool, "new");
+  avatarUpdate.catch(() => {});
 
   await resumeAndPrompt(
     sessionId,

package/src/feishu-api.ts

@@ -324,6 +324,7 @@ const AVATAR_BADGE_SIZE = 92;
 const AVATAR_BADGE_MARGIN = 10;
 const PLAIN_AVATAR_TOOL = "plain";
 const CODEX_AVATAR_USAGE_STYLE_VERSION = "usage-window-aware-v14";
+const CODEX_FAST_FRAME_STYLE_VERSION = "fast-champagne-frame-v1";
 const CURSOR_AVATAR_USAGE_STYLE_VERSION = "usage-battery-v1";
 
 export interface CodexUsageBalance {
@@ -371,18 +372,20 @@ function avatarCombinationPath(tool: string, status: string): string {
   return resolvePath(AVATAR_COMBINATIONS_DIR, `avatar_${normalizeAvatarTool(tool)}_${normalizeAvatarStatus(status)}.png`);
 }
 
-function avatarCacheKey(
-  tool: string,
-  status: string,
-  codexUsage: CodexUsageSummary | null = null,
-  cursorBatteryPercent: number | null = null,
-): string {
+function avatarCacheKey(
+  tool: string,
+  status: string,
+  codexUsage: CodexUsageSummary | null = null,
+  cursorBatteryPercent: number | null = null,
+  fastMode = false,
+): string {
   const normalizedTool = normalizeAvatarTool(tool);
   const normalizedStatus = normalizeAvatarStatus(status);
   if (normalizedTool === "codex") {
-    if (!codexUsage?.weekly) return `${normalizedTool}:${normalizedStatus}:plain`;
+    const fastKey = fastMode ? `:${CODEX_FAST_FRAME_STYLE_VERSION}` : "";
+    if (!codexUsage?.weekly) return `${normalizedTool}:${normalizedStatus}:plain${fastKey}`;
     const ringKey = codexUsage.fiveHour ? `:5h-ring:${codexUsage.fiveHour.remainingPercent}` : "";
-    return `${normalizedTool}:${normalizedStatus}:${CODEX_AVATAR_USAGE_STYLE_VERSION}:7d-battery:${codexUsage.weekly.remainingPercent}${ringKey}`;
+    return `${normalizedTool}:${normalizedStatus}:${CODEX_AVATAR_USAGE_STYLE_VERSION}:7d-battery:${codexUsage.weekly.remainingPercent}${ringKey}${fastKey}`;
   }
   if (normalizedTool === "cursor") {
     return cursorBatteryPercent !== null
@@ -757,7 +760,7 @@ function buildCodexUsageRingSvg(remainingPercent: number): Buffer {
 </svg>`);
 }
 
-async function buildAgentBadgeOverlay(tool: string): Promise<sharp.OverlayOptions> {
+async function buildAgentBadgeOverlay(tool: string): Promise<sharp.OverlayOptions> {
   const badge = await sharp(AVATAR_BADGES[tool])
     .resize(AVATAR_BADGE_SIZE, AVATAR_BADGE_SIZE, {
       fit: "contain",
@@ -770,24 +773,50 @@ async function buildAgentBadgeOverlay(tool: string): Promise<sharp.OverlayOption
     input: badge,
     left: AVATAR_SIZE - AVATAR_BADGE_SIZE - AVATAR_BADGE_MARGIN,
     top: AVATAR_SIZE - AVATAR_BADGE_SIZE - AVATAR_BADGE_MARGIN,
-  };
-}
-
-async function renderAvatar(
-  tool: string,
-  status: string,
-  codexUsage: CodexUsageSummary | null = null,
-  cursorBatteryPercent: number | null = null,
-): Promise<{ buffer: Buffer; contentType: string; filename: string }> {
+  };
+}
+
+function buildCodexFastFrameOverlay(): sharp.OverlayOptions {
+  const size = AVATAR_BADGE_SIZE + 16;
+  const innerOffset = 7;
+  const innerSize = size - innerOffset * 2;
+  const frame = Buffer.from(`
+<svg width="${size}" height="${size}" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="champagne" x1="0" y1="0" x2="${size}" y2="${size}" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#FFF0BE"/>
+      <stop offset="0.55" stop-color="#FFD56A"/>
+      <stop offset="1" stop-color="#EFA923"/>
+    </linearGradient>
+  </defs>
+  <rect x="0.5" y="0.5" width="${size - 1}" height="${size - 1}" rx="25" fill="url(#champagne)"/>
+  <rect x="${innerOffset}" y="${innerOffset}" width="${innerSize}" height="${innerSize}" rx="21" fill="#fffdf4"/>
+</svg>`);
+  return {
+    input: frame,
+    left: AVATAR_SIZE - size - 2,
+    top: AVATAR_SIZE - size - 2,
+  };
+}
+
+async function renderAvatar(
+  tool: string,
+  status: string,
+  codexUsage: CodexUsageSummary | null = null,
+  cursorBatteryPercent: number | null = null,
+  fastMode = false,
+): Promise<{ buffer: Buffer; contentType: string; filename: string }> {
   const normalizedTool = normalizeAvatarTool(tool);
   const normalizedStatus = normalizeAvatarStatus(status);
   const composites: sharp.OverlayOptions[] = [];
   const hasAgentBadge = normalizedTool !== PLAIN_AVATAR_TOOL;
+  const useFastCodexAvatar = normalizedTool === "codex" && fastMode;
 
   const codexWeeklyUsage = normalizedTool === "codex" ? codexUsage?.weekly ?? null : null;
   const useDynamicCodexAvatar = normalizedTool === "codex" && codexUsage !== null && codexWeeklyUsage !== null;
   const useDynamicCursorAvatar = normalizedTool === "cursor" && cursorBatteryPercent !== null;
-  const basePath = useDynamicCodexAvatar || useDynamicCursorAvatar
+  const useDynamicBadgeAvatar = useDynamicCodexAvatar || useDynamicCursorAvatar || useFastCodexAvatar;
+  const basePath = useDynamicBadgeAvatar
     ? AVATAR_SOURCES[normalizedStatus]
     : hasAgentBadge
       ? avatarCombinationPath(normalizedTool, normalizedStatus)
@@ -797,16 +826,15 @@ async function renderAvatar(
     if (codexUsage.fiveHour) {
       composites.push({ input: buildCodexUsageRingSvg(codexUsage.fiveHour.remainingPercent), left: 0, top: 0 });
     }
-    composites.push(
-      { input: buildCodexUsageBatterySvg(codexWeeklyUsage.remainingPercent), left: 0, top: 0 },
-      await buildAgentBadgeOverlay(normalizedTool),
-    );
-  } else if (useDynamicCursorAvatar) {
-    composites.push(
-      { input: buildCodexUsageBatterySvg(cursorBatteryPercent), left: 0, top: 0 },
-      await buildAgentBadgeOverlay(normalizedTool),
-    );
-  }
+    composites.push({ input: buildCodexUsageBatterySvg(codexWeeklyUsage.remainingPercent), left: 0, top: 0 });
+  } else if (useDynamicCursorAvatar) {
+    composites.push({ input: buildCodexUsageBatterySvg(cursorBatteryPercent), left: 0, top: 0 });
+  }
+
+  if (useDynamicBadgeAvatar) {
+    if (useFastCodexAvatar) composites.push(buildCodexFastFrameOverlay());
+    composites.push(await buildAgentBadgeOverlay(normalizedTool));
+  }
 
   let pipeline = sharp(await readFile(basePath))
     .resize(AVATAR_SIZE, AVATAR_SIZE, { fit: "cover", position: "center" });
@@ -824,21 +852,22 @@ async function renderAvatar(
     buffer: jpeg,
     contentType: "image/jpeg",
     filename: normalizedTool === "codex" && codexUsage?.weekly
-      ? `avatar_${normalizedTool}_${normalizedStatus}_7d_${codexUsage.weekly.remainingPercent}${codexUsage.fiveHour ? `_5h_${codexUsage.fiveHour.remainingPercent}` : ""}.jpg`
+      ? `avatar_${normalizedTool}_${normalizedStatus}${useFastCodexAvatar ? "_fast" : ""}_7d_${codexUsage.weekly.remainingPercent}${codexUsage.fiveHour ? `_5h_${codexUsage.fiveHour.remainingPercent}` : ""}.jpg`
       : normalizedTool === "cursor" && cursorBatteryPercent !== null
         ? `avatar_${normalizedTool}_${normalizedStatus}_battery_${cursorBatteryPercent}.jpg`
-      : `avatar_${normalizedTool}_${normalizedStatus}.jpg`,
+      : `avatar_${normalizedTool}_${normalizedStatus}${useFastCodexAvatar ? "_fast" : ""}.jpg`,
   };
 }
 
-async function uploadImage(
-  token: string,
-  tool: string,
-  status: string,
-  codexUsage: CodexUsageSummary | null = null,
-  cursorBatteryPercent: number | null = null,
-): Promise<string> {
-  const image = await renderAvatar(tool, status, codexUsage, cursorBatteryPercent);
+async function uploadImage(
+  token: string,
+  tool: string,
+  status: string,
+  codexUsage: CodexUsageSummary | null = null,
+  cursorBatteryPercent: number | null = null,
+  fastMode = false,
+): Promise<string> {
+  const image = await renderAvatar(tool, status, codexUsage, cursorBatteryPercent, fastMode);
   const blob = new Blob([new Uint8Array(image.buffer)], { type: image.contentType });
   const form = new FormData();
   form.append("image_type", "avatar");
@@ -869,13 +898,14 @@ async function getOrUploadAvatarKey(
   const normalizedTool = normalizeAvatarTool(tool);
   const normalizedStatus = normalizeAvatarStatus(status);
   const codexUsage = normalizedTool === "codex" ? await resolveCodexAvatarUsage(usageHints.codexUsage) : null;
-  const cursorBatteryPercent = normalizedTool === "cursor"
-    ? await resolveCursorAvatarBatteryPercent(usageHints.cursorUsage)
-    : null;
-  const keyName = avatarCacheKey(normalizedTool, normalizedStatus, codexUsage, cursorBatteryPercent);
-  const cached = avatarKeyCache.get(keyName);
-  if (cached) return cached;
-  const key = await uploadImage(token, normalizedTool, normalizedStatus, codexUsage, cursorBatteryPercent);
+  const cursorBatteryPercent = normalizedTool === "cursor"
+    ? await resolveCursorAvatarBatteryPercent(usageHints.cursorUsage)
+    : null;
+  const fastMode = normalizedTool === "codex" && usageHints.fastMode === true;
+  const keyName = avatarCacheKey(normalizedTool, normalizedStatus, codexUsage, cursorBatteryPercent, fastMode);
+  const cached = avatarKeyCache.get(keyName);
+  if (cached) return cached;
+  const key = await uploadImage(token, normalizedTool, normalizedStatus, codexUsage, cursorBatteryPercent, fastMode);
   avatarKeyCache.set(keyName, key);
   await persistAvatarKeyCache().catch((err) => {
     console.error(`[${ts()}] [AVATAR] persist cache FAIL: ${(err as Error).message}`);
@@ -1023,7 +1053,7 @@ export function formatDelayNotice(createTimeMs: number, messageText?: string, no
   }
 
   const contentLine = messageText ? `\n> 原始内容：${messageText.slice(0, 200)}` : "";
-  return `> ⚠️ 延迟送达提醒：此消息于 ${sendTimeStr} 发送，因服务离线，延迟约 ${delayStr}后送达${contentLine}`;
+  return `> ⚠️ 延迟送达提醒：此消息于 ${sendTimeStr} 发送，现延迟约 ${delayStr}后送达${contentLine}`;
 }
 
 /**

package/src/feishu-message-ingress.ts

@@ -0,0 +1,195 @@
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+
+export const MAX_PROCESSED = 5000;
+
+export type FeishuMessageDisposition = "accepted" | "duplicate" | "stale";
+
+export interface FeishuMessageIdentity {
+  messageId?: string;
+  chatId: string;
+  createTime: number;
+}
+
+interface PersistedMessageEntry {
+  messageId: string;
+  chatId: string;
+  createTime: number;
+}
+
+interface PersistedMessageLedger {
+  version: 1;
+  entries: PersistedMessageEntry[];
+}
+
+type ScheduleTask = (task: () => void) => void;
+
+const defaultSchedule: ScheduleTask = (task) => {
+  setImmediate(task);
+};
+
+/**
+ * The Feishu SDK waits for an event handler's return value before sending its
+ * WebSocket response. Schedule the real work for the next event-loop turn so
+ * the SDK callback can return and acknowledge the event immediately.
+ */
+export function createAckFirstEventHandler<T>(
+  worker: (data: T) => Promise<void>,
+  onError: (error: unknown) => void,
+  schedule: ScheduleTask = defaultSchedule,
+): (data: T) => Promise<void> {
+  return async (data) => {
+    schedule(() => {
+      void worker(data).catch(onError);
+    });
+  };
+}
+
+function isPersistedEntry(value: unknown): value is PersistedMessageEntry {
+  if (!value || typeof value !== "object") return false;
+  const entry = value as Record<string, unknown>;
+  return typeof entry.messageId === "string"
+    && entry.messageId.length > 0
+    && typeof entry.chatId === "string"
+    && typeof entry.createTime === "number"
+    && Number.isFinite(entry.createTime);
+}
+
+export class FeishuMessageLedger {
+  private readonly messageIds: Set<string>;
+  private entries: PersistedMessageEntry[] = [];
+  private latestCreateTimeByChat = new Map<string, number>();
+  private persistTail: Promise<void> = Promise.resolve();
+
+  constructor(
+    public readonly filePath: string,
+    private readonly maxEntries = MAX_PROCESSED,
+    messageIds?: Set<string>,
+  ) {
+    this.messageIds = messageIds ?? new Set<string>();
+  }
+
+  async load(): Promise<void> {
+    this.clearMemory();
+
+    try {
+      const raw = await readFile(this.filePath, "utf-8");
+      const parsed = JSON.parse(raw) as Partial<PersistedMessageLedger>;
+      const entries = Array.isArray(parsed.entries)
+        ? parsed.entries.filter(isPersistedEntry)
+        : [];
+      this.entries = entries.slice(-this.maxEntries);
+      this.rebuildIndexes();
+
+      if (entries.length > this.maxEntries) {
+        await this.persist();
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+        console.error(
+          `[FEISHU-DEDUP] Failed to load ${this.filePath}: ${(error as Error).message}`,
+        );
+      }
+    }
+  }
+
+  async accept(identity: FeishuMessageIdentity): Promise<FeishuMessageDisposition> {
+    const { messageId, chatId, createTime } = identity;
+
+    if (messageId && this.messageIds.has(messageId)) {
+      return "duplicate";
+    }
+
+    const latestCreateTime = this.latestCreateTimeByChat.get(chatId);
+    if (latestCreateTime !== undefined && createTime < latestCreateTime) {
+      return "stale";
+    }
+
+    if (!messageId) {
+      this.recordLatestCreateTime(chatId, createTime);
+      return "accepted";
+    }
+
+    this.entries.push({ messageId, chatId, createTime });
+    this.messageIds.add(messageId);
+    this.recordLatestCreateTime(chatId, createTime);
+
+    if (this.entries.length > this.maxEntries) {
+      this.entries = this.entries.slice(-this.maxEntries);
+      this.rebuildIndexes();
+    }
+
+    try {
+      await this.persist();
+    } catch (error) {
+      console.error(
+        `[FEISHU-DEDUP] Failed to persist ${this.filePath}: ${(error as Error).message}`,
+      );
+    }
+    return "accepted";
+  }
+
+  clearMemory(): void {
+    this.entries = [];
+    this.messageIds.clear();
+    this.latestCreateTimeByChat.clear();
+    this.persistTail = Promise.resolve();
+  }
+
+  private recordLatestCreateTime(chatId: string, createTime: number): void {
+    const current = this.latestCreateTimeByChat.get(chatId);
+    if (current === undefined || createTime > current) {
+      this.latestCreateTimeByChat.set(chatId, createTime);
+    }
+  }
+
+  private rebuildIndexes(): void {
+    this.messageIds.clear();
+    this.latestCreateTimeByChat.clear();
+    for (const entry of this.entries) {
+      this.messageIds.add(entry.messageId);
+      this.recordLatestCreateTime(entry.chatId, entry.createTime);
+    }
+  }
+
+  private persist(): Promise<void> {
+    const snapshot: PersistedMessageLedger = {
+      version: 1,
+      entries: this.entries.map((entry) => ({ ...entry })),
+    };
+
+    const nextPersist = this.persistTail
+      .catch(() => {})
+      .then(async () => {
+        await mkdir(dirname(this.filePath), { recursive: true });
+        const tempPath = `${this.filePath}.${process.pid}.tmp`;
+        try {
+          await writeFile(tempPath, JSON.stringify(snapshot), "utf-8");
+          await rename(tempPath, this.filePath);
+        } finally {
+          await rm(tempPath, { force: true }).catch(() => {});
+        }
+      });
+    this.persistTail = nextPersist;
+    return nextPersist;
+  }
+}
+
+const defaultLedgerPath = join(
+  homedir(),
+  ".chatccc",
+  "state",
+  "feishu-message-ledger.json",
+);
+
+export const processedMessages = new Set<string>();
+export const feishuMessageLedger = new FeishuMessageLedger(
+  defaultLedgerPath,
+  MAX_PROCESSED,
+  processedMessages,
+);
+
+export function clearFeishuMessageLedgerMemory(): void {
+  feishuMessageLedger.clearMemory();
+}

package/src/index.ts

@@ -96,11 +96,9 @@ import {
   sendCardKitMessage,
   updateCardKitCard,
 } from "./cardkit.ts";
-import {
-  MAX_PROCESSED,
-  loadSessionRegistryForBinding,
-  processedMessages,
-  rebuildBindingsFromRegistry,
+import {
+  loadSessionRegistryForBinding,
+  rebuildBindingsFromRegistry,
   resetState,
   setSessionPlatform,
   startUnifiedDisplayLoop,
@@ -115,7 +113,11 @@ import { handleCommand, type PlatformAdapter } from "./orchestrator.ts";
 import { createWechatAdapter, startWechatPlatform } from "./wechat-platform.ts";
 import { handleCodexResetCardAction } from "./codex-reset-actions.ts";
 import { resolveFeishuCardActionChatType } from "./card-action-routing.ts";
-import { reloadRuntimeConfig } from "./runtime-reload.ts";
+import { reloadRuntimeConfig } from "./runtime-reload.ts";
+import {
+  createAckFirstEventHandler,
+  feishuMessageLedger,
+} from "./feishu-message-ingress.ts";
 
 // ---------------------------------------------------------------------------
 // Feishu 平台适配器
@@ -262,12 +264,105 @@ function parseCardAction(data: unknown): CardActionResult | null {
 // WebSocket relay broadcast
 // ---------------------------------------------------------------------------
 
-let broadcastToRelay: (data: unknown) => void = () => {};
-const wechatSignal = { stopped: false };
-
-// ---------------------------------------------------------------------------
-// Simulate mode: inject message via HTTP
-// ---------------------------------------------------------------------------
+let broadcastToRelay: (data: unknown) => void = () => {};
+const wechatSignal = { stopped: false };
+
+async function processFeishuMessageEvent(data: Evt): Promise<void> {
+  const traceId = makeTraceId();
+  try {
+    broadcastToRelay(data);
+
+    const event = getInnerEvent(data);
+    const message = event.message;
+    if (!message) return;
+
+    const messageId = message.message_id;
+    const chatId = message.chat_id ?? "";
+    const chatType = message.chat_type ?? "group";
+    const msgTimestamp = parseInt(message.create_time ?? "0", 10) || Date.now();
+    const disposition = await feishuMessageLedger.accept({
+      messageId,
+      chatId,
+      createTime: msgTimestamp,
+    });
+
+    if (disposition === "duplicate") {
+      console.log(`[MSG] Duplicate message ignored: ${messageId ?? "(missing id)"}`);
+      return;
+    }
+    if (disposition === "stale") {
+      logTrace(traceId, "DONE", {
+        outcome: "skip_stale_feishu_message",
+        messageId,
+        chatId,
+        msgTimestamp,
+      });
+      console.log(
+        `[${ts()}] [SKIP] Stale Feishu message ignored: messageId=${messageId ?? "(missing id)"} chatId=${chatId} createTime=${msgTimestamp}`,
+      );
+      return;
+    }
+
+    const text = await formatMessageContent(message);
+    const openId = event.sender?.sender_id?.open_id ?? "";
+
+    console.log(
+      `[MSG] id=${messageId ?? "(missing)"} sender=${openId} chat=${chatId} type=${chatType} text="${text}"`,
+    );
+    appendChatLog(chatId, openId, text);
+
+    if (messageId) {
+      getTenantAccessToken().then((freshToken) =>
+        addReaction(freshToken, messageId).catch((err) =>
+          console.error(`[${ts()}] Reaction failed: ${(err as Error).message}`)
+        )
+      ).catch((err) =>
+        console.error(`[${ts()}] Reaction token failed: ${(err as Error).message}`)
+      );
+    }
+
+    if (!text) return;
+    logTrace(traceId, "RECV", {
+      messageId,
+      chatId,
+      chatType,
+      text: text.slice(0, 100),
+    });
+
+    const delayNotice = formatDelayNotice(msgTimestamp, text);
+    if (delayNotice) {
+      const delayToken = await getTenantAccessToken();
+      await sendCardReply(delayToken, chatId, "延迟送达", delayNotice, "yellow").catch(() => {});
+    }
+
+    await handleCommand(
+      feishuPlatform,
+      text,
+      chatId,
+      openId,
+      msgTimestamp,
+      chatType,
+      traceId,
+      buildUpdateCommandId("message", messageId),
+    );
+  } catch (err) {
+    logTrace(traceId, "ERROR", { message: (err as Error).message });
+    console.error(
+      `[${ts()}] [FATAL] im.message.receive_v1 worker crashed: ${(err as Error).message}`,
+    );
+  }
+}
+
+const handleFeishuMessageEventAckFirst = createAckFirstEventHandler(
+  processFeishuMessageEvent,
+  (err) => console.error(
+    `[${ts()}] [FATAL] Detached Feishu event worker failed: ${(err as Error).message}`,
+  ),
+);
+
+// ---------------------------------------------------------------------------
+// Simulate mode: inject message via HTTP
+// ---------------------------------------------------------------------------
 
 async function handleSimInjectMessage(req: IncomingMessage, res: ServerResponse): Promise<boolean> {
   const url = new URL(req.url ?? "/", "http://127.0.0.1");
@@ -399,74 +494,9 @@ async function startBotServiceCore(): Promise<void> {
 
   console.log(`[${ts()}] [AUTH] Token obtained`);
 
-  const eventDispatcher = new EventDispatcher({});
-  eventDispatcher.register({
-    "im.message.receive_v1": async (data: Evt) => {
-      const traceId = makeTraceId();
-      try {
-      broadcastToRelay(data);
-
-      const event = getInnerEvent(data);
-      const message = event.message;
-      if (!message) return;
-
-      const messageId = message.message_id;
-      if (messageId) {
-        if (processedMessages.has(messageId)) {
-          console.log(`[MSG] Duplicate message ignored: ${messageId}`);
-          return;
-        }
-        processedMessages.add(messageId);
-        if (processedMessages.size > MAX_PROCESSED) {
-          const it = processedMessages.values();
-          for (let i = 0; i < 1000; i++) processedMessages.delete(it.next().value as string);
-        }
-      }
-
-      const text = await formatMessageContent(message);
-      const sender = event.sender;
-      const openId = sender?.sender_id?.open_id ?? "";
-      const chatId = message.chat_id ?? "";
-      const chatType = message.chat_type ?? "group";
-
-      console.log(`[MSG] sender=${openId} chat=${chatId} type=${chatType} text="${text}"`);
-      appendChatLog(chatId, openId, text);
-
-      if (messageId) {
-        getTenantAccessToken().then((freshToken) =>
-          addReaction(freshToken, messageId).catch((err) =>
-            console.error(`[${ts()}] Reaction failed: ${(err as Error).message}`)
-          )
-        ).catch((err) =>
-          console.error(`[${ts()}] Reaction token failed: ${(err as Error).message}`)
-        );
-      }
-
-      if (!text) return;
-      const msgTimestamp = parseInt(message.create_time ?? "0", 10) || Date.now();
-      logTrace(traceId, "RECV", { chatId, chatType, text: text.slice(0, 100) });
-      const delayNotice = formatDelayNotice(msgTimestamp, text);
-      if (delayNotice) {
-        const delayToken = await getTenantAccessToken();
-        await sendCardReply(delayToken, chatId, "延迟送达", delayNotice, "yellow").catch(() => {});
-      }
-      // 仅 `/update` 会使用这个稳定 ID 做跨重启幂等；其他命令仍沿用
-      // processedMessages 的进程内去重。
-      await handleCommand(
-        feishuPlatform,
-        text,
-        chatId,
-        openId,
-        msgTimestamp,
-        chatType,
-        traceId,
-        buildUpdateCommandId("message", messageId),
-      );
-      } catch (err) {
-        logTrace(traceId, "ERROR", { message: (err as Error).message });
-        console.error(`[${ts()}] [FATAL] im.message.receive_v1 handler crashed: ${(err as Error).message}`);
-      }
-    },
+  const eventDispatcher = new EventDispatcher({});
+  eventDispatcher.register({
+    "im.message.receive_v1": handleFeishuMessageEventAckFirst,
 
     "card.action.trigger": async (data: Evt) => {
       try {
@@ -593,7 +623,8 @@ async function startBotServiceCore(): Promise<void> {
   } else {
     // 进程首次启动:此时所有 Map 都是空的,resetState 主要是打个 LOG 标识"开始
     // 干净状态"。修正残留的 running stream-state 并重建 session→chat 映射。
-    resetState();
+    resetState();
+    await feishuMessageLedger.load();
     startUnifiedDisplayLoop();
     fixStaleStreamStates().then(async () => {
       const registry = await loadSessionRegistryForBinding();

package/src/orchestrator.ts

@@ -340,6 +340,22 @@ function fastHelpAfterModel(tool: string): string {
     : "";
 }
 
+function setChatAvatarForSession(
+  platform: PlatformAdapter,
+  chatId: string,
+  tool: string,
+  status: string,
+  sessionId?: string,
+  usageHints?: ChatAvatarUsageHints,
+): Promise<void> {
+  const fastMode = getEffectiveFastModeForTool(tool, sessionId);
+  if (!usageHints && !fastMode) return platform.setChatAvatar(chatId, tool, status);
+  return platform.setChatAvatar(chatId, tool, status, {
+    ...usageHints,
+    ...(fastMode ? { fastMode: true } : {}),
+  });
+}
+
 async function sendFastModeStatus(
   platform: PlatformAdapter,
   chatId: string,
@@ -369,24 +385,26 @@ async function resolveUsageTarget(chatId: string): Promise<{ tool: "codex" | "cu
   }
 }
 
-function refreshUsageAvatar(
-  platform: PlatformAdapter,
-  chatId: string,
-  tool: "codex" | "cursor",
-  status: "busy" | "idle",
-  usageHints: ChatAvatarUsageHints,
-): void {
-  platform.setChatAvatar(chatId, tool, status, usageHints).catch((err) => {
+function refreshUsageAvatar(
+  platform: PlatformAdapter,
+  chatId: string,
+  tool: "codex" | "cursor",
+  status: "busy" | "idle",
+  usageHints: ChatAvatarUsageHints,
+  sessionId?: string,
+): void {
+  setChatAvatarForSession(platform, chatId, tool, status, sessionId, usageHints).catch((err) => {
     console.warn(`[${ts()}] [AVATAR] usage refresh failed: chatId=${chatId} tool=${tool} ${(err as Error).message}`);
   });
 }
 
-async function sendUsageSummary(
-  platform: PlatformAdapter,
-  chatId: string,
-  tool: "codex" | "cursor",
-  avatarStatus: "busy" | "idle" = "idle",
-): Promise<void> {
+async function sendUsageSummary(
+  platform: PlatformAdapter,
+  chatId: string,
+  tool: "codex" | "cursor",
+  avatarStatus: "busy" | "idle" = "idle",
+  sessionId?: string,
+): Promise<void> {
   if (tool === "cursor") {
     const usage = await getCursorUsageSummary();
     const content = formatCursorUsageSummary(usage);
@@ -395,7 +413,7 @@ async function sendUsageSummary(
     } else {
       await platform.sendCard(chatId, "Cursor Usage", content, "blue");
     }
-    refreshUsageAvatar(platform, chatId, tool, avatarStatus, { cursorUsage: usage });
+    refreshUsageAvatar(platform, chatId, tool, avatarStatus, { cursorUsage: usage }, sessionId);
     return;
   }
 
@@ -411,7 +429,7 @@ async function sendUsageSummary(
   } else {
     await platform.sendCard(chatId, "Codex Usage", content, "blue");
   }
-  refreshUsageAvatar(platform, chatId, tool, avatarStatus, { codexUsage: usage });
+  refreshUsageAvatar(platform, chatId, tool, avatarStatus, { codexUsage: usage }, sessionId);
 }
 
 async function sendUsageError(platform: PlatformAdapter, chatId: string, tool: "codex" | "cursor", err: unknown): Promise<void> {
@@ -585,7 +603,7 @@ async function resolveFeishuP2pAgent(
         `检测到默认 Agent 已变化：**${previousLabel} → ${desiredLabel}**。\n\n已创建新的空白 ${desiredLabel} 私聊会话，并从本条消息开始使用。`,
         "green",
       ).catch(() => {});
-      platform.setChatAvatar(chatId, desiredTool, "new").catch(() => {});
+      setChatAvatarForSession(platform, chatId, desiredTool, "new", init.sessionId).catch(() => {});
       return { kind: "ready", sessionId: init.sessionId, tool: desiredTool };
     } catch (err) {
       return {
@@ -817,7 +835,7 @@ export async function handleCommand(
     const avatarStatus = usageTarget.sessionId && isSessionRunning(usageTarget.sessionId) ? "busy" : "idle";
     logTrace(tid, "BRANCH", { cmd: "/usage", tool: usageTool });
     try {
-      await sendUsageSummary(platform, chatId, usageTool, avatarStatus);
+      await sendUsageSummary(platform, chatId, usageTool, avatarStatus, usageTarget.sessionId);
       logTrace(tid, "DONE", { outcome: "usage", tool: usageTool });
     } catch (err) {
       await sendUsageError(platform, chatId, usageTool, err);
@@ -1149,7 +1167,7 @@ export async function handleCommand(
       sessionId,
       tool,
     });
-    platform.setChatAvatar(newChatId, tool, "new").catch(() => {});
+    setChatAvatarForSession(platform, newChatId, tool, "new", sessionId).catch(() => {});
     console.log(`${"=".repeat(60)}`);
     return;
   }
@@ -1544,9 +1562,7 @@ export async function handleCommand(
         );
       }
 
-      platform
-        .setChatAvatar(chatId, descriptionTool, "new")
-        .catch(() => {});
+      setChatAvatarForSession(platform, chatId, descriptionTool, "new", newSessionId).catch(() => {});
 
       await platform.sendCard(
         chatId,
@@ -1716,7 +1732,7 @@ export async function handleCommand(
         );
       }
 
-      platform.setChatAvatar(chatId, target.tool, "new").catch(() => {});
+      setChatAvatarForSession(platform, chatId, target.tool, "new", target.sessionId).catch(() => {});
 
       const targetToolLabel = toolDisplayName(target.tool);
       const busyNote = isSessionRunning(target.sessionId)
@@ -1772,6 +1788,12 @@ export async function handleCommand(
       }
       const enabled = getEffectiveFastModeForTool("codex", sessionId);
       await sendFastModeStatus(platform, chatId, enabled).catch(() => {});
+      if (fastArg) {
+        const avatarStatus = isSessionRunning(sessionId) ? "busy" : "idle";
+        await platform.setChatAvatar(chatId, "codex", avatarStatus, { fastMode: enabled }).catch((err) => {
+          console.warn(`[${ts()}] [AVATAR] Fast mode refresh failed: chatId=${chatId} ${(err as Error).message}`);
+        });
+      }
       logTrace(tid, "DONE", {
         outcome: fastArg ? "fast_switched" : "fast_query",
         enabled,

package/src/platform-adapter.ts

@@ -8,10 +8,11 @@
 import type { CursorUsageSummary } from "./cursor-usage.ts";
 import type { CodexUsageSummary } from "./feishu-api.ts";
 
-export interface ChatAvatarUsageHints {
-  codexUsage?: CodexUsageSummary | null;
-  cursorUsage?: CursorUsageSummary | null;
-}
+export interface ChatAvatarUsageHints {
+  codexUsage?: CodexUsageSummary | null;
+  cursorUsage?: CursorUsageSummary | null;
+  fastMode?: boolean;
+}
 
 export interface PlatformAdapter {
   /** 平台标识，用于区分不同平台的行为（如 wechat、feishu 等） */
@@ -66,4 +67,4 @@ export interface PlatformAdapter {
 
   /** 更新已发送的进度展示，sequence 保证有序 */
   cardUpdate(cardId: string, cardJson: string, sequence: number): Promise<void>;
-}
+}

package/src/session.ts

@@ -42,6 +42,13 @@ import { resourceMonitor, registerProcess, unregisterProcess } from "./adapters/
 import { buildImSkillsPromptCached, exportSkillSubDocs, clearImSkillsPromptCache } from "./im-skills.ts";
 import type { PlatformAdapter } from "./platform-adapter.ts";
 import { hasResponseStalled, observeResponseProgress } from "./response-stall.ts";
+import {
+  MAX_PROCESSED,
+  clearFeishuMessageLedgerMemory,
+  processedMessages,
+} from "./feishu-message-ingress.ts";
+
+export { MAX_PROCESSED, processedMessages };
 
 // 微信显示循环压缩：头5 + ... + 尾5，避免在最后一步 sendText 中压缩指令回复
 function compressWechatDisplayText(text: string): string {
@@ -131,9 +138,6 @@ async function createVisibleProgressCard(
 // Shared state (imported by index.ts)
 // ---------------------------------------------------------------------------
 
-export const processedMessages = new Set<string>();
-export const MAX_PROCESSED = 5000;
-
 /** 每个 chatId 上一次已处理消息的时间戳，用于拦截延迟送达的旧消息 */
 export const lastMsgTimestamps = new Map<string, number>();
 
@@ -463,7 +467,7 @@ export function resetState(): void {
   }
   chatSessionMap.clear();
   sessionInfoMap.clear();
-  processedMessages.clear();
+  clearFeishuMessageLedgerMemory();
   lastMsgTimestamps.clear();
   chatPlatformMap.clear();
   for (const prompt of activePrompts.values()) {
@@ -534,6 +538,18 @@ export function getEffectiveFastModeForTool(tool: string, sessionId?: string): b
   }
   return config.codex.fastMode;
 }
+
+function setSessionChatAvatar(
+  platform: PlatformAdapter,
+  chatId: string,
+  tool: string,
+  status: string,
+  sessionId: string,
+): Promise<void> {
+  return getEffectiveFastModeForTool(tool, sessionId)
+    ? platform.setChatAvatar(chatId, tool, status, { fastMode: true })
+    : platform.setChatAvatar(chatId, tool, status);
+}
 
 /** 为指定 session 设置模型覆盖（/model <name>） */
 export function setSessionModelOverride(sessionId: string, model: string): void {
@@ -1286,7 +1302,7 @@ export async function runAgentSession(
         if (displayCards.get(displayChatId) !== display) {
           const finalStatus = turnFinalStatus(prevState.status);
           finalizeTurnCards(sessionId, prevState.turnCount, finalStatus).catch(() => {});
-          pp.setChatAvatar(displayChatId, prevState.tool, "idle").catch(() => {});
+          setSessionChatAvatar(pp, displayChatId, prevState.tool, "idle", sessionId).catch(() => {});
         } else {
           const nextSeq = display.sequence + 1;
           const { title: headerTitle, template: headerTemplate } = formatTerminalHeader(prevState.status);
@@ -1306,7 +1322,7 @@ export async function runAgentSession(
           if (prevTerminalReply && stillOursAfterUpdate && !isFinalReplySentForTurn(prevState)) {
             await sendFinalReplyTextOnce(pp, displayChatId, sessionId, prevState.turnCount, prevTerminalReply);
           }
-          pp.setChatAvatar(displayChatId, prevState.tool, "idle").catch(() => {});
+          setSessionChatAvatar(pp, displayChatId, prevState.tool, "idle", sessionId).catch(() => {});
         }
       } else if (pp && prevTerminalReply && !isFinalReplySentForTurn(prevState)) {
         // 无 display 记录但上一轮有 finalReply（极快轮次），至少发送
@@ -1371,7 +1387,7 @@ export async function runAgentSession(
   // 设置最后活跃群头像为 busy
   const activeCid = getLastActiveChat(sessionId) ?? getChatsForSession(sessionId)[0];
   if (activeCid) {
-    platform.setChatAvatar(activeCid, tool, "busy").catch(() => {});
+    setSessionChatAvatar(platform, activeCid, tool, "busy", sessionId).catch(() => {});
   }
 
   const state: AccumulatorState = {
@@ -1661,7 +1677,7 @@ export async function runAgentSession(
       const active1 = getLastActiveChat(sessionId) ?? finalizationChatIds[0];
       if (active1) {
         await platform.sendText(active1, "会话已停止。").catch(() => {});
-        platform.setChatAvatar(active1, tool, "idle").catch(() => {});
+        setSessionChatAvatar(platform, active1, tool, "idle", sessionId).catch(() => {});
       }
       console.log(`[${ts()}] Session ${sessionId} stopped (content chunks: ${state.chunkCount})`);
       if (tid) logTrace(tid, "SESSION_END", { sessionId, outcome: "stopped", chunks: state.chunkCount });
@@ -1691,7 +1707,7 @@ export async function runAgentSession(
             formatAutoEndedReply(finalReplyToWrite),
           );
         }
-        pp.setChatAvatar(activeAutoEnded, tool, "idle").catch(() => {});
+        setSessionChatAvatar(pp, activeAutoEnded, tool, "idle", sessionId).catch(() => {});
 
         if (wasAutoRecovery) {
           // 这是紧接第一次停滞而启动的恢复轮；再次发生相同停滞即终止
@@ -1726,7 +1742,7 @@ export async function runAgentSession(
         });
       }
       const activeErr = getLastActiveChat(sessionId) ?? finalizationChatIds[0];
-      if (activeErr) platform.setChatAvatar(activeErr, tool, "idle").catch(() => {});
+      if (activeErr) setSessionChatAvatar(platform, activeErr, tool, "idle", sessionId).catch(() => {});
       console.log(`[${ts()}] Session ${sessionId} process exited unexpectedly (content chunks: ${state.chunkCount})`);
       if (tid) logTrace(tid, "SESSION_END", { sessionId, outcome: "process_missing", chunks: state.chunkCount });
     } else {
@@ -1749,7 +1765,7 @@ export async function runAgentSession(
           const pp = platformForChat(active2) ?? platform;
           await sendFinalReplyTextOnce(pp, active2, sessionId, nextTurnCount, finalReply);
         }
-        platform.setChatAvatar(active2, tool, "idle").catch(() => {});
+        setSessionChatAvatar(platform, active2, tool, "idle", sessionId).catch(() => {});
       }
       console.log(`[${ts()}] Session ${sessionId} stream complete (content chunks: ${state.chunkCount})`);
       if (tid) logTrace(tid, "SESSION_END", { sessionId, chunks: state.chunkCount, finalTextLen: finalReply.length });
@@ -1992,7 +2008,7 @@ export function startUnifiedDisplayLoop(): void {
               finalizeTurnCards(sessionId, state.turnCount, finalSt).catch(() => {});
               displayCards.delete(chatId);
             }
-            p.setChatAvatar(chatId, state.tool, "idle").catch(() => {});
+            setSessionChatAvatar(p, chatId, state.tool, "idle", sessionId).catch(() => {});
             console.log(`[${ts()}] [DISPLAY] unified loop deleted display for ${chatId} (terminal: ${state.status})`);
           } else {
             // running: 创建或更新展示