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

4 Commits

Author SHA1 Message Date
JianFeeeee
d74f356f41 feat(web): 深色主题 —— 反转灰阶而非逐处 dark: 前缀 
**逐处加 dark: 前缀的方案在这里必然失败**：约 700 处颜色散在 21 个组件里，
漏一处就是深色下的白底白字，而它不报错、不影响构建、只有肉眼能发现，
且往往只出现在某个不常开的页面。此后每加一个组件都要记得写两遍，
那种约定活不过三次改动。

改法是把颜色下沉到 CSS 变量，深色模式**反转灰阶**。这套代码的灰阶本身
就是语义色阶（white/gray-50 = 表面层次，gray-200/300 = 分隔线，
gray-900→400 = 文字主次），反转之后 `bg-white text-gray-900` 自动变成
深色卡片 + 浅色文字。零组件改动，新组件照常写浅色类名也自动适配。

变量存 **RGB 三元组**而非 #hex：代码里有 bg-blue-50/70 这类透明度修饰符，
Tailwind 生成 rgb(var(--x) / 0.7)，而 rgb(#f9fafb / 0.7) 是无效 CSS ——
那些半透明高亮会静默失效（不报错，只是不透明）。

---

实测撞了三个必须分离的语义，每一个共用变量就坏：

**1. text-white 不能跟 bg-white 走。**
`white` 服务两种冲突用途：卡片表面（深色下要变暗）与彩色按钮上的文字
（深色下必须保持浅色）。共用时后者跟着变暗 —— 激活导航项的「收件」在
bg-chrome-700 上只剩 **1.34:1**，几乎消失。拆出 --c-on-accent。

**2. 侧栏与底部导航不能跟 gray 走。**
它们在浅色模式下**本来就是深色的**（深色侧栏配浅色内容区是原本设计）。
并入反转灰阶后深色模式下变成近白色（实测 rgb(243,245,248)），比内容区
（rgb(17,19,24)）还亮，整个层次翻过来。独立成 chrome 色阶，深色下只微调、
保持「框架比内容更沉」。

**3. 强调色不能反转。**
blue/red 跟着变会让主按钮在深色页面上失去「这是主操作」的视觉重量，
而且白字落在变暗的 blue-600 上对比度掉到 3:1 以下。改成固定值。

---

顺带修的三处真实对比度不足（实测量出来的，不是猜的）：
- 待决策橙徽标：orange-500 上白字 2.80:1 → orange-700 5.18:1
  （保留橙色语义，不能改成灰 —— 它与未读的红色是两种紧急）
- 空状态文案：gray-400 2.43:1 → gray-500。这类文字是**页面上唯一的内容**，
  不是次要装饰，读不动等于页面空白
- 列表头计数：同上

---

主题是**三态**而非开关：system 不是 light 的别名 —— 只给开关的话，
白天设浅色之后晚上系统切深色应用不会跟着变。且只有 pref 为 system 时
才跟随系统，显式选了的人不该因为日落被切换。

index.html 加同步内联脚本消除首帧闪屏：bundle 有 430KB，从 HTML 解析完到
React 挂载之间页面是 body 默认色，深色用户每次刷新都被闪一下白屏。
外链或 defer 都晚于首次绘制。它与 themeStore 共用同一个 localStorage 键
（不一致会导致首帧按 A 键渲染、挂载后按 B 键重渲染，闪一下再变回去）。

body 显式设底色：移动端橡皮筋回弹露出的是 body 背景。

入口两处：侧栏单按钮快速翻转，「我的」页三选一设定偏好。单按钮不足以
表达三态，但只给单按钮的话用户一旦点过就永久脱离「跟随系统」——
那是个回不去的单向门。

测试：test/theme.test.mjs 20 条结构性断言（已进 npm test），
test/manual/theme-verify.mjs 真实渲染对比度验收（遍历可见文本节点算 WCAG
比值，往上找第一个不透明背景）。两种模式各 4 项全过。
 2026-09-04 06:30:26 +08:00
JianFeeeee
514f443e54 fix: 「我的」页无法滚动 —— 缺滚动容器；顺带修矮屏登录页 
用户反馈「我的页面点击进入后无法滑动」。

## 根因：AccountPage 根本没有滚动容器

窄屏外壳是 `h-full flex flex-col overflow-hidden`，页面本身是
`flex-1 min-w-0 flex flex-col`，中间缺一层 `overflow-y-auto` ——
内容超出的部分**直接被裁**，滚不到也点不到。

实测 390px 下内容（资料 + 权限 + 改密码 + 密钥 + 退出）需 860px、容器只有
795px，「退出登录」按钮连同下面 65px 一起消失；1280x800 的桌面上同样看不到。

其余六个页面级组件（AdminUsersPage / MailView / ComposePage / ThreadView /
ContactPanel / MailList）都有这一层，只有它漏了 —— 上一轮把退出登录搬进这页
之后内容变高，问题才显形。

## 顺带：登录页与初始化页在矮屏滚不到底

卡片高约 371px，而 `h-full flex items-center` 在内容超高时让它上下**同时**溢出，
溢出到顶部那段是滚不到的（`scrollTop` 最小是 0）—— 实测 568x280（横屏手机，
或软键盘弹出后的可视高度）下「登录」按钮完全在视口外，光加 `overflow-y-auto`
也够不着。

改用卡片自己的 `my-auto` 而不是容器的 `items-center`：auto margin 在空间不足时
自动退化为 0，矮屏变成正常的顶对齐可滚布局，高屏仍然垂直居中
（390x844 与 1280x800 实测 centered=true，568x280 下滚到底能看到按钮）。

## 两侧都加了检查

- 结构断言：七个页面级组件都必须含 `overflow-y-auto`；
  登录/初始化页必须有 `my-auto` 且不用 `h-full ... items-center`
- 实测脚本新增 `scrollHealth()`：每页都有滚动容器，且没有内容被
  `overflow-hidden` 的父级裁掉

判据刻意是「**有**滚动容器」而不是「当前正在滚动」—— 内容暂时不够高时后者
为假，但页面是健康的；真正的 bug 是根本没有那一层。

## 验证

窄屏实测 18 项 + 宽屏回归 5 项全通过；结构断言从 28 条扩到 37 条。
生产已部署。
 2026-09-03 07:39:52 +08:00
JianFeeeee
342282b92c fix: 窄屏实测修复 —— 删抽屉、44px 命中区、触摸设备可见的次要动作 
用 playwright 连本机共享 Chromium，在 390px（iPhone 14 Pro）与 320px
（iPhone SE）量真实盒子。之前的窄屏适配是「照着规则写对」，实测发现
一个功能性 bug 加五处可用性问题。

## 抽屉式侧栏遮挡底部导航（真 bug）

抽屉是 `fixed left-0 top-0 bottom-0 z-50`，铺满整个视口高度；底部导航没有
z-index。抽屉打开时点最左那一项「收件」，elementFromPoint 命中的是抽屉里的
SVG，不是导航按钮 —— 按钮在那里、尺寸也够、CSS 规则也没写错，只有命中测试
才能发现。

**删掉抽屉而不是给导航加 z-index**：抽屉装的六项（收件/发件/联系/用户/新建/
管理）与底部导航完全重复，唯一独有的是退出登录。为一个按钮维护一套 fixed
层级加遮罩不划算，而它还附带「Esc 关不掉」「底层未锁滚」两个毛病。

退出登录移到「我的」页 —— 它与密码、密钥同属「账号自身」，而那页此前根本
没有退出入口。`NavToggle` 与 uiStore 的 navOpen/toggleNav/closeNav 一并删除。

## 触摸命中区：新增 .tap

详情页那排工具按钮视觉高度只有 15-16px（实测「标记已读」48x16、「对话树」
54x16、「转发」42x16、「抄送」20x15），移动端下限是 44x44。

直接加 padding 会把本来就挤的头部撑散、320px 下换行，因此用居中的透明伪元素
扩大命中区：**视觉一像素不动**。只在 max-width:767px 生效 —— 桌面用鼠标精度
足够，而扩大后的命中区在密排工具栏里会互相重叠，点一个可能命中隔壁那个。

覆盖 MailView / ContactPanel / WorkCard / ModelScopePanel / AdminUsersPage /
ComposePage / ThreadView / KeyPanel / QuotaPanel / Attachments / BackButton。

## 看不见却按得动的按钮：新增 .reveal

`opacity-0 group-hover:opacity-100` 在没有 hover 的设备上永远是 opacity:0，
**但仍然接收点击** —— 实测联系人列表里 elementFromPoint 命中的就是那个看不见的
「归档」。一个看不见却按得动的破坏性按钮比没有按钮更糟：人以为点的是卡片，
实际归档了一条会话。

改为默认可见，只在 `(hover: hover) and (pointer: fine)` 时隐藏。
单看 hover 会把带触摸板的平板算进去。

## 对话树

- 缩进随屏宽自适应：固定「每级 20px、上限 8 级」= 最多 160px，320px 屏还要
  去掉 px-4 的 32px 与连接线 18px，卡片只剩 110px，发件人一行直接被 truncate
  吃掉。窄屏改为每级 10px、上限 5 级
- 补返回出口：原先只有「关闭」。两者语义不同 —— 返回退出整个详情栏回到列表，
  关闭只收起树、留在这封邮件上

## 把实测脚本留进仓库

`web/test/manual/`（`npm run test:narrow` / `test:wide`），不进 npm test ——
要一个跑着的浏览器加一个活的 Gateway。

留着而不是用完即删，是因为结构性断言守不住「按钮实际多大、点下去命中谁」，
而这次最严重的 bug 恰好只有 elementFromPoint 能发现。helper 里两个函数专门
为此：tapTargets() 量 .tap 的真实命中区（伪元素尺寸，不是 boundingBox），
hitTest() 验每个元素点下去是否命中自己。

## 验证

- 窄屏 13 项 + 宽屏 5 项全通过。宽屏回归特意验了两件只该在窄屏生效的事：
  .tap 伪元素 content 为 none、没有返回按钮
- narrow-layout.test.mjs 从 20 条扩到 28 条，逐条钉住上面每个修复
- 无横向溢出：390px 与 320px 下 scrollWidth === clientWidth
- 生产已部署
 2026-09-02 23:53:59 +08:00
JianFeeeee
07e6b789b2 feat: 配额下沉到会话 + 窄屏覆盖式布局 + 工作列表卡片视图 
## 配额重构：废除 Agent 终身额度

原实现在 agents 上放一个 max_rounds/used_rounds 计数器，used_rounds 单调递增、
永不重置 —— 跑满就要管理员手工重置才能再干活。那是把一次性资源模型套在长期
在线的服务上，且并行任务互相抢额度。

改为：
- 唯一被强制的预算是【会话】的往返预算（sessions.max_rounds/used_rounds），
  写信时给、对话页里随时改 —— 配额的语义是「这件事值得多少个来回」，
  那是任务的属性而不是 Agent 的属性
- agents.default_rounds 只作为「派给这个 Agent 的新任务」的默认值（默认 20）
- agents.used_rounds 降级为纯统计
- 新建会话速率限制（1h/20 条）堵住用 .new 开一串新会话绕过预算；
  人类不受限（agentLimiterKey 返回空串即不计量）

## 窄屏适配（用户反馈「窄屏基本不可用」）

原先只有三栏并排：60(导航)+320(列表)+详情，375px 屏上详情被挤到 0。

第一版做成「一次只显示一栏」，用户纠正应当是新页面覆盖老页面并带动画，
于是重做为覆盖式：
- NarrowStack：底层列表始终挂载，详情绝对定位盖在上面。两个好处 ——
  列表滚动位置与选中态天然保留；退出动画有东西可播（直接卸载再渲染另一个
  组件的话，没有任何一帧能让旧页面往右滑出去）
- 因此必须区分「逻辑上是否打开」与「是否还在 DOM 里」：关闭时先播 200ms
  滑出，动画结束才卸载
- 入场用双层 requestAnimationFrame：必须让浏览器至少绘制一帧「在右侧之外」
  的状态，否则挂载与 translate-x-0 在同一帧内完成，transition 不触发
- 窄屏专属控件用 useIsNarrow() 条件渲染而非 md:hidden —— 后者只是视觉隐藏，
  宽屏用户按 Tab 会聚焦到看不见的返回按钮
- 底部导航 + 抽屉侧栏 + env(safe-area-inset-bottom)

## 工作列表卡片视图（Phase 7.1 最后一项）

中间栏可切列表/卡片。列表答「跟谁在聊」，卡片答「在聊什么、进展如何」：
主题 + 最新一封的发件人与摘要 + 往返预算徽标。

- 两种视图共用同一份数据与同一套动作；归档确认框也共用 —— 归档是破坏性操作，
  换个视图就换套确认 UI 只会让人对「自己点了什么」更没底
- 预算徽标在「不限」时不显示（对每张卡片都成立的「0/0」是纯噪声）
- 数据一次取回，不让卡片为每条会话再打一次库

## 修掉的缺陷

- GET /me/sessions 一直 500：ListSessionsFor 的 SELECT 加了预算两列却没加进
  Scan，列数不匹配。联系人栏一条数据都拉不到，而错误只是「Failed to list sessions」
- GET /sessions/{id} 忘了填充附件：前端会话视图走的是这个端点，于是 Agent
  回信里的附件在 UI 上完全不存在（另一个端点填了但没人调用）
- 插件曾完全没在加载：为了可测在 index.js 里 export 了辅助函数与一个 Map，
  而 opencode 把入口模块的每一个导出都当成插件工厂逐个检查，多导出一个 Map
  就 "Plugin export is not a function"，插件静默失效、邮件全投不进去。
  逻辑挪到 lib/relay-dedup.js，并加断言钉住「入口只有 default 导出」
- 同一件事发两封邮件：模型带附件主动回信后，session.idle 又把它最后那段话
  自动转了一遍（生产实测 311 与 342 字节各一封）。explicitSends 记录本轮
  主动发信，自动转发据此让位；relay_key 幂等管不了这个 —— 那个键保证的是
  「同一条消息不转两次」
- SQLite 时间戳只有秒精度：同秒插入的多封邮件排序不确定（实测同秒插 5 封，
  顺序由随机 UUID 决定）。「会话里最早那封」（决定联系人身份）与「最后那封」
  （决定最新进展）都会取错。NOW() 升到微秒 + mails 的 INSERT 显式传它
  （改 schema 默认值只对新库生效，SQLite 没有 ALTER COLUMN）+ 所有
  ORDER BY created_at 补 mail_id 兜底
- fillAttachments 从逐封查询改成一次 IN(...)：原来是 N+1，200 封的会话打开
  要打 200 次库
- repo 层 5 处 rows.Next() 循环补 rows.Err()：没有它，读到一半连接断掉会
  静默返回部分结果，UI 上表现为「邮件凭空少了几封」
- go:embed 占位页改名 placeholder.html：叫 index.html 会被 Vite 产物覆盖并
  提交进去，而它引用的 assets/ 是被忽略的 —— 新克隆打开是白屏

## 回复/转发栏

- 两处都加抄送（可折叠）；原邮件带抄送时多一个「回复全部」，回填用
  cc_list[].raw 而非重拼 name@path（后者会丢掉会话段）
- 会话视图每张卡片加转发入口：转发之前只存在于单封邮件视图，而人多数时间
  待在会话视图里，等于功能在 UI 上找不到
- ReplyBar 的错误从 console.error 改为显示出来：预算耗尽、地址不存在、
  速率限制都走这条路，之前点发送毫无反应

## 测试

- repo: 列顺序（三个 SQL 分支）、卡片字段、previewRunes 边界、时间戳亚秒精度、
  批量附件查询、速率限制（80 goroutine 断言恰好 20 条通过）
- web: 窄屏布局 16 条结构性断言（覆盖而非分栏、延迟卸载、双层 rAF、
  条件渲染而非 md:hidden）
- 插件: 自动转发去重 17 条（含「入口只有 default 导出」不变量）
- install.sh 把插件测试也纳入部署前门禁
 2026-09-02 14:16:46 +08:00