第二章. Gemini Cil 基础交互：两个符号走天下

2.1. 交互模式的三种启动方式

在项目目录或任意空目录中运行 gemini，出现 > 提示符后，你就进入了交互模式。这是最常用的方式，适合探索性开发和学习。

启动 Gemini CLI：

1

gemini

你会看到类似这样的界面：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

 ███            █████████  ██████████ ██████   ██████ █████ ██████   █████ █████
░░░███         ███░░░░░███░░███░░░░░█░░██████ ██████ ░░███ ░░██████ ░░███ ░░███
  ░░░███      ███     ░░░  ░███  █ ░  ░███░█████░███  ░███  ░███░███ ░███  ░███
    ░░░███   ░███          ░██████    ░███░░███ ░███  ░███  ░███░░███░███  ░███
     ███░    ░███    █████ ░███░░█    ░███ ░░░  ░███  ░███  ░███ ░░██████  ░███
   ███░      ░░███  ░░███  ░███ ░   █ ░███      ░███  ░███  ░███  ░░█████  ░███
 ███░         ░░█████████  ██████████ █████     █████ █████ █████  ░░█████ █████
░░░            ░░░░░░░░░  ░░░░░░░░░░ ░░░░░     ░░░░░ ░░░░░ ░░░░░    ░░░░░ ░░░░░

Tips for getting started:
1. Ask questions, edit files, or run commands.
2. Be specific for the best results.
3. /help for more information.

 1 GEMINI.md file
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ >   Type your message or @path/to/file                                                                               │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
 ~\Desktop\BMAD (master*)                         no sandbox (see /docs)                         Auto (Gemini 2.5) /model

这个 > 就是输入提示符，你可以在这里输入任何问题或指令。

启动方式 1：基础模式

1

gemini

这是最简单的启动方式，CLI 会加载当前目录的上下文（如果有 .gemini\GEMINI.md 文件）。

启动方式 2：包含额外目录

有时候你的项目依赖其他目录的代码，比如一个共享的工具库。你可以用 --include-directories 参数：

1

gemini --include-directories ..\shared-utils,..\common-types

注意 Windows 下的路径分隔符是反斜杠 \，但在命令行参数中，你也可以用正斜杠 /，PowerShell 会自动转换。

启动方式 3：指定模型

如果你想用更快的 Flash 模型，或者你是付费用户想用 Gemini 3 Flash：

1
2
3

gemini -m gemini-2.5-flash
# 或者（付费用户）
gemini -m gemini-3-flash --preview-features

2.2. @符号：引用文件和目录

@ 符号是 Gemini CLI 最强大的功能之一。它让你可以直接把文件内容注入到对话中，而不需要手动复制粘贴。

基础用法：引用单个文件

假设你有一个 src\auth.ts 文件，想让 AI 解释它的逻辑：

1

> @src\auth.ts 解释这个文件的认证流程

Gemini CLI 会自动读取 src\auth.ts 的内容，然后基于这些内容回答你的问题。你不需要手动打开文件、复制代码、粘贴到对话框——这一切都是自动的。

进阶用法：引用整个目录

如果你想让 AI 理解整个组件库的结构，可以引用整个目录：

1

> @src\components 分析这些组件的设计模式

Gemini CLI 会递归读取 src\components 下的所有文件，但有一个聪明的设计：它会自动遵循 .gitignore 规则。这意味着 node_modules、dist、.next 这些不需要的文件会被自动跳过。

为什么这很重要？因为如果你不小心把 node_modules 也喂给 AI，那 100 万 Token 的上下文窗口瞬间就被占满了，而且都是无用信息。Gemini CLI 帮你避免了这个坑。

多文件引用

你可以在一行中引用多个文件：

1

> @src\api\user.ts @src\types\user.ts @src\utils\validation.ts 这三个文件的类型定义不一致，请统一它们

Gemini CLI 会依次读取这些文件，然后基于所有内容给出建议。

引用时的路径补全

当你输入 @ 后，按 Tab 键，Gemini CLI 会自动显示当前目录下的文件和文件夹列表。这个功能特别方便，你不需要记住完整的路径。

