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

45 Commits

Author SHA1 Message Date
JianFeeeee
125aec1191 跨端: 2in1 键盘可达（Ctrl+N 写信 / ↑↓ 换补全 / Enter 选中）+ 三处判据被实测改判 
用户 2026-09-21：「接下来做一下 2in1 上的快捷键，比如快捷键打开发信页面」
「上下键切换发信目标」「回车展开输入框等」

## ① 打开发信页：Ctrl+N，用官方 `keyboardShortcut`

先查了官方文档再动手，避开两条静默失败的坑：

  · `keyboardShortcut`（组件快捷键事件，API 10+）「**无论组件是否获焦** ——
    只要窗口获焦，快捷键就会响应」。而 `onKeyEvent` 要求**组件先获焦**，
    邮件列表里焦点落在哪是不确定的（点一下就换）⇒ 用它做全局快捷键会时灵时不灵。
  · 「多个不同组件设置相同组合键 ⇒ 只响应节点树**深度最浅**的那个」。
    ⇒ 再给别处的"写信"按钮补一个 Ctrl+N 不是"多一个入口"，而是**让后来那处永久失效**。
    判据因此钉"全仓只许绑一处"。

绑定位置在 `MainPage` 的**根 Stack**（窗口组件树的根）—— 绑在 FAB 上不行，
它在 `if` 分支里、窄屏/宽屏位置也不同，会随分支挂卸。

键位 `Ctrl+N` 避开了官方列出的五个**禁止绑定**组合（Alt+F4/Alt+Tab/Ctrl+Shift+Esc…）。
判据直接解析调用参数校验这三点。

## ② 根够不着 `openCompose()` ⇒ 照 `PushService` 的"两半"形状

`openCompose()` 住在**条件挂载**的 `CommPage` 上（`if (currentIndex === 0)`），
根组件拿不到它。新建 `common/ComposeIntent.ets`：

  · **格子**（`pending`）—— 用户此刻在别的页、`CommPage` 还没实例化；
  · **回调**（`listener`）—— 用户此刻就在通信页、页面早挂载完了。

缺任何一半都是**按键静默失效**：只有格子 ⇒ `aboutToAppear` 不重跑；
只有回调 ⇒ 没有监听者。这形状与 `api/PushService.ets` 处理"点通知跳转"时
踩的是同一个坑，那边注释里已写过解法 —— 这次是照着抄，不是重新踩。

## ③ 收件人三段式补全（↑↓ 切换、Enter/Tab 选中、Esc 收起）

WebUI 的逻辑原先**散在组件闭包里**（`parseParts` 没 export、`apply`/`onKeyDown`
直接改 React state）⇒ 判据根本 import 不到。先把它抽成一对纯逻辑：
`client/electron/src/lib/addressSuggest.ts` ↔ `model/AddressSuggest.ts`，
**抽的时候行为一字不改**（抽出来顺手"改进"会让判据比新行为、线上跑旧行为，两边都错）。
`AddressInput.tsx` 改接这份 lib。

`cross-client-logic` 新增 `AddressSuggest` 一对，22 个用例两边逐例比。
其中 `nextActiveIndex(0,3,-1)` 是**负下标陷阱**：JS 的 `%` 对负数返回负数
（`-1 % 5 === -1`），而负下标在数组访问里**不报错**（返回 `undefined`），
只表现为"按上键后没有任何一项高亮"。直接写 `(i-1) % n` 就会这样静默坏掉。

候选走**内联渲染**而不是 `bindPopup`/`bindMenu`：那两者各有焦点体系，
会先吃掉按键 ⇒ "↑↓ 换候选"落不到 `onToKey` 上。

## ④ 另修一个真 bug：`AddressSuggestion` 字段名整套写错

模型声明 `value`/`kind`，而服务端（`contacts.go:206`）给的是 `alias`/`title`/`source`
—— **从来没返回过** `value`/`kind`。按本仓纪律「声明了服务端从不返回的字段 ⇒ 删掉声明」改正。

顺带守住 `title` 的 `omitempty`：缺键时裸 cast 给 `undefined`（**不是**类里那个 `= ''`），
直接读会 `Cannot read property of undefined` —— 本仓在 `MailDetail.normalize()` 上
踩过同一形状（整页白屏）。判据钉住那句 `typeof … === 'string'` 的守。

## ⑤ 三处判据被**实测**改判（不是我挑一边，是拿数字定的）

### a. 卡片不该有模糊 —— 反转原断言
原判据断言「玻璃卡要走参数化 `backgroundEffect`」。那是**记录旧实现的副作用**
（重言式）。逐字读 WebUI 的 CSS：全仓 `backdrop-filter` **只有两处**
（`.glass-control` 8px/1.1、`.narrow-nav` 18px/1.5），而 `.glass-card`（`index.css:1629`）
**完全没有** —— 它的玻璃感是 `rgb(255 255 255 / 0.92)` 这个 alpha。
留着旧断言更坏：下次谁把卡片改成正确的"白 + alpha"会被判红，然后去**把模糊加回来**。

### b. 我试了"把模糊移到导航条"，被实测否掉
推断「真归属是底栏」，于是把底栏改成 `backgroundEffect({radius:18, saturation:1.5})`。
实测（模拟器窄屏 1008×2232，底栏中心列 x=504）：

    y      backgroundEffect        backgroundBlurStyle
    1960   rgb(191,199,209)        rgb(234,235,239)      ← 差 -36 亮度
    2060   rgb(206,211,219)        rgb(234,235,239)      ← 差 -24

⇒ `backgroundEffect` **只给模糊、不给底色**，壁纸原样透上来，底栏暗了 24~36 级。
WebUI 的 `.narrow-nav` 是**两条声明**组合的（`background-color` + `backdrop-filter`），
我只搬了后者。系统材质**同时含色调 + 模糊 + 深浅两套** ⇒ 在这里它才是正解
（§7.12 把它判成"有意差异"是对的，我的"改进"是退步）。
判据改成**反向钉住** `backgroundEffect`，并把这段实测数字留在 Theme.ets 里。

### c. 页签条判据记录的是被否掉的"胶囊"
原判据钉 `TAB_BAR_RADIUS`/`TAB_BAR_SIDE`/`TAB_BAR_TOP` —— 那正是用户否掉的形状
（「你又在内部套了一个胶囊」）。CDP 读 WebUI 的实测几何：

    .comm-pane   x=80 w=320 radius=14px overflow=hidden   ← 窗格，裁圆的是它
    tabstrip     x=80 w=320 radius=0px                    ← 条自己无圆角

设备实测（`uitest dumpLayout`）：页签条 `[28,140][980,267]`、窗格 `[28,140][980,1957]`
⇒ 左右边缘逐像素相同。判据改为钉"与窗格齐平 + 只有左上角圆角"这两条**不变式**，
`TAB_BAR_RADIUS`/`TAB_BAR_SIDE` 一并**删除**（留着就是孤儿，会邀请人把胶囊拼回来）。

## ⑥ 顺带修两条判据自己的正则
`{6}` 看不见 8 位色 ⇒ 把 `glassCard`/`glassCardWall` 报成"清册过期"，
**病因报错了**。改成 `{6}(?:[0-9A-Fa-f]{2})?`（不能写 `{6,8}`，那会连 7 位也放进来）。
半透明禁令改为**枚举白名单**（不是放宽：遮罩那个真实约束原样保留，
`overlay` 写成 8 位单色照样红）。

新增判据 `harmony-2in1.test.mjs` 12 条；`files=34 checks=543 pass=540 fail=2`（收尾前）。
 2026-09-21 13:29:24 +08:00
JianFeeeee
99a2d7ad7e fix(webui): 深色模式真的落地了 —— 之前 .dark 是「有意留空」的 
用户报「深色模式可读性差」。实测（1280×800，读页面计算值）拿到两个数字：
  · .glass-card 合成成 rgb(237,237,237) 白卡，而其上 --c-gray-900 文字是
    rgb(243,245,248) ⇒ **1.07:1 的白底白字**
  · .nav-rail 合成成 rgb(188,189,190) 浅灰条，未选中文字只有 4.03:1

