跨端: 接手 pi 的两个 WebUI 开项——默认值统一到服务端契约 12/4；缓存键按账号（含一次性迁移）

pi 问"这两个开项谁执行"，我接了（他那边无 shell，我这边改过 WebUI）。两件都是他读源码读出来的实缺陷。

## 1 默认值：不是审美，是**服务端契约**（pi 更正了自己上一封）

`server/internal/models/models.go` 的 `DefaultAppearance()` 明写 `BgDim: 12, BgBlur: 4`，
且注释宣称"与客户端 backgroundStore / themeStore 的默认值一致"——而 WebUI 的
`backgroundStore.ts` 是 `dim: 24, blur: 8`，**那句注释是假的**；`lib/appearance.ts`
的 `clamp(..., 12, 4)` 又是另一套。**同一份代码里两个"默认值"**，走哪条路就落哪个数。

后果不是"两处代码不一样"这么轻：服务端"没有记录"时客户端以本地为准推上去，
于是**新账号的初始外观由第一个同步它的客户端决定**（先 WebUI 登录存 24/8，
先鸿蒙登录存 12/4）——同一个账号，压暗强度取决于谁先到。

改法：新增 `src/lib/appearanceDefaults.ts` 作为**唯一来源**（DEFAULT_DIM/DEFAULT_BLUR/
上限），`backgroundStore` 与 `lib/appearance` 都引用它，字面量全部消失。

## 2 缓存键按账号（含旧全局键的一次性迁移）

`STORAGE_KEY = 'agentmail.background'` → `storageKey(accountId)` = 前缀 + 账号；
写盘只走 `storageKey()`；旧全局键**只作为迁移源**：当前账号首次读到它时接管并存进自己的键，
然后**立刻删除**（否则下一个账号继续从它"继承"，等于把刚修的缺陷留在原地）；
未登录时不迁移（旧值不能送给一个还不知道是谁的账号）。

配套顺序：`appearanceSync` 在账号切换时**先 `reloadForAccount()` 再 `pull()`** ——
服务端"没有记录"时 `pull()` 会"以本地为准推上去"，那时"本地"必须已经是本账号的值。

## 3 判据（新增第 13 个判据文件 appearance-defaults）

`test/appearance-defaults.test.mjs`：**去 Go 源码里读** `DefaultAppearance()` 的四个字段，
再比对三处（WebUI 常量、store 的 DEFAULT_BACKGROUND 不许有字面量、鸿蒙 Appearance 的字段默认值）；
另两条钉"键按账号、不许退回全局键、旧键必须被删除"与"重读在 pull 之前"。
这样服务端那句注释是**可核对**的，不是承诺。

顺带更正：`Wallpaper.ts` 里"WebUI 默认 24"的注释已过时 → 改 12 并写明缘由；
`harmony-appearance` 里"WebUI 是全局键"的前提失效 → 改为断言两端都按账号分键。

## 验证

`npm test` 退出码 0（13 个判据文件全绿 + vitest 263 passed，原 258 + 新增 5 条行为测试：
键隔离、迁移一次并删除、未登录不迁移、默认值=12/4）。

client/electron/src/stores/backgroundStore.ts

@@ -1,5 +1,8 @@
 import { create } from 'zustand';
 
