前言¶

在 DSH 裏讓模型讀信、搜信、發信，常見做法是自建 HTTP 封裝或把郵箱當成「外部 API」來回拼。QQ 郵箱側已有官方 MCP 網關與 OAuth，但若每次都要重新掃碼、令牌輪換後兩邊不同步，智能體會頻繁斷鏈。維護者 0Sakura721 的 dsh-qqmail 把 QQ 郵箱接進 Harness：註冊 12 個原生工具，覆蓋收、發、搜、附件；憑據可複用本機 WorkBuddy 已授權 OAuth 令牌並自動續期，也可手工配置 credentials.json。插件分類爲聯網工具，許可證 MIT，當前 package.json 版本爲 1.0.0，運行環境要求 Node.js ≥ 22。

下面按定位、能力、安裝、授權、發信確認與配置說明用法；安裝命令與配置字段均出自倉庫 README，不憑插件名拼接 CLI。

這是什麼¶

dsh-qqmail 是 DeepSeek Harness 的 bundle 插件，通過 Streamable-HTTP 客戶端連接 QQ 郵箱官方 MCP 網關 https://api.mail.qq.com/mcp，在 profile 內注入工具定義與一段系統提示詞約定。它不實現 POP3/IMAP 直連，能力邊界與網關暴露的 12 個工具一致。

插件以當前 DSH 進程權限運行，會讀寫本機 ~/.dsh/qqmail/ 下的憑據與日誌；安裝前應閱讀源碼與許可證，並確認你願意讓 Harness 代表你調用郵箱讀寫接口。

核心功能：12 個工具¶

讀信與檢索類工具不需要用戶二次確認；發信、回覆、轉發、刪信、清空垃圾箱等會觸發網關的兩階段確認（見後文）。

工具	作用	需要確認
`qqmail_get_me`	授權狀態、主/附屬賬號、權限、限額	—
`qqmail_list_messages`	列郵件（文件夾 / 時間 / 已讀 / 附件篩選 + 翻頁）	—
`qqmail_get_message`	讀單封全文（HTML 自動轉純文本）	—
`qqmail_search_messages`	關鍵詞 / 發件人 / 收件人 / 時間搜索	—
`qqmail_list_attachments`	列附件元信息	—
`qqmail_download_attachment`	附件落盤（默認系統下載目錄）	—
`qqmail_send_message`	發新信	✓
`qqmail_reply_message`	回覆（可 reply_all）	✓
`qqmail_forward_message`	轉發（可帶原附件）	✓
`qqmail_delete_message`	移入垃圾箱（30 天可恢復）	✓
`qqmail_permanent_delete_message`	永久刪除	✓
`qqmail_clear_trash`	清空垃圾箱	✓

實現上插件採用懶連接：加載時不建連，首次真正調用工具才 initialize，避免憑據暫時不可用時把整個 profile 拖到 failed。qqmail_get_me 結果緩存 5 分鐘，減輕網關「10 次/分鐘」限速帶來的 alias 查詢壓力。

附件在本地會先校驗：服務端限制以實測爲準（README 記載爲 3 個附件、單文件 1MB、合計 3MB）；批量高頻調用仍可能觸達網關 200 次/小時等限額。

發信與破壞性操作：兩階段確認¶

QQ 郵箱 MCP 網關對發信、刪信等操作強制兩階段確認，插件不做「替用戶點頭」的短路。不帶 confirmation_token 的請求只會得到 42801 與摘要信息，不會真正執行。

模型
 └─ qqmail_send_message（不帶 token）
     └─ QQ 郵箱 MCP 網關 → 42801 + confirmation_token + operation_summary
         └─ 插件把摘要與 token 交給模型
             └─ 模型 ask_user_question → 用戶點確認
                 └─ 模型帶 token 重發 → 真正發出

因此在典型用法裏，模型先發一次不帶 token 的 qqmail_send_message，向用戶展示 operation_summary，用戶確認後再帶 confirmation_token 重發。刪信、清空垃圾箱同理。

安裝與啓用¶

DSH 通過 bundle 機制加載本插件；源碼可放在任意工作目錄，例如 ~/.dsh/plugins/dsh-qqmail。

# 1. 把本倉庫放到一個工作目錄，例如 ~/.dsh/plugins/dsh-qqmail
# 2. 安裝到 profile（把路徑換成你本地實際路徑）
plugin_manager install_bundle  action: install_bundle  target: <倉庫絕對路徑>

也可以手動把依賴寫入 profile 的 package.json，並在 dsh.profile.bundles 中掛載，再讓 Loader 重載。

裝完後插件自動註冊 12 個工具，並把使用約定寫入系統提示詞。插件入口爲 index.js，掛載聲明在 cordis.patch.yml（inject: [tools, systemPrompt]）。

授權：兩條路徑¶

路一：從 WorkBuddy 借用（推薦）¶

WorkBuddy 桌面端把 QQ 郵箱 OAuth 令牌加密存在本地，插件可解密借用並接管續期，首次調用工具時落盤到 ~/.dsh/qqmail/credentials.json（權限 0600）。

涉及文件：

~/.workbuddy/connectors/<userId>/.master.key —— 32 字節主密鑰
~/.workbuddy/connectors/<userId>/.credentials.v3.json —— 密文令牌