根因写在 index.css 自己的注释里：`.dark { /* 有意留空 */ }`。当年留空的理由
是「组件没有 dark: 变体，只换令牌会半深不浅」——**方向反了**：组件写的是语义
色阶（bg-white / text-gray-900），灰阶反转后本来就会自适应；真正没适配的是
**手写 CSS 里那几处硬编码白色**（.glass-card 的 0.92、--nav-bg 令牌），
它们不在 --c-* 色板里，所以「色板变量已全覆盖」的判据一直是绿的。

改动：
1. .glass-card / .nav-* 全部改走令牌，主题之间只差 alpha；
   深色给 --glass-card-a: 0.06 + --nav-bg: 30 35 44/0.72。
   遵守既有契约（background.test「玻璃是白色材料」）：**基材恒为白**，
   只降 alpha，绝不换成深色层。
2. CalendarView 的非本月农历小字 text-gray-300 → gray-400/500。
   gray-300 在这套调色板里是**分隔线档**（全仓 68 处 border-gray-300、
   当文字只有 5 处），深色下它是 61,68,81，落在深卡上 1.49:1；
   而 gray-400 在深色 4.66:1、浅色白卡 2.54:1，两端都更好。
3. 判据：theme.test 补 3 条（手写 CSS 不许有绕过主题的硬编码白色表面 /
   深色卡片 alpha 必须降低 / **按实际 alpha 合成后**正文须 ≥4.5:1，
   即把 1.07:1 那个事故写成可计算的断言）。background.test 那条
   「.dark 里不许出现 --nav-*」**方向反转**为「必须有且底暗字亮」——
   它原来守的是「还没有深色主题」这个前提，其注释本就写明
   「真做深色主题时这条要一起改」。

验证（不是"改了就算"）：
· 自建探针遍历 **9 个页面**（三个通信子页签 / 邮件详情 / 日历 / 联系人 /
  我的 / 写信 / 地址补全弹层）：修复前通信 14 处、日历 74 处、
  联系人 13 处低于 WCAG AA；修复后 **9/9 页面 0 处**。
· 三条新判据逐条**变异自检**（还原修复即变红，且失败信息自带药方）；
  浅色三个取色值与改动前**逐字节一致**（导航 0.72 白玻璃、卡片 0.92 白）⇒ 零回归。
· theme.test 34 通过 / background.test 44 通过 / tsc 干净。
· 已按 deploy/redeploy-gateway.sh 部署到 systemd 实例，后置清单自动项全绿，
  并在生产实例上复量 9 个页面（同为 0 处）+ 端到端发信（状态 read，非仅入库）。

#深色模式 #可读性 #WCAG
 2026-09-17 22:32:25 +08:00
JianFeeeee
d81ab319e4 fix(webui): 动画全量盘点 —— 两处死动画 + 一处过宽；并把盘点变成常驻判据 
用户：「全面检查整体的动画」。查出来的不是"好不好看"，而是**接线断了**（三种形态都很难靠肉眼发现）：

① @keyframes pane-in **定义了两处**、挂在 `html.view-switch .pane-enter` 上，而 `.pane-enter`
   **没有任何组件在穿** ⇒ 规则看着像"页面有入场动画"，一次都不会播（9aa702b 删整面板入场时的遗留）。
   已连规则与 keyframes 一起删干净（注释里我把"连它一起删"写了却没做，被新判据当场抓到）。
② `.animate-menu-in`（菜单入场）keyframes 与规则都写好了，**同样没人穿** ⇒ 所有下拉/候选菜单
   其实是"啪"地出现。已接到 AddressInput 的候选菜单上；线上实测捕捉到 menu-in @140ms。
③ `html.view-switch .glass-control` 把"菜单入场"错当成"控件档入场" ⇒ 每次切视图，页面上
   **所有**按钮与输入框一起淡入位移（几十个元素同时动，闪与卡顿的现成来源）。已收窄为
   只给 `.animate-menu-in`；线上实测切视图只剩 pane-rise + 导航项的颜色过渡。

判据化：新增 test/animation-audit.test.mjs —— 每个 @keyframes 都必须有人穿（死动画闸门）、
弹层必须带菜单入场类、不得再出现"整档控件一起动"的切视图规则、reduced-motion 必须显式
覆盖挂载即播那档。写判据的过程本身抓到两处我自己的不一致：删了规则却留下孤儿 keyframes；
以及正则把 reduced-motion 名单里的 `html.view-switch .glass-control` 误判成"还在让它动"
（已改为只扫顶层规则，媒体查询块里的"关掉名单"不算）。
 2026-09-15 08:51:18 +08:00
JianFeeeee
f5d05755b7 fix(webui): 窄屏两处 —— 收起补反向 morph、编辑态不再隐藏底部导航 
用户：「收起没有动画，且输入框弹出后，底部导航栏会消失，再次点击界面导航才会出现」

① 收起没动画：打开有 morph、收起是瞬间卸载（不对称）。补反向 morph：
   打开时把球的矩形存进 originRef（球在框打开时不在 DOM 上，收起草稿时取不到），
   收起时从当前形状缩回球的位置/大小（160ms），**播完再卸载**（先卸载就没得播）。
   finished 被取消时也会 reject，两种情况都落到"收起"。

② 底部导航消失：测量结果是 nav 的 rect = 0,0,0,0，即 **display:none**，不是被挤出去——
   根因是 `.form-editing .narrow-nav { display: none }` 撞上"回复框展开即自动聚焦 textarea"
   （form-editing 由 main.tsx 在任何输入框获焦时挂上）⇒ 一弹框导航就消失，点到别处才回来。
   而这条隐藏已经没必要：viewport 声明了 `interactive-widget=resizes-content`，键盘弹出时
   浏览器会重排布局，导航自然落在键盘上方。已删掉该隐藏。
   顺带：详情/列表两个窄屏根节点补 min-h-0（flex 子项默认不可压缩，回复框一撑会把导航顶出可视区）。

判据 +4（编辑态不隐藏导航、viewport 声明 resizes-content、两个根节点带 min-h-0、收起有反向
morph 且先播完再卸载）。变异：抽掉 min-h-0 → 红；收起改回瞬间卸载 → 红；把 display:none
放回去 → 红。
★ 一处判据自身的坑：判断"还有没有那条隐藏规则"必须用**剥注释版**——我第一版用原文判，
被我刚写的那段解释性注释（里面原样引用了那条规则）判红，与 read.mjs 里记的同一形态。

窄屏（420x820，真实邮件）实测：初始/开信/回复框弹出并聚焦(form-editing)/收起后 ——
底部导航高度都是 51px 且在视口内；收起时框上有 160ms 动画。
 2026-09-15 08:45:54 +08:00
JianFeeeee
110d457535 fix(webui): 回复球改成容器变形 + 摘掉邮件列表的入场动画 + 全局控件过渡不再补间阴影 
用户连着报了三件（2026-09-15）：

① 「邮件页面那个蓝色的圆形是聊天图标点击没有任何动画」
   上一版我只给了回复框一个 150ms 的 opacity 淡入 —— 观感上等于没有。用户要的形态与
   写信页一致：**球自己长成回复框**。现在蓝球带 data-morph-trigger、onClick 里就地记下
   自己的矩形（currentTarget 最准），回复框挂载时用 useLayoutEffect 在**首帧之前**把
   CSS 淡入关掉并接上 morph（220ms，只动 transform/opacity/border-radius）。

② 「邮件列表会闪」——**我上一版引入的回归**。
   我把 pane-rise 挂到了邮件列表上，而 view-switch 窗口在**选中一封邮件**时也会触发
   （narrowPane 是依赖之一）⇒ 每点一封信整个列表重放一次入场。已摘掉：列表这类
   "选中即变"的面不许挂入场动画，只有日历（真的换视图）保留 pane-rise。
   判据改成反向的"列表必须不动"，把这个回归钉死。

③ 「主页点击按钮有明显的卡顿」。
   全局 `button,a,input,textarea,select,[role=button]` 的 transition 里带了一条
   `box-shadow var(--dur-base)` —— 阴影是**绘制**属性，每次 hover/active 都要把元素
   连同阴影覆盖区重绘，且它挂在所有交互元素上。已去掉该补间（阴影瞬切），
   判据钉"全局控件过渡不得含 box-shadow"，个别表面仍可自己写。

