Gemini CLI高级功能与自定义配置-优快云博客

Gemini CLI高级功能与自定义配置

【免费下载链接】gemini-cli An open-source AI agent that brings the power of Gemini directly into your terminal. 项目地址: https://gitcode.com/gh_mirrors/gemi/gemini-cli

本文深入探讨了Gemini CLI的高级功能与自定义配置，包括自定义命令开发与TOML格式规范、GEMINI.md上下文文件与分层内存管理、检查点机制与对话状态保存恢复、以及主题定制与Vim模式高级配置。这些功能共同构成了Gemini CLI强大的定制化能力，让开发者能够根据个人偏好和项目需求打造高效的AI辅助开发环境。

自定义命令开发与TOML格式规范

Gemini CLI 提供了强大的自定义命令功能，允许开发者通过 TOML 格式的配置文件创建可重用的命令模板。这一功能极大地提升了开发效率，让常用工作流能够快速复用。本文将深入解析自定义命令的 TOML 格式规范、开发最佳实践以及高级用法。

TOML 文件基础结构

Gemini CLI 的自定义命令使用 TOML（Tom's Obvious, Minimal Language）格式进行定义。每个 .toml 文件代表一个独立的命令，文件路径决定了命令的名称和命名空间。

基本语法规范

# 必需字段：命令提示词
prompt = "请帮我分析这段代码的结构和潜在问题"

# 可选字段：命令描述（显示在帮助菜单中）
description = "代码分析与审查命令"

文件位置与命名规则

自定义命令支持多级目录结构，Gemini CLI 会自动将目录层级转换为命名空间：

mermaid

参数处理机制

Gemini CLI 提供了灵活的参数处理方式，根据 prompt 内容自动选择适当的处理策略。

1. 上下文感知的参数注入

使用 {{args}} 占位符实现智能参数替换：

description = "代码修复命令"
prompt = """
请分析以下问题描述并提供修复方案：

问题描述：{{args}}

请确保修复方案包含：
1. 根本原因分析
2. 具体的代码修改建议
3. 测试用例建议
"""

2. Shell 命令执行与安全注入

通过 !{...} 语法执行 shell 命令，{{args}} 在 shell 环境中会自动进行安全转义：

prompt = """
代码搜索结果显示如下：

!{grep -n "function" *.js | head -10}

请分析这些函数定义的模式和风格一致性。
用户搜索关键词：{{args}}
"""

参数处理策略对比

下表展示了不同参数处理方式的特性对比：

处理方式	语法	安全性	适用场景	示例
原始参数注入	`{{args}}`	中等	普通文本替换	`分析问题：{{args}}`
Shell 安全注入	`!{cmd {{args}}}`	高	命令行参数	`!{grep {{args}} file.txt}`
默认参数追加	无特殊语法	低	简单命令	自动追加完整命令

高级功能与最佳实践

多行提示与复杂逻辑

TOML 支持多行字符串，适合编写复杂的提示逻辑：

description = "项目架构分析命令"
prompt = """
# 项目架构分析报告

## 任务说明
你是一个资深软件架构师，需要全面分析当前项目的技术架构。

## 分析维度
1. **技术栈识别**：识别主要使用的编程语言、框架和工具
2. **架构模式**：分析系统采用的设计模式和架构风格
3. **依赖关系**：梳理模块间的依赖关系和接口设计
4. **性能考量**：评估架构的性能瓶颈和优化建议
5. **扩展性**：分析系统的水平扩展能力和限制

## 数据来源
- 项目文件结构：!{find . -name "*.js" -o -name "*.ts" -o -name "*.py" | head -20}
- 依赖配置：!{cat package.json 2>/dev/null || echo "No package.json found"}
- 构建配置：!{ls -la | grep -E "(Makefile|dockerfile|\.yml|\.yaml)"}

请生成详细的架构分析报告。
"""

命名空间与组织策略

合理的命名空间设计可以大幅提升命令的可维护性：

# 命令目录结构示例
.gemini/commands/
├── code/           # 代码相关命令
│   ├── review.toml
│   ├── refactor.toml
│   └── generate.toml
├── git/            # 版本控制命令
│   ├── commit.toml
│   ├── branch.toml
│   └── status.toml
├── devops/         # 运维相关命令
│   ├── deploy.toml
│   ├── monitor.toml
│   └── logs.toml
└── docs/           # 文档相关命令
    ├── generate.toml
    └── review.toml

