jianf/MailUI4Agents
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
197 Commits 1 Branch 0 Tags
f412751b37db8b9f10be52645b2e488803358388
Commit Graph

73 Commits

Author SHA1 Message Date
JianFeeeee
f412751b37 test(criteria): 规范加 §1.5「两张表各缺一半时按 id 联接，不按相邻关系配对」（pi 的建议 + 我方实测的串行实例） 2026-09-14 15:20:39 +08:00
JianFeeeee
dbdb2f5039 跨端: 修打包坑（构建失败被管道吞掉）+ dist 新鲜度判据；判据从"窗口式"改成同表达式 
接手 pi 的 WebUI 开项途中踩到三个坑，都已修好并配判据（承接 e94313f）。

## 坑 1：`npm run build 2>&1 | tail -4 && electron-builder …` 吞掉构建失败

pipeline 的退出码是 `tail` 的 → 构建失败、`&&` 照样往下走、electron-builder
**拿旧的 dist 打了新包**。而所有判据都是绿的：
- vitest 绿（见坑 2）；packaging 绿（它比 dist vs 安装包，两边都是旧的，自然一致）。

新增判据：**dist 必须比 src 新**（build-stamp）。变异：`touch` 一个 src 文件 → 红；
重新 `npm run build` → 绿。错误信息写明"注意别把它的退出码丢在管道里"。
已重构建 + 重打包（deb 与 app.asar 同批，15:19）。

## 坑 2：测试通过 ≠ 能打包

真正的失败：`AGGREGATE_ID` / `isUsableAccount` 被我当成 `accountStore` 的导出
（它们住在 `lib/accounts.ts`）。vitest 263 条全绿，生产构建直接报
`"AGGREGATE_ID" is not exported by "src/stores/accountStore.ts"` ——
测试运行时对缺的具名导出是宽容的（拿到 undefined）。**生产构建是一道独立的门。**

## 坑 3：判据写成"窗口式"，被自己的变异测试抓住两次

`appearance-defaults` 的"取键函数必须把账号拼进去"：
1. 第一版从 `export function` 切到 `}` → **参数表里的 accountId 满足了正则**，
   把实现退回全局键仍然全绿（假判据！）；
2. 第二版只取函数体 → `return accountId ? PREFIX : PREFIX;`（提了一下没用）又骗过去；
3. 第三版要求**同一个表达式里既有常量又有账号的插值/拼接**：
   两种退化都红，合法的 `PREFIX + accountId` 写法仍然绿。

三种变异都验过（红/红/绿），还原后基线绿。

## 文档

§7.12 两行改为「已修」并写明依据（默认值＝服务端契约；缓存键差异已消除，旧全局键
只作一次性迁移源）；新增 §7.20 记这三个坑与推论（产物是 gitignore 的，
"源码修好"≠"用户手上那个包修好"）。

## 验证

`npm test` 退出码 0（13 个判据文件全绿 + vitest 263 passed）；
`hvigorw assembleHap` BUILD SUCCESSFUL；`npm run build` + electron-builder 均 exit 0。
 2026-09-14 15:20:30 +08:00
JianFeeeee
e94313f66a 跨端: 接手 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）。
 2026-09-14 15:17:01 +08:00
JianFeeeee
2d8f5424b5 test(criteria): 规范补两条 + 还原纪律改写成"先固化基线再破坏" 
pi 三条增量的第三条（纠正我的写法）与配套文档：

## 1 还原纪律：禁令 → 操作顺序（pi 纠正）

我原来写的是"变异后不要用 `git checkout` 还原"——**治症不治因**。真因是
**被还原到的那个状态还没提交**（我丢的是一个刚加、尚未提交的 marker）。
可执行的形状：

> **任何破坏性还原，都要求"将被还原到的那个状态已经在某个提交里"。**

所以：**变异前先把基线提交掉**；更稳就 `git worktree add` 一个干净副本去变异。
`cp` 备份仍然可用，但它依赖"人记得备份"，顺序改对了则不依赖记性 ——
与"记得打 marker"改成"计数写在 `check()` 内部"是同一招。

本提交自身就是这条纪律的示范：先提交 `ec90cba`（helper + 移植 + 错误信息）作为基线，
再在已提交的基线上做 marker 变异验证。

## 2 共享 helper 与"失败信息自带修法"写进 §6.6

- `test/lib/checks.mjs` 的存在理由与用法（计数只可能在该模块内发生 →
  漏 marker / 计数写错位置在新判据上不可能发生）；
- **失败信息要自带修法**：red 是那个人一定会看到的东西，文档不一定被打开。
  验证方式也记了：真删掉一条判据的 marker 行跑一遍，确认错误信息能照抄执行
  （已验：输出里给了 helper 用法与样板文件路径，且 `node:test` 的判据不用管）。

## 3 规范自检关键词 7 → 9

新增 '已经在某个提交里'、'自带修法'，防止这两条被删掉还不报错。

## 验证

`npm test` 退出码 0（12 个判据文件全绿 + vitest 258/258）。
 2026-09-14 15:12:19 +08:00
JianFeeeee
ec90cba129 test(criteria): 抽出共享 check/finish（marker 不再靠记性）＋ 失败信息自带修法 
pi 的三条增量，前两条落地：

1. **错误信息自带修法**：受众不只是读过规范的人 —— 并发写 WebUI 的 agent 新加判据时不会打开
   CRITERIA.md，看到红的第一反应可能是"套件坏了"。所以把可照抄的修法写进那条错误本身
   （共享 helper 的用法 + 样板文件路径），并说明 node:test 的判据不用管。
   **red 是 ta 一定会看到的，文档不一定被打开。**

2. **marker 由共享 helper 打印**：新增 test/lib/checks.mjs（导出 check/finish），
   计数只可能在该模块内发生 → "漏打 marker"与"计数写错位置"这两类在新文件上不可能发生。
   为避免"写了没人用"（本仓踩过的坑），同时把两个手工计数的判据改用它：
   narrow-layout（原来只有 failed 计数）与 markdown-xss（原来根本没有计数器）——
   条数不变（52 / 9），套件仍全绿。

未回改其余 10 个文件：run-all 的 marker 检查已经覆盖它们。
 2026-09-14 15:11:47 +08:00
JianFeeeee
d1e0ba32f9 跨端: 壁纸遮盖色改用页面底色系（mask 两套主题都深，浅色下方向与 WebUI 相反）；模态遮罩保持 mask 
pi 提了一个**方向性**疑问，让我先把值读出来再定 —— 读完确认**他是对的**，而且这是"机制上确定不同"。

## 实测（两张 SDK 表交叉验证，不靠记忆）

`ets/build-tools/ets-loader/sysResource.js` 给名字→id，`previewer/.../resources.txt` 给 id→值：

| 令牌 | 浅色主题 | 深色主题 |
|---|---|---|
| `ohos_id_color_mask_regular`（原 `Theme.overlay`） | `#99182431` **深蓝灰** | `#b2000000` 黑 |
| `ohos_id_color_background` | `#ffffffff` **白** | `#ff18181a` 近黑 |

⇒ mask 的 light/regular/thick 是**浓度档**（同一深色的三个 alpha），不是深浅两套值：
它在**两套主题下都是深色**（模态遮罩语义）。而 WebUI 的 `--bg-scrim` 浅色是**白**
（原话「浅色下用白把花哨的图案洗淡」）—— 壁纸遮盖用 mask 就是**反方向**：
浅色主题下把预设压暗，而 WebUI 是把它洗淡。

## 改法

- 新增 `Theme.wallpaperScrim = $r('sys.color.ohos_id_color_background')`（页面底色系：
  浅色白、深色近黑，**自动换向**，与"朝底色淡化"同一意图）；预设档与图片档的遮盖层都用它。
- `Theme.overlay`（mask）**只留给模态弹层**（那里语义确实是压暗背后）。
- 不复用 `pageBg` 的原因写进注释：页面底在背景开启时会被换成**透明**
  （`bgActive ? Color.Transparent : Theme.pageBg`），而遮盖层**永远要一个真实颜色** ——
  两个用途生命周期不同，共用一个名字迟早坏一头（这个仓库撞过四次的模式）。

## 判据（从 SDK 读真值再判，不写死结论）

断言「mask 两套主题都深」「页面底色系浅白深黑」「WebUI 的 `--bg-scrim` 浅色是白」，
再落到代码：两处遮盖层必须用 `wallpaperScrim`、弹层仍用 `overlay`、两个令牌不许混用。
**这样"令牌选错方向"以后不能靠记性避免。**

变异：遮盖退回 mask → 红 1 条；只改一层 → 红 2 条。

## 文档

§7.17b-2 记这次读数（表格 + 两张表怎么读 + 为什么不复用 pageBg + 变异结果）；
§7.12 有意差异表加一行（遮盖色令牌：两个语义两个令牌，"不允许混用"）。

## 验证

`hvigorw assembleHap` BUILD SUCCESSFUL；`npm test` 退出码 0
（12 个判据文件全绿 + vitest 258/258；harmony-appearance 23 → 24 条）。
 2026-09-14 15:10:15 +08:00
JianFeeeee
a8ac2fc28b test(criteria): 闭环——判据自报条数 + 每文件期望条数（只增不减的棘轮） 
pi 指出的残余缺口：我上一轮加的自检 4 是**文本证据**（文件里有 `test(` / `check(` /
`process.exit(1)`），只能证明"**有能红的路径**"，不能证明"**它跑过**"。反例很短：

```js
const check = () => {};     // 实现被换空（现实形态：合并冲突改坏实现）
check('a', false);          // 存在、也执行了，但什么都不会红
console.log('主题：通过');   // 有输出
```

## 落地（pi 给的闭环形状）

1. 自定义 `check()` 的判据结尾打一行机器可读汇总 `RESULT pass=<条数> fail=<失败数>`
   （`node:test` 的判据不用改，已有 `# pass N`）；
2. `run-all.mjs` **只解析这个固定 marker**（不猜口语汇总——「窄屏布局：全部通过」里没有数字，
   按数字猜会误报，这一点我上轮已经实测过）；
3. 与清单里登记的**期望条数**比对，**低于 → 红**。

关键细节：**计数写在 `check()` 内部**（theme/background 原本就在内部 ++；
narrow-layout 只有 failed 计数，补了 passed；markdown-xss 按 payload 条数算）。
写在调用点或靠扫源码的话，"实现被换空"就看不见了。

棘轮"只增不减"：加判据**不用**改那个数，只有"条数掉了"才红。期望值按**实测**回填
（9/52/8/30/42/15/28/5/23/5/3/2）。

附带的可见性收益：这几轮我一直用"13→14""19→28""34→42"当信号，现在它成了判据 ——
某次改动顺手删掉两条判据、或某条被跳过，会立刻红。

## 变异

- pi 那个反例（`check` 换成空函数）→ 红（`自报 0 条 < 登记的 30 条`）；
- 删掉 5 条 `check(` 调用 → 红（`自报 47 条 < 登记的 52 条`）。

## 规范

§6.5 新增"涉及运行时行为的结论必须实测过才能写进规范/判据"——同一个错这轮犯了两次
（我从"报告 0 个测试、退出 0"推断"退出码被吞"，实测是照传；pi 拿我这个结论又建了一个洞）。
规则：**一次观察只支撑你看到的那一层**。
§6.6 记闭环形状与代价（故意删判据要同步改数字，属于一次可复核的显式编辑）。

⚠️ 并且如实记下一次**我自己违反规范**的事：写 §3 那条"变异后别用 `git checkout` 还原"的人
（就是我）在这次变异验证里又用了 `git checkout -- <文件>`，把刚加、尚未提交的 marker 抹掉了。
规矩写下来不等于会遵守 —— 已把这条实例写进规范，让人知道它是活人踩的坑。

## 验证

`npm test` 退出码 0（12 个判据文件全绿 + vitest 258/258）；`run-all` 单独跑也 exit 0。
 2026-09-14 15:06:14 +08:00
JianFeeeee
71585dc42b 跨端: 预设档补遮罩（WebUI 的 --bg-dim 不分档位）+ 主题变化时重算"我们自己算的值"；缓存键差异记入表 
pi 读 WebUI 源码后发现两处两边不一致，都处理了。这一提交同时改 harmony 与 electron，故自报家门。

## 1 预设档遮罩：**补上**（选"与 WebUI 一致"，因为那服务的是可读性）

pi 的证据：WebUI 的 `applyBackground()` **无条件**写 `--bg-dim`（默认 24），
`.app-backdrop::after` 是 `rgb(var(--bg-scrim) / var(--bg-dim))` —— **遮罩不区分档位**；
它的注释写着目的「背景越花，正文越需要一层遮罩才读得动」。
而鸿蒙当时只在 image 档压（`resolveBackground` 里那行注释还写着"preset 档不用"），
且我们已经让出了页面底 → 正文直接压在原色渐变上，**比 WebUI 更艳更亮、更不好读**。

现在两档用**同一个浓度**（同一个服务端字段），页面在预设分支的渐变之上加一层
系统遮罩色 × 浓度（浅色由系统洗白、深色压黑，不自己写 alpha）。

判据：旧断言"preset 档不压暗"**反过来**（留着理由），另加一条钉"两档同一浓度"+
"两处遮盖层都在"+"WebUI 确实无条件写 --bg-dim"（这条差异有据可查）。
变异：预设档不压 → 红 2 条；页面预设分支的遮盖层被删 → 红。

## 2 多账号缓存键：**鸿蒙是对的，不许退回**（pi 点名）

WebUI 的键是全局常量 `agentmail.background`，后果是切到服务端没有记录的账号时
`saved=false` 分支会把**上一个账号的外观** push 上去（新账号"继承"了外观，还写进了服务端）。
这条差异进 §7.12「有意差异」表，**明确写"鸿蒙是对的"**，
判据防的就是"将来有人为了两边一致把它改回去"：取键函数的**正文**里必须拼账号 id
（按块取，不是看调用点出现过 `accountId` 就当数 —— "判结构要配对/解析"那条对我自己也适用），
且不许出现 WebUI 那个全局键。变异：`prefKey` 去掉账号 → 红 2 条。

## 3 "未做" → 按 pi 的三档口径改成**已知不一致**，并把系统侧的接法做掉

pi 指出这不是"没做"：色板确实按主题算了，只是没接环境变化事件 ——
现象是运行期切系统深浅色时"系统语义色/材质立刻跟随、我们自己算的色板不重算"的**撕裂**。
他给的规则我记成了通用规则（会咬到 P5/P6）：**系统自动跟随的东西不会顺带把
"我们自己计算/缓存的值"一起更新** —— 凡随主题变化的自算值都要挂在**同一个主题变化事件**上。

照做：`applicationContext.on('environment')` → `onConfigurationUpdated` 里
**只在 `colorMode` 真换向时**重算（`applyAppearance()`），页面销毁 `off` 退订。
状态 = **未验**（只有真机/模拟器能验：切一次系统深浅色看预设是否跟着换）。

SDK 锚点与两个编译错都记进 §7.17b：`EnvironmentCallback.onConfigurationUpdated(config: Configuration)`
（`Configuration` 从 `@kit.AbilityKit` 取，**不在** `common` 命名空间下）、
`Configuration.colorMode` 是**枚举 | undefined**（字段写成 `number` 直接编译失败）、
`on('environment')` 返回 **number 型 callbackId**。变异：不订阅 → 红。