另补一个真缺口：prefers-reduced-motion 原先只覆盖"窗口触发"那档，**没覆盖"挂载即播"
那档（裸 .rise-in）**，两处 morph 也没走这个开关。现已全部纳入；判据加严到"必须行首
就是 .rise-in"（第一版被 `html.view-switch .rise-in,` 满足掉，变异测试才发现假绿）。

判据合计 84 通过 0 失败（变异都验过：删裸 .rise-in → 红；把 box-shadow 加回 → 红；
列表挂回 pane-rise → 红；useLayoutEffect 换回 useEffect → 红）。
 2026-09-15 08:15:22 +08:00
JianFeeeee
436de6ee4d feat(webui): 回复/转发动画真的会播了 + 写邮件改成「按钮长成整页」 
用户两问：
  ① 「回复邮件那个按钮还是没有动画」——**我上一版的锅**：我只给回复框/转发面板挂了
     `rise-in`，但那条规则写作 `html.view-switch .rise-in`，而 view-switch 窗口只由
     视图/页签/窄屏/写信 四个状态触发。**回复/转发根本不触发它** ⇒ 类挂着、动画永远不播。
     我当时的"验证"只覆盖了写信页（恰好命中四个触发之一），另外两处只验了类在不在。
  ② 「写邮件的按钮点击不应该是一个按钮扩大变成页面的动画吗？」——是，这才是对的形态。

改法：
- 拆两档作用域：`.rise-in` **挂载即播**（给"点了才出现"的面：写信页/回复框/转发面板），
  `.pane-rise` 由 `html.view-switch` 窗口触发（给常驻面板：列表栏/日历）。
  首屏不会有一堆东西同时淡入，因为前者只在用户动作时挂载。
- 新增 lib/composeOrigin.ts：在**捕获阶段**记录被点元素的矩形（React 的 onClick 在冒泡
  阶段，晚一步就取不到），带 2s 时效（防止"点了别的按钮 → 稍后被程序化打开写信页"时
  从旧按钮长出来）；优先认 `data-compose-trigger`，退一步认最近的 button，
  这样 4 个入口不必逐个改（漏一个的后果是静默无动画，与 ① 同一种失败）。
- ComposePage：有起点就 el.animate 从那个矩形长成整页（220ms，只动
  transform/opacity/border-radius —— 合成器可做，不动宽高），没起点退回 rise-in。
  两条动画都动 transform/opacity，所以渲染期就决定挂哪一条，不同时挂。

判据（narrow-layout +6）：rise-in 必须不带 view-switch 前缀、常驻面板必须用 pane-rise
且 window 规则在、reduced-motion 覆盖两档、morph 只动合成器属性、有起点 morph /
无起点 rise-in。生产实测：点悬浮球后 document.getAnimations() 里 ComposePage 根节点上
有 running 的 220ms 动画，首帧 translate(-564px,396px) scale(0.0549)、opacity 0.3
（悬浮球 56px ⇒ scale≈0.055）。回复框/转发面板因该账号收件箱为空未点穿，但触发条件
已从我写错的"窗口触发"改成"挂载即播"。
 2026-09-15 08:09:36 +08:00
JianFeeeee
e3b7f8f421 perf(webui): 动画卡顿三处治理 + 覆盖列表/日历 
用户：「动画卡顿严重，且绝大部分场景还是没有流畅的动画」。

① 提层：`html.view-switch .rise-in` 里加 will-change: transform, opacity。
   这一档只动 opacity+transform，但没提层时浏览器不保证合成器接管。
   写在 view-switch 窗口里（只在切换的 ~400ms 内有效），不是写在元素上 ——
   常驻 will-change 会把每个面板都变成常驻图层，白吃内存。

② 去掉触发动画时那次强制同步重排：App.tsx 原来用 `void root.offsetWidth`
   让 remove/add 分属两帧，代价是每次切视图都逼浏览器把整个文档布局算一遍，
   而这笔账正好落在动画第一帧上。改成两次 rAF，同样分两帧，不付重排的钱。

③ 覆盖：列表栏与日历根节点也穿 rise-in ⇒ 切 通信/日历/工作列表 都有入场，
   仍只动"新出现的那一块"，骨架不动（避免 09-14 那次"整屏闪"的老问题）。

判据（narrow-layout +3）：will-change 必须在 view-switch 规则里；
   App.tsx 不得再有 `void root.offsetWidth`（且必须用 requestAnimationFrame）；
   MailList/CalendarView 必须穿 rise-in。变异：抽掉 will-change → 红；
   把强制重排放回去 → 红；复原 → 77 通过 0 失败。

★ 顺带纠错：上一轮我报"整页 146 个元素带 backdrop-filter / 动画子树 76 个全带模糊"
   是我探针自己的 bug（`webkitBackdropFilter` 取到 undefined，`undefined !== 'none'` 恒真，
   连 <path>/<META> 都被算进去）。修正后实测：真模糊 0 个、同时动画 1 个、
   帧间隔中位/最长 17ms（60fps）。所以"卡顿"不是我能在本机复现的形态 ——
   需要知道你看的是哪一端/什么状态（见回信）。
 2026-09-15 07:57:04 +08:00
JianFeeeee
6ee58fa28a fix(webui): 局部入场动画补回（写信页/回复框/转发面板）—— 你猜对了，是被整条删掉的 
用户（2026-09-15）：「从发信按钮到发信页面，从聊天按钮到聊天输入，以及转发拉起输入框
都没有对应的动画，所有的动画都消失了，是不是我批评一下用力过猛你就全给删了」

是。9aa702b（09-14，回应「部分动画十分不合理，会导致页面大范围的闪动」）把
 整条删掉、换成 ，
而 **.pane-enter 没有任何组件在穿**（grep 确认）⇒ 这一档从「全部一起动」变成
「一条都不动」，连这三处局部、有明确语义的入场也一起没了。

批评针对的是**整面板/整屏**一起淡入（骨架跟着暗 = 闪），不是局部入场。所以补回
只动「刚出现的那一块」：@keyframes rise-in（4px + 不缩放，150ms，与 pane-in/menu-in
同一套尺子），仍挂在 view-switch 触发窗口上，骨架一动不动。

判据（narrow-layout 新增 3 条）：keyframes+规则存在、三处目标面都穿（MailView 里
回复框与转发面板各一处）、且 reduced-motion 块里也有它。变异：去掉转发面板那处 → 红；
从 reduced-motion 里删掉 → 红；复原 → 74 通过 0 失败。（第一版取错了 reduced-motion
块——文件里有多个，取到全局那个，判据自己假红，已改成逐块检查。）

生产实测（8180，点「新建邮件」后 90ms 读计算样式）：animationName=rise-in、0.15s、
cubic-bezier(.22,.61,.36,1)，此时 html 正带 view-switch。
 2026-09-15 07:49:25 +08:00
JianFeeeee
e6048e9914 fix(webui): 候选菜单改用不透明弹层表面 —— 半透明+背景模糊把背后的表单糊进了列表 
用户（2026-09-15，看着抄送/转发两处的候选）：「你在选择框的模糊逻辑上用力过猛，
导致只能显示一条信息」。

实测（生产构建 4c2bf26，浏览器里读计算样式，壁纸开）：
  菜单 background: rgba(255,255,255,0.5) + backdrop-filter: blur(8px) saturate(1.1)
  而它浮在**表单自己**之上（主题输入框 y=294 正落在菜单 284-510 下面）
⇒ 背后的输入框/标签被糊一遍再从半透明列表底下透上来，只有顶行还读得清。

根因与 2026-09-14 那次「模糊叠模糊」同族：把**控件档**（0.5 透 + 8px 模糊）用在
**弹层**上。控件背后是面板自身，透一点好看；弹层背后是别的内容，透就是叠两份内容。

- 新增 .popup-surface（rgb(var(--c-white))，不取 backdrop-filter；壁纸开时单独压回不透明，
  否则会撞上 html[data-bg='on'] .bg-white 那条接管规则）
- .popup-surface 并入「滚动区不淡」豁免（原来只认 .glass-control，换类会漏掉 → 弹层又被洗白）
- AddressInput 菜单 glass-control → popup-surface；旧断言 nav-merge.test.mjs:109 钉的正是
  那个错的意图（『地址建议菜单』必须用控件档），已改钉新意图

