Gemini CLI 扩展程序使用入门

1. 简介

Gemini CLI 是一款开源的 AI 赋能的终端智能体，可将 Gemini 模型的功能直接带入您的命令行。虽然 Gemini 本身就已十分强大，但通过 Gemini CLI 扩展服务，可以充分发挥其潜力。

扩展程序是增强 Gemini CLI 功能的官方标准化方式。在推出扩展程序之前，自定义 CLI 通常需要手动修改 settings.json 等配置文件，这个过程可能“杂乱无章且容易出错”。

可以将扩展程序视为 Gemini CLI 自定义的“运输容器”。它是一个自成一体、可进行版本控制且易于分发的软件包，其中捆绑了教 Gemini 学习新技能所需的所有组件。此“运输容器”可以包括：

MCP 服务器配置：这些配置将 Gemini 连接到外部工具和 API，例如 Google Cloud API 或第三方服务。
上下文文件 (GEMINI.md)：这些是“剧本”，可为模型提供有关如何有效使用新工具的具体说明和指南。
自定义斜杠命令（.toml 文件）：这些命令将复杂的多步骤提示封装为简单易用的命令，例如 /deploy。
工具限制 (excludeTools)：这些限制可以停用内置工具，以创建更安全或更专注的环境。

扩展程序的核心价值在于将 Gemini CLI 从个人助理转变为可扩展的企业级平台。团队可以将整个云堆栈打包到单个扩展程序中，从而让新开发者只需一条命令即可高效工作。

在此 Codelab 中，您将学习如何使用以下强大的生态系统。您不会编写扩展程序，但会安装并使用四种不同的扩展程序，以便为终端添加应用部署、安全分析、数据分析和基础设施即代码功能。

实践内容

安装并配置 Gemini CLI 及其 Google Cloud 前提条件。
浏览官方 Gemini CLI 扩展程序库以查找扩展程序。
使用 gemini extensions 命令行界面安装、列出和管理扩展程序。
探索一些 Gemini CLI 扩展程序

学习内容

Gemini CLI 扩展程序是什么，以及为什么它们是自定义 CLI 的标准。
如何从扩展程序库或 GitHub 网址中查找和安装扩展程序。
密钥管理命令的功能：gemini extensions install、gemini extensions list 和 gemini extensions update。
安装和使用几个 Gemini CLI 扩展程序

所需条件

Chrome 网络浏览器
Gmail 账号
启用了结算功能的 Cloud 项目

此 Codelab 适用于各种水平的用户和开发者（包括新手）。您应熟悉 Gemini CLI，不过我们也会提供从头开始安装 Gemini CLI 的步骤。如果您想熟悉 Gemini CLI，不妨试试这个 Codelab：“亲自体验 Gemini CLI”。

2. 准备工作

创建项目

在 Google Cloud Console 的项目选择器页面上，选择或创建一个 Google Cloud 项目。
确保您的 Cloud 项目已启用结算功能。了解如何检查项目是否已启用结算功能。
您将使用 Cloud Shell，这是一个在 Google Cloud 中运行的命令行环境，它预加载了 bq。点击 Google Cloud 控制台顶部的“激活 Cloud Shell”。

“激活 Cloud Shell”按钮图片

连接到 Cloud Shell 后，您可以使用以下命令检查自己是否已通过身份验证，以及项目是否已设置为您的项目 ID：

gcloud auth list

在 Cloud Shell 中运行以下命令，以确认 gcloud 命令了解您的项目。

gcloud config list project

如果项目未设置，请使用以下命令进行设置：

gcloud config set project <YOUR_PROJECT_ID>

通过以下命令启用所需的 API。这可能需要几分钟的时间，请耐心等待。

gcloud services enable cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       run.googleapis.com \
                       cloudbuild.googleapis.com \

成功执行该命令后，您应该会看到类似如下所示的消息：

Operation "operations/..." finished successfully.

如果遗漏了任何 API，您始终可以在实施过程中启用它。

如需了解 gcloud 命令和用法，请参阅文档。在进行设置并运行 Gemini CLI 之前，我们先创建一个文件夹，您将使用该文件夹作为在其中创建的所有项目的根文件夹。这是 Gemini CLI 的初始工作目录，不过它也会引用您系统中的其他一些文件夹，您稍后会根据需要用到这些文件夹。