## 4 文档

- §7.12 加两行：缓存键（含 WebUI 侧开项）、遮罩浓度默认值那两套（`24/8` vs `12/4`，
  按 `clamp` 的 12/4 对齐，因为服务端缺字段时落地的是它）。
- §四 验收纪律改成**四档口径**：没做 / 未验 / 已知不一致（要写触发条件与现象）/
  机制上确定不同（必须判），并把 pi 那条"自算值必须挂主题事件"的可复用规则写进去。

## 验证

`hvigorw assembleHap` BUILD SUCCESSFUL；`npm test` 退出码 0
（12 个判据文件全绿 + vitest 258/258；harmony-appearance 20 → 23 条）。
 2026-09-14 15:04:07 +08:00
JianFeeeee
4babc96f8b test(criteria): runner 不再手写 --test（由内容推导）+ 自检 4「这条判据能不能红」；规范补两档 
pi 提的三条，第一条落地前先按他的要求**贴真实样本实测**，结论与他的猜测不同（记在代码里）。

## 1 runner 内部那个"配错 flag = 绿" —— 实测后换了个形状

pi 的猜测：给自定义 `check()` 的判据传 `--test`，runner 会报"0 个测试"并以 0 退出。
实测（node v22.22.2，两条真实样本）：

- `node --test <自定义 check() 判据>`：**退出码照样传出来**（文件 exit 1 → 命令行 exit 1），
  没有被吞；
- 但 `node --test <什么都不做的文件>` 报 `# tests 1 / # pass 1` ——
  **pass 计数不是"检查跑过"的证据**。

所以"解析 pass 计数、0 就判红"这条路两头不讨好：抓不到空判据（它报 1），
还会在 `narrow-layout` 上误报（它的汇总行是"窄屏布局：全部通过"，里面没有数字）——
正是 pi 提醒的"别照抄我的正则，先贴样本"。

换成两条**结构证据**：

- **`--test` 不再手写**：由文件内容推导（源码里 `from 'node:test'` 就走 node:test），
  清单里出现手写 `--test` 直接红 —— 配对错误不再靠记性维护；
- **自检 4**：每条判据文件里必须存在"能红"的路径（`test(` / `check(` / `process.exit(1)`），
  外加"跑完必须有输出"。一个都没有 = 它永远不会红，与"全通过"长得一模一样
  （这是"判据自己不会跑"家族的第 6 个宿主，家族表和六种宿主都写进规范了）。

变异：清单手写 `--test` → 红；加一条"什么都不做、退出 0"的判据 → 红；
静默成功（有能红路径但一行不输出）→ 红。

## 2 规范 §3 补一档：变异红了还要看**红在哪**（pi）

"只报红了不算，要能指名红的是哪几条"；**红在解析/加载失败上不算红**（先让变异
"语法正确、语义错"）；变异作用于被剥掉的注释也不算。

## 3 `CRITERIA.md` 的可见性（pi 提的位置问题）

它管两个客户端的判据，却躺在 electron 的测试目录里。已在
`docs/HARMONY-ALIGN-PLAN.md` §四（验收纪律）加指针，并顺手把 pi 点名过的两条口径写死在那儿：
**"未验"只能用于"步骤做过、结果没看"，功能不存在必须写"没做"**；
**"机制上确定不同"要判、不许记成"未验"**（深色档预设那次）。

## 验证

`npm test` 退出码 0（12 个判据文件全绿 + vitest 258/258）。
 2026-09-14 15:00:26 +08:00
JianFeeeee
22c9be7181 跨端: 预设色板两套（pi：这不是"观感未验"而是机制上确定不同）+ 手写色清册跨文件 + TMPDIR 按会话分家 + 提交归属可判 
pi 读完 `model/Wallpaper.ts` 后指出四处，全部处理。这一提交同时改了
`client/harmony/` 与 `client/electron/`（跨端改动），所以 subject 按新约定自报家门。

## 1 预设色板不随主题 —— **类别判错了：不是"未验"，是机制上确定不同**

我上一版把"深色档预设"记成"观感未验"。pi 指出：WebUI 的 `.bg-preset-*` 写的是
`rgb(var(--c-blue-100))`，而 `--c-*` 在 `.dark` 里整体换了一套（blue-100 → `30 43 67`），
所以 **WebUI 的预设自动随主题变**；这边只有浅色那套 = 深色主题下"浅色渐变垫在深色系统表面之下"，
正是这一整轮在治的病。**它不需要真机就能判**（机制写在代码里）—— 我把可判的东西
记成了"未验"，这跟上一轮把"没做"写成"没验"是同一类错。

选 pi 倾向的那条（跟随主题，与 WebUI 一致）：

- 色板两套：`LIGHT_*` 取 CSS `:root`、`DARK_*` 取 CSS `.dark`；`paletteFor(dark)` 选一套，
  `layersFor(id, dark)` 按主题出层；
- `isDarkMode(theme, systemColorMode)` 放在纯逻辑里：选了 dark/light 就照办，
  `system` 看系统当时的 `colorMode`（锚到 SDK：`COLOR_MODE_DARK = 0` / `COLOR_MODE_LIGHT = 1`；
  读不到按浅色，与 WebUI 的 `:root` 默认一致）；
- 系统深浅从 `resourceManager.getConfigurationSync().colorMode` 读
  （`Context` 基类没有 `config`；`UIAbilityContext.config` 要转型；两个枚举取值一致，都核过 SDK）；
- 判据：两套值与 `:root`/`.dark` **逐个相等**；每个预设的深浅两套**必须真的不同**
  （否则"两套"是抄了两遍）；网格线色也要换；`isDarkMode` 五种输入。
- **未做**：运行期间改系统深浅色不会自动重算（要重进页面）——系统侧正确做法是订阅
  `applicationContext.on('environment', …)`，记在 §7.17b。

变异：`DARK_BLUE_100` 偏一位 → 红；`paletteFor` 永远返回浅色（= 我原来那个状态）→ 红；
`isDarkMode` 把系统深浅记反 → 红；页面把深浅写死成 false → 红。

## 2 手写色清册**跨文件按类扫**（原 A2 只保护 `Theme.ets`）

`Wallpaper.ts` 也有手写色。若对照是"按名字枚举"的，第 15 个色就会逃掉 ——
与 A2 要防的是同一件事，只是换了文件。现在一份清册按类扫：全 `ets/` 树里每个
`X: string = '#RRGGBB'` 都必须登记（Theme 的品牌/业务语义色，或预设色板 ——
后者常量名必须带 `LIGHT_`/`DARK_` 前缀，值由 CSS 两段比对负责）。反向也判清册过期。

变异：`Theme.ets` 加未登记色 → 红；`Wallpaper.ts` 加未登记色 → 红；
加一个"看着合规"的 `DARK_EXTRA` → 红。

## 3 `TMPDIR` 互踩（pi 提出）

这个 worktree 可能同时有多个 agent 跑构建，而 fpm 会把 291MB 的 `linux-unpacked`
**整份复制**进 `TMPDIR` —— 撞车就是随机的产物损坏。`whoami` 区分不开（大家都是 root），
所以按**会话**分家：`TMPDIR=$PWD/.tmp/${DSH_SESSION_ID:-$(id -un)-$$}`
（进了 `npm run build:linux` 与 BUILD.md 的手敲命令；普通终端退化成"用户+PID"）。

## 4 提交归属变成**跑判据就看得出来**（pi 给的形状）

新的 `test/commit-hygiene.test.mjs`：扫最近 40 条提交，**同时改两侧目录**的提交
必须在 subject 里自报家门（`跨端:`）。两条防腐：基线 = 该判据文件自己的引入提交
（**历史不改**，规则管从今往后）；分类逻辑拿合成输入自检
（未标注的混合提交必须判红、标注过的不许红）——否则"解析没跑起来"时它会全绿。
变异：`COMMIT_HYGIENE_BASELINE` 指到老提交 → 历史里那两个被卷进去的提交立刻判红。

## 验证

`hvigorw assembleHap` BUILD SUCCESSFUL；`npm test` 退出码 0
（12 个判据文件全绿 + vitest 258/258；`commit-hygiene` 在本提交落地后基线生效）。
 2026-09-14 14:57:18 +08:00
JianFeeeee
0ce8b29546 test(criteria): 判据规范 CRITERIA.md（邻接不是结构·第三次露头）+ 废弃 API allow-list 结构化 + 扫描范围自检 
pi 的两条增量，都不需要他再确认。

## 1（pi 建议）：生成清单 + 空 allow-list 的结构性风险

他的推演：SDK 升版会往清单里加新条目 → 某天早上套件**突然红**，且红在与本次改动无关的
代码上；这时人的第一反应是把名字塞进 allow-list —— 而 allow-list 一旦这么用，
就不再是"研究过的例外"，只是"红的止痛药"。所以条目结构化：

```js
const ALLOW = [ /* { name, replacement, why } */ ];
```

`replacement` 非空是硬断言（"暂时不想改"不是放行理由，"替代品要求的 API level 高于基线"才是）。
**刻意不断言"名单必须为空"** —— 那会挡住合理放行；断言的是"有名字、没替代品 → 红"，
于是侵蚀发生时红的是**放行这件事本身**，而不是某天的新 SDK。
变异：塞一条 `{ name:'px2vp', replacement:'', why:'暂时不想改' }` → 红。

## 2（pi 建议）：扫目录的判据要防"空判据"

他问废弃 API 判据扫哪些目录（怕只扫 `pages/`，`common/` 里的旧写法逃掉）。
答案：扫的是**整个 ets 目录递归**（实测 25 个文件，含 `pages/ common/ model/ api/ entryability/`）。
顺手加了防退化的自检：文件数 ≥ 20，且 `pages/ common/ model/ api/` 四个目录都必须扫到
—— 目录改名/只扫一个子目录会让这条变成空判据而依然全绿。
变异：把扫描范围改成只扫 `pages/` → 红。

## 3（pi 建议）：把"邻接不是结构"写进判据规范

同一个坑在本仓露头三次：① 窗口式正则被一行注释挤爆（原注释自嘲过）；
② 括号配对取代窗口；③ 链式修饰符让"看前一个字符是不是 `}`"静默失效。
共同形式值得升格成规则，于是新建 `client/electron/test/CRITERIA.md`（七条），
并在 `run-all.mjs` 加**自检 3**：规范文件必须在、且必须点到关键条目。
WebUI 侧 `background.test.mjs` 的窗口式存量按 pi 的说明**记着不动**（那是他的地盘）。

规范里另外两条是本仓自己踩出来的：剥注释读代码 vs 读原文读理由（混用必红）；
以及**验证要按真实入口跑** —— 我用 `node --test test/run-all.mjs` 验自检 3 时它"依然绿"，
其实是 runner 把内部的 `process.exit(1)` 吞了；换成 `npm test` 走的那一行就红对了。
变异：删掉规范里的一条关键规则 → `npm test` 那条路 exit 1。

## 验证

`npm test` 退出码 0（11 个判据文件全绿 + vitest 258/258）；`hvigorw assembleHap` 未受影响。
 2026-09-14 14:51:30 +08:00
JianFeeeee
962df62801 feat(harmony): P4b 预设档画法 + 壁纸真的渲染出来（并更正我上一轮"未验渲染"的说法） 
pi 复核时问了一个比上传入口更基础的问题：WebUI 的背景有**预设渐变**，
鸿蒙拿到 preset 名画得出来吗？只支持 image/none 的话，"换账号后外观跟随"
对预设档就是**不成立**的（用户设了预设，在鸿蒙看到的是没有背景）—— 信息对等缺口。

查下来比他说的更糟：**P4 第一版没有任何东西去画背景** —— `AppearanceStore` 取回了
`PixelMap`、算好了快照，但没有组件渲染它（预设更是完全没实现）。
上一轮我在文档里写的是"壁纸在真机上的**渲染**效果未验"，听着像"已经画出来了只是没上真机看"——
那是**说得比证据强**。取回像素这件事是真的（提交信息没写错），但"渲染未验"把"没做"说成了"没验"。
已在 §7.16 更正，并把这条记进文档以免后来人当成回归。

## 改了什么

- `model/Wallpaper.ts`（纯逻辑，判据直接跑）：6 个预设（id/中文标签/归一化）、色板、
  每个预设由哪些层叠出来、`resolveBackground()` 决定画什么（`image` 档但图没取回来 → 什么都不画）。
- `MainPage`：`WallpaperLayer` —— 预设用**系统原语** `radialGradient`/`linearGradient`；
  **网格档**（CSS 的 `repeating-linear-gradient`）系统没有对应原语 → 用系统 `Canvas` 画线
  （线色/间隔照抄 CSS），理由写在模块注释里；图片档 `Image(pixelMap)` + 系统遮罩色按服务端浓度压暗。
- **页面底让出**（这条不做，"画出来了"就是假的）：每个页面自己会刷一层**不透明**的系统页面底，
  壁纸会被全盖住。WebUI 侧的原话是「页面底 → 完全透明，让出背景；不改 27 个组件的 class，
  逐个加 class 必然漏（漏掉的那块就是一张不透明卡片浮在背景上）」。
  现在 `bgActive` 从主界面 → 通信页 + 联系人页 → 三个 pane，五个页面底全部让出。

## 判据（harmony-appearance 11 → 18 条）

预设 id/顺序/标签与 WebUI `PRESETS` 逐字一致；**预设色值与 CSS 调色板变量逐个对照**；
色板反向检查（登记了没用 → 红）；透明用关键字而非 8 位色值；三档 resolve 行为；
页面真的画了（三种系统原语 + 图片 + 压暗 + 铺在内容之下）；**页面底没有一处还在用不透明底**
+ 开关必须真的传到每个页面；模糊归属的互斥形式（壁纸层零模糊 / 导航条必须有系统材质）。

变异：预设少一档 → 红 2 条；preset 档不画东西 → 红；image 档图没取回来照样画 → 红；
色值写错两位 → 红；壁纸层加模糊 → 红；**五个页面里只漏一个没让出页面底 → 红**；
联系人页没收到开关 → 红。

## 判据抓到的真 bug

`--c-blue-200`（CSS：191 219 254 = `#BFDBFE`）我写成了 `#BFDCFE` —— 两位字母顺序反了。
"照 CSS 读出来比"才拦得住这类错。另外判据自己有两处切片毛病（用 `indexOf('build() {')`
两头夹会跨到别的成员上 / 断"注释里写了理由"却读了剥注释的源码），已改。

## 另外两件

- pi 撤回了他"模糊只由壁纸层负责"那句（那是 WebUI 的架构结论），按他给的两条性质
  （同一张底只糊一次 / 模糊该出现在背后是可变内容的层）写成互斥形式判据，记在 §7.18；
  并写明 WebUI 的"壁纸模糊度(px)"与鸿蒙的"材质档次"**不是同一个物理量**（§7.18 末）。
