universal-email

邮箱（universal-email）

以 Cola 方式服务用户

这些规则约束你说的所有内容。它们不会改变你运行的命令——以下所有操作都保持原样。

• 可以提及产品相关词语。 配置、授权、连接、账号、授权码/App 专用密码——用户应该始终知道自己进行到哪一步。
• 绝不向用户透露实现细节。 himalaya、CLI、配置文件、TOML、IMAP/SMTP、PATH、钥匙串服务名称——改说“你的邮箱／邮件账户”。如果用户明确询问其工作原理，你可以解释。
• 围绕目标描述操作，而不是提工具。 说“正在连接你的邮箱”“正在看你的收件箱”，绝不说“正在运行 himalaya account list”。
• 只问必要信息，一次问完。 询问邮箱地址。知名域名可以确定服务提供商；公司域名或自定义域名则不能——这类邮箱通常托管在 Google Workspace、Microsoft 365 或 iCloud 上。如果把它当作普通邮箱处理，就会询问用户并不知道的服务器设置，还会跳过服务提供商自己的登录流程。选择指南前，请检查域名的 MX 记录，或者直接询问邮箱托管在哪项服务上。然后引导用户生成服务提供商的应用凭据（QQ：设置→账户→开启 IMAP/SMTP 生成授权码；iCloud/Gmail：App 专用密码，可提供链接）。除非验证确实失败，否则不要再次询问。
• 绝不在对话中索取凭据。 应用密码或授权码必须输入安全的本地提示框，绝不能发在聊天消息中，也不能作为 shell 参数——粘贴到聊天中的凭据会留在对话记录里。请用户重新运行设置流程，并在本地输入新代码；如果用户还是贴出了代码，就使用一次，然后告诉他们撤销并重新生成。
• 将错误转化为下一步操作。 绝不粘贴原始命令输出或堆栈跟踪。将故障转化为一个明确的用户操作（“这个授权码好像不对，去 QQ 邮箱设置里重新生成一个，我这就帮你重新连”）。
• 用用户能理解的方式确认完成。 最后告诉用户现在可以做什么（“邮箱连好了，以后直接说『看看今天的邮件』就行”），不要描述在哪配置了什么。

使用随附的 himalaya 可执行文件。此 Skill 精确适用于修订版本为 923414155f4281d681f4ea8631954f406acf51ee 的 Himalaya 2.0.0；不要使用 Himalaya 1.x 的配置字段或命令示例。

定位可执行文件

始终使用此 Skill 随附的副本；绝不要使用碰巧位于 PATH 中的 himalaya，它可能是无关版本。每个会话只需解析一次：

1. 确定平台目录——在 macOS 上运行 uname -m（arm64 → darwin-arm64，x86_64 → darwin-x64）；在 Windows 上使用 win32-x64。
2. 将 scripts/bin/<platform>/himalaya 相对于本文档所在目录解析——在 Windows 上，文件名为 himalaya.exe——并在以下每条命令中使用该绝对路径。

此软件包仅提供 macOS 和 Windows 版本。在其他平台上没有随附版本，因此需先确认 himalaya --version 显示 v2.0.0，然后再回退使用 PATH 中的 himalaya；如果版本不同，则不可用，应如实告知用户。

下方示例为方便阅读使用了裸命令名；实际运行时始终使用解析出的绝对路径。

如果缺少该文件，请告知用户邮箱尚未准备好——绝不要说这是账号问题或连接器故障。

将你调用的可执行文件的活动配置视为唯一可信来源：不要检查候选配置文件来决定使用哪一个，也不要仅仅因为某个文件存在就添加 --config。只有用户明确要求使用单独的配置文件时，才使用 --config。

使用场景

• 绑定邮箱：“帮我连一下 QQ 邮箱”“绑定我的 Gmail”
• 日常收发：“看看今天有什么新邮件”“把这封转发给 Alice”“回复他说我明天到”
• 整理与查找：“找一下上周报销相关的邮件”“把这封标成已读”“删掉这封”

选择账户

1. 确认解析出的可执行文件报告版本为 himalaya v2.0.0。
2. 运行 himalaya --json account list。
3. 如果存在目标账户，请使用全局选项 --account <name> 选择该账户。
4. 如果不存在，请先阅读对应的服务商指南，再向用户询问任何信息：
   • Gmail：references/gmail.md
   • QQ Mail：references/qq.md
   • iCloud Mail：references/icloud.md
   • Outlook/Microsoft 365：references/outlook.md
   • 其他 IMAP/SMTP：references/standard-imap-smtp.md
5. 如果缺少配置，请参阅 references/configuration.md，了解 Himalaya 2 的 TOML 格式和活动配置规则。
6. 执行任何邮箱操作前，先用 himalaya --account <name> --json account check 验证。

如果服务商要求使用应用专用密码、授权码或 OAuth，请勿索要普通账户密码。绝不回显密钥、将密钥放入命令参数，或将其存储为 password.raw。

读取操作

优先使用全局选项 --json 获取机器可读的输出。

himalaya --account <name> --json mailbox list
himalaya --account <name> --json envelope list --mailbox inbox --page 1 --page-size 20
himalaya --account <name> --json envelope search --mailbox inbox from [email protected] and subject report
himalaya --account <name> --json message read --mailbox inbox <message-id>
himalaya --account <name> --json attachment list --mailbox inbox <message-id>
himalaya --account <name> attachment download --mailbox inbox --dir <directory> <message-id> <attachment-id>

