前言¶
在 DeepSeek Harness（DSH）里做智能体时，常需要把外部信息拉进对话上下文。邮件是其中一个来源：验证码、工单通知、订阅简报都可能落在收件箱里。自己写 IMAP 客户端要处理授权、编码和 MIME 结构，还要把能力封装成 Agent 可调用的工具。
dsh-qqmail 是社区维护的 Host 插件，通过 IMAP 连接 QQ 邮箱，向 DSH 暴露一组只读工具，并附带设置页完成账号配置与连通性校验。下面介绍它的定位、能力与安装用法。
这是什么¶
dsh-qqmail（npm 包名 @qhao/dsh-qqmail）由 Q-hao516 维护，归类为联网工具。插件在 Harness 进程内通过固定主机 imap.qq.com:993 读取 QQ 邮箱，登录使用 QQ 邮箱的 16 位授权码，不是 QQ 密码。
整体设计为只读：不发送、不删除、不移动邮件，也不把邮件标为已读。
核心功能¶
插件注册五个 Agent 工具和一个设置页。
| 工具 | 作用 |
|---|---|
qqmail_inbox |
列出近期邮件，可选仅未读 |
qqmail_read |
按 uid 读取单封正文；支持 base64、quoted-printable、GBK/UTF-8 及 multipart/alternative 等常见解码 |
qqmail_search |
按关键词、发件人或起始日期搜索 |
qqmail_status |
返回已配置地址、总邮件数、未读数 |
qqmail_setup |
在工具调用中保存邮箱地址与授权码（替代走 UI） |
设置入口在 Settings → QQ Mail（settings.section，id 为 qqmail）。页面填写地址与授权码后点「保存并验证」，会先向 imap.qq.com 校验，成功后才落库，并显示类似「连接成功，N 封邮件 / M 封未读」的结果。
授权码以 credential 记录保存，不作为明文配置；设置表单将该字段标为 secret。页面通过同源路由 /dsh-qqmail/settings 通信，拒绝跨域与非 JSON 请求体。
环境与依赖¶
- DeepSeek Harness 版本不低于
0.2.1-rc.3（见package.json中engines.dsh）。 - QQ 邮箱已开启 IMAP，并在 QQ 邮箱 → 设置 → 账户 → POP3/IMAP 服务 中生成授权码。
安装与启用¶
在目标 profile 下执行以下命令之一（包内无构建步骤，JavaScript 随包发布）：
dsh plugin --profile <your-profile> add @qhao/dsh-qqmail
或直接从 GitHub 仓库添加：
dsh plugin --profile <your-profile> add github:Q-hao516/dsh-qqmail
安装后打开 Settings → QQ Mail，填入 QQ 邮箱地址与授权码，保存并验证通过即可在 Agent 中调用上述工具。
典型用法¶
配置完成后，Agent 可按任务组合调用工具，例如：
- 用
qqmail_status确认账号与未读概况。 - 用
qqmail_inbox（可加仅未读）拉取最近邮件列表。 - 对感兴趣的邮件用
qqmail_read传入 uid 读取正文。 - 需要筛选时用
qqmail_search指定关键词、发件人或起始日期。
也可在对话中通过 qqmail_setup 写入地址与授权码，效果与设置页一致，但仍需 IMAP 校验成功才会持久化。
适用场景与注意¶
适合： 已在 DSH 中开发智能体、需要从 QQ 邮箱只读获取邮件摘要或正文的工作流（提醒跟进、信息摘录等），且能接受 QQ 邮箱与固定 IMAP 端点这一约束。
限制（以 README 为准）：
- 仅支持 QQ 邮箱，无通用 IMAP 主机/端口配置。
- 只读，不支持发信、回复、过滤规则或附件下载。
- 信头与正文解析覆盖常见 MIME，不保证处理所有 MIME 变体。
安全与权限： 插件以当前 DSH 进程权限运行，会使用你配置的邮箱授权码访问邮件。安装前建议查看 GitHub 仓库 源码与 MIT 许可证，确认符合你的环境策略。DSH 社区插件目录（如 SkillHub 目录页）为独立站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-qqmail 把 QQ 邮箱 IMAP 只读能力收敛成五个工具和一页设置，降低在 Harness 里接邮件的集成成本。需要进一步了解实现细节或提交 issue，可访问：
- 目录页：https://www.skillhub.cn/plugins/Q-hao516/dsh-qqmail
- GitHub：https://github.com/Q-hao516/dsh-qqmail