Windows 特有问题：路径中的空格

如果你的项目路径中有空格（比如 D:\my projects\app\src\main.ts），在引用时需要用引号包裹：

1

> @"D:\my projects\app\src\main.ts" 分析这个文件

但如果你已经在项目目录内，使用相对路径就不需要引号：

1

> @src\main.ts 分析这个文件

2.3. ! 符号：执行 Shell 命令

! 符号让你可以在 Gemini CLI 内部执行 Shell 命令，并把输出结果展示给 AI。这在代码审查和调试时特别有用。

基础用法：查看 Git 状态

1

> !git status

Gemini CLI 会执行 git status 命令，把输出结果显示在屏幕上，同时也传递给 AI。你可以接着问：

1

> 这些未提交的文件有什么问题吗？

AI 会基于刚才的 git status 输出给出建议。

进阶用法：代码审查

这是我最常用的一个组合：

1
2

> !git diff --staged
> 请审查这些变更，重点关注性能和安全问题

第一行执行 git diff --staged，显示暂存区的代码变更。第二行让 AI 审查这些变更。整个过程不需要离开 Gemini CLI，非常流畅。

示例：查看项目文件

1

> !dir /b src

这会列出 src 目录下的所有文件和文件夹（/b 参数表示只显示名称，不显示详细信息）。

示例：查看文件内容

1
2

> !type README.md
> 总结这份文档的核心内容

Shell 模式切换

如果你需要连续执行多个命令，可以切换到 Shell 模式：

1
2
3
4
5

> !
Shell Mode> dir
Shell Mode> git log --oneline -5
Shell Mode> npm test
Shell Mode> !

输入 ! 进入 Shell 模式，再输入 ! 退出。在 Shell 模式下，你输入的每一行都会被当作 Shell 命令执行。

环境变量注入

Gemini CLI 在执行 Shell 命令时，会自动注入一个环境变量 GEMINI_CLI=1。你可以在脚本中检测这个变量，实现不同的行为。

在 PowerShell 中检测：

1
2
3
4
5

if ($env:GEMINI_CLI -eq "1") {
    Write-Host "Running in Gemini CLI context"
} else {
    Write-Host "Running in normal shell"
}

2.4. 非交互模式：脚本化调用

除了交互模式，Gemini CLI 还支持非交互模式，适合脚本自动化和 CI/CD 集成。

单次查询

1

gemini -p "列出1到10的质数"

输出：

1

1到10之间的质数有：2, 3, 5, 7

管道输入

在 PowerShell 中，管道的使用方式和 Linux 类似：

1

type README.md | gemini -p "总结这份文档"

或者：

1

echo "怎么样才能躺平？" | gemini

JSON 输出

如果你需要在脚本中处理 Gemini CLI 的输出，可以用 --output-format json：

1
2

$result = gemini -p "什么是机器学习？" --output-format json | ConvertFrom-Json
$result.response

输出结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
  "response": "机器学习是...",
  "stats": {
    "models": {
      "gemini-2.5-pro": {
        "tokens": {
          "prompt": 100,
          "candidates": 50,
          "total": 150
        }
      }
    }
  }
}

流式 JSON 输出

对于长时间运行的任务，你可能想实时监控进度。使用 --output-format stream-json：

1

gemini -p "分析整个项目并生成报告" --output-format stream-json

输出是换行分隔的 JSON 事件流：

1
2
3
4
5

{"type":"init","model":"gemini-2.5-pro"}
{"type":"tool_use","tool_name":"read_file","parameters":{"path":"src\\main.ts"}}
{"type":"tool_result","status":"success"}
{"type":"message","role":"assistant","content":"分析完成..."}
...

在 PowerShell 中过滤特定事件：

1
2
3
4
5
6

gemini -p "运行测试" --output-format stream-json | ForEach-Object {
    $event = $_ | ConvertFrom-Json
    if ($event.type -eq "tool_use") {
        $event.tool_name
    }
}

2.5. 实战案例：自动化工作流

让我们用一个真实的例子，展示如何把 Gemini CLI 集成到日常工作流中。

