Gws Gmail Triage

核心用法

gws-gmail-triage 是 GWS（Google Workspace CLI）工具套件中的 Gmail 只读查询指令，专注于快速提取未读邮件的核心元数据。执行 gws gmail +triage 后，工具通过 Gmail API 拉取当前用户授权范围内的未读邮件，默认以表格形式输出发件人、主题、日期三要素，支持通过 --max 限制返回数量（默认 20 封），通过 --query 传入 Gmail 搜索语法实现精准筛选（如 from:boss），并可附加 --labels 显示邮件标签。

输出格式默认为人类可读的表格，亦可通过 --format json 配合 jq 等工具进行结构化处理，方便集成至自动化脚本或通知系统。

显著优点

• 零侵入只读设计：明确声明「Read-only — never modifies your mailbox」，从根本上杜绝误删、误标记风险
• 轻量高效：仅抓取邮件头信息（sender/subject/date），不下载正文与附件，API 调用开销极低
• 灵活过滤：完整支持 Gmail 原生搜索语法，可快速定位高优先级邮件
• 生态整合：作为 GWS 子命令，与 gws-gmail 的发送、管理指令形成闭环工作流

潜在局限

• 功能边界严格：仅提供摘要浏览，无法阅读正文、下载附件或执行归档/删除等操作，重度用户需频繁切换至其他子命令
• 依赖 OAuth 授权：需预先完成 gws-shared 中定义的全局认证流程，离线或令牌失效场景下无法使用
• 输出可控性有限：JSON 格式化依赖全局 --format 标志，缺乏针对 triage 场景的字段裁剪选项

适合人群

• 高频收件箱管理者：需要每日快速扫览未读摘要，判断处理优先级的职场人士
• 自动化集成开发者：将邮件摘要输出至 Slack/企业微信/邮件日报系统的 DevOps 工程师
• 隐私敏感用户：倾向使用本地 CLI 工具而非完整 Gmail Web 界面，减少浏览器 Cookie 暴露面

常规风险

• 令牌泄露风险：OAuth token 存储于本地配置文件，共享设备或代码仓库误提交可能导致邮箱访问权限外流（参见 gws-shared 安全规则）
• 搜索查询注入：虽为只读，但 --query 直接透传至 Gmail API，异常构造的查询可能触发 API 速率限制或返回超大数据集
• 第三方工具链依赖：gws 二进制版本迭代（当前 0.22.2）可能引入 Breaking Change，需关注 Release Note

核心用法

gws-gmail-triage 是一款纯 Markdown 文档型 Agent Skill，专为需要快速掌握 Gmail 收件箱动态的用户设计。该技能通过调用本地安装的 gws（Google Workspace CLI）命令行工具，执行只读的未读邮件查询操作。基础用法极为简洁：运行 gws gmail +triage 即可获取默认 20 封未读邮件的摘要列表，包含发件人、主题和接收日期三要素。

技能支持灵活的参数定制：--max 可调整返回邮件数量（默认 20，适合批量处理），--query 支持标准 Gmail 搜索语法（如 from:boss 筛选特定发件人），--labels 可附加标签信息辅助分类。输出默认为易读的表格格式，同时支持 JSON 格式便于与 jq 等工具链集成，满足自动化处理需求。

显著优点

极致安全性：本技能为 T-MD（纯 Markdown）分类，无任何独立可执行代码，全部功能通过调用本地可信的 gws 工具实现。六维安全检测全部通过，无危险函数、无敏感信息泄露、无外部网络调用、无依赖风险，安全评级达 S+。

权限最小化：严格遵循只读原则，绝不修改用户邮箱；仅访问功能必需的邮件元数据（发件人、主题、日期），不涉及邮件正文，符合 GDPR 数据最小化原则。

生态可信：底层依赖 gws 属于 Google Workspace 官方或社区维护的工具链，具备完善的 OAuth 授权机制和安全审计能力。

使用零门槛：无需编写代码，命令行交互直观；参数设计符合 CLI 用户习惯，学习成本极低。

潜在缺点与局限性

环境依赖性强：必须预先安装并配置 gws 工具及 Gmail OAuth 授权，对未接触 Google Workspace CLI 的用户存在初始配置门槛。

功能边界清晰：仅支持未读邮件摘要查询，不支持邮件发送、标记已读、归档等操作，也不提供邮件正文预览，重度邮件管理用户需配合其他工具使用。

隐私场景待优化：当前输出直接展示完整邮箱地址，屏幕分享或日志记录场景存在潜在泄露风险（报告已建议未来版本增加脱敏选项）。

无原生 GUI：纯命令行交互，对偏好图形界面的用户不够友好。

适合的目标群体

• 开发者与运维工程师：习惯 CLI 工作流，需要快速查看邮件通知而不切换上下文
• 自动化脚本编写者：通过 JSON 输出与现有工具链集成，实现邮件监控自动化
• 隐私敏感用户：追求最小权限、本地执行的邮件查询方案
• Google Workspace 重度用户：已配置 gws 环境，希望扩展命令行邮件管理能力
• 安全意识高的企业用户：需要经过安全审计、来源可信的邮件处理工具

使用风险与注意事项

依赖项风险：技能本身零依赖，但实际运行依赖本地 gws 工具。需确保从官方渠道安装 gws，避免供应链攻击；建议定期更新以修复潜在漏洞。

授权令牌管理：gws 需存储 Gmail OAuth 令牌，用户应确保令牌存储安全，避免在共享环境暴露凭据文件。

输出内容管控：查询结果可能包含敏感发件人信息，建议在公共场合或日志共享时谨慎使用，或等待未来版本的脱敏功能。

性能边界：大规模邮箱（数千未读邮件）查询时，建议通过 --max 限制返回数量，避免处理延迟。