Apps 脚本：使用 Gemini CLI 和 MCP 服务器对 Gmail 插件进行氛围编码

1. 概览

在本实验中，您将学习如何使用 AI 驱动的现代工作流，从头开始构建动态 Gmail 插件。您将使用 Gemini CLI 来编排强大的本地开发环境，利用 MCP (Model Context Protocol) 服务器和 Gemini CLI 扩展程序来集成 gcloud 和 clasp 等工具。

您创建的插件将通过调用 Google Cloud 的 Vertex AI 平台上的图片模型，按需生成并显示独特的猫图片。

最后，您将拥有一个功能齐全的 Gmail 插件，该插件会调用 Vertex AI API 以直接在 Gmail 界面中生成独特的图片，所有操作都通过本地命令行进行管理。

2. 学习内容

完成本实验后，您将学习如何：

  • 设置和使用带扩展程序的 Gemini CLI
  • 构建调用外部 API 的 Gmail 插件
  • 修改插件以调用 Vertex AI API 来生成图片
  • 从 Apps 脚本用户界面部署 Google Workspace 插件的测试版本

3. 设置和要求

开始实验之前

  1. 如果您还没有 Google 账号，则必须先创建一个 Google 账号。请使用个人账号，而不是工作或学校账号。工作和学校账号可能会受到限制，导致您无法启用本实验所需的 API。
  2. 登录 Google Cloud 控制台。
  3. 在 Cloud 控制台中启用结算功能。
  1. 创建新项目，或选择重复使用现有项目。

实验要求

如需充分利用本实验，您需要：

  • 网络浏览器 ：标准网络浏览器，例如 Chrome（推荐）。
  • 专用时间 ：预留足够的时间专注于实验活动。

4. 设置 Google Cloud 环境

  1. 点击“激活 Cloud Shell”图标7a0d8a88ebea95af.png： 在控制台标题栏的右上角，点击终端图标，将鼠标悬停在该图标上时，系统会显示“激活 Cloud Shell”。
  2. 授权 。
  3. 等待初始化 ：Cloud Shell 会话将在控制台窗口底部的新框内打开。会话需要一些时间才能初始化，因为它会为您预配基于 Debian 的临时虚拟机 (VM)。
  4. 会话初始化后，您会看到命令行提示符 (user@cloudshell:~ $)。
  5. 您可以点击展开按钮来展开 Cloud Shell 窗口，以增大窗口的大小。
  6. 验证您的项目 ：运行以下命令：
gcloud config list project
  1. 更改项目 （如果需要）：
gcloud config set project [YOUR_PROJECT_ID]

您已设置完毕，可以开始实验活动了！

5. 配置本地开发环境

在此任务中，您将设置 Gemini CLI 及其扩展程序，以便从终端管理 Cloud 和 Apps 脚本项目。

  1. Gemini CLI 已作为 Cloud Shell 环境的一部分安装，因此无需安装。
  2. clasp 也已作为 Cloud Shell 环境的一部分安装，但我们将确保在本实验中使用最新版本。
npm install -g @google/clasp@latest
  1. 输入以下命令并按照以下说明操作，以授权 clasp 访问您的账号：
clasp login --no-localhost

点击终端中生成的网址，以授权 clasp。使用学生实验账号登录，并在系统提示您选择权限时，选择全选 ，然后点击继续 。然后，您应该会看到类似下面的错误消息。

db77651c2ce19d7f.png

从浏览器窗口中复制网址（以 http://localhost:8888/?code=xxx 开头），然后将其粘贴到打开的 Cloud Shell 会话中，并按 Enter 键。clasp 将继续授权流程，如果登录成功，您将看到类似于 You are logged in as user@gmail.com 的确认消息。

  1. 安装 clasp Gemini CLI 扩展程序。
gemini extensions install https://github.com/google/clasp --consent
  1. 安装 gcloud Gemini CLI 扩展程序。
gemini extensions install https://github.com/gemini-cli-extensions/gcloud --consent
  1. 安装 Google Workspace 开发者 Gemini CLI 扩展程序。
gemini extensions install https://github.com/googleworkspace/developer-tools --consent
  1. 创建空项目目录：
