emailcli 技能

当需要通过 mail-cli 命令行客户端与用户邮箱交互时，请使用此技能。

快速参考

# 安装（如尚未安装）
npm install -g @laffy1309/emailcli

# 命令
mail-cli list [--folder FOLDER] [--limit N] [--account EMAIL:PROVIDER]
mail-cli read  [--thread] [--download [dir]]
mail-cli search "" [--account EMAIL:PROVIDER]
mail-cli send --to  --subject "" --body "" [--cc ] [--bcc ] [--attach ] [--save-draft] [--draft ]
mail-cli reply  --to  [--cc ]
mail-cli mark  --read|--unread
mail-cli mark --ids 1,2,3 --read|--unread  # 批量操作
mail-cli move  --folder ""
mail-cli move --ids 1,2,3 --folder ""  # 批量操作
mail-cli delete 
mail-cli delete --ids 1,2,3  # 批量操作
mail-cli folders [--account EMAIL:PROVIDER]
mail-cli status
mail-cli drafts --list|--delete 
mail-cli account list|add --provider gmail|outlook|remove --account EMAIL:PROVIDER|--all

账户格式

所有账户均采用 email:provider 格式：

• Gmail：me@gmail.com:gmail
• Outlook：me@outlook.com:outlook

当存在多个账户时，需使用 --account EMAIL:PROVIDER 明确指定目标账户。 若未指定账户，CLI 将默认内部使用 default:gmail。

JSON 输出

所有命令均返回 JSON 格式输出，可通过程序解析：

成功响应：

{"ok": true}
{"id": "abc123", "from": "sender@example.com", "subject": "Hello", "date": "2024-01-01T00:00:00Z"}
[{"id": "1", "from": "a@example.com"}, {"id": "2", "from": "b@example.com"}]
{"id": "...", "saved": true}   // --save-draft 的输出
{"removed": ["a@g.com:gmail", "b@outlook.com:outlook"]}  // account remove --all 的输出

错误响应：

{"error": {"code": "NO_ACCOUNTS", "message": "No accounts configured. Run 'mail-cli account add --provider gmail' first."}}
{"error": {"code": "DRAFT_NOT_FOUND", "message": "Draft with ID 'xxx' not found"}}
{"error": {"code": "MISSING_FLAG", "message": "Either --account  or --all is required"}}

批量操作部分失败：

{"ok": true, "failed": [{"id": "2", "error": {"code": "NOT_FOUND", "message": "Email not found"}}]}

命令模式

列出邮件

# 默认：最近 20 封收件箱邮件
mail-cli list

# 指定文件夹（Gmail 使用方括号）
mail-cli list --folder "[Gmail]/Sent"

# 限制结果数量
mail-cli list --limit 50

# 指定账户
mail-cli list --account me@gmail.com:gmail

阅读邮件

# 按 ID 查看单封邮件（ID 可从 list 输出中获取）
mail-cli read abc123

# 查看完整会话线程
mail-cli read thread-456 --thread

# 阅读并下载附件至当前目录
mail-cli read abc123 --download

# 阅读并下载附件至指定目录
mail-cli read abc123 --download ./attachments

搜索邮件

# Gmail 搜索语法
mail-cli search "from:foo subject:bar has:attachment"

# Outlook KQL 语法
mail-cli search "from:foo subject:bar"

发送邮件

# 基础发送
mail-cli send --to recipient@example.com --subject "Hello" --body "Message"

# 包含 CC/BCC
mail-cli send --to recipient@example.com --cc other@example.com --bcc hidden@example.com --subject "Hello" --body "Message"

# 从文件读取正文
mail-cli send --to recipient@example.com --subject "Hello" --body-file-path message.txt

# 附加文件
mail-cli send --to recipient@example.com --subject "Hello" --body "Message" --attach file.pdf

# 保存为草稿（不发送）
mail-cli send --to recipient@example.com --subject "Hello" --body "Message" --save-draft

# 加载并发送已有草稿
mail-cli send --draft draft-id-123 --subject "Updated Subject"

回复邮件

mail-cli reply  --to sender@example.com
mail-cli reply  --to sender@example.com --cc other@example.com

标记邮件

