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

172 Commits

This Branch
This Branch
All Branches
Author SHA1 Message Date
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
dfaeab0e4d docs(harmony): 记入"必须用系统方案"的要求与 WebUI→鸿蒙的做法对应表 
用户：「鸿蒙也同步，但是鸿蒙要求用系统方案」。

已转给 dsh（线索 harmony-ui-alignment），并写进计划文档：

- **含义**：能交给系统的就交给系统 —— 用 ArkUI 的组件/材质/语义资源，
  而不是把 WebUI 那套"手写 rgba + 自定义模糊 + 自制卡片"照搬。
  系统材质会跟随深色模式、动效曲线与无障碍设置，手写的不会。
- **对应表**：`backgroundBlurStyle(BlurStyle.*)` 取代手写模糊；系统 `Tabs`/`TabBar`
  取代自制导航条；`List`/`ListItem` 取代 `Scroll`+`Column`；组件自身的
  `borderRadius`/`shadow` 取代 `.glass-card`；`$r('sys.color.*')` 语义色取代自切变量
  （**顺带解决 WebUI 那个"半深不浅"的病根**）；`animateTo`/`transition` 取代自定义动画。
- **对既有判据的影响（重要）**：`cross-client-theme.test.mjs` 钉的是三个**取值**。
  改用系统资源后它应当变红 —— 那是预期的，届时要把它从"取值相同"改成"意图相同"
  （品牌蓝仍须一致，材质与圆角允许各自跟随系统）。**必须两侧一起改**，
  避免一边改了一半。

同时提醒 dsh 两条已同步的语义：列表项与顶部都是"每项一张卡/气泡"（不是通栏）；
玻璃只出现在一层。
 2026-09-14 13:45:34 +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
e07e3bf1a1 docs(harmony): 记入交接核对结果与 pi 回复的落地（P2a/P2b 顺序、判据、真 bug） 
第五节：收到 pi 移交信后的核对 —— 移交信里属实的两条（构建成功、cross-client 6/6 绿）、
三处纠正（P3 接口名写错、判据只挡枚举、导航差距其实是信息架构差距），
以及一条与鸿蒙无关但该让 pi 知道的（WebUI `npm test` 在 HEAD 上恒红）。

第六节：pi 回复的落地 ——
- 「会话」入口的结论：不是删功能，是联系人页的**卡片视图** + 收件箱按会话折叠，
  两件到位后再删 tab（在那之前删 = 丢信息：轮次预算 / status / from_agent 无处可看）。
  ⇒ 分期顺序改为 P2a 联系人双视图 + 收件箱折叠 → P2b 通信页签 → P3 授权 → P4 主题壁纸
  → P5 悬浮玻璃导航 → P6 日历 → 最后删 tab。
- 遮罩拆两段式；WebUI 侧不立同名令牌（立了没人用、判据只能验"它存在"，是自证）。
- 两条红判据的 patch 已落地且验证过能判红；background 判据 32 → 34 通过。
- 顺手修掉的真 bug：生成 CSS 头注释提前闭合导致 `.bg-amber-100` 那条规则被整条丢掉。
- 一条判据从来没被跑过：cross-client 判据不在 `npm test` 链里，已加进去。
- `npm test` 现在全绿（退出码 0）；deb 目标在本机打不出来（fpm），要确认是否影响交付平台。
- 仍未验的：鸿蒙侧的视觉与点击（模拟器起不来），到 P2a 必须有人眼或设备。
 2026-09-14 13:30:03 +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
fac30eb09c docs(harmony): 鸿蒙对齐移交 dsh（jianf 指定），计划文档记入负责人与纪律 
用户：「鸿蒙 ui 应当交给对这一块更熟悉的 dsh 负责」。

- 给 dsh 发了移交信（新线索 `harmony-ui-alignment`），交代：
  当前状态（P1 完成）、分期（P2–P6）、**判据纪律**（结构类改动必须配"点它"的判据
  —— WebUI 侧就是因此漏掉了"点日历不翻页"）、**避坑清单**（不许新写死颜色；
  这个应用没有真正的深色主题，别让单个面自己变深；玻璃只该出现一次；
  列表项每项一张卡；ArkTS 的 `arkts-no-any-unknown`/`arkts-no-standalone-this`；
  视觉不可验要如实标注）、以及两条服务端语义（已读按读者记录；
  授权被拒的备注必须送达模型）。
- `HARMONY-ALIGN-PLAN.md` 记入负责人与移交线索，并标明 P1 已完成、P2–P6 归 dsh。

分工：鸿蒙归 dsh，WebUI/Electron 与网关仍归 pi；需要两边同时改令牌之类的配合，
由 dsh 回信给我。
 2026-09-14 13:13:44 +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
be0693821b fix(agents): 四家桥的 read_inbox 一律按会话收窄（dsh/opencode/zcode/homeagent） 
用户：「你还是没修好不同 session agent 收件箱隔离的问题」。上一轮我只修了 **pi**，
另外四家还漏着 —— 它们是**每一家各自实现** read_inbox，不修就还是漏。

## 缺陷

列表按 Agent 列（整个收件箱），而 read_inbox 按契约把**列出来的都标成已读**
⇒ A 会话的回合会把 B 会话的未读标掉 ⇒ B 之后按 `?status=unread` 补投时
再也看不到那封信（静默丢信，不是"少看一封"）。用户是在别的 Agent 上看到它的。

## 四家的修法（各自平台能力不同，但都要"并发安全"）

| 桥 | 会话来源 | 为什么这样做 |
|---|---|---|
| dsh | 工具第二参数 `exec.agent.id` → `reverseMap` | 平台就在上下文里给了会话；**不能用模块级"当前会话"变量**（同进程可能同时跑多条会话的回合，会互相覆盖） |
| opencode | 工具第二参数 `context.sessionID` → `reverseMap` | 同上 |
| zcode | `AGENTMAIL_SESSION_ID`（在**调用时**读） | 一轮一个进程，驱动本来就注入它给授权钩子用；调用时读，避免将来复用进程拿到旧值 |
| homeagent | `p.currentSessionID`（回合开始设、结束清） | Go 插件，本来就有这个状态 |

取不到会话一律**退回整体收件箱**（历史行为），不猜 —— 猜错就是静默丢信。

## 判据

- 服务端语义：`server/internal/repo/session_scope_test.go`（读 A 不动 B、列表收窄、
  计数与列表口径一致）。
- 桥侧接线：dsh 4 条、opencode 3 条、zcode 3 条、homeagent Go 1 条
  （`TestInboxURLScopedBySession`，直接断言拼出来的 URL）。
  每家都带**判据自检**：拿旧写法喂进来必须判红；dsh/opencode 还专门断言
  "不得用模块级当前会话变量"。
- **部署件**（不是仓库）：四家的部署快照里都能 grep 到 `session_id=`。
- **线上实测**：用 opencode 自己的 Agent 身份请求收窄列表 —— 会话 A 3 封、
  会话 B 0 封、两者无交集、且都是全量的子集。

