对话式AI智能体创建：用自然语言定制你的Gemini CLI助手

1. 项目概述与核心价值

如果你和我一样，每天都在命令行里和代码、系统、数据打交道，那你肯定对效率工具有着近乎偏执的追求。最近，我在折腾一个叫 Gemini CLI 的工具，它本身已经是个不错的 AI 命令行助手了。但真正让我眼前一亮的，是社区里一个名为gemini-agent-creator的扩展。这玩意儿彻底改变了为 CLI 创建自定义 AI 智能体的方式——从手动编写繁琐的配置文件，变成了和 AI 聊聊天就能搞定。简单来说，它通过一个/new-agent命令，让你用自然语言描述需求，AI 就能帮你生成一个功能完整、配置妥当的智能体定义文件（TOML 格式）。这不仅仅是省去了查语法、写配置的时间，更重要的是，它把“设计智能体”这个有一定门槛的任务，变成了一个充满引导和创意的对话过程。无论你是想创建一个代码安全检查员、一个文档生成器，还是一个性能分析专家，这个扩展都能让你在几分钟内，把一个模糊的想法变成一个即插即用的命令行工具。

2. 核心设计思路与工作原理拆解

2.1 从“配置驱动”到“对话驱动”的范式转变

传统的 CLI 工具扩展或智能体创建，通常是“配置驱动”的。你需要理解一个特定的配置文件格式（比如 YAML、TOML 或 JSON），知道每个字段的含义，然后像填空一样，小心翼翼地编写name、description、systemPrompt、tools等。这个过程容易出错，且对新手不友好，一个缩进错误或字段名拼写错误就可能导致整个智能体无法加载。

gemini-agent-creator扩展的核心思路，是引入一个“对话驱动”的中间层。它没有发明新的配置格式，最终输出的仍然是标准的 Gemini CLI 智能体 TOML 文件。它的创新在于创建过程：它将你（用户）的自然语言描述，作为输入，利用底层的大语言模型（LLM）能力，进行意图理解、需求分析和结构化填充。

这个工作流程可以分解为几个关键步骤：

1. 意图捕获：当你输入/new-agent “分析代码性能瓶颈”时，扩展首先将你的描述文本，连同一些预定义的上下文（如可用的工具列表、常见的智能体模板），一起发送给 LLM。
2. 结构化解析与填充：LLM 会分析你的描述，识别核心任务（如“性能分析”）、可能需要的操作对象（如“代码文件”）、以及完成任务所需的工具（如需要read来读代码，grep来搜索特定模式）。接着，它会根据这些信息，自动生成一个合理的智能体名称（如performance_analyzer）、一个清晰的显示名、一个详细的系统指令（systemPrompt），并匹配合适的工具列表和输入参数。
3. 交互式确认与定制：生成初步配置后，扩展不会直接保存。它会将完整的 TOML 内容呈现给你，并询问是否满意。你可以直接确认，也可以要求调整，比如“把图标换成 🔍”、“增加glob工具以便分析整个目录”。这个确认环节至关重要，它保证了最终产物仍然在你的完全控制之下，AI 只是扮演了一个超级高效的“初级配置工程师”角色。

2.2 扩展与 CLI 的协同架构

理解这个扩展如何工作，需要一点对 Gemini CLI 扩展系统的了解。Gemini CLI 支持用户开发扩展来增加新的命令或功能。gemini-agent-creator就是一个这样的扩展。

1. 挂载机制：通过将扩展克隆到~/.gemini/extensions/目录下，Gemini CLI 在启动时会扫描这个目录，加载所有合法的扩展。每个扩展需要一个gemini-extension.json文件来声明自己提供的命令（这里是/new-agent）。
2. 命令执行流：当你在 CLI 中输入/new-agent并回车，控制权就交给了这个扩展。扩展的代码会处理你的输入参数（或无参数），初始化与 AI 模型的会话，并管理整个对话流程。
3. 文件系统操作：在获得你的最终确认后，扩展的核心操作其实很简单：将 AI 生成并经过你审核的那段 TOML 文本，写入到~/.gemini/agents/目录下的一个以智能体名命名的.toml文件中。Gemini CLI 会监控这个目录，新文件创建后，通常需要重启 CLI 或触发重新加载，新的智能体命令（如/performance_analyzer）就可用了。

这种设计的美妙之处在于职责分离：扩展只负责“创建”，而 Gemini CLI 负责“运行”。扩展利用了 CLI 已有的 AI 对话能力和扩展框架，专注于解决“创建难”这个痛点。