错误处理与健壮性设计

通过组合 shell 命令和条件逻辑创建健壮的命令：

prompt = """
项目状态报告：

## 版本控制状态
!{git status --short 2>/dev/null || echo "Not a git repository"}

## 依赖状态
!{if [ -f package.json ]; then echo "Node.js项目"; npm ls --depth=0 2>/dev/null | head -10; elif [ -f requirements.txt ]; then echo "Python项目"; cat requirements.txt | head -5; else echo "未识别到标准依赖文件"; fi}

## 构建状态
!{if [ -f Makefile ]; then make --dry-run 2>&1 | head -5; else echo "无Makefile构建配置"; fi}

请基于以上信息生成项目健康状态报告。
"""

安全最佳实践

1. 输入验证与转义

# 安全示例：使用引号包裹用户输入
prompt = """
执行安全搜索：
!{grep -r "{{args}}" . --include="*.js" --include="*.ts"}
"""

# 风险示例：直接拼接用户输入（避免使用）
prompt = """
执行风险搜索：
!{grep -r {{args}} .}  # 可能引发命令注入
"""

2. 权限控制与沙箱环境

# 限制命令执行范围
prompt = """
项目文件统计：
!{find . -name "*.js" -exec wc -l {} \; | awk '{total += $1} END {print total}'}

安全提示：此命令仅统计行数，不修改任何文件。
"""

实际应用案例

代码审查自动化

description = "自动化代码审查"
prompt = """
# 自动化代码审查报告

## 审查标准
基于行业最佳实践进行代码质量评估，包括：
- 代码风格一致性
- 潜在bug和反模式
- 性能优化建议
- 安全漏洞检测

## 审查数据
最近修改的文件：
!{git diff --name-only HEAD~1..HEAD 2>/dev/null | grep -E "\.(js|ts|py|java)$" | head -5}

当前变更内容：
!{git diff --staged 2>/dev/null || echo "无暂存变更"}

## 审查要求
请对上述代码变更进行详细审查，指出：
1. 代码风格问题
2. 潜在逻辑错误
3. 安全风险
4. 性能优化点
5. 测试覆盖建议

生成结构化审查报告。
"""

项目文档生成

description = "API文档自动生成"
prompt = """
# API接口文档生成

## 数据收集
项目结构概览：
!{find . -name "*.js" -o -name "*.ts" | grep -v node_modules | head -10}

主要导出模块：
!{grep -r "export default" . --include="*.js" --include="*.ts" 2>/dev/null | head -5 || echo "未找到默认导出"}

## 文档生成要求
基于代码分析生成REST API文档，包含：
- 接口端点列表
- 请求/响应格式
- 参数说明
- 使用示例
- 错误代码定义

请生成Markdown格式的API文档。
"""

通过掌握这些 TOML 格式规范和开发技巧，您可以创建出强大、安全且高效的自定义命令，显著提升开发工作流的自动化水平。Gemini CLI 的自定义命令系统为团队协作和项目标准化提供了强有力的工具支持。

GEMINI.md上下文文件与分层内存管理

Gemini CLI的分层内存管理系统通过GEMINI.md上下文文件实现了智能化的上下文管理，为开发者提供了强大的个性化记忆和项目特定配置能力。这一系统不仅支持全局记忆存储，还实现了项目级别的上下文隔离和智能继承机制。

GEMINI.md文件结构解析

GEMINI.md文件采用标准的Markdown格式，支持分层结构和智能导入功能。其核心结构包含以下几个关键部分：

1. 基本文件结构

# 项目名称 - GEMINI.md

## 项目概述
简要描述项目的目标、架构和主要功能

## 技术栈
- 编程语言: TypeScript, JavaScript
- 框架: React, Node.js
- 构建工具: esbuild, vitest
- 包管理器: npm

## 开发规范
代码风格、测试要求和提交规范说明

## Gemini Added Memories
- 用户偏好设置
- 项目特定配置
- 常用命令和快捷方式

2. 分层内存管理架构

Gemini CLI实现了四级分层内存管理机制：

mermaid

内存发现与加载机制

