前言¶

在 DSH 里跑智能体时，邮件往往仍是独立系统：人要自己开客户端查未读，或另写脚本拉 IMAP。若希望 agent 在同一套工具里列信、读正文、回复并转发，通常得对接各家 API 或自建中间层。dsh-email 走标准 IMAP/SMTP，用账号密码或应用专用密码即可，把邮箱能力挂到 DSH 的 email 工具上，适合「联网工具」类 profile 需要真实信箱读写、又不想绑死某一云厂商 SDK 的场景。

这是什么¶

dsh-email 是社区维护的 DSH 树外插件（维护者 xuan25，GitHub 仓库 xuan25/dsh-email，目录页 SkillHub 条目）。插件为 agent 提供可工作的邮箱访问：通过 email 工具按标准 IMAP 读信、按 SMTP 发信，配置到位后 agent 可检查并处理邮件，凭证仅需密码或服务商提供的应用专用密码。

当前 package 版本为 0.1.0，许可证 MIT；依赖 imapflow、nodemailer，并声明与 Cordis、dsh-agent 等 peer 组件的版本下限（见仓库 package.json）。

核心功能¶

以下能力均来自项目 README 说明，按用途归纳。

读信与检索

• 列出邮件、未读视图、结构化搜索。
• 读取邮件时可选择不标记为已读（read without marking seen）。

账号与健康检查

• verify：对每一个已配置账号做 live 检查（IMAP 登录 + SMTP 认证），无副作用。
• 单插件内支持多账号；未指定账号时可由 EMAIL_DEFAULT_ACCOUNT 指定默认账号。

发信

• 发送、回复、转发，支持附件。
• 可选 SENT_FOLDER：发信时把副本写入指定文件夹；缺文件夹时可按配置自动创建（不会创建名为 INBOX 的文件夹）。

邮箱管理

• 创建、删除文件夹，移动邮件。

删除与权限

• 删除邮件、删除文件夹（delete、delete_folder）按账号开关：默认 EMAIL_<N>_ALLOW_DELETE=false（fail-closed），仅对显式 opt-in 的账号生效。

新邮件触发（可选）

• 按账号常驻 IMAP 监听（默认监听 INBOX，可改 TRIGGER_FOLDER）。
• 每封新邮件可派发一次新的 agent 会话，并注入运维者定义的 TRIGGER_PROMPT 策略。
• 可限制并发、队列长度；队列溢出时邮件保持 UNSEEN 并重试。

会话卸载（Session offload）

• 按分钟扫描，将已超过该账号保留窗口的 trigger 会话归档（保留窗口仅通过 env：EMAIL_<N>_SESSION_RETENTION），归档与日志位于 $DSH_HOME/dsh-email/，用于控制框架会话存储规模。

连接模型

• 除启用 trigger 的账号上的 watcher 外，其余动词每次调用新建连接（stateless verbs）；trigger watcher 是唯一常驻连接。

安装与启用¶

dsh-email 安装到指定 dsh profile，使用官方命令（勿自行拼接 github:owner/repo 形式）：

dsh plugin --profile <name> add dsh-email

配置分三层：内置默认值、EMAIL_* 环境变量块、可选 Cordis patch 层。插件不在 profile 目录下创建配置或状态文件；与 trigger 平面相关的 on-disk 状态仅为 session offload 的 retention 日志与归档目录（见上节）。

环境变量在进程启动时加载；修改 env 后需重启 host 才生效。每个账号至少需要 EMAIL_<N>_USER、EMAIL_<N>_PASS、EMAIL_<N>_IMAP_HOST、EMAIL_<N>_SMTP_HOST；<N> 为账号名大写，账号名须匹配 ^[a-z][a-z0-9-]{0,31}$。缺必填项的账号会在启动时告警并丢弃，启动本身不会失败。

最小示例如下（摘自 README）：

EMAIL_DEFAULT_ACCOUNT=local
EMAIL_LOCAL_USER=agent@local.example
EMAIL_LOCAL_PASS=<credential>
EMAIL_LOCAL_IMAP_HOST=mail.local.example
EMAIL_LOCAL_SMTP_HOST=mail.local.example
EMAIL_LOCAL_SENT_FOLDER=Sent