QQ 郵箱的 refresh_token 爲一次性輪換：續期後插件除更新自有 credentials.json，還會按原格式加密回寫 WorkBuddy 憑據（lib/seal.js），避免 WorkBuddy 側 refresh_token 先於插件失效。網關對已失效 refresh 的響應形態爲 HTTP 200 + 空 body + LogicRet: -21653，插件會歸類爲 REFRESH_TOKEN_DEAD 而非泛化網絡錯誤。

路二：手工放置令牌¶

無 WorkBuddy 時，可將帶 refresh_token 的授權結果寫入 ~/.dsh/qqmail/credentials.json：

{
  "serverUrl": "https://api.mail.qq.com/mcp",
  "clientId": "<你的 OAuth client id>",
  "accessToken": "<access token>",
  "refreshToken": "<refresh token>",
  "expiresAt": 1794108777023,
  "scope": "alias:read mail:read mail:send mail:delete"
}

clientId 留空時退回內置公共客戶端 id。

授權失效時：刪除 credentials.json，下次調用會嘗試重新從 WorkBuddy 借用；若 WorkBuddy 側也失效，需在 WorkBuddy 內重新掃碼。

可選配置¶

~/.dsh/qqmail/config.json 示例：

{
  "downloadDir": "~/Downloads",
  "confirmTtlMs": 300000,
  "workbuddyAutoImport": true,
  "workbuddyReseal": true,
  "timeoutMs": 60000,
  "promptSection": true
}

同名鍵也可寫在 cordis.patch.yml 的 config 中（行配置優先於文件）。defaultAlias 可填，一般留空由插件自動取主賬號。

狀態與日誌路徑：

~/.dsh/qqmail/credentials.json —— 當前令牌
~/.dsh/qqmail/qqmail.log —— 續期、連接、回封記錄（不含明文令牌）

排障與自檢¶

倉庫 tools/ 下提供面向真實賬號的腳本，需在 profile 目錄執行以便包名解析：

cd ~/.dsh/profiles/<你的 profile>

node <倉庫>/tools/diag.mjs         # 憑據 + 連接 + 工具清單 + 主賬號
node <倉庫>/tools/live.mjs         # 走註冊後的 wrapped execute 路徑
node <倉庫>/tools/tools-run.mjs    # 逐個跑讀取類工具
node <倉庫>/tools/tools-run.mjs --send-to me@example.com   # 額外驗證二次確認第一階段
node <倉庫>/tools/check-sent.mjs   # 確認自檢信沒有真的發出
node <倉庫>/tools/dead.mjs         # 用僞造令牌驗證 REFRESH_TOKEN_DEAD 分類
node <倉庫>/tools/recover.mjs <json>  # 令牌斷鏈後恢復並雙向回封

tools/recover.mjs 可在 refresh 斷鏈時，用含 refresh_token 的 JSON 續期一次，並同時寫回 credentials.json 與 WorkBuddy 的 .credentials.v3.json。

適用場景與注意¶

適合誰： 已在 DSH profile 中開發郵件相關智能體、且主要使用 QQ 郵箱官方 MCP 能力的開發者；本機已用 WorkBuddy 完成 QQ 郵箱 OAuth、希望 Harness 與桌面端共用同一套令牌生命週期時，路一授權路徑更省事。

務必注意：

插件依賴 QQ 郵箱官方 MCP 網關與其 OAuth 服務，無網關未暴露的能力。
破壞性寫操作必須經過用戶確認，模型側需配合 ask_user_question 與帶 token 的重試。
網關限速與附件上限以服務端爲準，批量自動化需控制調用頻率。
社區目錄 SkillHub 與 DeepSeek / 幻方無官方從屬關係；插件星標與傳播數據以各站點展示爲準（目錄線索爲聯網工具類）。

第一次使用可參閱倉庫內從零開始使用（前提條件、安裝路徑與授權路徑、發信確認卡片說明）。

結尾¶

dsh-qqmail 把 QQ 郵箱的 12 個 MCP 能力原樣註冊進 Harness，並用 WorkBuddy 複用與 refresh 回封降低令牌維護成本；讀信搜信可直接編排，寫操作則遵守網關強制的兩階段確認。查閱與安裝線索：

社區目錄頁：https://www.skillhub.cn/plugins/0Sakura721/dsh-qqmail
源碼與 README：https://github.com/0Sakura721/dsh-qqmail

dsh-qqmail：在 DeepSeek Harness 裏用 12 個原生工具操作 QQ 郵箱

前言¶

這是什麼¶

核心功能：12 個工具¶

發信與破壞性操作：兩階段確認¶

安裝與啓用¶

授權：兩條路徑¶

路一：從 WorkBuddy 借用（推薦）¶

路二：手工放置令牌¶

可選配置¶

排障與自檢¶

適用場景與注意¶

結尾¶

精选优惠券

dsh-qqmail：在 DeepSeek Harness 裏用 12 個原生工具操作 QQ 郵箱

前言¶

這是什麼¶

核心功能：12 個工具¶

發信與破壞性操作：兩階段確認¶

安裝與啓用¶

授權：兩條路徑¶

路一：從 WorkBuddy 借用（推薦）¶

路二：手工放置令牌¶

可選配置¶

排障與自檢¶

適用場景與注意¶

結尾¶

精选优惠券

相關文章