- **重打包**：pi 的 WebUI 补丁（c9717da / 2e42aac）重建了 `dist`（14:30），
  而安装包是 13:49 的 —— `packaging` 判据正确地判红。已按 BUILD.md 的写法重打 deb
  （`-c.electronDownload.isVerifyChecksum=false`；第一次不带这个参数时 electron-builder
  卡在下载校验上超时，失败原因如实记在这里）。

## 验证 / 未验

`hvigorw assembleHap` BUILD SUCCESSFUL；`npm test` 退出码 0（11 个判据文件全绿 + vitest 258/258）。
**未验**：预设渐变与图片壁纸在真机上的观感（尤其**深色模式**下预设的表现 ——
色板取的是 CSS 浅色档，深色档要不要另给一套，等真机看过再定）；
卡片面（系统 `surface`，不透明）盖在壁纸上是否该半透明 —— 也留到真机看，
但它不影响"背景可见"这条（页面底已让出）。
**未做**：P4c 壁纸上传入口（pi 定：算 P4 范围、不阻塞别的阶段，
做时按 WebUI 三条约束：先压缩再上传 / 失败必须给原因 / 上传后仍以服务端为权威）。
 2026-09-14 14:48:30 +08:00
JianFeeeee
e21151e98d fix(webui): 手势卡严只作用于周/日刻度（我第一版卡太宽，把月视图翻页也一起杀了） 
用户原话：「**周视图**需要卡严条件」。我第一版对**所有刻度**都卡，判据写成
"这页里有没有可横向滚动的容器" —— 而月视图的外层容器本身就带 `auto`，
于是连月视图的翻页手势也一起没了（实测：栅格与标题栏起手都不翻页）。

判据必须贴在**真正有横向滚动需求的那个刻度**上，而不是"这页里有没有横滚容器"。

