前言¶

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