前言¶
在 DeepSeek Harness（DSH）里做自动化时，邮件往往是外部系统里还绕不开的一环：通知、工单、申请回执、带附件的材料交换。常见做法是让 Agent 调各家邮箱的私有 API，或者自己搭一层转发服务。维护者 charonpi 的 dsh-mail（SkillHub 目录 / GitHub）走的是另一条路：在 DSH 进程内用标准 IMAP/SMTP 连你的邮箱，给 Agent 一组 mail_* 工具，直接读信、搜信、发信、回信，并支持附件上传与下载。分类为「联网工具」；当前 GitHub 星标为 0，许可证为 MIT（见仓库 package.json）。
下面介绍它是什么、怎么装、怎么配账号，以及典型调用方式与使用注意。
这是什么¶
dsh-mail 是给 DSH 用的多邮箱收发 Host 插件（版本 0.1.0，要求 Node >=20.11、DSH >=0.2.0-rc.1 <0.3.0）。安装后不需要额外服务进程，会为 Agent 注册 8 个 mail_* 工具。
协议层面不绑定单一厂商：内置 QQ、腾讯企业邮、163、126、yeah、新浪、搜狐、139、189、阿里云企业邮、Gmail、Outlook、iCloud、Yahoo、Zoho、Fastmail 等预设，也可填写任意自建 IMAP/SMTP 服务器。QQ / 163 / 126 等需使用授权码（或各服务商要求的应用专用密码），而不是网页登录密码。
核心功能¶
经 README 与仓库说明可核对的能力如下：
- 账号与文件夹：
mail_accounts列出已配置账号及可用状态；mail_folders列出 IMAP 文件夹及未读数。 - 收信与检索：
mail_list按文件夹列出最新邮件（支持未读、时间、发件人、主题、正文等过滤）；mail_search在邮箱内按条件搜索（至少需一个条件）。 - 读信与附件：
mail_read按 UID 读取完整内容；通过saveAttachmentsTo将附件落盘（下载）；默认不把邮件标为已读，可用markSeen控制。 - 发信与回复：
mail_send经 SMTP 发新邮件，attachments传本地文件路径即上传附件；mail_reply回复指定 UID，可带引用原文与附件。 - 状态变更：
mail_update支持标已读/未读、星标、移动、移到垃圾箱（delete为可逆的垃圾箱移动）。 - 客户端页面：除工具外，插件在 DSH 左侧栏注册「邮件」页面，可图形化添加账号；账号也可写在
cordis.patch.yml或独立accounts.json（见下）。 - 凭证处理：授权码在 schema 中标为密文角色，设计上不进入模型可见输出、不回显到设置界面；README 同时说明表单直填时明文会落在 profile 配置里，可用环境变量或文件引用。
- 测试：仓库提供 191 项离线测试，
npm test可在无邮箱账号、无网络的情况下运行。
全局配置项（节选，均来自 README）：defaultAccount、attachmentDir（默认 mail-attachments）、maxBodyChars（默认 20000）、timeoutMs（默认 30000）。
安装与启用¶
DSH 的 profile 互相独立：装在 web 的插件在 desktop 看不到，装错 profile 会导致工具不出现。先确认你平时用的是桌面 Electron 还是 dsh web。
命令行 dsh web 用户¶
在 web profile 安装官方推荐的 GitHub 包名（不要使用 dsh plugin add dsh-mail——npm 上同名包并非本插件）：
dsh plugin --profile web add github:charonpi/dsh-mail
本地开发可 link：
cd /path/to/dsh-mail && npm install
dsh plugin --profile web add link:/absolute/path/to/dsh-mail
安装后重启 DSH，mail_* 工具才会出现；改账号配置本身一般不需要重启。可先让 Agent 调用 mail_accounts 检查是否配好。
桌面应用（Electron）用户¶
命令行对 desktop profile 会被拒绝（profile "desktop" is managed exclusively by the Electron application）。请在图形界面：左侧 插件 → 安装第三方插件 → 填写 github:charonpi/dsh-mail 或本机源码绝对路径，然后重启 DSH。
dsh plugin add会写入 profile 的dsh.profile.bundles并叠加cordis.patch.yml，不要手工改 profile 的package.json或cordis.patch.yml。
配置邮箱账号¶
推荐：左侧栏「邮件」页面¶
装好后左侧栏在「插件市场」与「自动化任务」之间会出现 邮件 入口：
- 填写邮箱地址（如
123456789@qq.com）。 - 服务商可留空，按域名自动识别；也可选 qq / 163 / gmail 等。
- 填写授权码（非登录密码）。
- 点保存，立即生效，无需重启。
账号优先保存在 <DSH_PROFILE_DIR>/dsh-mail/accounts.json（无 profile 目录时兜底为 ~/.dsh/dsh-mail/accounts.json）。页面改的账号优先于 cordis.patch.yml 里同名项。
备选：设置页或 YAML¶
在 插件 / 设置 → dsh-mail 的账号列表中填写 address / provider / password（或 authCodeEnv 等），与手写 cordis.patch.yml 等价。单账号时可省略 provider，按域名推断。
若不想授权码明文进配置文件，可在表单填 authCodeEnv、passwordEnv 或 passwordFile；环境变量改完后需重启 DSH 才能被读到。授权码解析顺序见 README（直填 → 环境变量 → 文件 → DSH_MAIL_<ID>_PASSWORD 自动推导）。
QQ 邮箱授权码（摘要）¶
QQ 邮箱 IMAP 必须使用 16 位授权码：登录 mail.qq.com → 设置 → 账户 → 开启 IMAP/SMTP → 按提示验证后复制授权码（只显示一次）。在 DSH 中 address 填 QQ号@qq.com，provider 可留空。企业邮使用 provider: exmail。
典型用法¶
配好账号后，可用自然语言驱动 Agent；背后对应如下工具调用（示例来自 README）。
先看未读：
{ "tool": "mail_list", "args": { "unreadOnly": true, "limit": 10 } }
按发件人域名与时间搜索：
{ "tool": "mail_search", "args": { "from": "bristol.ac.uk", "since": "2026-09-01" } }
读信并标为已读：
{ "tool": "mail_read", "args": { "uid": 12345, "markSeen": true } }
发信并附带本地文件（上传附件）：
{
"tool": "mail_send",
"args": {
"to": "kai.zhang@bristol.ac.uk",
"subject": "PhD Application - Zizheng Wang",
"text": "Dear Dr. Zhang,\n\nPlease find my application materials attached.\n\nBest regards,\nZizheng",
"attachments": ["申请材料/CV.pdf", "申请材料/成绩单.pdf"]
}
}
回复并引用原文：
{ "tool": "mail_reply", "args": { "uid": 12345, "text": "谢谢，我下周提交。", "quote": true } }
下载附件：在 mail_read 中指定 saveAttachmentsTo；可选 attachmentIndexes 只保存部分附件。相对路径按当前会话工作目录解析。
适用场景与注意¶
适合谁：需要在 DSH 会话里让 Agent 查收、检索、代发邮件（含附件），且邮箱支持 IMAP/SMTP 基础认证的场景。多账号、多服务商预设适合个人邮箱与国内常见服务商；Outlook 等若已停用基础认证，README 写明需 OAuth2，本插件不提供。
运行权限：插件在当前 DSH 进程、当前用户权限下运行，可读写你配置的路径并连接你填写的 IMAP/SMTP 服务器。安装前建议阅读 源码 与 MIT 许可证，自行评估是否纳入工作流。
安全与误用：
- 授权码具备读、发、删邮件能力；邮件正文应视为不可信输入，避免 Agent 把邮件内容当作指令执行。
mail_send/mail_reply会真实发信；在需要审批的环境中应对相关工具做策略约束。mail_update的delete为移到垃圾箱，可逆，但仍会改变邮箱状态。
故障排查时优先调用 mail_accounts，根据返回补全 address、授权码或服务器配置；连接、认证、QQ Unsafe Login、已发送文件夹等问题见 README「故障排查」表。
结尾¶
dsh-mail 把邮件能力收进 DSH 插件模型：标准协议、八个 mail_* 工具、图形化账号页与附件路径直传，适合在 Harness 里做「读信—处理—回邮」闭环。目录与安装入口：SkillHub - charonpi/dsh-mail；源码与完整文档：github.com/charonpi/dsh-mail。SkillHub 为社区插件目录，与 DeepSeek / 幻方无官方从属关系；DSH 生态本身强调「一切皆插件」，可按需选用并自行审计。