继续操作，创建一个示例文件夹 (gemini-cli-projects)，然后通过以下命令进入该文件夹。如果您希望使用其他文件夹名称，请这样做。

mkdir gemini-cli-projects

我们来导航到该文件夹：

cd gemini-cli-projects

您可以在新的 Cloud Shell 终端中通过 gemini 命令直接启动 Gemini CLI，也可以在单独的 Cloud Shell 终端中启动 Gemini CLI。

我们与 Gemini CLI 的首次互动

我们需要确保 Gemini CLI 环境一切正常，因此可以发出第一个提示，如下所示：

Give me a famous quote on Artificial Intelligence and who said that?

您会注意到，我们的查询触发了 GoogleSearch 工具（Gemini CLI 中的内置工具）。换句话说，您已经使用过 Gemini CLI 的一项强大的内置工具，即 GoogleSearch，该工具可根据从网络获取的信息生成回答。您应该会收到针对查询的回答。

接下来，我们来了解一下扩展程序。

3. 什么是扩展程序？

扩展程序是一个独立的、可确定版本且易于分发的软件包。您可以将其视为 Gemini CLI 自定义项的“运输容器”，将特定工作流所需的一切内容捆绑到一个整洁的软件包中。

扩展程序可以捆绑以下项的任意组合：

自定义斜杠命令（您的 .toml 文件）。
MCP 服务器配置（之前位于 settings.json 中）。
上下文文件 (GEMINI.md)，用于向模型提供具体说明和指南。
工具限制 (excludeTools)，可打造更安全、更专注的环境。

为什么要使用扩展程序？核心优势

采用扩展程序进行自定义可带来以下几项强大优势：

一键安装：这是关键。用户只需使用一个命令（gemini extensions install <URL> 或 gemini extensions install --path=some/local/path）即可安装完整而复杂的工具集，而无需进行多步骤的手动设置。上述命令中的 <网址> 可以是您托管扩展程序的 GitHub 网址。
简化分发：共享您的作品就像共享单个 Git 代码库网址一样简单。无需再传递各个文件和配置代码段。
版本控制和依赖项管理：由于扩展程序通常托管在 Git 代码库中，因此您可以免费获得版本控制功能。有 gemini extensions update command 种方法可将扩展程序更新到最新版本。
可发现性和生态系统：扩展程序是丰富且开放的生态系统的基础，与 VS Code 或 Chrome 的应用商店非常相似。扩展程序机制可以为未来的市场奠定基础，在该市场中，这些扩展程序可以供用户查看、下载等，真正实现社区风格。

扩展框架的推出清楚地表明，Gemini CLI 正在从强大的独立工具发展成为真正的可扩展平台。

4. 了解扩展程序基础知识

本部分将介绍扩展程序生态系统中面向用户的部分：查找扩展程序和管理扩展程序。

探索扩展程序库

扩展程序库是发现所有官方 Google 构建的扩展程序和第三方扩展程序的中心市场：

在浏览器中打开以下网址：https://geminicli.com/extensions/browse/。
此图库是生态系统的发现引擎。您可以看到来自 GitHub、Redis 和 DynaTrace 等公司的扩展程序，从而了解可用工具的广泛性。
向下滚动，找到 Cloud Run 的扩展程序卡片。
请注意，该卡片提供了说明、作者 (Google) 和一键式 Copy install 命令按钮。这是获取扩展程序安装命令的最简单方法。

Gemini CLI 扩展程序 - 管理命令

gemini extensions 命令是您管理本地扩展程序的入口点。

在终端中运行该命令，即可查看可用命令的列表。

这些命令非常简单（安装/卸载、列出、更新、启用/停用等），我们将在本 Codelab 中使用其中的一些命令。

查看当前状态

在安装任何内容之前，我们先检查一下“全新状态”。

运行 gemini extensions list 命令：
您应该会看到以下输出内容，确认尚未安装任何扩展程序。

No extensions installed.

5. Cloud Run 扩展程序（部署应用）

Gemini CLI 扩展程序库中提供的 Cloud Run 扩展程序是一个 MCP 服务器，可用于将应用部署到 Cloud Run。

