gmail-dsh：DeepSeek Harness 的原生 Gmail 集成

DeepSeek Harness (DSH) 採用插件化架構，旨在將能力直接注入到工具運行時和憑證系統中。gmail-dsh 是一個原生插件，它不依賴 MCP 服務器或第三方運行時，而是直接註冊到 DSH 的命令系統和系統提示中。它通過瀏覽器 OAuth 流程處理 Google 授權，並將每個可變操作（發送郵件、修改標籤）的批准權交給用戶。

核心能力¶

該插件提供以下工具和命令：

gmail_search: 執行 Gmail 查詢搜索（例如 is:unread、from:x、newer_than:1w），按時間倒序排列，支持分頁。
gmail_read: 讀取完整消息，包含純文本（HTML 可選）、頭部、附件、標籤和所屬線程。
gmail_send: 發送純文本郵件；支持基於 replyTo 的線程回覆；發送前會向用戶發起批准請求。
gmail_labels: 對單條消息或整個線程添加或移除標籤；操作前會向用戶發起批准請求。
gmail_status: 顯示授權狀態，包括已授權賬號、默認賬號、OAuth 作用域和客戶端狀態。
/gmail 命令: 提供輔助命令，如 /gmail status、/gmail auth [email] 和 /gmail unauth [email]。
system-prompt: 在配置文件中添加一段系統提示，告知模型 Gmail 已連接（在授權前不消耗 token）。

安裝與啓用¶

克隆倉庫或準備項目目錄。
在 DSH 中安裝插件到指定 profile：

    dsh plugin --profile web add file:$PWD

在 profile 的 package.json 中將插件加入 bundles 列表：

    "dsh": {
      "profile": {
        "bundles": [
          "@deepseek-ai/dsh-base",
          "@deepseek-ai/dsh-web-app",
          "yolo-mode",
          "gmail-dsh"
        ]
      }
    }

重啓 dsh web 或等待 HMR 自動加載。

Google Cloud 配置¶

使用前需在 Google Cloud Console 中完成項目設置：

創建或選擇一個項目。
進入 APIs & Services → Enable APIs and Services，啓用 Gmail API。
配置 OAuth consent screen（選擇 External 或 Internal），並在測試階段將你的賬號加入測試用戶列表。
創建 OAuth client ID，類型選擇 Desktop application。下載 JSON 文件並提取 client_id 和 client_secret。

憑證存儲¶

將 Google OAuth 客戶端憑據存儲在 DSH 的憑證存儲中（推薦），或通過環境變量設置。在 ~/.dsh/.credentials.yaml 中添加：

version: 1
refs:
  GMAIL_OAUTH_CLIENT_ID: <your-client-id>
  GMAIL_OAUTH_CLIENT_SECRET: <your-client-secret>

授權與使用¶

在 DSH 會話中運行以下命令進行授權：

/gmail auth

瀏覽器會打開 Google 的授權頁面。批准後，插件會通過 PKCE (S256) + state 機制完成驗證，並將刷新令牌存儲在憑證存儲中。

檢查狀態：

/gmail status

移除賬號：

/gmail unauth [email]

典型操作示例：
* 搜索：使用 gmail_search 查詢未讀郵件。
* 讀取：使用 gmail_read 獲取郵件內容。
* 發送：使用 gmail_send 發送郵件，系統會提示輸入收件人和主題。
* 管理：使用 gmail_labels 對郵件打標籤，系統會提示輸入標籤名稱和目標。

配置與注意事項¶

配置項¶

可以通過覆蓋 cordis.patch.yml 或環境變量調整配置，默認配置包括：
* scopes: [openid, email, gmail.modify]
* callbackHost: 127.0.0.1
* callbackPath: /gmail/callback

開發注意事項¶

Node 模塊解析：對於 file: 安裝，Node 需要能夠向上查找 @deepseek-ai 導入。如果缺少 node_modules/@deepseek-ai 符號鏈接，請手動創建。
pnpm 與開發：使用 pnpm 安裝時，file: 包會被複制到 node_modules（凍結快照），後續代碼修改不會生效。開發時建議移除已安裝的包並用符號鏈接指向檢出目錄。
批准機制：所有讀操作（搜索/讀取）不會提示用戶。只有發送和標籤操作會觸發 ask 決策。如果沒有掛載批准服務，這些操作會被降級爲拒絕，確保插件在無權限環境下是隻讀的。

總結¶

gmail-dsh 爲 DeepSeek Harness 代理提供了直接、安全的 Gmail 訪問能力。通過原生集成和基於提示的批准流程，它既滿足了代理自動化郵件操作的需求，又規避了未經授權的修改風險。