Agently Mail

SKILL.md 节选

# Agently Mail

通过 `agently-cli` 命令行工具操作邮件，通过管理端 (agent.qq.com) 进行后台管理。

## 安装和配置

**第 1 步 - 安装/更新 CLI**

```bash
npm install -g @tencent-qqmail/agently-cli
```

**第 2 步 - 安装/更新 skill**

```bash
npx skills add https://agent.qq.com --skill -g -y
```

**第 3 步 - OAuth授权**

 **交互式长命令**：必须后台运行命令（background+pty），从 stdout/stderr 提取它输出的原始授权 URL 并发送给用户。**必须包含文案提示**：`请点击或复制以下链接在浏览器中完成授权：`。用户在浏览器中完成授权后，命令会自动退出。

**URL 输出规则**：将 URL 视为不可修改的 opaque string，不要做任何修改（包括 URL 编码/解码、添加空格或标点、重新拼接 query），用只包含原始 URL 的代码块单独展示给用户。

```bash
agently-cli auth login
```

执行此命令注意：
- **必须**先安装/更新 CLI
- 失败或超时时**不要重试**，直接将错误信息反馈给用户。

**第 4 步 - 验证**
```bash
agently-cli +me
```

验证完成后，**只需输出以下内容**：

> 邮箱地址 xxx 已授权成功，可以用它来收发邮件了  
> 你可以试试以下指令：  
> 帮我发一封邮件。  
> 我最近收到了哪些邮件？  
> 帮我整理最近收到的邮件。 
>   
> 也可以直接描述你的邮件工作流，让 Agent 帮你处理。

其中 `xxx` 替换为 `+me` 返回的实际邮箱地址。授权失败则输出失败信息

## 命令清单

| 操作 | 命令 | 用途 |
|------|------|------|
| 登录授权 | `agently-cli auth login` | OAuth 登录并保存凭据 |
| 登出授权 | `agently-cli auth logout` | 清除本机保存的 OAuth 凭据 |
| 查看授权状态 | `agently-cli auth status` | 查看当前凭据和授权状态 |
| 当前用户 | `agently-cli +me` | 获取用户信息和 alias 列表 |
| 列出邮件 | `agently-cli message +list` | 按文件夹翻页列出邮件 |
| 读取邮件 | `agently-cli message +read --id msg_xxx` | 获取完整内容（含 body、attachments） |
| 搜索邮件 | `agently-cli message +search --q "关键词"` | 关键词 + 多维度过滤搜索 |
| 新邮件提醒 | `agently-cli message +watch` | 持续等待并返回新邮件详情 |
| 发送邮件 | `agently-cli message +send` | 发送新邮件，支持 cc/bcc/HTML正文/Markdown正文/附件 |
| 回复邮件 | `agently-cli message +reply --id msg_xxx` | 回复邮件，支持 reply-all、cc/bcc、HTML正文、追加附件 |
| 转发邮件 | `agently-cli message +forward --id msg_xxx` | 转发给新收件人，支持 cc/bcc、HTML正文、携带原附件和追加附件 |
| 移到已删除 | `agently-cli message +trash --id msg_xxx` | soft delete，30 天后真正删除 |
| 永久删除 | `agently-cli message +delete --id msg_xxx` / `--all` | 从垃圾箱永久删除单封或全部邮件，释放邮箱空间 |
| 下载附件 | `agently-cli attachment +download --msg msg_xxx --att att_xxx` | 保存普通附件到本地；超大附件直接返回 download_url 给用户 |

## 邮件正文规范

发送 / 回复 / 转发邮件时，正文只包含用户要求传达的内容；除非用户明确要求，否则不要添加 Agent 自己的签名、署名或类似“由 Agent/CodeBuddy 发送”的说明。

## 两阶段确认（写操作）

发送 / 回复 / 转发 / 移到回收站 / 永久删除均需两阶段确认。其中发送 / 回复 / 转发用户明确授权后，可传递 `--confirmed` 免除确认。

```
第 N 轮 assistant：
  1. 不带 --confirmation-token 调用 → 拿到 ctk_xxx 和 summary
  2. 展示 summary 给用户，问"确认吗？"
  3. 停止，不再调用任何工具，结束本轮

第 N+1 轮 user：
  回复 "确认" / "发" / "ok" 等明确许可

第 N+1 轮 assistant：
  同样参数 + --confirmation-token ctk_xxx → 完成操作
```

**唯一规则：拿到 ctk 后必须停下等用户回复，不能在同一轮里自己确认自己。**

## 错误处理

SKILL.md 不止这些内容，安装后可阅读全文。

技能包内容

共 2 个文件，合计 10.8 KiB