docs(readme): acknowledge PR #24 contributor and key acquisition improvements

Merge pull request #24 from H3CoF6/feat/wx-key
feat(wx-key)：support get db key and img key without other tools.
2026-06-18 15:54:08 +08:00 · 2026-02-09 11:38:21 +08:00 · 2026-02-09 11:32:42 +08:00 · 2026-02-09 03:35:04 +08:00 · 2026-02-09 03:33:08 +08:00 · 2026-02-09 03:30:24 +08:00
61 changed files with 6445 additions and 784 deletions
@@ -17,6 +17,7 @@ wheels/
 # Local config templates
 /wechat_db_config_template.json
 .ace-tool/
+pnpm-lock.yaml

 # Local dev repos and data
 /WxDatDecrypt/
@@ -5,7 +5,7 @@
 <div align="center">
    <h1>WeChatDataAnalysis - 微信数据库解密与分析工具</h1>
    <p>一个专门用于微信4.x版本数据库解密的工具（支持聊天记录实时更新）</p>
-    <p><b>特别致谢</b>：<a href="https://github.com/ycccccccy/echotrace">echotrace</a>（本项目大量功能参考其实现，提供了重要技术支持）</p>
+    <p><b>特别致谢</b>：<a href="https://github.com/ycccccccy/echotrace">echotrace</a>、<a href="https://github.com/hicccc77/WeFlow">WeFlow</a>（本项目大量功能参考其实现，提供了重要技术支持）</p>
    <img src="https://img.shields.io/github/v/tag/LifeArchiveProject/WeChatDataAnalysis" alt="Version" />
    <img src="https://img.shields.io/github/stars/LifeArchiveProject/WeChatDataAnalysis" alt="Stars" />
    <img src="https://gh-down-badges.linkof.link/LifeArchiveProject/WeChatDataAnalysis" alt="Downloads" />
@@ -66,7 +66,7 @@

 ## 年度总结

-年度总结现在支持 4 种不同风格（style1-4）。如果你对某个风格有更好的修改建议，或有新风格的点子，欢迎到 Issue 区反馈：https://github.com/LifeArchiveProject/WeChatDataAnalysis/issues
+年度总结现在支持 3 种不同风格（style1、style2、style3）。如果你对某个风格有更好的修改建议，或有新风格的点子，欢迎到 Issue 区反馈：https://github.com/LifeArchiveProject/WeChatDataAnalysis/issues

 > ⚠️ **提醒**：年度总结目前还不是最终版本，后续还会增加新总结或新风格。

@@ -82,12 +82,10 @@
    <td><img src="frontend/public/style2.png" alt="年度总结 Style 2" width="400"/></td>
  </tr>
  <tr>
-    <td align="center"><b>Style 3</b></td>
-    <td align="center"><b>Style 4</b></td>
+    <td align="center" colspan="2"><b>Style 3</b></td>
  </tr>
  <tr>
-    <td><img src="frontend/public/style3.png" alt="年度总结 Style 3" width="400"/></td>
-    <td><img src="frontend/public/style4.png" alt="年度总结 Style 4" width="400"/></td>
+    <td align="center" colspan="2"><img src="frontend/public/style3.png" alt="年度总结 Style 3" width="400"/></td>
  </tr>
 </table>

