从 AI Skills 学实战技能（五）：让 AI 接管你的 Google 办公全家桶

最近 GitHub 上 Google 有一个项目比较火：

googleworkspace/cli: github.com/googleworks…

今天，我们就来拆解这个项目的使用方法、原理和实际 AI Agent 应用场景。

一、Google Workspace CLI 是什么？

一句话总结：

安装之后，你可以在终端里，或通过 AI，直接做这些事情：

• 读取和发送 Gmail 邮件
• 创建、编辑 Google Docs
• 创建和管理 Calendar 会议
• 上传、下载、整理 Drive 文件
• 管理 Google Sheets

二、效果展示

安装并配置好 Skills 后（具体参照下文），最终效果如下（Cursor 中演示，其他 Agent 都是通用的）。

1，读取邮件：

2，查看会议：

3，创建 Google Doc

三、安装与配置

因为涉及到 Google 办公全家桶的能力调用，整体安装和配置过程，相比之前的 Skills，还是要复杂不少的，下面分步骤讲解。

3.1 Google Auth Platform 创建一个 OAuth Client

1，浏览器打开：

console.cloud.google.com/auth/overvi…

2，创建新的 project：

3，配置 OAuth Client:

点击 “Create”，会来到如下页面，需要将 JSON 文件，下载到~/.config/gws/client_secret.json.

注意，下载后的 JSON 文件本来不是这个命名，需要重命名成 client_secret.json。

3.2 安装 Google Workspace CLI

安装 CLI 非常简单：

npm install -g @googleworkspace/cli 

 

3.3 用 OAuth 登录 GWS CLI

命令行执行：

gws auth login 

 

默认全选，即授权所有 Scope，也可以按需选择。

PS：这点必须吐槽下，这个页面展示的绿色的 x，实际上已经是选中的意思，太反人性了，为啥不弄成 ，这块还纠结了会。

直接 Enter 键，进行 Confirm，会出现如下链接：

复制链接在浏览器进行 Google OAth，登录成功后即可使用 GWS CLI。

例如，验证 Calendar 访问：

gws calendar +agenda --tomorrow 

 

3.4 安装 Skills

直接将如下路径各 Skills，全部拷贝到自己 Agent 对应 skills 目录下，因 Skills 太多，实际中可以新建一个目录，如 gwsskills，然后统一放进去。这样方便以后统一管理。

github.com/googleworks…

3.5 Enable API

以 Gmail 为例，首次在 Agent 中使用时，会出现如下提示：

点击链接，去启动下 Gmail API 就好。

当然，其他的同理（如 Google Calendar、Docs 等），只需要每个首次启用下就好。

四、AI Agent Skills

启用完成后，即可正式使用。仓库里内置了 40+ Skills.

AI 可以直接调用，例如：

• 邮件分类（Email triage）
• 会议准备（Meeting preparation）
• 文件整理（File organization）

AI 可以自动执行完整流程，例如：

读取今天邮件 → 总结 → 生成文档 → 发给同事 

 

根据自己的工作场景，可以组合出各种自动化工作流，比如：

场景一：每日邮件摘要

• 每天早上让 AI 读取昨天的重要邮件
• 自动生成摘要文档
• 发送到团队协作频道

场景二：会议准备助手

• 读取即将到来的会议信息
• 从 Drive 中查找相关文档
• 自动生成会议准备清单

场景三：客户邮件跟进

• 识别未回复的客户邮件
• 在 Sheets 中记录跟进状态
• 设置 Calendar 提醒

这些工作流的核心价值在于：AI 不仅能理解你的意图，还能自动编排多个工具完成复杂任务。

五、核心技术原理

要理解 Google Workspace CLI 如何让 AI 操作你的办公软件，我们需要从三个层面来拆解：认证授权机制、CLI 工具架构，以及 AI Agent 的调用流程。

5.1 OAuth 2.0 认证流程

Google Workspace CLI 采用的是标准的 OAuth 2.0 授权码流程，这也是为什么我们需要在 Google Cloud Platform 创建 OAuth Client 的原因。

整个认证流程是这样的：

第一步：本地存储凭证

当你下载 client_secret.json 并放到 ~/.config/gws/ 目录时，这个文件包含了你的应用标识（Client ID）和密钥（Client Secret）。这就像是你的应用在 Google 那里的“身份证”。

第二步：授权请求

执行 gws auth login 时，CLI 会：

1. 读取 client_secret.json 中的凭证
2. 生成一个授权 URL，包含你选择的权限范围（Scopes）
3. 在浏览器中打开这个 URL，让你登录 Google 账号并授权

第三步：获取访问令牌

当你在浏览器完成授权后，Google 会返回一个授权码（Authorization Code）。CLI 用这个授权码换取：

• Access Token（访问令牌）：短期有效，用于实际的 API 调用
• Refresh Token（刷新令牌）：长期有效，用于在 Access Token 过期后自动获取新的令牌