## 实测（390×844，自有浏览器）

    月视图（标题栏起手横滑）：2026 年 9 月 → 2026 年 10 月   ✅ 可翻页
    周视图（栅格里起手横滑）：不翻页                        ✅ 让给横向滚动
    滚动容器遮罩：linear-gradient(rgba(0,0,0,0) 0px, rgb(0,…)  ✅ 已生效

⚠ 如实说明：最后一次探针里周视图的**标题取成了 null**（我的取样函数对
"2026 年 9 月 14–20 日"这种短横线格式没匹配上），null→null 不构成证据。
不过同一代码路径在上一轮探针里取到了真实标题（"9 月 14–20 日"）且未变化，
所以这条结论成立，但**证据强度弱于另外两条** —— 写在这里免得下次被当成硬结论。

## 附：部署差点又失败

`/tmp` 是 tmpfs，当时已 100% 满（9.8G），而部署脚本把构建产物写到硬编码的
`/tmp/agentmail-gateway-build-*` ⇒ `no space left on device`。
我差点把"旧构建上的测量结果"当成"改动无效"。清理我自己的产物后恢复。
**根治**：脚本应尊重 `TMPDIR`（未做，`/tmp` 现仍占 91%）。
 2026-09-14 14:36:49 +08:00
JianFeeeee
1717863c87 fix(webui): 手势与横向滚动分家 + 纵向滚动边缘淡出 
用户给了两条具体信息（这比我自己猜五轮都管用）：
「横向滚动条会与切换视图的手势冲突，我觉得周视图需要卡严条件，
  同时我说的其他硬截断是对应内容项上下滑动会直接被切断」。

## ① 手势卡严（周视图）

冲突是真的：周视图窄屏下必须横向滚（`overflow-auto` + `min-w-[36rem]`），
而我又给整页加了左右滑动翻页 ⇒ 同一次横滑既想滚又想翻，两边都不好用。

规则定死：**手势从可横向滚动的区域里起手，就归滚动条，完全不参与翻页判断**
（触点沿祖先链查找 `overflow-x: auto/scroll` 且真的能滚的容器）。
想翻页就从别处滑（例如上方标题栏）。

## ② 纵向滚动边缘淡出

滚动条本身是"一刀切"：卡片滚到边缘被硬生生截断 —— 这就是用户说的"直接被切断"。
给纵向滚动容器（`.overflow-y-auto`）加 12px 上下渐隐遮罩，切得有交代。

只作用在**纵向**容器：横向滚动有自己的滚动条，加纵向遮罩会跟它打架。

## 过程记录（值得记）

这两条改动**第一次没有生效**，因为部署失败了：`/tmp` 是 tmpfs 且已 100% 满，
而部署脚本把构建产物写到硬编码的 `/tmp/agentmail-gateway-build-*` ⇒
`no space left on device`。我差点把"旧构建上的测量结果"当成"改动无效"。
清理后（清掉我自己的探针脚本/截图/旧构建，约 950MB）部署成功。
⚠️ `/tmp` 现在仍占 91%（`gocache` 4.5G 等不全是我的），**下次部署可能还会撞上**；
脚本改成尊重 `TMPDIR` 才是根治（未做）。
 2026-09-14 14:35:43 +08:00
JianFeeeee
c9717daa13 fix(webui): 联系人项改为"每项一张玻璃卡"（补齐上一轮承诺） 
上一轮我说过"联系人/会话列表还是老结构，只有 MailList 改了"，这条把它补上：

- 联系人项：`rounded-lg border` → `.glass-card`（圆角 14px + 白色玻璃 + 细边框），
  与邮件行、顶部气泡、日历格子同一套语言；
- 会话分组行与邮件行上一轮已经是 `.glass-card`，所以三类列表现在一致了。

实测（自有浏览器，壁纸开，1400×900）：联系人页的卡片 `border-radius: 14px`、
底色 `rgba(255,255,255,0.78)`。

另外这一轮我又试了两个"滑动硬截断"的假设，**都不成立**：
- 窄屏日历（月/周/日三种刻度）：月与日刻度不溢出；周刻度溢出 208–278px 但
  **有横向滚动条**（`overflow-auto`），不是硬截断；
- 页面级横向溢出：390/320 下都是 0。

所以这条仍然需要用户指路。**而且教训很明确**：上一条"列表与正文之间的大空隙"，
我三轮猜都没猜中，用户一张截图我当场就定位了。截图比任何自测量法都快。
 2026-09-14 14:31:16 +08:00
JianFeeeee
2e42aacc07 fix(webui): 修「列表与正文之间那条大空隙」—— 包装层撑满而列表面板固定 320 
用户发截图指出：「外框列表和右边正文那么大一个空隙」。

## 根因（在代码里很难看出来）

我为了让「通信」有内部页签与悬浮加号，给中栏加了一层包装 div，它写着 `flex-1`；
而里面的列表面板是 `lg:w-[320px]` **固定宽度** ⇒ 包装层把剩余宽度全占了，
**空隙在包装层里、不在任何面板里** —— 于是既看不出是哪一层的错，也不像"布局 bug"，
看起来就像设计上多留了一条白。

## 改法

`​.app-shell .comm-pane { flex: 0 0 auto; width: 320px }` —— 宽屏下中栏贴住列表面板的宽度。
窄屏不动：那边外壳是**列**方向，`flex-1` 管的是高度，宽度由 `w-full` 决定。

## 实测（自有浏览器）

    宽屏 1600: 包装层 320 / 列表 320 / 详情 1180  →  包装层内空隙 0px，到详情 10px（设计间距）
    窄屏 390:  包装层 370 / 列表 370              →  包装层内空隙 0px

顺带说一句：这条与前面「日历没有圆角」「列表项变成一张大框」是**同一个包装层**引出的
三个症状（撑满宽度 / 内层直角戳出圆角 / 每项没有独立卡）。包装层是我为合并导航加的，
当时的验证只看了结构（页签在不在、点得到点不到），**没有量过宽度**，
所以它一连串地出问题。现在宽度已有判据（上面的数字就是判据）。
 2026-09-14 14:29:27 +08:00
JianFeeeee
a6b5e52f45 test(harmony): 判据按 pi 复核意见补强 —— 手写色登记表、玻璃叠用形状、按标题取小节、遮罩必须被用、废弃 API 清单从 SDK 生成 
pi 逐行读了 `cross-client-theme.test.mjs` 与 `Theme.ets` 后指出五处（第一处是真缺口），
外加一条建议。全部处理，并且**每一处都用变异验证过**。

## 一（真缺口）：枚举 11 个"必须是系统资源"的名字，挡不住第 12 个新写死的手写色

`static readonly brandSecondary: string = '#123456'` 这种新增**三条判据都碰不到**：
A（不在名单里）、B（六位、不是半透明）、裸色值那条（只管 `pages/`）。
原理与当初 14 处 Google 色逃出去是同一条 —— **枚举挡实例，类才挡漂移**，
只是这次枚举的单位是**名字**。补 `A2` 条：

- 枚举 `Theme.ets` 里所有 `static readonly X: string = '#……'`，未登记的 → 红；
- 名单里已不存在的名字 → 红（名单不能烂成化石）；
- `Theme.ets` 里的「手写色登记表」段必须逐个列出这些名字（理由不能只存在于记忆里）；
- 自检：把一个**新的**手写色塞进源码字符串，确认这条抓得到。
  `Theme.ets` 因此新增登记表（17 项，每项一行理由，按品牌 / 业务语义 / 档位胶囊分组）。

变异：Theme.ets 加 `brandSecondary` → 红。

## 二：C 的"玻璃只有一处"**说错了自己断言的东西**

`assert.equal(glassCalls.length, 1)` 断言的是"全仓共一处"，**不是**"没有嵌套"：
同页两个**并列**玻璃面（没问题）会让它红，真嵌套它没在判。P5 正是悬浮玻璃导航，
到时若把 1 改成 2 就等于不判。改成形状判据：

- 收集每个调用点所作用的**组件块**（按括号配对回溯；注意 ArkUI 修饰符是链式的，
  `X.blur(A).blur(B)` 前面是 `)` 不是 `}` —— 第一版只看一个字符，对这种写法**静默失效**，
  是判据自检抓出来的）；
- 判两种叠法：同一组件上叠多次（同一块）、以及套在另一层玻璃的子树里；
- 每一处玻璃都要在 `GLASS_REGISTRY` 里登记（附一句为什么），名单里的位置若已不存在 → 红。

变异：链式叠两层 → 红；通信页多开一处未登记玻璃 → 红；导航条块内嵌玻璃 → 红。

## 三：文档小节用 `indexOf('有意差异')` 会**拿错段落**

别的段落正文里出现这四个字，切片就从那里开始，后面所有断言都在**别的段落**上判。
改成**按标题**定位（正则匹配 `^#{2,4}…有意差异…$`），并加了表头列名断言
（WebUI / 鸿蒙 / 为什么）—— 拿错段落时表头不会是这个形状，于是它自己会红。

顺带修掉一个**我自己的**同类毛病：品牌色那行原来用"关键词 + 80 字符窗口"判，
窗口宽度在赌表格单元格字符数（该行两格之和 > 80）。改成**按行取**那一行再断言。
另外把偏移算术的切片换成**按行**切片（偏移差一个字符就会把最后一行拦腰截断，
现象是"品牌色那行只剩 57 字符"这种看着像文案、其实像切片的怪事）。

变异：文件前面插入含「有意差异」的段落 → 仍绿（按标题定位生效）；
再改坏真表里的品牌色行 → 红（确实读的是那一张表）。

## 四：`Theme.overlay` 只判了"存在"，没判"被用"

没使用点的令牌是自证。补断言：它必须在 `Theme.ets` **之外**有真实使用点
（实测 `SettingsPage.ets` / `MailDetailPage.ets` 两处自绘弹层在用），
并把 `overlayColor`/`overlayAlpha` 消失的理由写进 §7.12 —— 否则下一个人会当成漏改补回来。

## 五：材质档次是这次替换里唯一"判据绿但可能观感错"的地方

`COMPONENT_THICK` 的依据（对 THIN / BACKGROUND_* / ULTRA_THICK 的取舍）写进 §7.12，
并把"材质档次在导航条上的实际观感"列为**模拟器起来后第一个要看的项**（间距是数字，材质是判断）。

## 六（建议）：废弃 API 判据**类化** —— 清单从 SDK 生成

原来是手写"不得再用全局 `promptAction.showToast`"（只挡已踩过的那个）。
现在从 SDK 生成：顶层（花括号深度 0）被标 `@deprecated` 的 `declare function`
—— 实测 68 个名字（含 `animateTo` / `getContext` / `px2vp`），配一份**空**的 allow-list。
深度判定是必要的：`declare namespace fileIo { declare function open() }` 里的 `open`
是命名空间成员，算进来会造一堆假红。只算全局调用（排除 `x.name(`）。

变异：调 `px2vp(10)` → 红；`this.px2vp(10)`（成员调用）→ 绿（假阳性自检）。

## 验证

`hvigorw assembleHap` BUILD SUCCESSFUL；`npm test` 退出码 0
（11 个判据文件全绿 + vitest 258/258）。cross-client-theme 13 → 14 条，harmony-system-api 4 → 5 条。
 2026-09-14 14:26:45 +08:00
JianFeeeee
2a6ad93ec0 feat(harmony): P4 —— 外观（主题 + 壁纸）跟着账号走 
服务端 2026-09-13 起就是外观的权威（账号级 `/api/v1/me/appearance`），WebUI 接好了，
**鸿蒙这边此前完全没接**。这一期补上，并把"谁覆盖谁"的规则做成可判据的纯逻辑。

## 改了什么

- `api/AppearanceApi.ets`：`GET/PUT /me/appearance`、`POST /me/appearance/image`、
  `GET /me/appearance/image`（图片带认证取回本体：不用 `?token=`，也不让 Image 直连 http）。
- `api/ApiClient.ets`：新增 `getBytes()`（按 ARRAY_BUFFER 收）—— 复用 `request<T>` 会当场炸，
  因为它假定响应是 JSON（`JSON.parse`）。
- `model/Appearance.ts`（纯逻辑，判据直接执行）：归一化 / PUT 报文 / **合并决策** /
  模糊值→系统材质档次 / 主题→系统色彩模式 / 遮罩浓度 / 状态文案。
- `common/AppearanceStore.ets`：落地副作用 —— 主题交给**系统**（`setColorMode`，不自己维护
  深色色值）、壁纸取回 `PixelMap`、缓存**按账号**分键（`appearance.<accountId>`）。
- 入口两处：`MainPage`（进主界面就应用 —— 只在设置页生效的话"一进主界面就变回去"，
  WebUI 侧踩过）与 `SettingsPage` 新增「外观」段（三档主题 + 同步状态「已同步 / 仅本机」）。

## 为什么这么写（两条最贵的规则）

1. **服务端"没有记录"时以本地为准**（`saved === false`）：服务端这时回的是一份*默认值*，
   拿它覆盖本地 = 把用户已有的主题/壁纸抹掉（WebUI 原话：每个老用户升级后第一次登录
   都会发现被重置）。正确动作是把本地那份推上去。
2. **降级必须可见**（`local-only` → 显示「仅本机」）：否则用户以为换设备也能带走。

## 判据（新增 11 条，已接进 run-all；套件 10 → 11 个判据文件）

归一化（脏值/越界/小数/NaN 退回默认）；`image` 档无图 → 退回 `none`；PUT 报文蛇形字段名；
★服务端无记录 → 以本地为准且**一个字段都不能被默认值顶掉**；服务端有记录 → 以服务端为准但
**不擦掉**本地那张服务端还没有的图；离线状态可见且三种状态文案互不相同；
★模糊值→系统材质档次（与 SDK 的 `BlurStyle` 成员**逐一比对**）；
主题→色彩模式（数值与 SDK 的 `ConfigurationConstant.ColorMode` **逐一比对**）；
★路径必须**相对基地址**（WebUI 那条"整套同步从来没生效过而单测全绿"的坑）；
缓存键**带账号**；两处入口都真的应用。

变异验证（6 种，均判红）：默认值覆盖本地 / 不管"image 档但服务端无图" / 材质档次自造名字 /
路径多写 `/api/v1` / 缓存键不带账号 / 深浅色彩模式数值写反。

## 判据抓到的两个真 bug

- `snapshotFromResponse` 在字段缺失时给 `bgDim = 0`，而 WebUI 语义是退回 12 ——
  ArkTS 反序列化把缺失字段留成**类里写的默认值**，"字段不在"与"字段是 0"分不开。
  已把默认值对齐 WebUI 的 `clamp(..., dflt)` 语义（并让 `saved` 默认 false = 安全的那一侧）。
- 主题落地按"0=浅色、1=深色"写的 `setColorMode` —— **正好反了**
  （SDK：`COLOR_MODE_DARK = 0`、`COLOR_MODE_LIGHT = 1`），选深色会切成浅色。
  靠判据去 SDK 枚举文件读数比对发现；映射已搬进纯逻辑 `colorModeValue`，
  从"某处有个 setColorMode 调用"变成"可判据的行为"。

## 验证 / 未验

`hvigorw assembleHap` BUILD SUCCESSFUL；`npm test` 退出码 0（11 个判据文件全绿 + vitest 258/258）。
套件自检又抓到一次"判据写好没接进套件"（新文件第一版漏了 run-all），已修。

**未做**：壁纸**上传**入口（选图 → `POST /me/appearance/image`）—— 需要 picker，API 与命名已就位。
**未验**：壁纸在真机上的渲染 —— 需真机或模拟器。
 2026-09-14 14:19:26 +08:00
JianFeeeee
73f886aea5 feat(harmony): P2b+P3 —— 「收件箱」改成「通信」（内部三栏 + 徽标 + 悬浮加号），发件箱与授权栏落地 
用户：「收件发件授权改为一个导航项，通过内部导航区分，然后新建作为他们内部的一个悬浮的圆形加号」。
所以这一期不是"再加两个页面"，而是对齐信息架构。

## 鸿蒙侧

- 底部第一项 **收件箱 → 通信**（`CommPage`），内部三栏 收件箱 / 发件箱 / 授权；
  页签下划线式（不是浮动白胶囊 —— WebUI 侧用户原话「通信页面的二级页面与其他位置极其割裂」）。
- **徽标**：收件箱红（未读）、授权橙（**待决策**）、发件箱无；0 不显示，>99 写 `99+`。
  合并成一个导航项后，底部看不到"授权有 3 个在等我"，这个信息不能丢 —— 它比未读更急。
- **悬浮圆形加号**挂到通信页这一层（三个栏都要能新建）；`⚙` 也搬上来（否则切栏就够不到设置）。
- **收件箱不再混权限邮件**（`splitByPermission`），未读按筛后算 ——
  WebUI 实测过"一个会话 17 封权限邮件挤掉另外两个会话"。
- **发件箱**：`GET /me/mail/sent`，与收件箱同构（同一套折叠/行），行上主角是**收件人**；
  空态有说明（主句与 WebUI 逐字一致「暂无邮件」+ 一句"这里放什么"）。
- **授权栏**（P3 主体）：`GET /permission/pending`（不从收件箱筛）+ `POST /permission/decide`。
  拒绝**可填备注且备注真的送出**；请求**过期**时当场说清「审批不会让那次调用继续」。
- 顺手删掉死代码：收件箱里「写邮件」的 `bindSheet`（`composeVisible` 从未置 true，谁也打不开）。

## 判据（harmony-logic 19 → 28 条）

页签键/顺序从 WebUI 源码抽取比对（`uiStore.ts` 的 `CommTab` + `CommTabs.tsx` 的 `TABS`）；
页签状态机（键↔下标往返、脏键/越界/非整数 → 回收件箱）；徽标规则（数字来源、0 不显示、
99+ 上限、红/橙与 WebUI 类名对应）；分家语义（决策过的不再算待决策、空串与 null 同义）；
三栏空态互不相同且主句与 WebUI 一致；接线（三个 pane 真的渲染、加号是圆形且在通信页、
"先分家再折叠"、接口路径与决策体三字段、拒绝传备注、过期分支）。

判据抓到一个**真 bug**：`commTabFromIndex` 只判范围，`1.5` → `COMM_TABS[1.5]` = `undefined`
（表现"点哪都不亮"）。已加 `Number.isInteger`。

变异验证（六种）：授权徽标看未读 / 权限邮件不分出去 / 类型名拼错 / 决策过仍算待决策 /
收件箱不分家 / 发件箱空态去掉说明 —— 全部判红。

## 排序说明

**日历暂时没有入口**：P6 的内容（网格 + 事件读写 + 滑动翻页）还没做，
先放一个点进去空着的入口比暂时没有更糟 —— 有意排序，记在 §7.15 以免被当成漏做。

## 验证 / 未验

`hvigorw assembleHap` BUILD SUCCESSFUL；`npm test` 退出码 0（10 个判据文件全绿 + vitest 258/258）。
**未验**：页签/徽标/悬浮加号在真机上的观感与点击 —— 需设备或模拟器（模拟器要人在命令行启动）。
 2026-09-14 14:13:45 +08:00
JianFeeeee
c6aaf8c468 refactor(harmony): 23 处废弃 API 换成 UIContext 写法（全局 promptAction.showToast 自 API 18 废弃） 
SDK 里写得很清楚：`@ohos.promptAction.d.ts` 的全局 `showToast` 标着 `@deprecated since 18`，
替代品是 `UIContext.getPromptAction()`。仓库里有 23 处这种调用（6 个页面，历史遗留）——
这一轮既然在按"用系统方案"整理鸿蒙侧，就一次扫干净，并加判据挡住回潮。

- `promptAction.showToast(...)` → `this.getUIContext().getPromptAction().showToast(...)`（23 处）
- 清掉不再需要的 `promptAction` import（多个 → 只留 `router` 等）
- 新增判据：不得再用全局写法。防的不是这次，而是**新增页面照抄旧代码**这条回退路径 ——
  它编译照样通过、只在真机上行为不同。自检同时验"认得出旧写法"与"不误伤新写法"。
- 顺带把权限徽标那条"点它弹说明"的判据改成钉**非废弃**写法（原来是 `promptAction.showToast(`）。

变异验证：把 `SettingsPage` 的一处改回全局写法 → 判红并点出文件。

验证：`hvigorw assembleHap` BUILD SUCCESSFUL；`npm test` 退出码 0（harmony-logic 20 条）。
 2026-09-14 14:05:35 +08:00
JianFeeeee
36f3183bba feat(harmony): 系统方案第一批 —— 表面/文字/圆角交给系统、删手写玻璃、每项一张卡；跨端判据改"意图相同" 
jianf：「鸿蒙也同步，但是鸿蒙要求用系统方案」。按 pi 对齐的形状（A/B/C + 品牌色防线）落地。

## 鸿蒙侧改了什么

- `Theme.ets` 的表面/文字/分隔/遮罩/圆角**来源换成系统**：
  `pageBg→sys.color.ohos_id_color_background`、`surface→…_list_card_bg`、
  `surfaceMuted→…_sub_background`、`border→…_list_separator`、三级文字 `→…_text_primary/secondary/tertiary`、
  `overlay→…_mask_regular`、`radiusCard/Control→sys.float.ohos_id_corner_radius_card/button`。
  于是这些维度自动跟随深色模式与无障碍设置 —— 这正是"手抄 WebUI 色值"做不到的事。
- **删掉手写玻璃** `#B8FFFFFF`/`#B80F172A`：那两个值等于"我们替系统猜了深色该怎么做"。
  换成一个**档次**声明 `navMaterial: BlurStyle = BlurStyle.COMPONENT_THICK` + 导航条上的
  `.backgroundBlurStyle(...)`；深浅两套颜色与模糊半径由系统按主题给。
  遮罩的两段式（色 + 透明度）同样删掉：拆两段本就是为了"随主题换向"，而这件事系统已经做了。
- **每项一张卡/气泡**：收件箱行、会话组头、联系人列表行改成卡片（圆角 + 卡片底色 + 行间距），
  联系人列表那条贯通分隔线删除。
- 仍然自己写的只有两类：**品牌色**（`accent = #2563EB`，跨客户端身份）与**业务语义色**
  （权限三档、预算三档 —— 系统只有 warning/alert 两个情绪色，凑不出三档，硬套会丢语义）。

## 判据：从"取值相同"改"意图相同"（两侧一起改）

- 品牌蓝**唯一保留取值钉**，并新增防线：不得退化成 `$r('sys.color.*')`
  （系统强调色随主题/厂商皮肤变，"两个客户端是同一个产品"就靠不住了）。
- 圆角/材质/遮罩：改成"WebUI 自声明令牌 + 鸿蒙来自系统 + 差异被记录"（§7.12 有意差异表）。
- 新增 A（系统拥有的维度唯一来源是 `$r('sys.*')`，且不得退回 string/number）、
  B（旧机制不得回来：`navBg*`、8 位半透明色、`rgb(`/`rgba(`、写死的 14/8）、
  C（玻璃位置必须调 `backgroundBlurStyle` 且**只许一层**）。
- pi 指出的洞已补：裸色值判据原来只扫 `#RRGGBB(AA)`，抓不到 `rgba(`/`0xRRGGBBAA` ——
  而这几种恰是"改用系统材质"时最容易混进来的形态。现在四种一起扫，且**先剥注释**
  （注释里正当地引用旧写法不该被judged红）。
- pi 的 §5 建议也已落地：新增"版本库不得跟踪缓存/构建产物"判据（`.tmp/` 那次 554 个文件的事故判据化），
  并放行 `server/internal/static/static/placeholder.html`（go:embed 落点的有意占位，删了 Go 侧编不过）。

## 变异验证（能红，且红在对的地方）

| 变异 | 结果 |
|---|---|
| 品牌蓝 → 系统强调色 | 红 3 条 |
| 手写玻璃 `navBgLight` 回来 | 红 2 条 |
| 导航改用写死半透明色、不调 `backgroundBlurStyle` | 红 2 条 |
| 卡片上再开一层模糊 | 红 1 条（"玻璃应只出现在一处，实际 2 处"） |

## 验证 / 未验

`hvigorw assembleHap` BUILD SUCCESSFUL；`npm test` 退出码 0
（10 个判据文件全绿：跨端 13 条、系统资源名 4 条、harmony-logic 19 条… + vitest 258/258）。
**未验**：观感（卡片间距、系统材质在导航条上的实际效果、深色模式）—— 需真机/模拟器；
模拟器要人在命令行跑一次 `harmony-emu start`。`sys.*` 名字全部对着 SDK 名表核过，且判据持续盯着。
 2026-09-14 14:04:04 +08:00
JianFeeeee
4d226be056 test(harmony): 「用系统方案」的地基 —— 系统资源名与 BlurStyle 取值离线可校验（判据先于替换） 
jianf 追加要求「鸿蒙要求用系统方案」（§二·五）。难点是**没有设备**：
`$r('sys.color.写错了')` 编译期不报、只有真机运行到那一行才炸 —— 这块会变成谁都验不了的区域。

SDK 里其实带着答案：`sdk/default/openharmony/toolchains/id_defined.json` 列了全部系统资源名
及其类型（本机 API 26：7826 条，color 1059 条）；BlurStyle 取值在 `component/common.d.ts` 的
`declare enum BlurStyle` 里。两边都能离线查，所以"名字写对没有"可以变成构建期判据。

新增 `test/harmony-system-api.test.mjs`（4 条，已接进 run-all）：

1. SDK 名表/组件声明找不到时**判红并给出替代做法**（会静默跳过的判据等于没有这条判据 ——
   本仓库已栽过四次同类问题）；
2. 源码里每个 `$r('sys.<type>.<name>')` 必须存在且**类型相符**；
3. 每个 `BlurStyle.<MEMBER>` 必须在 SDK enum 里；
4. 替换计划要用的那批系统色**先核过再写代码**，并且钉住一条边界：名表里没有
   `brand`/`confirm`/`success` —— 权限三档、预算三档这些**业务语义色没有系统对应物**，
   继续用自定义令牌，不许"为了系统化"把 plan 档画成 warning 色（那是丢语义换形式）。

变异验证：拼错色名 `ohos_id_color_list_cad_bg` → 报「查无此名」并指出文件；
写错 `BlurStyle.COMPONENT_不存在` → 报出可用取值。顺带修掉解析精度问题：
早先的宽松正则把文档里的 `T`、`R` 也当成了枚举成员，现在精确到 `,`/`=` 分隔符。

验证：`npm test` 退出码 0（10 个判据文件全绿 + vitest 258/258）。
 2026-09-14 13:56:43 +08:00
JianFeeeee
5ce711fbcd test(suite): 自检 3（判据不得埋在 process.exit 之后）+ TMPDIR 固化 + API 同名不同义表 
## 自检 3（pi 提议）

自检 1/2 管"文件没接线"，管不到"检查写在 `process.exit()` 之后"—— 而那正是实际发生的
第 4 例（4 条玻璃判据被并发写入落到文件末尾）。成因是**结构性**的（并发写入总是往文件末尾
追加），所以它一定会再发生，而它下一次仍然不报错。静态扫一遍即可：`process.exit(` 之后
若再出现 `check(`，直接判红并指出文件。变异验证：往 `theme.test.mjs` 尾部追加一条 check → 判红。

## TMPDIR 固化（pi 建议，采纳）

"记得加 TMPDIR"这种约定活不过两次踩坑（hvigor、fpm 各一次）。所以不再靠口径：
- `npm run build:linux` 自带 `mkdir -p .tmp && TMPDIR=${TMPDIR:-$PWD/.tmp}`；
- `BUILD.md` 的 deb 一节写明这条前置与原因（`/tmp` 是 tmpfs、占内存、常年近满）。

## `docs/API.md`：`total` 不是总封数 + 同名不同义表

`GET /me/mail/inbox` 的 `total` 是**未读总数**（`repo.CountUnread`），不是本页/全部邮件数 ——
鸿蒙端曾因此写出「共 7 封」和「未读 7」两行自相矛盾的字。在人类接口开头加了醒目提示，
并新增一张表：`total`（未读数）/ `status`（邮件=unread|read，会话=active|archived）/
`status` 与 `is_read` 同义不同名。

## 验证

`npm test` 退出码 0：9 个判据文件全绿 + vitest 258/258（安装包已按判据要求重打，
AppImage 与 deb 均为最新）。
 2026-09-14 13:53:34 +08:00
JianFeeeee
b3f404838b feat(harmony): P2a 收尾 —— 撤掉平级「会话」tab + 权限"强制力"上界面，判据 14→19 
## 撤 tab（按 pi 的顺序：先补视图与折叠，再撤入口）

底部只剩 **收件箱 / 联系人**。「会话」不是第三个地方，而是同一批数据的两种看法：
收件箱那栏按会话折叠（组头就是会话），联系人那栏的卡片视图是会话的进度视角。
依据是"信息没丢"，并且把它做成了判据：**卡片字段集与 WebUI `WorkCard` 完全相等**
（多一个少一个都红）—— 其中 `status`(active/archived) 与 `from_agent` 参考实现也不显示；
哪天 WebUI 补上，这条会红，提醒跟着补，而不是悄悄少一块。

## 权限"强制力"上界面（WebUI 有、鸿蒙原先没有）

只显示档位会让人以为 plan 档真的管住了对方。WebUI 把说明放在 `title`（悬停提示），
**手指没有悬停** —— 所以鸿蒙拆两步：标记形状当场可辨（● 平台强制 / ◉ 覆盖不完整 /
○ 仅提示），点徽标用 toast 说完整那句话。三条纪律落进判据：

1. 档位/强制力标签与 WebUI 的 `MODE_LABEL` / `ENFORCEMENT_LABEL` **逐字一致**；
2. **说明文案从 WebUI 源码抽出字符串逐字比对**（3 档 × 3 强制力全覆盖）——
   两个客户端对同一个任务不能给两种保证；
3. 认不出的强制力归一到 `advisory`（保守方向），空/未知必须说"仅提示"。

收件箱每封邮件里没有 `permission_enforcement`（会话级字段），故那里只写中文档位 ——
凭空画一个强制力标记等于编一个"平台做到了什么"。

## 判据自己不可信的两个坑（变异测试逼出来的，各修一次）

- **断言一律读剥掉注释的源码**：把 `showToast` 注释掉，正则照样匹配 ——
  注释里有某个调用证明不了它存在。
- **"在回调里"不能靠正则窗口**：`onClick` 体掏空、或把 toast 挪到相邻的 `onHover`，
  窗口式正则都会放过。改成**括号配对**取那个 `onClick` 的 `{...}` 体，只在里面找。
  两次变异现在都判红。

`harmony-logic.test.mjs` 19 条（原 14）；变异验证：改文案 / 改档位标签 / 页签改回「会话」/
注释掉 toast / toast 挪出 onClick / toast 写死文案 → 各判红。

## 文档

§7.9 记本轮；§7.10 记 jianf 追加的「鸿蒙要求用系统方案」：同意该理解，并补上**可离线校验**的
做法 —— SDK 自带系统资源名表 `sdk/default/openharmony/toolchains/id_defined.json`（7826 条），
其中正好有 `ohos_id_color_list_card_bg`（每项一张卡的底色）、`_list_separator`、
`_text_primary/secondary/tertiary`、`_emphasize`、`_warning`、`_alert`、`_mask_*`、
`ohos_id_blur_style_component_*_color`。**没有设备**，`$r('sys.*')` 写错在运行前发现不了，
所以先立一条判据：源码里的每个 `sys.*` 名字都必须在该表里查得到，再逐处替换。
`cross-client-theme` 的三个取值钉改"意图相同"**先与 pi 对齐、两侧一起改**（他已明确要求）。

## 验证

`hvigorw assembleHap` BUILD SUCCESSFUL；`npm test` 9 个判据文件（background 42 /
cross-client 8 / harmony-logic 19 / nav-merge 8 / build-stamp 4 / packaging 3 …）+ vitest 258。
视觉与点击仍未验（无设备，模拟器需人在命令行启动）。
 2026-09-14 13:51:35 +08:00
JianFeeeee
bb855b1518 fix(webui): 日历补上圆角 —— 外层面板圆了、里面的格子还是直角 
用户：「日历页面怎么没有圆角」。

原因与列表那次同源：**外层面板一直是圆的**（`.app-shell > *` 给了 14px），
但里面的日格/列写的是 `border-b border-r`（直角 + 细边框），而我早前为了修滚动
去掉了面板的 `overflow: hidden` ⇒ 里面的直角就戳在圆角外面，看起来"整页没有圆角"。

改法：日格、周视图列、以及日历的两个大面板都改用 `.glass-card`
（圆角 14px + 白色玻璃 + 细边框），与列表项、顶部气泡同一套语言。
顺手去掉日格上的 `overflow-hidden`（它会把事件条裁掉，而"裁掉"正是这几轮的老毛病）。

实测（自有浏览器，壁纸开）：日历里 **42 个 `.glass-card`**（月视图 42 格 + 面板），
格子 `border-radius: 14px`、底色 `rgba(255,255,255,0.78)`。

（这条同样是"外层圆角 + 内层直角"这一类问题 —— 我已经在列表、顶部、日历上
各修了一次。要找根因的话：**面板圆角不能靠 `overflow: hidden` 裁**（它会杀滚动），
所以每一层自己都要圆角。这是这套"浮动面板"设计的固有代价，写在这里备查。）
 2026-09-14 13:47:58 +08:00
JianFeeeee
0c4100802f fix(webui): 顶部改气泡式 —— 列表头与详情头从"通栏 + 下边框"改成浮动玻璃卡 
用户：「同时顶部为什么不是气泡式的而是栏目式的」。

原因很直接：这两处写的是**通栏**（`px-4 py-3.5 border-b border-gray-200`）——
铺满面板宽度、靠一条下边框划分，就是"栏目/工具条"的语言；而列表项刚改成
"每项一张卡"之后，顶部还留着通栏，风格自然对不上。

- 列表顶部（标题 + 账号切换 + 计数）：`glass-card mx-2.5 mt-2.5 px-3.5 py-2.5`
- 详情顶部（发件人/主题/时间那条）：同样改成 `glass-card` 气泡

实测（自有浏览器，壁纸开）：圆角 **14px**、底色 `rgba(255,255,255,0.78)`、
在 320px 宽的面板里 left=90/top=65 ⇒ **四周有 10px 内缩**（真的浮起来，不是通栏）。

## 一个我没动的地方（需要你确认）

「通信」的内部页签（收件箱 / 发件箱 / 授权）现在是**下划线式**，不是气泡式。
我特意没动它：更早一轮你给过相反的意见 —— 那时它是"白色胶囊 + 阴影"浮在面板上，
你说「二级页面与其他位置极其割裂」，我才改成下划线。

如果你现在要的是**气泡式的分段控件**（半透明玻璃胶囊 —— 比当年那版少了阴影、
且底色走玻璃令牌，不会再有"白底压白底"的割裂感），说一声我就换；
或者你指的就是刚改的这两处，那这条就算完成。
 2026-09-14 13:44:49 +08:00
JianFeeeee
6be5a543af test(suite): 判据总入口 run-all —— 全部跑完再算退出码，并接上两条从未跑过的判据 
## 为什么

`npm test` 是 `&&` 链：**前面红一条，后面全部不跑**。于是"只红一条"看起来像
"只有一个问题"，实际后面那些判据连跑都没跑（`packaging` 那条能发现"界面改了没重打包"的
判据，长期因此隐身）。而且这套规矩下"全绿"可信、"红"不可信。

改成 `test/run-all.mjs`（pi 建议）：每条都跑，红的收集起来最后一起报、一起退出。

- **自检 1**：清单里的文件必须存在（名字写错 = 一条判据静默消失）；
- **自检 2**：`test/` 下每个 `*.test.mjs` 都必须接进清单 —— **新增判据忘了接线直接红**。
  这条自检当场抓出 `nav-merge.test.mjs`、`build-stamp.test.mjs` 两个"写好了没接线"的文件
  （8 + 4 条判据此前从未跑过，与 `cross-client-theme` 是同一族问题）。
- 变异验证：强制 `theme.test.mjs` 判红 → 后面 5 条判据照跑，汇总如实报"红 1/9"、退出码 1。

`package.json`：`"test": "node test/run-all.mjs && vitest run"`。

## 接线后暴露的两条陈旧判据（代码没错、判据钉的是旧写法），按"钉行为不钉字面"修

1. `setViewMode(target || commTab` —— 代码后来等价改写成
   `target ?? (isComm ? commTab : modes[0])`。改成钉行为"isComm 时落到 commTab"，
   并额外要求桌面分支带 `target`（否则日历/联系人点不动）。
2. `MailView.tsx` 里 grep `glass-control` —— 授权多选胶囊已抽成共用组件 `ComposerChip`，
   样式其实是对的（neutral 未选中态就是 `glass-control`）。改成钉
   "MailView 用 ComposerChip" + "ComposerChip 用控件档"（文件会搬、组件不会）。
   两条都做了变异验证（去掉玻璃档 / 去掉 commTab 回退 → 各判红 1 条）。

## 生成产物再补一条判据（pi 提议）

用 postcss 真解析 `background-takeover.generated.css`：断言每条规则的选择器形状恰好是
`html[data-bg='on'] .bg-xxx`，且规则条数与源码扫到的清单条数一致。
只验"能解析"不够 —— 实测 postcss 对当年那份坏产物照样解析出 1 条规则（选择器前粘了
注释尾巴），所以卡形状与条数。变异：把坏头注释塞回生成产物 → 该条判红。

## BUILD.md：deb 结论撤回（不是 fpm）

`TMPDIR=/var/tmp/ebtmp` 在本沙箱建不出来；把 TMPDIR 指到工作区大盘后 deb 正常产出
（`release/agentmail-web_0.1.0_amd64.deb`，约 100MB）。日志关键行是 **`Errno::ENOSPC`**：
fpm 要把 291MB 的 `linux-unpacked` 整份复制进 TMPDIR，而本机 `/tmp` 是 9.8G tmpfs、
被 `/tmp/gocache`（4.5G）等占到 99%。所以「本机打不出 deb」是环境症状、不是工具链缺陷，
deb 不必从 `build.linux.target` 摘掉。排查命令写进 BUILD.md。

## 验证

`npm test` 退出码 0：9 个判据文件全绿（markdown-xss、narrow-layout、nav-merge 8、
theme、background 42、cross-client 8、harmony-logic 14、build-stamp 4、packaging 3）
+ vitest 258/258。鸿蒙侧 `hvigorw assembleHap` 仍 BUILD SUCCESSFUL。
 2026-09-14 13:44:00 +08:00
JianFeeeee
f6feb7c0df test(webui): 「滑动硬截断」诊断脚本（自带浏览器，不依赖共享实例） 
用户：「webui 大片界面存在滑动硬截断」。

## 现状：这一轮我**没能复现**

量法是"内容溢出但没有可滚动祖先"⇒ 候选 0 个；换成用户视角四问
（有没有可滚动容器 / 能不能滚到底 / 末尾有没有被切 / 页面自己溢不溢出）后：

    390×700  通信 ✅ 日历 ✅ 联系人 ✅ 我的 ✅
    1400×700 通信 ✅ 日历 ✅ 联系人 ✅ 我的 ✅
    （造了 12 个会话、正文都很长；验完已归档）

即按这四种量法都测不到硬截断。**长正文详情页**那一块我的探针超时没跑完 ⇒
**未判定**，不能算"没问题"。

## 这次的交付物

`client/electron/test/manual/scroll-cut-verify.mjs`：把上面这套量法固化下来，
并且**自带浏览器**（不连共享 9222）—— 共享实例被历次被中断的运行留下僵尸上下文后，
`connectOverCDP` 会一直超时（我这个会话里已经遇到三次），诊断脚本必须在
"共享实例状态未知"时也能跑。

## 我需要的（否则只能继续猜）

请指一下**具体页面 + 具体手势/位置**：哪一屏、滚轮还是触摸拖动、硬截断出现在
列表末尾还是详情正文？也可以直接看截图。我上一轮"窄屏显示不全"也是同样情况 ——
我量不出来、但你说有，那多半是我量的维度不对。
 2026-09-14 13:43:11 +08:00
JianFeeeee
e0c68d8bb2 test(cross-client): 预算条三个档位的令牌也和 WebUI 对齐 + 记录模拟器权限门 
## 判据

P2a 新加的 6 个预算条令牌（`chipNeutral*` / `chipSpent*` / `chipWarn*`）此前只有鸿蒙侧
自己在用，没有任何判据钉住它们与 WebUI `BudgetChip` 的 gray-100/gray-500、
red-100/red-700、orange-100/orange-700 是**同一批值** —— 于是"鸿蒙那边自己挑了个接近的红"
没人会发现。补进 `cross-client-theme.test.mjs`（8 → 8 条，第 7 条扩了 6 个断言），
并加了反向对照（差一个色阶必须判红，实测判红）。

注意 `--c-gray-100` 等在 `.dark` 段有第二处定义，`cssVar()` 取第一处（`:root` 浅色一套），
与 `Theme.ets` 的浅色令牌对应。

## 文档

`docs/HARMONY-ALIGN-PLAN.md` §7.6：把"鸿蒙视觉/点击未验"查到根上 —— DevEco CLI 说明本机
**有**可启动的模拟器（起来后 `devecocli ui layout/click/screenshot` 能做点击级验证），
但 `harmony-emu start` 要写 `/run`、`/root/.Huawei`（工作区之外），按规矩升级重试一次后
被拒：**「权限询问无法送达：该任务链上没有人类用户」**。
即：鸿蒙的点击级验证不是"还没做"，是"当前做不到"——需要人在命令行跑一次
`harmony-emu start`。此前所有阶段只能按"逻辑有可执行判据 + 接线有判据 + 观感未验"验收。
 2026-09-14 13:38:35 +08:00
JianFeeeee
83cb7528fb fix(webui): 玻璃是白色材料 —— 深色模式只降 alpha，不换基材 
用户纠正我：「什么叫深色模式也是玻璃？深色模式不应该是浅色玻璃吗？」

**他是对的，而且这是个概念错误，不是一个数值错误。**
我原先把深色模式下的玻璃写成 `rgb(15 23 42 / .72)`（一整层深色）—— 那不是玻璃，
是把面板压黑。磨砂玻璃是**白色材料**；深色模式下要做的是**降低这层白的透明度**
让深背景透出来，而不是换基材颜色。

## 更深一层的真因（这才是"半深不浅"的源头）

`.dark` 里写着 `--c-white: 24 27 33`（近黑），而**所有**玻璃面都写成
`rgb(var(--c-white) / α)` ⇒ 深色模式下**整个玻璃层系**（正文面、嵌套卡、控件、
卡片）一起变深，而 Tailwind 的浅色工具类照旧 ⇒ 界面半深不浅。
用户先看到的是"导航栏为什么还是黑色"，根子在这里。

## 改法：让这个错误写不出来

- 新增 `--glass-base: 255 255 255`（**两个主题都一样**），玻璃面的基材只有这一个来源；
- 8 处玻璃面从 `rgb(var(--c-white) / α)` 改为 `rgb(var(--glass-base) / α)`；
- `.dark` 里的玻璃相关覆盖全部清空并写明：**深色主题必须与组件侧的 `dark:` 变体
  一起做**（现在一个都没有），单独生效只会"面变深、字还是深色"，读不了；
- 删掉提前写下的 `.dark .glass-card`（它按"深色主题已存在"写，实际只会让卡片
  在浅色页面上几乎消失）。

## 判据（background.test.mjs，34 条全绿）

三条新的，都是行为级而非数值级：
- 玻璃基材只有一处定义且必须是白色；
- 没有玻璃面再用 `--c-white`（它与深色主题冲突）；
- 深色主题里不许出现非白色的 `--glass-base`；并带扰动自检。

## 实测（自己的无头 Chromium，壁纸开，1600×1000）

    系统浅色: 卡片 rgba(255,255,255,0.78)  导航 rgba(255,255,255,0.72)
    系统深色: 卡片 rgba(255,255,255,0.78)  导航 rgba(255,255,255,0.72)   ← 不再变深

即"白色玻璃、只有透明度随主题变"确实生效；深色模式也不再出现半深不浅的观感。
 2026-09-14 13:36:54 +08:00
JianFeeeee
3729afd96f feat(harmony): P2a —— 收件箱按会话折叠 + 联系人页卡片视图（判据直接跑同一份逻辑） 
按 pi 的结论落地 P2a 的前一半：**先补视图与折叠，再删平级「会话」tab**（tab 本轮保留）。

## 判据怎么"点用户真正会点的那一层"

鸿蒙侧没有设备（`hdc list targets` 为空、模拟器在本机沙箱下起不来），"点一下"暂时
无法自动验。应对不是编个能过的新判据，而是把会点的那一层的内核抽成纯逻辑：
`entry/src/main/ets/model/MailGrouping.ts`（无 UI 依赖），判据用 node 的
`--experimental-strip-types` **执行同一份代码**（`test/harmony-logic.test.mjs`，14 条），
断言的是行为而不是"源码里出现过某个字符串"：

- 折叠后组头是不是**最新一封**、组内是否时间倒序、组间排序、同一时刻用 `mail_id` 倒序兜底；
- 时间解析失败**不能让顺序依赖入参**（WebUI 侧踩过的 NaN 比较坑）；
- 多账号合并下同名 `session_id` 不能被错并成一组；`session_id` 缺失时各自成组；
- 预算档位与 WebUI `BudgetChip` 完全一致（剩 0 用尽 / ≤1 将尽 / 上限 0 不显示）；
- 视图切换与卡片上"最新一封是人还是 Agent"的判据。

页面那一层另用源码判据钉"确实调了这些函数"，两层合起来覆盖「逻辑对」+「页面接上了」。
**变异验证 4 处全部判红**：去掉组内排序（2 条红）、预算阈值 `<=1` 改 `<1`、
分组键去掉账号前缀、页面不再区分单封组。

## 收件箱折叠

- 组头取组内最新一封的别名与主题，带未读数徽标与「N 封」，点它展开/收起；
- **单封不成组、平铺**（与 WebUI `isFlatGroup` 同结论：给孤立一封信套组头只是多一次点击）；
- 多账号是鸿蒙特有：分组键带账号前缀；`session_id` 缺失按 `mail:<id>` 各自成组。

## 顺带修掉一个"看起来是总数、其实是未读数"的显示

`/me/mail/inbox` 的 `total` 是 **`CountUnread`（未读总数）**，不是总封数
（`server/internal/handler/me.go`）。鸿蒙底部原写「共 N 封」⇒ 同一屏出现
「共 7 封」和「未读 7」两行自相矛盾的字。改成：未读数用服务端 `total`（权威，
原来数这一页会少报）；「共 N 封」→「已加载 N 封」；**这一页取满时如实提示
「已加载 50 封（本页上限 50，可能还有更多）」** —— 客户端没有可信总封数，
就不能把 50 封说成全部（pi 提醒的"别让只取 50 封伪装成只有这么多会话"）。
WebUI 侧不读这个字段，故只影响鸿蒙。

## 联系人页补卡片视图（撤 tab 的前置）

- 右上角切列表/卡片，标题「联系人」/「工作列表」（与 WebUI 同词），切换规则在
  `nextContactView()`；
- 卡片对应 WebUI 的 `WorkCard`：Agent 名 + 工作目录 + 未读徽标、会话别名、
  **主题当主角**、最新摘要 + 人/Agent 标记、`N 封 · 时间`、权限档位徽标、
  **往返预算条**（同一档位判据）。
- 平级「会话」tab 暂留：撤 tab 按 pi 的顺序排在后面单独一步（撤早了预算/status/from_agent 没处看）。

## 验证

- `hvigorw assembleHap` **BUILD SUCCESSFUL**（`.ts` 纯逻辑模块被 `.ets` 引用，实测可行）。
- `npm test` **退出码 0**：窄屏布局全通过、主题 30、背景 34、cross-client 8、
  harmony-logic 14、packaging 3、vitest 258/258；新判据已接进 `npm test`。
- **视觉与点击仍未验**（无设备）：展开手感、卡片间距、组头命中区没有任何自动判据
  能代替人眼 —— 交付按"结构/逻辑已验证、观感未验"写，未写成已完成。
 2026-09-14 13:36:05 +08:00
JianFeeeee
51522dd8c2 fix(webui): 导航令牌迁移收尾 + 生成 CSS 的头注释提前闭合（会丢规则）+ 两条过期判据重写 + 判据进 npm test 
## 改法

- **`Sidebar.tsx` 底部两个按钮还是旧的深色导航假设**（`text-chrome-400
  hover:text-white hover:bg-chrome-800`、外层 `border-chrome-700`）：导航改成白玻璃
  （`--nav-bg: 255 255 255 / 0.72`）之后，`chrome-400` 落在白底上约 2.6:1（图标要
  3:1），hover 还会在白导航上闪出一块近黑。账号头像那个按钮当时换成了 `.nav-item`，
  这两个漏了 —— 就是"导航令牌迁移做了一半"。已换成 `.nav-item` + `border-gray-200`。
  没加"Sidebar 里不许有 chrome-*"的判据：另有一处 `bg-chrome-600 text-chrome-100`
  是实心小色块（正常用法），一刀切会误红。

- **`background-takeover.generated.css` 的头注释提前闭合**：生成器在注释里写了
  「src」加「/」加两颗星加「/」加「.tsx」，其中那对「星号 + 斜杠」把 CSS 注释就地
  结束 —— 尾巴变成 CSS 正文，并与第一条规则的选择器连在一起成为非法选择器 ⇒
  **`.bg-amber-100` 那条接管规则被浏览器整条丢掉**（壁纸模式下不再变半透明）。
  构建只给一条 `[WARNING] Unexpected "14" [css-syntax-error]`，不报错、不影响构建，
  正是这套判据存在的理由。改在生成器（注释里只描述、不写 glob 字面量）并重新生成：
  压缩输出现在以 `html[data-bg=on] .bg-amber-100{` 起头、14 条规则全在、无告警。
  另加两条判据（"头注释没提前闭合" + 自检）。

- **`background.test.mjs` 第 18 组三条重写**：原先断言「浅色/深色两套 `--nav-bg` 都
  定义」与「壁纸模式下 `.nav-rail` 里有 `backdrop-filter`」，两条编码的都是**已被
  有意撤掉的设计**（`faacd3c` 撤深色导航、`9aa702b` 撤导航自叠模糊），于是 `npm test`
  在 HEAD 上恒红。判据红成常态就不再是判据 —— 该改的是判据本身，而不是把缺陷写回代码。
  改成方向相反的两条：`.dark` 不许单独给导航换色 / 模糊只由壁纸层负责。

- **`cross-client-theme.test.mjs` 从来不在 `npm test` 链里**（vitest 只收
  `test/components` 与 `test/stores`）—— 那条"防漂移判据"从没在默认套件里跑过。
  已加进 `npm test`。

## 验证

- 变异测试：往 `.dark { }` 塞一行 `--nav-bg: 15 23 42 / 0.72;` → 红；往
  `html[data-bg='on'] .nav-rail` 塞 `backdrop-filter: blur(18px);` → 红；撤回 → 绿。
- `npm test` 退出码 0：窄屏布局全通过、主题 30、背景 34、cross-client 8、packaging 3、
  vitest 258/258；`npm run typecheck` 通过。
- packaging 第 3 条此前是红的，但**不是判据过期**：安装包真的落后于 dist，而 `npm test`
  的 `&&` 链一直在 background 那条就中断，`packaging` 从没跑到过。已 `npm run build`
  + `npx electron-builder --linux -c.electronDownload.isVerifyChecksum=false` 重打包。
  ⚠️ deb 目标在本机打不出来（fpm 的 portable ruby 在 `Dir.chdir` 处退出），
  AppImage 与 `linux-unpacked` 正常。
 2026-09-14 13:29:57 +08:00
JianFeeeee
b041ea51e4 fix(harmony): 令牌收尾 —— 裸色值清零、遮罩拆两段式、权限档位配色对齐 WebUI 
接手核对时发现：「不许写死颜色」那条判据**只挡得住枚举的 8 个旧值** —— 判据全绿的
同期，pages/ 里还留着 14 处另一套写死的色（Google/Material：#E8F0FE、#E8F5E9、
#FFF3E0、#D93025、#777777×2、#555555、#444444、#cccccc、#aaaaaa、
遮罩 #80000000×2、透明 #00000000×2）。枚举挡不住漂移，只有"类"能挡。

## 改法

- 14 处全部换成令牌。新增 accentStrong / warnBg / warnFg（取值对齐 WebUI `:root`
  的 blue-700 / amber-50 / amber-700）与 `Theme.permBg/permFg` —— 权限档位徽标与
  WebUI 的 `PermissionChip.tsx` **同一映射**（plan=蓝 / workspace=绿 / full=琥珀）；
  原先写成 `full ? 绿 : 橙`（Material 色），与 WebUI **反着来**。
- 遮罩拆成 `overlayColor` + `overlayAlpha`（照 WebUI 的 `--bg-scrim` + `--bg-dim`
  两段式）：遮罩色要能随主题换向，色与透明度焊死成一个 `#AARRGGBB` 等于把枚举写回
  代码。ArkUI 只认单值，故由 `Theme.overlay()` 组装。
- 判据从"枚举旧值"改成"按类挡"：pages/ 下**一个裸色值都不许有**（含 8 位
  `#AARRGGBB`），页面清单从硬编码 7 个文件名改成**扫目录** —— 旧写法下，
  接下来要加的发件箱/授权/日历会自动逃出判据。另加一条判据：权限档位配色与
  WebUI `:root` 变量逐一比对，防"看起来差不多"。

## 验证

- 变异测试：往 `InboxPage.ets` 塞一个 `#E8F0FE` → 判据红；撤回 → 绿。
- cross-client 判据 6 → 8 条全绿；`hvigorw assembleHap` BUILD SUCCESSFUL。
- **视觉未验**（模拟器在本机文件沙箱下起不来，见 `docs/HARMONY-ALIGN-PLAN.md` 5.4），
  未写成"已完成"。
 2026-09-14 13:29:50 +08:00
JianFeeeee
4d6e944220 feat(webui): 打开即已读 + 回复即已读 
用户：「现在邮件需要完全手动标记是否已读而不支持点进去自动已读或者回复自动已读」。

## 改法

- **打开即已读**：MailView 里加一个 effect —— 当前邮件是 unread 且**真正可见**时
  调 `markRead`。两个刻意的细节：
  1. 窄屏下 MailView 可能已经渲染但被列表覆盖层盖住（NarrowStack）⇒ 必须等到
     `narrowPane === 'detail'` 才标，否则"滑过去但没看"的邮件也会被标已读；
  2. 只对 `unread` 发请求（已读的再标一次是白跑，还会让接口日志一直响）。
- **回复即已读**：ReplyBar 发送**成功之后**才标（发送失败不该把"我处理过了"记下来）。
- 手动标记按钮保留（显式动作仍然有用）。

## 端到端验证（真浏览器 + 真库）

造一封未读 → 浏览器里展开会话分组、点开那封邮件 →

    POST /read → 200
    mail_reads 里出现 (reader=gui-lab)
    冗余列 mails.status: unread → read

即"打开即已读"确实生效，而且是记在**读者维度**上（不会像旧的邮件级已读那样
被别人一标就没了）。

## 一个过程记录

前两次验证都"没有发出 /read 请求"，我一度以为代码没生效。其实是**点错了对象**：
会话分组默认折叠，`button:has-text(主题)` 匹配到的是**分组那颗**，点它只展开、
不选中邮件（所以不触发已读 —— 这恰恰是正确行为）。展开后再点具体邮件行才触发。
判据必须点"用户真正会点的那一层"，这句话这次又应验了。

套件：vitest 15 文件 / 258 用例全绿。
 2026-09-14 13:12:36 +08:00
JianFeeeee
8dd3b0eb17 fix(webui): 列表项改为"每项一张玻璃卡"，面板退成透明 
用户：「你为什么是给所有列表项一起套了一个玻璃外框，而不是每个列表项单独套外框？」

**他是对的，而且我上一轮没给理由**：之前的做法是"面板 = 一张玻璃，行躺在里面"，
把列表当成一个整体容器 —— 而界面上其它地方（正文卡、弹层）都是"每一项自己是一块面"，
列表成了唯一的例外，观感上少一层层次。

改法：
- 新增 `.glass-card`（圆角 14px + 半透明 + 细边框 + 悬停加深，带 dark 档）；
- **列表面板退成透明**（壁纸模式下 `html[data-bg='on'] .comm-pane > .bg-white`
  置为 transparent）—— 这样壁纸从卡片之间露出来，卡片才是真正的一块块面；
- 会话分组行与邮件行都换成 `.glass-card`。

实测（自己的无头 Chromium，1600×1000）：
    壁纸关: 面板 rgb(255,255,255) / 卡片 rgba(255,255,255,0.92) / 圆角 14px
    壁纸开: 面板 rgba(0,0,0,0)   / 卡片 rgba(255,255,255,0.78) / 圆角 14px
即"面板透明、每项一张卡"确实生效。

未做（如实说明）：**联系人列表与会话列表**仍是"一张面板 + 行走廊"的旧结构，
只有 MailList 换成了每项一卡。要全部统一说一声，同一套 `.glass-card` 直接套即可。
 2026-09-14 13:09:38 +08:00
JianFeeeee
faacd3c911 fix(webui): 修「宽屏导航栏还是黑色」的真因 —— 应用没有深色主题，导航却单独变深 
用户：「宽屏 ui 你是一点没修复啊」。

## 真因（我前两轮都判断错了方向）

不是令牌抄错、也不是特异性覆盖。是**整个应用根本没有深色主题**：

- `tailwind.config.js` 里 `darkMode: 'class'` 是配好的，
- 但我数了一遍：**没有任何组件写过 `dark:` 变体**（`grep -c 'dark:' src/components/*.tsx` 全 0）；

⇒ 挂上 `.dark` 只会切换我手写的 CSS 变量，Tailwind 工具类一律照旧。
于是系统是深色时（`prefers-color-scheme: dark` → themeStore 的 `system` 解析为 dark）：
**导航**（有深色令牌）变深、**正文**（没有深色样式）仍是浅色 —— 界面半深不浅，
用户看到的就是"导航栏为什么还是黑色"。

## 改法

在真正的深色主题做出来之前，导航**跟随内容的实际形态**（浅色）：
`.dark` 里的导航令牌块清空并留下说明。要做深色主题的正确做法是给组件补齐
`dark:` 变体（独立一件事），而不是先把导航单独压深。

顺带：
- 删掉一条更早的 `.app-shell > .bg-chrome-900 { background-color: rgb(var(--c-chrome-900)/0.82) }`
  —— 侧栏改成 `.nav-rail` 之后它是死代码，但特异性更高，一旦有人再挂上那个类就会重新变黑。
- 「我的」页宽屏用满：`max-w-lg`（512px，右半边全空）→ `max-w-3xl mx-auto`。

## 实测（自己的无头 Chromium，因为共享 9222 的 CDP 已被僵尸上下文拖死）

    系统浅色: htmlDark=false, 侧栏 rgba(255,255,255,0.72)
    系统深色: htmlDark=true,  侧栏 rgba(255,255,255,0.72)   ← 不再单独变黑（这就是修复点）

## 顺带清理

共享 Chromium（9222）里我历次被中断的运行留下了 12 个僵尸标签，
已按 URL 精确关闭（保留 5174/8080/18091 等别人的标签）。
 2026-09-14 13:08:19 +08:00
JianFeeeee
5434bc9e4e feat(harmony): 对齐第一阶段 + 对齐计划文档（差距/分期/验收纪律） 
用户：「安排对齐」。

## 先量差距（不靠感觉）

鸿蒙侧的调色板与 WebUI **根本不同**：`#1A73E8`（Google 蓝）vs 品牌 `#2563EB`、
`#333333` vs slate-900 `#0F172A`、`#F5F7FA` vs `#F8FAFC`、`#FF4444` vs red-600…
共 217 处硬编码色值散在 7 个页面里。

功能面：鸿蒙是 收件箱/会话/联系人 三个 tab，**缺 发件箱 / 授权 / 日历 / 管理**，
也没有玻璃悬浮底栏、主题壁纸同步、Composer 共用组件。

## 第一阶段（已完成并可验收）

- `common/Theme.ets` 补齐文字/浅底/语义令牌，页面里的旧调色板**全量替换为令牌**
  （共 203 处），`hvigorw assembleHap` **BUILD SUCCESSFUL**。
- 判据：`cross-client-theme.test.mjs` 新增"鸿蒙页面里不得再出现旧调色板色值"
  （6 条全绿，含扰动自检）。这条防的是**新页面又随手写个"差不多"的颜色** ——
  漂移就是这么开始的，而此前没有任何判据会红。

## 计划文档：docs/HARMONY-ALIGN-PLAN.md

写清两件事，免得每轮重新猜"还差什么"：

- **差距表**（逐项，标出"缺页面/交互不同/观感不同"的性质）；
- **分期**：P2 发件箱（与收件箱同构，风险最低）→ P3 授权页（备注必须随决策送达模型
  —— WebUI 侧踩过这个坑）→ P4 主题/壁纸同步（服务端"无记录"时以本地为准）
  → P5 玻璃悬浮导航 → P6 日历（最大，单独排）。

## 如实说明

鸿蒙**视觉未验证**：本机 `hdc list targets` 为空、HAP 未签名 ⇒ 只能保证编译通过 +
令牌一致，观感需要设备或签名后由人眼确认。文档里也把这条写进"验收纪律"。
 2026-09-14 12:49:40 +08:00
JianFeeeee
cefd96a6a3 feat(clients): UI 设计同步到客户端 —— Electron 包重建 + 鸿蒙设计令牌 
用户：「下一步就是同步 ui 设计到客户端了」。

## ① Electron 客户端（之前严重滞后）

打包产物停在 **09:11**，而前端 dist 是 **12:23** ⇒ 今天所有 UI 工作（导航合并、悬浮玻璃、
圆桌语言、Composer、动画、模糊分层…）**一个都不在包里**。已重建 AppImage + deb。

**验证**（关键：AppImage/deb 是压缩容器，`grep` 直接扫是扫不到的 ——
我第一次就差点因此得出"包里没有"的结论）：把 deb 解到 /tmp 再查 `app.asar`：

    comm-tabs=2  compose-fab=1  nav-rail=2  glass-control=2  cal-slide-next=2
    构建戳 "5ce25f6·0914-1240"（与当前提交一致）

## ② 鸿蒙客户端

它是**原生 ArkTS 应用**（22 个 .ets、自带 API 层），不是 WebView 壳 ⇒ 设计要移植。

第一步做的是**共用词表**：新增 `common/Theme.ets`（品牌蓝、页面底、面、分隔线、
导航玻璃不透明度、圆角 14/8、语义色、字号），全部注明与 WebUI 令牌的对应关系
（含一个易错点：CSS 是 `rgb(r g b / a)`，鸿蒙是 `#AARRGGBB`，0.72×255≈184=0xB8）。

顺带修掉一个真 bug：TabBar 的选中色写成 `this.currentIndex === 0` ⇒
**只有第一个 tab 会高亮**。现在按每个 tab 自己的下标判断。

**编译验证**：`hvigorw assembleHap` → **BUILD SUCCESSFUL**（HAP 已打包）。
（无法在设备上跑：本机 `hdc list targets` 为空、HAP 未签名 ⇒ 视觉未验证，如实说明。）

## ③ 判据：跨客户端令牌一致性

新增 `test/cross-client-theme.test.mjs` 5 条：品牌蓝、卡片圆角（0.875rem=14px）、
导航玻璃 0.72 —— 断言的是"两边对同一件事取值一致"，不约束实现方式
（CSS 变量 vs ArkTS 常量本来就该不同），并带一条扰动自检。
这种漂移**没有任何判据会红**，所以必须显式钉住。

## 还没做的（如实说明）

鸿蒙端只同步了**设计语言**，功能面不对等：鸿蒙是 收件箱/会话/联系人 三个 tab，
没有 日历/授权/管理；也没有玻璃悬浮底栏与 Compose 共用组件。要做功能对齐是另一件事，
需要单独排期（我可以按你的优先级来）。
 2026-09-14 12:43:08 +08:00
JianFeeeee
5ce25f6fdb fix(webui): 修侧栏点击无法翻页 + 回信 UI 统一成一个组件 
用户两句：「侧边导航栏完全不可用，点击无法翻页，而且窄屏显示不全」、
「按顺序做吧」（= 做回信 UI 统一）。

## ① 侧栏点击无法翻页（严重，我的错）

导航合并时我把点击目标写成：

    onClick={() => setViewMode(target || commTab || modes[0])}

只有「通信」有意回上次的子页签，而**日历/联系人没有 target** ⇒ 点它们会跳到
`commTab`（收件箱）⇒ 表现为"点了没反应/不翻页"。

修成 `setViewMode(target ?? (isComm ? commTab : modes[0]))`。

**为什么没被拦住**：我的验证全在看**结构与样式**（导航项数、徽标、圆角、玻璃、
对比度），**一次都没点过**。所以补了 `test/components/Sidebar.test.tsx`：点每一项，
断言落到它自己那一项，并带一条反向对照。真浏览器点击也复验：日历→日历页、
联系→联系人、通信→回通信页。

## ② 回信 UI 统一（用户点名的欠账）

新增 `src/components/Composer.tsx`：**形状**（输入区 / 动作行 / 提示）只有一处定义，
**差异**用 `header`（选项胶囊）、`footerExtra`、`submit.tone`、`density`
（compact=批注、roomy=回信正文）条件渲染 —— 差异是数据，不是又一套 UI。

三处各写一套的地方现在都走它：提问型授权表单、审批型（同意/拒绝）、ReplyBar 回信。
输入框的边框/圆角/聚焦环/禁用态从"抄了三遍"变成一处。

**重构时我引入过一个危险的错**：给审批型加了个"提交备注"按钮，兜底用 `options[0]`
（= 同意）⇒ 点一下就**默认批准**。被既有判据当场抓住（`PermissionPanel` 两条红），
已改成"点选项即提交"（`submit` 现在是可选的），并用 `variant="action"`
把同意/拒绝的颜色语义恢复成原来的实心绿 / 浅红。

## ③ 我自己的流程问题（写下来）

- 结构类改动必须配一条"**点它**"的判据 —— 这次就是缺了它。
- 单测里改 store 后必须 `rerender` 再点：否则闭包里是旧值（我第一版因此误判代码有问题）。
- 窄屏"显示不全"**没能复现**：390×844 与 320×568 都量了 —— 无横向溢出、
  内容面板完整落在悬浮导航之上、最后一行完整可见。需要用户指出具体页面。

判据：vitest **15 文件 / 258 用例全绿**（含新增 Sidebar 点击 4 条）。
 2026-09-14 12:26:06 +08:00
JianFeeeee
fc4671e55c fix(webui): 去掉卡片/面板各自的模糊 —— 模糊叠模糊 
用户：「你又犯了模糊叠模糊的毛病，整体的模糊是由壁纸那一层模糊确定的，
而你在每一个卡片又打了固定的模糊底」。

## 改动

浮在壁纸上的大面（列表栏、详情栏、卡片、侧栏）**不再各自 backdrop-filter**：

- 它们背后只有**已经模糊过的壁纸** ⇒ 再模糊一次不会更"玻璃"，只会更脏更糊，
  而且每层都要重新采样背景（滚动时明显掉帧）。
- `.bg-white` 接管、面板基线、侧栏基线、壁纸模式下的侧栏 —— 全部去掉 backdrop-filter。
- **模糊只留给真正悬浮在内容之上的层**：底部导航条（浮在滚动列表上）、
  地址建议菜单（浮在表单上）。它们背后是会滚动的内容，模糊在那里才有遮蔽意义。

模糊声明从 9 处降到 4 处。实测（真浏览器，通信页）：**没有任何元素带 backdrop-filter**
（`blurredCount = 0`）。

## 同一轮还有

`test/manual/nav-contrast-verify.mjs` 4/4：
浅色 白玻璃+深字 **7.48:1**、深色 深玻璃+亮字 **6.96:1**（自动反色真的生效）、
两主题底色确实不同、以及反向对照"过渡中途读会拿到起点色"——
这条正是我上一轮把深色模式误判成对比度不足（2.36）的原因。
 2026-09-14 12:02:57 +08:00
JianFeeeee
9aa702b8cc fix(webui): 导航改"按主题的玻璃"（浅色白玻璃+深字）+ 去掉整屏闪的入场动画 
用户两句话：
  「那你为什么不把白字换成黑字或者自动反色或者描边呢？」
  「部分动画十分不合理，会导致页面大范围的闪动，且不能让人自然的把注意力集中在
    将要出现的页面上」

## ① 导航：他说得对，我之前是用错误的方式解决对比度

这个应用是**浅色底 + 深字**，导航却是全页唯一一块黑的 —— 那才是"割裂"。我上一轮
为了"白字对比度"把它做成深玻璃，等于**把一块地方永久压黑**来回避问题。

现在导航底色/文字全部走令牌，按主题切换：

    浅色：白玻璃 rgb(255 255 255 / .72) + 深字 #475569   → 对比度 7.48:1
    深色：深玻璃 rgb(15 23 42 / .72)   + 亮字 #94a3b8   → 自动反色

组件侧改成 `.nav-rail` / `.nav-item[data-active]` 令牌类（Sidebar 与 NarrowNav 同一套）。
同时删掉壁纸模式里写死的深玻璃规则 —— 那条正是"为什么还是黑色"。

## ② 动画：整面板入场删掉

先是从"所有面板一起动"改成"只动主内容区"，试下来仍然不对：页面级淡入会把
**已经在那儿的框架**也一起暗一下，观感还是闪。所以这一档整体删掉，只保留局部、
有明确语义的动效（日历翻页、菜单展开）。实测切视图时 `animatedOnSwitch = 0`。
骨架不动，注意力自然落在变化的那块内容上。

## ③ 一条我自己的误判（值得记下）

深色主题下我量到导航文字对比度只有 2.36，一度以为是变量/级联的问题，还写死了一份
深色字面值。**那是误判**：`.nav-item` 有 `transition: color .15s`，我在切主题后
**立刻**读 computed color，拿到的是过渡的**起点**（浅色值）。决定性证据是连内联
`style.color` 都"改不动"它 —— 级联不可能这样，只可能是还在过渡中。等 400ms 再量就正常。
写死的那份已撤掉，并在 CSS 里留下说明；新判据 `test/manual/nav-contrast-verify.mjs`
用 WCAG 比值量对比度（不是"颜色是不是黑的"），每次读之前等 400ms。

背景套件 32 条全绿（含"导航走令牌 + 两套令牌都在"）。
 2026-09-14 11:57:41 +08:00
JianFeeeee
2b6eb97bc9 test(webui): 横竖屏判据跟上新契约（横屏=侧边导航、列表固定 320） 
`rotate-verify.mjs` 10/10。途中判据自己错了两次，都记在这里：

1. `content` 选择器取 `.narrow-shell > *:not(.narrow-nav)` —— 横屏改用侧边导航后，
   第一个子元素变成了 60px 侧栏 ⇒ 把侧栏当内容区来判断排布，报出一条假失败。
   改成同时排除 `.bg-chrome-900`。
2. 原先只断言"排布换了"，没断言"导航在哪边" ⇒ 用户后续追问的侧边栏
   根本没被判据覆盖。现在补：横屏侧栏必须 60px 且在左侧、底部导航必须不存在；
   竖屏反过来（底部导航存在、无侧栏）。
 2026-09-14 11:36:50 +08:00
JianFeeeee
a456d2127e feat(webui): 横屏导航改为侧边（不再压底部），列表栏固定 320 
用户：「导航栏在窄屏横屏情况下不也应当是在侧边吗？」。

横屏缺的是**竖向**空间：底部导航吃掉本就不多的高度（844×390 里它占了 61px），
而横向反而有余（824px）。所以在紧凑双栏下复用桌面那条 60px 图标栏，去掉底部导航。

## 顺带修掉"横屏没自适应"的另一半原因

列表栏宽度写的是 `lg:w-[320px]`，而 lg 断点是 **1024px** —— 844 宽的横屏不满足
⇒ 它退回 `w-full` ⇒ **列表吃掉整宽、详情被挤成一条缝**。之前我只改了排布方式，
没管这件事，所以横屏仍然不好用。现在按"紧凑双栏"这个**语义条件**给宽度
（`.compact-2pane .comm-pane { flex: 0 0 320px }`），而不是再猜一个像素断点。

**实测**（844×390）：侧栏 60×380 在左侧；导航项 = 通信/日历/联系/我；底部导航**不存在**；
列表栏 x=80 宽 **320**；详情 434；无横向溢出。
 2026-09-14 11:30:51 +08:00
JianFeeeee
d11e6df9a8 feat(webui): 日历翻页过渡动画（方向跟随手势/按钮） 
用户：「日历滑动页面为什么没有切换动画？」。

## 做法

`shift()` 里记下方向（手势与"上一页/下一页"按钮**都走这一个函数** ⇒ 方向只有一个来源），
容器用 **key + 声明的动画类**：

    <div key={`${anchor.getTime()}-${scale}`} className={`flex-1 min-h-0 flex ${slideClass}`}>

## 为什么不是"命令式加类"

第一版用 `el.classList.add()`（与视图切换动画同一套写法），**类根本没进 DOM**。
原因：切月时 `loading` 会把网格整块换成加载态、再换回来，命令式加上的类会被
React 的重渲染与那次重挂载抹掉。key 变化 ⇒ 新元素自带动画类出现 ⇒ 必然重放。

## 顺带修掉一个守卫 bug

`firstRender` 守卫原先只在 `el` 存在时才消费。挂载时 `loading=true` ⇒ 容器还没渲染
⇒ 守卫一直留着 ⇒ **用户第一次真正翻页的动画被吞掉**（实测：点第一下不动、第二下才动）。
现在无条件消费。

## 判据

`test/manual/calendar-swipe-verify.mjs` 增加三条（与滑动手势同一条线索）：
反向对照"刚进页面不跑动画"（animationName=none）、翻页时 `cal-slide-next` +
`cal-in-next` 且时长 >0、反向翻页是 `cal-slide-prev`（方向正确性）。
**实测**：静止 none → 点下一页 `cal-slide-next`/`cal-in-next` 0.2s → 上一页 `cal-slide-prev`/`cal-in-prev`。
 2026-09-14 11:27:37 +08:00
JianFeeeee
ef68c4950c fix(webui): 统一玻璃语言 —— 导航改深色玻璃 + 内层面板自带圆角 
用户：「你不觉得页面设计很割裂吗？尤其是通信页，大面积的非圆角元素。
同时还有大面积的非玻璃样式。导航栏不也应该改为玻璃样式吗，为什么还是黑色」。

## ① 导航还是黑的：因为我自己留了一条"必须不透明"的规则

`html[data-bg='on'] .bg-chrome-900 { background-color: rgb(var(--c-chrome-900));
backdrop-filter: none }` —— 这是**更早一轮**用户的要求（当时面板太透，壁纸从导航里
透出来显得脏）。现在整套语言统一到玻璃之后，导航继续做一块实心黑就成了全页唯一的
例外，也就是"割裂"的来源。

改成**深色玻璃**（α=0.72 + blur(18px) + saturate）——用深色而不是白色玻璃：
白字压在深色上才有对比度。没开壁纸时用 0.82（后面是页面底色而不是照片，太透显脏）。

## ② 通信页"大面积非圆角"：是我修滚动时带出来的

圆角原本只加在外壳上，靠 `overflow: hidden` 裁掉内层的直角 —— 但那个 overflow
会杀掉滚动（上一封），必须去掉。**于是内层白底面板的直角就从圆角外壳里戳了出来。**
现在把圆角直接给内层面板（`.comm-pane > *`），两边对齐，且不依赖裁剪 ⇒ 与滚动不冲突。
MailView 的两条工具条也不再自带宽底（只留上边框，底色继承面板），否则同样会戳角。

## 判据

`background.test.mjs` 里两条**旧判据**（断言"导航必须不透明、不参与模糊"）按现行契约
重写为"深色玻璃（α∈[0.6,0.9]）+ 参与模糊"，并新增"内层面板自带圆角"。
要求反转后旧判据必须一起改 —— 留着只会让下次改动"要么违规、要么把缺陷写回去"。

**实测**（真浏览器，1280×900，壁纸态）：导航 α=0.72 / blur(18px) / radius 14px；
内层 MailList 面板 radius **14px**（不再是直角）。背景套件 31 条全绿。
 2026-09-14 11:17:12 +08:00
JianFeeeee
8a9bc58433 feat(webui): 横竖屏自适应（紧凑双栏）+ 旋屏重算高度 
用户：「为什么窄屏的横屏和竖屏没有自适应」。

## 根因

断点是**纯宽度**的：`(max-width: 1023px)`。手机竖屏 390 与横屏 844 **都落在同一档**
⇒ 布局一个像素都不变，横屏多出来的 ~450px 全浪费在空白上。看起来就是"没自适应"。

## 改动

- 新增 `useCompactTwoPane()`：`(min-width: 700px) and (max-height: 560px)`
  —— 仍是紧凑外壳（悬浮底部导航），但内容区从**覆盖式**改成**列表 + 详情并排**。
  用高度而不是 `landscape` 判：桌面窗口压扁、分屏、软键盘弹起都会命中，
  而它们要的是同一件事（别浪费横向空间）。
- App：`compactTwoPane && hasList` 时走并排分支，其余情况仍是 NarrowStack 覆盖式。
- `--app-height` 增加 `orientationchange` 监听并延后一帧重算（iOS 上部分版本的
  resize 不跟着方向变化走；立刻读会拿到旧高度）。

## 判据

`test/manual/rotate-verify.mjs` 8 条，含**可逆性**与前置对照：
竖屏覆盖式 → 横屏并排（真的换了 class）→ 旋回竖屏恢复覆盖式；
三态的 `--app-height` 分别为 844 / 390 / 844（不是旧值）；横屏无横向溢出、
底部导航仍完整可见且浮着（left=20）。实测 **8/8**。

同一轮还补上了 `test/manual/calendar-swipe-verify.mjs`（日历滑动，4 条）。
 2026-09-14 11:13:24 +08:00
JianFeeeee
0a4b98144c feat(webui): 通信二级页签与列表头一体 + 沉浸式（PWA 全屏）+ 日历滑动验收脚本 
用户三条（同一线索）：「通信页面的二级页面与其他位置极其割裂」、
「不支持沉浸式网页」、「日历页面还不支持左右滑动手势」。

## ① 二级页签不再割裂

页签原先是**带 shadow 的白色胶囊**浮在面板上，看起来像硬贴上去的另一套控件。
改成**下划线页签**：与列表头同一内边距、同一条下边框，选中态用蓝色下划线 +
`-mb-px` 压住分隔线（否则会出现"两条线"的接缝）。

## ② 沉浸式

根因不是 viewport（`viewport-fit=cover` 早就有了，安全区也接了
`env(safe-area-inset-*)`），而是**没有 Web App Manifest**：手机上"添加到主屏幕"后
打开仍然是带地址栏的网页。现在加了 `manifest.webmanifest`（`display: standalone`）
+ iOS 的 `apple-mobile-web-app-capable` / `black-translucent`（状态栏内容叠在页面上）。

manifest 放在**根路径**而不是 /assets/ 下：它里面的 `start_url`/`scope` 是相对
manifest 自己的 URL 解析的，挂在 /assets/ 下就得写 "../"。静态只挂了 `/` 与 `/assets/*`，
所以显式加了一条路由（并从 embed 读，而不是读磁盘 —— 前端产物必须与应用同源同版本）。
图标由项目唯一图标源生成 192/512（尺寸与声明一致，我用 struct 读文件头核对过）。

**实测**：`/manifest.webmanifest` → HTTP 200 `application/manifest+json`。

## ③ 日历滑动：补上真正的验收脚本

`test/manual/calendar-swipe-verify.mjs` 四条，含**反向对照**（纵向拖动不得翻页）
与前置断言。写它时又踩了一次自己的坑：标题真实格式是「2026 年 9 月」（数字与"年月"
之间有空格），我第一版正则按无空格写 ⇒ 匹配不到 ⇒ 三个值全是 null，
**看起来像"滑动没生效"，其实是探针瞎了**。所以脚本里第一条就是"标题读得到"。

实测：9 月 →左滑→ 10 月 →右滑→ 9 月，纵向拖动不动。

## 顺带

把我为验收造的测试数据**归档**（不是删除）：10 个 `/tmp/scrollprobe-*` 独立会话 +
12 封"滚动验收/窄屏验收样例"邮件。
 2026-09-14 11:07:03 +08:00
JianFeeeee
50ee10a522 fix(webui): 修「通信页面完全无法上下滑动」+ 日历左右滑动手势 
## 滑动（用户：「通信页面的各个子页面还是无法滑动啊，我真服了」）

根因不是我第一次以为的 `overflow: hidden`，而是**我把列表包进了一个 flex 列**：

- `MailList` 的根是 `w-full lg:w-[320px] shrink-0 ... flex flex-col` —— 这个 `shrink-0`
  是给**行**方向布局写的（控制宽度），放进列方向后它作用在**高度**上：列表连高度
  都不肯让 ⇒ 内部的 `flex-1 overflow-y-auto` 永远拿不到可用高度 ⇒ 滚不动。
- 表现极具误导性：容器**自己也没有溢出**，所以连滚动条都不出现，看起来像"页面被裁掉了"。
- 为什么以前没坏：列表原先直接挂在窄屏覆盖层（`absolute inset-0 flex`，**行**方向）下，
  行方向的高度来自 `align-items: stretch`，不需要 `min-height:0`。

修法：`.comm-pane > *:not([data-testid='comm-tabs']) { flex: 1 1 0%; min-height: 0 }`
—— 让子面板既能压缩、也填满这一列。对收件/发件/授权/联系人一视同仁，避免只修好一个。

**实测**（390×844，11 行邮件）：修复前 `scrollerCount: 0`（一个可滚动容器都没有）；
修复后滚动容器 = `flex-1 overflow-y-auto p-2.5`、`overflow-y: auto`、可滚范围 236px、
`scrollTop` 实际移动 200px。导航仍完整可见（bottom=834 ≤ 844）。

## 我自己的两个方法错误（都写在这里，避免下次再犯）

1. **判据没断言前置条件**：前三次探针都报"没有滚动容器"，其实是 gui-lab 收件箱太短
   （12 封全落进同一个会话 ⇒ 只显示 1 组）⇒ 内容根本没溢出 ⇒ 我量的对象不存在。
   最后用 10 个**独立会话**把列表撑高才复现出来。用户报的缺陷是真的，是我的探针没到位。
2. 第一条修复（去掉 `overflow:hidden`）方向不对，但我当时**差点把它当成修好了** ——
   因为探针依旧是 0 滚动容器，只是我没深究。结论必须是三态，不能把"量不到"当"没问题"。

## 日历左右滑动（用户：「日历页面还不支持左右滑动手势」）

在日历主体上挂 touchstart/touchend，**复用 `shift()`**（与"上一月/下一月"按钮同一套翻页
逻辑）；阈值：水平位移 ≥40px、且 ≥1.5×垂直位移、且 <600ms —— 否则会把纵向滚动误判成翻页。

**这条我还没验成功**：探针取日历标题的方式不对（返回 null ⇒ 判不了），
不能说它好了。修好探针再补验。
 2026-09-14 11:01:10 +08:00
JianFeeeee
76ce201c3a feat(webui): 导航合并 + 悬浮玻璃 + 页面动画 + 控件档透明度 + 圆角无条件生效 
用户四封信（同一线索）提的六件事，都在这里：

## ① 导航合并（「导航栏的内容有点多了」）

收件箱/发件箱/授权 → 一项「通信」，进去由**内部页签**区分（CommTabs）；
新建 → 「通信」页内**悬浮圆形加号**（ComposeFab）；导航只剩 通信/日历/联系人；
管理 → 合进「我的」，管理员在页面**最下面**看得到（非管理员不渲染，不是禁用）。

`viewMode` 仍是原来那三个值（几十处调用点不用改），新增 `commTab` 记住上次用的子页签；
通信项的徽标 = 未读 + 待决策（授权信息不能因为合并而消失）。

## ② 窄屏底部导航：悬浮玻璃（「还是固定底部延伸，没有玻璃效果，也没有悬浮」）

原来是 `border-t bg-chrome-900` 通栏贴底。改成：左右/离底各留 10px、圆角、
深色半透明 + `blur(18px)`、投影，安全区并入下外边距。

## ③ 页面动画（「页面极度缺少动画，所有页面都是直接出现」）

在 `<html>` 上挂一个短命类触发外壳直接子面板的入场动画。**没有用 key 重挂载**：
面板是 flex 链上的一环，套 wrapper 会改掉 flex 传递（窄屏覆盖层最先坏）。
并且尊重 `prefers-reduced-motion`（关了就一点都不动）。

## ④ 控件档透明度（「复选框和地址猜测项…他们才是真正需要拉低透明度的地方」）

新增第三档 `--bg-glass-control`（0.5/0.55）：授权多选胶囊、地址建议菜单。
三档递减：正文面 0.88 > 嵌套 0.82 > 控件 0.5。

## ⑤ 打底 vs 透明（上一封「该打底的地方透了、该透的空白处糊了」）

正文面回到 0.88（读得清优先）、空白/页面底透明**且不模糊**、面板模糊降到 10px。

## ⑥ 圆角与玻璃**无条件**生效（「大面积缺失圆角与玻璃效果…都是硬截断」）

根因：`.app-shell` 的留缝/圆角/投影原先全写在 `html[data-bg='on']` 里
⇒ **没开壁纸的账号**看到的是硬边不透明面板。现在几何下沉为无条件基线，
壁纸相关的加强仍叠加在上面。窄屏内容面板同样浮起来。

## 判据

- `test/nav-merge.test.mjs` 8 条（含自检：重构前的写法必须判红）——
  改完跑老套件 254 条**全绿却一条都没测导航结构**，结构改动必须自带判据。
- `test/manual/nav-restructure-verify.mjs`：真浏览器 9 条（导航项数、页签切换真的换内容、
  加号 56×56 且 `elementFromPoint` 命中自己、我的页底部管理入口在退出登录之后、
  控件档 α=0.5 对正文面 α=0.88 的反向对照）。
- `test/manual/narrow-glass-verify.mjs` 6 条：悬浮几何（三边留缝 10px、圆角 14px、
  缝隙处命中的是页面底 ⇒ 真的浮着）、玻璃（α=0.82 + blur18）、触摸高度最小 49px、
  动画真的在跑（静止时 `animationName=none`，切换后 =pane-in）且 reduced-motion 下不动。
- `test/background.test.mjs`：把三条**过时判据**（早前那版"越透越好"）按现行契约重写 ——
  旧判据留着只会把我拽回错误方向。30 条全绿。

## 顺带

窄屏探针原先只调视口、**没模拟触屏**，于是 `(hover: hover)` 仍为真，
把「悬停才显形的次要动作」误报成透明 —— 差点去"修"一个本来就对的规则。
已改成 hasTouch + isMobile + DPR 的触屏上下文，且收尾只关自己的 context
（CDP 连的是共享 Chromium，`browser.close()` 会把别人的标签页一起关掉）。
 2026-09-14 10:35:05 +08:00
JianFeeeee
be13ae5959 feat(webui): 界面加构建戳 —— 让"我这边改了没"变成可核对的 
用户连续三轮说「webui 还没改」，而我每次都能证明部署是活的（入口 no-cache、
资源哈希 immutable、线上 bundle 与本地构建逐字节一致、无头浏览器实测生效）——
问题在于**隔着屏幕说不清对方的浏览器跑的是哪一份**。

现在界面里显示一行 `界面构建 <git短哈希>·<月日-时分>`（外观设置面板页脚）：

- `vite.config.ts` 在构建时注入 `__BUILD_STAMP__`（git 短哈希 + 构建时刻）
- `BackgroundPicker` 渲染它，并带 title 说明格式
- 判据 4 条（vite 注入 / 组件渲染 / **产物里真的有** / 判据自检：正则不能匹配随便一段文本）

实测：产物与线上都是 `d2904fc·0914-0910`；刷新后数字变了就是拿到了新构建。

顺带修正一处过时文案：图片说明还写着"保存在本机"，而它现在同时存到账号里
（服务端 + 本地缓存）。

前端 254 条 + 新增 4 条、打包一致性、server 10 包全绿；桌面包已重打。
 2026-09-14 09:11:36 +08:00