套件：opencode **331**、dsh **381**、zcode **385**、homeagent ok，全绿。
四家桥已重新部署（dsh/opencode/zcode 快照切换 + homeagent 新 plugin.bin 并重启），
四个服务均 active。
 2026-09-14 12:07:45 +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
552fbc731e fix(inbox): read_inbox 按会话收窄 —— 修「不同 session 的 agent 都能看到全部邮件」 
用户问：「你之前不是说你已经处理了不同 session 的 agent 都可以看到全部邮件的
问题了吗？」——**我得先纠正事实：上一轮我只做了诊断并问要不要动手，没有实施。**
这是我的表述问题（把"已定位并给了方案"说成了像"已处理"）。现在实施。

## 缺陷

`read_inbox` 是**按 Agent** 的：列的是该 Agent 的全部未读（含别的会话的来信），
并按契约把列出来的都标成已读 ⇒ A 会话的 worker 标掉 B 会话的未读。平时看不出来
（SSE 事件在途时队列兜着），但桥重启/漏事件后的补投判据是 `?status=unread` ——
被标掉的那封**再也不会补投** ⇒ 静默丢信。现场实例：另一条会话的来信在
`mail_reads` 里的 reader=pi、时间正是我读自己收件箱的那一刻。

## 改动

- **网关**：`GET /mail/inbox` 与 `POST /mail/read` 支持可选 `session_id`。
  不带 = 旧语义（整个 Agent 的收件箱，浏览器/脚本仍可用）；带了就只在这条会话内
  列与标。`ListInbox` / `MarkAllInboxReadFor` 保持原签名并委托给新变体 ——
  老调用点一个都不用改。
- **pi 桥**：`read_inbox` 把自己那条会话拼进 URL（worker 通过闭包把**邮件会话 id**
  递给工具，而不是在启动时取快照）。

## 判据

- repo 三条：列表按会话收窄（含"不带会话时两条都在"的反向对照）、
  ★"标会话 A 不动会话 B"、会话内计数与列表口径一致（否则界面会出现"徽标 2、列表 1"）。
- handler/网关：非法 `session_id` ⇒ 400（不静默忽略）。
- pi 接线三条（URL 拼了收窄、worker 递了 id、判据自检：旧写法必须判红）。
- 线上只读 E2E：两条真实会话 A/B 列表**无交集**、不带会话能列出全部、非法 id 400。

## 过程中测试当场抓到"只改了一半"

`MarkAllInboxReadForSession` 里插 `mail_reads` 的语句我加了会话条件，
**刷新冗余列的 UPDATE 忘了加** ⇒ 返回的"标掉几封"变成 2（应 1）。
判据一眼看出来了 —— 这类"改一半"正是这次要防的。

## 范围（诚实说明）

另外四家桥（dsh/opencode/zcode/homeagent）的 `read_inbox` 工具签名里**没有会话上下文**
（`execute(args)` / `execute(args, ctx)` 各不相同），要按各自框架的上下文 API 接线，
不是一行改动 ⇒ **未做**，列为待办（位置已定位）。所以：pi 上这个缺陷已消除，
另外四家仍在。

## 部署

网关已部署并线上验证；pi 桥的部署**延迟到本轮结束后 150 秒**执行
（重启 pi 桥会掐掉我自己这一轮 —— 之前真发生过），日志
`/var/log/agentmail-pi-redeploy.log`，可用 `node deploy/check-deploy-drift.mjs` 核对。
 2026-09-14 09:19:25 +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
JianFeeeee
d2904fc45d style(webui): 导航栏改为完全不透明 + 内容面板更通透 + 整屏浮动圆角玻璃 
用户 2026-09-14 原话：「导航栏应当完全不透明……没有正文的位置过于不通透，
同时导航栏应当现代化一下，整个界面应当圆角化玻璃化」。

这三句是**两个方向**的要求，我上一轮正好把导航栏做反了（越改越透）：

## ① 导航栏：完全不透明（含窄屏底部导航）

`chrome-800/900` 在背景模式下不再吃 alpha、也不参与模糊。它是**框架**，
不该跟着壁纸一起虚化。它与"内容要通透"是两个方向的要求，所以写成独立规则、
并在注释里点名 —— 合并成一条必然互相打架。

## ② 内容面板：更通透

`--bg-glass` 0.62 → **0.45**（深色 0.66 → 0.5），嵌套层 0.3 → 0.22。
实测（纯红壁纸读绿通道）：邮件列表有效不透明度 115/255 ≈ **0.45**，正文区全透。

## ③ 整屏浮动圆角玻璃

给宽屏外壳加了稳定钩子 `app-shell`，背景开启时：外壳 **padding/gap 10px**
（面板之间露壁纸 —— 没有缝隙的"玻璃"看上去仍是一整块板）、顶层面板
**圆角 var(--radius-card)** + 投影。实测三栏：导航 60px/圆角14px/不透明、
列表 320px/圆角14px/0.45、正文 1020px/圆角14px/全透。

## 判据

`test/background.test.mjs` 新增 5 条形态判据（导航不透明、导航不参与模糊、
`--bg-glass ≤ 0.55`、外壳留缝、顶层面板圆角），共 **28 条**。
前端 254 条 + 打包一致性全绿。

## 过程中的三处自纠

1. **我的 App.tsx 编辑第一次根本没落盘**：那份 python 脚本第 18 行语法错误就整体
   没执行，而我把"✓ 已加钩子"当成了成功 —— 后来 `.app-shell 存在: false` 才暴露。
   教训：脚本报成功不等于目标文件变了，**改完要回读**。
2. **JSX 里把 `{/* … */}` 放在 `return (` 与根元素之间**是非法的 ⇒ 构建失败。
   改为 JS 注释放在 `return` 之前。
3. ★ 这两次失败都是**新加的部署闸门先拦住的**（"前端 dist 比源码旧"），
   也就是上一轮刚补的那道门当天就发挥了作用 —— 换成以前，会再次静默部署旧界面。

## 顺带清理

验收截图用的 2 封样例邮件已删、随之产生的空会话已归档；测试账号外观已重置。
 2026-09-14 09:07:49 +08:00
JianFeeeee
ca96f77a4b fix(appearance): 浏览器里同步从来没跑起来（三处叠加）+ 部署链加"前端不得比源码旧"闸门 
用户说「webui 你也没改呢」。查证：**部署是活的**（本地产物 = 线上产物、CSS 里壁纸
修复的规则都在、入口 `Cache-Control: no-cache`、资源哈希+immutable）——是我新加的
"外观存服务端"那套在**浏览器**里根本没生效。沿途挖出三处叠加缺陷 + 一处部署链真空子：

## ① 路径写成绝对 `/api/v1/...`（双前缀 ⇒ 404）

