Agent Mail CLI 接入 WorkBuddy 实录

目标：让 Agent 具备收发邮件的能力 —— 安装 CLI、装好 Skill、跑通 OAuth，并实际发信验证。

一、背景

Agent 邮箱提供的是一套「CLI + Skill」组合：CLI 负责与邮箱服务通信，Skill 负责告诉 Agent「什么场景该用什么命令」。两者缺一不可 —— 只装 CLI，Agent 不知道有它；只装 Skill，命令跑不起来。

二、安装四步

1. 安装 CLI

npm install -g @tencent-qqmail/agently-cli
agently-cli --version   # 1.0.18

2. 安装 Skill

官方为 WorkBuddy 单独提供了一个下载分支（通用 Agent 走 npx skills add）：

# 下载 zip 并解压到用户级 skills 目录
curl -L -o skill.zip "https://lightmake.site/api/v1/download?slug=agently-mail"
unzip -o skill.zip -d "$HOME/.workbuddy/skills/agently-mail"

3. OAuth 授权

agently-cli auth login

走的是 device flow：命令输出一个授权链接，在浏览器打开完成授权即可，本地进程会自动退出。凭据最终落在系统凭据存储里（Windows 下为 DPAPI）。

4. 验证

agently-cli +me

返回账号别名、附件限制、频率配额和权限范围。

三、装之前先审一遍

这次装 Skill 时坚持做了一件事：来自第三方域名的压缩包，先解压审计再落盘。

审计结论：包内只有 SKILL.md（约 11KB）和 _meta.json，没有任何脚本或可执行文件，内容为纯文档，且自带一套反提示注入规则 —— 明确把邮件正文、主题、发件人名称等字段视为不可信外部输入，不得当作指令执行。属于安全项。

npm 包也做了同样的核查：维护者为官方企业邮箱、Apache-2.0 许可、无安装钩子，之后才执行全局安装。

为什么这一步不能省

技能目录里的内容会被 Agent 当作行为准则读取。一旦被投毒，等价于给 Agent 装了个后门 —— 这跟「下载一个普通工具」的风险等级完全不同。「从陌生域名下个 zip 塞进技能目录」是典型的高风险动作，审计必须前置。

四、两阶段确认：写操作不能自己拍板

Skill 对发信 / 回信 / 转发 / 删除这类写操作规定了「两阶段确认」流程：

1. 先用同样参数调用一次（不带确认令牌）→ 服务端不执行，只返回一个 confirmation_token 和一份 summary（收件人、主题、附件数）
2. Agent 把 summary 展示给用户，然后停下等回复
3. 用户在下一轮明确许可后，带上令牌再调一次，才真正发出

红线只有一条：拿到令牌后必须停下，不能在同一轮里自己确认自己。

一个与文档不符的实测点

文档的错误码表写着「缺少 confirmation-token → exit code 8」，但实测第一阶段返回的是 exit 0，真正的信号在响应体里：

{ "ok": true, "data": { "confirmation_required": true, "confirmation_token": "ctk_***" } }

判据必须看 JSON 返回体，不能看退出码 —— 否则会把「待确认」误判成「已发送」，这是很危险的错误。

五、实测：发一封天气邮件

agently-cli message +send \
  --to <收件人> \
  --subject "广州本周天气速览" \
  --body-file ./body.md

完整链路：第一轮返回确认令牌 → 展示摘要等用户确认 → 用户点头 → 带令牌重发 → 返回 queued: true → 在「已发送」中核对到该邮件，中文正文无乱码。

两个实践建议：

• 正文走 --body-file 而不是命令行内联，中文更稳，也方便留档复用；
• 确认令牌有效期很短（分钟级），用户回复慢时会过期，此时需要重新取一次令牌；但「重新取 + 立即确认」仅限用户已经明确授权的场景，否则等于绕过确认环节。

六、踩坑记录（Windows + 沙箱环境）

七、小结

• CLI + Skill 的分工值得借鉴：CLI 是可执行能力，Skill 是行为准则 + 参数速查，职责边界清晰。
• 写操作的两阶段确认是关键设计：把「发出去」的最终决定权留在人手里，而不是让 Agent 自我授权。
• 安装第三方 Skill 前必须审计包内容，这是安全底线，不是可选项。
• 文档和实测总有出入，以实测为准，并把差异记录下来 —— 下次就不会再被文档误导。