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

12 Commits

Author SHA1 Message Date
JianFeeeee
560c462768 feat(mcp): GET /api/v1/mcp —— 投递侧事件流（让接入方被动收信，不用轮询） 
## 这半边解决什么

工具面（POST）只解决「接入方**问**」。这一条解决「服务端**说**」：
邮件投递时把 new_mail / session_update 推给接入方，让它**拉起对话** ——
与各桥靠 /api/v1/events/stream 收信是同一件事，只是方言不同：

    桥:   id: 7\nevent: new_mail\ndata: {…}\n\n
    MCP:  {"jsonrpc":"2.0","method":"notifications/message","params":{…}}

## 为什么复用 sse.Manager 而不是另起一套

Manager 里那些东西**都是踩过坑才对的**：writeMu 串行化（2026-09-28 -race
实测 http.ResponseWriter 并发写会把 JSON 劈成半截，800 帧只切出 459 个完整）、
Last-Event-ID 回放（宁可重复也不丢失）、心跳（反代按空闲 30-58s 掐连接）、
环形缓冲上限、断线清理。复制一份等于把那些坑再踩一遍，
而两边的修复从此各走各的。

代价是 `sse.Client` 多了一个可选 `Frame` 钩子：
**nil = AgentMail 原格式，各桥与 WebUI 行为一字未变**（默认值即历史行为）。

## ★ 回放是第三条写路径，漏了就只在断线时现形

`Send` / `SendWithID` / `replay` 是三条写 Res 的路径。原先**三条都把格式写死**，
只改前两条的话：MCP 客户端**平时**一切正常，只有带 `Last-Event-ID` 重连时
才会收到一批自己解不开的帧 —— 同一个连接上两种方言。

判据 `TestCustomFrameAppliesToReplayToo` 专门钉这条，并带反向对照
（nil 帧必须回落 AgentMail 格式）。

`Frame` 必须在**注册时**传入（`AddClientWithFrame`），不能事后设 ——
回放发生在「先写响应、再注册」的前半段，事后设只影响之后推来的事件。
原先 `AddClient` 保留为薄封装，各桥与 WebUI 调用点一字未改。

## 判据（6 格）

    Frame 是 JSON-RPC 2.0 通知 + 帧完整性（单事件、\n\n 结尾）
    payload 原样嵌入（不是 JSON 字符串）—— 再 marshal 会让客户端解析两次
    event_id / event_type 必带（前者是 Last-Event-ID 续传的依据）
    Accept 判定（含 q 值、大小写）
    匿名 GET → 401（不能变成静默的匿名订阅）
    缺 Accept → 406（接错的客户端会静默收不到东西）

## 顺带修：TestAdvanceRecurrenceLunar 的时区缺陷（★ 今天第三次假红）

全量测试红了，查下来是**我今天早些时候改判据时引入的**，与本次改动无关。

农历换算必须按**本地公历日**算（`AdvanceRecurrence` 里那句
`eventTime.In(time.Local)` 就是这条规则）。库里读回的 EventTime 是 **UTC**
（DSN 用 `_timezone=UTC`），UTC 比本地晚 8 小时，跨零点时农历日差一天：

    start    (Local) = 2026-10-04        农历日 24
    after    (UTC)   = 2026-11-01 16:00   农历日 23   ← 断言没换算时区（错）
    after.In(Local)  = 2026-11-02 00:00   农历日 24   ← 正确

服务端代码一直是对的，是判据没照做。失败信息里现在打印时区，
免得下次要重新推导一遍。变异验证：去掉 `.In(time.Local)` → 红 1 ✓

（这条判据是农历的第三次假红了：3459605「断言要求不存在的农历日」、
今天早些「起点写死日期 + advanceToFuture 跳过过期月份」、现在「没换算时区」——
三次都是判据自己写错，代码三次都对。它依赖 Local 时区与「今天」，
天生脆弱，值得记着。）

## 验证

    go test ./...              14 包全绿
    go test ./internal/sse/    含新判据绿
    go test ./internal/mcp/    6 格新判据 + 原 19 格全绿
 2026-10-02 15:37:34 +08:00
JianFeeeee
457d1608f0 feat(mcp): MCP 集成进网关本体 —— POST /api/v1/mcp（Streamable HTTP） 
## 为什么要集成而不是独立进程

上一版（29ad8aa）是独立进程 `plugins/zcode-mail-bridge/mcp/server.mjs`，
用 HTTP 调本网关。四条真实成本：