这些令牌会被加密存储在本地，之后每次调用 Google API 时，CLI 会自动附带 Access Token 进行身份验证。

5.2 CLI 工具的架构设计

Google Workspace CLI 本质上是一个命令行封装层，它的核心架构包含三个部分：

命令解析层

当你执行类似 gws gmail list --max-results 10 这样的命令时，CLI 会：

1. 解析命令和参数
2. 验证参数的合法性
3. 将命令转换为对应的 API 调用

API 适配层

Google Workspace 包含多个独立的 API(Gmail API、Calendar API、Drive API 等），每个 API 都有自己的调用规范。CLI 的适配层负责：

• 统一不同 API 的调用方式
• 处理分页、限流等通用逻辑
• 格式化返回结果，使其更易读

认证管理层

这一层负责：

• 自动刷新过期的 Access Token
• 管理多账号切换
• 处理权限不足等异常情况

5.3 AI Agent 的调用机制

这是整个系统最精妙的部分 —— 如何让 AI 理解并正确调用这些 CLI 命令？

Skills 文件的作用

每个 Skill 文件（如 gws-gmail-send/SKILL.md）实际上是一个结构化的“使用说明书”，它告诉 AI:

1. 这个工具是干什么的（功能描述）
2. 什么时候应该用它（使用场景）
3. 怎么用（命令格式和参数说明）
4. 返回结果是什么样的（输出格式）

例如，gws-gmail-send/SKILL.md 的实际内容是：

--- 

name: gws-gmail-send 

version: 1.0.0 

description: "Gmail: Send an email."
--- 

 

# gmail +send 

 

Send an email 

 

## Usage 

gws gmail +send --to <emails> --subject <subject> --body <text> 

 

## Flags 

| Flag | Required | Default | Description | 

|------|----------|---------|-------------| 

| --to |  | — | Recipient email address(es), comma-separated | 

| --subject |  | — | Email subject | 

| --body |  | — | Email body (plain text, or HTML with --html) | 

| --cc | — | — | CC email address(es), comma-separated | 

| --html | — | — | Treat --body as HTML content | 

 

## Examples 

gws gmail +send --to alice@example.com --subject 'Hello' --body 'Hi Alice!' 

</text></subject></emails> 

 

AI 的决策流程

有了这些 Skills 文件作为“使用说明书”，AI 就能理解如何调用 CLI 工具。当你对 AI 说“发一封邮件给 alice@example.com“时，AI 会：

1. 意图识别：理解你想要“发送邮件”
2. 技能匹配：在加载的 Skills 中找到 gws-gmail-send 技能
3. 参数推理：根据你的描述提取收件人、主题、正文等参数
4. 命令执行：调用 gws gmail +send --to alice@example.com --subject "..." --body "..."
5. 结果解析：将执行结果转换为自然语言回复

再比如，当你说“查看今天的未读邮件”时，AI 会：

1. 意图识别：理解你想要“查看邮件”
2. 技能匹配：找到 gws-gmail-triage 技能（专门用于邮件分类）
3. 命令执行：调用 gws gmail +triage 获取未读邮件摘要
4. 结果呈现： 以结构化的方式展示发件人、主题、日期等信息

工具链的组合调用

更强大的是，AI 可以将多个 Skills 串联起来，形成自动化工作流。比如：

用户: "总结今天的邮件并创建一个文档" 

 

AI 执行流程: 

1. gws gmail users messages list --params '{"q":"after:2026/03/16"}'  (获取邮件列表) 

2. gws gmail users messages get --params '{"id":"xxx"}'  (逐个读取邮件内容) 

3. [AI 内部处理] 分析邮件内容,生成摘要 

4. gws docs documents create --json '{"title":"邮件摘要-2026-03-16"}'  (创建文档) 

5. gws docs documents batchUpdate --json '{"documentId":"xxx", ...}'  (写入摘要内容) 

 

这个过程中，AI 会：

• 从 gws-gmail/SKILL.md 了解如何操作邮件
• 从 gws-docs/SKILL.md 了解如何创建和编辑文档
• 自动处理中间的数据转换和错误处理
• 将多个独立的 CLI 命令编排成完整的业务流程

5.4 安全性考虑

这套机制的安全性体现在：

1. 最小权限原则：你可以在授权时只选择需要的 Scopes，比如只授权读取邮件，不授权发送
2. 本地凭证存储： Token 存储在你的本地机器，不会上传到 AI 服务器
3. 可撤销性：你随时可以在 Google 账号设置中撤销授权

六、结语

软件入口正在从「人→软件」变为「人→AI→软件」。Google Workspace CLI，也正是在这一背景下出来的。相信以后会有越来越多的应用，会统一能力接口，并在此基础上，统一封装成 Skills，支持 AI 的调用。这也正是 AI Skills 的魅力所在。