gws是什么
gws (Google Workspace CLI) 是 Google Workspace 团队开源的命令行工具，用 Rust 编写，通过 npm 分发。最大亮点是运行时动态构建命令，不依赖静态命令列表，实时读取 Google Discovery Service 自动支持所有 Workspace API（Drive、Gmail、Calendar、Sheets 等），Google 新增端点无需更新即可使用。gws 专为 AI Agent 时代设计，内置 MCP 服务器，支持 JSON 结构化输出、自动分页、Model Armor 安全扫描，以及类似 Git 的 Pull/Push 工作流，让 AI 能直接编辑本地文件后同步回 Workspace。
gws的主要功能
- 动态 API 发现：运行时从 Google Discovery Service 实时构建命令树，自动支持所有 Workspace API 及新增端点，无需等待工具更新。
- 统一命令接口：单一 CLI 覆盖 Drive、Gmail、Calendar、Sheets、Docs、Chat 等全部 Google Workspace 服务，告别多工具切换。
- 结构化 JSON 输出：所有响应（含错误）均为 JSON 格式，便于脚本解析和下游自动化处理。
- MCP 服务器支持：内置 Model Context Protocol 服务器，Claude、Gemini 等 AI Agent 可直接调用 Workspace API 作为工具。
- 智能认证管理：支持交互式 OAuth、服务账号、CI/CD 无头环境等多种认证方式，自动处理令牌刷新。
- 自动分页处理：
--page-all标志自动处理 API 分页，流式输出 NDJSON，轻松提取大量数据。 - Model Armor 集成：扫描 API 响应中的提示注入等安全风险，保护 AI Agent 免受恶意内容攻击。
- Agent Skills 库：内置 100+ 个预置 Skills，覆盖常见工作流，可直接与 OpenClaw 等 Agent 框架集成。
- Pull/Push 工作流：类似 Git 的操作，将 Google 文档拉取为本地结构化文件（TSV/JSON），AI 编辑后推送回 Workspace。
- Gemini CLI 扩展：专用扩展让 Gemini CLI Agent 原生访问所有 gws 命令和 Skills 能力。
gws的技术原理
- Rust 核心架构：底层采用 Rust 编写，保证高性能和内存安全，通过 npm 分发预构建二进制文件，支持跨平台运行。
- Discovery Service 动态解析：启动时实时拉取 Google Discovery Documents（JSON 格式的 API 规范），动态构建命令树和参数结构，而非硬编码静态命令。
- 命令树运行时生成：基于 Discovery Documents 中的资源和方法定义，自动生成对应的 CLI 子命令、参数映射和请求体结构。
- REST API 封装层：所有操作最终转换为对 Google REST API 的标准 HTTP 调用，统一处理 URL 构造、请求序列化和响应解析。
- OAuth 2.0 认证管道：内置完整的 OAuth 流程支持，包括本地回调服务器、令牌缓存、自动刷新，以及服务账号的 JWT 签名认证。
- JSON Schema 验证：利用 Discovery Documents 中的参数定义，在本地完成请求参数的类型检查和格式验证。
- 流式分页引擎：
--page-all模式下，自动识别响应中的分页令牌（pageToken/nextPageToken），递归获取并流式输出 NDJSON 格式结果。 - MCP 协议适配器：实现 Model Context Protocol 标准接口，将 gws 命令暴露为 MCP Tools，供 AI 客户端发现和调用。
- Model Armor 安全网关：调用 Google Cloud Model Armor API，对 API 响应内容进行实时安全扫描，拦截提示注入等攻击向量。
- Pull/Push 数据转换层：内置格式转换引擎，将 Google 文档（Sheets/Docs）与本地结构化文件（TSV/JSON/Markdown）双向转换，支持差异检测和增量同步。
gws的项目地址
- Github仓库：https://github.com/googleworkspace/cli
gws的应用场景
- AI Agent 开发：通过 MCP 协议让 LLM 直接操控 Google Workspace，实现智能文档处理、邮件自动回复、日程智能调度等 Agent 能力。
- 批量数据迁移：利用
--page-all自动分页，批量导出 Drive 文件列表、Gmail 邮件、Sheets 数据等，支持企业数据备份和迁移。 - CI/CD 自动化：在无头服务器环境运行，自动化文档生成、报表推送、权限管理等 DevOps 工作流，支持服务账号认证。
- 内容管理自动化：Pull/Push 工作流实现文档版本控制，将 Google Docs 转为本地 Markdown 供 AI 编辑后同步回云端。
- 企业级数据管道：构建 Sheets ↔ 数据仓库的实时同步管道，自动化报表生成和分发，替代传统 ETL 工具的部分能力。
- 安全合规审计：集成 Model Armor 扫描 API 响应，在企业级 Agent 应用中防止提示注入和数据泄露风险。