1. 简介
在此 Codelab 中,您将了解 Gemini CLI,这是一个开源 AI 智能体,可将 Gemini 的强大功能直接引入您的终端。
Gemini CLI 项目是开源的,您可以在此处查看公开路线图。
学习内容
- 安装和配置 Gemini CLI
- 探索 Gemini CLI 中的工具、内置命令和配置 MCP 服务器
- 通过
GEMINI.md
文件自定义 Gemini CLI - 探索 Gemini CLI 的一些应用场景
所需条件
此 Codelab 完全可以在 Google Cloud Shell 中运行,而 Google Cloud Shell 预安装了 Gemini CLI。
或者,如果您更喜欢在自己的机器上操作,可以参阅相关部分,在本地安装 Gemini CLI。
您需要具备以下条件:
- Chrome 网络浏览器
- Gmail 账号
本 Codelab 专为各种水平(包括新手)的用户和开发者而设计。Codelab 中的应用场景已分为开发者任务和非开发者任务。这些开发者用例展示了如何使用 Gemini CLI 编写代码,以及如何使用 GitHub 代码库执行常见的开发任务,例如代码说明/理解、生成文档、修复问题等。建议您完成此 Codelab 中的这些使用情形。最后还有一个可选部分,其中介绍了几个不以开发者为中心的日常任务。
2. 准备工作
创建项目
- 在 Google Cloud Console 的项目选择器页面上,选择或创建一个 Google Cloud 项目。
- 确保您的 Cloud 项目已启用结算功能。了解如何检查项目是否已启用结算功能。
- 您将使用 Cloud Shell,这是一个在 Google Cloud 中运行的命令行环境,它预加载了 bq。点击 Google Cloud 控制台顶部的“激活 Cloud Shell”。
- 连接到 Cloud Shell 后,您可以使用以下命令检查自己是否已通过身份验证,以及项目是否已设置为您的项目 ID:
gcloud auth list
- 在 Cloud Shell 中运行以下命令,以确认 gcloud 命令了解您的项目。
gcloud config list project
- 如果项目未设置,请使用以下命令进行设置:
gcloud config set project <YOUR_PROJECT_ID>
3. 安装
在进行设置并运行 Gemini CLI 之前,我们先创建一个文件夹,您将使用该文件夹作为在其中创建的所有项目的根文件夹。这是 Gemini CLI 的初始工作目录,不过它也会引用系统上的其他一些文件夹,您稍后会根据需要用到这些文件夹。
继续操作,创建一个示例文件夹 (gemini-cli-projects
),然后通过以下命令导航到该文件夹。如果您希望使用其他文件夹名称,请使用。
mkdir gemini-cli-projects
让我们前往该文件夹:
cd gemini-cli-projects
您可以通过 gemini 命令直接启动 Gemini CLI。
请直接前往下一部分(通过 settings.json 进行 Gemini CLI 配置)。
如果您想在本地安装 Gemini CLI,请按照以下说明操作。
第一步是在您的机器上安装 Node 20 及更高版本。完成此操作后,您可以通过以下任一方法安装并运行 Gemini CLI:
- 您可以先在系统上全局安装 Gemini CLI。您可能需要拥有管理员权限才能执行此步骤。
# option 1: install Gemini CLI
npm install -g @google/gemini-cli
# .. and then run
gemini
- 使用以下命令运行该脚本:
# option 2: run without installing Gemini CLI
npx https://github.com/google-gemini/gemini-cli
您可以运行以下命令来确认 CLI 是否已安装:
gemini --version
假设您已通过上述任一方法启动 Gemini CLI,您应该会看到以下屏幕,其中会询问您是否选择主题。请选择您喜欢的背景:
选择该选项后,系统会要求您选择身份验证方法。建议您在此实验中使用个人 Google 账号,而不是非 Google 账号或 Google Workspace 相关账号。通过该免费许可,您可以使用 Gemini 2.5 Pro 模型及其 100 万个 token 的上下文窗口。免费层级允许每分钟最多 60 次模型请求,每天最多 1,000 次,且无需付费。
如果您当前 Google 账号的免费配额已达到上限,可以选择使用 Gemini API 密钥,甚至可以使用 Google Cloud Vertex AI,但您需要拥有项目 ID 和相应项目的位置名称。如果您计划使用其他身份验证方法,请参阅文档的身份验证部分。
点击“输入”即可。系统随即会在浏览器中打开 Google 身份验证页面。继续使用您的 Google 账号进行身份验证,接受相关条款,成功通过身份验证后,您会发现 Gemini CLI 已准备就绪,等待您输入命令。以下是示例屏幕截图:
4. 通过 settings.json 配置 Gemini CLI
如果您选择使用 Cloud Shell 运行 Gemini,系统会为您选择并配置 Gemini CLI 的默认主题和身份验证方法。
如果您在自己的机器上安装了 Gemini CLI 并首次启动它,则需要选择主题,然后选择身份验证方法。
现在,在后续运行 Gemini CLI 时,系统不会再要求您选择主题和身份验证方法。这意味着,它会持久保存在某个位置,并且它使用的文件名为 settings.json
,这是自定义 Gemini CLI 的方式。
设置按以下优先顺序应用(Cloud Shell 仅提供用户设置):
- 系统:
/etc/gemini-cli/settings.json
(适用于所有用户,会覆盖用户和工作区设置)。 - 工作区:
.gemini/settings.json
(覆盖用户设置)。 - 用户:
~/.gemini/settings.json
。
Windows 用户:%USERPROFILE%.gemini\settings.json(通常会展开为 C:\Users<YourUsername>.gemini\settings.json)
系统:%ProgramData%\gemini-cli\settings.json(通常会扩展为 C:\ProgramData\gemini-cli\settings.json)
Mac 用户:~/.gemini/settings.json(展开后为 /Users/<YourUsername>/.gemini/settings.json)
系统:/etc/gemini-cli/settings.json
如果您还记得,在选择主题时,您曾选择将设置保存在“用户设置”中。因此,请访问 ~/.gemini folder
,您会看到 settings.json
文件。
我的 settings.json
文件如下所示。如果您选择了其他主题,则会在此处看到相应名称。
{
"theme": "Default",
"selectedAuthType": "oauth-personal" or "cloud-shell"
}
5. 我们与 Gemini CLI 的首次互动
我们先来开始使用 Gemini CLI,然后输入您的第一个查询,如下所示:
Give me a famous quote on Artificial Intelligence and who said that?
预期响应如下所示:
您会注意到,我们的查询导致 GoogleSearch
工具(Gemini CLI 中的内置工具)被调用。换句话说,您已经使用过 Gemini CLI 的一项强大的内置工具,即 GoogleSearch
,该工具可根据从网络获取的信息来生成回答。您将在下一部分中详细了解工具。
如需快速了解 Gemini CLI 及其支持的各种命令,您可以输入 /help
(正斜杠),然后您会看到各种命令和键盘快捷键,如下所示:
我们暂时退出 Gemini CLI。您可以通过 /quit
命令执行此操作,也可以在交互式 Gemini CLI 终端会话中执行两次 Ctrl-C
。
6. Gemini CLI - 命令参数
启动 Gemini CLI 时,您可以提供一些命令行参数。如需获取完整的选项列表,您可以使用 --help
,如下所示。
gemini --help
这应会显示所有可用的选项。建议您查看此处的文档。
下面我们来看几个示例。第一种方法是将 Gemini CLI 配置为使用 Pro 或 Flash 模型。目前,在撰写本实验时,仅支持这两种模型。默认情况下,系统会使用 Gemini 2.5 Pro 模型,但如果您想使用 Flash 模型,可以在启动 Gemini CLI 时通过 -m
参数来指定,如下所示:
gemini -m "gemini-2.5-flash"
您会注意到,如果您以这种方式启动,则可以检查 Gemini CLI 终端右下角的模型,如下所示:
非互动模式
一个有趣的选择是在非交互模式下运行 Gemini CLI。这意味着,您可以直接向其提供提示,它会立即做出回应,而不会打开 Gemini CLI 交互式终端。如果您计划以自动方式在脚本或任何其他自动化流程中使用 Gemini CLI,这将非常有用。您可以使用 -p 参数向 Gemini CLI 提供提示,如下所示:
gemini -p "What is the gcloud command to deploy to Cloud Run"
请注意,您无法通过追问来继续对话。在此模式下,您也无法授权工具(包括 WriteFile)或运行 shell 命令。
7. Gemini CLI - 内置工具
Gemini CLI 随附一组内置工具,工具文档中指出:“Gemini 模型使用这些工具与本地环境互动、访问信息和执行操作。这些工具增强了 CLI 的功能,使其不仅能生成文本,还能协助完成各种任务。
如需获取当前内置工具的列表,请按如下所示调用 /tools
命令:
您应该立即想到的一点是,Gemini CLI 是否可以在需要时直接调用这些工具?对于可能涉及写入本地系统、从外部系统读取数据、访问外部网络等敏感操作,默认答案为否。
虽然在启动 CLI 时有 --yolomode
可用(通常不建议使用),但您会发现 Gemini CLI 会提示您授予运行其所选工具的权限。您可以拒绝授予权限,也可以允许应用运行一次或授予应用始终运行的权限。您现在和将来都应完全掌控一切。
我们来使用一个提示,让 Gemini CLI 选择一个内置工具来执行,这样您就可以很好地了解整个过程的运作方式。
假设您想获取全球最新的财经新闻,并将其保存到您启动 Gemini CLI 的本地工作目录中的文件中。使用以下提示:
Search for the latest headlines today in the world of finance and save them in a file named finance-news-today.txt
不妨想象一下它应该做什么。理想情况下,它需要外出进行 Google 搜索,从一些可以提供财经新闻的相关信息来源获取新闻。然后,它需要创建一个名为 finance-news-today.txt
的文件(本地系统上的写入操作,需要您的许可),其中包含相应内容。
让我们看看会发生什么情况(您应该在自己的机器上执行相同的操作)。
首先,它会调用 GoogleSearch
工具来搜索网络。
搜索完成后,系统会检索数据,如下所示:
完成此操作后,系统即可将此内容写入文件,并将使用 WriteFile
工具,但由于这是一项敏感操作(写入),系统会征求您的许可。您可以决定权限类型,例如“允许一次”“始终允许”等。现在,请选择“允许一次”。
然后,系统会将信息写入文件,并显示以下成功消息:
如何检查文件是否已写入?您可以使用 @file
让它朗读内容。当您输入 @
时,系统会显示当前文件夹中的文件列表,并显示刚刚创建的文件。选择该选项,然后提交提示。我的提示如下所示:
read the contents of @finance-news-today.txt
这样一来,系统就会调用所需的工具(ReadManyFiles、ReadFile),并显示如下所示的内容:
8. Gemini CLI - Shell 模式
现在是学习如何直接在 Gemini CLI 中使用 Shell 的好时机。您可以在消息框中按 !
进入 shell 模式。这会切换到 Shell 模式。您可以再次按 !
或按 ESC
键返回。
在 shell 模式下,您会在提示符的开头看到 !
,如下所示:
您可以直接使用 pwd
和 ls
等标准命令进行检查,如下所示。请注意,这些命令假定您使用的是 Linux 类型操作系统。如果您使用的是其他操作系统 (Windows),请使用等效的命令,例如(cd
、dir
和 type
)。请注意,这些调用的输出会包含在模型的上下文窗口中。
您现在可以通过 cat
命令打印文件内容。
练习:下面是一项简短的练习,您可以尝试一下。选择您所需的 RSS Feed。向 Gemini CLI 提供提示,以获取 RSS Feed 的内容,并以特定方式为您设置结果格式。这是在一天开始时自动执行某项操作的好方法。您甚至可以要求 Gemini CLI 确定特定领域(例如 Google Cloud Platform 版本说明)是否有 RSS Feed。
以下是提示示例:
Get the latest release notes for Google Cloud from its RSS Feed and display the key points in a well-formatted list.
此提示应首先调用 GoogleSearch 工具来查找 Google Cloud Platform RSS Feed,然后使用 WebFetch 工具获取 RSS Feed 的内容并显示这些内容。
9. 配置 Model Context Protocol (MCP) 服务器
MCP 服务器是一种通过 Model Context Protocol 向 Gemini CLI 公开工具和资源的应用,使 Gemini CLI 能够与外部系统和数据源互动。MCP 服务器充当 Gemini 模型与本地环境或其他服务(例如 API)之间的桥梁。
MCP 服务器使 Gemini CLI 能够发现和执行工具,从而扩展 Gemini CLI 的功能,使其能够执行超出其内置功能的操作,例如与数据库、API、自定义脚本或专用工作流进行交互。
Gemini CLI 支持配置 MCP 服务器,以便发现和使用自定义工具。如果您已启动 Gemini CLI,则可以通过 /mcp
命令查看已配置的 MCP 服务器,如下所示:
如果您尚未配置任何 MCP 服务器,系统会启动 Gemini CLI 的 MCP 服务器文档。
您可以在 ~/.gemini/settings.json
文件或项目的根目录中全局配置 MCP 服务器。创建或打开 .gemini/settings.json
文件。在文件中,您需要添加 mcpServers
配置块,如下所示:
"mcpServers": {
"server_name_1": {},
"server_name_2": {},
"server_name_n": {}
}
每项服务器配置都支持以下属性(参考文档):
必需(以下任一)
- 命令(字符串):用于 Stdio 传输的可执行文件的路径
- url(字符串):SSE 端点网址(例如,"http://localhost:8080/sse")
- httpUrl(字符串):HTTP 流式传输端点网址
可选
- args (string[]):用于 Stdio 传输的命令行实参
- headers(对象):使用 url 或 httpUrl 时的自定义 HTTP 标头
- env(对象):服务器进程的环境变量。值可以使用 $VAR_NAME 或 ${VAR_NAME} 语法引用环境变量
- cwd(字符串):Stdio 传输的工作目录
- 超时(数字):请求超时时间(以毫秒为单位)(默认值:600,000 毫秒 = 10 分钟)
- trust(布尔值):如果为 true,则绕过此服务器的所有工具调用确认(默认值:false)
- includeTools (string[]):要从此 MCP 服务器中包含的工具名称列表。指定后,只有此处列出的工具可从此服务器获取(白名单行为)。如果未指定,则默认启用服务器中的所有工具。
- excludeTools (string[]):要从此 MCP 服务器中排除的工具名称列表。即使服务器公开了此处列出的工具,模型也无法使用这些工具。注意:excludeTools 的优先级高于 includeTools - 如果某个工具同时位于这两个列表中,则会被排除。
接下来,我们来配置一个您在使用 GitHub 时可能需要的主要 MCP 服务器。您可能会有疑问:如果您的系统上已设置了 Git 和其他相关工具,是否还需要 GitHub MCP 服务器?
Gemini CLI 将调用您系统中的 Git 工具,您也可以指示 Gemini CLI 使用该工具。因此,请务必注意,Gemini CLI 会将您的自然语言查询转换为您可能在系统上使用的等效工具,并且您可能需要在提示中明确声明这一点。
如果您已在系统上设置以下内容,则可能不需要下一部分来设置 GitHub MCP 服务器:
- Git 工具(这意味着您可以在系统上执行
git init
、git add
等命令) gh
:这是命令行中的 GitHub。它将拉取请求、问题和其他 GitHub 概念引入终端,让您可以在使用 Git 和代码的同时使用这些功能。从此处安装该工具,并通过一些命令验证其设置,尤其是从您的机器向 GitHub 进行身份验证。
如果您仍想试用 GitHub MCP 服务器,请参阅下一部分,也可以跳过该部分。
GitHub MCP 服务器
GitHub 官方 MCP 服务器提供了有关其公开的工具以及如何配置这些工具的充足文档。您可以选择在本地或远程运行 Gemini CLI,因为 Gemini CLI 也支持远程 MCP 服务器。
本教程演示了 GitHub 中的远程 MCP 服务器选项。为此,您需要先拥有 GitHub 的个人访问令牌 (PAT)。
获得该对象后,您需要在 settings.json
文件中添加 MCP 服务器对象。我系统上的完整 settings.json 文件如下所示。您可能还有其他设置,但 mcpServers
对象应如下所示:
{
"theme": "Default",
"selectedAuthType": "oauth-personal",
"mcpServers": {
"github": {
"httpUrl": "https://api.githubcopilot.com/mcp/",
"headers": {
"Authorization": "GITHUB_PAT"
},
"timeout": 5000
}
}
}
使用 GitHub MCP 服务器配置更新 settings.json
后,您可以再次启动 Gemini CLI 或运行 /mcp refresh
命令。以下屏幕截图突出显示了在我的机器上配置的 GitHub MCP 服务器,以及 Gemini CLI 现在可用于处理 MCP 的各种工具。
我们先从一个提示开始,该提示将调用 GitHub MCP 服务器中的一个工具。输入以下提示:
请注意,它会从 GitHub MCP 服务器中选择正确的工具,但与其他内置工具一样,这也需要您提供明确的权限来调用该工具。继续操作,看看会得到什么输出。
您现在应该使用您的某个 GitHub 项目。使用自然语言提出查询,例如:
- 向我描述 <repo-name>?
- 在本地机器上克隆 <repo-name>。
- 描述 @<file-name> 或 @<directory-name>/
- 此代码库包含哪些不同的组件?
- 我已经进行了必要的更改。您可以将更改推送到 GitHub,并使用 GitHub MCP 服务器工具来完成此操作。
在后面的实验中,您将找到有关如何详细使用 GitHub MCP 服务器的练习。
Context7 MCP 服务器
Context7 为 LLM 和 AI 代码编辑器提供最新文档。如果您希望使用所选框架的最新文档为 LLM 提供上下文,那么 Context7 MCP 服务器是一个不错的配置选择。
确保您的库已列在 Context7 首页上。
以下是您需要在 settings.json
文件中添加的 MCP 服务器。
"context7": {
"httpUrl": "https://mcp.context7.com/mcp"
}
配置 MCP 服务器并成功加载 Gemini CLI 后,您应该能够看到 Context7 工具,如下所示:
现在,您可以在提示中明确要求 Gemini CLI 在使用特定 XYZ 框架生成应用或代码段时使用 Context7
获取最新文档。
以下是一个提示示例,其中我希望使用 Google 的智能体开发套件 (ADK) 编写智能体。我在提示中指定通过 Context7 MCP 服务器查找相关文档。
I am working on coding an Agent using the Agent Development Kit (ADK) from Google. I would like to know how to create the LLMAgent in Python. Use Context7 for the latest documentation on ADK and specifically use /google/adk-python, /google/adk-docs and adk.wiki
以下是收到的输出:
Google 幻灯片 MCP 服务器
位于 https://github.com/matteoantoci/google-slides-mcp 的 GitHub 项目提供了一个用于与 Google Slides API 交互的 MCP 服务器。借助此 API,您可以以程序化的方式创建、读取和修改 Google 幻灯片演示文稿。
项目中提供了配置 MCP 服务器的步骤。您需要拥有一个 Node.js 环境,在其中构建服务器、配置 Google Cloud 项目和 OAuth 2.0 令牌,然后在 settings.json 文件中配置 MCP 服务器。
设置完成后,您可以运行以下提示:
- 从“web_url”中提取最新信息,将其总结为要点,然后创建名为“my_presentation”的演示文稿。
快来试试吧!
更多 MCP 服务器
下面列出了您可能感兴趣的其他 MCP 服务器:
- Firebase MCP 服务器
- Google Gen AI Media Services(Imagen、Veo、Lyria)
- 适用于数据库的 MCP 工具箱(适用于 Firestore、BigQuery、Google Cloud 数据库)
- Google Workspace MCP 服务器(适用于 Google 文档、表格、日历、Gmail)
有关设置上述 MCP 服务器的说明已发布在这篇博文中。
10. 使用 GEMINI.md 自定义 Gemini CLI
如果您注意到自己目前使用 Gemini CLI 的情况,就会发现我们只是给出提示,然后期待 Gemini CLI 执行该提示,但有时结果并不符合我们的预期。在某些提示中,您明确说明了要执行的操作,并将这些说明包含在提示中。
根据您指示 Gemini CLI 执行的操作以及您获得的结果,这可能没问题。但在许多情况下,您需要确保其遵循规则。这些规则可能包括要使用的特定编程语言或框架。也可能是特定工具。可能是编码风格。这不仅是生成的问题,您可能还希望 Gemini CLI 严格处于所谓的“规划”模式,并希望它仅呈现计划,而不生成任何代码或修改系统上的文件。
输入 GEMINI.md
。这是上下文文件(默认为 GEMINI.md
,但可通过 settings.json
文件中的 contextFileName
属性进行配置),对于配置提供给 Gemini 模型的指令上下文(也称为“记忆”)至关重要。借助此文件,您可以向 AI 提供项目专属的指令、编码规范或任何相关背景信息,使其响应更贴合您的需求、更加准确。
GEMINI.md
文件采用 Markdown 格式,并以分层方式加载,该文件由多个位置的内容组合而成。
加载顺序为:
- 全局上下文:**
~/.gemini/GEMINI.md
**(适用于所有项目的说明)。 - 项目/祖先上下文:CLI 会从当前目录开始向上搜索,直到项目根目录,以查找
GEMINI.md
文件。 - 子目录上下文:CLI 还会扫描子目录中的
GEMINI.md
文件,从而实现组件特定的指令。
您可以使用 /memory show
查看发送给模型的最终合并上下文。
GEMINI.md
是什么样子的?我们根据官方文档制作了一个:
# Project: My Awesome TypeScript Library
## General Instructions:
- When generating new TypeScript code, please follow the existing coding style.
- Ensure all new functions and classes have JSDoc comments.
- Prefer functional programming paradigms where appropriate.
- All code should be compatible with TypeScript 5.0 and Node.js 20+.
## Coding Style:
- Use 2 spaces for indentation.
- Interface names should be prefixed with `I` (e.g., `IUserService`).
- Private class members should be prefixed with an underscore (`_`).
- Always use strict equality (`===` and `!==`).
## Specific Component: `src/api/client.ts`
- This file handles all outbound API requests.
- When adding new API call functions, ensure they include robust error handling and logging.
- Use the existing `fetchWithRetry` utility for all GET requests.
## Regarding Dependencies:
- Avoid introducing new external dependencies unless absolutely necessary.
- If a new dependency is required, please state the reason.
您会发现,它不仅提供了一些常规说明,还针对编码风格、依赖项管理等提供了非常具体的说明。虽然这是一个适用于 TypeScript 项目的示例 GEMINI.md
文件,但您可以根据自己的编程语言、框架、编码风格和其他偏好设置来编写自己的文件。
您可以尝试使用自定义 GEMINI.md
文件。此示例来自已发布的 Gist,其中展示了如何在仅限规划模式下使用 Gemini CLI。该文件内容如下:
# Gemini CLI Plan Mode
You are Gemini CLI, an expert AI assistant operating in a special 'Plan Mode'. Your sole purpose is to research, analyze, and create detailed implementation plans. You must operate in a strict read-only capacity.
Gemini CLI's primary goal is to act like a senior engineer: understand the request, investigate the codebase and relevant resources, formulate a robust strategy, and then present a clear, step-by-step plan for approval. You are forbidden from making any modifications. You are also forbidden from implementing the plan.
## Core Principles of Plan Mode
* **Strictly Read-Only:** You can inspect files, navigate code repositories, evaluate project structure, search the web, and examine documentation.
* **Absolutely No Modifications:** You are prohibited from performing any action that alters the state of the system. This includes:
* Editing, creating, or deleting files.
* Running shell commands that make changes (e.g., `git commit`, `npm install`, `mkdir`).
* Altering system configurations or installing packages.
## Steps
1. **Acknowledge and Analyze:** Confirm you are in Plan Mode. Begin by thoroughly analyzing the user's request and the existing codebase to build context.
2. **Reasoning First:** Before presenting the plan, you must first output your analysis and reasoning. Explain what you've learned from your investigation (e.g., "I've inspected the following files...", "The current architecture uses...", "Based on the documentation for [library], the best approach is..."). This reasoning section must come **before** the final plan.
3. **Create the Plan:** Formulate a detailed, step-by-step implementation plan. Each step should be a clear, actionable instruction.
4. **Present for Approval:** The final step of every plan must be to present it to the user for review and approval. Do not proceed with the plan until you have received approval.
## Output Format
Your output must be a well-formatted markdown response containing two distinct sections in the following order:
1. **Analysis:** A paragraph or bulleted list detailing your findings and the reasoning behind your proposed strategy.
2. **Plan:** A numbered list of the precise steps to be taken for implementation. The final step must always be presenting the plan for approval.
NOTE: If in plan mode, do not implement the plan. You are only allowed to plan. Confirmation comes from a user message.
将上述内容保存到名为 GEMINI.md 的文件中,然后将该文件保存到 ~/.gemini/GEMINI.md
中。此文件夹与您之前创建 settings.json 文件的文件夹相同。您还可以将 GEMINI.md
文件保留在 <current project folder>/.gemini
文件夹中,甚至可以在子目录中放置多个 GEMINI.md
文件(如果您有不同的说明)。
提供提示以生成应用,并查看应用的响应。
以下是另一个 GEMINI.md
文件(Gemini 解释模式),您可以先研究一下,然后根据自己的需求重新调整用途并使用它。重点在于 GEMINI CLI 是一款交互式指南,可通过对话式发现过程帮助用户了解复杂的代码库。
GEMINI.md
文件是让 Gemini CLI 遵循您的偏好的关键。建议您查看“实用 Gemini CLI”这一实用系列,深入了解此领域,了解如何为项目自动生成该文件,甚至自定义系统提示等。
另请注意,您还可以在与 Gemini CLI 互动时构建 GEMINI.md
文件。在任何时候,您都可以使用 /memory add <some instruction/rule> 命令,Gemini CLI 会将其附加到 GEMINI.md
文件中。您甚至可以使用自然语言,通过“记住 <某些指令/规则>”或“添加到记忆 <某些指令/规则>”等提示,让 Gemini CLI 将信息添加到其记忆中,即 GEMINI.md
。
11. Gemini CLI - 自定义斜杠命令
您刚刚了解了如何自定义 GEMINI.md
以创建方案模式。上一部分还提供了指向“说明”模式的链接。
如果您想同时配置这两种模式,并指示 Gemini CLI 通过 /plan
或 /explain
斜杠命令进入其中任一模式,该怎么做?这正是 Gemini CLI 自定义斜杠命令的用途。
正如文档中所述,“借助自定义命令,您可以在 Gemini CLI 中将自己喜爱或最常用的提示保存为个人快捷方式并重复使用。您可以创建特定于单个项目的命令,也可以创建可在所有项目中全局使用的命令,从而简化工作流程并确保一致性。
让我们创建两个自定义斜杠命令:/plan
和 /explain
。
下一步是了解 Gemini CLI 从何处获取自定义命令。根据文档,它会从两个位置发现命令,并按特定顺序加载:
- 用户命令(全局):位于
~/.gemini/commands/
中。这些命令可在您处理的任何项目中执行。 - 项目命令(本地):位于
<your-project-root>/.gemini/commands/
中。这些命令特定于当前项目,可以签入版本控制以与团队共享。
让我们从您启动 Gemini CLI 的当前项目文件夹中进行选择。因此,此文件夹将为 <your-project-root>/.gemini/commands/
文件夹。继续操作,创建文件夹结构。
我们需要在此文件夹中创建哪些内容?我们需要两个 TOML 文件(plan.toml
和 explain.toml
)。如果您想详细了解命名空间和命名惯例,请点击此处。
每个 TOML 文件都需要包含两个字段:description
和 prompt
。请确保说明简明扼要,因为该说明将显示在 Gemini CLI 中的命令旁边。以下 TOML 文件示例摘自官方的“自定义斜杠命令”博文。
下面显示了一个 plan.toml 文件示例。请注意,提示中包含一个特殊占位符 {{args}}
,CLI 会将该占位符替换为用户在命令名称后输入的所有文本。
description="Investigates and creates a strategic plan to accomplish a task."
prompt = """
Your primary role is that of a strategist, not an implementer.
Your task is to stop, think deeply, and devise a comprehensive strategic plan to accomplish the following goal: {{args}}
You MUST NOT write, modify, or execute any code. Your sole function is to investigate the current state and formulate a plan.
Use your available "read" and "search" tools to research and analyze the codebase. Gather all necessary context before presenting your strategy.
Present your strategic plan in markdown. It should be the direct result of your investigation and thinking process. Structure your response with the following sections:
1. **Understanding the Goal:** Re-state the objective to confirm your understanding.
2. **Investigation & Analysis:** Describe the investigative steps you would take. What files would you need to read? What would you search for? What critical questions need to be answered before any work begins?
3. **Proposed Strategic Approach:** Outline the high-level strategy. Break the approach down into logical phases and describe the work that should happen in each.
4. **Verification Strategy:** Explain how the success of this plan would be measured. What should be tested to ensure the goal is met without introducing regressions?
5. **Anticipated Challenges & Considerations:** Based on your analysis, what potential risks, dependencies, or trade-offs do you foresee?
Your final output should be ONLY this strategic plan.
"""
尝试创建 explain.toml 文件。您可以参考 Gemini 的“说明”模式来选择一些内容。
重启 Gemini CLI。现在,您会发现它有一个斜杠命令 (/plan
),如下所示:
12. 可尝试的应用场景
Gemini CLI 可应用于各种用例,无论是开发者还是非开发者,都可以使用。下面列出了几种情形,您可以根据自己的兴趣尝试其中任何一种或全部情形。
在每种情况下,系统都会提供提示。您可以在启动 Gemini CLI 时通过 -p
参数在 Gemini CLI 交互模式或非交互模式下免费试用此功能。
使用 Gemini CLI 进行氛围编程
我们来使用 Gemini CLI 为应用添加振动效果。在此任务中,您将要求 Gemini CLI 生成应用,然后将初始版本推送到 GitHub 代码库。
前提条件
如需执行本部分中的任务,您需要满足以下前提条件:
- Git
- 使用 GitHub MCP 服务器的 Gemini CLI(我们之前已完成此操作),或者如果您已设置
gh
(GitHub CLI 工具),也可以。 - 熟悉 Git 基础知识,并具备一定的编程知识
我们将假定您已在所选的特定文件夹中启动 Gemini CLI。确保 MCP 服务器已成功启动,尤其是 GitHub MCP 服务器。
从初始提示开始。您可以根据需要随意修改。请注意,在与 Gemini CLI 的整个会话期间,它会要求您授予创建文件等权限。请授予所需的权限。
在此任务中,我们不希望 Gemini CLI 运行或测试应用,因为我们希望有更多控制权。但具体如何操作完全取决于您。
Generate a website for a 1-day event filled with technical talks. There are going to be 6 talks in a single track of 1 hour each. Each talk has the following information: title, 1 or maximum of 2 speakers, category (1 or maximum of 3 keywords), duration and a description. The website has a single page where users can see the schedule for the entire day with the timings. There will be one lunch break of an hour and the event starts at 10:00 AM. Keep a 10 minute transition between talks. I would like to use Node.js on the server side and standard HTML, JavaScript and CSS on the front-end. The users should be able to search the talks based on category.
I would like you to proceed in the following way:
1. Plan out how you would design and code this application.
2. Ask me for any clarifications along the way.
3. Once I am fine with it, do generate the code and provide me instructions to run and test locally.
以下几个提示和回答是观察到的示例对话流程。您可能会获得完全不同的回答,因此请仔细查看该方案,并根据需要与 Gemini CLI 进行来回互动。
我们发现,Gemini CLI 有时会尝试执行更多操作,甚至可能会为您提供它想要执行的命令。对于本练习,建议不要这样做,以便您更好地控制模型执行任务的方式以及您希望首先自行验证的内容。
例如,如果它建议运行命令,您可以直接退出并提供如下所示的消息:
按照说明启动服务器并前往首页后,我们得到了一个如下所示的示例网站(如果您使用了相同的提示,则应该会看到一个类似的网站变体):
您可以继续在 Gemini CLI 的帮助下进行更多更改。如果您对更改感到满意,可以将其推送到 GitHub 代码库。
首先,我们来创建一个 .gitignore 文件,您可以借助 Gemini CLI。
Create a .gitignore file for this project.
您的下一步是向 Gemini CLI 提供指令,以将此代码库推送到我们的 GitHub 账号下,这应该会在后台运行 GitHub MCP 服务器工具。
提供类似于以下内容的提示:
Great! I would now like to push all of this to a new repository in my Github account. I would like to name this repository <Your-Name>-event-talks-app
它将在此处执行多项命令:
- 创建代码库。
- 它将使用多个 Git 命令(init、add、commit)来管理本地 Git 代码库。
- 然后,它会设置 Git 远程库并执行推送
注意:在某些情况下,Gemini CLI 可能会超时或使用不正确的用户名等。请与它互动并建议修复方案。
如果一切顺利,您应该已经创建了 GitHub 代码库。示例屏幕截图如下所示:
请注意,您尚未为此项目生成 README.md
,这对于下一部分来说是一个很好的练习,我们现在将使用您刚刚创建的此代码库。
使用 Gemini CLI 处理 GitHub 代码库
在此使用情形下,您将使用 Gemini CLI 来处理 GitHub 代码库。您将执行多项任务,包括:
- 了解代码库
- 生成文档
- 实现新功能
- 提交更改并将其推送回代码库
- 处理 GitHub 问题并实现建议的更改
这应该会为您提供良好的基础,以便您随后处理代码库,并使用 Gemini CLI 作为助手来完成这些开发者专属任务。
前提条件
如需执行本部分中的任务,您需要满足以下条件:
- Git
- 使用 GitHub MCP 服务器的 Gemini CLI(我们之前已完成此操作),或者如果您已设置
gh
(GitHub CLI 工具),也可以。 - 熟悉 Git 基础知识,并具备一定的编程知识(在此示例中,我们将使用 Node.js,因为您可能已在自己的机器上准备好环境,这是因为您已安装 Gemini CLI)。不过,您稍后可以随意选择其他编程语言和框架的知识库。
- 您应该已完成上一部分,并准备好代码库,我们在其中创建了 Event Talks 网站。
让我们继续使用您之前用于生成 Event Talks 应用的文件夹/目录中的 Gemini CLI,或者,如果需要,您可以将该代码库克隆到本地机器,然后从该目录启动 Gemini CLI。尝试以下场景:
了解代码库
- 我想详细了解此项目。帮我了解主要功能,然后将其分解为服务器端和客户端。举例说明请求和响应的运作方式。
- 解释 @server.js
生成 README 文件
- 为此项目生成
README
文件。
在这种情况下,Gemini CLI 不仅生成了 README
文件,还想执行命令以添加到 Git 代码库并将更改推送到远程,如果您发现它正在执行这些操作,可以允许它这样做。
在某些情况下,它甚至可以为您生成 LICENSE
文件。您可以自行决定是否要这样做。根据结果,您会发现系统已生成 README
和/或 LICENSE
文件,并且更改已推送到 GitHub。
实现新功能
- 我想实现一项新功能,让用户也可以按特定演讲者进行搜索。首先向我展示您将如何实现此更改的计划,然后我们可以生成代码。
系统应会为您提供一个方案,您可以批准该方案。获得批准后,Gemini CLI 将继续进行这些更改。请务必测试您的更改,如果出现 bug(很可能),请让 Gemini CLI 修复它。
更改看起来没问题后,您可以按照相同的步骤提交并将其推送到远程代码库。
根据建议的功能生成问题
我们来试试一些有趣的东西。您将向 Gemini CLI 询问如何改进此应用的用户体验,然后根据其评估结果,在同一 GitHub 代码库中以问题形式创建这些建议。它将使用 GitHub MCP 服务器中的“create_issue”工具。
尝试使用以下提示:
- 我想请您从用户体验的角度评估该应用。易用性、响应速度、实用消息等。请列出一些改进建议,然后将这些建议作为问题在 GitHub 代码库中创建。
理想情况下,它会先与您分享改进,然后征得您的许可,在 GitHub 代码库中创建问题。以下是运行时的示例屏幕截图:
处理 GitHub 问题并实现建议的更改
现在,您可以选择之前生成的某个问题,然后让 Gemini CLI 处理并实现该问题。
以下是它生成的问题示例:
复制整个问题网址,然后提供如下提示:
- 请查看问题:
<YOUR_ISSUE_URL>
,了解需要做出哪些更改。先讨论方案,然后展示代码中建议的更改。
您可以放心地批准这些更改,并将其推送到代码库。您甚至可以要求它关闭问题。
(可选)日常任务
以下用例是您可能需要定期执行的任务。这些任务包括将文件整理到文件夹中、从网络中提取内容并进行总结、处理图片文件并从中提取内容、处理数据库等。
您可以随意探索自己喜欢的用例。
整理文件/文件夹
您可以根据需要在各种文件夹中使用 Gemini CLI 按类型整理文件。前往您机器上包含多个文件(.txt、.png、.jpg、.pdf、.mp4 等)的文件夹。这很可能是您的桌面或“下载内容”文件夹。
以下是一个示例文件夹,其中显示了该文件夹的内容(您可能还有其他文件):
前往该文件夹,然后启动 Gemini CLI。您将先让 Gemini CLI 创建一些文件夹:Images、Documents、Videos,然后让 Gemini CLI 整理这些文件夹中的文件。
Gemini CLI 通常会在执行命令(尤其是修改文件系统(例如写入、移动或删除文件)的命令)之前提示您授予权限。在授予权限之前,请务必仔细查看这些提示。这是您的安全网。
Create the following folders "Images","Documents","Videos"
然后,输入以下提示:
Go through all the files in this folder and then organize them by moving all the files ending with .jpg, .jpeg, .gif into the "Images" folder. Move all ".txt" files into the "Documents" folder. Move all the ".mp4" files in the "Videos" folder.
文件夹的最终状态示例如下所示。您应该会看到系统创建了新的子文件夹,并且文件已根据其类型移至相应的子文件夹中。
以下是一些其他整理场景(提示显示在每个场景旁边):
- 总结:对于“Documents”文件夹中的每个文档,在同一文件夹中创建一个名为“summary_ORIGINAL_FILENAME.txt”的 txt 文件,其中包含该文档主要内容的 3 句话总结。
- 按类型分类:扫描此目录中的所有 PDF 和 DOCX 文件。将名称或内容中包含“invoice”的所有文件移动到“Financial/Invoices”文件夹中。将包含“收据”的文件移至“财务/收据”。所有其他 .docx 文件都会放入“报告”文件夹。
- 提取关键信息(并“标记”):对于“财务/账单”文件夹中的每个 PDF 文件,读取其内容。如果您找到了日期,请重命名文件,使其包含该日期(格式为 YYYY-MM-DD),例如‘invoice_2025-07-26_original_name.pdf'.
整理图片
我们来看看如何在电脑中整理图片内容。
如需尝试此功能,请执行以下操作:
- 您需要有一个包含各种图片文件(.jpg、.png 等)的目录/文件夹。包括一些包含 EXIF 数据的照片(相机/手机拍摄的大多数照片都包含此数据)。
- 导航到此目录。
- 启动 Gemini CLI。
尝试以下任一场景(提示位于每个场景旁边):
- 按日期(EXIF 数据)重命名:将此目录中的所有 .jpg 和 .png 文件重命名为包含其 EXIF 数据中的创建日期,格式为“YYYYMMDD_HHMMSS_original_name.jpg”。如果未找到 EXIF 日期,请使用文件的上次修改日期。
- 创建图片说明:对于此文件夹中的每张图片,请描述图片中的内容,并将该说明保存在同一目录中名为“description_ORIGINAL_FILENAME.txt”的文本文件中。
- 识别重复项(概念性,需要更高级的逻辑):根据视觉内容查找此文件夹中的所有重复图片,并列出其文件名。暂时不要删除这些文件。
总结文章(本地文件或网页)
对于以下每种情形,您可以根据需要随意更改网址、感兴趣的主题和本地文件名。提供的文件名是示例文件名,您可以将其替换为系统中的文件名。
尝试以下任一场景(提示位于每个场景旁边):
- 总结一篇网页文章(单个网址):前往 https://medium.com/google-cloud/getting-started-with-gemini-cli-8cc4674a1371,并总结这篇新闻报道中的前 3 个关键要点。
- 总结多篇网页文章(例如,来自搜索结果):使用 Google 搜索查找有关“Gemini CLI”的最新新闻报道。对于前 5 篇相关文章,请用 2-3 句话总结每篇文章,并列出其网址。
- 总结本地文本文件:总结“my_research_paper.txt”中的文章要点。重点关注方法和结论。
- 总结本地 PDF:阅读“financial_report_Q2_2025.pdf”。简要说明所提及的财务表现和主要挑战。
提取特定信息(本地文件或网页)
对于以下每种情形,您可以根据需要随意更改网址、感兴趣的主题和本地文件名。提供的文件名是示例文件名,您可以将其替换为系统中的文件名。
尝试以下任一场景(提示位于每个场景旁边):
- 从本地文章中提取实体:从“biography.txt”中列出所有已命名的个人及其相关的重要日期。
- 从 PDF 中的表格提取数据:在“quarterly_sales.pdf”中,提取第 3 页上显示“各区域的产品销售额”的表格中的数据,并以 Markdown 表格格式呈现。
- 从新闻网站提取新闻标题和来源:前往“https://news.google.com/”(或类似的新闻网站)。从首页中提取主要新闻标题及其对应的新闻来源。以项目符号列表的形式呈现。
- 从电子商务页面查找商品规格:浏览至“https://www.amazon.in/Google-Cloud-Certified-Associate-Engineer/dp/1119871441”(以图书为例)。提取图书标题、作者和其他详细信息。以结构化 JSON 格式呈现此信息。
- 以特定格式(例如“2h37m42s”)从视频中提取时长。
根据内容回答问题(类似 RAG 的行为)
对于以下每种情形,您可以根据需要随意更改网址、感兴趣的主题和本地文件名。提供的文件名是示例文件名,您可以将其替换为系统中的文件名。
尝试以下任一场景(提示位于每个场景旁边):
- 本地文档问答:我正在附加“user_manual.pdf”。排查网络连接问题的步骤有哪些?
- 网页上的问答:根据“https://www.who.int/news-room/fact-sheets/detail/climate-change-and-health”中的内容,世界卫生组织认为与气候变化相关的主要健康风险有哪些?
- 比较多个来源的信息:我有两篇新闻报道,分别是“article1.txt”和“article2.txt”,这两篇报道都讨论了近期的经济政策变化。比较并对比他们对潜在的小企业影响的看法。
基于提取的信息生成内容
对于以下每种情形,您可以根据需要随意更改网址、感兴趣的主题和本地文件名。
尝试以下任一场景(提示位于每个场景旁边):
- 根据文章生成新闻简报:阅读 @tech_innovation_article.txt。撰写一篇简短而引人入胜的新闻简报(约 150 字),适合在公司简报中发布,重点介绍这项新技术及其潜力。
- 起草一封电子邮件,总结会议转写内容:以下是会议转写文件:@meeting_transcript.txt。起草一封电子邮件,向团队总结做出的关键决策和分配的待办事项,包括每项待办事项的负责人。
Gemini CLI 多模态支持
Gemini CLI 通过 Gemini 支持多模型,您可以根据自己的需求让它处理不同内容格式的文件。
您将使用 Gemini CLI 处理一批发票图片,并从中提取关键信息。请按下面给出的步骤操作:
- 在您的机器上创建一个文件夹,并从以下 GitHub 代码库下载一些发票。
- 从该文件夹启动 Gemini CLI
使用以下提示以表格形式从发票中提取信息。
The current folder contains a list of invoice files in Image format. Go through all the files in this folder and extract the following invoice information in the form of a table: Invoice No, Invoice Date, Invoice Sent By, Due Date, Due Amount.
理想情况下,您应该会看到如下所示的输出:
以下是另一个示例,您可以在其中请求添加其他派生列。假设您想针对所有已过期的账单截止日期显示一个红色叉号表情符号。您可以按如下方式提供提示:
list all files with .png extension in this folder. Extract the invoice information from it by reading them locally and display it in a table format containing the following column headers: : Invoice No, Invoice Date, Invoice Sent By, Due Date, Due Amount. Add a column at the end of the table that shows a red cross emoji in case the due date is in the past.
这会生成以下输出:
您可以将此功能应用于自己的任何非文本格式文件。
使用 Gemini CLI 处理数据库
您可以使用 Gemini CLI 更高效地处理各种数据库。您可以在多种场景中使用 Gemini,例如使用自然语言进行查询、导出数据、设计数据库架构、生成逼真的测试数据等。
您将使用 SQLite3
来完成此任务。您需要安装 SQLite3 并拥有示例 Chinook 数据库。
以下是有关设置 SQLite3 的简要说明:
- macOS:SQLite3 已预安装。通过
sqlite3 --version
验证。如果需要,请使用 Homebrew 进行安装:brew install sqlite3
。 - Windows:从 SQLite 网站下载预编译的二进制文件。将文件解压缩到某个目录(例如
C:\sqlite
)。将该目录添加到系统的 PATH 环境变量中。 - Linux:Debian/Ubuntu:
sudo apt update && sudo apt install sqlite3
下载 Chinook 示例数据库(点击此直接链接即可下载)。
为了运行这些提示,建议您在 gemini-cli-projects
目录中创建一个文件夹 (database-tasks
)。将 Chinook 数据库文件复制到该文件夹。确保在您的系统上设置了 sqlite3 工具,并且该工具可在路径中使用,以便 Gemini CLI 可以使用它。启动 Gemini CLI。
数据库架构图如下所示:
假设您位于名为 database-tasks
的文件夹中,并且 Chinook 数据库文件的名称为 chinook.db
。
下面列出了几个提示,可帮助您使用数据库。我们先简要介绍第一个示例,以演示将请求的权限。
首先,使用提示列出数据库中存在的表,给出以下提示:
What tables are present in the file: chinook.db
此示例使用该工具读取文件,然后希望使用系统上存在的 sqlite3
实用程序来完成必要的操作:
提供运行一次的权限,以获得预期输出:
您可以尝试使用以下提示或您选择的任何其他提示:
- 有多少员工?
- 账单表的架构是什么?
- 按总金额排序,前 3 张账单是哪些?这些账单是哪些客户下的?
您会发现,Gemini CLI 会处理两件事:生成符合您要求的正确 SQL 语句,并提供正确的 sqlite3
命令。
使用 Gemini CLI 生成数据
您可以提示 Gemini CLI 以各种数据格式生成数据。这可能包括您可能需要模拟的内容片段到 JSON 数据。我们在此重点介绍适用于开发者/测试者的场景。
以下是一些可尝试的提示:
生成示例客户评价的 JSON 数据
Generate a JSON array of 3 synthetic customer reviews for a new smartphone. Each review should have 'reviewId' (string, UUID-like), 'productId' (string, e.g., 'SMARTPHONE_X'), 'rating' (integer, 1-5), 'reviewText' (string, 20-50 words), and 'reviewDate' (string, YYYY-MM-DD format).
生成模拟 API 响应 (JSON)
Generate a JSON array representing 7 daily sales records for a mock API endpoint. Each record should include 'date' (YYYY-MM-DD, chronologically increasing), 'revenue' (float, between 5000.00 and 20000.00), 'unitsSold' (integer, between 100 and 500), and 'region' (string, either 'North', 'South', 'East', 'West').
生成示例数据库插入语句 (SQL)
Generate 5 SQL INSERT statements for a table named 'users' with columns: 'id' (INTEGER, primary key), 'username' (VARCHAR(50), unique), 'email' (VARCHAR(100)), 'password_hash' (VARCHAR(255)), 'created_at' (DATETIME, current timestamp). Ensure the password_hash is a placeholder string like 'hashed_password_X'.
生成用于数据加载/分析的 CSV 数据
Generate 10 lines of CSV data, including a header row, for customer transactions. Columns should be: 'TransactionID' (unique string), 'CustomerID' (integer), 'ItemPurchased' (string, e.g., 'Laptop', 'Monitor', 'Keyboard'), 'Quantity' (integer, 1-3), 'UnitPrice' (float, between 100.00 and 1500.00), 'TransactionDate' (YYYY-MM-DD).
生成配置文件 (YAML)
Generate a sample YAML configuration for a 'user_service'. Include sections for 'database' with 'host', 'port', 'username', 'password', 'database_name'. Also include a 'api_keys' section with 'payment_gateway' and 'email_service' placeholders. Use realistic default values.
为极端情况/验证生成测试数据
Generate a JSON array of 8 email addresses for testing purposes. Include a mix of: 2 valid standard emails, 2 with missing '@', 2 with invalid domains (e.g., '.com1'), and 2 with special characters in the local part that are usually invalid (e.g., spaces or multiple dots).
13. 恭喜
恭喜!您已成功探索 Gemini CLI 及其功能,并将其应用于一些使用情形。