技能介绍

gws 是一个用于所有 Google Workspace 的命令行工具，为人类用户和 AI 代理设计。它提供 Drive、Gmail、Calendar 及所有 Workspace API 的访问能力：零样板代码、结构化 JSON 输出，并内置代理技能。对人类用户来说，不必再手写 curl 调用并翻阅 REST 文档；对 AI 代理来说，所有响应都是结构化 JSON，配合内置技能，LLM 无需自定义工具即可管理 Workspace。

需要注意：这不是 Google 官方支持的正式产品。

适用场景

  • 列出、上传、下载 Google Drive 文件，例如列出最近 10 个文件。
  • 收发邮件：发送、回复、回复全部、转发、未读收件箱分诊、监听新邮件。
  • 日历与会议：创建事件、查看议程、为下一次会议准备议程与关联文档。
  • Sheets 与 Docs：创建电子表格、读写值、追加行、向文档追加文本。
  • 在 Chat 空间里发消息、宣布 Drive 文件。
  • 无头 / CI 环境与服务器到服务器的自动化，以及给 AI 代理补一层 Workspace 操作能力。

核心能力

  • 一套 CLI 覆盖全部 Workspace API：为每个资源提供 --help 帮助、--dry-run 请求预览与自动分页。
  • 代理友好：所有输出——成功、错误、下载元数据——都是结构化 JSON；可查看任意方法的请求/响应模式（gws schema drive.files.list），并以 NDJSON 流式输出分页结果。
  • 内置代理技能：仓库包含 100+ 个代理技能（SKILL.md 文件），每个受支持的 API 对应一个，外加高级工作流帮助器以及 50 个精选的 Gmail、Drive、Docs、Calendar 和 Sheets 配方，可一次性全装或按需挑选；页面介绍中该数量写作「内置 40+ 个代理技能」。
  • 多种认证工作流：覆盖本地桌面、CI、服务器与服务账号场景，凭据以 AES-256-GCM 加密存储，密钥保存在操作系统密钥环中。
  • 手写帮助器命令：以 + 前缀标记，与 Discovery 生成的方法名永不冲突，例如 +send、+reply、+triage、+agenda、+standup-report、+weekly-digest、+meeting-prep、+email-to-task、+file-announce 等。
  • 结构化退出码：脚本可按失败类型分支，无需解析错误输出。
  • Model Armor 响应净化：可集成 Google Cloud Model Armor，在响应到达代理前扫描其中的提示注入。
  • Gemini CLI 扩展：安装后 Gemini CLI 代理可直接访问所有 gws 命令与 Google Workspace 代理技能，并自动继承你已完成的认证。

效果预览

用命令行管理Google Workspace

退出码与失败类型对照：

↔ 左右滑动查看完整表格
代码含义示例原因
0成功命令正常完成
1API 错误Google 返回 4xx/5xx 响应
2认证错误凭据缺失、过期或无效
3验证错误参数错误、未知服务、无效标志
4Discovery 错误无法获取 API 模式文档
5内部错误意外失败

工作方式

两阶段解析架构：先读取 argv[1] 识别服务（例如 drive），获取该服务的 Discovery 文档（缓存 24 小时），再根据文档中的资源和方法构建 clap::Command 树，重新解析剩余参数，最后认证、构建 HTTP 请求并执行。

认证方式按场景选择：

↔ 左右滑动查看完整表格
你的情况推荐方式
已安装并认证了 gcloudgws auth setup（最快）
有 GCP 项目但没有 gcloud手动 OAuth 设置
已有 OAuth 访问令牌GOOGLE_WORKSPACE_CLI_TOKEN
已有凭据文件GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE

凭据来源有优先级：访问令牌 > 凭据文件 > 加密凭据（gws auth login）> 明文凭据（~/.config/gws/credentials.json）；环境变量也可以放在 .env 文件中。

