Apps Script: Vibe-code tiện ích bổ sung của Gmail với máy chủ Gemini CLI và MCP

1. Tổng quan

Phòng thí nghiệm này hướng dẫn bạn thực hiện quy trình làm việc hiện đại, dựa trên AI để xây dựng một tiện ích bổ sung Gmail linh hoạt từ đầu. Bạn sẽ sử dụng Gemini CLI để điều phối một môi trường phát triển cục bộ mạnh mẽ, tận dụng các máy chủ MCP (Giao thức ngữ cảnh mô hình) và các tiện ích Gemini CLI để tích hợp các công cụ như gcloud và clasp.

Tiện ích bổ sung mà bạn tạo sẽ tạo và hiển thị một hình ảnh mèo độc đáo theo yêu cầu bằng cách gọi một mô hình hình ảnh trên nền tảng Vertex AI của Google Cloud.

Đến cuối khoá học, bạn sẽ có một tiện ích bổ sung Gmail hoạt động đầy đủ, gọi Vertex AI API để tạo hình ảnh riêng biệt ngay trong giao diện Gmail, tất cả đều được quản lý từ dòng lệnh cục bộ.

2. Kiến thức bạn sẽ học được

Khi hoàn tất bài thực hành này, bạn sẽ tìm hiểu cách:

  • Thiết lập và sử dụng Gemini CLI với các tiện ích
  • Tạo một Tiện ích bổ sung cho Gmail gọi một API bên ngoài
  • Sửa đổi tiện ích bổ sung để gọi Vertex AI API nhằm tạo hình ảnh
  • Triển khai phiên bản thử nghiệm của một Tiện ích bổ sung Google Workspace từ giao diện người dùng Apps Script

3. Thiết lập và yêu cầu

Trước khi bạn bắt đầu thực hành

  1. Nếu chưa có Tài khoản Google, bạn phải tạo một Tài khoản Google. Sử dụng tài khoản cá nhân thay vì tài khoản do nơi làm việc hoặc trường học cấp. Tài khoản do nơi làm việc và trường học cấp có thể có các hạn chế khiến bạn không thể bật những API cần thiết cho lớp học này.
  2. Đăng nhập vào Google Cloud Console.
  3. Bật tính năng thanh toán trong Cloud Console.
  1. Tạo một dự án mới hoặc chọn sử dụng lại một dự án hiện có.

Yêu cầu về phòng thí nghiệm

Để khai thác tối đa lớp học này, bạn cần:

  • Trình duyệt web: Một trình duyệt web tiêu chuẩn như Chrome (nên dùng).
  • Dành thời gian: Dành đủ thời gian để tập trung vào các hoạt động trong phòng thí nghiệm.

4. Thiết lập môi trường Google Cloud

  1. Nhấp vào biểu tượng Kích hoạt Cloud Shell 7a0d8a88ebea95af.png: Ở góc trên cùng bên phải của tiêu đề bảng điều khiển, hãy nhấp vào biểu tượng thiết bị đầu cuối có nội dung "Kích hoạt Cloud Shell" khi bạn di chuột qua biểu tượng đó.
  2. Uỷ quyền.
  3. Chờ khởi tạo: Một phiên Cloud Shell sẽ mở trong một khung hình mới ở cuối cửa sổ bảng điều khiển. Phiên sẽ mất vài phút để khởi động vì phiên cung cấp cho bạn một máy ảo (VM) tạm thời dựa trên Debian.
  4. Sau khi phiên được khởi tạo, bạn sẽ thấy một dấu nhắc dòng lệnh (user@cloudshell:~ $).
  5. Bạn có thể mở rộng cửa sổ Cloud Shell bằng cách nhấp vào nút mở rộng để tăng kích thước của cửa sổ.
  6. Xác minh dự án của bạn: Chạy lệnh:
gcloud config list project
  1. Thay đổi dự án (nếu cần):
gcloud config set project [YOUR_PROJECT_ID]

Bạn đã sẵn sàng bắt đầu các hoạt động trong phòng thí nghiệm!

5. Định cấu hình môi trường phát triển cục bộ

Trong nhiệm vụ này, bạn sẽ thiết lập Gemini CLI và các tiện ích của Gemini CLI để quản lý các dự án trên đám mây và Apps Script từ thiết bị của mình.

  1. Gemini CLI đã được cài đặt trong môi trường Cloud Shell, nên bạn không cần cài đặt nữa.
  2. clasp cũng đã được cài đặt trong môi trường Cloud Shell, tuy nhiên, chúng ta sẽ đảm bảo rằng mình đang dùng phiên bản mới nhất trong phòng thực hành này.