1. 文件发现算法

Gemini CLI使用智能的文件发现算法来定位和加载GEMINI.md文件：

// 内存发现核心算法
async function discoverMemoryFiles(
  currentDir: string,
  includeDirs: string[] = []
): Promise<string[]> {
  const discoveredPaths = new Set<string>();
  
  // 1. 全局内存文件
  const globalPath = path.join(os.homedir(), '.gemini', 'GEMINI.md');
  if (await fileExists(globalPath)) {
    discoveredPaths.add(globalPath);
  }
  
  // 2. 向上遍历父目录
  let current = currentDir;
  while (current !== path.dirname(current)) {
    const potentialPath = path.join(current, 'GEMINI.md');
    if (await fileExists(potentialPath)) {
      discoveredPaths.add(potentialPath);
    }
    current = path.dirname(current);
  }
  
  // 3. 向下搜索子目录（广度优先）
  const queue = [currentDir, ...includeDirs];
  const visited = new Set<string>();
  
  while (queue.length > 0) {
    const dir = queue.shift()!;
    if (visited.has(dir)) continue;
    visited.add(dir);
    
    const geminiPath = path.join(dir, 'GEMINI.md');
    if (await fileExists(geminiPath)) {
      discoveredPaths.add(geminiPath);
    }
    
    // 继续搜索子目录
    const subdirs = await getSubdirectories(dir);
    queue.push(...subdirs);
  }
  
  return Array.from(discoveredPaths);
}

2. 内存加载优先级

系统按照以下优先级顺序加载内存文件：

优先级	文件位置	描述
1	`~/.gemini/GEMINI.md`	全局用户偏好和设置
2	项目根目录 `./GEMINI.md`	项目特定配置和规范
3	子目录 `./src/GEMINI.md`	模块级别的上下文
4	扩展目录 `./.gemini/extensions/`	第三方扩展提供的内存

高级功能特性

1. 导入语句支持

GEMINI.md支持@import语法，允许文件间的引用和组合：

## 项目配置
@import ./config/project-settings.md
@import ../shared/development-guidelines.md

## 团队规范
本项目遵循团队的标准化开发流程和代码审查要求。

2. 智能内存合并

当多个GEMINI.md文件存在时，系统会智能合并内容：

mermaid

3. 内存工具集成

通过save_memory工具，用户可以动态保存重要信息：

// 保存用户偏好的示例
await save_memory({
  fact: "用户偏好使用Dark主题和4空格缩进"
});

// 保存项目特定信息
await save_memory({
  fact: "本项目使用特定的API端点: https://api.example.com/v2"
});

配置与自定义

1. 文件名自定义

用户可以通过配置使用自定义的上下文文件名：

// 在设置中配置多个上下文文件
{
  "memory": {
    "contextFiles": ["README.ai.md", "CONTEXT.md", "GEMINI.md"]
  }
}

2. 导入格式控制

支持两种导入处理格式：

// 树形结构（默认）
const treeResult = await processImports(content, basePath, 'tree');

// 扁平化结构  
const flatResult = await processImports(content, basePath, 'flat');

3. 过滤选项配置

可以通过配置控制内存文件的加载行为：

interface FileFilteringOptions {
  maxFileSize?: number;          // 最大文件大小
  allowedExtensions?: string[];  // 允许的文件扩展名
  excludePatterns?: string[];    // 排除模式
  includePatterns?: string[];    // 包含模式
}

最佳实践指南

1. 项目级GEMINI.md配置

为每个项目创建专门的GEMINI.md文件：

# 项目名称 - 开发指南

## 技术栈
- **前端**: React 18, TypeScript, Vite
- **后端**: Node.js, Express, PostgreSQL
- **测试**: Vitest, Testing Library

## 开发命令
```bash
npm run dev          # 启动开发服务器
npm run test         # 运行测试
npm run build        # 构建生产版本

代码规范

使用ESLint和Prettier进行代码格式化
遵循Airbnb JavaScript风格指南
提交前必须通过所有测试

Gemini Added Memories

本项目使用特定的环境变量配置
API基地址: https://api.example.com
默认分页大小: 20条记录


#### 2. 团队协作配置

对于团队项目，建议配置共享的GEMINI.md：

```markdown
## 团队开发规范
@import https://raw.githubusercontent.com/team/guidelines/main/development.md

