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能力进行意图理解、需求分析和结构化填充。这个工作流程可以分解为几个关键步骤意图捕获当你输入/new-agent “分析代码性能瓶颈”时扩展首先将你的描述文本连同一些预定义的上下文如可用的工具列表、常见的智能体模板一起发送给 LLM。结构化解析与填充LLM 会分析你的描述识别核心任务如“性能分析”、可能需要的操作对象如“代码文件”、以及完成任务所需的工具如需要read来读代码grep来搜索特定模式。接着它会根据这些信息自动生成一个合理的智能体名称如performance_analyzer、一个清晰的显示名、一个详细的系统指令systemPrompt并匹配合适的工具列表和输入参数。交互式确认与定制生成初步配置后扩展不会直接保存。它会将完整的 TOML 内容呈现给你并询问是否满意。你可以直接确认也可以要求调整比如“把图标换成 ”、“增加glob工具以便分析整个目录”。这个确认环节至关重要它保证了最终产物仍然在你的完全控制之下AI 只是扮演了一个超级高效的“初级配置工程师”角色。2.2 扩展与 CLI 的协同架构理解这个扩展如何工作需要一点对 Gemini CLI 扩展系统的了解。Gemini CLI 支持用户开发扩展来增加新的命令或功能。gemini-agent-creator就是一个这样的扩展。挂载机制通过将扩展克隆到~/.gemini/extensions/目录下Gemini CLI 在启动时会扫描这个目录加载所有合法的扩展。每个扩展需要一个gemini-extension.json文件来声明自己提供的命令这里是/new-agent。命令执行流当你在 CLI 中输入/new-agent并回车控制权就交给了这个扩展。扩展的代码会处理你的输入参数或无参数初始化与 AI 模型的会话并管理整个对话流程。文件系统操作在获得你的最终确认后扩展的核心操作其实很简单将 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 (CtrlD 或输入 /exit) # 在普通终端中检查目录 ls -la ~/.gemini/你应该能看到类似以下的目录结构。如果agents目录不存在你可以手动创建它因为扩展会向里面写入文件。.gemini/ ├── config.json ├── agents/ # 这个目录可能初始不存在 └── extensions/ # 扩展存放目录手动创建agents目录mkdir -p ~/.gemini/agents3.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 来识别新扩展。完全退出当前的 Gemini CLI 会话。重新运行gemini命令进入 CLI。使用内置命令检查扩展是否加载成功# 在 Gemini CLI 的交互提示符 ( ) 下输入 /extensions list如果安装成功你会在输出的列表中看到agent-creator。至此安装全部完成。实操心得有时扩展没有立即出现可能是因为缓存或加载顺序问题。一个可靠的排查方法是检查扩展目录内的gemini-extension.json文件是否存在且格式正确。你也可以尝试完全退出终端模拟器再重新打开以确保全新的环境加载了所有配置。4. 两种核心使用模式深度解析安装完成后你就可以开始创造自己的智能体了。扩展提供了两种交互模式适用于不同的场景和用户偏好。4.1 快速模式一句话生成智能体快速模式是效率至上的选择。你只需要对智能体的功能有一个核心的、一句话的描述。命令格式/new-agent “你的智能体功能描述”底层发生了什么当你输入这样的命令后扩展并非简单地将你的描述填充到一个模板里。它会执行一个复杂的“需求分析-配置生成”流程功能抽象AI 会解读你的描述。例如“审查 Python 代码的 bug”AI 会理解到核心动作是“审查”对象是“Python 代码”目标是“bug”。工具匹配基于理解AI 会从可用工具池read,grep,glob,ls,read_many_files,memory,web_search中选择最相关的。对于代码审查read读取文件内容和grep搜索特定代码模式如try...except几乎是必选的。glob可能被用来查找特定扩展名的文件如*.py。指令Prompt工程这是最关键的一步。AI 会编写systemPrompt即给智能体角色的“人设”和“工作指南”。一个优秀的systemPrompt需要明确角色“你是一个经验丰富的 Python 代码审查员”、定义任务边界“专注于逻辑错误和常见的反模式不涉及代码风格”、给出工作方法“先通读代码理解逻辑再逐部分检查可能的问题点”、并规定输出格式“以列表形式列出问题每个问题注明行号和修改建议”。扩展中的 AI 已经内置了编写此类指令的最佳实践。参数定义AI 会思考这个智能体需要什么输入。对于代码审查器一个file_path输入参数是合理的。它会自动定义这个参数的类型字符串、描述“要审查的 Python 文件路径”和是否必需。呈现与确认最后AI 将生成的完整 TOML 配置展示给你并等待你的“最终发射指令”。你可以批准也可以要求修改。示例与技巧“写函数注释”AI 可能会创建一个名为doc_writer的智能体使用read工具其systemPrompt会强调生成符合 Google Docstring 或 JSDoc 风格的注释。“在日志里找错误”AI 可能会创建一个使用grep和glob的智能体其指令会专注于匹配 ERROR、FATAL 等关键词并可能尝试按时间戳排序。技巧描述越具体生成的结果越精准。“分析代码”就比较模糊“分析 JavaScript 代码的内存泄漏模式”则能引导 AI 生成更专业的工具选择和指令。4.2 交互模式引导式对话创建如果你对智能体的具体能力还没有完全想清楚或者想对每个配置项有更精细的控制交互模式是你的最佳选择。启动方式/new-agent不带任何参数运行该命令你就会进入一个多轮对话的创建流程。典型对话流程拆解目标定义AI 会首先问你“你想创建一个做什么的智能体” 你的回答应该尽可能清晰例如“我想创建一个能帮我快速阅读项目 README 和主要源码文件然后给我写一份项目概要总结的助手。”工具选择接着AI 可能会说“根据你的描述这个智能体可能需要读取文件。我建议使用read和glob工具。read用于读取文件内容glob用于快速定位 README.md 和*.py等源码文件。你觉得可以吗还是需要添加grep来搜索特定关键词” 这时你可以同意或者提出调整“加上grep吧方便它总结时引用关键函数名。”指令精炼AI 会生成一份初步的systemPrompt并念给你听“你将扮演一个技术文档总结者。你的任务是…第一步使用 glob 找到 README.md 和主要的 .py 文件第二步用 read 读取它们第三步提炼出项目目的、核心功能和关键模块……输出格式为 Markdown。” 你可以说“很好但请在总结开头先注明分析的文件列表。”输入参数确认AI 会问“这个智能体需要用户提供什么输入吗比如一个项目根目录的路径” 你可以定义“需要一个project_path参数类型是字符串描述是‘项目根目录的绝对路径’。”最终审查和快速模式一样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 truename: 智能体的机器标识符在命令行中用于调用如/code_reviewer。需保持简短使用蛇形命名法snake_case。displayNameicon: 在 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常见的调优场景强化指令AI 生成的systemPrompt可能不错但未必完美。你可以根据实际使用效果增补一些细节。例如在代码审查器中加入“特别注意检查是否使用了不安全的eval()函数”或“对于发现的密码或密钥硬编码在建议中推荐使用环境变量”。调整工具也许你发现智能体需要频繁切换目录可以手动在tools数组里加入ls。或者一个文档总结智能体如果经常需要参考网络资料可以加入web_search。修改输入参数你可以增加新的输入参数。比如为代码审查器增加一个severity_level参数枚举类型可选[“critical”, “major”, “minor”]让用户决定审查的严格程度并在systemPrompt中引用这个参数“Focus on issues of severity level ‘${severity_level}’ and above.”修复问题如果智能体行为异常首先检查 TOML 文件语法。常见的错误包括字符串引号不匹配、数组格式错误、或systemPrompt中有与 TOML 语法冲突的字符通常使用三引号“””可以避免。修改后的加载 修改保存后Gemini CLI 可能不会自动重载配置。最稳妥的方式是退出并重启 CLI。部分版本可能支持热重载命令可以查阅你所使用的 Gemini CLI 分支的文档。6. 实战从零创建三个实用智能体让我们通过三个具体的例子完整走一遍从构思到使用的全过程涵盖不同的复杂度。6.1 智能体一日志错误追踪器场景系统应用经常产生大量日志当出现问题时需要快速从日志文件中定位 ERROR 或 FATAL 级别的条目并查看其上下文。创建过程使用快速模式/new-agent “分析日志文件提取所有 ERROR 和 FATAL 级别的日志行并显示每条错误前后各5行的上下文”AI 生成与审核AI 可能会生成一个名为log_error_scanner的智能体。它会建议使用grep核心搜索和read获取上下文工具。systemPrompt会详细指示智能体首先用grep -n找到所有包含 ERROR/FATAL 的行号然后对于每个行号读取文件并提取 [行号-5, 行号5] 范围内的文本最后格式化输出。输入参数可能是一个log_file_path。自定义调整在审核时我们觉得还需要能指定日志级别。我们可以对 AI 说“增加一个可选的level输入参数默认值是 ‘ERROR,FATAL’但用户可以修改为 ‘WARN’ 或其他。” AI 会更新配置。保存并使用确认保存后重启 CLI。现在可以这样使用# 使用默认级别ERROR, FATAL扫描 /log_error_scanner /var/log/myapp/app.log # 只扫描 WARN 级别 /log_error_scanner /var/log/myapp/app.log “WARN”6.2 智能体二项目依赖分析器场景接手一个新 Python 项目想快速了解它依赖了哪些外部库以及这些库的用途。创建过程使用交互模式/new-agent引导式对话目标“创建一个能分析 Python 项目requirements.txt或pyproject.toml文件并列出所有依赖库简要说明每个库常见用途的智能体。”工具选择AI 建议read和glob。我们同意因为需要读取文件并且要能自动找到项目根目录下的依赖声明文件。指令精炼AI 生成的指令会包括使用glob寻找requirements.txt、Pipfile、pyproject.toml等用read读取它们解析出依赖名称然后基于常识或调用 AI 的知识为每个依赖生成一行简介如“requests: 用于发送 HTTP 请求的流行库。”、“pandas: 用于数据分析和操作的核心库。”。我们可以要求“在输出最后统计依赖的总数。”输入参数定义一个project_dir表示项目路径。最终成果智能体被创建为dep_analyzer。使用方式/dep_analyzer /home/user/code/my_project它会输出一个整洁的列表让你对新项目的技术栈有个快速印象。6.3 智能体三Markdown 文档美化器场景写的 Markdown 文档格式有些凌乱标题层级不统一列表格式混杂希望有一个智能体能自动整理格式。创建过程 这是一个更复杂的智能体因为它不仅需要读取内容还需要进行内容转换。需求分析这个任务无法仅通过已有的“读文件”工具完成因为工具是只读的。我们需要明确这个智能体的输出是“美化后的文本建议”而不是直接修改文件。用户需要手动复制输出并替换原文件。创建命令/new-agent “读取一个 Markdown 文件分析其结构并输出格式美化后的版本。美化包括统一标题的 ‘#’ 符号后加空格规范列表的缩进使用2个空格确保代码块有正确的语言标识符移除行尾多余的空格。”审核与理解AI 会生成一个使用read工具的智能体。其systemPrompt会非常关键它需要详细描述 Markdown 的格式化规则并指示 AI 按规则逐行处理文本。由于 AI 本身具有强大的文本理解和生成能力这个任务对它来说是合适的。它会输出整理好的全文。使用与后续调用/markdown_formatter path/to/doc.md将输出的文本复制到编辑器中替换原内容。你可以进一步扩展这个智能体比如让它在美化后再提供一个更改摘要“修复了3个标题格式规范了5个列表…”。7. 故障排查、常见问题与使用技巧即使有 AI 辅助在实际使用中也可能遇到一些问题。这里记录了一些常见的情况和解决思路。7.1 安装与加载问题问题现象可能原因解决方案运行/new-agent提示“命令未找到”1. 扩展未正确安装到~/.gemini/extensions/目录。2. Gemini CLI 不支持扩展系统或版本不对。3. CLI 需要重启。1. 检查~/.gemini/extensions/agent-creator目录是否存在且包含文件。2. 确认你安装的 Gemini CLI 分支支持扩展如feature/user-defined-agents。3. 完全退出并重启 Gemini CLI。/extensions list中看不到agent-creator扩展的gemini-extension.json文件缺失或格式错误。进入扩展目录检查gemini-extension.json文件是否存在。可以尝试重新克隆仓库。智能体创建成功但重启后/agents列表里没有1. 智能体配置文件有语法错误。2.~/.gemini/agents/目录不存在或路径不对。3. 智能体配置文件未保存在正确位置。1. 用toml语法检查器或直接cat查看生成的.toml文件。2. 确认目录存在且 Gemini CLI 有读取权限。3. 确认文件保存在~/.gemini/agents/下而非其他位置。7.2 智能体创建与使用问题问题现象可能原因解决方案AI 生成的智能体功能与预期不符初始描述过于模糊或宽泛。在交互模式中多轮对话细化需求。或先用快速模式生成一个基础版然后手动编辑systemPrompt进行精修。描述越具体、越场景化效果越好。智能体运行时提示“没有权限”或“工具错误”智能体配置的tools列表中的工具在当前 Gemini CLI 环境中不可用或未启用。检查 Gemini CLI 的版本和配置确认支持所列工具。某些工具如web_search可能需要额外的 API 密钥配置。智能体处理大文件时响应慢或无响应默认的上下文长度或处理能力有限。在systemPrompt中增加分步处理的指令例如“如果文件超过 1000 行请先分析前 200 行和后 200 行以了解结构再针对性地检查核心函数”。或者考虑让智能体先通过grep或glob定位关键部分再深入。想修改已创建的智能体需要编辑 TOML 文件。直接使用文本编辑器修改~/.gemini/agents/智能体名.toml文件。修改后需要重启 Gemini CLI 以加载新配置。7.3 高级技巧与最佳实践组合使用工具最强大的智能体往往是多个工具的组合。例如一个“项目代码统计器”可以先用glob找到所有*.py文件再用read_many_files批量读取或循环使用read最后让 AI 分析并统计行数、函数数量、类数量等。在systemPrompt中设定边界明确告诉智能体“不做什么”和“做什么”同样重要。例如在代码审查器中加入“你只负责审查代码逻辑和安全不负责代码风格美化如空格、换行除非发现明显的错误。”利用query模板提高效率设计好的query模板可以让调用更便捷。例如一个 SQL 查询分析器的query可以设为“Analyze the following SQL query for performance issues: ${sql_query}”。用户调用时只需提供 SQL 语句片段即可。创建智能体“工作流”你可以创建多个单一职责的智能体然后通过手动顺序调用来形成一个工作流。比如先用dep_analyzer看依赖再用code_reviewer看核心代码最后用doc_summarizer生成整体报告。分享你的智能体由于智能体就是简单的 TOML 文件你可以轻松地将其分享给同事。他们只需要将文件放入自己的~/.gemini/agents/目录即可。这是团队间标准化 AI 辅助工作流的绝佳方式。这个扩展将 AI 智能体的创建从一项开发任务转变为一种对话式的设计体验。它降低了技术门槛让更多专注于领域问题而非工具本身的人也能快速打造出贴合自己工作流的 AI 助手。无论是排查日志、分析代码还是整理文档你都可以通过几句描述获得一个专属的、立即可用的命令行伙伴。