npm install -g @google/clasp@latest
  1. Cho phép clasp truy cập vào tài khoản của bạn bằng cách nhập lệnh sau và làm theo hướng dẫn bên dưới:
clasp login --no-localhost

Nhấp vào URL được tạo trong thiết bị đầu cuối để uỷ quyền cho clasp. Sử dụng tài khoản phòng thực hành của học viên để đăng nhập, khi được nhắc cấp quyền, hãy chọn Chọn tất cả rồi nhấp vào Tiếp tục. Sau đó, bạn sẽ thấy một thông báo lỗi như bên dưới.

db77651c2ce19d7f.png

Sao chép URL từ cửa sổ trình duyệt (bắt đầu bằng http://localhost:8888/?code=xxx) rồi dán vào phiên Cloud Shell đang mở và nhấn phím Enter. clasp sẽ tiếp tục quy trình uỷ quyền và nếu đăng nhập thành công, bạn sẽ thấy một thông báo xác nhận tương tự như You are logged in as user@gmail.com.

  1. Cài đặt tiện ích clasp Gemini CLI.
gemini extensions install https://github.com/google/clasp --consent
  1. Cài đặt gcloudtiện ích Gemini CLI.
gemini extensions install https://github.com/gemini-cli-extensions/gcloud --consent
  1. Cài đặt tiện ích Gemini CLI dành cho nhà phát triển Google Workspace.
gemini extensions install https://github.com/googleworkspace/developer-tools --consent
  1. Tạo một thư mục dự án trống:
mkdir genai-cat-add-on
  1. Thay đổi thành thư mục dự án mới tạo:
cd genai-cat-add-on
  1. Định cấu hình tệp bối cảnh Gemini CLI cho dự án này:
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. Bật API Google Apps Script trong tài khoản phòng thí nghiệm dành cho sinh viên, rồi nhấp vào API Google Apps Script và chuyển trạng thái từ Tắt sang Bật.

41eb25a89e13e1ff.gif

6. Bắt đầu và xác minh chế độ thiết lập Gemini CLI

  1. Khởi động Gemini trong thư mục dự án của bạn.
gemini
  1. Theo mặc định, Gemini CLI sẽ yêu cầu bạn xem xét và chấp nhận các thay đổi đối với tệp. Đối với lớp học này, bạn nên tắt chế độ này bằng cách nhấn tổ hợp phím Shift + Tab để tự động chấp nhận nội dung chỉnh sửa, giúp bạn hoàn thành lớp học đúng thời gian. Lúc này, lựa chọn này sẽ được đánh dấu bằng màu đỏ trên màn hình.

31a7326896719d73.png

  1. Xác minh rằng tệp GEMINI.md đã được tải và cho biết tệp đó được tải trong ngữ cảnh của Gemini CLI:
/memory show
  1. Xác minh rằng các máy chủ MCP được định cấu hình đúng cách. Máy chủ gcloud MCP có thể mất một lúc để khởi động, vì vậy, đừng lo lắng nếu máy chủ này hiển thị trạng thái đã ngắt kết nối. Vui lòng đợi vài phút rồi thử lại.
/mcp list

7. Tạo tiện ích bổ sung Gmail

  1. Yêu cầu Gemini tạo phiên bản đầu tiên của tiện ích bổ sung 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. Sau khi Gemini hoàn tất việc phản hồi câu lệnh của bạn, hãy nhấp vào đường liên kết được cung cấp hoặc chuyển đến trang chủ Apps Script rồi nhấp vào dự án genai-cat-add-on.
  2. Nhấp vào biểu tượng Cài đặt dự án (biểu tượng bánh răng) 9485fddc5bf46369.pngở bên trái trang.

2bc043bb3c3a216d.png

  1. Chọn mục "Hiển thị tệp kê khai "appsscript.json" trong trình chỉnh sửa".

e74dca570d64e540.png 9. Chuyển sang màn hình Trình chỉnh sửa và xem mã được tạo trong Code.gs cũng như tệp kê khai định cấu hình dự án trong appsscript.json

8. Cài đặt và kiểm thử tiện ích bổ sung

  1. Quay lại trang dự án Apps Script.
  2. Tìm nút Triển khai ở trên cùng.
  3. Nhấp vào mũi tên bên cạnh mục Triển khai rồi chọn Triển khai thử nghiệm.
  4. Trong hộp thoại "Test deployments" (Kiểm thử việc triển khai) xuất hiện, bạn sẽ thấy một lựa chọn để cài đặt tiện ích bổ sung chưa xuất bản.
  5. Nhấp vào nút Install (Cài đặt).
  6. Một thông báo xác nhận sẽ xuất hiện. Nhấp vào Done (Xong) ở dưới cùng để đóng hộp thoại triển khai.
  7. Mở và làm mới trang chủ Gmail.
  8. Lúc này, tiện ích bổ sung sẽ có sẵn. Tiện ích bổ sung này sẽ xuất hiện trên bảng điều khiển bên phải.
  9. Lần đầu tiên tương tác với tiện ích bổ sung, bạn sẽ nhận được lời nhắc uỷ quyền cho tiện ích bổ sung này truy cập vào dữ liệu hoặc quyền cần thiết. Làm theo lời nhắc trên màn hình để cấp quyền.
  10. Bạn sẽ thấy hình ảnh của chú mèo. Nếu không thấy, hãy khắc phục sự cố bằng Gemini CLI bằng cách chia sẻ thông báo lỗi.

9. Triển khai logic Tạo hình ảnh bằng AI

  1. Yêu cầu Gemini thêm logic để tạo hình ảnh:
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. Làm mới trang chủ Gmail rồi mở lại tiện ích bổ sung. Chấp nhận mọi quyền mới nếu được yêu cầu.
  2. Lúc này, một hình ảnh về mèo do AI tạo sẽ xuất hiện. Nếu hình ảnh không xuất hiện, hãy khắc phục sự cố bằng Gemini CLI bằng cách chia sẻ thông báo lỗi và làm theo hướng dẫn của Gemini CLI.
  3. Mở một email và lưu ý cách hình ảnh thay đổi để hiển thị một bong bóng thoại có tên người gửi. Khắc phục mọi vấn đề với Gemini CLI tương tự như bước trước.

10. [Không bắt buộc] Thêm trình đơn thả xuống về loại động vật

  1. Yêu cầu Gemini thêm lựa chọn tạo hình ảnh các loài động vật khác ngoài hình ảnh mèo.
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. Làm mới tiện ích bổ sung bằng cách nhấp vào ba dấu chấm dọc rồi nhấp vào Làm mới, hoặc làm mới trang chủ Gmail rồi mở lại tiện ích bổ sung.
  2. Hãy thử chức năng mới bằng cách chọn một bức ảnh khác về động vật. Nếu có lỗi, chẳng hạn như giao diện người dùng không làm mới hoặc xuất hiện lỗi, hãy khắc phục sự cố bằng Gemini CLI bằng cách chia sẻ thông báo lỗi và làm theo hướng dẫn của Gemini CLI.

11. Dọn dẹp

Thoát Gemini CLI

Thoát Gemini CLI và xem số liệu thống kê về mức sử dụng bằng cách đưa ra lệnh sau:

/quit

Xoá dự án trên Google Cloud

Để tránh bị tính phí cho Tài khoản Google Cloud đối với các tài nguyên được dùng trong lớp học lập trình này, bạn nên xoá dự án trên Google Cloud.

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Xoá dự án Apps Script

Nhấp vào biểu tượng thông tin dc2524b2c9878567.png trong bảng điều hướng bên trái, rồi nhấp vào biểu tượng thùng rác 4ad389ddfeda5d7f.png ở bên phải màn hình để xoá dự án Apps Script.

12. Mẹo khắc phục sự cố

  • Nếu gặp vấn đề với Gemini CLI và các tiện ích, bạn có thể dùng lệnh sau để chạy một phiên bản cụ thể đang hoạt động của Gemini CLI:
npx https://github.com/google-gemini/gemini-cli#v0.12.0
  • Nếu bạn gặp phải lỗi, hãy yêu cầu Gemini sửa lỗi cho bạn và chia sẻ lỗi cũng như bối cảnh (nơi xảy ra lỗi)
  • Nếu Gemini triển khai tính năng ghi nhật ký lỗi và yêu cầu bạn chia sẻ mọi lỗi, hãy chạy lại các bước gây ra lỗi rồi chia sẻ kết quả với Gemini.
  • Bạn có thể thử một câu lệnh như:
You have my permission to fix any errors. Please go ahead and make it work.
  • Nếu gặp khó khăn và muốn giúp Gemini, bạn có thể sử dụng câu lệnh sau:
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. Xin chúc mừng!

Bạn đã hoàn tất thành công bài thực hành và sử dụng Gemini CLI để tạo mã rung cho một tiện ích bổ sung Gmail.

Trong phòng thí nghiệm này, bạn đã tìm hiểu cách:

  • Sử dụng Gemini CLI.
  • Cài đặt các công cụ và mở rộng Gemini CLI bằng máy chủ MCP (Giao thức ngữ cảnh mô hình).
  • Tạo, triển khai và cài đặt một Tiện ích bổ sung cho Gmail.

Giờ thì bạn đã sẵn sàng chuyển sang phòng thí nghiệm tiếp theo của chúng tôi.