扩展程序库中的 Cloud Run 扩展程序卡片如下所示：

我们先点击上图所示的复制安装命令，安装 Cloud Run 扩展程序。然后将该命令粘贴到 Cloud Shell 终端中（该命令应类似于以下内容）：

gemini extensions install https://github.com/GoogleCloudPlatform/cloud-run-mcp

运行上述命令后，系统会要求您进行确认。请继续并批准。然后，Cloud Run 扩展程序应会成功安装。

Installing extension "cloud-run".
**Extensions may introduce unexpected behavior. Ensure you have investigated the extension source and trust the author.**
This extension will run the following MCP servers:
  * cloud-run (local): npx -y @google-cloud/cloud-run-mcp
This extension will append info to your gemini.md context using gemini-extension/GEMINI.md
Do you want to continue? [Y/n]: Y
Extension "cloud-run" installed successfully and enabled.

如果您现在执行 Gemini 扩展程序列表命令，应该会看到已安装的 Cloud Run 扩展程序，如下所示：

✓ cloud-run (1.0.0)
 Path: <HOME_FOLDER>/.gemini/extensions/cloud-run
 Source: https://github.com/GoogleCloudPlatform/cloud-run-mcp (Type: github-release)
 Release tag: v1.5.0
 Enabled (User): true
 Enabled (Workspace): true
 Context files:
  <HOME_FOLDER>/.gemini/extensions/cloud-run/gemini-extension/GEMINI.md
 MCP servers:
  cloud-run

如果您现在启动 Gemini CLI 并执行 /mcp 命令，您将看到以下内容：

现在，我们回到 Cloud Shell，尝试部署应用。为此，我们首先需要有一个简单的应用来部署到 Cloud Run。请按下面给出的步骤操作：

确保您位于我们之前创建的文件夹中，即 gemini-cli-projects。在此文件夹内创建另一个名为 gemini-cloud-run 的文件夹，然后导航至该文件夹。

mkdir gemini-cloud-run

cd gemini-cloud-run

现在，在此文件夹中创建两个文件（app.py 文件和 requirements.txt 文件），其内容如下所示：

app.py

from flask import Flask
app = Flask(__name__)
@app.route('/')
def hello_world():
  return 'Hello from Gemini and Cloud Run!'
if __name__ == "__main__":
  app.run(debug=True, host='0.0.0.0', port=8080)

requirements.txt

Flask
gunicorn

现在，从 gemini-cloud-run 文件夹启动 Gemini CLI，并在终端准备就绪后，输入以下提示：

/deploy --project="PROJECT_ID" --location="PROJECT_LOCATION" --name="SERVICE_NAME"

您需要指定 PROJECT_ID（Google Cloud 项目 ID）、PROJECT_LOCATION 和 SERVICE_NAME。如果您未提供此信息，Cloud Run 命令会调用相应工具来帮助您选择。

在此过程中，它会从我们安装的 Cloud Run MCP 服务器扩展程序中选择合适的工具。例如，您应该会看到类似如下的消息：

请继续并允许使用该工具。

大功告成！现在，Gemini CLI 拥有了所需的所有信息，并且获得了执行工具的权限。现在，它将执行整个部署流水线：构建 Docker 映像、将其推送到 Artifact Registry，以及配置和部署新的 Cloud Run 服务。

片刻之后（实际上是 2-3 分钟），您将看到一条包含服务网址的成功消息。运行示例如下所示：

The Cloud Run service SERVICE_NAME has been deployed from the current folder in project PROJECT_ID.
  You can view the service in the Cloud Console: https://console.cloud.google.com/run/detail/PROJECT_LOCATION/SERVICE_NAME?project=PROJECT_ID
  The service is accessible at: https://SERVICE_NAME-SOME-ID.a.run.app

请继续点击该链接。您应该会看到 Flask 应用正在提供首页：

这展示了 Gemini CLI 扩展程序（在本例中为 Cloud Run）的强大功能，它完全封装了 gcloud CLI 命令的复杂性，并为您处理了所有细节。

您可以随意探索 Cloud Run MCP 服务器中的其他工具。

6. BigQuery 扩展程序（分析大型数据集）

