MailUI4Agents

jianf/MailUI4Agents

Fork 0

Commit Graph

Author	SHA1	Message	Date
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	0997d441af	docs(build): 安装包嵌的是前端快照 —— 前端改动后必须重打，并给出自查命令	2026-09-12 08:10:27 +08:00
JianFeeeee	dacf6c0e1f	feat(client): 打通 Electron 安装包打包，并留下构建文档 # 背景 Electron 桌面安装包一直没打出来过（`release/` 为空，只有 web bundle）。这次把它跑通，并验证了产物本身而不只是"文件存在"。 # 改动 package.json 补齐 electron-builder 需要的元数据（缺哪个就会让某个 target 直接失败，而报错不一定指向字段本身）： \| 字段 \| 位置 \| 不填的后果 \| \|---\|---\|---\| \| `description` \| 根 \| deb 描述为空 \| \| `author`（含 email） \| 根 \| deb 缺 maintainer \| \| `homepage` \| 根 \| deb 直接失败：`Please specify project homepage` \| \| `desktopName` \| 根 \| 窗口无法与 .desktop 关联（缺 `StartupWMClass`） \| \| `linux.syncDesktopName` \| `build.linux` \| 同上 \| \| `linux.synopsis` \| `build.linux` \| deb 描述只有一行 \| 新增 `client/electron/BUILD.md`：记录构建命令、本机两个坑（见下）、元数据清单、两个产物的实质区别、以及验证产物的方法。 # 两个产物（已在 release/，被 .gitignore 排除） - `AgentMail-0.1.0.AppImage` 122MB，有效 x86-64 ELF、可执行位已设 - `agentmail-web_0.1.0_amd64.deb` 100MB，Maintainer/Homepage/Depends/两行 Description 齐全实测的实质区别（不是猜测，来自解包对照）： \| \| AppImage \| deb \| \|---\|---\|---\| \| `.desktop` Exec \| `AppRun --no-sandbox %U` \| `/opt/AgentMail/agentmail-web %U` \| \| Chromium 沙箱 \| 禁用（squashfs 无法保留 setuid 的 chrome-sandbox） \| 启用（postinst 按能力 `0755` 或 `4755`，并装 AppArmor 配置） \| \| 卸载 \| 删文件 \| postrm 清理 alternatives / AppArmor / desktop-mime 库 \| 结论写进文档：对外分发优先 deb。 # 验证（不只查存在性） - AppImage：`--appimage-extract` 解包成功；`resources/app.asar` 8.5MB； asar 清单里 `/dist/index.html`、`/dist/assets/{index,CalendarView}.js`、 `/dist/assets/{agentmail.svg,favicon.ico,apple-touch-icon.png}`、 `/electron/{main,preload}.cjs` 齐全；`index.html` 里 DOCTYPE 仍是大写（即格式化器修复也进了包） - deb：`dpkg-deb --info/--contents` 核对元数据与布局；7 档图标尺寸齐全；读 postinst 确认沙箱策略与 AppArmor 安装 # 环境坑（已写进 BUILD.md）本网络下 `SHASUMS256.txt` 不可达（直连 20s 超时、走代理也失败），而 electron 构件本身 0.8s 就拿到（HTTP 206）。`@electron/get` 即使命中缓存也会取校验文件 → 构建卡 10 分钟后失败。用命令行覆盖绕过： npx electron-builder --linux -c.electronDownload.isVerifyChecksum=false 刻意不写进 package.json —— 那会让今后每次构建都跳过完整性校验。一次性绕过网络限制不该固化成永久弱化的默认值。代价已写进文档（关校验后可被篡改镜像在 TLS 之外替换构件）。 # 待用户确认的占位值 - `author.email` 用了仓库自身的 git 身份 `jianf@noreply.localhost` —— 容器占位邮箱，不是真实联系地址。项目里没有可用的真实邮箱，我没有编造一个。 - `homepage` 用 git remote 的唯一真实地址（内网 Gitea `192.168.2.106:3000`）。两者对外分发前都应替换。	2026-09-12 01:17:49 +08:00

