智能体发邮件实录：两次静默失败，和一套从报错里挖 schema 的笨办法

让智能体学会发邮件这件事，卡住我的不是 SMTP 协议，是两个「看起来配好了」的静默失败。排查过程和最终能跑的配置全贴在下面，改改账号就能用。

1. 起点：智能体的产出需要一条到达通道

场景很具体：我这边有几个定时任务每天产出报告，之前靠 IM 消息和本地文件交付。IM 依赖登录态，文件没人主动看。邮件是最稳的通道——不依赖会话、天然存档、还能转发给协作的人。

选型我选了 himalaya，开源的终端邮件客户端，Rust 写的单二进制。理由就一条：配置支持 password.cmd，密码从 macOS 钥匙串动态取，配置文件里不留明文。终端发信也简单，MML 格式管道喂进去就行。

然后我在配置上栽了两次，都是静默失败。

2. 第一次静默失败：旧文档喂给了新二进制

我库里存过一份 himalaya 配置笔记，当初照着 v1 文档写的：accounts 表里平铺 backend.type = “imap” 这类键。v2.1.0 的反馈是 No backend matching 'auto' is configured。这句话的杀伤力在于它读起来像「你没配置」，我第一反应是查文件路径、表名拼写，查了三轮才发现方向全错——不是没配，是 schema 整个不认。

判别方法很朴素：跑 himalaya account list，账号名都在，BACKENDS 列是空的。名字读到了，说明路径和 TOML 语法没问题；后端列空，说明这一版根本不认识这些键。v2 把配置 schema 重写了：server 从子表变回 host:port 字符串，认证从平铺键变成 sasl 枚举表，password 从明文键变成 raw/cmd 二选一。我那份笔记整份作废。

这轮教训单独记一条：CLI 工具跨大版本，别信任何旧文档——包括你自己当年存的笔记。文档的保质期跟二进制绑定，跟「当初写得对不对」无关。

3. 从报错里挖 schema：故意配错，逐层逼近

v2 当时没有把每个键的写法列全，我用了笨办法：故意配错，把报错当文档读。Rust serde 系的配置解析，错误信息会列出 expected one of …，这就是当前层级的 schema 提示。

实际试探链：先写 [accounts.work.imap]，报 expected server/tls/starttls/alpn/sasl——这层认了，字段名有了；把 server 写成子表，又报错，才知道它是 host:port 字符串；写 sasl，报 wanted exactly 1 element，明白这是枚举表，变体名试 plain 就通了；plain 下面是 username 和 password，password 再报 expected raw/cmd，挂上 password.cmd 从钥匙串取，整条链走完。十分钟，零猜测。

这套办法不新鲜，在「文档缺位 + schema 复杂」的场合比翻源码快。配错是故意的，报错是真实的，每一轮错误信息都是下一层的说明书。最终配置如下，占位符替换成自己的就能用：

# ~/.config/himalaya/config.toml（v2.x 实测可用）
[accounts.work]
email = "<你的163邮箱>"
display-name = "<你的名字>"
default = true

[accounts.work.imap]
server = "imap.163.com:993"      # server 是 host:port 字符串，不是子表

[accounts.work.imap.sasl.plain]  # sasl 是枚举表：plain/login/oauthbearer 等
username = "<你的163邮箱>"
password.cmd = "security find-generic-password -a '<你的163邮箱>' -s 'himalaya-mail' -w"

[accounts.work.smtp]
server = "smtp.163.com:465"

[accounts.work.smtp.sasl.plain]
username = "<你的163邮箱>"
password.cmd = "security find-generic-password -a '<你的163邮箱>' -s 'himalaya-mail' -w"

[accounts.work.folder.aliases]
inbox = "INBOX"

验证一条命令：himalaya account check，看到 smtp: OK 就能发信。163 的 IMAP 可能报一个 BAD Request not ending with，那是 163 服务端的兼容问题，不影响发信，忽略即可。

4. 第二次静默失败：密码存进去了，但是空的

配置对了，密码还没入库。163 邮箱要用授权码：网页版进设置，POP3/SMTP/IMAP 开服务时生成，需要短信验证，只显示一次。它是独立密码，跟登录密码不是一回事。

第二个坑在钥匙串这步。我第一次用 security add-generic-password 不带 -w，等它提示 password data for new item: 再交互输入——命令正常退出，条目也在，密码是空的。后面 IMAP/SMTP 全部 535 认证失败。根因：在非交互的执行环境里，这个提示根本吃不到输入，security 不报错，静默存了个空值。

修复两行：-w 非交互写入，写完立即取回校验。163 授权码固定 16 位字母数字，长度不对就重写。

# 授权码入钥匙串（非交互 -w，别用交互提示输入）
security add-generic-password -a "<你的163邮箱>" -s "himalaya-mail" -w "<16位授权码>"
# 写完立即取回校验
security find-generic-password -a "<你的163邮箱>" -s "himalaya-mail" -w | wc -c
himalaya account check

校验这步不能省。535 只会告诉你「认证失败」，不会告诉你「你存的密码是空的」——静默失败的排查成本，远高于写入时多花的那一秒。

5. 兜底：临时脚本直接 smtplib

himalaya 管常驻任务，一次性脚本没必要走这套配置。Python 标准库 smtplib 直发，二十行，我实测一次成功。中文主题和发件人名要用 Header 包 utf-8，附件名同理；sendmail 返回空 dict 表示全部被接收。

import smtplib
from email.mime.text import MIMEText
from email.mime.multipart import MIMEMultipart
from email.header import Header
from email.utils import formataddr

SMTP_HOST = "smtp.163.com"
SMTP_PORT = 465
USER = "<你的163邮箱>"
AUTH_CODE = "<16位授权码>"

def send_mail(to_addr, subject, body):
    msg = MIMEMultipart()
    msg["From"] = formataddr((str(Header("构建报告机器人", "utf-8")), USER))
    msg["To"] = to_addr
    msg["Subject"] = Header(subject, "utf-8")
    msg.attach(MIMEText(body, "plain", "utf-8"))
    with smtplib.SMTP_SSL(SMTP_HOST, SMTP_PORT) as s:
        s.login(USER, AUTH_CODE)
        undelivered = s.sendmail(msg["From"], [to_addr], msg.as_string())
    return undelivered  # 空 dict = 全部接收

if __name__ == "__main__":
    result = send_mail("someone@example.com", "每日构建报告", "正文内容见附件")
    print("undelivered:", result)

分工就一条：常驻任务用 himalaya，钥匙串管密码、MML 管格式；一次性脚本用 smtplib，标准库零依赖。

6. 总结

三句话收尾。第一，「配置存在」不等于「配置生效」，每个静默失败都要配显式校验兜底——account list 看 BACKENDS 列，钥匙串写入后取回验长度。第二，报错信息是被低估的文档，故意配错、逐层逼近，比等一份完整的迁移文档快得多。第三，发信通道做双轨，CLI 和标准库各管一摊，别把一次性需求也做成工程。

静默失败最贵的地方不在修复，在于你以为一切正常，而对面什么都没收到。