场景：自动生成 Commit Message

每次提交代码时，写 Commit Message 是个烦人的事情。我们可以让 Gemini CLI 自动生成。

创建一个 PowerShell 脚本 git-commit-ai.ps1：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# 检查是否有暂存的文件
$staged = git diff --cached --quiet
if ($LASTEXITCODE -ne 0) {
    # 获取diff内容
    $diff = git diff --cached

    # 调用Gemini CLI生成commit message
    $result = $diff | gemini -p "根据这些代码变更生成一个简洁的commit message，遵循Conventional Commits规范" --output-format json | ConvertFrom-Json
    $message = $result.response

    # 显示生成的message
    Write-Host "生成的Commit Message："
    Write-Host $message
    Write-Host ""

    # 询问是否使用
    $reply = Read-Host "是否使用这个message？(y/n)"
    if ($reply -eq "y") {
        git commit -m $message
    }
} else {
    Write-Host "没有暂存的文件"
}

使用方法：

1
2

git add .
.\git-commit-ai.ps1

首次运行 PowerShell 脚本时，可能会遇到 “无法加载，因为在此系统上禁止运行脚本” 的错误。解决方法：以管理员身份打开 PowerShell，运行 Set-ExecutionPolicy RemoteSigned，然后输入 Y 确认。

场景：生成 Release Notes

1
2
3
4
5
6
7
8
9
10

# 获取上一个版本到当前的所有commit
$commits = git log --oneline v1.0.0..HEAD

# 生成release notes
$notes = $commits | gemini -p "根据这些commit生成release notes，分类为Features、Bug Fixes、Breaking Changes" --output-format json | ConvertFrom-Json

# 追加到CHANGELOG.md
$notes.response | Add-Content -Path CHANGELOG.md -Encoding UTF8

Write-Host "Release notes已添加到CHANGELOG.md"

2.6. Windows 环境的特殊配置

在 Windows 上使用 Gemini CLI，有一些特殊的配置需要注意。

配置文件位置

Gemini CLI 的配置文件在 Windows 上的位置是：

1

C:\Users\你的用户名\.gemini\

这个目录下包含：

• settings.json - 全局配置
• .env - 环境变量（如 API Key）
• GEMINI.md - 全局上下文
• mcp-oauth-tokens.json - OAuth 令牌

环境变量设置

在 Windows 上设置永久环境变量有两种方式：

方式 1：通过系统设置（推荐）

1. 按 Win 键，搜索 “环境变量”
2. 点击 “编辑系统环境变量”
3. 点击 “环境变量” 按钮
4. 在 “用户变量” 区域，点击 “新建”
5. 变量名：GEMINI_API_KEY
6. 变量值：你的 API 密钥
7. 点击 “确定” 保存

方式 2：通过 PowerShell

1

[System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', '你的API密钥', 'User')

设置后，需要重新打开 PowerShell 窗口才能生效。

验证环境变量是否设置成功：

1

$env:GEMINI_API_KEY

如果显示你的 API 密钥，说明设置成功。

2.7. 本节小结

我们在本节学习了 Gemini CLI 的核心交互语法，并针对 Windows 环境做了详细说明。核心要点：

Windows 常用命令速查：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# 查看文件列表
dir src

# 查看文件内容
type README.md

# 切换目录
cd D:\projects\my-app

# 设置环境变量（临时）
$env:GEMINI_API_KEY = "your-key"

# 运行PowerShell脚本
.\script.ps1

# 管道使用
type file.txt | gemini -p "总结内容"

# JSON输出处理
$result = gemini -p "问题" --output-format json | ConvertFrom-Json
$result.response

Windows 特有注意事项：

1. 路径分隔符用反斜杠 \（也可以用正斜杠 /）
2. 路径中有空格必须用引号包裹
3. 首次运行脚本需要设置执行策略：Set-ExecutionPolicy RemoteSigned
4. 环境变量通过系统设置或 PowerShell 设置
5. 盘符切换需要先输入盘符（如 D:）

下一节，我们将深入学习 Memport 机制，了解如何用模块化的方式管理项目上下文。