mkdir genai-cat-add-on
  1. 切换到新创建的项目目录：
cd genai-cat-add-on
  1. 为此项目配置 Gemini CLI 上下文的描述文件：
cat << 'END_OF_FILE' > GEMINI.md
## **Gemini CLI Instructions for Gmail Add-on Development**

You are a methodical **Google Workspace extensibility and integration expert**. Your goal is to build a Gmail Add-on for the `genai-cat-add-on` project by writing Apps Script code and using command-line tools.

---

## **Tools Available**

*   **`clasp`**: Use this tool for all Apps Script project operations like pushing files.
*   **`gcloud`**: Use this tool for Google Cloud operations, such as enabling APIs or managing IAM permissions.
*   **`workspace-developer`**: Use this tool to search the official Google Workspace documentation for correct syntax, manifest properties, and required OAuth scopes.

---

## **Development Workflow and Validation**

You MUST follow the workflow below when building the add-on:

1.  **Mandatory Documentation Check**: Before creating, committing, or modifying any code (especially manifest files or Apps Script functions), you **MUST** first utilize the **`workspace-developer` tool** and use **search_workspace_docs** to search and validate the necessary Apps Script syntax, OAuth scopes, Apps Script services such as GmailApp, and best practices. Always refer to the official Google Workspace developer documentation via this tool for authoritative information.
2.  **Security and Scopes**: For every code commit or structural change, you must first **verify the manifest file (`appsscript.json`) includes the necessary OAuth scopes** for Gmail access and external API calls, ensuring you use the **minimal required scopes** and nothing more to adhere to the principle of least privilege.
3.  **Versioning/Persistence**: After any successful file creation, update, or deletion, you must ensure the changes are persistently saved and pushed using the appropriate `clasp` tool command.
4.  **Error Handling**: Include appropriate debugging and robust error handling code in all Apps Script functions.

---

## **Project and API Specifications**

* **Project Focus:** All work is centered on the **`genai-cat-add-on`** Apps Script project.
* **Vertex AI Details:** If asked to generate images, you must use the **`gemini-2.5-flash-image`** model on **Vertex AI**. Do NOT use imagen. All Vertex AI operations must use the currently logged-in user's credentials and the current Google Cloud project.
END_OF_FILE
  1. 在学生实验账号中启用 Google Apps 脚本 API，然后点击 Google Apps 脚本 API 并将其从 关闭 切换为 开启。

41eb25a89e13e1ff.gif

6. 启动并验证 Gemini CLI 设置

  1. 在项目目录中启动 Gemini。
gemini
  1. 默认情况下，Gemini CLI 会要求您查看并接受对文件的更改。对于本实验，我们建议您按 Shift + Tab 关闭此功能以自动接受修改，从而帮助您及时完成实验。现在，您的屏幕上应该会以红色突出显示此选项。

31a7326896719d73.png

  1. 验证 GEMINI.md 文件是否已加载，并显示其在 Gemini CLI 上下文中加载的内容：
/memory show
  1. 验证 MCP 服务器是否已正确配置。gcloud MCP 服务器可能需要一段时间才能初始化，因此如果显示已断开连接，请不要惊慌。请在几分钟后重试。
/mcp list

7. 创建 Gmail 插件

  1. 让 Gemini 创建第一个版本的 Gmail 插件：
Use Apps Script to create a new Google Workspace add-on that displays a random cat image using the Cat-as-a-Service API upon opening the add-on in Gmail. Make sure you update the code and manifest files, use the correct scopes, and use the API documentation at https://cataas.com/doc.html.

Once done, provide a link to view the project.
  1. Gemini 完成对您的提示的响应后，点击提供的链接，或前往 Apps 脚本 首页，然后点击 genai-cat-add-on 项目。
  2. 点击页面左侧的项目设置 图标（齿轮图标） 9485fddc5bf46369.png。

2bc043bb3c3a216d.png

  1. 选择“在编辑器中显示‘appsscript.json’清单文件”选项。

e74dca570d64e540.png 9. 切换到编辑器屏幕，查看 Code.gs 中生成的代码以及 appsscript.json 中配置项目的清单文件