+import { AGGREGATE_ID, isUsableAccount, useAccountStore } from './accountStore';
+import { DEFAULT_BLUR, DEFAULT_DIM } from '../lib/appearanceDefaults';
+
 /**
  * 自定义背景。
  *
@@ -38,7 +41,43 @@ export interface BackgroundState {
   blur: number;
 }
 
-export const STORAGE_KEY = 'agentmail.background';
+/**
+ * 旧版本用的**全局**键。现在只用于**一次性迁移**（见 `readStored`）。
+ *
+ * ⚠️ 不要再往它写东西：全局键的后果是"切到服务端没有记录的账号"时，
+ * `saved=false` 分支会把**上一个账号的外观**推上去（新账号"继承"了外观，
+ * 而且写进了服务端）。鸿蒙侧一直是按账号分键的，这是 WebUI 侧的缺陷
+ * （pi 2026-09-14 复核时点名："鸿蒙是对的，别为对齐退回全局键"）。
+ */
+export const LEGACY_STORAGE_KEY = 'agentmail.background';
+
+/** 按账号的键前缀：实际键是 `<前缀><accountId>` */
+export const STORAGE_KEY_PREFIX = 'agentmail.background.';
+
+/**
+ * 本机当前**用于同步的那个账号**。
+ *
+ * 与 `accountStore.syncAuth()` 取同一个目标：聚合模式用第一个可用账号
+ * （发信要有身份），否则用当前选中的账号。取不到（未登录/首屏）时返回空串，
+ * 此时用一个匿名兜底键 —— 不能退回全局键，那正是要修的东西。
+ */
+export function activeAppearanceAccountId(): string {
+  try {
+    const st = useAccountStore.getState();
+    const target =
+      st.activeId === AGGREGATE_ID
+        ? st.accounts.find(a => isUsableAccount(a))
+        : st.accounts.find(a => a.id === st.activeId);
+    return target?.id ?? '';
+  } catch {
+    return '';
+  }
+}
+
+/** 缓存键：**按账号**。传 accountId 便于判据与迁移直接验证 */
+export function storageKey(accountId: string = activeAppearanceAccountId()): string {
+  return accountId ? `${STORAGE_KEY_PREFIX}${accountId}` : `${STORAGE_KEY_PREFIX}anonymous`;
+}
 
 /** 预设清单。**渐变的实际色值定义在 index.css**，这里只有 id 与显示名。 */
 export const PRESETS: { id: string; label: string }[] = [
@@ -50,12 +89,18 @@ export const PRESETS: { id: string; label: string }[] = [
   { id: 'mesh', label: '网格' }
 ];
 
+/**
+ * 默认背景。**数值来自服务端契约**（`server/internal/models/models.go` 的
+ * `DefaultAppearance()`：`BgDim: 12, BgBlur: 4`），而不再是这里自己写一套 ——
+ * 原来这里是 `24 / 8`，与 `lib/appearance.ts` 的兜底 `12 / 4` 不一致，
+ * 于是"新账号的初始外观由第一个同步它的客户端决定"（详见 `lib/appearanceDefaults.ts`）。
+ */
 export const DEFAULT_BACKGROUND: BackgroundState = {
   kind: 'none',
   presetId: 'aurora',
   imageDataUrl: '',
-  dim: 24,
-  blur: 8
+  dim: DEFAULT_DIM,
+  blur: DEFAULT_BLUR
 };
 
 /** 图片最长边。超过就等比缩小 —— 背景是满屏铺开的，再大也看不出来。 */
@@ -105,9 +150,25 @@ export function normalizeBackground(
   };
 }
 
-export function readStored(): BackgroundState {
+/**
+ * 读本机缓存。**按账号**读，并做一次旧全局键的迁移。
+ *
+ * 迁移只做一次、只给**当前账号**：旧值属于"这台机器上当时那个账号"，
+ * 把它送给当前账号是合理的（用户的观感不会凭空消失），然后**立刻删掉旧键** ——
+ * 否则下一个账号又会从它那里"继承"，等于把刚修掉的缺陷留在原地。
+ */
+export function readStored(accountId: string = activeAppearanceAccountId()): BackgroundState {
   try {
-    const raw = localStorage.getItem(STORAGE_KEY);
+    const key = storageKey(accountId);
+    let raw = localStorage.getItem(key);
+    if (!raw) {
+      const legacy = accountId ? localStorage.getItem(LEGACY_STORAGE_KEY) : null;
+      if (legacy) {
+        localStorage.setItem(key, legacy);
+        localStorage.removeItem(LEGACY_STORAGE_KEY);
+        raw = legacy;
+      }
+    }
     if (!raw) return DEFAULT_BACKGROUND;
     return normalizeBackground(JSON.parse(raw));
   } catch {
@@ -155,11 +216,14 @@ interface BackgroundStore extends BackgroundState {
   setDim: (v: number) => void;
   setBlur: (v: number) => void;
   reset: () => void;
+  /** 切换账号后按新账号重读本地缓存（必须在 pull() 之前） */
+  reloadForAccount: () => void;
 }
 
 function persist(state: BackgroundState) {
   try {
-    localStorage.setItem(STORAGE_KEY, JSON.stringify(state));
+    // 按账号写：换账号后落到各自的键，互不串味
+    localStorage.setItem(storageKey(), JSON.stringify(state));
   } catch {
     // 配额满：本次会话仍生效，只是下次打开会退回默认值。
     // 不抛给调用方 —— 背景是装饰，不该让「换背景失败」打断任何操作。
@@ -185,7 +249,21 @@ export const useBackgroundStore = create<BackgroundStore>((set, get) => {
     setImage: imageDataUrl => commit({ imageDataUrl, kind: 'image' }),
     setDim: dim => commit({ dim: clampDim(dim) }),
     setBlur: blur => commit({ blur: clampBlur(blur) }),
-    reset: () => commit({ ...DEFAULT_BACKGROUND })
+    reset: () => commit({ ...DEFAULT_BACKGROUND }),
+
+    /**
+     * 切换账号后**重读本账号的本地缓存**。
+     *
+     * 顺序很重要：重读必须发生在 `pull()` **之前** —— 服务端"没有记录"时
+     * 调用方会"以本地为准推上去"，而那时"本地"必须已经是**这个账号**的值，
+     * 不能还是上一个账号的（那正是全局键时代的缺陷：新账号继承上一个人的外观）。
+     */
+    reloadForAccount: () => {
+      const next: BackgroundState = readStored();
+      // 不 persist：这只是"把本账号已有的缓存读回来"，不是用户的改动
+      applyBackground(next);
+      set(next);
+    }
   };
 });