## 项目特定配置
- 代码审查要求: 至少需要2个批准
- 部署流程: 使用蓝绿部署策略
- 监控工具: Prometheus + Grafana

## 常用快捷方式
/review # 请求代码审查
/deploy # 触发部署流程
/monitor # 查看系统监控

3. 个性化记忆管理

合理使用分层内存来管理不同级别的配置：

mermaid

故障排除与调试

1. 内存加载问题

如果内存文件未正确加载，可以启用调试模式：

gemini --debug

2. 导入解析问题

检查导入语句的路径是否正确：

# 正确的导入方式
@import ./config/settings.md      # 相对路径
@import ../shared/guidelines.md   # 父目录引用
@import /absolute/path/config.md  # 绝对路径（不推荐）

# 错误的导入方式  
@import settings.md               # 缺少路径前缀
@import ./nonexistent/file.md     # 文件不存在

3. 内存冲突解决

当多个文件包含冲突配置时，系统采用以下解决策略：

优先级覆盖: 更具体的位置覆盖更通用的配置
最后生效: 同级别文件中后加载的配置生效
用户确认: 重要变更需要用户确认

通过这种分层内存管理系统，Gemini CLI能够为每个项目和上下文提供高度定制化的AI辅助体验，同时保持配置的清晰性和可维护性。

检查点机制与对话状态保存恢复

Gemini CLI 的检查点机制是一个强大的安全功能，它能够在执行文件修改操作前自动保存项目的完整状态和对话历史。这个功能特别适合在复杂的代码重构、自动化脚本执行或实验性开发场景中使用，让你能够安全地进行尝试而无需担心破坏现有代码。

检查点机制的工作原理

检查点机制的核心思想是在每个潜在的文件修改操作执行前创建一个完整的状态快照。这个快照包含三个关键组成部分：

Git 快照：系统会在用户主目录下的特殊影子 Git 仓库（~/.gemini/history/<project_hash>）中创建一个提交，完整记录项目所有文件的状态。

对话历史保存：当前与 AI 代理的完整对话记录都会被保存，包括所有的提问、回答和工具调用。

工具调用记录：即将执行的工具调用（如 write_file、replace 等）的具体参数和上下文信息。

mermaid

启用检查点功能

检查点功能默认是禁用的，你可以通过两种方式启用：

命令行参数方式（临时启用）：

gemini --checkpointing

配置文件方式（永久启用）：在 ~/.gemini/settings.json 中添加以下配置：

{
  "checkpointing": {
    "enabled": true
  }
}

使用 /restore 命令管理检查点

启用检查点后，系统会自动创建检查点。你可以使用 /restore 命令来管理和恢复这些检查点。

列出所有可用检查点：

/restore

系统会显示类似如下的检查点列表：

2025-06-22T10-00-00_000Z-my-file.txt-write_file
2025-06-22T10-05-00_000Z-config.js-replace
2025-06-22T10-10-00_000Z-package.json-write_file

恢复特定检查点：

/restore 2025-06-22T10-00-00_000Z-my-file.txt-write_file

执行恢复操作后，系统会：

将项目文件恢复到检查点创建时的状态
恢复对话历史到对应的时刻
重新显示原始的工具调用提示

检查点文件格式与存储结构

检查点数据以 JSON 格式存储在本地，文件命名遵循特定的模式：

<时间戳>_<文件名>_<工具名>.json

每个检查点文件包含以下数据结构：

{
  "timestamp": "2025-06-22T10:00:00.000Z",
  "toolCall": {
    "name": "write_file",
    "args": {
      "path": "src/utils.js",
      "content": "function example() { return 'hello'; }"
    }
  },
  "history": [
    {
      "role": "user",
      "content": "请帮我创建一个工具函数"
    },
    {
      "role": "assistant",
      "content": "我将为您创建一个示例工具函数..."
    }
  ],
  "clientHistory": [...],
  "commitHash": "abc123def456..."
}

实际应用场景

代码重构安全网：在进行大规模代码重构时，检查点机制可以让你在每一步修改前都有回退的保障。

# 开始复杂的重构任务
gemini --checkpointing
> 请帮我重构这个React组件，将其拆分为更小的可复用组件

