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

5 Commits

Author SHA1 Message Date
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
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
f9d757b5e5 chore: directory migration - gateway→server, web→client/electron 2026-09-08 19:16:35 +08:00