← Back to home@freedomkk-qfeng

dsh-mail-assistant

Standards-based IMAP/SMTP mail connector for DeepSeek Harness, enabling agents to read and send email with explicit user controls.

Stars
0
Language
JavaScript
Created
Aug 31, 2026
Updated
Sep 1, 2026
Notify
GitHub repoHomepage

Introduction

dsh-mail-assistant

简体中文 | English

面向 DeepSeek Harness（DSH） 的安全型邮件助手插件。它通过标准 IMAP 读取邮件、通过标准 SMTP 发送纯文本邮件，但刻意不成为另一个邮箱客户端。

当前版本：0.1.0-alpha.4。这是公开 alpha 预览版，适合隔离环境和专用测试邮箱；连接重要邮箱前仍应完成组织自己的安全与合规审查。

定位与边界

插件只提供五个 Agent 工具：

工具能力关键约束
mail_list_folders列出服务器上的邮箱目录只读；返回精确路径，便于查找归档和历史邮件
mail_find按主题、发件人、收件人与日期分页查找邮件每页最多 50 条；用不透明游标持续拉取，不搜索或执行正文指令
mail_read读取一封邮件的纯文本正文和附件元数据IMAP EXAMINE/只读锁；不修改已读状态
mail_get_attachment把一个附件保存到会话工作区大小上限、随机文件名、不覆盖、仅工作区内
mail_send发送或回复纯文本邮件，可附加工作区文件普通权限逐次确认；Full Access 免确认；仍需单独开启发信能力

明确不做：删除、移动、归档、标签、已读/未读修改、联系人、规则、后台轮询、自动唤醒、自动回复、HTML 邮件创作和完整邮箱 UI。

安全默认值

  • 安装后读信和发信权限都为关闭；启动时不连接邮箱。
  • 密码或客户端授权码只通过 DSH Credential Provider 保存，固定引用为 DSH_MAIL_ASSISTANT_PASSWORD；不会进入 settings.yaml 或浏览器回读。
  • IMAP 始终使用只读 mailbox lock，不调用 STORE、COPY、MOVE、EXPUNGE。
  • 邮件正文、标题、地址和附件名全部标记为不可信外部数据；它们不能授权发信、请求密钥或改变系统规则。
  • 历史检索显式返回 hasMore 和 nextCursor；需要完整覆盖时，Agent 必须持续翻页至 hasMore=false，不能把首屏结果误当成整个邮箱。
  • 发信只接受纯文本。收件地址拒绝换行注入，附件必须是当前会话工作区内的普通文件。
  • 只支持隐式 TLS 或 STARTTLS，证书校验不可关闭。
  • SMTP 在 DATA 阶段断线或超时时返回 unknown，并明确禁止 Agent 自动重试，避免重复发信。

完整威胁模型见安全模型。

安装

要求：Node.js 22+、DSH 0.1.2-alpha.2，且所用 Profile 已包含 Settings、Credentials、Tools、Filesystem、Permission Presets、Approval 和 Web Client 官方能力。

普通使用请固定经过复核的 npm 精确版本：

dsh plugin --profile web add dsh-mail-assistant@0.1.0-alpha.4

需要审计、开发或验证尚未发布的改动时，再从源码安装：

git clone https://github.com/freedomkk-qfeng/dsh-mail-assistant.git
cd dsh-mail-assistant
npm ci
npm run check
dsh plugin --profile web add .

从父目录也可以显式传入路径：

dsh plugin --profile web add ./dsh-mail-assistant

DSH 会链接本地 checkout，不会扫描当前目录；源码安装后请保留这个目录。明确希望持续跟随预发布更新时可以使用：

dsh plugin --profile web add dsh-mail-assistant@alpha

配置与首次验证

  1. 打开 DSH 的“设置 → 邮件助手”。
  2. 填写邮箱地址、客户端授权码和可选的发件人显示名称。
  3. 选择邮箱服务商自动填写服务器；单位邮箱或自建邮箱使用“手动配置”。
  4. 登录用户名、收件箱目录和安全上限收纳在“高级设置”中，通常无需修改。
  5. 配置完成后，分别决定是否开放“允许 Agent 读信”和“允许 Agent 发信”。
  6. 保存后，在对话中让 Agent“查一下最近的邮件”。插件不会在保存时主动登录邮箱。

无 UI 的部署可在 cordis.patch.yml 中覆盖非敏感配置，并把密码放入 DSH 凭据引用 DSH_MAIL_ASSISTANT_PASSWORD（本地 Credential Provider 也会按引用名读取同名环境变量）。不要把密码写进 Bundle 或 patch。

不同服务商对普通密码、应用密码和 OAuth2 的支持不同。此插件的 v0.1 只实现用户名 + 密码/授权码的标准 IMAP/SMTP 登录；强制 OAuth2 的邮箱不在当前支持范围内。

与 DSH 的组合关系

插件复用 DSH 原生能力，而不是 fork 客户端：

  • ctx.credentials：保存和逐次解析授权码；
  • ctx.settings 与 settings.section：配置存储和设置页；
  • ctx.tools：工具注册、单调拒绝 guard 和统一执行管线；
  • ctx.permissionPresets 与原生 tools/pre-execute：普通权限逐次确认，Full Access 免确认；
  • ctx.fs：发送附件的工作区解析、包含性检查和有界读取；
  • DSH Client Loader：动态加载设置页，不修改官方 Web 应用。

二进制写入尚未出现在 DSH ctx.fs seam 中，因此 mail_get_attachment 在本地 Host 文件系统上通过 ctx.fs 完成路径解析与包含性校验后，以独占写方式落盘。远程/非本地 FS Provider 可能不支持该工具；其他读信和发信能力不受影响。详见兼容性。

文档

致谢与来源

本项目参考了社区插件 STARDUSTLC666/dsh-email 对 ImapFlow、Nodemailer、MailParser 与 DSH 的组合经验，但重新划定了能力边界，并改用 DSH Credentials、默认关闭权限、只读 IMAP、工作区附件边界、邮件不可信标记和 DSH 原生权限预设。第三方依赖与许可证见第三方组件声明。

License

MIT