IMAP 默认端口 993、安全模式默认 tls；SMTP 默认端口 587、安全模式默认 starttls。TLS 证书校验默认严格；仅在 tls / starttls 模式下，ALLOW_INSECURE_TLS=true 才表示接受不可信或自签证书。

可选 Cordis 层：在 profile 的 cordis.patch.yml、用户全局 ~/.dsh/cordis.patch.yml 或 --patch 覆盖中，以插件 id dsh-email 写入 camelCase 的 config（如 defaultAccount、readBodyLimit、accounts 映射）。优先级为：patch 交付值 > env > 内置默认；patch 按 id 整段替换 config，不做 deep merge。若部署支持 live patch reload，改 patch 可触插件重载；否则下次重启生效。agent 通过普通文件编辑改 patch；插件不提供自改配置的工具，accounts 动词仅展示当前值。

启用新邮件触发时，除 EMAIL_<N>_TRIGGER_ENABLE=true 外必须设置 EMAIL_<N>_TRIGGER_PROMPT；其余如 TRIGGER_IDLE_MS、TRIGGER_MAX_CONCURRENT、TRIGGER_QUEUE_MAX、TRIGGER_PRESET、TRIGGER_REASONING_EFFORT 等见 README 表格。

典型用法（配置侧）¶

1. 选定 profile，执行 dsh plugin --profile <name> add dsh-email 安装插件。
2. 为每个账号设置 EMAIL_<N>_USER / PASS / IMAP 与 SMTP 主机（及按需端口、TLS 模式）。
3. 多账号时设置 EMAIL_DEFAULT_ACCOUNT；需要 agent 删信或删文件夹时，仅对目标账号设 EMAIL_<N>_ALLOW_DELETE=true。
4. 启动或重启 DSH host 后，让 agent 调用 email 工具执行列信、搜索、读信、发信等；需要确认连通性时可使用 README 所述的 verify。
5. 若要做「来信即跑一轮 agent」，在对应账号打开 TRIGGER_ENABLE 并写好 TRIGGER_PROMPT；需要控制历史 trigger 会话体量时配置 SESSION_RETENTION 与全局 EMAIL_OFFLOAD_BATCH（默认每轮 sweep 最多 offload 50 个会话）。

读信正文默认截断上限为 20000 字符（EMAIL_READ_BODY_LIMIT），可在 env 或 patch 中调整。

适用场景与注意¶

适合

• 已有标准 IMAP/SMTP 信箱（自建或常见服务商），希望 agent 在对话中查未读、读正文、回复/转发，而不单独维护 REST 邮件 API。
• 多邮箱运维：同一插件内配置多账号，默认账号 + 按账号删除开关，降低误删风险。
• 需要可选的「新邮件 → 新 agent 会话」自动化，并由运维者用 prompt 固定处理策略。

注意

• 插件以当前 dsh 进程的权限与环境变量运行；PASS 与应用专用密码属于高敏感信息，安装前应阅读 源码 与 MIT 许可证，并只在可信环境配置。
• 社区目录 SkillHub 与 DeepSeek / 幻方无官方从属关系；DSH 生态强调「一切皆插件」，本文介绍的是社区插件能力，非官方应用商店条目。
• trigger 常驻连接与队列行为会影响信箱侧连接数与未读状态；生产启用前建议在测试账号上验证 verify 与 trigger 参数。
• env 与 patch 校验规则不同：patch 中未知键或越界值会导致插件条目加载失败；env 侧不完整账号仅告警。

结尾¶

dsh-email 把信箱读写收拢到 DSH 的 email 工具：IMAP/SMTP、多账号、可选来信触发与 session offload，配置以 EMAIL_* 为主、Cordis patch 为辅。进一步细节以仓库 README 为准。

• 目录页：https://www.skillhub.cn/plugins/xuan25/dsh-email
• GitHub：https://github.com/xuan25/dsh-email