dengshangli 邮件模板兼容性测试
概述
将本地 .html 邮件模板逐份发送到指定测试邮箱，并用可审计清单区分“服务器已接受”与“收件箱已送达/渲染正常”。默认适配 https://email-sent-chi.vercel.app/，也可使用用户指定的同类页面。
REQUIRED SUB-SKILL: 使用 browser:control-in-app-browser 完成网页操作。
浏览器选择是固定约束：直接使用应用内置浏览器（IAB）。 初始化浏览器运行时后，显式调用 agent.browsers.get("iab")；不要调用 getForUrl()、getDefault()，也不要先尝试 Chrome。若 IAB 不可用，停止并报告，不要自行切换到 Chrome。
工作流
盘点文件
- 用
rg --files -g '*.html' -g '*.htm'枚举用户指定目录；默认不递归目录外部。 - 记录稳定排序后的完整文件名、绝对路径和大小。
- 对照页面限制校验扩展名与大小；异常文件先报告，不擅自修改模板。
- 用
明确发送口径
- 收件人使用用户明确提供的测试邮箱，并去重。
- 每个模板上传一次，收件人字段同时填写全部测试邮箱。
- 邮件标题使用完整文件名，包括
.html后缀，除非用户另有要求。 - 预计投递数 = 模板数 × 收件人数。
准备浏览器
- 显式选择 IAB：
browser = await agent.browsers.get("iab")，完整读取其documentation()后再操作。 - 打开目标页面，读取 DOM 快照，确认上传、收件人、标题和发送控件。
- 文件上传属于用户初始请求明确授权的范围时，无需重复确认。
- 在点击“发送邮件”前，按浏览器确认策略进行一次批次级最终确认，列出模板数、收件人和预计投递数。
- 显式选择 IAB：
逐份上传与发送
- 先监听
filechooser，再点击可见的label[for="html-file"]或页面标注的可见上传区域，然后用绝对路径设置文件。 - 不要优先点击带
sr-only的隐藏input[type="file"]；它可能无法触发文件选择事件。 - 上传后从页面确认显示的文件名，再填写同名标题。
- 点击发送一次，等待按钮恢复并读取明确结果；不要因超时直接重复点击。
- 只有页面出现“邮件服务器已接受 N 封邮件”且
N等于收件人数，才把该模板记为“服务器已接受”。
- 先监听
失败恢复
- IAB 无法捕获文件选择器时，读取页面快照并检查可见上传标签；不要切换到 Chrome。
- IAB 本身不可用或连接失败时，停止并向用户报告当前阻塞。
- 结果不明确时标记“待核实”，先检查页面状态；未证明失败前不得重发，以免重复邮件。
- 明确失败只重试当前模板；保留已成功集合，从未成功项继续。
- CAPTCHA、登录或权限阻塞时按浏览器规则暂停并交接给用户。
验收
- 核对成功集合与原文件清单，确保遗漏为零且没有重复。
- 报告模板数、收件人数、预计投递数、服务器接受数、失败数和待核实数。
- 不把“服务器已接受”等同于“已送达”。若用户要求兼容性结论，再检查各测试邮箱中的送达、布局、字体、图片、链接、深色模式与移动端表现。
快速检查
| 检查项 | 通过条件 |
|---|---|
| 文件 | 扩展名和大小符合页面限制 |
| 标题 | 等于当前完整文件名 |
| 收件人 | 与确认清单完全一致 |
| 单模板结果 | 页面接受数等于收件人数 |
| 批次结果 | 成功 + 失败 + 待核实 = 模板总数 |
| 最终清单 | 无遗漏、无未说明重复 |
常见错误
- 通过
getForUrl()或getDefault()选中 Chrome：必须显式使用agent.browsers.get("iab")。 - 点击隐藏文件输入框后反复重试：改点可见 label，并在点击前监听
filechooser。 - 用固定等待时间判断成功：轮询按钮恢复与明确成功提示。
- 把一次页面成功提示当成整个批次成功：逐模板记录结果。
- 网络超时后立即重发：先标记待核实，避免重复发送。
- 只验证 SMTP 接受就声称兼容：兼容性必须以各邮箱实际渲染为准。