8. 安装并测试插件

  1. 返回到 Apps 脚本项目页面。
  2. 在顶部找到“部署”按钮。
  3. 点击“部署”旁边的箭头，然后选择测试部署 。
  4. 在随即显示的“测试部署”对话框中，您应该会看到一个用于安装未发布的插件的选项。
  5. 点击 Install 按钮。
  6. 在看到确认消息后，点击底部的“完成”以关闭部署对话框。
  7. 打开并刷新 Gmail 首页 。
  8. 插件现在应该可用了。插件会显示在右侧边栏中。
  9. 首次与插件互动时，系统会提示您授权该插件访问必要的数据或权限。按照屏幕上的提示授予权限。
  10. 您应该会看到猫的图片。如果没有看到，请通过分享错误消息来使用 Gemini CLI 进行问题排查。

9. 实现 AI 图片生成逻辑

  1. 让 Gemini 现在添加生成图片的逻辑：
Now update the add-on to display an AI-generated image using the samples in https://docs.cloud.google.com/vertex-ai/generative-ai/docs/multimodal/image-generation#use-image-generation. 

The image should show a cute cat if I open my inbox, and should add a speech bubble saying "<email sender name> rocks!" with the actual sender name when I open an email.
  1. 刷新 Gmail 首页，然后再次打开插件。如果系统要求您接受任何新权限，请接受。
  2. 现在应该会显示 AI 生成的猫图片。如果未显示图片，请通过分享错误消息并按照其说明来使用 Gemini CLI 进行问题排查。
  3. 打开一封电子邮件，注意图片如何更改以显示带有发件人姓名的对话气泡。使用 Gemini CLI 排查任何问题，类似于上一步。

10. [可选] 添加动物类型下拉菜单

  1. 问问 Gemini，除了猫图片以外，是否可以添加生成其他动物的选项。
Add a dropdown menu that lets the user choose the type of animal image it wants. Choose 2 random animals to add to the list in addition to the cat image.
  1. 刷新插件，方法是点击三个垂直点，然后点击“刷新”，或者刷新 Gmail 首页，然后再次打开插件。
  2. 选择其他动物图片，测试新功能。如果出现错误（例如界面未刷新或显示错误），请通过分享错误消息并按照其说明来使用 Gemini CLI 进行问题排查。

11. 清理

退出 Gemini CLI

发出以下命令，退出 Gemini CLI 并查看使用情况统计信息：

/quit

删除 Google Cloud 项目

为避免因本 Codelab 中使用的资源而向您的 Google Cloud 账号收取费用，我们建议您删除该 Google Cloud 项目。

gcloud projects delete $GOOGLE_CLOUD_PROJECT

删除 Apps 脚本项目

点击左侧导航面板中的 dc2524b2c9878567.png 信息图标，然后点击屏幕右侧的 4ad389ddfeda5d7f.png 垃圾桶图标，以移除 Apps 脚本项目。

12. 故障排除提示

  • 如果您在使用 Gemini CLI 和扩展程序时遇到问题，可以使用以下命令运行特定可正常运行的 Gemini CLI 版本：
npx https://github.com/google-gemini/gemini-cli#v0.12.0
  • 如果您遇到任何错误，请问问 Gemini 为您修复这些错误，并分享错误和上下文（发生错误的位置）
  • 如果 Gemini 实现错误日志记录并要求您分享任何错误，请重新运行导致错误的步骤，然后与 Gemini 分享结果。
  • 您可以尝试使用以下提示：
You have my permission to fix any errors. Please go ahead and make it work.
  • 如果您遇到问题并想帮助 Gemini，可以使用以下提示：
Use the following Github repo as a reference implementation to make my add-on work: https://github.com/googleworkspace/add-ons-samples/tree/main/apps-script/generative-ai/cat-add-on

13. 恭喜！

您已成功完成本实验，并使用 Gemini CLI 为 Gmail 插件编写了 vibe 代码。

在本实验中，您学习了如何执行以下任务：

  • 使用 Gemini CLI。
  • 使用 MCP (Model Context Protocol) 服务器安装工具并扩展 Gemini CLI。
  • 构建、部署和安装 Gmail 插件。

现在，您可以继续学习我们的下一个实验了。