注意：这个扩展依赖于 Gemini CLI 的一个实验性功能——用户自定义智能体（user-defined agents）。这意味着你可能需要安装特定分支版本的 Gemini CLI（如jduncan-rva/gemini-cli仓库的feature/user-defined-agents分支），而不是官方稳定版。主仓库的功能合并进度需要你关注相关项目的更新。

3. 详细安装与环境配置指南

3.1 前置条件：搭建 Gemini CLI 基础环境

在安装agent-creator扩展之前，你必须先有一个支持用户自定义智能体功能的 Gemini CLI 环境。这里假设你从基础开始。

第一步：安装或更新 Gemini CLI官方仓库是google-gemini/gemini-cli，但自定义智能体功能可能在特定分支。最稳妥的方法是克隆包含该特性的分支。

# 克隆带有用户自定义智能体特性的分支 git clone -b feature/user-defined-agents https://github.com/jduncan-rva/gemini-cli.git cd gemini-cli # 按照该仓库 README 进行安装，通常是基于 Go 的安装 go build -o gemini ./cmd/gemini # 将编译好的二进制文件移动到你的系统 PATH 中，例如 sudo mv gemini /usr/local/bin/ # 或者，如果你之前安装过，可能需要用新版本覆盖

安装完成后，在终端输入gemini并回车，你应该能看到 Gemini CLI 的启动界面，并进入一个以>为提示符的交互式对话环境。输入/help可以查看基本命令。

第二步：验证智能体目录结构自定义智能体需要特定的目录来存放配置文件。通常，Gemini CLI 会在你的用户主目录下创建.gemini文件夹。

# 退出 Gemini CLI (Ctrl+D 或输入 /exit) # 在普通终端中检查目录 ls -la ~/.gemini/

你应该能看到类似以下的目录结构。如果agents目录不存在，你可以手动创建它，因为扩展会向里面写入文件。

.gemini/ ├── config.json ├── agents/ # 这个目录可能初始不存在 └── extensions/ # 扩展存放目录

手动创建agents目录：

mkdir -p ~/.gemini/agents

3.2 安装 Agent Creator 扩展

现在可以安装主角gemini-agent-creator了。步骤非常直接。

# 1. 确保 extensions 目录存在 mkdir -p ~/.gemini/extensions # 2. 克隆扩展仓库到 extensions 目录下，并命名为 agent-creator git clone https://github.com/jduncan-rva/gemini-agent-creator.git ~/.gemini/extensions/agent-creator

执行完上述命令后，~/.gemini/extensions/目录下会多出一个agent-creator文件夹，里面包含了扩展的所有代码和配置文件。

第三步：加载扩展并验证扩展是动态加载的，通常需要重启 Gemini CLI 来识别新扩展。

1. 完全退出当前的 Gemini CLI 会话。
2. 重新运行gemini命令进入 CLI。
3. 使用内置命令检查扩展是否加载成功：

# 在 Gemini CLI 的交互提示符 (> ) 下输入 /extensions list

如果安装成功，你会在输出的列表中看到agent-creator。至此，安装全部完成。

实操心得：有时扩展没有立即出现，可能是因为缓存或加载顺序问题。一个可靠的排查方法是检查扩展目录内的gemini-extension.json文件是否存在且格式正确。你也可以尝试完全退出终端模拟器再重新打开，以确保全新的环境加载了所有配置。

4. 两种核心使用模式深度解析

安装完成后，你就可以开始创造自己的智能体了。扩展提供了两种交互模式，适用于不同的场景和用户偏好。

4.1 快速模式：一句话生成智能体

快速模式是效率至上的选择。你只需要对智能体的功能有一个核心的、一句话的描述。

命令格式：

/new-agent “你的智能体功能描述”

底层发生了什么？当你输入这样的命令后，扩展并非简单地将你的描述填充到一个模板里。它会执行一个复杂的“需求分析-配置生成”流程：

1. 功能抽象：AI 会解读你的描述。例如“审查 Python 代码的 bug”，AI 会理解到核心动作是“审查”，对象是“Python 代码”，目标是“bug”。
2. 工具匹配：基于理解，AI 会从可用工具池（read,grep,glob,ls,read_many_files,memory,web_search）中选择最相关的。对于代码审查，read（读取文件内容）和grep（搜索特定代码模式，如try...except）几乎是必选的。glob可能被用来查找特定扩展名的文件（如*.py）。
3. 指令（Prompt）工程：这是最关键的一步。AI 会编写systemPrompt，即给智能体角色的“人设”和“工作指南”。一个优秀的systemPrompt需要明确角色（“你是一个经验丰富的 Python 代码审查员”）、定义任务边界（“专注于逻辑错误和常见的反模式，不涉及代码风格”）、给出工作方法（“先通读代码理解逻辑，再逐部分检查可能的问题点”）、并规定输出格式（“以列表形式列出问题，每个问题注明行号和修改建议”）。扩展中的 AI 已经内置了编写此类指令的最佳实践。
4. 参数定义：AI 会思考这个智能体需要什么输入。对于代码审查器，一个file_path输入参数是合理的。它会自动定义这个参数的类型（字符串）、描述（“要审查的 Python 文件路径”）和是否必需。
5. 呈现与确认：最后，AI 将生成的完整 TOML 配置展示给你，并等待你的“最终发射指令”。你可以批准，也可以要求修改。