`resolveBase()` 解析出来的 base 已经含 `/api/v1`（默认就是它），既有调用者传的都是
`/me/mail/inbox` 这种**相对基地址**的形状。我写成 `/api/v1/me/appearance` ⇒ 实际请求
`/api/v1/api/v1/me/appearance` ⇒ 404。
**单测全绿却没抓住**：我只断言了方法、报文，没断言 URL。现在补了 URL 判据
（含"不得出现 /api/v1/api/v1"这条）。

## ② 浏览器密码登录只有 cookie、没有 Bearer ⇒ `currentAuth()` 直接短路

`currentAuth()` 原先要求 token 非空，而密码登录只建 cookie 会话（桌面端粘贴用户密钥
才设 Bearer）⇒ WebUI 里 `pull/push` 从来没跑过。已放宽为"只要有 base"，并补了两条
判据（cookie 会话也要能拉、能推）。
（"完全没有网关地址 ⇒ local-only"这条判据删掉了：`resolveBase()` 总有默认值，
那个状态到不了 —— 判据不量够不着的对象。）

## ③ 服务端"无记录"时拿默认值覆盖本地

首次启用同步时每个老用户都会中招：服务端回默认值（theme=system / bg=none），
客户端照着应用 ⇒ **用户已有的主题与本地壁纸被静默重置**。现在改为"以本地为准、
推上去认领"，并补判据（含"有记录时以服务端为准"的反向对照）。

## ④ 部署链真空子：dist 比源码旧也能"同步成功"

改完源码忘了 `vite build`，`redeploy-gateway.sh` 照样把旧 dist 打进二进制 —— 这正是
①在线上一直没被发现的直接原因。现在部署脚本会比对 `src/**` 与 `dist/index.html`
的 mtime，旧了就 **FAIL** 并提示先 build。

## 顺带：我自己在真实账号上留的测试数据

线上 E2E 时我把 `theme=dark/bg=preset(dusk)/dim=35` PUT 到了 **jianf** 这个真实账号
（应该用测试账号）。已删掉那条记录（接口现在回 `saved:false`），配合 ③ 的修复，
用户本地那份外观会被认领上去而不会被覆盖。

## 验证

- 浏览器实测（自带无头 Chromium + 真实功能，非注入 CSS）：
  `200 GET /api/v1/me/appearance` → `data-bg=on`、`dark=true`、本地缓存写入 ✓
- 三张对比图（自定义图片档 / 关背景 / 预设渐变）已随邮件发给用户
- 前端 253 条（含新增 URL 判据与 cookie 会话判据）、server 10 包、打包一致性全绿
 2026-09-14 08:59:32 +08:00
JianFeeeee
69b1887eae chore(deploy): 清理部署残留（1.0GB）+ 把清理写成可复跑脚本 
用户说「清理一下」。实测 /opt/agentmail 累计 1.3GB：
- 网关旧二进制 33 份 × 24MB ≈ 790MB（每次 redeploy 留一份，从 09-05 起没清过）
- 插件快照：opencode 6 份 339MB、dsh 7 份 195MB、zcode 16 份、pi 9 份
- /tmp 里的部署前数据库备份 10 份（tmpfs，占内存）

新增 `deploy/prune-deploy-artifacts.sh`（可复跑，不手敲 rm），两条硬规矩：
① **保留回滚窗口**：网关留最新 3 份、每个插件留最新 3 份快照，`current` 永远保留
（发布纪律要求有回滚目标，所以不是全清）；
② ★ **绝不删正在使用的快照**：扫 /proc 的 cmdline 与 cwd，命中就跳过。

执行结果：**/opt/agentmail 1305MB → 302MB（释放 1003MB）**，7 个服务全部 active，
`current` 指向未变，`check-deploy-drift` 仍报「四个宿主都在跑当前代码」。

## 过程中的一处自纠

"在用"闸门第一版有**自我匹配**缺陷：我的测试命令把路径写在命令行里，于是扫 /proc 时
扫到了自己 ⇒ 对不存在的路径也判"在用"（与 `pkill -f` 杀掉自己那条命令同一类）。
已改为排除本进程及其祖先链，并**换正确方式重测**（路径从文件读、不进 cmdline）：
在用快照判"在用" ✓、不存在的路径不误判 ✓ —— 判据两侧都验过才敢执行删除。

文档：docs/DEV-TOOLING.md 记了用法与那两条规矩。
 2026-09-14 08:43:54 +08:00
JianFeeeee
51789ee72e deploy: 标准目录部署 —— 运行时不再依赖源码目录 
用户注意到：「当前 agentmail 是在源码目录部署的，应当改为标准目录部署」。
查证后有三处实证（都不是猜测）：

1. ★ **失败通知钩子执行的是仓库里的脚本**
   （`/home/program/agentmail/deploy/service-failure-notify.mjs`，8 处引用：
   4 个 drop-in + zcode/zcode-mail-bridge 单元 + agentmail-failure-flush）。
   仓库一挪/一改名，故障通知就**静默失效** —— 而那条管线正是用来报告服务故障的。
2. **opencode-serve 的 cwd 就是源码目录**（`WorkingDirectory=/home/program/agentmail`）。
3. ★ **仓库里的 `deploy/*.service` 是旧的源码目录版本**（ExecStart 指向
   `/home/program/agentmail/plugins/...`），而机器上的已被改过 —— 也就是说
   **谁跑一次 install.sh 就会把部署退回源码目录**。drop-in 更是只存在于 /etc 里，
   仓库完全没有它们。

## 改动

- **唯一真相**：`deploy/systemd/` 镜像 systemd 目录结构，收进全部单元与 drop-in
  （8 个单元 + 12 个 drop-in），路径全部改到 `/opt`。
- 运行时脚本装到 **`/opt/agentmail/bin/service-failure-notify.mjs`**（自包含，
  无相对导入）；`install.sh` 与 `redeploy-gateway.sh` 都会幂等地装它。
- opencode 的 cwd 改为 `/opt/agentmail`（与网关一致），已重启生效
  （`/proc/<pid>/cwd` 已核）。
- 删掉 `deploy/*.service` 的旧副本，避免两个真相。
- dsh 的 `cordis.patch.yml` 注释里的安装示例也改到标准位置（运行时用的是环境变量，
  那条注释是唯一残留）。

## 判据（`deploy/check-deploy-drift.mjs` 新增「标准目录部署」四条 + 自检）

① 任何 unit/drop-in 都不得引用源码目录；② 已安装单元与 `deploy/systemd/` 逐字节一致；
③ 通知脚本在标准位置且可执行；④ 各服务的 cwd/ExecStart 不在源码目录
（homeagent/dsh/zcode 是**别的产品**的标准位置，按白名单放行）。
自检两个样本：引用源码目录的必须红、干净样本必须绿（证明不是恒真）。

顺带修掉一处**真漂移**：仓库里 dsh 的 `dist/index.js` 落后于部署件（改了 src 没重建），
重建后 `check-deploy-drift` 报「四个宿主都在跑当前代码」。

## 复核

- `/etc/systemd/system/` 引用仓库：**0** 个文件；`/opt/agentmail` 下只剩旧二进制/备份里
  的构建路径（Go 嵌的源码路径，无害）与一条注释。
