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 访问能力。通过原生集成和基于提示的批准流程，它既满足了代理自动化邮件操作的需求，又规避了未经授权的修改风险。