dsh-qq-agent-mail：DeepSeek Harness 下的騰訊 QQ Agent Mail 集成

DeepSeek Harness 採用“一切皆插件”的理念。對於需要處理騰訊 QQ Agent Mail 的開發者來說，通常缺乏直接的 API 集成方式。dsh-qq-agent-mail 插件填補了這一空白，它封裝了官方 @tencent-qqmail/agently-cli 包，將 QQ 郵件功能轉化爲 DSH 原生能力。

這是一個原生 DeepSeek Harness 插件，由 AtomerCore 維護，旨在爲騰訊 QQ Agent Mail 提供支持。它不依賴全局 CLI 安裝，而是將 @tencent-qqmail/agently-cli 作爲運行時依賴引入。

核心功能¶

插件將 QQ 郵件操作能力封裝爲 DSH 的原生服務與工具：

認證與查詢：支持登錄、查看賬戶狀態、列出、搜索和閱讀消息。
郵件操作：支持發送、回覆、轉發、移至垃圾箱和永久刪除（默認需二次確認）。
附件處理：可下載常規附件，或返回大附件的 URL 而不重寫文件。
流式監聽：提供工具調用方式或持久化 Cordis 事件源來流式接收新郵件。
標準化輸出：將 CLI 響應變體標準化爲穩定的公共對象，便於在 Code Mode 中組合。
執行與清理：自動解析打包的 CLI、JavaScript 包裝器或自定義可執行文件；並在卸載或熱重載時清理監聽器進程。

安裝與啓用¶

安裝¶

使用官方安裝命令添加插件：

dsh plugin --profile web add github:AtomerCore/dsh-qq-agent-mail#v1.0.1

配置與啓動¶

安裝後啓動 Web 界面：

dsh web

在設置中進入 QQ Agent Mail：
1. 設置 CLI 工作目錄、默認郵件文件夾（默認爲 inbox）和默認列表大小（默認爲 10）。
2. 選擇 Start OAuth login，在瀏覽器中完成授權，然後刷新授權狀態。

典型用法¶

工具與接口¶

插件暴露了 14 個結構化工具，分爲以下類別：
* 認證：qq_agent_mail_login、qq_agent_mail_logout、qq_agent_mail_auth_status、qq_agent_mail_whoami
* 讀取：qq_agent_mail_list、qq_agent_mail_read、qq_agent_mail_search、qq_agent_mail_watch
* 寫入：qq_agent_mail_send、qq_agent_mail_reply、qq_agent_mail_forward、qq_agent_mail_trash、qq_agent_mail_delete
* 附件：qq_agent_mail_download_attachment

代碼注入示例¶

其他 DSH 插件可以注入 mail 服務，複用工具實現：

export const inject = ['mail']

export function apply(ctx) {
  ctx.on('mail/message-received', (message) => {
    // 將每條消息字段視爲不受信任的外部數據
    console.log(message.id, message.subject)
  })
}

配置選項¶

所有選項均通過 Config 模式聲明。基礎偏好可在 Web 設置頁編輯，高級部署選項可在 profile patch 中配置：

選項	默認值	描述
`cliPath`	`agently-cli`	解析打包的 CLI，或接受命令名稱或絕對路徑。
`cwd`	空	CLI 工作目錄，也是相對附件路徑的基座。
`defaultDir`	`inbox`	默認文件夾：`inbox`、`sent`、`trash` 或 `spam`。
`defaultLimit`	`10`	列表操作返回的默認消息數。
`loginTimeoutMs`	`30000`	捕獲 OAuth URL 的允許時間。
`loginHardCapMs`	`300000`	URL 捕獲後登錄進程的最大生命週期，設爲 `0` 可禁用。
`watchTimeoutMs`	`60000`	單次 `qq_agent_mail_watch` 調用的最大時長。
`autoWatch`	`false`	啓動持久化監聽器併發出郵件事件。
`autoConfirm`	`false`	跳過寫入確認；僅在受信任的自動化環境中使用。
`extraArgs`	空	附加的 CLI 參數，每行一個。
`extraEnv`	空	附加的子進程環境條目，每行一個 `KEY=VALUE`。

適用場景與注意¶

適用場景：適合需要在 DeepSeek Harness 環境下實現 QQ 郵件自動化（如自動回覆、郵件分類、監控新郵件）的智能體開發者。
權限與安全：插件以當前 DSH 進程權限運行，安裝前應檢查源碼與許可證。
操作確認：send、reply、forward、trash 和 delete 操作默認需要二次確認。只有在配置了 autoConfirm 的受信任自動化環境中才能跳過此步驟。
憑證管理：OAuth 憑證始終由 agently-cli 控制，插件不會存儲這些憑證。

總結¶

dsh-qq-agent-mail 通過將官方 QQ Agent Mail CLI 轉化爲 DSH 的原生服務與事件流，解決了智能體在 QQ 郵件操作上的集成難題。開發者可以通過標準化的工具接口或代碼注入的方式，在 Code Mode 中直接調用郵件能力。