plugin-email: 实现 SMTP transport —— 设置页可选 SMTP 但后端无实现

[baozhoutao]

问题

plugin-email 目前只有 Resend / Postmark 两个真实投递 transport,没有 SMTP transport。但 Mail Delivery 设置页(packages/services/service-settings/src/manifests/mail.manifest.ts)把 SMTP 列为默认 provider,并提供 host / port / TLS / username / password 完整表单——用户填完保存后,transport 实际原地不动(仍是 LogTransport),邮件只写日志和 sys_email 表,不会真正发出。界面承诺与后端实现之间存在缺口。

代码里的现状注释(packages/plugins/plugin-email/src/email-plugin.ts → applyMailSettings):

No SMTP transport ships in core; … Users wanting real SMTP install @objectstack/plugin-mail-smtp and configure it via constructor opts.

而 @objectstack/plugin-mail-smtp 这个包在仓库中并不存在,该指引目前无法落地。

影响

• 选择 SMTP 的用户会误以为已配置成功(表单校验通过、保存成功),实际邮件静默不发——declared-but-not-delivered。
• 国内部署场景无任何可用发信通道:Resend / Postmark 均为国外 SaaS,国内可达性与对国内邮箱(QQ / 163 等)的送达率均不可靠;国内正路是企业邮箱或阿里云邮件推送 / 腾讯云 SES 的 SMTP 通道,SMTP 一通即全部打通。

建议范围

1. 在 plugin-email 新增 SmtpTransport(实现 IEmailTransport),支持 host / port / secure(TLS) / user / password,与 mail 设置命名空间现有字段(smtp_host / smtp_port / smtp_secure / smtp_user / smtp_password)对齐。
2. applyMailSettings 中 provider === 'smtp' 分支从「no-op + 日志」改为真实构建/热替换 SMTP transport;mail/test 动作(发送测试邮件)同步走通。
3. CLI serve 装配路径(OS_EMAIL_PROVIDER=smtp + 相应 env)打通。
4. 实现方式待定:引入 nodemailer 依赖,或按仓库零依赖偏好(Resend/Postmark 均为纯 fetch)自研最小 SMTP 客户端——需要权衡 STARTTLS / AUTH 的实现成本。

不在本 issue 范围

设置页还列出 SendGrid / Amazon SES 选项,同样后端无实现——属另一问题,按一事一议另行处理(SMTP 打通后,这两家也可直接走各自的 SMTP 端点作为过渡)。

[os-zhuang]

认领:PM 循环第 1 轮
会话:session_017MCKJaEomEqg4tvz4SzdNd
分支:claude/issue-5087-smtp-transport
Worktree:objectstack-issue-5087
域:domain:services(落地包 packages/plugins/plugin-email,按「域 = 修复落地的包」定级,不按标题词汇)
文件面:packages/plugins/plugin-email/**、packages/services/service-settings/src/manifests/mail.manifest.ts、packages/cli/src/commands/serve.ts、content/docs/deployment/environment-variables.mdx、.changeset/(越界即停,报告说明)

分诊:前提核验(对 origin/main @ 30ff55b)

issue 描述逐条属实,无过时前提:

• git grep "SmtpTransport" origin/main -- packages/ 零命中;反查邻近词 ResendTransport / PostmarkTransport 命中正常,零命中成立。
• @objectstack/plugin-mail-smtp 全仓只在注释与文档里出现(email-plugin.ts:478/499、content/docs/deployment/environment-variables.mdx:127/134),没有任何包,该指引确实无法落地。
• mail.manifest.ts 的 provider 默认值就是 'smtp',smtp_host 还是 required: true;applyMailSettings 对 smtp 走的是 no-op 分支;mailTestActionHandler 一路返回 ok: true + 「Wire @objectstack/plugin-mail for actual delivery」——表单校验通过、测试按钮报成功、邮件不发,declared-but-not-delivered 成立。
• 这几个文件今日无合并churn(最近一次 packages/plugins/plugin-email 相关合并是 feat(spec,runtime,hono)!: 入站 rateLimit 从零建 seam —— 授权预算真正产生 429 (#4910, #4937) #5006),不存在同日改写。

顺带核实、不构成额外工作:smtp_password 虽未写 encrypted: true,但 SettingsService 的注册逻辑是 if (spec.encrypted || spec.type === 'password'),type: 'password' 已隐式入 encryptedKeys,静态存储侧无缺口——不要为此改 manifest。

决策:第 4 条(nodemailer vs 自研最小 SMTP 客户端)取 nodemailer

这一条不上升给维护者 —— 它不改变产品语义,也不改变公共契约形状(两种做法都实现同一个既有的 IEmailTransport),且仓库既有规范已经给出答案。这是 PM 的决定,维护者拥有否决窗口而非审批门。

轴一 · 项目长远合理性。 「仓库零依赖偏好」经核验不是仓库规范:plugin-auth 直接依赖 better-auth / jose / @noble/hashes,driver-sql 依赖 knex 并把 pg/mysql2/tedious 列 peer,plugin-hono-server 依赖 hono。Resend/Postmark 之所以是纯 fetch,是因为那两家本身就是 HTTP API,不是因为存在禁依赖的规定。方向上,ADR-0012 明确记载「M1 ships smtp and sendgrid transports in core,SMTP is non-negotiable for on-prem/air-gapped(using nodemailer)」;ADR-0030 取代它的是分层与收件箱漂移部分,对 transport 只字未改,故该方向未被推翻。反过来,自研 SMTP 要正确覆盖 STARTTLS 协商、AUTH PLAIN/LOGIN/CRAM-MD5、MIME multipart、quoted-printable/base64、RFC 2047 中文主题头编码、dot-stuffing、超时与连接复用——这正是 Prime Directive #5 所禁的临时补丁式选项。

轴二 · 防 AI 犯错。 半成品 SMTP 客户端会把本 issue 报的缺陷下沉一层:它对多数服务器可用、只对 163/QQ 这类对 AUTH 与 TLS 行为挑剔的服务器静默失败,比现在这个「原地不动」更难被发现,也更容易被后来的 agent 用「放宽一点就通了」的方式改坏协议实现。成熟库 + 响亮错误,是让 AI 在结构上更难写错的那一侧。

配套约束(交派发词):nodemailer 作为 plugin-email 的正式 dependency,但在 SmtpTransport 内部惰性 await import(),使非 SMTP 部署与非 Node 运行时不会加载 node:net/node:tls;任何构建失败一律响亮——绝不允许回落成 LogTransport 后继续报成功,那等于原样保留本 issue 的缺陷。

派发中(os-dev / opus),PR 落地后回帖。

---

Generated by Claude Code