无头 / CI 环境用导出流程：先在带浏览器的机器上完成交互式认证，用 gws auth export --unmasked > credentials.json 导出，再在无头机器上通过 GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE 指向该文件直接使用。服务账号则直接指向密钥文件，无需登录。

分页由 --page-all（自动分页，每页一行 JSON）、--page-limit（最大页数，默认 10）、--page-delay（页间延迟，默认 100 毫秒）控制。

你需要提供

  • Node.js 18+（如果使用 npm 安装），或直接使用从 GitHub Releases 下载的预编译二进制文件。
  • 一个 Google Cloud 项目，用于 OAuth 凭据：可通过 Google Cloud Console 创建，或使用 gcloud CLI，或运行 gws auth setup。
  • 一个拥有 Google Workspace 访问权限的 Google 账号。
  • 手动 OAuth 时需在同意屏幕的「测试用户」里把自己加进去，并把下载的客户端 JSON 保存到 ~/.config/gws/client_secret.json。

你会获得

  • 结构化 JSON 格式的命令输出，配合 jq 可直接取字段，例如 gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'。
  • 实际执行的 Workspace 操作结果：列出的 Drive 文件、创建好的电子表格、发送出去的邮件与 Chat 消息、创建好的日历事件、上传完成的文件等。
  • 可按 / 或 + 前缀区分的完整命令面：Discovery 生成的方法加手写帮助器命令。

使用示例

快速开始：

gws auth setup     # 引导你完成 Google Cloud 项目配置
gws auth login     # 后续 OAuth 登录
gws drive files list --params '{"pageSize": 5}'

常用命令：

# 列出最近 10 个文件
gws drive files list --params '{"pageSize": 10}'

# 创建电子表格
gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'

# 发送 Chat 消息
gws chat spaces messages create \
  --params '{"parent": "spaces/xyz"}' \
  --json '{"text": "Deploy complete."}' \
  --dry-run

# 查看任意方法的请求/响应模式
gws schema drive.files.list

# 流式输出分页结果（NDJSON 格式）
gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'

帮助器命令与多部分上传：

# 发送邮件
gws gmail +send --to alice@example.com --subject "Hello" --body "Hi there"

# 回复消息
gws gmail +reply --message-id MESSAGE_ID --body "Thanks!"

# 追加行到电子表格
gws sheets +append --spreadsheet SPREADSHEET_ID --values "Alice,95"

# 显示今日日历议程
gws calendar +agenda

# 上传文件到 Drive
gws drive +upload ./report.pdf --name "Q1 Report"

# 早晨站立会议摘要
gws workflow +standup-report

# 显示指定时区的今日议程
gws calendar +agenda --today --timezone America/New_York

# 多部分上传
gws drive files create --json '{"name": "report.pdf"}' --upload ./report.pdf

Google Sheets 的范围使用 !，bash 会将其解释为历史扩展，因此必须用单引号包裹值：

# 读取 "Sheet1" 中的 A1:C10 单元格
gws sheets spreadsheets values get \
  --params '{"spreadsheetId": "SPREADSHEET_ID", "range": "Sheet1!A1:C10"}'

# 追加行
gws sheets spreadsheets values append \
  --params '{"spreadsheetId": "ID", "range": "Sheet1!A1", "valueInputOption": "USER_ENTERED"}' \
  --json '{"values": [["Name", "Score"], ["Alice", 95]]}'

认证与无头环境：

# 只选择你需要的作用域（未验证应用仅支持约 25 个作用域）
gws auth login --scopes drive,gmail,calendar

# 导出凭据到无头机器使用
gws auth export --unmasked > credentials.json
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json
gws drive files list   # 直接使用

Model Armor 响应净化：

gws gmail users messages get --params '...' \
  --sanitize "projects/P/locations/L/templates/T"

退出码在脚本中的分支判断：

gws drive files list --params '{"fileId": "bad"}'
echo $?   # 1 —— API 错误

gws unknown-service files list
echo $?   # 3 —— 验证错误（未知服务）