自动化脚本调试：当使用非交互模式运行自动化脚本时，检查点可以帮助追踪和调试问题。

# 运行自动化脚本并启用检查点
gemini --checkpointing -p "自动化部署脚本：更新版本号并提交"

团队协作安全：在团队环境中，检查点机制可以防止意外的文件修改影响其他开发者的工作。

最佳实践与性能考虑

虽然检查点功能非常有用，但也需要注意一些最佳实践：

选择性启用：对于大型项目，频繁的检查点创建可能会影响性能，建议只在需要时启用。
定期清理：检查点文件会占用磁盘空间，建议定期清理旧的检查点：

rm -rf ~/.gemini/history/old_project_hashes

结合版本控制：检查点机制不能替代正式的版本控制系统（如 Git），应该作为额外的安全层使用。
网络隔离环境：所有检查点数据都存储在本地，这使得该功能特别适合在网络隔离或安全要求较高的环境中使用。

检查点机制与对话状态保存恢复功能为开发者提供了一个强大的安全网，使得在与 AI 代理进行复杂交互时能够保持对项目状态的完全控制。这个功能体现了 Gemini CLI 对开发者工作流程深度理解和对生产环境安全性的重视。

主题定制与Vim模式高级配置

Gemini CLI提供了强大的主题定制功能和专业的Vim模式支持，让开发者可以根据个人偏好和工作环境深度定制终端体验。本节将详细介绍如何创建自定义主题、配置Vim模式的高级功能，以及两者的协同使用技巧。

自定义主题创建与配置

Gemini CLI支持完全自定义的主题系统，允许开发者创建符合个人审美的配色方案。自定义主题通过JSON格式在settings.json文件中定义，支持标准的CSS颜色名称和十六进制颜色代码。

自定义主题配置示例

{
  "customThemes": {
    "MidnightBlue": {
      "name": "MidnightBlue",
      "type": "custom",
      "Background": "#0a0e14",
      "Foreground": "#abb2bf",
      "LightBlue": "#61afef",
      "AccentBlue": "#528bff",
      "AccentPurple": "#c678dd",
      "AccentCyan": "#56b6c2",
      "AccentGreen": "#98c379",
      "AccentYellow": "#e5c07b",
      "AccentRed": "#e06c75",
      "Comment": "#5c6370",
      "Gray": "#3e4452",
      "DiffAdded": "#73c990",
      "DiffRemoved": "#f87060",
      "DiffModified": "#ffcc66",
      "GradientColors": ["#4796e4", "#847ace", "#c3677f"]
    },
    "SolarizedLight": {
      "name": "SolarizedLight",
      "type": "custom",
      "Background": "#fdf6e3",
      "Foreground": "#657b83",
      "LightBlue": "#268bd2",
      "AccentBlue": "#268bd2",
      "AccentPurple": "#6c71c4",
      "AccentCyan": "#2aa198",
      "AccentGreen": "#859900",
      "AccentYellow": "#b58900",
      "AccentRed": "#dc322f",
      "Comment": "#93a1a1",
      "Gray": "#eee8d5",
      "DiffAdded": "#859900",
      "DiffRemoved": "#dc322f",
      "DiffModified": "#b58900"
    }
  },
  "theme": "MidnightBlue"
}

主题颜色属性详解

颜色属性	描述	示例值	必需
`Background`	背景颜色	`#0a0e14`	是
`Foreground`	前景/文本颜色	`#abb2bf`	是
`LightBlue`	浅蓝色调	`#61afef`	是
`AccentBlue`	强调蓝色	`#528bff`	是
`AccentPurple`	强调紫色	`#c678dd`	是
`AccentCyan`	强调青色	`#56b6c2`	是
`AccentGreen`	强调绿色	`#98c379`	是
`AccentYellow`	强调黄色	`#e5c07b`	是
`AccentRed`	强调红色	`#e06c75`	是
`Comment`	注释颜色	`#5c6370`	是
`Gray`	灰色调	`#3e4452`	是
`DiffAdded`	差异-新增内容	`#73c990`	否
`DiffRemoved`	差异-删除内容	`#f87060`	否
`DiffModified`	差异-修改内容	`#ffcc66`	否
`GradientColors`	渐变颜色数组	`["#4796e4", "#847ace"]`	否