示例与技巧：

• “写函数注释”：AI 可能会创建一个名为doc_writer的智能体，使用read工具，其systemPrompt会强调生成符合 Google Docstring 或 JSDoc 风格的注释。
• “在日志里找错误”：AI 可能会创建一个使用grep和glob的智能体，其指令会专注于匹配 ERROR、FATAL 等关键词，并可能尝试按时间戳排序。
• 技巧：描述越具体，生成的结果越精准。“分析代码”就比较模糊，“分析 JavaScript 代码的内存泄漏模式”则能引导 AI 生成更专业的工具选择和指令。

4.2 交互模式：引导式对话创建

如果你对智能体的具体能力还没有完全想清楚，或者想对每个配置项有更精细的控制，交互模式是你的最佳选择。

启动方式：

/new-agent

不带任何参数运行该命令，你就会进入一个多轮对话的创建流程。

典型对话流程拆解：

1. 目标定义：AI 会首先问你：“你想创建一个做什么的智能体？” 你的回答应该尽可能清晰，例如：“我想创建一个能帮我快速阅读项目 README 和主要源码文件，然后给我写一份项目概要总结的助手。”
2. 工具选择：接着，AI 可能会说：“根据你的描述，这个智能体可能需要读取文件。我建议使用read和glob工具。read用于读取文件内容，glob用于快速定位 README.md 和*.py等源码文件。你觉得可以吗？还是需要添加grep来搜索特定关键词？” 这时你可以同意，或者提出调整：“加上grep吧，方便它总结时引用关键函数名。”
3. 指令精炼：AI 会生成一份初步的systemPrompt并念给你听：“你将扮演一个技术文档总结者。你的任务是…第一步，使用 glob 找到 README.md 和主要的 .py 文件；第二步，用 read 读取它们；第三步，提炼出项目目的、核心功能和关键模块……输出格式为 Markdown。” 你可以说：“很好，但请在总结开头先注明分析的文件列表。”
4. 输入参数确认：AI 会问：“这个智能体需要用户提供什么输入吗？比如一个项目根目录的路径？” 你可以定义：“需要一个project_path参数，类型是字符串，描述是‘项目根目录的绝对路径’。”
5. 最终审查：和快速模式一样，AI 会展示完整的 TOML 文件供你最终审阅。你可以在此刻提出任何最后的调整，比如修改智能体的显示名称或图标。

交互模式的价值： 这个过程不仅创建了一个智能体，更是一次对“如何设计一个有效 AI 智能体”的微型教学。通过问答，你被迫思考了智能体的边界、所需的数据访问权限、以及它与用户的交互契约，这能极大提升你日后设计其他智能体的能力。

5. 智能体配置详解与高级定制

虽然扩展帮你生成了配置，但理解每个配置项的含义，能让你在审核 AI 的提案时更有底气，也能手动微调已有的智能体。

5.1 TOML 配置文件结构剖析

一个典型的生成文件~/.gemini/agents/my_agent.toml内容如下：

name = “code_reviewer” displayName = “🔍 Code Reviewer” description = “Reviews Python code for bugs and security issues” icon = “🔍” tools = [“read”, “grep”] systemPrompt = “”” You are an expert Python code reviewer. Your task is to analyze the provided Python code for potential bugs, security vulnerabilities (like SQL injection, hardcoded secrets), and anti-patterns. Follow these steps: 1. First, understand the overall purpose of the code. 2. Examine each function and logic block carefully. 3. Identify specific issues, citing the line number if possible. 4. For each issue, provide a brief explanation and a suggested fix. Output your findings in a clear list, prioritizing critical security issues first. “”” query = “Review the code in ${file_path} for issues” [inputs.file_path] type = “string” description = “Path to the Python file to review” required = true