如需学习本教程，您需要：

已启用 BigQuery API 的 Google Cloud 项目。
IAM 权限：
BigQuery User (roles/bigquery.user)

运行此命令以设置 BIGQUERY_PROJECT 环境变量。此项目将执行 BigQuery 作业，但不一定就是您的数据所在的项目（不过它们确实可以是同一个项目）

export BIGQUERY_PROJECT=<YOUR_GCP_PROJECT_ID>

通过以下命令安装 BigQuery 数据分析扩展程序。请授予其安装权限。成功安装后，您的设置中将安装 2 个扩展程序：cloud-run 和 bigquery-data-analytics。

gemini extensions install https://github.com/gemini-cli-extensions/bigquery-data-analytics

我们通过以下命令再次启动 Gemini CLI：

gemini

Gemini CLI 应在终端中启动：

应在 Gemini CLI 终端中输入以下命令。

输入以下斜杠命令，确认 BigQuery 扩展程序已安装并可正常使用：

/extensions list

您应该也会看到列出的 bigquery-data-analytics 扩展程序。

运行以下命令以查看可用的工具

/mcp list

我们来针对 BigQuery 公共数据集（即 Look 电子商务数据集）提出一个基本分析问题。此数据集包含虚构服装电子商务网站的客户、商品和订单数据。在 Gemini CLI 中输入以下提示：

Look at BigQuery's the look ecommerce public dataset. Identify the top 5 products that had the most orders.

Gemini CLI 会询问您是否愿意允许执行 BigQuery 工具。如需继续，请选择第三个选项：Yes, always allow all tools from server "bigquery_data_analytics"。
在后台，Gemini 将生成相应的 SQL 查询，调用 execute_sql 工具，并返回自然语言回答以及您的数据：

现在，我们将让 Gemini 根据历史数据预测商品的退货率。对于此命令，Gemini CLI 不应尝试生成一些详细的 SQL 来创建此预测，而应从 MCP 服务器调用 forecast 工具，该工具将在后台使用 BigQuery 的 AI.Forecast：

Forecast what the return rate will be next month.

您应该会看到如下所示的响应：

7. Google Workspace 扩展服务（日常工作流程）

Google Workspace 扩展程序以 MCP 服务器的形式提供，可与 Google Workspace 应用（如 Google 文档、Google Chat、Google 日历、Google 云端硬盘等）集成。此扩展程序的一项关键功能是其本地执行模型。MCP 服务器在用户机器上运行，而不是在云端运行。它使用用户自己的 OAuth 凭据直接与 Google API 通信。

扩展服务库中的 Google Workspace 扩展服务卡片如下所示：

如需安装 Google Workspace 扩展程序，请点击复制按钮，然后将该命令粘贴到 Cloud Shell 终端中（该命令应类似于以下内容）：

gemini extensions install https://github.com/gemini-cli-extensions/workspace

运行上述命令后，系统会要求您进行确认。请继续并批准。然后，Google Workspace 扩展程序应该会成功安装。

如果您现在执行 gemini extensions list 命令，应该会看到已安装的 Google Workspace 扩展服务，如下所示（或类似输出）：

✓ google-workspace (v0.0.3)
 ID: 40be7ad1253320a38aba2f107f21349b41a458416fd4616550c832ff1d3b7dce
 name: a1f88ed96997755f9cd591bb26d8e1087e5969979caabe19fcde7b3544ea1a1e
 Path: /Users/romin/.gemini/extensions/google-workspace
 Source: https://github.com/gemini-cli-extensions/workspace (Type: github-release)
 Release tag: v0.0.3
 Enabled (User): true
 Enabled (Workspace): true
 Context files:
  /Users/romin/.gemini/extensions/google-workspace/WORKSPACE-Context.md
 MCP servers:
  google-workspace

如果您现在启动 Gemini CLI，则必须完成此扩展程序设置过程中最重要的一步，即身份验证。与可能使用静态 API 密钥的简单脚本不同，Workspace 扩展程序会代表用户充当授权代理，因此需要访问敏感范围（云端硬盘、Gmail、日历）。

扩展程序会启动 OAuth 2.0 流程。选择您的账号，然后 Google 会显示扩展程序请求的权限（范围）列表。这些指标非常广泛，包括以下关键指标：

