STARDUSTLC666/dsh-email

English

dsh-email

给 agent 一个邮箱：八个国内邮箱预设开箱即用，收发/搜索/附件下载全搞定。

DeepSeek Harness 邮件工具插件：让 agent 能查收件箱、读邮件、搜邮件、代发邮件、收发附件。纯插件实现，零核心改动，安装即可用。

Email tools for DeepSeek Harness: list, read, search and send mail through standard IMAP/SMTP — with one-line presets for QQ / 163 / 126 / Sina / Aliyun / Gmail / Outlook / iCloud.

纯 Node 实现，全平台通用（Windows / macOS / Linux 同一份代码），不依赖 shell、无原生二进制。

工具一览

示例对话：

帮我看下 QQ 邮箱最新的 10 封未读，把要回复的列出来。

v0.6.2 优化

• 服务器端搜索补齐 cc，搜索范围真正覆盖主题 / 发件人 / 收件人 / 抄送。
• 正文回退扫描的匹配范围也加入 to / cc；单封邮件解析失败不会中断整批扫描。
• 邮件列表结果强制按 UID 降序，保证「最新在前」。
• email_send 的附件参数严格校验为路径字符串数组，并做 trim。

安装

dsh plugin --profile web add dsh-email

（或从 GitHub 安装：dsh plugin --profile web add github:你的账号/dsh-email#<commit>，随后按提示在 profile 的 pnpm-workspace.yaml 里授权 prepare 构建。）

装好后重启 dsh web。插件自带空配置，不会弄崩启动；配置前调用任何 email 工具都会返回明确的配置提示。

配置方式有两种（任选其一）：

1. 网页设置（推荐）：重启后打开 设置 → 邮件 (dsh-email)，表单里填邮箱地址和授权码，点「保存并应用」，还带「测试连接」按钮。零 YAML、零重启。
2. YAML：按下面的 cordis.patch.yml 模板手写；设置页的「多账号（高级，YAML）」文本框也能填账号映射（覆盖 YAML 里的 accounts）。

设置页保存的值存在 settings.yaml 的 dsh-email 命名空间里，覆盖 YAML 的默认账号配置；密码字段标记为 secret（不会出现在任何导出/诊断里）。

配置

在你 profile 的 cordis.patch.yml 里覆盖 tool-email 行（在 $DSH_HOME/profiles/<name>/ 下），然后重启：

- id: tool-email
  config:
    provider: qq          # qq | 163 | 126 | sina | aliyun | gmail | outlook | icloud
    user: you@qq.com
    password: 你的授权码   # 强烈建议改用环境变量 DSH_EMAIL_PASSWORD，见下

不需要预设？手填任意 IMAP/SMTP 服务器即可：

- id: tool-email
  config:
    user: you@corp.example
    password: 你的授权码
    imap: { host: imap.corp.example, port: 993, secure: true }
    smtp: { host: smtp.corp.example, port: 465, secure: true }
    inboxFolder: INBOX

多账号：一个 tool-email 行可以配多个邮箱，工具调用时用 account 参数选择：

- id: tool-email
  config:
    accounts:
      work: { provider: qq, user: work@qq.com, password: 授权码1 }
      home: { provider: '163', user: home@163.com, password: 授权码2 }
    defaultAccount: work        # 省略 account 参数时用这个
    downloadDir: E:/attachments # 可选，默认 $DSH_HOME/email-downloads

顶层的 provider/user/password/imap/smtp/inboxFolder 仍然可用，作为各账号的共享默认值（v0.1 单账号写法完全兼容）。

常用邮箱预设

完整配置项

第一步：拿到授权码

各邮箱都要求用「授权码/应用专用密码」而不是登录密码：

• QQ 邮箱：设置 → 账户 → 开启 IMAP/SMTP 服务 → 生成授权码
• 163/126：设置 → POP3/SMTP/IMAP → 开启 → 新增授权码
• Gmail：开启两步验证 → 安全 → 应用专用密码
• Outlook：Microsoft 账户安全 → 应用密码（部分账号需先开两步验证）

安全须知

• 授权码就是你的邮箱钥匙。它写在本机（profile 的 cordis.patch.yml 或 settings.yaml），请勿提交到任何 Git 仓库；更推荐用环境变量 DSH_EMAIL_PASSWORD。
• email_send 默认走 DSH 审批通道：每次发信都显示「发送邮件给 xx，主题「xx」」，你批准才发出。没有审批通道的环境（如无 UI 的 headless）会直接拒绝发信，这是安全默认。
• 会话处于 Full Access（完全访问） 模式时，harness 的审批策略是 never（不弹任何确认框）——email_send 会被拦截并给出明确提示。两条出路：① 把访问模式切回 Read Only / Write；② 关闭 sendApproval（设置页勾掉「发信前确认」），即显式声明自行承担风险。
• 本插件不做任何联网上报，凭证只在内存中用于连接你的邮箱服务器。

已知限制

• 不支持 OAuth2：强制 OAuth 的企业环境（部分 M365 / Google Workspace）暂不可用，只能使用邮箱服务商的应用专用密码 / 授权码。
• 正文搜索：服务器端只搜 subject / from / to / cc；多数服务器（如 QQ）的 IMAP TEXT / HEADER 搜索不可靠，无结果时回退到最近 bodySearchLimit 封的正文扫描（较慢，可用 bodySearchFallback 关闭）。
• 附件：内嵌图片暂不支持单独下载；附件定位失败会直接报错而不是下载错误文件（安全默认）。
• 密码落盘：设置页保存的授权码以明文写在本机 settings.yaml（secret 标记只保证它不进日志 / 导出 / 诊断，不做磁盘加密）。请勿把 settings.yaml 交给不信任的人。

开发

pnpm install
pnpm run build   # tsc → lib/
pnpm test        # 构建 + node --test（配置/解析/注册与审批门，44 个用例，无需真实邮箱）

协议

MIT。这是一个社区插件，与 DeepSeek 官方无关；@deepseek-ai/* 为官方保留命名空间。

相关插件

• dsh-slack — Slack 通知/收件箱
• dsh-dingtalk — 钉钉群通知（零依赖）
• dsh-email — 邮件六件套 + Web 设置页