gws是面向人类与AI Agent的Google Workspace统一命令行工具，动态生成全量Workspace API命令，内置40+AI Agent技能，无需样板代码即可操作Drive、Gmail、Calendar等资源，本文档涵盖项目定位、安装方式、使用指南与实现特点。
gws（Google Workspace CLI）是面向人类与AI Agent的非Google官方Google Workspace统一命令行工具，动态基于Google Discovery Service生成全量Workspace API命令，内置40+AI Agent技能，无需样板代码即可操作Drive、Gmail、Calendar等所有Workspace资源，大幅降低Workspace自动化与AI集成的门槛。
gws（全称Google Workspace CLI）是面向人类用户与AI Agent的Google Workspace统一命令行工具，属于非Google官方支持的开源项目。其核心定位是作为Google Workspace全量API的统一操作入口，覆盖Drive、Gmail、Calendar、Sheets、Docs、Chat、Admin等所有Workspace服务。工具运行时动态读取Google官方Discovery Service生成全部命令表面，无需静态绑定API定义，当Google Workspace新增或更新API端点时，gws可自动适配生效。同时内置40+预置AI Agent技能，为AI集成提供开箱即用的Workspace操作能力，所有API响应均支持结构化JSON输出，适配人类与AI的读取需求。
gws主要解决两类核心痛点：一是人工操作Google Workspace API的繁琐问题，传统方式需要手动编写curl请求、处理OAuth2认证流程、手动实现分页逻辑、解析API响应，每个Workspace服务都需要单独维护调用代码，样板代码占比极高；二是AI Agent集成Workspace的门槛问题，此前没有统一的Workspace命令行工具，AI需要为每个API单独编写调用逻辑，且非结构化的文本输出不便于AI解析处理。gws通过动态命令生成、统一认证管理、结构化输出与预置AI技能，彻底消除了上述样板代码与集成成本。
gws适用于以下核心场景：1. 本地或CI/CD环境批量管理Google Workspace资源，包括Drive文件的上传下载与权限管理、Gmail邮件的批量发送与检索、日历事件的创建与查询、Sheets/Docs的读写操作等；2. 为AI Agent提供Workspace操作能力，通过内置的40+预置技能，让AI可以直接执行邮件处理、日程协调、文档协作、群聊消息发送等自动化工作流，无需额外开发工具；3. 快速调试与验证Google Workspace API调用，通过--dry-run参数预览请求、gws schema命令查看API Schema，无需编写临时代码即可验证API行为。
仓库中明确提供了5种安装方式：1. 预编译二进制（推荐）：从GitHub Releases页面下载对应操作系统与架构的预编译包，解压后将gws可执行文件放入系统PATH即可使用；2. npm全局安装：执行npm install -g @googleworkspace/cli，npm脚本会自动下载对应系统的GitHub Release二进制；3. Rust源码构建：已安装Rust环境的用户可通过cargo install --git https://github.com/googleworkspace/cli --locked从源码编译安装；4. Nix运行：Nix用户可通过nix run github:googleworkspace/cli直接运行无需安装；5. Homebrew安装：macOS与Linux用户可通过brew install googleworkspace-cli安装。所有安装方式的前提是Node.js 18+（仅npm安装需要）或Rust环境（仅源码构建需要）。
gws的使用流程分为认证与命令调用两步：1. 认证初始化：首次使用执行gws auth setup，可交互式完成Google Cloud项目配置与OAuth凭证初始化；已有gcloud认证环境的用户可快速完成配置，无gcloud的用户也可通过命令引导创建GCP项目与凭证；配置完成后执行gws auth login完成OAuth用户登录。2. API调用：gws的命令表面完全动态生成，直接通过<服务名> <资源名> <方法名>的结构调用对应API，例如gws drive files list --params '{"pageSize": 5}'可列出Drive根目录前5个文件，gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'可创建新的电子表格。工具还支持--dry-run预览请求、--page-all流式输出全部分页结果、gws schema <方法名>查看指定API的请求/响应Schema。
gws的核心实现特点包括：1. 动态发现驱动架构：基于Rust双crate设计，核心库google-workspace负责异步拉取Google Discovery Service文档、解析API定义、构建带自动重试的HTTP客户端，CLI层google-workspace-cli基于核心库实现命令解析、认证管理、输出格式化与AI技能生成，Google Workspace新增API时无需更新gws即可自动支持；2. 多环境认证支持：支持OAuth2用户凭证、服务账号凭证、预获取Access Token、gcloud凭证等多种认证方式，适配本地开发、CI/CD、服务器等不同场景；3. 输入安全机制：针对AI/LLM调用场景设计了路径安全、资源名校验、URL编码等输入校验逻辑，防范恶意输入风险；4. 项目当前处于活跃开发阶段，尚未发布v1.0版本，可能存在破坏性变更。仓库中未明确给出具体的AI Agent技能调用示例与各Workspace服务的权限配置要求。
不是，仓库中明确标注该项目为非Google官方支持的开源项目，由社区开发者维护。
gws基于Google Discovery Service动态生成命令，覆盖Drive、Gmail、Calendar、Sheets、Docs、Chat、Admin等所有Google Workspace API，Google Workspace新增API时gws可自动适配。
gws内置40+预置AI Agent技能，执行gws auth setup完成认证配置后，AI即可通过gws的命令行接口调用Workspace API，所有响应均为结构化JSON格式，便于AI解析处理。
仓库中明确支持多种认证方式：通过gcloud CLI凭证、OAuth2用户凭证、服务账号凭证、预获取的Access Token、环境变量配置的OAuth客户端ID与密钥等，适配本地开发、CI/CD等不同场景。
gws默认输出结构化JSON，支持通过--page-all参数流式输出NDJSON格式的分页结果，也支持--dry-run参数预览请求内容，适配人类阅读与AI解析的不同需求。