完成此 OAuth 2.0 流程后，您就万事俱备了。

您可以启动 Gemini，然后使用 /mcp list 命令检查扩展程序是否已成功安装。这应表明扩展程序已安装，并且命令已作为 MCP 工具公开。此界面截图如下所示：

Workspace 工具

该扩展程序将特定的 Google Workspace API 端点映射到 LLM 可调用的“工具”。这些工具并非随意选择，而是经过精心挑选，可涵盖知识工作的主要模式：

文件管理（云端硬盘）
文档撰写（文档）
时间管理（日历）
通讯 (Gmail/Chat)

下面我们来看一些示例，您可以根据可用的不同工具尝试这些示例。若要测试这些工具，您需要在关联的 Gmail 账号中拥有一些电子邮件、日历安排、Google 云端硬盘中的文件等。

云端硬盘和文档：知识库

如果您在 Google 云端硬盘中有一个设计文档或有趣的文档，可以尝试使用以下示例提示搜索并总结该文档：

Search for <DOC_NAME> in Google Drive

找到文档后，Gemini CLI 会列出该文档及其文档 ID。然后，您可以要求它总结文档，如下所示：

Summarize <DOC_ID> for me

我们来做一项通常在需要某些信息时会做的活动。我们会搜索网页，然后将相关信息放入 Google 文档中。

不妨考虑一下这样的提示：

Lookup information on The Richat Structure (Eye of Africa) and create a 1-pager document for me with relevant information about

此提示首先会导致 Gemini CLI 执行 Google 搜索工具以从网络检索信息，一旦获取信息，它就会将这些信息合成到我们请求的单页文档中，并在 Google 云端硬盘中创建一个新的 Google 文档。

请访问您账号的 Google 云端硬盘，然后查看其创建的文档。以下文档来自一次示例运行。

日历

使用扩展程序中提供的日历工具，让其充当管理时间的行政助理。

您可以选择使用 /calendar:get-schedule，也可以只使用自然语言查询来获取信息。

我们先从最基本的操作开始，了解一下您今天的日程安排。输入以下提示，并注意它访问了您今天的日历，并给出了您今天设置的日历活动（请确保您在日历中设置了今天的几个活动）。

What does my schedule look like for today?

然后，您可以尝试以下操作：

向 Gemini 询问您当天的日程安排，如果您对它提供的时段感到满意，甚至可以要求它为当天创建活动。试试看吧！

通讯：Gmail 和 Chat

您可以使用 /gmail:search 工具搜索电子邮件，并允许从电子邮件会话中检索上下文。

例如，如果您每周都会收到特定电子邮件或来自某个团队的电子邮件，请尝试通过如下提示搜索这些电子邮件：

/gmail:search "Project Phoenix updates"

然后，您可以通过如下提示让 Gemini 总结特定邮件，并将其发送到 Google Chat 聊天室：

Send a chat message to <SPACE_NAME> and highlight the key points from the email.

以上只是一些示例，考虑以下更复杂的工作流：

Find the 'Project Phoenix Design Doc' in Drive,
read the section on API authentication,
and help me scaffold the middleware based on those specs.

Send a message to the ‘Core Eng' chat space letting them know the deployment is starting now.

使用此类扩展程序的最佳方式是使用您自己的文件、日历、Gmail 等内容来试用它们，并设计出您想要自动化的流程，或者找到一种更好的方式来避免上下文切换并节省时间。

8. 深入探索

至此，我们的 Codelab 已完成。在此 Codelab 中，我们介绍了 Gemini CLI 扩展程序是什么、使用它们的基本命令，并探索了 cloud-run 和 bigquery-data-analytics 扩展程序。

访问 Gemini 扩展程序库 (https://geminicli.com/extensions/)，探索目前可供您使用的扩展程序（撰写本文时，已有 100 多个）。每个扩展程序卡片都包含信息、扩展程序的类型（MCP、上下文等）、GitHub 代码库链接以及用于在环境中安装扩展程序的命令。

9. 恭喜

恭喜！您已成功了解 Gemini CLI 扩展程序以及如何安装和使用各种 Gemini CLI 扩展程序。