技能介绍

问题在哪

给 Codex 接 QQ 邮箱这件事，手动折腾一次很容易留下隐患：qq_mail 这个 MCP 条目可能残留旧配置，模板复制不完整，.env 少了变量，或者 Windows 终端编码把 IMAP/SMTP 输出糊成一堆乱码。这些故障没有一个是“一眼就能看出来”的——Codex 只是突然读不到邮件，要排查还得翻日志、重新敲命令。

这个技能做了什么

它把一次性的安装过程固化成可重复的流程，核心是两个 PowerShell 脚本加一个随附的 MCP 模板：

安装器 — 确定安装目录（默认 ~/Documents/skills/qq-mail-mcp），复制 assets/qq-mail-mcp-template，执行 npm install，必要时从 .env.example 生成 .env，删除遗留的 qq_mail 条目，再用 codex mcp add 重新注册。需要换目录就传 -InstallDir。
冒烟测试 — 验证 IMAP 登录与 SMTP 验证、拉取收件箱最新邮件摘要、或发送一封纯 ASCII 的自测邮件。支持 -Mode check、-Mode latest、-Mode send-self-test 等模式，也可以用 -Mailbox、-To、-Subject 做覆盖。

关键步骤一览

选定或沿用安装目录。
跑安装器，把桥接搭好。
在 .env 里补上 QQ_MAIL_USER 和 QQ_MAIL_AUTH_CODE——注意要用授权码，不是 QQ 密码。
跑冒烟测试，最后回报安装路径、.env 是新建还是复用、codex mcp list 里有没有 qq_mail、最新邮件摘要，以及发送测试是否通过。

适用边界与注意点

优先用随附脚本，不要临时敲内联 Node 片段；Windows 下编码和模板漂移大多就是这么来的。
自测邮件保持纯 ASCII，除非你明确要用 UTF-8 内容并走文件脚本发送。
授权码绝不能出现在最终回报里。
测试失败时先读 references/qq-mail-troubleshooting.md，再决定怎么修。

截图预览

使用场景

在 Windows 开发机上为 Codex 接入 QQ 邮箱时，用随附安装器建立可复现的 qq_mail MCP 桥接，并确认 codex mcp list 中出现该条目。
已填好 .env 却收不到新邮件时，用 check 模式验证 IMAP 登录与 SMTP 验证，再用 latest 模式拉取收件箱最新摘要定位断点。
上线前验证发送链路：用 send-self-test 模式向自己发一封 ASCII 确认邮件，并指定 -To 与 -Subject 便于归档和回看。
遇到乱码或授权码报错时，先读 troubleshooting 参考，再决定改 .env 还是重跑安装器，避免临时内联脚本导致配置漂移。