主题配置流程图

mermaid

Vim模式高级配置

Gemini CLI内置了完整的Vim模式，支持NORMAL和INSERT两种编辑模式，提供了丰富的Vim风格导航和编辑命令。

Vim模式启用配置

{
  "vimMode": true
}

或者通过命令行启用：

# 启动时启用Vim模式
gemini --vim-mode

# 在会话中使用/vim命令切换
/vim

Vim模式功能特性

Gemini CLI的Vim模式实现了完整的Vim编辑体验：

导航命令：

h, j, k, l - 基本方向导航
w, b, e - 单词级别跳转
0, $, ^ - 行首/行尾导航
gg, G - 文档首尾跳转
数字前缀支持：3h, 5w, 10G

编辑命令：

x - 删除字符
dd - 删除整行
dw, db, de - 单词删除操作
cw, cb, ce - 单词修改操作
i, a, o, O - 插入模式进入
D, C - 删除/修改到行尾
. - 重复上次编辑操作

Vim模式状态机

mermaid

高级Vim配置示例

{
  "vimMode": true,
  "theme": "Dracula",
  "hideTips": true,
  "hideBanner": false,
  "hideFooter": false
}

主题与Vim模式协同配置

将自定义主题与Vim模式结合使用，可以创建极致的开发体验：

专业开发者配置示例

{
  "customThemes": {
    "DeveloperDark": {
      "name": "DeveloperDark",
      "type": "custom",
      "Background": "#1e1e1e",
      "Foreground": "#d4d4d4",
      "LightBlue": "#9cdcfe",
      "AccentBlue": "#569cd6",
      "AccentPurple": "#c586c0",
      "AccentCyan": "#4ec9b0",
      "AccentGreen": "#6a9955",
      "AccentYellow": "#dcdcaa",
      "AccentRed": "#f44747",
      "Comment": "#6a9955",
      "Gray": "#858585",
      "DiffAdded": "#4b5632",
      "DiffRemoved": "#6c2b2b",
      "DiffModified": "#3c3c3c"
    }
  },
  "theme": "DeveloperDark",
  "vimMode": true,
  "hideTips": true,
  "maxSessionTurns": 50,
  "fileFiltering": {
    "respectGitIgnore": true,
    "enableRecursiveFileSearch": true
  }
}

配置验证与调试

创建配置后，可以通过以下命令验证：

# 检查当前配置
/settings

# 测试Vim模式功能
/vim
# 进入NORMAL模式，尝试基本导航

# 验证主题显示
/theme

性能优化建议

对于大型项目，建议配置以下优化设置：

{
  "vimMode": true,
  "fileFiltering": {
    "respectGitIgnore": true,
    "enableRecursiveFileSearch": true,
    "disableFuzzySearch": false
  },
  "memoryDiscoveryMaxDirs": 100,
  "maxSessionTurns": 100
}

故障排除与常见问题

主题不生效：

检查JSON格式是否正确
确认所有必需颜色属性都已设置
验证颜色值格式（十六进制或CSS颜色名）

Vim模式问题：

确认vimMode设置为true
检查终端是否支持相应的键盘输入
尝试通过/vim命令手动切换

性能问题：

对于大型项目，考虑禁用模糊搜索
调整memoryDiscoveryMaxDirs限制目录搜索深度
使用.geminiignore文件排除不必要的目录

通过深度定制主题和Vim模式，Gemini CLI可以完全适配个人开发习惯，提供高效、舒适的终端AI助手体验。建议根据实际使用场景逐步调整配置，找到最适合自己的工作流设置。

总结

Gemini CLI通过四大核心功能模块提供了全方位的定制化体验：TOML格式的自定义命令系统让常用工作流可复用；分层内存管理通过GEMINI.md文件实现智能上下文管理；检查点机制为文件操作提供安全网；主题与Vim模式定制则优化了终端交互体验。这些功能相互配合，使Gemini CLI不仅是一个AI助手，更是一个可深度定制的高效开发平台，适合从个人开发者到大型团队的各种使用场景。

【免费下载链接】gemini-cli An open-source AI agent that brings the power of Gemini directly into your terminal. 项目地址: https://gitcode.com/gh_mirrors/gemi/gemini-cli

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考