• name: 智能体的机器标识符，在命令行中用于调用（如/code_reviewer）。需保持简短，使用蛇形命名法（snake_case）。
• displayName&icon: 在 CLI 的交互界面中显示的名称和图标，用于提升可读性和美观度。
• description: 对智能体功能的简要说明，帮助用户理解其用途。
• tools:核心配置项之一。定义了智能体可以调用哪些底层能力。这是一个字符串数组。选择工具的本质是授予智能体不同的“权限”：
  • read：读取单个文件内容。最常用，几乎所有与文件内容分析的智能体都需要。
  • grep：在文件中搜索文本模式。用于日志分析、查找特定代码模式等。
  • glob：根据模式匹配文件路径。用于处理整个目录或特定类型的文件（如*.log,src/**/*.py）。
  • read_many_files：批量读取多个文件。适合需要同时分析多个文件的场景。
  • ls：列出目录内容。用于探索性任务。
  • memory：提供跨会话的持久化记忆能力。适合需要记住上下文（如之前对话内容）的复杂助手。
  • web_search：进行网络搜索。适合研究型、信息搜集型智能体。
• systemPrompt:最核心的配置项，决定了智能体的“灵魂”。它定义了角色的身份、行为准则、思考过程和输出格式。AI 在生成时会尽力编写详细、可操作的指令。一个好的systemPrompt应该是具体、分步、带有示例的。
• query: 定义用户调用智能体时的默认问题模板。其中的${file_path}是一个变量，会被用户提供的实际输入值替换。这提供了一个便捷的调用起点。
• [inputs]: 定义了智能体所需的输入参数表。每个参数有自己的类型、描述和是否必填。这构成了智能体与用户交互的“接口”。在上例中，调用/code_reviewer时，CLI 会提示用户输入file_path的值。

5.2 手动编辑与调优智能体

扩展创建了智能体，但你不必就此止步。所有智能体都是普通的 TOML 文件，你可以随时用文本编辑器打开修改。

# 例如，用 nano 编辑器修改一个智能体 nano ~/.gemini/agents/code_reviewer.toml

常见的调优场景：

1. 强化指令：AI 生成的systemPrompt可能不错，但未必完美。你可以根据实际使用效果，增补一些细节。例如，在代码审查器中加入：“特别注意检查是否使用了不安全的eval()函数”或“对于发现的密码或密钥硬编码，在建议中推荐使用环境变量”。
2. 调整工具：也许你发现智能体需要频繁切换目录，可以手动在tools数组里加入ls。或者，一个文档总结智能体如果经常需要参考网络资料，可以加入web_search。
3. 修改输入参数：你可以增加新的输入参数。比如，为代码审查器增加一个severity_level参数（枚举类型，可选[“critical”, “major”, “minor”]），让用户决定审查的严格程度，并在systemPrompt中引用这个参数：“Focus on issues of severity level ‘${severity_level}’ and above.”
4. 修复问题：如果智能体行为异常，首先检查 TOML 文件语法。常见的错误包括：字符串引号不匹配、数组格式错误、或systemPrompt中有与 TOML 语法冲突的字符（通常使用三引号“””可以避免）。

修改后的加载： 修改保存后，Gemini CLI 可能不会自动重载配置。最稳妥的方式是退出并重启 CLI。部分版本可能支持热重载命令，可以查阅你所使用的 Gemini CLI 分支的文档。

6. 实战：从零创建三个实用智能体

让我们通过三个具体的例子，完整走一遍从构思到使用的全过程，涵盖不同的复杂度。

6.1 智能体一：日志错误追踪器

场景：系统应用经常产生大量日志，当出现问题时，需要快速从日志文件中定位 ERROR 或 FATAL 级别的条目，并查看其上下文。

创建过程：

1. 使用快速模式：

   /new-agent “分析日志文件，提取所有 ERROR 和 FATAL 级别的日志行，并显示每条错误前后各5行的上下文”

2. AI 生成与审核：AI 可能会生成一个名为log_error_scanner的智能体。它会建议使用grep（核心搜索）和read（获取上下文）工具。systemPrompt会详细指示智能体：首先用grep -n找到所有包含 ERROR/FATAL 的行号，然后对于每个行号，读取文件并提取 [行号-5, 行号+5] 范围内的文本，最后格式化输出。输入参数可能是一个log_file_path。
3. 自定义调整：在审核时，我们觉得还需要能指定日志级别。我们可以对 AI 说：“增加一个可选的level输入参数，默认值是 ‘ERROR,FATAL’，但用户可以修改为 ‘WARN’ 或其他。” AI 会更新配置。
4. 保存并使用：确认保存后，重启 CLI。现在可以这样使用：

   # 使用默认级别（ERROR, FATAL）扫描 /log_error_scanner /var/log/myapp/app.log # 只扫描 WARN 级别 /log_error_scanner /var/log/myapp/app.log “WARN”

