前言¶

DeepSeek Harness (DSH) 插件生态允许开发者扩展智能体的能力。在构建需要读取邮件的智能体时，直接集成 IMAP 协议需要处理连接、认证、代理和错误处理等细节。dsh-email-reader 插件封装了这些底层逻辑，提供了列表、读取和搜索邮件的能力。

该插件主要解决两个具体问题：一是针对微软自 2024 年 9 月起仅支持 OAuth2 的 Outlook.com 账号，提供自动 token 刷新的 OAuth2 认证方案；二是通过工具命名隔离，避免与市场版 dsh-email 插件的功能冲突。

核心功能¶

该插件基于 imapflow 构建，为 DSH 模型提供以下工具：

1. ol_email_list：列出收件箱最近邮件，返回发件人、主题、时间和旗标。
2. ol_email_read：读取单封邮件全文，自动解析 MIME 格式。
3. ol_email_search：在服务端进行 IMAP 全文搜索，结果按最新优先排序。

除此之外，插件支持多账号配置、OAuth2 自动 token 刷新、HTTP/SOCKS 代理以及将所有工具的错误返回标准化为 { ok, ... } 格式，避免异常中断宿主服务。

安装¶

在 DSH 环境中执行以下命令安装插件：

dsh plugin --profile web add dsh-email-reader

配置¶

插件支持三种配置方式：OAuth2（推荐）、密码/应用专用密码，以及环境变量。以下为常见配置示例。

OAuth2 配置（Outlook 等）¶

对于微软 2024 年 9 月后仅支持 OAuth2 的账号，需提供 refreshToken 和 clientId。

- insert:
    - id: email-reader
      name: dsh-email-reader
      config:
        accounts:
          - id: outlook
            host: outlook.office365.com
            port: 993
            user: you@outlook.com
            refreshToken: "从 OAuth 授权流程获取"
            clientId: "你的应用 Client ID"
            tokenUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/token"
            mailbox: INBOX

代理配置（访问 Gmail）¶

当网络环境需要代理（如教育网访问 Google）时，可在账号配置中指定 proxy。

- insert:
    - id: email-reader
      name: dsh-email-reader
      config:
        accounts:
          - id: gmail
            host: imap.gmail.com
            port: 993
            user: you@gmail.com
            pass: your-app-password
            proxy: "http://127.0.0.1:7892"
            mailbox: INBOX

环境变量配置¶

若希望凭据不落盘，可使用环境变量。主要变量包括 DSH_IMAP_HOST、DSH_IMAP_USER、DSH_IMAP_PASS、DSH_IMAP_OAUTH_REFRESH、DSH_IMAP_CLIENT_ID 以及 DSH_IMAP_PROXY。

使用示例¶

插件提供的工具名称均以 ol_email_ 开头，以区别于其他市场版插件。

1. 列出邮件：调用 ol_email_list。
   • 提示词：「看下收件箱最近 5 封邮件」
2. 读取邮件：调用 ol_email_read。
   • 提示词：「读第 12 封邮件的内容」
3. 搜索邮件：调用 ol_email_search。
   • 提示词：「搜一下主题里含 ‘invoice’ 的邮件」

注意事项¶

1. 微软账号变更：微软自 2024 年 9 月起停止对个人 Outlook.com 账号支持 IMAP 基本认证（用户名+密码），仅支持 OAuth2。使用此类账号时必须配置 OAuth2。
2. 工具命名冲突：为了与市场版 dsh-email 插件共存，本插件注册的工具前缀为 ol_email_*（ol = Outlook）。
3. 错误处理：所有工具均返回 { ok, ... } 格式，绝不抛出异常，确保配置错误不会导致宿主程序崩溃。
4. 权限与安全：插件以当前 DSH 进程权限运行，配置凭据（尤其是密码和 Token）时需注意宿主的安全策略。

总结¶

dsh-email-reader 提供了基于 IMAP 的邮件读取能力，重点解决了微软账号的 OAuth2 认证问题，并通过命名空间隔离保证了生态兼容性。对于需要在智能体中集成邮件处理能力的开发者，这是一个直接可用的解决方案。

项目地址：https://github.com/huaxiren6/dsh-email-reader