判据：narrow-layout 新增 4 条（表面不透明/不取模糊/壁纸开时也压回/菜单穿的类）+
nav-merge 反向对照。两侧都验：变异①换回 glass-control → 红；变异②改回 0.5 → 红；
复原 → 71 通过 0 失败。生产实测：rgba(...,0.5)+blur → rgb(255,255,255)+无模糊。
 2026-09-15 07:46:54 +08:00
pi
59b2575838 fix(webui): 底部导航选中态只换颜色（去掉背景块与顶部指示条） 
用户：「同时底部导航栏选中对应的文字和图标变色即可」。

- NarrowNav：删掉 bg-blue-400 顶部指示条
- index.css：.narrow-nav .nav-item[data-active='true'] 背景置 transparent——
  只作用在底部导航；宽屏侧栏是 48px 竖条、没有文字标签，那块底色是它唯一的选中线索
- 图标本就是 stroke=currentColor，所以跟着文字色走（判据钉住这一点）
- 判据 nav-merge ④ + 变异自检：把 bg-blue-400 加回去，④ 立刻红
 2026-09-14 17:50:34 +08:00
JianFeeeee
6702cc2f5e fix(webui): 窄屏日历/详情的圆角——圆角要给到「能裁剪的那一层」 
用户（2026-09-14）：「我这边看还是方角」。上一轮我只修了宽屏那条分支，
窄屏（手机/平板，<1024px）当时仍然是方角 —— 这次按像素量到了。

## 实测（真浏览器读渲染像素，不是读声明）

390x844 日历页左上角：
  改前 (255,255,255) 纯白 → 方角；面板 computed radius = 0px
  改后 (249,250,251) 页面底色 → 圆角；上边缘内缩 8px

## 根因：圆角落在**裁不住东西**的那层上

窄屏走 NarrowStack（`list`+`main` 的覆盖式容器，日历与收件箱详情都用它）：

    .narrow-shell > *          ← 14px 加在这里（App.tsx 的 flex-1 min-h-0 flex）
      NarrowStack 根            ← overflow:hidden，但 radius 0px
        absolute inset-0 flex   ← 透明
          gridPane (bg-white)   ← 0px，直角原样露出来

`overflow: visible` 的透明 flex 容器拿到圆角 = 什么也没发生。
NarrowStack 的根节点是**唯一**同时具备「自己 overflow:hidden」与「包住有底色那一层」
的层，圆角必须加在它上面 —— 加给它，底层页与滑入的覆盖层就一起被裁到圆角里。

顺带修好一处同类问题：**收件箱详情在窄屏也是方角**（同一个容器），
以前没人报过，这次一起圆了（实测同上）。

## 判据

narrow-layout 新增 2 条，分开钉两件事（分开一条都不算修好）：
  ① 那层自己带上面板圆角（类名与 CSS 规则接得上）；
  ② 那一层同时具备裁剪能力（overflow:hidden）。
三组变异全部红在对的那条上（去掉类名 / 去掉 border-radius / 去掉 overflow-hidden）。

narrow-verify（手动探针）新增**读像素**的能力与两条判据 —— 这件事只有像素能回答：
computed radius 是 14px、角上 2px 处"谁在画"也指着面板本身，**但渲染出来仍是方的**
（圆角加在没底色的层上，被内层直角原地盖掉）。所以这里截 1x1 再解 PNG，
只用 zlib，不引图像库。方角=255,255,255 / 圆角=249,250,251，两个数字就能分辨。
 2026-09-14 16:51:31 +08:00
JianFeeeee
d78f19fe9a fix(webui): 日历页面补上圆角（圆角要给到「有底色的那一层」） 
用户（2026-09-14）：「日历页面还没有添加圆角」。

根因不是「忘了写 border-radius」—— 外壳那条 `.app-shell > *` 是生效的，
它给日历**根节点**加了 14px 圆角。问题是根节点写着
`flex-1 min-w-0 flex min-h-0`、**自己完全没有底色**：
真正白底的是里面那两块面板（网格栏、右栏），它们的直角从透明外壳里戳出来。
所以 `getComputedStyle(根).borderRadius` 一直是 14px，看上去却全是方角。

两处不能照搬收件箱做法的地方：

① 网格栏与右栏**不是两张卡**（中间只有 1px 分隔线，没有外壳间距）
   ⇒ 只能给**外沿**：左边那块给左两角、右边那块给右两角。
   内侧也给会露出底色缺口。
② 右栏外面还套了一层容器（管 `lg:w-[400px]` 与 `border-l`，自己不上色），
   真正上色的是它里面的 DayAgendaPane / CalendarEventEditor
   ⇒ 圆角要**再往下给一层**，只加在容器上会被内层直角原地盖掉。
   （左栏本身就是白底面板，不能再往下给：它的第一个子元素是工具条。）

实测（1280×800，真浏览器读渲染像素）：
  改前 左栏 radius=0px、右栏 radius=0px，四个外角都是白像素（方角）
  改后 左栏 `14px 0px 0px 14px`、右栏内层 `0px 14px 14px 0px`，
       四个外角像素都等于页面底色（被切掉）；上边缘内缩 8px，
       与收件箱详情栏（对照）完全一致；内侧分隔线两侧保持直角。

判据：narrow-layout 新增 4 条 —— 钉的是「规则与 JSX 接没接上」「给的是哪几条边」
「右栏有没有再往下给一层」「左栏有没有多给一层」，不是那条 14px。
wide-regression 新增一条**渲染层**判据：从 `elementFromPoint` 沿祖先链找第一个
自带底色的元素，四个外角都必须正是那个圆角面板（光看 computed style 区分不了，
因为被盖掉的形态 computed 也照样是 14px）。

顺手修掉 wide-regression 里一条**假失败**：`#root > div` 现在指向壁纸幕布
（`app-backdrop` 后来挂成了 `#root` 的第一个子节点），于是「仍是三栏并排」
一直报「栏数=0」，而三栏好好的。假失败比没有判据更贵 —— 看的人会去查一个
本来没坏的东西。
 2026-09-14 16:05:15 +08:00
JianFeeeee
7ef3ea7306 fix(webui): 宽屏也同步折叠策略 —— 头部与回复框默认收起（正文 48% → 90%） 
用户（2026-09-14）：「我发现宽屏布局也有邮件内容显示区域过小的问题，
宽屏也同步窄屏的折叠策略吧」。

上一版是「窄屏默认收起 / 宽屏恒展开」，理由是「宽屏横向空间够、不该引入多余
点击」。那条理由只看了**横向**：实测 1280x800 下详情栏里头部 139px(17%)、
回复框 246px(31%)，留给正文的只剩 385px（48%）—— 竖向一样不够用。

改法：两种宽度用同一套默认值（收起），点标题行 / 悬浮球展开。
- CollapsibleHeader：useState(false)，toggle 不再以 narrow 为条件，展开箭头常显；
- ReplyBar：收起态恒为悬浮球（原来只有窄屏才收），「收起」按钮宽窄都有，
  autoFocus 不再以 narrow 为条件；
- MailView 两个根节点补 relative —— 否则宽屏下 `absolute` 会一路找到视口，
  悬浮球会挂到窗口右下角而不是这块详情栏里。

实测（真浏览器量盒子，1280x800，同一封正文撑满的长信）：
  头部 139 → 48px，回复框 246 → 0（收起为球），正文 385 → 722px（占视口 48% → 90%）；
  点标题展开 / 点球开输入框（带焦点）/「收起」收回，三条都通。
窄屏 390x844 同项通过，横向溢出 0。

判据：narrow-layout 里三条旧判据钉的是「窄屏专属」，已改成钉「宽窄同一套」，
并新增两条（折叠分支里不得再有 `narrow &&`；悬浮球必须锚在详情栏内）。
wide-regression 补 6 条宽屏实测 —— 此前宽屏的折叠行为**一条判据都没有**，
这正是它坏掉而没人发现的原因。

已知遗留（另行报告，本次未改）：窄屏上回复框展开后，第一次点它上面的按钮
（抄送 / 回复全部 / 收起）会被吞掉 —— 焦点离开 textarea 会让 .form-editing
失效、底部导航重新占位 71px，按钮在 mousedown 与 mouseup 之间从指针下移走，
click 目标退化成公共祖先。HEAD 上已存在，与本次改动无关。
 2026-09-14 15:38:49 +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
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
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
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
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
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
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
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
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
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
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
JianFeeeee
addde97600 feat(electron): 多账号第一纵切 —— 账号存储/选择器/聚合收件箱 
按 docs/MULTI-ACCOUNT-PLAN.md 实现客户端多账号的前半段（SSE 多连接与
写信账号切换留作下一轮）。