6.2 智能体二：项目依赖分析器

场景：接手一个新 Python 项目，想快速了解它依赖了哪些外部库，以及这些库的用途。

创建过程：

1. 使用交互模式：

   /new-agent

2. 引导式对话：
   • 目标：“创建一个能分析 Python 项目requirements.txt或pyproject.toml文件，并列出所有依赖库，简要说明每个库常见用途的智能体。”
   • 工具选择：AI 建议read和glob。我们同意，因为需要读取文件，并且要能自动找到项目根目录下的依赖声明文件。
   • 指令精炼：AI 生成的指令会包括：使用glob寻找requirements.txt、Pipfile、pyproject.toml等；用read读取它们；解析出依赖名称；然后基于常识（或调用 AI 的知识）为每个依赖生成一行简介，如“requests: 用于发送 HTTP 请求的流行库。”、“pandas: 用于数据分析和操作的核心库。”。我们可以要求：“在输出最后，统计依赖的总数。”
   • 输入参数：定义一个project_dir，表示项目路径。
3. 最终成果：智能体被创建为dep_analyzer。使用方式：

   /dep_analyzer /home/user/code/my_project

   它会输出一个整洁的列表，让你对新项目的技术栈有个快速印象。

6.3 智能体三：Markdown 文档美化器

场景：写的 Markdown 文档格式有些凌乱，标题层级不统一，列表格式混杂，希望有一个智能体能自动整理格式。

创建过程： 这是一个更复杂的智能体，因为它不仅需要读取内容，还需要进行内容转换。

1. 需求分析：这个任务无法仅通过已有的“读文件”工具完成，因为工具是只读的。我们需要明确，这个智能体的输出是“美化后的文本建议”，而不是直接修改文件。用户需要手动复制输出并替换原文件。
2. 创建命令：

   /new-agent “读取一个 Markdown 文件，分析其结构，并输出格式美化后的版本。美化包括：统一标题的 ‘#’ 符号后加空格，规范列表的缩进（使用2个空格），确保代码块有正确的语言标识符，移除行尾多余的空格。”

3. 审核与理解：AI 会生成一个使用read工具的智能体。其systemPrompt会非常关键：它需要详细描述 Markdown 的格式化规则，并指示 AI 按规则逐行处理文本。由于 AI 本身具有强大的文本理解和生成能力，这个任务对它来说是合适的。它会输出整理好的全文。
4. 使用与后续：调用/markdown_formatter path/to/doc.md，将输出的文本复制到编辑器中替换原内容。你可以进一步扩展这个智能体，比如让它在美化后，再提供一个更改摘要（“修复了3个标题格式，规范了5个列表…”）。

7. 故障排查、常见问题与使用技巧

即使有 AI 辅助，在实际使用中也可能遇到一些问题。这里记录了一些常见的情况和解决思路。

7.1 安装与加载问题

7.2 智能体创建与使用问题

7.3 高级技巧与最佳实践

1. 组合使用工具：最强大的智能体往往是多个工具的组合。例如，一个“项目代码统计器”可以：先用glob找到所有*.py文件，再用read_many_files批量读取（或循环使用read），最后让 AI 分析并统计行数、函数数量、类数量等。
2. 在systemPrompt中设定边界：明确告诉智能体“不做什么”和“做什么”同样重要。例如，在代码审查器中加入：“你只负责审查代码逻辑和安全，不负责代码风格美化（如空格、换行），除非发现明显的错误。”
3. 利用query模板提高效率：设计好的query模板可以让调用更便捷。例如，一个 SQL 查询分析器的query可以设为“Analyze the following SQL query for performance issues: ${sql_query}”。用户调用时只需提供 SQL 语句片段即可。
4. 创建智能体“工作流”：你可以创建多个单一职责的智能体，然后通过手动顺序调用来形成一个工作流。比如，先用dep_analyzer看依赖，再用code_reviewer看核心代码，最后用doc_summarizer生成整体报告。
5. 分享你的智能体：由于智能体就是简单的 TOML 文件，你可以轻松地将其分享给同事。他们只需要将文件放入自己的~/.gemini/agents/目录即可。这是团队间标准化 AI 辅助工作流的绝佳方式。

这个扩展将 AI 智能体的创建从一项开发任务，转变为一种对话式的设计体验。它降低了技术门槛，让更多专注于领域问题而非工具本身的人，也能快速打造出贴合自己工作流的 AI 助手。无论是排查日志、分析代码还是整理文档，你都可以通过几句描述，获得一个专属的、立即可用的命令行伙伴。