diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 26b18151..e475426f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -130,3 +130,39 @@ jobs:
             mv apps/desktop/package.dev.json apps/desktop/package.json
           fi
           rm -f apps/desktop/package.release.json
+
+  # 浏览器版打包冒烟：构建 → 两个守卫 → 启动真实产物走一遍鉴权流程。
+  # 守卫防的是同一类回归：Electron-only 的代码混进 web 构建后不会报错，
+  # 只在运行时炸成一句看不懂的 "does not provide an export named 'app'"。
+  build-web:
+    runs-on: ubuntu-latest
+    env:
+      ELECTRON_SKIP_BINARY_DOWNLOAD: '1'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      # 鉴权闸 + 端到端路由测试。不需要构建产物，先跑、失败得早。
+      - name: Test auth gate
+        run: pnpm --filter @weq/web test
+
+      # build 内含 check：check-electron-free（走真实 import 图）
+      # + check-bundle（扫前端产物里残留的自定义协议 URL）。
+      - name: Build + guards
+        run: pnpm --filter @weq/web build
+
+      # 启动打包好的 server.mjs 走一遍完整流程 —— 覆盖 esbuild 的 CJS 互操作
+      # 和原生模块解析，这些只有真跑起来才会暴露。
+      - name: Smoke-test packaged server
+        run: pnpm --filter @weq/web test:dist
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 530382bd..50c9f20f 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -221,11 +221,64 @@ jobs:
           echo "== release/ tree =="
           ls -laR apps/desktop/release 2>/dev/null || echo "(no release/ dir)"
 
+  # ============================ Web（浏览器版）============================
+  # 平台无关：一个 tar.gz 同时含 win32-x64 / linux-x64 / linux-arm64 三份
+  # native/，运行时按 process.platform/arch 自动选，所以只构建一次。
+  # 不内置 Node（要求机器上有 Node ≥22），产物约 24 MB。
+  #
+  # 依赖 windows job：Release 由 electron-builder --publish 创建，这里只往
+  # 已存在的 Release 上传，不自己建。
+  web:
+    needs: [windows]
+    runs-on: ubuntu-latest
+    env:
+      ELECTRON_SKIP_BINARY_DOWNLOAD: '1'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      # 版本号会被 esbuild 烘焙进 server.mjs（设置页显示 + 压缩包命名）。
+      - name: Sync version from tag
+        run: node scripts/set-version.mjs ${{ github.ref_name }}
+
+      # 含 check 守卫：确认没有 Electron 代码泄漏进 web 构建。
+      - name: Build + guards
+        run: pnpm --filter @weq/web build
+
+      # 发布前先启动打包产物验一遍，别把跑不起来的包传上去。
+      - name: Smoke-test packaged server
+        run: pnpm --filter @weq/web test:dist
+
+      - name: Pack tarball
+        run: pnpm --filter @weq/web pack:release ${{ github.ref_name }}
+
+      - name: Upload to release
+        run: gh release upload "${{ github.ref_name }}" apps/web/release/*.tar.gz --clobber
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Dump build output on failure
+        if: failure()
+        run: |
+          echo "== apps/web/dist =="
+          ls -laR apps/web/dist 2>/dev/null | head -50 || echo "(no dist/)"
+
   # ======================= Release 说明（中文）=======================
-  # 等三个平台都发完（Release 已存在），用「中文说明头 + GitHub 自动
+  # 等四个产物都发完（Release 已存在），用「中文说明头 + GitHub 自动
   # 生成的 commit/PR 变更列表」覆写 Release 正文，并标注 aarch64 未实测。
   notes:
-    needs: [windows, linux-x64, linux-arm64]
+    needs: [windows, linux-x64, linux-arm64, web]
     runs-on: ubuntu-latest
     steps:
       - name: 生成并写入中文 Release 说明
@@ -254,6 +307,9 @@ jobs:
           - **Windows**: \`weQ-${TAG#v}-setup.exe\`
           - **Linux x64**: \`weQ-${TAG#v}-linux-x64.AppImage\` / \`.tar.gz\`
           - **Linux arm64（未实测）**: \`weQ-${TAG#v}-linux-arm64.AppImage\` / \`.tar.gz\`
+          - **浏览器版**: \`weq-web-${TAG#v}.tar.gz\` —— 三平台通用，需自备 Node ≥22。
+            解压后 \`npm install --omit=dev && node server.mjs\`，
+            详见[使用说明](https://github.com/${REPO}/blob/main/apps/web/README.md)
 
           ### 变更
           ${CHANGES}
diff --git a/.gitignore b/.gitignore
index 2ea96723..807d89cd 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,6 +8,10 @@ out/
 build/
 *.tsbuildinfo
 
+# weq web runtime dirs (exports / logs, created next to the server)
+weq-exports/
+weq-data/
+
 
 # editor / OS
 .DS_Store
diff --git a/README.md b/README.md
index 144a5f17..0ef3a7da 100644
--- a/README.md
+++ b/README.md
@@ -44,6 +44,21 @@
 2. 按照引导操作获取数据库密钥 (**无需提前打开QQ**)
 3. 打开对应账号即可开始使用
 
+### 浏览器版
+
+除桌面版外还提供 **WeQ Web** —— 同一套界面与功能，跑在浏览器里。适合无桌面环境的机器
+（NAS / 服务器 / WSL），或想从别的设备访问。
+
+下载 `weq-web-<版本>.tar.gz`（三平台通用，需自备 Node ≥ 22），解压后：
+
+```bash
+npm install --omit=dev
+node server.mjs
+```
+
+终端会打印地址和访问令牌，浏览器打开即可。默认只监听本机；
+**对外暴露前请先读 [apps/web/README.md](./apps/web/README.md)**。
+
 #### 开发者指南
 
 > 
diff --git a/apps/desktop/electron.vite.config.ts b/apps/desktop/electron.vite.config.ts
index 65612e5b..5f920d23 100644
--- a/apps/desktop/electron.vite.config.ts
+++ b/apps/desktop/electron.vite.config.ts
@@ -58,6 +58,8 @@ export default defineConfig({
       alias: {
         '@renderer': resolve(__dirname, 'src/renderer/src'),
         '@resources': resolve(__dirname, '../../resources'),
+        // Per-target tRPC transport; the web app aliases this to transport.web.
+        '@transport': resolve(__dirname, 'src/renderer/src/trpc/transport.electron.ts'),
       },
     },
     build: {
diff --git a/apps/desktop/package.json b/apps/desktop/package.json
index a50e52e4..ee8d596a 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -4,6 +4,9 @@
   "private": true,
   "type": "module",
   "main": "./out/main/index.js",
+  "exports": {
+    "./main/*": "./src/main/*.ts"
+  },
   "scripts": {
     "dev": "electron-vite dev",
     "build": "electron-vite build && electron-builder",
diff --git a/apps/desktop/src/main/avatar_protocol.ts b/apps/desktop/src/main/avatar_protocol.ts
index 7e83ecb3..c0f3272b 100644
--- a/apps/desktop/src/main/avatar_protocol.ts
+++ b/apps/desktop/src/main/avatar_protocol.ts
@@ -16,7 +16,6 @@
  * `ready`; `registerAvatarProtocol()` MUST run after.
  */
 
-import { protocol } from 'electron';
 import { getAppContext } from './context/app_context';
 
 export const AVATAR_SCHEME = 'weq-avatar';
@@ -36,32 +35,34 @@ export const AVATAR_PRIVILEGED_SCHEME = {
   },
 } as const;
 
-export function registerAvatarProtocol(): void {
-  protocol.handle(AVATAR_SCHEME, async (request) => {
-    const url = new URL(request.url);
-    const src = url.searchParams.get('src');
-    if (!src) {
-      return new Response('missing src', { status: 400 });
-    }
+/**
+ * Serve one `weq-avatar://` request. Pure `Request`→`Response`, so the web app
+ * can mount it on a plain HTTP route (see `apps/web`) without Electron.
+ */
+export async function handleAvatarRequest(request: Request): Promise<Response> {
+  const url = new URL(request.url);
+  const src = url.searchParams.get('src');
+  if (!src) {
+    return new Response('missing src', { status: 400 });
+  }
 
-    const ctx = getAppContext();
-    if (!ctx.bootstrap) {
-      return new Response('native unavailable', { status: 503 });
-    }
+  const ctx = getAppContext();
+  if (!ctx.bootstrap) {
+    return new Response('native unavailable', { status: 503 });
+  }
 
-    try {
-      const blob = await ctx.bootstrap.avatarCache.get(src);
-      return new Response(new Uint8Array(blob.data), {
-        status: 200,
-        headers: {
-          'Content-Type': blob.contentType,
-          // Let the renderer / Chromium memory-cache it too; the on-disk cache
-          // is authoritative, this just avoids re-asking the protocol.
-          'Cache-Control': 'public, max-age=86400',
-        },
-      });
-    } catch {
-      return new Response('avatar fetch failed', { status: 502 });
-    }
-  });
+  try {
+    const blob = await ctx.bootstrap.avatarCache.get(src);
+    return new Response(new Uint8Array(blob.data), {
+      status: 200,
+      headers: {
+        'Content-Type': blob.contentType,
+        // Let the renderer / Chromium memory-cache it too; the on-disk cache
+        // is authoritative, this just avoids re-asking the protocol.
+        'Cache-Control': 'public, max-age=86400',
+      },
+    });
+  } catch {
+    return new Response('avatar fetch failed', { status: 502 });
+  }
 }
diff --git a/apps/desktop/src/main/context/app_context.ts b/apps/desktop/src/main/context/app_context.ts
index 26a0c31c..02aef54e 100644
--- a/apps/desktop/src/main/context/app_context.ts
+++ b/apps/desktop/src/main/context/app_context.ts
@@ -31,7 +31,7 @@ import { aiToolSpecs, runAiTool } from '../mcp/openai_tools';
 import { getExternalMcpHub, disposeExternalMcp } from '../mcp/external';
 import { sampleHitokoto } from '../hitokoto';
 import { pkexecStubHooks } from '../stub_elevation';
-import { getQqProtocolExe } from './qq_protocol';
+import { getQqProtocolExe } from './qq_protocol_cache';
 import { createPkexecInjectHook } from '../inject_elevation';
 import {
   accountConfigId,
diff --git a/apps/desktop/src/main/context/qq_protocol.ts b/apps/desktop/src/main/context/qq_protocol.ts
index 1c664235..375f3c55 100644
--- a/apps/desktop/src/main/context/qq_protocol.ts
+++ b/apps/desktop/src/main/context/qq_protocol.ts
@@ -1,32 +1,24 @@
 /**
- * Resolve which exe the OS associates with QQ's `tencent://` URL scheme, so
- * the win32 platform can anchor every install path (QQ.exe / wrapper.node /
- * version) on it instead of the `Uninstall\QQ` registry key — which is missing
- * or relocated for portable installs, non-standard layouts, and machines whose
- * registry has been cleaned.
+ * Probe which exe the OS associates with QQ's `tencent://` URL scheme.
  *
- * The handler is QQNT's `timwp.exe`, sitting in the same `resources/app` dir as
- * `wrapper.node`. We prefer `tencent://`, then `mqqapi://` (both point at the
- * same handler in practice; the second is a fallback for installs that only
- * registered one). Anything else — no association, throw — leaves the cached
- * value null and the platform silently falls back to the registry probe.
+ * We prefer `tencent://`, then `mqqapi://` (both point at the same handler in
+ * practice; the second is a fallback for installs that only registered one).
+ * Anything else — no association, throw — leaves the cached value null and the
+ * platform silently falls back to the registry probe.
  *
  * Win32-only: linux QQ doesn't register these schemes, so the caller skips the
- * probe there entirely and the getter stays null.
+ * probe there entirely and the cache stays null.
+ *
+ * Electron-only (needs `app.getApplicationInfoForProtocol`). The cache itself
+ * lives in `qq_protocol_cache.ts` so non-Electron hosts can read it.
  */
 
 import { app } from 'electron';
 import { getLogger } from '@weq/service';
+import { setQqProtocolExe } from './qq_protocol_cache';
 
 const SCHEMES = ['tencent://', 'mqqapi://'] as const;
 
-let cachedExe: string | null = null;
-
-/** The resolved protocol-handler exe path, or null until/unless the probe finds one. */
-export function getQqProtocolExe(): string | null {
-  return cachedExe;
-}
-
 /**
  * Probe the OS protocol association once and cache the handler exe path. Safe
  * to call before any path lookup; resolves (never rejects) so a missing
@@ -38,7 +30,7 @@ export async function probeQqProtocolHandler(): Promise<void> {
     try {
       const info = await app.getApplicationInfoForProtocol(scheme);
       if (info.path) {
-        cachedExe = info.path;
+        setQqProtocolExe(info.path);
         logger.info('resolved QQ protocol handler', {
           event: 'qq-protocol-resolved',
           scheme,
diff --git a/apps/desktop/src/main/context/qq_protocol_cache.ts b/apps/desktop/src/main/context/qq_protocol_cache.ts
new file mode 100644
index 00000000..a499f3dc
--- /dev/null
+++ b/apps/desktop/src/main/context/qq_protocol_cache.ts
@@ -0,0 +1,23 @@
+/**
+ * Cache for the exe the OS associates with QQ's `tencent://` URL scheme, so the
+ * win32 platform can anchor every install path (QQ.exe / wrapper.node /
+ * version) on it instead of the `Uninstall\QQ` registry key — which is missing
+ * or relocated for portable installs, non-standard layouts, and machines whose
+ * registry has been cleaned.
+ *
+ * Only the cache lives here. The probe that fills it needs Electron's
+ * `app.getApplicationInfoForProtocol` and therefore sits in `qq_protocol.ts`,
+ * which only the desktop shell imports — this module stays Electron-free so
+ * `app_context` (and through it the web app) can depend on it.
+ */
+
+let cachedExe: string | null = null;
+
+/** The resolved protocol-handler exe path, or null until/unless a probe finds one. */
+export function getQqProtocolExe(): string | null {
+  return cachedExe;
+}
+
+export function setQqProtocolExe(path: string | null): void {
+  cachedExe = path;
+}
diff --git a/apps/desktop/src/main/file_response.ts b/apps/desktop/src/main/file_response.ts
new file mode 100644
index 00000000..49c71f43
--- /dev/null
+++ b/apps/desktop/src/main/file_response.ts
@@ -0,0 +1,111 @@
+/**
+ * `file://` → `Response`, without Electron's `net.fetch`.
+ *
+ * The protocol handlers used `net.fetch(pathToFileURL(p))` to stream a file off
+ * disk with `Range` support. Node's global `fetch` refuses `file://`, so the web
+ * app needs its own implementation — and since it must behave identically in
+ * both shells, Electron uses this one too.
+ *
+ * Streams via `createReadStream` (never buffers whole files: videos are large
+ * and `<video>` seeking issues range requests).
+ */
+
+import { createReadStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { extname } from 'node:path';
+import { Readable } from 'node:stream';
+
+const MIME: Record<string, string> = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.bmp': 'image/bmp',
+  '.svg': 'image/svg+xml',
+  '.apng': 'image/apng',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.mov': 'video/quicktime',
+  '.wav': 'audio/wav',
+  '.mp3': 'audio/mpeg',
+  '.ogg': 'audio/ogg',
+  '.m4a': 'audio/mp4',
+  '.ttf': 'font/ttf',
+  '.otf': 'font/otf',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.json': 'application/json',
+  '.html': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.txt': 'text/plain; charset=utf-8',
+};
+
+export function mimeOf(path: string): string {
+  return MIME[extname(path).toLowerCase()] ?? 'application/octet-stream';
+}
+
+/** Parse a single `bytes=a-b` range against `size`. Null when absent/unsatisfiable. */
+function parseRange(header: string | null, size: number): { start: number; end: number } | null {
+  if (!header) return null;
+  const m = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+  if (!m) return null;
+  const [, rawStart, rawEnd] = m;
+  let start: number;
+  let end: number;
+  if (rawStart === '') {
+    // Suffix form `bytes=-N` — the last N bytes.
+    const n = Number(rawEnd);
+    if (!Number.isFinite(n) || n <= 0) return null;
+    start = Math.max(0, size - n);
+    end = size - 1;
+  } else {
+    start = Number(rawStart);
+    end = rawEnd === '' ? size - 1 : Number(rawEnd);
+  }
+  if (!Number.isFinite(start) || !Number.isFinite(end)) return null;
+  if (start > end || start >= size) return null;
+  return { start, end: Math.min(end, size - 1) };
+}
+
+/**
+ * Stream `path` as a `Response`, honoring the request's `Range` header.
+ * Returns 404 when the file is missing, 206 for a partial response.
+ */
+export async function fileResponse(path: string, request?: Request): Promise<Response> {
+  let size: number;
+  try {
+    const st = await stat(path);
+    if (!st.isFile()) return new Response('not a file', { status: 404 });
+    size = st.size;
+  } catch {
+    return new Response('not found', { status: 404 });
+  }
+
+  const type = mimeOf(path);
+  const range = parseRange(request?.headers.get('range') ?? null, size);
+
+  if (range) {
+    const stream = createReadStream(path, { start: range.start, end: range.end });
+    return new Response(Readable.toWeb(stream) as ReadableStream, {
+      status: 206,
+      headers: {
+        'Content-Type': type,
+        'Content-Length': String(range.end - range.start + 1),
+        'Content-Range': `bytes ${range.start}-${range.end}/${size}`,
+        'Accept-Ranges': 'bytes',
+      },
+    });
+  }
+
+  const stream = createReadStream(path);
+  return new Response(Readable.toWeb(stream) as ReadableStream, {
+    status: 200,
+    headers: {
+      'Content-Type': type,
+      'Content-Length': String(size),
+      'Accept-Ranges': 'bytes',
+    },
+  });
+}
diff --git a/apps/desktop/src/main/host.ts b/apps/desktop/src/main/host.ts
new file mode 100644
index 00000000..2fb03c3c
--- /dev/null
+++ b/apps/desktop/src/main/host.ts
@@ -0,0 +1,65 @@
+/**
+ * Electron implementation of {@link HostBridge} — native file dialogs and
+ * `shell.openPath`. Installed once from `index.ts` before any router runs.
+ */
+
+import { app, dialog, shell } from 'electron';
+import type { HostBridge, SaveTarget } from '@weq/service';
+
+export const electronHost: HostBridge = {
+  canReveal: true,
+
+  async pickDirectory(opts) {
+    const result = await dialog.showOpenDialog({
+      title: opts?.title,
+      properties: ['openDirectory', 'createDirectory'],
+    });
+    if (result.canceled || result.filePaths.length === 0) return null;
+    return result.filePaths[0] ?? null;
+  },
+
+  async pickFile(opts) {
+    const result = await dialog.showOpenDialog({
+      title: opts?.title,
+      filters: opts?.extensions?.length
+        ? [{ name: 'File', extensions: opts.extensions }]
+        : undefined,
+      properties: ['openFile'],
+    });
+    if (result.canceled || result.filePaths.length === 0) return null;
+    return result.filePaths[0] ?? null;
+  },
+
+  async pickSaveTarget({ defaultName, extension }): Promise<SaveTarget | null> {
+    const result = await dialog.showSaveDialog({
+      defaultPath: defaultName,
+      filters: extension ? [{ name: 'File', extensions: [extension] }] : undefined,
+    });
+    if (result.canceled || !result.filePath) return null;
+    return { path: result.filePath, downloadId: null };
+  },
+
+  async revealPath(path) {
+    const err = await shell.openPath(path);
+    if (err) throw new Error(err);
+  },
+
+  async revealInFolder(path) {
+    shell.showItemInFolder(path);
+  },
+
+  async openHtmlReport(path) {
+    const { openReportWindow } = await import('./report_window');
+    await openReportWindow(path);
+    return null;
+  },
+
+  async openBotConsole({ url, key, title }) {
+    const { openBotWebUiWindow } = await import('./bot_webui_window');
+    await openBotWebUiWindow(url, key, title);
+    return null;
+  },
+
+  appVersion: () => app.getVersion(),
+  isPackaged: () => app.isPackaged,
+};
diff --git a/apps/desktop/src/main/index.ts b/apps/desktop/src/main/index.ts
index 2f2ad718..6e7bc656 100644
--- a/apps/desktop/src/main/index.ts
+++ b/apps/desktop/src/main/index.ts
@@ -8,31 +8,30 @@ import { initAppContext } from './context/app_context';
 import { probeQqProtocolHandler } from './context/qq_protocol';
 import { appRouter } from './ipc/router';
 import { resolveResource } from './resource';
+import { RESOURCE_PRIVILEGED_SCHEME } from './resource_protocol';
+import { AVATAR_PRIVILEGED_SCHEME } from './avatar_protocol';
+import { MEDIA_PRIVILEGED_SCHEME } from './media_protocol';
 import {
   registerResourceProtocol,
-  RESOURCE_PRIVILEGED_SCHEME,
-} from './resource_protocol';
-import {
   registerAvatarProtocol,
-  AVATAR_PRIVILEGED_SCHEME,
-} from './avatar_protocol';
-import {
   registerMediaProtocol,
-  MEDIA_PRIVILEGED_SCHEME,
-} from './media_protocol';
+} from './protocol_register';
 import { getAppContext } from './context/app_context';
-import { checkForUpdate } from './update/updater';
+import { checkForUpdate, installUpdateActions } from './update/updater';
 import { stopMcpServer } from './mcp/server';
-import { stopWeqServer, registerWeqAssistantIpc } from './weq_assistant/server';
+import { stopWeqServer } from './weq_assistant/server';
+import { registerWeqAssistantIpc } from './weq_assistant/ipc';
 import { disposeExternalMcp } from './mcp/external';
 import { registerChannelIpc } from './channel';
 import { registerQzoneIpc } from './qzone';
 import {
   getLogDir,
   getLogger,
+  setHost,
   type MediaElement,
   type WindowCloseBehavior,
 } from '@weq/service';
+import { electronHost } from './host';
 import { systemAuthService } from './system_auth';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -471,6 +470,9 @@ void app.whenReady().then(async () => {
   }
 
   // Order matters: AppContext (loads native + platform) before IPC handler.
+  // The host bridge must be installed before any router runs.
+  setHost(electronHost);
+  installUpdateActions();
   initAppContext();
   logger.info('electron app ready', { event: 'app-ready' });
 
diff --git a/apps/desktop/src/main/ipc/router.ts b/apps/desktop/src/main/ipc/router.ts
index aa2cfeaf..e60fffe2 100644
--- a/apps/desktop/src/main/ipc/router.ts
+++ b/apps/desktop/src/main/ipc/router.ts
@@ -2,10 +2,13 @@
  * Top-level router. `AppRouter` type is the contract the renderer uses
  * to derive end-to-end-typed tRPC clients.
  *
- * The two sub-routers split by lifecycle, NOT by URL aesthetics:
+ * The three sub-routers split by lifecycle, NOT by URL aesthetics:
  *   - `bootstrap` — usable any time (read-only platform probes, dbkey
  *      acquisition, account open/close)
  *   - `account`   — requires a live AccountSession (msg / peer queries)
+ *   - `update`    — in-app updates; the shell installs the implementation
+ *      (`UpdateActions`), so this module stays Electron-free and the web app
+ *      can mount the very same router.
  */
 
 import { router } from './trpc';
diff --git a/apps/desktop/src/main/ipc/routers/account.ts b/apps/desktop/src/main/ipc/routers/account.ts
index 860fde96..d954153b 100644
--- a/apps/desktop/src/main/ipc/routers/account.ts
+++ b/apps/desktop/src/main/ipc/routers/account.ts
@@ -19,7 +19,6 @@ import { basename, dirname, extname, join } from 'node:path';
 import { getAppContext, dbEventBus, type AccountServices } from '../../context/app_context';
 import { sampleHitokoto } from '../../hitokoto';
 import { resolveResource } from '../../resource';
-import { dialog } from 'electron';
 import { procedure, router } from '../trpc';
 import { dbExplorerRouter } from './db_explorer';
 import { antiRecallRouter } from './anti_recall';
@@ -37,11 +36,15 @@ import { validateMcpConfig } from '../../mcp/external';
 import { groupChatBus, type GroupChatStreamEvent } from '../../mcp/agentlab_group_bus';
 import {
   clientKeyExpiryMs,
+  buildPtlogin2JumpUrl,
+  parseClientKeyJson,
   toRenderElements,
   PRIVATE_PTT_RKEY_TYPE,
   GROUP_PTT_RKEY_TYPE,
+  getHost,
   getVoiceModel,
   buildBotExport,
+  probeBotWebUi,
   type AlbumMedia,
   type NewMessages,
   type DbChange,
@@ -59,6 +62,7 @@ import {
   groupMsgToWire,
   groupNotifyToWire,
   recentContactToWire,
+  recentContactTopToWire,
   userProfileToWire,
   groupDetailToWire,
   groupEssenceToWire,
@@ -752,13 +756,10 @@ export const accountRouter = router({
       if (!botMjs) throw new Error('找不到 bot 引擎 bot.mjs（开发环境请先运行 pnpm build:bot）');
 
       // 选输出位置。
-      const picked = await dialog.showOpenDialog({
-        title: '选择导出位置',
-        properties: ['openDirectory', 'createDirectory'],
-      });
-      if (picked.canceled || !picked.filePaths[0]) return { canceled: true as const };
+      const pickedDir = await getHost().pickDirectory({ title: '选择导出位置' });
+      if (!pickedDir) return { canceled: true as const };
       const safeName = (persona.name || 'clone').replace(/[^\w一-龥-]+/g, '_').slice(0, 40) || 'clone';
-      const outDir = join(picked.filePaths[0], `${safeName}-bot`);
+      const outDir = join(pickedDir, `${safeName}-bot`);
 
       const result = await buildBotExport({
         outDir,
@@ -804,12 +805,19 @@ export const accountRouter = router({
       const info = svc.getExportInfo(input.personaId);
       if (!info) throw new Error('这个克隆体还没有导出过，请先导出机器人。');
       const base = (input.url?.trim() || info.url).replace(/\/+$/, '');
-      const { probeBotWebUi, openBotWebUiWindow } = await import('../../bot_webui_window');
       const reachable = await probeBotWebUi(`${base}/`);
       if (!reachable) return { opened: false as const, needUrl: true as const, defaultUrl: info.url };
       const persona = svc.getPersona(input.personaId);
-      await openBotWebUiWindow(base, info.key, persona?.name);
-      return { opened: true as const, needUrl: false as const };
+      const opened = await getHost().openBotConsole({
+        url: base,
+        key: info.key,
+        title: persona?.name,
+      });
+      return {
+        opened: true as const,
+        needUrl: false as const,
+        openUrl: opened?.url ?? null,
+      };
     }),
 
   // ── 克隆体群聊（M2 群骨架）─────────────────────────────────────────────
@@ -1110,15 +1118,10 @@ export const accountRouter = router({
     .input(z.object({ id: z.string().min(1) }))
     .mutation(async ({ input }) => {
       const { path, kind } = requireServices().assistant.artifactInfo(input.id);
-      if (kind === 'html') {
-        const { openReportWindow } = await import('../../report_window');
-        await openReportWindow(path);
-      } else {
-        const { shell } = await import('electron');
-        const err = await shell.openPath(path);
-        if (err) throw new Error(err);
-      }
-      return true;
+      const host = getHost();
+      const opened = kind === 'html' ? await host.openHtmlReport(path) : null;
+      if (kind !== 'html') await host.revealPath(path);
+      return { ok: true as const, openUrl: opened?.url ?? null };
     }),
 
   /** 把助手写的报告文件另存到用户选定位置（复用 saveExportFile 范式）。 */
@@ -1126,15 +1129,14 @@ export const accountRouter = router({
     .input(z.object({ id: z.string().min(1), name: z.string().min(1) }))
     .mutation(async ({ input }) => {
       const { path } = requireServices().assistant.artifactInfo(input.id);
-      const { dialog } = await import('electron');
       const { copyFileSync } = await import('node:fs');
       const ext = extname(input.name).replace(/^\./, '') || 'html';
-      const result = await dialog.showSaveDialog({
-        defaultPath: input.name,
-        filters: [{ name: 'Report', extensions: [ext] }],
+      const target = await getHost().pickSaveTarget({
+        defaultName: input.name,
+        extension: ext,
       });
-      if (result.canceled || !result.filePath) return false;
-      copyFileSync(path, result.filePath);
+      if (!target) return false;
+      copyFileSync(path, target.path);
       return true;
     }),
 
@@ -1155,6 +1157,12 @@ export const accountRouter = router({
     return contacts.map(recentContactToWire);
   }),
 
+  /** 置顶会话（recent_contact_top_table），最近置顶的在前。 */
+  listTopContacts: procedure.query(async () => {
+    const tops = await requireServices().recentContacts.getTopContacts();
+    return tops.map(recentContactTopToWire);
+  }),
+
   /** 首页门面：随机一言若干（打字机轮播用；已按句长筛过）。 */
   sampleHitokoto: procedure
     .input(z.object({ count: z.number().int().min(1).max(80).default(30) }).optional())
@@ -1816,13 +1824,7 @@ export const accountRouter = router({
 
   /** Folder dialog for decrypted database output. */
   pickDecryptOutputDir: procedure.mutation(async () => {
-    const { dialog } = await import('electron');
-    const result = await dialog.showOpenDialog({
-      title: '选择解密保存文件夹',
-      properties: ['openDirectory', 'createDirectory'],
-    });
-    if (result.canceled || result.filePaths.length === 0) return null;
-    return result.filePaths[0] ?? null;
+    return getHost().pickDirectory({ title: '选择解密保存文件夹' });
   }),
 
   /** Bulk decrypt selected databases into the chosen folder. */
@@ -1832,6 +1834,43 @@ export const accountRouter = router({
       return requireServices().dbDecrypt.decryptDatabases(input);
     }),
 
+  // ---- 外部站点跳转（QQ 空间 / QQ 频道，网页版用） ----
+
+  /**
+   * A one-shot ptlogin2 jump URL that lands on QQ 空间 / QQ 频道 already logged in.
+   *
+   * 桌面版用 `<webview>` + 手工种 cookie；浏览器里两条路都走不通（对方站点禁 iframe，
+   * 且我们无法跨站写 cookie）。所以改把跳转 URL 交给浏览器开新标签：302 链在浏览器
+   * 里跑完，cookie 落进浏览器自己的 jar，等价于用户手动登录了一次。
+   *
+   * URL 里带着 clientKey，属于一次性凭据 —— 只在点击时现取，不缓存不落库。
+   */
+  getExternalSiteUrl: procedure
+    .input(z.object({ site: z.enum(['qzone', 'channel']) }))
+    .mutation(async ({ input }) => {
+      const ctx = getAppContext();
+      const services = requireServices();
+      const uin = ctx.account?.context.uin;
+      const nt = ctx.platform?.native.ntHelper;
+      const record = services.accountConfig.getRecord();
+      const landing =
+        input.site === 'qzone'
+          ? `https://user.qzone.qq.com/${uin}/infocenter?loginfrom=31`
+          : 'https://pd.qq.com/';
+
+      // 没有在线 QQ 就没有 clientKey 可换 —— 退回裸地址，用户自己在浏览器里登录。
+      if (!uin || !nt || !record?.qqOnline || !record.qqPid) {
+        return { url: landing, autoLogin: false };
+      }
+      try {
+        const ck = parseClientKeyJson(await nt.fetchClientKey(record.qqPid));
+        if (!ck) return { url: landing, autoLogin: false };
+        return { url: buildPtlogin2JumpUrl(ck, String(uin), landing), autoLogin: true };
+      } catch {
+        return { url: landing, autoLogin: false };
+      }
+    }),
+
   // ---- group album ----
 
   /** List group albums via Qzone web CGI. Requires online QQ + fresh ClientKey. */
@@ -1854,13 +1893,7 @@ export const accountRouter = router({
 
   /** Folder dialog for group album export output. */
   pickGroupAlbumExportDir: procedure.mutation(async () => {
-    const { dialog } = await import('electron');
-    const result = await dialog.showOpenDialog({
-      title: '选择群相册保存文件夹',
-      properties: ['openDirectory', 'createDirectory'],
-    });
-    if (result.canceled || result.filePaths.length === 0) return null;
-    return result.filePaths[0] ?? null;
+    return getHost().pickDirectory({ title: '选择群相册保存文件夹' });
   }),
 
   /** Enumerate selected albums first, then concurrently download all media. */
@@ -2231,14 +2264,13 @@ export const accountRouter = router({
       format: z.enum(['json', 'jsonl', 'txt', 'csv', 'xlsx', 'html']),
     }))
     .mutation(async ({ input }) => {
-      const { dialog } = await import('electron');
       const { copyFileSync } = await import('node:fs');
-      const result = await dialog.showSaveDialog({
-        defaultPath: input.defaultName,
-        filters: [{ name: 'Export', extensions: [input.format] }],
+      const target = await getHost().pickSaveTarget({
+        defaultName: input.defaultName,
+        extension: input.format,
       });
-      if (result.canceled || !result.filePath) return false;
-      copyFileSync(input.sourcePath, result.filePath);
+      if (!target) return false;
+      copyFileSync(input.sourcePath, target.path);
       return true;
     }),
 
@@ -2254,13 +2286,9 @@ export const accountRouter = router({
       if (!task?.bundleDir) return false;
       const { existsSync, cpSync } = await import('node:fs');
       if (!existsSync(task.bundleDir)) return false;
-      const { dialog } = await import('electron');
-      const result = await dialog.showOpenDialog({
-        title: '选择导出保存文件夹',
-        properties: ['openDirectory', 'createDirectory'],
-      });
-      if (result.canceled || result.filePaths.length === 0) return false;
-      const dest = join(result.filePaths[0]!, sanitizePathSegment(task.name, task.id));
+      const picked = await getHost().pickDirectory({ title: '选择导出保存文件夹' });
+      if (!picked) return false;
+      const dest = join(picked, sanitizePathSegment(task.name, task.id));
       cpSync(task.bundleDir, dest, { recursive: true });
       return true;
     }),
@@ -2275,9 +2303,7 @@ export const accountRouter = router({
       const task = requireServices().exportManager.getTask(input.taskId);
       const path = task?.bundleDir || task?.filePath;
       if (!path) throw new Error('导出结果不存在（可能已被清理）。');
-      const { shell } = await import('electron');
-      const err = await shell.openPath(path);
-      if (err) throw new Error(err);
+      await getHost().revealPath(path);
       return true;
     }),
 
@@ -2290,27 +2316,24 @@ export const accountRouter = router({
     .mutation(async ({ input }) => {
       const task = requireServices().exportManager.getTask(input.taskId);
       if (!task) throw new Error('导出结果不存在（可能已被清理）。');
-      const { dialog } = await import('electron');
+      const host = getHost();
       if (task.bundleDir) {
         const { existsSync, cpSync } = await import('node:fs');
         if (!existsSync(task.bundleDir)) return false;
-        const result = await dialog.showOpenDialog({
-          title: '选择导出保存文件夹',
-          properties: ['openDirectory', 'createDirectory'],
-        });
-        if (result.canceled || result.filePaths.length === 0) return false;
-        const dest = join(result.filePaths[0]!, sanitizePathSegment(task.name, task.id));
+        const picked = await host.pickDirectory({ title: '选择导出保存文件夹' });
+        if (!picked) return false;
+        const dest = join(picked, sanitizePathSegment(task.name, task.id));
         cpSync(task.bundleDir, dest, { recursive: true });
         return true;
       }
       if (!task.filePath) return false;
       const { copyFileSync } = await import('node:fs');
-      const result = await dialog.showSaveDialog({
-        defaultPath: `${task.name}.${task.format}`,
-        filters: [{ name: 'Export', extensions: [task.format] }],
+      const target = await host.pickSaveTarget({
+        defaultName: `${task.name}.${task.format}`,
+        extension: task.format,
       });
-      if (result.canceled || !result.filePath) return false;
-      copyFileSync(task.filePath, result.filePath);
+      if (!target) return false;
+      copyFileSync(task.filePath, target.path);
       return true;
     }),
 
diff --git a/apps/desktop/src/main/ipc/routers/bootstrap.ts b/apps/desktop/src/main/ipc/routers/bootstrap.ts
index db41759e..cf5e4481 100644
--- a/apps/desktop/src/main/ipc/routers/bootstrap.ts
+++ b/apps/desktop/src/main/ipc/routers/bootstrap.ts
@@ -14,7 +14,6 @@
  */
 
 import { observable } from '@trpc/server/observable';
-import { app, dialog } from 'electron';
 import { z } from 'zod';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
@@ -36,6 +35,7 @@ import { procedure, router } from '../trpc';
 import {
   accountConfigId,
   fetchHomeDress,
+  getHost,
   getLogger,
   logErrorContext,
   type KeyEvent,
@@ -272,12 +272,13 @@ export const bootstrapRouter = router({
 
   /** WeQ app version + the runtime versions, for the 全局设置 page. */
   getVersionInfo: procedure.query(() => {
+    const host = getHost();
     return {
-      app: app.getVersion(),
+      app: host.appVersion(),
       electron: process.versions.electron ?? '',
       chrome: process.versions.chrome ?? '',
       node: process.versions.node ?? '',
-      isDev: !app.isPackaged,
+      isDev: !host.isPackaged(),
     };
   }),
 
@@ -682,14 +683,7 @@ export const bootstrapRouter = router({
   /** Folder dialog → set the cache override. Returns the new path info. */
   pickCacheDir: procedure.mutation(async () => {
     const boot = requireBootstrap();
-    const result = await dialog.showOpenDialog({
-      title: '选择缓存目录',
-      properties: ['openDirectory', 'createDirectory'],
-    });
-    if (result.canceled || result.filePaths.length === 0) {
-      return boot.userConfig.getCacheDirInfo();
-    }
-    const picked = result.filePaths[0];
+    const picked = await getHost().pickDirectory({ title: '选择缓存目录' });
     if (picked) boot.userConfig.setCacheDirOverride(picked);
     return boot.userConfig.getCacheDirInfo();
   }),
@@ -720,14 +714,9 @@ export const bootstrapRouter = router({
   // ---- filesystem dialog (Tencent Files fallback / manual db pick) ----
 
   pickTencentFilesRoot: procedure.mutation(async (): Promise<PickRootResult> => {
-    const result = await dialog.showOpenDialog({
+    const picked = await getHost().pickDirectory({
       title: '选择 Tencent Files 目录（必须选到 Tencent Files 文件夹本身）',
-      properties: ['openDirectory'],
     });
-    if (result.canceled || result.filePaths.length === 0) {
-      return { ok: false, path: null };
-    }
-    const picked = result.filePaths[0] ?? null;
     if (!picked) return { ok: false, path: null };
     // Hard rule: the override must point at the `Tencent Files` folder itself,
     // not a parent or the per-account `…\Tencent Files\<uin>` subdir. Reject
@@ -752,22 +741,11 @@ export const bootstrapRouter = router({
   }),
 
   pickMsgDb: procedure.mutation(async () => {
-    const result = await dialog.showOpenDialog({
-      title: '选择 nt_msg.db',
-      filters: [{ name: 'SQLite database', extensions: ['db'] }],
-      properties: ['openFile'],
-    });
-    if (result.canceled || result.filePaths.length === 0) return null;
-    return result.filePaths[0] ?? null;
+    return getHost().pickFile({ title: '选择 nt_msg.db', extensions: ['db'] });
   }),
 
   pickStaticDbDir: procedure.mutation(async () => {
-    const result = await dialog.showOpenDialog({
-      title: '选择已解密的 QQ 数据库目录',
-      properties: ['openDirectory'],
-    });
-    if (result.canceled || result.filePaths.length === 0) return null;
-    return result.filePaths[0] ?? null;
+    return getHost().pickDirectory({ title: '选择已解密的 QQ 数据库目录' });
   }),
 
   // ---- key correctness probe ----
diff --git a/apps/desktop/src/main/ipc/routers/dressup.ts b/apps/desktop/src/main/ipc/routers/dressup.ts
index 625a6195..ca357ed8 100644
--- a/apps/desktop/src/main/ipc/routers/dressup.ts
+++ b/apps/desktop/src/main/ipc/routers/dressup.ts
@@ -18,6 +18,7 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { observable } from '@trpc/server/observable';
+import { getHost } from '@weq/service';
 import { z } from 'zod';
 import { DressAppId, normalizeMallItems, toPeerDress, type DressMallItem } from '@weq/service';
 import { accountEventBus, getAppContext, type AccountServices } from '../../context/app_context';
@@ -262,13 +263,10 @@ export const dressupRouter = router({
    */
   pickBackground: procedure.mutation(async () => {
     const services = requireServices();
-    const { dialog } = await import('electron');
-    const result = await dialog.showOpenDialog({
+    const picked = await getHost().pickFile({
       title: '选择聊天背景图',
-      properties: ['openFile'],
-      filters: [{ name: '图片', extensions: ['png', 'jpg', 'jpeg', 'webp', 'gif', 'bmp'] }],
+      extensions: ['png', 'jpg', 'jpeg', 'webp', 'gif', 'bmp'],
     });
-    const picked = result.canceled ? '' : (result.filePaths[0] ?? '');
     if (!picked) return services.dressInstall.read();
     return services.dressInstall.setCustomBackground(picked);
   }),
diff --git a/apps/desktop/src/main/ipc/routers/file_resource.ts b/apps/desktop/src/main/ipc/routers/file_resource.ts
index d7bf33b1..15d4273f 100644
--- a/apps/desktop/src/main/ipc/routers/file_resource.ts
+++ b/apps/desktop/src/main/ipc/routers/file_resource.ts
@@ -16,6 +16,7 @@
 import { z } from 'zod';
 import { existsSync } from 'node:fs';
 import { getAppContext, type AccountServices } from '../../context/app_context';
+import { getHost } from '@weq/service';
 import { procedure, router } from '../trpc';
 
 function requireServices(): AccountServices {
@@ -49,15 +50,17 @@ const listInput = z.object({
 
 /** Reveal a path in the OS file manager; falls back to opening on failure. */
 async function revealInFolder(path: string): Promise<void> {
-  const { shell } = await import('electron');
-  shell.showItemInFolder(path);
+  await getHost().revealInFolder(path);
 }
 
 /** Open a path with the OS default handler. */
 async function openPath(path: string): Promise<{ ok: boolean; error?: string }> {
-  const { shell } = await import('electron');
-  const err = await shell.openPath(path);
-  return err ? { ok: false, error: err } : { ok: true };
+  try {
+    await getHost().revealPath(path);
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : String(e) };
+  }
 }
 
 export const fileResourceRouter = router({
diff --git a/apps/desktop/src/main/ipc/routers/update.ts b/apps/desktop/src/main/ipc/routers/update.ts
index d3e11f19..416eae0c 100644
--- a/apps/desktop/src/main/ipc/routers/update.ts
+++ b/apps/desktop/src/main/ipc/routers/update.ts
@@ -9,27 +9,32 @@
  *   - `onEvent`    — available / downloaded / error (state machine + red dot)
  *
  * Mirrors the EventEmitter→observable bridge used by `bootstrap.onVoiceModelProgress`.
+ *
+ * The actual work is behind {@link UpdateActions}, installed by the shell — the
+ * desktop app wires `electron-updater`, other hosts get no-ops. That keeps this
+ * router (and the shared `AppRouter` type) free of Electron imports.
  */
 
 import { observable } from '@trpc/server/observable';
 import { procedure, router } from '../trpc';
 import {
-  checkForUpdate,
+  getUpdateActions,
   getUpdateState,
-  quitAndInstall,
-  startDownload,
   updateBus,
   type UpdateEvent,
   type UpdateProgress,
   type UpdateState,
-} from '../../update/updater';
+} from '../../update/state';
 
 export const updateRouter = router({
   /** Last cached check result, or null if not checked yet this session. */
   getState: procedure.query((): UpdateState | null => getUpdateState()),
 
+  /** True when this host can actually install updates (false on web). */
+  isSupported: procedure.query((): boolean => getUpdateActions().supported),
+
   /** Speed-test mirrors + compare versions. Rejects if no mirror is reachable. */
-  check: procedure.mutation((): Promise<UpdateState> => checkForUpdate(true)),
+  check: procedure.mutation((): Promise<UpdateState> => getUpdateActions().check(true)),
 
   /**
    * Kick off the download. Returns immediately — progress and the terminal
@@ -37,13 +42,13 @@ export const updateRouter = router({
    * event (so we swallow the rejection here).
    */
   download: procedure.mutation((): boolean => {
-    void startDownload().catch(() => {});
+    void getUpdateActions().startDownload().catch(() => {});
     return true;
   }),
 
   /** Quit, install the downloaded update silently, relaunch. */
   install: procedure.mutation((): boolean => {
-    quitAndInstall();
+    getUpdateActions().quitAndInstall();
     return true;
   }),
 
diff --git a/apps/desktop/src/main/ipc/serde.ts b/apps/desktop/src/main/ipc/serde.ts
index b02830fc..07d948ac 100644
--- a/apps/desktop/src/main/ipc/serde.ts
+++ b/apps/desktop/src/main/ipc/serde.ts
@@ -22,6 +22,7 @@ import type {
   GroupMemberLevelInfo,
   GroupNotify,
   RecentContact,
+  RecentContactTop,
   UserProfile,
 } from '@weq/db';
 import { decodeElement, type MsgCacheRecord, type SetEmojiItem } from '@weq/codec';
@@ -267,6 +268,15 @@ export interface RecentContactWire {
   tempSourceGroupCode: string;
 }
 
+export interface RecentContactTopWire {
+  /** Mapped ChatType name (or raw number). */
+  chatType: string | number;
+  /** 41103 — pin timestamp, unix seconds (string). */
+  topTime: string;
+  /** Conversation key: peer uid for c2c, group code for groups. */
+  targetId: string;
+}
+
 export function c2cMsgToWire(m: RenderC2cMsg): ChatMsgWire {
   return {
     kind: 'c2c',
@@ -319,6 +329,14 @@ export function recentContactToWire(c: RecentContact): RecentContactWire {
   };
 }
 
+export function recentContactTopToWire(t: RecentContactTop): RecentContactTopWire {
+  return {
+    chatType: t.chatType,
+    topTime: t.topTime.toString(),
+    targetId: t.targetId,
+  };
+}
+
 export function userProfileToWire(p: UserProfile): UserProfileWire {
   return {
     uid: p.uid,
diff --git a/apps/desktop/src/main/media_protocol.ts b/apps/desktop/src/main/media_protocol.ts
index 5bd542ba..37e62a83 100644
--- a/apps/desktop/src/main/media_protocol.ts
+++ b/apps/desktop/src/main/media_protocol.ts
@@ -29,8 +29,8 @@
  * `ready`; `registerMediaProtocol()` runs after.
  */
 
-import { net, protocol } from 'electron';
-import { pathToFileURL } from 'node:url';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { fileResponse as streamFile } from './file_response';
 import { createHash } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
@@ -99,8 +99,14 @@ function notFound(reason: string): Response {
   return new Response(reason, { status: 404 });
 }
 
+/**
+ * The in-flight request, so {@link fileResponse} can honor `Range` without
+ * threading a parameter through all ~24 call sites below.
+ */
+const currentRequest = new AsyncLocalStorage<Request>();
+
 function fileResponse(path: string): Promise<Response> {
-  return net.fetch(pathToFileURL(path).toString());
+  return streamFile(path, currentRequest.getStore());
 }
 
 /**
@@ -141,7 +147,7 @@ async function albumRemoteResponse(src: string): Promise<Response> {
   if (!allowed) return notFound('album image host not allowed');
   // Referer 的协议必须跟目标一致：Chromium 禁止 https→http 的 referrer 降级,
   // 撞上就是 ERR_BLOCKED_BY_CLIENT(资料卡精选图片走的 ugc.qpic.cn 只有 http)。
-  const res = await net.fetch(src, {
+  const res = await fetch(src, {
     headers: {
       Referer: `${target.protocol}//user.qzone.qq.com/`,
       'User-Agent':
@@ -202,8 +208,12 @@ async function dressRemoteResponse(src: string): Promise<Response> {
   }
 }
 
-export function registerMediaProtocol(): void {
-  protocol.handle(MEDIA_SCHEME, async (request) => {
+/**
+ * Serve one `weq-media://` request. Pure `Request`→`Response`, so the web app
+ * can mount it on a plain HTTP route (see `apps/web`) without Electron.
+ */
+export function handleMediaRequest(request: Request): Promise<Response> {
+  return currentRequest.run(request, async () => {
     const url = new URL(request.url);
     const kind = url.hostname;
     const q = url.searchParams;
diff --git a/apps/desktop/src/main/protocol_register.ts b/apps/desktop/src/main/protocol_register.ts
new file mode 100644
index 00000000..6d9aacce
--- /dev/null
+++ b/apps/desktop/src/main/protocol_register.ts
@@ -0,0 +1,25 @@
+/**
+ * Electron custom-scheme registration for the three media/asset protocols.
+ *
+ * The handlers themselves live next to their logic (`media_protocol.ts`,
+ * `avatar_protocol.ts`, `resource_protocol.ts`) as plain `Request → Response`
+ * functions with no Electron imports, so the web app can mount them on HTTP
+ * routes. This file is the desktop-only shim that binds them to custom schemes.
+ */
+
+import { protocol } from 'electron';
+import { MEDIA_SCHEME, handleMediaRequest } from './media_protocol';
+import { AVATAR_SCHEME, handleAvatarRequest } from './avatar_protocol';
+import { RESOURCE_SCHEME, handleResourceRequest } from './resource_protocol';
+
+export function registerMediaProtocol(): void {
+  protocol.handle(MEDIA_SCHEME, handleMediaRequest);
+}
+
+export function registerAvatarProtocol(): void {
+  protocol.handle(AVATAR_SCHEME, handleAvatarRequest);
+}
+
+export function registerResourceProtocol(): void {
+  protocol.handle(RESOURCE_SCHEME, handleResourceRequest);
+}
diff --git a/apps/desktop/src/main/resource.ts b/apps/desktop/src/main/resource.ts
index 9b8aeca4..487ee0a3 100644
--- a/apps/desktop/src/main/resource.ts
+++ b/apps/desktop/src/main/resource.ts
@@ -21,8 +21,14 @@ const moduleDir = dirname(fileURLToPath(import.meta.url));
 
 /** First existing `resources/` root among the candidates, or null. */
 export function resolveResourceRoot(): string | null {
+  // `resourcesPath` is injected by Electron and absent under plain Node (the
+  // web app), where the bundle ships its own sibling `resources/`. Same probe
+  // shape as `@weq/native`'s loader.
+  const electronResources = (process as NodeJS.Process & { resourcesPath?: string })
+    .resourcesPath;
   const candidates = [
-    join(process.resourcesPath ?? '', 'resources'), // packaged
+    join(electronResources ?? '', 'resources'), // packaged (Electron)
+    join(moduleDir, 'resources'), // packaged (web: dist/resources)
     join(moduleDir, '../../../../resources'), // dev (out/main → repo root)
     join(process.cwd(), 'resources'),
   ];
diff --git a/apps/desktop/src/main/resource_protocol.ts b/apps/desktop/src/main/resource_protocol.ts
index e58da35f..ac7ef7f9 100644
--- a/apps/desktop/src/main/resource_protocol.ts
+++ b/apps/desktop/src/main/resource_protocol.ts
@@ -19,10 +19,9 @@
  * Protocol()` MUST run after.
  */
 
-import { net, protocol } from 'electron';
 import { join, normalize, sep } from 'node:path';
-import { pathToFileURL } from 'node:url';
 import { resolveResourceRoot } from './resource';
+import { fileResponse } from './file_response';
 import { getAppContext } from './context/app_context';
 
 export const RESOURCE_SCHEME = 'weq-asset';
@@ -58,26 +57,28 @@ function resolveEmojiRoot(): string | null {
   return null;
 }
 
-export function registerResourceProtocol(): void {
-  protocol.handle(RESOURCE_SCHEME, async (request) => {
-    const url = new URL(request.url);
-    const isEmoji = url.hostname === 'emoji';
+/**
+ * Serve one `weq-asset://` request. Pure `Request`→`Response`, so the web app
+ * can mount it on a plain HTTP route (see `apps/web`) without Electron.
+ */
+export async function handleResourceRequest(request: Request): Promise<Response> {
+  const url = new URL(request.url);
+  const isEmoji = url.hostname === 'emoji';
 
-    const root = isEmoji ? resolveEmojiRoot() : resolveResourceRoot();
-    if (!root) return new Response('resource root not found', { status: 404 });
+  const root = isEmoji ? resolveEmojiRoot() : resolveResourceRoot();
+  if (!root) return new Response('resource root not found', { status: 404 });
 
-    // Emoji lives under its own root, so drop the `emoji` host segment; other
-    // hosts are a path segment under the bundled resources root.
-    const relative = isEmoji
-      ? decodeURIComponent(url.pathname)
-      : decodeURIComponent(`${url.hostname}${url.pathname}`);
-    const target = normalize(join(root, relative));
+  // Emoji lives under its own root, so drop the `emoji` host segment; other
+  // hosts are a path segment under the bundled resources root.
+  const relative = isEmoji
+    ? decodeURIComponent(url.pathname)
+    : decodeURIComponent(`${url.hostname}${url.pathname}`);
+  const target = normalize(join(root, relative));
 
-    // Containment check — refuse anything that escapes the resources root.
-    if (target !== root && !target.startsWith(root + sep)) {
-      return new Response('forbidden', { status: 403 });
-    }
+  // Containment check — refuse anything that escapes the resources root.
+  if (target !== root && !target.startsWith(root + sep)) {
+    return new Response('forbidden', { status: 403 });
+  }
 
-    return net.fetch(pathToFileURL(target).toString());
-  });
+  return fileResponse(target, request);
 }
diff --git a/apps/desktop/src/main/update/state.ts b/apps/desktop/src/main/update/state.ts
new file mode 100644
index 00000000..7ecd0d1e
--- /dev/null
+++ b/apps/desktop/src/main/update/state.ts
@@ -0,0 +1,86 @@
+/**
+ * Update types + the event bus and cached state that the router reads.
+ *
+ * Split from `updater.ts` (which imports `electron` and `electron-updater`) so
+ * the update router — and through it the whole `AppRouter` — stays importable
+ * outside Electron. The web app mounts the same router; its actions are wired
+ * to no-ops because a browser-served WeQ can't replace its own binary.
+ */
+
+import { EventEmitter } from 'node:events';
+
+export interface UpdateState {
+  /** Running app version (app.getVersion()). */
+  current: string;
+  /** Latest version from the manifest, or null if never checked. */
+  latest: string | null;
+  /** Whether `latest` is newer than `current`. */
+  hasUpdate: boolean;
+  /** Fastest mirror's release base, or null. */
+  base: string | null;
+  /** Healthy mirror bases, fastest first (download fallback order). */
+  ranked: string[];
+}
+
+export interface UpdateProgress {
+  percent: number;
+  transferred: number;
+  total: number;
+  bytesPerSecond: number;
+}
+
+export type UpdateEvent =
+  | { kind: 'available'; latest: string }
+  | { kind: 'downloaded'; latest: string }
+  | { kind: 'error'; message: string };
+
+export const updateBus = new EventEmitter();
+
+/** Last check result, cached for the session (settings getState + startup red dot). */
+let lastState: UpdateState | null = null;
+
+export function getUpdateState(): UpdateState | null {
+  return lastState;
+}
+
+export function setUpdateState(state: UpdateState | null): void {
+  lastState = state;
+}
+
+/**
+ * The shell-specific half of the update flow. The desktop app installs the
+ * `electron-updater` implementation; hosts that can't self-update leave the
+ * default no-op actions in place.
+ */
+export interface UpdateActions {
+  check(force: boolean): Promise<UpdateState>;
+  startDownload(): Promise<void>;
+  quitAndInstall(): void;
+  /** False when this host can't self-update, so the UI can hide the card. */
+  readonly supported: boolean;
+}
+
+const unsupported: UpdateActions = {
+  supported: false,
+  async check() {
+    return (
+      lastState ?? { current: '', latest: null, hasUpdate: false, base: null, ranked: [] }
+    );
+  },
+  async startDownload() {
+    // No-op — nothing to install into.
+  },
+  quitAndInstall() {
+    // No-op.
+  },
+};
+
+let actions: UpdateActions = unsupported;
+
+export function setUpdateActions(next: UpdateActions): void {
+  actions = next;
+}
+
+export function getUpdateActions(): UpdateActions {
+  return actions;
+}
diff --git a/apps/desktop/src/main/update/updater.ts b/apps/desktop/src/main/update/updater.ts
index c9218863..0674daa6 100644
--- a/apps/desktop/src/main/update/updater.ts
+++ b/apps/desktop/src/main/update/updater.ts
@@ -16,49 +16,24 @@
  */
 
 import { app } from 'electron';
-import { EventEmitter } from 'node:events';
 import semver from 'semver';
 import electronUpdater from 'electron-updater';
 import { resolveBestMirror } from './mirrors';
+import {
+  getUpdateState,
+  setUpdateActions,
+  setUpdateState,
+  updateBus,
+  type UpdateEvent,
+  type UpdateProgress,
+  type UpdateState,
+} from './state';
 
 const { autoUpdater } = electronUpdater;
 
-export interface UpdateState {
-  /** Running app version (app.getVersion()). */
-  current: string;
-  /** Latest version from the manifest, or null if never checked. */
-  latest: string | null;
-  /** Whether `latest` is newer than `current`. */
-  hasUpdate: boolean;
-  /** Fastest mirror's release base, or null. */
-  base: string | null;
-  /** Healthy mirror bases, fastest first (download fallback order). */
-  ranked: string[];
-}
-
-export interface UpdateProgress {
-  percent: number;
-  transferred: number;
-  total: number;
-  bytesPerSecond: number;
-}
-
-export type UpdateEvent =
-  | { kind: 'available'; latest: string }
-  | { kind: 'downloaded'; latest: string }
-  | { kind: 'error'; message: string };
-
-export const updateBus = new EventEmitter();
-
-/** Last check result, cached for the session (settings getState + startup red dot). */
-let lastState: UpdateState | null = null;
 let lastCheckedAt = 0;
 const CHECK_TTL_MS = 5 * 60_000;
 
-export function getUpdateState(): UpdateState | null {
-  return lastState;
-}
-
 function isDev(): boolean {
   return !app.isPackaged;
 }
@@ -75,25 +50,27 @@ function isNewer(latest: string, current: string): boolean {
  */
 export async function checkForUpdate(force = false): Promise<UpdateState> {
   const current = app.getVersion();
-  if (!force && lastState && Date.now() - lastCheckedAt < CHECK_TTL_MS) {
-    return lastState;
+  const cached = getUpdateState();
+  if (!force && cached && Date.now() - lastCheckedAt < CHECK_TTL_MS) {
+    return cached;
   }
 
   const best = await resolveBestMirror();
   const hasUpdate = isNewer(best.version, current);
-  lastState = {
+  const state: UpdateState = {
     current,
     latest: best.version,
     hasUpdate,
     base: best.base,
     ranked: best.ranked,
   };
+  setUpdateState(state);
   lastCheckedAt = Date.now();
 
   if (hasUpdate) {
     updateBus.emit('event', { kind: 'available', latest: best.version } satisfies UpdateEvent);
   }
-  return lastState;
+  return state;
 }
 
 let wired = false;
@@ -153,11 +130,12 @@ function attemptDownload(base: string): Promise<void> {
 export async function startDownload(): Promise<void> {
   if (isDev()) throw new Error('开发模式不支持自更新，请使用打包后的安装版。');
 
-  if (!lastState?.hasUpdate || lastState.ranked.length === 0) {
+  if (!getUpdateState()?.hasUpdate) {
     await checkForUpdate(true);
   }
-  const ranked = lastState?.ranked ?? [];
-  if (!lastState?.hasUpdate || ranked.length === 0) {
+  const state = getUpdateState();
+  const ranked = state?.ranked ?? [];
+  if (!state?.hasUpdate || ranked.length === 0) {
     throw new Error('当前已是最新版本或没有可用的更新源。');
   }
 
@@ -184,3 +162,13 @@ export function quitAndInstall(): void {
   // (isSilent, isForceRunAfter): silent install in place, then relaunch.
   autoUpdater.quitAndInstall(true, true);
 }
+
+/** Wire this Electron implementation into the shell-agnostic update router. */
+export function installUpdateActions(): void {
+  setUpdateActions({
+    supported: true,
+    check: checkForUpdate,
+    startDownload,
+    quitAndInstall,
+  });
+}
diff --git a/apps/desktop/src/main/weq_assistant/ipc.ts b/apps/desktop/src/main/weq_assistant/ipc.ts
new file mode 100644
index 00000000..6106ec62
--- /dev/null
+++ b/apps/desktop/src/main/weq_assistant/ipc.ts
@@ -0,0 +1,23 @@
+/**
+ * Electron-only IPC surface for the WeQ 助手 server. Split from `server.ts` so
+ * that module stays free of `electron` imports and can be reused by the web app.
+ */
+
+import { ipcMain } from 'electron';
+import { setWeqTheme } from './theme';
+
+/**
+ * Register the renderer→main theme pipe. The renderer's `applyTheme` calls this
+ * whenever accent / 深浅 changes (and once on hydrate), so the 每日推文 封面 + 跳转页
+ * — rendered in the main process — track WeQ Desktop's theme. Idempotent; safe
+ * to call once at startup even before the server is enabled.
+ */
+export function registerWeqAssistantIpc(): void {
+  ipcMain.handle(
+    'weqAssistant:set-theme',
+    (_event, theme?: { accent?: string; mode?: 'light' | 'dark' }) => {
+      setWeqTheme(theme);
+      return true;
+    },
+  );
+}
diff --git a/apps/desktop/src/main/weq_assistant/server.ts b/apps/desktop/src/main/weq_assistant/server.ts
index d8df87b6..422ab148 100644
--- a/apps/desktop/src/main/weq_assistant/server.ts
+++ b/apps/desktop/src/main/weq_assistant/server.ts
@@ -20,12 +20,11 @@
  */
 
 import http from 'node:http';
-import { ipcMain } from 'electron';
 import { readFileSync, existsSync } from 'node:fs';
 import { getLogger, logErrorContext } from '@weq/service';
 import { resolveResource } from '../resource';
 import { renderCardPng, dailyCardSpec } from './cover';
-import { buildPalette, getWeqTheme, setWeqTheme } from './theme';
+import { buildPalette, getWeqTheme } from './theme';
 import { getWeqStats } from './stats';
 import { renderStatsPageHtml, statsPendingHtml, statsCardSpec } from './stats_page';
 
@@ -49,17 +48,11 @@ export function isWeqServerRunning(): boolean {
  * whenever accent / 深浅 changes (and once on hydrate), so the 每日推文 封面 + 跳转页
  * — rendered here in the main process — track WeQ Desktop's theme. Idempotent;
  * safe to call once at startup even before the server is enabled.
+ *
+ * Lives in `./ipc` (not here) so this module stays importable outside Electron:
+ * the web app pulls in `startWeqServer` / `isWeqServerRunning` and must not
+ * drag `electron` into its bundle.
  */
-export function registerWeqAssistantIpc(): void {
-  ipcMain.handle(
-    'weqAssistant:set-theme',
-    (_event, theme?: { accent?: string; mode?: 'light' | 'dark' }) => {
-      setWeqTheme(theme);
-      return true;
-    },
-  );
-}
-
 export function runningWeqServerConfig(): WeqServerOptions | null {
   return activeConfig;
 }
diff --git a/apps/desktop/src/renderer/src/App.tsx b/apps/desktop/src/renderer/src/App.tsx
index 3adedd72..4f2e0017 100644
--- a/apps/desktop/src/renderer/src/App.tsx
+++ b/apps/desktop/src/renderer/src/App.tsx
@@ -13,6 +13,7 @@ import { DialogHost } from './components/Dialog';
 import { ToastHost } from './components/Toast';
 import { WelcomeDialog } from './components/WelcomeDialog';
 import { CloseConfirmDialog } from './components/CloseConfirmDialog';
+import { DesktopOnly } from './lib/target';
 import { ImageLightbox } from './components/ImageLightbox';
 import { VideoLightbox } from './components/VideoLightbox';
 import { MarketFaceLightbox } from './components/MarketFaceLightbox';
@@ -115,8 +116,12 @@ export default function App(): ReactElement {
         {view === 'main' ? <WelcomeDialog /> : null}
         <DialogHost />
         <ToastHost />
-        <CloseConfirmDialog />
-        <AppLockOverlay />
+        <DesktopOnly>
+          <CloseConfirmDialog />
+        </DesktopOnly>
+        <DesktopOnly>
+          <AppLockOverlay />
+        </DesktopOnly>
         <ImageLightbox />
         <VideoLightbox />
         <MarketFaceLightbox />
diff --git a/apps/desktop/src/renderer/src/components/AppLockOverlay.tsx b/apps/desktop/src/renderer/src/components/AppLockOverlay.tsx
index 7d7f779e..cabf6aa6 100644
--- a/apps/desktop/src/renderer/src/components/AppLockOverlay.tsx
+++ b/apps/desktop/src/renderer/src/components/AppLockOverlay.tsx
@@ -4,6 +4,7 @@ import { trpc } from '../trpc/client';
 import { useDialog, Modal } from './Dialog';
 import { useViewState } from '../state/view';
 import { useAppLock } from '../state/lock';
+import { shellBridge } from '../lib/target';
 
 type SystemAuthStatus = Awaited<ReturnType<typeof window.weq.systemAuth.getStatus>>;
 
@@ -30,7 +31,9 @@ export function AppLockOverlay(): ReactElement | null {
   const inMain = view === 'main';
 
   useEffect(() => {
-    void window.weq.systemAuth
+    const bridge = shellBridge();
+    if (!bridge) return;
+    void bridge.systemAuth
       .getStatus()
       .then(setStatus)
       .catch((error) => {
diff --git a/apps/desktop/src/renderer/src/components/GroupCallEndedMessage.tsx b/apps/desktop/src/renderer/src/components/GroupCallEndedMessage.tsx
new file mode 100644
index 00000000..c4bd6dad
--- /dev/null
+++ b/apps/desktop/src/renderer/src/components/GroupCallEndedMessage.tsx
@@ -0,0 +1,50 @@
+/**
+ * 群通话「已结束」灰条 (CALL element, elementType=21, subType=16/25).
+ *
+ * 群聊和私聊的通话记录结构完全不同：私聊一条消息就是整通电话的最终状态（接通 /
+ * 未接 / 拒绝），群聊则拆成两条独立消息 —— 「XXX 发起了语音通话」（callMethod=
+ * 1/2，40020 是发起人）和「语音通话已结束」（callMethod=0，40020 为空），中间没
+ * 有任何状态。
+ *
+ * 发起那条有正常的发送人，仍走气泡（QqCall）；结束这条谁也不属于，套气泡会凭空
+ * 多出一个发送者，所以画成居中灰条。
+ */
+
+import { Phone, Video } from 'lucide-react';
+
+interface GroupCallEndedMessageProps {
+  element: {
+    type: 'call';
+    data?: {
+      subType?: number;
+      callSummary?: string[];
+    };
+  };
+}
+
+/** CALL subType：群通话结束。见 packages/codec/src/element/types.ts。 */
+const GROUP_VOICE_ENDED = 16;
+const GROUP_VIDEO_ENDED = 25;
+
+export const GROUP_CALL_ENDED_SUBTYPES = new Set<number>([
+  GROUP_VOICE_ENDED,
+  GROUP_VIDEO_ENDED,
+]);
+
+export function GroupCallEndedMessage({ element }: GroupCallEndedMessageProps) {
+  const { subType, callSummary } = element.data || {};
+  const isVideo = Number(subType) === GROUP_VIDEO_ENDED;
+  const Icon = isVideo ? Video : Phone;
+
+  // QQ 自己写好的文案（"语音通话已结束"），拿不到就自己拼。
+  const summary = Array.isArray(callSummary)
+    ? callSummary.filter((s) => typeof s === 'string' && s).join(' ')
+    : '';
+
+  return (
+    <div className="weq-graytip weq-group-call text-center text-xs py-2">
+      <Icon className="weq-group-call-icon" size={13} strokeWidth={2} aria-hidden />
+      <span>{summary || `${isVideo ? '视频通话' : '语音通话'}已结束`}</span>
+    </div>
+  );
+}
diff --git a/apps/desktop/src/renderer/src/components/OnlineStatus.tsx b/apps/desktop/src/renderer/src/components/OnlineStatus.tsx
index 908ce82f..faeeb956 100644
--- a/apps/desktop/src/renderer/src/components/OnlineStatus.tsx
+++ b/apps/desktop/src/renderer/src/components/OnlineStatus.tsx
@@ -1,6 +1,7 @@
 import type React from 'react';
 import { trpc } from '../trpc/client';
 import { Circle, Smile, Clock, Minus, Ban, MinusCircle } from 'lucide-react';
+import { resourceUrl } from '../lib/resourceUrl';
 
 const SUB_ICONS: Record<number, string> = {
   1028: 'music@2x.png',
@@ -53,7 +54,7 @@ export function OnlineStatus({ uid }: { uid: string }) {
 
   const filename = status.type === 10 && SUB_ICONS[status.subType];
   const icon = filename
-    ? <img src={`weq-asset://OnlineStatus/${filename}`} alt="" style={{ width: 16, height: 16 }} />
+    ? <img src={resourceUrl('OnlineStatus', filename)} alt="" style={{ width: 16, height: 16 }} />
     : TYPE_ICONS[status.type]?.();
 
   return (
diff --git a/apps/desktop/src/renderer/src/components/QqCall.tsx b/apps/desktop/src/renderer/src/components/QqCall.tsx
index b65e4d3f..c0e41152 100644
--- a/apps/desktop/src/renderer/src/components/QqCall.tsx
+++ b/apps/desktop/src/renderer/src/components/QqCall.tsx
@@ -17,15 +17,26 @@ import { Phone, Video, MonitorUp, LaptopMinimal, PhoneCall } from 'lucide-react'
 // CallSubType values that mean "the call actually connected". Every other
 // value (rejected by either side, handled on another device, plain failure)
 // gets the red treatment. See packages/codec/src/element/types.ts.
+//
+// 群聊的「发起」（1/26）也算非失败 —— 那是一通电话的开头，不是未接来电。群聊的
+// 「已结束」（16/25）走灰条（GroupCallEndedMessage），走不到这里，但导出/转发等
+// 旁路会，所以一并列上。
 const CONNECTED_SUBTYPES = new Set<number>([
+  1, // GROUP_VOICE_STARTED
   2, // VIDEO_ACCEPTED
+  5, // VIDEO_ACCEPTED_LEGACY — 旧版客户端的视频接通
   7, // VOICE_ACCEPTED
+  16, // GROUP_VOICE_ENDED
   19, // SCREEN_SHARE_ACCEPTED
+  25, // GROUP_VIDEO_ENDED
+  26, // GROUP_VIDEO_STARTED
   33, // REMOTE_ASSIST_ACCEPTED
 ]);
 
-// CallType (callMethod) → display label + lucide icon.
+// CallType (callMethod) → display label + lucide icon. 0 是群通话结束提示，
+// QQ 不在这条消息里区分语音/视频（只能看 subType），所以用中性的话筒图标。
 const CALL_KIND: Record<number, { label: string; Icon: typeof Phone }> = {
+  0: { label: '通话已结束', Icon: PhoneCall },
   1: { label: '语音通话', Icon: Phone },
   2: { label: '视频通话', Icon: Video },
   3: { label: '屏幕共享', Icon: MonitorUp },
diff --git a/apps/desktop/src/renderer/src/components/QqMedia.tsx b/apps/desktop/src/renderer/src/components/QqMedia.tsx
index dee98e3a..cff52f67 100644
--- a/apps/desktop/src/renderer/src/components/QqMedia.tsx
+++ b/apps/desktop/src/renderer/src/components/QqMedia.tsx
@@ -13,6 +13,7 @@ import { cn } from '@renderer/lib/utils';
 import { trpc } from '@renderer/trpc/client';
 import { openLightbox } from './ImageLightbox';
 import { openMarketFaceLightbox } from './MarketFaceLightbox';
+import { IS_ELECTRON } from '@renderer/lib/target';
 
 type Data = Record<string, unknown>;
 
@@ -274,12 +275,13 @@ export function QqFile({
     if (busy) return;
     setError(null);
     void (async () => {
-      // 1. Local first: file_assistant.db → reveal in OS file manager.
-      if (msgId && (await revealFile(msgId))) return;
+      // 1. Local first: file_assistant.db → reveal in OS file manager. There's
+      //    no file manager to reveal into on web, so skip straight to (2).
+      if (IS_ELECTRON && msgId && (await revealFile(msgId))) return;
       // 2. Not on disk → OIDB completion (needs an online QQ). Only msgId is
       //    required; token just disambiguates multiple files in one message.
       if (!msgId) {
-        revealMedia(sendTimeMs, name, 'file');
+        if (IS_ELECTRON) revealMedia(sendTimeMs, name, 'file');
         return;
       }
       setBusy(true);
@@ -298,7 +300,7 @@ export function QqFile({
     <div
       className="qq-media-file"
       role="button"
-      title={error ?? (busy ? '正在下载…' : '在文件夹中打开（本地无则尝试下载）')}
+      title={error ?? (busy ? '正在下载…' : IS_ELECTRON ? '在文件夹中打开（本地无则尝试下载）' : '下载')}
       onClick={onClick}
     >
       <img className="qq-media-file-icon" src={fileIconUrl(iconForName(name))} alt="" draggable={false} />
diff --git a/apps/desktop/src/renderer/src/components/RailAccountFooter.tsx b/apps/desktop/src/renderer/src/components/RailAccountFooter.tsx
index 5a340999..3cffcc4b 100644
--- a/apps/desktop/src/renderer/src/components/RailAccountFooter.tsx
+++ b/apps/desktop/src/renderer/src/components/RailAccountFooter.tsx
@@ -28,6 +28,7 @@ import { runAccountWarmup } from '../lib/accountWarmup';
 import { useDialog } from './Dialog';
 import { useToast } from './Toast';
 import { QqAvatar } from './QqAvatar';
+import { DesktopOnly, shellBridge } from '../lib/target';
 
 function errMsg(e: unknown): string {
   return e instanceof Error ? e.message : String(e);
@@ -70,8 +71,10 @@ export function RailAccountFooter({
   const wrapRef = useRef<HTMLDivElement | null>(null);
 
   useEffect(() => {
+    const bridge = shellBridge();
+    if (!bridge) return undefined;
     let alive = true;
-    void window.weq.systemAuth
+    void bridge.systemAuth
       .getStatus()
       .then((s) => {
         if (!alive) return;
@@ -284,15 +287,17 @@ export function RailAccountFooter({
 
   return (
     <>
-      <button
-        type="button"
-        className="weq-rail-capture-btn"
-        title="截图当前窗口（复制到剪贴板）"
-        aria-label="截图当前窗口"
-        onClick={() => void captureNow()}
-      >
-        <Camera size={18} strokeWidth={1.8} aria-hidden />
-      </button>
+      <DesktopOnly>
+        <button
+          type="button"
+          className="weq-rail-capture-btn"
+          title="截图当前窗口（复制到剪贴板）"
+          aria-label="截图当前窗口"
+          onClick={() => void captureNow()}
+        >
+          <Camera size={18} strokeWidth={1.8} aria-hidden />
+        </button>
+      </DesktopOnly>
       <button
         type="button"
         className={`weq-rail-privacy-btn${privacyEnabled ? ' is-on' : ''}`}
@@ -320,16 +325,18 @@ export function RailAccountFooter({
           <Moon size={18} strokeWidth={1.8} aria-hidden />
         )}
       </button>
-      <button
-        type="button"
-        className="weq-rail-lock-btn"
-        title={authAvailable === false ? authError ?? '系统认证不可用' : '锁定 WeQ'}
-        aria-label="锁定 WeQ"
-        onClick={lockNow}
-        disabled={busy || authAvailable === false}
-      >
-        <LockKeyhole size={18} strokeWidth={1.8} aria-hidden />
-      </button>
+      <DesktopOnly>
+        <button
+          type="button"
+          className="weq-rail-lock-btn"
+          title={authAvailable === false ? authError ?? '系统认证不可用' : '锁定 WeQ'}
+          aria-label="锁定 WeQ"
+          onClick={lockNow}
+          disabled={busy || authAvailable === false}
+        >
+          <LockKeyhole size={18} strokeWidth={1.8} aria-hidden />
+        </button>
+      </DesktopOnly>
       <div ref={wrapRef} className="weq-rail-account-footer">
       <button
         type="button"
diff --git a/apps/desktop/src/renderer/src/components/settings/GlobalSettingsSection.tsx b/apps/desktop/src/renderer/src/components/settings/GlobalSettingsSection.tsx
index 6d1fd25b..6a3e6309 100644
--- a/apps/desktop/src/renderer/src/components/settings/GlobalSettingsSection.tsx
+++ b/apps/desktop/src/renderer/src/components/settings/GlobalSettingsSection.tsx
@@ -34,6 +34,7 @@ import { useToast } from '../Toast';
 import { QqAvatar } from '../QqAvatar';
 import { Card, Row, SectionHeader } from './controls';
 import { UpdateCard } from './UpdateCard';
+import { DesktopOnly, shellBridge } from '../../lib/target';
 import logoUrl from '@resources/brand/logo.png';
 
 function errMsg(e: unknown): string {
@@ -136,7 +137,9 @@ export function GlobalSettingsSection(): ReactElement {
   }, [settings.data?.windowCloseBehavior]);
 
   useEffect(() => {
-    void window.weq.systemAuth
+    const bridge = shellBridge();
+    if (!bridge) return;
+    void bridge.systemAuth
       .getStatus()
       .then(setSystemAuthStatus)
       .catch(() => setSystemAuthStatus(null));
@@ -284,10 +287,13 @@ export function GlobalSettingsSection(): ReactElement {
         </p>
       </Card>
 
-      {/* Software update */}
-      <UpdateCard />
+      {/* Software update — the web build can't replace its own binary. */}
+      <DesktopOnly>
+        <UpdateCard />
+      </DesktopOnly>
 
-      <Card title="应用锁">
+      <DesktopOnly>
+        <Card title="应用锁">
         <Row
           label={
             <span className="weq-set-row-icon">
@@ -363,6 +369,7 @@ export function GlobalSettingsSection(): ReactElement {
           }
         />
       </Card>
+      </DesktopOnly>
 
       {/* Account list */}
       <Card title="现有配置">
@@ -513,18 +520,20 @@ export function GlobalSettingsSection(): ReactElement {
         </div>
       </Card>
 
-      <Card title="日志">
-        <Row
-          label="日志文件夹"
-          desc="日志按日期拆分保存到 WeQ 缓存目录下的 logs 文件夹。"
-          control={
-            <button type="button" className="weq-set-btn" onClick={() => void onOpenLogDir()}>
-              <FolderOpen size={14} strokeWidth={1.8} aria-hidden />
-              打开日志文件夹
-            </button>
-          }
-        />
-      </Card>
+      <DesktopOnly>
+        <Card title="日志">
+          <Row
+            label="日志文件夹"
+            desc="日志按日期拆分保存到 WeQ 缓存目录下的 logs 文件夹。"
+            control={
+              <button type="button" className="weq-set-btn" onClick={() => void onOpenLogDir()}>
+                <FolderOpen size={14} strokeWidth={1.8} aria-hidden />
+                打开日志文件夹
+              </button>
+            }
+          />
+        </Card>
+      </DesktopOnly>
     </div>
   );
 }
diff --git a/apps/desktop/src/renderer/src/im-template/styles/sidebar.css b/apps/desktop/src/renderer/src/im-template/styles/sidebar.css
index e88cedbc..b948cad6 100644
--- a/apps/desktop/src/renderer/src/im-template/styles/sidebar.css
+++ b/apps/desktop/src/renderer/src/im-template/styles/sidebar.css
@@ -526,6 +526,30 @@ html[data-theme="dark"] .contact-cat-count {
 	font-weight: 400;
 }
 
+.row-time-line {
+	display: inline-flex;
+	align-items: center;
+	gap: 4px;
+}
+
+.row-pinned {
+	flex: 0 0 auto;
+	color: var(--weq-accent-effective, #0099f7);
+}
+
+/* 置顶会话：整行浅色底，与普通会话拉开层级（QQ 同款）。 */
+.conversation-row.pinned:not(.active) {
+	background: color-mix(in srgb, var(--weq-accent-effective) 6%, transparent);
+}
+
+.conversation-row.pinned:not(.active):hover {
+	background: color-mix(in srgb, var(--weq-accent-effective) 11%, transparent);
+}
+
+.conversation-row.active .row-pinned {
+	color: rgba(255, 255, 255, 0.86);
+}
+
 .conversation-row .avatar,
 .contact-row .avatar {
 	width: 50px;
diff --git a/apps/desktop/src/renderer/src/im-template/template/TitleBar.tsx b/apps/desktop/src/renderer/src/im-template/template/TitleBar.tsx
index 183a9d53..6bb26607 100644
--- a/apps/desktop/src/renderer/src/im-template/template/TitleBar.tsx
+++ b/apps/desktop/src/renderer/src/im-template/template/TitleBar.tsx
@@ -4,6 +4,7 @@ import { Avatar } from "./primitives";
 import type { User } from "./types";
 import { displayUserName } from "./user";
 import logoUrl from "@resources/brand/logo.png";
+import { DesktopOnly } from "../../lib/target";
 
 export function TitleBar({
 	user,
@@ -48,17 +49,19 @@ export function TitleBar({
 				)}
 				</div>
 			<div className="app-title-bar-drag" />
-			<div className="app-title-bar-actions">
-				<button onClick={handleMinimize} title="最小化">
-					<Minus size={14} />
-				</button>
-				<button onClick={handleMaximize} title="全屏/还原">
-					<Square size={12} />
-				</button>
-				<button onClick={handleClose} className="close" title="关闭">
-					<X size={16} />
-				</button>
-			</div>
+			<DesktopOnly>
+				<div className="app-title-bar-actions">
+					<button onClick={handleMinimize} title="最小化">
+						<Minus size={14} />
+					</button>
+					<button onClick={handleMaximize} title="全屏/还原">
+						<Square size={12} />
+					</button>
+					<button onClick={handleClose} className="close" title="关闭">
+						<X size={16} />
+					</button>
+				</div>
+			</DesktopOnly>
 		</div>
 	);
 }
diff --git a/apps/desktop/src/renderer/src/im-template/template/chatPane.tsx b/apps/desktop/src/renderer/src/im-template/template/chatPane.tsx
index 8ec1d64b..7c161dde 100644
--- a/apps/desktop/src/renderer/src/im-template/template/chatPane.tsx
+++ b/apps/desktop/src/renderer/src/im-template/template/chatPane.tsx
@@ -87,6 +87,7 @@ import { GrayTipGroupMessage } from '../../components/GrayTipGroupMessage';
 import { GrayTipInviteMessage } from '../../components/GrayTipInviteMessage';
 import { GrayTipFileRecvMessage } from '../../components/GrayTipFileRecvMessage';
 import { GrayTipTempSessionMessage } from '../../components/GrayTipTempSessionMessage';
+import { GroupCallEndedMessage, GROUP_CALL_ENDED_SUBTYPES } from '../../components/GroupCallEndedMessage';
 
 const composerHeightStorageKey = "chat-template.layout.composerHeight";
 const groupInfoCollapsedStorageKey = "chat-template.layout.groupInfoCollapsed";
@@ -1490,6 +1491,9 @@ export function ChatPane({
 				) : (
 					(() => {
 						// Detect the gray-tip element (if any) a message carries.
+						// 群通话的「已结束」（CALL 元素，subType 16/25）也走灰条：那条消息的
+						// 40020 是空的，谁也不属于，套气泡会凭空多出一个发送者。发起那条有正常
+						// 发送人，和私聊的 CALL 一样继续走气泡。
 						const GRAY_TIP_KINDS = ['grayTipPoke', 'grayTipRevoke', 'grayTipGroup', 'grayTipInvite', 'grayTipFileRecv', 'grayTipTempSession'];
 						const grayTipOf = (message) => {
 							const els = message.qqElements ?? [];
@@ -1497,6 +1501,10 @@ export function ChatPane({
 								const el = els.find((e) => e?.type === kind);
 								if (el) return { kind, el };
 							}
+							const callEnded = els.find(
+								(e) => e?.type === 'call' && GROUP_CALL_ENDED_SUBTYPES.has(Number(e?.data?.subType)),
+							);
+							if (callEnded) return { kind: 'groupCallEnded', el: callEnded };
 							return null;
 						};
 
@@ -1515,6 +1523,8 @@ export function ChatPane({
 									return <GrayTipFileRecvMessage element={gt.el} />;
 								case 'grayTipTempSession':
 									return <GrayTipTempSessionMessage element={gt.el} />;
+								case 'groupCallEnded':
+									return <GroupCallEndedMessage element={gt.el} />;
 								default:
 									return null;
 							}
diff --git a/apps/desktop/src/renderer/src/im-template/template/conversationLists.tsx b/apps/desktop/src/renderer/src/im-template/template/conversationLists.tsx
index 7ac37187..504497f7 100644
--- a/apps/desktop/src/renderer/src/im-template/template/conversationLists.tsx
+++ b/apps/desktop/src/renderer/src/im-template/template/conversationLists.tsx
@@ -1,10 +1,11 @@
 // @ts-nocheck
-import { BellOff, Bot, PenLine, MessageSquare, Users, UserRound, Circle, Smile, Clock, Minus, Ban, MinusCircle, ChevronRight } from "lucide-react";
+import { BellOff, Bot, PenLine, Pin, MessageSquare, Users, UserRound, Circle, Smile, Clock, Minus, Ban, MinusCircle, ChevronRight } from "lucide-react";
 import { useMemo, useState } from "react";
 import { cn } from "./classNames";
 import { Avatar, EmptyState, } from "./primitives";
 import { isBotConversation } from "./conversationDisplay";
 import { messageMentionsUser } from "./mentions";
+import { resourceUrl } from "../../lib/resourceUrl";
 import type {
 	Contact,
 	Conversation,
@@ -40,10 +41,11 @@ export function ConversationList({
 				)
 			: conversations;
 
+		// 置顶会话排最前。sort 是稳定的，所以 MainView 已排好的置顶时间（41103）
+		// 次序在这里被保留。
 		return [...next].sort(
 			(first, second) =>
-				Number(Boolean(preferences[second.id]?.pinned)) -
-				Number(Boolean(preferences[first.id]?.pinned)),
+				Number(isPinned(second, preferences)) - Number(isPinned(first, preferences)),
 		);
 	}, [conversations, preferences, query]);
 
@@ -80,11 +82,12 @@ export function ConversationList({
 					...conversation.preference,
 					...preferences[conversation.id],
 				}.muted);
+				const pinned = isPinned(conversation, preferences);
 
 				return (
 					<button
 						key={conversation.id}
-						className={cn(listRowClass(active, "conversation-row"))}
+						className={cn(listRowClass(active, "conversation-row"), pinned && "pinned")}
 						onClick={() => onSelect(conversation.id)}
 					>
 						<Avatar
@@ -141,7 +144,17 @@ export function ConversationList({
 							</span>
 						</span>
 						<span className={cn("row-meta")}>
-							<span>{formatConversationTime(conversation.updatedAt)}</span>
+							<span className={cn("row-time-line")}>
+								{pinned ? (
+									<Pin
+										className={cn("row-pinned")}
+										size={12}
+										aria-label="置顶"
+										title="置顶会话"
+									/>
+								) : null}
+								{formatConversationTime(conversation.updatedAt)}
+							</span>
 							{unreadCount ? (
 								<span className={cn(unreadClass(muted))}>
 									{formatBadgeCount(unreadCount)}
@@ -366,7 +379,7 @@ function ContactOnlineStatusIcon({ status }: { status: OnlineStatusInfo | undefi
 	if (!status) return null;
 	const filename = status.type === 10 && SUB_ICONS[status.subType];
 	if (filename) {
-		return <img src={`weq-asset://OnlineStatus/${filename}`} alt="" style={{ width: 14, height: 14 }} />;
+		return <img src={resourceUrl('OnlineStatus', filename)} alt="" style={{ width: 14, height: 14 }} />;
 	}
 	const TypeIcon = TYPE_ICONS[status.type];
 	return TypeIcon ? <TypeIcon /> : null;
@@ -490,6 +503,20 @@ function formatBadgeCount(value: number) {
 	return value > 99 ? "99+" : String(value);
 }
 
+/**
+ * 置顶：会话自带的 DB 值（recent_contact_top_table）打底，本地手动偏好覆盖 ——
+ * merge 顺序与上面的 muted（41220）保持一致。
+ */
+function isPinned(
+	conversation: Conversation,
+	preferences: ConversationPreferences,
+): boolean {
+	return Boolean({
+		...conversation.preference,
+		...preferences[conversation.id],
+	}.pinned);
+}
+
 function listRowClass(
 	active: boolean,
 	semanticClass: "conversation-row" | "contact-row",
diff --git a/apps/desktop/src/renderer/src/lib/accountWarmup.ts b/apps/desktop/src/renderer/src/lib/accountWarmup.ts
index aa75c9ef..4a59b440 100644
--- a/apps/desktop/src/renderer/src/lib/accountWarmup.ts
+++ b/apps/desktop/src/renderer/src/lib/accountWarmup.ts
@@ -35,6 +35,7 @@ interface WarmupStep {
 const STEPS: readonly WarmupStep[] = [
   { label: '账号资料', run: (u) => u.account.getSelfProfile.fetch(undefined) },
   { label: '最近会话', run: (u) => u.account.listRecentContacts.fetch(undefined) },
+  { label: '置顶会话', run: (u) => u.account.listTopContacts.fetch(undefined) },
   { label: '好友列表', run: (u) => u.account.listBuddies.fetch({ limit: 2000 }) },
   { label: '好友分组', run: (u) => u.account.listCategories.fetch(undefined) },
   { label: '好友资料', run: (u) => u.account.listProfiles.fetch({ limit: 2000 }) },
diff --git a/apps/desktop/src/renderer/src/lib/avatarCache.ts b/apps/desktop/src/renderer/src/lib/avatarCache.ts
index 8291ceaf..406380f5 100644
--- a/apps/desktop/src/renderer/src/lib/avatarCache.ts
+++ b/apps/desktop/src/renderer/src/lib/avatarCache.ts
@@ -5,8 +5,7 @@
  * site is all the renderer has to do.
  */
 
-const SCHEME = 'weq-avatar';
-const MEDIA_SCHEME = 'weq-media';
+import { avatarFetchUrl, mediaUrl } from './resourceUrl';
 
 /**
  * Build the local-first avatar URL: the main process resolves the peer's cached
@@ -15,8 +14,7 @@ const MEDIA_SCHEME = 'weq-media';
  * falls back to the thumbnail when that's all QQ cached.
  */
 function localFirst(params: Record<string, string>, fb: string): string {
-  const q = new URLSearchParams({ ...params, v: 'big', fb });
-  return `${MEDIA_SCHEME}://avatar?${q.toString()}`;
+  return mediaUrl('avatar', { ...params, v: 'big', fb });
 }
 
 /**
@@ -40,5 +38,5 @@ export function cachedAvatarUrl(src: string | null | undefined): string | null {
   if (groupGh) return localFirst({ scope: 'group', uid: groupGh[1]! }, src);
 
   // Non-QQ remote avatar (e.g. GitHub in demo/agentlab): plain URL disk cache.
-  return `${SCHEME}://fetch?src=${encodeURIComponent(src)}`;
+  return avatarFetchUrl(src);
 }
diff --git a/apps/desktop/src/renderer/src/lib/resourceUrl.ts b/apps/desktop/src/renderer/src/lib/resourceUrl.ts
index ca3e48c9..c82d7d55 100644
--- a/apps/desktop/src/renderer/src/lib/resourceUrl.ts
+++ b/apps/desktop/src/renderer/src/lib/resourceUrl.ts
@@ -1,9 +1,18 @@
 /**
  * URL builders for the `weq-asset://` protocol (served by the main process
  * from the shared `resources/` tree — see src/main/resource_protocol.ts).
+ *
+ * In the browser build there are no custom schemes, so the same handlers are
+ * mounted on HTTP routes and these builders emit `/_asset/…` / `/_media/…`
+ * instead. `VITE_WEQ_TARGET` is set by each app's vite config.
  */
 
-const SCHEME = 'weq-asset';
+const IS_WEB = import.meta.env.VITE_WEQ_TARGET === 'web';
+
+/** `weq-asset://` on Electron, `/_asset/` in the browser. */
+const SCHEME_PREFIX = IS_WEB ? '/_asset/' : 'weq-asset://';
+const MEDIA_PREFIX = IS_WEB ? '/_media/' : 'weq-media://';
+const AVATAR_PREFIX = IS_WEB ? '/_avatar/' : 'weq-avatar://';
 
 /** `weq-asset://<segments joined by '/'>` */
 export function resourceUrl(...segments: string[]): string {
@@ -12,7 +21,7 @@ export function resourceUrl(...segments: string[]): string {
     .filter(Boolean)
     .map(encodeURIComponent)
     .join('/');
-  return `${SCHEME}://${path}`;
+  return `${SCHEME_PREFIX}${path}`;
 }
 
 /** Shorthand for assets under `resources/emoji/…`. */
@@ -25,8 +34,6 @@ export function fileIconUrl(iconBasename: string): string {
   return resourceUrl('fileIcon', iconBasename);
 }
 
-const MEDIA_SCHEME = 'weq-media';
-
 /**
  * `weq-media://<kind>?<query>` — streams a chat message's on-disk media (served
  * by src/main/media_protocol.ts). `kind` is pic/video/ptt/mface.
@@ -34,7 +41,7 @@ const MEDIA_SCHEME = 'weq-media';
 export function mediaUrl(kind: string, params: Record<string, string | number>): string {
   const q = new URLSearchParams();
   for (const [k, v] of Object.entries(params)) q.set(k, String(v));
-  return `${MEDIA_SCHEME}://${kind}?${q.toString()}`;
+  return `${MEDIA_PREFIX}${kind}?${q.toString()}`;
 }
 
 /** Proxy a remote QQ album image through the main process so Qzone referer is attached. */
@@ -42,13 +49,18 @@ export function albumMediaUrl(src: string): string {
   return mediaUrl('album', { src });
 }
 
+/** `weq-avatar://fetch?src=…` — the disk-cached bridge for a remote image. */
+export function avatarFetchUrl(src: string): string {
+  return `${AVATAR_PREFIX}fetch?src=${encodeURIComponent(src)}`;
+}
+
 /**
  * Proxy a QQ 收藏 (collection) collector-CDN image (`http://shp.qpic.cn/collector/…`)
  * through the disk-cached avatar bridge. The collector CDN is public (no referer),
  * so the generic fetch+cache bridge is enough; on failure `<img onError>` falls back.
  */
 export function collectionImageUrl(src: string): string {
-  return `weq-avatar://fetch?src=${encodeURIComponent(src)}`;
+  return avatarFetchUrl(src);
 }
 
 /**
diff --git a/apps/desktop/src/renderer/src/lib/target.tsx b/apps/desktop/src/renderer/src/lib/target.tsx
new file mode 100644
index 00000000..c3a70fc3
--- /dev/null
+++ b/apps/desktop/src/renderer/src/lib/target.tsx
@@ -0,0 +1,34 @@
+/**
+ * Build-target helpers.
+ *
+ * `VITE_WEQ_TARGET` is set by each app's vite config ('electron' | 'web').
+ * Because it's a literal at build time, rollup drops the dead branch entirely —
+ * so Electron-only UI (and the `window.electron` calls behind it) never reaches
+ * the browser bundle.
+ */
+
+import type { ReactElement, ReactNode } from 'react';
+
+export const IS_WEB = import.meta.env.VITE_WEQ_TARGET === 'web';
+export const IS_ELECTRON = !IS_WEB;
+
+/**
+ * Render `children` only in the Electron build. Use for anything that depends
+ * on a native shell: window controls, tray, file-manager reveal, screenshots,
+ * system auth, in-app updates.
+ */
+export function DesktopOnly({ children }: { children: ReactNode }): ReactElement | null {
+  if (IS_WEB) return null;
+  return <>{children}</>;
+}
+
+/**
+ * The preload bridge, or `undefined` in the browser build.
+ *
+ * `DesktopOnly` only skips JSX — hooks in the same component still run on web,
+ * where `window.weq` was never injected. Any effect touching the bridge must go
+ * through this and bail when it's absent.
+ */
+export function shellBridge(): Window['weq'] | undefined {
+  return IS_WEB ? undefined : window.weq;
+}
diff --git a/apps/desktop/src/renderer/src/styles/index.css b/apps/desktop/src/renderer/src/styles/index.css
index 3a9025d0..ac0fdc2c 100644
--- a/apps/desktop/src/renderer/src/styles/index.css
+++ b/apps/desktop/src/renderer/src/styles/index.css
@@ -3362,6 +3362,87 @@ html[data-theme='dark'] .app-shell .rail-footer .weq-rail-privacy-btn {
   font-size: 13px;
 }
 
+/* 网页版的 QQ 空间 / 频道入口：一张居中的「开新标签」卡片。 */
+.weq-extsite {
+  display: grid;
+  place-items: center;
+  width: 100%;
+  height: 100%;
+  padding: 24px;
+}
+
+.weq-extsite-card {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 10px;
+  max-width: 380px;
+  padding: 36px 32px 30px;
+  text-align: center;
+  border: 1px solid var(--weq-border, rgba(0, 153, 255, 0.16));
+  border-radius: 16px;
+  background: var(--weq-surface, rgba(255, 255, 255, 0.6));
+  backdrop-filter: blur(10px);
+}
+
+.weq-extsite-icon {
+  display: grid;
+  place-items: center;
+  width: 56px;
+  height: 56px;
+  margin-bottom: 4px;
+  border-radius: 16px;
+  color: var(--weq-accent, #0099ff);
+  background: color-mix(in srgb, var(--weq-accent, #0099ff) 12%, transparent);
+}
+
+.weq-extsite-title {
+  margin: 0;
+  font-size: 17px;
+  font-weight: 600;
+  color: var(--weq-fg-primary, #142235);
+}
+
+.weq-extsite-desc {
+  margin: 0;
+  font-size: 13px;
+  line-height: 1.65;
+  color: var(--weq-text-muted, #8a94a6);
+}
+
+.weq-extsite-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 7px;
+  margin-top: 10px;
+  padding: 9px 18px;
+  font-size: 13.5px;
+  font-weight: 500;
+  color: #fff;
+  background: var(--weq-accent, #0099ff);
+  border: 0;
+  border-radius: 9px;
+  cursor: pointer;
+  transition: transform 140ms ease, filter 140ms ease;
+}
+
+.weq-extsite-btn:hover:not(:disabled) {
+  transform: translateY(-1px);
+  filter: brightness(1.06);
+}
+
+.weq-extsite-btn:disabled {
+  cursor: default;
+  opacity: 0.6;
+}
+
+.weq-extsite-hint {
+  margin: 6px 0 0;
+  font-size: 12px;
+  line-height: 1.6;
+  color: var(--weq-text-muted, #8a94a6);
+}
+
 
 .weq-readonly-chat .chat-pane {
   grid-template-rows: var(--chat-header-height) minmax(0, 1fr) 0 !important;
@@ -10971,6 +11052,18 @@ html[data-theme="dark"] .weq-graytip-band {
   color: var(--weq-fg-muted, var(--weq-fg-tertiary, var(--weq-fg-secondary)));
 }
 
+/* 群通话灰条：图标与文字同行居中（发起人名字用 .weq-graytip-accent 着色）。 */
+.weq-group-call {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 4px;
+}
+.weq-group-call-icon {
+  flex-shrink: 0;
+  color: currentColor;
+}
+
 /* "本地暂无内容" hint — centered, small, non-bold, accent-leaning. */
 .weq-graytip-band-hint {
   margin-top: 2px;
diff --git a/apps/desktop/src/renderer/src/trpc/client.ts b/apps/desktop/src/renderer/src/trpc/client.ts
index e0e20e6d..ece13d7d 100644
--- a/apps/desktop/src/renderer/src/trpc/client.ts
+++ b/apps/desktop/src/renderer/src/trpc/client.ts
@@ -25,9 +25,9 @@
  */
 
 import { createTRPCReact } from '@trpc/react-query';
-import { createTRPCClientProxy, type TRPCLink } from '@trpc/client';
-import { ipcLink } from 'electron-trpc/renderer';
+import { createTRPCClientProxy } from '@trpc/client';
 import superjson from 'superjson';
+import { createLinks } from '@transport';
 import type { AppRouter } from '../../../shared/router';
 
 export const trpc = createTRPCReact<AppRouter>();
@@ -36,9 +36,12 @@ export const trpc = createTRPCReact<AppRouter>();
  * The single underlying (untyped) client for the whole renderer. Passed to
  * <trpc.Provider> in provider.tsx; do NOT call `trpc.createClient` a second
  * time — every consumer must share this one instance / id space.
+ *
+ * `@transport` resolves per build target: IPC in Electron, HTTP + WebSocket in
+ * the browser (see each app's vite alias).
  */
 export const trpcClient = trpc.createClient({
-  links: [ipcLink() as unknown as TRPCLink<AppRouter>],
+  links: createLinks(),
   transformer: superjson,
 });
 
diff --git a/apps/desktop/src/renderer/src/trpc/transport.electron.ts b/apps/desktop/src/renderer/src/trpc/transport.electron.ts
new file mode 100644
index 00000000..ff3cb7a4
--- /dev/null
+++ b/apps/desktop/src/renderer/src/trpc/transport.electron.ts
@@ -0,0 +1,15 @@
+/**
+ * tRPC transport — Electron build.
+ *
+ * `ipcLink` carries every call over the IPC bridge set up in the preload.
+ * The web build resolves `@transport` to `transport.web.ts` instead; see the
+ * alias in each app's vite config.
+ */
+
+import type { TRPCLink } from '@trpc/client';
+import { ipcLink } from 'electron-trpc/renderer';
+import type { AppRouter } from '../../../shared/router';
+
+export function createLinks(): TRPCLink<AppRouter>[] {
+  return [ipcLink() as unknown as TRPCLink<AppRouter>];
+}
diff --git a/apps/desktop/src/renderer/src/trpc/transport.web.ts b/apps/desktop/src/renderer/src/trpc/transport.web.ts
new file mode 100644
index 00000000..1f636ea1
--- /dev/null
+++ b/apps/desktop/src/renderer/src/trpc/transport.web.ts
@@ -0,0 +1,35 @@
+/**
+ * tRPC transport — browser build.
+ *
+ * Queries and mutations go over HTTP; the 14 subscriptions ride a single
+ * WebSocket (tRPC v10 has no SSE link). `splitLink` routes by operation type.
+ *
+ * A 401 means the session expired — reload so the server serves the login page
+ * rather than leaving the UI stuck on failing requests.
+ */
+
+import { createWSClient, httpBatchLink, splitLink, wsLink, type TRPCLink } from '@trpc/client';
+import type { AppRouter } from '../../../shared/router';
+
+const wsProtocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
+
+const wsClient = createWSClient({
+  url: `${wsProtocol}//${location.host}/trpc-ws`,
+});
+
+export function createLinks(): TRPCLink<AppRouter>[] {
+  return [
+    splitLink({
+      condition: (op) => op.type === 'subscription',
+      true: wsLink({ client: wsClient }),
+      false: httpBatchLink({
+        url: '/trpc',
+        async fetch(input, init) {
+          const res = await fetch(input, { ...init, credentials: 'same-origin' });
+          if (res.status === 401) location.reload();
+          return res;
+        },
+      }),
+    }),
+  ];
+}
diff --git a/apps/desktop/src/renderer/src/views/ChannelView.tsx b/apps/desktop/src/renderer/src/views/ChannelView.tsx
index a4c1fb1a..d86918fd 100644
--- a/apps/desktop/src/renderer/src/views/ChannelView.tsx
+++ b/apps/desktop/src/renderer/src/views/ChannelView.tsx
@@ -1,10 +1,24 @@
 /**
- * QQ 频道内嵌视图。见 EmbeddedBrowserView 的说明。
+ * QQ 频道视图。桌面版内嵌 `<webview>`（见 EmbeddedBrowserView）；网页版嵌不了
+ * （对方站点禁 iframe），改成开新标签（见 ExternalSiteView）。
  */
 
 import type { ReactElement } from 'react';
+import { Hash } from 'lucide-react';
 import { EmbeddedBrowserView } from './EmbeddedBrowserView';
+import { ExternalSiteView } from './ExternalSiteView';
+import { IS_WEB } from '../lib/target';
 
 export function ChannelView(): ReactElement {
+  if (IS_WEB) {
+    return (
+      <ExternalSiteView
+        site="channel"
+        label="QQ 频道"
+        desc="子频道、话题、动态 —— 在浏览器新标签里打开 QQ 频道。"
+        icon={<Hash size={28} strokeWidth={1.5} aria-hidden />}
+      />
+    );
+  }
   return <EmbeddedBrowserView bridge={window.weq?.channel} label="QQ 频道" />;
 }
diff --git a/apps/desktop/src/renderer/src/views/ExternalSiteView.tsx b/apps/desktop/src/renderer/src/views/ExternalSiteView.tsx
new file mode 100644
index 00000000..d679cab6
--- /dev/null
+++ b/apps/desktop/src/renderer/src/views/ExternalSiteView.tsx
@@ -0,0 +1,73 @@
+/**
+ * 网页版的 QQ 空间 / QQ 频道入口 —— 一张「在新标签页打开」的卡片。
+ *
+ * 桌面版把这两个站点嵌在 `<webview>` 里（见 EmbeddedBrowserView），浏览器里做不到：
+ * user.qzone.qq.com 与 pd.qq.com 都发 X-Frame-Options，iframe 会被拒；跨站 cookie
+ * 也不是我们能替浏览器写的。
+ *
+ * 所以改为：点击时向后端现取一条 ptlogin2 跳转 URL（带一次性 clientKey），交给浏览器
+ * 开新标签。302 链在浏览器里跑完，登录 cookie 落进浏览器自己的 jar —— 等价于用户
+ * 手动登录了一次，之后再访问都是登录态。
+ *
+ * QQ 没在线（拿不到 clientKey）时后端退回裸地址，用户自己在新标签里登录。
+ */
+
+import { useState, type ReactElement } from 'react';
+import { ExternalLink, Loader2 } from 'lucide-react';
+import { trpc } from '../trpc/client';
+import { useDialog } from '../components/Dialog';
+
+export function ExternalSiteView({
+  site,
+  label,
+  desc,
+  icon,
+}: {
+  site: 'qzone' | 'channel';
+  label: string;
+  desc: string;
+  icon: ReactElement;
+}): ReactElement {
+  const showError = useDialog((s) => s.showError);
+  const resolve = trpc.account.getExternalSiteUrl.useMutation();
+  const [autoLogin, setAutoLogin] = useState<boolean | null>(null);
+
+  async function open(): Promise<void> {
+    try {
+      const res = await resolve.mutateAsync({ site });
+      setAutoLogin(res.autoLogin);
+      // 先开窗再等异步会被拦截器挡下，所以这里接受「用户点击→请求→开窗」的延迟。
+      window.open(res.url, '_blank', 'noopener,noreferrer');
+    } catch (e) {
+      showError(`打开${label}失败`, e instanceof Error ? e.message : String(e));
+    }
+  }
+
+  return (
+    <div className="weq-extsite">
+      <div className="weq-extsite-card">
+        <span className="weq-extsite-icon">{icon}</span>
+        <h2 className="weq-extsite-title">{label}</h2>
+        <p className="weq-extsite-desc">{desc}</p>
+        <button
+          type="button"
+          className="weq-extsite-btn"
+          onClick={() => void open()}
+          disabled={resolve.isLoading}
+        >
+          {resolve.isLoading ? (
+            <Loader2 size={16} strokeWidth={1.9} className="weq-spin" aria-hidden />
+          ) : (
+            <ExternalLink size={16} strokeWidth={1.9} aria-hidden />
+          )}
+          在新标签页打开
+        </button>
+        <p className="weq-extsite-hint">
+          {autoLogin === false
+            ? '当前账号的 QQ 未在线，无法免登录跳转 —— 新标签里需要自己登录一次。'
+            : '会带上当前账号的登录跳转，在新标签里直接是登录态。'}
+        </p>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/desktop/src/renderer/src/views/MainView.tsx b/apps/desktop/src/renderer/src/views/MainView.tsx
index a98fc6bc..9adbebce 100644
--- a/apps/desktop/src/renderer/src/views/MainView.tsx
+++ b/apps/desktop/src/renderer/src/views/MainView.tsx
@@ -164,6 +164,15 @@ type RecentContactWire = {
   tempSourceGroupCode: string;
 };
 
+/** 置顶会话一行（recent_contact_top_table）。 */
+type RecentContactTopWire = {
+  chatType: string | number;
+  /** 41103 — 置顶时间，unix 秒。 */
+  topTime: string;
+  /** 会话键：c2c 是对端 uid，群是群号 —— 对齐 RecentContactWire.targetUid。 */
+  targetId: string;
+};
+
 type MessageWire = {
   msgId: string;
   /** In-conversation sequence number (column 40003); the seq-window cursor. */
@@ -1511,6 +1520,7 @@ export function MainView(): ReactElement {
   const showError = useDialog((s) => s.showError);
   const pushToast = useToast((s) => s.push);
   const contacts = trpc.account.listRecentContacts.useQuery();
+  const topContacts = trpc.account.listTopContacts.useQuery();
   const selfProfile = trpc.account.getSelfProfile.useQuery();
   const buddies = trpc.account.listBuddies.useQuery({ limit: 2000 });
   const categories = trpc.account.listCategories.useQuery();
@@ -1569,6 +1579,7 @@ export function MainView(): ReactElement {
     const sub = client.account.onDbChanged.subscribe(undefined, {
       onData() {
         void utils.account.listRecentContacts.invalidate();
+        void utils.account.listTopContacts.invalidate();
         void refreshWindow();
       },
       onError(err) {
@@ -1918,6 +1929,14 @@ export function MainView(): ReactElement {
       ),
     [buddies.data, categoryById, onlineStatusByUid, profileByUid],
   );
+  // 置顶会话（recent_contact_top_table）：会话 id → 置顶时间（41103，秒）。
+  const topTimeByConv = useMemo(() => {
+    const map: Record<string, number> = {};
+    for (const top of (topContacts.data ?? []) as RecentContactTopWire[]) {
+      if (top.targetId) map[top.targetId] = Number(top.topTime);
+    }
+    return map;
+  }, [topContacts.data]);
   const conversations = useMemo(
     () => {
       const groups = (allGroups.data ?? []) as GroupDetailWire[];
@@ -1935,20 +1954,30 @@ export function MainView(): ReactElement {
         .map((conversation) => {
           const unread = unreadByConv[conversation.id];
           const highlights = highlightsByConv[conversation.id] ?? null;
-          if (!unread && !highlights) return conversation;
+          const topTime = topTimeByConv[conversation.id];
+          if (!unread && !highlights && topTime === undefined) return conversation;
           return {
             ...conversation,
             ...(unread ? { unreadCount: unread } : {}),
+            ...(topTime === undefined
+              ? {}
+              : { preference: { ...fallbackPreference, ...conversation.preference, pinned: true } }),
             highlights,
           };
         })
+        // 置顶会话整体排在最前，组内按置顶时间（41103）倒序；其余按最后消息时间倒序。
         .sort((a, b) => {
-          const aTime = Date.parse(a.updatedAt);
-          const bTime = Date.parse(b.updatedAt);
-          return bTime - aTime;
+          const aTop = topTimeByConv[a.id];
+          const bTop = topTimeByConv[b.id];
+          if (aTop !== undefined || bTop !== undefined) {
+            if (aTop === undefined) return 1;
+            if (bTop === undefined) return -1;
+            return bTop - aTop;
+          }
+          return Date.parse(b.updatedAt) - Date.parse(a.updatedAt);
         });
     },
-    [allGroups.data, contacts.data, user, unreadByConv, highlightsByConv],
+    [allGroups.data, contacts.data, user, unreadByConv, highlightsByConv, topTimeByConv],
   );
   const groupsById = useMemo(() => new Map(conversations.map((conversation) => [conversation.id, conversation])), [conversations]);
   const contactRequests = useMemo(
diff --git a/apps/desktop/src/renderer/src/views/QzoneView.tsx b/apps/desktop/src/renderer/src/views/QzoneView.tsx
index 8bb86763..402da7f7 100644
--- a/apps/desktop/src/renderer/src/views/QzoneView.tsx
+++ b/apps/desktop/src/renderer/src/views/QzoneView.tsx
@@ -1,10 +1,24 @@
 /**
- * QQ 空间内嵌视图。见 EmbeddedBrowserView 的说明。
+ * QQ 空间视图。桌面版内嵌 `<webview>`（见 EmbeddedBrowserView）；网页版嵌不了
+ * （对方站点禁 iframe），改成开新标签（见 ExternalSiteView）。
  */
 
 import type { ReactElement } from 'react';
+import { Star } from 'lucide-react';
 import { EmbeddedBrowserView } from './EmbeddedBrowserView';
+import { ExternalSiteView } from './ExternalSiteView';
+import { IS_WEB } from '../lib/target';
 
 export function QzoneView(): ReactElement {
+  if (IS_WEB) {
+    return (
+      <ExternalSiteView
+        site="qzone"
+        label="QQ 空间"
+        desc="说说、相册、留言板 —— 在浏览器新标签里打开你的 QQ 空间主页。"
+        icon={<Star size={28} strokeWidth={1.5} aria-hidden />}
+      />
+    );
+  }
   return <EmbeddedBrowserView bridge={window.weq?.qzone} label="QQ 空间" />;
 }
diff --git a/apps/desktop/src/renderer/src/views/agentlab/ChatBubble.tsx b/apps/desktop/src/renderer/src/views/agentlab/ChatBubble.tsx
index 089fb111..e6046371 100644
--- a/apps/desktop/src/renderer/src/views/agentlab/ChatBubble.tsx
+++ b/apps/desktop/src/renderer/src/views/agentlab/ChatBubble.tsx
@@ -3,6 +3,7 @@ import { Fragment, useRef, useState, type ReactElement, type ReactNode } from 'r
 import { Bot, Pause, Play } from 'lucide-react';
 import { QqAvatar } from '../../components/QqAvatar';
 import { FaceEmoji } from '../../components/FaceEmoji';
+import { mediaUrl } from '../../lib/resourceUrl';
 
 /** 系统表情匹配上下文：whitelist=本克隆体用过的 faceText；descToId=外显文字→faceId。 */
 export interface FaceContext {
@@ -55,7 +56,7 @@ const VOICE_MARKER = /^\[\[voice:([0-9a-zA-Z._-]+)\]\]$/;
 function VoiceBubble({ personaId, voiceId }: { personaId: string; voiceId: string }): ReactElement {
   const audioRef = useRef<HTMLAudioElement | null>(null);
   const [playing, setPlaying] = useState(false);
-  const src = `weq-media://agentvoice?persona=${encodeURIComponent(personaId)}&id=${encodeURIComponent(voiceId)}`;
+  const src = mediaUrl('agentvoice', { persona: personaId, id: voiceId });
   const toggle = (): void => {
     let audio = audioRef.current;
     if (!audio) {
@@ -132,7 +133,7 @@ export function ChatBubble({
           {stickerMatch ? (
             <img
               className="weq-agentlab-sticker-img"
-              src={`weq-media://sticker?persona=${encodeURIComponent(personaId!)}&md5=${encodeURIComponent(stickerMatch[1] ?? '')}`}
+              src={mediaUrl('sticker', { persona: personaId!, md5: stickerMatch[1] ?? '' })}
               alt="[表情]"
               draggable={false}
               onLoad={onMediaLoad}
diff --git a/apps/desktop/src/renderer/src/views/cache/AvatarExplorer.tsx b/apps/desktop/src/renderer/src/views/cache/AvatarExplorer.tsx
index 7e56e9f9..cd3becf8 100644
--- a/apps/desktop/src/renderer/src/views/cache/AvatarExplorer.tsx
+++ b/apps/desktop/src/renderer/src/views/cache/AvatarExplorer.tsx
@@ -18,6 +18,7 @@ import { Users, UsersRound, Image as ImageIcon, RefreshCw, Calculator } from 'lu
 import type { AvatarEntry, AvatarScope, AvatarScopeInfo } from '@weq/service';
 import { trpc, client } from '../../trpc/client';
 import { AvatarPathDialog } from './AvatarPathDialog';
+import { mediaUrl } from '../../lib/resourceUrl';
 
 const PAGE = 120;
 
@@ -41,7 +42,7 @@ function fmtBytes(bytes: number): string {
 
 /** weq-media URL for one avatar file. */
 function avatarSrc(scope: AvatarScope, hash: string, variant: 'big' | 'small'): string {
-  return `weq-media://avatar?scope=${scope}&hash=${hash}&v=${variant}`;
+  return mediaUrl('avatar', { scope, hash, v: variant });
 }
 
 export function AvatarExplorer(): ReactElement {
diff --git a/apps/desktop/src/renderer/src/views/cache/AvatarPathDialog.tsx b/apps/desktop/src/renderer/src/views/cache/AvatarPathDialog.tsx
index 5788b651..75c61592 100644
--- a/apps/desktop/src/renderer/src/views/cache/AvatarPathDialog.tsx
+++ b/apps/desktop/src/renderer/src/views/cache/AvatarPathDialog.tsx
@@ -15,6 +15,7 @@ import { X, Search, User, Users, Copy, Check } from 'lucide-react';
 import type { AvatarPathProbe } from '@weq/service';
 import { Modal } from '../../components/Dialog';
 import { client } from '../../trpc/client';
+import { mediaUrl } from '../../lib/resourceUrl';
 
 type Kind = 'user' | 'group';
 
@@ -32,7 +33,7 @@ function fmtBytes(bytes: number): string {
 
 /** weq-media URL for the resolved avatar (by hash — same as the grid). */
 function previewSrc(probe: AvatarPathProbe, variant: 'big' | 'small'): string {
-  return `weq-media://avatar?scope=${probe.scope}&hash=${probe.hash}&v=${variant}`;
+  return mediaUrl('avatar', { scope: probe.scope, hash: probe.hash, v: variant });
 }
 
 export function AvatarPathDialog({ onClose }: { onClose: () => void }): ReactElement {
diff --git a/apps/desktop/src/renderer/src/views/cache/DownloadFileExplorer.tsx b/apps/desktop/src/renderer/src/views/cache/DownloadFileExplorer.tsx
index 40d2859c..0baac019 100644
Binary files a/apps/desktop/src/renderer/src/views/cache/DownloadFileExplorer.tsx and b/apps/desktop/src/renderer/src/views/cache/DownloadFileExplorer.tsx differ
diff --git a/apps/desktop/src/renderer/src/views/cache/FileDirExplorer.tsx b/apps/desktop/src/renderer/src/views/cache/FileDirExplorer.tsx
index 5bcd5799..e64ae7fb 100644
Binary files a/apps/desktop/src/renderer/src/views/cache/FileDirExplorer.tsx and b/apps/desktop/src/renderer/src/views/cache/FileDirExplorer.tsx differ
diff --git a/apps/desktop/tsconfig.web.json b/apps/desktop/tsconfig.web.json
index 15a4b3b4..9affae26 100644
--- a/apps/desktop/tsconfig.web.json
+++ b/apps/desktop/tsconfig.web.json
@@ -11,7 +11,8 @@
     "types": ["vite/client"],
     "paths": {
       "@renderer/*": ["src/renderer/src/*"],
-      "@resources/*": ["../../resources/*"]
+      "@resources/*": ["../../resources/*"],
+      "@transport": ["src/renderer/src/trpc/transport.electron.ts"]
     },
     "outDir": "out/types-web"
   },
diff --git a/apps/web/README.md b/apps/web/README.md
new file mode 100644
index 00000000..c0ada4d7
--- /dev/null
+++ b/apps/web/README.md
@@ -0,0 +1,157 @@
+# WeQ Web
+
+浏览器版 WeQ —— 同一套后端与界面，跑在 HTTP 上而不是 Electron 窗口里。
+
+适合：想在无桌面环境的机器上跑（NAS / 服务器 / WSL），或者想从另一台设备访问。
+
+> [!Warning]
+>
+> **这个服务能读取所在机器上 QQ 的全部本地聊天记录。**
+> 默认只监听 `127.0.0.1`。要对外暴露，请先读完[远程访问](#远程访问)一节。
+
+---
+
+## 快速开始
+
+需要 **Node.js ≥ 22**（不内置）。
+
+从 [Releases](../../releases) 下载 `weq-web-<版本>.tar.gz`，解压后：
+
+```bash
+npm install --omit=dev    # 装 3 个依赖，约 10 秒
+node server.mjs
+```
+
+终端会打印地址和访问令牌：
+
+```
+  WeQ Web  →  http://127.0.0.1:7690
+  访问令牌  →  3f9a2b...            (设置 WEQ_TOKEN 可固定)
+  导出目录  →  ./weq-exports
+```
+
+浏览器打开该地址，粘贴令牌即可进入。之后的流程和桌面版一致：取密钥 → 打开账号 → 看消息。
+
+一个压缩包同时支持 **Windows x64 / Linux x64 / Linux arm64**，启动时按当前平台
+自动选择 `native/` 下对应的原生模块。
+
+---
+
+## 配置
+
+全部通过环境变量：
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `WEQ_TOKEN` | 随机生成并打印 | 访问令牌。对外暴露时**必须**显式设置 |
+| `WEQ_HOST` | `127.0.0.1` | 监听地址。设为 `0.0.0.0` 才对外可见 |
+| `WEQ_PORT` | `7690` | 端口。被占用时自动向后探测 10 个 |
+| `WEQ_EXPORT_DIR` | `./weq-exports` | 导出文件落盘目录 |
+| `WEQ_DATA_DIR` | `./weq-data` | 日志目录 |
+| `WEQ_NATIVE_DIR` | 随包的 `native/` | 原生模块目录（一般不用管） |
+
+固定令牌的例子：
+
+```bash
+WEQ_TOKEN=$(openssl rand -hex 24) node server.mjs
+```
+
+---
+
+## 远程访问
+
+绑定到非本机地址时，**必须显式设置 `WEQ_TOKEN`**，否则服务拒绝启动 ——
+自动生成的令牌只出现在一行没人会看的日志里，那等于没有门。
+
+```bash
+WEQ_TOKEN=$(openssl rand -hex 24) WEQ_HOST=0.0.0.0 node server.mjs
+```
+
+暴露前请确认：
+
+- **放在 HTTPS 反向代理之后。** 明文 HTTP 下令牌和聊天记录全程裸奔。
+- **令牌要足够长。** 服务端做了每 IP 指数退避，但短令牌仍然扛不住。
+- **考虑限制来源 IP。** 这个服务没有多用户概念 —— 拿到令牌就等于拿到全部数据。
+
+已经做了的防护：除登录页和登录接口外一律拒绝；令牌比对用常量时间算法（防时序侧信道）；
+会话 cookie 为 `HttpOnly` + `SameSite=Strict`，非本机时加 `Secure`；WebSocket 握手同样校验。
+
+---
+
+## 与桌面版的差异
+
+需要原生外壳的功能在网页版不提供，对应入口已隐藏：
+
+| 功能 | 网页版 |
+| --- | --- |
+| 窗口最小化 / 最大化 / 关闭、托盘 | 无（浏览器自己管窗口） |
+| 在文件管理器中定位 / 打开文件 | 无 |
+| 应用锁（Windows Hello 等系统认证） | 无（改由访问令牌把关） |
+| 应用内自动更新 | 无（重新下载压缩包即可） |
+| 截图当前窗口 | 无 |
+| 语音转文字 | 未随包提供 |
+| 选择文件 / 文件夹的系统对话框 | 无。导出统一落到 `WEQ_EXPORT_DIR` |
+| QQ 空间 / QQ 频道 | 不内嵌，改为在浏览器新标签页打开（见下） |
+
+**QQ 空间 / QQ 频道。** 桌面版把这两个站点嵌在 `<webview>` 里并手工种登录 cookie；
+浏览器里两条路都走不通——`user.qzone.qq.com` 与 `pd.qq.com` 都发 `X-Frame-Options`，
+iframe 会被拒，跨站 cookie 也不是网页能替浏览器写的。所以网页版改成：点击时向后端现取
+一条 ptlogin2 跳转 URL（带一次性 clientKey），交给浏览器开新标签。302 链在浏览器里跑完，
+登录 cookie 落进浏览器自己的 jar，之后再访问都是登录态。QQ 未在线时退回裸地址，
+在新标签里自己登录一次即可。
+
+其余功能——聊天记录浏览、媒体、导出、分析、克隆、收藏——与桌面版共用同一套后端代码，
+行为一致。
+
+---
+
+## 从源码构建
+
+```bash
+pnpm i
+pnpm --filter @weq/web build     # 产物在 apps/web/dist/
+```
+
+开发模式（前端热更新 + 单独跑服务端）：
+
+```bash
+pnpm --filter @weq/web dev       # 前端 dev server
+pnpm --filter @weq/web start     # 需先 build 过一次
+```
+
+### 验证
+
+```bash
+pnpm --filter @weq/web test        # 鉴权 + 端到端闸测试
+pnpm --filter @weq/web check       # 确认没有 Electron 代码泄漏进 web 构建
+pnpm --filter @weq/web test:dist   # 启动打包产物跑一遍完整流程
+```
+
+`check` 有两个守卫，都是为了防同一类回归 —— Electron-only 的代码悄悄混进 web 构建后，
+不会报错，只会在运行时炸成一句看不懂的 `does not provide an export named 'app'`：
+
+- `check-electron-free`：走真实 import 图，确认 web 复用的桌面模块没有一条链指向 `electron`
+- `check-bundle`：扫前端产物，确认 `weq-media://` 之类的自定义协议 URL 全部换成了 HTTP 路由
+
+### 架构
+
+网页版**不复制**桌面版的代码，而是复用：
+
+- `packages/*`（8 个包）—— 零改动，本来就不依赖 Electron
+- `apps/desktop/src/main` 的服务装配、tRPC router（259 个 procedure）、三个协议 handler
+- `apps/desktop/src/renderer` 的全部界面
+
+只有两处按构建目标分流：
+
+- **传输层** —— `@transport` 别名：桌面版走 `ipcLink`（IPC），网页版走 `httpBatchLink` + `wsLink`
+- **外壳能力** —— `HostBridge` 接口：桌面版注入原生对话框，网页版注入服务端目录 + HTTP 下载
+
+自定义协议在网页版挂成 HTTP 路由，handler 函数本身两端共用：
+
+| 桌面版 | 网页版 |
+| --- | --- |
+| `weq-media://pic?t=…` | `GET /_media/pic?t=…` |
+| `weq-avatar://fetch?src=…` | `GET /_avatar/fetch?src=…` |
+| `weq-asset://brand/logo.png` | `GET /_asset/brand/logo.png` |
+
+详细的实施记录见 [docs/web-app-plan.md](../../docs/web-app-plan.md)。
diff --git a/apps/web/package.json b/apps/web/package.json
new file mode 100644
index 00000000..8d556f6d
--- /dev/null
+++ b/apps/web/package.json
@@ -0,0 +1,43 @@
+{
+  "name": "@weq/web",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build && node scripts/build-server.mjs && pnpm check",
+    "pack:release": "node scripts/pack-release.mjs",
+    "check": "tsx scripts/check-electron-free.ts && tsx scripts/check-bundle.ts",
+    "start": "node dist/server.mjs",
+    "test": "tsx src/server/auth.test.ts && tsx src/server/http.test.ts",
+    "test:dist": "tsx scripts/smoke-dist.ts",
+    "typecheck": "tsc --noEmit -p tsconfig.server.json"
+  },
+  "dependencies": {
+    "@trpc/client": "^10.45.4",
+    "@trpc/react-query": "^10.45.4",
+    "@trpc/server": "^10.45.4",
+    "@weq/account": "workspace:*",
+    "@weq/agentlab": "workspace:*",
+    "@weq/codec": "workspace:*",
+    "@weq/db": "workspace:*",
+    "@weq/desktop": "workspace:*",
+    "@weq/native": "workspace:*",
+    "@weq/platform": "workspace:*",
+    "@weq/service": "workspace:*",
+    "superjson": "^2.2.2",
+    "ws": "^8.18.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.0.0",
+    "@types/node": "^22.10.6",
+    "@types/ws": "^8.5.13",
+    "@vitejs/plugin-react": "^4.3.4",
+    "esbuild": "^0.28.1",
+    "tailwindcss": "^4.0.0",
+    "tsx": "^4.22.4",
+    "typescript": "^5.7.3",
+    "vite": "^6.0.0"
+  }
+}
diff --git a/apps/web/scripts/build-server.mjs b/apps/web/scripts/build-server.mjs
new file mode 100644
index 00000000..f261cdd4
--- /dev/null
+++ b/apps/web/scripts/build-server.mjs
@@ -0,0 +1,124 @@
+/**
+ * Bundle the server into a single `dist/server.mjs`.
+ *
+ * Universal by design: `native/` ships all platform/arch subtrees and
+ * `@weq/native`'s loader picks `native/<process.platform>/<process.arch>` at
+ * runtime, so one archive runs on win32-x64, linux-x64 and linux-arm64.
+ *
+ * `.node` addons stay external — esbuild can't inline them, and they don't need
+ * rebuilding anyway (both are N-API, so the same binary loads under plain Node
+ * and under Electron).
+ */
+
+import { build } from 'esbuild';
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const appRoot = resolve(here, '..');
+const repoRoot = resolve(appRoot, '../..');
+const dist = join(appRoot, 'dist');
+
+const NATIVE_SRC = join(repoRoot, 'native');
+const RESOURCES_SRC = join(repoRoot, 'resources');
+
+// `scripts/set-version.mjs` stamps this from the release tag; baked in so the
+// running server can report its own version without reading package.json.
+const { version } = JSON.parse(readFileSync(join(appRoot, 'package.json'), 'utf8'));
+
+/**
+ * Packages that load native `.node` bindings. esbuild can't inline those, so
+ * they stay external and ship as real `node_modules` alongside the bundle.
+ */
+const NATIVE_DEPS = {
+  ws: '^8.18.0',
+  '@resvg/resvg-js': '^2.6.2',
+};
+
+await build({
+  entryPoints: [join(appRoot, 'src/server/index.ts')],
+  outfile: join(dist, 'server.mjs'),
+  bundle: true,
+  platform: 'node',
+  target: 'node22',
+  format: 'esm',
+  external: [...Object.keys(NATIVE_DEPS), '*.node'],
+  banner: {
+    // Bundled CJS deps reach for CJS globals that don't exist in an ESM bundle.
+    //   - `require`: esbuild's dynamic-require stub checks `typeof require` and
+    //     defers to it when defined, so defining it here turns "Dynamic require
+    //     of crypto is not supported" (exceljs) into a working call.
+    //   - `__filename`/`__dirname`: provided under mangled names + `define`d,
+    //     because bundled chunks already declare their own `__dirname` and a
+    //     direct declaration would collide.
+    js: [
+      "import { createRequire as __weqCreateRequire } from 'node:module';",
+      "import { fileURLToPath as __weqFromFileUrl } from 'node:url';",
+      "import { dirname as __weqDirname } from 'node:path';",
+      'const require = __weqCreateRequire(import.meta.url);',
+      'const __weqFilename = __weqFromFileUrl(import.meta.url);',
+      'const __weqDirnameValue = __weqDirname(__weqFilename);',
+    ].join('\n'),
+  },
+  define: {
+    __filename: '__weqFilename',
+    __dirname: '__weqDirnameValue',
+    __WEQ_VERSION__: JSON.stringify(version),
+  },
+  logLevel: 'info',
+});
+
+// native/ — every platform, so one archive covers them all.
+if (!existsSync(NATIVE_SRC)) {
+  console.error(`\nnative/ not found at ${NATIVE_SRC} — the build would not run.`);
+  process.exit(1);
+}
+rmSync(join(dist, 'native'), { recursive: true, force: true });
+cpSync(NATIVE_SRC, join(dist, 'native'), { recursive: true });
+
+// resources/ — brand assets etc. read at runtime.
+if (existsSync(RESOURCES_SRC)) {
+  rmSync(join(dist, 'resources'), { recursive: true, force: true });
+  cpSync(RESOURCES_SRC, join(dist, 'resources'), { recursive: true });
+}
+
+// A manifest so `node server.mjs` resolves `ws` without a full install.
+mkdirSync(dist, { recursive: true });
+writeFileSync(
+  join(dist, 'package.json'),
+  `${JSON.stringify({ name: 'weq-web', private: true, type: 'module', dependencies: NATIVE_DEPS }, null, 2)}\n`,
+);
+
+writeFileSync(
+  join(dist, 'README.txt'),
+  [
+    'WeQ Web — 浏览器版',
+    '',
+    '需要 Node.js 22 或更高版本（不内置）。',
+    '',
+    '启动：',
+    '  npm install --omit=dev     # 装 3 个依赖',
+    '  node server.mjs',
+    '',
+    '然后浏览器打开终端里打印的地址，用同时打印的访问令牌登录。',
+    '',
+    '环境变量：',
+    '  WEQ_TOKEN       访问令牌。绑定到非本机地址时必须显式设置。',
+    '  WEQ_HOST        监听地址，默认 127.0.0.1。设为 0.0.0.0 才对外可见。',
+    '  WEQ_PORT        端口，默认 7690；被占用时自动向后探测。',
+    '  WEQ_EXPORT_DIR  导出目录，默认 ./weq-exports',
+    '  WEQ_DATA_DIR    日志目录，默认 ./weq-data',
+    '',
+    '⚠ 对外暴露前请务必放在 HTTPS 反向代理之后，并设置一个足够长的 WEQ_TOKEN。',
+    '   这个服务能读取该机器上 QQ 的全部本地聊天记录。',
+    '',
+    'native/ 同时包含 win32-x64 / linux-x64 / linux-arm64 三份原生模块，',
+    '运行时按当前平台自动选择，因此同一个压缩包三平台通用。',
+    '',
+    '完整说明： https://github.com/H3CoF6/WeQ/blob/main/apps/web/README.md',
+  ].join('\n'),
+);
+
+console.log(`\n  built → ${dist}`);
+console.log('  contents: server.mjs + public/ + native/ + resources/\n');
diff --git a/apps/web/scripts/check-bundle.ts b/apps/web/scripts/check-bundle.ts
new file mode 100644
index 00000000..0ba3193f
--- /dev/null
+++ b/apps/web/scripts/check-bundle.ts
@@ -0,0 +1,59 @@
+/**
+ * Guard: the browser bundle must contain no Electron-only artifacts.
+ *
+ * A stray `weq-media://` URL doesn't fail the build — it fails silently at
+ * runtime as a broken image, which is easy to miss and tedious to trace. This
+ * greps the built assets for anything that only works inside Electron.
+ *
+ * (Written after a hand-audit missed a second `weq-avatar://` builder that had
+ * been duplicated across two files.)
+ *
+ * Run after `vite build`: npx tsx apps/web/scripts/check-bundle.ts
+ */
+
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const DIST = resolve(here, '../dist/public/assets');
+
+/** Substrings that must never appear in a browser bundle. */
+const FORBIDDEN = [
+  { needle: 'weq-media://', why: 'custom scheme — should be /_media/' },
+  { needle: 'weq-avatar://', why: 'custom scheme — should be /_avatar/' },
+  { needle: 'weq-asset://', why: 'custom scheme — should be /_asset/' },
+  { needle: 'electron-trpc', why: 'Electron IPC transport' },
+  { needle: 'require("electron")', why: 'Electron require' },
+];
+
+if (!existsSync(DIST)) {
+  console.error(`FAIL  no build found at ${DIST} — run \`pnpm --filter @weq/web build\` first`);
+  process.exit(1);
+}
+
+const files = readdirSync(DIST).filter((f) => f.endsWith('.js'));
+if (files.length === 0) {
+  console.error('FAIL  build produced no JS assets');
+  process.exit(1);
+}
+
+let bad = 0;
+for (const file of files) {
+  const source = readFileSync(join(DIST, file), 'utf8');
+  for (const { needle, why } of FORBIDDEN) {
+    if (!source.includes(needle)) continue;
+    bad++;
+    // Show a little context so the offending call site is findable.
+    const at = source.indexOf(needle);
+    const snippet = source.slice(Math.max(0, at - 70), at + needle.length + 30);
+    console.error(`FAIL  ${file}: found "${needle}" (${why})\n      …${snippet}…\n`);
+  }
+}
+
+if (bad > 0) {
+  console.error(`${bad} Electron-only artifact(s) leaked into the web bundle.`);
+  process.exit(1);
+}
+
+console.log(`PASS  ${files.length} bundle assets are free of Electron-only artifacts`);
diff --git a/apps/web/scripts/check-electron-free.ts b/apps/web/scripts/check-electron-free.ts
new file mode 100644
index 00000000..8fe15ab4
--- /dev/null
+++ b/apps/web/scripts/check-electron-free.ts
@@ -0,0 +1,98 @@
+/**
+ * Guard: the modules the web app reuses from `apps/desktop/src/main` must not
+ * pull in `electron`, transitively or otherwise.
+ *
+ * This broke twice while building the web app — first via
+ * `app_context → qq_protocol`, then via the protocol handlers sharing a file
+ * with their `protocol.handle` registration. Both were only caught at runtime,
+ * as an opaque "does not provide an export named 'app'". This walks the real
+ * import graph so the next regression fails loudly at build time instead.
+ *
+ * Run: npx tsx apps/web/scripts/check-electron-free.ts
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(here, '../../..');
+const DESKTOP_MAIN = join(REPO_ROOT, 'apps/desktop/src/main');
+
+/** The entry points `apps/web/src/server` imports from the desktop app. */
+const ENTRIES = [
+  'context/app_context.ts',
+  'ipc/router.ts',
+  'media_protocol.ts',
+  'avatar_protocol.ts',
+  'resource_protocol.ts',
+  'file_response.ts',
+];
+
+const IMPORT_RE = /(?:^|\n)\s*(?:import|export)[\s\S]*?from\s*['"]([^'"]+)['"]/g;
+const DYNAMIC_RE = /\bimport\(\s*['"]([^'"]+)['"]\s*\)/g;
+
+function specifiersOf(source: string): string[] {
+  const out: string[] = [];
+  for (const re of [IMPORT_RE, DYNAMIC_RE]) {
+    re.lastIndex = 0;
+    let m: RegExpExecArray | null = re.exec(source);
+    while (m !== null) {
+      if (m[1]) out.push(m[1]);
+      m = re.exec(source);
+    }
+  }
+  return out;
+}
+
+/** Resolve a relative specifier to a real .ts file, or null for packages. */
+function resolveLocal(fromFile: string, spec: string): string | null {
+  if (!spec.startsWith('.')) return null;
+  const base = join(dirname(fromFile), spec);
+  for (const candidate of [base, `${base}.ts`, join(base, 'index.ts')]) {
+    if (existsSync(candidate) && candidate.endsWith('.ts')) return candidate;
+  }
+  return null;
+}
+
+const seen = new Set<string>();
+const offenders: Array<{ file: string; via: string[] }> = [];
+
+function walk(file: string, trail: string[]): void {
+  if (seen.has(file)) return;
+  seen.add(file);
+
+  const source = readFileSync(file, 'utf8');
+  const specs = specifiersOf(source);
+
+  if (specs.includes('electron')) {
+    offenders.push({ file, via: [...trail, file] });
+  }
+
+  for (const spec of specs) {
+    const next = resolveLocal(file, spec);
+    if (next) walk(next, [...trail, file]);
+  }
+}
+
+const rel = (p: string): string => p.slice(REPO_ROOT.length + 1).replace(/\\/g, '/');
+
+for (const entry of ENTRIES) {
+  const path = join(DESKTOP_MAIN, entry);
+  if (!existsSync(path)) {
+    console.error(`FAIL  entry not found: ${entry}`);
+    process.exit(1);
+  }
+  walk(path, []);
+}
+
+if (offenders.length > 0) {
+  console.error(`\nFAIL  ${offenders.length} module(s) reachable from the web app import 'electron':\n`);
+  for (const { via } of offenders) {
+    console.error(`  ${via.map(rel).join('\n    → ')}\n`);
+  }
+  console.error('Split the Electron-only part into its own module (see protocol_register.ts).\n');
+  process.exit(1);
+}
+
+console.log(`PASS  ${seen.size} modules reachable from apps/web are electron-free`);
diff --git a/apps/web/scripts/pack-release.mjs b/apps/web/scripts/pack-release.mjs
new file mode 100644
index 00000000..235a176a
--- /dev/null
+++ b/apps/web/scripts/pack-release.mjs
@@ -0,0 +1,67 @@
+/**
+ * Pack `dist/` into the release tarball.
+ *
+ * Separate from `build-server.mjs` so a normal `pnpm build` doesn't pay the
+ * compression cost — only the release workflow calls this.
+ *
+ * One archive covers every platform: `native/` ships all three platform/arch
+ * subtrees and the loader picks the right one at runtime.
+ *
+ *   node scripts/pack-release.mjs [version]
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, openSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const appRoot = resolve(here, '..');
+const dist = join(appRoot, 'dist');
+const outDir = join(appRoot, 'release');
+
+const version =
+  process.argv[2]?.replace(/^v/, '') ??
+  JSON.parse(readFileSync(join(appRoot, 'package.json'), 'utf8')).version;
+
+for (const entry of ['server.mjs', 'public', 'native', 'resources', 'package.json']) {
+  if (existsSync(join(dist, entry))) continue;
+  console.error(`dist/${entry} missing — run \`pnpm build\` first`);
+  process.exit(1);
+}
+
+mkdirSync(outDir, { recursive: true });
+const name = `weq-web-${version}.tar.gz`;
+const archive = join(outDir, name);
+
+// Notes on the argv shape:
+//   -C dist .        unpacks into the current directory, not a nested dist/
+//   --exclude first  GNU tar exits 128 if an --exclude trails the path operand
+//   -czf -           write to stdout, redirected to the archive by the caller.
+//                    Passing a Windows `C:\…` path directly makes GNU tar read
+//                    it as rsh host:path syntax and fail.
+const fd = openSync(archive, 'w');
+const res = spawnSync(
+  'tar',
+  [
+    // Skip anything a local run may have left in dist/.
+    '--exclude=./node_modules',
+    '--exclude=./weq-exports',
+    '--exclude=./weq-data',
+    '--exclude=./package-lock.json',
+    '-czf',
+    '-',
+    '-C',
+    dist,
+    '.',
+  ],
+  { stdio: ['ignore', fd, 'inherit'] },
+);
+
+if (res.status !== 0) {
+  console.error(`tar exited with ${res.status}`);
+  process.exit(1);
+}
+
+const mb = (statSync(archive).size / 1024 / 1024).toFixed(1);
+console.log(`\n  packed → ${archive}  (${mb} MB)\n`);
diff --git a/apps/web/scripts/smoke-dist.ts b/apps/web/scripts/smoke-dist.ts
new file mode 100644
index 00000000..38c199c9
--- /dev/null
+++ b/apps/web/scripts/smoke-dist.ts
@@ -0,0 +1,140 @@
+/**
+ * Smoke-test the packaged server: boot `dist/server.mjs` exactly as a user
+ * would and walk the auth flow end to end.
+ *
+ * This covers what unit tests can't — that the esbuild bundle actually starts
+ * under plain Node (CJS interop, native module resolution, `native/` layout),
+ * which broke three separate times while building the packaging step.
+ *
+ * Requires `pnpm build` first. Run: npx tsx apps/web/scripts/smoke-dist.ts
+ */
+
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const dist = resolve(here, '../dist');
+
+const TOKEN = 'smoke-dist-token';
+const PORT = 39955;
+
+let failed = 0;
+function check(ok: boolean, label: string): void {
+  if (!ok) failed++;
+  console.log(`${ok ? 'PASS' : 'FAIL'}  ${label}`);
+}
+
+for (const entry of ['server.mjs', 'public/index.html', 'native', 'resources']) {
+  if (existsSync(join(dist, entry))) continue;
+  console.error(`FAIL  dist/${entry} missing — run \`pnpm build\` first`);
+  process.exit(1);
+}
+
+// One archive must carry every platform's native bundle.
+for (const platform of ['win32/x64', 'linux/x64', 'linux/arm64']) {
+  check(existsSync(join(dist, 'native', platform)), `native/${platform} shipped (universal)`);
+}
+
+// The bundle keeps native-loading packages external, so a release needs the
+// same `npm install` the README tells users to run. Do it here, both to test
+// that instruction and because the server won't start without it.
+if (!existsSync(join(dist, 'node_modules'))) {
+  console.log('installing runtime deps into dist/ (as the README instructs)…');
+  const install = spawnSync('npm', ['install', '--omit=dev', '--no-audit', '--no-fund'], {
+    cwd: dist,
+    stdio: 'inherit',
+    shell: true,
+  });
+  if (install.status !== 0) {
+    console.error('FAIL  npm install in dist/ failed');
+    process.exit(1);
+  }
+}
+
+const server = spawn(process.execPath, [join(dist, 'server.mjs')], {
+  cwd: dist,
+  env: { ...process.env, WEQ_TOKEN: TOKEN, WEQ_PORT: String(PORT) },
+  stdio: ['ignore', 'pipe', 'pipe'],
+});
+
+let stderr = '';
+server.stderr.on('data', (c: Buffer) => {
+  stderr += c.toString();
+});
+
+const base = `http://127.0.0.1:${PORT}`;
+
+async function waitForServer(): Promise<boolean> {
+  for (let i = 0; i < 40; i++) {
+    if (server.exitCode !== null) return false;
+    try {
+      await fetch(base, { headers: { accept: 'text/html' } });
+      return true;
+    } catch {
+      await new Promise((r) => setTimeout(r, 500));
+    }
+  }
+  return false;
+}
+
+try {
+  const up = await waitForServer();
+  check(up, 'packaged server boots under plain Node');
+  if (!up) {
+    console.error(`\nserver output:\n${stderr}`);
+    process.exit(1);
+  }
+
+  // Pre-auth: closed, but a browser navigation gets the login form.
+  const guarded = await fetch(`${base}/trpc/bootstrap.getVersionInfo`);
+  check(guarded.status === 401, 'pre-auth tRPC → 401');
+
+  const loginHtml = await (await fetch(base, { headers: { accept: 'text/html' } })).text();
+  check(loginHtml.includes('访问令牌'), 'pre-auth navigation → login page');
+  check(!loginHtml.includes('/assets/'), 'login page ships no app bundle');
+
+  check(
+    (
+      await fetch(`${base}/_auth/login`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ token: 'wrong' }),
+      })
+    ).status === 401,
+    'wrong token → 401',
+  );
+
+  const login = await fetch(`${base}/_auth/login`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ token: TOKEN }),
+  });
+  check(login.status === 200, 'correct token → 200');
+  const cookie = (login.headers.get('set-cookie') ?? '').split(';')[0] ?? '';
+
+  // Post-auth: a real procedure round-trips, and the SPA + assets are served.
+  const version = await (
+    await fetch(`${base}/trpc/bootstrap.getVersionInfo`, { headers: { cookie } })
+  ).json();
+  check(
+    typeof version?.result?.data?.json?.node === 'string',
+    'post-auth tRPC procedure returns data',
+  );
+
+  const shell = await (await fetch(base, { headers: { accept: 'text/html', cookie } })).text();
+  check(shell.includes('/assets/'), 'post-auth → SPA shell');
+
+  const asset = await fetch(`${base}/_asset/brand/logo.png`, { headers: { cookie } });
+  check(
+    asset.status === 200 && (asset.headers.get('content-type') ?? '').startsWith('image/'),
+    'weq-asset:// handler serves over /_asset/',
+  );
+
+  console.log(failed === 0 ? '\nALL PASS' : `\n${failed} FAILED`);
+} finally {
+  server.kill();
+}
+
+process.exit(failed === 0 ? 0 : 1);
diff --git a/apps/web/src/server/auth.test.ts b/apps/web/src/server/auth.test.ts
new file mode 100644
index 00000000..52168647
--- /dev/null
+++ b/apps/web/src/server/auth.test.ts
@@ -0,0 +1,136 @@
+/**
+ * Auth gate tests — run with `npx tsx apps/web/src/server/auth.test.ts`.
+ *
+ * This is the one component where a bug means "anyone on the network can read
+ * the user's entire QQ history", so the behaviour is pinned down explicitly.
+ */
+
+import { AuthGate } from './auth';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+let failed = 0;
+function check(ok: boolean, label: string): void {
+  if (!ok) failed++;
+  console.log(`${ok ? 'PASS' : 'FAIL'}  ${label}`);
+}
+
+/** Minimal ServerResponse stand-in that records Set-Cookie. */
+function fakeRes(): ServerResponse & { cookie: string | null } {
+  const headers: Record<string, string> = {};
+  return {
+    setHeader(k: string, v: string) {
+      headers[k.toLowerCase()] = v;
+    },
+    get cookie() {
+      return headers['set-cookie'] ?? null;
+    },
+  } as unknown as ServerResponse & { cookie: string | null };
+}
+
+function fakeReq(cookie?: string, ip = '1.2.3.4'): IncomingMessage {
+  return {
+    headers: cookie ? { cookie } : {},
+    socket: { remoteAddress: ip },
+  } as unknown as IncomingMessage;
+}
+
+/** Pull `weq_session=...` out of a Set-Cookie header into a Cookie header. */
+function cookieHeader(setCookie: string | null): string {
+  return (setCookie ?? '').split(';')[0] ?? '';
+}
+
+async function main(): Promise<void> {
+  // ---- happy path ----
+  {
+    const gate = new AuthGate({ token: 'correct-horse', remote: false });
+    const res = fakeRes();
+    const ok = await gate.login('correct-horse', '1.1.1.1', res);
+    check(ok, 'correct token → login succeeds');
+    check(res.cookie !== null, 'login sets a cookie');
+    check(res.cookie!.includes('HttpOnly'), 'cookie is HttpOnly');
+    check(res.cookie!.includes('SameSite=Strict'), 'cookie is SameSite=Strict');
+    check(!res.cookie!.includes('Secure'), 'loopback → no Secure flag');
+    check(gate.isAuthed(fakeReq(cookieHeader(res.cookie))), 'session cookie authenticates');
+  }
+
+  // ---- rejection ----
+  {
+    const gate = new AuthGate({ token: 'correct-horse', remote: false });
+    const res = fakeRes();
+    check(!(await gate.login('wrong', '2.2.2.2', res)), 'wrong token → rejected');
+    check(res.cookie === null, 'failed login sets no cookie');
+    check(!gate.isAuthed(fakeReq()), 'no cookie → not authed');
+    check(!gate.isAuthed(fakeReq('weq_session=forged')), 'forged session id → not authed');
+    check(
+      !(await gate.login('correct-horse-longer', '2.2.2.2', fakeRes())),
+      'longer token with correct prefix → rejected',
+    );
+    check(!(await gate.login('', '2.2.2.2', fakeRes())), 'empty token → rejected');
+  }
+
+  // ---- remote hardening ----
+  {
+    const gate = new AuthGate({ token: 'tok', remote: true });
+    const res = fakeRes();
+    await gate.login('tok', '3.3.3.3', res);
+    check(res.cookie!.includes('Secure'), 'remote bind → Secure flag set');
+  }
+
+  // ---- backoff ----
+  {
+    const gate = new AuthGate({ token: 'tok', remote: false });
+    const peer = '4.4.4.4';
+    // First failure is immediate; subsequent ones must stall progressively.
+    await gate.login('nope', peer, fakeRes());
+    const t0 = Date.now();
+    await gate.login('nope', peer, fakeRes());
+    const firstDelay = Date.now() - t0;
+    const t1 = Date.now();
+    await gate.login('nope', peer, fakeRes());
+    const secondDelay = Date.now() - t1;
+    check(firstDelay >= 200, `2nd failure stalls (${firstDelay}ms)`);
+    check(secondDelay > firstDelay, `3rd failure stalls longer (${secondDelay}ms)`);
+
+    // A different peer is unaffected by this one's failures.
+    const t2 = Date.now();
+    await gate.login('nope', '5.5.5.5', fakeRes());
+    check(Date.now() - t2 < 100, 'backoff is per-peer, not global');
+
+    // Correct token still works (after paying the accrued backoff) and resets.
+    const res = fakeRes();
+    check(await gate.login('tok', peer, res), 'correct token still accepted after failures');
+    const t3 = Date.now();
+    await gate.login('nope', peer, fakeRes());
+    check(Date.now() - t3 < 100, 'successful login clears the backoff');
+  }
+
+  // ---- logout ----
+  {
+    const gate = new AuthGate({ token: 'tok', remote: false });
+    const res = fakeRes();
+    await gate.login('tok', '6.6.6.6', res);
+    const cookie = cookieHeader(res.cookie);
+    check(gate.isAuthed(fakeReq(cookie)), 'authed before logout');
+    const out = fakeRes();
+    gate.logout(fakeReq(cookie), out);
+    check(!gate.isAuthed(fakeReq(cookie)), 'session dead after logout');
+    check(out.cookie!.includes('Max-Age=0'), 'logout clears the cookie');
+  }
+
+  // ---- session isolation ----
+  {
+    const gate = new AuthGate({ token: 'tok', remote: false });
+    const a = fakeRes();
+    const b = fakeRes();
+    await gate.login('tok', '7.7.7.7', a);
+    await gate.login('tok', '8.8.8.8', b);
+    check(cookieHeader(a.cookie) !== cookieHeader(b.cookie), 'each login gets a distinct session');
+    gate.logout(fakeReq(cookieHeader(a.cookie)), fakeRes());
+    check(gate.isAuthed(fakeReq(cookieHeader(b.cookie))), "one logout doesn't kill other sessions");
+  }
+
+  console.log(failed === 0 ? '\nALL PASS' : `\n${failed} FAILED`);
+  process.exit(failed === 0 ? 0 : 1);
+}
+
+void main();
diff --git a/apps/web/src/server/auth.ts b/apps/web/src/server/auth.ts
new file mode 100644
index 00000000..4dcd6582
--- /dev/null
+++ b/apps/web/src/server/auth.ts
@@ -0,0 +1,155 @@
+/**
+ * Auth gate for the web app.
+ *
+ * Unlike the desktop shell, a browser-served WeQ can be reached by anything
+ * that can open a TCP connection to it — and behind that gate sits the user's
+ * entire QQ history. So the rule here is **deny by default**: every route
+ * except the login page and the login endpoint requires a session cookie.
+ *
+ * Threat model / decisions:
+ *   - Token compare is `timingSafeEqual` (constant-time) so an attacker can't
+ *     walk the token out one byte at a time from response latency.
+ *   - Failed attempts back off exponentially per-IP, so the token can't be
+ *     brute-forced at line rate.
+ *   - Binding to anything other than loopback REQUIRES an explicitly-set
+ *     `WEQ_TOKEN`. Auto-generating one and printing it to a log nobody reads
+ *     is how "I just wanted to try it on my LAN" turns into an open door.
+ *   - Sessions live in memory only: a restart logs everyone out. That's a
+ *     feature, not a gap — there's no session store to steal.
+ */
+
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+const SESSION_COOKIE = 'weq_session';
+/** Sessions expire after this long without use. */
+const SESSION_TTL_MS = 12 * 60 * 60 * 1000;
+/** Failed-attempt backoff: delay = BASE * 2^(fails-1), capped. */
+const BACKOFF_BASE_MS = 250;
+const BACKOFF_MAX_MS = 30_000;
+/** Drop a peer's failure record after this long with no attempts. */
+const FAIL_RESET_MS = 60 * 60 * 1000;
+
+export interface AuthConfig {
+  /** The shared secret a client must present to log in. */
+  token: string;
+  /** True when the server binds beyond loopback (enables Secure cookie). */
+  remote: boolean;
+}
+
+interface Session {
+  expiresAt: number;
+}
+
+interface FailRecord {
+  count: number;
+  lastAt: number;
+}
+
+export class AuthGate {
+  private readonly tokenBuf: Buffer;
+  private readonly remote: boolean;
+  private readonly sessions = new Map<string, Session>();
+  private readonly fails = new Map<string, FailRecord>();
+
+  constructor(config: AuthConfig) {
+    this.tokenBuf = Buffer.from(config.token, 'utf8');
+    this.remote = config.remote;
+  }
+
+  /**
+   * Constant-time token check. Length is compared separately because
+   * `timingSafeEqual` throws on a length mismatch — but length alone is a
+   * negligible leak next to byte-by-byte content timing.
+   */
+  private tokenMatches(candidate: string): boolean {
+    const buf = Buffer.from(candidate, 'utf8');
+    if (buf.length !== this.tokenBuf.length) return false;
+    return timingSafeEqual(buf, this.tokenBuf);
+  }
+
+  /** Milliseconds to stall before answering a login from `peer`. */
+  private backoffFor(peer: string): number {
+    const rec = this.fails.get(peer);
+    if (!rec) return 0;
+    if (Date.now() - rec.lastAt > FAIL_RESET_MS) {
+      this.fails.delete(peer);
+      return 0;
+    }
+    return Math.min(BACKOFF_BASE_MS * 2 ** (rec.count - 1), BACKOFF_MAX_MS);
+  }
+
+  private noteFailure(peer: string): void {
+    const rec = this.fails.get(peer);
+    this.fails.set(peer, { count: (rec?.count ?? 0) + 1, lastAt: Date.now() });
+  }
+
+  /**
+   * Validate a login attempt. Resolves true and sets the session cookie on
+   * success. Always waits out the current backoff first, so a wrong token
+   * costs the caller real time.
+   */
+  async login(token: string, peer: string, res: ServerResponse): Promise<boolean> {
+    const delay = this.backoffFor(peer);
+    if (delay > 0) await new Promise((r) => setTimeout(r, delay));
+
+    if (!this.tokenMatches(token)) {
+      this.noteFailure(peer);
+      return false;
+    }
+
+    this.fails.delete(peer);
+    const sid = randomBytes(32).toString('base64url');
+    this.sessions.set(sid, { expiresAt: Date.now() + SESSION_TTL_MS });
+
+    const attrs = [
+      `${SESSION_COOKIE}=${sid}`,
+      'HttpOnly',
+      'SameSite=Strict',
+      'Path=/',
+      `Max-Age=${Math.floor(SESSION_TTL_MS / 1000)}`,
+    ];
+    // Secure would make the cookie unusable over plain http on loopback, which
+    // is the normal local case. Only set it when we're actually exposed.
+    if (this.remote) attrs.push('Secure');
+    res.setHeader('Set-Cookie', attrs.join('; '));
+    return true;
+  }
+
+  /** True when the request carries a live session cookie. Refreshes its TTL. */
+  isAuthed(req: IncomingMessage): boolean {
+    const sid = readCookie(req.headers.cookie, SESSION_COOKIE);
+    if (!sid) return false;
+    const session = this.sessions.get(sid);
+    if (!session) return false;
+    if (session.expiresAt < Date.now()) {
+      this.sessions.delete(sid);
+      return false;
+    }
+    session.expiresAt = Date.now() + SESSION_TTL_MS;
+    return true;
+  }
+
+  /** Drop the caller's session and clear the cookie. */
+  logout(req: IncomingMessage, res: ServerResponse): void {
+    const sid = readCookie(req.headers.cookie, SESSION_COOKIE);
+    if (sid) this.sessions.delete(sid);
+    res.setHeader('Set-Cookie', `${SESSION_COOKIE}=; HttpOnly; SameSite=Strict; Path=/; Max-Age=0`);
+  }
+}
+
+/** Read one cookie value out of a `Cookie:` header. */
+function readCookie(header: string | undefined, name: string): string | null {
+  if (!header) return null;
+  for (const part of header.split(';')) {
+    const eq = part.indexOf('=');
+    if (eq === -1) continue;
+    if (part.slice(0, eq).trim() === name) return part.slice(eq + 1).trim();
+  }
+  return null;
+}
+
+/** Stable per-peer key for backoff bookkeeping. */
+export function peerKey(req: IncomingMessage): string {
+  return req.socket.remoteAddress ?? 'unknown';
+}
diff --git a/apps/web/src/server/host.ts b/apps/web/src/server/host.ts
new file mode 100644
index 00000000..da8c85f5
--- /dev/null
+++ b/apps/web/src/server/host.ts
@@ -0,0 +1,75 @@
+/**
+ * Web implementation of {@link HostBridge}.
+ *
+ * A browser can't drive native file dialogs on the server, so the semantics
+ * shift: "pick a directory" becomes "use the server's configured export dir",
+ * and "save as" writes there and hands back a download id the client fetches
+ * over HTTP. Reveal-in-file-manager has no meaning at all — `canReveal` is
+ * false and the UI hides those buttons.
+ */
+
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import type { HostBridge, SaveTarget } from '@weq/service';
+
+export interface WebHostOptions {
+  /** Directory that receives exports/saves. Created if missing. */
+  exportDir: string;
+  version: string;
+}
+
+/** Pending downloads, keyed by the id handed to the client. */
+const downloads = new Map<string, { path: string; name: string }>();
+
+export function lookupDownload(id: string): { path: string; name: string } | undefined {
+  return downloads.get(id);
+}
+
+export function createWebHost({ exportDir, version }: WebHostOptions): HostBridge {
+  mkdirSync(exportDir, { recursive: true });
+
+  return {
+    canReveal: false,
+
+    async pickDirectory() {
+      // No dialog: everything lands in the server-side export dir.
+      return exportDir;
+    },
+
+    async pickFile() {
+      // The server's filesystem isn't the user's to browse. Callers treat null
+      // as "cancelled"; the UI hides these entry points on web anyway.
+      return null;
+    },
+
+    async pickSaveTarget({ defaultName }): Promise<SaveTarget> {
+      const id = randomUUID();
+      const path = join(exportDir, `${id}-${defaultName}`);
+      downloads.set(id, { path, name: defaultName });
+      return { path, downloadId: id };
+    },
+
+    async revealPath() {
+      // No-op — nothing to reveal on a headless host.
+    },
+
+    async revealInFolder() {
+      // No-op.
+    },
+
+    async openHtmlReport(path) {
+      const id = randomUUID();
+      downloads.set(id, { path, name: 'report.html' });
+      return { url: `/_download/${id}` };
+    },
+
+    async openBotConsole({ url }) {
+      // The bot console is its own HTTP server; let the browser open it.
+      return { url };
+    },
+
+    appVersion: () => version,
+    isPackaged: () => process.env.NODE_ENV === 'production',
+  };
+}
diff --git a/apps/web/src/server/http.test.ts b/apps/web/src/server/http.test.ts
new file mode 100644
index 00000000..a68d8b87
--- /dev/null
+++ b/apps/web/src/server/http.test.ts
@@ -0,0 +1,129 @@
+/**
+ * End-to-end gate test: start the real HTTP server and prove that every route
+ * is closed before login and open after. Unit-testing `AuthGate` isn't enough —
+ * a routing mistake in `http.ts` (a route checked before the gate, a typo'd
+ * prefix) would leave data exposed with the gate still passing its own tests.
+ *
+ * Run: npx tsx apps/web/src/server/http.test.ts
+ */
+
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { AuthGate } from './auth';
+import { startServer } from './http';
+
+let failed = 0;
+function check(ok: boolean, label: string): void {
+  if (!ok) failed++;
+  console.log(`${ok ? 'PASS' : 'FAIL'}  ${label}`);
+}
+
+const TOKEN = 'test-token-abc';
+
+async function main(): Promise<void> {
+  const pub = mkdtempSync(join(tmpdir(), 'weq-web-'));
+  writeFileSync(join(pub, 'index.html'), '<html>APP SHELL</html>');
+  writeFileSync(join(pub, 'robots.txt'), 'secret-ish');
+
+  let trpcHits = 0;
+  const { server, port } = await startServer({
+    port: 39871,
+    host: '127.0.0.1',
+    publicDir: pub,
+    auth: new AuthGate({ token: TOKEN, remote: false }),
+    trpc: (_req, res) => {
+      trpcHits++;
+      res.writeHead(200, { 'Content-Type': 'text/plain' });
+      res.end('trpc-reached');
+    },
+  });
+
+  const base = `http://127.0.0.1:${port}`;
+  const get = (path: string, cookie?: string, accept = '*/*'): Promise<Response> =>
+    fetch(base + path, {
+      headers: cookie ? { cookie, accept } : { accept },
+      redirect: 'manual',
+    });
+
+  // ---- everything is closed before login ----
+  const guarded = ['/trpc/bootstrap.getVersionInfo', '/_media/pic?t=1&name=x',
+    '/_avatar/fetch?src=http://x/', '/_asset/brand/logo.png', '/_download/anything',
+    '/robots.txt', '/some/spa/route'];
+  for (const path of guarded) {
+    const res = await get(path);
+    check(res.status === 401, `pre-auth ${path} → 401 (got ${res.status})`);
+  }
+  check(trpcHits === 0, 'tRPC handler never reached pre-auth');
+
+  // A browser navigation gets the login form rather than a bare 401.
+  {
+    const res = await get('/', undefined, 'text/html');
+    const body = await res.text();
+    check(res.status === 200 && body.includes('访问令牌'), 'pre-auth HTML nav → login page');
+    check(!body.includes('APP SHELL'), 'login page is not the app shell');
+  }
+
+  // ---- login ----
+  const bad = await fetch(`${base}/_auth/login`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ token: 'nope' }),
+  });
+  check(bad.status === 401, 'login with wrong token → 401');
+  check(bad.headers.get('set-cookie') === null, 'failed login sets no cookie');
+
+  const good = await fetch(`${base}/_auth/login`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ token: TOKEN }),
+  });
+  check(good.status === 200, 'login with correct token → 200');
+  const setCookie = good.headers.get('set-cookie') ?? '';
+  const cookie = setCookie.split(';')[0] ?? '';
+  check(cookie.startsWith('weq_session='), 'login returns a session cookie');
+
+  // ---- routes open after login ----
+  {
+    const res = await get('/trpc/anything', cookie);
+    check(res.status === 200 && (await res.text()) === 'trpc-reached', 'post-auth /trpc reaches router');
+    check(trpcHits === 1, 'tRPC handler invoked exactly once');
+  }
+  {
+    const res = await get('/robots.txt', cookie);
+    check(res.status === 200 && (await res.text()) === 'secret-ish', 'post-auth static file served');
+  }
+  {
+    const res = await get('/some/spa/route', cookie, 'text/html');
+    check((await res.text()).includes('APP SHELL'), 'post-auth unknown route → SPA shell');
+  }
+  {
+    const res = await get('/_download/bogus-id', cookie);
+    check(res.status === 404, 'post-auth unknown download id → 404');
+  }
+  // Protocol routes reach their handlers (no account open → handler's own 4xx/5xx,
+  // which is still proof the gate passed us through rather than a flat 401).
+  {
+    const res = await get('/_media/pic?t=1&name=x', cookie);
+    check(res.status !== 401, `post-auth /_media reaches handler (got ${res.status})`);
+  }
+
+  // ---- a forged cookie stays out ----
+  {
+    const res = await get('/trpc/anything', 'weq_session=forged-value');
+    check(res.status === 401, 'forged session cookie → 401');
+  }
+
+  // ---- logout closes the door again ----
+  {
+    await fetch(`${base}/_auth/logout`, { method: 'POST', headers: { cookie } });
+    const res = await get('/trpc/anything', cookie);
+    check(res.status === 401, 'after logout → 401 again');
+  }
+
+  server.close();
+  console.log(failed === 0 ? '\nALL PASS' : `\n${failed} FAILED`);
+  process.exit(failed === 0 ? 0 : 1);
+}
+
+void main();
diff --git a/apps/web/src/server/http.ts b/apps/web/src/server/http.ts
new file mode 100644
index 00000000..3f059858
--- /dev/null
+++ b/apps/web/src/server/http.ts
@@ -0,0 +1,188 @@
+/**
+ * The web app's HTTP server.
+ *
+ * Routing, in order:
+ *   /_auth/login   POST   — the only unauthenticated endpoint
+ *   /_auth/logout  POST
+ *   /trpc/*               — tRPC over HTTP (259 procedures, unchanged)
+ *   /_media/*             — weq-media:// handler
+ *   /_avatar/*            — weq-avatar:// handler
+ *   /_asset/*             — weq-asset:// handler
+ *   /_download/:id        — files produced by HostBridge.pickSaveTarget
+ *   everything else       — the built SPA (index.html fallback)
+ *
+ * Everything except the login endpoint and the login page is behind
+ * {@link AuthGate}. Port binding mirrors `main/mcp/server.ts`: probe forward
+ * from the requested port so a squatter (Windows loves these) doesn't stop us.
+ */
+
+import http from 'node:http';
+import { type AuthGate, peerKey } from './auth';
+import { LOGIN_PAGE } from './login_page';
+import { toProtocolRequest, writeResponse } from './protocol_adapter';
+import { lookupDownload } from './host';
+import { serveStatic } from './static';
+import { handleMediaRequest } from '@weq/desktop/main/media_protocol';
+import { handleAvatarRequest } from '@weq/desktop/main/avatar_protocol';
+import { handleResourceRequest } from '@weq/desktop/main/resource_protocol';
+import { fileResponse } from '@weq/desktop/main/file_response';
+
+const PORT_FALLBACK_ATTEMPTS = 10;
+/** Refuse absurd login bodies outright. */
+const MAX_LOGIN_BODY = 4096;
+
+export interface ServerOptions {
+  port: number;
+  host: string;
+  publicDir: string;
+  auth: AuthGate;
+  /** Mounted at /trpc — created in index.ts so this file stays transport-only. */
+  trpc: (req: http.IncomingMessage, res: http.ServerResponse) => void;
+}
+
+/** Read a JSON body, refusing anything oversized. */
+async function readJson(req: http.IncomingMessage): Promise<unknown> {
+  const chunks: Buffer[] = [];
+  let size = 0;
+  for await (const chunk of req) {
+    size += (chunk as Buffer).length;
+    if (size > MAX_LOGIN_BODY) throw new Error('body too large');
+    chunks.push(chunk as Buffer);
+  }
+  return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+
+function send(res: http.ServerResponse, status: number, body: string, type = 'text/plain'): void {
+  res.writeHead(status, { 'Content-Type': `${type}; charset=utf-8` });
+  res.end(body);
+}
+
+/** Map a URL prefix onto one of the reused protocol handlers. */
+const PROTOCOL_ROUTES: Array<{
+  prefix: string;
+  scheme: string;
+  handle: (req: Request) => Promise<Response>;
+}> = [
+  { prefix: '/_media', scheme: 'weq-media', handle: handleMediaRequest },
+  { prefix: '/_avatar', scheme: 'weq-avatar', handle: handleAvatarRequest },
+  { prefix: '/_asset', scheme: 'weq-asset', handle: handleResourceRequest },
+];
+
+async function handleRequest(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  opts: ServerOptions,
+): Promise<void> {
+  const url = req.url ?? '/';
+  const path = url.split('?')[0] ?? '/';
+
+  // ---- unauthenticated surface (exactly two entries) ----
+  if (path === '/_auth/login') {
+    if (req.method !== 'POST') return send(res, 405, 'method not allowed');
+    let token = '';
+    try {
+      const body = await readJson(req);
+      token = typeof (body as { token?: unknown })?.token === 'string'
+        ? (body as { token: string }).token
+        : '';
+    } catch {
+      return send(res, 400, 'bad request');
+    }
+    const ok = await opts.auth.login(token, peerKey(req), res);
+    return send(res, ok ? 200 : 401, ok ? 'ok' : 'unauthorized');
+  }
+
+  const authed = opts.auth.isAuthed(req);
+
+  if (path === '/_auth/logout') {
+    opts.auth.logout(req, res);
+    return send(res, 200, 'ok');
+  }
+
+  // ---- the gate ----
+  if (!authed) {
+    // A browser navigating to any page gets the login form; anything else
+    // (XHR, media, tRPC) gets a plain 401 so the client can react.
+    const wantsHtml = (req.headers.accept ?? '').includes('text/html');
+    if (wantsHtml) {
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' });
+      res.end(LOGIN_PAGE);
+      return;
+    }
+    return send(res, 401, 'unauthorized');
+  }
+
+  // ---- authenticated routes ----
+  if (path.startsWith('/trpc')) {
+    opts.trpc(req, res);
+    return;
+  }
+
+  for (const route of PROTOCOL_ROUTES) {
+    if (path !== route.prefix && !path.startsWith(`${route.prefix}/`)) continue;
+    const protoReq = toProtocolRequest(req, route.scheme, route.prefix);
+    if (!protoReq) return send(res, 400, 'bad request');
+    const out = await route.handle(protoReq);
+    return writeResponse(res, out);
+  }
+
+  if (path.startsWith('/_download/')) {
+    const id = path.slice('/_download/'.length);
+    const entry = lookupDownload(id);
+    if (!entry) return send(res, 404, 'not found');
+    const out = await fileResponse(entry.path);
+    const headers = new Headers(out.headers);
+    headers.set(
+      'Content-Disposition',
+      `attachment; filename*=UTF-8''${encodeURIComponent(entry.name)}`,
+    );
+    return writeResponse(res, new Response(out.body, { status: out.status, headers }));
+  }
+
+  await serveStatic(res, opts.publicDir, url);
+}
+
+/** Bind `server` to `port`, resolving false when the port is taken. */
+function tryListen(server: http.Server, port: number, host: string): Promise<boolean> {
+  return new Promise((resolve, reject) => {
+    const onError = (err: NodeJS.ErrnoException): void => {
+      server.off('listening', onListening);
+      if (err.code === 'EADDRINUSE') {
+        resolve(false);
+        return;
+      }
+      reject(err);
+    };
+    const onListening = (): void => {
+      server.off('error', onError);
+      resolve(true);
+    };
+    server.once('error', onError);
+    server.once('listening', onListening);
+    server.listen(port, host);
+  });
+}
+
+export async function startServer(
+  opts: ServerOptions,
+): Promise<{ server: http.Server; port: number }> {
+  const server = http.createServer((req, res) => {
+    handleRequest(req, res, opts).catch((e) => {
+      console.error('[web] request failed:', e);
+      if (!res.headersSent) send(res, 500, 'internal error');
+      else res.destroy();
+    });
+  });
+
+  for (let i = 0; i < PORT_FALLBACK_ATTEMPTS; i += 1) {
+    const port = opts.port + i;
+    if (port > 65535) break;
+    if (await tryListen(server, port, opts.host)) return { server, port };
+    if (i > 0) console.warn(`[web] port ${port} in use, trying next`);
+  }
+
+  server.close();
+  throw new Error(
+    `端口 ${opts.port}–${Math.min(opts.port + PORT_FALLBACK_ATTEMPTS - 1, 65535)} 都被占用，无法启动。`,
+  );
+}
diff --git a/apps/web/src/server/index.ts b/apps/web/src/server/index.ts
new file mode 100644
index 00000000..4c018cf8
--- /dev/null
+++ b/apps/web/src/server/index.ts
@@ -0,0 +1,106 @@
+/**
+ * Entry point for the browser-served WeQ.
+ *
+ * Assembles the same services the desktop app uses (`initAppContext` from
+ * `apps/desktop/src/main`, which is Electron-free by construction), installs
+ * the web {@link HostBridge}, then starts the HTTP + WebSocket server.
+ *
+ * Environment:
+ *   WEQ_TOKEN       access token. Required when binding beyond loopback;
+ *                   auto-generated (and printed) otherwise.
+ *   WEQ_HOST        bind address (default 127.0.0.1). Set 0.0.0.0 to expose.
+ *   WEQ_PORT        preferred port (default 7690). Probes forward if taken.
+ *   WEQ_EXPORT_DIR  where exports/saves land (default <cwd>/weq-exports).
+ *   WEQ_DATA_DIR    logs + app data (default <cwd>/weq-data).
+ *   WEQ_NATIVE_DIR  override for the native/ bundle (see @weq/native loader).
+ */
+
+import { randomBytes } from 'node:crypto';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { setHost, initLogger } from '@weq/service';
+import { initAppContext } from '@weq/desktop/main/context/app_context';
+import { appRouter } from '@weq/desktop/main/ipc/router';
+import { AuthGate } from './auth';
+import { createWebHost } from './host';
+import { startServer } from './http';
+import { createTrpcHandler, attachWsHandler } from './trpc_adapter';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+const HOST = process.env.WEQ_HOST || '127.0.0.1';
+const PORT = Number(process.env.WEQ_PORT || 7690);
+const EXPORT_DIR = process.env.WEQ_EXPORT_DIR || join(process.cwd(), 'weq-exports');
+const DATA_DIR = process.env.WEQ_DATA_DIR || join(process.cwd(), 'weq-data');
+const PUBLIC_DIR = resolve(here, 'public');
+
+const isLoopback = HOST === '127.0.0.1' || HOST === 'localhost' || HOST === '::1';
+
+/**
+ * Baked in by `scripts/build-server.mjs` (esbuild `define`). Running from
+ * source leaves the identifier undeclared, so the lookup is guarded — a bare
+ * reference would throw ReferenceError rather than yield undefined.
+ */
+declare const __WEQ_VERSION__: string;
+const VERSION = ((): string => {
+  try {
+    return __WEQ_VERSION__;
+  } catch {
+    return '0.0.0-dev';
+  }
+})();
+
+/**
+ * Resolve the access token. Binding beyond loopback with an auto-generated
+ * token would mean the only copy is a console line the operator may never
+ * read — so in that case we refuse to start instead.
+ */
+function resolveToken(): string {
+  const fromEnv = process.env.WEQ_TOKEN?.trim();
+  if (fromEnv) return fromEnv;
+  if (!isLoopback) {
+    console.error(
+      `\n拒绝启动：绑定到 ${HOST}（非本机回环）时必须显式设置 WEQ_TOKEN。\n` +
+        `  例：WEQ_TOKEN=$(openssl rand -hex 24) WEQ_HOST=0.0.0.0 node server.mjs\n` +
+        `远程暴露时请同时考虑放在 HTTPS 反向代理之后。\n`,
+    );
+    process.exit(1);
+  }
+  return randomBytes(24).toString('hex');
+}
+
+async function main(): Promise<void> {
+  initLogger(DATA_DIR);
+
+  const token = resolveToken();
+  const generated = !process.env.WEQ_TOKEN?.trim();
+
+  setHost(createWebHost({ exportDir: EXPORT_DIR, version: VERSION }));
+  initAppContext();
+
+  const auth = new AuthGate({ token, remote: !isLoopback });
+  const { server, port } = await startServer({
+    port: PORT,
+    host: HOST,
+    publicDir: PUBLIC_DIR,
+    auth,
+    trpc: createTrpcHandler(appRouter),
+  });
+  attachWsHandler(server, appRouter, auth);
+
+  console.log(`\n  WeQ Web  →  http://${isLoopback ? '127.0.0.1' : HOST}:${port}`);
+  if (generated) console.log(`  访问令牌  →  ${token}    (设置 WEQ_TOKEN 可固定)`);
+  console.log(`  导出目录  →  ${EXPORT_DIR}\n`);
+
+  const shutdown = (): void => {
+    server.close(() => process.exit(0));
+    setTimeout(() => process.exit(0), 3000).unref();
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
+main().catch((e) => {
+  console.error('[web] failed to start:', e);
+  process.exit(1);
+});
diff --git a/apps/web/src/server/login_page.ts b/apps/web/src/server/login_page.ts
new file mode 100644
index 00000000..877a1e47
--- /dev/null
+++ b/apps/web/src/server/login_page.ts
@@ -0,0 +1,361 @@
+/**
+ * Login page — the only HTML served before authentication.
+ *
+ * Deliberately self-contained (no bundle, no assets, no network): everything
+ * reachable pre-auth is attack surface, so the pre-auth surface is exactly this
+ * string plus `POST /_auth/login`. That constraint is why the logo is inline SVG
+ * rather than `resources/brand/logo.png` — serving that would mean opening an
+ * unauthenticated static route.
+ *
+ * Visually it mirrors the app's own landing screen (`.weq-home-shell`): same
+ * accent (#0099ff), same pale multi-stop gradient, same fine dot grid. The
+ * aurora blobs are the one addition — a static gradient reads as "unstyled" on
+ * an otherwise empty page.
+ */
+
+export const LOGIN_PAGE = `<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<meta name="color-scheme" content="light dark" />
+<title>WeQ · 登录</title>
+<style>
+  :root {
+    --accent: #0099ff;
+    --fg: #142235;
+    --fg-muted: #5b7d99;
+    --card: rgba(255, 255, 255, 0.72);
+    --card-border: rgba(0, 153, 255, 0.16);
+    --field: rgba(255, 255, 255, 0.78);
+    --field-border: rgba(20, 34, 53, 0.13);
+    --danger: #c0392f;
+    --shadow: 0 24px 60px -28px rgba(6, 44, 76, 0.34);
+  }
+
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --fg: #e8eef5;
+      --fg-muted: #8ba6bd;
+      --card: rgba(23, 29, 37, 0.72);
+      --card-border: rgba(0, 153, 255, 0.2);
+      --field: rgba(13, 17, 23, 0.68);
+      --field-border: rgba(255, 255, 255, 0.11);
+      --danger: #ff7b70;
+      --shadow: 0 24px 60px -28px rgba(0, 0, 0, 0.7);
+    }
+  }
+
+  * { box-sizing: border-box; }
+
+  html, body { height: 100%; }
+
+  body {
+    margin: 0;
+    display: grid;
+    place-items: center;
+    padding: 24px;
+    overflow: hidden;
+    color: var(--fg);
+    font: 15px/1.6 system-ui, -apple-system, "Segoe UI", "Microsoft YaHei", sans-serif;
+    /* Same multi-stop wash as .weq-home-shell in the app. */
+    background:
+      radial-gradient(ellipse at 14% 16%, rgba(0, 153, 255, 0.11) 0, transparent 42%),
+      radial-gradient(ellipse at 78% 14%, rgba(255, 220, 83, 0.10) 0, transparent 38%),
+      radial-gradient(ellipse at 82% 82%, rgba(83, 206, 144, 0.09) 0, transparent 42%),
+      radial-gradient(ellipse at 36% 88%, rgba(132, 126, 224, 0.055) 0, transparent 46%),
+      linear-gradient(135deg, #fdfeff 0%, #f8fcff 38%, #fffef4 68%, #fbfffc 100%);
+  }
+
+  @media (prefers-color-scheme: dark) {
+    body {
+      background:
+        radial-gradient(ellipse at 14% 16%, rgba(0, 153, 255, 0.16) 0, transparent 44%),
+        radial-gradient(ellipse at 80% 84%, rgba(83, 206, 144, 0.10) 0, transparent 44%),
+        linear-gradient(150deg, #10161e 0%, #0d1117 52%, #121a22 100%);
+    }
+  }
+
+  /* --- aurora: three slow-drifting blurred blobs --- */
+  .aurora {
+    position: fixed;
+    inset: -25vmax;
+    z-index: 0;
+    pointer-events: none;
+    filter: blur(72px);
+    opacity: 0.55;
+  }
+  .aurora i {
+    position: absolute;
+    display: block;
+    border-radius: 50%;
+    mix-blend-mode: multiply;
+  }
+  @media (prefers-color-scheme: dark) {
+    .aurora { opacity: 0.42; }
+    .aurora i { mix-blend-mode: screen; }
+  }
+  .aurora i:nth-child(1) {
+    width: 44vmax; height: 44vmax; top: 8%; left: 6%;
+    background: radial-gradient(circle, rgba(0, 153, 255, 0.5), transparent 68%);
+    animation: drift-a 26s ease-in-out infinite;
+  }
+  .aurora i:nth-child(2) {
+    width: 38vmax; height: 38vmax; top: 44%; left: 58%;
+    background: radial-gradient(circle, rgba(83, 206, 144, 0.42), transparent 68%);
+    animation: drift-b 33s ease-in-out infinite;
+  }
+  .aurora i:nth-child(3) {
+    width: 34vmax; height: 34vmax; top: 2%; left: 52%;
+    background: radial-gradient(circle, rgba(132, 126, 224, 0.36), transparent 68%);
+    animation: drift-c 29s ease-in-out infinite;
+  }
+
+  @keyframes drift-a {
+    0%, 100% { transform: translate3d(0, 0, 0) scale(1); }
+    50%      { transform: translate3d(9vmax, 6vmax, 0) scale(1.14); }
+  }
+  @keyframes drift-b {
+    0%, 100% { transform: translate3d(0, 0, 0) scale(1.06); }
+    50%      { transform: translate3d(-11vmax, -7vmax, 0) scale(0.9); }
+  }
+  @keyframes drift-c {
+    0%, 100% { transform: translate3d(0, 0, 0) scale(0.94); }
+    50%      { transform: translate3d(-6vmax, 10vmax, 0) scale(1.12); }
+  }
+
+  /* --- the fine dot grid the app's home shell uses --- */
+  .grain {
+    position: fixed;
+    inset: 0;
+    z-index: 1;
+    pointer-events: none;
+    opacity: 0.2;
+    mix-blend-mode: multiply;
+    background-image:
+      radial-gradient(circle at 14% 22%, rgba(0, 153, 255, 0.22) 0 0.34px, transparent 0.42px),
+      radial-gradient(circle at 73% 31%, rgba(112, 96, 54, 0.18) 0 0.3px, transparent 0.42px),
+      radial-gradient(circle at 46% 78%, rgba(31, 104, 79, 0.18) 0 0.32px, transparent 0.44px),
+      radial-gradient(circle at 88% 66%, rgba(0, 153, 255, 0.12) 0 0.28px, transparent 0.42px);
+    background-size: 13px 17px, 19px 23px, 29px 31px, 37px 41px;
+    background-position: 0 0, 7px 11px, 17px 5px, 23px 29px;
+  }
+  @media (prefers-color-scheme: dark) {
+    .grain { mix-blend-mode: screen; opacity: 0.12; }
+  }
+
+  /* --- card --- */
+  form {
+    position: relative;
+    z-index: 2;
+    width: min(372px, calc(100vw - 40px));
+    padding: 38px 32px 30px;
+    text-align: center;
+    background: var(--card);
+    border: 1px solid var(--card-border);
+    border-radius: 18px;
+    box-shadow: var(--shadow);
+    backdrop-filter: blur(20px) saturate(1.35);
+    -webkit-backdrop-filter: blur(20px) saturate(1.35);
+    animation: rise 720ms cubic-bezier(0.16, 1, 0.3, 1) both;
+  }
+  @keyframes rise {
+    from { opacity: 0; transform: translateY(18px) scale(0.975); filter: blur(6px); }
+    to   { opacity: 1; transform: none; filter: none; }
+  }
+
+  .mark {
+    width: 74px; height: 74px;
+    margin: 0 auto 16px;
+    filter: drop-shadow(0 12px 22px rgba(0, 122, 204, 0.26));
+    animation: float 6.5s ease-in-out infinite;
+  }
+  @keyframes float {
+    0%, 100% { transform: translateY(0); }
+    50%      { transform: translateY(-5px); }
+  }
+
+  h1 {
+    margin: 0;
+    font-size: 27px;
+    font-weight: 600;
+    letter-spacing: 0.5px;
+  }
+  p.hint {
+    margin: 7px 0 26px;
+    font-size: 12.5px;
+    letter-spacing: 0.06em;
+    color: var(--fg-muted);
+  }
+
+  .field { text-align: left; }
+
+  label {
+    display: block;
+    margin-bottom: 7px;
+    font-size: 12px;
+    letter-spacing: 0.04em;
+    color: var(--fg-muted);
+  }
+
+  input {
+    width: 100%;
+    padding: 11px 13px;
+    font-size: 15px;
+    font-family: inherit;
+    letter-spacing: 0.08em;
+    color: var(--fg);
+    background: var(--field);
+    border: 1px solid var(--field-border);
+    border-radius: 10px;
+    transition: border-color 160ms ease, box-shadow 220ms ease;
+  }
+  input::placeholder {
+    letter-spacing: normal;
+    color: color-mix(in srgb, var(--fg-muted) 62%, transparent);
+  }
+  input:focus {
+    outline: none;
+    border-color: var(--accent);
+    box-shadow: 0 0 0 4px color-mix(in srgb, var(--accent) 15%, transparent);
+  }
+
+  button {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 8px;
+    width: 100%;
+    margin-top: 18px;
+    padding: 11px;
+    font-size: 14.5px;
+    font-weight: 500;
+    font-family: inherit;
+    letter-spacing: 0.04em;
+    color: #fff;
+    background: linear-gradient(120deg, #0099ff 0%, #38b6ff 52%, #0099ff 100%);
+    background-size: 220% 100%;
+    border: 0;
+    border-radius: 10px;
+    cursor: pointer;
+    box-shadow: 0 10px 24px -12px rgba(0, 122, 204, 0.75);
+    transition: transform 160ms ease, box-shadow 220ms ease, background-position 520ms ease;
+  }
+  button:hover:not(:disabled) {
+    transform: translateY(-1px);
+    background-position: 100% 0;
+    box-shadow: 0 14px 30px -12px rgba(0, 122, 204, 0.85);
+  }
+  button:active:not(:disabled) { transform: translateY(0); }
+  button:disabled { cursor: default; opacity: 0.62; box-shadow: none; }
+
+  .spinner {
+    width: 15px; height: 15px;
+    border: 2px solid rgba(255, 255, 255, 0.34);
+    border-top-color: #fff;
+    border-radius: 50%;
+    animation: spin 780ms linear infinite;
+  }
+  @keyframes spin { to { transform: rotate(360deg); } }
+
+  .err {
+    min-height: 19px;
+    margin-top: 13px;
+    font-size: 12.5px;
+    color: var(--danger);
+  }
+
+  form.shake { animation: shake 400ms cubic-bezier(0.36, 0.07, 0.19, 0.97); }
+  @keyframes shake {
+    10%, 90% { transform: translateX(-2px); }
+    20%, 80% { transform: translateX(4px); }
+    30%, 50%, 70% { transform: translateX(-7px); }
+    40%, 60% { transform: translateX(7px); }
+  }
+
+  .foot {
+    margin: 18px 0 0;
+    font-size: 11.5px;
+    letter-spacing: 0.05em;
+    color: color-mix(in srgb, var(--fg-muted) 72%, transparent);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    *, *::before, *::after {
+      animation-duration: 0.01ms !important;
+      animation-iteration-count: 1 !important;
+    }
+  }
+</style>
+</head>
+<body>
+<div class="aurora" aria-hidden="true"><i></i><i></i><i></i></div>
+<div class="grain" aria-hidden="true"></div>
+
+<form id="f">
+  <svg class="mark" viewBox="0 0 64 64" fill="none" aria-hidden="true">
+    <defs>
+      <linearGradient id="g" x1="6" y1="4" x2="58" y2="60" gradientUnits="userSpaceOnUse">
+        <stop stop-color="#1f7bff" />
+        <stop offset="1" stop-color="#12b5ff" />
+      </linearGradient>
+    </defs>
+    <circle cx="29" cy="29" r="25" fill="url(#g)" />
+    <path d="m22 44-5.5 10 11-3.4 1.6-6.6H22Z" fill="url(#g)" />
+    <path d="M29 12c-6.9 0-12 5.6-12 13 0 3.3-1.4 5.4-2.6 7.2-1 1.6-1.9 2.9-1.4 4.5.6 1.9 2.9 2.6 5.4 2.9 1.2 2.6 5.4 4.6 10.6 4.6s9.4-2 10.6-4.6c2.5-.3 4.8-1 5.4-2.9.5-1.6-.4-2.9-1.4-4.5-1.2-1.8-2.6-3.9-2.6-7.2 0-7.4-5.1-13-12-13Z" fill="#fff" />
+    <rect x="39" y="41" width="21" height="17" rx="4.5" fill="#fff" />
+    <path d="M44 41v-4a5.5 5.5 0 0 1 11 0v4" stroke="#fff" stroke-width="3.6" stroke-linecap="round" />
+    <circle cx="49.5" cy="48" r="2.5" fill="url(#g)" />
+    <rect x="48.3" y="48" width="2.4" height="4.4" rx="1.2" fill="url(#g)" />
+  </svg>
+
+  <h1>WeQ</h1>
+  <p class="hint">QQ NT 本地数据工具</p>
+
+  <div class="field">
+    <label for="t">访问令牌</label>
+    <input id="t" type="password" autocomplete="current-password" placeholder="粘贴启动时打印的令牌" autofocus />
+  </div>
+
+  <button id="b" type="submit">进入</button>
+  <div class="err" id="e" role="alert"></div>
+  <p class="foot">数据全程留在本机 · 不上传任何服务器</p>
+</form>
+
+<script>
+  const f = document.getElementById('f');
+  const t = document.getElementById('t');
+  const b = document.getElementById('b');
+  const e = document.getElementById('e');
+
+  function fail(msg) {
+    e.textContent = msg;
+    f.classList.remove('shake');
+    // Force reflow so the animation restarts on a repeated failure.
+    void f.offsetWidth;
+    f.classList.add('shake');
+  }
+
+  f.addEventListener('submit', async (ev) => {
+    ev.preventDefault();
+    e.textContent = '';
+    b.disabled = true;
+    b.innerHTML = '<span class="spinner"></span><span>验证中…</span>';
+    try {
+      const res = await fetch('/_auth/login', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ token: t.value }),
+      });
+      if (res.ok) { location.replace('/'); return; }
+      fail(res.status === 429 ? '尝试过于频繁，请稍候再试。' : '令牌不正确。');
+    } catch {
+      fail('无法连接服务器。');
+    }
+    b.disabled = false;
+    b.textContent = '进入';
+    t.select();
+  });
+</script>
+</body>
+</html>`;
diff --git a/apps/web/src/server/protocol_adapter.ts b/apps/web/src/server/protocol_adapter.ts
new file mode 100644
index 00000000..ba434080
--- /dev/null
+++ b/apps/web/src/server/protocol_adapter.ts
@@ -0,0 +1,67 @@
+/**
+ * Bridge between `node:http` and the Web `Request`/`Response` pair that the
+ * protocol handlers speak.
+ *
+ * The desktop app serves media through Electron custom schemes, whose handlers
+ * are `(Request) => Response`. Those handlers were made shell-agnostic in M2,
+ * so the web app reuses them verbatim — this file only translates the envelope:
+ *
+ *   GET /_media/pic?t=1&name=x   →   weq-media://pic?t=1&name=x
+ *
+ * `Range` is forwarded both ways so `<video>`/`<audio>` seeking works.
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { Readable } from 'node:stream';
+
+/** Build a Web `Request` addressed to `scheme://<first-segment>/...`. */
+export function toProtocolRequest(
+  req: IncomingMessage,
+  scheme: string,
+  mountPath: string,
+): Request | null {
+  const raw = req.url ?? '/';
+  if (!raw.startsWith(mountPath)) return null;
+  // `/_media/pic?x=1` → rest = `pic?x=1`
+  const rest = raw.slice(mountPath.length).replace(/^\/+/, '');
+  if (!rest) return null;
+
+  const qMark = rest.indexOf('?');
+  const pathPart = qMark === -1 ? rest : rest.slice(0, qMark);
+  const query = qMark === -1 ? '' : rest.slice(qMark);
+  // The custom schemes are "standard", so the first segment is the authority
+  // (`weq-media://pic`) and the remainder is the path.
+  const slash = pathPart.indexOf('/');
+  const host = slash === -1 ? pathPart : pathPart.slice(0, slash);
+  const path = slash === -1 ? '' : pathPart.slice(slash);
+
+  const headers = new Headers();
+  const range = req.headers.range;
+  if (typeof range === 'string') headers.set('range', range);
+
+  return new Request(`${scheme}://${host}${path}${query}`, { method: 'GET', headers });
+}
+
+/** Write a Web `Response` out to a `node:http` response, streaming the body. */
+export async function writeResponse(res: ServerResponse, out: Response): Promise<void> {
+  const headers: Record<string, string> = {};
+  out.headers.forEach((value, key) => {
+    headers[key] = value;
+  });
+  res.writeHead(out.status, headers);
+
+  if (!out.body) {
+    res.end();
+    return;
+  }
+  const nodeStream = Readable.fromWeb(out.body as Parameters<typeof Readable.fromWeb>[0]);
+  nodeStream.pipe(res);
+  await new Promise<void>((resolve) => {
+    nodeStream.on('end', resolve);
+    nodeStream.on('error', () => {
+      res.destroy();
+      resolve();
+    });
+    res.on('close', resolve);
+  });
+}
diff --git a/apps/web/src/server/static.ts b/apps/web/src/server/static.ts
new file mode 100644
index 00000000..8b2ebb1e
--- /dev/null
+++ b/apps/web/src/server/static.ts
@@ -0,0 +1,40 @@
+/**
+ * Static file serving for the built SPA, with an index.html fallback so
+ * client-side routes resolve.
+ */
+
+import { existsSync, statSync } from 'node:fs';
+import type { ServerResponse } from 'node:http';
+import { join, normalize, sep } from 'node:path';
+import { fileResponse } from '@weq/desktop/main/file_response';
+import { writeResponse } from './protocol_adapter';
+
+export async function serveStatic(
+  res: ServerResponse,
+  root: string,
+  urlPath: string,
+): Promise<void> {
+  const clean = decodeURIComponent(urlPath.split('?')[0] ?? '/');
+  const target = normalize(join(root, clean));
+
+  // Containment — a crafted path must not escape the public dir.
+  const inRoot = target === root || target.startsWith(root + sep);
+  const isFile = inRoot && existsSync(target) && statSync(target).isFile();
+
+  // Anything that isn't a real file falls through to the SPA shell.
+  const path = isFile ? target : join(root, 'index.html');
+  if (!existsSync(path)) {
+    res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+    res.end('build missing — run `pnpm --filter @weq/web build`');
+    return;
+  }
+
+  const out = await fileResponse(path);
+  // Hashed asset filenames are immutable; the shell must never be cached.
+  const cache = isFile && clean.startsWith('/assets/')
+    ? 'public, max-age=31536000, immutable'
+    : 'no-store';
+  const headers = new Headers(out.headers);
+  headers.set('Cache-Control', cache);
+  await writeResponse(res, new Response(out.body, { status: out.status, headers }));
+}
diff --git a/apps/web/src/server/trpc_adapter.ts b/apps/web/src/server/trpc_adapter.ts
new file mode 100644
index 00000000..e7fe41bc
--- /dev/null
+++ b/apps/web/src/server/trpc_adapter.ts
@@ -0,0 +1,68 @@
+/**
+ * tRPC transport for the web app.
+ *
+ * The router itself (259 procedures) is reused verbatim from the desktop app —
+ * only the transport differs: `electron-trpc`'s IPC link becomes plain HTTP for
+ * queries/mutations, plus a WebSocket for the 14 subscriptions (tRPC v10 has no
+ * SSE link, and a single socket covers all of them).
+ *
+ * The WebSocket upgrade re-checks the session cookie: without that, the socket
+ * would be an unauthenticated side door straight into the router.
+ */
+
+import type { IncomingMessage, Server, ServerResponse } from 'node:http';
+import { createHTTPHandler } from '@trpc/server/adapters/standalone';
+import { applyWSSHandler } from '@trpc/server/adapters/ws';
+import { WebSocketServer } from 'ws';
+import type { AppRouter } from '@weq/desktop/main/ipc/router';
+import type { AuthGate } from './auth';
+
+/** HTTP handler for queries + mutations, mounted under `/trpc`. */
+export function createTrpcHandler(
+  router: AppRouter,
+): (req: IncomingMessage, res: ServerResponse) => void {
+  const handler = createHTTPHandler({
+    router,
+    createContext: () => ({}),
+    onError({ error, path }) {
+      console.error(`[trpc] ${path ?? '<no path>'}:`, error.message);
+    },
+  });
+  return (req, res) => {
+    // The standalone adapter wants the path relative to its mount point.
+    const original = req.url ?? '/';
+    req.url = original.slice('/trpc'.length) || '/';
+    handler(req, res);
+  };
+}
+
+/**
+ * Attach the subscription WebSocket at `/trpc-ws`, gated on the same session
+ * cookie as every HTTP route.
+ */
+export function attachWsHandler(server: Server, router: AppRouter, auth: AuthGate): void {
+  const wss = new WebSocketServer({ noServer: true });
+
+  server.on('upgrade', (req, socket, head) => {
+    const path = (req.url ?? '').split('?')[0];
+    if (path !== '/trpc-ws') {
+      socket.destroy();
+      return;
+    }
+    if (!auth.isAuthed(req)) {
+      socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
+      socket.destroy();
+      return;
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => wss.emit('connection', ws, req));
+  });
+
+  applyWSSHandler({
+    wss,
+    router,
+    createContext: () => ({}),
+    onError({ error, path }) {
+      console.error(`[trpc-ws] ${path ?? '<no path>'}:`, error.message);
+    },
+  });
+}
diff --git a/apps/web/tsconfig.server.json b/apps/web/tsconfig.server.json
new file mode 100644
index 00000000..5bab6141
--- /dev/null
+++ b/apps/web/tsconfig.server.json
@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "types": ["node"],
+    "noEmit": true
+  },
+  "include": ["src/server/**/*.ts", "scripts/**/*.mjs"]
+}
diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts
new file mode 100644
index 00000000..7b84586f
--- /dev/null
+++ b/apps/web/vite.config.ts
@@ -0,0 +1,37 @@
+import { resolve } from 'node:path';
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+
+/**
+ * The browser build reuses the desktop renderer verbatim. Only two things
+ * differ, both resolved here:
+ *
+ *   - `@transport` → the HTTP + WebSocket tRPC links (instead of `ipcLink`)
+ *   - `VITE_WEQ_TARGET` → 'web', which flips the media/asset URL prefixes and
+ *     tree-shakes every `<DesktopOnly>` branch out of the bundle
+ */
+
+const RENDERER = resolve(__dirname, '../desktop/src/renderer');
+
+export default defineConfig({
+  root: RENDERER,
+  plugins: [react(), tailwindcss()],
+  define: {
+    'import.meta.env.VITE_WEQ_TARGET': JSON.stringify('web'),
+  },
+  resolve: {
+    alias: {
+      '@renderer': resolve(RENDERER, 'src'),
+      '@resources': resolve(__dirname, '../../resources'),
+      '@transport': resolve(RENDERER, 'src/trpc/transport.web.ts'),
+    },
+  },
+  build: {
+    outDir: resolve(__dirname, 'dist/public'),
+    emptyOutDir: true,
+    rollupOptions: {
+      input: { index: resolve(RENDERER, 'index.html') },
+    },
+  },
+});
diff --git a/docs/README.md b/docs/README.md
index 71263f84..2e477e12 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -17,7 +17,7 @@ Native 部分闭源**仅为防止倒卖**，原理完全公开。
 
 ## 🗄️ 数据库分析
 
-NTQQ 各数据库表结构与字段解析（并入 [QQBackup](https://github.com/QQBackup) 维护）。
+NTQQ 各数据库的表结构与字段解析，全部依据 WeQ 自己的解析实现手写维护。
 
 - [数据库分析入口](./database/index.md)
 
@@ -30,4 +30,5 @@ NTQQ 各数据库表结构与字段解析（并入 [QQBackup](https://github.com
 
 ---
 
-> 文档正在持续补充中，欢迎在 [Issue](../../issues) 或 [交流群](https://qm.qq.com/q/ysMZoAcC1a) 反馈。
+> 文档正在持续补充中 —— 编写进度与待办见 [文档待办总目录](./TODO.md)。
+> 欢迎在 [Issue](../../issues) 或 [交流群](https://qm.qq.com/q/ysMZoAcC1a) 反馈。
diff --git a/docs/TODO.md b/docs/TODO.md
new file mode 100644
index 00000000..3698eb74
--- /dev/null
+++ b/docs/TODO.md
@@ -0,0 +1,105 @@
+# 文档待办总目录
+
+本页跟踪 `docs/` 下**非使用手册**部分（原理 / 架构 / 数据库分析）的编写进度。
+使用手册（`docs/guide/`）由维护者本人撰写，不在本表范围内。
+
+图例：`✅ 已完成` · `🚧 进行中` · `⬜ 待写`
+
+---
+
+## 一、Desktop 架构设计（`docs/develop/`）
+
+| 状态 | 文档 | 内容要点 |
+| ---- | ---- | -------- |
+| ⬜ | [architecture.md](./develop/architecture.md) | monorepo 分层：`native → db → codec → service → desktop`，各 package 职责与依赖方向 |
+| ⬜ | develop/ipc-trpc.md | 主进程 / 渲染进程边界：tRPC over IPC、router 组织、缓存失效约定 |
+| ⬜ | develop/data-flow.md | 一条消息从加密 DB 到界面的完整链路（解密 → 取行 → 解 protobuf → domain → view） |
+| ⬜ | [build-release.md](./develop/build-release.md) | 构建、打包、Tag 发版、应用内自动更新 |
+| ⬜ | [platform-linux.md](./develop/platform-linux.md) | 跨平台与 Linux 移植现状 |
+| ✅ | [testing.md](./develop/testing.md) | `@weq/testkit` 测试约定 |
+
+## 二、数据库分析（`docs/database/`）
+
+> 全部依据 WeQ 自己的解析实现手写维护，不转述二手资料；
+> 未解析过的表宁可留空，也不写没验证过的内容。
+
+### `nt_msg.db`
+
+| 状态 | 文档 | 内容要点 |
+| ---- | ---- | -------- |
+| ✅ | [nt_msg/index.md](./database/nt_msg/index.md) | 表一览 + `nt_uid_mapping_table` + 消息段索引 |
+| ✅ | [40800.md](./database/nt_msg/40800.md) | ElementWire 信封、tag 分段约定、跨类型共用字段族、容错解码 |
+| ✅ | [40900.md](./database/nt_msg/40900.md) | MsgCache 字段表与递归嵌套 |
+| ✅ | [recent-contact.md](./database/nt_msg/recent-contact.md) | 会话列表：列结构、40051 外显预览、ChatType 全表、免打扰 41220 |
+| ✅ | [recent-contact-top.md](./database/nt_msg/recent-contact-top.md) | 置顶会话：5 列全表、1000/60001 二选一、41103 置顶时间与会话标识归一化 |
+| ✅ | [unread-info.md](./database/nt_msg/unread-info.md) | 未读信息：48902 嵌套结构、未读数算法、50000 提醒类别码枚举 |
+| ⬜ | database/nt_msg/row.md | 消息行本身的列（40001/40003/40011/40012/40050…）与「删除 / 撤回」签名 |
+| ⬜ | database/nt_msg/40062.md | 消息表情回应（贴表情） |
+| ⬜ | database/nt_msg/draft.md | `draft_storage_table_v1` 草稿表（尚未解析） |
+
+### 消息段（element）逐类型字段解析
+
+| 状态 | elementType | 文档 |
+| ---- | ----------- | ---- |
+| ✅ | 1 文本 / @ | [text.md](./database/nt_msg/elements/text.md) |
+| ✅ | 2 图片 | [pic.md](./database/nt_msg/elements/pic.md) |
+| ✅ | 3 文件 | [file.md](./database/nt_msg/elements/file.md) |
+| ✅ | 4 语音 | [ptt.md](./database/nt_msg/elements/ptt.md) |
+| ✅ | 5 视频 | [video.md](./database/nt_msg/elements/video.md) |
+| ✅ | 6 系统表情 | [face.md](./database/nt_msg/elements/face.md) |
+| ✅ | 7 回复引用 | [reply.md](./database/nt_msg/elements/reply.md) |
+| ✅ | 8 灰字提示 | [gray-tip.md](./database/nt_msg/elements/gray-tip.md) |
+| ✅ | 9 红包 / 转账 | [wallet.md](./database/nt_msg/elements/wallet.md) |
+| ✅ | 10 ARK 卡片 | [ark.md](./database/nt_msg/elements/ark.md) |
+| ✅ | 11 商城表情 | [mface.md](./database/nt_msg/elements/mface.md) |
+| ✅ | 14 Markdown | [markdown.md](./database/nt_msg/elements/markdown.md) |
+| ✅ | 16 合并转发 | [multi-msg.md](./database/nt_msg/elements/multi-msg.md) |
+| ✅ | 21 通话记录 | [call.md](./database/nt_msg/elements/call.md) |
+| ✅ | 23 在线文件 | [online-file.md](./database/nt_msg/elements/online-file.md) |
+| ✅ | 26 空间动态 | [qq-dynamic.md](./database/nt_msg/elements/qq-dynamic.md) |
+| ✅ | 27 弹射表情 | [emoji-bounce.md](./database/nt_msg/elements/emoji-bounce.md) |
+| ✅ | 30 在线文件夹 | [online-folder.md](./database/nt_msg/elements/online-folder.md) |
+| ⬜ | 28 位置共享 | 目前只有一个文案字段（52152），暂并入 40800 总览说明 |
+
+### 其它库
+
+| 状态 | 文档 | 内容要点 |
+| ---- | ---- | -------- |
+| ⬜ | database/collection.md | `collection.db` 收藏：type ↔ 子标签公式、8 种类型 |
+| ✅ | [profile_info/index.md](./database/profile_info/index.md) | `profile_info.db` 库总览：好友名单/分组/申请/AI 机器人/FTS 坑 |
+| ✅ | [profile_info/profile-info-v6.md](./database/profile_info/profile-info-v6.md) | `profile_info_v6` 44 列 + `21000` 七大分块 + 两个非 protobuf 的 TLV 列 |
+| ⬜ | database/group-info.md | `group_info.db` 中 WeQ 用到的表与 protobuf 列 |
+| ⬜ | database/emoji.md | `emoji.db` 系统表情 / 商城表情包 |
+| ⬜ | database/login.md | `login.db` 账号列表 |
+
+## 三、QQ 数据库密钥获取原理（`docs/principles/`）
+
+| 状态 | 文档 | 内容要点 |
+| ---- | ---- | -------- |
+| ⬜ | [key-extraction.md](./principles/key-extraction.md) | 两条路线总览与取舍 |
+| ⬜ | principles/key-nt-helper.md | nt_helper 路线（`nt_helper/src`）：原理与关键步骤 |
+| ⬜ | principles/key-ninebird.md | ninebird 路线（`nt_helper/ninebird`）：原理与关键步骤 |
+| ⬜ | [db-decrypt.md](./principles/db-decrypt.md) | 拿到密钥之后：文件头处理、SQLCipher 参数、`login.db` 特例 |
+| ⬜ | [native-boundary.md](./principles/native-boundary.md) | native / JS 边界约定与打包坑 |
+
+## 四、一些小巧思（`docs/principles/`）
+
+| 状态 | 文档 | 内容要点 |
+| ---- | ---- | -------- |
+| ⬜ | principles/anti-recall-trigger.md | 防撤回：用 SQLite trigger 拦截 QQ 本体的撤回写入 |
+| ⬜ | principles/mface-decrypt.md | 商城表情本地文件的解密（`encryptKey` / 80824） |
+| ⬜ | [avatar-hash.md](./principles/avatar-hash.md) | 本地头像文件名的三重 md5 定位公式 |
+| ⬜ | principles/msg-delete.md | 「删除消息」的 QQ 原生改法与可恢复设计 |
+
+---
+
+## 编写约定
+
+- **只写代码里能直接看出来的东西**：字段解析以 `packages/codec/src/proto/` 的 schema 为准，
+  行为描述以实际实现为准；推测性内容必须显式标注「未验证」。
+- **可信度分级**：字段表统一用「置信度」列区分 `已验证` / `观测一致` / `推测`。
+- **枚举可以只进文档**：解析层用不到的 QQ 原生枚举（如视频封装格式 `NTVideoType`、
+  JSON 灰条业务 id `JsonGrayBusiId`）不必写进代码，直接记在对应字段文档里即可。
+- 每篇文末保留返回上级的导航链接。
+
+[← 返回文档中心](./README.md)
diff --git a/docs/database/index.md b/docs/database/index.md
index f5feec26..5026c1de 100644
--- a/docs/database/index.md
+++ b/docs/database/index.md
@@ -1,30 +1,31 @@
 # 数据库分析
 
-NTQQ 各数据库的**表结构与字段解析**主要维护在文档站项目 **[QQBackup/QQDecrypt](https://github.com/QQBackup/QQDecrypt)**（在线阅读：<https://qqbackup.github.io/QQDecrypt/>）。
+NTQQ 把数据分散在若干个 SQLCipher 加密数据库里。本栏目记录 WeQ **实际解析过**的表与字段 ——
+全部依据自己的解析实现手写维护，不转述二手资料；未解析过的部分宁可留空，也不写没验证过的东西。
 
-WeQ 文档**不重复**收录通用表结构，仅维护与本项目实现强相关、且文档站尚未系统化的深度解析部分。
+## 数据库一览
 
-## 通用表结构（指向文档站）
+| 数据库 | 内容 | 文档 |
+| ------ | ---- | ---- |
+| `nt_msg.db` | 聊天记录本体：消息行、会话列表、未读状态 | [nt_msg.db](./nt_msg/index.md) |
+| `profile_info.db` | 好友 / 陌生人资料、好友列表与分组 | [profile_info.db](./profile_info/index.md) |
+| `group_info.db` | 群资料、群成员、公告、精华 | ⬜ 待写 |
+| `collection.db` | QQ 收藏 | ⬜ 待写 |
+| `emoji.db` | 系统表情、商城表情包 | ⬜ 待写 |
+| `login.db` | 登录过的账号列表 | ⬜ 待写 |
 
-各数据库已解密后的表结构、列含义，请前往文档站的「数据库解析」栏目查阅：
+> 📌 数据库**解密**（取密钥、去文件头、SQLCipher 参数）属于原理部分，见
+> [原理总览](../principles/index.md)。
 
-| 数据库             | 文档站链接                                                                              |
-| ------------------ | --------------------------------------------------------------------------------------- |
-| `nt_msg.db`        | <https://qqbackup.github.io/QQDecrypt/view/db_file_analysis/nt_msg.db>                   |
-| `profile_info.db`  | <https://qqbackup.github.io/QQDecrypt/view/db_file_analysis/profile_info.db>             |
-| `group_info.db`    | <https://qqbackup.github.io/QQDecrypt/view/db_file_analysis/group_info.db>               |
-| `collection.db`    | <https://qqbackup.github.io/QQDecrypt/view/db_file_analysis/collection.db>               |
-| `emoji.db`         | <https://qqbackup.github.io/QQDecrypt/view/db_file_analysis/emoji.db>                    |
-| `login.db`         | <https://qqbackup.github.io/QQDecrypt/view/db_file_analysis/login.db>                    |
-| 其它               | <https://qqbackup.github.io/QQDecrypt/view/db_file_analysis/>                            |
+## 字段表约定
 
-> 📌 数据库解密（取密钥、去文件头、SQLCipher 参数）同样见文档站的「数据库解密」栏目。
+各页的字段表统一使用「置信度」一列区分三档：
 
-## WeQ 单独维护的深度解析
-
-以下内容结构复杂、文档站仅有零散引用，由 WeQ 依据实际解析实现单独维护：
-
-- [`nt_msg.db` 消息体解析（40800 / 40900）](./nt_msg/index.md)
+| 档位 | 含义 |
+| ---- | ---- |
+| 已验证 | 主动构造场景 / 前后 diff 确认过语义 |
+| 观测一致 | 大量真实样本上表现一致，但没有主动构造验证 |
+| 推测 | 只是看起来合理，**未验证** —— 会显式标注 |
 
 ---
 
diff --git a/docs/database/nt_msg/40800.md b/docs/database/nt_msg/40800.md
index a6477191..55ec1faf 100644
--- a/docs/database/nt_msg/40800.md
+++ b/docs/database/nt_msg/40800.md
@@ -1,16 +1,263 @@
 # 40800 — 消息正文（MsgBody）
 
-`40800` 是 `c2c_msg_table` / `group_msg_table` / `dataline_msg_table` 中存贮消息正文的列，为 protobuf，结构为可重复的消息段（`ElementWire`）序列——类似富文本，一条消息可包含多个消息段，按内容顺序排列，部分类型可嵌套。
+`40800` 是 `c2c_msg_table` / `group_msg_table` / `dataline_msg_table` 中存贮消息正文的列，
+内容是 **protobuf**，结构为可重复的消息段（element）序列 —— 类似富文本：一条消息可包含多个消息段，
+按内容顺序排列，部分类型可嵌套。
 
-> 🚧 骨架待补充。
+对应 WeQ 解析实现：
 
-## 结构概览
+| 文件 | 职责 |
+| ---- | ---- |
+| `packages/codec/src/proto/msg/40800.ts` | 列本身的外壳（`MsgBody`） |
+| `packages/codec/src/proto/msg/element.ts` | 单个消息段的**物理 wire 结构**（`ElementWire`），全部 tag 的唯一事实来源 |
+| `packages/codec/src/element/types.ts` | `elementType` / 各 `subType` 的枚举 |
+| `packages/codec/src/element/registry.ts` | wire → 语义 `Element` 的分发 |
+| `packages/codec/src/element/spec.ts` | 每种 element 的 zod schema（哪些字段必有、哪些可选） |
 
-<!-- TODO: ElementWire 外层通用字段 (45001 elementId / 45002 elementType / 45003 subType / 40010 isSender ...) -->
+---
+
+## 一、外壳：列 = 重复的 element
+
+`40800` 这个 BLOB 本身是一个 protobuf 消息，里面**只有一个字段**：tag 同样为 `40800` 的重复子消息。
+每一个 tag-40800 条目就是一个消息段。
+
+```text
+40800 (BLOB)
+└── 40800  repeated ElementWire   ← 每项 = 一个消息段
+    ├── [0] elementType=1  文本
+    ├── [1] elementType=6  表情
+    └── [2] elementType=1  文本
+```
+
+C2C 与群聊的 `40800` **结构完全一致**，两者的差异（发送者 uid、会话对端 uid…）在行级列上，不在这一列里。
+
+## 二、扁平信封：`elementType` 是判别式，不是 oneof
+
+这是理解 `40800` 最关键的一点：
+
+> QQ 并没有把各类型的字段包在各自的子消息里，而是把**所有类型的字段平铺在同一层**，
+> 用 `45002 (elementType)` 这个判别式告诉你该看哪一批 tag。
+
+也就是说 `ElementWire` 是一个「大而全」的扁平结构：文本的 `45101`、图片的 `45402`、
+表情的 `47601`、商城表情的 `80900` 全都是同一层的兄弟字段。一个具体的 element 只会填写
+其中属于自己类型的那几个，其余留空。
+
+带来的直接后果：
+
+- **解析简单**：一次 decode 就能拿到所有字段，不需要按类型切换 schema。
+- **字段号必须全局唯一**：不同类型不能复用同一个 tag 表达不同含义，否则会打架。
+  这也是 QQ 把 tag 编到 4~5 位数的原因。
+- **共用字段天然复用**：图片 / 文件 / 视频 / 语音都是「一个文件」，于是共享同一批 `454xx/455xx`
+  文件族 tag（见下文第五节）。
+
+## 三、tag 分段约定
+
+`element.ts` 顶部记录的分段规律，按 tag 区间划分归属：
+
+| tag 区间 | 归属 |
+| -------- | ---- |
+| `40010..40021` | 信封级元数据（发送方标记、原消息 uid…），与消息行的同名列同义 |
+| `45001..45099` | element 通用字段（id / type / subType） |
+| `45101..45199` | 文本（TEXT） |
+| `45201..45299` | 表情（FACE，历史区段） |
+| `45401..45599` | **文件族**：图片 / 文件 / 视频 / 语音 / 在线文件共用的文件元数据 |
+| `45801..45899` | 文件族的 URL / 本地缓存路径 / CDN 信息 |
+| `45901..45999` | 语音（PTT）专属 + 文件缩略图路径 |
+| `47401..47425` | 回复引用（REPLY） |
+| `47501..47502` | 灰条 · 临时会话（GRAY_TIP subType=15） |
+| `47601..47622` | 表情（FACE） |
+| `47702..47716` | 灰条 · 撤回（GRAY_TIP subType=1） |
+| `47901..47904` | ARK 卡片 |
+| `48101` | 回复引用（补充） |
+| `48151..48157` | 通话记录（CALL） |
+| `48172..48193` | QQ 动态分享卡（QQ_DYNAMIC） |
+| `48210..48275` | 灰条 · JSON / XML（GRAY_TIP subType=17 / 12） |
+| `48401..48461` | 红包 / 转账（WALLET） |
+| `48501..48542` | 灰条 · 群通知（GRAY_TIP subType=4） |
+| `48601..48603` | 合并转发（MULTI_MSG） |
+| `48701..48722` | Markdown |
+| `49154/49155` | 漫游 / 消息同步标记 |
+| `52132..52152` | 弹射表情（EMOJI_BOUNCE）、位置共享（SHARE_LOCATION） |
+| `80810..80995` | 商城表情（MFACE），完全独立的一段 |
+
+> ⚠️ 这个规律是**观测归纳**，不是 QQ 的正式约定。大多数区段吻合，但也有例外
+> （如 FACE 同时用了 `45004` 和 `476xx`，REPLY 用了 `40020/40021` 这两个信封级 tag）。
+
+## 四、每个 element 都有的通用字段
+
+| tag | 字段名 | 类型 | 含义 | 置信度 |
+| --- | ------ | ---- | ---- | ------ |
+| 40010 | `isSender` | bool | **本机**是否发出者。注意语义很窄：只有「这台设备按下发送」才为 true；别人发来的、以及本账号其它端发的都不带此字段 | 已验证 |
+| 45001 | `elementId` | uint64 | 消息段序号 | 已验证 |
+| 45002 | `elementType` | uint32 | 类型判别式，取值见下表 | 已验证 |
+| 45003 | `subType` | uint32 | 子类型，语义**取决于 `elementType`**（同一个数字在不同类型下含义完全不同） | 已验证 |
+
+另有两个「读出来只为完整性」的信封级 tag，不属于任何 element：
+
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 49154 | `roaming` | bytes | 漫游标记 |
+| 49155 | `msgSyncFlag` | uint64 | 消息同步时间戳 |
+
+### `elementType` 全表
+
+值来自 QQ NT 自身的 `NTMsgElementType` 枚举。标注「未观测」的表示本地样本库中从未出现，
+声明出来只是为了将来遇到时有名字可对，而不是一个裸数字。
+
+| 值 | 名称 | 说明 | 文档 |
+| -- | ---- | ---- | ---- |
+| 0 | UNKNOWN | 占位（未观测） | — |
+| 1 | TEXT | 文本 / @ | [text](./elements/text.md) |
+| 2 | PIC | 图片 | [pic](./elements/pic.md) |
+| 3 | FILE | 文件 | [file](./elements/file.md) |
+| 4 | PTT | 语音 | [ptt](./elements/ptt.md) |
+| 5 | VIDEO | 视频 | [video](./elements/video.md) |
+| 6 | FACE | 系统表情 | [face](./elements/face.md) |
+| 7 | REPLY | 回复引用 | [reply](./elements/reply.md) |
+| 8 | GRAY_TIP | 小灰条（撤回 / 拍一拍 / 入群…），语义由 subType 决定 | [gray-tip](./elements/gray-tip.md) |
+| 9 | WALLET | 红包 / 转账 | [wallet](./elements/wallet.md) |
+| 10 | ARK | ARK 卡片 | [ark](./elements/ark.md) |
+| 11 | MFACE | 商城表情 | [mface](./elements/mface.md) |
+| 12 | LIVE_GIFT | 直播礼物（未观测） | — |
+| 13 | STRUCT_LONG_MSG | 结构化长消息（未观测） | — |
+| 14 | MARKDOWN | Markdown | [markdown](./elements/markdown.md) |
+| 15 | GIPHY | Giphy 动图（未观测） | — |
+| 16 | MULTI_MSG | 合并转发（QQ 内部名 MULTIFORWARD） | [multi-msg](./elements/multi-msg.md) |
+| 17 | INLINE_KEYBOARD | 内联键盘 / 机器人按钮（未观测） | — |
+| 18 | IN_TEXT_GIFT | 文字内嵌礼物（未观测） | — |
+| 19 | CALENDAR | 日程（未观测） | — |
+| 20 | YOLO_GAME_RESULT | YOLO 小游戏结果（未观测） | — |
+| 21 | CALL | 音视频通话记录（QQ 内部名 AVRECORD） | [call](./elements/call.md) |
+| 22 | FEED | 动态 Feed（未观测） | — |
+| 23 | ONLINE_FILE | 在线文件（QQ 内部名 TOFURECORD） | [online-file](./elements/online-file.md) |
+| 24 | ACE_BUBBLE | 气泡（未观测） | — |
+| 25 | ACTIVITY | 活动卡片（未观测） | — |
+| 26 | QQ_DYNAMIC | QQ 动态分享卡（QQ 内部名 TOFU） | [qq-dynamic](./elements/qq-dynamic.md) |
+| 27 | EMOJI_BOUNCE | 表情弹射（QQ 内部名 FACEBUBBLE） | [emoji-bounce](./elements/emoji-bounce.md) |
+| 28 | SHARE_LOCATION | 位置共享 | 见下方 |
+| 29 | TASK_TOP_MSG | 任务置顶消息（未观测） | — |
+| 30 | ONLINE_FOLDER | 在线文件夹 | [online-folder](./elements/online-folder.md) |
+| 43 | RECOMMENDED_MSG | 推荐消息（未观测） | — |
+| 44 | ACTION_BAR | 操作栏（未观测） | — |
+
+**elementType=28（位置共享）** 字段极少，不单独成篇：
+
+| tag | 字段名 | 类型 | 必有 | 含义 |
+| --- | ------ | ---- | ---- | ---- |
+| 52152 | `shareLocationText` | string | ✅ | 展示文案，如「发起了位置共享」 |
+
+## 五、跨类型共用的「文件族」字段
+
+图片 / 文件 / 视频 / 语音 / 在线文件在 QQ 眼里都是「一个待传输的文件」，
+因此共用同一批 tag。理解这一批，五种类型就都懂了一半。
+
+### 基本元数据
+
+| tag | 字段名 | 类型 | 含义 | 用于 |
+| --- | ------ | ---- | ---- | ---- |
+| 45402 | `fileName` | string | 文件名 | PIC / FILE / VIDEO / PTT / ONLINE_FILE |
+| 45403 | `filePath` | string | 本地文件路径 | PTT / FILE / ONLINE_FILE |
+| 45405 | `fileSize` | uint32 | 字节数 | 全部 |
+| 45406 | `md5Bytes` | bytes | 二进制 MD5 | 全部 |
+| 45407 | `md5Bytes2` | bytes | 第二份 MD5，作用与 45406 相同 | FILE |
+| 45408 | `contentHash` | bytes | 内容校验 hash | 全部 |
+| 45424 | `md5` | string | 大写十六进制 MD5 字符串 | PIC / PTT |
+| 45411 / 45412 | `imgWidth` / `imgHeight` | uint32 | 宽 / 高（像素） | PIC / FILE / VIDEO / ONLINE_FILE |
+| 45418 | `isOriginal` | bool | 是否原图 / 原画质 | PIC / VIDEO / PTT |
+
+### 传输与下载
+
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 45503 | `fileToken` | string | 下载凭据 |
+| 45505 | `uploadTime` | uint32 | 上传 / 处理时间戳 |
+| 45510 | `videoToken` | string | 下载 token（VIDEO / FILE） |
+| 45511 | `picTransferState` | uint32 | 传输状态 |
+| 45513 | `transferVersion` | uint32 | 传输版本 |
+| 45517 | `uploadTimestamp` | uint32 | 上传时间戳 |
+| 45518 | `fileTTL` | uint32 | 有效期（秒） |
+| 45550 | `transferState` | uint32 | 传输状态（PTT / FILE） |
+| 45554 | `transferErrorText` | string | 传输失败文案，如「传输失败，请稍后重试」 |
+
+### URL / 本地缓存路径
+
+QQ 对同一张图存了**三档尺寸**，每档都有一个远端 URL 和一个本地缓存路径，两两对应：
+
+| 档位 | 远端 URL | 本地缓存路径 | 本地文件名后缀 |
+| ---- | -------- | ------------ | -------------- |
+| 缩略图 | 45802 `thumbnailUrl` | 45812 `thumbnailLocalPath` | `…_0.jpg` |
+| 预览图 | 45803 `previewUrl` | 45813 `previewLocalPath` | `…_198.jpg` |
+| 大图 | 45804 `originalUrl` | 45814 `originalLocalPath` | `…_720.jpg` |
+
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 45806 | `cdnServerIp` | uint32 | CDN 服务器地址，**大端打包的 IPv4**（如 `3082863821` → `183.192.196.205`）。为 0 时表示应由客户端自行解析 `cdnHost` |
+| 45807 | `cdnServerPort` | uint32 | CDN 端口。观测到 80 / 443 / 8080 / 14000 / 57897 / 0 |
+| 45815 | `summary` | string（repeated） | 摘要 / 描述文案 |
+| 45816 | `cdnHost` | string | CDN 域名 |
+
+### 近似常量的传输标记
+
+| tag | 字段名 | 说明 |
+| --- | ------ | ---- |
+| 45507 | `transferFlag45507` | 只有按**有符号 int64** 解释才有意义：几乎恒为 `18446744073704048574`（即 `-5503042`）。声明成 INT64 是为了让 varint 能原样回写，而不被截断成 32 位 |
+| 45509 | `transferFlag45509` | 只要 45507 存在就恒为 1 |
+
+> 45507 / 45509 总是成对出现，PIC、FILE、VIDEO 上都能看到。
+
+## 六、容错解码：`sanitizeBytes`
+
+`40800` 里有大量 tag 的类型是**逆向猜出来的**，猜错会有真实代价：
+
+protobuf-ts 解码一个「已知」字段时，只按 schema 里**声明的类型**读，不校验实际 wire type。
+所以若某个 tag 被声明成了 `uint32`（varint），实际却是长度分隔的 blob，
+解码器就会读错字节数、游标错位，进而**整条消息 decode 抛异常** —— 丢的不是一个字段，是整条消息。
+
+WeQ 的解法是在 decode 前加一道 `sanitizeBytes`（`packages/codec/src/raw/sanitize.ts`）：
+
+1. 纯 wire 级遍历 buffer（始终按**真实** wire type 走，因此不可能读错）；
+2. 逐字段比对「实际 wire type」与「schema 声明类型」，**冲突就丢弃该字段**；
+3. 声明为 `string` 但字节不是合法 UTF-8 的也丢弃 —— protobuf-ts 用的是 fatal 的 `TextDecoder`，
+   否则同样会炸掉整条消息；
+4. 嵌套消息递归处理；未知 tag 原样保留（protobuf-ts 会安全跳过）；
+5. 尾部损坏 / 截断时，保留已累积的合法前缀。
+
+结果是：猜错类型的字段只会「消失」，而不会让整条消息渲染失败。
+
+> 注意范围：只丢弃**真正的 wire type 冲突**。varint 数值超出声明范围的不动它 ——
+> protobuf-ts 会无害地截断，丢掉反而会损失调用方可能需要的数据。
+
+## 七、语义化：从 wire 到 `Element`
+
+`registry.ts` 里的 `decodeElement` 把扁平 wire 结构映射成带 `kind` 的语义对象。由于
+element 接口的字段名与 wire schema 的字段名**完全一致**，这层薄到只剩分发：
+
+```text
+decode: 按 elementType 查出 kind → 展开 wire 全部字段 + 补一个 kind
+encode: 去掉 kind → 展开字段 + 由 kind 反推回 elementType
+```
+
+两处例外值得注意：
+
+- **`text` 与 `at` 共用 elementType=1**。区分方式是看 `45105 (bubbleId)` 有没有值：
+  有值即为 @，其中 `bubbleId` 装的是被 @ 者的 uid、`45103 (textEncodingFlag)` 装 uin。
+  （字段名是历史遗留，与聊天「气泡」无关。）
+- **`GRAY_TIP` 一个 elementType 对应 6 种 kind**，靠 `subType` 再分一次（见 [gray-tip](./elements/gray-tip.md)）。
+
+无法识别的 `elementType` 会被包成 `UnknownElement`，原始 wire 完整保留在 `raw` 里，
+保证「读出来再写回去」字节不丢。
+
+---
+
+## 字段表约定
 
-## 消息段字段
+各消息段文档的字段表统一使用以下列：
 
-各 `elementType` 的具体字段解析见 [消息段索引](./index.md#消息段element索引)。
+- **tag** — protobuf 字段号
+- **字段名** — `element.ts` 中的名字（同时也是 `Element` 对象上的属性名）
+- **类型** — wire 类型
+- **必有** — 该类型的 element 是否必带此字段（依据 `spec.ts` 的 zod schema）
+- **含义** — 名字里带 `flagNNNNN` 的表示**语义未知**，仅为往返保真而解析
 
 ---
 
diff --git a/docs/database/nt_msg/40900.md b/docs/database/nt_msg/40900.md
index fc498953..d7319fd4 100644
--- a/docs/database/nt_msg/40900.md
+++ b/docs/database/nt_msg/40900.md
@@ -1,19 +1,175 @@
 # 40900 — 消息缓存（MsgCache）
 
-`40900` 存贮转发 / 引用场景下缓存的源消息快照，为 protobuf，结构为可重复的 `MsgCache` 记录，且可递归嵌套（转发中套转发）。
+`40900` 存贮转发 / 引用场景下缓存的**源消息快照**，为 protobuf，结构为可重复的 `MsgCache` 记录，
+且可递归嵌套（转发里套转发）。
+
+对应 WeQ 解析实现：`packages/codec/src/proto/msg/40900.ts`。
 
 以列 `40011`（msgType）区分用途：
 
-| 40011 值 | 含义     | 40900 内容                 |
-| -------- | -------- | -------------------------- |
-| 8        | 合并转发 | 被转发的源消息缓存         |
-| 9        | 回复引用 | 被引用的源消息缓存         |
+| 40011 值 | 含义 | 40900 内容 |
+| -------- | ---- | ---------- |
+| 8 | 合并转发 | 被转发的源消息缓存 |
+| 9 | 回复引用 | 被引用的源消息缓存 |
+
+---
+
+## 一、与 40800 的关系
+
+这是理解 `40900` 的入口：
+
+- **`40800` 是「一条消息的正文」** —— 只有 element 列表，没有身份、没有时间、没有发送者。
+- **`40900` 是「一整行消息的自包含快照」** —— 身份（msgId / seq / random）、路由（收发双方 uid + uin）、
+  时间、状态、发送者昵称头像，**外加那条消息的 40800 element 列表本身**。
+
+换句话说：`MsgCache` ⊃ `MsgBody`。`MsgCache` 里 tag 为 `40800` 的字段，
+就是原样的 `repeated ElementWire`，与 `40800` 列里的东西**结构完全一致**。
+
+```text
+40900 (BLOB)
+└── 40900  repeated MsgCache        ← 每项 = 一条被缓存的完整消息
+    ├── 40001 msgId / 40003 msgSeq / 40050 sendTime / …   （行级标量）
+    ├── 40600 senderInfo                                   （发送者展示信息）
+    ├── 40800 repeated ElementWire  ← 这条消息的正文，同 40800 列
+    └── 40900 repeated MsgCache     ← 递归：它自己缓存的源消息
+```
+
+## 二、递归嵌套
+
+当 `msgType` 为 `MULTI_FORWARD (8)` 或 `REPLY (9)` 时，这条消息会把它所缓存的源消息
+挂在 tag `40900` 下（repeated）。而那些条目**本身也是完整的 `MsgCache`**，可以再挂 `40900` ——
+即结构是任意深的。
+
+典型场景：把一段「合并转发」再引用回复一次，就会出现两层嵌套。
+
+> 实现上，`subMsgs` 字段用 `(): ProtoMessageType => MsgCache` 这个显式返回类型的 thunk
+> 打断自引用的类型推导循环。运行时是惰性解析的，调用 thunk 时 `MsgCache` 早已定义完毕。
+
+## 三、字段表
+
+### 身份与序号
+
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 40001 | `msgId` | int64 | 消息 id（雪花 id） |
+| 40002 | `msgRandom` | uint32 | 消息随机数，用于去重 |
+| 40003 | `msgSeq` | uint32 | 消息序列号 |
+
+### 类型与状态
+
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 40010 | `isSender` | bool | 是否本机发送（语义同 `ElementWire.isSender`） |
+| 40011 | `msgType` | uint32 | 消息类型，见下方 `MsgType` |
+| 40012 | `msgSubType` | uint32 | 消息子类型 |
+| 40013 | `sendType` | uint32 | 消息来源，见下方 `SendType` |
+| 40041 | `sendStatus` | uint32 | 发送状态，见下方 `SendStatus` |
+
+### 收发双方
+
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 40020 | `senderUid` | string | 发送者 uid |
+| 40021 | `peerUid` | string | 会话对端 uid |
+| 40033 | `senderUin` | uint32 | 发送者 QQ 号 |
+| 40093 | `sendNick` | string | 发送者昵称 |
+
+### 时间
+
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 40050 | `sendTime` | uint32 | 发送时间，unix 秒 |
+| 40058 | `sendDayStartTime` | uint32 | 发送当天 00:00 的时间戳，unix 秒 |
+
+### 内容与嵌套
+
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 40600 | `senderInfo` | message | 发送者展示信息，见下方嵌套结构 |
+| 40800 | `elements` | repeated ElementWire | **消息正文**，结构与 [40800 列](./40800.md) 完全一致 |
+| 40801 | `proto40801` | bytes | 低价值嵌套 protobuf，保留为不透明字节 |
+| 40802 | `proto40802` | bytes | 同上 |
+| 40900 | `subMsgs` | repeated MsgCache | **递归**：被缓存的源 / 引用消息 |
+
+### 语义未知的标量
+
+以下 tag 为往返保真而解析，语义未定，字段名统一为 `flagNNNNN`（均为 uint32）：
+
+`40005` · `40006` · `40008` · `40009` · `40016` · `40105`
+
+## 四、嵌套结构
+
+### 发送者展示块（tag 40600）
+
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 42261 | `flag42261` | uint32 | 未知 |
+| 42341 | `avatar` | message | 头像信息，见下 |
+
+### 头像信息（tag 42341，位于 40600 内）
+
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 42342 | `flag42342` | uint32 | 未知 |
+| 42343 | `flag42343` | uint32 | 未知 |
+| 42344 | `avatarType` | uint32 | 头像图片类型 |
+| 42345 | `encryptedUin` | string | 头像加密 uin |
+| 42346 | `avatarUrl` | string | 头像加密外链 URL |
+
+## 五、枚举
+
+### `MsgType`（tag 40011）
+
+其中 8 / 9 已在真实数据上确认；其余镜像自 QQ NT 的 `KMSGTYPE*` 表，视作尽力而为。
+
+| 值 | 名称 | 说明 |
+| -- | ---- | ---- |
+| 0 | UNKNOWN | |
+| 1 | NULL | QQ 撤回 / 删除消息时会把**行级** 40011 改写为 1 |
+| 2 | MIX | 图文混排（普通消息的常见值） |
+| 3 | FILE | |
+| 4 | STRUCT | |
+| 5 | GRAY_TIP | 小灰条 |
+| 6 | PTT | |
+| 7 | VIDEO | |
+| 8 | MULTI_FORWARD | **合并转发**（已确认） |
+| 9 | REPLY | **引用回复**（已确认） |
+| 10 | WALLET | |
+| 11 | ARK_STRUCT | |
+| 12 | STRUCT_LONG_MSG | |
+| 13 | GIPHY | |
+| 14 | GIFT | |
+| 15 | TEXT_GIFT | |
+| 21 | ONLINE_FILE | |
+| 24 | FACE_BUBBLE | |
+| 25 | SHARE_LOCATION | |
+| 27 | ONLINE_FOLDER | |
+| 29 | PROLOGUE | |
+
+### `SendType`（tag 40013）
+
+消息相对于**本设备 / 本账号**的来源。
+
+| 值 | 名称 | 说明 |
+| -- | ---- | ---- |
+| 0 | RECEIVED | 别人发来的消息 |
+| 1 | LOCAL | 本机发送 |
+| 2 | OTHER_CLIENT | 本账号的其它客户端发送 |
+| 5 | FORWARD | 转发产生的消息 |
+
+> 这几档解释了为什么 `isSender`（40010）语义那么窄：只有 `LOCAL` 才置位；
+> `OTHER_CLIENT` 虽然也是「我发的」，却不带 `isSender`。
 
-> 🚧 骨架待补充。
+### `SendStatus`（tag 40041）
 
-## 结构概览
+注意取值**不与** NapCat 的 `SendStatusType` 命名一一对应，下列语义来自实际观测。
 
-<!-- TODO: MsgCache 字段 (40001 msgId / 40011 msgType / 40020 senderUid / 40800 elements / 40900 subMsgs 递归 ...) -->
+| 值 | 名称 | 说明 |
+| -- | ---- | ---- |
+| 0 | BLOCKED | 发送被阻止（如不是对方好友） |
+| 1 | PENDING | 尚未发送成功（如网络问题） |
+| 2 | SUCCESS | 发送成功 |
+| 3 | BANNED | 消息被 QQ 封禁 |
 
 ---
 
diff --git a/docs/database/nt_msg/elements/ark.md b/docs/database/nt_msg/elements/ark.md
index 784b8aa4..283b4038 100644
--- a/docs/database/nt_msg/elements/ark.md
+++ b/docs/database/nt_msg/elements/ark.md
@@ -1,12 +1,201 @@
 # elementType 10 — ARK 卡片
 
-> 🚧 骨架待补充。
-
 对应 WeQ 解析实现：`packages/codec/src/proto/msg/element.ts`（`elementType = 10`）。
 
-## 字段
+ARK 是 QQ 的结构化卡片消息：分享链接、小程序、群公告卡、游戏中心广告等等，
+渲染样式由服务端下发的模板决定。
+
+wire 层极其简单——**只有三个字段**，真正的内容全在一段 JSON 字符串里。
+
+---
+
+## 一、字段
+
+| tag | 字段名 | 类型 | 必有 | 含义 |
+| --- | ------ | ---- | ---- | ---- |
+| 47901 | `arkData` | string | ✅ | **卡片 JSON 负载**（UTF-8 字符串装的 JSON 文档） |
+| 47902 | `arkSignature` | string | | 64 字符 base64 卡片签名，与 JSON 里的 `config.token` 配对 |
+| 47904 | `arkCardId` | string | | 卡片实例 UUID，如 `33cad47c-09f0-42a6-ab42-6329c0898765` |
+
+## 二、`arkData` 的 JSON 结构
+
+顶层形状固定（`ArkPayload`），但 `meta` 的内部结构**随 `view` 而变**——
+这是解析 ARK 的关键：先看 `view`，再决定怎么读 `meta`。
+
+```ts
+interface ArkPayload {
+  app: string;          // 应用标识，如 "com.tencent.gamecenter.mall"
+  desc: string;         // 描述，如 "QQ手游消息"
+  meta: Record<string, Record<string, unknown>>;  // 形状取决于 view
+  prompt: string;       // 会话列表外显文案
+  sourceName?: string;
+  ver?: string;
+  view: string;         // 模板名 —— 决定 meta 的形状
+  config?: {
+    ctime: number;      // unix 秒
+    token: string;      // 卡片签名 token
+  };
+}
+```
+
+典型读法：
+
+```ts
+const payload = JSON.parse(el.arkData) as ArkPayload;
+if (payload.view === 'pubAdArkView') {
+  const t = payload.meta.template3 as Record<string, unknown>;
+  // ...
+}
+```
+
+## 三、样例：`view: "pubAdArkView"`
+
+代码里保留了一份实际抓取的完整样例
+（`packages/codec/src/element/ark.ts` 的 `SAMPLE_GAME_CENTER_AD`），
+是推送进聊天的 QQ 游戏中心广告，`meta` 下挂 `template3`：
+
+| 字段 | 说明 |
+| ---- | ---- |
+| `arkType` | 具体子模板，如 `pubSinglePicArk` |
+| `title` / `contentText` | 标题 / 正文 |
+| `coverUrl` | 封面图 |
+| `url` | 点击跳转地址 |
+| `appid` / `adId` / `actId` / `feedId` | 各类业务 id |
+| `time` | 时间戳（字符串形式） |
+| `__preloadFields` | 客户端预加载提示，值为需要预取的字段名 |
+
+> 想支持新的卡片样式，就在 `ark.ts` 里再加一个样例常量：把逆向出来的 `view`
+> 与对应 `meta` 形状固化下来，避免每次都重新猜。
+
+---
+
+## 四、渲染：`app` 才是真正的判别式
+
+上面说 `view` 决定 `meta` 的形状，那是从 JSON 文档自身看。但**渲染**这一侧，
+WeQ 的判别式是 `app`（如 `com.tencent.structmsg`）而不是 `view`——
+因为 QQ 官方的 ark 资源包本身就是按 app 组织的。
+
+渲染链路（`apps/desktop/src/renderer/src/components/ark/`）：
+
+| 文件 | 职责 |
+| ---- | ---- |
+| `ark-cards.generated.json` | **机械提取**的绑定表：`app → metaKey → { jump, slots, bindings }` |
+| `arkCards.ts` | 在其上叠加**人工策展**（布局归类 + 标准字段兜底），产出渲染器直接消费的 `ArkValues` |
+| `QqArk.tsx` | 按布局类型渲染 |
+
+### 数据从哪来
+
+`ark-cards.generated.json` 由 `scripts/extract-ark-cards.mjs` 从 QQ 官方 ark 资源包
+（`resources/arks_resource/<app>/<时间戳>/index.js`）机械提取：
+
+- 每个 `index.js` 用 `_setViewTemplate('<id>', \`<XML>\`)` 注册布局模板；
+- 用 Lua 的 `ViewModel:OnSetMetadata(value)` 定义 `data["字段"] → self.<节点>` 的绑定。
+
+脚本只抽取静态渲染需要的「排版 + 字段绑定」，运行时 Lua 逻辑、网络请求、动效一律忽略。
+
+> ⚠️ 原始资源包约 25MB，提取完成后已从仓库删除，只保留脚本与生成的 JSON。
+> 需要重新生成时得先把 ark 包放回 `resources/arks_resource/` 再跑
+> `node scripts/extract-ark-cards.mjs`。
+
+### 生成 JSON 的结构
+
+```jsonc
+{
+  "com.tencent.music.lua": {
+    "defaultMetaKey": "music",          // payload 没命中已知变体时的兜底
+    "variants": {
+      "music": {
+        "jump": "jumpUrl",              // 点击跳转取自 meta 的哪个字段
+        "slots": {                      // 自动归一化的「语义槽 → meta 字段」
+          "title": "title",
+          "desc": "desc",
+          "thumb": "preview",
+          "sourceIcon": "tagIcon"
+        },
+        "bindings": {                   // 原始的「模板节点 id → meta 字段」，未归一化
+          "titleView": "title",
+          "descView": "desc",
+          "background": "preview",
+          "tagIcon": "tagIcon"
+        }
+      }
+    }
+  }
+}
+```
+
+`slots` 与 `bindings` 的区别：`bindings` 是从 Lua 里原样抠出来的节点绑定，
+`slots` 是在其之上自动归一化出的语义槽位（长尾 app 的兜底）；
+常见 app 的权威槽位在 `arkCards.ts` 里手写覆盖。
+
+### 已收录的 16 个 app
+
+`defaultMetaKey` 是 payload 的 `meta` 里没有任何已知变体时的兜底选择。
+
+| app | 默认 metaKey | 变体 |
+| --- | ------------ | ---- |
+| `com.tencent.contact.lua` | contact | contact |
+| `com.tencent.miniapp.lua` | miniapp | miniapp |
+| `com.tencent.mobileqq.cardshare` | contact | contact |
+| `com.tencent.music.lua` | music | music |
+| `com.tencent.od` | pic | pic, news, music, video, contact, messages, miniapp |
+| `com.tencent.qidian.general` | pic | pic, transfercontact |
+| `com.tencent.qqgxh.general` | pic | pic, news, music, video, contact, messages, miniapp |
+| `com.tencent.qun.invite` | pic | pic, news, music, video, contact, messages, miniapp |
+| `com.tencent.structmsg` | news | news, music, video, contact, messages |
+| `com.tencent.tdoc.qqpush` | pic | pic, news, music, video, contact, messages, miniapp |
+| `com.tencent.template.qqfavorite.share` | news | news |
+| `com.tencent.tianxuan.share` | pic | pic, news, music, video, contact, messages, miniapp |
+| `com.tencent.together` | invite | invite |
+| `com.tencent.troopsharecard` | pic | pic, news, music, video, contact, messages, miniapp |
+| `com.tencent.tuwen.lua` | news | news |
+| `com.tencent.weishi.public.share` | pic | pic, news, music, video, contact, messages, miniapp |
+
+### 布局归类
+
+布局**不进** JSON —— 刻意保持「机械提取的数据」与「人工策展」分离。
+`arkCards.ts` 里有两张表，按下面的优先级决定用哪种布局：
+
+1. **`APP_LAYOUT`** — 单一用途的 app 直接钉死布局（覆盖 metaKey 推断）：
+
+   | app | 布局 |
+   | --- | ---- |
+   | `com.tencent.miniapp.lua` | appBlock |
+   | `com.tencent.contact.lua` | contact |
+   | `com.tencent.mobileqq.cardshare` | contact |
+   | `com.tencent.music.lua` | news |
+   | `com.tencent.tuwen.lua` | news |
+   | `com.tencent.together` | mediaBlock |
+
+2. **`METAKEY_LAYOUT`** — 多模板分享类 app（structmsg / troopsharecard / …）按变体名推断：
+
+   | metaKey | 布局 |
+   | ------- | ---- |
+   | news / music / video / messages / pic | news |
+   | contact / transfercontact | contact |
+   | miniapp | appBlock |
+   | invite | mediaBlock |
+
+3. 两张表都没命中 → `generic`（仍然带槽位值，好过纯猜）。
+
+### 语义槽位
+
+归一化后交给渲染器的字段（`ArkValues`）：
+
+| 槽位 | 含义 |
+| ---- | ---- |
+| `title` / `desc` / `summary` | 标题 / 描述 / 摘要 |
+| `thumb` | 小方缩略图 |
+| `cover` | 通栏大图 |
+| `name` / `avatar` | 名称 / 头像（联系人类卡片） |
+| `source` / `sourceIcon` | 顶部主来源标签文字 / 图标 |
+| `footerSource` / `footerIcon` | 底部来源标签（部分卡片顶底各有一个来源，如小程序顶=来源、底=「QQ小程序」） |
+| `button` | 按钮文案 |
+| `jump` | 点击跳转地址 |
 
-<!-- TODO: 列出该 element 的 protobuf 字段号、类型、含义 -->
+槽位没覆盖到的，再用 QQ 通用字段名兜底（各卡字段命名高度一致），
+按顺序尝试，例如 `desc` 依次试 `desc` → `digest` → `contactInfo` → `contact` → `address`，
+`jump` 依次试 `jumpUrl` → `qqdocurl` → `url`。
 
 ---
 
diff --git a/docs/database/nt_msg/elements/call.md b/docs/database/nt_msg/elements/call.md
index 0d717d76..0d460c91 100644
--- a/docs/database/nt_msg/elements/call.md
+++ b/docs/database/nt_msg/elements/call.md
@@ -1,12 +1,115 @@
 # elementType 21 — 通话记录
 
-> 🚧 骨架待补充。
-
 对应 WeQ 解析实现：`packages/codec/src/proto/msg/element.ts`（`elementType = 21`）。
+枚举定义：`packages/codec/src/element/types.ts`（`CallType` / `CallSubType`）。
+
+音视频通话记录（QQ 内部名 AVRECORD）：语音通话、视频通话、屏幕共享、远程协助的结果条目。
+
+> ⚠️ **私聊与群聊是两套结构**，`subType` 的编号也不互通，详见第四节。
+
+---
+
+## 一、字段
+
+| tag | 字段名 | 类型 | 必有 | 含义 |
+| --- | ------ | ---- | ---- | ---- |
+| 48151 | `answerType` | uint32 | ✅ | 接听 / 挂断类型，与 `subType` 一致，取值见 `CallSubType` |
+| 48152 | `duration` | uint32 | ✅ | **通话时长（毫秒）**，但旧版客户端写的是时间戳，见下方说明 |
+| 48154 | `callMethod` | uint32 | ✅ | **通话方式**，见下表 |
+| 48157 | `callSummary` | string（repeated） | ✅ | 通话摘要文案 |
+| 48153 | `callFlag48153` | string | | 协议标志（长度分隔）。实测恒等于 `callSummary` 去掉前缀后的正文 |
+| 48155 | `callUnknownType` | uint32 | | 未知类型标志。观测到 0 / 1 / 2 或缺失 |
+| 48156 | `callFlag48156` | uint32 | | 协议标志。可当作**客户端世代标记**：旧版写 0，新版写 1 |
+
+> ⚠️ `48152` 的单位是**毫秒**，与语音元素的 `45906`（秒）不同。
+
+### `duration` 的世代差异（坑）
+
+2025 年前后 QQ 重构过通话模块，`48152` 的语义跟着变了：
+
+| 世代 | `callFlag48156` | `duration` 实际内容 | `callSummary` 形态 |
+| ---- | --------------- | ------------------- | ------------------ |
+| 旧版 | `0` | **unix 秒级时间戳**（如 `1726891067`） | 带方式前缀：`[语音通话] 通话时长 00:35` |
+| 新版 | `1` | 毫秒时长（如 `1001` = 00:01） | 无前缀：`通话时长 00:01` |
+
+所以**不要直接拿 `duration` 格式化时长** —— 旧记录会算出荒谬的值。渲染一律优先用
+QQ 已经排好版的 `callSummary`（WeQ 的 `QqCall` 就是这么做的）。
+
+## 二、`callMethod`（48154）
+
+| 值 | 名称 | 说明 |
+| -- | ---- | ---- |
+| 0 | GROUP_ENDED | **群聊**「通话已结束」提示，无方式字段；具体是语音还是视频只能看 `subType` |
+| 1 | VOICE | 语音通话 |
+| 2 | VIDEO | 视频通话 |
+| 3 | SCREEN_SHARE | 屏幕共享 |
+| 5 | REMOTE_ASSIST | 远程协助 |
+
+## 三、`subType` / `answerType`
+
+`45003 (subType)`、`48151 (answerType)` 与消息行的 `40012` 列三者取值一致，合起来
+描述「什么类型的通话、以什么方式结束」。
+
+### 私聊（c2c_msg_table）
+
+一条消息 = 一整通电话的**最终状态**，中间过程不落库。
+
+| 值 | 名称 | 摘要文案 | 说明 |
+| -- | ---- | -------- | ---- |
+| 2 | VIDEO_ACCEPTED | 通话时长 xx:xx | 视频通话已接通 |
+| 3 | VIDEO_REJECTED_BY_US | 未接听，点击回拨 | 视频通话被本方拒绝 |
+| 5 | VIDEO_ACCEPTED_LEGACY | [视频通话] 通话时长 xx:xx | 视频接通，**旧版客户端编号**，语义同 2 |
+| 6 | VIDEO_REJECTED_BY_PEER | 对方已拒绝 | 视频通话被对方拒绝 |
+| 7 | VOICE_ACCEPTED | 通话时长 xx:xx | 语音通话已接通 |
+| 8 | VOICE_REJECTED_BY_US | 未接听，点击回拨 | 语音通话被本方拒绝 |
+| 9 | VOICE_PEER_NO_ANSWER | 对方未接听 | 我方拨出、对方一直没接（**旧版客户端**） |
+| 10 | VOICE_CANCELED_BY_US | 已取消，点击重拨 | 我方拨出后自己取消 |
+| 11 | VOICE_REJECTED_BY_PEER | 对方已拒绝 | 语音通话被对方拒绝 |
+| 12 | VIDEO_HANDLED_OTHER_DEVICE | 已在其他设备处理 | 视频通话已在其它设备处理 |
+| 13 | VOICE_HANDLED_OTHER_DEVICE | 已在其他设备处理 | 语音通话已在其它设备处理 |
+| 19 | SCREEN_SHARE_ACCEPTED | 通话时长 xx:xx | 屏幕共享已接通 |
+| 22 | SCREEN_SHARE_REJECTED | 对方未接听 | 屏幕共享被拒绝 |
+| 33 | REMOTE_ASSIST_ACCEPTED | 远程协助时长 xx:xx | 远程协助已接通 |
+| 34 | REMOTE_ASSIST_FAILED | 已取消，点击重新发起 | 远程协助失败 |
+
+> 5 / 9 是旧版客户端才写的编号（`callFlag48156 = 0`），2025 年后的记录不再出现。
+> 保留是为了历史消息能正确渲染。
+
+### 群聊（group_msg_table）
+
+**拆成两条独立消息**，中间状态（谁加入、谁离开、通了多久）一概不落库：
+
+| 值 | 名称 | `callMethod` | 40020（发送者） | 摘要文案 |
+| -- | ---- | ------------ | --------------- | -------- |
+| 1 | GROUP_VOICE_STARTED | 1 (VOICE) | 发起人 uid | 发起了语音通话 |
+| 26 | GROUP_VIDEO_STARTED | 2 (VIDEO) | 发起人 uid | 发起了视频通话 |
+| 16 | GROUP_VOICE_ENDED | **0** | **空** | 语音通话已结束 |
+| 25 | GROUP_VIDEO_ENDED | **0** | **空** | 视频通话已结束 |
+
+结束那条的 `40020` / `40033` 都是空的 —— 它不属于任何人，QQ 电脑端也把它画成居中
+灰条。另外**只有本机发起的通话才会写「发起」消息**：别人在群里发起时本机只收得到
+结束提示，所以历史记录里「结束」往往比「发起」多。
+
+## 四、渲染约定（WeQ）
+
+| 场景 | 组件 | 形态 |
+| ---- | ---- | ---- |
+| 私聊全部 | `QqCall` | 气泡内联：图标 + `callSummary`，失败/拒绝/未接标红 |
+| 群聊「发起」(1/26) | `QqCall` | 同上，气泡带发起人头像与昵称 |
+| 群聊「已结束」(16/25) | `GroupCallEndedMessage` | 居中灰条，无发送者 |
+
+分流在 `apps/desktop/src/renderer/src/im-template/template/chatPane.tsx` 的
+`grayTipOf()` 里：CALL 元素且 `subType ∈ {16, 25}` 的走灰条 band，其余照常走气泡。
+
+## 五、排查工具
 
-## 字段
+```bash
+# 全表扫描，统计 (callMethod, subType) 组合并列出未枚举值的会话与时间
+pnpm tsx packages/db/tools/scan_call_types.ts
 
-<!-- TODO: 列出该 element 的 protobuf 字段号、类型、含义 -->
+# 解码指定 msgId 的 CALL 元素（含原始 hex）
+pnpm tsx packages/db/tools/dump_call_element.ts <msgId> [<msgId> ...]
+```
 
 ---
 
diff --git a/docs/database/nt_msg/elements/emoji-bounce.md b/docs/database/nt_msg/elements/emoji-bounce.md
index e375d20e..14743466 100644
--- a/docs/database/nt_msg/elements/emoji-bounce.md
+++ b/docs/database/nt_msg/elements/emoji-bounce.md
@@ -1,12 +1,33 @@
 # elementType 27 — 弹射表情
 
-> 🚧 骨架待补充。
-
 对应 WeQ 解析实现：`packages/codec/src/proto/msg/element.ts`（`elementType = 27`）。
 
-## 字段
+表情弹射（QQ 内部名 FACEBUBBLE）—— 会「弹进」聊天窗口的动画表情。tag 段为 `521xx`。
+
+---
+
+## 一、字段
+
+下列字段在 EMOJI_BOUNCE element 上都是必有的。
+
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 52132 | `emojiBounceId` | uint32 | 弹射表情 id |
+| 52133 | `emojiBounceFlag52133` | bool | 未知布尔标志 |
+| 52134 | `emojiBounceName` | string | 弹射表情名称 |
+| 52137 | `emojiBounceDetail` | message | 嵌套详情，见下 |
+| 52138 | `emojiBounceTextSummary` | string | **文本总结（含弹射个数）** |
+| 52139 | `emojiBouncePcText` | string | 电脑端显示文本 |
+
+## 二、`emojiBounceDetail`（52137）
+
+冗余地重复了一份表情名称与文本摘要：
 
-<!-- TODO: 列出该 element 的 protobuf 字段号、类型、含义 -->
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 52142 | `flag52142` | uint32 | 未知 |
+| 52143 | `name` | string | 名称（同 52134） |
+| 52144 | `textSummary` | string | 文本摘要（同 52138） |
 
 ---
 
diff --git a/docs/database/nt_msg/elements/face.md b/docs/database/nt_msg/elements/face.md
index d1a4c40f..7ee362aa 100644
--- a/docs/database/nt_msg/elements/face.md
+++ b/docs/database/nt_msg/elements/face.md
@@ -1,12 +1,69 @@
 # elementType 6 — 系统表情
 
-> 🚧 骨架待补充。
-
 对应 WeQ 解析实现：`packages/codec/src/proto/msg/element.ts`（`elementType = 6`）。
 
-## 字段
+QQ 自带表情，包含普通小黄脸、超级表情、互动表情。
+（**商城表情**是另一个类型，见 [mface](./mface.md)。）
+
+---
+
+## 一、subType
+
+| 值 | 名称 | 说明 |
+| -- | ---- | ---- |
+| 1 | QQ_BUILTIN_OLD | 旧版内置表情 |
+| 2 | QQ_BUILTIN_NEW | 新版内置表情 |
+| 3 | SUPER_EMOJI | 超级表情（会带 `476xx` 的超级表情字段） |
+| 4 | UNKNOWN_4 | 未知 |
+| 5 | INTERACTIVE | 互动表情 |
+
+## 二、必有字段
+
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 47601 | `faceId` | uint32 | 表情 id（例：骰子 `FaceIndex.DICE = 358`） |
+| 47602 | `faceText` | string | 表情文字描述 |
+
+## 三、超级表情
+
+仅 subType=3 时出现。
+
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 47603 | `superEmojiCategory` | string | 超级表情分类 |
+| 47604 | `AniStickerId` | string | 动画贴纸 ID |
+| 47605 | `superEmojiFlag1` | uint32 | 标志 1 |
+| 47606 | `superEmojiFlag2` | uint32 | 标志 2 |
+| 47607 | `diceValue` | string | **命名为骰子点数**，实际上是随机表情的随机值<br />包括骰子，包剪锤，篮球等等 |
+| 47609 | `superEmojiFlag3` | uint32 | 标志 3 |
+| 47610 | `superEmojiFlag4` | uint32 | 标志 4 |
+
+## 四、其它可选字段
+
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 45004 | `faceExtDesc` | string | 扩展描述（注意这个 tag 落在通用段而非 476xx 段） |
+| 47608 | `faceFlag47608` | bytes | 未知的长度分隔字段 |
+| 47622 | `canChain` | bool | 该表情是否支持连锁反应 |
+
+## 五、`47611..47621` —— 几乎每个表情都会捎带的一块
+
+不论 subType 如何，这一块基本都会出现在 FACE element 上。其中只有
+`47612` / `47615` / `47616` / `47621` 真正携带内容，其余是标志位，绝大多数行里为 0。
 
-<!-- TODO: 列出该 element 的 protobuf 字段号、类型、含义 -->
+| tag | 字段名 | 类型 | 含义 / 观测 |
+| --- | ------ | ---- | ----------- |
+| 47611 | `faceFlag47611` | uint32 | 多数为 0/1，偶见 2..6 或 126 |
+| 47612 | `interactiveFaceName` | string | **互动表情名称**，如「模了个块」。通常为空 |
+| 47613 | `faceFlag47613` | uint32 | 恒为 0（有一行为 1） |
+| 47614 | `faceFlag47614` | uint32 | 恒为 0（有三行为 2003） |
+| 47615 | `interactiveFaceName2` | string | 互动表情名称副本 —— 所有观测行都与 47612 相同 |
+| 47616 | `interactiveFaceVersion` | string | **互动表情版本号**，如 `7.2.0`。通常为空 |
+| 47617 | `faceFlag47617` | uint32 | 取值 0/1/2/3 |
+| 47618 | `faceFlag47618` | uint32 | 恒为 0 |
+| 47619 | `faceFlag47619` | uint32 | 恒为 0 |
+| 47620 | `faceFlag47620` | uint32 | 恒为 0 |
+| 47621 | `faceFallbackText` | string | **旧版客户端降级文案**，如「[戳一戳]请使用最新版手机QQ体验新功能。」。所有客户端都能渲染的表情上为空 |
 
 ---
 
diff --git a/docs/database/nt_msg/elements/file.md b/docs/database/nt_msg/elements/file.md
index 497d340e..e35f0079 100644
--- a/docs/database/nt_msg/elements/file.md
+++ b/docs/database/nt_msg/elements/file.md
@@ -1,12 +1,59 @@
 # elementType 3 — 文件
 
-> 🚧 骨架待补充。
-
 对应 WeQ 解析实现：`packages/codec/src/proto/msg/element.ts`（`elementType = 3`）。
 
-## 字段
+通用文件传输。大量复用「文件族」共用 tag，共用部分见
+[40800 总览 · 第五节](../40800.md#五跨类型共用的文件族字段)。
+
+---
+
+## 一、复用自文件族的字段
+
+| tag | 字段名 | 说明 |
+| --- | ------ | ---- |
+| 45402 | `fileName` | 文件名 |
+| 45403 | `filePath` | 本地路径 |
+| 45405 | `fileSize` | 字节数 |
+| 45406 | `md5Bytes` | 二进制 MD5 |
+| 45408 | `contentHash` | 内容校验 hash |
+| 45411 / 45412 | `imgWidth` / `imgHeight` | 宽高（图片类文件才有意义） |
+| 45415 | `fileFlag45415` | 文件相关标识 |
+| 45503 | `fileToken` | 下载凭据 |
+| 45504 | `transferFlag45504` | 传输标志（string） |
+| 45505 | `uploadTime` | 上传 / 处理时间戳 |
+| 45510 | `videoToken` | 下载 token |
+| 45511 | `picTransferState` | 传输状态 |
+| 45513 | `transferVersion` | 传输版本 |
+| 45550 | `transferState` | 传输状态 |
+
+> `45510` 曾被误标为 `fileFlag45510`，实为下载 token，VIDEO 与 FILE 共用。
+
+## 二、FILE 专属字段
+
+### 必有
+
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 45003 | `subType` | uint32 | 文件类型判别式，观测到约 20 种取值，尚未逐一映射（代码里留有 `FileSubType` 的 TODO） |
+| 45407 | `md5Bytes2` | bytes | 第二份 MD5，形状与作用同 45406 |
+| 45409 | `fileFlag45409` | bytes | 未知字节串 |
+| 45501 | `fileFlag45501` | uint32 | 未知整数（可能是 bool） |
+| 45512 | `fileFlag45512` | bool | 未知布尔标志 |
+| 45514 | `fileFlag45514` | bool | 未知布尔标志 |
+
+### 可选
 
-<!-- TODO: 列出该 element 的 protobuf 字段号、类型、含义 -->
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 45554 | `transferErrorText` | string | 人类可读的传输错误，如「传输失败，请稍后重试」 |
+| 45533 | `fileFlag45533` | uint32 | 仅在一条 subType=4 的行上观测到（值为 2） |
+| 45951 | `fileThumbPathRemote` | string | **发送端**的缩略图路径（手机端，`.thumbnails/…`） |
+| 45953 | `fileThumbPathRemote2` | string | 发送端的第二个缩略图路径（`qlarge-dsc-…`） |
+| 45954 | `fileThumbLocalPath` | string | 本机缓存的缩略图路径（`nt_data/File/Thumb/…`） |
+| 45966 | `fileFlag45966` | bytes | 所有观测行均为空 |
+| 45967 | `fileFlag45967` | bytes | 所有观测行均为空 |
+| 45968 | `fileGroupMeta` | bytes | 群文件元数据块（上传者 uin / 昵称、文件 uuid、上传时间…）。仅观测到一次，子 tag 未验证，故保留为原始字节 |
+| 45507 / 45509 | 传输标记 | | 见总览 |
 
 ---
 
diff --git a/docs/database/nt_msg/elements/gray-tip.md b/docs/database/nt_msg/elements/gray-tip.md
index d69e06cf..7686cc1c 100644
--- a/docs/database/nt_msg/elements/gray-tip.md
+++ b/docs/database/nt_msg/elements/gray-tip.md
@@ -1,12 +1,353 @@
 # elementType 8 — 灰字提示
 
-> 🚧 骨架待补充。
-
 对应 WeQ 解析实现：`packages/codec/src/proto/msg/element.ts`（`elementType = 8`）。
 
-## 字段
+「小灰条」是聊天中居中显示的那一行灰色提示：撤回、拍一拍、入群、禁言、临时会话……
+它们**共用一个 elementType**，靠 `45003 (subType)` 再分一次类，
+而不同 subType 使用的 tag 段**几乎不重叠**——实际上是六种完全不同的结构挤在同一个类型下。
+
+---
+
+## 一、subType 全表
+
+名字取自 QQ NT 的 `NTGrayTipElementSubTypeV2` 枚举。
+目前只观测到 1 / 4 / 10 / 12 / 15 / 17；其余声明出来只为将来遇到时有名字可对。
+
+| 值 | 名称 | WeQ 的 kind | 说明 | tag 段 |
+| -- | ---- | ----------- | ---- | ------ |
+| 0 | UNKNOWN | — | 占位（未观测） | — |
+| 1 | REVOKE | `grayTipRevoke` | **撤回提示**（「XX 撤回了一条消息」） | `477xx` |
+| 2 | PROCLAMATION | — | 群公告（未观测） | — |
+| 3 | EMOJI_REPLY | — | 表情回应（未观测） | — |
+| 4 | GROUP_TIP | `grayTipGroup` | **群通知**：入群 / 退群 / 禁言 / 改群名 | `485xx` |
+| 5 | BUDDY | — | 好友相关提示（未观测） | — |
+| 6 | FEED | — | 动态 Feed 提示（未观测） | — |
+| 7 | ESSENCE | — | 设为精华消息（未观测） | — |
+| 8 | GROUP_NOTIFY | — | 群通知（系统下发，未观测） | — |
+| 9 | BUDDY_NOTIFY | — | 好友通知（系统下发，未观测） | — |
+| 10 | FILE | `grayTipFileRecv` | **文件接收完成灰条** | 文件族 `454xx/455xx` |
+| 11 | FEED_CHANNEL_MSG | — | 频道消息 Feed（未观测） | — |
+| 12 | XML_MSG | `grayTipInvite` | **XML 灰条**（通用 XML 消息） | `482xx` |
+| 13 | LOCAL_MSG | — | 本地消息，仅本端可见（未观测） | — |
+| 14 | BLOCK | — | 拉黑相关（未观测） | — |
+| 15 | AIO_OP | `grayTipTempSession` | **临时会话提示** | `475xx` |
+| 16 | WALLET | — | 钱包相关（未观测） | — |
+| 17 | JSON | `grayTipPoke` | **JSON 灰条**：拍一拍、互动标识 | `482xx` |
+
+> 历史上 subType=12 曾被 WeQ 当作「邀请」处理，故 kind 名叫 `grayTipInvite`；
+> 实际它是通用的 XML 灰条。
+
+---
+
+## 二、subType=1 — 撤回
+
+| tag | 字段名 | 类型 | 必有 | 含义 |
+| --- | ------ | ---- | ---- | ---- |
+| 47702 | `recallFlag47702` | uint32 | ✅ | 未知整数 |
+| 47703 | `recallRevokeUid` | string | ✅ | **撤回操作者** uid |
+| 47704 | `recallSenderUid` | string | ✅ | **被撤回消息发送者** uid |
+| 47705 | `recallSenderNick` | string | ✅ | 被撤回者昵称 |
+| 47713 | `recallDisplayText` | string | ✅ | 撤回展示文案 |
+| 47714 | `recallRevokeNick` | string | ✅ | 撤回者昵称 |
+| 47710 | `recallElements` | repeated `ReplyElementWire` | | 被撤回消息的原始 element 副本。**只在撤回自己的消息时才有** |
+| 47711 | `recallFlag47711` | uint32 | | 未知整数 |
+| 47712 | `recallFlag47712` | uint32 | | 两条观测行均为 1 |
+
+### 六个昵称字段的关系
+
+`47706/47715` 是昵称副本，`47707/47716` 装的是**群名片**。这一点在一次群撤回上得到验证：
+该用户昵称为「🍬🐱帕罗丁，然后8年之誓」，而群名片是「期中考试加油」，两者确实不同。
+
+QQ 会**同时写一份「被撤回者」副本和一份「撤回者」副本**，即使两者是同一个人。
+所以自己撤回自己的消息时，这六个字段值全部一致。
+
+| tag | 字段名 | 归属 | 含义 |
+| --- | ------ | ---- | ---- |
+| 47705 | `recallSenderNick` | 被撤回者 | 昵称 |
+| 47706 | `recallSenderNickCopy` | 被撤回者 | 昵称副本（同 47705） |
+| 47707 | `recallSenderGroupNick` | 被撤回者 | **群名片**（群里与昵称不同） |
+| 47714 | `recallRevokeNick` | 撤回者 | 昵称 |
+| 47715 | `recallRevokeNickCopy` | 撤回者 | 昵称副本（同 47714） |
+| 47716 | `recallRevokeGroupNick` | 撤回者 | **群名片** |
+
+---
+
+## 三、subType=4 — 群通知
+
+| tag | 字段名 | 类型 | 必有 | 含义 |
+| --- | ------ | ---- | ---- | ---- |
+| 48501 | `groupTipType` | uint32 | ✅ | 事件类型，见下表 |
+| 48503 | `user1Uid` | string | | 用户 1 uid |
+| 48504 | `user1Nick` | string | | 用户 1 昵称 |
+| 48505 | `user1GroupNick` | string | | 用户 1 群名片 |
+| 48506 | `user2Uid` | string | | 用户 2 uid |
+| 48507 | `user2Nick` | string | | 用户 2 昵称 |
+| 48508 | `user2GroupNick` | string | | 用户 2 群名片 |
+| 48509 | `groupTipGroupName` | string | | **群名称** —— 出现在「XX 邀请你加入 &lt;群名&gt;」这类提示上（该群不是当前会话） |
+| 48541 | `muteInfo` | message | | 禁言详情，见下 |
+| 48542 | `grayTipTimestamp` | uint32 | | 提示时间戳，unix 秒。约 9700 个不同取值，均与消息自身发送时间一致 |
+
+### `groupTipType`（48501）
+
+名字取自 QQ NT 的 `TipGroupElementType` 枚举。本地库里出现过 1/2/3/5/8。
+
+| 值 | 名称 | 说明 |
+| -- | ---- | ---- |
+| 0 | KUNKNOWN | 占位（未观测） |
+| 1 | KMEMBERADD | **成员入群**：user1 是新成员，user2 是邀请人（无邀请人时 QQ 只写 user1） |
+| 2 | KDISBANDED | 群已解散 |
+| 3 | KQUITTE | **成员被移出群聊**：user1Nick 是操作者昵称，user2Uid 是被移出者 |
+| 4 | KCREATED | 群创建成功（未观测） |
+| 5 | KGROUPNAMEMODIFIED | **群名被修改**：user1 是操作者，`groupTipGroupName` 是新群名 |
+| 6 | KBLOCK | 成员被拉黑（未观测） |
+| 7 | KUNBLOCK | 成员被移出黑名单（未观测） |
+| 8 | KSHUTUP | **禁言**：详情在 `muteInfo`，时长为 0 表示解除禁言 |
+| 9 | KBERECYCLED | 群因违规被回收（未观测） |
+| 10 | KDISBANDORBERECYCLED | 群被解散或被回收（未观测） |
+
+### `muteInfo`（48541）
+
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 48521 | `operator` | message | 操作者，内含 `1000: uid` |
+| 48522 | `mutedUser` | message | 被禁言者，内含 `1000: uid`、`20002: groupNick` |
+| 48531 | `timestamp` | uint64 | 时间戳 |
+| 48532 | `duration` | uint32 | **禁言时长（秒）**，0 = 解除 |
+
+### 未验证
+
+| tag | 字段名 | 观测情况 |
+| --- | ------ | -------- |
+| 48502 | `groupTipFlag48502` | 取值 0/1/2 |
+| 48510 | `groupTipFlag48510` | 只要出现就恒为 1 |
+| 48511 | `groupTipFlag48511` | 取值 0（×2874）/ 2 / 1 / 3 |
+
+---
+
+## 四、subType=10 — 文件接收完成
+
+结构上是一个**披着 elementType=8 外壳的 FILE element**：它复用 `454xx/455xx` 文件族 tag，
+一个灰条专属字段都没有。QQ 把它作为一条独立的行，写在真正的 FILE 消息旁边。
+
+已验证：发送者（行级 `40020`）**永远是对端，绝不是本账号**，
+所以它表达的是「对方发来的文件已接收完成」。
+行级 msgType 为 `40011=5 / 40012=1`（系统提示）或 `40011=1 / 40012=2`。
+
+| tag | 字段名 | 类型 | 必有 |
+| --- | ------ | ---- | ---- |
+| 45402 | `fileName` | string | ✅ |
+| 45405 | `fileSize` | uint32 | ✅ |
+| 45407 | `md5Bytes2` | bytes | |
+| 45503 | `fileToken` | string | |
+| 45411 / 45412 | `imgWidth` / `imgHeight` | uint32 | |
+| 45410 | `videoDuration` | uint32 | |
+
+> `fileName` 在 wire 上出现了两次，WeQ 取第一个。
+
+---
+
+## 五、subType=15 — 临时会话
+
+QQ 渲染为「该用户通过 xxx 群聊向你发起临时会话」。
+恒为一个 C2C 会话的**首条消息**（seq=1），且该行本身不带发送者（`40020` 为空）。
+
+| tag | 字段名 | 类型 | 必有 | 含义 |
+| --- | ------ | ---- | ---- | ---- |
+| 47502 | `tempSessionGroupCode` | string | ✅ | **发起临时会话的来源群号**（十进制字符串） |
+| 47501 | `aioOpFlag47501` | uint32 | | 恒为 1，疑似提示变体标识 |
+| 40021 | `origReceiverUid` | string | | 行级对端 uid 的冗余副本 |
+
+> `47502` 已验证确实是群号而非对方 QQ 号：所有观测值在 `group_msg_table` 里都有真实群聊记录，
+> 且没有一个与对端自身 uin 相同。
+
+---
+
+## 六、subType=17（JSON）与 subType=12（XML）
+
+这两者共用 `482xx` 段。subType=17 是拍一拍、互动标识（畅聊之火 / 初泛涟漪）等；
+subType=12 是通用 XML 灰条。
+
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 48210 | `actionInitiator` | message | **动作发起者**，内含 `1005: uid`、`1006: nickname` |
+| 43210 | `actionTarget` | message | **动作目标**，结构同上 |
+| 48211 | `actionId` | uint32 | 动作类型 id。观测到 12（拍一拍）、16（红包） |
+| 48212 | `detailedId` | uint32 | 详细动作 id。1=系统，1061=拍一拍，19357=红包 |
+| 48213 | `typeFlag` | uint32 | 类型标志。观测到 7 |
+| 48214 | `grayTipXmlContent` | string | **XML 预览文档** |
+| 48215 | `businessId` | uint32 | **业务 id**，见下方 `JsonGrayBusiId` 全表。观测到 1132 |
+| 48216 | `actionUniqueId` | uint32 | 本次动作的唯一 id |
+| 48217 | `actionAttributes` | repeated message | 附加属性，每项 `{1005: key, 1006: value}` |
+| 48271 | `tipJson` | string | **提示的 JSON 负载**（subType=17 必有） |
+| 48273 | `tipType` | uint32 | 提示类型，1=系统，与 `detailedId` 对应 |
+| 48274 | `grayTipPlainText` | string | **互动标识提示原文**，如「你和XX互发消息连续超过7天，已获得畅聊之火标识」。`tipJson` 的纯文本版 |
+| 48542 | `grayTipTimestamp` | uint32 | 提示时间戳 |
+
+### `tipJson`（48271）的形状
+
+```jsonc
+{
+  "items": [
+    { "type": "nor", "txt": "文本片段" },
+    { "type": "qq",  "uid": "u_xxx", "col": "#ff0000", "jp": "跳转协议" },
+    { "type": "img", "src": "图片地址" },
+    { "type": "url", "txt": "链接文字", "jp": "跳转地址" }
+  ]
+}
+```
+
+`type` 已知 `img` / `qq` / `nor` / `url` 四种；`jp` 是点击跳转协议。
+
+### `grayTipXmlContent`（48214）的形状
+
+```xml
+<gtip align="...">
+  <qq uin="..." col="..." nm="..." tp="..."/>
+  <img src="..." />
+  <nor txt="..." />
+</gtip>
+```
+
+### 未验证
+
+| tag | 字段名 | 观测情况 |
+| --- | ------ | -------- |
+| 48218 | `grayTipReserved` | 保留字段（string） |
+| 48219 | `grayTipFlag48219` | 取值 0（×49）/ 1（×1） |
+| 48220 | `grayTipFlag48220` | 取值 0（×59）/ 64（×1） |
+| 48272 | `grayTipFlag48272` | 观测为 true |
+| 48275 | `grayTipFlag48275` | uint32，语义未知 |
+
+---
+
+## 七、`businessId`（48215）全表
+
+取值来自 QQ NT 自身的 `JsonGrayBusiId` 枚举 —— 它标识这条 JSON 灰条**由哪个业务下发**，
+决定了 `tipJson` 里的文案与跳转协议属于什么场景。本地样本只覆盖到其中极少数（如 1132），
+这里完整列出以便遇到时能直接对号入座。
+
+> ⚠️ 枚举仅记录在此文档，未进代码：解析层不依赖它，`48215` 照旧按裸数字解析。
+> 取值命名保留 QQ 原样。
+
+### 在线文件传输（1..13）
+
+| 值 | 名称 | 含义 |
+| -- | ---- | ---- |
+| 1 | ONLINE_FILE_STOP_SEND | 停止发送 |
+| 2 | ONLINE_FILE_STOP_SEND_ON_SENDING | 发送中停止发送 |
+| 3 | ONLINE_FILE_REFUSE_RECV | 拒绝接收 |
+| 4 | ONLINE_FILE_CANCEL_RECV_ON_RECVING | 接收中取消接收 |
+| 5 | ONLINE_FILE_STOP_ALL_SEND | 停止全部发送 |
+| 6 | ONLINE_FILE_STOP_ALL_SEND_ON_SENDING | 发送中停止全部发送 |
+| 7 | ONLINE_FILE_REFUSE_ALL_RECV | 拒绝接收全部 |
+| 8 | ONLINE_FILE_REFUSE_ALL_RECV_ON_RECVING | 接收中拒绝接收全部 |
+| 9 | ONLINE_FILE_SEND_ERROR | 发送出错 |
+| 10 | ONLINE_FILE_RECV_ERROR | 接收出错 |
+| 11 | ONLINE_FILE_GO_OFFLINE | 离线 |
+| 12 | ONLINE_FILE_GO_OFFLINE_ALL | 全部离线 |
+| 13 | ONLINE_FILE_RECV_BY_MOBILE | 已由手机接收 |
+
+### 杂项
+
+| 值 | 名称 | 含义 |
+| -- | ---- | ---- |
+| 51 | ONLINE_GROUP_HOME_WORK | 群作业 |
+| 81 | RED_BAG | 红包 |
+| 86 | LITE_ACTION | 轻量动作 |
+
+### 关系链（1000..1022）
+
+| 值 | 名称 | 含义 |
+| -- | ---- | ---- |
+| 1000 | RELATION_CHAIN_BLACKED | 被拉黑 |
+| 1001 | RELATION_EMOJIEGG_SHOW | 表情彩蛋展示 |
+| 1002 | RELATION_EMOJIEGG_WILL_DEGRADE | 表情彩蛋即将降级 |
+| 1003 | RELATION_C2C_LOVER_BONUS | 情侣加成 |
+| 1004 | RELATION_C2C_SAY_HELLO | 打招呼 |
+| 1005 | RELATION_C2C_GROUP_AIO_SETUP_GROUP_AND_REMARK | 设置分组与备注 |
+| 1006 | RELATION_FRIEND_CLONE_INFO | 好友克隆信息 |
+| 1007 | RELATION_CHAIN_MATCH_FRIEND | 匹配好友 |
+| 1008 | RELATION_NEARBY_GOTO_VERIFY | 附近的人去验证 |
+| 1009 | RELATION_CREATE_GROUP_GRAY_TIP_ID | 创建群聊 |
+| 1010 | RELATION_YQT | 一起听 |
+| 1011 | RELATION_LIMIT_TMP_CONVERSATION_SET | 临时会话限制设置 |
+| 1012 | RELATION_ONEWAY_FRIEND_GRAY_TIP_ID | 单向好友 |
+| 1013 | RELATION_ONEWAY_FRIEND_NEW_GRAY_TIP_ID | 单向好友（新） |
+| 1014 | RELATION_GROUP_SHUT_UP | 群禁言 |
+| 1015 | RELATION_GROUP_MEMBER_ADD_WITH_MODIFY_NAME | 加群成员并改名 |
+| 1016 | RELATION_GROUP_MEMBER_ADD_WITH_WELCOME | 加群成员并欢迎 |
+| 1017 | RELATION_C2C_MEMBER_ADD | 添加好友 |
+| 1018 | RELATION_C2C_REACTIVE_UPGRADE_MSG | 亲密度升级 |
+| 1019 | RELATION_C2C_REACTIVE_DEGRADE_MSG | 亲密度降级 |
+| 1020 | RELATION_GROUP_BATCH_ADD_FRIEND | 群内批量加好友 |
+| 1021 | RELATION_GROUP_MEMBER_RECOMMEND | 群成员推荐 |
+| 1022 | RELATION_GROUP_MEMBER_ADD | 加群成员 |
+
+### AIO 会话内提示（2000..2100）
+
+| 值 | 名称 | 含义 |
+| -- | ---- | ---- |
+| 2000 | AIO_RECALL_MSGCUSTOM_WORDINGGUIDE | 撤回自定义文案引导 |
+| 2021 | AIO_AV_C2C_NOTICE | 私聊音视频通知 |
+| 2022 | AIO_AV_GROUP_NOTICE | 群音视频通知 |
+| 2041 | AIO_NUDGE_CUSTOM_GUIDE | 拍一拍自定义引导 |
+| 2050 | AIO_CRM_FLAGS_TIPS | CRM 标识提示 |
+| 2060 | PTT_AUTO_CHANGE_GUIDE | 语音自动变声引导 |
+| 2100 | AIO_C2C_DONT_DISTURB | 私聊免打扰 |
+
+### Z-Plan / 机器人 / 推送（2201..2701）
+
+| 值 | 名称 | 含义 |
+| -- | ---- | ---- |
+| 2201 | AIO_ROBOT_SAFETY_TIP | 机器人安全提示 |
+| 2300 | AIO_ZPLAN_SEND_MEME | Z-Plan 发送梗图 |
+| 2301 | AIO_ZPLAN_EMOTICON_GUIDE | Z-Plan 表情引导 |
+| 2302 | AIO_ZPLAN_SCENE_LINKAGE | Z-Plan 场景联动 |
+| 2601 | QCIRCLE_SHOW_FULE_TIPS | 小世界提示 |
+| 2602 | QWALLET_GRAY_TIP_ID | QQ 钱包 |
+| 2603 | DISBAND_DISCUSSION_GRAY_TIP_ID | 解散讨论组 |
+| 2701 | AIO_PUSH_GUIDE_GRAY_TIPS | 推送引导 |
+
+### 群会话（2401..2408）
+
+| 值 | 名称 | 含义 |
+| -- | ---- | ---- |
+| 2401 | AIO_GROUP_ESSENCE_MSG_TIP | 群精华消息 |
+| 2402 | GROUP_AIO_SHUTUP_GRAY_TIP_ID | 群禁言 |
+| 2403 | GROUP_AIO_UPLOAD_PERMISSIONS_GRAY_TIP_ID | 群上传权限 |
+| 2404 | GROUP_AIO_HOME_SCHOOL_WELCOME_GRAY_TIP_ID | 家校群欢迎 |
+| 2405 | GROUP_AIO_TEMPORARY_GRAY_TIP_ID | 群临时会话 |
+| 2406 | GROUP_AIO_MSG_FREQUENCY_GRAY_TIP_ID | 群消息频率 |
+| 2407 | GROUP_AIO_CONFIGURABLE_GRAY_TIPS | 群可配置灰条 |
+| 2408 | GROUP_AIO_UNREAD_MSG_AI_SUMMARY | 群未读消息 AI 总结 |
+
+### 文件大小限制（3001..3003）
+
+| 值 | 名称 | 含义 |
+| -- | ---- | ---- |
+| 3001 | VAS_FILE_UPLOAD_OVER_LIMIT | 上传超出限制 |
+| 3002 | VAS_FILE_UPLOAD_OVER_1G | 上传超过 1G |
+| 3003 | FILE_SENDING_SIZE_4GB_LIMIT | 发送 4GB 限制 |
+
+### 群加好友 / 破冰（10405, 19264..19273）
+
+| 值 | 名称 | 含义 |
+| -- | ---- | ---- |
+| 10405 | TROOP_BREAK_ICE | 群破冰 |
+| 19264 | TROOP_ADD_FRIEND_ACTIVE | 加好友：活跃成员 |
+| 19265 | TROOP_ADD_FRIEND_HOT_CHAT | 加好友：热聊 |
+| 19266 | TROOP_ADD_FRIEND_REPLY_OR_AT | 加好友：回复或 @ |
+| 19267 | TROOP_ADD_FRIEND_NEW_MEMBER | 加好友：新成员 |
+| 19273 | TROOP_FLAME_IGNITED | 群火花点燃 |
+
+### 预留
+
+| 值 | 名称 | 含义 |
+| -- | ---- | ---- |
+| 100000 | UI_RESERVE_100000_110000 | UI 预留区间起点（100000–110000） |
 
-<!-- TODO: 列出该 element 的 protobuf 字段号、类型、含义 -->
+> 💡 WeQ 的[防撤回](../../../guide/anti-recall.md)功能正是构造一条 subType=17 的自定义灰条
+> 来记录被拦截的撤回事件。
 
 ---
 
diff --git a/docs/database/nt_msg/elements/markdown.md b/docs/database/nt_msg/elements/markdown.md
index 5f50eb3e..046495f4 100644
--- a/docs/database/nt_msg/elements/markdown.md
+++ b/docs/database/nt_msg/elements/markdown.md
@@ -1,12 +1,72 @@
 # elementType 14 — Markdown
 
-> 🚧 骨架待补充。
-
 对应 WeQ 解析实现：`packages/codec/src/proto/msg/element.ts`（`elementType = 14`）。
 
-## 字段
+富文本 markdown 消息，tag 段为 `487xx`。其中三个用于「QQ 闪传」的嵌套结构
+（`48707` / `48708` / `48711`）过于复杂，除 `48708` 外均保留为原始字节 ——
+它们属于可选边缘功能，逐字段维护的成本不划算。
+
+---
+
+## 一、必有字段
+
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 48701 | `markdownContent` | string | **markdown 正文** |
+| 48702 | `markdownMeta` | message | 元数据（构建时间戳、标志），见下 |
+| 48703 | `markdownFlag48703` | message | 嵌套标志块，见下 |
+| 48704 | `markdownFlag48704` | string | 未知的长度分隔字段 |
+| 48705 | `markdownTextSummary` | string | 文本摘要 |
+| 48706 | `markdownFlag48706` | uint32 | 未知整数标志 |
+
+## 二、`markdownMeta`（48702）
+
+这个嵌套块用的是**小 tag**（1..4）：
+
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 1 | `flag1` | uint32 | 未知 |
+| 2 | `buildTimestamp` | uint32 | 构建时间戳 |
+| 3 | `flag3` | bytes | 未知 |
+| 4 | `flag4` | uint32 | 未知 |
+
+## 三、`markdownFlag48703`（48703）
+
+与 `48702` 相反，这个嵌套块用的是**绝对 tag**（`487xx` 段）：
+
+| tag | 字段名 | 类型 |
+| --- | ------ | ---- |
+| 48720 | `field48720` | string |
+| 48721 | `field48721` | string |
+| 48722 | `field48722` | uint32 |
+
+> 同一个 element 里，一个嵌套块用小 tag、另一个用绝对 tag —— 这是 QQ 的实际做法，
+> 不是解析实现的笔误。
+
+## 四、QQ 闪传
+
+| tag | 字段名 | 类型 | 说明 |
+| --- | ------ | ---- | ---- |
+| 48707 | `flashTransferProto1` | bytes | 复杂嵌套结构，保留为原始字节 |
+| 48708 | `flashTransferInfo` | message | 已解析，见下 |
+| 48711 | `flashTransferProto3` | bytes | 复杂嵌套结构，保留为原始字节 |
+
+### `flashTransferInfo`（48708）
+
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 1 | `fileSetId` | string | 文件集 ID |
+| 2 | `thumbnailName` | string | 缩略图名称 |
+| 3 | `fileBytes` | uint32 | 文件字节数 |
+| 4 | `thumbAlt` | message | 缩略图备选，见下 |
+| 6 | `createTime` | uint32 | 创建时间 |
+
+`thumbAlt`（48708 → 4）：
 
-<!-- TODO: 列出该 element 的 protobuf 字段号、类型、含义 -->
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 1 | `fileId` | string | 文件 ID |
+| 2 | `urlInfo` | message | `{1: type(uint32), 2: url(string)}` |
 
 ---
 
diff --git a/docs/database/nt_msg/elements/mface.md b/docs/database/nt_msg/elements/mface.md
index 93197d5e..95935938 100644
--- a/docs/database/nt_msg/elements/mface.md
+++ b/docs/database/nt_msg/elements/mface.md
@@ -1,12 +1,76 @@
 # elementType 11 — 商城表情
 
-> 🚧 骨架待补充。
-
 对应 WeQ 解析实现：`packages/codec/src/proto/msg/element.ts`（`elementType = 11`）。
 
-## 字段
+商城表情（marketface / 商业贴纸）。它使用**完全独立的 `808xx / 809xx` tag 段**，
+与其它所有 element 类型都不重叠。
+
+---
+
+## 一、已理解的字段
+
+| tag | 字段名 | 类型 | 必有 | 含义 |
+| --- | ------ | ---- | ---- | ---- |
+| 80810 | `emojiPackId` | uint32 | ✅ | 表情包 ID |
+| 80900 | `emojiDesc` | string | ✅ | 表情描述文字，如 `[嗨]` |
+| 80901 | `mfaceType` | uint32 | ✅ | 表情类型 |
+| 80902 | `mfaceSubType` | bool | ✅ | 表情子类型标志 |
+| 80903 | `marketEmoticonId` | bytes | ✅ | **真正的贴纸 id**，也是磁盘上的文件名 |
+| 80905 | `mediaType` | uint32 | ✅ | 媒体类型标志 |
+| 80908 | `renderFlag` | bool | ✅ | 渲染标志 |
+| 80909 | `previewWidth` | uint32 | ✅ | 预览图宽 |
+| 80910 | `previewHeight` | uint32 | ✅ | 预览图高 |
+| 80935 | `isAnimated` | bool | ✅ | 是否动图 |
+| 80824 | `encryptKey` | string | | **本地 / CDN 加密表情图的解密密钥** |
+
+## 二、`encryptKey`（80824）—— 渲染无需爆破
+
+商城表情的图片文件（本地缓存与 CDN 上）都是**加密**的。关键结论是：
+
+> 消息 element 里自带的 `encryptKey` 就是 QQTEA 的 16 字节密钥
+> （形式为 `md5(时间戳)[:16]` 的 ASCII 串），拿它直接就能解密。
+
+这意味着渲染聊天记录里的商城表情**完全不需要爆破时间戳**。
+只有 `encryptKey` 为空的旧消息，才退化到「靠 `emojiPackId` 去 CDN + 爆破」的路子。
+
+CDN 地址由 `marketEmoticonId` 的十六进制串拼出：
+
+```text
+https://i.gtimg.cn/club/item/parcel/item/<hash前2位>/<hash>/<300_300 或 200_200>
+```
+
+解密流程（QQTEA，交织链式 CBC）：
+
+1. 取 `encryptKey` 的 16 个 ASCII 字节作为 TEA key；
+2. 按 8 字节分块做 16 轮大端 TEA 解密，前后块交织异或；
+3. 去头：第 1 字节是控制位，`控制位 & 7` 得到填充长度，再跳过 2 字节 salt；
+4. 去尾：截到最后一个 GIF trailer `0x3b`；
+5. 结果应以 `GIF89a` / `GIF87a` 开头。
+
+端到端验证脚本：`packages/db/tools/mface_tea_decrypt.ts`
+（`pnpm --filter @weq/db test:mface-tea-decrypt`）。
+
+> 📌 详细原理另见 [商城表情的解密](../../../principles/index.md)（编写中）。
+
+## 三、语义未验证的字段
+
+以下 `808xx/809xx` tag 仅为往返完整性而解析，wire 类型是**依字段标签猜的**，
+含义均未验证。
 
-<!-- TODO: 列出该 element 的 protobuf 字段号、类型、含义 -->
+| tag | 字段名 | 类型（推测） | 推测含义 |
+| --- | ------ | ------------ | -------- |
+| 80907 | `mfaceFlag80907` | bytes | 空对象 |
+| 80913 | `mfaceFlag80913` | bytes | 扩展元数据 |
+| 80941 | `mfaceFlag80941` | bytes | 样式 / 空对象 |
+| 80942 | `mfaceFlag80942` | bytes | 样式 / 空对象 |
+| 80970 | `sizeInfo` | bytes | protobuf 编码的宽高，如 `e0 c1 27 c8 01 e8 c1 27 c8 01` |
+| 80975 | `mfaceFlag80975` | uint32 | 兼容性标志 |
+| 80977 | `mfaceFlag80977` | bytes | 样式 / 空对象 |
+| 80978 | `mfaceFlag80978` | string | 颜色 / 样式代码 |
+| 80980 | `mfaceFlag80980` | uint32 | 权限标志 |
+| 80981 | `mfaceFlag80981` | uint32 | 权限标志 |
+| 80983 | `mfaceFlag80983` | string | 扩展 JSON |
+| 80995 | `mfaceFlag80995` | uint32 | 结束 / 填充标志 |
 
 ---
 
diff --git a/docs/database/nt_msg/elements/multi-msg.md b/docs/database/nt_msg/elements/multi-msg.md
index cd543f1b..5bebc18b 100644
--- a/docs/database/nt_msg/elements/multi-msg.md
+++ b/docs/database/nt_msg/elements/multi-msg.md
@@ -1,12 +1,52 @@
 # elementType 16 — 合并转发
 
-> 🚧 骨架待补充。
-
 对应 WeQ 解析实现：`packages/codec/src/proto/msg/element.ts`（`elementType = 16`）。
 
-## 字段
+合并转发（QQ 内部名 MULTIFORWARD）。element 本身**只是一张卡片壳**：
+三个字段分别是服务端资源 id、渲染用的 XML 预览、以及上传会话 id。
+真正的消息链条要么去服务端拉（凭 `resId`），要么读本地 [40900 列](../40900.md) 的缓存。
+
+---
+
+## 一、字段
+
+| tag | 字段名 | 类型 | 必有 | 含义 |
+| --- | ------ | ---- | ---- | ---- |
+| 48601 | `resId` | string | ✅ | **服务端资源 ID**，用于向 QQ 服务器拉取完整消息链 |
+| 48602 | `xmlContent` | string | ✅ | **XML 预览文档**，携带标题、摘要与元数据，用于渲染转发卡片 |
+| 48603 | `sessionId` | string | ✅ | 关联本次上传会话的标识，在 XML 中体现为 `m_fileName` |
+
+## 二、`xmlContent`（48602）的结构
+
+```ts
+interface MultiMsgXmlPayload {
+  serviceID: string;
+  templateID: string;
+  action: string;
+  brief: string;         // 会话列表外显的简述
+  m_resid: string;       // 与 48601 对应
+  m_fileName: string;    // 与 48603 对应
+  tSum: string;          // 条数
+  flag: string;
+  item?: {
+    layout: string;
+    titles: Array<{ color: string; size: string; text: string }>;  // 预览的前几条
+    summary?: { color: string; text: string };                     // 「查看 N 条转发消息」
+  };
+  source?: { name: string };
+}
+```
+
+## 三、与 40900 的关系
+
+一条合并转发消息的行级 `40011 = 8`（`MsgType.MULTI_FORWARD`），此时该行的
+[`40900` 列](../40900.md)里存着被转发消息的**完整快照**（每条都是一个 `MsgCache`，
+含各自的 `40800` 正文）。
+
+也就是说：
 
-<!-- TODO: 列出该 element 的 protobuf 字段号、类型、含义 -->
+- **离线可读**：不联网也能展开转发内容，因为快照就在本地库里；
+- **可递归**：被转发的消息若本身也是合并转发，`40900` 会再嵌套一层。
 
 ---
 
diff --git a/docs/database/nt_msg/elements/online-file.md b/docs/database/nt_msg/elements/online-file.md
index aa465e71..24ad45c3 100644
--- a/docs/database/nt_msg/elements/online-file.md
+++ b/docs/database/nt_msg/elements/online-file.md
@@ -1,12 +1,25 @@
 # elementType 23 — 在线文件
 
-> 🚧 骨架待补充。
-
 对应 WeQ 解析实现：`packages/codec/src/proto/msg/element.ts`（`elementType = 23`）。
 
+在线文件（QQ 内部名 TOFURECORD）—— 不落地下载、直接在线预览 / 转存的文件。
+字段完全复用「文件族」，没有专属 tag，共用部分见
+[40800 总览 · 第五节](../40800.md#五跨类型共用的文件族字段)。
+
+---
+
 ## 字段
 
-<!-- TODO: 列出该 element 的 protobuf 字段号、类型、含义 -->
+| tag | 字段名 | 类型 | 必有 | 含义 |
+| --- | ------ | ---- | ---- | ---- |
+| 45402 | `fileName` | string | ✅ | 文件名 |
+| 45403 | `filePath` | string | ✅ | 本地路径 |
+| 45405 | `fileSize` | uint32 | ✅ | 字节数 |
+| 45411 | `imgWidth` | uint32 | ✅ | 宽（图片类文件才有意义） |
+| 45412 | `imgHeight` | uint32 | ✅ | 高 |
+| 45503 | `fileToken` | string | ✅ | 下载凭据 |
+| 45415 | `fileFlag45415` | uint32 | | 文件相关标识 |
+| 45504 | `transferFlag45504` | string | | 传输标志 |
 
 ---
 
diff --git a/docs/database/nt_msg/elements/online-folder.md b/docs/database/nt_msg/elements/online-folder.md
index ec19cbfb..f45b71f0 100644
--- a/docs/database/nt_msg/elements/online-folder.md
+++ b/docs/database/nt_msg/elements/online-folder.md
@@ -1,12 +1,23 @@
 # elementType 30 — 在线文件夹
 
-> 🚧 骨架待补充。
-
 对应 WeQ 解析实现：`packages/codec/src/proto/msg/element.ts`（`elementType = 30`）。
 
+在线文件夹。结构与[在线文件](./online-file.md)几乎一致，只是没有宽高
+（文件夹没有尺寸概念）。字段全部复用「文件族」，见
+[40800 总览 · 第五节](../40800.md#五跨类型共用的文件族字段)。
+
+---
+
 ## 字段
 
-<!-- TODO: 列出该 element 的 protobuf 字段号、类型、含义 -->
+| tag | 字段名 | 类型 | 必有 | 含义 |
+| --- | ------ | ---- | ---- | ---- |
+| 45402 | `fileName` | string | ✅ | 文件夹名 |
+| 45403 | `filePath` | string | ✅ | 本地路径 |
+| 45405 | `fileSize` | uint32 | ✅ | 总字节数 |
+| 45503 | `fileToken` | string | ✅ | 下载凭据 |
+| 45415 | `fileFlag45415` | uint32 | | 文件相关标识 |
+| 45504 | `transferFlag45504` | string | | 传输标志 |
 
 ---
 
diff --git a/docs/database/nt_msg/elements/pic.md b/docs/database/nt_msg/elements/pic.md
index b70e469c..02fc8741 100644
--- a/docs/database/nt_msg/elements/pic.md
+++ b/docs/database/nt_msg/elements/pic.md
@@ -1,12 +1,95 @@
 # elementType 2 — 图片
 
-> 🚧 骨架待补充。
-
 对应 WeQ 解析实现：`packages/codec/src/proto/msg/element.ts`（`elementType = 2`）。
 
-## 字段
+图片是「文件族」中字段最全的一类，绝大多数 `454xx / 455xx / 458xx` tag 都能在图片行上看到。
+文件族的**共用字段**（文件名 / 大小 / MD5 / 三档 URL 与本地路径 / CDN 信息 / 传输标记）
+统一在 [40800 总览 · 第五节](../40800.md#五跨类型共用的文件族字段) 说明，本页不重复。
+
+---
+
+## 一、subType — 图片的来源分类
+
+名字取自 QQ NT 自身的 `PicSubType` 枚举。实践中 0 / 1 最常见，2/3/4/7 也确有出现；
+另有 10..14 出现在野外，超出厂商枚举范围，未命名（需要有渲染结果才能确认）。
+
+| 值 | 名称 | 说明 |
+| -- | ---- | ---- |
+| 0 | NORMAL | 普通图片 |
+| 1 | CUSTOM | 自定义表情（收藏的表情包） |
+| 2 | HOT | 热图 |
+| 3 | DIPPER_CHART | 斗图 |
+| 4 | SMART | 智能图 |
+| 5 | SPACE | 空间图（未观测） |
+| 6 | UNKNOW | 厂商枚举里就叫 `KUNKNOW`（未观测） |
+| 7 | RELATED | 关联图 |
+
+## 二、`imgType`（45416）
+
+| 值 | 名称 | 说明 |
+| -- | ---- | ---- |
+| 1000 | NORMAL | 普通图 |
+| 1001 | ORIGINAL | 原图 |
+| 2000 | EMOJI | 表情 |
+
+## 三、必有字段
+
+依据 `element/spec.ts` 的 `PicElementSchema`，一个图片 element 一定带这些字段：
+
+| tag | 字段名 | 类型 | 说明 |
+| --- | ------ | ---- | ---- |
+| 45402 | `fileName` | string | 图片文件名 |
+| 45405 | `fileSize` | uint32 | 字节数 |
+| 45406 | `md5Bytes` | bytes | 二进制 MD5 |
+| 45408 | `contentHash` | bytes | 内容校验 hash |
+| 45411 | `imgWidth` | uint32 | 宽（像素） |
+| 45412 | `imgHeight` | uint32 | 高（像素） |
+| 45416 | `imgType` | uint32 | 见上表 |
+| 45418 | `isOriginal` | bool | 是否原图 |
+| 45424 | `md5` | string | 大写十六进制 MD5 |
+| 45503 | `fileToken` | string | 下载凭据 |
+| 45505 | `uploadTime` | uint32 | 上传 / 处理时间戳 |
+| 45517 | `uploadTimestamp` | uint32 | 上传时间戳 |
+| 45518 | `fileTTL` | uint32 | 有效期（秒） |
+| 45802 | `thumbnailUrl` | string | 缩略图 URL |
+| 45803 | `previewUrl` | string | 预览图 URL |
+| 45804 | `originalUrl` | string | 大图 URL |
+| 45815 | `summary` | string（repeated） | 摘要 / 描述 |
+| 45816 | `cdnHost` | string | CDN 域名 |
+
+## 四、可选字段
+
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 45403 | `filePath` | string | 本地文件路径 |
+| 45511 | `picTransferState` | uint32 | 传输状态 |
+| 45513 | `transferVersion` | uint32 | 传输版本 |
+| 45806 | `cdnServerIp` | uint32 | CDN 地址，大端打包 IPv4 |
+| 45807 | `cdnServerPort` | uint32 | CDN 端口 |
+| 45812 | `thumbnailLocalPath` | string | 缩略图本地缓存路径（`…_0.jpg`） |
+| 45813 | `previewLocalPath` | string | 预览图本地缓存路径（`…_198.jpg`） |
+| 45814 | `originalLocalPath` | string | 大图本地缓存路径（`…_720.jpg`） |
+| 45507 | `transferFlag45507` | int64 | 近似常量哨兵，见总览 |
+| 45509 | `transferFlag45509` | uint32 | 恒为 1（与 45507 成对） |
+| 45600 | `picFlag45600` | bytes | 复杂嵌套结构（图片冗余信息），保留为原始字节 |
+
+## 五、观测到但语义未验证
+
+以下 tag 在图片行上出现过，但取值几乎恒定，携带不了可利用的信息，仅为往返保真而解析。
 
-<!-- TODO: 列出该 element 的 protobuf 字段号、类型、含义 -->
+| tag | 观测情况 |
+| --- | -------- |
+| 45425 | 只在 subType=13 的行上出现，取值 1（×93）/ 2（×2） |
+| 45801 | 唯一一次观测为空字符串 |
+| 45557 | 唯一一次观测为 0 |
+| 45805 | 所有观测行恒为 0 |
+| 45817 | PIC 协议标志（uint32） |
+| 45818 / 45819 / 45820 | string，语义未知 |
+| 45821 / 45822 / 45823 | uint32，语义未知 |
+| 45824 | string，语义未知 |
+| 45825 / 45826 / 45827 | uint32，语义未知 |
+| 45828 | string，语义未知 |
+| 45829 / 45830 / 45831 | 恒为 0 |
 
 ---
 
diff --git a/docs/database/nt_msg/elements/ptt.md b/docs/database/nt_msg/elements/ptt.md
index 7adef60e..c48bb3af 100644
--- a/docs/database/nt_msg/elements/ptt.md
+++ b/docs/database/nt_msg/elements/ptt.md
@@ -1,12 +1,74 @@
 # elementType 4 — 语音
 
-> 🚧 骨架待补充。
-
 对应 WeQ 解析实现：`packages/codec/src/proto/msg/element.ts`（`elementType = 4`）。
 
-## 字段
+语音（PTT）复用大部分「文件族」tag（`45402`–`45518`、`45815`）承载文件元数据，
+共用部分见 [40800 总览 · 第五节](../40800.md#五跨类型共用的文件族字段)。
+
+---
+
+## 一、两个容易踩坑的字段
+
+### 时长看 `45906`，不要看波形
+
+`45906 (pttDuration)` 是唯一可靠的时长来源，同时决定界面上的「时长」标签和气泡宽度。
+
+波形数据 `45925 (waveform)` 是**装饰性**的，不能反推时长：AI 声聊的音频无论多长，
+都携带一条固定的 30 字节合成波形。
+
+### AI 声聊看 `45915`
+
+`45915 (isAiVoice)` **只在 AI 声聊片段上出现**（值为 true）；普通麦克风录音、对讲、
+其它端发来的语音都不带这个字段。这是唯一可靠的判据 —— QQ 没有其它地方标记它，
+而它们的波形又是上面说的合成占位。
+
+## 二、必有字段
+
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 45402 | `fileName` | string | 文件名 |
+| 45403 | `filePath` | string | 本地路径 |
+| 45405 | `fileSize` | uint32 | 字节数 |
+| 45406 | `md5Bytes` | bytes | 二进制 MD5 |
+| 45408 | `contentHash` | bytes | 内容校验 hash |
+| 45418 | `isOriginal` | bool | 是否原始音质 |
+| 45424 | `md5` | string | 大写十六进制 MD5 |
+| 45503 | `fileToken` | string | 下载凭据 |
+| 45505 | `uploadTime` | uint32 | 上传时间戳 |
+| 45517 | `uploadTimestamp` | uint32 | 上传时间戳 |
+| 45518 | `fileTTL` | uint32 | 有效期（秒） |
+| 45815 | `summary` | string（repeated） | 摘要 |
+| 45906 | `pttDuration` | uint32 | **时长（秒）** |
+| 45911 | `voiceChanged` | bool | 是否变声 |
+| 45925 | `waveform` | bytes | 波形可视化数据 |
+
+> 字段名之所以叫 `pttDuration` 而不是 `duration`：CALL（通话记录）的 `48152` 也叫
+> `duration`，而 `ElementWire` 是扁平结构，键名重复会让 `45906` 被静默丢弃。
+
+## 三、可选字段
+
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 45915 | `isAiVoice` | bool | **AI 声聊标记**，见上 |
+| 45923 | `pttTranscript` | string | **QQ 自带的语音转文字结果**，缓存在行上。跑过一次「转文字」之后才有；转录结果为空时是空字符串 |
+| 45905 | `pttVoiceId` | string | 服务端语音 id，如 `98PO#bjWUtk8qVPcpAiG57xZrOeS28AXRNmR` |
+| 45550 | `transferState` | uint32 | 传输状态 |
+| 45511 | `picTransferState` | uint32 | 传输状态 |
+| 45513 | `transferVersion` | uint32 | 传输版本 |
+
+## 四、观测到但语义未验证
 
-<!-- TODO: 列出该 element 的 protobuf 字段号、类型、含义 -->
+| tag | 观测情况 |
+| --- | -------- |
+| 45903 | 恒为 0 |
+| 45907 | PTT 协议标志（uint32） |
+| 45909 | uint32，语义未知 |
+| 45912 | 取值 2（×39）/ 1（×1） |
+| 45922 | uint32，语义未知 |
+| 45924 | 只要出现就恒为 1，疑似「转录结果可用」 |
+| 45926 | 只要出现就恒为 2 |
+| 45908 | 嵌套 `{1, 5, 7}`，所有观测行三项全为 0 |
+| 45601 | 嵌套 `{2:{37}, 4:{1,2}}`，所有观测行均为空 / 0，保留为原始字节 |
 
 ---
 
diff --git a/docs/database/nt_msg/elements/qq-dynamic.md b/docs/database/nt_msg/elements/qq-dynamic.md
index a8a78b8e..59024a6f 100644
--- a/docs/database/nt_msg/elements/qq-dynamic.md
+++ b/docs/database/nt_msg/elements/qq-dynamic.md
@@ -1,12 +1,44 @@
 # elementType 26 — 空间动态提示
 
-> 🚧 骨架待补充。
-
 对应 WeQ 解析实现：`packages/codec/src/proto/msg/element.ts`（`elementType = 26`）。
 
-## 字段
+QQ 空间动态（说说 / 动态）的分享卡，QQ 内部名 TOFU。tag 段为 `481xx`。
+
+---
+
+## 一、字段
+
+除 `dynamicTags` 外，下列字段在 QQ_DYNAMIC element 上都是必有的。
+
+| tag | 字段名 | 类型 | 必有 | 含义 |
+| --- | ------ | ---- | ---- | ---- |
+| 48172 | `dynamicType` | uint32 | ✅ | 动态类型 |
+| 48173 | `dynamicId` | string | ✅ | 动态 id |
+| 48174 | `dynamicFlag48174` | uint32 | ✅ | 未知整数 |
+| 48175 | `dynamicDesc` | message | ✅ | 主描述块，见下 |
+| 48176 | `dynamicDesc2` | message | ✅ | 次描述块（结构同 48175） |
+| 48180 | `dynamicCoverUrl` | string | ✅ | 封面图 URL |
+| 48181 | `dynamicZoneLogoUrl` | string | ✅ | QQ 空间 logo URL |
+| 48182 | `dynamicPublisherUin` | uint32 | ✅ | 动态发布者 QQ 号 |
+| 48183 | `dynamicMeta` | string | ✅ | 动态 meta 数据 |
+| 48189 | `dynamicTags` | repeated message | | 标签列表，见下 |
+
+## 二、描述块（48175 / 48176）
+
+两者结构相同：
+
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 48178 | `mainDesc` | string | 主描述 |
+| 48179 | `subDesc` | string | 次描述 |
+
+## 三、标签项（48189，repeated）
 
-<!-- TODO: 列出该 element 的 protobuf 字段号、类型、含义 -->
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 48191 | `flag48191` | bool | 未知标志 |
+| 48192 | `tagId` | uint32 | 标签 id |
+| 48193 | `tagContent` | string | 标签内容 |
 
 ---
 
diff --git a/docs/database/nt_msg/elements/reply.md b/docs/database/nt_msg/elements/reply.md
index aa1883b2..3cc9cf16 100644
--- a/docs/database/nt_msg/elements/reply.md
+++ b/docs/database/nt_msg/elements/reply.md
@@ -1,12 +1,69 @@
 # elementType 7 — 回复引用
 
-> 🚧 骨架待补充。
-
 对应 WeQ 解析实现：`packages/codec/src/proto/msg/element.ts`（`elementType = 7`）。
 
-## 字段
+引用一条更早的消息。回复元素**自带被引用消息的快照**（`47423`），
+所以即使原消息已被删除，引用块依然能渲染出内容。
+
+> 与 [40900 列](../40900.md) 的关系：行级 `40011 = 9` 时，`40900` 列里也存了一份
+> 被引用消息的**完整行快照**。`47423` 是元素内的轻量副本，`40900` 是列级的完整副本，
+> 两者并存、粒度不同。
+
+---
+
+## 一、被引用消息的定位
+
+| tag | 字段名 | 类型 | 必有 | 含义 |
+| --- | ------ | ---- | ---- | ---- |
+| 40020 | `origSenderUid` | string | ✅ | 原消息发送者 uid（复用信封级 tag） |
+| 40021 | `origReceiverUid` | string | ✅ | 原消息接收者 uid（复用信封级 tag） |
+| 47402 | `origMsgSeq` | uint32 | ✅ | 原消息序列号 |
+| 47403 | `origSenderUin` | uint32 | ✅ | 原消息发送者 QQ 号 |
+| 47404 | `origMsgTime` | uint32 | ✅ | 原消息时间戳，unix 秒 |
+| 47411 | `origReceiverUin` | uint32 | ✅ | 原消息接收者 QQ 号 |
+| 47416 | `origMsgId` | uint64 | ✅ | 原消息 id |
+| 47419 | `origMsgIndex` | uint32 | ✅ | 原消息在会话内的序号 |
+| 47401 | `replyOrigMsgIdRef` | uint64 | | 原消息 id 引用 |
+| 48101 | `replyOrigMsgSeqCopy` | uint32 | | `47402` 的副本 —— 所有观测行完全相同 |
+
+> 群聊里 `origReceiverUid` / `origMsgIndex` 常常缺失。WeQ 自己构造回复时会填无害的占位值。
+
+## 二、被引用内容的快照
+
+| tag | 字段名 | 类型 | 必有 | 含义 |
+| --- | ------ | ---- | ---- | ---- |
+| 47423 | `origElements` | repeated `ReplyElementWire` | ✅ | **原消息 element 的轻量快照** |
+| 47413 | `replyTextSummary` | string | | 原消息的文本摘要 |
+| 47421 | `replyOrigSenderNick` | string | | 被回复者的群名片 / 昵称 |
+| 47410 | `replyOrigSenderBlob` | bytes | | 被引用消息发送者的完整快照（uin、uid、群名片、seq/time…）。嵌套很深，且携带的信息 `47402..47423` 已全部提供，故保留为原始字节 |
+
+### `ReplyElementWire`（47423 的每一项）
+
+结构是 `ElementWire` 的**裁剪版**：`elementId` + `elementType` 打头，
+后面跟着「实际出现在 wire 上的」各类型字段。由于捕获时并不知道原消息是什么类型，
+除前两项外**全部可选**：
+
+- 通用：`45001` `45002` `45003`
+- 文本：`45101`
+- 文件族：`45402` `45403` `45405` `45406` `45407` `45408` `45411` `45412` `45416`
+  `45418` `45424` `45503` `45505` `45511` `45513` `45517` `45518` `45550`
+  `45802` `45803` `45804` `45815` `45816`
+- 语音：`45906` `45911` `45915` `45925`
+- 表情：`47601` `47602`
+- ARK：`47901`
+- 合并转发：`48601` `48602` `48603`
+
+## 三、语义未验证的字段
 
-<!-- TODO: 列出该 element 的 protobuf 字段号、类型、含义 -->
+| tag | 字段名 | 类型 | 观测情况 |
+| --- | ------ | ---- | -------- |
+| 47422 | `replyFlag47422` | uint64 | 必有。大小接近 `elementId` |
+| 47405 | `replyFlag47405` | uint32 | 取值 1（×290）/ 0（×14） |
+| 47407 | `replyFlag47407` | uint32 | 取值 1（×207）/ 0（×96） |
+| 47415 | `replyFlag47415` | bool | 未知 |
+| 47418 | `replyFlag47418` | bool | 未知 |
+| 47424 | `replyFlag47424` | uint32 | 恒为 1 |
+| 47425 | `replyFlag47425` | uint32 | 恒为 1 |
 
 ---
 
diff --git a/docs/database/nt_msg/elements/text.md b/docs/database/nt_msg/elements/text.md
index daedaad1..cfcbb535 100644
--- a/docs/database/nt_msg/elements/text.md
+++ b/docs/database/nt_msg/elements/text.md
@@ -1,12 +1,70 @@
 # elementType 1 — 文本 / @
 
-> 🚧 骨架待补充。
-
 对应 WeQ 解析实现：`packages/codec/src/proto/msg/element.ts`（`elementType = 1`）。
 
-## 字段
+文本是最常见的消息段。**@ 提及并不是独立的 elementType**，它同样是 `elementType = 1`，
+靠额外字段区分。
+
+---
+
+## 一、text 与 at 的区分
+
+WeQ 在 `element/registry.ts` 里的判据只有一句：
+
+```ts
+const kind = wire.bubbleId ? 'at' : 'text';
+```
+
+即：**`45105` 有值就是 @，没值就是普通文本**。
+
+@ 元素上三个字段的实际用途（注意字段名是历史遗留，与聊天「气泡」无关）：
+
+| tag | 字段名 | @ 元素中装的东西 |
+| --- | ------ | ---------------- |
+| 45101 | `textContent` | 展示文本，形如 `@某人 `（末尾带一个空格） |
+| 45105 | `bubbleId` | **被 @ 者的 uid** |
+| 45103 | `textEncodingFlag` | **被 @ 者的 uin**（QQ 号） |
+
+`@全体成员` 同样走这条路径，只是 uid / uin 为特殊值。
+
+## 二、subType — 是链接安全分级，不是文字样式
+
+`45003 (subType)` 在文本上的语义容易误解：它**不表示字体或样式**，而是 QQ 对链接的安全分类。
+全表扫描的结论是：`subType > 0` 只出现在内容是 / 含 URL 的消息上。
+
+| 值 | 名称 | 说明 |
+| -- | ---- | ---- |
+| 0 | PLAIN | 普通文本，不含链接 |
+| 1 | EXTERNAL_LINK | 外部链接。会附带 `45112 (urlVerifyFlag)` —— QQ 扫描域名后附的 12 / 24 / 248 字节安全校验负载 |
+| 2 | TRUSTED_LINK | 可信链接（腾讯系域名：`docs.qq.com` / `mp.weixin.qq.com` …）。**不带 45112**，QQ 对自家域名跳过安全检查 |
+
+## 三、字段
+
+### 核心
+
+| tag | 字段名 | 类型 | 必有 | 含义 |
+| --- | ------ | ---- | ---- | ---- |
+| 45101 | `textContent` | string | ✅ | 文本内容 |
+| 45102 | `textReserve` | uint32 | | 文本信封标志。构造 @ 时 WeQ 写 2 |
+
+### 观测到但语义未验证
+
+以下字段在真实文本行上出现过，会被解析（这样 tag 字典能给它们名字），但既不会被提升进
+`TextElement` 的渲染路径，也不参与回写。含义列均为**推测**，无一验证。
+
+| tag | 字段名 | 类型 | 推测含义 |
+| --- | ------ | ---- | -------- |
+| 45103 | `textEncodingFlag` | uint32 | 文本编码 / 加密标志。**@ 元素中确定装的是被 @ 者 uin** |
+| 45104 | `fontStyle` | uint32 | 字体 / 样式相关 |
+| 45105 | `bubbleId` | string | 气泡 ID。**实际用途见上：@ 的目标 uid** |
+| 45106 | `textInputState` | uint32 | 文本输入状态 |
+| 45108 | `translationFlag` | uint32 | 翻译 / 转换标志 |
+| 45109 | `linkDetectionFlag` | uint32 | 链接识别标志 |
+| 45110 | `atMentionMask` | string | @ 相关位掩码（字符串编码） |
+| 45111 | `walletFlag` | uint32 | 红包 / 钱包含义标志 |
+| 45112 | `urlVerifyFlag` | bytes | 网址校验字段，见上方 subType=1 |
 
-<!-- TODO: 列出该 element 的 protobuf 字段号、类型、含义 -->
+> `45107` 至今未观测到。
 
 ---
 
diff --git a/docs/database/nt_msg/elements/video.md b/docs/database/nt_msg/elements/video.md
index 329fbde0..42de3f57 100644
--- a/docs/database/nt_msg/elements/video.md
+++ b/docs/database/nt_msg/elements/video.md
@@ -1,12 +1,88 @@
 # elementType 5 — 视频
 
-> 🚧 骨架待补充。
-
 对应 WeQ 解析实现：`packages/codec/src/proto/msg/element.ts`（`elementType = 5`）。
 
-## 字段
+短视频。复用「文件族」tag：`45402` `45405` `45406` `45408` `45411` `45412` `45415`
+`45418` `45503` `45505` `45511` `45513` `45517` `45518` `45815`，
+共用部分见 [40800 总览 · 第五节](../40800.md#五跨类型共用的文件族字段)。
+
+---
+
+## 一、宽高有两套
+
+视频行上同时存在两组宽高，来源不同：
+
+| 用途 | tag |
+| ---- | --- |
+| 封面图（缩略图）宽高 | `45411` / `45412`（`imgWidth` / `imgHeight`，文件族共用） |
+| **视频本身**宽高 | `45413` / `45414`（`videoWidth` / `videoHeight`） |
+
+## 二、两级过期时间
+
+视频在服务端有**两段**过期：第一次过期下线原片，第二次过期把它从服务端彻底清除。
+
+| tag | 字段名 | 含义 |
+| --- | ------ | ---- |
+| 45515 | `expireTimestamp` | 第一级过期时间，unix 秒 |
+| 45516 | `validPeriodSec` | 有效期长度，秒 |
+| 45519 | `secondExpireTimestamp` | 第二级过期时间，unix 秒 |
+
+## 三、必有字段
+
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 45003 | `subType` | uint32 | 视频文件类型判别式，尚未逐一映射（代码里留有 `VideoSubType` 的 TODO） |
+| 45410 | `videoDuration` | uint32 | 时长（秒） |
+| 45413 | `videoWidth` | uint32 | 视频宽 |
+| 45414 | `videoHeight` | uint32 | 视频高 |
+| 45421 | `videoFlag45421` | bytes | 未知字节串 |
+| 45422 | `coverFileName` | string | 封面（缩略图）文件名 |
+| 45423 | `videoFlag45423` | bool | 未知布尔标志 |
+| 45510 | `videoToken` | string | 下载 token |
+| 45515 | `expireTimestamp` | uint32 | 见上 |
+| 45516 | `validPeriodSec` | uint32 | 见上 |
+| 45519 | `secondExpireTimestamp` | uint32 | 见上 |
+| 45862 | `channelParams` | bytes | 文件通道参数 |
+| 45863 | `videoFlag45863` | uint32 | 未知整数 |
+
+## 四、可选字段
+
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 45404 | `videoCoverLocalPath` | string | 封面的本地缓存路径（`nt_data/Video/…/Thumb/…_0.png`） |
+| 45954 | `fileThumbLocalPath` | string | 缩略图本地缓存路径 |
+| 45507 / 45509 | 传输标记 | | 见总览 |
+
+## 五、观测到但语义未验证
+
+| tag | 观测情况 |
+| --- | -------- |
+| 45852 / 45853 / 45854 | 近似恒为 0（各有一行为 1） |
+| 45855 | 恒为 0 |
+| 45856 | 嵌套块 `45857..45861`，所有观测行的五个子字段全为空 / 0 |
+| 45865 | 取值 0（×30）/ 2（×4） |
+
+## 六、`45851` —— 视频封装格式
+
+本地样本里 `45851` 恒为 2，一度以为是常量；对照 QQ NT 自身的 `NTVideoType` 枚举可知，
+它其实是**视频封装格式**——恒为 2 只是因为发到 QQ 的视频几乎都会被转成 MP4。
+
+| 值 | 名称 | 格式 |
+| -- | ---- | ---- |
+| 1 | VIDEO_FORMAT_AVI | AVI |
+| 2 | VIDEO_FORMAT_MP4 | **MP4**（实际观测到的唯一取值） |
+| 3 | VIDEO_FORMAT_WMV | WMV |
+| 4 | VIDEO_FORMAT_MKV | MKV |
+| 5 | VIDEO_FORMAT_RMVB | RMVB |
+| 6 | VIDEO_FORMAT_RM | RM |
+| 7 | VIDEO_FORMAT_AFS | AFS |
+| 8 | VIDEO_FORMAT_MOV | MOV |
+| 9 | VIDEO_FORMAT_MOD | MOD |
+| 10 | VIDEO_FORMAT_TS | TS |
+| 11 | VIDEO_FORMAT_MTS | MTS |
 
-<!-- TODO: 列出该 element 的 protobuf 字段号、类型、含义 -->
+> 枚举仅记录在此文档，未进代码：解析层用不到它，`45851` 目前仍以
+> `videoFlag45851` 的名义原样解析、原样回写。
 
 ---
 
diff --git a/docs/database/nt_msg/elements/wallet.md b/docs/database/nt_msg/elements/wallet.md
index 34b5e57b..91530907 100644
--- a/docs/database/nt_msg/elements/wallet.md
+++ b/docs/database/nt_msg/elements/wallet.md
@@ -1,12 +1,77 @@
 # elementType 9 — 红包 / 转账
 
-> 🚧 骨架待补充。
-
 对应 WeQ 解析实现：`packages/codec/src/proto/msg/element.ts`（`elementType = 9`）。
 
-## 字段
+QQ 钱包相关消息：转账、各类红包。tag 段为 `484xx`。
+
+---
+
+## 一、红包类型（48412）
+
+`RedbagType` 中 TRANSFER / NORMAL / PASSWORD / VOICE 来自早期逆向；
+LUCKY(3) 与 DESIGNATED(8) 为**实测确认**（对比同群的拼手气红包与专属红包的 msgBody）。
+
+| 值 | 名称 | 说明 |
+| -- | ---- | ---- |
+| 1 | TRANSFER | 转账 |
+| 2 | NORMAL | 普通红包（等额） |
+| 3 | LUCKY | 拼手气红包 |
+| 6 | PASSWORD | 口令红包 |
+| 8 | DESIGNATED | **专属红包**（指定领取人），会额外带 `48420` |
+| 15 | VOICE | 语音红包 |
+
+## 二、主要字段
+
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 48401 | `walletTargetUin` | uint32 | 目标 uin |
+| 48402 | `walletTransferProto` | bytes | 转账 protobuf 字节 |
+| 48403 | `walletDetail` | message | 钱包详情，见下 |
+| 48409 | `walletOrderId` | string | 订单 ID |
+| 48412 | `walletRedbagType` | uint32 | **红包类型**，见上表 |
+| 48420 | `walletDesignatedUin` | uint32 | **指定领取人 uin**。只在专属红包（`48412 = 8`）上出现，是唯一被允许领取的群成员 |
+| 48421 | `walletExt` | message | 扩展字段，见下 |
+
+## 三、`walletDetail`（48403）
+
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 48442 | `redbagType` | uint32 | 红包类型（与 48412 呼应） |
+| 48443 | `redbagTitle` | string | 红包标题 |
+| 48444 | `openPrompt` | string | 「开」的提示文案 |
+| 48445 | `subTitle` | string | 副标题 |
+| 48448 | `display` | string | 展示文案 |
+| 48454 | `orderUrl` | string | 订单链接 |
+| 48441 | `flag48441` | uint32 | 未知 |
+| 48446 / 48447 | `flag48446` / `flag48447` | string | 未知 |
+| 48449 / 48450 | `flag48449` / `flag48450` | uint32 | 未知 |
+| 48451 / 48452 / 48453 | `flag4845x` | string | 未知 |
+| 48461 | `flag48461` | bytes | 未知 |
+
+## 四、`walletExt`（48421）
+
+注意这个嵌套块用的是**小 tag**（1..8），不是 `484xx` 段。
+
+| tag | 字段名 | 类型 | 含义 |
+| --- | ------ | ---- | ---- |
+| 5 | `redbagCover` | string | **红包封面** |
+| 3 | `flag3` | bool | 未知 |
+| 7 | `flag7` | bool | 未知 |
+| 8 | `flag8` | bool | 未知 |
+
+## 五、语义未验证的标量
+
+以下 tag 为往返保真而解析，含义未定：
 
-<!-- TODO: 列出该 element 的 protobuf 字段号、类型、含义 -->
+| tag | 类型 |
+| --- | ---- |
+| 48404 / 48405 / 48406 / 48407 / 48408 | uint32 |
+| 48410 | string |
+| 48411 | uint32 |
+| 48417 | bytes |
+| 48418 | string |
+| 48419 | uint32 |
+| 48437 / 48438 | uint32 |
 
 ---
 
diff --git a/docs/database/nt_msg/index.md b/docs/database/nt_msg/index.md
index ade8d34c..bb2d59da 100644
--- a/docs/database/nt_msg/index.md
+++ b/docs/database/nt_msg/index.md
@@ -1,19 +1,56 @@
-# nt_msg.db 消息体解析（40800 / 40900）
+# nt_msg.db — 消息数据库
 
-`nt_msg.db` 的消息行中，最复杂的两列是 `40800`（消息正文）与 `40900`（消息缓存）。二者均为 protobuf，文档站仅有零散字段引用，这里由 WeQ 依据实际解析实现单独系统维护。
+`nt_msg.db` 是 NTQQ 存贮**聊天记录本体**的数据库：消息行、会话列表、未读状态都在这里。
+本栏目的内容全部由 WeQ 依据自己的解析实现手写维护。
 
-> 🚧 本章节为骨架结构，内容待补充。
+## 表一览
 
-## 两列职责
+| 表 | 内容 | 文档 |
+| -- | ---- | ---- |
+| `c2c_msg_table` | 好友单聊消息 | [消息行](#消息行) |
+| `group_msg_table` | 群聊消息（结构同 c2c） | [消息行](#消息行) |
+| `dataline_msg_table` | 数据线消息（我的手机 / 电脑 / 平板，结构同 c2c） | [消息行](#消息行) |
+| `recent_contact_v3_table` | 会话列表 | [recent-contact](./recent-contact.md) |
+| `recent_contact_top_table` | 置顶会话 | [recent-contact-top](./recent-contact-top.md) |
+| `msg_unread_info_table` | 未读信息 + 提醒高亮 | [unread-info](./unread-info.md) |
+| `nt_uid_mapping_table` | uid ↔ uin ↔ sortNo 目录 | [下见](#nt_uid_mapping_table) |
+| `draft_storage_table_v1` | 草稿：输入了但还没点发送的内容 | 暂未解析 |
+
+### 消息行
+
+三张消息表的**列布局完全一致**，差别只在会话维度（c2c 按 sortNo 分区、群按群号）。
+一行里最复杂的是两个 protobuf 列：
 
 | 列    | 名称                 | 结构                              | 说明                                                   |
 | ----- | -------------------- | --------------------------------- | ------------------------------------------------------ |
 | 40800 | 消息正文（MsgBody）  | `repeated ElementWire`            | 一条消息的富文本消息段序列，见 [40800 解析](./40800.md) |
 | 40900 | 消息缓存（MsgCache） | `repeated MsgCache`（可递归嵌套） | 转发/引用时缓存的源消息快照，见 [40900 解析](./40900.md) |
 
+> 📖 建议先读 [40800 解析](./40800.md) 的前半部分 —— 「扁平信封」与「文件族共用字段」
+> 两节是理解所有消息段的前提，各消息段文档不再重复这些内容。
+
+### nt_uid_mapping_table
+
+账号级的身份目录，三列：
+
+| 列 | 含义 |
+| -- | ---- |
+| 48901 | sortNo —— 该账号给每个交互过的对端分配的 1 起递增小整数 |
+| 48902 | uid —— 其它地方通用的不透明对端标识 |
+| 1002 | uin —— 对端 QQ 号 |
+
+它之所以重要：`c2c_msg_table` 的**会话分区列是 `40027`（= 这里的 sortNo）**，
+所有有用的复合索引都建在它上面（`(40027,40003)` 等）；而应用层是按 uid 找会话的，
+`40021` 恰恰**没有索引**。所以走快路径查 c2c 消息，必须先 uid → sortNo 翻译一次。
+这张表很小且稳定，WeQ 在会话启动时整表读进内存（`UidMap`）常驻。
+
+---
+
 ## 消息段（Element）索引
 
-`40800` 由若干消息段（Element）组成，每段以 `elementType` 区分类型。各类型的字段解析见下：
+`40800` 由若干消息段（Element）组成，每段以 `elementType` 区分类型。各类型的字段解析见下；
+未观测到的 elementType（12/13/15/17/18/19/20/22/24/25/29/43/44）不单独成篇，
+完整枚举见 [40800 解析 · elementType 全表](./40800.md#elementtype-全表)。
 
 | elementType | 名称                  | 文档                                        |
 | ----------- | --------------------- | ------------------------------------------- |
@@ -34,6 +71,7 @@
 | 23          | 在线文件              | [online-file](./elements/online-file.md)    |
 | 26          | 空间动态提示          | [qq-dynamic](./elements/qq-dynamic.md)      |
 | 27          | 弹射表情              | [emoji-bounce](./elements/emoji-bounce.md)  |
+| 28          | 位置共享              | 仅一个字段，见 [40800 解析](./40800.md#elementtype-全表) |
 | 30          | 在线文件夹            | [online-folder](./elements/online-folder.md)|
 
 ---
diff --git a/docs/database/nt_msg/recent-contact-top.md b/docs/database/nt_msg/recent-contact-top.md
new file mode 100644
index 00000000..d2c898d1
--- /dev/null
+++ b/docs/database/nt_msg/recent-contact-top.md
@@ -0,0 +1,95 @@
+# recent_contact_top_table — 置顶会话
+
+`nt_msg.db` 里的**置顶会话表**，一行 = 一个被置顶的会话。
+QQ 会话列表顶部那几个「钉在最前面」的会话就来自这里。
+
+对应 WeQ 解析实现：
+
+| 文件 | 职责 |
+| ---- | ---- |
+| `packages/db/src/contact/recent_contact_top.ts` | 取行 + 列 → `RecentContactTop` |
+| `packages/db/src/contact/types.ts` | `RecentContactTop` 的字段语义 |
+| `packages/db/tools/recent_contact_top.ts` | 探针：打印置顶会话并 join 会话名 |
+
+---
+
+## 一、这张表的定位
+
+关键认识：**这是一张「纯登记表」，只记「谁被置顶了、什么时候置的」，不带任何展示信息。**
+
+它没有会话名、没有头像、没有最后一条消息 —— 这些全在
+[recent_contact_v3_table](./recent-contact.md) 里。这与那张表刻意冗余展示信息的做法正好相反：
+置顶是一条「用户设置」，改动频率低、数据量小（实测就两三行），没有冗余的必要。
+
+所以使用方式是**两表 join**：读 `recent_contact_v3_table` 拿到会话，
+再用本表的会话标识去标记哪些会话置顶、按 `41103` 决定置顶组内的先后。
+
+## 二、列结构
+
+整张表只有 5 列，全部列在下面（不是节选）。
+
+| 列 | 字段名 | 类型 | 含义 | 置信度 |
+| -- | ------ | ---- | ---- | ------ |
+| 41145 | `id` | INTEGER | 行主键，一个 64 位大整数。**不是会话标识**，读取路径不关心 | 观测一致 |
+| 40010 | `chatType` | INTEGER | 会话类型，枚举同 [recent_contact · ChatType](./recent-contact.md#四chattype会话类型) | 已验证 |
+| 41103 | `topTime` | INTEGER | **置顶时间**，unix 秒。置顶组内的排序键 | 已验证 |
+| 1000 | `peerUid` | TEXT | **私聊**会话的对端 uid。群聊行为 `NULL` | 已验证 |
+| 60001 | `groupCode` | INTEGER | **群聊**会话的群号。私聊行为 `NULL` | 已验证 |
+
+要点：
+
+- **`1000` 和 `60001` 二选一，另一个是 `NULL`**（不是 0、不是空串）。
+  靠 `40010` 判断该读哪一列，也可以直接「哪列非空取哪列」。
+- 注意 `60001` 在这里的含义和 `recent_contact_v3_table` **不一样**：
+  那边的 `60001` 是「临时会话的来源群号」，这边是「被置顶的群本身」。同名不同义。
+- `41103` 与 `recent_contact_v3_table` 的 `40050`（最后消息时间）无关。
+  刚置顶一个死了半年的会话，它照样排最前。
+
+实测两行（一群一私聊）：
+
+```text
+41145 = 339226880527203757   40010 = 2   41103 = 1785509063   1000 = NULL                       60001 = 673646675
+41145 = 4391097541244030732  40010 = 1   41103 = 1785509057   1000 = "u_LKt3AdAIMP-CUfn6ydzDzw"  60001 = NULL
+```
+
+## 三、会话标识的归一化
+
+`RecentContactTop.targetId` 把二选一的两列收敛成一个字符串，**刻意对齐
+`RecentContact.targetUid`**（那一列同样兼任 uid / 群号两种身份）：
+
+```ts
+targetId = peerUid || (groupCode === 0n ? '' : groupCode.toString())
+```
+
+有了它，前端就是一次 Map 查表：
+
+```ts
+const topTimeByConv = new Map(tops.map((t) => [t.targetId, Number(t.topTime)]));
+// conversation.id 就是 RecentContact.targetUid
+const pinned = topTimeByConv.has(conversation.id);
+```
+
+## 四、常见查询
+
+WeQ 的读法（整表，不分页 —— QQ 的置顶数量本来就只有个位数）：
+
+```sql
+SELECT "41145","40010","41103","1000","60001"
+FROM recent_contact_top_table
+ORDER BY "41103" DESC;
+```
+
+## 五、前端渲染
+
+会话列表的排序变成两级（`MainView.tsx` 的 `conversations`）：
+
+1. 置顶会话整体排在最前，组内按 `41103` 倒序；
+2. 其余会话按最后一条消息时间倒序。
+
+置顶状态经 `ConversationPreference.pinned` 下发给模板层。这里的 merge 顺序与免打扰
+（`41220`）保持一致：**DB 值打底，本地手动偏好覆盖**，所以用户在界面上手动取消置顶时
+不会被 DB 值顶回去。行上的表现是浅色底 + 时间左侧一枚图钉（`.conversation-row.pinned`）。
+
+---
+
+[← 返回 nt_msg.db](./index.md)
diff --git a/docs/database/nt_msg/recent-contact.md b/docs/database/nt_msg/recent-contact.md
new file mode 100644
index 00000000..faac820e
--- /dev/null
+++ b/docs/database/nt_msg/recent-contact.md
@@ -0,0 +1,214 @@
+# recent_contact_v3_table — 会话列表
+
+`nt_msg.db` 里的**最近会话列表**，一行 = 一个会话（好友 / 群 / 临时会话 / 公众号 / 频道…）。
+它是聊天软件左侧那一栏的数据源：会话名、头像、最后一条消息的外显文本、时间、免打扰状态全在这里。
+
+对应 WeQ 解析实现：
+
+| 文件 | 职责 |
+| ---- | ---- |
+| `packages/db/src/contact/recent_contact.ts` | 取行 + 列 → `RecentContact` |
+| `packages/db/src/contact/types.ts` | `RecentContact` 的字段语义 |
+| `packages/codec/src/proto/msg/40051.ts` | `40051` 预览列的 protobuf 外壳 |
+
+---
+
+## 一、这张表的定位
+
+关键认识：**这张表是一份「冗余快照」，不是消息表的视图。**
+
+会话的最新一条消息，其正文明明已经存在 `c2c_msg_table` / `group_msg_table` 里，
+QQ 仍然把「发送者昵称 / 群名片 / 外显文本 / 头像路径」等一整套展示信息**再抄一份**进这张表。
+原因很实际：渲染会话列表时不能为每个会话都去消息表里查一次、再去 profile 库查一次昵称，
+那是 N 次跨库查询。抄一份进来，列表就是一条 `ORDER BY 40050 DESC LIMIT n`。
+
+带来的两个后果，写代码时必须记住：
+
+1. **这里的展示信息可能过时**。对方改了昵称、群改了名，只有下次这个会话来消息、这一行被重写时才会更新。
+   要「当前」的昵称/群名，得去 `profile_info.db` / `group_info.db`，不能信这里。
+2. **删掉这一行 ≠ 删掉聊天记录**。QQ 里「删除会话」删的就是这一行，消息表纹丝不动。
+   WeQ 的「WeQ 助手」开关也正是这么做的（关掉只删 `recent_contact_v3_table` 的行，
+   `c2c_msg_table` 从不动 —— 见 `packages/service/src/account/weq_assistant.ts`）。
+
+## 二、列结构
+
+WeQ 实际读取的列（`SELECT` 见 `recent_contact.ts`），按用途分组。
+
+### 会话身份
+
+| 列 | 字段名 | 类型 | 含义 | 置信度 |
+| -- | ------ | ---- | ---- | ------ |
+| 41102 | — | INTEGER | 行主键。WeQ 只在**插入**伪造会话时用到（取 `MAX + 随机`），读取路径不关心 | 观测一致 |
+| 40010 | `chatType` | INTEGER | 会话类型，见下方 [ChatType](#四chattype会话类型) | 已验证 |
+| 40021 | `targetUid` | TEXT | **会话标识**：c2c 是对端 uid，群是群号 | 已验证 |
+| 40030 | `targetUin` | INTEGER | 会话对端的 QQ 号（c2c 用；无则 0） | 已验证 |
+| 40027 | — | INTEGER | 会话 sortNo，同 `nt_uid_mapping_table.48901`，与消息表的分区列同义 | 观测一致 |
+
+> 注意 `40021` 一列同时兼任「好友 uid」和「群号」两种身份 —— 靠 `40010` 区分。
+> 这与消息表的 `40021` 是同一约定。
+
+### 最后一条消息
+
+| 列 | 字段名 | 类型 | 含义 | 置信度 |
+| -- | ------ | ---- | ---- | ------ |
+| 40001 | — | INTEGER | 最后一条消息的 msgId，指回消息表 | 观测一致 |
+| 40003 | `msgSeq` | INTEGER | 最后一条消息的序列号。**未读数就是拿它减去已读 seq 算的**，见 [msg_unread_info_table](./unread-info.md) | 已验证 |
+| 40011 | — | INTEGER | 最后一条消息的 msgType，枚举同 [40900 · MsgType](./40900.md#msgtypetag-40011) | 观测一致 |
+| 40050 | `sendTime` | INTEGER | 最后一条消息的时间，unix 秒。**会话列表的排序键** | 已验证 |
+| 41136 | — | INTEGER | 与 `40050` 同值的时间镜像列 | 观测一致 |
+| 40051 | `preview` | BLOB | **外显预览**，protobuf，见下方第三节 | 已验证 |
+
+### 发送者展示信息（最后一条消息的发送者）
+
+| 列 | 字段名 | 类型 | 含义 | 置信度 |
+| -- | ------ | ---- | ---- | ------ |
+| 40020 | `senderUid` | TEXT | 发送者 uid | 已验证 |
+| 40033 | — | INTEGER | 发送者 QQ 号 | 观测一致 |
+| 40090 | `senderDisplayName` | TEXT | 发送者展示名，群聊场景主要是**群名片** | 已验证 |
+| 40093 | `senderNick` | TEXT | 发送者昵称 | 已验证 |
+| 40095 | `senderRemark` | TEXT | 发送者备注名 | 已验证 |
+
+> 三个名字列的优先级由使用方决定。WeQ 的会话列表取 `senderDisplayName || senderNick`。
+
+### 会话自身展示信息
+
+| 列 | 字段名 | 类型 | 含义 | 置信度 |
+| -- | ------ | ---- | ---- | ------ |
+| 40094 | `targetDisplayName` | TEXT | **会话名**：好友昵称 / 群名 | 已验证 |
+| 41135 | `targetRemark` | TEXT | 会话备注名（好友备注） | 已验证 |
+| 41110 | `targetAvatar` | TEXT | 会话头像。**是本地文件的绝对路径**，不是 URL —— QQ 直接读这个路径渲染 | 已验证 |
+| 41148 | `targetGroupNick` | TEXT | 对方的**群名片**，只在「群里发起的临时会话」行上有值，其它场景为空 | 观测一致 |
+
+> `41110` 是本地路径这一点被 WeQ 反向利用：「WeQ 助手」把自己的头像图片写进 QQ 自己的
+> `nt_data/avatar/weq/` 目录，再把绝对路径填进这一列，QQ 就会像渲染任何缓存头像一样渲染它。
+
+### 会话设置与来源
+
+| 列 | 字段名 | 类型 | 含义 | 置信度 |
+| -- | ------ | ---- | ---- | ------ |
+| 41220 | `notifyLevel` | INTEGER | **免打扰**。`0`/`1` = 正常提醒，其它值（实测 `4`）= 免打扰 | 已验证 |
+| 60001 | `tempSourceGroupCode` | INTEGER | 临时会话的**来源群号**。非临时会话为 0 | 已验证 |
+
+`41220` 是逆向出来的：开关某个群的免打扰、前后各 dump 一次整行做 diff，只有这一列变。
+84 个群被这一列干净二分。`msg_unread_info_table` 里**没有**免打扰字段，别去那边找。
+
+判定写法（`MainView.tsx`）：
+
+```ts
+function mutedFromNotifyLevel(notifyLevel: number | undefined): boolean {
+  return notifyLevel !== undefined && notifyLevel !== 0 && notifyLevel !== 1;
+}
+```
+
+`60001` 用于「群 xxx 的临时会话」这种标题回退：群还在我的群列表里就显示群名，退群了就退化成群号。
+
+## 三、`40051` — 外显预览
+
+会话列表里那句「张三：[图片]」的来源。它是 protobuf，外壳里只有一个 tag 同为 `40051` 的子消息：
+
+```text
+40051 (BLOB)
+└── 40051  PreviewElementWire     ← 单个消息段，不是列表
+    ├── …  与 40800 的 ElementWire 完全相同的全部字段
+    └── 49093  displayText        ← 会话列表外显文本
+```
+
+理解要点：
+
+- **它就是一个 `ElementWire`**（结构见 [40800 解析](./40800.md)），只是**单个**，不是 `repeated`。
+  多消息段的消息（图 + 文）只挑第一段做预览。
+- **多出来的只有一个 tag：`49093`**，装的是最终外显文本。图片消息这里就是 `"[图片]"`，
+  也就是说**外显文案是 QQ 写进库的，不需要解析方自己按类型翻译**。
+
+| tag | 字段名 | 类型 | 含义 | 置信度 |
+| --- | ------ | ---- | ---- | ------ |
+| 49093 | `displayText` | string | 会话列表外显的最新消息文本 | 已验证 |
+
+解码同样先过 `sanitizeBytes` 容错（原因见 [40800 · 容错解码](./40800.md#六容错解码sanitizebytes)），
+一个猜错类型的 tag 不至于让整个会话列表少一行。
+
+## 四、ChatType（会话类型）
+
+`40010` 的取值，来自 QQ NT 自身的 `KCHATTYPE*` 枚举（`packages/codec/src/domain/msg/enums.ts`）。
+下表按「WeQ 是否实际渲染」分组，值全部来自枚举定义本身。
+
+### 常规会话
+
+| 值 | 名称 | 说明 |
+| -- | ---- | ---- |
+| 1 | KCHATTYPEC2C | 好友单聊 |
+| 2 | KCHATTYPEGROUP | 群聊 |
+| 3 | KCHATTYPEDISC | 讨论组（历史遗留） |
+| 8 | KCHATTYPEDATALINE | 数据线（我的手机 / 电脑 / 平板），消息落在 `dataline_msg_table` |
+| 134 | KCHATTYPEDATALINEMQQ | 数据线（手机 QQ） |
+
+### 临时会话
+
+| 值 | 名称 | 说明 |
+| -- | ---- | ---- |
+| 99 | KCHATTYPETEMPC2CFROMUNKNOWN | 来源未知的临时会话 |
+| 100 | KCHATTYPETEMPC2CFROMGROUP | **群聊发起的临时会话**，来源群号在 `60001`，对方群名片在 `41148` |
+| 101 | KCHATTYPETEMPFRIENDVERIFY | 好友验证 |
+| 102 | KCHATTYPETEMPBUSSINESSCRM | 商家客服 |
+| 103 | KCHATTYPETEMPPUBLICACCOUNT | 公众号 / 服务号 |
+| 111 | KCHATTYPETEMPADDRESSBOOK | 通讯录来源 |
+| 117 | KCHATTYPETEMPWPA | 网页发起会话 |
+| 119 | KCHATTYPETEMPNEARBYPRO | 附近的人（Pro） |
+
+### 系统 / 折叠入口
+
+这些不是真人会话，而是各种「助手」「通知」的折叠入口。
+
+| 值 | 名称 | 说明 |
+| -- | ---- | ---- |
+| 5 | KCHATTYPEBUDDYNOTIFY | 好友通知 |
+| 6 | KCHATTYPEGROUPNOTIFY | 群通知 |
+| 7 | KCHATTYPEGROUPHELPER | 群助手 |
+| 30 | KCHATTYPESUBSCRIBEFOLDER | 订阅号折叠 |
+| 40 | KCHATTYPEWEIYUN | 微云 |
+| 41 | KCHATTYPEFAV | 收藏 |
+| 42 | KCHATTYPEADELIE | Adelie（内部） |
+| 104 / 109 | KCHATTYPEMATCHFRIEND(FOLDER) | 交友匹配（及其折叠） |
+| 105 / 116 | KCHATTYPEGAMEMESSAGE(FOLDER) | 游戏消息（及其折叠） |
+| 106 ~ 112 | KCHATTYPENEARBY* | 附近的人相关（助手 / 折叠 / 互动 / 打招呼折叠） |
+| 113 | KCHATTYPECIRCLE | 圈子 |
+| 115 | KCHATTYPESQUAREPUBLIC | 广场 |
+| 118 / 201 | KCHATTYPESERVICEASSISTANT(SUB) | 服务号助手（及子项） |
+| 131 | KCHATTYPERELATEACCOUNT | 关联账号 |
+| 132 | KCHATTYPEQQNOTIFY | QQ 官方通知 |
+| 133 | KCHATTYPEGROUPBLESS | 群祝福 |
+
+### 频道（被 WeQ 排除）
+
+| 值 | 名称 | 说明 |
+| -- | ---- | ---- |
+| 0 | KCHATTYPEUNKNOWN | 占位 |
+| 4 | KCHATTYPEGUILD | 频道 |
+| 9 | KCHATTYPEGROUPGUILD | 群频道 |
+| 16 | KCHATTYPEGUILDMETA | **频道元信息** |
+
+`16` 被 WeQ 显式过滤掉（`BLOCKED_CHAT_TYPES`）。原因是频道行**换了一套列布局**：
+会话名在 `40091` 而不是 `40094`，预览嵌在 `41150` 而不是 `40051`，也没有头像列 ——
+按常规列读出来是一行空白，不如不显示。
+
+## 五、常见查询
+
+会话列表（WeQ 的读法）：
+
+```sql
+SELECT "40003","40010","40020","40021","40030","40050","40051",
+       "40090","40093","40094","40095","41110","41135","41148","41220","60001"
+FROM recent_contact_v3_table
+WHERE "40010" NOT IN (16)          -- 排除频道元信息行
+ORDER BY "40050" DESC
+LIMIT ? OFFSET ?;
+```
+
+`40050` 上有索引，会话数量本身也就几百，所以单条有序 `LIMIT` 足够，不需要分页优化。
+
+> 会话的**置顶**状态不在这张表里，而在独立的
+> [recent_contact_top_table](./recent-contact-top.md)，靠 `40021` / `targetUid` 关联。
+
+---
+
+[← 返回 nt_msg.db](./index.md)
diff --git a/docs/database/nt_msg/unread-info.md b/docs/database/nt_msg/unread-info.md
new file mode 100644
index 00000000..b79d39b5
--- /dev/null
+++ b/docs/database/nt_msg/unread-info.md
@@ -0,0 +1,165 @@
+# msg_unread_info_table — 未读信息
+
+`nt_msg.db` 里记录每个会话**读到哪了**的表，两列而已，但第二列是一个嵌套 protobuf，
+里面藏着「特别关心 / @我 / @全体 / 新文件」这些提醒标记 —— 它们**不是**独立的列或表。
+
+对应 WeQ 解析实现：
+
+| 文件 | 职责 |
+| ---- | ---- |
+| `packages/db/src/msg/unread_info.ts` | 取行 + 展平高亮 → `UnreadInfoResult` |
+| `packages/codec/src/proto/msg/48902.ts` | `48902` blob 的 protobuf 结构 |
+
+---
+
+## 一、列结构
+
+只有两列：
+
+| 列 | 类型 | 含义 |
+| -- | ---- | ---- |
+| 48901 | TEXT | 会话键，格式 **`"chatType_uid"`**，如 `2_673646675`（群）、`1_u_xxxx`（好友） |
+| 48902 | BLOB | 未读信息 protobuf，见下 |
+
+> 注意 `48901`/`48902` 这对列号在 `nt_uid_mapping_table` 里是另一套含义（sortNo / uid）。
+> QQ 的列号只在**表内**唯一，跨表复用很常见，不要按列号去猜语义。
+
+查询就是一次主键命中：
+
+```sql
+SELECT "48901", "48902" FROM msg_unread_info_table WHERE "48901" = ? LIMIT 1;
+-- 参数形如 "2_673646675"
+```
+
+## 二、未读数是算出来的，不是存出来的
+
+**这张表里没有「未读数」这个字段。** 它只存「已读到的 seq」，未读数要自己减：
+
+```text
+未读数 = recent_contact_v3_table.40003 (会话最新消息 seq)
+       - msg_unread_info_table.48902.41002 (已读到的 seq)
+```
+
+即需要**跨两张表**。WeQ 的做法（`MainView.tsx`）是先加载会话列表，
+再按 12 个一批并发查每个会话的未读信息，两边相减；差值 ≤ 0 视作 0。
+
+这个设计也解释了一个现象：未读数是「消息条数差」而不是精确的未读消息数 ——
+中间若有被撤回/删除的消息，seq 仍然占位，所以红点数字可能比实际能看到的消息条数多。
+
+## 三、`48902` 的结构
+
+外壳只有一个 tag 同为 `48902` 的子消息。整体形状（已在真实 blob 上验证）：
+
+```text
+48902 (BLOB)
+└── 48902 {
+    ├── 40010  chatType             会话类型（与 48901 前缀重复）
+    ├── 40021  peerUid              会话 uid（与 48901 后缀重复）
+    ├── 41002  msgSeq               ★ 已读到的消息序号
+    └── 50005 {                     会话扩展
+        ├── 50001  peerUid          再重复一次
+        ├── 50002  chatType         再重复一次
+        └── 50060 {                 ★ 提醒高亮组（没有提醒时整块不存在）
+            ├── 50000  kind         类别码，见第四节
+            └── 50040 {             该类别下的高亮消息（可多条）
+                ├── 50020  msgSeq
+                ├── 50022  senderUid
+                ├── 50023  sendTime
+                └── 50024  text
+            }
+        }
+    }
+}
+```
+
+### 顶层字段
+
+| tag | 字段名 | 类型 | 含义 | 置信度 |
+| --- | ------ | ---- | ---- | ------ |
+| 40010 | `chatType` | uint32 | 会话类型，同 `recent_contact_v3_table.40010` | 已验证 |
+| 40021 | `peerUid` | string | 会话 uid | 已验证 |
+| 41002 | `msgSeq` | uint32 | **已读到的消息序号** | 已验证 |
+| 50005 | `ext` | message | 会话扩展，见下 | 已验证 |
+
+另观测到 `41027` / `41032` / `41037` 三个计数类字段，语义未定，WeQ 未解析。
+
+### 会话扩展（tag 50005）
+
+| tag | 字段名 | 类型 | 含义 | 置信度 |
+| --- | ------ | ---- | ---- | ------ |
+| 50001 | `peerUid` | string | 会话 uid（重复 40021） | 已验证 |
+| 50002 | `chatType` | uint32 | 会话类型（重复 40010） | 已验证 |
+| 50060 | `highlight` | repeated message | **提醒高亮组**，见下 | 已验证 |
+
+**普通会话的 `50005` 里只有 `50001` / `50002` 两个字段，没有 `50060`。**
+所以判定很直接：`50060` 存在 ⇒ 这个会话有提醒类未读。
+
+### 提醒高亮组（tag 50060）
+
+| tag | 字段名 | 类型 | 含义 | 置信度 |
+| --- | ------ | ---- | ---- | ------ |
+| 50000 | `kind` | uint32 | **类别码**，见第四节 | 已验证 |
+| 50040 | `items` | repeated message | 该类别下的高亮消息 | 已验证 |
+
+**每个类别一个 `50060` 组**，壳子结构完全一样，只有 `50000` 的值不同。所以它被建模成 `repeated`。
+
+### 高亮消息（tag 50040）
+
+| tag | 字段名 | 类型 | 含义 | 置信度 |
+| --- | ------ | ---- | ---- | ------ |
+| 50020 | `msgSeq` | uint32 | 该条消息的序号 | 已验证 |
+| 50022 | `senderUid` | string | 发送者 uid | 已验证 |
+| 50023 | `sendTime` | uint32 | 发送时间，unix 秒 | 已验证 |
+| 50024 | `text` | string | 预览文本，**实测常为空** | 观测一致 |
+
+## 四、`50000` 类别码枚举
+
+这是本页的重点。**这批码不是从 QQ 的枚举表抄来的**，QQ 前端不暴露它；
+它是逐个触发场景、每次抓一份 blob 做 diff 逆向出来的 —— 同一个群（673646675）反复制造不同提醒，
+观察到壳子完全不变、**只有 `50000` 的值在变**，于是把值和场景一一对上。
+
+| 值 | 类别 | WeQ `HighlightKind` | 触发场景 | 置信度 |
+| -- | ---- | ------------------- | -------- | ------ |
+| 1000 | @我 | `atMe` | 群里有人 @ 我 | 已验证 |
+| 1006 | 特别关心 | `specialCare` | 被设为「特别关心」的好友/群友发来消息 | 已验证 |
+| 1007 | QQ 红包 | `redPacket` | 会话内有未领取的红包 | 观测一致 |
+| 2000 | @全体 | `atAll` | 群里有人 @全体成员 | 已验证 |
+| 2001 | 新文件 | `newFile` | 群文件有新上传 | 已验证 |
+
+未映射到的码会落到 `'unknown'`，同时保留 `rawKind` 原值，方便后续继续逆向。
+
+**已知缺口：「回复我」的码还没抓到。** 补一个新类别的成本很低 —— 三处各加一行：
+`HIGHLIGHT_KIND_BY_CODE`（db）、`ConversationHighlightKind`（前端类型）、`ConversationList` 的渲染分支。
+
+> 数值本身也透着分组规律：`10xx` 像是「找我的」（@我 / 特别关心 / 红包），
+> `20xx` 像是「群内广播」（@全体 / 新文件）。**未验证**，仅供继续逆向时参考。
+
+## 五、展平约定
+
+一个类别下可能有多条高亮消息（比如被 @ 了三次）。WeQ 每个类别只保留 **seq 最大的那一条**
+（`extractHighlights`），因为界面只需要「有没有」这个布尔，`msgSeq` 保留但不展示。
+
+结果对象：
+
+```ts
+interface UnreadHighlight {
+  kind: HighlightKind;   // 映射后的类别
+  rawKind: number;       // 50000 原值，未映射类别也能被识别
+  msgSeq: number;        // 该类别下最新的一条
+  senderUid: string;
+  sendTime: number;
+}
+```
+
+界面上分成两类颜色：**「找我的」告警类用红色**（`[特别关心]` / `[有人@我]` / `[@全体]`），
+**内容类用蓝色**（`[新文件]`）。
+
+## 六、和免打扰的关系：没有关系
+
+一个容易走的弯路：免打扰状态**不在这张表里**。它在
+[`recent_contact_v3_table` 的 `41220` 列](./recent-contact.md#会话设置与来源)。
+这张表只管「读到哪了」和「有哪些提醒」，不管「要不要提醒」。
+
+---
+
+[← 返回 nt_msg.db](./index.md)
diff --git a/docs/database/profile_info/index.md b/docs/database/profile_info/index.md
new file mode 100644
index 00000000..2df673c7
--- /dev/null
+++ b/docs/database/profile_info/index.md
@@ -0,0 +1,176 @@
+# profile_info.db — 资料数据库
+
+`profile_info.db` 存**人**：好友、陌生人、机器人、公众号的资料，以及好友列表和分组。
+本栏目的内容全部由 WeQ 依据自己的解析实现手写维护。
+
+对应 WeQ 解析实现：
+
+| 文件 | 职责 |
+| ---- | ---- |
+| `packages/db/src/profile/profile_info.ts` | 取行 + 列 → `UserProfile` |
+| `packages/codec/src/proto/profile/21000.ts` | `21000` 扩展资料列的 protobuf |
+| `packages/codec/src/proto/profile/20057.ts` | `20057` 自定义状态列 |
+| `packages/codec/src/proto/profile/20072.ts` | `20072` 密友关系列 |
+
+## 表一览
+
+本机实测（52243 行 profile / 195 个好友）的完整表清单：
+
+| 表 | 行数量级 | 内容 | 文档 |
+| -- | -------- | ---- | ---- |
+| `profile_info_v6` | 5 万+ | **资料主表**，一行 = 一个人 | [profile-info-v6](./profile-info-v6.md) |
+| `buddy_list` | 好友数 | **好友名单**（权威） | [下见](#buddy_list--好友名单) |
+| `category_list_v2` | 1 | 好友分组定义（打包在一个 BLOB 里） | [下见](#category_list_v2--好友分组) |
+| `buddy_req_list_5` | 十几 | 好友申请列表 | [下见](#buddy_req_list_5--好友申请) |
+| `profile_info_adelie` | 个位数 | **AI 机器人**资料（元宝 / Q 群管家等），88 列 | [下见](#profile_info_adelie--ai-机器人) |
+| `profile_info_public_account` | 个位数 | 公众号 / 服务号资料 | [下见](#其余小表) |
+| `user_sec_quality_table` | 1 | 账号安全等级 | [下见](#其余小表) |
+| `user_tab_table` | 1 | 资料卡页签配置 | [下见](#其余小表) |
+| `user_like_id_table` | 0 | 点赞（本机为空） | — |
+| `adelie_uid_friends` / `adelie_uid_recommended_v2` | 0 | AI 机器人好友 / 推荐（本机为空） | — |
+| `profile_info_v6_fts*` | — | 资料全文索引（`pinyin_letter` 分词器） | [下见](#fts-表打不开是正常的) |
+| `profile_info_public_account_fts*` | — | 公众号全文索引 | 同上 |
+
+---
+
+## profile_info_v6 — 资料主表
+
+44 列，是这个库的绝对主体，单独成篇：**[profile_info_v6 详解](./profile-info-v6.md)**。
+
+一句话概括它的定位：**这是一张缓存表，不是好友表**。5 万多行里只有 195 个是好友，
+其余全是「在群里见过一面」的陌生人。判定谁是好友要去 `buddy_list`，不能靠这张表有没有行。
+
+## buddy_list — 好友名单
+
+四列，短小但**权威** —— 判定「是不是我好友」以这张表为准。
+
+| 列 | 含义 | 置信度 |
+| -- | ---- | ------ |
+| 1000 | uid（主键） | 已验证 |
+| 1001 | QID（个性 ID，多数为空串） | 已验证 |
+| 1002 | uin（QQ 号） | 已验证 |
+| 25007 | 所属分组 id，对应 `category_list_v2` 的分组。**未分组的好友这里是 NULL 而非 0** | 已验证 |
+
+它与 `profile_info_v6` 同库，所以「好友 + 资料」是一次普通 JOIN，不用跨库：
+
+```sql
+SELECT b."1000", b."1002", p."20002", p."20009", p."20070"
+FROM buddy_list b
+LEFT JOIN profile_info_v6 p ON b."1000" = p."1000"
+ORDER BY COALESCE(p."20070", 0) DESC   -- 按亲密度排
+```
+
+这正是 WeQ「好友亲密度排行」用的查询（`listFriendsByIntimacy`）。用 `LEFT JOIN` 而非
+`INNER JOIN` 是因为**存在有好友关系但资料行缺失的情况**，用内连接会悄悄少人。
+
+## category_list_v2 — 好友分组
+
+只有 1 行，因为**所有分组打包在一个 BLOB 里**（`25011`），不是一组一行。
+
+| 列 | 含义 | 置信度 |
+| -- | ---- | ------ |
+| 1000 | 自己的 uid | 已验证 |
+| 25006 | 好友总数（实测 1640，含单向/历史） | 推测 |
+| 25013 | 另一个计数（实测 644） | 推测 |
+| 25012 / 20075 | 两个毫秒时间戳（版本 / 拉取时间） | 推测 |
+| 25011 | **分组定义列表**，protobuf | 已验证 |
+| 25015 | 序列号 | 推测 |
+
+`25011` 的结构 —— 外层 tag 与列号同为 `25011`，repeated，一项一个分组：
+
+```text
+25011 (BLOB)
+└── 25011  分组项 (repeated)
+    ├── 25007  分组 id
+    ├── 25008  分组名
+    ├── 25009  排序序号（本机恒等于分组 id）
+    └── 25010  组内好友数
+```
+
+本机实测（5 个分组）：
+
+| 25007 分组 id | 25008 分组名 | 25010 人数 |
+| ------------- | ------------ | ---------- |
+| 0 | 我的好友 | 185 |
+| 1 | 日本朋友 | 1 |
+| 2 | 家人 | 3 |
+| 3 | 同学 | 4 |
+| 4 | 老师 | 2 |
+
+> ⚠️ **`buddy_list."25007"` 在本机 185 行是 NULL**，只有被手动分过组的 10 个好友有值。
+> 也就是说「默认组」是靠 **NULL** 表达的，不是靠写 `0`。按 `25007 = 0` 查默认组会查空 ——
+> 要用 `COALESCE("25007", 0)`。这是本页最容易踩的一个坑。
+
+## buddy_req_list_5 — 好友申请
+
+26 列，一行 = 一条好友申请。已确认语义的列：
+
+| 列 | 含义 | 置信度 |
+| -- | ---- | ------ |
+| 21204 | 申请时间（unix 秒） | 已验证 |
+| 21001 | 申请方 uid | 已验证 |
+| 20002 | 申请方昵称 | 已验证 |
+| 20004 | 申请方头像 URL | 已验证 |
+| 21509 | **来源描述文本**（"QQ群" / "群查找" / "搜索账号"…） | 已验证 |
+| 60001 | **来源群号**（从群里加的才有，否则 0） | 已验证 |
+| 21505 | 来源类型码（9 = 群相关） | 观测一致 |
+| 21501 | 申请方向（1 = 对方申请加我） | 观测一致 |
+| 21510 / 21511 | 共同好友数 / 共同群数 | 推测 |
+| 21515 / 21526 / 21537 | 各类状态 bool（已读 / 已处理 / 可回关…） | 推测 |
+
+## profile_info_adelie — AI 机器人
+
+**88 列**，是全库列数最多的表，但只装 QQ 官方 AI 机器人（本机 4 行：元宝小 Q、Q 群管家等）。
+`adelie` 是 QQ 内部对这套 AI 体系的代号（会话类型 `KCHATTYPEADELIE = 42` 也是它）。
+
+已辨识的列：
+
+| 列 | 含义 | 置信度 |
+| -- | ---- | ------ |
+| 1000 / 1002 | uid / uin | 已验证 |
+| 320001 | 机器人名（"元宝小Q" / "Q群管家"） | 已验证 |
+| 320002 | 头像 URL | 已验证 |
+| 320003 | 长简介 | 已验证 |
+| 320004 | 欢迎语 | 已验证 |
+| 320007 | 归属方（"@QQ"） | 观测一致 |
+| 320008 / 320009 | 资料卡配图 / 背景图 URL | 观测一致 |
+| 320068 | **主题色**，形如 `#1E74FF` 的 CSS 十六进制串 | 已验证 |
+| 320047 | 创建/更新时间（unix 秒） | 观测一致 |
+| 320011 | 语音配置（音色 id + 试听 URL），protobuf | 观测一致 |
+| 320084 | 合规声明（规则链接 +《…信息处理规则》标题） | 观测一致 |
+| 320086 | **模型清单**，内嵌 JSON：`{"model_list":["hy3","hy3-think","deepseek-v4-pro",…]}` | 已验证 |
+| 320066 | 功能入口列表（AI 搜索 / 画图 / 录音纪要…图标 + 文案） | 观测一致 |
+| 320065 / 320082 | 资料卡 / 聊天背景素材组 | 推测 |
+
+> 剩下 60 多个 `3200xx` 列在本机全是 0 或空。这张表 QQ 明显是按「最大化字段」建的，
+> 实际填充的不到三成 —— 与其瞎猜，不如留空。
+
+## 其余小表
+
+**`profile_info_public_account`** —— 公众号/服务号，6 列：`1000` uid、`1002` uin、
+`20002` 名称（本机全空）、`410001` 类型码（实测恒为 3）、`410002` 更新时间（毫秒）、`20032`。
+
+**`user_sec_quality_table`** —— 只有自己一行，`20501` 是个 6 字节 protobuf，解出来只有
+`{ 20501: { 1: 1 } }` 一个位。样本只有 1 个，语义不下结论。
+
+**`user_tab_table`** —— 只有自己一行，`49572` 是资料卡页签配置，repeated：
+`[{49573:2, 49574:1}, {49573:1, 49574:0}]` —— 两个页签项，各带一个 id 和一个显隐/顺序位。
+
+## FTS 表打不开是正常的
+
+`profile_info_v6_fts` / `profile_info_public_account_fts` 用 `PRAGMA table_info` 一碰就报：
+
+```text
+Error: no such tokenizer: pinyin_letter
+```
+
+这不是解密失败，而是这两张虚拟表声明了腾讯自己实现的**拼音分词器**，SQLite 本体没有它。
+所以：
+
+- **别去查 `*_fts` 虚拟表**，会直接抛错；扫全库表清单时要 try/catch 包住。
+- 想要索引内容，读它的影子表 `*_fts_data` / `*_fts_idx` / `*_fts_docsize`（普通表，能读）。
+- 按昵称搜人不要指望 FTS，直接 `LIKE` 扫 `profile_info_v6."20002"` 就行 —— 5 万行 SQLite 扛得住。
+
+---
+
+[← 返回数据库分析](../index.md)
diff --git a/docs/database/profile_info/profile-info-v6.md b/docs/database/profile_info/profile-info-v6.md
new file mode 100644
index 00000000..02375a50
--- /dev/null
+++ b/docs/database/profile_info/profile-info-v6.md
@@ -0,0 +1,398 @@
+# profile_info_v6 — 资料主表
+
+`profile_info.db` 的绝对主体：44 列，一行 = 一个人的完整资料。
+好友、群友、只在某个群里发过一句话的陌生人，全在这一张表里。
+
+对应 WeQ 解析实现：
+
+| 文件 | 职责 |
+| ---- | ---- |
+| `packages/db/src/profile/profile_info.ts` | 取行 + 列 → `UserProfile` |
+| `packages/codec/src/proto/profile/21000.ts` | `21000` 扩展资料列 |
+| `packages/codec/src/proto/profile/20057.ts` | `20057` 自定义状态列 |
+| `packages/codec/src/proto/profile/20072.ts` | `20072` 密友关系列 |
+
+---
+
+## 一、这张表的定位
+
+**它是缓存，不是名册。** 本机实测 52243 行，其中好友只有 195 个 —— 99.6% 是陌生人。
+只要你在群里见过某人一次，QQ 就会把他的昵称/头像塞进这张表，方便下次渲染群消息时不用回源。
+
+由此推出三条写代码时的铁律：
+
+1. **判定「是不是好友」必须查 `buddy_list`**，不能靠这张表有没有行。
+2. **陌生人行是残缺的**。5 万行里只有约 4.8% 填了生日/性别/年龄这批「资料卡字段」，
+   剩下的只有 uid / uin / 昵称 / 头像四样。所以任何字段都要当可空处理。
+3. **行可以比现实旧**。资料是拉过一次就留着，对方后来改了昵称，这里不会自动跟。
+
+另一个反直觉的点：**头像 URL（`20004`）只有 19.9% 的行有**。剩下 80% 连头像都没缓存。
+这就是 WeQ 走 `md5(md5(md5(uid)+uid)+uid)` 本地头像路径推导、而不是依赖这一列的原因。
+
+## 二、标量列
+
+按用途分组。「填充率」一列是本机 4000 行采样的实测非空比例，用来判断这个字段可不可靠。
+
+### 身份
+
+| 列 | 字段名 | 类型 | 填充率 | 含义 | 置信度 |
+| -- | ------ | ---- | ------ | ---- | ------ |
+| 1000 | `uid` | TEXT | 100% | **主键**，`u_xxxxxxxx` 形式的不透明标识 | 已验证 |
+| 1002 | `uin` | INTEGER | 100% | QQ 号 | 已验证 |
+| 1001 | `qid` | TEXT | 0.7% | **QID**（个性 ID，如 `hydr0g3n`）。极少人设置 | 已验证 |
+| 20002 | `nick` | TEXT | 100% | 昵称 | 已验证 |
+| 20009 | `remark` | TEXT | 3.1% | **我给对方设的备注名** | 已验证 |
+| 20011 | `signature` | TEXT | 3.0% | 个性签名（纯文本版，富文本版见 `24105`） | 已验证 |
+
+`20009` / `20011` 的填充率 ≈ 好友占比，符合预期：只有好友才会有备注和签名缓存。
+
+### 资料卡字段
+
+这一组的填充率高度一致地卡在 **4.8%** —— 它们是同一次「拉完整资料」写进去的，要么全有要么全无。
+
+| 列 | 字段名 | 类型 | 填充率 | 含义 | 置信度 |
+| -- | ------ | ---- | ------ | ---- | ------ |
+| 20006 | `birthYear` | INTEGER | 4.8% | 出生年（`0` = 未填） | 已验证 |
+| 20007 | `birthMonth` | INTEGER | 4.8% | 出生月 | 已验证 |
+| 20008 | `birthDay` | INTEGER | 4.8% | 出生日 | 已验证 |
+| 24103 | `age` | INTEGER | 4.8% | 年龄。**由生年算出的冗余值**，实测 179/180 行与 `2026 - 20006` 吻合 | 已验证 |
+| 20014 | `gender` | INTEGER | 4.8% | 性别：`1` 男 / `2` 女 / `0` 未知 / **`255` 保密** | 已验证 |
+
+> `20014 = 255` 是个坑：WeQ 的 `rowToProfile` 只认 1/2，其余一律归 0（未知），
+> 所以「保密」和「没填」在上层是一回事。实测 4000 行里有 20 行是 255。
+
+### 头像
+
+| 列 | 字段名 | 类型 | 填充率 | 含义 | 置信度 |
+| -- | ------ | ---- | ------ | ---- | ------ |
+| 20004 | `avatarUrl` | TEXT | 19.9% | 头像 CDN URL（`qh.qlogo.cn/g?b=qq&ek=…`） | 已验证 |
+| 20005 | — | INTEGER | 19.9% | 头像 URL 的写入时间（毫秒） | 观测一致 |
+| 20016 | — | INTEGER | 19.9% | **头像更新时间**（unix 秒），与 `20017.20102` 恒等（60/60） | 已验证 |
+| 20017 | — | BLOB | 19.6% | 头像摘要，见 [第四节](#四20017--头像摘要) | 已验证 |
+
+### 关系与互动
+
+| 列 | 字段名 | 类型 | 填充率 | 含义 | 置信度 |
+| -- | ------ | ---- | ------ | ---- | ------ |
+| 20070 | `intimacy` | INTEGER | 4.8% | **好友亲密度**。WeQ 的「亲密度排行」就排这一列 | 已验证 |
+| 20072 | `extRelation` | BLOB | 3.3% | **密友关系**，见 [第六节](#六20072--密友关系) | 已验证 |
+| 20057 | `customStatus` | BLOB | 0.02% | **自定义在线状态**，见 [第五节](#五20057--自定义状态) | 已验证 |
+| 24104 | `sigUpdateTime` | INTEGER | 4.8% | 签名更新时间（unix 秒） | 观测一致 |
+| 24105 | — | BLOB | 3.0% | **签名富文本容器**，见 [第七节](#七24105--签名富文本) | 已验证 |
+
+### 未解语义的列
+
+诚实记录 —— 这些列有数据，但语义没验证出来，别在代码里用：
+
+| 列 | 类型 | 填充率 | 观测 |
+| -- | ---- | ------ | ---- |
+| 20001 | INTEGER | 4.8% | 只有 4 种取值，130/192 行是同一个大数 `1785936742016` |
+| 20003 | INTEGER | 99.9% | 90 种取值，形如 `2019839462274` 的 13 位数。**填充率 100% 却高度重复**，像是「资料来源/渠道」的编码 |
+| 20010 / 20012 | INTEGER | 4.8% | 两个大数时间戳，128/192 行共用同一个值 `237579889225` |
+| 20043 | INTEGER | 19.9% | 761/795 行是 `60`，其余是 0/4/12/13/28。像某种 TTL 或缓存档位 |
+| 20037 / 20048 / 20056 / 20067 / 20075 / 20083 | INTEGER | 4.8% | 几乎全 0，偶有一两行非零，样本不足以定性 |
+| 20060 / 20061 / 24110 | INTEGER | 4.8% | 本机**恒为 0**，没有任何信息量 |
+| 24111 | INTEGER | 4.8% | 190/192 行为 0，2 行是 unix 秒时间戳 |
+| 20042 / 20059 / 20066 | BLOB | **0%** | 全库为空。注意 `20059`/`20066` 这两个号在 `21000` 内部另有含义（特权容器/相册容器），别混 |
+| 24106 ~ 24109 | TEXT | **0%** | 全库为空 |
+
+---
+
+## 三、`21000` — 扩展资料（最大的一列）
+
+整张表最复杂的东西。BLOB，本机 6% 的行有，中位数 195 字节，**最大 9784 字节**。
+外层 tag 与列号同为 `21000`，里面按 `2200x` 分成七个功能块：
+
+```text
+21000 (BLOB)
+└── 21000
+    ├── 22003  好友互动标识（拍一拍/一起看/情侣…）
+    ├── 22004  VIP 与特权
+    ├── 22005  扩展资料（星座/生肖/地区/教育/兴趣/老资料）
+    ├── 22006  隐私与状态开关
+    ├── 22007  更多开关
+    └── 22009  QQ 空间相册
+```
+
+本机全量扫描（682 个非空行）共观测到 **142 条 tag 路径**。下面只记已定性的。
+
+### 22003 — 好友互动标识
+
+QQ 资料卡上那排「你和 TA 拍了 12 次」「一起看了 3 部电影」的小徽章。
+`31000` 是 repeated，一个好友可以同时挂多个。
+
+| tag | 字段名 | 含义 | 置信度 |
+| --- | ------ | ---- | ------ |
+| 31024 | `type` | 类型名：`pat`（拍一拍）/ `intimate` / `lover` / `partner_dining` / `partner_sport` / `mysteriousCharacter` / `fire` … | 已验证 |
+| 31002 | `markId` | **标识种类 id，不是等级**。实测按 type 固定：pat=44、spray=75、fire=17 | 已验证 |
+| 31015 | — | 小图标 URL（`downv6.qq.com/qqweb/res/mutualmark/<type>/<level>_0_0_small.png`） | 已验证 |
+| 31019 | — | 图标 URL **模板**，带 `{level}_{sub_level}_{style}_{size}` 占位 | 已验证 |
+| 31001 | — | 视觉档位，取值集中在 0 / 64 / 88 / 92 / 144 / 150 | 推测 |
+| 31003 | — | 小整数 1~5，多数为 1 | 推测 |
+| 31005 | — | 计数（互动次数？）0~300 | 推测 |
+| 31006 / 31017 | — | 两个 unix 秒时间戳（点亮时间 / 最近互动时间） | 推测 |
+| 31016 / 31018 | — | 两个 bool | 推测 |
+| 31020 | — | 0~6 的小整数（等级？） | 推测 |
+| 31012 | — | 皮肤/主题子块：`20606` 是款名（`Mangata`/`Breeze`/`Copain`/`Mars`），`20602`/`20607` 是素材 URL | 已验证 |
+
+> `31002` 曾被误读成「等级」。实测同一 type 下所有人的 31002 完全相同（44 出现 25 次），
+> 它是**种类 id**。真正的视觉等级藏在 `31015` 图标 URL 的文件名首段（`5_0.png` → 5 级）。
+
+### 22004 — VIP 与特权
+
+分两部分：`20059` 是**特权清单**（有结构），`28xxx` 是一堆**扁平散列**。
+
+`20059` 特权清单：
+
+| tag | 字段名 | 含义 | 置信度 |
+| --- | ------ | ---- | ------ |
+| 20431 | — | 特权页入口 URL。本人是 `club.vip.qq.com/privilege`，看别人是 `guestprivilege` | 已验证 |
+| 20432 | `opened` | **已开通**特权项（repeated） | 已验证 |
+| 20433 | `unopened` | **未开通**特权项（repeated） | 已验证 |
+
+每一项特权（20432/20433 内部）：
+
+| tag | 字段名 | 含义 | 置信度 |
+| --- | ------ | ---- | ------ |
+| 20447 | `bizId` | 特权业务 id：`1` 超级会员、`4` 腾讯视频、`101` 红钻、`102` 黄钻、`103` 音乐 SVIP、`105` 微云、`107` SVIP 音乐、`108` 微客、`109` 音乐、`113` 大会员、`116` 文档 VIP、`117` 卡片、`118` 蓝钻、`119` **情侣 SVIP** | 已验证 |
+| 20448 | `level` | 等级，与图标文件名 `big_light_N` 一致 | 已验证 |
+| 20444 / 20442 | `iconUrl` | 图标 URL。**`gray_N` = 灰/未开通，`big_light_N` = 亮/已开通**。两个位轮流用，取值时要 `20444 \|\| 20442` | 已验证 |
+| 20441 | `jumpUrl` | 点击跳转 URL | 已验证 |
+| 20446 | — | 是否已开通的 bool，与所处的 20432/20433 分支一致 | 观测一致 |
+| 20449 | — | 另一个 bool（是否年费？） | 推测 |
+
+`28xxx` 散列 —— 填充率 99.9%（只要有 21000 就有），但绝大多数恒为 0：
+
+| tag | 含义 | 置信度 |
+| --- | ---- | ------ |
+| 28004 | **超级会员等级**。实测与 `bizId=1` 那项的 `20448` 命中 **22/24** | 观测一致 |
+| 28018 | **当前装扮 itemId**（`10016`/`10049`/`59500` 等，与 `home_dress` 用的 itemId 同域） | 观测一致 |
+| 28014 | 某个等级值，取值分为 1~8 和 101~108 两段。**与超会等级只命中 1/24，不是超会等级** | 推测 |
+| 28027 | 0~26 的整数，66/195 好友非零。曾被当作 QQ 等级候选，但**上限只到 26，形态不符** | 推测 |
+| 28001/28002/28003/28008 | 四个 bool，两两同步（28001 与 28003 完全一致） | 推测 |
+| 28015 / 28017 / 28024 / 28026 | 大整数 id / 时间戳，绝大多数为 0 | 推测 |
+| 28007 | **repeated**（一行出现 2 次），取值 0/2/36/258 | 推测 |
+| 28019 | 0/1/2/4，分布均匀 | 推测 |
+| 28005/28006/28009~28013/28016/28020~28023/28025/28028/28029 | 几乎恒 0 | 推测 |
+
+### 22005 — 扩展资料
+
+这一块信息密度最高，也藏着最有意思的东西。
+
+| tag | 字段名 | 含义 | 置信度 |
+| --- | ------ | ---- | ------ |
+| 20018 | — | **星座**，1~12 = 水瓶/双鱼/白羊/金牛/双子/巨蟹/狮子/处女/天秤/天蝎/射手/摩羯 | 已验证 |
+| 20019 | — | **生肖**，1~12 = 鼠/牛/虎/兔/龙/蛇/马/羊/猴/鸡/狗/猪 | 已验证 |
+| 20020 | — | **血型**，0 未填 / 1~5（`5` 出现 18 次，疑为「其它」） | 观测一致 |
+| 20022 | — | **职业**，0 未填，`13`（24 次）与 `14`（15 次）占绝大多数 —— 学生党画像 | 观测一致 |
+| 20023 | `degree` | 学历（文本，如「初二中级」） | 已验证 |
+| 20026 | `school` | 学校（「电子科技大学」「成都信息工程大学」） | 已验证 |
+| 20027 | `country` | 国家 | 已验证 |
+| 20028 | `province` | 省份 | 已验证 |
+| 20036 | `city` | 城市 | 已验证 |
+| 20029 | — | **邮编**（实测多为空，有人填了「621700」，也有人填「看地址」） | 已验证 |
+| 20030 | — | **详细地址**（同样是自由文本，实测「四海为家」「阳光城 77 栋…」） | 已验证 |
+| 20038 | — | 资料创建/注册时间（unix 秒，多在 2015~2019） | 推测 |
+| 20041.20410 | `interests` | **兴趣标签**（repeated string） | 已验证 |
+| 20042 | — | 子块，`20401`~`20405` 五个 0~3 的小整数，疑似隐私可见范围 | 推测 |
+| 20021 | — | **未解**，见下 | — |
+| 20039 | — | **老版个人档案 TLV**，见 [第八节](#八2003920039--老版个人档案) | 已验证 |
+
+关于 `20018` / `20019` 的验证方式：拿同一行的生日列（`20006`/`20007`/`20008`）算出星座和生肖，
+再与这两个 tag 比对 —— **星座 116/118 命中，生肖 103/125 命中**。
+生肖差的那些是因为部分人填的生日年份不真实（`2021-01-01` 之类的占位值），星座只依赖月日所以更准。
+
+关于 `20021`：形如 `"49-102-55"` / `"222-0-229"` 的三段串，70 种取值，227 行是 `0-0-0`。
+两个假设都验过、都不成立：
+
+- **不是昵称颜色 RGB** —— 与超级会员开通状态无相关性（开通超会的 16 有色/36 全零，
+  非超会的 112 有色/191 全零，比例几乎一样）。
+- **不是地区码** —— 同一个段值对应的国家/省/市文本五花八门（第 2 段 `104` 同时对应
+  四川、广东、北京、英格兰、台湾、福建）。
+
+数值集中在 48~57 和 97~108 这两段，恰好是 ASCII 的 `'0'~'9'` 和 `'a'~'l'`，
+更像是某个字符串被逐字节拆开存的。**留作未解。**
+
+### 22006 / 22007 — 开关位
+
+两块全是 bool 和小整数，本机几乎全为 0。`22006.27006` 是个毫秒时间戳，
+`22007.29002` 偶尔出现 `10115`/`20124` 这类五位数 id。没有一项定性，不建议解析。
+
+### 22009 — QQ 空间相册
+
+| tag | 字段名 | 含义 | 置信度 |
+| --- | ------ | ---- | ------ |
+| 20066.20461 | — | 每张照片（repeated） | 已验证 |
+| 20471 | `photoId` | 照片 hash | 已验证 |
+| 20472 | `time` | 上传时间（unix 秒） | 已验证 |
+| 20473.20481 | `size` | 尺寸档位：**1 原图 / 2 = 640 / 3 = 160 / 4 = 100** | 已验证 |
+| 20473.20482 | `url` | 该档位的完整可访问 URL（`ugc.qpic.cn/mqq_photo/…`） | 已验证 |
+
+四个档位是**齐全的** —— 实测 78 张照片 × 4 档 = 312 条，一条不缺。所以要缩略图直接取 size=4，
+不用自己拼 URL 参数。
+
+---
+
+## 四、`20017` — 头像摘要
+
+小 BLOB（44~56 字节），19.6% 的行有。结构很简单：
+
+```text
+20017 (BLOB)
+└── 20017
+    ├── 20100  头像 md5（32 位 hex）—— 与 20101 二选一
+    ├── 20101  头像 md5（32 位 hex）—— 与 20100 二选一
+    ├── 20102  头像更新时间（unix 秒）
+    └── 20103  同上，或 1
+```
+
+实测 783 行里 `20100` 出现 637 次、`20101` 出现 146 次，**从不同时出现**。
+两者应该是「默认头像 / 自定义头像」之类的区分，但没有证据，暂不下结论。
+
+已经**排除**的两个猜想（各 60 样本，0 命中）：
+
+- 它**不是**本地头像文件名 hash `md5(md5(md5(uid)+uid)+uid)`（见 [头像 hash 公式](../../principles/avatar-hash.md)）。
+- 它**不出现在** `20004` 那个 CDN URL 的 `ek=` 参数里。
+
+确定成立的一条：**`20102` 与列 `20016` 恒等（60/60）**，所以这两个是同一个时间戳的两份拷贝。
+
+## 五、`20057` — 自定义状态
+
+就是 QQ 资料卡昵称下面那行「在线状态」（如「学习中」「emo 中」）。
+本机 4000 行只有 1 行有 —— 这东西 QQ 只给自己和极少数人缓存。
+
+| tag | 字段名 | 含义 | 置信度 |
+| --- | ------ | ---- | ------ |
+| 1 | `id` | 状态 id（实测 `264`） | 已验证 |
+| 2 | `desc` | 状态文案（实测 `"cd ~"` —— 自定义文本） | 已验证 |
+| 3 | — | bool，恒为 1 | 推测 |
+
+## 六、`20072` — 密友关系
+
+这一列的**存在性本身就是信息**：`profile_info.ts` 里 `isFriend` 就是判断它非 NULL。
+不过实测这个判据不严谨 —— 本机 132 行有 `20072`，但好友有 195 个，对不上。
+**判定好友仍应查 `buddy_list`。**
+
+内容极简，132 行里有 129 行是**空壳**（4 字节，只有外层 tag 没有内容）：
+
+| tag | 字段名 | 含义 | 置信度 |
+| --- | ------ | ---- | ------ |
+| 20073 | `preselectedIds` | 可选的密友关系 id（repeated，实测 81/82/101） | 观测一致 |
+| 20074 | `displayId` | 当前展示的密友关系 id | 观测一致 |
+
+## 七、`24105` — 签名富文本
+
+**不是 protobuf**，是 QQ 老式的 `[u8 tag][u8 len][payload]` TLV 串。
+本机 436 行**全部**能被这个格式完整解析（436/436），且其中 417 行的内容里含 `20011` 的纯文本签名 ——
+所以它是签名的**富文本版本**，`20011` 是它的降级纯文本副本。
+
+| tag | 含义 | 置信度 |
+| --- | ---- | ------ |
+| `0x03` (3) | **签名正文**（UTF-8）。436 行全有 | 已验证 |
+| `0x04` (4) | **地理位置文本**（「电子科技大学(清水河校区)」「荷兰阿姆斯特丹」「网安学院图书馆」） | 已验证 |
+| `0x94` (148) | **话题标签**（`#新的一年 好事鼠不完#`、`#一约既定 万山无阻#`），前缀有几字节二进制 | 已验证 |
+| `0x90` (144) | 元数据串：**开头就是这个人的 uin**，后接 28 位十六进制（如 `1707889225` + `69fcb339…`） | 观测一致 |
+| `0x91` / `0x92` (145/146) | 4 字节大端整数，绝大多数为 0 或 1 | 推测 |
+| `0x81` / `0x82` (129/130) | 8 字节，几乎全 0 | 推测 |
+| `0x95` (149) | 零长度占位（58 次） | 推测 |
+| `0x01` (1) | 出现 1 次，内容「祈愿平安」 | 推测 |
+
+解析注意：`len` 是**单字节**，所以单段最长 255 字节。签名超过这个长度会怎么切分没有样本，
+本机最长的一行 324 字节也是靠多段拼出来的。
+
+## 八、`21000.22005.20039` — 老版个人档案
+
+**另一个不是 protobuf 的东西**，也是 TLV，但用的是 `[u16 tag][u16 len][UTF-8]` 大端格式。
+本机 14 行有内容，14/14 完整解析。
+
+这是 QQ 十几年前那套「个人档案」问卷的遗留数据 —— 里面装的全是 2008~2012 年填的答案，
+现在的 QQ 客户端已经**不再展示**，但数据一直躺在库里跟着同步。
+
+已观测到的 key（1~55，连续）：
+
+| key | 含义 | 实测样例 |
+| --- | ---- | -------- |
+| 1~3 | 偶像 / 喜欢的理由 / 喜欢的歌 | 「成龙」「Rammstein」「龙的传人」 |
+| 4 | 会的乐器 | 「电子琴」「萧」「笛」 |
+| 5~9 | 电影 / 影片 / 影片类型 / 动画 / 电视剧 | 「变形金刚2」「喜剧片」「兄弟连」 |
+| 10~12 | 身材 / 最满意的部位 / 性格 | 「苗条」「保密」「活泼开朗」 |
+| 13 | 休闲方式 | 「电子游戏/网游」「睡觉/发呆」 |
+| **14~15** | **手机品牌-型号**（现用 / 曾用） | **「诺基亚-5700」「摩托罗拉-」** |
+| **16~17** | **电脑品牌-型号** | **「华硕(ASUS)-Z99」「惠普(HP)-911」** |
+| **18** | **MP3 / 随身听** | 「昂达(ONDA)」「魅族(MEIZU)-x3」 |
+| **19** | **相机** | 「佳能(CANON)-IXUS200」「索尼(SONY)-120」 |
+| **20~22** | **汽车（现有 / 想要 / 梦想）** | 「大众」「奥迪-TT」「兰博基尼-110」 |
+| 23~27 | 饰品 / 服装 / 包 / 珠宝 / 鞋 品牌 | 「Converse 匡威」「Jack Jones」「nike」 |
+| 28~31 | 化妆品 / 护肤 / 饮品类 | 「无」「工夫茶」 |
+| 32~34 | 去过 / 想去 / 最想去的地方 | 「阳朔」「九寨沟」「塞班岛」 |
+| 35~37 | 游戏类型 / 游戏 / 网游 | 「格斗游戏」「魔兽争霸3」「跑跑卡丁车」 |
+| 38~43 | 菜系 / 菜 / 食材 / 餐厅 / 主食 / 饮料 | 「川菜系」「干煸鸡」「可口可乐.雪碧」 |
+| 44 | 感情状态 | 「热恋中」「未恋过」「追求中」 |
+| 45~48 | 书类型 / 书 / 作者 / 杂志 | 「小说」「诛仙」「唐家三少」「读者」 |
+| 49~51 | 宠物 / 奶粉 / 母婴品牌 | 「金毛寻回犬」「雀巢」「强生」 |
+| 52~55 | 运动 / 另一项运动 / 运动品牌 / 运动员 | 「足球」「游泳」「李宁」「刘翔」 |
+
+> ⚠️ **这一列会被 raw protobuf 解码器误判成嵌套消息或字节串。** 想读它必须先按 u16 TLV 拆，
+> 直接丢给 protobuf 解析器会得到一堆无意义的假 tag。这是本页第二个容易踩的坑。
+
+---
+
+## 九、没找到的东西
+
+诚实记录两个**确认不在这个库里**的字段，省得下次再翻一遍。
+
+### QQ 等级
+
+全库找过，**没有**。筛查方法：QQ 等级的形态特征是「好友几乎人人有、取值 1~256 连续宽分布」，
+按这个形态扫了 195 个好友行的全部 44 个标量列 + `21000` 里的全部整数 tag，
+形态匹配的候选只有这些，逐个排除：
+
+| 候选 | 为什么不是 |
+| ---- | ---------- |
+| 列 `20007` / `20008` | 是出生月（1~12）和出生日（1~31） |
+| 列 `24103` | 是年龄，与生年吻合 179/180 |
+| `21000.22004.20448` | 是 SVIP 等级（1~9），只有开通的人有 |
+| `21000.22004.28004` | 同上，与 20448 命中 22/24 |
+| `21000.22004.28027` | 上限只到 26，且只有 66/195 好友非零 |
+| `21000.22005.20018/20019` | 星座 / 生肖，都是 1~12 |
+
+**结论：QQ 等级是现拉的，不落库。** 合理 —— 等级每天变（活跃度累加），
+缓存进本地库只会立刻过时，客户端显示时走接口反而更简单。
+
+### 昵称颜色 / VIP 颜色
+
+同样**没有**。唯一形似的 `21000.22005.20021`（`"49-102-55"` 三段串）已在
+[22005 节](#22005--扩展资料) 排除 —— 与超会状态无关，与地区也无关。
+
+**推论：昵称颜色是客户端按 `bizId` + `level` 算出来的，不是存下来的。**
+`21000.22004.20059` 里已经有完整的特权清单（谁开了超会、几级、图标 URL 是 `big_light_4` 还是 `gray_0`），
+客户端拿这些就够渲染颜色了，没必要再存一份颜色值。
+
+---
+
+## 十、常见查询
+
+WeQ 实际读的列（`profile_info.ts` 的 `SELECT_COLUMNS`）：
+
+```sql
+SELECT "1000","1001","1002","20002","20004","20006","20007","20008",
+       "20009","20011","20014","20057","20070","20072","24103","24104","21000"
+FROM profile_info_v6
+WHERE "1000" = ?
+```
+
+按昵称搜人 —— **不要用 FTS**（`pinyin_letter` 分词器不存在，见 [库总览](./index.md#fts-表打不开是正常的)）：
+
+```sql
+SELECT "1000","20002" FROM profile_info_v6 WHERE "20002" LIKE ? LIMIT 50
+```
+
+批量补昵称（WeQ 的 `nicksByUids`，避免 N 次单查）：
+
+```sql
+SELECT "1000","20002" FROM profile_info_v6 WHERE "1000" IN (?,?,?,…)
+```
+
+---
+
+[← 返回 profile_info.db](./index.md) ｜ [← 返回数据库分析](../index.md)
diff --git a/docs/web-app-plan.md b/docs/web-app-plan.md
new file mode 100644
index 00000000..f2a8e6ff
--- /dev/null
+++ b/docs/web-app-plan.md
@@ -0,0 +1,317 @@
+# WeQ Web App（apps/web）实施计划
+
+浏览器打开的前后端形态，与 `apps/desktop` 并存、共享 `packages/*` 与 tRPC router。
+
+> **状态：M0–M5 全部完成。** 实施结果与偏差见文末「实施记录」。
+
+---
+
+## 0. 调查结论（改动量基线）
+
+| 层 | electron 耦合 | 处置 |
+|---|---|---|
+| `packages/*`（8 个包） | **0 处** | 原样复用，一行不动 |
+| `main/context/app_context.ts`（~800 行服务装配） | **0 处** | 原样复用 |
+| `main/ipc/trpc.ts`（16 行）、`ipc/router.ts` | **0 处** | 原样复用 |
+| 14 个 router / **259 procedure** / 14 subscription | **2 文件 ~19 处** | 抽 `HostBridge` 注入 |
+| 3 个协议 handler（media 447 / avatar 67 / resource 83 行） | `protocol.handle` + `net.fetch` | 抽适配器，双端共用 |
+| `renderer/`（51k 行） | **13 处** `window.electron` | 删 / 换 |
+| 协议 URL 拼接 | `lib/resourceUrl.ts` 15 个函数已集中 + 13 处散点 | 加前缀变量 |
+
+关键前提（已验证）：
+- `nt_helper.node` / `NineBird.node` 均为 **N-API** → 纯 Node 可直接加载，无需 rebuild。
+- `packages/db` **不依赖 better-sqlite3**，全部走 `nt_helper.executeSqlWithKey()`；`better-sqlite3` 仅存在于 `packages/codec` 的 tools/tests 语境，`src/` 零引用 → **运行时零 sqlite 原生模块**。
+- `packages/native/src/loader.ts:149` 支持 `WEQ_NATIVE_DIR` 环境变量覆盖 → 打包路径可控。
+- `main/mcp/server.ts`、`main/weq_assistant/server.ts` 已有 `node:http` + Token + `tryListen` 端口 fallback 的成熟模板。
+
+---
+
+## 1. 目标形态
+
+```
+apps/web/
+  package.json
+  src/
+    server/
+      index.ts              # 入口：装配 + 启动
+      http.ts               # node:http server + 路由分发（抄 mcp/server.ts 骨架）
+      auth.ts               # ★ 鉴权闸（本方案安全核心）
+      trpc_adapter.ts       # tRPC standalone/fetch adapter 挂载
+      protocol_adapter.ts   # IncomingMessage→Request / Response→res 适配
+      host_bridge.ts        # HostBridge 的 web 实现
+      static.ts             # 前端静态产物托管
+    client/
+      main.tsx              # 复用 desktop renderer
+      index.html
+  vite.config.ts
+```
+
+产物：`dist/server.mjs`（esbuild 单文件） + `dist/public/`（前端） + `native/`。
+
+---
+
+## 2. 分步骤
+
+### M0 — 骨架 + 鉴权（先把门守住）
+
+**新建** `apps/web/package.json`，`pnpm-workspace.yaml` 的 `apps/*` 已覆盖，无需改。
+
+**新建** `src/server/auth.ts` — 这是远程场景唯一的安全边界，必须先做：
+
+- 启动时读 `WEQ_TOKEN` 环境变量；未设置则生成随机 token 并打印到控制台（同时写入 `~/.weq/web-token`）。
+- 登录端点 `POST /_auth/login`，body `{token}`，比对用 **`crypto.timingSafeEqual`**（防时序侧信道），成功则下发 `HttpOnly; SameSite=Strict; Secure(非 loopback 时)` 的会话 cookie。
+- 中间件 `requireAuth(req)`：**默认拒绝**。白名单仅 `/_auth/login`、登录页 HTML、登录页所需的静态资源。**其余全部（含 `/trpc/*`、`/_media/*`、`/_avatar/*`、`/_asset/*`）一律校验。**
+- 登录失败计数 + 指数退避（同 IP 连续失败则延迟响应），防暴力枚举。
+- 会话存内存 Map（重启失效，可接受），带 TTL。
+- `BIND_HOST` 默认 `127.0.0.1`；要远程必须显式设 `0.0.0.0`，且此时**强制要求 `WEQ_TOKEN` 已显式设置**（不接受自动生成），否则拒绝启动 —— 避免"随手开了远程但 token 只打印在没人看的日志里"。
+
+**新建** `src/server/http.ts` — 抄 `main/mcp/server.ts:148-200` 的 `tryListen` + `startServer` 骨架，路由分发：
+
+```
+/_auth/*   → auth.ts
+/trpc/*    → trpc_adapter.ts   (requireAuth)
+/_media/*  → protocol_adapter  (requireAuth)
+/_avatar/* → protocol_adapter  (requireAuth)
+/_asset/*  → protocol_adapter  (requireAuth)
+其余       → static.ts (SPA fallback → index.html)
+```
+
+**验收**：起服务，未带 cookie 访问 `/trpc/bootstrap.xxx` 返回 401；带正确 token 登录后返回 200。
+
+---
+
+### M1 — HostBridge 抽象（解耦 19 处 electron）
+
+**新建** `packages/service/src/host/bridge.ts`（或放 `apps/desktop/src/main/host.ts` + web 各一份实现，接口放共享处）：
+
+```ts
+export interface HostBridge {
+  pickDirectory(opts?: { title?: string }): Promise<string | null>;
+  pickSaveTarget(defaultName: string): Promise<string | null>;
+  revealPath(p: string): Promise<void>;      // web: no-op
+  appVersion(): string;
+  isPackaged(): boolean;
+}
+```
+
+**改** `main/context/app_context.ts` — `AppContext` 增加 `host: HostBridge` 字段，`initAppContext()` 接受注入。
+
+**改** `main/ipc/routers/account.ts:22` — 删 `import { dialog } from 'electron'`，11 处（`showOpenDialog`×5 / `showSaveDialog`×3 / `shell.openPath`×2 / `dialog.error`×1）改走 `ctx.host.*`。
+
+**改** `main/ipc/routers/bootstrap.ts:17` — 删 `import { app, dialog } from 'electron'`，~8 处同上。
+
+**新建** desktop 侧实现（`dialog`/`shell`/`app` 原样）与 web 侧实现：
+- `pickDirectory` → 返回服务端预设导出根目录（配置项 `WEQ_EXPORT_DIR`，默认 `~/.weq/exports`），前端不弹系统对话框
+- `pickSaveTarget` → 同上，落盘后前端走 `GET /_download?id=` 取文件
+- `revealPath` → no-op（前端按钮已删）
+
+**验收**：`pnpm -r typecheck` 通过；desktop 行为无变化；`grep "from 'electron'" ipc/routers/` 零命中。
+
+---
+
+### M2 — 协议 handler 双端共用
+
+`protocol.handle(scheme, req => Response)` 用的是 Web 标准 `Request`/`Response`，与 `node:http` 同构。
+
+**改** `media_protocol.ts` / `avatar_protocol.ts` / `resource_protocol.ts`：把 handler 主体抽成纯函数 `handleMediaRequest(req: Request): Promise<Response>`，只留 `protocol.handle(SCHEME, handleMediaRequest)` 这一行 electron 代码在 desktop 侧。
+
+`net.fetch`（media 2 处、resource 1 处）替换为全局 `fetch`（Node 22 原生有；desktop 侧行为等价，electron 的 `net.fetch` 优势主要是走系统代理 —— 若依赖代理则保留注入式：`deps.fetch`）。
+
+**新建** `src/server/protocol_adapter.ts`（~80 行）：
+- `IncomingMessage` → `Request`：把 `/_media/pic?t=&name=` 重写为 `weq-media://pic?t=&name=`，headers 透传（`Range` 必须透传，视频/音频要 seek）
+- `Response` → `res`：`writeHead(status, headers)` + `Readable.fromWeb(body).pipe(res)`
+
+**验收**：desktop 图片/视频/语音/表情/装扮全部正常；web 端同一张图两边字节一致。
+
+---
+
+### M3 — tRPC over HTTP
+
+**新建** `src/server/trpc_adapter.ts` — `@trpc/server/adapters/standalone` 的 `createHTTPHandler`（或 fetch adapter），挂 `appRouter`，`createContext` 从 cookie 取会话。**router 与 259 个 procedure 一行不动。**
+
+14 个 subscription 全部是 `observable` + EventEmitter（零 electron），需要传输层支持：
+- tRPC v10 的 HTTP subscription 走 **SSE**（`httpSubscriptionLink`），或
+- 更省事：`wsLink` + `applyWSSHandler`（`ws` 已是 workspace 现成依赖）
+
+选 **WS**：一个连接覆盖全部 14 路，且与现有 `observable` 写法完全兼容。WS 握手时同样校验 cookie。
+
+**改** `renderer/src/trpc/client.ts:41`：
+```diff
+- links: [ipcLink() as unknown as TRPCLink<AppRouter>]
++ links: [splitLink({ condition: op => op.type === 'subscription',
++   true: wsLink({client: wsClient}), false: httpBatchLink({url:'/trpc'}) })]
+```
+用条件编译/环境变量区分两个 app 的 link（`import.meta.env.VITE_TARGET`）。
+
+**验收**：web 端进账号、查消息、导出进度条（subscription）实时更新。
+
+---
+
+### M4 — 前端适配（含按钮删除）
+
+**改** `lib/resourceUrl.ts` — 15 个函数内部的 `weq-media://` 前缀提取为常量：
+```ts
+const MEDIA = import.meta.env.VITE_TARGET === 'web' ? '/_media/' : 'weq-media://';
+```
+另 13 处散点（`QqMedia.tsx` / `avatarCache.ts` / `dressSkin.ts` / `graphModel.ts` / `views/cache/*` 等）收敛到 helper。
+
+**删除功能 + 对应 UI 按钮**（按你的要求，前端按钮一并删）：
+
+| 功能 | 位置 | 处置 |
+|---|---|---|
+| 窗口最小化/最大化/关闭 | `im-template/template/TitleBar.tsx:18,22,26` | web 构建下整个 TitleBar 不渲染 |
+| 关窗确认 | `components/CloseConfirmDialog.tsx:21` | 不挂载 |
+| 窗口布局 | `lib/windowLayout.ts:17` | no-op |
+| 资源管理器定位 | `components/QqMedia.tsx:65,72` (`media:reveal`/`file:reveal`) | **删按钮**，保留"复制路径" |
+| 文件下载 | `QqMedia.tsx:87` (`file:download`) | 改走 `GET /_download` |
+| 窗口截图 | `capture:window` | **删按钮** |
+| 系统认证（Windows Hello） | `system_auth.ts` | **删入口**，鉴权已由 token 承担 |
+| 应用内更新 | `update/updater.ts` + 设置页更新区块 | **删区块**，`update` router 在 web 下不挂载 |
+| 打开日志目录 | `logs:open-dir` | **删按钮** |
+| 托盘 | `index.ts:102 buildTray` | 不存在 |
+
+做法：`components/host/` 下加 `<DesktopOnly>` 包装组件（web 构建返回 `null`），配合 vite `define` 让 rollup tree-shake 掉。
+
+**验收**：web 端无任何点了没反应的按钮；`grep "window.electron" ` 在 web 构建产物中零命中。
+
+---
+
+### M5 — 构建与打包
+
+**新建** `apps/web/vite.config.ts` — 复用 desktop renderer 的 alias（`@renderer` 指向 `../desktop/src/renderer/src`）、react、tailwind 插件；`define: {'import.meta.env.VITE_TARGET': '"web"'}`。
+
+**构建脚本**（根 `package.json`）：
+```json
+"build:web": "vite build --config apps/web/vite.config.ts && esbuild apps/web/src/server/index.ts --bundle --platform=node --format=esm --external:ws --external:*.node --outfile=dist/web/server.mjs"
+```
+（`build:bot` 那条已验证过这套 esbuild 打包路径可行）
+
+**三种交付**：
+
+| 形态 | 内容 | 体积 | 说明 |
+|---|---|---|---|
+| **A. 不带 node** | `server.mjs` + `public/` + `native/` | **~15 MB**（10 MB 是 `nt_helper.node`） | 要求 Node ≥22。默认形态 |
+| **B. 自带 node（推荐）** | A + 同目录 `node.exe` + `start.bat` | ~60 MB | 解压即用，零打包器坑，`.node` 加载正常 |
+| **C. SEA / `@yao-pkg/pkg`** | 单 exe | ~110 MB | 对 `.node` 加载支持别扭，**不推荐** |
+
+A 与 B 共享同一产物，B 只多两个文件 —— 构建差异 < 10 行。
+
+`native/` 通过 `WEQ_NATIVE_DIR` 指向随包目录，`loader.ts` 无需改。
+
+`sherpa-onnx-node`（语音转录）是另一个原生模块：web 版**默认不带**，`transcribe` 相关 procedure 在 web 下不挂载；需要时按 desktop 的 `extraResources` 方式补。
+
+**验收**：干净机器解压运行，浏览器打开 → 登录 → 进账号 → 看消息 → 导出。
+
+---
+
+## 3. 安全（远程场景）
+
+按你的定位，**重点在最外层鉴权闸**：
+
+1. **默认拒绝** — `requireAuth` 覆盖 `/trpc`、`/_media`、`/_avatar`、`/_asset`、`/_download`，白名单只有登录页与登录端点。
+2. **`timingSafeEqual`** 比对 token，失败退避。
+3. **绑 `0.0.0.0` 时强制显式 `WEQ_TOKEN`**，否则拒启动。
+4. HttpOnly + SameSite=Strict cookie；非 loopback 时置 Secure（提示用户上 HTTPS/反代）。
+5. WS 握手同样校验。
+
+次要（记录但不阻塞）：`localfile?path=<绝对路径>` 在远程下是任意文件读取，闸后仍建议加个前缀白名单 —— 放 M2 收尾时顺手做。
+
+---
+
+## 4. 顺序与依赖
+
+```
+M0 骨架+鉴权 ──┐
+M1 HostBridge ─┼─→ M3 tRPC ──→ M4 前端 ──→ M5 打包
+M2 协议适配器 ─┘
+```
+
+M1 / M2 可与 M0 并行，且**两者都对 desktop 是净收益**（解耦 + 无行为变化），可以先单独合入。
+
+## 5. 工作量估计
+
+- 新写：~1200–1800 行（server 外壳 + 适配器 + 鉴权 + 两份 HostBridge 实现）
+- 改动：现有 ~40 处（19 router + 13 前端 electron + 协议 handler 签名 + URL 前缀收敛）
+- `packages/*`：**0 行**
+
+---
+
+## 6. 实施记录
+
+### 与计划的偏差
+
+**electron 耦合点比静态 grep 多。** 计划里数出 19 处，实际 22 处：`dressup.ts` 和
+`file_resource.ts` 用的是**动态** `await import('electron')`，静态 grep 抓不到。
+另外发现 `shell.showItemInFolder`（定位并高亮）与 `shell.openPath`（打开）语义不同，
+`HostBridge` 拆成了 `revealInFolder` / `revealPath` 两个方法。
+
+**传递依赖是主要障碍，且只在运行时暴露。** router 本身干净了，但仍有三条链把
+electron 拖进来，每次都表现为难懂的 `does not provide an export named 'app'`：
+
+| 污染链 | 处置 |
+|---|---|
+| `app_context` → `qq_protocol`（`app.getApplicationInfoForProtocol`） | 缓存拆到 `qq_protocol_cache.ts` |
+| 三个协议 handler 与 `protocol.handle` 同文件 | 注册集中到 `protocol_register.ts` |
+| `ipc/router` → `routers/update` → `updater`（`electron-updater`） | 类型/事件总线拆到 `update/state.ts`，动作经 `UpdateActions` 由外壳注入 |
+
+这促成了 `scripts/check-electron-free.ts`：走真实 import 图，把运行时崩溃前移成构建期失败。
+它当场就抓出了第三条链。
+
+**`net.fetch` 需要自己实现替代。** Node 的全局 `fetch` 不支持 `file://`，所以新写了
+`file_response.ts`（`createReadStream` 流式 + 完整 Range 支持）。media 里 `fileResponse`
+有 24 个调用点，为免改 24 处签名，用 `AsyncLocalStorage` 传递当前 request。
+
+**esbuild 打包踩了三个 CJS 互操作坑**（均由 `smoke-dist.ts` 暴露）：
+`silk-wasm` 要 `__filename`；`__dirname` 直接声明会与 bundle 内既有声明冲突（改用
+`define`）；`exceljs` 动态 `require('crypto')` —— esbuild 的桩会先看 `typeof require`，
+所以 banner 里定义 `require` 即可放行。
+
+**前端散点比预期少。** `lib/resourceUrl.ts` 已是集中 helper（15 个函数），42 处引用里
+只有 7 处真正散落。但手工 grep 漏了 `avatarCache.ts` 与 `resourceUrl.ts` 各有一份
+`weq-avatar://` 构造器 —— 因此加了 `scripts/check-bundle.ts` 扫产物。
+
+### 最终结构
+
+```
+apps/web/
+  src/server/{index,http,auth,trpc_adapter,protocol_adapter,host,static,login_page}.ts
+  src/server/{auth,http}.test.ts
+  scripts/{build-server.mjs,check-electron-free.ts,check-bundle.ts,smoke-dist.ts}
+  vite.config.ts
+```
+
+传输层用 `@transport` 别名分流：desktop → `transport.electron.ts`（`ipcLink`），
+web → `transport.web.ts`（`httpBatchLink` + `wsLink`）。`AppRouter` 与 259 个
+procedure 两端完全共用。
+
+### 验证
+
+| 检查 | 结果 |
+|---|---|
+| `pnpm typecheck`（13 个 workspace） | 全绿 |
+| `biome lint`（295 文件） | 0 |
+| desktop `electron-vite build` | 0 error |
+| `auth.test.ts` | 23/23 |
+| `http.test.ts`（端到端闸） | 24/24 |
+| `file_response` Range 语义 | 21/21 |
+| `check-electron-free` | 44 模块纯净 |
+| `check-bundle` | 304 产物纯净 |
+| `smoke-dist`（真实打包产物启动） | 12/12 |
+
+### 交付物
+
+`dist/` 65 MB：`server.mjs` 5.7 MB + `public/` 13 MB + `native/` 38 MB + `resources/` 9.2 MB。
+`native/` 同时含 win32-x64 / linux-x64 / linux-arm64，由 `@weq/native` 的 loader 按
+`process.platform`/`arch` 自动选 —— **一个包三平台通用**。不内置 Node（需 ≥22），
+运行前 `npm install --omit=dev` 装 3 个 external 包（`ws` + `@resvg/resvg-js`）。
+
+前端 bundle 2.09 MB（desktop 是 4.33 MB），`electron-trpc` 已完全消失。
+
+### 已知限制
+
+- `DesktopOnly` 是运行时组件，其 children 仍留在 chunk 里（不渲染但没被 tree-shake）。
+  要真正剔除需改成构建期条件编译。
+- `smoke-dist.ts` 只验到 HTTP 层；`DesktopOnly` 的 DOM 行为未做无头浏览器断言。
+- WS subscription 未在真实浏览器里跑通（服务端已挂载，14 个 subscription 待实测）。
+- 语音转录（`sherpa-onnx-node`）未纳入 web 包。
+- 远程部署时 `localfile?path=` 仍是任意文件读取面 —— 闸后风险，但建议补前缀白名单。
diff --git a/packages/account/src/session.ts b/packages/account/src/session.ts
index fcbc820e..a6b7d23d 100644
--- a/packages/account/src/session.ts
+++ b/packages/account/src/session.ts
@@ -13,6 +13,7 @@ import {
   C2cMsgDb,
   GroupMsgDb,
   RecentContactDb,
+  RecentContactTopDb,
   UidMappingDb,
   UidMap,
   ForwardMsgDb,
@@ -99,6 +100,8 @@ export interface AccountSession {
   readonly groupMsgs: GroupMsgDb;
   /** Recent-conversation list. */
   readonly recentContacts: RecentContactDb;
+  /** 置顶会话（recent_contact_top_table）。 */
+  readonly recentContactTops: RecentContactTopDb;
   /** Merged-forward / quote-reply cache (40900 column). */
   readonly forwardMsgs: ForwardMsgDb;
   /** Full-text-search index over message text (buddy_msg_fts.db). */
@@ -189,6 +192,12 @@ export async function openAccount(
     algo: ctx.algo,
   });
 
+  const recentContactTops = new RecentContactTopDb(nt, {
+    dbPath: msgDbPath,
+    key: ctx.dbKey,
+    algo: ctx.algo,
+  });
+
   // Load the uid ↔ uin ↔ sortNo directory once and keep it resident; the c2c
   // query path needs uid → sortNo (column 40027) translation on every call.
   // A failure here (e.g. table absent on an older QQ build) must NOT block
@@ -315,6 +324,7 @@ export async function openAccount(
     datalineMsgs,
     groupMsgs,
     recentContacts,
+    recentContactTops,
     forwardMsgs,
     buddyMsgFts,
     groupMsgFts,
@@ -339,6 +349,7 @@ export async function openAccount(
       datalineMsgs.close();
       groupMsgs.close();
       recentContacts.close();
+      recentContactTops.close();
       forwardMsgs.close();
       buddyMsgFts.close();
       groupMsgFts.close();
diff --git a/packages/account/src/static_session.ts b/packages/account/src/static_session.ts
index e1f42e5c..e05ba927 100644
--- a/packages/account/src/static_session.ts
+++ b/packages/account/src/static_session.ts
@@ -20,6 +20,7 @@ import {
   C2cMsgDb,
   GroupMsgDb,
   RecentContactDb,
+  RecentContactTopDb,
   UidMappingDb,
   UidMap,
   ForwardMsgDb,
@@ -149,6 +150,7 @@ export async function openStaticAccount(
   const datalineMsgs = new C2cMsgDb(nt, { ...opts(msgDbPath), table: 'dataline_msg_table' });
   const groupMsgs = new GroupMsgDb(nt, opts(msgDbPath));
   const recentContacts = new RecentContactDb(nt, opts(msgDbPath));
+  const recentContactTops = new RecentContactTopDb(nt, opts(msgDbPath));
 
   // Load the uid ↔ uin ↔ sortNo directory.
   const uidMappingDb = new UidMappingDb(nt, opts(msgDbPath));
@@ -210,6 +212,7 @@ export async function openStaticAccount(
     datalineMsgs,
     groupMsgs,
     recentContacts,
+    recentContactTops,
     forwardMsgs,
     buddyMsgFts,
     groupMsgFts,
@@ -234,6 +237,7 @@ export async function openStaticAccount(
       datalineMsgs.close();
       groupMsgs.close();
       recentContacts.close();
+      recentContactTops.close();
       forwardMsgs.close();
       buddyMsgFts.close();
       groupMsgFts.close();
diff --git a/packages/codec/src/element/types.ts b/packages/codec/src/element/types.ts
index d582ae59..53197e1b 100644
--- a/packages/codec/src/element/types.ts
+++ b/packages/codec/src/element/types.ts
@@ -234,22 +234,55 @@ export enum TipGroupElementType {
   KDISBANDORBERECYCLED = 10,
 }
 
+/**
+ * CALL 元素的 subType（= wire tag 48151 `answerType`，也等于消息行的 40012 列）。
+ *
+ * 私聊与群聊是两套编号：私聊一条消息就是一整通电话的最终状态（接通 / 未接 /
+ * 拒绝 / 取消），群聊则拆成「发起」与「已结束」两条独立消息，中间状态不落库。
+ *
+ * 2025 年前后 QQ 重构过通话模块，旧客户端与新客户端对同一语义会写不同的编号
+ * （例如视频接通旧版写 5、新版写 2），所以两个都得留着。旧记录还能靠
+ * `callFlag48156 === 0`、`duration` 存的是 unix 秒级时间戳（新版是毫秒时长）、
+ * 以及 callSummary 带「[语音通话] 」前缀来辨认。
+ */
 export enum CallSubType {
+  /** 群聊：某人发起了语音通话（callMethod=VOICE，发送者即发起人）。 */
+  GROUP_VOICE_STARTED = 1,
   VIDEO_ACCEPTED = 2,
   VIDEO_REJECTED_BY_US = 3,
+  /** 视频接通（旧版客户端编号，语义同 VIDEO_ACCEPTED）。 */
+  VIDEO_ACCEPTED_LEGACY = 5,
   VIDEO_REJECTED_BY_PEER = 6,
   VOICE_ACCEPTED = 7,
   VOICE_REJECTED_BY_US = 8,
+  /** 我方拨出、对方一直没接（旧版客户端）。 */
+  VOICE_PEER_NO_ANSWER = 9,
+  /** 我方拨出后自己取消 —「已取消，点击重拨」。 */
+  VOICE_CANCELED_BY_US = 10,
   VOICE_REJECTED_BY_PEER = 11,
   VIDEO_HANDLED_OTHER_DEVICE = 12,
   VOICE_HANDLED_OTHER_DEVICE = 13,
+  /** 群聊：语音通话已结束（callMethod=0，无发送者）。 */
+  GROUP_VOICE_ENDED = 16,
   SCREEN_SHARE_ACCEPTED = 19,
   SCREEN_SHARE_REJECTED = 22,
+  /** 群聊：视频通话已结束（callMethod=0，无发送者）。 */
+  GROUP_VIDEO_ENDED = 25,
+  /** 群聊：某人发起了视频通话（callMethod=VIDEO，发送者即发起人）。 */
+  GROUP_VIDEO_STARTED = 26,
   REMOTE_ASSIST_ACCEPTED = 33,
   REMOTE_ASSIST_FAILED = 34,
 }
 
+/**
+ * CALL 元素的通话方式（wire tag 48154 `callMethod`）。
+ *
+ * 群聊的「通话已结束」消息写 0：那条消息不属于任何发起人（40020 为空），QQ 也
+ * 不再区分是语音还是视频 —— 具体类型只能从 subType（16 / 25）看出来。
+ */
 export enum CallType {
+  /** 群通话结束提示，无方式字段。 */
+  GROUP_ENDED = 0,
   VOICE = 1,
   VIDEO = 2,
   SCREEN_SHARE = 3,
diff --git a/packages/codec/src/proto/profile/21000.ts b/packages/codec/src/proto/profile/21000.ts
index 1aee918a..92e5c385 100644
--- a/packages/codec/src/proto/profile/21000.ts
+++ b/packages/codec/src/proto/profile/21000.ts
@@ -22,13 +22,22 @@
  *           #20447 bizId   特权业务ID(超会=1, 音乐=103, 情侣=119…)
  *           #20448 level   等级(与图标 big_light_N 一致)
  *     #22005 扩展资料
+ *       #20018 constellation 星座(1..12, 由生日算出的冗余值)
+ *       #20019 zodiac        生肖(1..12)
+ *       #20020 bloodType     血型(0=未填)
+ *       #20022 occupation    职业(0=未填)
  *       #20023 degree     学历
  *       #20026 school     教育经历/学校
  *       #20027 country    国家
  *       #20028 province   省份
+ *       #20029 zip        邮编(自由文本)
+ *       #20030 address    详细地址(自由文本)
  *       #20036 city       城市
  *       #20041
  *         #20410 interest  兴趣标签(repeated)
+ *       #20039 —— 老版「个人档案」，**不是 protobuf**，是 [u16 tag][u16 len][utf8] TLV，
+ *                 装着手机/电脑/相机/汽车机型等 2008 年代的问卷答案。详见
+ *                 docs/database/profile_info/profile-info-v6.md 第八节。
  *     #22009 QQ空间相册
  *       #20066
  *         #20461 (repeated) 每张照片
@@ -95,6 +104,14 @@ export const InterestGroupWire = {
 
 /** #22005 —— 扩展资料(教育/所在地/兴趣)。 */
 export const ExtInfoWire = {
+  /** #20018: 星座(1..12 = 水瓶/双鱼/白羊/金牛/双子/巨蟹/狮子/处女/天秤/天蝎/射手/摩羯)。 */
+  constellation: ProtoField(20018, ScalarType.INT32, { optional: true }),
+  /** #20019: 生肖(1..12 = 鼠/牛/虎/兔/龙/蛇/马/羊/猴/鸡/狗/猪)。 */
+  zodiac: ProtoField(20019, ScalarType.INT32, { optional: true }),
+  /** #20020: 血型(0=未填)。 */
+  bloodType: ProtoField(20020, ScalarType.INT32, { optional: true }),
+  /** #20022: 职业(0=未填)。 */
+  occupation: ProtoField(20022, ScalarType.INT32, { optional: true }),
   /** #20023: 学历(如 "初二中级")。 */
   degree: ProtoField(20023, ScalarType.STRING, { optional: true }),
   /** #20026: 教育经历/学校。 */
@@ -103,6 +120,10 @@ export const ExtInfoWire = {
   country: ProtoField(20027, ScalarType.STRING, { optional: true }),
   /** #20028: 省份。 */
   province: ProtoField(20028, ScalarType.STRING, { optional: true }),
+  /** #20029: 邮编(自由文本, 有人填"看地址")。 */
+  zip: ProtoField(20029, ScalarType.STRING, { optional: true }),
+  /** #20030: 详细地址(自由文本)。 */
+  address: ProtoField(20030, ScalarType.STRING, { optional: true }),
   /** #20036: 城市。 */
   city: ProtoField(20036, ScalarType.STRING, { optional: true }),
   /** #20041: 兴趣标签容器。 */
diff --git a/packages/db/package.json b/packages/db/package.json
index 5f300b4b..1a76c1fc 100644
--- a/packages/db/package.json
+++ b/packages/db/package.json
@@ -25,6 +25,7 @@
     "tools:verify-avatar-probe": "tsx tools/verify_avatar_probe.ts",
     "tools:verify-new-elements": "tsx tools/verify_new_elements.ts",
     "tools:inspect-game-center": "tsx tools/inspect_game_center.ts",
+    "tools:scan-profile-info": "tsx tools/scan_profile_info.ts",
     "mutate:anti-recall-trigger": "tsx tools/mutate/anti_recall_trigger.ts",
     "mutate:insert-weq-assistant": "tsx tools/mutate/insert_weq_assistant.ts",
     "mutate:delete-weq-assistant": "tsx tools/mutate/delete_weq_assistant.ts"
diff --git a/packages/db/src/contact/index.ts b/packages/db/src/contact/index.ts
index a00740d5..eb4c80f3 100644
--- a/packages/db/src/contact/index.ts
+++ b/packages/db/src/contact/index.ts
@@ -3,10 +3,13 @@
  *
  * Reads `recent_contact_v3_table` and decodes the 40051 preview BLOB through
  * `@weq/codec`, surfacing the typed `RecentContact` shape from `types.ts`.
+ * `recent_contact_top_table` (置顶会话) is read alongside as `RecentContactTop`.
  */
 
 export { RecentContactDb } from './recent_contact';
 export type { RecentContactDbOptions } from './recent_contact';
-export type { RecentContact } from './types';
+export { RecentContactTopDb } from './recent_contact_top';
+export type { RecentContactTopDbOptions } from './recent_contact_top';
+export type { RecentContact, RecentContactTop } from './types';
 export { UidMappingDb, UidMap } from './uid_mapping';
 export type { UidMappingDbOptions, UidMappingRow } from './uid_mapping';
diff --git a/packages/db/src/contact/recent_contact_top.ts b/packages/db/src/contact/recent_contact_top.ts
new file mode 100644
index 00000000..9f947c34
--- /dev/null
+++ b/packages/db/src/contact/recent_contact_top.ts
@@ -0,0 +1,89 @@
+/**
+ * `recent_contact_top_table` — the pinned (置顶) conversations.
+ *
+ * Column map (the whole table — it only has 5 columns):
+ *   41145  id        (INTEGER, pk — a 64-bit row id, not a conversation id)
+ *   40010  chatType  (INTEGER → mapped ChatType, same enum as recent_contact)
+ *   41103  topTime   (INTEGER, unix seconds — when the pin was applied)
+ *   1000   peerUid   (TEXT — c2c peer uid; NULL on group rows)
+ *   60001  groupCode (INTEGER — group code; NULL on c2c rows)
+ *
+ * The table is a pure pin registry: no name/preview/time-of-last-message. It's
+ * joined against `recent_contact_v3_table` by `targetId` on the consumer side.
+ */
+
+import { enumName, ChatType } from '@weq/codec';
+import type { DatabaseAlgorithms, NtHelperBinding, SqlRow, SqlValue } from '@weq/native';
+import type { RecentContactTop } from './types';
+import { QqDb } from '../qq_db';
+
+const SELECT_COLUMNS = `"41145","40010","41103","1000","60001"`;
+
+export interface RecentContactTopDbOptions {
+  /** Absolute path to nt_msg.db. */
+  dbPath: string;
+  /** SQLCipher key. (omit for plain decrypted). */
+  key?: string;
+  /** Database algorithms (omit for plain decrypted). */
+  algo?: DatabaseAlgorithms;
+}
+
+export class RecentContactTopDb {
+  private readonly qq: QqDb;
+
+  constructor(nt: NtHelperBinding, opts: RecentContactTopDbOptions) {
+    this.qq = new QqDb(nt, { dbPath: opts.dbPath, key: opts.key, algo: opts.algo });
+  }
+
+  /**
+   * Every pinned conversation, most recently pinned first. QQ caps the pin
+   * count at a handful, so there's no limit/paging.
+   */
+  async getTopContacts(): Promise<RecentContactTop[]> {
+    const rows = await this.qq.query(
+      `SELECT ${SELECT_COLUMNS} FROM recent_contact_top_table ORDER BY "41103" DESC`,
+    );
+    return rows.map(rowToTopContact);
+  }
+
+  /** Drop the cached native connection. Call on account switch / shutdown. */
+  close(): void {
+    this.qq.close();
+  }
+}
+
+// ---------- row → RecentContactTop ---------------------------------------
+
+function rowToTopContact(row: SqlRow): RecentContactTop {
+  const peerUid = toStr(row[3]);
+  const groupCode = toBigint(row[4]);
+  return {
+    id: toBigint(row[0]),
+    chatType: enumName(ChatType, toNum(row[1])),
+    topTime: toBigint(row[2]),
+    peerUid,
+    groupCode,
+    targetId: peerUid || (groupCode === 0n ? '' : groupCode.toString()),
+  };
+}
+
+function toBigint(v: SqlValue | undefined): bigint {
+  if (typeof v === 'bigint') return v;
+  if (typeof v === 'number') return BigInt(v);
+  if (typeof v === 'string' && v !== '') return BigInt(v);
+  return 0n;
+}
+
+function toNum(v: SqlValue | undefined): number {
+  if (typeof v === 'number') return v;
+  if (typeof v === 'bigint') return Number(v);
+  if (typeof v === 'string') {
+    const n = Number(v);
+    return Number.isFinite(n) ? n : 0;
+  }
+  return 0;
+}
+
+function toStr(v: SqlValue | undefined): string {
+  return typeof v === 'string' ? v : '';
+}
diff --git a/packages/db/src/contact/types.ts b/packages/db/src/contact/types.ts
index f382ecf4..c01a0218 100644
--- a/packages/db/src/contact/types.ts
+++ b/packages/db/src/contact/types.ts
@@ -55,3 +55,26 @@ export interface RecentContact {
    */
   tempSourceGroupCode: bigint;
 }
+
+/**
+ * Domain shape for one row of `recent_contact_top_table` — one pinned (置顶)
+ * conversation. The table carries no display info at all; it's a pin registry
+ * that consumers join against `RecentContact` via `targetId`.
+ */
+export interface RecentContactTop {
+  /** 41145 — row primary key. Not a conversation identifier. */
+  id: bigint;
+  /** 40010 — mapped ChatType (same enum as `RecentContact.chatType`). */
+  chatType: string | number;
+  /** 41103 — when the pin was applied (unix seconds). Pin ordering key. */
+  topTime: bigint;
+  /** 1000 — c2c peer uid. Empty on group rows. */
+  peerUid: string;
+  /** 60001 — group code. 0 on c2c rows. */
+  groupCode: bigint;
+  /**
+   * The conversation key, matching `RecentContact.targetUid`: peer uid for c2c,
+   * group code (as a string) for groups. Empty if the row has neither.
+   */
+  targetId: string;
+}
diff --git a/packages/db/src/profile/profile_info.ts b/packages/db/src/profile/profile_info.ts
index 065bdef8..27976ca0 100644
--- a/packages/db/src/profile/profile_info.ts
+++ b/packages/db/src/profile/profile_info.ts
@@ -1,6 +1,9 @@
 /**
  * `profile_info_v6` — Detailed user profiles.
  *
+ * 完整 44 列的语义/填充率/未解列见
+ * `docs/database/profile_info/profile-info-v6.md`。下面只列 WeQ 实际读取的列。
+ *
  * Column map:
  *   1000   uid             (TEXT)
  *   1001   qid             (TEXT)
@@ -12,12 +15,16 @@
  *   20008  birthDay        (INTEGER)
  *   20009  remark          (TEXT)
  *   20011  signature       (TEXT)
- *   20014  gender          (INTEGER)
+ *   20014  gender          (INTEGER; 1=男 2=女 0=未知 255=保密)
  *   20057  customStatus    (BLOB/Protobuf)
  *   20070  intimacy        (INTEGER)
  *   20072  extRelation     (BLOB/Protobuf)
+ *   21000  extInfo         (BLOB/Protobuf; 最大列, 七个 2200x 分块)
  *   24103  age             (INTEGER)
  *   24104  sigUpdateTime   (INTEGER)
+ *
+ * 注意这张表是**缓存不是名册**：本机 52243 行里好友只有 195 个，其余全是群里见过的
+ * 陌生人。判定好友必须查 `buddy_list`，`20072` 非空并不等价于好友。
  */
 
 import { ProtoMsg } from '@weq/codec';
@@ -89,6 +96,14 @@ export interface ProfileExtInfo {
   province?: string;
   /** 城市。 */
   city?: string;
+  /** 星座(1..12 = 水瓶→摩羯)。 */
+  constellation?: number;
+  /** 生肖(1..12 = 鼠→猪)。 */
+  zodiac?: number;
+  /** 血型(0/缺省=未填)。 */
+  bloodType?: number;
+  /** 职业(0/缺省=未填)。 */
+  occupation?: number;
   /** 兴趣标签。 */
   interests: string[];
   /** QQ空间相册。 */
@@ -346,6 +361,10 @@ function parseExtInfo(blob: SqlValue | undefined): ProfileExtInfo | undefined {
     country: ext.extInfo?.country || undefined,
     province: ext.extInfo?.province || undefined,
     city: ext.extInfo?.city || undefined,
+    constellation: ext.extInfo?.constellation || undefined,
+    zodiac: ext.extInfo?.zodiac || undefined,
+    bloodType: ext.extInfo?.bloodType || undefined,
+    occupation: ext.extInfo?.occupation || undefined,
     interests,
     album,
   };
@@ -359,6 +378,10 @@ function parseExtInfo(blob: SqlValue | undefined): ProfileExtInfo | undefined {
     !info.country &&
     !info.province &&
     !info.city &&
+    !info.constellation &&
+    !info.zodiac &&
+    !info.bloodType &&
+    !info.occupation &&
     interests.length === 0 &&
     album.length === 0;
   return empty ? undefined : info;
diff --git a/packages/db/tools/dump_call_element.ts b/packages/db/tools/dump_call_element.ts
new file mode 100644
index 00000000..238406a3
--- /dev/null
+++ b/packages/db/tools/dump_call_element.ts
@@ -0,0 +1,48 @@
+/**
+ * Decode the CALL elements of specific msgIds from group_msg_table / c2c_msg_table.
+ *
+ * Run: pnpm tsx packages/db/tools/dump_call_element.ts <msgId> [<msgId> ...]
+ */
+
+import { loadNative } from '@weq/native';
+import { testEnv } from '@weq/testkit';
+import { QqDb } from '../src/qq_db';
+import { decodeBody } from '../src/msg/util';
+
+const ALGO = { pageHmacAlgorithm: 'SHA1', kdfHmacAlgorithm: 'SHA512' } as const;
+
+const json = (v: unknown) =>
+  JSON.stringify(v, (_k, x) => (typeof x === 'bigint' ? x.toString() : x), 2);
+
+async function main(): Promise<void> {
+  const ids = process.argv.slice(2);
+  const native = loadNative();
+  const db = new QqDb(native.ntHelper, {
+    dbPath: testEnv.msgDbPath,
+    key: testEnv.key,
+    algo: ALGO,
+  });
+
+  for (const id of ids) {
+    for (const table of ['group_msg_table', 'c2c_msg_table']) {
+      const rows = await db.query(
+        `SELECT "40001","40012","40020","40033","40050","40800" FROM ${table} WHERE "40001" = ?`,
+        [id],
+      );
+      for (const r of rows) {
+        console.log(
+          `\n═══ ${table} msgId=${id} 40012=${r[1]} sender=${r[3]}(${r[2]}) time=${r[4]} ═══`,
+        );
+        console.log('raw 40800 hex:', Buffer.from(r[5] as Uint8Array).toString('hex'));
+        console.log(json(decodeBody(r[5])));
+      }
+    }
+  }
+
+  db.close();
+}
+
+main().catch((e) => {
+  console.error('failed:', e);
+  process.exit(1);
+});
diff --git a/packages/db/tools/recent_contact_top.ts b/packages/db/tools/recent_contact_top.ts
new file mode 100644
index 00000000..7516c0e1
--- /dev/null
+++ b/packages/db/tools/recent_contact_top.ts
@@ -0,0 +1,45 @@
+/**
+ * Verify `RecentContactTopDb` against the live nt_msg.db — prints every pinned
+ * conversation and joins it against `recent_contact_v3_table` so the resolved
+ * `targetId` can be eyeballed against a real conversation name.
+ *
+ * Run:  pnpm tsx ./packages/db/tools/recent_contact_top.ts
+ */
+
+import { loadNative } from '@weq/native';
+import { RecentContactTopDb } from '../src/contact/recent_contact_top';
+import { RecentContactDb } from '../src/contact/recent_contact';
+import { testEnv } from '@weq/testkit';
+
+async function main(): Promise<void> {
+  const native = loadNative();
+  const opts = {
+    dbPath: testEnv.msgDbPath,
+    key: testEnv.key,
+    algo: { pageHmacAlgorithm: 'SHA1', kdfHmacAlgorithm: 'SHA512' } as const,
+  };
+  const topDb = new RecentContactTopDb(native.ntHelper, opts);
+  const contactDb = new RecentContactDb(native.ntHelper, opts);
+
+  const tops = await topDb.getTopContacts();
+  const nameById = new Map(
+    (await contactDb.getRecentContact(500)).map((c) => [c.targetUid, c.targetDisplayName]),
+  );
+
+  console.log(`置顶会话 ${tops.length} 个：\n`);
+  for (const top of tops) {
+    const when = new Date(Number(top.topTime) * 1000).toLocaleString('zh-CN');
+    const name = nameById.get(top.targetId) ?? '(不在最近会话列表里)';
+    console.log(
+      `  ${top.chatType.toString().padEnd(16)} ${top.targetId.padEnd(26)} ${when}  ${name}`,
+    );
+  }
+
+  topDb.close();
+  contactDb.close();
+}
+
+main().catch((e) => {
+  console.error('[recent-contact-top] failed:', e);
+  process.exit(1);
+});
diff --git a/packages/db/tools/scan_call_types.ts b/packages/db/tools/scan_call_types.ts
new file mode 100644
index 00000000..90f67957
--- /dev/null
+++ b/packages/db/tools/scan_call_types.ts
@@ -0,0 +1,220 @@
+/**
+ * Scan every message table for CALL elements (elementType=21) and tally the
+ * distinct (callMethod, subType/answerType) combinations, flagging the ones
+ * missing from CallType / CallSubType in packages/codec/src/element/types.ts.
+ *
+ * For each unknown combination we print the conversation key and send time of
+ * up to a few sample messages so they can be located in QQ itself.
+ *
+ * Run: pnpm tsx packages/db/tools/scan_call_types.ts
+ */
+
+import { loadNative } from '@weq/native';
+import { testEnv } from '@weq/testkit';
+import { QqDb } from '../src/qq_db';
+import { decodeBody } from '../src/msg/util';
+
+const ALGO = { pageHmacAlgorithm: 'SHA1', kdfHmacAlgorithm: 'SHA512' } as const;
+
+const KNOWN_METHOD: Record<number, string> = {
+  1: 'VOICE',
+  2: 'VIDEO',
+  3: 'SCREEN_SHARE',
+  5: 'REMOTE_ASSIST',
+};
+
+const KNOWN_SUBTYPE: Record<number, string> = {
+  2: 'VIDEO_ACCEPTED',
+  3: 'VIDEO_REJECTED_BY_US',
+  6: 'VIDEO_REJECTED_BY_PEER',
+  7: 'VOICE_ACCEPTED',
+  8: 'VOICE_REJECTED_BY_US',
+  11: 'VOICE_REJECTED_BY_PEER',
+  12: 'VIDEO_HANDLED_OTHER_DEVICE',
+  13: 'VOICE_HANDLED_OTHER_DEVICE',
+  19: 'SCREEN_SHARE_ACCEPTED',
+  22: 'SCREEN_SHARE_REJECTED',
+  33: 'REMOTE_ASSIST_ACCEPTED',
+  34: 'REMOTE_ASSIST_FAILED',
+};
+
+interface Sample {
+  table: string;
+  msgId: string;
+  conv: string;
+  senderUin: string;
+  time: string;
+  duration: number;
+  summary: string;
+  answerType: number;
+  unknownType: number | undefined;
+  flag48153: string | undefined;
+  flag48156: number | undefined;
+}
+
+interface Bucket {
+  count: number;
+  samples: Sample[];
+}
+
+const fmtTime = (sec: number): string => {
+  if (!sec) return '(no time)';
+  const d = new Date(sec * 1000);
+  const p = (n: number) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+};
+
+const num = (v: unknown): number => (typeof v === 'bigint' ? Number(v) : Number(v ?? 0));
+const str = (v: unknown): string => (v === null || v === undefined ? '' : String(v));
+
+const TABLES: { name: string; convCol: string; label: string }[] = [
+  { name: 'group_msg_table', convCol: '40027', label: '群' },
+  { name: 'c2c_msg_table', convCol: '40030', label: '私聊对端QQ' },
+  { name: 'dataline_msg_table', convCol: '40030', label: '数据线' },
+];
+
+const MAX_SAMPLES = 20;
+
+async function main(): Promise<void> {
+  const native = loadNative();
+  const db = new QqDb(native.ntHelper, {
+    dbPath: testEnv.msgDbPath,
+    key: testEnv.key,
+    algo: ALGO,
+  });
+
+  const buckets = new Map<string, Bucket>();
+  const methodTally = new Map<number, number>();
+  const subTypeTally = new Map<number, number>();
+  let totalCalls = 0;
+
+  for (const t of TABLES) {
+    let rows: Awaited<ReturnType<typeof db.query>>;
+    try {
+      rows = await db.query(
+        `SELECT "40001","${t.convCol}","40033","40050","40800" FROM ${t.name}`,
+        [],
+      );
+    } catch (e) {
+      console.log(`skip ${t.name}: ${(e as Error).message}`);
+      continue;
+    }
+    let calls = 0;
+    for (const r of rows) {
+      const blob = r[4];
+      if (!(blob instanceof Uint8Array)) continue;
+      let els: ReturnType<typeof decodeBody>;
+      try {
+        els = decodeBody(blob);
+      } catch {
+        continue;
+      }
+      for (const el of els ?? []) {
+        const e = el as Record<string, unknown>;
+        if (num(e.elementType) !== 21 && e.kind !== 'call') continue;
+        calls++;
+        totalCalls++;
+        const method = num(e.callMethod);
+        const sub = num(e.subType);
+        methodTally.set(method, (methodTally.get(method) ?? 0) + 1);
+        subTypeTally.set(sub, (subTypeTally.get(sub) ?? 0) + 1);
+
+        const key = `${method}|${sub}`;
+        let b = buckets.get(key);
+        if (!b) {
+          b = { count: 0, samples: [] };
+          buckets.set(key, b);
+        }
+        b.count++;
+        if (b.samples.length < MAX_SAMPLES) {
+          const summary = Array.isArray(e.callSummary)
+            ? (e.callSummary as unknown[]).map(String).join(' / ')
+            : '';
+          b.samples.push({
+            table: t.name,
+            msgId: str(r[0]),
+            conv: `${t.label} ${str(r[1])}`,
+            senderUin: str(r[2]),
+            time: fmtTime(num(r[3])),
+            duration: num(e.duration),
+            summary,
+            answerType: num(e.answerType),
+            unknownType: e.callUnknownType === undefined ? undefined : num(e.callUnknownType),
+            flag48153: e.callFlag48153 === undefined ? undefined : String(e.callFlag48153),
+            flag48156: e.callFlag48156 === undefined ? undefined : num(e.callFlag48156),
+          });
+        }
+      }
+    }
+    console.log(`${t.name}: rows=${rows.length} callElements=${calls}`);
+  }
+
+  console.log(`\n=== 总计 CALL 元素: ${totalCalls} ===`);
+
+  console.log('\n--- callMethod (48154 / CallType) 分布 ---');
+  for (const [m, c] of [...methodTally.entries()].sort((a, b) => a[0] - b[0])) {
+    const tag = KNOWN_METHOD[m] ?? '*** 未枚举 ***';
+    console.log(`  callMethod=${m}  count=${c}  ${tag}`);
+  }
+
+  console.log('\n--- subType (CallSubType) 分布 ---');
+  for (const [s, c] of [...subTypeTally.entries()].sort((a, b) => a[0] - b[0])) {
+    const tag = KNOWN_SUBTYPE[s] ?? '*** 未枚举 ***';
+    console.log(`  subType=${s}  count=${c}  ${tag}`);
+  }
+
+  const entries = [...buckets.entries()]
+    .map(([k, b]) => {
+      const parts = k.split('|');
+      return { m: Number(parts[0]), s: Number(parts[1]), b };
+    })
+    .sort((a, b) => a.m - b.m || a.s - b.s);
+
+  console.log('\n--- (callMethod, subType) 组合矩阵 ---');
+  for (const { m, s, b } of entries) {
+    const unknownM = KNOWN_METHOD[m] === undefined;
+    const unknownS = KNOWN_SUBTYPE[s] === undefined;
+    const mark = unknownM || unknownS ? '  <== 未枚举' : '';
+    console.log(
+      `  method=${m}(${KNOWN_METHOD[m] ?? '?'}) subType=${s}(${KNOWN_SUBTYPE[s] ?? '?'}) count=${b.count}${mark}`,
+    );
+  }
+
+  console.log('\n\n================ 未枚举组合的样本 ================');
+  let any = false;
+  for (const { m, s, b } of entries) {
+    if (KNOWN_METHOD[m] !== undefined && KNOWN_SUBTYPE[s] !== undefined) continue;
+    any = true;
+    console.log(
+      `\n### callMethod=${m} (${KNOWN_METHOD[m] ?? '未枚举'})  subType=${s} (${KNOWN_SUBTYPE[s] ?? '未枚举'})  共 ${b.count} 条`,
+    );
+    for (const sm of b.samples) {
+      console.log(
+        `  - [${sm.time}] ${sm.conv}  发送者=${sm.senderUin}  msgId=${sm.msgId}\n` +
+          `      表=${sm.table} 时长=${sm.duration} answerType=${sm.answerType}` +
+          ` unknownType=${sm.unknownType ?? '-'} flag48153=${sm.flag48153 ?? '-'} flag48156=${sm.flag48156 ?? '-'}\n` +
+          `      摘要="${sm.summary}"`,
+      );
+    }
+  }
+  if (!any) console.log('（没有未枚举的组合）');
+
+  console.log('\n\n================ 已枚举组合的样本（对照用） ================');
+  for (const { m, s, b } of entries) {
+    if (KNOWN_METHOD[m] === undefined || KNOWN_SUBTYPE[s] === undefined) continue;
+    console.log(`\n### method=${m}/${KNOWN_METHOD[m]} sub=${s}/${KNOWN_SUBTYPE[s]} count=${b.count}`);
+    for (const sm of b.samples) {
+      console.log(
+        `  - [${sm.time}] ${sm.conv} 发送者=${sm.senderUin} 时长=${sm.duration}` +
+          ` u=${sm.unknownType ?? '-'} f56=${sm.flag48156 ?? '-'} 摘要="${sm.summary}"`,
+      );
+    }
+  }
+
+  db.close();
+}
+
+main().catch((e) => {
+  console.error('failed:', e);
+  process.exit(1);
+});
diff --git a/packages/db/tools/scan_profile_info.ts b/packages/db/tools/scan_profile_info.ts
new file mode 100644
index 00000000..ea19aeae
--- /dev/null
+++ b/packages/db/tools/scan_profile_info.ts
@@ -0,0 +1,302 @@
+/**
+ * profile_info.db 全库普查。
+ *
+ * 目的：找出 WeQ 还没解析的列/字段 —— 尤其是「昵称颜色 / VIP 等级 / QQ 等级」
+ * 这类肉眼确定应该存在、但一直没定位到的数据。
+ *
+ * 做三件事：
+ *   1) 列出库里所有表，每张表的行数 + 列。
+ *   2) 对 profile_info_v6 每一列做填充率统计 + 标量列的取值分布(top N)。
+ *   3) 对每个 BLOB 列做「递归 tag 普查」：统计每条 tag 路径出现次数、
+ *      wire 类型、以及几个真实样例值 —— 无 schema 也能看出藏了什么。
+ *
+ * Run:  pnpm tsx ./packages/db/tools/scan_profile_info.ts [table] [--limit N]
+ */
+
+import { loadNative } from '@weq/native';
+import { decode } from '@weq/codec/raw';
+import type { Guess, RawField } from '@weq/codec/raw';
+import { testEnv } from '@weq/testkit';
+import { QqDb } from '../src/qq_db';
+
+const TABLE =
+  process.argv[2] && !process.argv[2].startsWith('--') ? process.argv[2] : 'profile_info_v6';
+const LIMIT = Number(process.env.WEQ_SCAN_LIMIT ?? 4000);
+/** 标量列取值分布的展示上限。 */
+const TOP_N = 8;
+/** 每条 tag 路径保留的样例数。 */
+const SAMPLES = 4;
+
+function log(msg = ''): void {
+  console.log(msg);
+}
+
+// ───────────────────────────── 标量统计 ─────────────────────────────
+
+interface ColStat {
+  name: string;
+  declared: string;
+  nonNull: number;
+  classes: Map<string, number>;
+  values: Map<string, number>;
+  /** 值域太大(如 uid/昵称)就停止收集分布。 */
+  tooMany: boolean;
+  blobSizes: number[];
+}
+
+function classOf(v: unknown): string {
+  if (v === null || v === undefined) return 'null';
+  if (v instanceof Uint8Array) return 'blob';
+  if (typeof v === 'bigint') return 'int';
+  if (typeof v === 'number') return Number.isInteger(v) ? 'int' : 'real';
+  if (typeof v === 'string') return 'text';
+  return typeof v;
+}
+
+function shortValue(v: unknown): string {
+  if (typeof v === 'string') return v.length > 40 ? `${v.slice(0, 40)}…` : v;
+  return String(v);
+}
+
+// ───────────────────────────── BLOB tag 普查 ─────────────────────────────
+
+interface TagStat {
+  path: string;
+  wire: Set<string>;
+  count: number;
+  /** 出现在多少行里(去重后)。 */
+  rows: number;
+  samples: string[];
+  /** 数值型字段的取值集合(小基数才有意义)。 */
+  numeric: Map<string, number>;
+  numericOverflow: boolean;
+}
+
+function bestGuess(f: RawField): Guess | undefined {
+  return f.guesses[0];
+}
+
+function renderGuess(g: Guess): string {
+  switch (g.kind) {
+    case 'len-utf8':
+      return g.value.length > 60 ? `"${g.value.slice(0, 60)}…"` : `"${g.value}"`;
+    case 'len-bytes':
+      return `<${g.value.byteLength}b ${Buffer.from(g.value).toString('hex').slice(0, 40)}>`;
+    case 'len-nested':
+      return `{${g.value.length} fields}`;
+    case 'varint-bool':
+      return String(g.value);
+    case 'varint-timestamp-sec':
+    case 'varint-timestamp-ms':
+      return g.value.toISOString();
+    default:
+      return String((g as { value: unknown }).value);
+  }
+}
+
+/** 数值型 guess → 归一化的数字字符串(用于取值分布)；非数值返回 undefined。 */
+function numericOf(g: Guess): string | undefined {
+  switch (g.kind) {
+    case 'varint-uint64':
+    case 'i64-fixed':
+      return String(g.value);
+    case 'i32-fixed':
+      return String(g.value);
+    case 'varint-bool':
+      return g.value ? '1' : '0';
+    case 'varint-timestamp-sec':
+      return String(Math.floor(g.value.getTime() / 1000));
+    case 'varint-timestamp-ms':
+      return String(g.value.getTime());
+    default:
+      return undefined;
+  }
+}
+
+function walk(
+  fields: RawField[],
+  prefix: string,
+  stats: Map<string, TagStat>,
+  seenThisRow: Set<string>,
+  depth: number,
+): void {
+  if (depth > 8) return;
+  for (const f of fields) {
+    const path = prefix ? `${prefix}.${f.tag}` : String(f.tag);
+    let st = stats.get(path);
+    if (!st) {
+      st = {
+        path,
+        wire: new Set(),
+        count: 0,
+        rows: 0,
+        samples: [],
+        numeric: new Map(),
+        numericOverflow: false,
+      };
+      stats.set(path, st);
+    }
+    st.count++;
+    if (!seenThisRow.has(path)) {
+      seenThisRow.add(path);
+      st.rows++;
+    }
+    st.wire.add(String(f.wireType));
+
+    const g = bestGuess(f);
+    if (!g) continue;
+
+    if (g.kind === 'len-nested' && g.consumedAll) {
+      walk(g.value, path, stats, seenThisRow, depth + 1);
+      continue;
+    }
+
+    if (st.samples.length < SAMPLES) {
+      const rendered = renderGuess(g);
+      if (!st.samples.includes(rendered)) st.samples.push(rendered);
+    }
+    const num = numericOf(g);
+    if (num !== undefined && !st.numericOverflow) {
+      st.numeric.set(num, (st.numeric.get(num) ?? 0) + 1);
+      if (st.numeric.size > 40) st.numericOverflow = true;
+    }
+  }
+}
+
+// ───────────────────────────── main ─────────────────────────────
+
+async function main(): Promise<void> {
+  const native = loadNative();
+  const db = new QqDb(native.ntHelper, {
+    dbPath: testEnv.profileDbPath,
+    key: testEnv.key,
+    algo: { pageHmacAlgorithm: 'SHA1', kdfHmacAlgorithm: 'SHA512' },
+  });
+
+  log(`# profile_info.db 普查  (table=${TABLE}, 采样上限=${LIMIT})\n`);
+
+  // ── 1) 全库表清单 ──
+  log('## 1. 库内表清单\n');
+  const tables = await db.query(`SELECT name FROM sqlite_master WHERE type='table' ORDER BY name`);
+  for (const t of tables) {
+    const name = String(t[0]);
+    try {
+      const count = String((await db.query(`SELECT COUNT(*) FROM "${name}"`))[0]?.[0] ?? '?');
+      const info = await db.query(`PRAGMA table_info("${name}")`);
+      const cols = info.map((r) => String(r[1])).join(' ');
+      log(`- **${name}**  rows=${count}  cols(${info.length}): ${cols}`);
+    } catch (e) {
+      log(`- **${name}**  (打不开: ${(e as Error).message})`);
+    }
+  }
+
+  // ── 2) 列统计 ──
+  log(`\n## 2. ${TABLE} 每列填充率 / 取值分布\n`);
+  const info = await db.query(`PRAGMA table_info("${TABLE}")`);
+  const cols = info.map((r) => String(r[1]));
+  const declared = new Map(info.map((r) => [String(r[1]), String(r[2] || '')]));
+
+  const total = Number((await db.query(`SELECT COUNT(*) FROM "${TABLE}"`))[0]?.[0] ?? 0);
+  const quoted = cols.map((c) => `"${c}"`).join(',');
+  const rows = await db.query(`SELECT ${quoted} FROM "${TABLE}" LIMIT ?`, [LIMIT]);
+  log(`表总行数=${total}，本次采样=${rows.length}\n`);
+
+  const stats: ColStat[] = cols.map((name) => ({
+    name,
+    declared: declared.get(name) ?? '',
+    nonNull: 0,
+    classes: new Map(),
+    values: new Map(),
+    tooMany: false,
+    blobSizes: [],
+  }));
+
+  for (const row of rows) {
+    for (let i = 0; i < cols.length; i++) {
+      const v = row[i];
+      const st = stats[i]!;
+      const cls = classOf(v);
+      st.classes.set(cls, (st.classes.get(cls) ?? 0) + 1);
+      if (cls === 'null') continue;
+      st.nonNull++;
+      if (v instanceof Uint8Array) {
+        st.blobSizes.push(v.byteLength);
+        continue;
+      }
+      if (st.tooMany) continue;
+      const key = shortValue(v);
+      st.values.set(key, (st.values.get(key) ?? 0) + 1);
+      if (st.values.size > 300) {
+        st.tooMany = true;
+        st.values.clear();
+      }
+    }
+  }
+
+  for (const st of stats) {
+    const pct = rows.length ? ((st.nonNull / rows.length) * 100).toFixed(1) : '0.0';
+    const clsStr = [...st.classes.entries()]
+      .filter(([k]) => k !== 'null')
+      .map(([k, n]) => `${k}×${n}`)
+      .join(' ');
+    log(`### ${st.name}  (${st.declared})  非空 ${st.nonNull}/${rows.length} = ${pct}%  ${clsStr}`);
+    if (st.blobSizes.length) {
+      const sorted = [...st.blobSizes].sort((a, b) => a - b);
+      const p = (q: number) => sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * q))];
+      log(`  BLOB 大小: min=${sorted[0]} p50=${p(0.5)} p90=${p(0.9)} max=${sorted.at(-1)}`);
+    }
+    if (st.tooMany) {
+      log('  取值: (高基数，略)');
+    } else if (st.values.size) {
+      const top = [...st.values.entries()].sort((a, b) => b[1] - a[1]).slice(0, TOP_N);
+      log(`  取值(${st.values.size} 种): ${top.map(([v, n]) => `${v}×${n}`).join('  ')}`);
+    }
+    log();
+  }
+
+  // ── 3) BLOB 列 tag 普查 ──
+  log(`\n## 3. ${TABLE} BLOB 列 protobuf tag 普查\n`);
+  for (let i = 0; i < cols.length; i++) {
+    const name = cols[i]!;
+    if (!stats[i]!.blobSizes.length) continue;
+    log(`\n### BLOB 列 ${name}\n`);
+    const tagStats = new Map<string, TagStat>();
+    let parsed = 0;
+    let failed = 0;
+    for (const row of rows) {
+      const v = row[i];
+      if (!(v instanceof Uint8Array) || v.byteLength === 0) continue;
+      try {
+        const fields = decode(v);
+        walk(fields, '', tagStats, new Set(), 0);
+        parsed++;
+      } catch {
+        failed++;
+      }
+    }
+    log(`解析成功 ${parsed} 行，失败 ${failed} 行，共 ${tagStats.size} 条 tag 路径\n`);
+    const sorted = [...tagStats.values()].sort((a, b) => (a.path < b.path ? -1 : 1));
+    for (const st of sorted) {
+      const pct = parsed ? ((st.rows / parsed) * 100).toFixed(1) : '0';
+      log(
+        `  ${st.path.padEnd(34)} rows=${st.rows}(${pct}%) n=${st.count} wire=${[...st.wire].join('/')}`,
+      );
+      if (st.samples.length) log(`      样例: ${st.samples.join(' | ')}`);
+      if (!st.numericOverflow && st.numeric.size > 1 && st.numeric.size <= 24) {
+        const top = [...st.numeric.entries()]
+          .sort((a, b) => b[1] - a[1])
+          .slice(0, 12)
+          .map(([v, n]) => `${v}×${n}`)
+          .join(' ');
+        log(`      取值(${st.numeric.size}): ${top}`);
+      }
+    }
+  }
+
+  db.close();
+}
+
+main().catch((e) => {
+  console.error('[scan-profile-info] failed:', e);
+  process.exit(1);
+});
diff --git a/packages/service/src/account/agentlab_export.ts b/packages/service/src/account/agentlab_export.ts
index de5cb21d..87780eec 100644
--- a/packages/service/src/account/agentlab_export.ts
+++ b/packages/service/src/account/agentlab_export.ts
@@ -64,6 +64,23 @@ async function copyIfExists(src: string, dest: string): Promise<boolean> {
   return true;
 }
 
+/**
+ * 探活：GET <url> 判断导出 bot 的 WebUI 是否在跑（3s 超时）。
+ * 200 页面 或 401（服务在跑，只是缺鉴权）都算可达。
+ */
+export async function probeBotWebUi(url: string): Promise<boolean> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 3000);
+  try {
+    const res = await fetch(url, { method: 'GET', signal: controller.signal });
+    return res.ok || res.status === 401;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 export async function buildBotExport(input: BotExportInput): Promise<BotExportResult> {
   const personaDir = join(input.outDir, 'persona');
   const stickersDir = join(personaDir, 'stickers');
diff --git a/packages/service/src/account/recent_contact.ts b/packages/service/src/account/recent_contact.ts
index c2e623dc..bf0c20d9 100644
--- a/packages/service/src/account/recent_contact.ts
+++ b/packages/service/src/account/recent_contact.ts
@@ -8,7 +8,7 @@
  */
 
 import type { AccountSession } from '@weq/account';
-import type { RecentContact } from '@weq/db';
+import type { RecentContact, RecentContactTop } from '@weq/db';
 
 export class RecentContactService {
   constructor(private readonly session: AccountSession) {}
@@ -17,4 +17,9 @@ export class RecentContactService {
   getRecentContact(limit = 200): Promise<RecentContact[]> {
     return this.session.recentContacts.getRecentContact(limit);
   }
+
+  /** 置顶会话，最近置顶的在前。 */
+  getTopContacts(): Promise<RecentContactTop[]> {
+    return this.session.recentContactTops.getTopContacts();
+  }
 }
diff --git a/packages/service/src/account/web/ptlogin.ts b/packages/service/src/account/web/ptlogin.ts
index 5e12079d..7dfc0db6 100644
--- a/packages/service/src/account/web/ptlogin.ts
+++ b/packages/service/src/account/web/ptlogin.ts
@@ -79,20 +79,38 @@ export function httpsGetCookies(
   });
 }
 
+/**
+ * ptlogin2 jump URL —— 用 clientKey 换「登录后落到 `landingUrl`」的一次性跳转地址。
+ *
+ * 跟着这个 URL 走一遍 302 链,沿途每一跳都会下发 qq.com 子域的 cookie。服务端用它
+ * 收 jar(见 {@link fetchPtlogin2Jar});网页版则把它直接交给浏览器开新标签 ——
+ * 302 链在浏览器里跑完,cookie 落进浏览器自己的 jar,等价于用户手动登录了一次。
+ *
+ * 参数与 SnowLuma 的 jump URL 逐个对齐。
+ */
+export function buildPtlogin2JumpUrl(
+  ck: ClientKeyInfo,
+  uin: string,
+  landingUrl: string,
+): string {
+  const u1 = encodeURIComponent(landingUrl);
+  return (
+    `https://ssl.ptlogin2.qq.com/jump?ptlang=1033&clientuin=${uin}` +
+    `&clientkey=${ck.clientKey}&u1=${u1}&keyindex=${ck.keyIndex}`
+  );
+}
+
 /**
  * ptlogin2 jump → 某个 qq.com 子域的完整 cookie jar。
  *
  * `u1` 落地页指向目标域的个人页,跳转链会在该域下补齐 p_skey/风控 cookie。
- * 与 SnowLuma 的 jump URL 逐参数对齐。
  */
 export async function fetchPtlogin2Jar(
   ck: ClientKeyInfo,
   uin: string,
   domain: string,
 ): Promise<Record<string, string>> {
-  const u1 = encodeURIComponent(`https://${domain}/${uin}/infocenter`);
-  const url =
-    `https://ssl.ptlogin2.qq.com/jump?ptlang=1033&clientuin=${uin}` +
-    `&clientkey=${ck.clientKey}&u1=${u1}&keyindex=${ck.keyIndex}`;
-  return httpsGetCookies(url);
+  return httpsGetCookies(
+    buildPtlogin2JumpUrl(ck, uin, `https://${domain}/${uin}/infocenter`),
+  );
 }
diff --git a/packages/service/src/common/host.ts b/packages/service/src/common/host.ts
new file mode 100644
index 00000000..f388dd12
--- /dev/null
+++ b/packages/service/src/common/host.ts
@@ -0,0 +1,82 @@
+/**
+ * `HostBridge` — the shell-specific capabilities a router may need.
+ *
+ * Everything else in `@weq/service` is pure Node. These four operations are
+ * the only ones that differ between an Electron window (native file dialogs,
+ * `shell.openPath`) and a browser served over HTTP (no dialogs at all — the
+ * server picks a directory and the client downloads over the wire).
+ *
+ * Routers call `getHost()`; each app installs its implementation at startup
+ * via `setHost()`. This keeps `import 'electron'` out of the router layer.
+ */
+
+/** Where a "save as" request should land, plus how to hand it to the user. */
+export interface SaveTarget {
+  /** Absolute path the caller should write/copy to. */
+  path: string;
+  /**
+   * Opaque id the client can use to fetch the file afterwards, when the host
+   * can't put it where the user wanted it directly (web). `null` on Electron —
+   * the user already chose the final location.
+   */
+  downloadId: string | null;
+}
+
+export interface HostBridge {
+  /**
+   * Pick a directory. Electron opens a folder dialog; web returns a
+   * server-side directory (no dialog). `null` means the user cancelled —
+   * web never cancels.
+   */
+  pickDirectory(opts?: { title?: string }): Promise<string | null>;
+  /**
+   * Pick a single file. Electron opens a file dialog; web has no way to browse
+   * the server's disk, so it returns `null` (callers surface "unsupported").
+   */
+  pickFile(opts?: { title?: string; extensions?: string[] }): Promise<string | null>;
+  /**
+   * Resolve where to save `defaultName`. Electron opens a save dialog; web
+   * allocates a path under the export dir and returns a `downloadId`.
+   */
+  pickSaveTarget(opts: {
+    defaultName: string;
+    /** Extension for the dialog filter (no leading dot). */
+    extension?: string;
+  }): Promise<SaveTarget | null>;
+  /** Reveal a path in the OS file manager / default app. No-op on web. */
+  revealPath(path: string): Promise<void>;
+  /** Select a path in the OS file manager (highlight it). No-op on web. */
+  revealInFolder(path: string): Promise<void>;
+  /** Whether {@link revealPath} does anything — the UI hides the button when false. */
+  readonly canReveal: boolean;
+  /**
+   * Show an HTML report. Electron opens an isolated window and returns `null`
+   * (already handled); web returns a URL the client should open in a new tab.
+   */
+  openHtmlReport(path: string): Promise<{ url: string } | null>;
+  /**
+   * Show an exported bot's WebUI console, logging in with `key`. Electron opens
+   * a window and returns `null`; web returns the URL for the client to open.
+   */
+  openBotConsole(opts: {
+    url: string;
+    key: string;
+    title?: string;
+  }): Promise<{ url: string } | null>;
+  /** App version string (`app.getVersion()` on Electron, package version on web). */
+  appVersion(): string;
+  /** False in dev builds. */
+  isPackaged(): boolean;
+}
+
+let installed: HostBridge | null = null;
+
+/** Install the host implementation. Call once, before any router runs. */
+export function setHost(host: HostBridge): void {
+  installed = host;
+}
+
+export function getHost(): HostBridge {
+  if (!installed) throw new Error('HostBridge not installed — call setHost() at startup.');
+  return installed;
+}
diff --git a/packages/service/src/index.ts b/packages/service/src/index.ts
index c79835c7..b8080ad8 100644
--- a/packages/service/src/index.ts
+++ b/packages/service/src/index.ts
@@ -272,6 +272,7 @@ export type { NewMessages, NtMsgHooks } from './account/nt_msg_hook';
 
 // ---- web cgi (query-only: group notice / album list / honor) ----
 export { WebQueryService, HonorType, computeBkn } from './account/web';
+export { buildPtlogin2JumpUrl, parseClientKeyJson } from './account/web/ptlogin';
 export type {
   GroupNotice,
   GroupNoticeImage,
@@ -345,6 +346,8 @@ export type {
 } from './common/voice_transcribe';
 export { getLogDir, getLogger, initLogger, logErrorContext } from './common/logger';
 export type { Logger, LoggerContext, LogLevel } from './common/logger';
+export { getHost, setHost } from './common/host';
+export type { HostBridge, SaveTarget } from './common/host';
 export { TtsService, TTS_VENDOR_CATALOG, getTtsCatalogEntry, getTtsCapabilities } from '@weq/agentlab';
 export type {
   TtsVendor,
@@ -355,5 +358,5 @@ export type {
   TtsCapabilities,
   TtsVendorCatalogEntry,
 } from '@weq/agentlab';
-export { buildBotExport } from './account/agentlab_export';
+export { buildBotExport, probeBotWebUi } from './account/agentlab_export';
 export type { BotExportInput, BotExportResult, BotExportLlmProvider } from './account/agentlab_export';
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 92775e6e..58a49dec 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -190,6 +190,79 @@ importers:
         specifier: ^6.0.0
         version: 6.4.3(@types/node@22.19.20)(jiti@2.7.0)(lightningcss@1.32.0)(tsx@4.22.4)
 
+  apps/web:
+    dependencies:
+      '@trpc/client':
+        specifier: ^10.45.4
+        version: 10.45.4(@trpc/server@10.45.4)
+      '@trpc/react-query':
+        specifier: ^10.45.4
+        version: 10.45.4(@tanstack/react-query@4.44.0(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(@trpc/client@10.45.4(@trpc/server@10.45.4))(@trpc/server@10.45.4)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@trpc/server':
+        specifier: ^10.45.4
+        version: 10.45.4
+      '@weq/account':
+        specifier: workspace:*
+        version: link:../../packages/account
+      '@weq/agentlab':
+        specifier: workspace:*
+        version: link:../../packages/agentlab
+      '@weq/codec':
+        specifier: workspace:*
+        version: link:../../packages/codec
+      '@weq/db':
+        specifier: workspace:*
+        version: link:../../packages/db
+      '@weq/desktop':
+        specifier: workspace:*
+        version: link:../desktop
+      '@weq/native':
+        specifier: workspace:*
+        version: link:../../packages/native
+      '@weq/platform':
+        specifier: workspace:*
+        version: link:../../packages/platform
+      '@weq/service':
+        specifier: workspace:*
+        version: link:../../packages/service
+      superjson:
+        specifier: ^2.2.2
+        version: 2.2.6
+      ws:
+        specifier: ^8.18.0
+        version: 8.21.0
+      zod:
+        specifier: ^3.23.8
+        version: 3.25.76
+    devDependencies:
+      '@tailwindcss/vite':
+        specifier: ^4.0.0
+        version: 4.3.0(vite@6.4.3(@types/node@22.19.20)(jiti@2.7.0)(lightningcss@1.32.0)(tsx@4.22.4))
+      '@types/node':
+        specifier: ^22.10.6
+        version: 22.19.20
+      '@types/ws':
+        specifier: ^8.5.13
+        version: 8.18.1
+      '@vitejs/plugin-react':
+        specifier: ^4.3.4
+        version: 4.7.0(vite@6.4.3(@types/node@22.19.20)(jiti@2.7.0)(lightningcss@1.32.0)(tsx@4.22.4))
+      esbuild:
+        specifier: ^0.28.1
+        version: 0.28.1
+      tailwindcss:
+        specifier: ^4.0.0
+        version: 4.3.0
+      tsx:
+        specifier: ^4.22.4
+        version: 4.22.4
+      typescript:
+        specifier: ^5.7.3
+        version: 5.9.3
+      vite:
+        specifier: ^6.0.0
+        version: 6.4.3(@types/node@22.19.20)(jiti@2.7.0)(lightningcss@1.32.0)(tsx@4.22.4)
+
   packages/account:
     dependencies:
       '@weq/db':
diff --git a/resources/emoji/market.csv b/resources/emoji/market.csv
index 744ce4ba..fb8e5d6b 100644
--- a/resources/emoji/market.csv
+++ b/resources/emoji/market.csv
@@ -25922,3 +25922,43 @@ Some are born to endless night.",1
 248069,夜白,一只叫夜白的崽崽  画师，亚麒,1
 248070,猫猫龙喵酱,画师@Nichomiazzz,1
 248072,核桃桃v2,一只路过的蓝色小猫咪,1
+248074,方菱律动1,沐泞和她们的日常,1
+248075,比噶鳅二,玄隍的小小份表情包2,1
+248076,比噶鳅,玄隍的小小份表情包,1
+248079,熊猫弟弟01,一头来自深山竹林里的野生熊猫。,1
+248080,狐月月1,尾巴很多的矮狐狸,1
+248081,Klau克劳狼,Klau克劳狼的日常表情包,1
+248082,洛水新明2.0,关注洛水新明谢谢喵,1
+248083,简笔画兰特,简笔画兰特狐狐,1
+248084,圆＆咪次5,画师：柃，记录圆子和mst的日常,1
+248086,Tockey,Tockey 画师：盐水毛小豆,1
+248087,芒果蛋糕,再见了，所有的芒果,1
+248088,核桃桃v4,一只路过的蓝色小猫咪,1
+248089,莫璇小可爱,B站关注莫璇star,1
+248090,圆＆咪次4,画师：柃，圆子和mst日常,1
+248091,小福猩趣味篇64,小福猩趣味篇64,1
+248092,小福猩呆萌篇4,小福猩呆萌篇4,1
+248093,小福猩呆萌篇5,小福猩呆萌篇5,1
+248094,小粉猩活力篇2,小粉猩活力篇2,1
+248095,小福猩活力篇45,小福猩活力篇45,1
+248096,小福猩活力篇47,小福猩活力篇47,1
+248097,小粉猩活力篇3,小粉猩活力篇3,1
+248098,小福猩呆萌篇6,小福猩呆萌篇6,1
+248099,小福猩活力篇46,小福猩活力篇46,1
+248100,库斯开播了,真的假的,1
+248101,蕾米莱娅,支持蕾米莱娅谢谢喵,1
+248102,核桃桃v3副本篇,一只路过的蓝色小猫咪,1
+248103,爱丽丝与彼岸,一起坠入彼岸吧！,1
+248104,猫羽3,猫羽的日常,1
+248105,猫羽2,猫羽的日常,1
+248106,桂木狐桂木,（假装有一段介绍）,1
+248107,鳆炤1,b站vup鳆炤,1
+248108,故障机器龙,？！鸡煲 ！？,1
+248109,蓝莓列巴第一弹,蓝莓列巴第一弹,1
+248110,海鲜鱼龙(1),扩列幺久三溜溜零四溜漆画师夜兰幽,1
+248111,吃鼠饼的小虎3,b站vup吃鼠饼的小虎,1
+248112,6D6L.（沪）,本地特别版,1
+248113,猫耳精灵,精选萌系表情一网打尽,1
+248114,精灵猫娘,梦幻精灵猫娘表情包,1
+248117,是白泠雨狐,B站白泠雨bravo，画师炸虾,1
+248118,方方鼠,方糖好吃爱吃,1
diff --git a/scripts/set-version.mjs b/scripts/set-version.mjs
index 52ce6d3c..4dcf9634 100644
--- a/scripts/set-version.mjs
+++ b/scripts/set-version.mjs
@@ -25,7 +25,7 @@ if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
 }
 
 const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
-const targets = ['package.json', 'apps/desktop/package.json'];
+const targets = ['package.json', 'apps/desktop/package.json', 'apps/web/package.json'];
 
 // Also stamp every packages/*/package.json that has a `name` field.
 for (const pkgDir of readdirSync(join(repoRoot, 'packages'))) {