跨端: 接手 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)。
This commit is contained in:
2026-09-14 15:17:01 +08:00
parent 2d8f5424b5
commit e94313f66a
10 changed files with 366 additions and 25 deletions

View File

@ -0,0 +1,153 @@
// 外观的**服务端契约**与**本机缓存的键**:两个客户端的默认值必须等于服务端那三个数,
// 缓存键必须按账号分。
//
// 为什么值得单独一个判据文件:
// 1. 服务端 `DefaultAppearance()` 的注释宣称"与客户端 backgroundStore / themeStore 的
// 默认值一致" —— 在 WebUI 用 24/8 时那句话**是假的**pi 2026-09-14 更正了自己
// 上一封"数值是审美"的说法:它是契约问题)。这条判据把那句注释变成**可核对**的。
// 2. 默认值决定"新账号的初始外观":服务端"没有记录"时客户端以本地为准推上去,
// 于是**谁先同步谁决定**。24/8 与 12/4 的差别不是审美,是同一个账号在不同客户端
// 登录会得到不同的压暗强度。
// 3. 缓存键是"换账号串味"的成因(全局键 → saved=false 时把上一个账号的外观推上去)。
import { readFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { test } from 'node:test';
import assert from 'node:assert/strict';
// 与其它判据同一个约定HERE = client/electron/testROOT = 仓库根
const HERE = dirname(fileURLToPath(import.meta.url));
const ROOT = join(HERE, '..', '..', '..');
const SERVER_MODELS = join(ROOT, 'server/internal/models/models.go');
const ETS = join(ROOT, 'client/harmony/entry/src/main/ets');
/** 从 Go 源码里读服务端契约(不复制一份数字到判据里 —— 那又会变成"两处各写一套" */
function serverDefaults() {
const src = readFileSync(SERVER_MODELS, 'utf8');
// 只取 DefaultAppearance 函数体,避免匹配到别的结构体字面量
const at = src.indexOf('func DefaultAppearance()');
assert.ok(at > 0, '服务端要有 DefaultAppearance()');
let depth = 0;
let end = at;
for (let i = src.indexOf('{', at); i < src.length; i++) {
if (src[i] === '{') depth++;
else if (src[i] === '}') { depth--; if (depth === 0) { end = i; break; } }
}
const body = src.slice(at, end + 1);
const dim = /BgDim:\s*(\d+)/.exec(body);
const blur = /BgBlur:\s*(\d+)/.exec(body);
const theme = /Theme:\s*"([^"]+)"/.exec(body);
const kind = /BgKind:\s*"([^"]+)"/.exec(body);
const preset = /BgPresetID:\s*"([^"]+)"/.exec(body);
assert.ok(dim && blur && theme && kind && preset, `DefaultAppearance 里这几个字段都要有(实际:${body}`);
return {
dim: Number(dim[1]),
blur: Number(blur[1]),
theme: theme[1],
kind: kind[1],
preset: preset[1]
};
}
test('★ 默认外观 = 服务端契约(去 Go 源码里读,不在判据里写死数字)', () => {
const s = serverDefaults();
assert.deepEqual([s.dim, s.blur], [12, 4], '服务端 DefaultAppearance 是 12/4权威值');
// WebUI默认值必须来自共享常量且等于服务端
const defaults = readFileSync(join(ROOT, 'client/electron/src/lib/appearanceDefaults.ts'), 'utf8');
assert.match(defaults, new RegExp(`DEFAULT_DIM = ${s.dim}\\b`), `DEFAULT_DIM 要等于服务端的 BgDim=${s.dim}`);
assert.match(defaults, new RegExp(`DEFAULT_BLUR = ${s.blur}\\b`), `DEFAULT_BLUR 要等于服务端的 BgBlur=${s.blur}`);
// 严格store 里不许再自写一套数字(原来这里写的是 24/8与服务端不一致
const store = readFileSync(join(ROOT, 'client/electron/src/stores/backgroundStore.ts'), 'utf8');
const defBlock = /export const DEFAULT_BACKGROUND: BackgroundState = \{[\s\S]*?\};/.exec(store);
assert.ok(defBlock, 'DEFAULT_BACKGROUND 要能取到');
assert.match(defBlock[0], /dim:\s*DEFAULT_DIM/, 'dim 要引用共享常量,不许自写字面量');
assert.match(defBlock[0], /blur:\s*DEFAULT_BLUR/, 'blur 要引用共享常量');
assert.ok(!/dim:\s*\d/.test(defBlock[0]), `DEFAULT_BACKGROUND 里不许再出现数字字面量(现在:${defBlock[0].replace(/\s+/g, ' ')}`);
// 同步层的兜底值也要引用同一常量(原来 clamp(..., 12, 4) 是另写的一份)
const lib = readFileSync(join(ROOT, 'client/electron/src/lib/appearance.ts'), 'utf8');
const clamps = [...lib.matchAll(/clamp\([^)]*\)/g)].map(m => m[0]);
assert.ok(clamps.length >= 4, `clamp 调用要能取到(实际 ${clamps.length} 处)`);
for (const c of clamps) {
assert.ok(!/,\s*\d+\s*\)$/.test(c), `clamp 的兜底值要引用常量,不许写死:${c}`);
}
// 鸿蒙:默认值(在 AppearanceResponse 的字段默认值里)与预设也要与服务端对得上
const ap = readFileSync(join(ETS, 'model/Appearance.ts'), 'utf8');
assert.match(ap, new RegExp(`bg_dim: number = ${s.dim}\\b`), `鸿蒙默认压暗要等于服务端 BgDim=${s.dim}`);
assert.match(ap, new RegExp(`bg_blur: number = ${s.blur}\\b`), `鸿蒙默认模糊要等于服务端 BgBlur=${s.blur}`);
assert.match(ap, new RegExp(`theme: string = '${s.theme}'`), `鸿蒙默认主题要等于服务端 Theme=${s.theme}`);
const wp = readFileSync(join(ETS, 'model/Wallpaper.ts'), 'utf8');
assert.match(wp, new RegExp(`'${s.preset}'`), `服务端默认预设 ${s.preset} 要在鸿蒙的预设清单里`);
// 服务端那句注释现在是**事实**(它宣称"与客户端默认值一致")—— 这条就是它的核对器
const models = readFileSync(SERVER_MODELS, 'utf8');
const comment = /\/\/ DefaultAppearance[\s\S]{0,200}?func DefaultAppearance/.exec(models);
assert.ok(comment, 'DefaultAppearance 上面要有说明注释');
assert.match(comment[0], /一致/, '注释仍在宣称"与客户端默认值一致"(本判据负责让它为真)');
});
test('★ 缓存键按账号分:两端的键都带账号,且都不许退回全局键', () => {
const store = readFileSync(join(ROOT, 'client/electron/src/stores/backgroundStore.ts'), 'utf8');
// 键函数:必须把 accountId 拼进去(按块取函数体,不看调用点 —— "配对/解析"那条)
const at = store.indexOf('export function storageKey(');
assert.ok(at > 0, '要有 storageKey 函数');
let depth = 0;
let end = at;
for (let i = store.indexOf('{', at); i < store.length; i++) {
if (store[i] === '{') depth++;
else if (store[i] === '}') { depth--; if (depth === 0) { end = i; break; } }
}
const body = store.slice(at, end + 1);
assert.match(body, /STORAGE_KEY_PREFIX[\s\S]*accountId|accountId[\s\S]*STORAGE_KEY_PREFIX/,
`取键函数必须把账号拼进键里(现在:${body.replace(/\s+/g, ' ')}`);
/*
* 不许写死键名:写入的键只能是 `storageKey()`,或由它算出来的变量(迁移时写 `key`)。
* 我第一版写成"只允许字面量 setItem(storageKey(" —— 结果把迁移那次合法写入
* `setItem(key, legacy)`key 就是按账号的键)也判红了;判据要钉**键的来源**
* 不是调用的字面形状。
*/
const badWrites = [...store.matchAll(/setItem\(([^,)]+)/g)]
.map(m => m[1].trim())
.filter(k => !/^storageKey\(/.test(k) && k !== 'key');
assert.deepEqual(badWrites, [], `写入的键必须来自 storageKey()(现在这些不是:${badWrites.join('、')}`);
assert.match(store, /removeItem\(LEGACY_STORAGE_KEY\)/, '旧全局键要被删除(否则下一个账号继续从它继承)');
// 读/写都要走按账号的键(`key` 由 storageKey() 算出,见函数开头)
assert.match(store, /const key = storageKey\(accountId\)/, '键要先按账号算出来');
assert.match(store, /let raw = localStorage\.getItem\(key\)/, '读缓存要按账号的键');
assert.match(store, /localStorage\.setItem\(storageKey\(\), JSON\.stringify\(state\)\)/, '写缓存要按账号的键');
// 鸿蒙侧:键同样带账号(两边形状一致,这条差异已经消除)
const ets = readFileSync(join(ETS, 'common/AppearanceStore.ets'), 'utf8');
const eAt = ets.indexOf('prefKey(accountId: string)');
assert.ok(eAt > 0, '鸿蒙要有按账号取键的函数');
let d2 = 0;
let e2 = eAt;
for (let i = ets.indexOf('{', eAt); i < ets.length; i++) {
if (ets[i] === '{') d2++;
else if (ets[i] === '}') { d2--; if (d2 === 0) { e2 = i; break; } }
}
assert.match(ets.slice(eAt, e2 + 1), /KEY_PREFIX\s*\+\s*accountId/, '鸿蒙的键也要拼账号');
});
test('★ 切账号的顺序:**先按新账号重读本地**,再拉服务端', () => {
/*
* 服务端"没有记录"时 `pull()` 会"以本地为准推上去"——所以重读必须在前,
* 否则推上去的是上一个账号的外观(全局键时代就是这个现象,而且写进了服务端)。
*/
const sync = readFileSync(join(ROOT, 'client/electron/src/stores/appearanceSync.ts'), 'utf8');
const sub = /activeId !== prev\.activeId\)[\s\S]{0,400}?\}\);/.exec(sync);
assert.ok(sub, '要能取到账号切换的处理块');
const block = sub[0];
const reloadAt = block.indexOf('reloadForAccount()');
const pullAt = block.indexOf('.pull()');
assert.ok(reloadAt > 0, `切换账号要先重读本账号的缓存:${block.replace(/\s+/g, ' ')}`);
assert.ok(pullAt > 0, '切换账号仍然要拉服务端');
assert.ok(reloadAt < pullAt, 'reloadForAccount() 必须在 pull() 之前(顺序就是这条判据的全部意义)');
// 重读本身不许落盘(它只是把本账号已有的值读回来,不是用户的改动)
const store = readFileSync(join(ROOT, 'client/electron/src/stores/backgroundStore.ts'), 'utf8');
const rAt = store.indexOf('reloadForAccount: () => {');
assert.ok(rAt > 0, 'store 要提供 reloadForAccount');
const rBlock = store.slice(rAt, store.indexOf('}', store.indexOf('set(next)', rAt)));
assert.ok(!/persist\(/.test(rBlock), '重读不许写盘');
});