Author

SHA1

Message

Date

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

0997d441af

docs(build): 安装包嵌的是前端快照 —— 前端改动后必须重打，并给出自查命令

2026-09-12 08:10:27 +08:00

JianFeeeee

dacf6c0e1f

feat(client): 打通 Electron 安装包打包，并留下构建文档

# 背景

Electron 桌面安装包一直没打出来过（`release/` 为空，只有 web bundle）。
这次把它跑通，并验证了产物本身而不只是"文件存在"。

# 改动

**package.json 补齐 electron-builder 需要的元数据**（缺哪个就会让某个 target
直接失败，而报错不一定指向字段本身）：

| 字段 | 位置 | 不填的后果 |
|---|---|---|
| `description` | 根 | deb 描述为空 |
| `author`（含 email） | 根 | deb 缺 maintainer |
| `homepage` | 根 | **deb 直接失败**：`Please specify project homepage` |
| `desktopName` | 根 | 窗口无法与 .desktop 关联（缺 `StartupWMClass`） |
| `linux.syncDesktopName` | `build.linux` | 同上 |
| `linux.synopsis` | `build.linux` | deb 描述只有一行 |

**新增 `client/electron/BUILD.md`**：记录构建命令、本机两个坑（见下）、
元数据清单、两个产物的实质区别、以及验证产物的方法。

# 两个产物（已在 release/，被 .gitignore 排除）

- `AgentMail-0.1.0.AppImage` 122MB，有效 x86-64 ELF、可执行位已设
- `agentmail-web_0.1.0_amd64.deb` 100MB，Maintainer/Homepage/Depends/两行 Description 齐全

**实测的实质区别（不是猜测，来自解包对照）**：

| | AppImage | deb |
|---|---|---|
| `.desktop` Exec | `AppRun --no-sandbox %U` | `/opt/AgentMail/agentmail-web %U` |
| Chromium 沙箱 | **禁用**（squashfs 无法保留 setuid 的 chrome-sandbox） | **启用**（postinst 按能力 `0755` 或 `4755`，并装 AppArmor 配置） |
| 卸载 | 删文件 | postrm 清理 alternatives / AppArmor / desktop-mime 库 |

结论写进文档：**对外分发优先 deb**。

# 验证（不只查存在性）

- AppImage：`--appimage-extract` 解包成功；`resources/app.asar` 8.5MB；
  asar 清单里 `/dist/index.html`、`/dist/assets/{index,CalendarView}.js`、
  `/dist/assets/{agentmail.svg,favicon.ico,apple-touch-icon.png}`、
  `/electron/{main,preload}.cjs` 齐全；`index.html` 里 DOCTYPE 仍是大写
  （即格式化器修复也进了包）
- deb：`dpkg-deb --info/--contents` 核对元数据与布局；7 档图标尺寸齐全；
  读 postinst 确认沙箱策略与 AppArmor 安装

# 环境坑（已写进 BUILD.md）

**本网络下 `SHASUMS256.txt` 不可达**（直连 20s 超时、走代理也失败），
而 electron 构件本身 0.8s 就拿到（HTTP 206）。`@electron/get` 即使命中缓存
也会取校验文件 → 构建卡 10 分钟后失败。用命令行覆盖绕过：

    npx electron-builder --linux -c.electronDownload.isVerifyChecksum=false

**刻意不写进 package.json** —— 那会让今后每次构建都跳过完整性校验。一次性绕过
网络限制不该固化成永久弱化的默认值。代价已写进文档（关校验后可被篡改镜像在
TLS 之外替换构件）。

# 待用户确认的占位值

- `author.email` 用了仓库自身的 git 身份 `jianf@noreply.localhost` —— 容器占位邮箱，
  **不是真实联系地址**。项目里没有可用的真实邮箱，我没有编造一个。
- `homepage` 用 git remote 的唯一真实地址（内网 Gitea `192.168.2.106:3000`）。

两者对外分发前都应替换。

2026-09-12 01:17:49 +08:00

3 Commits