1. **工具语义有两份**。桥里的 read_inbox / send_mail 是**手抄**网关的，
   抄错就是行为分叉 —— 已抓到两次：`connect_to_server` 只发
   `X-Agent-Secret` 头，而 `/agent/register` 只认 Bearer 或 body 里的
   secret ⇒ secret-only 的 Agent 必然 400。
2. **鉴权与收窄要再实现一遍**。工作区收窄、会话收窄、冷静期、配额住在服务端。
3. **多一跳 + 多一个故障点**。
4. **接入端仍要装东西**（node + 桥 + 环境变量）。

现在：工具**包装现有 handler**，同一份代码、同一套鉴权与收窄；
接入端只填一个 URL。

## 传输与实现（用户裁定）

- **Streamable HTTP**（规范 2025-06-18）：单端点 POST，通知回 202，
  请求回 JSON-RPC。
- **包装 handler**（不是直调 repo）：`newRequest` + `invoke` 造内部请求
  交给 `handler.GetInbox` / `SendMail` / … 于是 `AgentMayReadSession`、
  冷静期、配额、附件保护目录全部是同一条代码路径，不是复述。
- 手写零依赖 JSON-RPC（协议面只有 4 个方法），与本仓取向一致。

端点挂在 `AgentAuth` **之内**：必须与 /mail/send 同一套凭证，
否则就成了绕过收窄的旁门。

## 11 个工具，名字与参数与四桥逐字一致

`connect_to_server` 在这里只做一次真实读来确认连通性 —— 能调到它本身
就证明凭证已过（它是局内端点，不再需要 register）。

## ★ 端到端撞出并修掉的两个真 bug

**① `Tool.Run` 丢掉了身份**（本来写成 `context.Background()`）。
症状：每个工具调用都 Unauthorized，模型表现为「说连上了但读不到任何信」。

**② 路径参数没到位**：被包装的 handler 用 `chi.URLParam(r,"id")` 取 id，
而 `httptest.NewRequest` 造的请求**没过 chi 的路由** ⇒ `URLParam` 恒空
⇒ 任何带路径参数的工具都报「Invalid id」。

第②个的发现过程值得记：端到端测越权时，主人和越权者**都**返回
「Invalid id」。只看越权那一次会误判成「收得太紧」，进而把**正确的收窄改松**；
做对照才看出是参数没到位。

修法两处：`withRouteParams` 注入 chi RouteContext；`invoke` 里**不能**再
`WithContext(ctx)` —— 那会覆盖掉刚注入的 RouteContext。

**③ 发现并暴露了会话越权漏洞**（同批，单独提交 095213b）：
`AgentMayReadSession` 只比 `scope == target`，不问「你是不是参与方」，
而 session_id 由请求方给。对照实验 + 生产复核证实可读他人正文。

## 判据（13 格）

`internal/mcp/mcp_test.go`。真正在钉三件**只有集成才可能坏**的事：

1. MCP 不能成为越权旁门（工具参数里没有身份字段）。
2. 参数映射不许偷偷放宽/收紧（`attachment_ids` 被吞 ⇒ 附件静默不随信发出）。
3. 协议语义不许退化（工具失败必须 result+isError，不是 JSON-RPC error）。

`TestEveryErrorResponseCarriesID` 是被真 bug 逼出来的：曾用
`ID json.RawMessage` + `omitempty`，nil 时**整个 id 字段从 JSON 里消失**，
客户端会一直等这条的响应。遍历全部错误出口逐条验。

**变异验证**：

    Run 丢身份                    → 红 4
    工具失败回 JSON-RPC error     → 红 4
    read_inbox 丢 workspace 收窄  → 红 1
    id 泄露（tag+idPtr 同时失效） → 红 1 ★（真 bug 需两处同时失效，故两处防御都要留）
    去掉 withRouteParams          → 红 1
    invoke 里加回 WithContext     → 红 1

## 端到端（真实网关进程，临时库，备用端口 8199，不动生产）

    未认证 /mcp              → 401
    错误密钥                 → 401
    initialize               → 回显 2025-06-18
    notifications/initialized→ 202 且无响应体
    tools/list               → 11 个，带 annotations 与 required
    send_mail → read_inbox   → mcp-peer 通过 MCP 读到对方发来的信
    read_mail（带 session_id）→ 主人读到自己的信

## 未做