- 四个宿主都在跑当前代码；标准目录四项全绿。
- 全部服务 active，opencode/网关 cwd 均已在安装根下。
 2026-09-14 08:38:33 +08:00
JianFeeeee
5b6fef764f feat(appearance): 主题与壁纸搬到服务端（账号级）—— 回答"为什么背景存在本地" 
用户质问：「为什么背景是保存在本地而不是服务器！」当时的实情是主题与壁纸只写
localStorage：换设备/换浏览器就没了，而且**多账号共用一份**（键是全局常量
`agentmail.background`）—— 同一台机器换账号背景不跟着走。而 localStorage 的 ~5MB
配额也解释了客户端那套"压到 2.4MB 以内"的限制本来就是为本地存储设计的。

现在：**服务端是权威（账号级），本地只是缓存**（首屏秒开、离线可用）。

## 服务端

- 新表 `user_appearance`（两种方言），用**列**而不是 JSON：blob GC 要一眼看出
  "这张图还有没有人用"。
- `/api/v1/me/appearance`：GET / PUT（主题+背景档）/ POST image（multipart）/
  GET image / DELETE image。鉴权同其余 /me/*（cookie 或 Bearer）。
- 图片走**内容寻址的 blob 存储**（与附件同一套），库里只存 sha256；上限 4MB 兜底
  （客户端会先压到 ~2.4MB），只收图片类型（非图片 415 —— 浏览器会把非图片渲染成
  空白，用户只会看到"设置了却没变化"），超限 413 不静默截断。
- ★ **blob GC 的引用源加了这张表**：我在实现前先读了 `SweepUnreferencedBlobs`，
  它只认 attachments / calendar_attachments。漏了这一处，壁纸会在下次 GC 时被当
  孤儿删掉，而库里那行还在 —— 表现为"图 404、设置却显示已设置"。判据同时验了
  壁纸存活**与**孤儿确实被清（否则"还在"可能只是因为 GC 没跑）。

## 客户端

- `lib/appearance.ts`（纯函数：两侧形状换算、data URL→Blob）+ `stores/appearanceSync.ts`
  （pull / push / 去抖订阅 / 账号切换重新拉取）。
- 三条不变量都有判据：拉取以服务端为准；★ **拉取不会再推回去**（否则是自触发回环，
  一次拉取顺带一次 PUT，服务端 updated_at 被无意义刷新）；本地改动会推上去。
- 壁纸**只在换图时上传一次**（几 MB 不该每次 PUT 都跟着走）。
- 降级**必须可见**：未登录/不可达 → `local-only`，推失败 → `pending`，背景设置里
  有徽标与说明（"已同步 / 待同步 / 仅本机"）。静默降级会让人以为已经同步，
  然后在另一台机器上发现没有 —— 正是这次的缺陷。
- 图片用**带认证的 fetch** 取回再转 data URL：`<img src>` 发不出 Bearer，而
  `?token=` 会把密钥写进历史记录与服务端日志（明确不做）。

## 判据

- Go 10 条：往返、★多账号隔离、非法值归一、上传/取回字节一致、非图片 415、
  超限 413、删除、未登录 401（五个端点）、★GC 存活 + 孤儿对照。
- 客户端 10 条：形状换算、image 无图退回 none、越界夹取、拉取生效、
  ★拉取不推送、推送 payload、未登录/500 → local-only、推失败 → pending、
  ★壁纸只上传一次。
- 全量：server 10 包全绿、客户端 249 通过（含打包一致性判据 —— 它先红后绿，
  因为前端改了必须重打安装包，这条护栏是先前特意留下的）。

## 线上验证与交付

- jianf 设置 → 回包 saved=true；**gui-lab 读到自己那份默认值**（隔离生效）；
  gui-lab 上传 67B PNG → 取回 sha256 一致、`has_image=true`；DELETE 后 404。
- 网关已重打（WebUI 内嵌）并部署；Electron 安装包已重打（AppImage + deb）。

遗留：鸿蒙端还没有外观功能（数据已在服务端，将来可直接读）；本地缓存仍在（离线可用）。
 2026-09-14 08:32:22 +08:00
JianFeeeee
1ec88866ac fix(permission): 另外四家桥的"人类说明"缺口 —— 三家修、一家本来就有 
承接 453f451（pi 桥）。用户批准后把同款缺口在其余四家逐一核对：
**zcode 本来就有**（`说明：${decision.note}`），homeagent / dsh / opencode 三家缺。

## homeagent（Go，能完整修）

SSE 事件结构里**根本没有 Note 字段**（json 里只有 decision/decided_by）⇒ 备注在
解码那一步就没了。补上字段，并把提示词抽成纯函数 `permissionDecisionPrompt(evt)`，
加了判据（说明必须出现 + 反向对照：无说明/空白说明不得凭空造出说明段）。
构建（`go build -buildmode=plugin`）后 install 到
`/home/newqqagent/plugins/homeagent-mail-bridge/plugin.bin` 并重启，已核验部署件
含新符号（`grep -a`，中文用 strings 查是查不到的）。

## dsh / opencode（平台回执放不下理由 → 分两步）

两家的审批回执都是**三态字符串**：DSH `ApprovalOutcome` 只有
allowed-once / rejected / cancelled / unavailable，openCode 只有 once / always / reject
—— **没有地方放人类的说明**。所以：

1. 提示词（"你之前发起的权限请求已有结论：…"）统一走 `permissionPrompt(data)`，
   带上 `用户的说明：…`。dsh 原有**三处**内联文案（续谈/新会话/通知投递），
   措辞分叉正是这类信息漏掉的地方 —— 判据直接钉"只有一处拼这句话"。
2. 带说明的决策**另投一趟通知**，让模型在会话里看到理由。代价是多一轮；比悄悄
   丢掉人的指令轻（原缺陷就是丢了指令，模型把同一条命令换写法又问一遍，连问 9 次）。
3. 决策回执不再被当成"新任务"（内容已随 permission_decision 交付），并记下
   `decision_mail_id` 防重复 —— 与 pi 桥同源。

判据：dsh / opencode 各 5 条（含"拿缺陷时的源码形态喂进来必须判红"的自检）。

## 部署与代价

- dsh → 快照 20260914-081456、opencode → 20260914-081516、homeagent → 新 plugin.bin，
  三家的服务 active 且心跳/连接已核。
- 重启 dsh 时它正在"续谈"一封邮件（08:10:45 日志）——事后核对：那一轮**已回完**
  （faad0037 的 parent = 4919aa88），没有丢活。
- 套件：dsh 372、opencode 323、homeagent go test ok、zcode 382 全绿。
 2026-09-14 08:17:23 +08:00
JianFeeeee
ababe4ae56 fix(webui): 壁纸被不透明层盖住 —— 玻璃不再层层相乘 + 浅色表面类全部接管 
用户报的：「webui 目前在壁纸底上叠了太多不透明层，导致壁纸效果很差，几乎看不出来」，
追问后补充：「不只是玻璃，而是很多界面是不透明的」。两句都成立，是两个叠加的原因。

## ① 玻璃层层相乘

每层面板都吃同一个不透明度 a，两层就是 1-(1-a)²。a=0.82 时两层 0.97、三层 0.995
—— 壁纸在数学上被吃掉，而且每层各做一次 16px 模糊，图案被糊成灰块。
改法：玻璃只出现一次（外层 0.62 + 18px 模糊；嵌套层只留 0.3 色调且不再模糊；
第三层透明）。同时把遮罩 24%→12%、照片自身模糊 8→4px（那张被洗白的锅之一）。

## ② 14 个浅色表面类根本没被接管（"很多界面是不透明的"就是这条）

旧规则只接管 white / gray-50 / slate-100，而源码里在用的是
gray-100(24 处)、blue-50(17)、red-50(13)、blue-100(8)、gray-200(8)、green-50(8)…
—— 全是实心的，正好盖住壁纸。

清单改为**从源码用法生成**（`scripts/gen-background-takeover.mjs` → 生成的 CSS，
构建前自动跑），因为手写清单必然烂；判据保证"源码里出现的浅色表面类必须都被接管"，
并明确排除页面底（gray-50/slate-100 必须保持**全透明**，不能被改成半透明）。
按钮/徽标（*-600/700、chrome-600/700）**故意保持不透明**：小控件可读性优先
（index.css 里原有注释记着实测 4.46:1 的教训）。

## 判据

- `test/background.test.mjs` 23 条（新增 8 条）：玻璃算式（两层 ≤0.85）、外层 ≤0.70、
  嵌套规则存在、**判据自检**（旧值 0.82 必须算得出 >0.95）、表面类覆盖、页面底不得进清单、
  清单非空跑。犯过一次错：第一版把判据追加在 `process.exit()` **之后** ⇒ 根本没执行，
  从"测试数没变"才发现。
- `test/manual/wallpaper-layers-verify.mjs`（真实渲染，自带无头 Chromium）：
  用**纯红壁纸读绿通道**测有效不透明度（纯色下 backdrop-filter 不影响读数）。
  面板 p95：**修复前 82% → 修复后 62%**；反向对照（改回旧值）能分辨 ≥10 个百分点；
  深色照片面上面板仍是浅底；关掉壁纸的同坐标对照更实。5/5。
  过程中作废了两个指标：只看绿通道会把深色元素误判成"盖死"；"面积占比"类阈值
  （Δ≥8/≥40）在 0.97 时仍会蹭过门槛，饱和而无分辨力 —— 同坐标比值才可信。

## 交付

已部署（网关内嵌 WebUI 重建）：线上 CSS 已含 `--bg-glass-inner`、嵌套规则与 14 个接管类。
 2026-09-14 08:09:22 +08:00
JianFeeeee
453f451fbb fix(permission): 人类的备注必须到达模型 + 决策回执不再被当成新任务 
用户报的「很严重的问题」：被拒绝的 agent 看不到授权备注，且看不到他发的回复邮件。
按数据查到了两个**真缺陷**，都在桥的权限回路上（不是猜测，三层证据）。

## 缺陷一：备注在桥内被连丢三处

网关其实一路都带着备注（`CreateDecisionMail(..., req.Note)` 把备注写进决策邮件正文，
SSE payload 里也有 `"note"`），但桥的三个环节只传 decision：
  index.mjs  `pool.routePermission(relayKey, String(data.decision))`
  pool.mjs   `child.send({type:'permission_decision', relayKey, decision})`
  worker.mjs `resolve(String(msg.decision))`
模型最终看到的只有 `用户拒绝了这次 bash 调用`（pi 会话转录逐字可查）。

现场：人类写「我说了让你拉取仓库到program下你听不懂吗」，模型不知道要改什么，
把同一条命令换个写法又问了 —— 会话里连问 **9 次**（22:16–22:26）。

## 缺陷二：决策回执照样被当"新任务"投递 + 等人的邮件被堵在后面

决策是**双通道**送达：SSE `permission_decision`（唤醒停放的 worker）+ 一封普通形状的
邮件（"Re: 权限请求 - 拒绝"）。以前两条都会起动作 ⇒ 同一件事被处理两次；而这条会话
的新邮件在 worker 停放期间只能排队。实测：人类 22:18:08 发出的更正
「不对，不是让你拉取到agentmail仓库，是让你拉取到program仓库！！」
直到 22:26:30（worker 回合结束）才被模型看到 —— **8 分钟**里它一直在错误的目录上打转。
转录里那封更正确实是模型自己 `read_mail` 读到的（不是没人给它）。

## 改动

- 网关：`CreateDecisionMail` 写 `mail_type='permission_decision'` —— 桥据此区分
  「控制面回执」与「新任务」。
- pi 桥（新增 `lib/denial-reason.js`、`lib/waiting-mails.js`）：
  · 备注随决策一路透传到**模型看到的拒绝理由**（工具拦截与通知投递两条路都带）；
  · 恢复停放的 worker 时，顺带把「等人期间新到、尚未标记已读」的邮件附进理由，
    模型当场就能改道（这正是那 8 分钟的洞）；
  · 决策回执不再起新任务轮次（记进 deliveredMails）；若决策事件尚未到达，
    退化为 B-4.3 的通知投递，且没有会话时不凭空新开。

## 判据

- `test/permission-note.test.mjs`：11 条（备注进理由、无备注不得凭空造说明、
  等人期间的邮件要点名 read_inbox、只挑本会话非权限类未交付的、上限、旧回包缺
  session_id 不能丢邮件、接线 8 处形状、判据自检）。
- **扰动验证**：把备注从 `pool.mjs` 的 send 里去掉 → 接线判据 2 条红；恢复 → 11 绿。
- 既有 pi 套件 420/420；server 10 包全绿（新增 1 条 Go 判据验决策邮件的类型与备注正文）。

## 现场证据（可复核）

- 桥日志：9 次 `权限 <key> 决策 同意/拒绝（决策人 jianf）已转交 worker`，全程不含备注；
  「worker 2135211 等待权限决策，让出并发额度（停放 1/5）」
- 会话转录：`{"toolName":"bash","content":[{"text":"用户拒绝了这次 bash 调用"}]}` ×6
 2026-09-13 22:47:25 +08:00
JianFeeeee
773acd079f harden(migrate): 抄送回填取切换时刻改 CAST(TEXT) —— PG 的 timestamptz 会被扫成 time.Time 
判据只在 SQLite 上跑过：把 MIN(read_at) 扫进 sql.NullString 在 PG 上依赖驱动返回类型，
不可靠。改成 CAST(... AS TEXT) 再解析，并把 PG 的文本形态（+00 时区后缀）加进可识别的
layout 列表。认不出来时退回现在= 把当下已有的已读邮件全算作迁移前 —— 首次升级时
正是对的，且有一次标记守着不会反复跑。
 2026-09-13 16:22:00 +08:00
JianFeeeee
2e5d84330b fix(gateway): 已读迁移对抄送方保持行为不变 —— 我上一版迁移把桥的补投判据放大了 
上一提交（1619399）把已读改成按读者记录后，回填只把历史 `status='read'` 记到**主收件人**
名下 —— 对抄送方等于"突然多出一批未读旧邮件"。这不是理论风险，**当天就在野外发生了**：

  opencode 桥（部署后 46 分钟）：
    16:06:48 [mail-bridge] 已接入 http://127.0.0.1:8180，身份 opencode（密钥认证）
    16:06:49 [mail-bridge] 补投 2 封离线期间的邮件（共 2 封未读）
  → 它对 05:42 那封「打个招呼」**又回了两次信**（08:07:21Z / 08:08:37Z）

即桥的 `pending_mails = CountUnread` 因迁移变大 ⇒ 桥一重启就把旧信当漏投重放并再次回信。
两个人工探针当时都只覆盖主收件人，恰好绕过这个面（"同一封被多人共享"的坑，
判据必须站到每个收件人各自的位置上）。

修法（`backfillMailReadsCC`）：迁移前的邮件（`created_at <` 切换时刻）凡 `status='read'`，
给它的**所有收件人**（主 + 抄送）各补一行 —— 与旧模型下"所有人看到的都是已读"完全一致；
迁移后的邮件一律不碰（那条界线是判据核心：越界就会把"某个人读过"错写成"所有收件人都读过"）。
切换时刻：迁移时写进 `app_meta(read_model_switchover_at)`；老库没有这个键时退化成
`MIN(mail_reads.read_at)`（那张表的第一笔写入就是回填批次）。

判据 `internal/db/migrate_reads_test.go`：迁移前的老邮件必须补到抄送方、**迁移后的不能碰**、
重复执行不重复插。扰动验证：去掉时间界线 → 判据红（补记 2 行，期望 1）。

实测收口：
- 迁移日志「再给 4 个抄送方补记历史已读」；"抄送方仍算未读（已读邮件）" 计数 **0**。
- **重放反证**：重启 opencode / pi 的桥 → 无"补投"行、3 分钟内 0 封新邮件 ✓
  （对比修复前 opencode 重启即补投并回信）。
- 清掉那 2 封由这次迁移产生的误回信（happy-pixel 回到 6 封）。
- 全量 server 10 包 + client/electron vitest 239 + 五 Agent 演练 20/20 全绿。

教训：**语义迁移必须让"可观测状态"保持不变**，新语义只对迁移后新增的对象生效 ——
否则用户会看到一批凭空冒出来的未读，而下游（这里是桥的补投）会把它当真实信号动作。
 2026-09-13 16:18:37 +08:00
JianFeeeee
1619399470 fix(gateway): 已读改为**按读者**记录 —— 修掉"别人读掉，我就看不到" 
用户报的那句 dsh 自述（"收件箱列表未展示它，直接按 mail_id 读取成功"）不是插件问题，
是网关的已读模型：`mails.status` 是**邮件级**的一个列，任何收件人读掉，对所有收件人
（含抄送）都变成已读 —— 全库没有任何按人记录已读的表，我查过 schema 与迁移文件。

实测复现（两个人类用户、一封共享邮件，排除 Agent 干扰）：
  gui-lab 读掉 → gui-lab 未读清空（应当）→ **jianf 的未读也没了**（错误）
  而 jianf 的 `status=all` 里仍在 ⇒ 是已读语义问题，不是送达问题。
线上那封信正是这个形状：`jianf → dsh` 抄送 pi/opencode/zcode/homeagent，**pi 最先
回复（= 它读过了）** ⇒ 这封对 dsh 也变成 read ⇒ dsh 的 `read_inbox`（默认 unread）
返回空 ⇒ 它只能按提示词里的 mail_id 兜。

三个受害面：① Agent 的 `read_inbox` 拿不到信（换一个不兜的模型就变成"正文是空的"）；
② 人类的未读被抄送的 Agent 读掉；③ ★ 桥的补投判据 `pending_mails = CountUnread` 归零
⇒ SSE 漏过或进程重启时那封信**不再补投**（静默丢信）。

改动：
- 新表 `mail_reads(mail_id, reader_name, read_at)`，未读 = 这张表里没有该读者的行。
- 判据收敛到一处（repo 的 `unreadFor` / `readStateFor`），六处读写点全部改用它：
  单封已读、批量标已读、权限决策（只记**决策人**）、`ListInbox`（过滤 + 返回的
  status 都按读者算）、`CountUnread`、`CountUnreadInSession`、会话列表未读计数。
- 一次性回填补历史：`mails.status='read'` 记到**主收件人**名下（唯一可用的推断），
  用 `app_meta` 里的标记守住 —— 不能每次启动都跑，那会把"某抄送方读过"按主收件人
  写成已读，正是这次要修的错。实测：`done rows=207`。
- `mails.status` 保留为"有人读过 / 已归档"的冗余列，**不再是判据**。

★ 顺带挖出并修掉一个真 bug：`CountUnreadInSession` 用的是 PG 专有语法
（`cc_list @> $3::jsonb`），而线上是 SQLite ⇒ 那条 SQL **语法错误**
（`unrecognized token: "@"`），调用点又是 `unread, _ :=`（吞错）⇒
**会话列表的未读数一直是 0**。现已改用仓库既有的方言助手 `db.CCHas`。
实测：happy-pixel 会话现在 `unread_count=5`（修复前恒 0）。

判据：新增 `internal/repo/readstate_test.go`（5 条：按读者未读、会话内计数、
批量标已读、归档对所有人可见性、权限决策只记决策人）。
**扰动验证**：把 `unreadFor` 退回旧语义 → 4 条判据全红；恢复 → 绿。
全量 server 10 包全绿。文档同步：API.md 的「标记已读」段 + PLUGIN-CONTRACT 的 T-1.4。

线上复验：同一受控实验 —— gui-lab 读掉后，**jianf 的未读仍在且 status=unread** ✅
 2026-09-13 14:25:44 +08:00
JianFeeeee
49ec22f916 fix(pi): 等人点头的 worker 不再占并发额度，也不会被硬超时杀掉 
实测（今天全 Agent 演练时撞到的）：pi 的 `maxWorkers=3` 被**三个正在等人工授权**的
worker 吃满，于是新邮件只能排队 —— 而人可能十分钟后才看邮箱。清掉卡住的请求后队列
立即排空，机制本身没错，错的是"等待"被当成了"在干活"。

两处改动（`src/pool.mjs`）：

1. **等待期间让出并发额度**。worker 发 `permission_pending` 时把它的 entry 标为
   parked，`pump()` 只数"在干活"的（`activeCount()`）。停放另有上限 `maxParked`
   （默认 5，防止内存无界：每 worker 约 140MB）；超出后仍占额度并打日志说明。
   决策到达（`routePermission`）时解除停放，回到额度里。

2. **等待期间暂停硬超时**。硬超时的用途是回收**卡死**的进程，而等人点头不是卡死：
   停放时清掉计时器，决策到达后重新起一个完整窗口。否则 worker 会在人还在读邮件时
   被 SIGKILL —— 那次工具调用直接消失，人后来批了也没人接（这类"批了没反应"的现象
   与此吻合）。

判据（`test/pool.test.mjs` 新增 3 条）：
  · ★ 等待授权的 worker 让出额度：另一个会话的邮件必须能开跑
  · ★ 等人点头期间（800ms > 300ms 硬超时）不得被强杀，且恢复后能跑完
  · 停放有上限：超出后仍占额度（不无限超发）
**扰动验证**：整块回退到 HEAD → 3 条全红；修复后 3/3。全量 pi 套件 420/420。

已部署（快照 20260913-131216，桥重启并重新心跳）。
 2026-09-13 13:14:56 +08:00
JianFeeeee
35f71d5144 test(webui): 全流程演练的两处判据修正（同主题请求的定位、工作区目录） 
第三次跑通 **37/37（0 失败 0 无法判定）**，含真 Agent 闭环：写信带附件 →
pi 请求 bash 授权 → **在界面点同意** → 决策落库 → pi 回信把附件原样带回
（sha256 一致）→ 回信出现在收件箱。

两处都是**判据/前置条件**的问题，不是产品缺陷，但都会伪装成产品故障：

1. 授权页上同一 Agent 的请求主题**一模一样**（"是否允许执行 bash？"）。原先按主题
   `.first()` 选行，于是点到了**别的会话那条旧请求**上 —— 网关回 `expired` 警告，
   界面看起来"点了但没生效"。现在按**本轮会话别名**定位分组容器
   （`header.locator('xpath=..')`，DOM 探针确认头与请求行同容器），且**只在折叠时**
   才点头按钮（已展开时再点会把它折起来，那正是第二次又落到别人行上的原因）。

2. **工作区寻址里的 path 必须是已存在的目录**，否则桥按设计回退到自己的兜底目录
   （`~/.pi/mail-sessions/<会话>`），产物就落在别处而不是我指定的目录。脚本现在
   先 mkdir —— zcode 那次也栽在同一条规则上。

顺带记录一个**产品层面值得决策**的现象：pi 的 worker 池上限是 3，而**"等人点头"的
worker 占着池子**。我上一轮的误点让 3 个 worker 全卡在等决策上 → 池满 → 新邮件排队
（设计如此：满载排队不丢信），于是我 300s 等不到回信。清掉卡住的请求后队列**立即
排空**、排队那封信被取出并起了一轮。也就是说：人在开会时，同一个 Agent 接不了新活。
是否把等待授权的 worker 挪出池子（或单独给额度），需要你定。
 2026-09-13 12:06:40 +08:00
JianFeeeee
2922fb711f fix(deploy): 故障通知的三处缺陷 —— 死信目录、隔夜补投、失败无原因 
起因：用户邮箱里「[dsh] 桥服务异常终止」反复出现。查下来有两层。

**第一层：崩溃本身（已修，是历史）**
dsh 在 2026-09-12 11:40 起崩溃循环，根因是当时那次插件快照切换后
`/root/.dsh/profiles/web/node_modules/dsh-mail-bridge/cordis.patch.yml` 不存在
（`failed to read overlay … ENOENT`）→ 起不来 → systemd 反复重启。
现在快照里该文件在、dsh `NRestarts=0`、今天 0 次失败。

**第二层：通知管线本身坏了（本次修）**

1. ★ **死信目录**：`zcode.service`（应用单元）既没有 `AGENTMAIL_AGENT_NAME` 也没有
   密钥，报告就落进 `unknown-agent/` —— 而 flush **只读自己那个 Agent 的目录**，
   于是 25 份 zcode 崩溃告警永久投不出去。修法是两件事：
   · `resolveIdentity()`：身份按「单元 env → 单元名推导 → /etc/agentmail/<agent>.env」
     解析；`zcode.service`→zcode、`pi-mail-bridge.service`→pi……
   · 支持 `AGENTMAIL_AGENT_SECRET`：zcode 只配了 secret 没有 key，而脚本原先只认
     Bearer key ⇒ 就算目录对了也发不出去（网关的 AgentAuth 两种都认）。

2. ★ **隔夜补投**：补投原先只在**同一个单元**的下次 `ExecStartPost` 跑，于是
   网关不可达时攒下的报告要等到那个服务自己重启才补投 —— 实测 4 封 Sep-12 的
   告警在 Sep-13 10:35 才到。现在新增 `agentmail-failure-flush.timer`（每 10 分钟
   `--flush-all`），它遍历所有 Agent 目录、按目录名逐个解析身份后补投。
   过时报告还会在主题与正文上标 **「补投：这是 N 分钟前的故障报告，不代表现在仍在
   故障」**（原先正文里只有昨天的时间戳，读起来像刚崩）。

3. **补投失败只报数不报因**：`catch { failed++ }` → 日志只有 `spool: sent=0 failed=4`，
   没人知道卡在哪。现在每条失败都带回原因（HTTP 状态码/网关不可达/身份未配置）。

4. 顺带两处准确性问题：
   · 主题写**单元名**而不是笼统的「桥服务」—— 25 封标题写着"桥服务异常终止"，
     实际崩的是 zcode **应用**单元，照标题去查桥方向就错了。
   · `created_at_ms` 是我们的元数据，但 `/mail/send` 是**严格解码**的（实测 400
     不认识的字段）→ 发送前剥离，线格式保持干净。

判据：新增 `deploy/service-failure-notify.test.mjs`（12 条，含假网关做真实投递、
严格解码断言、补投标记的正反两向）。端到端验证：模拟"没有身份的 zcode.service
崩溃"——修复前落 `unknown-agent/` 永久死信；现在**真的投出去了**，且
`from_name=zcode`、主题 `[zcode] zcode.service 异常终止 #…`。

积压清理：27 份（dsh 2 + unknown-agent 25）全部来自 09-12 那两轮崩溃、事件已在
邮箱与 journal 里出现过，按**不再补投**处理（避免把隔夜告警灌进邮箱），
原始文件留档 /root/gotmp/failure-spool-backlog-20260913.tar.gz（600），
spool 目录留 README.md 说明。
 2026-09-13 11:06:01 +08:00
JianFeeeee
77699e216b fix(webui): 新到的授权请求藏在折叠分组里 —— 徽标动了，内容看不见 
用户报告："我点到授权界面，才更新显示授权请求"。

先排除了推送本身：实测徽标是**实时**更新的（gui-lab 授权 7→8、jianf 1→2，
都没导航）。问题在内容：`PermissionList` 的展开状态
`const openSet = expanded ?? new Set(autoOpen)` —— 一旦手动点过一次，
`expanded` 就冻结成"点的那一刻"的快照，此后新到的待决请求落在一个折叠的分组里：
徽标数字变了，正文却看不见，直到离开再回到授权页（组件重挂载、`expanded`
回到 null、默认展开重算）才出现。

这违反代码自己的设计意图（注释写着「有待决策请求的会话默认展开：那些是在等人
动手的，藏起来等于没解决问题」）。

修法：加一条**状态迁移**判据 —— 新出现的待决邮件（`sessionId:mailId`）让它所在
的会话自动展开。用 mail_id 而不是"会话有没有待决"作判据，是因为实测撞到的正是
"会话早就有待决、用户把它折叠了，之后又来了一条"；而用户在那之后再手动折叠同一
条不会被弹开（没有新 mail_id）。

验证：
  · 真浏览器复现：授权 2 → 3 而新请求正文不可见，重进页面才可见（复现成功）
  · 新增 `test/components/PermissionList-autopen.test.tsx`（3 条，含反向对照）
  · 扰动验证：撤掉修复 → 2 条目标判据红、对照判据仍绿；恢复 → 3/3
  · 部署后同一探针复验：折叠状态下新请求**立刻可见**，不再需要重进页面
  · 前端 239 测试全绿；桌面重打包与 WebUI 同源（index-jaRgHqX2.js）

顺带修掉一个**更严重的缺陷**（在做「用 zcode 写个网页」时被 agent 自己报出来的）：

  fix(plugins): zcode 的 read_mail 永远返回空正文

agent 回信原话：「read_mail 返回的正文是空的，收件箱预览在「点击计数…」处被截断」
—— 它因此只看到前两条要求，写出来的页面漏了第 3 条（生成时间）。

根因在 `lib/inbox-format.js` 的渲染端：

    const body = m?.body_preview || m?.body || '';
    lines.push(`内容: ${String(body).slice(0, bodyLimit)}`);

zcode 的 read_mail 用 `bodyLimit = 0` 表示"要全文"（HTTP 侧 `?body_limit=0`
也确实是这个语义，服务端返回了完整正文），但这里 `slice(0, 0)` 把正文渲染成
**空字符串** ⇒ 模型永远读不到全文，只能看收件箱里那段预览。

修法：`bodyLimit <= 0` 视为不截断；不截断时优先取 `body`（单封接口可能同时带
`body_preview`，那是短的那个）。四份副本逐字节同源（`check-shared-libs.sh`
通过），每个桥各加 2 条判据：0 = 不截断、不截断时优先全文。
扰动验证：退回旧写法 → 2 条红。

端到端验证：让 zcode 读全文并原样回报最后一行（一个随机标记）。
修复后它精确回出 `最后一行标记：ZTOKEN-2c7561fd` ✓ —— 修复前这不可能。

四家桥都已重新部署到新快照（pi/opencode/dsh/zcode），部署漂移检查：
「四个宿主都在跑当前代码」。测试基线：pi 417 / opencode 323 / dsh 372 / zcode 382。
 2026-09-13 10:39:26 +08:00
JianFeeeee
f243355bd4 test(webui): 全流程演练（真浏览器 + 真后端 + 真 Agent 闭环） 
test/manual/webui-full-flow.mjs —— 37 项判据，实测 37/37 全绿、0 失败
0 无法判定。覆盖：登录（含错密码负向对照）→ 收件箱 → 打开详情 → 写信带
附件 → **真 Agent 闭环**（Agent 请求 bash 授权 → 在界面批准 → 决策落库 →
Agent 继续 → 回信把附件原样带回，sha256 一致）→ 授权页 → 多账号添加/切换
→ 主题与背景（含自定义图片）刷新后保持 → 窄屏 → 全程无预期外 4xx/5xx。

判据要点（这轮踩过的坑都在里面）：
- 授权邮件**不在收件箱列表里**（MailList 明确把 permission_request 滤到
  「授权」导航项）——在收件箱里找它必然"找不到同意按钮"，看着像 UI 缺陷。
- 决策按钮必须用**精确文本**：`has-text("同意")` 会命中"已同意"/"一直同意"，
  `.first()` 可能点到别处，表现是"点了但库里没有任何决策"（像后端失灵）。
- 一次「同意」只放行**一条**命令，多步任务会一条接一条地问（实测 pi 连问
  两次）——所以脚本首次用「同意」、之后用「一直同意」，两种选项都验到。
- 未登录时前端要问一次 `/auth/me`，那时 401 是**正常回答**；登录之后再 401
  才是会话丢失。判据按时间点区分，而不是无条件放过这个端点。
- 故意用错密码造的 401 也要断言"确实产生了"，否则"被拒"那条可能是假绿。

顺带清掉本轮留下的测试数据：6 条待决权限决策为拒绝（剩 0），13 个测试会话
归档 12 个（余下 1 个属他人会话，服务端 403「无权归档他人的会话」——这是
对的，没绕过去）。
 2026-09-13 09:30:44 +08:00
JianFeeeee
5804ba4f63 fix(webui): 自定义背景完全不可用 —— 「图片」档进不去 
现象：点「图片」后背景反而被关掉，上传控件永远不出现 ⇒ 自定义图片在 UI 上
完全不可达（用户看到的正是"自定义背景不正常"）。

根因：`normalizeBackground` 把「kind=image 但还没有图片数据」折叠成 `none`
（这条判据本身是对的 —— 读盘时那确实是脏数据），但 store 的 `commit()` 每次
patch 都要过一遍它，于是 `setKind('image')` 这一瞬间就被折叠回去；而上传控件
只在 `kind === 'image'` 下渲染 ⇒ 鸡生蛋问题，用户永远走不到选文件那一步。

修法：给归一化加 `keepEmptyImage`。
  - 读盘（`readStored`）保持严格：空图片状态是脏数据，退回 none。
  - 交互（`commit`）保留瞬态：允许"已选图片档、还没挑文件"这个中间状态存在。
静止态的不变量没有放松，放松的只是正在选图的那一瞬间；`applyBackground` 对
空图片本来就不铺开（不会出现 `url("")`）。

判据（都验过"修复前会红"）：
  · 新增 `test/components/BackgroundPicker.test.tsx` —— 点「图片」后选文件控件
    必须出现、选完图背景必须亮、失败必须说原因、选「无」必须能关掉。
    **扰动验证**：把修复撤掉 → 组件 3 红 + store 1 红；恢复 → 22 全绿。
  · `test/stores/background.test.ts` 补 2 条：交互进入图片档要留住 /
    瞬态落盘后重读必须退回 none。

线上验证（真浏览器，部署后）：线上 bundle 换成 index-CSFGa8wa.js 后 ——
点「图片」→ `kind=image` 保持 → 上传 16KB 小图与 9MB 大图都成功
（大图压缩到 1790KB）→ 刷新后仍在 → 全程无页面错误。

顺带：应用内**从未出现**过品牌图标。`BrandMarkIcon` 只用在登录页与首启页
（都是登录前界面），登录后的日常界面里一处都没有。侧栏顶端加上品牌标记
（点它回收件箱）。favicon 那条链本来就是好的（3 个 link 都 200、类型正确、
图标内容正确），已在验证中确认。
 2026-09-13 08:55:55 +08:00