适用场景

当用户需要检查或操作跨平台 IMAP 邮箱（包括 Gmail、Fastmail、ProtonMail Bridge、兼容 Exchange 的网关，或自托管邮件服务器）时，请使用此技能。

在以下场景中启用该技能：收件箱搜索、未读邮件分类、邮件头与正文获取、附件处理、文件夹映射，或需保证准确性的增量式邮箱同步（此时正确性优先于快速即席抓取）。

架构

状态数据存储于 ~/imap/ 目录下。若该目录不存在，请运行 setup.md。默认结构与文件模板详见 memory-template.md。

~/imap/
├── memory.md       # 激活默认配置、变更策略、首选报告风格
├── accounts.md     # 邮箱专属端点、认证说明及服务器能力
├── folder-map.md   # 标准化文件夹映射与各服务商特有行为
├── sync-state.md   # UIDVALIDITY、最后 UID、MODSEQ 及同步检查点
└── playbooks.md    # 已保存的邮箱工作流与可复用的搜索配方

速查表

当当前邮箱任务所需细节超出核心规则覆盖范围时，请参考以下文件：

核心规则

1. 在做出任何假设前，先探测邮箱能力

• 在构建命令或解析结果前，须明确识别服务器能力、命名空间布局、路径分隔符行为，以及特殊用途文件夹（Special-Use Folders）支持情况。
• 检查服务器是否支持 UIDPLUS、CONDSTORE、QRESYNC、MOVE 或替代 XLIST 的扩展功能。
• 文件夹命名、归档机制与标志位行为因服务商而异，切勿将 Gmail 的语义硬编码至所有邮箱环境。

2. 默认执行只读安全操作，除非用户明确要求变更

• 初始操作应采用安全检查模式，例如能力探测、文件夹列表、EXAMINE 命令、邮件头获取，以及按需提取特定正文内容。
• 将删除、移动、复制、清空（expunge）及批量标志位更新视为变更型操作，必须获得用户显式批准，或基于此前已确认的长期策略执行。
• 若用户仅要求检查或汇总邮件内容，则不得静默标记消息为“已读”，亦不得修改邮箱状态。

3. 使用 UID 与持久化同步标记，而非易变的序列号

• 序列号随新邮件到达或旧邮件移除而动态变化，因此不适合作为持久化追踪标识。
• 为保障可重复执行的工作流，请在 ~/imap/sync-state.md 中持久化存储 UIDVALIDITY、最后处理的 UID，以及（如可用）HIGHESTMODSEQ 或其他相关同步检查点。
• 一旦 UIDVALIDITY 发生变更，应视先前所有游标（cursor）为失效，并执行全量重扫，而非依赖陈旧状态。

4. 仅获取回答问题所必需的最少数据

• 优先获取文件夹列表、统计数量、标志位、信封（envelope）或邮件头信息，再决定是否下载完整正文或附件。
• 仅当用户实际需要更细粒度内容时，才升级至正文段落（body sections）、MIME 结构解析或附件下载。
• 精简获取范围可降低延迟、节省带宽，并避免将敏感内容不必要地引入下游处理流程。

5. 使用明确的服务器端搜索过滤器，并如实说明其语义

• 优先选用精确的 IMAP 服务端搜索约束条件（如日期范围、发件人、主题片段、标志位、大小限制、UID 区间），而非对整个邮箱进行宽泛扫描。
• 需明确说明该服务器搜索是否仅限邮件头、面向全文本、对字符集敏感，或存在服务商特有匹配逻辑。
• 当搜索语义存在歧义时，应指出该限制，并建议执行更窄范围的搜索，或提供可验证的补充查询。

6. 将 MIME 结构与附件视为结构化数据，而非不透明二进制块

• 在推断文本位置或识别附件前，务必先读取 BODYSTRUCTURE 或等效元数据。
• 区分内联内容（inline parts）与可下载附件；安全解码文件名；保留字符集（charset）与传输编码（transfer-encoding）信息。
• 除非确有需要，否则避免下载大体积附件；在分类处理（triage）阶段，应优先报告部件标识符、尺寸及媒体类型（media type）。

7. 确保凭据不出现在技能内存中，并严格限定网络访问范围

• 仅在 ~/imap/ 下存储非敏感连接说明、服务器能力与工作流偏好设置。
• 切勿要求用户将账户密码粘贴至内存文件中；应复用现有本地认证流程、应用专用密码（app passwords）、OAuth 支持的桥接器（OAuth-backed bridges），或其他环境原生支持的安全运行时机制。
• 网络活动应严格限制于用户当前配置的 IMAP 端点，仅服务于本次邮箱任务所需。

IMAP 常见陷阱

• 将消息序列号（sequence numbers）误认为稳定标识符 → 邮箱状态变动后，后续 fetch 操作将命中错误消息。
• 在只读审查过程中静默标记邮件为“已读” → 用户未主动请求，却丢失了未读状态。
• 为回答窄范围问题而下载整个文件夹 → 导致无谓的延迟、带宽消耗与隐私风险。
• 忽略 UIDVALIDITY 重置 → 增量同步将静默跳过或重复处理消息。
• 假定所有服务器均支持 MOVE、IDLE 或 Gmail 风格的特殊文件夹 → 同一命令在不同服务商上可能失败或行为不一致。
• 未预先检查 MIME 结构即解析附件 → 导致内联部件、文件名或字符集被误判。

外部端点

不向其他任何外部系统发送数据。

安全与隐私

保留在本地的数据：

• 存储于 ~/imap/ 下的激活默认配置、服务商特有问题说明、同步检查点及可复用工作流
• 用户明确要求在后续会话中记住的邮箱备注信息

离开您设备的数据：

• 仅限与已配置邮箱服务器通信所需的 IMAP 请求
• 为完成当前任务而从该邮箱获取的消息元数据、正文或附件

本技能不会：

• 将邮箱密码或 OAuth token 存储于 ~/imap/
• 默认允许对邮箱执行变更操作
• 将邮箱内容发送给未经声明的第三方
• 将序列号视为持久化同步状态

信任模型

使用本技能时，所有数据交换均发生于用户自行配置的邮件服务商或 IMAP 桥接器之间。请仅在您已信任对应邮箱系统及本地凭证流程的前提下启用本技能。

关联技能

若用户确认安装，则执行：clawhub install

• api — 当邮箱任务实质是 API 集成或带身份认证的服务封装问题时使用。
• http — 当任务聚焦于请求构造、请求头调试或 IMAP 会话之外的协议分析时使用。
• json — 当邮箱返回结果需进行结构化转换、标准化，或输出为下游机器可读格式时使用。
• code — 当用户需要端到端构建、验证并交付完整实现、解析器或同步工作器时使用。
• bash — 当任务以 Shell 为首选工具链，用于本地自动化或构建可重复调用的命令封装器时使用。

反馈

• 若本技能有用：clawhub star imap
• 保持更新：clawhub sync