Google Workspace CLI（gws）：为 AI Agent 设计的命令行
介绍 Google Workspace CLI 的 JSON 输入、结构化输出与 Discovery 命令生成，说明非官方支持状态、认证及 Agent 权限边界。
直接回答：gws 是 googleworkspace 组织公开的 Workspace CLI，服务人类、脚本和 AI Agent；仓库注明不是获得官方支持的 Google 产品。它基于 Discovery 文档构造命令，不保证与所有 API 变化即时同步。
人类 DX 与 Agent DX 的冲突
传统 CLI 为人类优化：详尽的 --help、容错输入、拼写纠错建议、几十个语义化 flag。对人友好，对 Agent 昂贵——Agent 要在几十个 flag 里推理选哪个，每次都烧 Token 还容易选错。
Agent 要的恰恰相反：
- 可预测：从已知 schema 构造合法请求，不要模糊地带
- 结构化：输出确定格式，程序可直接消费
- 低 Token：最小化描述与往返
三个关键设计
1. JSON 负载代替定制 flag
创建表格的人本 CLI 写法：
some-cli sheets create --title "Q1 预算" --locale "zh_CN" --frozen-rows 1
gws 写法——请求体直接映射 API 的 JSON：
gws sheets spreadsheets create --json '{"properties": {"title": "Q1 预算", "locale": "zh_CN"}, "sheets": [{"properties": {"gridProperties": {"frozenRowCount": 1}}}]}'
Agent 只需懂 API 的 JSON schema（已有文档和类型定义），不必学习一套新的 flag 方言。
2. 结构化输出：返回的就是 API 原生 JSON，Agent 直接解析字段，不用从人类友好文本里抠数据。
3. 动态命令生成：依据 Discovery 文档构造命令；文档版本、缓存和 CLI 实现仍可能带来滞后，需检查实际 schema。
上手
# 安装后授权
gws auth login
# 读邮件、建文档、管日历——全部统一 JSON 风格
gws gmail users messages list --params '{"userId": "me", "maxResults": 5}'
授权前先配置 OAuth 项目与凭证，检查所请求 scopes。只读任务不要授予发信、删除或修改权限；示例中的创建表格会修改账号数据，只有明确需要时才执行。令牌与输出可能包含隐私，禁止写入公开日志。
更大的启示
gws 是个样本："Agent 优先"正在重塑工具设计——CLI、API 文档、SDK 都开始为机器消费者优化。给自家产品做开发者工具时，这套原则同样适用：schema 化输入、结构化输出、文档即代码。
常见问题（FAQ）
Q：gws 适合人类日常使用吗？
A：可以，项目同时面向人类与 Agent；JSON、帮助和示例可结合使用。
Q：和直接调 Google API 有什么区别？
A：gws 封装了认证、分页、错误重试等杂事，动态读取 Discovery 文档，但仍应验证版本和缓存。对 Agent 而言省掉的是"写 HTTP 客户端代码"这层，直接给可执行命令。
Q：这套"Agent DX"原则能用在自家 CLI 上吗？
A：完全可以，三条核心：接受 JSON 负载直通 API schema、输出严格结构化、提供机器可读的能力清单（类似 --json-schema 自省）。仍需验证兼容性、权限、错误处理和实际效率。
参考资料
资料核对日期：2026 年 9 月 29 日。本文基于公开文档整理，代码片段和评估方案未作独立运行或性能验证；厂商测试结果已注明来源。