- `src/lib/accounts.ts`：纯逻辑（地址规范化、身份判重、默认账号、聚合合并），
  16 条测试钉住每条判据（含反向对照）。
- 持久化在主进程：`userData/accounts.json`，**原子写**（临时文件 + rename）+
  0600。不落 localStorage：那份存储渲染层任何脚本都可读，且 file:// 与
  http:// 是两套。无 IPC 时（浏览器）退到 localStorage 并在界面**如实写明**。
- 取信：单账号走原路径（逐字节不变）；聚合时**每账号各一次请求、各带自己的
  令牌**（`fetchWithAuth`，不碰认证单例，避免并发串号）。
- ★ 只合并**同一网关**的账号：跨网关的邮件混进列表后点开会去问当前账号的
  服务器（404，或 mail_id 撞上就打开了别人的信）。如实排除 + 列表上方说明。
- ★ 部分失败可见：某账号取不到时给出账号名与原因 —— 静默丢掉它会让聚合列表
  少一整份邮件而界面看起来完全正常。
- `API_BASE` 改为 `let`（切换账号要换网关），api 层不得缓存它
  （`client.ts` 的 `const BASE` 快照已改成每次读）。
- UI：列表头下拉（≥2 个可用账号才出现「全部邮箱」）+ 账号徽标 + 账号页
  「多账号」一段（添加前调 /auth/me 验证，401 当场拒绝，不写进列表）。
- 测试：vitest 230 通过（原 222 + 新 8）、`test/lib/accounts.test.mjs` 16 通过、
  typecheck 通过。新增 `test/manual/multi-account-verify.mjs`（真起打包产物 +
  两个真实账号，判据落在网络层：聚合必须每账号各一次请求且各带自己的令牌）。
 2026-09-13 06:16:59 +08:00
JianFeeeee
8b2206ed53 fix(electron): Phase 3 验收抓到的两个静默缺陷 —— 白屏与登录 
Phase 3（写信 + 附件 + 权限面板）的验收脚本第一次跑就把这两件事翻出来了，
两个都**表现正常**：进程活着、窗口标题对、接口能通，只有结果不对。

## 1. 打包后的应用是白屏（vite 的 base 缺省值）

`vite.config.ts` 没设 `base`，Vite 按默认的 `/` 生成 `src="/assets/index-xxx.js"`。
同一份 dist 有两个宿主：网关在 `/` 下伺服它（Web 正常），Electron 用 `loadFile()`
从 **file:///…/dist/index.html** 加载它 —— 绝对路径在那儿解析成
`file:///assets/index-xxx.js`（不存在），**JS 根本没加载**。

现场：`#root` 里一个子节点都没有。没有报错对话框，控制台里只有一条不起眼的
资源加载失败。而当时所有既有检查都是绿的：`npm run build` 成功、deb 元数据检查、
asar 内容清点（**它们只看文件在不在，不看文件引用什么**）。

修法：`base: './'` —— 两边都对（Web 在 /index.html 里 `./assets/x.js` → `/assets/x.js`；
Electron 在 dist/index.html 里 → `dist/assets/x.js`）。

## 2. 桌面壳用账号密码登录是断的，而且静默失败

账号密码登录靠 `SameSite=Lax` 的会话 Cookie，而桌面壳的页面是 `file://`
（**不透明源**）—— Chromium 按第三方上下文处理它，Cookie **不予存储**。

实测现场：`POST /auth/login` 返 **200**、响应体能读出用户名，但 `document.cookie`
是空的，紧接着的 `/auth/me` 返 **401**；界面停在登录页，看起来像「密码错了」，
而同样的账号密码用 curl 登录是成功的。所以这不是凭据问题。

修法：桌面壳里**不再给账号密码表**（一个必然失败的按钮比没有更糟），改成粘贴
**用户密钥**（`Authorization: Bearer`，桌面端本来就该这么用）：
- preload 显式声明 `__AGENTMAIL_SHELL__ = 'desktop'`（宿主契约，而不是让渲染层
  sniff 协议；顺带让 jsdom 里可测 —— 那里的 `location.protocol` 不可重写）
- 新增 `authStore.loginWithKey`：成功后才留下令牌，失败**还原**（否则之后每个请求
  都会带上这个坏 key 并 401，而人看到的是「重输一次也不行」）
- 顺手修了 label 与 input 没有关联（`htmlFor`/`id`）—— 无障碍缺陷，也让测试能按标签查

## 验收

- 结构性守卫进 `npm test`（`test/packaging.test.mjs`，不需要浏览器）：base 必须是
  相对路径、产物里不能有绝对资源引用、**安装包里的 dist 与当前构建一致**
  （前端改了没重打包时，装上去的人看到的是旧界面，两边不一致却谁都不报错）。
  判据自检过：把 base 改回 `/` 或把产物改回绝对路径，各自都能让对应那条变红。
- 组件测试 6 条（两种壳的形态、密钥成功/失败、空密钥不可提交）。
- `test/manual/desktop-phase3-verify.mjs`：真起打包好的应用（xvfb + CDP），
  一条贯穿的链 —— 用桌面 UI 写信带附件 → 外部核验信与附件真到了网关 →
  这封信触发 zcode 的真实授权请求 → 在桌面**授权面板**里点同意 →
  外部核验 **Agent 真的执行了**（标记文件出现）。第二次跑 14/14 全绿。
- 客户端全量 222/222；网关换新产物后 Web 依旧正常（相对路径在 `/` 下同样成立，
  实测渲染出收件箱、无控制台错误），并真发一封邮件确认回信到达。

## 判据自己的错（记一笔）

第一次跑时「附件真的挂在信上」报红，而库里那 41 字节的附件**明明挂在信上** ——
我把端点写成了 `/me/mail/{id}`（不存在，404），正确是 `/mail/{id}`。
判据用错端点时以「附件是空的」现形，看起来像功能 bug。

另：`pkill -f 'agentmail-web'` 会把**自己这条命令**也杀掉（命令行里含同样的字符串），
表现是「脚本没有任何输出、退出码 143」。改用端口定位（`ss -tlnp | grep :9223`）。
 2026-09-12 20:25:00 +08:00
JianFeeeee
c19eea5e3c feat(webui): 真正动可见层的现代化 —— 字号、层次、间距、分隔线 
# 起因：上一轮的「现代化」基本不算现代化

用户指出「我说的是 webui 现代化」。回看上一轮，我交付的其实是**底层改进**：
圆角加大一档、自定义滚动条、焦点环、过渡、reduce-motion、令牌与可访问性。
这些都对，但**可见变化几乎只有圆角** —— 界面看起来还是老样子。

实测数据确认了「老」在哪：

  text-xs(12px)  172 处   ← 被当正文用
  text-[10px]     84 处
  text-[11px]     68 处
  text-[9px]      19 处   ← 现代显示器上基本读不了
  text-sm(14px)   69 处
  text-base(16px)  4 处

  57 处 border-b + 21 处 border-r，其中 67 条是 border-gray-200 的硬灰线

  阴影：全站共 10 处，且全是 Tailwind 系统默认档；
        index.css 里 --shadow-1/2/3 三个语义令牌**定义了但零处使用**

所以真正的病因是三条：**字太小、层次为零、硬线切分**。

# 改动

## 1. 字号体系抬一档（tailwind.config.js）

不用 Tailwind 默认档，重定为：

  3xs 11px（角标下限，取代 9/10px 魔法数字）
  2xs 12px（元信息，取代 11px）
  xs  13px（次要正文，原 12px —— 拿它当正文的地方自动变舒适）
  sm  14px（正文）
  base 15px

并把 171 处裸 px 类名（text-[9px]/[10px]/[11px]）统一换成令牌 ——
顺带消除魔法数字。行高一起给：小档位 1.35/1.45，正文 1.55，
只放大字号不放行高会把密排列表顶得很难看。

## 2. 把层次接出来（原本是死代码）