View File

@ -15,7 +15,7 @@ import { render, screen, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import BackgroundPicker from '../../src/components/BackgroundPicker';
import { STORAGE_KEY, useBackgroundStore } from '../../src/stores/backgroundStore';
import { LEGACY_STORAGE_KEY, storageKey, useBackgroundStore } from '../../src/stores/backgroundStore';
import * as store from '../../src/stores/backgroundStore';
describe('BackgroundPicker', () => {
@ -54,7 +54,7 @@ describe('BackgroundPicker', () => {
await waitFor(() => expect(document.documentElement.dataset.bg).toBe('on'));
expect(document.documentElement.style.getPropertyValue('--bg-image')).toContain('ZZZZ');
expect(JSON.parse(localStorage.getItem(STORAGE_KEY)!).kind).toBe('image');
expect(JSON.parse(localStorage.getItem(storageKey(''))!).kind).toBe('image');
});
it('图片准备失败时说出原因,并且不假装成功', async () => {

View File

@ -621,9 +621,15 @@ test('★ 多账号缓存键:**按账号**分(鸿蒙是对的,不许为"
assert.ok(!/AGENTMAIL_BACKGROUND|'agentmail\.background'/.test(store),
'不要退回 WebUI 那个全局键(那正是"换账号继承上一个人的外观"的成因)');
assert.match(store, /loadLocal\([^)]*accountId/, '读缓存要按账号');
// WebUI 侧的前提也钉一下:它确实是全局键(这条差异有据可查)
const webLib = readFileSync(join(ROOT, 'client/electron/src/lib/appearance.ts'), 'utf8');
assert.match(webLib, /agentmail\.background/, 'WebUI 现在是全局键(差异记录的依据)');
/*
* ⚠️ 这条判据原来还断言"WebUI 是全局键"(作为差异记录的依据)。
* 2026-09-14 WebUI 侧也按账号分键了dsh 接手 pi 的两个开项),**差异已消除** ——
* 所以现在断言的是"两端都是按账号的键",而且不允许任何一端退回全局键。
*/
const webStore = readFileSync(join(ROOT, 'client/electron/src/stores/backgroundStore.ts'), 'utf8');
assert.match(webStore, /export function storageKey\(/, 'WebUI 也要有按账号取键的函数');
assert.match(webStore, /LEGACY_STORAGE_KEY/, '旧全局键只作为迁移源存在');
assert.ok(!/setItem\('agentmail\.background'/.test(webStore), 'WebUI 也不许再往全局键写');
});
test('★ 主题变化时**我们自己算的值**要跟着重算pi 的规则:系统只跟它自己那部分)', () => {

View File

@ -67,6 +67,8 @@ const SUITE = [
['test/harmony-system-api.test.mjs', [], 5],
// P4 外观同步:跑 model/Appearance.ts纯逻辑所以也要 strip-types
['test/harmony-appearance.test.mjs', ['--experimental-strip-types', '--no-warnings'], 23],
// 外观契约:默认值去 Go 源码里读(服务端 DefaultAppearance 是权威)+ 缓存键按账号
['test/appearance-defaults.test.mjs', [], 3],
['test/build-stamp.test.mjs', [], 5],
['test/packaging.test.mjs', [], 3],
['test/commit-hygiene.test.mjs', ['--experimental-strip-types', '--no-warnings'], 2]

View File

@ -1,13 +1,14 @@
import { beforeEach, describe, expect, it } from 'vitest';
import {
DEFAULT_BACKGROUND,
LEGACY_STORAGE_KEY,
MAX_DATA_URL_BYTES,
STORAGE_KEY,
readStored,
storageKey,
applyBackground,
clampBlur,
clampDim,
normalizeBackground,
readStored,
useBackgroundStore
} from '../../src/stores/backgroundStore';
@ -77,7 +78,7 @@ describe('脏数据归一化', () => {
});
it('★ 瞬态里的空图片状态被持久化后,重读必须退回 none静止态不放松', () => {
localStorage.setItem(STORAGE_KEY, JSON.stringify({ kind: 'image', imageDataUrl: '', dim: 30, blur: 10 }));
localStorage.setItem(storageKey(''), JSON.stringify({ kind: 'image', imageDataUrl: '', dim: 30, blur: 10 }));
const back = readStored();
expect(back.kind).toBe('none');
// 用户接着选图片仍能成功(不是"坏状态卡死"
@ -155,13 +156,13 @@ describe('store 动作', () => {
const s = useBackgroundStore.getState();
expect(s.kind).toBe('preset');
expect(s.presetId).toBe('sand');
expect(JSON.parse(localStorage.getItem(STORAGE_KEY)!).presetId).toBe('sand');
expect(JSON.parse(localStorage.getItem(storageKey(''))!).presetId).toBe('sand');
});
it('setImage 记录图片并落盘', () => {
useBackgroundStore.getState().setImage('data:image/jpeg;base64,DDDD');
expect(useBackgroundStore.getState().kind).toBe('image');
expect(JSON.parse(localStorage.getItem(STORAGE_KEY)!).imageDataUrl).toContain('DDDD');
expect(JSON.parse(localStorage.getItem(storageKey(''))!).imageDataUrl).toContain('DDDD');
});
it('reset 回到默认并落盘', () => {
@ -170,7 +171,7 @@ describe('store 动作', () => {
const s = useBackgroundStore.getState();
expect(s.kind).toBe('none');
expect(s.presetId).toBe(DEFAULT_BACKGROUND.presetId);
expect(JSON.parse(localStorage.getItem(STORAGE_KEY)!).kind).toBe('none');
expect(JSON.parse(localStorage.getItem(storageKey(''))!).kind).toBe('none');
});
it('localStorage 抛异常时不打断操作', () => {
@ -191,3 +192,53 @@ describe('上限常量', () => {
expect(MAX_DATA_URL_BYTES).toBeLessThan(5_000_000 / 2);
});
});
describe('按账号分键(★ 这条修的是"新账号继承上一个账号的外观"', () => {
it('键按账号区分,互不串味', () => {
// pi 2026-09-14 复核时点名:全局键会让"切到服务端没有记录的账号"时,
// saved=false 分支把**上一个账号的外观**推上去(而且写进了服务端)。
expect(storageKey('acct-a')).not.toBe(storageKey('acct-b'));
expect(storageKey('acct-a')).toBe('agentmail.background.acct-a');
// 未登录/首屏(取不到账号)时用匿名键 —— 但**不能退回全局键**,那正是要修的东西
expect(storageKey('')).toBe('agentmail.background.anonymous');
expect(storageKey('')).not.toBe('agentmail.background');
});
it('两个账号的缓存互相看不见', () => {
localStorage.setItem(storageKey('acct-a'), JSON.stringify({ ...DEFAULT_BACKGROUND, dim: 30, presetId: 'sand' }));
localStorage.setItem(storageKey('acct-b'), JSON.stringify({ ...DEFAULT_BACKGROUND, dim: 5, presetId: 'ink' }));
expect(readStored('acct-a').presetId).toBe('sand');
expect(readStored('acct-a').dim).toBe(30);
expect(readStored('acct-b').presetId).toBe('ink');
expect(readStored('acct-b').dim).toBe(5);
});
it('没有本账号缓存时,旧全局键被迁移一次并立刻删除(不留"继承源"', () => {
// 迁移的意义:老用户升级后观感不凭空消失;删除的意义:下一个账号不会再从它继承
localStorage.clear();
localStorage.setItem(LEGACY_STORAGE_KEY, JSON.stringify({ ...DEFAULT_BACKGROUND, dim: 42, presetId: 'dusk' }));
const first = readStored('acct-a');
expect(first.dim).toBe(42);
expect(first.presetId).toBe('dusk');
expect(localStorage.getItem(LEGACY_STORAGE_KEY)).toBeNull();
expect(JSON.parse(localStorage.getItem(storageKey('acct-a'))!).dim).toBe(42);
// 第二个账号拿不到那份旧值,得到的是默认外观(不是继承来的)
expect(readStored('acct-b')).toEqual(DEFAULT_BACKGROUND);
});
it('未登录时不迁移(旧值不能送给一个还不知道是谁的账号)', () => {
localStorage.clear();
localStorage.setItem(LEGACY_STORAGE_KEY, JSON.stringify({ ...DEFAULT_BACKGROUND, dim: 42 }));
expect(readStored('')).toEqual(DEFAULT_BACKGROUND);
expect(localStorage.getItem(LEGACY_STORAGE_KEY)).not.toBeNull();
});
});
describe('默认值 = 服务端契约', () => {
it('默认压暗/模糊与服务端 DefaultAppearance 的 12/4 一致', () => {
// 权威值在服务端server/internal/models/models.go 的 DefaultAppearance
// 跨端那条判据会直接去 Go 源码里读这两个数比对,这里守住"本文件不再自写一套"
expect(DEFAULT_BACKGROUND.dim).toBe(12);
expect(DEFAULT_BACKGROUND.blur).toBe(4);
});
});