dsh-qq-email
用已授权的 agently-cli 发一封 QQ 邮件。一个包，两种用法：
| 用法 | 入口 | 给谁用 |
|---|
Cordis 服务 ctx.qqEmail | service.js（exports["."]） | 其他插件：inject: ['qqEmail'] 后直接调用 |
Agent 工具 send_qq_email | tool.js（exports["./tool"]） | 对话里直接说「给 xxx 发封邮件」 |
发送逻辑只在服务层实现一次；工具只是参数翻译层。两行插件可以独立开关
（见 cordis.patch.yml）。
功能
- 对话里发邮件：模型调用
send_qq_email，DSH 弹出确认卡，用户批准后才真正发送。
- 其他插件发邮件：
ctx.qqEmail.send(...)；也可以自己管理确认 UX
（prepare() → 自己问用户 → commit()）。
- 预检与发送分离：
prepare() 只拿确认令牌，不会发信。
- 默认 fail-closed：没有批准、没有确认入口、没有
confirmedByCaller 都不会发送。
前置条件
-
Node.js ≥ 22.19（DSH 运行环境自带）。
-
DSH 0.2.x（见 package.json 的 engines.dsh）。
-
本机安装并授权 agently-cli：
npm install -g @tencent-qqmail/agently-cli
agently-cli auth login
agently-cli +me # 能打印出邮箱地址即授权成功
插件本身不保存、不接触 OAuth 凭据：令牌由 agently-cli 自己管理
（Windows 上是 DPAPI），插件只是以当前进程身份调用这个 CLI。
安装
发布到 npm 后：
dsh plugin --profile web add dsh-qq-email
也可以直接从 GitHub 安装（包内是纯 JS，无构建步骤，不需要 allowBuilds 授权）：
dsh plugin --profile web add github:altmanWang/dsh-qq-email
或本地目录（开发时）：
dsh plugin --profile web add /绝对路径/plugin/dsh-qq-email
装完重启 dsh web（或刷新页面）；在 Web UI 的插件页能看到两行：服务与工具。
使用：在对话里
直接说：
帮我给 alice@qq.com 发一封邮件，主题「项目进度同步」，正文「本周已完成 X，下周计划 Y」；抄送 bob@qq.com。
模型调用 send_qq_email 后会弹出确认卡（发件人 / 收件人 / 抄送 / 密送 / 主题 / 正文预览），
只有点「批准」才会发送。
使用：在其他插件里
// 你的插件入口
export const inject = ['qqEmail']
export function apply(ctx) {
// 1) 最常用：完整流程。传 agent 上下文时，服务会弹出确认提示，用户批准后才发送。
const sent = await ctx.qqEmail.send(
{ to: 'alice@example.com', subject: '周报', body: '见附件' },
{ agent, callId, signal },
)
// 2) 自己管确认 UX（例如在 IM 频道里问）：先预检，用户点头后再提交。
const pending = await ctx.qqEmail.prepare({ to: 'a@qq.com', subject: 'Hi', body: '你好' })
// …向用户展示 pending.summary / pending.request，拿到许可…
const sent2 = await ctx.qqEmail.commit(pending, { signal })
// 3) 查当前授权账号与额度（默认缓存 60 秒）
const { email, scopes, rateLimits } = await ctx.qqEmail.account()
}
agent 必须是完整的 DSH Agent 对象（工具里的 exec.agent），只传 { id }
会在 approval 服务内部报错。commit() 自身不做用户确认；只要用了
prepare() + commit()，确认责任就在调用方。
类型
types.d.ts 只包含纯类型声明、不引用任何 @deepseek-ai/*，所以任何 TS 工程都能引用。
它不做 ctx.qqEmail 的模块增强（增强在外部安装形态下可能解析不到 cordis 类型而静默失效），
请在你的插件里自己写三行：
import type { Context } from '@deepseek-ai/cordis'
import type { QqEmailService } from 'dsh-qq-email/types'
declare module '@deepseek-ai/cordis' {
interface Context { qqEmail: QqEmailService }
}
配置
CLI 入口按以下顺序解析，第一个存在的生效：
- 环境变量
DSH_QQ_EMAIL_CLI（指向 .../agently-cli/scripts/run.js 的绝对路径）
- 插件 config 的
cliEntry 字段（在 profile patch 里给该行加 config:）
- 各平台 npm 全局前缀推导：Windows 的
%APPDATA%\npm、Program Files\nodejs、
%LOCALAPPDATA%\pnpm；POSIX 的 /usr/local、/usr、/opt/homebrew、
~/.npm-global、nvm 的各 Node 版本前缀
# profile 的 cordis.patch.yml
- id: qq-email-service
name: dsh-qq-email
config:
cliEntry: C:\Users\me\AppData\Roaming\npm\node_modules\@tencent-qqmail\agently-cli\scripts\run.js
确认与安全模型
- 两道确认：CLI 自身的两阶段（
prepare 拿 ctk_* 令牌，commit 才发送）+ DSH 的
approval。工具路径下用户必须在界面上点「批准」；rejected / cancelled /
unavailable 一律不发送。
- 确认前不可变：
prepare() 返回的 request 被深度冻结，确认卡里的收件人 / 主题
与实际发送内容来自同一份数据。
- 正文传输方式：正文通过 argv 内联传给 CLI，因此它可能出现在本机进程命令行里
（同用户可读）。高度敏感的内容请注意这一点；同时 Windows 命令行长度有限，
超长请求会提前报
QQ_EMAIL_ARGS 而不是运行到一半失败。
- 取消/超时的语义：预检阶段被取消 = 一定没发；发送阶段被取消或超时 = 结果未知，
错误信息会提示先检查「已发送」，不要直接重试。
- 确认令牌过期：令牌默认 5 分钟，用户思考过久时
send() 会在批准后用同一请求
重新预检一次再发送，内容不变。
限制
- 只发送，不读信、不回复、不转发、不带附件（需要这些能力请直接用 agently-cli）。
- 主题按 UTF-8 4 KB 限制（约 1365 个汉字）；正文最多 20000 字符。
- 收件人（to+cc+bcc）最多 50 个；同一地址不能同时出现在 cc 和 bcc。
- 工具路径必须由用户在 DSH 里确认；无头/自动化场景请用
confirmedByCaller: true
的插件调用路径，并自行负责确认。
错误码
按 error.code 分支，不要匹配文案：
| code | 含义 |
|---|
QQ_EMAIL_ARGS | 请求不合法（地址、主题字节数、正文、命令行过长等） |
QQ_EMAIL_CLI_MISSING | 找不到 agently-cli，错误信息里带全部候选路径 |
QQ_EMAIL_CLI_FAILED | CLI 退出非 0 / ok:false / 调用被取消、超时；授权失效与限频会附操作提示 |
QQ_EMAIL_NOT_CONFIRMED | 用户没批准 / 没有确认入口 / 缺 confirmedByCaller |
QQ_EMAIL_UNEXPECTED | CLI 返回了预期之外的信封（协议变更、只返回预检结果等） |
开发与测试
npm test
npm test 是 hermetic 的：用 tests/fixtures/fake-cli.mjs 冒充 agently-cli，覆盖
预检/发送/确认拒绝/空令牌/空信封/取消等路径，不联网、不发信。
真实 CLI 的只读集成测试默认跳过，显式开启：
DSH_QQ_EMAIL_INTEGRATION=1 npm test
注意：DSH 的 Windows 沙箱会禁止被约束进程用管道 spawn 子进程（spawn EPERM），
在沙箱内跑测试时 spawn 类用例会自动跳过——它们真正覆盖的是未约束的 Host/CI 环境。
License
MIT