tailwind.config.js 新增 boxShadow 映射 `--shadow-1/2/3` + 新增
`--shadow-panel`（横向偏移 + 大扩散，竖向几乎不偏移，否则全高面板像浮在半空）。

用于：列表面板（lg:shadow-panel，**同时去掉 border-r 硬线**）、
登录/初始化卡片（shadow-sm → shadow-2 + 去硬边框）、
地址自动补全下拉（shadow-lg → shadow-2）、窄屏滑入详情面板
（shadow-2xl → shadow-3 + 去 border-l）、主题分段控件的选中滑块。

深色下层次比浅色更难感知，所以 --shadow-panel 在深色里更实一些；
深色里靠边框分组几乎看不见，层次是**唯一**有效的分组手段。

## 3. 分隔线软化（改令牌而不是改 67 处类名）

`--c-gray-200` 浅色 229 231 235 → 234 236 241，深色 44 49 59 → 39 43 52。
改在令牌上，67 条边框 + 8 处底色一次性生效且不会漏。

**刻意没有一起调 gray-300**：它同时是滚动条滑块色，调淡会让滑块更难看见。

## 4. 配比放宽（列表行的呼吸感）

MailList：行内距 px-3 py-2.5 → px-3.5 py-3，列表 gap space-y-0.5 → space-y-1，
表头 py-3 → py-3.5。未读主题字重 medium → semibold，已读 gray-500 → gray-600。

## 5. 量出来的两个真实对比度缺陷（不是估算）

新增 `test/manual/modernization-verify.mjs`，用真实渲染做四条判据。
它量出浅色下两个 WCAG AA 不达标（阈值 4.5:1）：

  - 会话别名 `text-blue-500` 白底 3.68:1（别名在 mail list / thread / mailview
    共 4 处，都是 11px 小字）→ 改 blue-600/700，达 5.17:1
  - 时间戳 `text-gray-400` 压在选中行淡蓝底 `bg-blue-50` 上 4.44:1

第二个的**根因是调色板缺一档**：浅色下 `--c-gray-400` 与 `--c-gray-500`
完全相同（都是 107 114 128），于是「比次要文字再深一档的中间色」根本不存在，
时间戳无处可退。拉开 gray-500 → 90 98 112（5.65:1），并把 5 个列表组件的
行内元信息（19 处）从 gray-400 提到 gray-500。

# 验证

- typecheck 干净
- 前端全量 `npm test` EXIT=0（markdown-xss / narrow-layout / theme 30 /
  background 15 / vitest 216）
- **真实渲染** `modernization-verify.mjs`：浅色 8/8、深色 8/8，判据含
  最小字号 ≥ 11px（改造前 9px）、邮件正文 ≥ 14px、列表面板真有 box-shadow、
  gray-200 是软化值、40 处正文对比度全部达标

# 我自己的三处错（都被这次的度量拦下）

1. **判据量错对象**：第一版拿「收件箱列表」要求 40% 元素 ≥13px，量出 39.7%
   判失败 —— 而收件箱本质是元信息密集区，发件人/时间/别名本来就该小。
   改成量真正该达标的**邮件正文**（≥14px）。
2. **探针忽略 alpha**：`parseRgb` 把 `rgba(239,246,255,0.4)` 的 alpha 丢掉当实色，
   于是把淡蓝底当纯蓝算出 4.44:1 的假缺陷。改为按画家算法合成整条背景链。
3. **config 注释换算写错**：3xs 注释写 10px，0.6875rem 其实是 11px。
 2026-09-12 09:54:31 +08:00
JianFeeeee
84c1d749cd feat(webui): 自定义背景 + 外观现代化；修正实心按钮白字在深色下的对比度 
# 自定义背景（新功能）

三选一：不设 / 预设渐变 / 自定义图片，另加压暗与模糊两条滑杆。

**预设的色值全部复用现有调色板变量**，因此自动随主题变化 —— 那一组
（50–300）在深色下本来就是暗的（见 .dark 与 theme.test.mjs 第 19 条），
于是浅色得到柔和 pastel、深色得到低沉暗调，不需要维护两套渐变，也不会
出现「深色模式下原样落下浅色渐变」这类绕过主题变量的错误。

图片路径的关键取舍：
- **先压缩再存**。手机直出照片 4–8MB，而 localStorage 配额约 5MB，直接写会抛
  异常，用户看到的是「选了图片没反应」。等比缩到最长边 2560px、转 JPEG；
  仍超限则再缩一档；再不行就**明确拒绝并说明原因**（不是静默失败）。
- 失败一律返回 `{ok:false, reason}` 并渲染成 `role="alert"`。

# 背景层为什么不放进主题 store

主题（light/dark/system）是必须全局一致的语义；背景是纯装饰偏好，取值空间
与主题毫无关系。混在一起会让「跟随系统」的实现被背景字段淹没。

# 背景层实现在 CSS，不改 27 个组件

按 Tailwind 生成的实际类名统一接管：背景开启时让出不透明的页面底
（body / bg-gray-50 / bg-slate-100 → 透明），并把卡片（bg-white）与框架
（bg-chrome-800/900）变成半透明 + 背景模糊。

逐个组件加 class 必然漏 —— 漏掉的那块就是一张不透明卡片浮在背景上。
这段 CSS **刻意放在所有 @layer 之外**：它要覆盖的正是 utilities 生成的
`.bg-white`，写进 @layer components 会被 utilities 压过去（静默失效），
而分层 CSS 恒输给未分层 CSS，这是唯一稳定可靠的位置。

**chrome-600/700 刻意保持不透明**：它们不是大面板，而是导航项与 15px 的
计数徽标。真实渲染量得半透明会把徽标上的数字压到 4.46:1，低于 AA 4.5 ——
小控件的可读性优先于装饰效果（已用脚本量出，见下）。

# 「跟随系统」的可见性

三态本来就已实现（system 为默认值 + matchMedia 监听）。这次做的是让它可被
发现与信任：选择器改成分段控件（role=radiogroup + aria-checked），说明文案
写清「跟随系统会随系统的深色开关自动切换」，并保留单选按钮入口的
「当前跟随系统：深色/浅色」提示。

# 外观现代化

- **圆角整体调大一档**（默认 0.25→0.5rem）。原值是几年前的紧凑风格，
  在宽屏桌面应用上偏硬。只改比例尺，200 处圆角一次性刷新，不产生
  「新组件大圆角、旧组件小圆角」的断层。
- 语义化圆角令牌：`rounded-card` / `rounded-control`（数值档位答的是「多大」，
  这两个名字答的是「用在哪」）。
- 自定义滚动条（桌面应用里常驻可见，系统默认样式偏旧）。
- 键盘焦点环（`:focus-visible`，仅键盘导航时出现；可访问性硬要求）。
- 交互元素统一过渡；并尊重 `prefers-reduced-motion`。

# 顺带修正两处真实问题（都由真实渲染量出，不是估算）

1. **实心按钮白字在深色下 4.46:1，低于 AA**。
   深色 `--c-on-accent` 是「近白」244 246 250（为了不刺眼），而结构检查第 23
   条只拿**浅色**的纯白 255 去算 → 4.83 通过。**测试存在盲区**：
   同一个实心底，白字换暗一点点就越过 AA 线。导航未读徽标「12」正是这个组合。

   两处都修：把第 23 条改成**两种模式的 on-accent 都算**（闭合盲区），
   并把深色 on-accent 抬到 250 250 252（4.65:1，仍非纯白，保留原初衷）。

2. **theme.test.mjs 切颜色块的方式很脆**：它用 `indexOf('.dark')` 切片，于是在
   :root 的注释里写一句带点的选择器写法就会把浅色块提前截断（我加注释时
   真的踩到了，第 8 条假失败）。更危险的是反向情形：块被截短后变量集合变小，
   「覆盖齐全」这类断言可能**真空通过**。改为所有块切分都基于**剥注释后**的文本。

# 测试

- 新增 `test/background.test.mjs`（15 条结构检查）：遮罩两主题各一份、
  背景层必须负 z-index（0 会盖住界面）、背景开启时必须让出页面底、
  玻璃化只在 data-bg=on 下、悬停态一并接管、预设复用调色板变量、
  图片上限与失败原因存在、尊重 reduced-motion 等。