- 未删除旧桥 `plugins/zcode-mail-bridge/mcp/server.mjs`。它是 zcode 插件
  清单里声明的入口（`.zcode-plugin/plugin.json` 的 mcpServers），删掉会破坏
  该插件的组装。两者并存无害：桥仍走 HTTP，服务端这份是接入端零安装的那条路。
- 未部署（本提交只含代码）。
 2026-10-02 13:28:07 +08:00
JianFeeeee
de6b91516a feat(默认会话): 非邮件轮次用 /tmp 默认会话作合法 session_id —— 配套 15e4fe9 的收严 
`15e4fe9` 让未声明 session_id 的读信一律 403，而 homeagent 的工具**全局可调** ⇒
对话里自主调 read_mail/read_thread 时 `currentSessionID` 为空 ⇒ 403。
不能因此让「非邮件轮次读信」这个能力消失（它是 10-01 那个 read_inbox 修复的
用户可见部分），所以给它一个合法声明。

## 关键约束：workspace 能回落 cwd，session_id 不能

`session_id` 是 AgentMail 会话的 UUID，进程 cwd 给不出它 ⇒ 只能问服务端。
落点选 `/tmp`：非邮件轮次没有真实工作目录，而 /tmp 是中性落点（不属于任何真实
项目，不会把项目邮件混进来），且满足 `UnreadWorkspaces` 的 `workspace LIKE '/%'`
（能被寻址补投）。

## 服务端：`GET /api/v1/agent/session/default`

**复用**已有的默认会话语义（`FindOrCreateDefaultSession`，8 个测试覆盖），
只把它开放成可查询形状 —— 不新造概念。

★ 第一版调 `FindOrCreateDefaultSessionCreated`，判据当场报**每次都新建**
（连问两次得到两个不同 UUID）。根因：那个函数的复用条件含
`EXISTS (SELECT 1 FROM mails …)`，空会话不满足 ⇒ 永远「没找到可复用」。
改「先查后建」仍不够。想深一层：**根本不该建** —— 非邮件轮次若 `name@/tmp`
一封都没通过，收件箱本来就该是空的，不需要一条 id 才能表达「空」。
⇒ 改成**纯只读**：没通信过就返回 `session_id: null`。
GET 有副作用是坏味道，它会被桥每轮调一次。

同时把匹配 SQL 抽成 `defaultSessionMatchSQL` 共享常量：`FindExisting` 与
`FindOrCreate` 必须给出**同一个**答案，否则「查到的默认会话」与「发信落进去的
会话」会静默分叉（各写一份 SQL 的话，改一边不会红）。

## 桥（homeagent）：effectiveSessionID = 信封 → 默认会话

⚠ 取值函数**不发请求**。我第一版把 HTTP 塞进 `effectiveSessionID`，
`&Plugin{}` 构造的测试当场 nil panic，且 scopeQuery 变成「拼 URL 时顺带发请求」。
IO 移到装配期 `register()` 里的 `ensureDefaultSession()`。

⚠ `client == nil` 时**不标记已问** —— 那不是「答案是空」而是「还没资格问」，
标了会永久缓存空值。而 register() 里就会调它，真的会在插件加载阶段崩。

## 判据

服务端 6 格（含★「不是万能钥匙」：拿默认会话 id 去读别人的会话仍须 403 ——
少了这格，这个端点就是「声明一个合法会话然后读遍全场」的后门）。
homeagent 6 格。
三个变异各红 1 格：退回旧的整体放弃 / 未就绪也标记 / 默认落点与服务端不一致。

## 未改：pi / dsh / opencode

实测它们的裸奔已停止（pi 自 Sep 26、opencode 自 Sep 28，`[agent-scope]` 日志归零），
`getMailSessionId` 由 worker 闭包注入且只有一处装配点。dsh 待单独核。
 2026-10-02 01:09:19 +08:00
JianFeeeee
31939f2b10 服务端: 顶栏内容端点（一言句库缓存 + 个人签名）+ 修老库升级时序 bug 
用户裁定：
  · 「可以在服务器集成一言与签名，同时 app 本地缓存一部分」
  · 「摘要也应该放在顶部，显示摘要不显示一言，显示一言不显示摘要」
  · 「自动轮播，要有消失出现动画。同时注意，是纯文字不要加底」