# 单封邮件
mail-cli mark abc123 --read
mail-cli mark abc123 --unread

# 批量操作 —— ID 以逗号分隔（不可含空格）
mail-cli mark --ids 1,2,3 --read

移动邮件

# 单封邮件
mail-cli move abc123 --folder "[Gmail]/Trash"

# 批量操作
mail-cli move --ids 1,2,3 --folder "[Gmail]/Archive"

删除邮件

# 单封邮件（移入回收站）
mail-cli delete abc123

# 批量操作
mail-cli delete --ids 1,2,3

文件夹操作

# 列出所有文件夹
mail-cli folders

# 邮箱状态（各文件夹邮件数量）
mail-cli status

草稿管理

# 列出所有已保存的草稿
mail-cli drafts --list

# 按 ID 删除草稿
mail-cli drafts --delete draft-id-123

账户管理

# 添加账户
mail-cli account add --provider gmail
mail-cli account add --provider outlook

# 列出所有账户
mail-cli account list

# 删除指定账户
mail-cli account remove --account me@gmail.com:gmail

# 删除全部账户
mail-cli account remove --all

工作流

检查收件箱

1. 运行 mail-cli list 获取最新邮件列表
2. 解析 JSON 输出 —— 每封邮件包含 id、from、subject、date 字段
3. 向用户呈现摘要信息
4. 用户可按 ID 请求查看特定邮件

发送邮件

1. 收集收件人、主题、正文（以及可选的 CC、附件）
2. 构造命令，并确保参数正确转义
3. 执行命令并检查响应是否为 {"ok": true} 或含 error 字段
4. 向用户报告成功或具体错误信息

保存草稿

1. 撰写邮件但暂不发送
2. 使用 --save-draft 参数替代发送操作
3. 输出 {"id": "...", "saved": true} 中的 id 即为该草稿 ID，可用于后续操作

加载并编辑草稿

1. 使用 mail-cli drafts --list 列出所有草稿
2. 使用 mail-cli send --draft 加载指定草稿
3. 通过命令行参数覆盖任意字段（CLI 参数优先级高于草稿原始内容）
4. 成功发送后，对应草稿将自动删除

搜索并执行操作

1. 使用合适的查询语法运行 mail-cli search
2. 向用户展示搜索结果
3. 用户可基于返回的 ID 对邮件执行标记、移动或删除等操作

批量操作

1. 获取 ID 列表（来自 list 或 search 输出）
2. 使用 --ids 1,2,3 格式（逗号分隔，不可含空格）
3. 检查响应中的 failed 数组，识别部分失败项

下载附件

1. 阅读邮件时添加 --download 或 --download
2. 附件将保存至指定目录（或当前目录）
3. 输出中包含 downloads 数组，其中每个元素含附件的文件名、路径及大小

错误处理

若收到错误响应，请按以下步骤处理：

1. 提取 error.code 和 error.message
2. 向用户清晰说明问题
3. 如适用，提供修复建议：
   • NO_ACCOUNTS：运行 mail-cli account add --provider gmail|outlook
   • NOT_FOUND：该消息 ID 不存在，或已被删除
   • INVALID_CREDENTIALS：先运行 mail-cli account remove，再运行 mail-cli account add 重新认证
   • DRAFT_NOT_FOUND：该草稿 ID 不存在，或已被发送/删除
   • MISSING_FLAG：缺少必需参数（例如对 account remove 命令，需指定 --account 或 --all）
   • CONFLICTING_FLAGS：不可同时使用 --account 和 --all

重要说明

• 始终使用 JSON 解析输出 —— CLI 仅输出 JSON
• Gmail 文件夹名称含方括号：[Gmail]/Sent、[Gmail]/Trash、[Gmail]/Archive
• 从 list 或 search 返回的消息 ID 均为字符串，请严格保留原样
• 批量操作 ID 必须以逗号分隔且不含空格：--ids 1,2,3
• 回复操作必须同时提供消息 ID 和 --to 参数（含收件人地址）
• 未指定 --account 时，命令默认使用首个可用账户
• 草稿存储于本地，跨会话持久化
• --save-draft 与 --draft 在同一命令中互斥