- 新增 `test/stores/background.test.ts`（16 条）：脏数据归一化（未知预设、
  kind=image 却无图、越界数值）、CSS 变量写入与清理成对（残留 --bg-image 会
  让「关掉背景」后仍显示旧图）、localStorage 抛异常不打断操作。
- 新增 `test/manual/background-verify.mjs`：连真实 Chromium 验收**渲染结果**
  （背景层是否真的可见、玻璃化的计算样式、正文在背景之上是否仍达 WCAG AA、
  自动模式在**不刷新**页面时跟随系统切换、显式选择不被系统覆盖）。
  它拦住了上面两个真问题，也拦住了我自己两次写错的判据。

# 验证

- typecheck 干净
- 主题 30/30、背景 15/15、vitest 216/216（新增 16）
- 真实渲染验收 23/23（AGENTMAIL_DIST 注入本地构建 + 活 Gateway，未部署即验收）
- 截图对照：浅色/深色 + 极光背景，面板玻璃化与层次均符合预期
 2026-09-12 08:02:30 +08:00
JianFeeeee
bbddee26b9 feat(permission): 待办带上失效时刻；越窗的决策不再假装成功 
# 起因：一次端到端验证暴露的静默缺口

建了示例工程让 pi 通过邮件干活（plan 档拦截、workspace 档审批、多 agent 指派）。
plan 档与多 agent 都通过，workspace 档却卡住：**人在界面上批准了一条待办，
接口回 200，但那件事什么都没发生。**

追下去是三件事叠在一起：

1. **桥**等不到决策时（pi 的回合超时 TURN_TIMEOUT_MS，默认 10 分钟）会拆掉 worker
   与它的决策路由表；此后再来的决策只会作为**通知**投给 Agent，不恢复当时那次
   工具调用 —— 该轮已经结束了。
2. **服务端**只有 `permission_requests.result IS NULL`，没有「失效」概念。
   迟到决策照样回 `{"status":"decided"}`。
3. **前端**只看 `permission_result` 判待决/已决，没有任何时间或失效提示。

于是那条待办永远挂在授权页上显示「等待你决策」，人点了也白点。这是 I-5
（失败必须当场可见）要消灭的那类静默成功，而且**跨所有客户端**成立 ——
WebUI 不显示，Electron / Harmony 同样无从显示。

# 设计：邮件上给「时刻」，不给「是否失效」的布尔值

服务端不知道插件此刻是否还在等（那是它进程内的状态），所以只标出「这封待办已经
放了很久」，不替插件宣布裁决。

关键取舍：对外只发**截止时刻**（`permission_expires_at`），不发 `stale` 布尔值。
布尔值是「发出那一刻」的快照 —— 经 SSE 推送并被客户端缓存后会永久停在旧值，
界面就会一直显示「等待你决策」。时刻是持久事实，任何客户端在任何时候都能自己
比出现在过没过期。这也是为什么推导而非落库：它是 created_at 的函数，存下来会失真。

`DecidePermission` 的响应里则用布尔值（`expired`）—— 响应本身就是「此刻」的
一次性快照，不会像邮件那样被缓存反复展示。

# 改动

- `models.PermissionWaitWindow`（10 分钟，与 pi 桥的回合超时同量级）+
  `PermissionDeadline(createdAt)`；两端共用这一处算式，避免「界面说已过期、
  决策说没过期」。
- `Mail.PermissionExpiresAt` / `PermissionRequest.ExpiresAt`：由读路径推导填充。
  5 个读路径各插一行（`AttachPermissionDeadline*`）—— 与审计修复① 加
  permission_kind 时同一套路数，漏掉任一路径只会静默变成 nil。
  只给**仍未决策**的待办填，已决策的不再是待办。
- `decideResponse`（抽出纯函数以便测试）：越窗时加 `expired` + `warning`，
  讲清「决策已记录、但不会恢复原调用」。**不改 HTTP 状态码**：决策仍是人的真实
  意愿、仍然有效（桥会当通知投递，Agent 重起一轮），所以不能拒掉，但必须说清。
- 前端：列表里失效项不再与「还能立刻生效」的长得一样（灰底 + 「可能已失效」）；
  批准面板在决策**前**（人正要按下去）与决策**后**（人以为事情办了）都显示提示。

# 验证

- Go：models/repo/handler 三处新增测试全绿；全量 `go test ./...` 通过；vet 通过
- 前端：typecheck 通过；200 项测试全绿（含新增 4 条失效态）
- 真机（用现成的过期待办，未造合成数据）：
  - `/permission/pending` 返回 `expires_at` = 创建 + 10 分钟，服务端判定已过窗
  - 邮件载荷带上 `permission_expires_at`（前端列表的数据源）
  - 对过期待办提交批准 → `{"expired":true, "expires_at":…, "warning":"该请求已超过
    等待窗口（10 分钟）…不会恢复当时那次工具调用…"}`
- 已用 redeploy-gateway.sh 部署，服务 active、四 agent 心跳正常、日志无 panic
 2026-09-11 22:02:25 +08:00
JianFeeeee
a404cbad54 feat(branding): 确定项目图标，并接入 Web / Electron / HarmonyOS 
# 唯一源

`client/electron/src/icons/agentmail.svg` 是图标唯一源（24×24 视图框，`currentColor`
跟随文字色）。此前各端用的都是占位物：Electron 的窗口/托盘指向一个**不存在**的
`src/icons/tray-icon.png`（`nativeImage` 拿到空图，托盘不可见），
HarmonyOS 的 `startIcon/foreground/background` 是 1×1 PNG，
Web 端根本没有 favicon。

# 为什么带生成脚本

PNG/ICO 是二进制的，换一次配色要重出十几个尺寸，手工做必然出现
「Web 是旧的、Harmony 是新的」这种不一致，而且没人能复核。
`generate.py` 只认上面那一份源，所有变体都由它推导（本机无 rsvg/ImageMagick，
用 cairosvg + Pillow）。改图标只需改源文件再跑一次脚本。

# 各端产物

- **Web**：`public/assets/{agentmail.svg,favicon.ico,apple-touch-icon.png}` + `index.html` 引用。
  放 `assets/` 下而非根目录，是因为 Gateway 只把 `/assets/*` 与 `/` 交给静态处理器
  （`server/cmd/server/main.go`），放根下会 404。已实测本机与 LAN 均 200。
- **Electron**：应用图标 `icon.png`(512) / `icon.ico`(16–256) / 各尺寸 PNG /
  托盘 `tray-icon.png`(32)，`package.json` 里 `win.icon` 与 `linux.icon` 指过去。
  托盘用品牌色字形而非白色 —— 浅色面板下白色会消失。
- **HarmonyOS**：`startIcon.png`(512) 用完整应用图标（启动页底色浅 `#FFF` /
  深 `#000`，白底蓝图标两套都立得住）；分层图标的 `background` 是品牌色整块、
  `foreground` 是白色字形并留 12% 安全区，避免被系统圆角裁掉。
- **应用内**：新增 `BrandMarkIcon`（fill 型，与现有描边图标集不同族），
  替换登录页与初始化页品牌位的占位 `MailboxIcon`；后者已无引用，一并删除。

图标色 `#2563eb` 与门户 Dashy 主题主色一致。

# 验证

- 前端 typecheck 与 196 项测试全绿；`npm run build` 产物含三个图标文件
- Gateway 重新部署后 `/assets/{agentmail.svg,favicon.ico,apple-touch-icon.png}`
  在本机与 `192.168.2.60:8180` 都返回 200，Content-Type 正确
- 所有 PNG/ICO 用 Pillow 复核尺寸与 alpha 边界（合成失败会表现为全透明，
  已用 getbbox 排除）
 2026-09-11 15:49:41 +08:00
JianFeeeee
4050827e5c feat(permission): 新增第三种强制力 partial —— DSH 如实自报，不再冒充 native 
# 问题

审计发现 DSH 自报 mode_enforcement=native，而实测它的 Landlock 沙箱受内核 ABI
版本限制、拦截覆盖不完整（PLAN.md L5 自己写的就是 dsh = Landlock partial）。

只有 native / advisory 两个取值时，这个平台无论标哪个都是在说假话：
  - 标 native → 人会以为 plan 档是硬保证，把它当安全边界依赖；
  - 标 advisory → 又低估了它（确实在拦），而「平台无法强制」会让模型
    在本可依赖的边界上过度保守。
