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 中直接调用邮件能力。