核心用法
Surface CLI 是一款本地优先的邮件命令行工具，为 Gmail、Outlook 及通用 IMAP/SMTP 提供商提供统一的 JSON-first 接口。其核心能力包括：
- 多账户管理：支持 Gmail OAuth、Outlook 网页认证及通用 IMAP/SMTP 密码认证
- 结构化操作：
fetch-unread获取未读邮件、search多条件检索、thread get读取完整对话、sent查看发件记录 - 消息处理：
read读取内容、mark-read/unread标记状态、archive归档、RSVP 日历回复 - 附件管理：
attachment list/download独立处理附件下载 - 撰写发送：
send/reply/reply-all/forward支持--draft草稿模式和--attach附件
关键设计亮点：使用稳定的 thread_ref/message_ref 标识符实现跨命令引用，支持 Outlook 暖会话（warm session）优化性能，纯 JSON 输出便于自动化集成。
显著优点
- Outlook 工作/学校账户支持：解决传统 IMAP 被封禁的企业/教育账户访问难题
- 统一接口抽象：无论底层是 Gmail API、Microsoft Graph 还是原始 IMAP，命令与输出格式一致
- 本地状态管理：
~/.surface-cli存储认证状态、会话和配置，支持离线缓存与增量刷新 - 安全认证选项：支持
--password-env/--password-file/--password-command避免密码泄露 - 灵活的轮询原语：为邮件监控场景提供清晰的刷新、对比、通知工作流指导
潜在局限
- Outlook 性能约束：冷启动需浏览器资源，高频查询需暖会话管理
- IMAP 功能缩减：无可靠跨文件夹会话 ID、不支持 RSVP、归档依赖特定邮箱配置
- 隐私权衡：可选的 AI 摘要功能需将邮件内容发送至外部模型提供商
- 写入安全门槛：发送邮件受本地
writes_enabled配置限制，需显式开启 - 无内置调度：仅提供轮询原语，邮件监控需外部 cron 或自动化系统驱动
适合人群
- 需要 CLI 自动化处理邮件的开发者和 DevOps 工程师
- 使用 Outlook 工作/学校账户且无法启用 IMAP 的用户
- 追求本地优先、机器可读工作流的技术用户
- 需要批量邮件处理、附件管理或状态追踪的自动化场景
常规风险
- 凭证安全：IMAP 密码若使用
--password明文传递可能泄露于 shell 历史或进程列表 - OAuth 令牌管理：Gmail/Outlook 令牌存储于本地状态目录，需保障文件系统权限
- 误发送风险：
--draft为默认安全模式，直接发送需确认writes_enabled及测试收件人配置 - 隐私合规：启用摘要功能前需确认用户接受邮件内容外传至第三方 AI 服务