前言¶
在 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
