From 700f3e4b069db57275de8c0acf467e4dcd508810 Mon Sep 17 00:00:00 2001
From: H3CoF6 <h3cof6@gmail.com>
Date: Sun, 2 Aug 2026 04:33:01 +0800
Subject: [PATCH 1/2] fix: sysEmoji fallback default database content

---
 .../src/views/cache/SysEmojiExplorer.tsx      |   1 +
 packages/db/tools/gen_sys_emoji_fallback.ts   | 128 ++++++++++++++++++
 .../service/src/account/sys_emoji_download.ts |  32 ++++-
 .../service/src/account/sys_emoji_fallback.ts |  92 +++++++++++++
 4 files changed, 250 insertions(+), 3 deletions(-)
 create mode 100644 packages/db/tools/gen_sys_emoji_fallback.ts
 create mode 100644 packages/service/src/account/sys_emoji_fallback.ts

diff --git a/apps/desktop/src/renderer/src/views/cache/SysEmojiExplorer.tsx b/apps/desktop/src/renderer/src/views/cache/SysEmojiExplorer.tsx
index 0aa672b..b6cb742 100644
--- a/apps/desktop/src/renderer/src/views/cache/SysEmojiExplorer.tsx
+++ b/apps/desktop/src/renderer/src/views/cache/SysEmojiExplorer.tsx
@@ -134,6 +134,7 @@ export function SysEmojiExplorer(): ReactElement {
         <span className="weq-cache-data-meta">
           {total ?? entries.length} 个 · 默认动图(APNG)预览，点击查看全部格式
           {status && !status.qqRoot ? ' · QQ 资源目录缺失，已改用下载补全' : ''}
+          {status?.usingFallback ? ' · emoji.db 无表情数据，用内置地址表兜底' : ''}
         </span>
         {missing > 0 ? (
           <button
diff --git a/packages/db/tools/gen_sys_emoji_fallback.ts b/packages/db/tools/gen_sys_emoji_fallback.ts
new file mode 100644
index 0000000..b3eaafb
--- /dev/null
+++ b/packages/db/tools/gen_sys_emoji_fallback.ts
@@ -0,0 +1,128 @@
+/**
+ * 生成 `packages/service/src/account/sys_emoji_fallback.ts` —— 内置表情资源地址的
+ * 兜底表，供 emoji.db 缺失 / `base_sys_emoji_table` 为空的环境使用。
+ *
+ * 需要一份有数据的 emoji.db（走 @weq/testkit 的 .env 配置）。腾讯更新内置表情后
+ * 可以重跑本脚本刷新兜底表。
+ *
+ * 用法:
+ *   pnpm tsx packages/db/tools/gen_sys_emoji_fallback.ts > packages/service/src/account/sys_emoji_fallback.ts
+ *   npx biome format --write packages/service/src/account/sys_emoji_fallback.ts
+ */
+import { loadNative } from '@weq/native';
+import { QqDb } from '../src/qq_db';
+import { testEnv, qqDbPath } from '@weq/testkit';
+
+const KEY = testEnv.key;
+const P = qqDbPath('emoji.db');
+const RE =
+  /^(https:\/\/wa\.qq\.com\/qgif-web-permanent\/(?:test\/)?sysemoji\/v\d\/singleres)\/(.+)_adv_(\d+)\.zip$/;
+
+class Raw extends QqDb {
+  q(s: string) {
+    return this.query(s);
+  }
+}
+
+async function main() {
+  const { ntHelper } = loadNative();
+  const probe = await ntHelper.testDatabaseKey(P, KEY);
+  const db = new Raw(ntHelper, {
+    dbPath: P,
+    key: KEY,
+    algo: {
+      pageHmacAlgorithm: probe.pageHmacAlgorithm!,
+      kdfHmacAlgorithm: probe.kdfHmacAlgorithm!,
+    },
+  });
+
+  const rows = await db.q(
+    `SELECT "81211","81229","81230" FROM base_sys_emoji_table ORDER BY "81211"`,
+  );
+  db.close();
+
+  // prefix|ts → id[]，只收有 adv 包（能下载）的行。
+  const groups = new Map<string, string[]>();
+  for (const r of rows) {
+    const id = String(r[0] ?? '');
+    const base = String(r[1] ?? '');
+    const adv = String(r[2] ?? '').trim();
+    if (!id || !adv) continue;
+    const m = RE.exec(adv);
+    if (!m || m[2] !== id) throw new Error(`unexpected adv url for ${id}: ${adv}`);
+    const [, prefix, , ts] = m;
+    if (base !== `${prefix}/${id}_base_${ts}.zip`) {
+      throw new Error(`base/adv mismatch for ${id}: ${base}`);
+    }
+    const key = `${prefix}|${ts}`;
+    const list = groups.get(key);
+    if (list) list.push(id);
+    else groups.set(key, [id]);
+  }
+
+  const sorted = [...groups.entries()].sort((a, b) => b[1].length - a[1].length);
+  const total = sorted.reduce((n, [, ids]) => n + ids.length, 0);
+
+  const lines = sorted.map(([key, ids]) => {
+    const [prefix, ts] = key.split('|');
+    ids.sort((a, b) => (Number(a) || 0) - (Number(b) || 0) || a.localeCompare(b));
+    return `  ['${prefix}', '${ts}', '${ids.join(',')}'],`;
+  });
+
+  process.stdout.write(`/**
+ * 内置表情资源地址的兜底表 —— 当 \`emoji.db\` 的 \`base_sys_emoji_table\` 读不到内容时使用。
+ *
+ * 这张表**不是**为了替代数据库，而是残缺环境的最后退路。已知的两种残缺:
+ *   - emoji.db 整个不存在（只拿到一份解密库的静态账号）；
+ *   - **表在但 0 行** —— QQ 尚未同步过内置表情，实测发生在从没登录过桌面端的环境。
+ *     此时 QQ 自己的 EmojiSystermResource 目录多半也不存在，两头皆空。
+ *
+ * 数据来自一份真实的 emoji.db（生成脚本 \`packages/db/tools/gen_sys_emoji_fallback.ts\`）。
+ * 腾讯会更新这张表（新表情、资源改版会换时间戳），所以**数据库永远优先**，这里只在
+ * 库读不到时兜底 —— 表情少几个、或某个表情停在旧版本，都好过一个都渲染不出来。
+ *
+ * URL 完全由 (前缀, id, 时间戳) 决定，且同一 id 的 _base/_adv 共用一组:
+ *   <prefix>/<id>_base_<ts>.zip   静态 png
+ *   <prefix>/<id>_adv_<ts>.zip    apng + lottie
+ * 所以按 (前缀, 时间戳) 分组存 id 列表最省 —— ${total} 个表情压进 ${sorted.length} 组。
+ * 只收有 adv 包的表情；Unicode 字符表情（😊 那批）没有资源包，按字符渲染。
+ */
+
+/** [前缀, 时间戳, 逗号分隔的 id 列表] */
+const GROUPS: ReadonlyArray<readonly [string, string, string]> = [
+${lines.join('\n')}
+];
+
+/** 一个表情的两个资源包地址。 */
+export interface FallbackSysEmojiUrls {
+  staticUrl: string;
+  apngUrl: string;
+}
+
+/** id → 资源包地址。首次调用时展开，之后复用。 */
+let cached: Map<string, FallbackSysEmojiUrls> | null = null;
+
+/**
+ * 兜底的「id → 资源包地址」表。调用方在数据库读不到内容时用它顶上。
+ */
+export function fallbackSysEmojiUrls(): Map<string, FallbackSysEmojiUrls> {
+  if (cached) return cached;
+  const out = new Map<string, FallbackSysEmojiUrls>();
+  for (const [prefix, ts, ids] of GROUPS) {
+    for (const id of ids.split(',')) {
+      out.set(id, {
+        staticUrl: \`\${prefix}/\${id}_base_\${ts}.zip\`,
+        apngUrl: \`\${prefix}/\${id}_adv_\${ts}.zip\`,
+      });
+    }
+  }
+  cached = out;
+  return out;
+}
+`);
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});
diff --git a/packages/service/src/account/sys_emoji_download.ts b/packages/service/src/account/sys_emoji_download.ts
index 5df5f5d..d4fe40f 100644
--- a/packages/service/src/account/sys_emoji_download.ts
+++ b/packages/service/src/account/sys_emoji_download.ts
@@ -20,6 +20,10 @@
  *
  * URL 里的时间戳每个表情不同（多数 1712825561，但 148/55 是 1719222678，443 更
  * 走 `test/sysemoji/v2/` 另一条路径），**必须从库里读，不能拼**。
+ *
+ * 库读不到时退到 `sys_emoji_fallback.ts` 的硬编码表。这不是可选的锦上添花：实测
+ * 存在 `base_sys_emoji_table` **表在但 0 行**的环境（QQ 从没在该机器上同步过内置
+ * 表情），此时 QQ 的资源目录同样是空的 —— 两头皆空，没有兜底就一个表情都渲染不出。
  */
 
 import { existsSync } from 'node:fs';
@@ -29,6 +33,7 @@ import type { AccountSession } from '@weq/account';
 import type { Platform } from '@weq/platform';
 import { BaseSysEmojiDb } from '@weq/db';
 import { readZipEntries } from '../common/zip';
+import { fallbackSysEmojiUrls } from './sys_emoji_fallback';
 
 /** 一个内置表情的 CDN 资源包地址（来自 base_sys_emoji_table）。 */
 export interface SysEmojiSource {
@@ -65,6 +70,8 @@ export interface SysEmojiDownloadStatus {
   available: number;
   /** 其中已在本地（QQ 目录或镜像）的表情数。 */
   present: number;
+  /** 地址来自硬编码兜底表而非 emoji.db（库缺失或 base_sys_emoji_table 为空）。 */
+  usingFallback: boolean;
 }
 
 /** 资源包最大字节数——最大的动画包约 1MB，留足余量后拒绝异常响应。 */
@@ -89,6 +96,8 @@ export class SysEmojiDownloadService {
   private readonly inFlight = new Map<string, Promise<SysEmojiFetchOutcome>>();
   /** id → 上次失败时刻，用于冷却期内直接返回失败而不打网络。 */
   private readonly failedAt = new Map<string, number>();
+  /** 本次解析是否退到了硬编码兜底表（emoji.db 缺失或表为空）。 */
+  private fellBack = false;
 
   /**
    * @param cacheRoot 镜像根目录（`userConfig.cacheDir('sysemoji')` 之类）——
@@ -106,12 +115,19 @@ export class SysEmojiDownloadService {
   }
 
   /**
-   * 读 `base_sys_emoji_table`，得到 id → 资源包地址。缺库 / 解析失败返回空表
-   * （此时补全能力整体不可用，调用方按「没有源」处理）。
+   * id → 资源包地址。优先 `base_sys_emoji_table`（腾讯会更新它），库缺失 / 读失败
+   * / **表为空** 时退到硬编码兜底表。
    */
   async listSources(): Promise<Map<string, SysEmojiSource>> {
     if (!this.sources) {
-      this.sources = this.loadSources().catch(() => new Map<string, SysEmojiSource>());
+      this.sources = this.loadSources()
+        .catch(() => new Map<string, SysEmojiSource>())
+        .then((fromDb) => {
+          // 空表和读失败一样要兜底——实测存在表在但 0 行的环境。
+          if (fromDb.size > 0) return fromDb;
+          this.fellBack = true;
+          return fallbackSources();
+        });
     }
     return this.sources;
   }
@@ -215,6 +231,7 @@ export class SysEmojiDownloadService {
       cacheRoot: this.cacheRoot,
       available,
       present,
+      usingFallback: this.fellBack,
     };
   }
 
@@ -290,6 +307,15 @@ function isAllowedUrl(url: string): boolean {
   }
 }
 
+/** 硬编码兜底表展开成与数据库同形的 id → 地址。 */
+function fallbackSources(): Map<string, SysEmojiSource> {
+  const out = new Map<string, SysEmojiSource>();
+  for (const [id, urls] of fallbackSysEmojiUrls()) {
+    out.set(id, { id, staticUrl: urls.staticUrl, apngUrl: urls.apngUrl });
+  }
+  return out;
+}
+
 /**
  * 剥掉 zip 条目路径里与表情同名的首段（`358/apng/358.png` → `apng/358.png`）。
  * 首段不匹配时原样返回；目录条目（以 `/` 结尾）返回 null。
diff --git a/packages/service/src/account/sys_emoji_fallback.ts b/packages/service/src/account/sys_emoji_fallback.ts
new file mode 100644
index 0000000..c23cfbb
--- /dev/null
+++ b/packages/service/src/account/sys_emoji_fallback.ts
@@ -0,0 +1,92 @@
+/**
+ * 内置表情资源地址的兜底表 —— 当 `emoji.db` 的 `base_sys_emoji_table` 读不到内容时使用。
+ *
+ * 这张表**不是**为了替代数据库，而是残缺环境的最后退路。已知的两种残缺:
+ *   - emoji.db 整个不存在（只拿到一份解密库的静态账号）；
+ *   - **表在但 0 行** —— QQ 尚未同步过内置表情，实测发生在从没登录过桌面端的环境。
+ *     此时 QQ 自己的 EmojiSystermResource 目录多半也不存在，两头皆空。
+ *
+ * 数据来自一份真实的 emoji.db（生成脚本 `packages/db/tools/gen_sys_emoji_fallback.ts`）。
+ * 腾讯会更新这张表（新表情、资源改版会换时间戳），所以**数据库永远优先**，这里只在
+ * 库读不到时兜底 —— 表情少几个、或某个表情停在旧版本，都好过一个都渲染不出来。
+ *
+ * URL 完全由 (前缀, id, 时间戳) 决定，且同一 id 的 _base/_adv 共用一组:
+ *   <prefix>/<id>_base_<ts>.zip   静态 png
+ *   <prefix>/<id>_adv_<ts>.zip    apng + lottie
+ * 所以按 (前缀, 时间戳) 分组存 id 列表最省 —— 286 个表情压进 19 组。
+ * 只收有 adv 包的表情；Unicode 字符表情（😊 那批）没有资源包，按字符渲染。
+ */
+
+/** [前缀, 时间戳, 逗号分隔的 id 列表] */
+const GROUPS: ReadonlyArray<readonly [string, string, string]> = [
+  [
+    'https://wa.qq.com/qgif-web-permanent/sysemoji/v1/singleres',
+    '1712825561',
+    '0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,41,42,43,46,49,53,56,59,60,63,64,66,67,74,75,76,77,78,79,85,86,89,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,114,116,118,119,120,121,123,124,125,129,137,144,146,147,169,171,172,173,174,175,176,177,178,179,181,182,183,185,187,201,212,262,263,264,265,266,267,268,269,270,271,272,273,277,281,282,283,284,285,286,287,289,293,294,295,297,298,299,300,302,303,305,306,307,311,312,314,317,318,319,320,323,324,325,326,333,334,336,337,338,339,341,342,343,345,346,347,349,350,351,352,353,354,355,356,357,358,359,360,361,362,363,364,365,366,367,368,369,370,371,372,373,374,375,376,377,378,379,380,381,382,383,384,385,386,387,388,389,390,391,392,393,394,395,396,397,398,399,400,401,402,403,404,405,406,407,408,409,410,411,412,413',
+  ],
+  [
+    'https://wa.qq.com/qgif-web-permanent/sysemoji/v1/singleres',
+    '1755829391',
+    '450,451,452,453,454,455,456,457,458,459,460,461,462',
+  ],
+  [
+    'https://wa.qq.com/qgif-web-permanent/sysemoji/v1/singleres',
+    '1725334580',
+    '422,425,426,427,428',
+  ],
+  [
+    'https://wa.qq.com/qgif-web-permanent/sysemoji/v1/singleres',
+    '1770110858',
+    '464,466,468,469,470',
+  ],
+  [
+    'https://wa.qq.com/qgif-web-permanent/sysemoji/v1/singleres',
+    '1781494455',
+    '475,476,477,478,479',
+  ],
+  [
+    'https://wa.qq.com/qgif-web-permanent/sysemoji/v1/singleres',
+    '1782964748',
+    '480,481,482,483,484',
+  ],
+  ['https://wa.qq.com/qgif-web-permanent/sysemoji/v1/singleres', '1717502894', '415,416,417,418'],
+  ['https://wa.qq.com/qgif-web-permanent/sysemoji/v1/singleres', '1727061166', '419,420,421,423'],
+  ['https://wa.qq.com/qgif-web-permanent/sysemoji/v1/singleres', '1736835691', '429,430,432'],
+  ['https://wa.qq.com/qgif-web-permanent/sysemoji/v1/singleres', '1719222678', '55,148'],
+  ['https://wa.qq.com/qgif-web-permanent/sysemoji/v1/singleres', '1770110940', '463,467'],
+  ['https://wa.qq.com/qgif-web-permanent/sysemoji/v1/singleres', '1766043611', '332'],
+  ['https://wa.qq.com/qgif-web-permanent/sysemoji/v1/singleres', '1755499209', '344'],
+  ['https://wa.qq.com/qgif-web-permanent/sysemoji/v1/singleres', '1725960670', '424'],
+  ['https://wa.qq.com/qgif-web-permanent/sysemoji/v1/singleres', '1736838652', '431'],
+  ['https://wa.qq.com/qgif-web-permanent/test/sysemoji/v2/singleres', '1754032265', '443'],
+  ['https://wa.qq.com/qgif-web-permanent/sysemoji/v1/singleres', '1770260458', '465'],
+  ['https://wa.qq.com/qgif-web-permanent/sysemoji/v1/singleres', '1778739853', '472'],
+  ['https://wa.qq.com/qgif-web-permanent/sysemoji/v1/singleres', '1781239647', '474'],
+];
+
+/** 一个表情的两个资源包地址。 */
+export interface FallbackSysEmojiUrls {
+  staticUrl: string;
+  apngUrl: string;
+}
+
+/** id → 资源包地址。首次调用时展开，之后复用。 */
+let cached: Map<string, FallbackSysEmojiUrls> | null = null;
+
+/**
+ * 兜底的「id → 资源包地址」表。调用方在数据库读不到内容时用它顶上。
+ */
+export function fallbackSysEmojiUrls(): Map<string, FallbackSysEmojiUrls> {
+  if (cached) return cached;
+  const out = new Map<string, FallbackSysEmojiUrls>();
+  for (const [prefix, ts, ids] of GROUPS) {
+    for (const id of ids.split(',')) {
+      out.set(id, {
+        staticUrl: `${prefix}/${id}_base_${ts}.zip`,
+        apngUrl: `${prefix}/${id}_adv_${ts}.zip`,
+      });
+    }
+  }
+  cached = out;
+  return out;
+}

From 07718a12aa2b561df4e43c3e857f41ae9991b43a Mon Sep 17 00:00:00 2001
From: H3CoF6 <h3cof6@gmail.com>
Date: Sun, 2 Aug 2026 22:32:28 +0800
Subject: [PATCH 2/2] fix: avatar cache ttl error

---
 apps/desktop/src/main/avatar_protocol.ts      |  7 +-
 apps/desktop/src/main/context/app_context.ts  | 12 +++-
 apps/desktop/src/main/file_response.ts        | 31 ++++++++-
 .../src/main/ipc/routers/media_resource.ts    | 22 ++++++-
 apps/desktop/src/main/media_protocol.ts       | 17 ++++-
 .../desktop/src/renderer/src/styles/cache.css | 52 +++++++++++++++
 .../views/cache/MediaResourceExplorers.tsx    | 64 +++++++++++++++++--
 packages/platform/src/linux/index.ts          |  5 --
 packages/platform/src/types.ts                |  8 ---
 packages/platform/src/win32/index.ts          |  7 --
 .../service/src/bootstrap/avatar_cache.ts     | 57 +++++++++++------
 packages/service/src/bootstrap/user_config.ts |  1 -
 12 files changed, 228 insertions(+), 55 deletions(-)

diff --git a/apps/desktop/src/main/avatar_protocol.ts b/apps/desktop/src/main/avatar_protocol.ts
index c0f3272..07e821e 100644
--- a/apps/desktop/src/main/avatar_protocol.ts
+++ b/apps/desktop/src/main/avatar_protocol.ts
@@ -57,9 +57,10 @@ export async function handleAvatarRequest(request: Request): Promise<Response> {
       status: 200,
       headers: {
         'Content-Type': blob.contentType,
-        // Let the renderer / Chromium memory-cache it too; the on-disk cache
-        // is authoritative, this just avoids re-asking the protocol.
-        'Cache-Control': 'public, max-age=86400',
+        // Let the renderer / Chromium memory-cache it too; the on-disk cache is
+        // authoritative (and applies the TTL), so keep this short — a long
+        // max-age would outlive the disk entry and pin a stale avatar.
+        'Cache-Control': 'public, max-age=300',
       },
     });
   } catch {
diff --git a/apps/desktop/src/main/context/app_context.ts b/apps/desktop/src/main/context/app_context.ts
index a423f4c..2733501 100644
--- a/apps/desktop/src/main/context/app_context.ts
+++ b/apps/desktop/src/main/context/app_context.ts
@@ -488,6 +488,12 @@ export interface AppContext {
    * no account is open / QQ is offline / harvest failed.
    */
   refreshRkeysNow(): Promise<boolean>;
+  /**
+   * Transcribe a SILK file on disk with the globally selected model. Account
+   * independent (the model is a global setting), so callers that already have a
+   * path — e.g. the Ptt cache browser — can skip the message-lookup dance.
+   */
+  transcribeSilk(silkPath: string): Promise<{ ok: boolean; text?: string; error?: string }>;
 }
 
 let cached: AppContext | undefined;
@@ -529,6 +535,9 @@ export function initAppContext(): AppContext {
       refreshRkeysNow(): Promise<boolean> {
         return Promise.resolve(false);
       },
+      transcribeSilk(): Promise<{ ok: boolean; text?: string; error?: string }> {
+        return Promise.resolve({ ok: false, error: '原生组件未就绪' });
+      },
     };
     return cached;
   }
