googleworkspace--cli/README.md

<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/googleworkspace/cli) · [上游 README](https://github.com/googleworkspace/cli/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

<h1 align="center">gws</h1>

**一个 CLI，统驭全部 Google Workspace — 为人与 AI 智能体而生。**<br>
Drive、Gmail、Calendar 及全部 Workspace API。零样板代码。结构化 JSON 输出。内置 40+ 个 agent skills。

> [!NOTE]
> 这**不是** Google 官方支持的产品。

<p>
  <a href="https://www.npmjs.com/package/@googleworkspace/cli"><img src="https://img.shields.io/npm/v/@googleworkspace/cli" alt="npm 版本"></a>
  <a href="https://github.com/googleworkspace/cli/blob/main/LICENSE"><img src="https://img.shields.io/github/license/googleworkspace/cli" alt="许可证"></a>
  <a href="https://github.com/googleworkspace/cli/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/googleworkspace/cli/ci.yml?branch=main&label=CI" alt="CI 状态"></a>
  <a href="https://www.npmjs.com/package/@googleworkspace/cli"><img src="https://img.shields.io/npm/unpacked-size/@googleworkspace/cli" alt="安装体积"></a>
</p>
<br>

⬇️ **[下载适用于你操作系统的最新版本](https://github.com/googleworkspace/cli/releases)**

`gws` 不提供静态命令列表。它会在运行时读取 Google 自有的 [Discovery Service](https://developers.google.com/discovery)，并动态构建整套命令界面。当 Google Workspace 新增 API 端点或方法时，`gws` 会自动吸纳。

> [!IMPORTANT]
> 本项目仍在积极开发中。在向 v1.0 推进的过程中，预计会出现破坏性变更。

## 目录

- [前置要求](#prerequisites)
- [安装](#installation)
- [快速开始](#quick-start)
- [为什么选择 gws？](#why-gws)
- [身份验证](#authentication)
- [AI Agent Skills](#ai-agent-skills)
- [高级用法](#advanced-usage)
- [环境变量](#environment-variables)
- [退出码](#exit-codes)
- [架构](#architecture)
- [故障排除](#troubleshooting)
- [开发](#development)

## 前置要求

- **Node.js 18+** — 用于 `npm install`（或从 [GitHub Releases](https://github.com/googleworkspace/cli/releases)) 下载预编译二进制文件
- **Google Cloud 项目** — OAuth 凭据所需。可通过 [Google Cloud Console](https://console.cloud.google.com/) 创建，或使用 [`gcloud` CLI](https://cloud.google.com/sdk/docs/install)，或使用 `gws auth setup` 命令。
- 拥有 Google Workspace 访问权限的 **Google 账号**

## 安装

推荐安装 `gws` 的方式是：从 **[GitHub Releases](https://github.com/googleworkspace/cli/releases)** 页面下载适用于你操作系统和架构的预编译二进制文件。解压归档文件，并将 `gws` 二进制文件放入 `$PATH`。

为方便起见，也可使用 `npm` 自动从 GitHub Releases 下载对应二进制文件：

```bash
npm install -g @googleworkspace/cli
```

或从源码构建：

```bash
cargo install --git https://github.com/googleworkspace/cli --locked
```

Nix flake 也可在 `github:googleworkspace/cli` 获取

```bash
nix run github:googleworkspace/cli
```

在 macOS 和 Linux 上，也可通过 [Homebrew](https://brew.sh/): 安装

```bash
brew install googleworkspace-cli
```

## 快速开始

```bash
gws auth setup     # walks you through Google Cloud project config
gws auth login     # subsequent OAuth login
gws drive files list --params '{"pageSize": 5}'
```

## 为什么选择 gws？

**面向人类** — 别再对着 REST 文档手写 `curl` 调用。`gws` 为每个资源提供 `--help`、用于预览请求的 `--dry-run`，以及自动分页。

**面向 AI 智能体** — 每个响应均为结构化 JSON。配合内置的 agent skills，你的 LLM 即可管理 Workspace，无需自定义工具链。

```bash
# List the 10 most recent files
gws drive files list --params '{"pageSize": 10}'

# Create a spreadsheet
gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'

# Send a Chat message
gws chat spaces messages create \
  --params '{"parent": "spaces/xyz"}' \
  --json '{"text": "Deploy complete."}' \
  --dry-run

# Introspect any method's request/response schema
gws schema drive.files.list

# Stream paginated results as NDJSON
gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'
```

## 身份验证

该 CLI 支持多种身份验证流程，可在笔记本电脑、CI 和服务器上运行。

### 我该用哪种配置？

| 我已有… | 使用 |
|---|---|
| 已安装并完成身份验证的 `gcloud` | [`gws auth setup`](#interactive-local-desktop)（最快） |
| 有 GCP 项目但没有 `gcloud` | [手动 OAuth 配置](#manual-oauth-setup-google-cloud-console) |
| 已有的 OAuth 访问令牌 | [`GOOGLE_WORKSPACE_CLI_TOKEN`](#pre-obtained-access-token) |
| 已有凭据 | [`GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE`](#service-account-server-to-server) |

### 交互式（本地桌面）

凭据静态加密存储（AES-256-GCM），密钥保存在系统密钥环（或当 `GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file` 时的 `~/.config/gws/.encryption_key`）中。

```bash
gws auth setup       # one-time: creates a Cloud project, enables APIs, logs you in
gws auth login       # subsequent scope selection and login
```

> `gws auth setup` 需要 [`gcloud` CLI](https://cloud.google.com/sdk/docs/install).。若没有 `gcloud`，请改用下方的 [手动配置](#manual-oauth-setup-google-cloud-console)。

> [!WARNING]
> **测试模式下的 Scope 限制：** 若 OAuth 应用未经验证（测试模式），Google 将同意范围限制在约 25 个 scope。`recommended` scope 预设包含 85+ 个 scope，对未验证应用**将失败**（对 `@gmail.com` 账号尤为明显）。请改为选择单个服务以筛选 scope 选择器：
> ```bash
> gws auth login -s drive,gmail,sheets
> ```


### 手动 OAuth 配置（Google Cloud Console）

当 `gws auth setup` 无法自动创建项目/客户端，或你需要显式控制时使用此方式。

1. 在目标项目中打开 Google Cloud Console：
   - OAuth 同意屏幕：`https://console.cloud.google.com/apis/credentials/consent?project=<PROJECT_ID>`
   - 凭据：`https://console.cloud.google.com/apis/credentials?project=<PROJECT_ID>`
2. 若提示，配置 OAuth 品牌/受众：
   - 应用类型：**External**（测试模式即可）
3. 在 **Test users** 下添加你的账号
4. 创建 OAuth 客户端：
   - 类型：**Desktop app**
5. 下载客户端 JSON 并保存至：
   - `~/.config/gws/client_secret.json`

> [!IMPORTANT]
> **你必须将自己添加为测试用户。** 在 OAuth 同意屏幕上，点击
> **Test users → Add users**，输入你的 Google 账号邮箱。否则登录将因笼统的「Access blocked」错误而失败。

然后运行：

```bash
gws auth login
```

### 浏览器辅助身份验证（人类或智能体）

你可以手动完成 OAuth，也可借助浏览器自动化完成。

- **人类流程**：运行 `gws auth login`，打开打印出的 URL，批准 scope。
- **智能体辅助流程**：智能体打开 URL、选择账号、处理同意提示，并在 localhost 回调成功后交还控制权。

若同意页面显示 **"Google hasn't verified this app"**（测试模式），点击 **Continue**。
若出现 scope 复选框，请先选择所需 scope（或 **Select all**）再继续。

### 无头 / CI（导出流程）

1. 在带浏览器的机器上完成交互式身份验证。
2. 导出凭据：
   ```bash
   gws auth export --unmasked > credentials.json
   ```
3. 在无头机器上：
   ```bash
   export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json
   gws drive files list   # just works
   ```

### 服务账号（server-to-server）

指向你的密钥文件；无需登录。

```bash
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json
gws drive files list
```

### 预先获取的访问令牌（Pre-obtained Access Token）

当其他工具（例如 `gcloud`）已为你的环境签发令牌时很有用。

```bash
export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)
```

### 优先级

| 优先级 | 来源                 | 设置方式                                 |
| -------- | ---------------------- | --------------------------------------- |
| 1        | 访问令牌           | `GOOGLE_WORKSPACE_CLI_TOKEN`            |
| 2        | 凭据文件       | `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` |
| 3        | 加密凭据  | `gws auth login`                        |
| 4        | 明文凭据  | `~/.config/gws/credentials.json`        |

环境变量也可以放在 `.env` 文件中。

## AI Agent Skills

本仓库提供 100+ 个 Agent Skills（`SKILL.md` 文件）——每个受支持的 API 各有一个，此外还有面向常见工作流的高层辅助技能，以及 50 个针对 Gmail、Drive、Docs、Calendar 和 Sheets 的精选配方。完整列表见 [Skills Index](docs/skills.md)。

```bash
# Install all skills at once
npx skills add https://github.com/googleworkspace/cli

# Or pick only what you need
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-gmail
```

<details>
<summary>OpenClaw 设置</summary>

```bash
# Symlink all skills (stays in sync with repo)
ln -s $(pwd)/skills/gws-* ~/.openclaw/skills/

# Or copy specific skills
cp -r skills/gws-drive skills/gws-gmail ~/.openclaw/skills/
```

`gws-shared` 技能包含一个 `install` 代码块，这样当 `gws` 不在 PATH 上时，OpenClaw 会通过 `npm` 自动安装 CLI。

</details>

## Gemini CLI Extension

1. 首先对 CLI 进行身份验证：

   ```bash
   gws auth setup
   ```

2. 将扩展安装到 Gemini CLI：
   ```bash
   gemini extensions install https://github.com/googleworkspace/cli
   ```

安装此扩展后，你的 Gemini CLI agent 可直接使用所有 `gws` 命令和 Google Workspace agent skills。由于 `gws` 会安全地自行处理身份验证，你只需在使用 agent 前对终端完成一次身份验证，扩展会自动继承你的凭据。

## Advanced Usage

### Multipart Uploads

```bash
gws drive files create --json '{"name": "report.pdf"}' --upload ./report.pdf
```

### Pagination

| Flag                | Description                                    | Default |
| ------------------- | ---------------------------------------------- | ------- |
| `--page-all`        | 自动分页，每页一行 JSON（NDJSON） | off     |
| `--page-limit <N>`  | 最多获取的页数                             | 10      |
| `--page-delay <MS>` | 分页之间的延迟                            | 100 ms  |

### Google Sheets — Shell Escaping

Sheets 范围使用 `!`，bash 会将其解释为历史展开。请始终用**单引号**包裹值：

```bash
# Read cells A1:C10 from "Sheet1"
gws sheets spreadsheets values get \
  --params '{"spreadsheetId": "SPREADSHEET_ID", "range": "Sheet1!A1:C10"}'

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

### Helper Commands

部分服务在自动生成的 Discovery 接口之外，还提供手工编写的辅助命令。辅助命令以 `+` 为前缀，以便与 Discovery 生成的方法名在视觉上区分，且不会发生冲突。

感知时间的辅助命令（`+agenda`、`+standup-report`、`+weekly-digest`、`+meeting-prep`）会自动使用你的 **Google 账户时区**（从 Calendar Settings API 获取并缓存 24 小时）。可在 `+agenda` 上用 `--timezone`/`--tz` 覆盖，或设置 `--timezone` 标志进行显式控制。

运行 `gws <service> --help` 可同时查看 Discovery 方法和辅助命令。

```bash
gws gmail --help      # shows +send, +reply, +reply-all, +forward, +triage, +watch …
gws calendar --help   # shows +insert, +agenda …
gws drive --help      # shows +upload …
```

**完整辅助命令参考：**

| Service | Command | Description |
|---------|---------|-------------|
| `gmail` | `+send` | 发送邮件 |
| `gmail` | `+reply` | 回复邮件（自动处理线程） |
| `gmail` | `+reply-all` | 回复全部收件人 |
| `gmail` | `+forward` | 将邮件转发给新收件人 |
| `gmail` | `+triage` | 显示未读收件箱摘要（发件人、主题、日期） |
| `gmail` | `+watch` | 监听新邮件并以 NDJSON 流式输出 |
| `sheets` | `+append` | 向电子表格追加一行 |
| `sheets` | `+read` | 从电子表格读取值 |
| `docs` | `+write` | 向文档追加文本 |
| `chat` | `+send` | 向空间发送消息 |
| `drive` | `+upload` | 上传文件并自动生成元数据 |
| `calendar` | `+insert` | 创建新事件 |
| `calendar` | `+agenda` | 显示即将到来的事件（使用 Google 账户时区；可用 `--timezone` 覆盖） |
| `script` | `+push` | 用本地文件替换 Apps Script 项目中的所有文件 |
| `workflow` | `+standup-report` | 今日会议与待办任务，生成站会摘要 |
| `workflow` | `+meeting-prep` | 为下一场会议做准备：议程、与会者和关联文档 |
| `workflow` | `+email-to-task` | 将 Gmail 邮件转换为 Google Tasks 条目 |
| `workflow` | `+weekly-digest` | 周度摘要：本周会议与未读邮件数量 |
| `workflow` | `+file-announce` | 在 Chat 空间中公告 Drive 文件 |
| `events` | `+subscribe` | 订阅 Workspace 事件并以 NDJSON 流式输出 |
| `events` | `+renew` | 续订/重新激活 Workspace Events 订阅 |
| `modelarmor` | `+sanitize-prompt` | 通过 Model Armor 模板清理用户提示词 |
| `modelarmor` | `+sanitize-response` | 通过 Model Armor 模板清理模型响应 |
| `modelarmor` | `+create-template` | 创建新的 Model Armor 模板 |

**示例：**

```bash
# Send an email
gws gmail +send --to alice@example.com --subject "Hello" --body "Hi there"

# Reply to a message
gws gmail +reply --message-id MESSAGE_ID --body "Thanks!"

# Append a row to a spreadsheet
gws sheets +append --spreadsheet SPREADSHEET_ID --values "Alice,95"

# Show today's calendar agenda
gws calendar +agenda

# Upload a file to Drive
gws drive +upload ./report.pdf --name "Q1 Report"

# Morning standup summary
gws workflow +standup-report

# Show today's agenda in a specific timezone
gws calendar +agenda --today --timezone America/New_York
```

### Model Armor (Response Sanitization)

集成 [Google Cloud Model Armor](https://cloud.google.com/security/products/model-armor)，在 API 响应到达你的 agent 之前扫描其中的提示词注入。

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

| Variable                                 | Description                  |
| ---------------------------------------- | ---------------------------- |
| `GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE` | 默认 Model Armor 模板 |
| `GOOGLE_WORKSPACE_CLI_SANITIZE_MODE`     | `warn`（默认）或 `block`  |

## Environment Variables

所有变量均为可选。可复制粘贴模板见 [`.env.example`](.env.example)。

| Variable | Description |
|---|---|
| `GOOGLE_WORKSPACE_CLI_TOKEN` | 预获取的 OAuth2 访问令牌（优先级最高） |
| `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` | OAuth 凭据 JSON 的路径（用户或服务账号） |
| `GOOGLE_WORKSPACE_CLI_CLIENT_ID` | OAuth 客户端 ID（`client_secret.json` 的替代方案） |
| `GOOGLE_WORKSPACE_CLI_CLIENT_SECRET` | OAuth 客户端密钥（与 `CLIENT_ID` 配对） |
| `GOOGLE_WORKSPACE_CLI_CONFIG_DIR` | 覆盖配置目录（默认：`~/.config/gws`） |
| `GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE` | 默认 Model Armor 模板 |
| `GOOGLE_WORKSPACE_CLI_SANITIZE_MODE` | `warn`（默认）或 `block` |
| `GOOGLE_WORKSPACE_CLI_LOG` | stderr 日志级别（例如 `gws=debug`）。默认关闭。 |
| `GOOGLE_WORKSPACE_CLI_LOG_FILE` | 带按日轮转的 JSON 日志文件目录。默认关闭。 |
| `GOOGLE_WORKSPACE_PROJECT_ID` | 用于配额/计费的 GCP 项目 ID 覆盖，以及辅助命令的回退值 |

环境变量也可以设置在 `.env` 文件中（通过 [dotenvy](https://crates.io/crates/dotenvy)). 加载

## Exit Codes

`gws` 使用结构化退出码，脚本可根据失败类型分支处理，而无需解析错误输出。

| Code | Meaning | Example cause |
|------|---------|---------------|
| `0` | 成功 | 命令正常完成 |
| `1` | API 错误 | Google 返回了 4xx/5xx 响应 |
| `2` | 身份验证错误 | 凭据缺失、过期或无效 |
| `3` | 验证错误 | 参数错误、未知服务、无效标志 |
| `4` | Discovery 错误 | 无法获取 API 架构文档 |
| `5` | 内部错误 | 意外失败 |

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

gws unknown-service files list
echo $?   # 3 — validation error (unknown service)
```

## 架构

`gws` 采用 **两阶段解析**（two-phase parsing）策略：

1. 读取 `argv[1]` 以识别服务（例如 `drive`）
2. 获取该服务的 Discovery Document（缓存 24 小时）
3. 根据文档中的资源和 method 构建 `clap::Command` 树
4. 重新解析剩余参数
5. 完成认证、构建 HTTP 请求并执行

所有输出——成功结果、错误、下载元数据——均为结构化 JSON。

## 故障排查

### 登录时出现「Access blocked」或 403

你的 OAuth 应用处于 **测试模式**（testing mode），且你的账号未列为测试用户。

**修复：** 在你的 GCP 项目中打开 [OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent) → **Test users** → **Add users** → 输入你的 Google 账号邮箱。然后重试 `gws auth login`。

### 「Google hasn't verified this app」

应用在测试模式时出现此提示属正常现象。点击 **Advanced** → **Go to \<app name\> (unsafe)** 继续。个人使用是安全的；只有向其他用户公开发布应用时才需要完成验证。

### 作用域过多 / 同意屏幕错误

未验证（测试模式）应用最多约 25 个 OAuth scope。`recommended` 的 scope 预设包含大量 scope，会超出此限制。

**修复：** 仅选择你需要的 scope：

```bash
gws auth login --scopes drive,gmail,calendar
```

### 找不到 `gcloud` CLI

`gws auth setup` 需要 `gcloud` CLI 来自动创建项目。你有三种选择：

1. [Install gcloud](https://cloud.google.com/sdk/docs/install)，并直接使用 `gcloud`。
2. 重新运行 `gws auth setup`，它会封装 `gcloud` 调用。
3. 完全跳过 `gcloud`——在 [Cloud Console](#manual-oauth-setup-google-cloud-console) 中手动配置 OAuth 凭据

### `redirect_uri_mismatch`

OAuth 客户端未创建为 **Desktop app** 类型。在 [Credentials](https://console.cloud.google.com/apis/credentials) 页面，删除现有客户端，新建类型为 **Desktop app** 的客户端，并下载新的 JSON。

### API 未启用 — `accessNotConfigured`

如果 GCP 项目未启用所需的 Google API，你会看到 reason 为 `accessNotConfigured` 的 403 错误：

```json
{
  "error": {
    "code": 403,
    "message": "Gmail API has not been used in project 549352339482 ...",
    "reason": "accessNotConfigured",
    "enable_url": "https://console.developers.google.com/apis/api/gmail.googleapis.com/overview?project=549352339482"
  }
}
```

`gws` 还会在 **stderr** 上打印一条可操作的提示：

```
💡 API not enabled for your GCP project.
   Enable it at: https://console.developers.google.com/apis/api/gmail.googleapis.com/overview?project=549352339482
   After enabling, wait a few seconds and retry your command.
```

**修复步骤：**

1. 点击 `enable_url` 链接（或从 `enable_url` JSON 字段复制）。
2. 在 GCP Console 中点击 **Enable**。
3. 等待约 10 秒，然后重试 `gws` 命令。

> [!TIP]
> 你也可以运行 `gws auth setup`，它会引导你自动为项目启用所有必需的 API。

## 开发

```bash
cargo build                       # dev build
cargo clippy -- -D warnings       # lint
cargo test                        # unit tests
./scripts/coverage.sh             # HTML coverage report → target/llvm-cov/html/
```

## 许可证

Apache-2.0

## 免责声明

> [!CAUTION]
> 这 **并非** Google 官方支持的产品。