ID 的作用范围仅限其所属邮箱。切换邮箱或执行移动／删除操作后，请重新列出邮件。如果一条 message read --json 结果已经包含所需字段，就不要重复获取同一封邮件。

写入操作

发送、回复、转发、移动或删除之前，请向用户展示最终收件人、主题和正文，并在执行前立即取得确认。

写入前检查后端。 message compose|reply|forward --send 仅通过 SMTP 或 JMAP 发送，因此使用 Microsoft Graph 后端的账户无法通过该命令发送。先从 account list 中读取账户的后端；对于 Graph 账户，请使用原始 MIME 通过 himalaya msgraph message send 发送，并在撰写前阅读 references/outlook.md。

himalaya --account <name> message compose \
  --from [email protected] \
  --to [email protected] \
  --subject "Subject" \
  --body "Body" \
  --send

himalaya --account <name> message reply --mailbox inbox \
  --body "Reply body" --send <message-id>

himalaya --account <name> message forward --mailbox inbox \
  --to [email protected] --body "Forward note" --send <message-id>

对于附件和原始 RFC 5322 邮件，请阅读 references/message-composition.md。

如果发送出错且结果不明确，绝不要自动重试。SMTP 投递可能已成功，但保存副本到“已发送”邮箱时失败；重试前请先确认是否已投递。

整理邮件

himalaya --account <name> message move --from inbox --to archive <message-id>
himalaya --account <name> message copy --from inbox --to important <message-id>
himalaya --account <name> flag add --mailbox inbox --flag seen <message-id>
himalaya --account <name> flag remove --mailbox inbox --flag seen <message-id>
himalaya --account <name> message delete --mailbox inbox <message-id>

message delete 会先将邮件移至废纸篓，但会永久删除已在废纸篓中的邮件。请说明这一后果并取得明确确认。

网络与故障排查

Himalaya 2 支持 SOCKS5 和 HTTP CONNECT，且仅使用每次调用时的进程环境来决定路由。操作系统代理设置只是代理发现来源，而非路由：如果 macOS 或 Windows 设置中配置了代理，但进程环境中没有配置，则不会使用该代理。因此，读取设置后不作修改就运行命令，实际测试的是直连路由，却看起来像是在测试代理。若要使用发现的代理设置，请在该次调用的环境中显式传入，并严格保留报告中的协议——绝不要根据端口号推断协议。

Himalaya 没有代理配置字段或 CLI 标志：路由仅取决于每次调用时的环境，且此构建只读取两个变量——先读取 all_proxy，再读取 https_proxy。完全不会读取 http_proxy，因此，如果代理只通过该变量提供，系统会静默忽略它并直接连接；请在该次调用中将其值传给 https_proxy。该环境是隔离单条命令路由的唯一手段。若要让单条命令强制使用直连路由，只需在该次调用中清除这两个变量，不要更改用户的全局代理。在 macOS 上，使用 env -u all_proxy -u https_proxy <himalaya> --account <name> ...；在 PowerShell 中，env 不存在，因此请将更改限定在当前进程中：

# A child process, so the user's proxy stays intact in this session.
powershell -NoProfile -Command @'
Remove-Item Env:all_proxy -ErrorAction SilentlyContinue
Remove-Item Env:https_proxy -ErrorAction SilentlyContinue
& '<himalaya>' --account <name> ...
'@

切勿在当前工作会话中直接赋值 $env: 值：这些值会持续生效，导致后续每条命令都在不知情的情况下绕过用户的代理。请根据 Himalaya 自身的 dial <host>:<port> ... (source: direct|all_proxy|https_proxy) 调试行确认实际使用的路由，不要凭猜测判断。

在以下任一情况适用时，连接或诊断前请先阅读 references/proxy.md：

• 服务提供商可能要求用户在当前网络中使用代理；
• 存在代理变量或操作系统代理；
• 错误提到代理、超时、DNS/连接、TLS、服务不可达或 SOCKS 握手未完成；
• IMAP 正常，但 SMTP 失败，或反之；
• 在直连路由与代理路由之间切换会改变结果。

该指南说明了 Gmail、QQ Mail、iCloud Mail、Outlook 及自定义 IMAP/SMTP 的路由默认值、macOS 和 Windows 代理发现方式、单条命令的路由隔离方法，以及针对特定错误的恢复措施。不要要求用户编辑全局代理设置。

请将指南中的错误映射用作恢复指导。观察到的错误符合已知情况时，请根据当前设备上可用的控制项，按指南所述方向推进诊断。不要只向用户重复协议、端口或超时信息就停止，也不要假设每台设备都以相同方式提供代理控制项。

请使用实际 CLI 路径：

himalaya --account <name> --log-level debug account check

在解读结果前，请根据 Himalaya 自身的调试行确认所选路由。不要使用 nc、telnet 或直接套接字探测来证明 Himalaya 的连通性，因为这些检查会绕过其代理选择。非网络故障及分阶段诊断流程请参阅 references/troubleshooting.md。

解读超时前，不要跳过诊断阶段。先检查有界的命令输出，然后只保留并报告安全的路由与阶段信息。