@@ -605,7 +614,7 @@ export function initAppContext(): AppContext {
     keys: new Win32KeyService(platform, stubHooks),
     userConfig,
     globalConfig: new GlobalConfigService(platform, userConfig),
-    avatarCache: new AvatarCacheService(platform, userConfig),
+    avatarCache: new AvatarCacheService(userConfig),
     linkPreview,
     agentLabConfig: new AgentLabConfigService(userConfig),
     voiceTranscribe: new VoiceTranscribeService(platform),
@@ -663,6 +672,7 @@ export function initAppContext(): AppContext {
     account: null,
     services: null,
     scheduler: null,
+    transcribeSilk,
     async setAccount(accountCtx: AccountContext, metadata: AccountConfigMetadata = {}): Promise<void> {
       logger.info('opening account session', {
         event: 'open-account-start',
diff --git a/apps/desktop/src/main/file_response.ts b/apps/desktop/src/main/file_response.ts
index 49c71f4..8726000 100644
--- a/apps/desktop/src/main/file_response.ts
+++ b/apps/desktop/src/main/file_response.ts
@@ -72,13 +72,26 @@ function parseRange(header: string | null, size: number): { start: number; end:
 /**
  * Stream `path` as a `Response`, honoring the request's `Range` header.
  * Returns 404 when the file is missing, 206 for a partial response.
+ *
+ * `revalidate` opts the file into `Last-Modified` + `Cache-Control: no-cache`,
+ * so Chromium re-asks with `If-Modified-Since` and we answer 304 when the file
+ * hasn't changed. Use it for paths whose NAME is stable but whose CONTENT is
+ * rewritten in place — QQ's `nt_data/avatar` files are keyed by a uid hash, so
+ * changing your avatar overwrites the same path and a plain `max-age` would
+ * pin the old picture in the renderer's cache until it expired.
  */
-export async function fileResponse(path: string, request?: Request): Promise<Response> {
+export async function fileResponse(
+  path: string,
+  request?: Request,
+  opts: { revalidate?: boolean } = {},
+): Promise<Response> {
   let size: number;
+  let mtimeMs: number;
   try {
     const st = await stat(path);
     if (!st.isFile()) return new Response('not a file', { status: 404 });
     size = st.size;
+    mtimeMs = st.mtimeMs;
   } catch {
     return new Response('not found', { status: 404 });
   }
@@ -86,6 +99,20 @@ export async function fileResponse(path: string, request?: Request): Promise<Res
   const type = mimeOf(path);
   const range = parseRange(request?.headers.get('range') ?? null, size);
 
+  // `Last-Modified` has one-second granularity, so compare at that resolution —
+  // otherwise a sub-second mtime always reads as "newer" and we never 304.
+  const lastModified = new Date(Math.floor(mtimeMs / 1000) * 1000);
+  const revalidateHeaders = opts.revalidate
+    ? { 'Last-Modified': lastModified.toUTCString(), 'Cache-Control': 'no-cache' }
+    : undefined;
+
+  if (revalidateHeaders && !range) {
+    const since = Date.parse(request?.headers.get('if-modified-since') ?? '');
+    if (Number.isFinite(since) && lastModified.getTime() <= since) {
+      return new Response(null, { status: 304, headers: revalidateHeaders });
+    }
+  }
+
   if (range) {
     const stream = createReadStream(path, { start: range.start, end: range.end });
     return new Response(Readable.toWeb(stream) as ReadableStream, {
@@ -95,6 +122,7 @@ export async function fileResponse(path: string, request?: Request): Promise<Res
         'Content-Length': String(range.end - range.start + 1),
         'Content-Range': `bytes ${range.start}-${range.end}/${size}`,
         'Accept-Ranges': 'bytes',
+        ...revalidateHeaders,
       },
     });
   }
@@ -106,6 +134,7 @@ export async function fileResponse(path: string, request?: Request): Promise<Res
       'Content-Type': type,
       'Content-Length': String(size),
       'Accept-Ranges': 'bytes',
+      ...revalidateHeaders,
     },
   });
 }
diff --git a/apps/desktop/src/main/ipc/routers/media_resource.ts b/apps/desktop/src/main/ipc/routers/media_resource.ts
index 4fd3eee..7caca09 100644
--- a/apps/desktop/src/main/ipc/routers/media_resource.ts
+++ b/apps/desktop/src/main/ipc/routers/media_resource.ts
@@ -5,7 +5,8 @@
  * listings. Thin tRPC skin over `MediaResourceService` (see `@weq/service`); all
  * scanning / merging lives there. Bytes are NOT returned here — the renderer
  * points `<img>`/`<video>` at `weq-media://localmedia`, resolved via the same
- * service. Read-only.
+ * service. Read-only apart from `transcribeVoice`, which runs the recognition
+ * engine on a cached clip (it writes nothing).
  */
 
 import { z } from 'zod';
@@ -66,4 +67,23 @@ export const mediaResourceRouter = router({
   analyzeTree: procedure.input(z.object({ key: treeKey })).query(({ input }) => {
     return requireServices().mediaResource.analyzeTree(input.key);
   }),
+
+  /**
+   * Transcribe one cached voice clip (语音 → 转文字). `rel` is the same Ptt-tree
+   * path the browser streams through `weq-media://localvoice`; the service
+   * re-validates it stays inside the tree. There's no message behind a cache
+   * entry, so unlike `account.transcribeVoice` nothing is written back — the
+   * text only lives in the browser's UI.
+   *
+   * Returns `{ success:false, error }` for every failure mode so the card can
+   * show a friendly message instead of throwing.
+   */
+  transcribeVoice: procedure
+    .input(z.object({ rel: z.string() }))
+    .mutation(async ({ input }): Promise<{ success: boolean; text?: string; error?: string }> => {
+      const silk = await requireServices().mediaResource.resolveFile('ptt', input.rel);
+      if (!silk) return { success: false, error: '语音文件不存在' };
+      const r = await getAppContext().transcribeSilk(silk);
+      return r.ok ? { success: true, text: r.text ?? '' } : { success: false, error: r.error };
+    }),
 });
diff --git a/apps/desktop/src/main/media_protocol.ts b/apps/desktop/src/main/media_protocol.ts
index 4ac448a..a119b87 100644
--- a/apps/desktop/src/main/media_protocol.ts
+++ b/apps/desktop/src/main/media_protocol.ts
@@ -110,11 +110,24 @@ function fileResponse(path: string): Promise<Response> {
   return streamFile(path, currentRequest.getStore());
 }
 
+/**
+ * Like {@link fileResponse} but asking the renderer to revalidate (304 on an
+ * unchanged mtime). For the local avatar cache: the file NAME is a uid hash, so
+ * QQ overwrites it in place when someone changes their picture — caching by
+ * max-age would keep showing the old one.
+ */
+function revalidatingFileResponse(path: string): Promise<Response> {
+  return streamFile(path, currentRequest.getStore(), { revalidate: true });
+}
+
 /**
  * CDN fallback for an avatar the local cache didn't have. Routes through the
  * shared {@link AvatarCacheService} disk cache (so the fetched bytes warm the
  * same cache the rest of the app reads), returning 404 on any failure so the
  * renderer shows its glyph.
+ *
+ * Short `max-age`: the disk cache is the real cache (and applies its own TTL),
+ * so a long browser cache would only delay a changed avatar from showing.
  */
 async function avatarFallbackResponse(src: string): Promise<Response> {
   if (!/^https?:\/\//i.test(src)) return notFound('avatar fallback needs http url');
@@ -124,7 +137,7 @@ async function avatarFallbackResponse(src: string): Promise<Response> {
     const blob = await cache.get(src);
     return new Response(new Uint8Array(blob.data), {
       status: 200,
-      headers: { 'Content-Type': blob.contentType, 'Cache-Control': 'public, max-age=86400' },
+      headers: { 'Content-Type': blob.contentType, 'Cache-Control': 'public, max-age=300' },
     });
   } catch {
     return notFound('avatar fallback failed');
@@ -394,7 +407,7 @@ export function handleMediaRequest(request: Request): Promise<Response> {
           if (hash) path = await services.avatarResource.resolveFile(scope, hash, variant);
           else if (uid) path = await services.avatarResource.resolveByUid(scope, uid, variant);
           else if (uin) path = await services.avatarResource.resolveByUin(scope, uin, variant);
-          if (path) return fileResponse(path);
+          if (path) return revalidatingFileResponse(path);
           // Local miss → CDN fallback (disk-cached by AvatarCacheService).
           if (fb) return avatarFallbackResponse(fb);
           return notFound('avatar not found');
diff --git a/apps/desktop/src/renderer/src/styles/cache.css b/apps/desktop/src/renderer/src/styles/cache.css
index a433432..99ccbbd 100644
--- a/apps/desktop/src/renderer/src/styles/cache.css
+++ b/apps/desktop/src/renderer/src/styles/cache.css
@@ -3946,6 +3946,58 @@ html[data-theme="dark"] .weq-filerow-name {
   font-variant-numeric: tabular-nums;
 }
 
+/* 转文字入口：常态低调，hover 卡片时点亮。 */
+.weq-voice-t9n-btn {
+  flex: none;
+  display: inline-flex;
+  align-items: center;
+  gap: 3px;
+  padding: 2px 7px;
+  border: 1px solid color-mix(in srgb, var(--weq-accent-effective) 30%, transparent);
+  border-radius: 999px;
+  color: var(--weq-accent-effective);
+  font-size: 10.5px;
+  line-height: 1.4;
+  white-space: nowrap;
+  cursor: pointer;
+  opacity: 0;
+  transition: opacity 120ms ease, background-color 120ms ease;
+}
+
+.weq-voice-card:hover .weq-voice-t9n-btn,
+.weq-voice-t9n-btn:focus-visible,
+.weq-voice-t9n-btn:disabled {
+  opacity: 1;
+}
+
+.weq-voice-t9n-btn:hover:not(:disabled) {
+  background: color-mix(in srgb, var(--weq-accent-effective) 12%, transparent);
+}
+
+.weq-voice-t9n-btn:disabled {
+  cursor: progress;
+  color: var(--weq-fg-muted);
+  border-color: color-mix(in srgb, var(--weq-fg-primary) 14%, transparent);
+}
+
+.weq-voice-t9n {
+  padding: 7px 10px;
+  border: 1px solid var(--weq-border-subtle);
+  border-radius: 10px;
+  background: color-mix(in srgb, var(--weq-accent-effective) 6%, transparent);
+  color: var(--weq-fg-secondary);
+  font-size: 12px;
+  line-height: 1.55;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.weq-voice-t9n.is-error {
+  border-color: color-mix(in srgb, #d94c4c 30%, transparent);
+  background: color-mix(in srgb, #d94c4c 8%, transparent);
+  color: #c0392b;
+}
+
 /* ══════════════════════════════════════════════════════════════════════════
  * 整体资源分析弹窗
  * ════════════════════════════════════════════════════════════════════════ */
diff --git a/apps/desktop/src/renderer/src/views/cache/MediaResourceExplorers.tsx b/apps/desktop/src/renderer/src/views/cache/MediaResourceExplorers.tsx
index 9a0c9ba..19a94aa 100644
--- a/apps/desktop/src/renderer/src/views/cache/MediaResourceExplorers.tsx
+++ b/apps/desktop/src/renderer/src/views/cache/MediaResourceExplorers.tsx
@@ -10,7 +10,8 @@
  *   - {@link VoiceExplorer}     — 语音 (Ptt): month-bucketed SILK clips, rendered
  *     as cards with a (simulated) waveform + duration + play/pause. Clicking
  *     decodes the SILK to WAV via `weq-media://localvoice` and plays it; only one
- *     clip plays at a time.
+ *     clip plays at a time. With a transcription model configured, each card also
+ *     offers 转文字.
  *
  * All share {@link useCursorPaged}, a cursor-based infinite-scroll loader (the
  * backend pages by bucket, so a cursor — not an offset — resumes the walk). All
@@ -19,9 +20,9 @@
  */
 
 import { useCallback, useEffect, useMemo, useRef, useState, type ReactElement } from 'react';
-import { RefreshCw, Play, Pause } from 'lucide-react';
+import { RefreshCw, Play, Pause, FileText, Loader2 } from 'lucide-react';
 import type { FlatMediaEntry, MonthMediaEntry, VoiceMediaEntry } from '@weq/service';
-import { client } from '../../trpc/client';
+import { client, trpc } from '../../trpc/client';
 import { localMediaUrl, localVoiceUrl } from '../../lib/resourceUrl';
 import { openLightbox } from '../../components/ImageLightbox';
 import { openVideoLightbox } from '../../components/VideoLightbox';
@@ -326,6 +327,13 @@ export function VoiceExplorer(): ReactElement {
   );
   const { entries, loading, error, done, sentinelRef } = useCursorPaged<VoiceMediaEntry>(fetchPage);
 
+  // 转文字 only shows when a transcription model is selected in the settings.
+  const settings = trpc.bootstrap.getSettings.useQuery(undefined, {
+    refetchOnWindowFocus: false,
+    staleTime: 60_000,
+  });
+  const canTranscribe = Boolean(settings.data?.voiceTranscribe.modelId);
+
   if (error && entries.length === 0) {
     return <div className="weq-cache-grid-state is-error">{error}</div>;
   }
@@ -343,7 +351,7 @@ export function VoiceExplorer(): ReactElement {
         </div>,
       );
     }
-    nodes.push(<VoiceCard key={entry.rel} entry={entry} />);
+    nodes.push(<VoiceCard key={entry.rel} entry={entry} canTranscribe={canTranscribe} />);
   }
 
   return (
@@ -360,14 +368,24 @@ export function VoiceExplorer(): ReactElement {
  * One voice clip: a simulated waveform + duration + play/pause. The SILK bytes
  * are decoded to WAV on demand (first play), and the real duration replaces the
  * byte-estimated one once the audio's metadata loads. Playback progress lights
- * up the waveform left-to-right.
+ * up the waveform left-to-right. With a transcription model configured, a
+ * 转文字 button runs the recognizer over the clip and shows the text below.
  */
-function VoiceCard({ entry }: { entry: VoiceMediaEntry }): ReactElement {
+function VoiceCard({
+  entry,
+  canTranscribe,
+}: {
+  entry: VoiceMediaEntry;
+  canTranscribe: boolean;
+}): ReactElement {
   const bars = useMemo(() => fakeWaveform(entry.hash), [entry.hash]);
   const audioRef = useRef<HTMLAudioElement | null>(null);
   const [playing, setPlaying] = useState(false);
   const [progress, setProgress] = useState(0);
   const [realDur, setRealDur] = useState<number | null>(null);
+  const transcribe = trpc.account.mediaResource.transcribeVoice.useMutation();
+  const [transcript, setTranscript] = useState<string | null>(null);
+  const [transcribeError, setTranscribeError] = useState<string | null>(null);
 
   // Stop + drop the audio if the card is recycled to a different clip.
   useEffect(() => {
@@ -413,8 +431,21 @@ function VoiceCard({ entry }: { entry: VoiceMediaEntry }): ReactElement {
     }
   };
 
+  const runTranscribe = (): void => {
+    if (transcribe.isLoading) return;
+    setTranscribeError(null);
+    transcribe
+      .mutateAsync({ rel: entry.rel })
+      .then((res) => {
+        if (res.success) setTranscript(res.text ?? '');
+        else setTranscribeError(res.error ?? '识别失败');
+      })
+      .catch((err) => setTranscribeError(err instanceof Error ? err.message : String(err)));
+  };
+
   const seconds = realDur ?? Math.min(60, Math.max(1, Math.round(entry.bytes / SILK_BYTES_PER_SEC)));
   const filled = Math.round(progress * bars.length);
+  const hasResult = transcript !== null || transcribeError !== null;
 
   return (
     <figure className="weq-voice-card" title={entry.name}>
@@ -443,8 +474,29 @@ function VoiceCard({ entry }: { entry: VoiceMediaEntry }): ReactElement {
       </button>
       <figcaption className="weq-voice-meta">
         <span className="weq-voice-hash">{entry.hash.slice(0, 8)}…</span>
+        {canTranscribe && !hasResult ? (
+          <button
+            type="button"
+            className="weq-voice-t9n-btn"
+            title="转文字"
+            onClick={runTranscribe}
+            disabled={transcribe.isLoading}
+          >
+            {transcribe.isLoading ? (
+              <Loader2 size={11} strokeWidth={2} className="weq-spin" aria-hidden />
+            ) : (
+              <FileText size={11} strokeWidth={2} aria-hidden />
+            )}
+            <span>{transcribe.isLoading ? '转写中' : '转文字'}</span>
+          </button>
+        ) : null}
         <span className="weq-voice-size">{fmtBytes(entry.bytes)}</span>
       </figcaption>
+      {hasResult ? (
+        <div className={`weq-voice-t9n${transcribeError ? ' is-error' : ''}`}>
+          {transcribeError ?? (transcript || '（未识别到语音内容）')}
+        </div>
+      ) : null}
     </figure>
   );
 }
diff --git a/packages/platform/src/linux/index.ts b/packages/platform/src/linux/index.ts
index 5211578..1dd7d1c 100644
--- a/packages/platform/src/linux/index.ts
+++ b/packages/platform/src/linux/index.ts
@@ -82,11 +82,6 @@ export function createLinuxPlatform(
       const base = xdg && xdg.length > 0 ? xdg : join(homedir(), '.config');
       return join(base, 'weq');
     },
-    avatarCacheDir: () => {
-      const xdg = process.env.XDG_CACHE_HOME;
-      const base = xdg && xdg.length > 0 ? xdg : join(homedir(), '.cache');
-      return join(base, 'weq', 'avatar');
-    },
     tencentFilesRoots: () => candidateQqRoots(home, override()),
     loginDbPath: () => findLoginDb(home, override()),
     accountDir: (u: string) => findAccountDir(uid(u), home, override()),
diff --git a/packages/platform/src/types.ts b/packages/platform/src/types.ts
index 347ece4..65fc196 100644
--- a/packages/platform/src/types.ts
+++ b/packages/platform/src/types.ts
@@ -23,14 +23,6 @@ export interface Platform {
    */
   appDataRoot(): string;
 
-  /**
-   * Default on-disk directory for the avatar cache. On Windows this is
-   * `%APPDATA%\weq\cache\avatar`. Per-OS so the cache lands in the platform's
-   * conventional location; the global config may override it. NOT guaranteed
-   * to exist — the cache service `mkdir -p`s before writing.
-   */
-  avatarCacheDir(): string;
-
   /**
    * Candidate roots that may contain `<uin>/nt_qq/...` directories. Resolved
    * synchronously from well-known locations on this OS — no I/O needed by
diff --git a/packages/platform/src/win32/index.ts b/packages/platform/src/win32/index.ts
index 2acea1e..8a03241 100644
--- a/packages/platform/src/win32/index.ts
+++ b/packages/platform/src/win32/index.ts
@@ -87,13 +87,6 @@ export function createWin32Platform(
       }
       return join(base, 'weq');
     },
-    avatarCacheDir: () => {
-      const base = process.env.APPDATA;
-      if (!base) {
-        throw new Error('%APPDATA% not set — cannot derive weq avatar cache dir on win32');
-      }
-      return join(base, 'weq', 'cache', 'avatar');
-    },
     tencentFilesRoots: () => candidateTencentFilesRoots(undefined, override()),
     loginDbPath: () => findLoginDb(undefined, override()),
     accountDir: (uin: string) => findAccountDir(uin, undefined, override()),
diff --git a/packages/service/src/bootstrap/avatar_cache.ts b/packages/service/src/bootstrap/avatar_cache.ts
index 76eb409..15dd64e 100644
--- a/packages/service/src/bootstrap/avatar_cache.ts
+++ b/packages/service/src/bootstrap/avatar_cache.ts
@@ -7,23 +7,19 @@
  * we
  *
  *   1. hash the URL → a stable filename under the cache dir,
- *   2. serve the cached bytes if present,
+ *   2. serve the cached bytes if present and not past {@link TTL_MS},
  *   3. otherwise fetch upstream once, persist, and return the bytes.
  *
  * Concurrent requests for the same URL share a single in-flight fetch (so a
  * screen that mounts 50 identical avatars hits the network once).
  *
- * Cache directory resolution (override wins, default never hard-coded here):
- *   `UserConfig.avatarCacheDir`  →  `platform.avatarCacheDir()`
- *
  * The transport (a custom protocol) lives in the desktop app; this service is
  * transport-agnostic and just deals in URLs → bytes.
  */
 
 import { createHash } from 'node:crypto';
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { readFile, stat, unlink, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import type { Platform } from '@weq/platform';
 import type { UserConfigService } from './user_config';
 
 /** Bytes + content type for one resolved avatar. */
@@ -65,19 +61,34 @@ function contentTypeForExt(ext: string): string {
   }
 }
 
+/**
+ * How long a cached avatar stays fresh. QQ's avatar URLs carry no version
+ * (`…/g?b=sdk&nk=<uin>&s=0` is the same string before and after the user
+ * changes their picture), so the sha1(url) key can never invalidate itself —
+ * without an expiry a changed avatar would show the old bytes forever. Seven
+ * days trades a weekly re-fetch per avatar for a bounded staleness window.
+ *
+ * The LOCAL `nt_data/avatar` path (see AvatarResourceService) deliberately has
+ * no TTL: its filename is derived from the uid, so QQ overwrites the same file
+ * in place and our next read already sees the new bytes.
+ */
+const TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
 export class AvatarCacheService {
   /** De-dupe concurrent fetches of the same upstream URL. */
   private readonly inFlight = new Map<string, Promise<AvatarBlob>>();
 
-  constructor(
-    private readonly platform: Platform,
-    private readonly userConfig: UserConfigService,
-  ) {}
+  constructor(private readonly userConfig: UserConfigService) {}
 
-  /** Effective cache directory: config override, else the platform default. */
+  /**
+   * Cache directory — the shared `<cacheBase>/avatar` that the 清理缓存 UI
+   * enumerates and wipes (`UserConfigService.clearCache`). It MUST be derived
+   * from `cacheBaseDir()` so a user-set cache-dir override moves both the
+   * writes and the cleanup; a separately-resolved path would leave the old
+   * directory growing forever while the UI reported 0 bytes.
+   */
   cacheDir(): string {
-    const override = this.userConfig.read().avatarCacheDir;
-    return override?.trim() ? override : this.platform.avatarCacheDir();
+    return this.userConfig.cacheDir('avatar');
   }
 
   /**
@@ -113,16 +124,24 @@ export class AvatarCacheService {
   }
 
   /**
-   * Return cached bytes for `url` if any extension variant exists on disk.
-   * Async (non-blocking) so dozens of concurrent avatar requests interleave on
-   * the main-process event loop instead of each one blocking it in turn — we
-   * just attempt each extension's read and treat a miss as ENOENT.
+   * Return cached bytes for `url` if any extension variant exists on disk and
+   * is still within {@link TTL_MS}. Async (non-blocking) so dozens of concurrent
+   * avatar requests interleave on the main-process event loop instead of each
+   * one blocking it in turn — we just attempt each extension's read and treat a
+   * miss as ENOENT. An expired file is deleted so the refetch below writes a
+   * clean entry (and a different extension can't shadow it).
    */
   private async readFromDisk(url: string): Promise<AvatarBlob | null> {
     const base = this.basePath(url);
     for (const ext of ['png', 'jpg', 'gif', 'webp']) {
+      const path = `${base}.${ext}`;
       try {
-        const data = await readFile(`${base}.${ext}`);
+        const st = await stat(path);
+        if (Date.now() - st.mtimeMs > TTL_MS) {
+          await unlink(path).catch(() => {});
+          continue;
+        }
+        const data = await readFile(path);
         return { data, contentType: contentTypeForExt(ext), fromCache: true };
       } catch {
         // Missing (ENOENT) or unreadable — try the next extension.
@@ -145,8 +164,6 @@ export class AvatarCacheService {
     }
 
     const ext = extFor(contentType, url);
-    const dir = this.cacheDir();
-    await mkdir(dir, { recursive: true });
     try {
       await writeFile(`${this.basePath(url)}.${ext}`, data);
     } catch {
diff --git a/packages/service/src/bootstrap/user_config.ts b/packages/service/src/bootstrap/user_config.ts
index 4038a68..452c8e7 100644
--- a/packages/service/src/bootstrap/user_config.ts
+++ b/packages/service/src/bootstrap/user_config.ts
@@ -231,7 +231,6 @@ export const DEFAULT_APP_SETTINGS: AppSettings = {
 export interface UserConfig {
   autoEnter?: AutoEnterTarget | null;
   tencentFilesRootOverride?: string | null;
-  avatarCacheDir?: string | null;
   settings?: DeepPartial<AppSettings>;
   cacheDirOverride?: string | null;
   welcomeAcknowledged?: boolean;