Surface Cli — Surface 命令行界面（CLI）

Surface CLI Surface 是一个本地优先的邮件 CLI，用于 Gmail 和 Outlook。它尤其适用于只能通过 Web UI 工作的 Outlook 学校或工作账户，不需要 IMAP 或管理员更改。Surface 将机器可读的 JSON 输出到 stdout，并在 ~/.surface-cli 中存储本地状态。

使用此技能 当用户想要从 Gmail 或 Outlook 读取或处理电子邮件时，用户需要一个提供商中立的 CLI 来进行搜索、未读邮件获取、读取、附件或操作，需要稳定的 thread_ref / message_ref 值用于后续命令或线程监视。

前提条件 Surface CLI 已安装（surface --help 应该可以工作） 至少一个配置好的账户 目标账户的有效身份验证 检查设置：surface account list surface auth status

账户设置 添加账户：surface account add personal_2 --provider gmail --email you@example.com surface account add uni --provider outlook --email you@example.com 为了获得可靠的 summary.needs_action，Surface 应该知道账户所有者是谁。Gmail 身份验证可以自动验证邮箱电子邮件；Outlook 可能需要显式的人类标识符：surface account identity set uni --email you@example.com --name "Your Name" --name-alias "FirstName" surface account identity show uni 登录：surface auth login personal_2 surface auth login uni

本地策略位于：~/.surface-cli/config.toml 重要的本地控制：summarizer_backend summarizer_model writes_enabled send_mode test_recipients test_account_allowlist 摘要是可选的，并由用户的本地配置控制。除非用户明确要求，否则不要更改 summarizer_backend、summarizer_model 或相关环境变量。如果启用了外部摘要后端，电子邮件线程内容可能会被发送到配置的模型提供者；在启用或更改摘要之前，请确认用户接受该隐私权衡。

常见操作 列出账户：surface account list surface auth status surface auth status personal_2 获取未读线程：surface mail fetch-unread --account uni --limit 10 surface mail fetch-unread --account personal_2 --limit 20 surface mail fetch-unread --account uni --session sess_01... --limit 10 搜索邮件：surface mail search --account uni --text "invoice" --limit 10 surface mail search --account uni --from registrar@school.edu --subject "waitlist" --limit 10 surface mail search --account uni --session sess_01... --from registrar@school.edu --limit 10 surface mail search --account personal_2 --mailbox inbox --label unread --text "sale" --limit 10 surface mail search --account personal_2 --text "has:attachment newer_than:30d" --limit 5

监视线程和主题 Surface 是轮询原语，而不是调度程序或传输。 如果用户要求监视邮件，请使用周围的自动化系统重新运行 Surface 命令并将 Surface 更新发送到用户请求的目标。 对于特定的线程监视，保留账户、thread_ref 和最新已知消息/时间戳。 每次检查时，重新运行 surface mail thread get --refresh 并仅在最新消息状态更改时通知。 对于主题监视，使用搜索建立基线，然后使用周期性获取未读检查捕获新到达的收件箱和有针对性的搜索检查，当主题有明确的 --from、--subject、--mailbox、--label 或 --text 过滤器时。 不要假设传输目标。 通过当前代理会话或用户明确要求的目标返回更新。 合理的起始节奏是： 对于一个活动线程，5-10 分钟 对于一个狭窄的主题监视，30-60 分钟 对于收件箱摘要，2-4 小时 避免除非用户明确要求，否则避免每 5 分钟轮询。 对于 Outlook 重度轮询，请保持并发性适中，并且如果多个实时检查将在短时间内运行，请更喜欢每个并行工作人员一个热会话。

热会话 surface session start --account uni surface session list surface session stop sess_01...

并行读取指南 只读命令可以并行运行。 已通过以下测试： 在同一个账户上运行两个 Gmail 搜索 在同一个账户上运行两个冷 Outlook 搜索 同时运行 Gmail 和 Outlook 搜索 同时运行两个独立的 Outlook 热会话搜索 对于 Outlook，请保持并发性适中，因为每个冷命令或热会话都使用浏览器资源。 如果计划多个并发 Outlook 操作，请更喜欢每个并行工作人员一个热会话。 同时使用相同的 --session 可以在测试用例中正常工作，但可能会由于争用而变慢。

读取一个线程 surface mail thread get thr_01... surface mail thread get thr_01... --refresh surface mail thread get thr_01... --refresh --session sess_01...

读取一条消息 surface mail read msg_01... surface mail read msg_01... --refresh surface mail read msg_01... --refresh --session sess_01... surface mail read msg_01... --mark-read

附件 surface attachment list msg_01... surface attachment download msg_01... att_0