多一个取值比多说一句假话便宜。

# 改动

- Go models：EnforcementPartial = "partial"，ValidEnforcement 接受它；
  NormalizeEnforcement 对显式自报值一律原样保留（partial 降级到任一极端都是假话），
  未知值仍然 fail-closed 到 advisory。
- 三桥共用 lib/permission-mode.js（逐字节同源）：ENFORCE_PARTIAL +
  modeBriefing 三态措辞。partial 版必须同时做到两件事：
  说清「覆盖不完整」，并收回 native 那句「都会被平台拦下」的承诺
  —— 否则模型会以为越界一定被拦，于是不必自己小心。
- 前端 PermissionChip：三个点形区分（实心 / 靶心 / 空心）+ 三套 tooltip 文案；
  认不出的强制力按 advisory（与后端同方向）。
- DSH 插件心跳改报 partial。
- 顺带修正活跃 DSH 会话的历史快照：那批 native 是插件当时的**误报**，
  不是能力变化，因此把 status<>'archived' 的 dsh 会话改为 partial；
  归档会话按设计保留（不重写已结束的历史）。改前已 sqlite3 .backup 备份。

# 验证

- agents.mode_enforcement：dsh 由 native 变为 partial（心跳生效）
- Go 全量、三桥插件 320/362/409、前端 196 全绿（新增 PermissionChip 11 例）
- 三桥共用模块同源校验通过
- 关键判据：partial 的措辞与 native/advisory 两两不同，且不含「无法强制」
 2026-09-11 12:04:06 +08:00
JianFeeeee
429149e118 chore(format): 撤销误入提交的整体重排，并关闭本仓库的格式化器 
# 发生了什么

pi-lens 内置「安全格式化」：它会自动安装 biome 并对**编辑过的文件**跑
`biome format --write`。本机原先没有任何 biome 配置，于是 biome 用它自己的
默认值 —— tab 缩进 + 双引号 —— 把文件整体重写。

我在 19a3161 那次提交里用了 `git add -A`，把这批与功能无关的重排一起扫了进去：
约 7000 行改动散落在 20 个文件上，使那次提交无法审查，还掩盖了
server/internal/handler/permission.go 的一处删行（实为文件末尾空行，无代码丢失）。

# 为什么是「关掉」而不是「配置成我们的风格」

试过把缩进/引号/lineWidth 全部对齐本仓库习惯（biome.json + space/2/single/
lineWidth 120）：`biome format --write` 仍然改动 17 个文件。原因是本仓库从未按
biome 的规则排版过 —— 注释按语义换行、数组与调用按可读性手工折行，
这些无法由格式化器还原。也就是说只要格式化器开着，每次编辑都会产生与内容无关的
大面积 diff，把真正的改动埋掉。

因此 biome.jsonc 里 formatter 与 linter 都关闭：本仓库的静态检查由
tsc / go vet / tree-sitter / ast-grep 与各自测试套件承担，不引入会改动无关行的
自动修复。

（pi-lens 这一版把 format 服务的 enabled 硬编码为 true，没有配置开关，
所以只能在仓库侧用 biome 配置让它不动文件；已验证 `biome format --write`
对这些文件零改动。）

# 本提交内容

把 19a3161 里除「有意改动」外的 20 个文件还原到重排前的样子。
19a3161 中真正有意的改动是 deploy/install.sh 的扩展注册与
plugins/pi-mail-bridge/extension/index.ts 新文件，两者原样保留。

验证：Go 全量、三桥插件（320/362/409）、前端 196 全绿；
`biome format --write` 对还原后的文件零改动。
 2026-09-11 12:03:51 +08:00
JianFeeeee
19a3161ee4 feat(pi): 交互式 pi 会话接入邮件工具（send_mail/read_inbox 等 10 个） 
问题（⑧）：守护进程用 noExtensions:true 起会话，它的邮件工具只给模型在邮件
会话里用；人在 TUI 里敲的 pi 拿不到。结果是平台的建设者自己收不到邮件 ——
一个「邮件驱动」的平台，维护者只能绕到 curl + 密钥直连 Gateway 才能看收件箱。

新增 plugins/pi-mail-bridge/extension/index.ts：把同一套工具（createMailTools）
注册到交互式会话。两者是同一条 AgentMail 身份（agent pi）的两个入口，与 DSH 的
「TUI + 邮箱是同一个 Agent」一致。

密钥解析顺序（交互式 pi 的环境里没有 AGENTMAIL_*）：
  1. 进程环境
  2. AGENTMAIL_ENV_FILE（默认 /etc/agentmail/pi.env）—— 与守护进程同一把密钥，
     因此身份一致
  3. AGENTMAIL_CONFIG_DIR/agent.key 或 ~/.agentmail/agent.key
     （兼容 key 与 key_token 两种字段名；实测本机文件用的是 key_token，
      只认 key 会静默读不到）
拿不到密钥时不注册任何工具并明确告知 —— 挂一组永远 401 的工具比没有更糟。

不注册 connect_to_server：它会重写 Gateway 坐标并重新登记密钥，而交互式会话与
守护进程共用同一身份，一次 TUI 对话不该改到守护进程的配置。

为什么不会重复注册（读 SDK 实现确认，并用探针实测）：
  resource-loader.js 里 noExtensions 为真时只用 cliEnabledExtensions，
  settings.json 的 extensions 数组被排除 —— 即 noExtensions:true 只加载
  命令行 -e 传入的扩展。
  探针：noExtensions=true → 扩展数=0；false → 16 个且含 pi-mail-bridge。

deploy/install.sh 增加幂等的扩展注册步骤（写入 settings.json 的 extensions）。

验证：headless pi 实际调用 read_inbox 返回真实邮件主题；工具清单含
send_mail/read_inbox/read_mail/forward_mail/upload_attachment/download_attachment/
suggest_address/list_contacts/session_participants/read_thread（10 个），
connect_to_server 按设计排除。
 2026-09-11 11:32:47 +08:00
JianFeeeee
f91efd2d8d feat(question): DSH ask_user_question 桥接 + 前端问答面板 + 待办字段全路径透出 
问题（P0）：DSH 有两个独立的人机交互 seam —— approval/request（危险工具审批）
与 ask_user_question → ctx.userQuestions（模型主动提问）。原来只桥接了前者。
邮件驱动的会话没有本地 UI，而 ask() 的 provider 是 DSH host 注册的本地 UI 实现，
于是在那里等人点选永久等不到，那一轮工具调用**静默挂死**。

修法（不抢注全局 provider —— registerProvider 只允许一个活动实例，抢注会让
平台自己的界面失效）：在 tools/execute around-dispatch 里只对**邮件驱动**的
会话接管 ask_user_question，其余原样 next()。失败一律当场报错而不是 next()：
下一个 answerer 是本地 UI，邮件会话没有兜底 UI，放过去就是挂死。

- lib/user-question.js（三桥逐字节同源，14 例测试）：DSH questions[] ↔ AgentMail
  单问题询问邮件的双向映射。多问题时把选项并集摊平、按 label 归属分配回各问题
  （label 认不出来就不猜测放行）；无选项题走自由文本 custom。
- Gateway：kind=question 且无选项时**不再**回落「同意/拒绝」（那会让自由文本
  问题变成两个毫无意义的按钮）；主题按类型区分「权限请求 / 需要回答」；
  推送 payload 带上 permission_kind / multi_select / options。
- mails.permission_kind / permission_multi_select 此前只存在于结构体与写入路径，
  五个读路径的 SELECT/Scan 都没带 —— 前端永远拿到空串，把提问渲染成批准/拒绝。
  container 修正五处并加 repo 测试（含反向验证：删掉任一处字段，测试即失败）。
- 前端 PermissionPanel：question 走「勾选 + 自由文本」，多选/单选、空回答禁止提交；
  approval 路径不变（回归测试覆盖）。

测试：opencode 316 / dsh 349 / pi 405 / 前端 185 / Go 全量 全绿。
 2026-09-11 10:44:18 +08:00
JianFeeeee
f9d757b5e5 chore: directory migration - gateway→server, web→client/electron 2026-09-08 19:16:35 +08:00