@@ -196,21 +194,33 @@ npm run dist
 1. **[echotrace](https://github.com/ycccccccy/echotrace)** - 微信数据解析/取证工具
   - 本项目大量功能参考并复用其实现思路，提供了重要技术支持

-2. **[wx_key](https://github.com/ycccccccy/wx_key)** - 微信数据库与图片密钥提取工具
+2. **[WeFlow](https://github.com/hicccc77/WeFlow)** - 微信数据分析工具
+   - 提供了重要的功能参考和技术支持
+
+3. **[wx_key](https://github.com/ycccccccy/wx_key)** - 微信数据库与图片密钥提取工具
   - 支持获取微信 4.x 数据库密钥与缓存图片密钥
   - 本项目推荐使用此工具获取密钥

-3. **[wechat-dump-rs](https://github.com/0xlane/wechat-dump-rs)** - Rust实现的微信数据库解密工具
+4. **[wechat-dump-rs](https://github.com/0xlane/wechat-dump-rs)** - Rust实现的微信数据库解密工具
   - 提供了SQLCipher 4.0解密的正确实现参考
   - 本项目的HMAC验证和页面处理逻辑基于此项目的实现

-4. **[oh-my-wechat](https://github.com/chclt/oh-my-wechat)** - 微信聊天记录查看工具
+5. **[oh-my-wechat](https://github.com/chclt/oh-my-wechat)** - 微信聊天记录查看工具
   - 提供了优秀的聊天记录界面设计参考
   - 本项目的聊天界面风格参考了此项目的实现

-5. **[vue3-wechat-tool](https://github.com/Ele-Cat/vue3-wechat-tool)** - 微信聊天记录工具（Vue3）
+6. **[vue3-wechat-tool](https://github.com/Ele-Cat/vue3-wechat-tool)** - 微信聊天记录工具（Vue3）
   - 提供了聊天记录展示与交互的实现参考

+7. **[wx-dat](https://github.com/waaaaashi/wx-dat)** - 微信图片密钥获取工具
+   - 实现真正的无头获取图片密钥，不再依赖扫描微信内存与点击朋友圈大图
+
+8. **PR #24 贡献者 [H3CoF6](https://github.com/H3CoF6)** - 微信密钥获取能力增强
+   - 无第三方工具依赖实现微信密钥获取能力
+   - 实现数据库密钥获取：实现形式参考 [wx_key](https://github.com/ycccccccy/wx_key) 项目，完成 Python 预编译 wheel 封装，详情见 [py_wx_key](https://github.com/H3CoF6/py_wx_key)
+   - 特征码不在 C++ 内硬编码，而由 Python 模块传入，减少 wheel 更新次数
+   - 实现真正的无头获取图片密钥，不再依赖扫描微信内存（以及点击朋友圈大图），感谢项目 [wx-dat](https://github.com/waaaaashi/wx-dat)
+
 ## Star History

 [![Star History Chart](https://api.star-history.com/svg?repos=LifeArchiveProject/WeChatDataAnalysis&type=Date)](https://www.star-history.com/#LifeArchiveProject/WeChatDataAnalysis&Date)
@@ -222,3 +232,4 @@ npm run dist
 ---

 **免责声明**: 本工具仅供学习研究使用，使用者需自行承担使用风险。开发者不对因使用本工具造成的任何损失负责。
+
@@ -1,12 +1,12 @@
 {
  "name": "wechat-data-analysis-desktop",
-  "version": "0.2.0",
+  "version": "0.2.1",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "wechat-data-analysis-desktop",
-      "version": "0.2.0",
+      "version": "0.2.1",
      "devDependencies": {
        "concurrently": "^9.2.1",
        "cross-env": "^10.1.0",
@@ -1,7 +1,7 @@
 {
  "name": "wechat-data-analysis-desktop",
  "private": true,
-  "version": "0.2.0",
+  "version": "0.2.1",
  "main": "src/main.cjs",
  "scripts": {
    "dev": "concurrently -k -s first \"cd ..\\\\frontend && npm run dev\" \"cross-env ELECTRON_START_URL=http://localhost:3000 electron .\"",
@@ -611,6 +611,25 @@ function registerWindowIpc() {
      return getCloseBehavior();
    }
  });
+
+  ipcMain.handle("dialog:chooseDirectory", async (_event, options) => {
+    try {
+      const result = await dialog.showOpenDialog({
+        title: String(options?.title || "选择文件夹"),
+        properties: ["openDirectory", "createDirectory"],
+      });
+      return {
+        canceled: !!result?.canceled,
+        filePaths: Array.isArray(result?.filePaths) ? result.filePaths : [],
+      };
+    } catch (err) {
+      logMain(`[main] dialog:chooseDirectory failed: ${err?.message || err}`);
+      return {
+        canceled: true,
+        filePaths: [],
+      };
+    }
+  });
 }

 async function main() {
@@ -11,4 +11,6 @@ contextBridge.exposeInMainWorld("wechatDesktop", {

  getCloseBehavior: () => ipcRenderer.invoke("app:getCloseBehavior"),
  setCloseBehavior: (behavior) => ipcRenderer.invoke("app:setCloseBehavior", String(behavior || "")),
+
+  chooseDirectory: (options = {}) => ipcRenderer.invoke("dialog:chooseDirectory", options),
 });
@@ -30,7 +30,7 @@ onBeforeUnmount(() => {
 })

 const route = useRoute()
-const isChatRoute = computed(() => route.path?.startsWith('/chat') || route.path?.startsWith('/sns'))
+const isChatRoute = computed(() => route.path?.startsWith('/chat') || route.path?.startsWith('/sns') || route.path?.startsWith('/contacts'))

 const rootClass = computed(() => {
  const base = 'bg-gradient-to-br from-green-50 via-emerald-50 to-green-100'
@@ -730,35 +730,39 @@
  }

  .header-btn {
-    @apply flex items-center gap-1.5 text-xs px-3 py-1.5 rounded-lg bg-white border border-gray-200 text-gray-700 transition-all duration-200 disabled:opacity-50 disabled:cursor-not-allowed;
+    @apply flex items-center gap-1.5 text-xs px-3 py-1.5 rounded-md bg-white border border-gray-200 text-gray-700 transition-all duration-150 disabled:opacity-50 disabled:cursor-not-allowed shadow-sm;
  }

  .header-btn:hover:not(:disabled) {
-    @apply bg-gray-50 border-gray-300;
+    @apply bg-gray-50 border-gray-300 shadow;
  }

  .header-btn:active:not(:disabled) {
-    @apply bg-gray-100;
+    @apply bg-gray-100 scale-95;
+  }
+
+  .header-btn svg {
+    @apply w-3.5 h-3.5;
  }

  .header-btn-icon {
-    @apply w-8 h-8 flex items-center justify-center rounded-lg bg-white border border-gray-200 text-gray-600 transition-all duration-200;
+    @apply w-8 h-8 flex items-center justify-center rounded-lg bg-transparent border border-transparent text-gray-600 transition-all duration-200 disabled:opacity-50 disabled:cursor-not-allowed;
  }

  .header-btn-icon:hover {
-    @apply bg-gray-50 border-gray-300 text-gray-800;
+    @apply bg-transparent border-transparent text-gray-800;
  }

  .header-btn-icon-active {
-    @apply bg-[#03C160]/10 border-[#03C160] text-[#03C160];
+    @apply bg-transparent border-transparent text-[#03C160];
  }

  .header-btn-icon-active:hover {
-    @apply bg-[#03C160]/15;
+    @apply bg-transparent;
  }

  .message-filter-select {
-    @apply text-xs px-2 py-1.5 rounded-lg bg-white border border-gray-200 text-gray-700 focus:outline-none focus:ring-2 focus:ring-[#03C160]/20 focus:border-[#03C160] transition-all disabled:opacity-50 disabled:cursor-not-allowed;
+    @apply text-xs px-2 py-1.5 rounded-lg bg-transparent border-0 text-gray-700 focus:outline-none focus:ring-0 transition-all disabled:opacity-50 disabled:cursor-not-allowed;
  }

  /* 搜索侧边栏样式 */
@@ -186,7 +186,7 @@
                暂无可展示的排行榜数据。
              </div>

-              <div v-else class="race-scroll mt-4 max-h-[26rem] overflow-auto pr-1">
+              <div v-else class="race-scroll mt-4 max-h-[26rem] overflow-y-auto overflow-x-hidden pr-1">
                <TransitionGroup
                  name="race"
                  tag="div"
@@ -258,8 +258,7 @@ const props = defineProps({

 const { theme } = useWrappedTheme()
 const isGameboy = computed(() => theme.value === 'gameboy')
-const isDos = computed(() => theme.value === 'dos')
-const isRetro = computed(() => isGameboy.value || isDos.value)
+const isRetro = computed(() => isGameboy.value)

 const nfInt = new Intl.NumberFormat('zh-CN', { maximumFractionDigits: 0 })
 const formatInt = (n) => nfInt.format(Math.round(Number(n) || 0))
@@ -756,6 +755,16 @@ onBeforeUnmount(() => {
  transition: transform 500ms cubic-bezier(0.22, 1, 0.36, 1) !important;
 }

+.race-scroll {
+  scrollbar-width: none;
+  -ms-overflow-style: none;
+}
+
+.race-scroll::-webkit-scrollbar {
+  width: 0;
+  height: 0;
+}
+
 .race-move {
  transition: transform 350ms cubic-bezier(0.22, 1, 0.36, 1) !important;
 }
@@ -0,0 +1,291 @@
+<template>
+  <div
+    ref="containerRef"
+    class="bits-card-swap absolute bottom-0 right-0 translate-x-[24%] translate-y-[-2%] origin-bottom-right overflow-visible [perspective:900px]"
+    :style="containerStyle"
+  >
+    <div
+      v-for="(_, index) in visibleCardCount"
+      :key="index"
+      ref="cardRefs"
+      class="bits-card-swap-item absolute top-1/2 left-1/2 rounded-xl [transform-style:preserve-3d] [will-change:transform] [backface-visibility:hidden]"
+      :style="cardStyle"
+      @click="onCardClick(index)"
+    >
+      <slot :name="`card-${index}`" :index="index" />
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { computed, nextTick, onMounted, onUnmounted, ref, watch } from 'vue'
+import gsap from 'gsap'
+
+const props = defineProps({
+  cardCount: { type: Number, default: 3 },
+  width: { type: [Number, String], default: 250 },
+  height: { type: [Number, String], default: 300 },
+  cardDistance: { type: Number, default: 24 },
+  verticalDistance: { type: Number, default: 34 },
+  delay: { type: Number, default: 4200 },
+  pauseOnHover: { type: Boolean, default: false },
+  onCardClick: { type: Function, default: null },
+  skewAmount: { type: Number, default: 4 },
+  easing: { type: String, default: 'elastic' }
+})
+
+const emit = defineEmits(['cardClick'])
+
+const containerRef = ref(null)
+const cardRefs = ref([])
+const order = ref([0, 1, 2])
+const timelineRef = ref(null)
+let intervalRef = null
+
+const toPx = (value) => (typeof value === 'number' ? `${value}px` : value)
+
+const containerStyle = computed(() => ({
+  width: toPx(props.width),
+  height: toPx(props.height)
+}))
+
+const cardStyle = computed(() => ({
+  width: toPx(props.width),
+  height: toPx(props.height)
+}))
+
+const visibleCardCount = computed(() => {
+  const count = Number(props.cardCount)
+  if (!Number.isFinite(count)) return 1
+  const normalized = Math.floor(count)
+  return Math.max(1, normalized)
+})
+
+const config = computed(() => {
+  if (props.easing === 'elastic') {
+    return {
+      ease: 'elastic.out(0.6,0.9)',
+      dropDuration: 1.8,
+      moveDuration: 1.8,
+      returnDuration: 1.8,
+      overlap: 0.85,
+      returnDelay: 0.08
+    }
+  }
+  return {
+    ease: 'power1.inOut',
+    dropDuration: 0.8,
+    moveDuration: 0.8,
+    returnDuration: 0.8,
+    overlap: 0.45,
+    returnDelay: 0.2
+  }
+})
+
+const makeSlot = (index, total) => ({
+  x: index * props.cardDistance,
+  y: -index * props.verticalDistance,
+  z: -index * props.cardDistance * 1.5,
+  zIndex: total - index
+})
+
+const placeNow = (element, slot) => {
+  gsap.set(element, {
+    x: slot.x,
+    y: slot.y,
+    z: slot.z,
+    xPercent: -50,
+    yPercent: -50,
+    skewY: props.skewAmount,
+    transformOrigin: 'center center',
+    zIndex: slot.zIndex,
+    force3D: true
+  })
+}
+
+const initializeCards = () => {
+  const list = cardRefs.value || []
+  if (!list.length) return
+  const total = visibleCardCount.value
+  list.forEach((element, index) => {
+    if (!element) return
+    placeNow(element, makeSlot(index, total))
+  })
+}
+
+const updateCardPositions = () => {
+  const list = cardRefs.value || []
+  if (!list.length) return
+  const total = visibleCardCount.value
+  list.forEach((element, index) => {
+    if (!element) return
+    const slot = makeSlot(index, total)
+    gsap.set(element, {
+      x: slot.x,
+      y: slot.y,
+      z: slot.z,
+      skewY: props.skewAmount
+    })
+  })
+}
+
+const runSwap = () => {
+  const total = visibleCardCount.value
+  if (order.value.length !== total) {
+    order.value = Array.from({ length: total }, (_, idx) => idx)
+  }
+  const activeOrder = order.value.slice(0, total)
+  if (activeOrder.length < 2) return
+  const [front, ...rest] = activeOrder
+  const frontElement = cardRefs.value[front]
+  if (!frontElement) return
+
+  const tl = gsap.timeline()
+  timelineRef.value = tl
+
+  tl.to(frontElement, {
+    y: '+=480',
+    duration: config.value.dropDuration,
+    ease: config.value.ease
+  })
+
+  tl.addLabel('promote', `-=${config.value.dropDuration * config.value.overlap}`)
+
+  rest.forEach((index, slotIndex) => {
+    const element = cardRefs.value[index]
+    if (!element) return
+    const slot = makeSlot(slotIndex, activeOrder.length)
+    tl.set(element, { zIndex: slot.zIndex }, 'promote')
+    tl.to(
+      element,
+      {
+        x: slot.x,
+        y: slot.y,
+        z: slot.z,
+        duration: config.value.moveDuration,
+        ease: config.value.ease
+      },
+      `promote+=${slotIndex * 0.15}`
+    )
+  })
+
+  const backSlot = makeSlot(activeOrder.length - 1, activeOrder.length)
+
+  tl.addLabel('return', `promote+=${config.value.moveDuration * config.value.returnDelay}`)
+  tl.call(() => {
+    gsap.set(frontElement, { zIndex: backSlot.zIndex })
+  }, undefined, 'return')
+  tl.set(frontElement, { x: backSlot.x, z: backSlot.z }, 'return')
+  tl.to(
+    frontElement,
+    {
+      y: backSlot.y,
+      duration: config.value.returnDuration,
+      ease: config.value.ease
+    },
+    'return'
+  )
+
+  tl.call(() => {
+    order.value = [...rest, front]
+  })
+}
+
+const stopAnimation = () => {
+  if (timelineRef.value) {
+    timelineRef.value.kill()
+    timelineRef.value = null
+  }
+  if (intervalRef) {
+    clearInterval(intervalRef)
+    intervalRef = null
+  }
+}
+
+const startAnimation = () => {
+  stopAnimation()
+  if (visibleCardCount.value < 2) {
+    initializeCards()
+    return
+  }
+  runSwap()
+  intervalRef = window.setInterval(runSwap, props.delay)
+}
+
+const resumeAnimation = () => {
+  timelineRef.value?.play()
+  if (!intervalRef) intervalRef = window.setInterval(runSwap, props.delay)
+}
+
+const onMouseEnter = () => {
+  stopAnimation()
+}
+
+const onMouseLeave = () => {
+  resumeAnimation()
+}
+
+const setupHoverListeners = () => {
+  if (!props.pauseOnHover || !containerRef.value) return
+  containerRef.value.addEventListener('mouseenter', onMouseEnter)
+  containerRef.value.addEventListener('mouseleave', onMouseLeave)
+}
+
+const removeHoverListeners = () => {
+  if (!containerRef.value) return
+  containerRef.value.removeEventListener('mouseenter', onMouseEnter)
+  containerRef.value.removeEventListener('mouseleave', onMouseLeave)
+}
+
+const onCardClick = (index) => {
+  emit('cardClick', index)
+  if (typeof props.onCardClick === 'function') props.onCardClick(index)
+}
+
+watch(
+  () => [props.cardDistance, props.verticalDistance, props.skewAmount],
+  () => {
+    updateCardPositions()
+  }
+)
+
+watch(
+  () => props.delay,
+  () => {
+    if (intervalRef) {
+      clearInterval(intervalRef)
+      intervalRef = window.setInterval(runSwap, props.delay)
+    }
+  }
+)
+
+watch(
+  () => props.pauseOnHover,
+  () => {
+    removeHoverListeners()
+    setupHoverListeners()
+  }
+)
+
+onMounted(async () => {
+  await nextTick()
+  initializeCards()
+  startAnimation()
+  setupHoverListeners()
+})
+
+watch(
+  () => visibleCardCount.value,
+  async () => {
+    order.value = Array.from({ length: visibleCardCount.value }, (_, idx) => idx)
+    await nextTick()
+    initializeCards()
+    startAnimation()
+  }
+)
+
+onUnmounted(() => {
+  stopAnimation()
+  removeHoverListeners()
+})
+</script>
@@ -0,0 +1,184 @@
+<template>
+  <div class="bits-grid-motion w-full h-full overflow-hidden">
+    <section class="relative flex h-full w-full items-center justify-center overflow-hidden" :style="sectionStyle">
+      <div class="bits-grid-motion-grid">
+        <div
+          v-for="rowIndex in safeRowCount"
+          :key="`row-${rowIndex}`"
+          class="bits-grid-motion-row"
+          :style="rowInlineStyle"
+        >
+          <div
+            v-for="columnIndex in renderColumnCount"
+            :key="`cell-${rowIndex}-${columnIndex}`"
+            class="bits-grid-motion-cell"
+            v-show="loopedItems[resolveIndex(rowIndex, columnIndex)]"
+          >
+            <slot
+              name="item"
+              :item="loopedItems[resolveIndex(rowIndex, columnIndex)]"
+              :index="resolveIndex(rowIndex, columnIndex)"
+            >
+              <div class="bits-grid-motion-fallback">
+                {{ String(loopedItems[resolveIndex(rowIndex, columnIndex)] ?? '') }}
+              </div>
+            </slot>
+          </div>
+        </div>
+      </div>
+
+      <div class="bits-grid-motion-mask" />
+    </section>
+  </div>
+</template>
+
+<script setup>
+import { computed, onMounted, onUnmounted, ref } from 'vue'
+import gsap from 'gsap'
+
+const props = defineProps({
+  items: { type: Array, default: () => [] },
+  gradientColor: { type: String, default: 'rgba(7, 193, 96, 0.2)' },
+  rowCount: { type: Number, default: 8 },
+  columnCount: { type: Number, default: 10 },
+  scrollSpeed: { type: Number, default: 38 },
+  baseOffsetX: { type: Number, default: 0 },
+  itemWidth: { type: Number, default: 300 },
+  rowGap: { type: Number, default: 12 }
+})
+
+let removeTicker = null
+let lastTickAt = 0
+let loopDistance = 0
+const marqueeX = ref(0)
+
+const safeRowCount = computed(() => Math.max(1, Number(props.rowCount) || 1))
+const safeColumnCount = computed(() => Math.max(1, Number(props.columnCount) || 1))
+const safeItemWidth = computed(() => Math.max(1, Number(props.itemWidth) || 1))
+const safeRowGap = computed(() => Math.max(0, Number(props.rowGap) || 0))
+const safeScrollSpeed = computed(() => Math.max(0, Number(props.scrollSpeed) || 0))
+
+const renderColumnCount = computed(() => safeColumnCount.value * 2)
+const totalSlots = computed(() => safeRowCount.value * renderColumnCount.value)
+
+const repeatedItems = computed(() => {
+  const source = Array.isArray(props.items) ? props.items.filter(Boolean) : []
+  if (!source.length) return []
+  const output = []
+  for (let idx = 0; idx < safeRowCount.value * safeColumnCount.value; idx += 1) {
+    output.push(source[idx % source.length])
+  }
+  return output
+})
+
+const loopedItems = computed(() => {
+  const base = repeatedItems.value
+  if (!base.length) return []
+  const output = []
+  for (let idx = 0; idx < totalSlots.value; idx += 1) {
+    output.push(base[idx % base.length])
+  }
+  return output
+})
+
+const rowInlineStyle = computed(() => ({
+  willChange: 'transform',
+  transform: `translate3d(${props.baseOffsetX + marqueeX.value}px, 0, 0)`
+}))
+
+const sectionStyle = computed(() => ({
+  background: `radial-gradient(circle at center, ${props.gradientColor} 0%, transparent 72%)`
+}))
+
+const resolveIndex = (rowIndex, columnIndex) => (
+  (Number(rowIndex) - 1) * renderColumnCount.value + (Number(columnIndex) - 1)
+)
+
+const updateMotion = () => {
+  if (typeof window === 'undefined') return
+
+  const now = typeof performance !== 'undefined' ? performance.now() : Date.now()
+  const dt = lastTickAt > 0 ? Math.min((now - lastTickAt) / 1000, 0.08) : 0
+  lastTickAt = now
+
+  if (loopDistance <= 0 || safeScrollSpeed.value <= 0 || dt <= 0) return
+
+  marqueeX.value -= safeScrollSpeed.value * dt
+  if (marqueeX.value <= -loopDistance) {
+    marqueeX.value += loopDistance
+  }
+}
+
+onMounted(() => {
+  if (typeof window === 'undefined') return
+
+  loopDistance = safeColumnCount.value * (safeItemWidth.value + safeRowGap.value)
+  marqueeX.value = 0
+  lastTickAt = 0
+
+  // Kick one frame immediately to avoid initial static delay.
+  marqueeX.value = -Math.min(loopDistance * 0.02, 8)
+
+  gsap.ticker.lagSmoothing(1000, 33)
+  removeTicker = gsap.ticker.add(updateMotion)
+})
+
+onUnmounted(() => {
+  loopDistance = 0
+  lastTickAt = 0
+  if (typeof removeTicker === 'function') removeTicker()
+})
+</script>
+
+<style scoped>
+.bits-grid-motion-grid {
+  position: relative;
+  z-index: 2;
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: 12px;
+  width: 180%;
+  height: 165%;
+  transform: rotate(-15deg);
+  transform-origin: center;
+}
+
+.bits-grid-motion-row {
+  display: flex;
+  gap: 12px;
+}
+
+.bits-grid-motion-cell {
+  position: relative;
+  height: 210px;
+  min-width: 300px;
+  flex-shrink: 0;
+}
+
+.bits-grid-motion-fallback {
+  height: 100%;
+  width: 100%;
+  border-radius: 12px;
+  border: 1px solid rgba(7, 193, 96, 0.2);
+  background: #ffffff;
+  color: rgba(0, 0, 0, 0.5);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 16px;
+  text-align: center;
+  font-size: 14px;
+}
+
+.bits-grid-motion-mask {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+  background:
+    linear-gradient(180deg, rgba(243, 255, 248, 0.78) 0%, rgba(243, 255, 248, 0.12) 20%, rgba(243, 255, 248, 0) 38%),
+    linear-gradient(90deg, rgba(243, 255, 248, 0.86) 0%, rgba(243, 255, 248, 0.12) 24%, rgba(243, 255, 248, 0) 44%),
+    linear-gradient(270deg, rgba(243, 255, 248, 0.9) 0%, rgba(243, 255, 248, 0.14) 30%, rgba(243, 255, 248, 0) 48%),
+    linear-gradient(0deg, rgba(243, 255, 248, 0.88) 0%, rgba(243, 255, 248, 0.16) 36%, rgba(243, 255, 248, 0) 58%);
+  z-index: 3;
+}
+</style>
@@ -0,0 +1,160 @@
+<template>
+  <p
+    ref="textRef"
+    class="bits-split-text inline-block overflow-hidden whitespace-normal"
+    :class="className"
+    :style="{ textAlign, wordWrap: 'break-word' }"
+  >
+    {{ text }}
+  </p>
+</template>
+
+<script setup>
+import { nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import { gsap } from 'gsap'
+import { ScrollTrigger } from 'gsap/ScrollTrigger'
+import { SplitText as GSAPSplitText } from 'gsap/SplitText'
+
+const props = defineProps({
+  text: { type: String, required: true },
+  className: { type: String, default: '' },
+  delay: { type: Number, default: 100 },
+  duration: { type: Number, default: 0.6 },
+  ease: { type: [String, Function], default: 'power3.out' },
+  splitType: { type: String, default: 'chars' },
+  from: { type: Object, default: () => ({ opacity: 0, y: 32 }) },
+  to: { type: Object, default: () => ({ opacity: 1, y: 0 }) },
+  threshold: { type: Number, default: 0.1 },
+  rootMargin: { type: String, default: '-100px' },
+  textAlign: { type: String, default: 'center' },
+  onLetterAnimationComplete: { type: Function, default: null }
+})
+
+const emit = defineEmits(['animationComplete'])
+
+gsap.registerPlugin(ScrollTrigger, GSAPSplitText)
+
+const textRef = ref(null)
+let timeline = null
+let scrollTrigger = null
+let splitter = null
+
+const cleanup = () => {
+  if (timeline) {
+    timeline.kill()
+    timeline = null
+  }
+  if (scrollTrigger) {
+    scrollTrigger.kill()
+    scrollTrigger = null
+  }
+  if (splitter) {
+    splitter.revert()
+    splitter = null
+  }
+}
+
+const createAnimation = async () => {
+  if (!import.meta.client || !textRef.value || !props.text) return
+  await nextTick()
+
+  const element = textRef.value
+  const absoluteLines = props.splitType === 'lines'
+  if (absoluteLines) element.style.position = 'relative'
+
+  try {
+    splitter = new GSAPSplitText(element, {
+      type: props.splitType,
+      absolute: absoluteLines,
+      linesClass: 'split-line'
+    })
+  } catch {
+    return
+  }
+
+  let targets = splitter.chars
+  if (props.splitType === 'words') targets = splitter.words
+  if (props.splitType === 'lines') targets = splitter.lines
+  if (!targets?.length) {
+    cleanup()
+    return
+  }
+
+  targets.forEach((target) => {
+    target.style.willChange = 'transform, opacity'
+  })
+
+  const startPercent = (1 - props.threshold) * 100
+  const marginMatch = /^(-?\d+(?:\.\d+)?)(px|em|rem|%)?$/.exec(props.rootMargin)
+  const marginValue = marginMatch ? Number.parseFloat(marginMatch[1]) : 0
+  const marginUnit = marginMatch ? marginMatch[2] || 'px' : 'px'
+  const sign = marginValue < 0
+    ? `-=${Math.abs(marginValue)}${marginUnit}`
+    : `+=${marginValue}${marginUnit}`
+
+  timeline = gsap.timeline({
+    scrollTrigger: {
+      trigger: element,
+      start: `top ${startPercent}%${sign}`,
+      toggleActions: 'play none none none',
+      once: true,
+      onToggle: (self) => {
+        scrollTrigger = self
+      }
+    },
+    onComplete: () => {
+      gsap.set(targets, {
+        ...props.to,
+        clearProps: 'willChange',
+        immediateRender: true
+      })
+      if (typeof props.onLetterAnimationComplete === 'function') {
+        props.onLetterAnimationComplete()
+      }
+      emit('animationComplete')
+    }
+  })
+
+  timeline.set(targets, {
+    ...props.from,
+    immediateRender: false,
+    force3D: true
+  })
+
+  timeline.to(targets, {
+    ...props.to,
+    duration: props.duration,
+    ease: props.ease,
+    stagger: props.delay / 1000,
+    force3D: true
+  })
+}
+
+watch(
+  () => [
+    props.text,
+    props.delay,
+    props.duration,
+    props.ease,
+    props.splitType,
+    props.from,
+    props.to,
+    props.threshold,
+    props.rootMargin,
+    props.textAlign,
+    props.onLetterAnimationComplete
+  ],
+  async () => {
+    cleanup()
+    await createAnimation()
+  }
+)
+
+onMounted(async () => {
+  await createAnimation()
+})
+
+onBeforeUnmount(() => {
+  cleanup()
+})
+</script>
@@ -1,6 +1,17 @@
 <template>
  <!-- CRT 滤镜叠加层 - 复古主题使用 -->
  <div class="absolute inset-0 pointer-events-none select-none z-30" aria-hidden="true">
+    <!-- Game Boy: noise 作为最前景层统一覆盖整个画面 -->
+    <WrappedGameboyDither
+      v-if="theme === 'gameboy'"
+      class="opacity-[0.3]"
+      style="filter: contrast(1.16)"
+      :pattern-refresh-interval="1"
+      :pattern-alpha="56"
+      mix-blend-mode="overlay"
+      :pattern-size="256"
+    />
+
    <!-- 扫描线 / RGB 子像素 / 闪烁 / 暗角 / 曲率 -->
    <div class="absolute inset-0 crt-scanlines"></div>
    <div class="absolute inset-0 crt-rgb-pixels"></div>
@@ -8,31 +19,9 @@
    <div class="absolute inset-0 crt-vignette"></div>
    <div class="absolute inset-0 crt-curvature"></div>

-    <!-- DOS: 语义化光标 -->
-    <div v-if="theme === 'dos'" class="dos-cursor">█</div>
  </div>
 </template>

 <script setup>
 const { theme } = useWrappedTheme()
 </script>
-
-<style scoped>
-/* DOS 语义化光标 */
-.dos-cursor {
-  position: fixed;
-  bottom: 20px;
-  right: 20px;
-  color: #33ff33;
-  font-size: 1.5rem;
-  font-family: var(--font-pixel-10), 'Courier New', monospace;
-  text-shadow: 0 0 8px rgba(51, 255, 51, 0.6);
-  animation: dos-cursor-blink 530ms steps(1) infinite;
-  z-index: 100;
-}
-
-@keyframes dos-cursor-blink {
-  0%, 50% { opacity: 1; }
-  51%, 100% { opacity: 0; }
-}
-</style>
@@ -87,8 +87,7 @@ defineProps({
 const { theme } = useWrappedTheme()
 const isWin98 = computed(() => theme.value === 'win98')
 const isGameboy = computed(() => theme.value === 'gameboy')
-const isDos = computed(() => theme.value === 'dos')
-const isCompactSlide = computed(() => isGameboy.value || isDos.value)
+const isCompactSlide = computed(() => isGameboy.value)

 const slideTitleClass = computed(() => (
  isCompactSlide.value ? 'text-xl sm:text-2xl' : 'text-2xl sm:text-3xl'
@@ -142,39 +141,4 @@ const slideContainerClass = computed(() => (
  border-color: #306230 !important;
 }

-/* ========== DOS 主题 ========== */
-
-/* 卡片背景 */
-.wrapped-theme-dos .bg-white {
-  background: #0a0a0a !important;
-  border-color: #33ff33 !important;
-  box-shadow: 0 0 10px rgba(51, 255, 51, 0.3);
-}
-
-/* 标题 */
-.wrapped-theme-dos .wrapped-title {
-  color: #33ff33 !important;
-  text-shadow: 0 0 5px #33ff33;
-  font-family: 'Courier New', monospace;
-}
-
-/* 描述文字 */
-.wrapped-theme-dos .wrapped-body {
-  color: #22aa22 !important;
-  text-shadow: 0 0 3px #22aa22;
-  font-family: 'Courier New', monospace;
-}
-
-/* 数字高亮 */
-.wrapped-theme-dos .wrapped-number {
-  color: #33ff33 !important;
-  text-shadow: 0 0 8px #33ff33;
-  font-family: 'Courier New', monospace;
-}
-
-/* 边框 */
-.wrapped-theme-dos .border-\[\#EDEDED\],
-.wrapped-theme-dos .border-\[\#F3F3F3\] {
-  border-color: #33ff33 !important;
-}
 </style>
@@ -131,30 +131,6 @@ const yearOptions = computed(() => {
  filter: brightness(1.1);
 }

-/* DOS 特殊样式 */
-.wrapped-theme-dos .controls-panel {
-  border-radius: 0;
-  border: 2px solid #33ff33;
-  box-shadow: 0 0 10px rgba(51, 255, 51, 0.3);
-}
-
-.wrapped-theme-dos .controls-select {
-  border-radius: 0;
-  border: 1px solid #33ff33;
-  text-shadow: 0 0 5px #33ff33;
-}
-
-.wrapped-theme-dos .controls-btn {
-  border-radius: 0;
-  background-color: #33ff33;
-  color: #000000;
-  text-shadow: none;
-}
-
-.wrapped-theme-dos .controls-btn:hover:not(:disabled) {
-  background-color: #44ff44;
-}
-
 /* Win98 特殊样式 */
 .wrapped-theme-win98 .controls-panel {
  border-radius: 0;
@@ -1,5 +1,5 @@
 <template>
-  <!-- Shared backdrop for all "Wrapped" slides (keeps cover + cards visually consistent). -->
+  <!-- Shared backdrop for modern/gameboy "Wrapped" slides (keeps cover + cards visually consistent). -->
  <div v-if="theme !== 'win98'" class="absolute inset-0 pointer-events-none select-none z-0" aria-hidden="true">
    <!-- Soft color blobs (brand + warm highlights) -->
    <div class="absolute -top-24 -left-24 w-80 h-80 bg-[#07C160] opacity-[0.08] rounded-full blur-3xl"></div>
@@ -11,8 +11,17 @@
      class="absolute inset-0 bg-[linear-gradient(rgba(7,193,96,0.05)_1px,transparent_1px),linear-gradient(90deg,rgba(7,193,96,0.05)_1px,transparent_1px)] bg-[size:52px_52px] opacity-[0.28]"
    ></div>

-    <!-- Grain/noise: enhanced with dynamic jitter for CRT feel -->
-    <div class="absolute inset-0 wrapped-noise-enhanced opacity-[0.08]"></div>
+    <!-- Grain/noise: gameboy 使用动态 canvas 噪点，其它主题沿用现有纹理 -->
+    <WrappedGameboyDither
+      v-if="theme === 'gameboy'"
+      class="opacity-[0.3]"
+      style="filter: contrast(1.16)"
+      :pattern-refresh-interval="1"
+      :pattern-alpha="56"
+      mix-blend-mode="overlay"
+      :pattern-size="256"
+    />
+    <div v-else class="absolute inset-0 wrapped-noise-enhanced opacity-[0.08]"></div>

    <!-- Gentle vignette so typography stays readable on textured bg -->
    <div class="absolute inset-x-0 top-0 h-40 bg-gradient-to-b from-white/50 to-transparent"></div>
@@ -0,0 +1,98 @@
+<template>
+  <canvas
+    ref="grainRef"
+    class="pointer-events-none absolute inset-0 h-full w-full"
+    :style="canvasStyle"
+    aria-hidden="true"
+  ></canvas>
+</template>
+
+<script setup>
+import { computed, onBeforeUnmount, onMounted, ref } from 'vue'
+
+const props = defineProps({
+  patternRefreshInterval: {
+    type: Number,
+    default: 2
+  },
+  patternAlpha: {
+    type: Number,
+    default: 20
+  },
+  mixBlendMode: {
+    type: String,
+    default: 'multiply'
+  },
+  patternSize: {
+    type: Number,
+    default: 512
+  }
+})
+
+const grainRef = ref(null)
+
+const canvasStyle = computed(() => `image-rendering: pixelated; mix-blend-mode: ${props.mixBlendMode};`)
+
+let animationId = 0
+let frame = 0
+let noiseData
+let noise32
+
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value))
+
+const resize = () => {
+  const canvas = grainRef.value
+  if (!canvas) return
+  const size = Math.max(64, Math.round(props.patternSize))
+  canvas.width = size
+  canvas.height = size
+}
+
+const initImageData = (ctx) => {
+  const canvas = grainRef.value
+  if (!canvas) return
+  noiseData = ctx.createImageData(canvas.width, canvas.height)
+  noise32 = new Uint32Array(noiseData.data.buffer)
+}
+
+const drawGrain = () => {
+  if (!noise32) return
+  const alpha = clamp(Math.round(props.patternAlpha), 0, 255) << 24
+  for (let i = 0; i < noise32.length; i++) {
+    const value = (Math.random() * 255) | 0
+    noise32[i] = alpha | (value << 16) | (value << 8) | value
+  }
+}
+
+const loop = (ctx) => {
+  const refreshEvery = Math.max(1, Math.round(props.patternRefreshInterval))
+  if (frame % refreshEvery === 0) {
+    drawGrain()
+    ctx.putImageData(noiseData, 0, 0)
+  }
+
+  frame++
+  animationId = window.requestAnimationFrame(() => loop(ctx))
+}
+
+onMounted(() => {
+  const canvas = grainRef.value
+  if (!canvas) return
+
+  const ctx = canvas.getContext('2d', { alpha: true })
+  if (!ctx) return
+
+  resize()
+  initImageData(ctx)
+  drawGrain()
+  ctx.putImageData(noiseData, 0, 0)
+  loop(ctx)
+
+  window.addEventListener('resize', resize)
+})
+
+onBeforeUnmount(() => {
+  window.removeEventListener('resize', resize)
+  window.cancelAnimationFrame(animationId)
+})
+</script>
@@ -35,7 +35,7 @@
              </div>

              <div class="mt-10 sm:mt-14">
-                <h1 class="wrapped-title text-4xl sm:text-6xl text-[#000000e6] leading-[1.05]">
+                <h1 class="wrapped-title text-3xl sm:text-5xl text-[#000000e6] leading-[1.05]">
                  {{ randomTitle.main }}
                  <span class="block mt-3 win98-hero-highlight">
                    {{ randomTitle.highlight }}
@@ -70,7 +70,7 @@
          </div>

          <div class="mt-10 sm:mt-14">
-            <h1 class="wrapped-title text-4xl sm:text-6xl text-[#000000e6] leading-[1.05]">
+            <h1 class="wrapped-title text-3xl sm:text-5xl text-[#000000e6] leading-[1.05]">
              {{ randomTitle.main }}
              <span class="block mt-3 text-[#07C160]">
                {{ randomTitle.highlight }}
@@ -90,6 +90,84 @@
            </div>
          </div>
        </div>
+
+        <div
+          v-if="previewQuestions.length > 0 && (isGameboy || isModern)"
+          class="pointer-events-none absolute bottom-0 right-0 hidden xl:flex items-end"
+        >
+          <div class="pointer-events-auto relative" :class="previewStageClass">
+            <div class="relative" :class="previewViewportClass">
+              <template v-if="isGameboy">
+              <BitsCardSwap
+                :width="previewCardWidth"
+                :height="previewCardHeight"
+                :delay="previewSwapDelay"
+                :card-count="previewQuestions.length"
+                :card-distance="previewCardDistance"
+                :vertical-distance="previewVerticalDistance"
+                :skew-amount="4"
+                easing="elastic"
+                :pause-on-hover="true"
+              >
+                <template
+                  v-for="(previewItem, previewIndex) in previewQuestions"
+                  :key="`preview-${previewItem.order}-${previewIndex}`"
+                  v-slot:[`card-${previewIndex}`]
+                >
+                  <WrappedCardShell
+                    :card-id="previewItem.order"
+                    :title="previewItem.title"
+                    variant="panel"
+                    class="h-full w-full"
+                  >
+                    <div
+                      class="flex h-[168px] items-center justify-center rounded-xl border border-dashed px-5"
+                      :class="previewQuestionPanelClass"
+                    >
+                      <p class="wrapped-body text-lg leading-relaxed text-center" :class="previewQuestionClass">
+                        {{ previewItem.question }}
+                      </p>
+                    </div>
+                  </WrappedCardShell>
+                </template>
+              </BitsCardSwap>
+              </template>
+
+              <template v-else>
+                <BitsGridMotion
+                  :items="modernPreviewItems"
+                  gradient-color="rgba(7, 193, 96, 0.24)"
+                  :row-count="7"
+                  :column-count="8"
+                  :scroll-speed="42"
+                  :base-offset-x="46"
+                >
+                  <template #item="{ item }">
+                    <WrappedCardShell
+                      :card-id="Number(item?.order || 0)"
+                      :title="String(item?.title || '年度卡片')"
+                      variant="panel"
+                      class="h-full w-full preview-grid-shell"
+                    >
+                      <div class="preview-grid-body">
+                        <div class="preview-grid-summary">
+                          {{ String(item?.summary || '年度线索') }}
+                        </div>
+                        <p class="preview-grid-question">
+                          {{ String(item?.question || '这一页会揭晓你的聊天答案。') }}
+                        </p>
+                        <div class="preview-grid-lines" aria-hidden="true">
+                          <span></span>
+                          <span></span>
+                        </div>
+                      </div>
+                    </WrappedCardShell>
+                  </template>
+                </BitsGridMotion>
+              </template>
+            </div>
+          </div>
+        </div>
      </template>

      <template v-else>
@@ -235,13 +313,126 @@ const subtitleIndex = useState('wrapped-subtitle-index', () => Math.floor(Math.r
 const randomTitle = computed(() => TITLES[titleIndex.value])
 const randomSubtitle = computed(() => SUBTITLES[subtitleIndex.value])

+const PREVIEW_BY_KIND = {
+  'global/overview': {
+    summary: '年度全景',
+    question: '这一年你最常把消息发给谁？'
+  },
+  'time/weekday_hour_heatmap': {
+    summary: '聊天作息',
+    question: '你是早八型还是夜猫子型聊天选手？'
+  },
+  'text/message_chars': {
+    summary: '表达强度',
+    question: '你这一年打出的字，能拼成几段故事？'
+  },
+  'chat/reply_speed': {
+    summary: '回复速度',
+    question: '谁是你愿意秒回的那个人？'
+  }
+}
+
+const PREVIEW_FALLBACK_SUMMARY = '年度线索'
+const PREVIEW_FALLBACK_QUESTION = '这一页会揭晓你的哪段聊天答案？'
+const PREVIEW_BOOTSTRAP_ITEMS = [
+  { summary: '年度全景', question: '这一年你最常把消息发给谁？' },
+  { summary: '聊天作息', question: '你是「早八人」还是「夜猫子」？' },
+  { summary: '表达强度', question: '你这一年打了多少字？' },
+  { summary: '回复速度', question: '谁是你愿意秒回的那个人？' }
+]
+
+const resolvePreviewMeta = (kind, idx) => {
+  const key = String(kind || '').trim()
+  if (PREVIEW_BY_KIND[key]) return PREVIEW_BY_KIND[key]
+  return {
+    summary: PREVIEW_FALLBACK_SUMMARY,
+    question: idx % 2 === 0
+      ? '这一页会揭晓你聊天里的哪种习惯？'
+      : '你猜这页的答案会指向谁和哪段时光？'
+  }
+}
+
 const props = defineProps({
  year: { type: Number, required: true },
-  variant: { type: String, default: 'panel' } // 'panel' | 'slide'
+  variant: { type: String, default: 'panel' }, // 'panel' | 'slide'
+  cardManifests: { type: Array, default: () => [] }
 })

 const { theme } = useWrappedTheme()
 const isWin98 = computed(() => theme.value === 'win98')
+const isGameboy = computed(() => theme.value === 'gameboy')
+const isModern = computed(() => theme.value === 'off')
+
+const previewQuestions = computed(() => {
+  const manifests = Array.isArray(props.cardManifests) ? props.cardManifests : []
+  if (!manifests.length) {
+    return Array.from({ length: 8 }, (_, idx) => {
+      const fallback = PREVIEW_BOOTSTRAP_ITEMS[idx % PREVIEW_BOOTSTRAP_ITEMS.length]
+      return {
+        order: idx + 1,
+        title: `第 ${idx + 1} 张卡片`,
+        summary: fallback.summary,
+        question: fallback.question
+      }
+    })
+  }
+
+  return manifests.map((item, idx) => {
+    const meta = resolvePreviewMeta(item?.kind, idx)
+    return {
+      order: idx + 1,
+      title: String(item?.title || `第 ${idx + 1} 张卡片`),
+      summary: meta.summary,
+      question: meta.question
+    }
+  })
+})
+
+const previewSwapDelay = 4200
+const previewCardWidth = 420
+const previewCardHeight = 280
+
+const modernPreviewItems = computed(() => {
+  if (!previewQuestions.value.length) return []
+  return previewQuestions.value.map((item) => ({
+    order: item.order,
+    title: item.title,
+    summary: item.summary,
+    question: item.question
+  }))
+})
+
+const previewStageClass = computed(() => (
+  isGameboy.value
+    ? 'w-[500px] h-[360px] translate-x-24 -translate-y-8'
+    : 'w-[620px] h-[420px] translate-x-32 -translate-y-10'
+))
+
+const previewViewportClass = computed(() => (
+  isGameboy.value
+    ? 'h-[340px] w-[460px]'
+    : 'h-[390px] w-[580px]'
+))
+
+const previewCardDistance = computed(() => {
+  const total = previewQuestions.value.length
+  return total >= 9 ? 9 : total >= 7 ? 11 : total >= 5 ? 13 : 18
+})
+
+const previewVerticalDistance = computed(() => {
+  const total = previewQuestions.value.length
+  return total >= 9 ? 10 : total >= 7 ? 11 : total >= 5 ? 14 : 18
+})
+
+const previewQuestionClass = computed(() => {
+  if (isWin98.value) return 'text-[#111111]'
+  return 'text-[#1F2937]'
+})
+
+const previewQuestionPanelClass = computed(() => {
+  if (isWin98.value) return 'border-[#B7B7B7] bg-[#FFFFFF]'
+  return 'border-[#07C160]/30 bg-[#F7FFFB]'
+})

 const yearText = computed(() => `${props.year}年`)

@@ -267,4 +458,64 @@ const innerClass = computed(() => {
  background: #000080;
  color: #ffffff;
 }
+
+.preview-grid-shell {
+  border-radius: 12px;
+  box-shadow: 0 10px 24px rgba(7, 193, 96, 0.14);
+  background: #f3fff8 !important;
+  border-color: rgba(7, 193, 96, 0.24) !important;
+}
+
+.preview-grid-shell :deep(.wrapped-title) {
+  font-size: 16px;
+  line-height: 1.25;
+}
+
+.preview-grid-body {
+  height: 96px;
+  border-radius: 10px;
+  border: 1px solid rgba(7, 193, 96, 0.2);
+  background: rgba(243, 255, 248, 0.88);
+  display: flex;
+  flex-direction: column;
+  justify-content: space-between;
+  padding: 10px 12px;
+}
+
+.preview-grid-summary {
+  font-size: 11px;
+  line-height: 1;
+  letter-spacing: 0.04em;
+  color: #07c160;
+  font-weight: 700;
+}
+
+.preview-grid-question {
+  margin-top: 6px;
+  color: #1f2937;
+  font-size: 13px;
+  line-height: 1.35;
+  font-weight: 600;
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+
+.preview-grid-lines {
+  margin-top: 6px;
+  display: grid;
+  gap: 5px;
+}
+
+.preview-grid-lines span {
+  display: block;
+  height: 5px;
+  border-radius: 999px;
+  background: linear-gradient(90deg, rgba(7, 193, 96, 0.18), rgba(7, 193, 96, 0.08));
+}
+
+.preview-grid-lines span:last-child {
+  width: 68%;
+}
 </style>
@@ -10,7 +10,6 @@ const themeSwitcherComponent = computed(() => {
  const map = {
    off: resolveComponent('WrappedThemeSwitcherModern'),
    gameboy: resolveComponent('WrappedThemeSwitcherGameboy'),
-    dos: resolveComponent('WrappedThemeSwitcherDos'),
    win98: resolveComponent('WrappedThemeSwitcherWin98')
  }
  return map[theme.value] || map.off
@@ -1,100 +0,0 @@
-<template>
-  <div class="dos-menu select-none">
-    <!-- DOS 风格功能键菜单栏 -->
-    <div class="dos-menu-bar">
-      <button
-        v-for="(t, idx) in themes"
-        :key="t.value"
-        class="dos-menu-item"
-        :class="{ 'is-active': theme === t.value }"
-        @click="setTheme(t.value)"
-      >
-        <span class="dos-fkey">F{{ idx + 1 }}</span>
-        <span class="dos-label">{{ t.label }}</span>
-      </button>
-    </div>
-    <!-- 状态提示 -->
-    <div class="dos-status">
-      Press F1-F4 to switch theme
-    </div>
-  </div>
-</template>
-
-<script setup>
-const { theme, setTheme } = useWrappedTheme()
-
-const themes = [
-  { value: 'off', label: 'Modern' },
-  { value: 'gameboy', label: 'GameBoy' },
-  { value: 'dos', label: 'DOS' },
-  { value: 'win98', label: 'Win98' }
-]
-</script>
-
-<style scoped>
-.dos-menu {
-  font-family: 'Courier New', 'Consolas', monospace;
-  font-size: 11px;
-}
-
-.dos-menu-bar {
-  display: flex;
-  background: #000000;
-  border: 1px solid #33ff33;
-  overflow: hidden;
-}
-
-.dos-menu-item {
-  display: flex;
-  align-items: center;
-  gap: 2px;
-  padding: 4px 8px;
-  background: #000000;
-  color: #33ff33;
-  border: none;
-  border-right: 1px solid #1a5c1a;
-  cursor: pointer;
-  text-shadow: 0 0 5px #33ff33;
-  transition: all 0.1s;
-  font-family: inherit;
-  font-size: inherit;
-}
-
-.dos-menu-item:last-child {
-  border-right: none;
-}
-
-.dos-menu-item:hover {
-  background: #0a1a0a;
-}
-
-.dos-menu-item.is-active {
-  background: #33ff33;
-  color: #000000;
-  text-shadow: none;
-}
-
-.dos-fkey {
-  font-weight: bold;
-  padding: 1px 3px;
-  background: #1a5c1a;
-  color: #33ff33;
-  font-size: 9px;
-}
-
-.dos-menu-item.is-active .dos-fkey {
-  background: #000000;
-  color: #33ff33;
-}
-
-.dos-label {
-  letter-spacing: 0.5px;
-}
-
-.dos-status {
-  margin-top: 4px;
-  color: #1a5c1a;
-  font-size: 9px;
-  text-shadow: 0 0 3px #1a5c1a;
-}
-</style>
@@ -25,7 +25,6 @@ const { theme, setTheme } = useWrappedTheme()
 const themes = [
  { value: 'off', label: 'MODERN' },
  { value: 'gameboy', label: 'GAME BOY' },
-  { value: 'dos', label: 'DOS' },
  { value: 'win98', label: 'WIN98' }
 ]

@@ -25,7 +25,6 @@ const { theme, setTheme } = useWrappedTheme()
 const themes = [
  { value: 'off', label: 'Modern' },
  { value: 'gameboy', label: 'Game Boy' },
-  { value: 'dos', label: 'DOS' },
  { value: 'win98', label: 'Win98' }
 ]
 </script>
@@ -23,7 +23,6 @@ const { theme, setTheme } = useWrappedTheme()
 const themes = [
  { value: 'off', label: 'Modern' },
  { value: 'gameboy', label: 'Game Boy' },
-  { value: 'dos', label: 'DOS' },
  { value: 'win98', label: 'Win98' }
 ]
 </script>
@@ -19,25 +19,6 @@
      </div>
    </div>

-    <!-- DOS 风格 -->
-    <div v-else-if="theme === 'dos'" class="year-dos">
-      <span class="dos-prompt">C:\WRAPPED&gt;</span>
-      <span class="dos-label">YEAR:</span>
-      <button
-        class="dos-arrow"
-        :disabled="!canGoPrev"
-        @click="prevYear"
-        aria-label="Previous year"
-      >[-]</button>
-      <span class="dos-value">{{ modelValue }}</span>
-      <button
-        class="dos-arrow"
-        :disabled="!canGoNext"
-        @click="nextYear"
-        aria-label="Next year"
-      >[+]</button>
-    </div>
-
    <!-- Win98 风格 -->
    <div v-else-if="theme === 'win98'" class="year-win98">
      <div class="win98-year-box">
@@ -209,57 +190,6 @@ onBeforeUnmount(() => {
  letter-spacing: 2px;
 }

-/* ========== DOS 风格 ========== */
-.year-dos {
-  font-family: 'Courier New', 'Consolas', monospace;
-  font-size: 11px;
-  display: flex;
-  align-items: center;
-  gap: 4px;
-  color: #33ff33;
-  text-shadow: 0 0 5px #33ff33;
-}
-
-.dos-prompt {
-  color: #1a5c1a;
-}
-
-.dos-label {
-  color: #33ff33;
-}
-
-.dos-arrow {
-  background: transparent;
-  border: none;
-  color: #33ff33;
-  font-family: inherit;
-  font-size: inherit;
-  cursor: pointer;
-  padding: 0 2px;
-  text-shadow: 0 0 5px #33ff33;
-  transition: color 0.1s;
-}
-
-.dos-arrow:hover:not(:disabled) {
-  color: #66ff66;
-  text-shadow: 0 0 8px #66ff66;
-}
-
-.dos-arrow:disabled {
-  color: #1a5c1a;
-  cursor: not-allowed;
-  text-shadow: none;
-}
-
-.dos-value {
-  background: #0a1a0a;
-  padding: 2px 6px;
-  border: 1px solid #1a5c1a;
-  letter-spacing: 1px;
-  min-width: 50px;
-  text-align: center;
-}
-
 /* ========== Win98 风格 ========== */
 .year-win98 {
  font-family: "MS Sans Serif", Tahoma, "Microsoft Sans Serif", "Segoe UI", sans-serif;
@@ -292,6 +292,7 @@ export const useApi = () => {
        message_types: Array.isArray(data.message_types) ? data.message_types : [],
        include_media: data.include_media == null ? true : !!data.include_media,
        media_kinds: Array.isArray(data.media_kinds) ? data.media_kinds : ['image', 'emoji', 'video', 'video_thumb', 'voice', 'file'],
+        output_dir: data.output_dir == null ? null : String(data.output_dir || '').trim(),
        allow_process_key_extract: !!data.allow_process_key_extract,
        privacy_mode: !!data.privacy_mode,
        file_name: data.file_name || null
@@ -313,6 +314,36 @@ export const useApi = () => {
    return await request(`/chat/exports/${encodeURIComponent(String(exportId))}`, { method: 'DELETE' })
  }

+  // 联系人
+  const listChatContacts = async (params = {}) => {
+    const query = new URLSearchParams()
+    if (params && params.account) query.set('account', params.account)
+    if (params && params.keyword) query.set('keyword', params.keyword)
+    if (params && params.include_friends != null) query.set('include_friends', String(!!params.include_friends))
+    if (params && params.include_groups != null) query.set('include_groups', String(!!params.include_groups))
+    if (params && params.include_officials != null) query.set('include_officials', String(!!params.include_officials))
+    const url = '/chat/contacts' + (query.toString() ? `?${query.toString()}` : '')
+    return await request(url)
+  }
+
+  const exportChatContacts = async (payload = {}) => {
+    return await request('/chat/contacts/export', {
+      method: 'POST',
+      body: {
+        account: payload.account || null,
+        output_dir: payload.output_dir || '',
+        format: payload.format || 'json',
+        include_avatar_link: payload.include_avatar_link == null ? true : !!payload.include_avatar_link,
+        keyword: payload.keyword || null,
+        contact_types: {
+          friends: payload?.contact_types?.friends == null ? true : !!payload.contact_types.friends,
+          groups: payload?.contact_types?.groups == null ? true : !!payload.contact_types.groups,
+          officials: payload?.contact_types?.officials == null ? true : !!payload.contact_types.officials,
+        }
+      }
+    })
+  }
+
  // WeChat Wrapped（年度总结）
  const getWrappedAnnual = async (params = {}) => {
    const query = new URLSearchParams()
@@ -344,7 +375,22 @@ export const useApi = () => {
    const url = `/wrapped/annual/cards/${safeId}` + (query.toString() ? `?${query.toString()}` : '')
    return await request(url)
  }
-  
+
+  // 获取微信进程状态
+  const getWxStatus = async () => {
+    return await request('/wechat/status')
+  }
+
+  // 获取数据库密钥
+  const getDbKey = async () => {
+    return await request('/get_db_key')
+  }
+
+  // 获取图片密钥
+  const getImageKey = async () => {
+    return await request('/get_image_key')
+  }
+
  return {
    detectWechat,
    detectCurrentAccount,
@@ -373,8 +419,13 @@ export const useApi = () => {
    getChatExport,
    listChatExports,
    cancelChatExport,
+    listChatContacts,
+    exportChatContacts,
    getWrappedAnnual,
    getWrappedAnnualMeta,
-    getWrappedAnnualCard
+    getWrappedAnnualCard,
+    getDbKey,
+    getImageKey,
+    getWxStatus,
  }
 }
@@ -1,11 +1,11 @@
 /**
 * 年度总结页面主题管理 composable
- * 支持三种主题：modern（现代）、gameboy（Game Boy）、dos（DOS终端）
+ * 支持三种主题：modern（现代）、gameboy（Game Boy）、win98（Windows 98）
 */

 const STORAGE_KEY = 'wrapped-theme'
-const VALID_THEMES = ['off', 'gameboy', 'dos', 'win98']
-const RETRO_THEMES = new Set(['gameboy', 'dos'])
+const VALID_THEMES = ['off', 'gameboy', 'win98']
+const RETRO_THEMES = new Set(['gameboy'])

 // 全局响应式状态（跨组件共享）
 const theme = ref('off')
@@ -15,19 +15,12 @@ let keyboardInitialized = false
 export function useWrappedTheme() {
  // 初始化：从 localStorage 读取（仅执行一次）
  const initTheme = () => {
-    if (initialized) return
-    if (import.meta.client) {
-      const saved = localStorage.getItem(STORAGE_KEY)
-      if (saved && VALID_THEMES.includes(saved)) {
-        theme.value = saved
-      }
-      initialized = true
+    if (initialized || !import.meta.client) return
+    const saved = localStorage.getItem(STORAGE_KEY)
+    if (saved && VALID_THEMES.includes(saved)) {
+      theme.value = saved
    }
-  }
-
-  // 立即初始化（客户端）
-  if (import.meta.client) {
-    initTheme()
+    initialized = true
  }

  // 设置主题
@@ -66,7 +59,6 @@ export function useWrappedTheme() {
    const names = {
      off: 'Modern',
      gameboy: 'Game Boy',
-      dos: 'DOS Terminal',
      win98: 'Windows 98'
    }
    return names[theme.value] || 'Modern'
@@ -91,9 +83,6 @@ export function useWrappedTheme() {
        e.preventDefault()
        setTheme('gameboy')
      } else if (e.key === 'F3') {
-        e.preventDefault()
-        setTheme('dos')
-      } else if (e.key === 'F4') {
        e.preventDefault()
        setTheme('win98')
      }
@@ -102,10 +91,11 @@ export function useWrappedTheme() {
    window.addEventListener('keydown', handleKeydown)
  }

-  // 自动初始化键盘快捷键
-  if (import.meta.client) {
+  // 客户端挂载后再初始化：避免 SSR 与首帧 hydration 不一致
+  onMounted(() => {
+    initTheme()
    initKeyboardShortcuts()
-  }
+  })

  return {
    theme: readonly(theme),
@@ -28,7 +28,8 @@ export default defineNuxtConfig({
        { name: 'description', content: '微信4.x版本数据库解密工具' }
      ],
      link: [
-        { rel: 'icon', type: 'image/png', href: '/logo.png' }
+        { rel: 'icon', type: 'image/png', href: '/logo.png' },
+        { rel: 'stylesheet', href: 'https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css' }
      ]
    },
    pageTransition: { name: 'page', mode: 'out-in' }
@@ -11,7 +11,9 @@
        "@pinia/nuxt": "^0.11.2",
        "@vueuse/motion": "^3.0.3",
        "axios": "^1.11.0",
+        "gsap": "^3.14.2",
        "nuxt": "^4.0.1",
+        "ogl": "^1.0.11",
        "vue": "^3.5.17",
        "vue-router": "^4.5.1"
      }
@@ -7363,6 +7365,12 @@
      "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==",
      "license": "ISC"
    },
+    "node_modules/gsap": {
+      "version": "3.14.2",
+      "resolved": "https://registry.npmmirror.com/gsap/-/gsap-3.14.2.tgz",
+      "integrity": "sha512-P8/mMxVLU7o4+55+1TCnQrPmgjPKnwkzkXOK1asnR9Jg2lna4tEY5qBJjMmAaOBDDZWtlRjBXjLa0w53G/uBLA==",
+      "license": "Standard 'no charge' license: https://gsap.com/standard-license."
+    },
    "node_modules/gzip-size": {
      "version": "7.0.0",
      "resolved": "https://registry.npmmirror.com/gzip-size/-/gzip-size-7.0.0.tgz",
@@ -8394,6 +8402,279 @@
        "safe-buffer": "~5.1.0"
      }
    },
+    "node_modules/lightningcss": {
+      "version": "1.30.2",
+      "resolved": "https://registry.npmmirror.com/lightningcss/-/lightningcss-1.30.2.tgz",
+      "integrity": "sha512-utfs7Pr5uJyyvDETitgsaqSyjCb2qNRAtuqUeWIAKztsOYdcACf2KtARYXg2pSvhkt+9NfoaNY7fxjl6nuMjIQ==",
+      "license": "MPL-2.0",
+      "optional": true,
+      "peer": true,
+      "dependencies": {
+        "detect-libc": "^2.0.3"
+      },
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      },
+      "optionalDependencies": {
+        "lightningcss-android-arm64": "1.30.2",
+        "lightningcss-darwin-arm64": "1.30.2",
+        "lightningcss-darwin-x64": "1.30.2",
+        "lightningcss-freebsd-x64": "1.30.2",
+        "lightningcss-linux-arm-gnueabihf": "1.30.2",
+        "lightningcss-linux-arm64-gnu": "1.30.2",
+        "lightningcss-linux-arm64-musl": "1.30.2",
+        "lightningcss-linux-x64-gnu": "1.30.2",
+        "lightningcss-linux-x64-musl": "1.30.2",
+        "lightningcss-win32-arm64-msvc": "1.30.2",
+        "lightningcss-win32-x64-msvc": "1.30.2"
+      }
+    },
+    "node_modules/lightningcss-android-arm64": {
+      "version": "1.30.2",
+      "resolved": "https://registry.npmmirror.com/lightningcss-android-arm64/-/lightningcss-android-arm64-1.30.2.tgz",
+      "integrity": "sha512-BH9sEdOCahSgmkVhBLeU7Hc9DWeZ1Eb6wNS6Da8igvUwAe0sqROHddIlvU06q3WyXVEOYDZ6ykBZQnjTbmo4+A==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-darwin-arm64": {
+      "version": "1.30.2",
+      "resolved": "https://registry.npmmirror.com/lightningcss-darwin-arm64/-/lightningcss-darwin-arm64-1.30.2.tgz",
+      "integrity": "sha512-ylTcDJBN3Hp21TdhRT5zBOIi73P6/W0qwvlFEk22fkdXchtNTOU4Qc37SkzV+EKYxLouZ6M4LG9NfZ1qkhhBWA==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-darwin-x64": {
+      "version": "1.30.2",
+      "resolved": "https://registry.npmmirror.com/lightningcss-darwin-x64/-/lightningcss-darwin-x64-1.30.2.tgz",
+      "integrity": "sha512-oBZgKchomuDYxr7ilwLcyms6BCyLn0z8J0+ZZmfpjwg9fRVZIR5/GMXd7r9RH94iDhld3UmSjBM6nXWM2TfZTQ==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-freebsd-x64": {
+      "version": "1.30.2",
+      "resolved": "https://registry.npmmirror.com/lightningcss-freebsd-x64/-/lightningcss-freebsd-x64-1.30.2.tgz",
+      "integrity": "sha512-c2bH6xTrf4BDpK8MoGG4Bd6zAMZDAXS569UxCAGcA7IKbHNMlhGQ89eRmvpIUGfKWNVdbhSbkQaWhEoMGmGslA==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-linux-arm-gnueabihf": {
+      "version": "1.30.2",
+      "resolved": "https://registry.npmmirror.com/lightningcss-linux-arm-gnueabihf/-/lightningcss-linux-arm-gnueabihf-1.30.2.tgz",
+      "integrity": "sha512-eVdpxh4wYcm0PofJIZVuYuLiqBIakQ9uFZmipf6LF/HRj5Bgm0eb3qL/mr1smyXIS1twwOxNWndd8z0E374hiA==",
+      "cpu": [
+        "arm"
+      ],
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-linux-arm64-gnu": {
+      "version": "1.30.2",
+      "resolved": "https://registry.npmmirror.com/lightningcss-linux-arm64-gnu/-/lightningcss-linux-arm64-gnu-1.30.2.tgz",
+      "integrity": "sha512-UK65WJAbwIJbiBFXpxrbTNArtfuznvxAJw4Q2ZGlU8kPeDIWEX1dg3rn2veBVUylA2Ezg89ktszWbaQnxD/e3A==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-linux-arm64-musl": {
+      "version": "1.30.2",
+      "resolved": "https://registry.npmmirror.com/lightningcss-linux-arm64-musl/-/lightningcss-linux-arm64-musl-1.30.2.tgz",
+      "integrity": "sha512-5Vh9dGeblpTxWHpOx8iauV02popZDsCYMPIgiuw97OJ5uaDsL86cnqSFs5LZkG3ghHoX5isLgWzMs+eD1YzrnA==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-linux-x64-gnu": {
+      "version": "1.30.2",
+      "resolved": "https://registry.npmmirror.com/lightningcss-linux-x64-gnu/-/lightningcss-linux-x64-gnu-1.30.2.tgz",
+      "integrity": "sha512-Cfd46gdmj1vQ+lR6VRTTadNHu6ALuw2pKR9lYq4FnhvgBc4zWY1EtZcAc6EffShbb1MFrIPfLDXD6Xprbnni4w==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-linux-x64-musl": {
+      "version": "1.30.2",
+      "resolved": "https://registry.npmmirror.com/lightningcss-linux-x64-musl/-/lightningcss-linux-x64-musl-1.30.2.tgz",
+      "integrity": "sha512-XJaLUUFXb6/QG2lGIW6aIk6jKdtjtcffUT0NKvIqhSBY3hh9Ch+1LCeH80dR9q9LBjG3ewbDjnumefsLsP6aiA==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-win32-arm64-msvc": {
+      "version": "1.30.2",
+      "resolved": "https://registry.npmmirror.com/lightningcss-win32-arm64-msvc/-/lightningcss-win32-arm64-msvc-1.30.2.tgz",
+      "integrity": "sha512-FZn+vaj7zLv//D/192WFFVA0RgHawIcHqLX9xuWiQt7P0PtdFEVaxgF9rjM/IRYHQXNnk61/H/gb2Ei+kUQ4xQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-win32-x64-msvc": {
+      "version": "1.30.2",
+      "resolved": "https://registry.npmmirror.com/lightningcss-win32-x64-msvc/-/lightningcss-win32-x64-msvc-1.30.2.tgz",
+      "integrity": "sha512-5g1yc73p+iAkid5phb4oVFMB45417DkRevRbt/El/gKXJk4jid+vPFF/AXbxn05Aky8PapwzZrdJShv5C0avjw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss/node_modules/detect-libc": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmmirror.com/detect-libc/-/detect-libc-2.1.2.tgz",
+      "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
+      "license": "Apache-2.0",
+      "optional": true,
+      "peer": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
    "node_modules/lilconfig": {
      "version": "3.1.3",
      "resolved": "https://registry.npmmirror.com/lilconfig/-/lilconfig-3.1.3.tgz",
@@ -8449,14 +8730,14 @@
      "license": "MIT"
    },
    "node_modules/local-pkg": {
-      "version": "1.1.1",
-      "resolved": "https://registry.npmmirror.com/local-pkg/-/local-pkg-1.1.1.tgz",
-      "integrity": "sha512-WunYko2W1NcdfAFpuLUoucsgULmgDBRkdxHxWQ7mK0cQqwPiy8E1enjuRBrhLtZkB5iScJ1XIPdhVEFK8aOLSg==",
+      "version": "1.1.2",
+      "resolved": "https://registry.npmmirror.com/local-pkg/-/local-pkg-1.1.2.tgz",
+      "integrity": "sha512-arhlxbFRmoQHl33a0Zkle/YWlmNwoyt6QNZEIJcqNbdrsix5Lvc4HyyI3EnwxTYlZYc32EbYrQ8SzEZ7dqgg9A==",
      "license": "MIT",
      "dependencies": {
        "mlly": "^1.7.4",
-        "pkg-types": "^2.0.1",
-        "quansync": "^0.2.8"
+        "pkg-types": "^2.3.0",
+        "quansync": "^0.2.11"
      },
      "engines": {
        "node": ">=14"
@@ -9406,6 +9687,12 @@
        "ufo": "^1.5.4"
      }
    },
+    "node_modules/ogl": {
+      "version": "1.0.11",
+      "resolved": "https://registry.npmmirror.com/ogl/-/ogl-1.0.11.tgz",
+      "integrity": "sha512-kUpC154AFfxi16pmZUK4jk3J+8zxwTWGPo03EoYA8QPbzikHoaC82n6pNTbd+oEaJonaE8aPWBlX7ad9zrqLsA==",
+      "license": "Unlicense"
+    },
    "node_modules/ohash": {
      "version": "2.0.11",
      "resolved": "https://registry.npmmirror.com/ohash/-/ohash-2.0.11.tgz",
@@ -10740,9 +11027,9 @@
      }
    },
    "node_modules/quansync": {
-      "version": "0.2.10",
-      "resolved": "https://registry.npmmirror.com/quansync/-/quansync-0.2.10.tgz",
-      "integrity": "sha512-t41VRkMYbkHyCYmOvx/6URnN80H7k4X0lLdBMGsz+maAwrJQYB1djpV6vHrQIBE0WBSGqhtEHrK9U3DWWH8v7A==",
+      "version": "0.2.11",
+      "resolved": "https://registry.npmmirror.com/quansync/-/quansync-0.2.11.tgz",
+      "integrity": "sha512-AifT7QEbW9Nri4tAwR5M/uzpBuqfZf+zwaEM/QkzEjj7NBuFD2rBuy0K3dE+8wltbezDV7JMA0WfnCPYRSYbXA==",
      "funding": [
        {
          "type": "individual",
@@ -14,8 +14,13 @@
    "@pinia/nuxt": "^0.11.2",
    "@vueuse/motion": "^3.0.3",
    "axios": "^1.11.0",
+    "gsap": "^3.14.2",
    "nuxt": "^4.0.1",
+    "ogl": "^1.0.11",
    "vue": "^3.5.17",
    "vue-router": "^4.5.1"
+  },
+  "devDependencies": {
+    "tailwindcss": "3.4.17"
  }
 }
@@ -0,0 +1,572 @@
+<template>
+  <div class="h-screen flex overflow-hidden" style="background-color: #EDEDED">
+    <div class="border-r border-gray-200 flex flex-col" style="background-color: #e8e7e7; width: 60px; min-width: 60px; max-width: 60px">
+      <div class="flex-1 flex flex-col justify-start pt-0 gap-0">
+        <div class="w-full h-[60px] flex items-center justify-center">
+          <div class="w-[40px] h-[40px] rounded-md overflow-hidden bg-gray-300 flex-shrink-0">
+            <img v-if="selfAvatarUrl" :src="selfAvatarUrl" alt="avatar" class="w-full h-full object-cover" />
+            <div v-else class="w-full h-full flex items-center justify-center text-white text-xs font-bold" style="background-color: #4B5563">我</div>
+          </div>
+        </div>
+
+        <div class="w-full h-[var(--sidebar-rail-step)] flex items-center justify-center cursor-pointer group" title="聊天" @click="goChat">
+          <div class="w-[var(--sidebar-rail-btn)] h-[var(--sidebar-rail-btn)] rounded-md flex items-center justify-center transition-colors bg-transparent group-hover:bg-[#E1E1E1]">
+            <div class="w-[var(--sidebar-rail-icon)] h-[var(--sidebar-rail-icon)]" :class="isChatRoute ? 'text-[#07b75b]' : 'text-[#5d5d5d]'">
+              <svg class="w-full h-full" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+                <path d="M12 19.8C17.52 19.8 22 15.99 22 11.3C22 6.6 17.52 2.8 12 2.8C6.48 2.8 2 6.6 2 11.3C2 13.29 2.8 15.12 4.15 16.57C4.6 17.05 4.82 17.29 4.92 17.44C5.14 17.79 5.21 17.99 5.23 18.4C5.24 18.59 5.22 18.81 5.16 19.26C5.1 19.75 5.07 19.99 5.13 20.16C5.23 20.49 5.53 20.71 5.87 20.72C6.04 20.72 6.27 20.63 6.72 20.43L8.07 19.86C8.43 19.71 8.61 19.63 8.77 19.59C8.95 19.55 9.04 19.54 9.22 19.54C9.39 19.53 9.64 19.57 10.14 19.65C10.74 19.75 11.37 19.8 12 19.8Z" />
+              </svg>
+            </div>
+          </div>
+        </div>
+
+        <div class="w-full h-[var(--sidebar-rail-step)] flex items-center justify-center cursor-pointer group" title="朋友圈" @click="goSns">
+          <div class="w-[var(--sidebar-rail-btn)] h-[var(--sidebar-rail-btn)] rounded-md flex items-center justify-center transition-colors bg-transparent group-hover:bg-[#E1E1E1]">
+            <div class="w-[var(--sidebar-rail-icon)] h-[var(--sidebar-rail-icon)]" :class="isSnsRoute ? 'text-[#07b75b]' : 'text-[#5d5d5d]'">
+              <svg class="w-full h-full" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+                <circle cx="12" cy="12" r="10" />
+                <line x1="14.31" y1="8" x2="20.05" y2="17.94" />
+                <line x1="9.69" y1="8" x2="21.17" y2="8" />
+                <line x1="7.38" y1="12" x2="13.12" y2="2.06" />
+                <line x1="9.69" y1="16" x2="3.95" y2="6.06" />
+                <line x1="14.31" y1="16" x2="2.83" y2="16" />
+                <line x1="16.62" y1="12" x2="10.88" y2="21.94" />
+              </svg>
+            </div>
+          </div>
+        </div>
+
+        <div class="w-full h-[var(--sidebar-rail-step)] flex items-center justify-center cursor-pointer group" title="联系人">
+          <div class="w-[var(--sidebar-rail-btn)] h-[var(--sidebar-rail-btn)] rounded-md flex items-center justify-center transition-colors bg-transparent group-hover:bg-[#E1E1E1]">
+            <div class="w-[var(--sidebar-rail-icon)] h-[var(--sidebar-rail-icon)] text-[#07b75b]">
+              <svg class="w-full h-full" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+                <path d="M17 21v-2a4 4 0 0 0-4-4H7a4 4 0 0 0-4 4v2" />
+                <circle cx="10" cy="7" r="4" />
+                <path d="M23 21v-2a4 4 0 0 0-3-3.87" />
+                <path d="M16 3.13a4 4 0 0 1 0 7.75" />
+              </svg>
+            </div>
+          </div>
+        </div>
+
+        <div class="w-full h-[var(--sidebar-rail-step)] flex items-center justify-center cursor-pointer group" title="年度总结" @click="goWrapped">
+          <div class="w-[var(--sidebar-rail-btn)] h-[var(--sidebar-rail-btn)] rounded-md flex items-center justify-center transition-colors bg-transparent group-hover:bg-[#E1E1E1]">
+            <div class="w-[var(--sidebar-rail-icon)] h-[var(--sidebar-rail-icon)]" :class="isWrappedRoute ? 'text-[#07b75b]' : 'text-[#5d5d5d]'">
+              <svg class="w-full h-full" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+                <rect x="4" y="4" width="16" height="16" rx="2" />
+                <path d="M8 16v-5" />
+                <path d="M12 16v-8" />
+                <path d="M16 16v-3" />
+              </svg>
+            </div>
+          </div>
+        </div>
+
+        <div class="w-full h-[var(--sidebar-rail-step)] flex items-center justify-center cursor-pointer group" @click="privacyMode = !privacyMode" :title="privacyMode ? '关闭隐私模式' : '开启隐私模式'">
+          <div class="w-[var(--sidebar-rail-btn)] h-[var(--sidebar-rail-btn)] rounded-md flex items-center justify-center transition-colors bg-transparent group-hover:bg-[#E1E1E1]">
+            <svg class="w-[var(--sidebar-rail-icon)] h-[var(--sidebar-rail-icon)]" :class="privacyMode ? 'text-[#07b75b]' : 'text-[#5d5d5d]'" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">
+              <path v-if="privacyMode" stroke-linecap="round" stroke-linejoin="round" d="M3.98 8.223A10.477 10.477 0 001.934 12C3.226 16.338 7.244 19.5 12 19.5c.993 0 1.953-.138 2.863-.395M6.228 6.228A10.45 10.45 0 0112 4.5c4.756 0 8.773 3.162 10.065 7.498a10.523 10.523 0 01-4.293 5.774M6.228 6.228L3 3m3.228 3.228l3.65 3.65m7.894 7.894L21 21m-3.228-3.228l-3.65-3.65m0 0a3 3 0 10-4.243-4.243m4.242 4.242L9.88 9.88" />
+              <path v-else stroke-linecap="round" stroke-linejoin="round" d="M2.036 12.322a1.012 1.012 0 010-.639C3.423 7.51 7.36 4.5 12 4.5c4.638 0 8.573 3.007 9.963 7.178.07.207.07.431 0 .639C20.577 16.49 16.64 19.5 12 19.5c-4.638 0-8.573-3.007-9.963-7.178z" />
+              <circle v-if="!privacyMode" cx="12" cy="12" r="3" />
+            </svg>
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <div class="flex-1 flex flex-col min-h-0" style="background-color: #EDEDED">
+      <DesktopTitleBar />
+      <div class="flex-1 min-h-0 overflow-hidden p-4">
+        <div class="h-full grid grid-cols-1 lg:grid-cols-[400px_minmax(0,1fr)] gap-4">
+          <div class="bg-white border border-gray-200 rounded-lg flex flex-col min-h-0 overflow-hidden">
+            <div class="p-3 border-b border-gray-200" style="background-color: #F7F7F7">
+              <div class="flex items-center gap-2">
+                <div class="contact-search-wrapper flex-1" :class="{ 'privacy-blur': privacyMode }">
+                  <svg class="contact-search-icon" fill="none" stroke="currentColor" viewBox="0 0 16 16">
+                    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M7.33333 12.6667C10.2789 12.6667 12.6667 10.2789 12.6667 7.33333C12.6667 4.38781 10.2789 2 7.33333 2C4.38781 2 2 4.38781 2 7.33333C2 10.2789 4.38781 12.6667 7.33333 12.6667Z" />
+                    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M14 14L11.1 11.1" />
+                  </svg>
+                  <input v-model="searchKeyword" class="contact-search-input" type="text" placeholder="搜索联系人" />
+                  <button v-if="searchKeyword" type="button" class="contact-search-clear" @click="searchKeyword = ''">
+                    <svg class="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                      <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
+                    </svg>
+                  </button>
+                </div>
+
+                <select v-if="availableAccounts.length > 1" v-model="selectedAccount" class="account-select">
+                  <option v-for="acc in availableAccounts" :key="acc" :value="acc">{{ acc }}</option>
+                </select>
+              </div>
+            </div>
+
+            <div class="px-3 py-2 border-b border-gray-200 bg-white flex items-center gap-4 text-sm">
+              <label class="flex items-center gap-2">
+                <input v-model="contactTypes.friends" type="checkbox" />
+                <span>好友 {{ counts.friends }}</span>
+              </label>
+              <label class="flex items-center gap-2">
+                <input v-model="contactTypes.groups" type="checkbox" />
+                <span>群聊 {{ counts.groups }}</span>
+              </label>
+              <label class="flex items-center gap-2">
+                <input v-model="contactTypes.officials" type="checkbox" />
+                <span>公众号 {{ counts.officials }}</span>
+              </label>
+              <span class="ml-auto text-gray-500">总计 {{ counts.total }}</span>
+            </div>
+
+            <div class="flex-1 min-h-0 overflow-auto">
+              <div v-if="loading" class="p-4 text-sm text-gray-500">加载中…</div>
+              <div v-else-if="error" class="p-4 text-sm text-red-500 whitespace-pre-wrap">{{ error }}</div>
+              <div v-else-if="contacts.length === 0" class="p-4 text-sm text-gray-500">暂无联系人</div>
+              <div v-else>
+                <div
+                  v-for="contact in contacts"
+                  :key="contact.username"
+                  class="px-3 py-2 border-b border-gray-100 flex items-center gap-3"
+                >
+                  <div class="w-10 h-10 rounded-md overflow-hidden bg-gray-300 shrink-0" :class="{ 'privacy-blur': privacyMode }">
+                    <img v-if="contact.avatar" :src="contact.avatar" :alt="contact.displayName" class="w-full h-full object-cover" referrerpolicy="no-referrer" />
+                    <div v-else class="w-full h-full flex items-center justify-center text-white text-xs font-bold" style="background-color:#4B5563">{{ contact.displayName?.charAt(0) || '?' }}</div>
+                  </div>
+                  <div class="min-w-0 flex-1" :class="{ 'privacy-blur': privacyMode }">
+                    <div class="text-sm text-gray-900 truncate">{{ contact.displayName }}</div>
+                    <div class="text-xs text-gray-500 truncate">{{ contact.username }}</div>
+                    <div class="text-[11px] text-gray-500 truncate" v-if="contact.type !== 'group' && (contact.region || contact.source)">
+                      <span v-if="contact.region">地区：{{ contact.region }}</span>
+                      <span v-if="contact.region && contact.source"> · </span>
+                      <span
+                        v-if="contact.source"
+                        :title="contact.sourceScene != null ? `来源场景码：${contact.sourceScene}` : ''"
+                      >来源：{{ contact.source }}</span>
+                    </div>
+                  </div>
+                  <div class="text-xs px-2 py-0.5 rounded" :class="typeBadgeClass(contact.type)">
+                    {{ typeLabel(contact.type) }}
+                  </div>
+                </div>
+              </div>
+            </div>
+          </div>
+
+          <div class="bg-white border border-gray-200 rounded-lg p-4 flex flex-col gap-3">
+            <div>
+              <div class="text-base font-medium text-gray-900">导出联系人</div>
+              <div class="text-xs text-gray-500 mt-1">支持 JSON / CSV，默认包含头像链接</div>
+            </div>
+
+            <div class="space-y-2 text-sm">
+              <div class="font-medium text-gray-800">导出格式</div>
+              <label class="flex items-center gap-2"><input v-model="exportFormat" type="radio" value="json" /> JSON</label>
+              <label class="flex items-center gap-2"><input v-model="exportFormat" type="radio" value="csv" /> CSV (Excel)</label>
+            </div>
+
+            <div class="space-y-2 text-sm">
+              <div class="font-medium text-gray-800">导出类型（多选）</div>
+              <label class="flex items-center gap-2"><input v-model="exportTypes.friends" type="checkbox" /> 好友</label>
+              <label class="flex items-center gap-2"><input v-model="exportTypes.groups" type="checkbox" /> 群聊</label>
+              <label class="flex items-center gap-2"><input v-model="exportTypes.officials" type="checkbox" /> 公众号</label>
+            </div>
+
+            <label class="flex items-center gap-2 text-sm">
+              <input v-model="includeAvatarLink" type="checkbox" />
+              导出头像链接
+            </label>
+
+            <div class="space-y-2 text-sm">
+              <div class="font-medium text-gray-800">导出目录</div>
+              <div class="px-2 py-2 rounded border border-gray-200 bg-gray-50 text-xs break-all min-h-[38px]">{{ exportFolder || '未选择' }}</div>
+              <button type="button" class="w-full px-3 py-2 rounded border border-gray-200 hover:bg-gray-50" @click="chooseExportFolder">选择文件夹</button>
+            </div>
+
+            <button
+              type="button"
+              class="mt-2 w-full px-3 py-2 rounded text-white"
+              :class="canExport && !exporting ? 'bg-[#03C160] hover:bg-[#02ad56]' : 'bg-gray-300 cursor-not-allowed'"
+              :disabled="!canExport || exporting"
+              @click="startExport"
+            >
+              {{ exporting ? '导出中…' : '开始导出' }}
+            </button>
+
+            <div v-if="exportMsg" class="text-xs whitespace-pre-wrap" :class="exportOk ? 'text-green-600' : 'text-red-500'">{{ exportMsg }}</div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup>
+useHead({ title: '联系人 - 微信数据分析助手' })
+
+const route = useRoute()
+const api = useApi()
+
+const isChatRoute = computed(() => route.path?.startsWith('/chat'))
+const isSnsRoute = computed(() => route.path?.startsWith('/sns'))
+const isWrappedRoute = computed(() => route.path?.startsWith('/wrapped'))
+
+const PRIVACY_MODE_KEY = 'ui.privacy_mode'
+const privacyMode = ref(false)
+onMounted(() => {
+  if (!process.client) return
+  try {
+    privacyMode.value = localStorage.getItem(PRIVACY_MODE_KEY) === '1'
+  } catch {}
+})
+watch(() => privacyMode.value, (v) => {
+  if (!process.client) return
+  try {
+    localStorage.setItem(PRIVACY_MODE_KEY, v ? '1' : '0')
+  } catch {}
+})
+
+const sidebarMediaBase = process.client ? 'http://localhost:8000' : ''
+
+const availableAccounts = ref([])
+const selectedAccount = ref(null)
+const searchKeyword = ref('')
+
+const contactTypes = reactive({
+  friends: true,
+  groups: true,
+  officials: true,
+})
+
+const contacts = ref([])
+const counts = reactive({
+  friends: 0,
+  groups: 0,
+  officials: 0,
+  total: 0,
+})
+
+const loading = ref(false)
+const error = ref('')
+
+const exportFormat = ref('json')
+const includeAvatarLink = ref(true)
+const exportTypes = reactive({
+  friends: true,
+  groups: true,
+  officials: true,
+})
+const exportFolder = ref('')
+const exportFolderHandle = ref(null)
+const exporting = ref(false)
+const exportMsg = ref('')
+const exportOk = ref(false)
+
+const selfAvatarUrl = computed(() => {
+  const acc = String(selectedAccount.value || '').trim()
+  if (!acc) return ''
+  return `${sidebarMediaBase}/api/chat/avatar?account=${encodeURIComponent(acc)}&username=${encodeURIComponent(acc)}`
+})
+
+const typeLabel = (type) => {
+  if (type === 'friend') return '好友'
+  if (type === 'group') return '群聊'
+  if (type === 'official') return '公众号'
+  return '其他'
+}
+
+const typeBadgeClass = (type) => {
+  if (type === 'friend') return 'bg-blue-100 text-blue-700'
+  if (type === 'group') return 'bg-green-100 text-green-700'
+  if (type === 'official') return 'bg-orange-100 text-orange-700'
+  return 'bg-gray-100 text-gray-600'
+}
+
+const goChat = async () => {
+  await navigateTo('/chat')
+}
+
+const goSns = async () => {
+  await navigateTo('/sns')
+}
+
+const goWrapped = async () => {
+  await navigateTo('/wrapped')
+}
+
+const isDesktopExportRuntime = () => {
+  return !!(process.client && window?.wechatDesktop?.chooseDirectory)
+}
+
+const isWebDirectoryPickerSupported = () => {
+  return !!(process.client && typeof window.showDirectoryPicker === 'function')
+}
+
+const canExport = computed(() => {
+  const hasExportTarget = isDesktopExportRuntime()
+    ? !!exportFolder.value
+    : !!exportFolderHandle.value
+  return !!selectedAccount.value && hasExportTarget && (exportTypes.friends || exportTypes.groups || exportTypes.officials)
+})
+
+const safeExportPart = (value) => {
+  const cleaned = String(value || '').trim().replace(/[^0-9A-Za-z._-]+/g, '_').replace(/^[._-]+|[._-]+$/g, '')
+  return cleaned || 'account'
+}
+
+const buildExportTimestamp = () => {
+  const now = new Date()
+  const pad = (n) => String(n).padStart(2, '0')
+  return `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}_${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`
+}
+
+const escapeCsvCell = (value) => {
+  const text = String(value == null ? '' : value)
+  if (/[",\n\r]/.test(text)) return `"${text.replace(/"/g, '""')}"`
+  return text
+}
+
+const buildExportContactsPayload = async () => {
+  const resp = await api.listChatContacts({
+    account: selectedAccount.value,
+    keyword: searchKeyword.value || '',
+    include_friends: exportTypes.friends,
+    include_groups: exportTypes.groups,
+    include_officials: exportTypes.officials,
+  })
+  const contactsList = Array.isArray(resp?.contacts) ? resp.contacts : []
+  const exportContacts = contactsList.map((item) => {
+    const row = {
+      username: String(item?.username || ''),
+      displayName: String(item?.displayName || ''),
+      remark: String(item?.remark || ''),
+      nickname: String(item?.nickname || ''),
+      alias: String(item?.alias || ''),
+      type: String(item?.type || ''),
+      region: String(item?.region || ''),
+      country: String(item?.country || ''),
+      province: String(item?.province || ''),
+      city: String(item?.city || ''),
+      source: String(item?.source || ''),
+      sourceScene: item?.sourceScene == null ? '' : String(item?.sourceScene),
+    }
+    if (includeAvatarLink.value) {
+      row.avatarLink = String(item?.avatarLink || '')
+    }
+    return row
+  })
+
+  return {
+    account: String(selectedAccount.value || ''),
+    count: exportContacts.length,
+    contacts: exportContacts,
+  }
+}
+
+const writeWebExportFile = async ({ fileName, content }) => {
+  if (!exportFolderHandle.value || typeof exportFolderHandle.value.getFileHandle !== 'function') {
+    throw new Error('未选择浏览器导出目录')
+  }
+  const fileHandle = await exportFolderHandle.value.getFileHandle(fileName, { create: true })
+  const writable = await fileHandle.createWritable()
+  await writable.write(content)
+  await writable.close()
+}
+
+const exportContactsInWeb = async () => {
+  const fmt = String(exportFormat.value || 'json').toLowerCase()
+  if (fmt !== 'json' && fmt !== 'csv') {
+    throw new Error('网页端仅支持 JSON/CSV 导出')
+  }
+  if (!exportFolderHandle.value) {
+    throw new Error('请先选择导出目录')
+  }
+
+  const payload = await buildExportContactsPayload()
+  const fileName = `contacts_${safeExportPart(payload.account)}_${buildExportTimestamp()}.${fmt}`
+
+  if (fmt === 'json') {
+    const jsonPayload = {
+      exportedAt: new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'),
+      account: payload.account,
+      count: payload.count,
+      filters: {
+        keyword: String(searchKeyword.value || ''),
+        contactTypes: {
+          friends: !!exportTypes.friends,
+          groups: !!exportTypes.groups,
+          officials: !!exportTypes.officials,
+        },
+        includeAvatarLink: !!includeAvatarLink.value,
+      },
+      contacts: payload.contacts,
+    }
+    await writeWebExportFile({ fileName, content: JSON.stringify(jsonPayload, null, 2) })
+  } else {
+    const columns = [
+      ['username', '用户名'],
+      ['displayName', '显示名称'],
+      ['remark', '备注'],
+      ['nickname', '昵称'],
+      ['alias', '微信号'],
+      ['type', '类型'],
+      ['region', '地区'],
+      ['country', '国家/地区码'],
+      ['province', '省份'],
+      ['city', '城市'],
+      ['source', '来源'],
+      ['sourceScene', '来源场景码'],
+    ]
+    if (includeAvatarLink.value) {
+      columns.push(['avatarLink', '头像链接'])
+    }
+    const lines = [columns.map(([, label]) => escapeCsvCell(label)).join(',')]
+    for (const row of payload.contacts) {
+      lines.push(columns.map(([key]) => escapeCsvCell(row[key])).join(','))
+    }
+    await writeWebExportFile({ fileName, content: `\uFEFF${lines.join('\n')}` })
+  }
+
+  return {
+    count: payload.count,
+    outputPath: `${exportFolder.value}/${fileName}`,
+  }
+}
+
+const loadAccounts = async () => {
+  try {
+    const resp = await api.listChatAccounts()
+    const accounts = resp?.accounts || []
+    availableAccounts.value = accounts
+    selectedAccount.value = selectedAccount.value || resp?.default_account || accounts[0] || null
+  } catch (e) {
+    availableAccounts.value = []
+    selectedAccount.value = null
+  }
+}
+
+const loadContacts = async () => {
+  if (!selectedAccount.value) {
+    contacts.value = []
+    counts.friends = 0
+    counts.groups = 0
+    counts.officials = 0
+    counts.total = 0
+    return
+  }
+  loading.value = true
+  error.value = ''
+  try {
+    const resp = await api.listChatContacts({
+      account: selectedAccount.value,
+      keyword: searchKeyword.value || '',
+      include_friends: contactTypes.friends,
+      include_groups: contactTypes.groups,
+      include_officials: contactTypes.officials,
+    })
+    contacts.value = Array.isArray(resp?.contacts) ? resp.contacts : []
+    counts.friends = Number(resp?.counts?.friends || 0)
+    counts.groups = Number(resp?.counts?.groups || 0)
+    counts.officials = Number(resp?.counts?.officials || 0)
+    counts.total = Number(resp?.counts?.total || contacts.value.length)
+  } catch (e) {
+    contacts.value = []
+    error.value = e?.message || '加载联系人失败'
+  } finally {
+    loading.value = false
+  }
+}
+
+let keywordTimer = null
+watch(() => searchKeyword.value, () => {
+  if (keywordTimer) clearTimeout(keywordTimer)
+  keywordTimer = setTimeout(() => {
+    void loadContacts()
+  }, 250)
+})
+
+watch(() => [selectedAccount.value, contactTypes.friends, contactTypes.groups, contactTypes.officials], () => {
+  void loadContacts()
+})
+
+const chooseExportFolder = async () => {
+  exportMsg.value = ''
+  exportOk.value = false
+  try {
+    if (!process.client) {
+      exportMsg.value = '当前环境不支持选择导出目录'
+      return
+    }
+
+    if (isDesktopExportRuntime()) {
+      const result = await window.wechatDesktop.chooseDirectory({ title: '选择导出目录' })
+      if (result && !result.canceled && Array.isArray(result.filePaths) && result.filePaths.length > 0) {
+        exportFolder.value = String(result.filePaths[0] || '')
+        exportFolderHandle.value = null
+      }
+      return
+    }
+
+    if (isWebDirectoryPickerSupported()) {
+      const handle = await window.showDirectoryPicker()
+      if (handle) {
+        exportFolderHandle.value = handle
+        exportFolder.value = `浏览器目录：${String(handle.name || '已选择')}`
+      }
+      return
+    }
+
+    exportMsg.value = '当前浏览器不支持目录选择，请使用桌面端或 Chromium 新版浏览器'
+  } catch (e) {
+    exportMsg.value = e?.message || '选择文件夹失败'
+    exportOk.value = false
+  }
+}
+
+const startExport = async () => {
+  exportMsg.value = ''
+  exportOk.value = false
+
+  if (!canExport.value) {
+    exportMsg.value = '请先选择账号、导出目录，并至少勾选一种联系人类型'
+    return
+  }
+
+  exporting.value = true
+  try {
+    const resp = isDesktopExportRuntime()
+      ? await api.exportChatContacts({
+          account: selectedAccount.value,
+          output_dir: exportFolder.value,
+          format: exportFormat.value,
+          include_avatar_link: includeAvatarLink.value,
+          keyword: searchKeyword.value || '',
+          contact_types: {
+            friends: exportTypes.friends,
+            groups: exportTypes.groups,
+            officials: exportTypes.officials,
+          }
+        })
+      : await exportContactsInWeb()
+    exportOk.value = true
+    exportMsg.value = `导出成功：${resp?.outputPath || ''}\n共 ${Number(resp?.count || 0)} 个联系人`
+  } catch (e) {
+    exportOk.value = false
+    exportMsg.value = e?.message || '导出失败'
+  } finally {
+    exporting.value = false
+  }
+}
+
+onMounted(async () => {
+  await loadAccounts()
+  await loadContacts()
+})
+</script>
+
+<style scoped>
+.privacy-blur {
+  filter: blur(9px);
+  transition: filter 0.2s ease;
+}
+
+.privacy-blur:hover {
+  filter: none;
+}
+</style>
@@ -26,24 +26,40 @@
            <!-- 密钥输入 -->
            <div>
              <label for="key" class="block text-sm font-medium text-[#000000e6] mb-2">
-                <svg class="w-4 h-4 inline mr-1" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                  <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 7a2 2 0 012 2m4 0a6 6 0 01-7.743 5.743L11 17H9v2H7v2H4a1 1 0 01-1-1v-2.586a1 1 0 01.293-.707l5.964-5.964A6 6 0 1121 9z"/>
-                </svg>
                解密密钥 <span class="text-red-500">*</span>
              </label>
-              <div class="relative">
-                <input
-                  id="key"
-                  v-model="formData.key"
-                  type="text"
-                  placeholder="请输入64位十六进制密钥"
-                  class="w-full px-4 py-3 bg-white border border-[#EDEDED] rounded-lg font-mono text-sm focus:outline-none focus:ring-2 focus:ring-[#07C160] focus:border-transparent transition-all duration-200"
-                  :class="{ 'border-red-500': formErrors.key }"
-                  required
-                />
-                <div v-if="formData.key" class="absolute right-3 top-1/2 transform -translate-y-1/2">
-                  <span class="text-xs text-[#7F7F7F]">{{ formData.key.length }}/64</span>
+
+              <div class="flex gap-3">
+                <div class="relative flex-1">
+                  <input
+                      id="key"
+                      v-model="formData.key"
+                      type="text"
+                      placeholder="请输入64位十六进制密钥"
+                      class="w-full px-4 py-3 bg-white border border-[#EDEDED] rounded-lg font-mono text-sm focus:outline-none focus:ring-2 focus:ring-[#07C160] focus:border-transparent transition-all duration-200"
+                      :class="{ 'border-red-500': formErrors.key }"
+                      required
+                  />
+                  <div v-if="formData.key" class="absolute right-3 top-1/2 transform -translate-y-1/2">
+                    <span class="text-xs text-[#7F7F7F]">{{ formData.key.length }}/64</span>
+                  </div>
                </div>
+
+                <button
+                    type="button"
+                    @click="handleGetDbKey"
+                    :disabled="isGettingDbKey"
+                    class="flex-none inline-flex items-center px-4 py-3 bg-[#07C160] text-white rounded-lg text-sm font-medium hover:bg-[#06AD56] transition-all duration-200 disabled:opacity-50 disabled:cursor-wait whitespace-nowrap"
+                >
+                  <svg v-if="isGettingDbKey" class="animate-spin -ml-1 mr-2 h-4 w-4 text-white" fill="none" viewBox="0 0 24 24">
+                    <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
+                    <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z"></path>
+                  </svg>
+                  <svg v-else class="w-4 h-4 mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 4v5h.582m15.356 2A8.001 8.001 0 004.582 9m0 0H9m11 11v-5h-.581m0 0a8.003 8.003 0 01-15.357-2m15.357 2H15" />
+                  </svg>
+                  {{ isGettingDbKey ? '获取中...' : '自动获取' }}
+                </button>
              </div>
              <p v-if="formErrors.key" class="mt-1 text-sm text-red-600 flex items-center">
                <svg class="w-4 h-4 mr-1" fill="none" stroke="currentColor" viewBox="0 0 24 24">
@@ -55,7 +71,7 @@
                <svg class="w-4 h-4 mr-1 text-[#10AEEF]" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                  <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z"/>
                </svg>
-                使用 <a href="https://github.com/ycccccccy/wx_key" target="_blank" class="text-[#07C160] hover:text-[#06AD56]">wx_key</a> 等工具获取的64位十六进制字符串
+                尝试自动获取，或者使用 <a href="https://github.com/ycccccccy/wx_key" target="_blank" class="text-[#07C160] hover:text-[#06AD56]">wx_key</a> 等工具获取的64位十六进制字符串
              </p>
            </div>
            
@@ -131,6 +147,26 @@
          <!-- 填写密钥 -->
          <div class="mb-6">
            <div class="bg-gray-50 rounded-lg p-4">
+
+              <div class="flex justify-between items-center mb-4 pb-3 border-b border-gray-200">
+                <span class="text-sm font-medium text-gray-500">手动输入或通过微信获取</span>
+                <button
+                    type="button"
+                    @click="handleGetImageKey"
+                    :disabled="isGettingImageKey"
+                    class="flex-none inline-flex items-center px-4 py-3 bg-[#07C160] text-white rounded-lg text-sm font-medium hover:bg-[#06AD56] transition-all duration-200 disabled:opacity-50 disabled:cursor-wait whitespace-nowrap"
+                >
+                  <svg v-if="isGettingImageKey" class="animate-spin -ml-1 mr-2 h-4 w-4 text-white" fill="none" viewBox="0 0 24 24">
+                    <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
+                    <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z"></path>
+                  </svg>
+                  <svg v-else class="w-4 h-4 mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 4v5h.582m15.356 2A8.001 8.001 0 004.582 9m0 0H9m11 11v-5h-.581m0 0a8.003 8.003 0 01-15.357-2m15.357 2H15" />
+                  </svg>
+                  {{ isGettingImageKey ? '正在获取...' : '自动获取' }}
+                </button>
+              </div>
+
              <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
                <div>
                  <label class="block text-sm font-medium text-[#000000e6] mb-2">XOR（必填）</label>
@@ -158,7 +194,7 @@
                <svg class="w-4 h-4 mr-1 text-[#10AEEF]" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                  <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z"/>
                </svg>
-                使用 <a href="https://github.com/ycccccccy/wx_key" target="_blank" class="text-[#07C160] hover:text-[#06AD56]">wx_key</a> 获取图片密钥；AES 可选（V4-V2 需要）
+                尝试自动获取，或使用 <a href="https://github.com/ycccccccy/wx_key" target="_blank" class="text-[#07C160] hover:text-[#06AD56]">wx_key</a> 获取图片密钥；AES 可选（V4-V2 需要）
              </p>
            </div>
          </div>
@@ -325,6 +361,19 @@
          </div>
        </div>
      </div>
+
+      <!-- 警告渲染 -->
+      <transition name="fade">
+        <div v-if="warning" class="bg-amber-50 border border-amber-200 rounded-lg p-4 mt-6 flex items-start">
+          <svg class="h-5 w-5 mr-2 flex-shrink-0 text-amber-500" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"/>
+          </svg>
+          <div>
+            <p class="font-semibold text-amber-800">温馨提示</p>
+            <p class="text-sm mt-1 text-amber-700">{{ warning }}</p>
+          </div>
+        </div>
+      </transition>
    
      <!-- 错误提示 -->
      <transition name="fade">
@@ -367,12 +416,15 @@
 import { ref, reactive, computed, onMounted } from 'vue'
 import { useApi } from '~/composables/useApi'

-const { decryptDatabase, saveMediaKeys, getSavedKeys } = useApi()
+const { decryptDatabase, saveMediaKeys, getSavedKeys, getDbKey, getImageKey, getWxStatus } = useApi()

 const loading = ref(false)
 const error = ref('')
+const warning = ref('') // 警告，用于密钥提示
 const currentStep = ref(0)
 const mediaAccount = ref('')
+const isGettingDbKey = ref(false)
+const isGettingImageKey = ref(false)

 // 步骤定义
 const steps = [
@@ -453,10 +505,89 @@ const prefillKeysForAccount = async (account) => {
  }
 }

+const handleGetDbKey = async () => {
+  if (isGettingDbKey.value) return
+  isGettingDbKey.value = true
+
+  error.value = ''
+  warning.value = ''
+  formErrors.key = ''
+
+  try {
+    const statusRes = await getWxStatus() // pid不是主进程，但是没关系
+    const wxStatus = statusRes?.wx_status
+
+    if (wxStatus?.is_running) {
+      warning.value = '检测到微信正在运行，5秒后将终止进程并重启以获取密钥！！'
+      await new Promise(resolve => setTimeout(resolve, 5000))
+    } else {
+      // 没有逻辑
+    }
+
+    warning.value = '正在启动微信以获取密钥，请确保微信未开启“自动登录”，并在启动后 1 分钟内完成登录操作。'
+
+    const res = await getDbKey()
+
+    if (res && res.status === 0) {
+      if (res.data?.db_key) {
+        formData.key = res.data.db_key
+        warning.value = ''
+      }
+
+      if (res.errmsg && res.errmsg !== 'ok') {
+        warning.value = res.errmsg
+      }
+    } else {
+      error.value = '获取失败: ' + (res?.errmsg || '未知错误')
+    }
+  } catch (e) {
+    console.error(e)
+    error.value = '系统错误: ' + e.message
+  } finally {
+    isGettingDbKey.value = false
+  }
+}
+
+const handleGetImageKey = async () => {
+  if (isGettingImageKey.value) return
+  isGettingImageKey.value = true
+  manualKeyErrors.xor_key = ''
+  manualKeyErrors.aes_key = ''
+
+  error.value = ''
+  warning.value = ''
+
+  try {
+    const res = await getImageKey()
+
+    if (res && res.status === 0) {
+      if (res.data?.aes_key) {
+        manualKeys.aes_key = res.data.aes_key
+      }
+      if (res.data?.xor_key) {
+        // 后端记得处理为16进制再返回！！！
+        manualKeys.xor_key = res.data.xor_key
+      }
+
+      if (res.errmsg && res.errmsg !== 'ok') {
+        error.value = res.errmsg
+      }
+    } else {
+      error.value = '获取失败: ' + (res?.errmsg || '未知错误')
+    }
+  } catch (e) {
+    console.error(e)
+    error.value = '系统错误: ' + e.message
+  } finally {
+    isGettingImageKey.value = false
+  }
+}
+
 const applyManualKeys = () => {
  manualKeyErrors.xor_key = ''
  manualKeyErrors.aes_key = ''
  error.value = ''
+  warning.value = ''

  const aes = normalizeAesKey(manualKeys.aes_key)
  if (!aes.ok) {
@@ -550,6 +681,7 @@ const handleDecrypt = async () => {
  
  loading.value = true
  error.value = ''
+  warning.value = ''
  
  try {
    const result = await decryptDatabase({
@@ -596,6 +728,7 @@ const decryptAllImages = async () => {
  mediaDecrypting.value = true
  mediaDecryptResult.value = null
  error.value = ''
+  warning.value = ''
  
  // 重置进度
  decryptProgress.current = 0
@@ -671,6 +804,7 @@ const decryptAllImages = async () => {
 // 从密钥步骤进入图片解密步骤
 const goToMediaDecryptStep = async () => {
  error.value = ''
+  warning.value = ''
  // 校验并应用（未填写则允许直接进入，后端会使用已保存密钥或报错提示）
  const ok = applyManualKeys()
  if (!ok || manualKeyErrors.xor_key || manualKeyErrors.aes_key) return
@@ -68,6 +68,26 @@
          </div>
        </div>

+        <!-- 联系人图标 -->
+        <div
+          class="w-full h-[var(--sidebar-rail-step)] flex items-center justify-center cursor-pointer group"
+          title="联系人"
+          @click="goContacts"
+        >
+          <div
+            class="w-[var(--sidebar-rail-btn)] h-[var(--sidebar-rail-btn)] rounded-md flex items-center justify-center transition-colors bg-transparent group-hover:bg-[#E1E1E1]"
+          >
+            <div class="w-[var(--sidebar-rail-icon)] h-[var(--sidebar-rail-icon)]" :class="isContactsRoute ? 'text-[#07b75b]' : 'text-[#5d5d5d]'">
+              <svg class="w-full h-full" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+                <path d="M17 21v-2a4 4 0 0 0-4-4H7a4 4 0 0 0-4 4v2" />
+                <circle cx="10" cy="7" r="4" />
+                <path d="M23 21v-2a4 4 0 0 0-3-3.87" />
+                <path d="M16 3.13a4 4 0 0 1 0 7.75" />
+              </svg>
+            </div>
+          </div>
+        </div>
+
        <!-- 年度总结图标 -->
        <div
          class="w-full h-[var(--sidebar-rail-step)] flex items-center justify-center cursor-pointer group"
@@ -411,6 +431,7 @@ const route = useRoute()

 const isChatRoute = computed(() => route.path?.startsWith('/chat'))
 const isSnsRoute = computed(() => route.path?.startsWith('/sns'))
+const isContactsRoute = computed(() => route.path?.startsWith('/contacts'))
 const isWrappedRoute = computed(() => route.path?.startsWith('/wrapped'))

 // 隐私模式（聊天/朋友圈共用本地开关）
@@ -1051,6 +1072,10 @@ const goSns = async () => {
  await navigateTo('/sns')
 }

+const goContacts = async () => {
+  await navigateTo('/contacts')
+}
+
 const goWrapped = async () => {
  await navigateTo('/wrapped')
 }
@@ -1,14 +1,14 @@
 <template>
  <div
    ref="deckEl"
-    class="relative h-screen w-full overflow-hidden transition-colors duration-500"
+    class="wrapped-deck-root relative h-screen w-full overflow-hidden transition-colors duration-500"
    :class="themeClass"
    :style="{ backgroundColor: currentBg }"
  >
    <!-- PPT 风格：单张卡片占据全页面，鼠标滚轮切换 -->
    <WrappedDeckBackground />
-    <!-- CRT 叠加层仅用于“像素屏/终端”类主题，Win98 等桌面 GUI 主题不应开启 -->
-    <WrappedCRTOverlay v-if="theme === 'gameboy' || theme === 'dos'" />
+    <!-- CRT 叠加层仅用于“像素屏”类主题，Win98 等桌面 GUI 主题不应开启 -->
+    <WrappedCRTOverlay v-if="theme === 'gameboy'" />

    <!-- 左上角：刷新 + 复古模式开关 -->
    <div class="absolute top-6 left-6 z-20 select-none">
@@ -81,13 +81,19 @@
    </div>

    <div
-      class="relative z-10 h-full w-full will-change-transform transition-transform duration-700 ease-[cubic-bezier(0.22,1,0.36,1)]"
+      class="relative h-full w-full will-change-transform transition-transform duration-700 ease-[cubic-bezier(0.22,1,0.36,1)]"
+      :class="deckTrackClass"
      :style="trackStyle"
    >
      <!-- Cover -->
      <section class="w-full" :style="slideStyle">
        <div class="h-full w-full relative">
-          <WrappedHero :year="year" variant="slide" class="h-full w-full" />
+          <WrappedHero
+            :year="year"
+            :card-manifests="report?.cards || []"
+            variant="slide"
+            class="h-full w-full"
+          />
        </div>
      </section>

@@ -196,7 +202,7 @@ const year = ref(Number(route.query?.year) || new Date().getFullYear())
 // 分享视图不展示账号信息：默认让后端自动选择；需要指定时可用 query ?account=wxid_xxx
 const account = ref(typeof route.query?.account === 'string' ? route.query.account : '')

-// 主题管理：modern / gameboy / dos
+// 主题管理：modern / gameboy / win98
 const { theme, cycleTheme, isRetro, themeClass } = useWrappedTheme()

 const accounts = ref([])
@@ -227,12 +233,12 @@ const activeIndex = ref(0)
 const navLocked = ref(false)
 const wheelAcc = ref(0)
 let navUnlockTimer = null
+let deckResizeObserver = null

 // 各主题的背景颜色
 const THEME_BG = {
  off: '#F3FFF8',       // Modern: 浅绿
  gameboy: '#9bbc0f',   // Game Boy: 亮绿
-  dos: '#0a0a0a',       // DOS: 黑色
  win98: '#008080'      // Win98: 经典桌面青色
 }

@@ -252,6 +258,14 @@ const taskbarTitle = computed(() => {
 })

 const currentBg = computed(() => THEME_BG[theme.value] || THEME_BG.off)
+const deckTrackClass = computed(() => 'z-10')
+
+const applyViewportBg = () => {
+  if (!import.meta.client) return
+  const bg = currentBg.value
+  document.documentElement.style.backgroundColor = bg
+  document.body.style.backgroundColor = bg
+}

 const slideStyle = computed(() => (
  viewportHeight.value > 0 ? { height: `${viewportHeight.value}px` } : { height: '100%' }
@@ -376,7 +390,7 @@ const onTouchEnd = (e) => {
 }

 const updateViewport = () => {
-  const h = deckEl.value?.clientHeight || window.innerHeight || 0
+  const h = Math.round(deckEl.value?.getBoundingClientRect?.().height || deckEl.value?.clientHeight || window.innerHeight || 0)
  if (!h) return
  // Reserve space for the Win98 taskbar at the bottom.
  const offset = theme.value === 'win98' ? 40 : 0
@@ -525,7 +539,14 @@ watch(activeIndex, (i) => {
 })

 onMounted(async () => {
+  applyViewportBg()
  updateViewport()
+  if (import.meta.client && typeof ResizeObserver !== 'undefined' && deckEl.value) {
+    deckResizeObserver = new ResizeObserver(() => {
+      updateViewport()
+    })
+    deckResizeObserver.observe(deckEl.value)
+  }
  window.addEventListener('resize', updateViewport)
  // passive:false 才能 preventDefault，避免外层容器产生滚动/回弹
  deckEl.value?.addEventListener('wheel', onWheel, { passive: false })
@@ -542,10 +563,17 @@ onMounted(async () => {

 // Theme switch may change reserved UI space (e.g., Win98 taskbar)
 watch(theme, () => {
+  applyViewportBg()
  updateViewport()
 })

 onBeforeUnmount(() => {
+  if (import.meta.client) {
+    document.documentElement.style.backgroundColor = ''
+    document.body.style.backgroundColor = ''
+  }
+  deckResizeObserver?.disconnect()
+  deckResizeObserver = null
  window.removeEventListener('resize', updateViewport)
  deckEl.value?.removeEventListener('wheel', onWheel)
  window.removeEventListener('keydown', onKeydown)
@@ -573,3 +601,15 @@ watch(year, async (newYear, oldYear) => {
  await reload()
 })
 </script>
+
+<style>
+.wrapped-deck-root {
+  height: 100dvh;
+  min-height: 100dvh;
+}
+
+.wechat-desktop .wechat-desktop-content > .wrapped-deck-root {
+  height: 100%;
+  min-height: 100%;
+}
+</style>
@@ -1,6 +1,6 @@
 [project]
 name = "wechat-decrypt-tool"
-version = "0.2.0"
+version = "0.2.1"
 description = "Modern WeChat database decryption tool with React frontend"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -19,6 +19,9 @@ dependencies = [
    "zstandard>=0.23.0",
    "pilk>=0.2.4",
    "pypinyin>=0.53.0",
+    "wx_key",
+    "packaging",
+    "httpx",
 ]

 [project.optional-dependencies]
@@ -40,3 +43,6 @@ include = [
    "src/wechat_decrypt_tool/native/wcdb_api.dll",
    "src/wechat_decrypt_tool/native/WCDB.dll",
 ]
+
+[tool.uv]
+find-links = ["./tools/key_wheels/"]
@@ -13,6 +13,7 @@ from .logging_config import setup_logging, get_logger
 from .path_fix import PathFixRoute
 from .chat_realtime_autosync import CHAT_REALTIME_AUTOSYNC
 from .routers.chat import router as _chat_router
+from .routers.chat_contacts import router as _chat_contacts_router
 from .routers.chat_export import router as _chat_export_router
 from .routers.chat_media import router as _chat_media_router
 from .routers.decrypt import router as _decrypt_router
@@ -52,6 +53,7 @@ app.include_router(_decrypt_router)
 app.include_router(_keys_router)
 app.include_router(_media_router)
 app.include_router(_chat_router)
+app.include_router(_chat_contacts_router)
 app.include_router(_chat_export_router)
 app.include_router(_chat_media_router)
 app.include_router(_sns_router)
@@ -0,0 +1,454 @@
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import sqlite3
+import time
+from email.utils import formatdate
+from pathlib import Path
+from typing import Any, Optional
+from urllib.parse import urlsplit, urlunsplit
+
+from .app_paths import get_output_dir
+from .logging_config import get_logger
+
+logger = get_logger(__name__)
+
+AVATAR_CACHE_TTL_SECONDS = 7 * 24 * 60 * 60
+
+
+def is_avatar_cache_enabled() -> bool:
+    v = str(os.environ.get("WECHAT_TOOL_AVATAR_CACHE_ENABLED", "1") or "").strip().lower()
+    return v not in {"", "0", "false", "off", "no"}
+
+
+def get_avatar_cache_root_dir() -> Path:
+    return get_output_dir() / "avatar_cache"
+
+
+def _safe_segment(value: str) -> str:
+    cleaned = re.sub(r"[^0-9A-Za-z._-]+", "_", str(value or "").strip())
+    cleaned = cleaned.strip("._-")
+    return cleaned or "default"
+
+
+def _account_layout(account: str) -> tuple[Path, Path, Path, Path]:
+    account_dir = get_avatar_cache_root_dir() / _safe_segment(account)
+    files_dir = account_dir / "files"
+    tmp_dir = account_dir / "tmp"
+    db_path = account_dir / "avatar_cache.db"
+    return account_dir, files_dir, tmp_dir, db_path
+
+
+def _ensure_account_layout(account: str) -> tuple[Path, Path, Path, Path]:
+    account_dir, files_dir, tmp_dir, db_path = _account_layout(account)
+    account_dir.mkdir(parents=True, exist_ok=True)
+    files_dir.mkdir(parents=True, exist_ok=True)
+    tmp_dir.mkdir(parents=True, exist_ok=True)
+    return account_dir, files_dir, tmp_dir, db_path
+
+
+def _connect(account: str) -> sqlite3.Connection:
+    _, _, _, db_path = _ensure_account_layout(account)
+    conn = sqlite3.connect(str(db_path), timeout=5)
+    conn.row_factory = sqlite3.Row
+    _ensure_schema(conn)
+    return conn
+
+
+def _ensure_schema(conn: sqlite3.Connection) -> None:
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS avatar_cache_entries (
+            account TEXT NOT NULL,
+            cache_key TEXT NOT NULL,
+            source_kind TEXT NOT NULL,
+            username TEXT NOT NULL DEFAULT '',
+            source_url TEXT NOT NULL DEFAULT '',
+            source_md5 TEXT NOT NULL DEFAULT '',
+            source_update_time INTEGER NOT NULL DEFAULT 0,
+            rel_path TEXT NOT NULL DEFAULT '',
+            media_type TEXT NOT NULL DEFAULT 'application/octet-stream',
+            size_bytes INTEGER NOT NULL DEFAULT 0,
+            etag TEXT NOT NULL DEFAULT '',
+            last_modified TEXT NOT NULL DEFAULT '',
+            fetched_at INTEGER NOT NULL DEFAULT 0,
+            checked_at INTEGER NOT NULL DEFAULT 0,
+            expires_at INTEGER NOT NULL DEFAULT 0,
+            PRIMARY KEY (account, cache_key)
+        )
+        """
+    )
+    conn.execute(
+        "CREATE INDEX IF NOT EXISTS idx_avatar_cache_entries_account_username ON avatar_cache_entries(account, username)"
+    )
+    conn.execute(
+        "CREATE INDEX IF NOT EXISTS idx_avatar_cache_entries_account_source ON avatar_cache_entries(account, source_kind, source_url)"
+    )
+    conn.commit()
+
+
+def _row_to_dict(row: Optional[sqlite3.Row]) -> Optional[dict[str, Any]]:
+    if row is None:
+        return None
+    out: dict[str, Any] = {}
+    for k in row.keys():
+        out[str(k)] = row[k]
+    return out
+
+
+def normalize_avatar_source_url(url: str) -> str:
+    raw = str(url or "").strip()
+    if not raw:
+        return ""
+    try:
+        p = urlsplit(raw)
+    except Exception:
+        return raw
+    scheme = str(p.scheme or "").lower()
+    host = str(p.hostname or "").lower()
+    if not scheme or not host:
+        return raw
+    netloc = host
+    if p.port:
+        netloc = f"{host}:{int(p.port)}"
+    path = p.path or "/"
+    return urlunsplit((scheme, netloc, path, p.query or "", ""))
+
+
+def cache_key_for_avatar_user(username: str) -> str:
+    u = str(username or "").strip()
+    return hashlib.sha1(f"user:{u}".encode("utf-8", errors="ignore")).hexdigest()
+
+
+def cache_key_for_avatar_url(url: str) -> str:
+    u = normalize_avatar_source_url(url)
+    return hashlib.sha1(f"url:{u}".encode("utf-8", errors="ignore")).hexdigest()
+
+
+def get_avatar_cache_entry(account: str, cache_key: str) -> Optional[dict[str, Any]]:
+    if (not is_avatar_cache_enabled()) or (not cache_key):
+        return None
+    try:
+        conn = _connect(account)
+    except Exception:
+        return None
+    try:
+        row = conn.execute(
+            "SELECT * FROM avatar_cache_entries WHERE account = ? AND cache_key = ? LIMIT 1",
+            (str(account or ""), str(cache_key or "")),
+        ).fetchone()
+        return _row_to_dict(row)
+    except Exception:
+        return None
+    finally:
+        try:
+            conn.close()
+        except Exception:
+            pass
+
+
+def get_avatar_cache_user_entry(account: str, username: str) -> Optional[dict[str, Any]]:
+    if not username:
+        return None
+    return get_avatar_cache_entry(account, cache_key_for_avatar_user(username))
+
+
+def get_avatar_cache_url_entry(account: str, source_url: str) -> Optional[dict[str, Any]]:
+    if not source_url:
+        return None
+    return get_avatar_cache_entry(account, cache_key_for_avatar_url(source_url))
+
+
+def resolve_avatar_cache_entry_path(account: str, entry: Optional[dict[str, Any]]) -> Optional[Path]:
+    if not entry:
+        return None
+    rel = str(entry.get("rel_path") or "").strip().replace("\\", "/")
+    if not rel:
+        return None
+    account_dir, _, _, _ = _account_layout(account)
+    p = account_dir / rel
+    try:
+        account_dir_resolved = account_dir.resolve()
+        p_resolved = p.resolve()
+        if p_resolved != account_dir_resolved and account_dir_resolved not in p_resolved.parents:
+            return None
+        return p_resolved
+    except Exception:
+        return p
+
+
+def avatar_cache_entry_file_exists(account: str, entry: Optional[dict[str, Any]]) -> Optional[Path]:
+    p = resolve_avatar_cache_entry_path(account, entry)
+    if not p:
+        return None
+    try:
+        if p.exists() and p.is_file():
+            return p
+    except Exception:
+        return None
+    return None
+
+
+def avatar_cache_entry_is_fresh(entry: Optional[dict[str, Any]], now_ts: Optional[int] = None) -> bool:
+    if not entry:
+        return False
+    try:
+        expires = int(entry.get("expires_at") or 0)
+    except Exception:
+        expires = 0
+    if expires <= 0:
+        return False
+    now0 = int(now_ts or time.time())
+    return expires > now0
+
+
+def _guess_ext(media_type: str) -> str:
+    mt = str(media_type or "").strip().lower()
+    if mt == "image/jpeg":
+        return "jpg"
+    if mt == "image/png":
+        return "png"
+    if mt == "image/gif":
+        return "gif"
+    if mt == "image/webp":
+        return "webp"
+    if mt == "image/bmp":
+        return "bmp"
+    if mt == "image/svg+xml":
+        return "svg"
+    if mt == "image/avif":
+        return "avif"
+    if mt.startswith("image/"):
+        return mt.split("/", 1)[1].split("+", 1)[0].split(";", 1)[0] or "img"
+    return "dat"
+
+
+def _http_date_from_ts(ts: Optional[int]) -> str:
+    try:
+        t = int(ts or 0)
+    except Exception:
+        t = 0
+    if t <= 0:
+        return ""
+    try:
+        return formatdate(timeval=float(t), usegmt=True)
+    except Exception:
+        return ""
+
+
+def upsert_avatar_cache_entry(
+    account: str,
+    *,
+    cache_key: str,
+    source_kind: str,
+    username: str = "",
+    source_url: str = "",
+    source_md5: str = "",
+    source_update_time: int = 0,
+    rel_path: str = "",
+    media_type: str = "application/octet-stream",
+    size_bytes: int = 0,
+    etag: str = "",
+    last_modified: str = "",
+    fetched_at: Optional[int] = None,
+    checked_at: Optional[int] = None,
+    expires_at: Optional[int] = None,
+) -> Optional[dict[str, Any]]:
+    if (not is_avatar_cache_enabled()) or (not cache_key):
+        return None
+
+    acct = str(account or "").strip()
+    ck = str(cache_key or "").strip()
+    sk = str(source_kind or "").strip().lower()
+    if not acct or not ck or not sk:
+        return None
+
+    source_url_norm = normalize_avatar_source_url(source_url) if source_url else ""
+
+    now_ts = int(time.time())
+    fetched = int(fetched_at if fetched_at is not None else now_ts)
+    checked = int(checked_at if checked_at is not None else now_ts)
+    expire_ts = int(expires_at if expires_at is not None else (checked + AVATAR_CACHE_TTL_SECONDS))
+
+    try:
+        conn = _connect(acct)
+    except Exception as e:
+        logger.warning(f"[avatar_cache_error] open db failed account={acct} err={e}")
+        return None
+    try:
+        conn.execute(
+            """
+            INSERT INTO avatar_cache_entries (
+                account, cache_key, source_kind, username, source_url,
+                source_md5, source_update_time, rel_path, media_type, size_bytes,
+                etag, last_modified, fetched_at, checked_at, expires_at
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            ON CONFLICT(account, cache_key) DO UPDATE SET
+                source_kind=excluded.source_kind,
+                username=excluded.username,
+                source_url=excluded.source_url,
+                source_md5=excluded.source_md5,
+                source_update_time=excluded.source_update_time,
+                rel_path=excluded.rel_path,
+                media_type=excluded.media_type,
+                size_bytes=excluded.size_bytes,
+                etag=excluded.etag,
+                last_modified=excluded.last_modified,
+                fetched_at=excluded.fetched_at,
+                checked_at=excluded.checked_at,
+                expires_at=excluded.expires_at
+            """,
+            (
+                acct,
+                ck,
+                sk,
+                str(username or "").strip(),
+                source_url_norm,
+                str(source_md5 or "").strip().lower(),
+                int(source_update_time or 0),
+                str(rel_path or "").strip().replace("\\", "/"),
+                str(media_type or "application/octet-stream").strip() or "application/octet-stream",
+                int(size_bytes or 0),
+                str(etag or "").strip(),
+                str(last_modified or "").strip(),
+                fetched,
+                checked,
+                expire_ts,
+            ),
+        )
+        conn.commit()
+        row = conn.execute(
+            "SELECT * FROM avatar_cache_entries WHERE account = ? AND cache_key = ? LIMIT 1",
+            (acct, ck),
+        ).fetchone()
+        return _row_to_dict(row)
+    except Exception as e:
+        logger.warning(f"[avatar_cache_error] upsert failed account={acct} cache_key={ck} err={e}")
+        return None
+    finally:
+        try:
+            conn.close()
+        except Exception:
+            pass
+
+
+def touch_avatar_cache_entry(account: str, cache_key: str, *, ttl_seconds: int = AVATAR_CACHE_TTL_SECONDS) -> bool:
+    if (not is_avatar_cache_enabled()) or (not cache_key):
+        return False
+    now_ts = int(time.time())
+    try:
+        conn = _connect(account)
+    except Exception:
+        return False
+    try:
+        conn.execute(
+            "UPDATE avatar_cache_entries SET checked_at = ?, expires_at = ? WHERE account = ? AND cache_key = ?",
+            (now_ts, now_ts + max(60, int(ttl_seconds or AVATAR_CACHE_TTL_SECONDS)), str(account or ""), str(cache_key or "")),
+        )
+        conn.commit()
+        return True
+    except Exception:
+        return False
+    finally:
+        try:
+            conn.close()
+        except Exception:
+            pass
+
+
+def write_avatar_cache_payload(
+    account: str,
+    *,
+    source_kind: str,
+    username: str = "",
+    source_url: str = "",
+    payload: bytes,
+    media_type: str,
+    source_md5: str = "",
+    source_update_time: int = 0,
+    etag: str = "",
+    last_modified: str = "",
+    ttl_seconds: int = AVATAR_CACHE_TTL_SECONDS,
+) -> tuple[Optional[dict[str, Any]], Optional[Path]]:
+    if (not is_avatar_cache_enabled()) or (not payload):
+        return None, None
+
+    acct = str(account or "").strip()
+    sk = str(source_kind or "").strip().lower()
+    if not acct or sk not in {"user", "url"}:
+        return None, None
+
+    source_url_norm = normalize_avatar_source_url(source_url) if source_url else ""
+    if sk == "user":
+        cache_key = cache_key_for_avatar_user(username)
+    else:
+        cache_key = cache_key_for_avatar_url(source_url_norm)
+
+    digest = hashlib.sha1(bytes(payload)).hexdigest()
+    ext = _guess_ext(media_type)
+    rel_path = f"files/{digest[:2]}/{digest}.{ext}"
+
+    try:
+        account_dir, _, tmp_dir, _ = _ensure_account_layout(acct)
+    except Exception as e:
+        logger.warning(f"[avatar_cache_error] ensure dirs failed account={acct} err={e}")
+        return None, None
+
+    abs_path = account_dir / rel_path
+    try:
+        abs_path.parent.mkdir(parents=True, exist_ok=True)
+        if (not abs_path.exists()) or (int(abs_path.stat().st_size) != len(payload)):
+            tmp_path = tmp_dir / f"{digest}.{time.time_ns()}.tmp"
+            tmp_path.write_bytes(payload)
+            os.replace(str(tmp_path), str(abs_path))
+    except Exception as e:
+        logger.warning(f"[avatar_cache_error] write file failed account={acct} path={abs_path} err={e}")
+        return None, None
+
+    if (not etag) and digest:
+        etag = f'"{digest}"'
+    if (not last_modified) and source_update_time:
+        last_modified = _http_date_from_ts(source_update_time)
+    if not last_modified:
+        last_modified = _http_date_from_ts(int(time.time()))
+
+    entry = upsert_avatar_cache_entry(
+        acct,
+        cache_key=cache_key,
+        source_kind=sk,
+        username=username,
+        source_url=source_url_norm,
+        source_md5=source_md5,
+        source_update_time=int(source_update_time or 0),
+        rel_path=rel_path,
+        media_type=media_type,
+        size_bytes=len(payload),
+        etag=etag,
+        last_modified=last_modified,
+        fetched_at=int(time.time()),
+        checked_at=int(time.time()),
+        expires_at=int(time.time()) + max(60, int(ttl_seconds or AVATAR_CACHE_TTL_SECONDS)),
+    )
+    if not entry:
+        return None, None
+    return entry, abs_path
+
+
+def build_avatar_cache_response_headers(
+    entry: Optional[dict[str, Any]], *, max_age: int = AVATAR_CACHE_TTL_SECONDS
+) -> dict[str, str]:
+    headers: dict[str, str] = {
+        "Cache-Control": f"public, max-age={int(max_age)}",
+    }
+    if not entry:
+        return headers
+    etag = str(entry.get("etag") or "").strip()
+    last_modified = str(entry.get("last_modified") or "").strip()
+    if etag:
+        headers["ETag"] = etag
+    if last_modified:
+        headers["Last-Modified"] = last_modified
+    return headers
+
@@ -74,6 +74,25 @@ def _safe_name(s: str, max_len: int = 80) -> str:
    return t


+def _resolve_export_output_dir(account_dir: Path, output_dir_raw: Any) -> Path:
+    text = str(output_dir_raw or "").strip()
+    if not text:
+        default_dir = account_dir.parents[1] / "exports" / account_dir.name
+        default_dir.mkdir(parents=True, exist_ok=True)
+        return default_dir
+
+    out_dir = Path(text).expanduser()
+    if not out_dir.is_absolute():
+        raise ValueError("output_dir must be an absolute path.")
+
+    try:
+        out_dir.mkdir(parents=True, exist_ok=True)
+    except Exception as e:
+        raise ValueError(f"Failed to prepare output_dir: {e}") from e
+
+    return out_dir.resolve()
+
+
 def _format_ts(ts: int) -> str:
    if not ts:
        return ""
@@ -99,43 +118,54 @@ def _normalize_render_type_key(value: Any) -> str:
    return lower


-def _render_types_to_local_types(render_types: set[str]) -> Optional[set[int]]:
-    rt = {str(x or "").strip() for x in (render_types or set())}
-    rt = {x for x in rt if x}
-    if not rt:
+def _is_render_type_selected(render_type: Any, selected_render_types: Optional[set[str]]) -> bool:
+    if selected_render_types is None:
+        return True
+    rt = _normalize_render_type_key(render_type) or "text"
+    return rt in selected_render_types
+
+
+def _media_kinds_from_selected_types(selected_render_types: Optional[set[str]]) -> Optional[set[MediaKind]]:
+    if selected_render_types is None:
        return None

-    out: set[int] = set()
-    for k in rt:
-        if k == "text":
-            out.add(1)
-        elif k == "image":
-            out.add(3)
-        elif k == "voice":
-            out.add(34)
-        elif k == "video":
-            out.update({43, 62})
-        elif k == "emoji":
-            out.add(47)
-        elif k == "voip":
-            out.add(50)
-        elif k == "system":
-            out.update({10000, 266287972401})
-        elif k == "quote":
-            out.add(244813135921)
-            out.add(49)  # Some quote messages are embedded as appmsg (local_type=49).
-        elif k in {"link", "file", "transfer", "redpacket"}:
-            out.add(49)
-        else:
-            # Unknown type: cannot safely prefilter by local_type.
-            return None
+    out: set[MediaKind] = set()
+    if "image" in selected_render_types:
+        out.add("image")
+    if "emoji" in selected_render_types:
+        out.add("emoji")
+    if "video" in selected_render_types:
+        out.add("video")
+        out.add("video_thumb")
+    if "voice" in selected_render_types:
+        out.add("voice")
+    if "file" in selected_render_types:
+        out.add("file")
    return out


-def _should_estimate_by_local_type(render_types: set[str]) -> bool:
-    # Only estimate counts when every requested type maps 1:1 to local_type.
-    # App messages (local_type=49) are heterogeneous and cannot be counted accurately without parsing.
-    return not bool(render_types & {"link", "file", "transfer", "redpacket", "quote"})
+def _resolve_effective_media_kinds(
+    *,
+    include_media: bool,
+    media_kinds: list[MediaKind],
+    selected_render_types: Optional[set[str]],
+    privacy_mode: bool,
+) -> tuple[bool, list[MediaKind]]:
+    if privacy_mode or (not include_media):
+        return False, []
+
+    kinds = [k for k in media_kinds if k in {"image", "emoji", "video", "video_thumb", "voice", "file"}]
+    if not kinds:
+        return False, []
+
+    selected_media_kinds = _media_kinds_from_selected_types(selected_render_types)
+    if selected_media_kinds is not None:
+        kinds = [k for k in kinds if k in selected_media_kinds]
+
+    kinds = list(dict.fromkeys(kinds))
+    if not kinds:
+        return False, []
+    return True, kinds


@dataclass
@@ -235,6 +265,7 @@ class ChatExportManager:
        include_media: bool,
        media_kinds: list[MediaKind],
        message_types: list[str],
+        output_dir: Optional[str],
        allow_process_key_extract: bool,
        privacy_mode: bool,
        file_name: Optional[str],
@@ -257,6 +288,7 @@ class ChatExportManager:
                "includeMedia": bool(include_media),
                "mediaKinds": media_kinds,
                "messageTypes": list(dict.fromkeys([str(t or "").strip() for t in (message_types or []) if str(t or "").strip()])),
+                "outputDir": str(output_dir or "").strip(),
                "allowProcessKeyExtract": bool(allow_process_key_extract),
                "privacyMode": bool(privacy_mode),
                "fileName": str(file_name or "").strip(),
@@ -313,10 +345,6 @@ class ChatExportManager:
            if ks in {"image", "emoji", "video", "video_thumb", "voice", "file"}:
                media_kinds.append(ks)  # type: ignore[arg-type]

-        if privacy_mode:
-            include_media = False
-            media_kinds = []
-
        st = int(opts.get("startTime") or 0) or None
        et = int(opts.get("endTime") or 0) or None

@@ -328,9 +356,15 @@ class ChatExportManager:
            if want:
                want_types = want

-        local_types = _render_types_to_local_types(want_types) if want_types else None
-        can_estimate = (want_types is None) or _should_estimate_by_local_type(want_types)
-        estimate_local_types = local_types if (want_types and can_estimate) else None
+        include_media, media_kinds = _resolve_effective_media_kinds(
+            include_media=include_media,
+            media_kinds=media_kinds,
+            selected_render_types=want_types,
+            privacy_mode=privacy_mode,
+        )
+
+        local_types = None
+        estimate_local_types = None

        target_usernames = _resolve_export_targets(
            account_dir=account_dir,
@@ -342,8 +376,7 @@ class ChatExportManager:
        if not target_usernames:
            raise ValueError("No target conversations to export.")

-        exports_root = account_dir.parents[1] / "exports" / account_dir.name
-        exports_root.mkdir(parents=True, exist_ok=True)
+        exports_root = _resolve_export_output_dir(account_dir, opts.get("outputDir"))
        ts = datetime.now().strftime("%Y%m%d_%H%M%S")

        base_name = str(opts.get("fileName") or "").strip()
@@ -456,16 +489,13 @@ class ChatExportManager:
                        job.progress.current_conversation_messages_total = 0

                    try:
-                        if not can_estimate:
-                            estimated_total = 0
-                        else:
-                            estimated_total = _estimate_conversation_message_count(
-                                account_dir=account_dir,
-                                conv_username=conv_username,
-                                start_time=st,
-                                end_time=et,
-                                local_types=estimate_local_types,
-                            )
+                        estimated_total = _estimate_conversation_message_count(
+                            account_dir=account_dir,
+                            conv_username=conv_username,
+                            start_time=st,
+                            end_time=et,
+                            local_types=estimate_local_types,
+                        )
                    except Exception:
                        estimated_total = 0

@@ -557,6 +587,8 @@ class ChatExportManager:
                    zf.writestr(f"{conv_dir}/meta.json", json.dumps(meta, ensure_ascii=False, indent=2))

                    with self._lock:
+                        job.progress.current_conversation_messages_exported = int(exported_count)
+                        job.progress.current_conversation_messages_total = int(exported_count)
                        job.progress.conversations_done += 1

                manifest = {
@@ -1325,12 +1357,8 @@ def _write_conversation_json(
                    resource_chat_id=resource_chat_id,
                    sender_alias=sender_alias,
                )
-                if want_types:
-                    rt_key = _normalize_render_type_key(msg.get("renderType"))
-                    if rt_key not in want_types:
-                        if scanned % 500 == 0 and job.cancel_requested:
-                            raise _JobCancelled()
-                        continue
+                if not _is_render_type_selected(msg.get("renderType"), want_types):
+                    continue

                su = str(msg.get("senderUsername") or "").strip()
                if privacy_mode:
@@ -1506,12 +1534,8 @@ def _write_conversation_txt(
                    resource_chat_id=resource_chat_id,
                    sender_alias=sender_alias,
                )
-                if want_types:
-                    rt_key = _normalize_render_type_key(msg.get("renderType"))
-                    if rt_key not in want_types:
-                        if scanned % 500 == 0 and job.cancel_requested:
-                            raise _JobCancelled()
-                        continue
+                if not _is_render_type_selected(msg.get("renderType"), want_types):
+                    continue

                su = str(msg.get("senderUsername") or "").strip()
                if privacy_mode:
@@ -0,0 +1,357 @@
+# import sys
+# import requests
+
+try:
+    import wx_key
+except ImportError:
+    print('[!] 环境中未安装wx_key依赖，可能无法自动获取数据库密钥')
+    wx_key = None
+    # sys.exit(1)
+
+import time
+import psutil
+import subprocess
+import hashlib
+import os
+import json
+import random
+import logging
+import httpx
+from pathlib import Path
+from typing import Optional, List, Dict, Any
+from dataclasses import dataclass
+from packaging import version as pkg_version  # 建议使用 packaging 库处理版本比较
+from .wechat_detection import detect_wechat_installation
+from .key_store import upsert_account_keys_in_store
+from .media_helpers import _resolve_account_dir, _resolve_account_wxid_dir
+
+logger = logging.getLogger(__name__)
+
+
+# ======================  以下是hook逻辑  ======================================
+
+@dataclass
+class HookConfig:
+    min_version: str
+    pattern: str  # 用 00 不要用 ?  !!!!  否则C++内存会炸
+    mask: str
+    offset: int
+
+
+class WeChatKeyFetcher:
+    def __init__(self):
+        self.process_name = "Weixin.exe"
+        self.timeout_seconds = 60
+
+    @staticmethod
+    def _hex_array_to_str(hex_array: List[int]) -> str:
+        return " ".join([f"{b:02X}" for b in hex_array])
+
+    def _get_hook_config(self, version_str: str) -> Optional[HookConfig]:
+        """搬运自wx_key代码，未来用ida脚本直接获取即可"""
+        try:
+            v_curr = pkg_version.parse(version_str)
+        except Exception as e:
+            logger.error(f"版本号解析失败: {version_str} || {e}")
+            return None
+
+        if v_curr > pkg_version.parse("4.1.6.14"):
+            return HookConfig(
+                min_version=">4.1.6.14",
+                pattern=self._hex_array_to_str([
+                    0x24, 0x50, 0x48, 0xC7, 0x45, 0x00, 0xFE, 0xFF, 0xFF, 0xFF,
+                    0x44, 0x89, 0xCF, 0x44, 0x89, 0xC3, 0x49, 0x89, 0xD6, 0x48,
+                    0x89, 0xCE, 0x48, 0x89
+                ]),
+                mask="xxxxxxxxxxxxxxxxxxxxxxxx",
+                offset=-3
+            )
+
+        if pkg_version.parse("4.1.4") <= v_curr <= pkg_version.parse("4.1.6.14"):
+            return HookConfig(
+                min_version="4.1.4-4.1.6.14",
+                pattern=self._hex_array_to_str([
+                    0x24, 0x08, 0x48, 0x89, 0x6c, 0x24, 0x10, 0x48, 0x89, 0x74,
+                    0x00, 0x18, 0x48, 0x89, 0x7c, 0x00, 0x20, 0x41, 0x56, 0x48,
+                    0x83, 0xec, 0x50, 0x41
+                ]),
+                mask="xxxxxxxxxx?xxxx?xxxxxxxx",
+                offset=-3
+            )
+
+        if v_curr < pkg_version.parse("4.1.4"):
+            return HookConfig(
+                min_version="<4.1.4",
+                pattern=self._hex_array_to_str([
+                    0x24, 0x50, 0x48, 0xc7, 0x45, 0x00, 0xfe, 0xff, 0xff, 0xff,
+                    0x44, 0x89, 0xcf, 0x44, 0x89, 0xc3, 0x49, 0x89, 0xd6, 0x48,
+                    0x89, 0xce, 0x48, 0x89
+                ]),
+                mask="xxxxxxxxxxxxxxxxxxxxxxxx",
+                offset=-15  # -0xf
+            )
+
+        return None
+
+    def kill_wechat(self):
+        """检测并查杀微信进程"""
+        killed = False
+        for proc in psutil.process_iter(['pid', 'name']):
+            try:
+                if proc.info['name'] == self.process_name:
+                    logger.info(f"Killing WeChat process: {proc.info['pid']}")
+                    proc.terminate()
+                    killed = True
+            except (psutil.NoSuchProcess, psutil.AccessDenied, psutil.ZombieProcess):
+                pass
+
+        if killed:
+            time.sleep(1)  # 等待完全退出
+
+    def launch_wechat(self, exe_path: str) -> int:
+        """启动微信并返回 PID"""
+        try:
+
+            process = subprocess.Popen(exe_path)
+
+            time.sleep(2)
+            candidates = []
+            for proc in psutil.process_iter(['pid', 'name', 'create_time']):
+                if proc.info['name'] == self.process_name:
+                    candidates.append(proc)
+
+            if candidates:
+
+                candidates.sort(key=lambda x: x.info['create_time'], reverse=True)
+                target_pid = candidates[0].info['pid']
+                return target_pid
+
+            return process.pid
+
+        except Exception as e:
+            logger.error(f"启动微信失败: {e}")
+            raise RuntimeError(f"无法启动微信: {e}")
+
+    def fetch_key(self) -> str:
+        """没有wx_key模块无法自动获取密钥"""
+        if wx_key is None:
+            raise RuntimeError("wx_key 模块未安装或加载失败")
+
+        install_info = detect_wechat_installation()
+
+        exe_path = install_info.get('wechat_exe_path')
+        version = install_info.get('wechat_version')
+
+        if not exe_path or not version:
+            raise RuntimeError("无法自动定位微信安装路径或版本")
+
+        logger.info(f"Detect WeChat: {version} at {exe_path}")
+
+        config = self._get_hook_config(version)
+        if not config:
+            raise RuntimeError(f"不支持的微信版本: {version}")
+
+        self.kill_wechat()
+
+        pid = self.launch_wechat(exe_path)
+        logger.info(f"WeChat launched, PID: {pid}")
+
+        logger.info(f"Initializing Hook with pattern: {config.pattern[:20]}... Offset: {config.offset}")
+
+        if not wx_key.initialize_hook(pid, "", config.pattern, config.mask, config.offset):
+            err = wx_key.get_last_error_msg()
+            raise RuntimeError(f"Hook初始化失败: {err}")
+
+        start_time = time.time()
+
+
+        try:
+            while True:
+                if time.time() - start_time > self.timeout_seconds:
+                    raise TimeoutError("获取密钥超时 (60s)")
+
+                key = wx_key.poll_key_data()
+                if key:
+                    found_key = key
+                    break
+
+                while True:
+                    msg, level = wx_key.get_status_message()
+                    if msg is None:
+                        break
+                    if level == 2:
+                        logger.error(f"[Hook Error] {msg}")
+
+                time.sleep(0.1)
+
+        finally:
+            logger.info("Cleaning up hook...")
+            wx_key.cleanup_hook()
+
+        if found_key:
+            return found_key
+        else:
+            raise RuntimeError("未知错误，未获取到密钥")
+
+def get_db_key_workflow():
+    fetcher = WeChatKeyFetcher()
+    return fetcher.fetch_key()
+
+
+# ==============================   以下是图片密钥逻辑  =====================================
+
+
+# 远程 API 配置
+REMOTE_URL = "https://view.free.c3o.re/dashboard"
+NEXT_ACTION_ID = "7c8f99280c70626ccf5960cc4a68f368197e15f8e9"
+
+
+def get_wechat_internal_global_config(wx_dir: Path, file_name1) -> bytes:
+    """
+    读微信目录下的主配置文件
+    """
+    xwechat_files_root = wx_dir.parent
+
+    target_path = os.path.join(xwechat_files_root, "all_users", "config", file_name1)
+
+    if not os.path.exists(target_path):
+        logger.error(f"未找到微信内部 global_config: {target_path}")
+        raise FileNotFoundError(f"找不到文件: {target_path}，请确认微信数据目录结构是否完整")
+
+    return Path(target_path).read_bytes()
+
+
+# def get_local_config_sha3_224() -> bytes:
+#     """
+#     不要在意，抽象的实现 哈哈哈
+#     """
+#     content = json.dumps({
+#         "wxfile_dir": "C:\\Users\\17078\\xwechat_files",
+#         "weixin_id_folder": "wxid_lnyf4hdo9csb12_f1c4",
+#         "cache_dir": "C:\\Users\\17078\\Desktop\\wxDBHook\\test\\wx-dat\\wx-dat\\.cache",
+#         "db_key": "",
+#         "port": 8001
+#     }, indent=4).encode("utf-8")
+#
+#     # 计算 SHA3-224
+#     digest = hashlib.sha3_224(content).digest()
+#     return digest
+
+# async def log_request(request):
+#     print(f"--- Request Raw ---")
+#     print(f"{request.method} {request.url} {request.extensions.get('http_version', b'HTTP/1.1').decode()}")
+#     for name, value in request.headers.items():
+#         print(f"{name}: {value}")
+#
+#     print()
+#
+#     body = request.read()
+#     if body:
+#         print(body.decode(errors='replace'))
+#     print(f"-------------------\n")
+
+
+async def fetch_and_save_remote_keys(account: Optional[str] = None) -> Dict[str, Any]:
+    account_dir = _resolve_account_dir(account)
+    wx_id_dir = _resolve_account_wxid_dir(account_dir)
+    wxid = wx_id_dir.name
+
+    logger.info(f"正在为账号 {wxid} 获取密钥...")
+
+    try:
+        blob1_bytes = get_wechat_internal_global_config(wx_id_dir, file_name1= "global_config") # 估计这是唯一有效的数据！！
+        logger.info(f"获取微信内部配置成功，大小: {len(blob1_bytes)} bytes")
+    except Exception as e:
+        raise RuntimeError(f"读取微信内部文件失败: {e}")
+
+    try:
+        blob2_bytes = get_wechat_internal_global_config(wx_id_dir, file_name1= "global_config.crc")
+        logger.info(f"获取微信内部配置成功，大小: {len(blob2_bytes)} bytes")
+    except Exception as e:
+        raise RuntimeError(f"读取微信内部文件失败: {e}")
+
+    blob3_bytes = b""
+
+    headers = {
+        "Accept": "text/x-component",
+        "Next-Action": NEXT_ACTION_ID,
+        "Next-Router-State-Tree": "%5B%22%22%2C%7B%22children%22%3A%5B%22dashboard%22%2C%7B%22children%22%3A%5B%22__PAGE__%22%2C%7B%7D%2Cnull%2Cnull%5D%7D%2Cnull%2Cnull%5D%7D%2Cnull%2Cnull%2Ctrue%5D",
+        "Origin": "https://view.free.c3o.re",
+        "Referer": "https://view.free.c3o.re/dashboard",
+        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36"
+    }
+
+    files = {
+        '1': ('blob', blob1_bytes, 'application/octet-stream'),
+        '2': ('blob', blob2_bytes, 'application/octet-stream'),
+        '3': ('blob', blob3_bytes, 'application/octet-stream'),
+        '0': (None, json.dumps([wxid, "$A1", "$A2", "$A3", 0],separators=(",",":")).encode('utf-8')),
+    }
+
+
+    async with httpx.AsyncClient(timeout=30) as client:
+        logger.info("向远程服务器发送请求...")
+        response = await client.post(REMOTE_URL, headers=headers, files=files)
+
+    if response.status_code != 200:
+        raise RuntimeError(f"远程服务器错误: {response.status_code} - {response.text[:100]}")
+
+
+    result_data = {}
+    lines = response.text.split('\n')
+
+    found_config = False
+    for line in lines:
+        line = line.strip()
+        if not line:
+            continue
+
+        if line.startswith('1:'):
+            try:
+                json_part = line[2:]  # 去掉 "1:"
+                data_obj = json.loads(json_part)
+
+                if "config" in data_obj:
+                    config = data_obj["config"]
+                    result_data = {
+                        "xor_key": config.get("xor_key", ""),
+                        "aes_key": config.get("aes_key", ""),
+                        "nick_name": config.get("nick_name", ""),
+                        "avatar_url": config.get("avatar_url", "")
+                    }
+                    found_config = True
+                    break
+            except Exception as e:
+                logger.warning(f"解析响应行失败: {e}")
+                continue
+
+    if not found_config or not result_data.get("aes_key"):
+        logger.error(f"响应中未找到密钥信息。Full Response: {response.text[:500]}")
+        raise RuntimeError("解析失败: 服务器未返回 config 数据")
+
+    # 6. 处理并保存密钥
+    xor_raw = str(result_data["xor_key"])
+    aes_val = str(result_data["aes_key"])
+
+    try:
+        if xor_raw.startswith("0x"):
+            xor_int = int(xor_raw, 16)
+        else:
+            xor_int = int(xor_raw)
+        xor_hex_str = f"0x{xor_int:02X}"
+    except:
+        xor_hex_str = xor_raw
+
+    upsert_account_keys_in_store(
+        account=wxid,
+        image_xor_key=xor_hex_str,
+        image_aes_key=aes_val
+    )
+
+    return {
+        "wxid": wxid,
+        "xor_key": xor_hex_str,
+        "aes_key": aes_val,
+        "nick_name": result_data["nick_name"]
+    }
+
@@ -45,7 +45,6 @@ from ..chat_helpers import (
    _normalize_xml_url,
    _parse_app_message,
    _parse_pat_message,
-    _pick_avatar_url,
    _pick_display_name,
    _query_head_image_usernames,
    _quote_ident,
@@ -85,6 +84,19 @@ _REALTIME_SYNC_LOCKS: dict[tuple[str, str], threading.Lock] = {}
 _REALTIME_SYNC_ALL_LOCKS: dict[str, threading.Lock] = {}


+def _avatar_url_unified(
+    *,
+    account_dir: Path,
+    username: str,
+    local_avatar_usernames: set[str] | None = None,
+) -> str:
+    u = str(username or "").strip()
+    if not u:
+        return ""
+    # Unified avatar entrypoint: backend decides local db vs remote fallback + cache.
+    return _build_avatar_url(str(account_dir.name or ""), u)
+
+
 def _realtime_sync_lock(account: str, username: str) -> threading.Lock:
    key = (str(account or "").strip(), str(username or "").strip())
    with _REALTIME_SYNC_MU:
@@ -1946,9 +1958,11 @@ async def chat_search_index_senders(
            continue
        cnt = int(r["c"] or 0)
        row = contact_rows.get(su)
-        avatar_url = _pick_avatar_url(row)
-        if (not avatar_url) and (su in local_sender_avatars):
-            avatar_url = _build_avatar_url(account_dir.name, su)
+        avatar_url = _avatar_url_unified(
+            account_dir=account_dir,
+            username=su,
+            local_avatar_usernames=local_sender_avatars,
+        )
        senders.append(
            {
                "username": su,
@@ -2568,7 +2582,7 @@ def _postprocess_full_messages(
            row = sender_contact_rows.get(u)
            if _pick_display_name(row, u) == u:
                need_display.append(u)
-            if (not _pick_avatar_url(row)) and (u not in local_sender_avatars):
+            if u not in local_sender_avatars:
                need_avatar.append(u)

        need_display = list(dict.fromkeys(need_display))
@@ -2606,13 +2620,11 @@ def _postprocess_full_messages(
            if wd and wd != su:
                display_name = wd
        m["senderDisplayName"] = display_name
-        avatar_url = _pick_avatar_url(row)
-        if not avatar_url and su in local_sender_avatars:
-            avatar_url = base_url + _build_avatar_url(account_dir.name, su)
-        if not avatar_url:
-            wa = str(wcdb_avatar_urls.get(su) or "").strip()
-            if wa.lower().startswith(("http://", "https://")):
-                avatar_url = wa
+        avatar_url = base_url + _avatar_url_unified(
+            account_dir=account_dir,
+            username=su,
+            local_avatar_usernames=local_sender_avatars,
+        )
        m["senderAvatar"] = avatar_url

        qu = str(m.get("quoteUsername") or "").strip()
@@ -2922,7 +2934,7 @@ def list_chat_sessions(
                if u not in local_avatar_usernames:
                    need_avatar.append(u)
            else:
-                if (not _pick_avatar_url(row)) and (u not in local_avatar_usernames):
+                if u not in local_avatar_usernames:
                    need_avatar.append(u)

        need_display = list(dict.fromkeys(need_display))
@@ -2984,15 +2996,11 @@ def list_chat_sessions(

        # Prefer local head_image avatars when available: decrypted contact.db URLs can be stale
        # (or hotlink-protected for browsers). WCDB realtime (when available) is the next best.
-        avatar_url = ""
-        if username in local_avatar_usernames:
-            avatar_url = base_url + _build_avatar_url(account_dir.name, username)
-        if not avatar_url:
-            wa = str(wcdb_avatar_urls.get(username) or "").strip()
-            if wa.lower().startswith(("http://", "https://")):
-                avatar_url = wa
-        if not avatar_url:
-            avatar_url = _pick_avatar_url(c_row) or ""
+        avatar_url = base_url + _avatar_url_unified(
+            account_dir=account_dir,
+            username=username,
+            local_avatar_usernames=local_avatar_usernames,
+        )

        last_message = ""
        if preview_mode == "session":
@@ -4388,7 +4396,7 @@ def list_chat_messages(
            row = sender_contact_rows.get(u)
            if _pick_display_name(row, u) == u:
                need_display.append(u)
-            if (not _pick_avatar_url(row)) and (u not in local_sender_avatars):
+            if u not in local_sender_avatars:
                need_avatar.append(u)

        need_display = list(dict.fromkeys(need_display))
@@ -4426,13 +4434,11 @@ def list_chat_messages(
            if wd and wd != su:
                display_name = wd
        m["senderDisplayName"] = display_name
-        avatar_url = _pick_avatar_url(row)
-        if not avatar_url and su in local_sender_avatars:
-            avatar_url = base_url + _build_avatar_url(account_dir.name, su)
-        if not avatar_url:
-            wa = str(wcdb_avatar_urls.get(su) or "").strip()
-            if wa.lower().startswith(("http://", "https://")):
-                avatar_url = wa
+        avatar_url = base_url + _avatar_url_unified(
+            account_dir=account_dir,
+            username=su,
+            local_avatar_usernames=local_sender_avatars,
+        )
        m["senderAvatar"] = avatar_url

        qu = str(m.get("quoteUsername") or "").strip()
@@ -4897,7 +4903,7 @@ async def _search_chat_messages_via_fts(
                row = contact_rows.get(uu)
                if _pick_display_name(row, uu) == uu:
                    need_display.append(uu)
-                if (not _pick_avatar_url(row)) and (uu not in local_avatar_usernames):
+                if uu not in local_avatar_usernames:
                    need_avatar.append(uu)

            need_display = list(dict.fromkeys(need_display))
@@ -4919,13 +4925,11 @@ async def _search_chat_messages_via_fts(
            wd = str(wcdb_display_names.get(username) or "").strip()
            if wd and wd != username:
                conv_name = wd
-        conv_avatar = _pick_avatar_url(conv_row)
-        if (not conv_avatar) and (username in local_avatar_usernames):
-            conv_avatar = base_url + _build_avatar_url(account_dir.name, username)
-        if not conv_avatar:
-            wa = str(wcdb_avatar_urls.get(username) or "").strip()
-            if wa.lower().startswith(("http://", "https://")):
-                conv_avatar = wa
+        conv_avatar = base_url + _avatar_url_unified(
+            account_dir=account_dir,
+            username=username,
+            local_avatar_usernames=local_avatar_usernames,
+        )

        for h in hits:
            su = str(h.get("senderUsername") or "").strip()
@@ -4939,13 +4943,11 @@ async def _search_chat_messages_via_fts(
                    if wd and wd != su:
                        display_name = wd
                h["senderDisplayName"] = display_name
-                avatar_url = _pick_avatar_url(row)
-                if (not avatar_url) and (su in local_avatar_usernames):
-                    avatar_url = base_url + _build_avatar_url(account_dir.name, su)
-                if not avatar_url:
-                    wa = str(wcdb_avatar_urls.get(su) or "").strip()
-                    if wa.lower().startswith(("http://", "https://")):
-                        avatar_url = wa
+                avatar_url = base_url + _avatar_url_unified(
+                    account_dir=account_dir,
+                    username=su,
+                    local_avatar_usernames=local_avatar_usernames,
+                )
                h["senderAvatar"] = avatar_url
    else:
        uniq_contacts = list(
@@ -4968,7 +4970,7 @@ async def _search_chat_messages_via_fts(
                row = contact_rows.get(uu)
                if _pick_display_name(row, uu) == uu:
                    need_display.append(uu)
-                if (not _pick_avatar_url(row)) and (uu not in local_avatar_usernames):
+                if uu not in local_avatar_usernames:
                    need_avatar.append(uu)

            need_display = list(dict.fromkeys(need_display))
@@ -4994,13 +4996,11 @@ async def _search_chat_messages_via_fts(
                if wd and wd != cu:
                    conv_name = wd
            h["conversationName"] = conv_name or cu
-            conv_avatar = _pick_avatar_url(crow)
-            if (not conv_avatar) and cu and (cu in local_avatar_usernames):
-                conv_avatar = base_url + _build_avatar_url(account_dir.name, cu)
-            if not conv_avatar and cu:
-                wa = str(wcdb_avatar_urls.get(cu) or "").strip()
-                if wa.lower().startswith(("http://", "https://")):
-                    conv_avatar = wa
+            conv_avatar = base_url + _avatar_url_unified(
+                account_dir=account_dir,
+                username=cu,
+                local_avatar_usernames=local_avatar_usernames,
+            )
            h["conversationAvatar"] = conv_avatar
            if su:
                row = contact_rows.get(su)
@@ -5010,13 +5010,11 @@ async def _search_chat_messages_via_fts(
                    if wd and wd != su:
                        display_name = wd
                h["senderDisplayName"] = display_name
-                avatar_url = _pick_avatar_url(row)
-                if (not avatar_url) and (su in local_avatar_usernames):
-                    avatar_url = base_url + _build_avatar_url(account_dir.name, su)
-                if not avatar_url:
-                    wa = str(wcdb_avatar_urls.get(su) or "").strip()
-                    if wa.lower().startswith(("http://", "https://")):
-                        avatar_url = wa
+                avatar_url = base_url + _avatar_url_unified(
+                    account_dir=account_dir,
+                    username=su,
+                    local_avatar_usernames=local_avatar_usernames,
+                )
                h["senderAvatar"] = avatar_url

    return {
@@ -0,0 +1,749 @@
+import csv
+import json
+import re
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Literal, Optional
+
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel, Field
+
+from ..chat_helpers import (
+    _build_avatar_url,
+    _pick_avatar_url,
+    _pick_display_name,
+    _resolve_account_dir,
+    _should_keep_session,
+)
+from ..path_fix import PathFixRoute
+
+router = APIRouter(route_class=PathFixRoute)
+
+
+_SYSTEM_USERNAMES = {
+    "filehelper",
+    "fmessage",
+    "floatbottle",
+    "medianote",
+    "newsapp",
+    "qmessage",
+    "qqmail",
+    "tmessage",
+    "brandsessionholder",
+    "brandservicesessionholder",
+    "notifymessage",
+    "opencustomerservicemsg",
+    "notification_messages",
+    "userexperience_alarm",
+}
+
+_SOURCE_SCENE_LABELS = {
+    1: "通过QQ号添加",
+    3: "通过微信号添加",
+    6: "通过手机号添加",
+    10: "通过名片添加",
+    14: "通过群聊添加",
+    30: "通过扫一扫添加",
+}
+
+_COUNTRY_LABELS = {
+    "CN": "中国大陆",
+}
+
+
+class ContactTypeFilter(BaseModel):
+    friends: bool = True
+    groups: bool = True
+    officials: bool = True
+
+
+class ContactExportRequest(BaseModel):
+    account: Optional[str] = Field(None, description="账号目录名（可选，默认使用第一个）")
+    output_dir: str = Field(..., description="导出目录绝对路径")
+    format: str = Field("json", description="导出格式，仅支持 json/csv")
+    include_avatar_link: bool = Field(True, description="是否导出 avatarLink 字段")
+    contact_types: ContactTypeFilter = Field(default_factory=ContactTypeFilter)
+    keyword: Optional[str] = Field(None, description="关键词筛选（可选）")
+
+
+def _normalize_text(v: Any) -> str:
+    if v is None:
+        return ""
+    return str(v).strip()
+
+
+def _to_int(v: Any) -> int:
+    try:
+        return int(v or 0)
+    except Exception:
+        return 0
+
+
+def _to_optional_int(v: Any) -> Optional[int]:
+    if v is None:
+        return None
+    if isinstance(v, bool):
+        return int(v)
+    if isinstance(v, int):
+        return v
+    s = _normalize_text(v)
+    if not s:
+        return None
+    try:
+        return int(s)
+    except Exception:
+        return None
+
+
+def _decode_varint(raw: bytes, offset: int) -> tuple[Optional[int], int]:
+    value = 0
+    shift = 0
+    pos = int(offset)
+    n = len(raw)
+    while pos < n:
+        byte = raw[pos]
+        pos += 1
+        value |= (byte & 0x7F) << shift
+        if (byte & 0x80) == 0:
+            return value, pos
+        shift += 7
+        if shift > 63:
+            return None, n
+    return None, n
+
+
+def _decode_proto_text(raw: bytes) -> str:
+    if not raw:
+        return ""
+    try:
+        text = raw.decode("utf-8", errors="ignore")
+    except Exception:
+        return ""
+    return re.sub(r"[\x00-\x08\x0b\x0c\x0e-\x1f]", "", text).strip()
+
+
+def _parse_contact_extra_buffer(extra_buffer: Any) -> dict[str, Any]:
+    out = {
+        "signature": "",
+        "country": "",
+        "province": "",
+        "city": "",
+        "source_scene": None,
+    }
+    if extra_buffer is None:
+        return out
+
+    raw: bytes
+    if isinstance(extra_buffer, memoryview):
+        raw = extra_buffer.tobytes()
+    elif isinstance(extra_buffer, (bytes, bytearray)):
+        raw = bytes(extra_buffer)
+    else:
+        return out
+
+    if not raw:
+        return out
+
+    idx = 0
+    n = len(raw)
+    while idx < n:
+        tag, idx_next = _decode_varint(raw, idx)
+        if tag is None:
+            break
+        idx = idx_next
+        field_no = tag >> 3
+        wire_type = tag & 0x7
+
+        if wire_type == 0:
+            val, idx_next = _decode_varint(raw, idx)
+            if val is None:
+                break
+            idx = idx_next
+            if field_no == 8:
+                out["source_scene"] = int(val)
+            continue
+
+        if wire_type == 2:
+            size, idx_next = _decode_varint(raw, idx)
+            if size is None:
+                break
+            idx = idx_next
+            end = idx + int(size)
+            if end > n:
+                break
+            chunk = raw[idx:end]
+            idx = end
+
+            if field_no in {4, 5, 6, 7}:
+                text = _decode_proto_text(chunk)
+                if field_no == 4:
+                    out["signature"] = text
+                elif field_no == 5:
+                    out["country"] = text
+                elif field_no == 6:
+                    out["province"] = text
+                elif field_no == 7:
+                    out["city"] = text
+            continue
+
+        if wire_type == 1:
+            idx += 8
+            continue
+        if wire_type == 5:
+            idx += 4
+            continue
+
+        break
+
+    return out
+
+
+def _country_label(country: str) -> str:
+    c = _normalize_text(country)
+    if not c:
+        return ""
+    return _COUNTRY_LABELS.get(c.upper(), c)
+
+
+def _source_scene_label(source_scene: Optional[int]) -> str:
+    if source_scene is None:
+        return ""
+    if source_scene in _SOURCE_SCENE_LABELS:
+        return _SOURCE_SCENE_LABELS[source_scene]
+    return f"场景码 {source_scene}"
+
+
+def _build_region(country: str, province: str, city: str) -> str:
+    parts: list[str] = []
+    country_text = _country_label(country)
+    province_text = _normalize_text(province)
+    city_text = _normalize_text(city)
+    if country_text:
+        parts.append(country_text)
+    if province_text:
+        parts.append(province_text)
+    if city_text:
+        parts.append(city_text)
+    return "·".join(parts)
+
+
+def _safe_export_part(s: str) -> str:
+    cleaned = re.sub(r"[^0-9A-Za-z._-]+", "_", str(s or "").strip())
+    cleaned = cleaned.strip("._-")
+    return cleaned or "account"
+
+
+def _is_valid_contact_username(username: str) -> bool:
+    u = _normalize_text(username)
+    if not u:
+        return False
+    if u in _SYSTEM_USERNAMES:
+        return False
+    if u.startswith("fake_"):
+        return False
+    if not _should_keep_session(u, include_official=True) and not u.startswith("gh_") and u != "weixin":
+        return False
+    return True
+
+
+def _get_table_columns(conn: sqlite3.Connection, table: str) -> set[str]:
+    try:
+        rows = conn.execute(f"PRAGMA table_info({table})").fetchall()
+    except Exception:
+        return set()
+
+    out: set[str] = set()
+    for row in rows:
+        try:
+            name = _normalize_text(row["name"] if "name" in row.keys() else row[1]).lower()
+        except Exception:
+            continue
+        if name:
+            out.add(name)
+    return out
+
+
+def _build_contact_select_sql(table: str, columns: set[str]) -> Optional[str]:
+    if "username" not in columns:
+        return None
+
+    specs: list[tuple[str, str, str]] = [
+        ("username", "username", "''"),
+        ("remark", "remark", "''"),
+        ("nick_name", "nick_name", "''"),
+        ("alias", "alias", "''"),
+        ("local_type", "local_type", "0"),
+        ("verify_flag", "verify_flag", "0"),
+        ("big_head_url", "big_head_url", "''"),
+        ("small_head_url", "small_head_url", "''"),
+        ("extra_buffer", "extra_buffer", "x''"),
+    ]
+
+    select_parts: list[str] = []
+    for key, alias, fallback in specs:
+        if key in columns:
+            select_parts.append(key)
+        else:
+            select_parts.append(f"{fallback} AS {alias}")
+    return f"SELECT {', '.join(select_parts)} FROM {table}"
+
+
+def _load_contact_rows_map(contact_db_path: Path) -> dict[str, dict[str, Any]]:
+    out: dict[str, dict[str, Any]] = {}
+    if not contact_db_path.exists():
+        return out
+
+    conn = sqlite3.connect(str(contact_db_path))
+    conn.row_factory = sqlite3.Row
+    try:
+        def read_rows(table: str) -> list[sqlite3.Row]:
+            columns = _get_table_columns(conn, table)
+            sql = _build_contact_select_sql(table, columns)
+            if not sql:
+                return []
+            try:
+                return conn.execute(sql).fetchall()
+            except Exception:
+                return []
+            return []
+
+        for table in ("contact", "stranger"):
+            rows = read_rows(table)
+            for row in rows:
+                username = _normalize_text(row["username"] if "username" in row.keys() else "")
+                if (not username) or (username in out):
+                    continue
+
+                extra_info = _parse_contact_extra_buffer(
+                    row["extra_buffer"] if "extra_buffer" in row.keys() else b""
+                )
+                out[username] = {
+                    "username": username,
+                    "remark": _normalize_text(row["remark"] if "remark" in row.keys() else ""),
+                    "nick_name": _normalize_text(row["nick_name"] if "nick_name" in row.keys() else ""),
+                    "alias": _normalize_text(row["alias"] if "alias" in row.keys() else ""),
+                    "local_type": _to_int(row["local_type"] if "local_type" in row.keys() else 0),
+                    "verify_flag": _to_int(row["verify_flag"] if "verify_flag" in row.keys() else 0),
+                    "big_head_url": _normalize_text(row["big_head_url"] if "big_head_url" in row.keys() else ""),
+                    "small_head_url": _normalize_text(row["small_head_url"] if "small_head_url" in row.keys() else ""),
+                    "country": _normalize_text(extra_info.get("country")),
+                    "province": _normalize_text(extra_info.get("province")),
+                    "city": _normalize_text(extra_info.get("city")),
+                    "source_scene": _to_optional_int(extra_info.get("source_scene")),
+                }
+        return out
+    finally:
+        conn.close()
+
+
+def _load_session_sort_timestamps(session_db_path: Path) -> dict[str, int]:
+    out: dict[str, int] = {}
+    if not session_db_path.exists():
+        return out
+
+    conn = sqlite3.connect(str(session_db_path))
+    conn.row_factory = sqlite3.Row
+    try:
+        rows: list[sqlite3.Row] = []
+        queries = [
+            "SELECT username, COALESCE(sort_timestamp, 0) AS ts FROM SessionTable",
+            "SELECT username, COALESCE(last_timestamp, 0) AS ts FROM SessionTable",
+        ]
+        for sql in queries:
+            try:
+                rows = conn.execute(sql).fetchall()
+                break
+            except Exception:
+                continue
+
+        for row in rows:
+            username = _normalize_text(row["username"] if "username" in row.keys() else "")
+            if not username:
+                continue
+            ts = _to_int(row["ts"] if "ts" in row.keys() else 0)
+            prev = out.get(username, 0)
+            if ts > prev:
+                out[username] = ts
+        return out
+    finally:
+        conn.close()
+
+
+def _load_session_group_usernames(session_db_path: Path) -> set[str]:
+    out: set[str] = set()
+    if not session_db_path.exists():
+        return out
+
+    conn = sqlite3.connect(str(session_db_path))
+    conn.row_factory = sqlite3.Row
+    try:
+        queries = [
+            "SELECT username FROM SessionTable",
+            "SELECT username FROM sessiontable",
+        ]
+        for sql in queries:
+            try:
+                rows = conn.execute(sql).fetchall()
+            except Exception:
+                continue
+            for row in rows:
+                username = _normalize_text(row["username"] if "username" in row.keys() else "")
+                if username and ("@chatroom" in username):
+                    out.add(username)
+            return out
+        return out
+    finally:
+        conn.close()
+
+
+def _infer_contact_type(username: str, row: dict[str, Any]) -> Optional[str]:
+    if not username:
+        return None
+
+    if "@chatroom" in username:
+        return "group"
+
+    verify_flag = _to_int(row.get("verify_flag"))
+    if username.startswith("gh_") or verify_flag != 0:
+        return "official"
+
+    local_type = _to_int(row.get("local_type"))
+    if local_type == 1:
+        return "friend"
+
+    return None
+
+
+def _matches_keyword(contact: dict[str, Any], keyword: str) -> bool:
+    kw = _normalize_text(keyword).lower()
+    if not kw:
+        return True
+
+    fields = [
+        contact.get("username", ""),
+        contact.get("displayName", ""),
+        contact.get("remark", ""),
+        contact.get("nickname", ""),
+        contact.get("alias", ""),
+        contact.get("region", ""),
+        contact.get("source", ""),
+        contact.get("country", ""),
+        contact.get("province", ""),
+        contact.get("city", ""),
+    ]
+    for field in fields:
+        if kw in _normalize_text(field).lower():
+            return True
+    return False
+
+
+def _collect_contacts_for_account(
+    *,
+    account_dir: Path,
+    base_url: str,
+    keyword: Optional[str],
+    include_friends: bool,
+    include_groups: bool,
+    include_officials: bool,
+) -> list[dict[str, Any]]:
+    if not (include_friends or include_groups or include_officials):
+        return []
+
+    contact_db_path = account_dir / "contact.db"
+    session_db_path = account_dir / "session.db"
+    contact_rows = _load_contact_rows_map(contact_db_path)
+    session_ts_map = _load_session_sort_timestamps(session_db_path)
+    session_group_usernames = _load_session_group_usernames(session_db_path)
+
+    contacts: list[dict[str, Any]] = []
+    for username, row in contact_rows.items():
+        if not _is_valid_contact_username(username):
+            continue
+
+        contact_type = _infer_contact_type(username, row)
+        if contact_type is None:
+            continue
+        if contact_type == "friend" and not include_friends:
+            continue
+        if contact_type == "group" and not include_groups:
+            continue
+        if contact_type == "official" and not include_officials:
+            continue
+
+        display_name = _pick_display_name(row, username)
+        if not display_name:
+            display_name = username
+
+        avatar_link = _normalize_text(_pick_avatar_url(row) or "")
+        avatar = base_url + _build_avatar_url(account_dir.name, username)
+        country = _normalize_text(row.get("country"))
+        province = _normalize_text(row.get("province"))
+        city = _normalize_text(row.get("city"))
+        source_scene = _to_optional_int(row.get("source_scene"))
+
+        item = {
+            "username": username,
+            "displayName": display_name,
+            "remark": _normalize_text(row.get("remark")),
+            "nickname": _normalize_text(row.get("nick_name")),
+            "alias": _normalize_text(row.get("alias")),
+            "type": contact_type,
+            "country": country,
+            "province": province,
+            "city": city,
+            "region": _build_region(country, province, city),
+            "sourceScene": source_scene,
+            "source": _source_scene_label(source_scene),
+            "avatar": avatar,
+            "avatarLink": avatar_link,
+            "_sortTs": _to_int(session_ts_map.get(username, 0)),
+        }
+
+        if not _matches_keyword(item, keyword or ""):
+            continue
+        contacts.append(item)
+
+    if include_groups:
+        for username in session_group_usernames:
+            if username in contact_rows:
+                continue
+            if not _is_valid_contact_username(username):
+                continue
+
+            avatar_link = ""
+            avatar = base_url + _build_avatar_url(account_dir.name, username)
+
+            item = {
+                "username": username,
+                "displayName": username,
+                "remark": "",
+                "nickname": "",
+                "alias": "",
+                "type": "group",
+                "country": "",
+                "province": "",
+                "city": "",
+                "region": "",
+                "sourceScene": None,
+                "source": "",
+                "avatar": avatar,
+                "avatarLink": avatar_link,
+                "_sortTs": _to_int(session_ts_map.get(username, 0)),
+            }
+
+            if not _matches_keyword(item, keyword or ""):
+                continue
+            contacts.append(item)
+
+    contacts.sort(
+        key=lambda x: (
+            -_to_int(x.get("_sortTs", 0)),
+            _normalize_text(x.get("displayName", "")).lower(),
+            _normalize_text(x.get("username", "")).lower(),
+        )
+    )
+    for item in contacts:
+        item.pop("_sortTs", None)
+    return contacts
+
+
+def _build_counts(contacts: list[dict[str, Any]]) -> dict[str, int]:
+    counts = {
+        "friends": 0,
+        "groups": 0,
+        "officials": 0,
+        "total": 0,
+    }
+    for item in contacts:
+        t = _normalize_text(item.get("type"))
+        if t == "friend":
+            counts["friends"] += 1
+        elif t == "group":
+            counts["groups"] += 1
+        elif t == "official":
+            counts["officials"] += 1
+    counts["total"] = len(contacts)
+    return counts
+
+
+def _build_export_contacts(
+    contacts: list[dict[str, Any]],
+    *,
+    include_avatar_link: bool,
+) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    for item in contacts:
+        row = {
+            "username": _normalize_text(item.get("username")),
+            "displayName": _normalize_text(item.get("displayName")),
+            "remark": _normalize_text(item.get("remark")),
+            "nickname": _normalize_text(item.get("nickname")),
+            "alias": _normalize_text(item.get("alias")),
+            "type": _normalize_text(item.get("type")),
+            "region": _normalize_text(item.get("region")),
+            "country": _normalize_text(item.get("country")),
+            "province": _normalize_text(item.get("province")),
+            "city": _normalize_text(item.get("city")),
+            "source": _normalize_text(item.get("source")),
+            "sourceScene": _to_optional_int(item.get("sourceScene")),
+        }
+        if include_avatar_link:
+            row["avatarLink"] = _normalize_text(item.get("avatarLink"))
+        out.append(row)
+    return out
+
+
+def _write_json_export(
+    output_path: Path,
+    *,
+    account: str,
+    contacts: list[dict[str, Any]],
+    include_avatar_link: bool,
+    keyword: str,
+    contact_types: ContactTypeFilter,
+) -> None:
+    payload = {
+        "exportedAt": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "account": account,
+        "count": len(contacts),
+        "filters": {
+            "keyword": keyword,
+            "contactTypes": {
+                "friends": bool(contact_types.friends),
+                "groups": bool(contact_types.groups),
+                "officials": bool(contact_types.officials),
+            },
+            "includeAvatarLink": bool(include_avatar_link),
+        },
+        "contacts": contacts,
+    }
+    output_path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+
+
+def _write_csv_export(
+    output_path: Path,
+    *,
+    contacts: list[dict[str, Any]],
+    include_avatar_link: bool,
+) -> None:
+    columns: list[tuple[str, str]] = [
+        ("username", "用户名"),
+        ("displayName", "显示名称"),
+        ("remark", "备注"),
+        ("nickname", "昵称"),
+        ("alias", "微信号"),
+        ("type", "类型"),
+        ("region", "地区"),
+        ("country", "国家/地区码"),
+        ("province", "省份"),
+        ("city", "城市"),
+        ("source", "来源"),
+        ("sourceScene", "来源场景码"),
+    ]
+    if include_avatar_link:
+        columns.append(("avatarLink", "头像链接"))
+
+    with output_path.open("w", encoding="utf-8-sig", newline="") as f:
+        writer = csv.writer(f)
+        writer.writerow([label for _, label in columns])
+        for item in contacts:
+            writer.writerow([_normalize_text(item.get(key, "")) for key, _ in columns])
+
+
+@router.get("/api/chat/contacts", summary="获取联系人列表")
+def list_chat_contacts(
+    request: Request,
+    account: Optional[str] = None,
+    keyword: Optional[str] = None,
+    include_friends: bool = True,
+    include_groups: bool = True,
+    include_officials: bool = True,
+):
+    account_dir = _resolve_account_dir(account)
+    base_url = str(request.base_url).rstrip("/")
+
+    contacts = _collect_contacts_for_account(
+        account_dir=account_dir,
+        base_url=base_url,
+        keyword=keyword,
+        include_friends=bool(include_friends),
+        include_groups=bool(include_groups),
+        include_officials=bool(include_officials),
+    )
+
+    return {
+        "status": "success",
+        "account": account_dir.name,
+        "total": len(contacts),
+        "counts": _build_counts(contacts),
+        "contacts": contacts,
+    }
+
+
+@router.post("/api/chat/contacts/export", summary="导出联系人")
+def export_chat_contacts(request: Request, req: ContactExportRequest):
+    account_dir = _resolve_account_dir(req.account)
+
+    output_dir_raw = _normalize_text(req.output_dir)
+    if not output_dir_raw:
+        raise HTTPException(status_code=400, detail="output_dir is required.")
+
+    output_dir = Path(output_dir_raw).expanduser()
+    if not output_dir.is_absolute():
+        raise HTTPException(status_code=400, detail="output_dir must be an absolute path.")
+
+    try:
+        output_dir.mkdir(parents=True, exist_ok=True)
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=f"Failed to prepare output_dir: {e}")
+
+    base_url = str(request.base_url).rstrip("/")
+    contacts = _collect_contacts_for_account(
+        account_dir=account_dir,
+        base_url=base_url,
+        keyword=req.keyword,
+        include_friends=bool(req.contact_types.friends),
+        include_groups=bool(req.contact_types.groups),
+        include_officials=bool(req.contact_types.officials),
+    )
+
+    export_contacts = _build_export_contacts(
+        contacts,
+        include_avatar_link=bool(req.include_avatar_link),
+    )
+
+    fmt = _normalize_text(req.format).lower()
+    if fmt not in {"json", "csv"}:
+        raise HTTPException(status_code=400, detail="Unsupported format, use 'json' or 'csv'.")
+
+    ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+    safe_account = _safe_export_part(account_dir.name)
+    output_path = output_dir / f"contacts_{safe_account}_{ts}.{fmt}"
+
+    try:
+        if fmt == "json":
+            _write_json_export(
+                output_path,
+                account=account_dir.name,
+                contacts=export_contacts,
+                include_avatar_link=bool(req.include_avatar_link),
+                keyword=_normalize_text(req.keyword),
+                contact_types=req.contact_types,
+            )
+        else:
+            _write_csv_export(
+                output_path,
+                contacts=export_contacts,
+                include_avatar_link=bool(req.include_avatar_link),
+            )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to export contacts: {e}")
+
+    return {
+        "status": "success",
+        "account": account_dir.name,
+        "format": fmt,
+        "outputPath": str(output_path),
+        "count": len(export_contacts),
+    }
@@ -27,15 +27,16 @@ class ChatExportCreateRequest(BaseModel):
    end_time: Optional[int] = Field(None, description="结束时间（Unix 秒，含）")
    include_hidden: bool = Field(False, description="是否包含隐藏会话（scope!=selected 时）")
    include_official: bool = Field(False, description="是否包含公众号/官方账号会话（scope!=selected 时）")
-    include_media: bool = Field(True, description="是否打包离线媒体（图片/表情/视频/语音/文件）")
+    include_media: bool = Field(True, description="是否允许打包离线媒体（最终仍受 message_types 与 privacy_mode 约束）")
    media_kinds: list[MediaKind] = Field(
        default_factory=lambda: ["image", "emoji", "video", "video_thumb", "voice", "file"],
-        description="打包的媒体类型",
+        description="允许打包的媒体类型（最终仍受 message_types 勾选约束）",
    )
    message_types: list[MessageType] = Field(
        default_factory=list,
-        description="导出消息类型（renderType）过滤：为空=导出全部消息；可多选（如仅 voice / 仅 transfer / 仅 redPacket 等）",
+        description="导出消息类型（renderType）过滤：为空=导出全部类型；不为空时，仅导出勾选类型",
    )
+    output_dir: Optional[str] = Field(None, description="导出目录绝对路径（可选；不填时使用默认目录）")
    allow_process_key_extract: bool = Field(
        False,
        description="预留字段：本项目不从微信进程提取媒体密钥，请使用 wx_key 获取并保存/批量解密",
@@ -61,6 +62,7 @@ async def create_chat_export(req: ChatExportCreateRequest):
        include_media=req.include_media,
        media_kinds=req.media_kinds,
        message_types=req.message_types,
+        output_dir=req.output_dir,
        allow_process_key_extract=req.allow_process_key_extract,
        privacy_mode=req.privacy_mode,
        file_name=req.file_name,
@@ -8,7 +8,7 @@ import os
 import sqlite3
 import subprocess
 from pathlib import Path
-from typing import Optional
+from typing import Any, Optional
 from urllib.parse import urlparse

 import requests
@@ -16,6 +16,21 @@ from fastapi import APIRouter, HTTPException
 from fastapi.responses import FileResponse, Response
 from pydantic import BaseModel, Field

+from ..avatar_cache import (
+    AVATAR_CACHE_TTL_SECONDS,
+    avatar_cache_entry_file_exists,
+    avatar_cache_entry_is_fresh,
+    build_avatar_cache_response_headers,
+    cache_key_for_avatar_user,
+    cache_key_for_avatar_url,
+    get_avatar_cache_url_entry,
+    get_avatar_cache_user_entry,
+    is_avatar_cache_enabled,
+    normalize_avatar_source_url,
+    touch_avatar_cache_entry,
+    upsert_avatar_cache_entry,
+    write_avatar_cache_payload,
+)
 from ..logging_config import get_logger
 from ..media_helpers import (
    _convert_silk_to_wav,
@@ -43,14 +58,56 @@ from ..media_helpers import (
    _try_find_decrypted_resource,
    _try_strip_media_prefix,
 )
-from ..chat_helpers import _extract_md5_from_packed_info
+from ..chat_helpers import _extract_md5_from_packed_info, _load_contact_rows, _pick_avatar_url
 from ..path_fix import PathFixRoute
+from ..wcdb_realtime import WCDB_REALTIME, get_avatar_urls as _wcdb_get_avatar_urls

 logger = get_logger(__name__)

 router = APIRouter(route_class=PathFixRoute)


+def _resolve_avatar_remote_url(*, account_dir: Path, username: str) -> str:
+    u = str(username or "").strip()
+    if not u:
+        return ""
+
+    # 1) contact.db first (cheap local lookup)
+    try:
+        rows = _load_contact_rows(account_dir / "contact.db", [u])
+        row = rows.get(u)
+        raw = str(_pick_avatar_url(row) or "").strip()
+        if raw.lower().startswith(("http://", "https://")):
+            return normalize_avatar_source_url(raw)
+    except Exception:
+        pass
+
+    # 2) WCDB fallback (more complete on enterprise/openim IDs)
+    try:
+        wcdb_conn = WCDB_REALTIME.ensure_connected(account_dir)
+        with wcdb_conn.lock:
+            mp = _wcdb_get_avatar_urls(wcdb_conn.handle, [u])
+        wa = str(mp.get(u) or "").strip()
+        if wa.lower().startswith(("http://", "https://")):
+            return normalize_avatar_source_url(wa)
+    except Exception:
+        pass
+
+    return ""
+
+
+def _parse_304_headers(headers: Any) -> tuple[str, str]:
+    try:
+        etag = str((headers or {}).get("ETag") or "").strip()
+    except Exception:
+        etag = ""
+    try:
+        last_modified = str((headers or {}).get("Last-Modified") or "").strip()
+    except Exception:
+        last_modified = ""
+    return etag, last_modified
+
+
@lru_cache(maxsize=4096)
 def _fast_probe_image_path_in_chat_attach(
    *,
@@ -267,27 +324,309 @@ async def get_chat_avatar(username: str, account: Optional[str] = None):
    if not username:
        raise HTTPException(status_code=400, detail="Missing username.")
    account_dir = _resolve_account_dir(account)
+    account_name = str(account_dir.name or "").strip()
+    user_key = str(username or "").strip()
+
+    # 1) Try on-disk cache first (fast path)
+    user_entry = None
+    cached_file = None
+    if is_avatar_cache_enabled() and account_name and user_key:
+        try:
+            user_entry = get_avatar_cache_user_entry(account_name, user_key)
+            cached_file = avatar_cache_entry_file_exists(account_name, user_entry)
+            if cached_file is not None:
+                logger.info(f"[avatar_cache_hit] kind=user account={account_name} username={user_key}")
+        except Exception as e:
+            logger.warning(f"[avatar_cache_error] read user cache failed account={account_name} username={user_key} err={e}")
+
    head_image_db_path = account_dir / "head_image.db"
    if not head_image_db_path.exists():
+        # No local head_image.db: allow fallback from cached/remote URL path.
+        if cached_file is not None and user_entry:
+            headers = build_avatar_cache_response_headers(user_entry)
+            return FileResponse(
+                str(cached_file),
+                media_type=str(user_entry.get("media_type") or "application/octet-stream"),
+                headers=headers,
+            )
        raise HTTPException(status_code=404, detail="head_image.db not found.")

    conn = sqlite3.connect(str(head_image_db_path))
    try:
-        row = conn.execute(
-            "SELECT image_buffer FROM head_image WHERE username = ? ORDER BY update_time DESC LIMIT 1",
+        meta = conn.execute(
+            "SELECT md5, update_time FROM head_image WHERE username = ? ORDER BY update_time DESC LIMIT 1",
            (username,),
        ).fetchone()
+        if meta and meta[0] is not None:
+            db_md5 = str(meta[0] or "").strip().lower()
+            try:
+                db_update_time = int(meta[1] or 0)
+            except Exception:
+                db_update_time = 0
+
+            # Cache still valid against head_image metadata.
+            if cached_file is not None and user_entry:
+                cached_md5 = str(user_entry.get("source_md5") or "").strip().lower()
+                try:
+                    cached_update = int(user_entry.get("source_update_time") or 0)
+                except Exception:
+                    cached_update = 0
+                if cached_md5 == db_md5 and cached_update == db_update_time:
+                    touch_avatar_cache_entry(account_name, str(user_entry.get("cache_key") or ""))
+                    headers = build_avatar_cache_response_headers(user_entry)
+                    return FileResponse(
+                        str(cached_file),
+                        media_type=str(user_entry.get("media_type") or "application/octet-stream"),
+                        headers=headers,
+                    )
+
+            # Refresh from blob (changed or first-load)
+            row = conn.execute(
+                "SELECT image_buffer FROM head_image WHERE username = ? ORDER BY update_time DESC LIMIT 1",
+                (username,),
+            ).fetchone()
+            if row and row[0] is not None:
+                data = bytes(row[0]) if isinstance(row[0], (memoryview, bytearray)) else row[0]
+                if not isinstance(data, (bytes, bytearray)):
+                    data = bytes(data)
+                if data:
+                    media_type = _detect_image_media_type(data)
+                    media_type = media_type if media_type.startswith("image/") else "application/octet-stream"
+                    entry, out_path = write_avatar_cache_payload(
+                        account_name,
+                        source_kind="user",
+                        username=user_key,
+                        payload=bytes(data),
+                        media_type=media_type,
+                        source_md5=db_md5,
+                        source_update_time=db_update_time,
+                        ttl_seconds=AVATAR_CACHE_TTL_SECONDS,
+                    )
+                    if entry and out_path:
+                        logger.info(
+                            f"[avatar_cache_download] kind=user account={account_name} username={user_key} src=head_image"
+                        )
+                        headers = build_avatar_cache_response_headers(entry)
+                        return FileResponse(str(out_path), media_type=media_type, headers=headers)
+
+                    # cache write failed: fallback to response bytes
+                    logger.warning(
+                        f"[avatar_cache_error] kind=user account={account_name} username={user_key} action=write_fallback"
+                    )
+                    return Response(content=bytes(data), media_type=media_type)
+
+        # meta not found (no local avatar blob)
+        row = None
    finally:
        conn.close()

-    if not row or row[0] is None:
-        raise HTTPException(status_code=404, detail="Avatar not found.")
+    # 2) Fallback: remote avatar URL (contact/WCDB), cache by URL.
+    remote_url = _resolve_avatar_remote_url(account_dir=account_dir, username=user_key)
+    if remote_url and is_avatar_cache_enabled():
+        url_entry = get_avatar_cache_url_entry(account_name, remote_url)
+        url_file = avatar_cache_entry_file_exists(account_name, url_entry)
+        if url_entry and url_file and avatar_cache_entry_is_fresh(url_entry):
+            logger.info(f"[avatar_cache_hit] kind=url account={account_name} username={user_key}")
+            touch_avatar_cache_entry(account_name, str(url_entry.get("cache_key") or ""))
+            # Keep user-key mapping aligned, so next user lookup is direct.
+            try:
+                upsert_avatar_cache_entry(
+                    account_name,
+                    cache_key=cache_key_for_avatar_user(user_key),
+                    source_kind="user",
+                    username=user_key,
+                    source_url=remote_url,
+                    source_md5=str(url_entry.get("source_md5") or ""),
+                    source_update_time=int(url_entry.get("source_update_time") or 0),
+                    rel_path=str(url_entry.get("rel_path") or ""),
+                    media_type=str(url_entry.get("media_type") or "application/octet-stream"),
+                    size_bytes=int(url_entry.get("size_bytes") or 0),
+                    etag=str(url_entry.get("etag") or ""),
+                    last_modified=str(url_entry.get("last_modified") or ""),
+                    fetched_at=int(url_entry.get("fetched_at") or 0),
+                    checked_at=int(url_entry.get("checked_at") or 0),
+                    expires_at=int(url_entry.get("expires_at") or 0),
+                )
+            except Exception:
+                pass
+            headers = build_avatar_cache_response_headers(url_entry)
+            return FileResponse(
+                str(url_file),
+                media_type=str(url_entry.get("media_type") or "application/octet-stream"),
+                headers=headers,
+            )

-    data = bytes(row[0]) if isinstance(row[0], (memoryview, bytearray)) else row[0]
-    if not isinstance(data, (bytes, bytearray)):
-        data = bytes(data)
-    media_type = _detect_image_media_type(data)
-    return Response(content=data, media_type=media_type)
+        # Revalidate / download remote avatar
+        def _download_remote_avatar(
+            source_url: str,
+            *,
+            etag: str,
+            last_modified: str,
+        ) -> tuple[bytes, str, str, str, bool]:
+            base_headers = {
+                "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120 Safari/537.36",
+                "Accept": "image/avif,image/webp,image/apng,image/*,*/*;q=0.8",
+            }
+
+            header_variants = [
+                {
+                    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/107.0.0.0 Safari/537.36 MicroMessenger/7.0.20.1781(0x6700143B) WindowsWechat(0x63090719) XWEB/8351",
+                    "Accept": "image/avif,image/webp,image/apng,image/svg+xml,image/*,*/*;q=0.8",
+                    "Accept-Language": "zh-CN,zh;q=0.9",
+                    "Referer": "https://servicewechat.com/",
+                    "Origin": "https://servicewechat.com",
+                    "Range": "bytes=0-",
+                },
+                {"Referer": "https://wx.qq.com/", "Origin": "https://wx.qq.com"},
+                {"Referer": "https://mp.weixin.qq.com/", "Origin": "https://mp.weixin.qq.com"},
+                {"Referer": "https://www.baidu.com/", "Origin": "https://www.baidu.com"},
+                {},
+            ]
+
+            last_err: Exception | None = None
+            for extra in header_variants:
+                headers = dict(base_headers)
+                headers.update(extra)
+                if etag:
+                    headers["If-None-Match"] = etag
+                if last_modified:
+                    headers["If-Modified-Since"] = last_modified
+
+                r = requests.get(source_url, headers=headers, timeout=20, stream=True)
+                try:
+                    if r.status_code == 304:
+                        e2, lm2 = _parse_304_headers(r.headers)
+                        return b"", "", (e2 or etag), (lm2 or last_modified), True
+                    r.raise_for_status()
+                    content_type = str(r.headers.get("Content-Type") or "").strip()
+                    e2, lm2 = _parse_304_headers(r.headers)
+                    max_bytes = 10 * 1024 * 1024
+                    chunks: list[bytes] = []
+                    total = 0
+                    for ch in r.iter_content(chunk_size=64 * 1024):
+                        if not ch:
+                            continue
+                        chunks.append(ch)
+                        total += len(ch)
+                        if total > max_bytes:
+                            raise HTTPException(status_code=400, detail="Avatar too large (>10MB).")
+                    return b"".join(chunks), content_type, e2, lm2, False
+                except HTTPException:
+                    raise
+                except Exception as e:
+                    last_err = e
+                finally:
+                    try:
+                        r.close()
+                    except Exception:
+                        pass
+
+            raise last_err or RuntimeError("avatar remote download failed")
+
+        etag0 = str((url_entry or {}).get("etag") or "").strip()
+        lm0 = str((url_entry or {}).get("last_modified") or "").strip()
+        try:
+            payload, ct, etag_new, lm_new, not_modified = await asyncio.to_thread(
+                _download_remote_avatar,
+                remote_url,
+                etag=etag0,
+                last_modified=lm0,
+            )
+        except Exception as e:
+            logger.warning(f"[avatar_cache_error] kind=url account={account_name} username={user_key} err={e}")
+            if url_entry and url_file:
+                headers = build_avatar_cache_response_headers(url_entry)
+                return FileResponse(
+                    str(url_file),
+                    media_type=str(url_entry.get("media_type") or "application/octet-stream"),
+                    headers=headers,
+                )
+            raise HTTPException(status_code=404, detail="Avatar not found.")
+
+        if not_modified and url_entry and url_file:
+            touch_avatar_cache_entry(account_name, cache_key_for_avatar_url(remote_url))
+            if etag_new or lm_new:
+                try:
+                    upsert_avatar_cache_entry(
+                        account_name,
+                        cache_key=cache_key_for_avatar_url(remote_url),
+                        source_kind="url",
+                        username=user_key,
+                        source_url=remote_url,
+                        source_md5=str(url_entry.get("source_md5") or ""),
+                        source_update_time=int(url_entry.get("source_update_time") or 0),
+                        rel_path=str(url_entry.get("rel_path") or ""),
+                        media_type=str(url_entry.get("media_type") or "application/octet-stream"),
+                        size_bytes=int(url_entry.get("size_bytes") or 0),
+                        etag=etag_new or etag0,
+                        last_modified=lm_new or lm0,
+                    )
+                except Exception:
+                    pass
+            logger.info(f"[avatar_cache_revalidate] kind=url account={account_name} username={user_key} status=304")
+            headers = build_avatar_cache_response_headers(url_entry)
+            return FileResponse(
+                str(url_file),
+                media_type=str(url_entry.get("media_type") or "application/octet-stream"),
+                headers=headers,
+            )
+
+        if payload:
+            payload2, media_type, _ext = _detect_media_type_and_ext(payload)
+            if media_type == "application/octet-stream" and ct:
+                try:
+                    mt = ct.split(";")[0].strip()
+                    if mt.startswith("image/"):
+                        media_type = mt
+                except Exception:
+                    pass
+            if str(media_type or "").startswith("image/"):
+                entry, out_path = write_avatar_cache_payload(
+                    account_name,
+                    source_kind="url",
+                    username=user_key,
+                    source_url=remote_url,
+                    payload=payload2,
+                    media_type=media_type,
+                    etag=etag_new,
+                    last_modified=lm_new,
+                    ttl_seconds=AVATAR_CACHE_TTL_SECONDS,
+                )
+                if entry and out_path:
+                    # bind user-key record to same file for quicker next access
+                    try:
+                        upsert_avatar_cache_entry(
+                            account_name,
+                            cache_key=cache_key_for_avatar_user(user_key),
+                            source_kind="user",
+                            username=user_key,
+                            source_url=remote_url,
+                            source_md5=str(entry.get("source_md5") or ""),
+                            source_update_time=int(entry.get("source_update_time") or 0),
+                            rel_path=str(entry.get("rel_path") or ""),
+                            media_type=str(entry.get("media_type") or "application/octet-stream"),
+                            size_bytes=int(entry.get("size_bytes") or 0),
+                            etag=str(entry.get("etag") or ""),
+                            last_modified=str(entry.get("last_modified") or ""),
+                            fetched_at=int(entry.get("fetched_at") or 0),
+                            checked_at=int(entry.get("checked_at") or 0),
+                            expires_at=int(entry.get("expires_at") or 0),
+                        )
+                    except Exception:
+                        pass
+                    logger.info(f"[avatar_cache_download] kind=url account={account_name} username={user_key}")
+                    headers = build_avatar_cache_response_headers(entry)
+                    return FileResponse(str(out_path), media_type=media_type, headers=headers)
+
+    if cached_file is not None and user_entry:
+        headers = build_avatar_cache_response_headers(user_entry)
+        return FileResponse(
+            str(cached_file),
+            media_type=str(user_entry.get("media_type") or "application/octet-stream"),
+            headers=headers,
+        )
+
+    raise HTTPException(status_code=404, detail="Avatar not found.")


 class EmojiDownloadRequest(BaseModel):
@@ -434,7 +773,25 @@ async def proxy_image(url: str):
    if not _is_allowed_proxy_image_host(host):
        raise HTTPException(status_code=400, detail="Unsupported url host for proxy_image.")

-    def _download_bytes() -> tuple[bytes, str]:
+    source_url = normalize_avatar_source_url(u)
+    proxy_account = "_proxy"
+    cache_entry = get_avatar_cache_url_entry(proxy_account, source_url) if is_avatar_cache_enabled() else None
+    cache_file = avatar_cache_entry_file_exists(proxy_account, cache_entry)
+    if cache_entry and cache_file and avatar_cache_entry_is_fresh(cache_entry):
+        logger.info(f"[avatar_cache_hit] kind=proxy_url account={proxy_account}")
+        touch_avatar_cache_entry(proxy_account, cache_key_for_avatar_url(source_url))
+        headers = build_avatar_cache_response_headers(cache_entry)
+        return FileResponse(
+            str(cache_file),
+            media_type=str(cache_entry.get("media_type") or "application/octet-stream"),
+            headers=headers,
+        )
+
+    def _download_bytes(
+        *,
+        if_none_match: str = "",
+        if_modified_since: str = "",
+    ) -> tuple[bytes, str, str, str, bool]:
        base_headers = {
            "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120 Safari/537.36",
            "Accept": "image/avif,image/webp,image/apng,image/*,*/*;q=0.8",
@@ -464,10 +821,20 @@ async def proxy_image(url: str):
        for extra in header_variants:
            headers = dict(base_headers)
            headers.update(extra)
+            if if_none_match:
+                headers["If-None-Match"] = if_none_match
+            if if_modified_since:
+                headers["If-Modified-Since"] = if_modified_since
            r = requests.get(u, headers=headers, timeout=20, stream=True)
            try:
+                if r.status_code == 304:
+                    etag0 = str(r.headers.get("ETag") or "").strip()
+                    lm0 = str(r.headers.get("Last-Modified") or "").strip()
+                    return b"", "", etag0, lm0, True
                r.raise_for_status()
                content_type = str(r.headers.get("Content-Type") or "").strip()
+                etag0 = str(r.headers.get("ETag") or "").strip()
+                lm0 = str(r.headers.get("Last-Modified") or "").strip()
                max_bytes = 10 * 1024 * 1024
                chunks: list[bytes] = []
                total = 0
@@ -478,7 +845,7 @@ async def proxy_image(url: str):
                    total += len(ch)
                    if total > max_bytes:
                        raise HTTPException(status_code=400, detail="Proxy image too large (>10MB).")
-                return b"".join(chunks), content_type
+                return b"".join(chunks), content_type, etag0, lm0, False
            except HTTPException:
                # Hard failure, don't retry with another referer.
                raise
@@ -493,14 +860,50 @@ async def proxy_image(url: str):
        # All variants failed.
        raise last_err or RuntimeError("proxy_image download failed")

+    etag0 = str((cache_entry or {}).get("etag") or "").strip()
+    lm0 = str((cache_entry or {}).get("last_modified") or "").strip()
    try:
-        data, ct = await asyncio.to_thread(_download_bytes)
+        data, ct, etag_new, lm_new, not_modified = await asyncio.to_thread(
+            _download_bytes,
+            if_none_match=etag0,
+            if_modified_since=lm0,
+        )
    except HTTPException:
        raise
    except Exception as e:
        logger.warning(f"proxy_image failed: url={u} err={e}")
+        if cache_entry and cache_file:
+            headers = build_avatar_cache_response_headers(cache_entry)
+            return FileResponse(
+                str(cache_file),
+                media_type=str(cache_entry.get("media_type") or "application/octet-stream"),
+                headers=headers,
+            )
        raise HTTPException(status_code=502, detail=f"Proxy image failed: {e}")

+    if not_modified and cache_entry and cache_file:
+        logger.info(f"[avatar_cache_revalidate] kind=proxy_url account={proxy_account} status=304")
+        upsert_avatar_cache_entry(
+            proxy_account,
+            cache_key=cache_key_for_avatar_url(source_url),
+            source_kind="url",
+            source_url=source_url,
+            username="",
+            source_md5=str(cache_entry.get("source_md5") or ""),
+            source_update_time=int(cache_entry.get("source_update_time") or 0),
+            rel_path=str(cache_entry.get("rel_path") or ""),
+            media_type=str(cache_entry.get("media_type") or "application/octet-stream"),
+            size_bytes=int(cache_entry.get("size_bytes") or 0),
+            etag=etag_new or etag0,
+            last_modified=lm_new or lm0,
+        )
+        headers = build_avatar_cache_response_headers(cache_entry)
+        return FileResponse(
+            str(cache_file),
+            media_type=str(cache_entry.get("media_type") or "application/octet-stream"),
+            headers=headers,
+        )
+
    if not data:
        raise HTTPException(status_code=502, detail="Proxy returned empty body.")

@@ -518,8 +921,24 @@ async def proxy_image(url: str):
    if not str(media_type or "").startswith("image/"):
        raise HTTPException(status_code=502, detail="Proxy did not return an image.")

+    if is_avatar_cache_enabled():
+        entry, out_path = write_avatar_cache_payload(
+            proxy_account,
+            source_kind="url",
+            source_url=source_url,
+            payload=payload,
+            media_type=media_type,
+            etag=etag_new,
+            last_modified=lm_new,
+            ttl_seconds=AVATAR_CACHE_TTL_SECONDS,
+        )
+        if entry and out_path:
+            logger.info(f"[avatar_cache_download] kind=proxy_url account={proxy_account}")
+            headers = build_avatar_cache_response_headers(entry)
+            return FileResponse(str(out_path), media_type=media_type, headers=headers)
+
    resp = Response(content=payload, media_type=media_type)
-    resp.headers["Cache-Control"] = "public, max-age=86400"
+    resp.headers["Cache-Control"] = f"public, max-age={AVATAR_CACHE_TTL_SECONDS}"
    return resp


@@ -3,6 +3,7 @@ from typing import Optional
 from fastapi import APIRouter

 from ..key_store import get_account_keys_from_store
+from ..key_service import get_db_key_workflow, fetch_and_save_remote_keys
 from ..media_helpers import _load_media_keys, _resolve_account_dir
 from ..path_fix import PathFixRoute

@@ -51,3 +52,76 @@ async def get_saved_keys(account: Optional[str] = None):
        "keys": result,
    }

+
+@router.get("/api/get_db_key", summary="自动获取微信数据库密钥")
+async def get_wechat_db_key():
+    """
+    自动流程：
+    1. 结束微信进程
+    2. 启动微信
+    3. 根据版本注入 Hook
+    4. 抓取密钥并返回
+    """
+    try:
+        # 不需要async吧，我相信fastapi的线程池
+        db_key = get_db_key_workflow()
+
+        return {
+            "status": 0,
+            "errmsg": "ok",
+            "data": {
+                "db_key": db_key
+            }
+        }
+
+    except TimeoutError:
+        return {
+            "status": -1,
+            "errmsg": "获取超时，请确保微信没有开启自动登录 或者 加快手速",
+            "data": {}
+        }
+    except Exception as e:
+        return {
+            "status": -1,
+            "errmsg": f"获取失败: {str(e)}",
+            "data": {}
+        }
+
+
+@router.get("/api/get_image_key", summary="获取并保存微信图片密钥")
+async def get_image_key(account: Optional[str] = None):
+    """
+    通过模拟 Next.js Server Action 协议，利用本地微信配置文件换取 AES/XOR 密钥。
+
+    1. 读取 [wx_dir]/all_users/config/global_config (Blob 1)
+    2. 读 同上目录下的global_config.crc
+    3. 构造 Multipart 包发送至远程服务器
+    4. 解析返回流，自动存入本地数据库
+    """
+    try:
+        result = await fetch_and_save_remote_keys(account)
+
+        return {
+            "status": 0,
+            "errmsg": "ok",
+            "data": {
+                "xor_key": result["xor_key"],
+                "aes_key": result["aes_key"],
+                "nick_name": result.get("nick_name"),
+                "account": result["wxid"]
+            }
+        }
+    except FileNotFoundError as e:
+        return {
+            "status": -1,
+            "errmsg": f"文件缺失: {str(e)}",
+            "data": {}
+        }
+    except Exception as e:
+        import traceback
+        traceback.print_exc()
+        return {
+            "status": -1,
+            "errmsg": f"获取失败: {str(e)}",
+            "data": {}
+        }
@@ -1,5 +1,5 @@
 from typing import Optional
-
+import psutil
 from fastapi import APIRouter

 from ..logging_config import get_logger
@@ -71,3 +71,49 @@ async def detect_current_account(data_root_path: Optional[str] = None):
            'error': str(e),
            'data': None,
        }
+
+
+@router.get("/api/wechat/status", summary="检查微信运行状态")
+async def check_wechat_status():
+    """
+    检查系统中是否有 Weixin.exe 或 WeChat.exe 进程在运行
+    返回: status=0 成功, wx_status={is_running: bool, pid: int, ...}
+    """
+    process_name_targets = ["Weixin.exe", "WeChat.exe"]
+
+    wx_status = {
+        "is_running": False,
+        "pid": None,
+        "exe_path": None,
+        "memory_usage_mb": 0.0
+    }
+
+    try:
+        for proc in psutil.process_iter(['pid', 'name', 'exe', 'memory_info']):
+            try:
+                if proc.info['name'] and proc.info['name'] in process_name_targets:
+                    wx_status["is_running"] = True
+                    wx_status["pid"] = proc.info['pid']
+                    wx_status["exe_path"] = proc.info['exe']
+
+                    mem = proc.info['memory_info']
+                    if mem:
+                        wx_status["memory_usage_mb"] = round(mem.rss / (1024 * 1024), 2)
+
+                    break
+            except (psutil.NoSuchProcess, psutil.AccessDenied, psutil.ZombieProcess):
+                continue
+
+        return {
+            "status": 0,
+            "errmsg": "ok",
+            "wx_status": wx_status
+        }
+
+    except Exception as e:
+        # 即使出错也返回 JSON，但 status 非 0
+        return {
+            "status": -1,
+            "errmsg": f"检查进程失败: {str(e)}",
+            "wx_status": wx_status
+        }
@@ -17,7 +17,6 @@ from ...chat_helpers import (
    _decode_sqlite_text,
    _iter_message_db_paths,
    _load_contact_rows,
-    _pick_avatar_url,
    _pick_display_name,
    _quote_ident,
    _should_keep_session,
@@ -701,7 +700,7 @@ def build_card_00_global_overview(
        u, cnt = stats.top_contact
        row = contact_rows.get(u)
        display = _pick_display_name(row, u)
-        avatar = _pick_avatar_url(row) or (_build_avatar_url(str(account_dir.name or ""), u) if u else "")
+        avatar = _build_avatar_url(str(account_dir.name or ""), u) if u else ""
        top_contact_obj = {
            "username": u,
            "displayName": display,
@@ -716,7 +715,7 @@ def build_card_00_global_overview(
        u, cnt = stats.top_group
        row = contact_rows.get(u)
        display = _pick_display_name(row, u)
-        avatar = _pick_avatar_url(row) or (_build_avatar_url(str(account_dir.name or ""), u) if u else "")
+        avatar = _build_avatar_url(str(account_dir.name or ""), u) if u else ""
        top_group_obj = {
            "username": u,
            "displayName": display,
@@ -14,7 +14,6 @@ from ...chat_helpers import (
    _build_avatar_url,
    _iter_message_db_paths,
    _load_contact_rows,
-    _pick_avatar_url,
    _pick_display_name,
    _quote_ident,
    _row_to_search_hit,
@@ -713,7 +712,7 @@ def _fetch_message_moment_payload(

        contact_row = contact_rows.get(username)
        display = _pick_display_name(contact_row, username)
-        avatar = _pick_avatar_url(contact_row) or (_build_avatar_url(str(account_dir.name or ""), username) if username else "")
+        avatar = _build_avatar_url(str(account_dir.name or ""), username) if username else ""

        return {
            "timestamp": int(ref.ts),
@@ -12,7 +12,6 @@ from typing import Any, Optional
 from ...chat_helpers import (
    _build_avatar_url,
    _load_contact_rows,
-    _pick_avatar_url,
    _pick_display_name,
    _should_keep_session,
 )
@@ -385,7 +384,7 @@ def compute_reply_speed_stats(*, account_dir: Path, year: int) -> dict[str, Any]
    def conv_to_obj(score: float | None, agg: _ConvAgg) -> dict[str, Any]:
        row = contact_rows.get(agg.username)
        display = _pick_display_name(row, agg.username)
-        avatar = _pick_avatar_url(row) or (_build_avatar_url(str(account_dir.name or ""), agg.username) if agg.username else "")
+        avatar = _build_avatar_url(str(account_dir.name or ""), agg.username) if agg.username else ""
        avg_s = agg.avg_gap()
        out: dict[str, Any] = {
            "username": agg.username,
@@ -420,7 +419,7 @@ def compute_reply_speed_stats(*, account_dir: Path, year: int) -> dict[str, Any]
        else:
            row = contact_rows.get(global_fastest_u)
            display = _pick_display_name(row, global_fastest_u)
-            avatar = _pick_avatar_url(row) or (_build_avatar_url(str(account_dir.name or ""), global_fastest_u) if global_fastest_u else "")
+            avatar = _build_avatar_url(str(account_dir.name or ""), global_fastest_u) if global_fastest_u else ""
            fastest_obj = {
                "username": global_fastest_u,
                "displayName": display,
@@ -440,7 +439,7 @@ def compute_reply_speed_stats(*, account_dir: Path, year: int) -> dict[str, Any]
        else:
            row = contact_rows.get(global_slowest_u)
            display = _pick_display_name(row, global_slowest_u)
-            avatar = _pick_avatar_url(row) or (_build_avatar_url(str(account_dir.name or ""), global_slowest_u) if global_slowest_u else "")
+            avatar = _build_avatar_url(str(account_dir.name or ""), global_slowest_u) if global_slowest_u else ""
            slowest_obj = {
                "username": global_slowest_u,
                "displayName": display,
@@ -547,7 +546,7 @@ def compute_reply_speed_stats(*, account_dir: Path, year: int) -> dict[str, Any]

                row = contact_rows.get(u)
                display = _pick_display_name(row, u)
-                avatar = _pick_avatar_url(row) or (_build_avatar_url(str(account_dir.name or ""), u) if u else "")
+                avatar = _build_avatar_url(str(account_dir.name or ""), u) if u else ""
                series.append(
                    {
                        "username": u,
@@ -595,7 +594,7 @@ def compute_reply_speed_stats(*, account_dir: Path, year: int) -> dict[str, Any]
                    if not u:
                        continue
                    display = _pick_display_name(r, u)
-                    avatar = _pick_avatar_url(r) or (_build_avatar_url(str(account_dir.name or ""), u) if u else "")
+                    avatar = _build_avatar_url(str(account_dir.name or ""), u) if u else ""
                    all_contacts_list.append({
                        "username": u,
                        "displayName": display,
@@ -0,0 +1,173 @@
+import os
+import sqlite3
+import sys
+import unittest
+import importlib
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "src"))
+
+
+class TestAvatarCacheChatMedia(unittest.TestCase):
+    def _seed_contact_db(self, path: Path, *, username: str = "wxid_friend") -> None:
+        conn = sqlite3.connect(str(path))
+        try:
+            conn.execute(
+                """
+                CREATE TABLE contact (
+                    username TEXT,
+                    remark TEXT,
+                    nick_name TEXT,
+                    alias TEXT,
+                    local_type INTEGER,
+                    verify_flag INTEGER,
+                    big_head_url TEXT,
+                    small_head_url TEXT
+                )
+                """
+            )
+            conn.execute(
+                """
+                CREATE TABLE stranger (
+                    username TEXT,
+                    remark TEXT,
+                    nick_name TEXT,
+                    alias TEXT,
+                    local_type INTEGER,
+                    verify_flag INTEGER,
+                    big_head_url TEXT,
+                    small_head_url TEXT
+                )
+                """
+            )
+            conn.execute(
+                "INSERT INTO contact VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+                (
+                    username,
+                    "",
+                    "测试好友",
+                    "",
+                    1,
+                    0,
+                    "https://wx.qlogo.cn/mmhead/ver_1/test_remote_avatar/132",
+                    "",
+                ),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    def _seed_session_db(self, path: Path, *, username: str = "wxid_friend") -> None:
+        conn = sqlite3.connect(str(path))
+        try:
+            conn.execute(
+                """
+                CREATE TABLE SessionTable (
+                    username TEXT,
+                    sort_timestamp INTEGER,
+                    last_timestamp INTEGER
+                )
+                """
+            )
+            conn.execute("INSERT INTO SessionTable VALUES (?, ?, ?)", (username, 200, 200))
+            conn.commit()
+        finally:
+            conn.close()
+
+    def _seed_head_image_db(self, path: Path, *, username: str = "wxid_friend") -> None:
+        # 1x1 PNG
+        png = bytes.fromhex(
+            "89504E470D0A1A0A"
+            "0000000D49484452000000010000000108060000001F15C489"
+            "0000000D49444154789C6360606060000000050001A5F64540"
+            "0000000049454E44AE426082"
+        )
+        conn = sqlite3.connect(str(path))
+        try:
+            conn.execute("CREATE TABLE head_image(username TEXT PRIMARY KEY, md5 TEXT, image_buffer BLOB, update_time INTEGER)")
+            conn.execute(
+                "INSERT INTO head_image VALUES (?, ?, ?, ?)",
+                (username, "0123456789abcdef0123456789abcdef", sqlite3.Binary(png), 1735689600),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    def test_chat_avatar_caches_to_output_avatar_cache(self):
+        from fastapi import FastAPI
+        from fastapi.testclient import TestClient
+
+        with TemporaryDirectory() as td:
+            root = Path(td)
+            account = "wxid_test"
+            username = "wxid_friend"
+            account_dir = root / "output" / "databases" / account
+            account_dir.mkdir(parents=True, exist_ok=True)
+
+            self._seed_contact_db(account_dir / "contact.db", username=username)
+            self._seed_session_db(account_dir / "session.db", username=username)
+            self._seed_head_image_db(account_dir / "head_image.db", username=username)
+
+            prev_data = None
+            prev_cache = None
+            try:
+                prev_data = os.environ.get("WECHAT_TOOL_DATA_DIR")
+                prev_cache = os.environ.get("WECHAT_TOOL_AVATAR_CACHE_ENABLED")
+                os.environ["WECHAT_TOOL_DATA_DIR"] = str(root)
+                os.environ["WECHAT_TOOL_AVATAR_CACHE_ENABLED"] = "1"
+
+                import wechat_decrypt_tool.app_paths as app_paths
+                import wechat_decrypt_tool.chat_helpers as chat_helpers
+                import wechat_decrypt_tool.avatar_cache as avatar_cache
+                import wechat_decrypt_tool.routers.chat_media as chat_media
+
+                importlib.reload(app_paths)
+                importlib.reload(chat_helpers)
+                importlib.reload(avatar_cache)
+                importlib.reload(chat_media)
+
+                app = FastAPI()
+                app.include_router(chat_media.router)
+                client = TestClient(app)
+
+                resp = client.get("/api/chat/avatar", params={"account": account, "username": username})
+                self.assertEqual(resp.status_code, 200)
+                self.assertTrue(resp.headers.get("content-type", "").startswith("image/"))
+
+                cache_db = root / "output" / "avatar_cache" / account / "avatar_cache.db"
+                self.assertTrue(cache_db.exists())
+
+                conn = sqlite3.connect(str(cache_db))
+                try:
+                    row = conn.execute(
+                        "SELECT cache_key, source_kind, username, rel_path, media_type FROM avatar_cache_entries WHERE source_kind = 'user' LIMIT 1"
+                    ).fetchone()
+                    self.assertIsNotNone(row)
+                    rel_path = str(row[3] or "")
+                finally:
+                    conn.close()
+
+                self.assertTrue(rel_path)
+                cache_file = (root / "output" / "avatar_cache" / account / rel_path).resolve()
+                self.assertTrue(cache_file.exists())
+
+                resp2 = client.get("/api/chat/avatar", params={"account": account, "username": username})
+                self.assertEqual(resp2.status_code, 200)
+                self.assertEqual(resp2.content, resp.content)
+            finally:
+                if prev_data is None:
+                    os.environ.pop("WECHAT_TOOL_DATA_DIR", None)
+                else:
+                    os.environ["WECHAT_TOOL_DATA_DIR"] = prev_data
+                if prev_cache is None:
+                    os.environ.pop("WECHAT_TOOL_AVATAR_CACHE_ENABLED", None)
+                else:
+                    os.environ["WECHAT_TOOL_AVATAR_CACHE_ENABLED"] = prev_cache
+
+
+if __name__ == "__main__":
+    unittest.main()
+
@@ -0,0 +1,418 @@
+import os
+import json
+import hashlib
+import sqlite3
+import sys
+import unittest
+import zipfile
+import importlib
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "src"))
+
+
+class TestChatExportMessageTypesSemantics(unittest.TestCase):
+    def _reload_export_modules(self):
+        import wechat_decrypt_tool.app_paths as app_paths
+        import wechat_decrypt_tool.chat_helpers as chat_helpers
+        import wechat_decrypt_tool.media_helpers as media_helpers
+        import wechat_decrypt_tool.chat_export_service as chat_export_service
+
+        importlib.reload(app_paths)
+        importlib.reload(chat_helpers)
+        importlib.reload(media_helpers)
+        importlib.reload(chat_export_service)
+        return chat_export_service
+
+    def _seed_contact_db(self, path: Path, *, account: str, username: str) -> None:
+        conn = sqlite3.connect(str(path))
+        try:
+            conn.execute(
+                """
+                CREATE TABLE contact (
+                    username TEXT,
+                    remark TEXT,
+                    nick_name TEXT,
+                    alias TEXT,
+                    local_type INTEGER,
+                    verify_flag INTEGER,
+                    big_head_url TEXT,
+                    small_head_url TEXT
+                )
+                """
+            )
+            conn.execute(
+                """
+                CREATE TABLE stranger (
+                    username TEXT,
+                    remark TEXT,
+                    nick_name TEXT,
+                    alias TEXT,
+                    local_type INTEGER,
+                    verify_flag INTEGER,
+                    big_head_url TEXT,
+                    small_head_url TEXT
+                )
+                """
+            )
+            conn.execute(
+                "INSERT INTO contact VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+                (account, "", "我", "", 1, 0, "", ""),
+            )
+            conn.execute(
+                "INSERT INTO contact VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+                (username, "", "测试好友", "", 1, 0, "", ""),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    def _seed_session_db(self, path: Path, *, username: str) -> None:
+        conn = sqlite3.connect(str(path))
+        try:
+            conn.execute(
+                """
+                CREATE TABLE SessionTable (
+                    username TEXT,
+                    is_hidden INTEGER,
+                    sort_timestamp INTEGER
+                )
+                """
+            )
+            conn.execute(
+                "INSERT INTO SessionTable VALUES (?, ?, ?)",
+                (username, 0, 1735689600),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    def _seed_message_db(self, path: Path, *, account: str, username: str) -> None:
+        conn = sqlite3.connect(str(path))
+        try:
+            conn.execute("CREATE TABLE Name2Id (rowid INTEGER PRIMARY KEY, user_name TEXT)")
+            conn.execute("INSERT INTO Name2Id(rowid, user_name) VALUES (?, ?)", (1, account))
+            conn.execute("INSERT INTO Name2Id(rowid, user_name) VALUES (?, ?)", (2, username))
+
+            table_name = f"msg_{hashlib.md5(username.encode('utf-8')).hexdigest()}"
+            conn.execute(
+                f"""
+                CREATE TABLE {table_name} (
+                    local_id INTEGER,
+                    server_id INTEGER,
+                    local_type INTEGER,
+                    sort_seq INTEGER,
+                    real_sender_id INTEGER,
+                    create_time INTEGER,
+                    message_content TEXT,
+                    compress_content BLOB
+                )
+                """
+            )
+
+            image_xml = '<msg><img md5="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" cdnthumburl="img_file_id_1" /></msg>'
+            video_xml = '<msg><videomsg md5="bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" cdnthumbmd5="cccccccccccccccccccccccccccccccc" cdnvideourl="video_file_id_1" cdnthumburl="video_thumb_id_1" /></msg>'
+
+            rows = [
+                (1, 1001, 3, 1, 2, 1735689601, image_xml, None),
+                (2, 1002, 43, 2, 2, 1735689602, video_xml, None),
+                (3, 1003, 49, 3, 2, 1735689603, '<msg><appmsg><type>2000</type><des>收到转账0.01元</des></appmsg></msg>', None),
+                (4, 1004, 1, 4, 2, 1735689604, '普通文本消息', None),
+                (5, 1005, 10000, 5, 2, 1735689605, '系统提示消息', None),
+            ]
+            conn.executemany(
+                f"INSERT INTO {table_name} (local_id, server_id, local_type, sort_seq, real_sender_id, create_time, message_content, compress_content) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+                rows,
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    def _seed_media_files(self, account_dir: Path) -> None:
+        resource_root = account_dir / "resource"
+        (resource_root / "aa").mkdir(parents=True, exist_ok=True)
+        (resource_root / "bb").mkdir(parents=True, exist_ok=True)
+        (resource_root / "cc").mkdir(parents=True, exist_ok=True)
+
+        (resource_root / "aa" / "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.jpg").write_bytes(b"\xff\xd8\xff\xd9")
+        (resource_root / "bb" / "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb.mp4").write_bytes(b"video-bytes")
+        (resource_root / "cc" / "cccccccccccccccccccccccccccccccc.jpg").write_bytes(b"\xff\xd8\xff\xd9")
+
+    def _seed_source_info(self, account_dir: Path, wxid_dir: Path) -> None:
+        payload = {
+            "wxid_dir": str(wxid_dir),
+            "db_storage_path": str(wxid_dir / "db_storage"),
+        }
+        (account_dir / "_source.json").write_text(json.dumps(payload, ensure_ascii=False), encoding="utf-8")
+
+    def _seed_wxid_media_files(self, wxid_dir: Path) -> None:
+        (wxid_dir / "msg" / "video").mkdir(parents=True, exist_ok=True)
+        (wxid_dir / "msg" / "attach").mkdir(parents=True, exist_ok=True)
+        (wxid_dir / "cache").mkdir(parents=True, exist_ok=True)
+        (wxid_dir / "db_storage").mkdir(parents=True, exist_ok=True)
+
+        (wxid_dir / "msg" / "video" / "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb.mp4").write_bytes(b"video-bytes")
+        (wxid_dir / "msg" / "video" / "cccccccccccccccccccccccccccccccc.jpg").write_bytes(b"\xff\xd8\xff\xd9")
+
+    def _prepare_account(self, root: Path, *, account: str, username: str) -> Path:
+        account_dir = root / "output" / "databases" / account
+        account_dir.mkdir(parents=True, exist_ok=True)
+        wxid_dir = root / "wxid_data" / account
+
+        self._seed_contact_db(account_dir / "contact.db", account=account, username=username)
+        self._seed_session_db(account_dir / "session.db", username=username)
+        self._seed_message_db(account_dir / "message_0.db", account=account, username=username)
+        self._seed_media_files(account_dir)
+        self._seed_wxid_media_files(wxid_dir)
+        self._seed_source_info(account_dir, wxid_dir)
+        return account_dir
+
+    def _create_job(self, manager, *, account: str, username: str, message_types, include_media=True, media_kinds=None, privacy_mode=False):
+        if media_kinds is None:
+            media_kinds = ["image", "emoji", "video", "video_thumb", "voice", "file"]
+
+        job = manager.create_job(
+            account=account,
+            scope="selected",
+            usernames=[username],
+            export_format="json",
+            start_time=None,
+            end_time=None,
+            include_hidden=False,
+            include_official=False,
+            include_media=include_media,
+            media_kinds=media_kinds,
+            message_types=message_types,
+            output_dir=None,
+            allow_process_key_extract=False,
+            privacy_mode=privacy_mode,
+            file_name=None,
+        )
+
+        for _ in range(200):
+            latest = manager.get_job(job.export_id)
+            if latest and latest.status in {"done", "error", "cancelled"}:
+                return latest
+            import time as _time
+
+            _time.sleep(0.05)
+        self.fail("export job did not finish in time")
+
+    def _load_export_payload(self, zip_path: Path):
+        self.assertTrue(zip_path.exists())
+        with zipfile.ZipFile(zip_path, "r") as zf:
+            names = set(zf.namelist())
+            msg_path = next((n for n in names if n.endswith("/messages.json")), "")
+            self.assertTrue(msg_path)
+            import json as _json
+
+            payload = _json.loads(zf.read(msg_path).decode("utf-8"))
+            manifest = _json.loads(zf.read("manifest.json").decode("utf-8"))
+        return payload, manifest, names
+
+    def test_unchecked_image_is_filtered_out(self):
+        with TemporaryDirectory() as td:
+            root = Path(td)
+            account = "wxid_test"
+            username = "wxid_friend"
+            self._prepare_account(root, account=account, username=username)
+
+            prev_data = os.environ.get("WECHAT_TOOL_DATA_DIR")
+            try:
+                os.environ["WECHAT_TOOL_DATA_DIR"] = str(root)
+                svc = self._reload_export_modules()
+                job = self._create_job(
+                    svc.CHAT_EXPORT_MANAGER,
+                    account=account,
+                    username=username,
+                    message_types=["text", "transfer"],
+                    include_media=True,
+                )
+                self.assertEqual(job.status, "done", msg=job.error)
+
+                payload, _, names = self._load_export_payload(job.zip_path)
+                image_msg = next((m for m in payload.get("messages", []) if int(m.get("type") or 0) == 3), None)
+                self.assertIsNone(image_msg)
+                render_types = {str(m.get("renderType") or "") for m in payload.get("messages", [])}
+                self.assertTrue(render_types.issubset({"text", "transfer"}))
+                self.assertFalse(any(n.startswith("media/images/") for n in names))
+            finally:
+                if prev_data is None:
+                    os.environ.pop("WECHAT_TOOL_DATA_DIR", None)
+                else:
+                    os.environ["WECHAT_TOOL_DATA_DIR"] = prev_data
+
+    def test_checked_image_exports_media_file(self):
+        with TemporaryDirectory() as td:
+            root = Path(td)
+            account = "wxid_test"
+            username = "wxid_friend"
+            self._prepare_account(root, account=account, username=username)
+
+            prev_data = os.environ.get("WECHAT_TOOL_DATA_DIR")
+            try:
+                os.environ["WECHAT_TOOL_DATA_DIR"] = str(root)
+                svc = self._reload_export_modules()
+                job = self._create_job(
+                    svc.CHAT_EXPORT_MANAGER,
+                    account=account,
+                    username=username,
+                    message_types=["image", "text"],
+                    include_media=True,
+                )
+                self.assertEqual(job.status, "done", msg=job.error)
+
+                payload, _, names = self._load_export_payload(job.zip_path)
+                image_msg = next((m for m in payload.get("messages", []) if int(m.get("type") or 0) == 3), None)
+                self.assertIsNotNone(image_msg)
+                self.assertEqual(str(image_msg.get("renderType") or ""), "image")
+                self.assertTrue(isinstance(image_msg.get("offlineMedia"), list) and image_msg.get("offlineMedia"))
+                self.assertTrue(any(n.startswith("media/images/") for n in names))
+            finally:
+                if prev_data is None:
+                    os.environ.pop("WECHAT_TOOL_DATA_DIR", None)
+                else:
+                    os.environ["WECHAT_TOOL_DATA_DIR"] = prev_data
+
+    def test_unchecked_non_media_type_is_filtered_out(self):
+        with TemporaryDirectory() as td:
+            root = Path(td)
+            account = "wxid_test"
+            username = "wxid_friend"
+            self._prepare_account(root, account=account, username=username)
+
+            prev_data = os.environ.get("WECHAT_TOOL_DATA_DIR")
+            try:
+                os.environ["WECHAT_TOOL_DATA_DIR"] = str(root)
+                svc = self._reload_export_modules()
+                job = self._create_job(
+                    svc.CHAT_EXPORT_MANAGER,
+                    account=account,
+                    username=username,
+                    message_types=["text"],
+                    include_media=True,
+                )
+                self.assertEqual(job.status, "done", msg=job.error)
+
+                payload, manifest, _ = self._load_export_payload(job.zip_path)
+                system_msg = next((m for m in payload.get("messages", []) if int(m.get("type") or 0) == 10000), None)
+                self.assertIsNone(system_msg)
+                self.assertTrue(all(str(m.get("renderType") or "") == "text" for m in payload.get("messages", [])))
+                self.assertEqual(manifest.get("filters", {}).get("messageTypes"), ["text"])
+            finally:
+                if prev_data is None:
+                    os.environ.pop("WECHAT_TOOL_DATA_DIR", None)
+                else:
+                    os.environ["WECHAT_TOOL_DATA_DIR"] = prev_data
+
+    def test_checked_video_exports_video_and_thumb(self):
+        with TemporaryDirectory() as td:
+            root = Path(td)
+            account = "wxid_test"
+            username = "wxid_friend"
+            self._prepare_account(root, account=account, username=username)
+
+            prev_data = os.environ.get("WECHAT_TOOL_DATA_DIR")
+            try:
+                os.environ["WECHAT_TOOL_DATA_DIR"] = str(root)
+                svc = self._reload_export_modules()
+                job = self._create_job(
+                    svc.CHAT_EXPORT_MANAGER,
+                    account=account,
+                    username=username,
+                    message_types=["video", "text"],
+                    include_media=True,
+                )
+                self.assertEqual(job.status, "done", msg=job.error)
+
+                payload, _, names = self._load_export_payload(job.zip_path)
+                video_msg = next((m for m in payload.get("messages", []) if int(m.get("type") or 0) == 43), None)
+                self.assertIsNotNone(video_msg)
+                self.assertEqual(str(video_msg.get("renderType") or ""), "video")
+                image_msg = next((m for m in payload.get("messages", []) if int(m.get("type") or 0) == 3), None)
+                self.assertIsNone(image_msg)
+                media_items = video_msg.get("offlineMedia") or []
+                kinds = sorted(str(x.get("kind") or "") for x in media_items)
+                self.assertIn("video", kinds)
+                self.assertIn("video_thumb", kinds)
+                self.assertTrue(any(n.startswith("media/videos/") for n in names))
+                self.assertTrue(any(n.startswith("media/video_thumbs/") for n in names))
+            finally:
+                if prev_data is None:
+                    os.environ.pop("WECHAT_TOOL_DATA_DIR", None)
+                else:
+                    os.environ["WECHAT_TOOL_DATA_DIR"] = prev_data
+
+    def test_privacy_mode_never_exports_media(self):
+        with TemporaryDirectory() as td:
+            root = Path(td)
+            account = "wxid_test"
+            username = "wxid_friend"
+            self._prepare_account(root, account=account, username=username)
+
+            prev_data = os.environ.get("WECHAT_TOOL_DATA_DIR")
+            try:
+                os.environ["WECHAT_TOOL_DATA_DIR"] = str(root)
+                svc = self._reload_export_modules()
+                job = self._create_job(
+                    svc.CHAT_EXPORT_MANAGER,
+                    account=account,
+                    username=username,
+                    message_types=["image", "video", "text"],
+                    include_media=True,
+                    privacy_mode=True,
+                )
+                self.assertEqual(job.status, "done", msg=job.error)
+
+                payload, manifest, names = self._load_export_payload(job.zip_path)
+                self.assertFalse(any(n.startswith("media/images/") for n in names))
+                self.assertFalse(any(n.startswith("media/videos/") for n in names))
+                self.assertFalse(any(n.startswith("media/video_thumbs/") for n in names))
+
+                for msg in payload.get("messages", []):
+                    self.assertFalse(msg.get("offlineMedia"))
+
+                self.assertFalse(bool(manifest.get("options", {}).get("includeMedia")))
+            finally:
+                if prev_data is None:
+                    os.environ.pop("WECHAT_TOOL_DATA_DIR", None)
+                else:
+                    os.environ["WECHAT_TOOL_DATA_DIR"] = prev_data
+
+    def test_transfer_only_exports_transfer_messages(self):
+        with TemporaryDirectory() as td:
+            root = Path(td)
+            account = "wxid_test"
+            username = "wxid_friend"
+            self._prepare_account(root, account=account, username=username)
+
+            prev_data = os.environ.get("WECHAT_TOOL_DATA_DIR")
+            try:
+                os.environ["WECHAT_TOOL_DATA_DIR"] = str(root)
+                svc = self._reload_export_modules()
+                job = self._create_job(
+                    svc.CHAT_EXPORT_MANAGER,
+                    account=account,
+                    username=username,
+                    message_types=["transfer"],
+                    include_media=True,
+                )
+                self.assertEqual(job.status, "done", msg=job.error)
+
+                payload, manifest, _ = self._load_export_payload(job.zip_path)
+                messages = list(payload.get("messages", []))
+                self.assertEqual(len(messages), 1)
+                self.assertTrue(all(str(m.get("renderType") or "") == "transfer" for m in messages))
+                self.assertEqual(manifest.get("filters", {}).get("messageTypes"), ["transfer"])
+            finally:
+                if prev_data is None:
+                    os.environ.pop("WECHAT_TOOL_DATA_DIR", None)
+                else:
+                    os.environ["WECHAT_TOOL_DATA_DIR"] = prev_data
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,71 @@
+import sys
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "src"))
+
+
+class TestContactTypeDetection(unittest.TestCase):
+    def test_infer_group(self):
+        from wechat_decrypt_tool.routers.chat_contacts import _infer_contact_type
+
+        row = {"local_type": 0, "alias": "", "remark": "", "nick_name": ""}
+        self.assertEqual(_infer_contact_type("123@chatroom", row), "group")
+
+    def test_infer_official_by_prefix(self):
+        from wechat_decrypt_tool.routers.chat_contacts import _infer_contact_type
+
+        row = {"local_type": 0, "verify_flag": 0, "alias": "", "remark": "", "nick_name": ""}
+        self.assertEqual(_infer_contact_type("gh_xxx", row), "official")
+
+    def test_infer_official_by_verify_flag(self):
+        from wechat_decrypt_tool.routers.chat_contacts import _infer_contact_type
+
+        row = {"local_type": 1, "verify_flag": 24, "alias": "", "remark": "", "nick_name": ""}
+        self.assertEqual(_infer_contact_type("wxid_xxx", row), "official")
+
+    def test_infer_none_for_local_type_3_without_verify(self):
+        from wechat_decrypt_tool.routers.chat_contacts import _infer_contact_type
+
+        row = {"local_type": 3, "verify_flag": 0, "alias": "", "remark": "", "nick_name": "普通联系人"}
+        self.assertIsNone(_infer_contact_type("wxid_xxx", row))
+
+    def test_infer_none_from_wxid_alias_when_local_type_not_1(self):
+        from wechat_decrypt_tool.routers.chat_contacts import _infer_contact_type
+
+        row = {"local_type": 0, "verify_flag": 0, "alias": "wechat_id", "remark": "", "nick_name": ""}
+        self.assertIsNone(_infer_contact_type("wxid_xxx", row))
+
+    def test_infer_friend_from_local_type_1(self):
+        from wechat_decrypt_tool.routers.chat_contacts import _infer_contact_type
+
+        row = {"local_type": 1, "verify_flag": 0, "alias": "", "remark": "", "nick_name": ""}
+        self.assertEqual(_infer_contact_type("wxid_xxx", row), "friend")
+
+    def test_infer_none_from_local_type_2(self):
+        from wechat_decrypt_tool.routers.chat_contacts import _infer_contact_type
+
+        row = {"local_type": 2, "verify_flag": 0, "alias": "", "remark": "", "nick_name": ""}
+        self.assertIsNone(_infer_contact_type("wxid_xxx", row))
+
+    def test_infer_none_when_empty_type_0(self):
+        from wechat_decrypt_tool.routers.chat_contacts import _infer_contact_type
+
+        row = {"local_type": 0, "verify_flag": 0, "alias": "", "remark": "", "nick_name": ""}
+        self.assertIsNone(_infer_contact_type("wxid_xxx", row))
+
+    def test_valid_contact_username_filters_system_accounts(self):
+        from wechat_decrypt_tool.routers.chat_contacts import _is_valid_contact_username
+
+        self.assertFalse(_is_valid_contact_username("filehelper"))
+        self.assertFalse(_is_valid_contact_username("notifymessage"))
+        self.assertFalse(_is_valid_contact_username("fake_abc"))
+        self.assertTrue(_is_valid_contact_username("weixin"))
+        self.assertTrue(_is_valid_contact_username("wxid_abc"))
+        self.assertTrue(_is_valid_contact_username("123@chatroom"))
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,546 @@
+import json
+import os
+import sqlite3
+import sys
+import unittest
+import importlib
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "src"))
+
+
+class TestContactsExport(unittest.TestCase):
+    @staticmethod
+    def _encode_varint(value: int) -> bytes:
+        v = int(value)
+        out = bytearray()
+        while True:
+            b = v & 0x7F
+            v >>= 7
+            if v:
+                out.append(b | 0x80)
+            else:
+                out.append(b)
+                break
+        return bytes(out)
+
+    @classmethod
+    def _encode_field_len(cls, field_no: int, raw: bytes) -> bytes:
+        tag = (int(field_no) << 3) | 2
+        payload = bytes(raw)
+        return cls._encode_varint(tag) + cls._encode_varint(len(payload)) + payload
+
+    @classmethod
+    def _encode_field_varint(cls, field_no: int, value: int) -> bytes:
+        tag = int(field_no) << 3
+        return cls._encode_varint(tag) + cls._encode_varint(int(value))
+
+    @classmethod
+    def _build_extra_buffer(cls, *, country: str, province: str, city: str, source_scene: int) -> bytes:
+        return b"".join(
+            [
+                cls._encode_field_len(5, country.encode("utf-8")),
+                cls._encode_field_len(6, province.encode("utf-8")),
+                cls._encode_field_len(7, city.encode("utf-8")),
+                cls._encode_field_varint(8, source_scene),
+            ]
+        )
+
+    def _seed_contact_db(self, path: Path) -> None:
+        conn = sqlite3.connect(str(path))
+        try:
+            conn.execute(
+                """
+                CREATE TABLE contact (
+                    username TEXT,
+                    remark TEXT,
+                    nick_name TEXT,
+                    alias TEXT,
+                    local_type INTEGER,
+                    verify_flag INTEGER,
+                    big_head_url TEXT,
+                    small_head_url TEXT,
+                    extra_buffer BLOB
+                )
+                """
+            )
+            conn.execute(
+                """
+                CREATE TABLE stranger (
+                    username TEXT,
+                    remark TEXT,
+                    nick_name TEXT,
+                    alias TEXT,
+                    local_type INTEGER,
+                    verify_flag INTEGER,
+                    big_head_url TEXT,
+                    small_head_url TEXT,
+                    extra_buffer BLOB
+                )
+                """
+            )
+
+            friend_extra_buffer = self._build_extra_buffer(
+                country="CN",
+                province="Sichuan",
+                city="Chengdu",
+                source_scene=14,
+            )
+
+            conn.execute(
+                "INSERT INTO contact VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                (
+                    "wxid_friend",
+                    "好友备注",
+                    "好友昵称",
+                    "friend_alias",
+                    1,
+                    0,
+                    "https://cdn.example.com/friend_big.jpg",
+                    "https://cdn.example.com/friend_small.jpg",
+                    friend_extra_buffer,
+                ),
+            )
+            conn.execute(
+                "INSERT INTO contact VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                (
+                    "room@chatroom",
+                    "",
+                    "测试群",
+                    "",
+                    0,
+                    0,
+                    "https://cdn.example.com/group_big.jpg",
+                    "",
+                    b"",
+                ),
+            )
+            conn.execute(
+                "INSERT INTO contact VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                (
+                    "gh_official",
+                    "",
+                    "公众号",
+                    "",
+                    4,
+                    8,
+                    "",
+                    "https://cdn.example.com/official_small.jpg",
+                    b"",
+                ),
+            )
+            conn.execute(
+                "INSERT INTO contact VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                (
+                    "wxid_local_type_3",
+                    "",
+                    "不应计入联系人",
+                    "",
+                    3,
+                    0,
+                    "",
+                    "",
+                    b"",
+                ),
+            )
+            conn.execute(
+                "INSERT INTO contact VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                (
+                    "weixin",
+                    "",
+                    "微信团队",
+                    "",
+                    1,
+                    56,
+                    "",
+                    "",
+                    b"",
+                ),
+            )
+            conn.execute(
+                "INSERT INTO contact VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                (
+                    "filehelper",
+                    "",
+                    "文件传输助手",
+                    "",
+                    0,
+                    0,
+                    "",
+                    "",
+                    b"",
+                ),
+            )
+            conn.execute(
+                "INSERT INTO stranger VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                (
+                    "stranger_verified",
+                    "",
+                    "陌生人认证号",
+                    "",
+                    4,
+                    24,
+                    "",
+                    "",
+                    b"",
+                ),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    def _seed_session_db(self, path: Path) -> None:
+        conn = sqlite3.connect(str(path))
+        try:
+            conn.execute(
+                """
+                CREATE TABLE SessionTable (
+                    username TEXT,
+                    sort_timestamp INTEGER,
+                    last_timestamp INTEGER
+                )
+                """
+            )
+            conn.execute("INSERT INTO SessionTable VALUES (?, ?, ?)", ("room@chatroom", 300, 300))
+            conn.execute("INSERT INTO SessionTable VALUES (?, ?, ?)", ("wxid_friend", 200, 200))
+            conn.execute("INSERT INTO SessionTable VALUES (?, ?, ?)", ("gh_official", 100, 100))
+            conn.execute("INSERT INTO SessionTable VALUES (?, ?, ?)", ("missing@chatroom", 250, 250))
+            conn.commit()
+        finally:
+            conn.close()
+
+    def _seed_contact_db_legacy(self, path: Path) -> None:
+        conn = sqlite3.connect(str(path))
+        try:
+            conn.execute(
+                """
+                CREATE TABLE contact (
+                    username TEXT,
+                    remark TEXT,
+                    nick_name TEXT,
+                    alias TEXT,
+                    local_type INTEGER,
+                    verify_flag INTEGER,
+                    big_head_url TEXT,
+                    small_head_url TEXT
+                )
+                """
+            )
+            conn.execute(
+                """
+                CREATE TABLE stranger (
+                    username TEXT,
+                    remark TEXT,
+                    nick_name TEXT,
+                    alias TEXT,
+                    local_type INTEGER,
+                    verify_flag INTEGER,
+                    big_head_url TEXT,
+                    small_head_url TEXT
+                )
+                """
+            )
+            conn.execute(
+                "INSERT INTO contact VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+                (
+                    "wxid_legacy_friend",
+                    "旧版好友备注",
+                    "旧版好友昵称",
+                    "legacy_friend_alias",
+                    1,
+                    0,
+                    "",
+                    "",
+                ),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    def test_export_json_and_csv(self):
+        from fastapi import FastAPI
+        from fastapi.testclient import TestClient
+
+        with TemporaryDirectory() as td:
+            root = Path(td)
+            account = "wxid_test"
+            account_dir = root / "output" / "databases" / account
+            account_dir.mkdir(parents=True, exist_ok=True)
+
+            self._seed_contact_db(account_dir / "contact.db")
+            self._seed_session_db(account_dir / "session.db")
+
+            prev = None
+            try:
+                prev = os.environ.get("WECHAT_TOOL_DATA_DIR")
+                os.environ["WECHAT_TOOL_DATA_DIR"] = str(root)
+
+                import wechat_decrypt_tool.chat_helpers as chat_helpers
+                import wechat_decrypt_tool.routers.chat_contacts as chat_contacts
+
+                importlib.reload(chat_helpers)
+                importlib.reload(chat_contacts)
+
+                app = FastAPI()
+                app.include_router(chat_contacts.router)
+
+                client = TestClient(app)
+
+                list_resp = client.get(
+                    "/api/chat/contacts",
+                    params={
+                        "account": account,
+                        "include_friends": True,
+                        "include_groups": True,
+                        "include_officials": True,
+                    },
+                )
+                self.assertEqual(list_resp.status_code, 200)
+                list_payload = list_resp.json()
+                self.assertEqual(list_payload["status"], "success")
+                self.assertEqual(list_payload["total"], 6)
+                self.assertEqual(list_payload["counts"]["friends"], 1)
+                self.assertEqual(list_payload["counts"]["groups"], 2)
+                self.assertEqual(list_payload["counts"]["officials"], 3)
+                usernames = {str(x.get("username")) for x in list_payload.get("contacts", [])}
+                self.assertIn("missing@chatroom", usernames)
+                self.assertIn("weixin", usernames)
+                self.assertNotIn("wxid_local_type_3", usernames)
+                first = list_payload["contacts"][0]
+                self.assertIn("avatarLink", first)
+
+                friend_contact = next(
+                    (x for x in list_payload.get("contacts", []) if str(x.get("username")) == "wxid_friend"),
+                    {},
+                )
+                self.assertEqual(friend_contact.get("country"), "CN")
+                self.assertEqual(friend_contact.get("province"), "Sichuan")
+                self.assertEqual(friend_contact.get("city"), "Chengdu")
+                self.assertEqual(friend_contact.get("region"), "中国大陆·Sichuan·Chengdu")
+                self.assertEqual(friend_contact.get("sourceScene"), 14)
+                self.assertEqual(friend_contact.get("source"), "通过群聊添加")
+
+                export_dir = root / "exports"
+                export_dir.mkdir(parents=True, exist_ok=True)
+
+                json_resp = client.post(
+                    "/api/chat/contacts/export",
+                    json={
+                        "account": account,
+                        "output_dir": str(export_dir),
+                        "format": "json",
+                        "include_avatar_link": True,
+                        "contact_types": {
+                            "friends": True,
+                            "groups": True,
+                            "officials": True,
+                        },
+                    },
+                )
+                self.assertEqual(json_resp.status_code, 200)
+                json_payload = json_resp.json()
+                self.assertEqual(json_payload["status"], "success")
+                self.assertEqual(json_payload["count"], 6)
+                json_path = Path(json_payload["outputPath"])
+                self.assertTrue(json_path.exists())
+
+                data = json.loads(json_path.read_text(encoding="utf-8"))
+                self.assertEqual(data["count"], 6)
+                self.assertIn("avatarLink", data["contacts"][0])
+                self.assertIn("region", data["contacts"][0])
+                self.assertIn("country", data["contacts"][0])
+                self.assertIn("province", data["contacts"][0])
+                self.assertIn("city", data["contacts"][0])
+                self.assertIn("source", data["contacts"][0])
+                self.assertIn("sourceScene", data["contacts"][0])
+                export_usernames = {str(x.get("username")) for x in data.get("contacts", [])}
+                self.assertIn("missing@chatroom", export_usernames)
+                self.assertNotIn("wxid_local_type_3", export_usernames)
+
+                friend_export = next(
+                    (x for x in data.get("contacts", []) if str(x.get("username")) == "wxid_friend"),
+                    {},
+                )
+                self.assertEqual(friend_export.get("region"), "中国大陆·Sichuan·Chengdu")
+                self.assertEqual(friend_export.get("sourceScene"), 14)
+                self.assertEqual(friend_export.get("source"), "通过群聊添加")
+
+                csv_resp = client.post(
+                    "/api/chat/contacts/export",
+                    json={
+                        "account": account,
+                        "output_dir": str(export_dir),
+                        "format": "csv",
+                        "include_avatar_link": False,
+                        "contact_types": {
+                            "friends": True,
+                            "groups": False,
+                            "officials": False,
+                        },
+                    },
+                )
+                self.assertEqual(csv_resp.status_code, 200)
+                csv_payload = csv_resp.json()
+                self.assertEqual(csv_payload["count"], 1)
+                csv_path = Path(csv_payload["outputPath"])
+                text = csv_path.read_text(encoding="utf-8-sig")
+                self.assertIn("用户名,显示名称,备注,昵称,微信号,类型,地区,国家/地区码,省份,城市,来源,来源场景码", text.splitlines()[0])
+                self.assertNotIn("头像链接", text.splitlines()[0])
+                self.assertIn("wxid_friend", text)
+                self.assertIn("中国大陆·Sichuan·Chengdu", text)
+                self.assertIn("通过群聊添加", text)
+                self.assertIn(",14", text)
+                self.assertNotIn("wxid_local_type_3", text)
+            finally:
+                if prev is None:
+                    os.environ.pop("WECHAT_TOOL_DATA_DIR", None)
+                else:
+                    os.environ["WECHAT_TOOL_DATA_DIR"] = prev
+
+    def test_export_invalid_format_returns_400(self):
+        from fastapi import FastAPI
+        from fastapi.testclient import TestClient
+
+        with TemporaryDirectory() as td:
+            root = Path(td)
+            account = "wxid_test"
+            account_dir = root / "output" / "databases" / account
+            account_dir.mkdir(parents=True, exist_ok=True)
+
+            self._seed_contact_db(account_dir / "contact.db")
+            self._seed_session_db(account_dir / "session.db")
+
+            prev = None
+            try:
+                prev = os.environ.get("WECHAT_TOOL_DATA_DIR")
+                os.environ["WECHAT_TOOL_DATA_DIR"] = str(root)
+
+                import wechat_decrypt_tool.chat_helpers as chat_helpers
+                import wechat_decrypt_tool.routers.chat_contacts as chat_contacts
+
+                importlib.reload(chat_helpers)
+                importlib.reload(chat_contacts)
+
+                app = FastAPI()
+                app.include_router(chat_contacts.router)
+
+                client = TestClient(app)
+                resp = client.post(
+                    "/api/chat/contacts/export",
+                    json={
+                        "account": account,
+                        "output_dir": str(root / "exports"),
+                        "format": "vcf",
+                        "include_avatar_link": True,
+                        "contact_types": {
+                            "friends": True,
+                            "groups": True,
+                            "officials": True,
+                        },
+                    },
+                )
+                self.assertEqual(resp.status_code, 400)
+            finally:
+                if prev is None:
+                    os.environ.pop("WECHAT_TOOL_DATA_DIR", None)
+                else:
+                    os.environ["WECHAT_TOOL_DATA_DIR"] = prev
+
+    def test_missing_contact_db_returns_404(self):
+        from fastapi import FastAPI
+        from fastapi.testclient import TestClient
+
+        with TemporaryDirectory() as td:
+            root = Path(td)
+            account = "wxid_test"
+            account_dir = root / "output" / "databases" / account
+            account_dir.mkdir(parents=True, exist_ok=True)
+
+            # only session.db exists
+            self._seed_session_db(account_dir / "session.db")
+
+            prev = None
+            try:
+                prev = os.environ.get("WECHAT_TOOL_DATA_DIR")
+                os.environ["WECHAT_TOOL_DATA_DIR"] = str(root)
+
+                import wechat_decrypt_tool.chat_helpers as chat_helpers
+                import wechat_decrypt_tool.routers.chat_contacts as chat_contacts
+
+                importlib.reload(chat_helpers)
+                importlib.reload(chat_contacts)
+
+                app = FastAPI()
+                app.include_router(chat_contacts.router)
+                client = TestClient(app)
+
+                resp = client.get("/api/chat/contacts", params={"account": account})
+                self.assertEqual(resp.status_code, 404)
+            finally:
+                if prev is None:
+                    os.environ.pop("WECHAT_TOOL_DATA_DIR", None)
+                else:
+                    os.environ["WECHAT_TOOL_DATA_DIR"] = prev
+
+    def test_legacy_schema_without_extra_buffer_is_compatible(self):
+        from fastapi import FastAPI
+        from fastapi.testclient import TestClient
+
+        with TemporaryDirectory() as td:
+            root = Path(td)
+            account = "wxid_legacy"
+            account_dir = root / "output" / "databases" / account
+            account_dir.mkdir(parents=True, exist_ok=True)
+
+            self._seed_contact_db_legacy(account_dir / "contact.db")
+            self._seed_session_db(account_dir / "session.db")
+
+            prev = None
+            try:
+                prev = os.environ.get("WECHAT_TOOL_DATA_DIR")
+                os.environ["WECHAT_TOOL_DATA_DIR"] = str(root)
+
+                import wechat_decrypt_tool.chat_helpers as chat_helpers
+                import wechat_decrypt_tool.routers.chat_contacts as chat_contacts
+
+                importlib.reload(chat_helpers)
+                importlib.reload(chat_contacts)
+
+                app = FastAPI()
+                app.include_router(chat_contacts.router)
+                client = TestClient(app)
+
+                resp = client.get(
+                    "/api/chat/contacts",
+                    params={
+                        "account": account,
+                        "include_friends": True,
+                        "include_groups": False,
+                        "include_officials": False,
+                    },
+                )
+                self.assertEqual(resp.status_code, 200)
+                payload = resp.json()
+                self.assertEqual(payload.get("status"), "success")
+                self.assertEqual(int(payload.get("total", 0)), 1)
+
+                contact = payload.get("contacts", [])[0]
+                self.assertEqual(contact.get("username"), "wxid_legacy_friend")
+                self.assertEqual(contact.get("country"), "")
+                self.assertEqual(contact.get("province"), "")
+                self.assertEqual(contact.get("city"), "")
+                self.assertEqual(contact.get("region"), "")
+                self.assertIsNone(contact.get("sourceScene"))
+                self.assertEqual(contact.get("source"), "")
+            finally:
+                if prev is None:
+                    os.environ.pop("WECHAT_TOOL_DATA_DIR", None)
+                else:
+                    os.environ["WECHAT_TOOL_DATA_DIR"] = prev
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,2 @@
+> 这里放wx_key模块的python预编译wheel：https://github.com/H3CoF6/py_wx_key/releases/
+> 解压放入即可
@@ -1,5 +1,5 @@
 version = 1
-revision = 2
+revision = 3
 requires-python = ">=3.11"

 [[package]]
@@ -230,6 +230,19 @@ wheels = [
    { url = "https://files.pythonhosted.org/packages/04/4b/29cac41a4d98d144bf5f6d33995617b185d14b22401f75ca86f384e87ff1/h11-0.16.0-py3-none-any.whl", hash = "sha256:63cf8bbe7522de3bf65932fda1d9c2772064ffb3dae62d55932da54b31cb6c86", size = 37515, upload-time = "2025-04-24T03:35:24.344Z" },
 ]

+[[package]]
+name = "httpcore"
+version = "1.0.9"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "certifi" },
+    { name = "h11" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/06/94/82699a10bca87a5556c9c59b5963f2d039dbd239f25bc2a63907a05a14cb/httpcore-1.0.9.tar.gz", hash = "sha256:6e34463af53fd2ab5d807f399a9b45ea31c3dfa2276f15a2c3f00afff6e176e8", size = 85484, upload-time = "2025-04-24T22:06:22.219Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7e/f5/f66802a942d491edb555dd61e3a9961140fd64c90bce1eafd741609d334d/httpcore-1.0.9-py3-none-any.whl", hash = "sha256:2d400746a40668fc9dec9810239072b40b4484b640a8c38fd654a024c7a1bf55", size = 78784, upload-time = "2025-04-24T22:06:20.566Z" },
+]
+
 [[package]]
 name = "httptools"
 version = "0.6.4"
@@ -259,6 +272,21 @@ wheels = [
    { url = "https://files.pythonhosted.org/packages/4d/dc/7decab5c404d1d2cdc1bb330b1bf70e83d6af0396fd4fc76fc60c0d522bf/httptools-0.6.4-cp313-cp313-win_amd64.whl", hash = "sha256:28908df1b9bb8187393d5b5db91435ccc9c8e891657f9cbb42a2541b44c82fc8", size = 87682, upload-time = "2024-10-16T19:44:46.46Z" },
 ]

+[[package]]
+name = "httpx"
+version = "0.28.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio" },
+    { name = "certifi" },
+    { name = "httpcore" },
+    { name = "idna" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b1/df/48c586a5fe32a0f01324ee087459e112ebb7224f646c0b5023f5e79e9956/httpx-0.28.1.tar.gz", hash = "sha256:75e98c5f16b0f35b567856f597f06ff2270a374470a5c2392242528e3e3e42fc", size = 141406, upload-time = "2024-12-06T15:37:23.222Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2a/39/e50c7c3a983047577ee07d2a9e53faf5a69493943ec3f6a384bdc792deb2/httpx-0.28.1-py3-none-any.whl", hash = "sha256:d909fcccc110f8c7faf814ca82a9a4d816bc5a6dbfea25d6591d6985b8ba59ad", size = 73517, upload-time = "2024-12-06T15:37:21.509Z" },
+]
+
 [[package]]
 name = "idna"
 version = "3.10"
@@ -838,13 +866,15 @@ wheels = [

 [[package]]
 name = "wechat-decrypt-tool"
-version = "0.2.0"
+version = "0.2.1"
 source = { editable = "." }
 dependencies = [
    { name = "aiofiles" },
    { name = "cryptography" },
    { name = "fastapi" },
+    { name = "httpx" },
    { name = "loguru" },
+    { name = "packaging" },
    { name = "pilk" },
    { name = "psutil" },
    { name = "pycryptodome" },
@@ -854,6 +884,7 @@ dependencies = [
    { name = "requests" },
    { name = "typing-extensions" },
    { name = "uvicorn", extra = ["standard"] },
+    { name = "wx-key" },
    { name = "zstandard" },
 ]

@@ -867,7 +898,9 @@ requires-dist = [
    { name = "aiofiles", specifier = ">=23.2.1" },
    { name = "cryptography", specifier = ">=41.0.0" },
    { name = "fastapi", specifier = ">=0.104.0" },
+    { name = "httpx" },
    { name = "loguru", specifier = ">=0.7.0" },
+    { name = "packaging" },
    { name = "pilk", specifier = ">=0.2.4" },
    { name = "psutil", specifier = ">=7.0.0" },
    { name = "pycryptodome", specifier = ">=3.23.0" },
@@ -878,6 +911,7 @@ requires-dist = [
    { name = "requests", specifier = ">=2.32.4" },
    { name = "typing-extensions", specifier = ">=4.8.0" },
    { name = "uvicorn", extras = ["standard"], specifier = ">=0.24.0" },
+    { name = "wx-key" },
    { name = "zstandard", specifier = ">=0.23.0" },
 ]
 provides-extras = ["build"]
@@ -891,6 +925,17 @@ wheels = [
    { url = "https://files.pythonhosted.org/packages/e1/07/c6fe3ad3e685340704d314d765b7912993bcb8dc198f0e7a89382d37974b/win32_setctime-1.2.0-py3-none-any.whl", hash = "sha256:95d644c4e708aba81dc3704a116d8cbc974d70b3bdb8be1d150e36be6e9d1390", size = 4083, upload-time = "2024-12-07T15:28:26.465Z" },
 ]

+[[package]]
+name = "wx-key"
+version = "1.0.0"
+source = { registry = "tools/key_wheels" }
+wheels = [
+    { path = "wx_key-1.0.0-cp311-cp311-win_amd64.whl" },
+    { path = "wx_key-1.0.0-cp312-cp312-win_amd64.whl" },
+    { path = "wx_key-1.0.0-cp313-cp313-win_amd64.whl" },
+    { path = "wx_key-1.0.0-cp314-cp314-win_amd64.whl" },
+]
+
 [[package]]
 name = "zstandard"
 version = "0.25.0"