新增端点
  · GET /api/v1/me/topbar → { quotes: [{text, source}], signature }
    一次给一批（默认 10 条），客户端拿去本地轮播 —— 轮播是秒级的，
    每条问一次服务器既浪费又会在断网时停下（而轮播的观感依赖"一直有下一条"）。
  · PUT /api/v1/me/signature —— 改个人签名（「我的」页用）
  · quotes 表（句库缓存）+ users.signature 列

设计要点
  · 一言**落库缓存**：库里有就**不打外网**（常态路径）；不足 20 条才去
    hitokoto 补一批。补失败**不影响返回** —— 装饰性内容不该成为失败点
    （顶栏少轮播内容是小事，整个接口 500 会让 App 启动时顶栏坏掉）。
  · 签名存 users 而不是 quotes 表：它是**用户资料**（跟账号走、
    在「我的」页可编辑），放 quotes 里会让"改签名"变成"改一条 quote"。
  · 限长 80 字，超了**拒绝且不落库** —— 顶栏是一行，静默截断比报错更坏
    （用户以为存进去了，实际存的是被砍过的）。
  · 迁移改两处（本仓既定纪律）：init_sqlite.sql 给新库 +
    sqliteAddColumns 给老库。

★ 顺手修掉一个既有 bug（不是本次引入的）
  「从很旧的库升级会直接启动失败」：
      migrate sqlite (语句 #10 … idx_sessions_path_alias_uniq):
        SQL logic error: no such column: workspace

  根因是**时序**：这条索引引用 sessions.workspace，而那是**后补的列**
  （sqliteAddColumns），索引却住在 init_sqlite.sql（在补列**之前**执行）。
  新库没事（建表时就有该列）；老库直接炸，且报错指向索引名 ——
  看着像索引写错，实际是顺序问题。
  生产库一直没暴露，因为它早就补过列了（暴露面只有"从很旧的库升级"）。

  证据：`git stash` 掉当天全部改动后**同样复现**。
  修法：把索引搬到 migrate.go 的 sqliteAddIndexes（那个列表在补列之后跑）。

测试（internal/handler/topbar_test.go，5/5）
  ① 签名账号隔离 —— bob 没设过就该是空串，不能串到 alice 的
     （本仓 user_appearance 那轮踩过"多账号共用一份"，同一形状不许重演）
  ② 有货不打外网（灌 25 条，断言返回不超过 quoteBatchSize）
  ③ ★ 外网挂了仍返回 —— 耗时 4.01s = quoteHTTPTimeout，
     证明它真去拉了并按超时降级，不是假绿
  ④ 限长：81 字拒绝**且不落库**；80 字（边界）接受
  ⑤ 未登录读写都 401

★ 两个踩过的坑（记进注释了）
  1. `init_sqlite.sql` **只能写 `--` 行注释**：切语句器只跳过 `--` 开头的行，
     块注释的文字会被当 SQL 执行。我第一版用 `/* */`，新库初始化直接失败，
     且报错指向一个完全无关的地方（no such column: workspace）。
  2. 该 SQL 文件的 splitStatements 也会被注释里的反引号/连续减号破坏。
 2026-09-25 16:29:19 +08:00
JianFeeeee
2da38bba83 农历走服务端端点：换算只在服务端做一次（两边各写一遍天文算法迟早差一天） 
用户定的方案：「加 api 端点」。

## 为什么不移植到 ArkTS

`lunar-javascript` 的 `lunar.js` 有 **43 万字节**，内部是**日月位置的级数展开**
（实测：全文件最大的数字字面量是 16KB 的系数数组，**不是**"某年到某年的月长表"）。
即"照搬一张小数据表"这条路**不存在** —— 移植等于在 ArkTS 里再实现一遍天文算法。
两份实现迟早会在某个闰月或某个朔日上差一天，而那种错**表现为日期错位、不是报错**，
界面上完全看不出（用户得自己去查日历才知道）。

所以：`GET /api/v1/calendar/lunar?from=&to=`（服务端 `internal/lunar`，同一作者的 lunar-go）。

## 形状是「按日期键索引的映射」，不是数组

客户端拿到 `map[iso] -> 标签` 直接按格子键查，不用自己遍历比对。
`text` 字段是**格子里直接显示的那个串**（初一=月名、其余=日名）——
由服务端定，两端同源。客户端各拼一份的话，同一天在两边日历上可能长得不一样
（例如闰月到底写不写「闰」）。

几个刻意的取舍：
- **不设默认 from/to**：默认范围会让「我要 3 月」与「服务端以为我要这个月」悄悄不一致；
- 入参只收 `YYYY-MM-DD`（**日期键**，不是 RFC3339）：农历是"这一天是农历几号"的
  纯日期语义，混用时间戳会被时区挪一天；
- 换不出来的日子**不进 map**（客户端查不到 ⇒ 那格不显示农历），而不是塞空对象 ——
  空对象会让客户端以为"有农历、只是没内容"；
- 区间上限 400 天（不是安全边界，是防客户端传十年前到十年后）。

## 判据（`server/internal/handler/lunar_test.go`）

参照物是服务端的 `internal/lunar`（权威实现），**不抄一份答案表** —— 库升级时判据跟着走。
钉的点各自对着一个会静默出错的错法：
- `Full` 与权威实现逐字一致（5 个日期，含春节、跨世纪、29 天月的边界年份）；
- 日名表覆盖 1..30 且**五种前缀形态都在**（WebUI 那版漏过「二十」）；
- ★ 初一显示**月名**、其余显示**日名**（与 WebUI `cellLunarLabel()` 同一口径）；
- 闰月必须带「闰」字（不带的话闰六月与六月在格子里一样）；
- 极端值（公元 1 年 / 1900 / 2100 / 9999）**不许 panic**，且换出来时文字里不许含
  「无效/NaN」这类失败标记。

★ 最后一条我第一版**写错了**：断言「`time.Time{}` 应当换不出来」，实测库**换得出来**
  （0001-01-01 → 「〇年冬月十八」）—— 我断言的是自己的想象而不是实际行为。
  改成断言真正的契约（不 panic / 失败就不给 / 给了就得是真结果）后才对。

## 客户端

`LunarLabels` / `LunarRangeResponse` 两个模型 + `CalendarApi.listLunar(fromIso, toIso)`；
`CalendarPage` 在 `loadEvents()` 之后**不 await** 地拉农历（附加信息不该拖慢事件列表），
失败**不算 `this.error`**（否则"农历服务抖一下"会变成"整个日历打不开"），
只写 hilog 留痕。区间按**网格**取（不只本月 —— 月视图首尾显示上/下月格子）。
 2026-09-18 11:23:12 +08:00
JianFeeeee
46fa7fa729 feat(push): 可选、配置式、多厂商的推送通道（HMS 为首个实现） 
用户要求：推送密钥必须是可选项（自部署后端不能写死推送方式），且要支持
多厂商配置式接入 —— 每个用户各自部署服务器、自己选厂商、自己配凭证。
所以落地成：

· internal/push：通道抽象 + 工厂表（RegisterType），加厂商不改配置层与端点形状；
  HMS 只是第一个实现（internal/push/hms.go）
· 配置在 PUSH_CONFIG（默认 <AGENTMAIL_DATA_DIR>/push.json），一项一个厂商，
  凭证走文件（app_secret_file / files.*，建议 600）；环境变量只是可选覆盖
· 没配 = 整条推送路径连一次查库都不发生（shouldDispatch 早退）；
  单项配错（未知类型/密钥读不到/enabled:false）只跳过那一条，不影响启动
· push_tokens 表带 provider 维度 + 三个 /me/devices/push-token 端点；
  没配推送时端点照存并回 enabled:false（登记成功 != 服务端开了推送）
· notify.Recipients 末尾异步挂钩：收件人名单直接用 SSE 那份 seen（两条通道
  共用同一份"谁该收到"的判据）；失败只记日志，绝不拖住收信

HMS 的形状是拿真凭证打线上接口问出来的（v1 + message.token[] + testMessage；
payload/target 形状 v1 不认、v2 要服务账号 JWT）。未上架应用必须 test_message=true，
单批 ≤10 token（MaxTokensPerRequest 声明）、每日 1000 条兜底（项目级额度）。
实测：App ID + App Secret 能换到 access_token（3600s）；形状被线上服务接受。

判据：repo 6 条 + push 12 条 + handler 3 组，全部做过**变异验证** ——
过程中抓出两条假判据（异步分发与 t.Cleanup 赛跑而假绿；密钥文件优先级没被覆盖）
并补掉。Go 全量测试与 go vet 干净。

★ 未验：端到端真机送达（需要真机 token + 客户端按 com.jianf.agentmail 重编并签名，
签名指纹还要在 AGC 登记）—— 从未真正发出过一条能到达设备的推送。
详见 docs/HMS-PUSH-PLAN.md 的「实现状态」一节。
 2026-09-15 11:21:00 +08:00
JianFeeeee
1f48c5c4ff feat(sandbox): am-sandbox —— 给命令套 Landlock 内核边界（界内可写、界外 EACCES） 
「工作区档」此前名不副实：档位表写「本目录内可动、越界要问人」，而 pi 这一路只能按
**工具名**判（bash/write/edit 一律问人），因为命令的影响范围无法从文本静态判定
（`cd /工作区 && rm -rf /opt/x` 以"进工作区"开头）。pi 自己**故意**不内置沙箱
（docs/security.md §No Built-in Sandbox：进程内的部分沙箱会被误解成安全边界，
"Real isolation needs to come from the operating system or a container boundary"）——
dsh 是把沙箱放进自己的运行时；这个二进制补的是 pi 这一侧的**宿主**部分。

## 语义

写：只有 `--rw` 列出的目录（含子树）与 `--rw-file` 列出的文件可写，其余写操作一律
EACCES（内核判）。读与执行不限制 —— Landlock 只做白名单式加法，要连读都挡住得靠
容器/挂载命名空间。套不上边界时 **fail closed**（退出码 126，不执行命令）：静默裸跑
会让"档位=workspace"变成谎话，而谎话比做不到更危险。

## 判据

- 行为 `deploy/check-sandbox.sh`：19 项全绿 —— 界内可写/子目录递归/rename+删除、
  读界外、执行、写 /dev/null；界外新建/建目录/覆盖/删除/删目录/跨边界 rename/
  软链接逃逸/子进程继承；**对照**（不套边界时那些"必须被拒"的命令必须成功，否则
  判据可能只是环境本来就只读）；fail-closed 那条（rw 不存在 ⇒ 126 且命令未执行）。
- 算法 `cmd/am-sandbox` 单测：按 ABI 逐位裁剪、文件目标不得带目录类权限、
  allowed ⊂ handled、参数解析。

## 过程中撞到两个"看着能过"的坑

1. `--rw-file` 任意文件 → add_rule **EINVAL**：文件目标只能用文件类权限
   （MAKE_*/REMOVE_*/REFER 是目录类），而错误信息只有 "invalid argument"，
   看不出是权限位不匹配。单测里"文件权限必须是 handled 的子集"就是拦它的。
2. ★ 判据自己翻车：`"$SB" … 2>&1 | grep -q "Permission denied"` 在
   `set -o pipefail` 下 —— **grep 命中即退出 → 左侧 EPIPE 失败 → 整条管道判失败**
   ⇒ 7 条"界外必须被拒"全被判成"没被拒"。改成先收输出再匹配，顺带打印真实输出。

## 已知边界（写进文件头 + 判据输出留痕，不假装没有）

- 元数据（chmod/chown/utimes）不受 Landlock 管辖：界外文件**内容**改不了，
  但**模式位**能改
- 网络出向不受限
- 界内**已存在**的、指向界外文件的硬链，经界内路径写入会改到界外（路径式沙箱固有）
- 本机 ABI=2（无 TRUNCATE）；实测 `truncate` 越界仍被拒（coreutils 先 open 写 ⇒
  WRITE_FILE 挡住），所以那个缺口比纸面上窄
- **读不限制** ⇒ 以 root 跑的 agent 仍能读整机（含 /etc/agentmail/*.env）。沙箱在这里
  的价值是"界外留不下脚印"，不是"拿不到东西" —— 要后者得上容器

## 接线

`redeploy-gateway.sh` / `install.sh` 在**边界判据真跑绿了**之后才装到
`/opt/agentmail/bin/am-sandbox`（装一个套不上边界的工具等于发空头支票）。
pi 桥的接线（按档位把 worker 套进边界）还没做 —— 见随后的报告。
 2026-09-14 23:33:11 +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
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
0f379a2ca0 fix(static): 给前端加缓存策略，修掉「换了新前端但用户仍看到旧界面」 
# 起因

用户问「webui 更新了吗」。实测三个入口（本机 / LAN / 公网 mail.jianfgit.xyz）
服务的都是同一份新构建（`index-DUb2s9Ly.css`，DOM 里有 `.app-backdrop`，
`--radius-card` 已生效）—— **确实已更新**。但响应头显示：

    HTTP/1.1 200 OK
    Content-Type: text/html; charset=utf-8
    Vary: Origin
    （没有 Cache-Control）

入口页没有任何缓存指令 → 浏览器走启发式缓存，可能长期使用旧的 HTML。
而 Vite 给资源按内容加哈希，**新构建生成新文件名**：旧 HTML 引用旧文件名，
于是整站被钉死在那一代资源上。这类故障没有任何报错，只有人肉硬刷新才能发现，
而且每次部署都会重演一次。

# 修法：区分两类资源，而不是一刀切

  - **入口页 `no-cache`**（不是 `no-store`）：可以落盘，但每次必须先回源确认。
    它只有 ~2KB，回源代价可忽略，而它决定了用户拿到哪一代资源。
  - **带内容哈希的 `/assets/*` 永久缓存**（`max-age=31536000, immutable`）：
    内容变了文件名就变，不存在「缓存了旧内容」的问题，连回源都不需要。
  - **不带哈希的资源 `no-cache`**：`STATIC_DIR` 指向开发目录时文件名可能没有哈希，
    给它们 immutable 会让改动永远不生效 —— 那比缓存旧资源更难查。

哈希判据（`-[A-Za-z0-9_-]{8,}\.[a-z0-9]+$`）刻意**不宽松**：只有真正像
Vite 产出的内容哈希才配 immutable。`short-ab12.css` 这种（哈希不足 8 位，
更像版本号或缩写）按无哈希处理。

# 测试

`internal/static/cache_test.go` 10 条路径判据 + 3 条响应头断言，含两组
**反向对照**：
  - 带哈希 → immutable，无哈希 → no-cache（证明判据有区分力，不是恒真）
  - 入口页必须是 `no-cache` 而**不是** `no-store`（后者连磁盘缓存都不用，
    每次全量重取）

# 验证

- `go vet` 干净；`go test ./... -count=1` 全量通过（新增 internal/static 用例）
- 部署后线上实测三处响应头：
  - `/` → `Cache-Control: no-cache`
  - `/assets/index-DUb2s9Ly.css` → `public, max-age=31536000, immutable`
  - `/assets/agentmail.svg`（无哈希）→ `no-cache`
 2026-09-12 09:13:56 +08:00
JianFeeeee
4186ad4784 fix(setup): 首个管理员的创建只允许 Gateway 本机 
# 之前的缺口

`POST /api/v1/setup/admin` 是公开路由，唯一的门是「系统还没有任何用户」。
Gateway 监听 `*:8180`，于是局域网里任何人可以绕开 nginx 直接调它。
本机已初始化时它只回 409，所以这条是纵深防御；但在**尚未初始化**的部署上，
它是「谁先提交谁成为管理员」——一个可被抢注的管理员入口。

# 为什么不是收紧监听地址

`.106` 上的反代（公网 `mail.jianfgit.xyz`）与本机鸿蒙客户端都直连
`192.168.2.60:8180`，把监听收到 127.0.0.1 会把这两条入口一起切断。
缺口在端点本身，不在监听面，所以只收紧端点。

# 改动

- 新增 `middleware.LocalOnly`：只有真实 TCP 对端为回环地址才放行。
- 新增 `middleware.CapturePeerAddress`，**注册在 `chimw.RealIP` 之前**。
  RealIP 会信任 `X-Forwarded-For` 并改写 `RemoteAddr`，直接读它等于让外部
  调用者用一个请求头冒充本机；所以先存原始连接地址，安全判断只认那份。
- `SetupAdmin` 的注释同步：本机限制在路由层，`NeedsSetup` 保留为第二道防线。
- 测试（`localonly_test.go`）按生产中间件顺序组装链，覆盖：
  IPv4/IPv6 回环放行、局网拒绝、**伪造 X-Forwarded-For 仍拒绝**、
  非法地址拒绝，以及未装 CapturePeerAddress 时 fail closed。

# 验证

- 回环 `/setup/admin` → 409（进入处理器，系统已初始化）
- LAN `/setup/admin` → 403
- LAN + `X-Forwarded-For: 127.0.0.1` → 403
- LAN `/setup/status` → 200（登录页判断是否显示向导仍正常）
- 登录 + 收件箱 → 200；Go 全量测试与 vet 通过；已部署，四桥/SSE 正常
 2026-09-11 15:49:26 +08:00
JianFeeeee
f9d757b5e5 chore: directory migration - gateway→server, web→client/electron 2026-09-08 19:16:35 +08:00