1. 项目概述一个为Gemini CLI深度定制的命令集如果你和我一样日常重度依赖命令行并且最近开始尝试用Gemini CLI来提升工作效率那你可能已经发现了一个痛点原生的命令虽然强大但总感觉少了点“私人订制”的味道。那些重复性的、特定于你个人工作流的任务每次都要手动输入冗长的提示词或者在不同的工具间来回切换效率瓶颈很快就出现了。今天要聊的这个项目——palladius/gemini-cli-custom-commands就是来解决这个问题的。它不是一个独立的工具而是一个Gemini CLI的扩展包你可以把它理解为一套由社区开发者主要是项目作者Palladius精心打磨的“快捷指令集”或“技能包”。它的核心价值在于将一系列复杂、多步骤的AI驱动任务封装成一个个简单易记的命令让你在终端里敲几个单词就能调用Gemini完成特定工作。简单来说安装了这个扩展你的gemini命令就获得了一堆超能力。比如你想让AI帮你分析代码库里的所有TODO注释不用再费心组织提示词直接输入/common:find_todos就行或者你需要遵循一个严谨的“计划-定义-执行”流程来生成代码/code:pda命令已经为你搭建好了框架。它把最佳实践和常用场景固化成命令让你能更专注在问题本身而不是与AI的沟通方式上。这个项目特别适合几类人开发者和DevRel开发者关系工程师因为它包含了大量与代码、文档、Git、云平台GCP相关的自动化命令SRE站点可靠性工程师虽然部分功能已迁移但其思路对自动化运维很有启发以及所有希望将AI更深度、更结构化地融入自己命令行工作流的效率追求者。接下来我会带你深入拆解这个项目的设计思路、核心命令的实战用法并分享我在集成和使用过程中的一系列经验与踩过的坑。2. 核心设计思路与架构解析2.1 为什么需要自定义命令从“对话”到“执行”的范式转变在深入代码之前我们得先想明白一个问题用Gemini CLI直接对话不香吗为什么还要搞一套自定义命令这背后其实是一种工作范式的转变。原始模式对话式你有一个需求 - 你在脑中构思如何向AI描述 - 你输入一段可能很冗长且不精确的提示词 - AI返回结果 - 你可能需要多轮交互来修正。这个过程充满了不确定性并且难以复用。比如每次代码审查你都得重新描述一遍你的代码风格偏好。自定义命令模式执行式你有一个明确定义的任务类型 - 你调用一个对应的、预先定义好的命令 - 命令背后是一套精心设计的提示词模板、上下文获取逻辑和输出处理流程 - AI基于这个“标准化流程”返回结果。这就像为你常用的复杂操作编写了一个Shell脚本或函数只不过这个脚本的“核心逻辑”是由AI驱动的。palladius/gemini-cli-custom-commands项目就是基于后一种思路。它的目标不是替代gemini的通用对话能力而是对其能力进行场景化、产品化的封装。每个命令都对应一个具体的、高频的“工作流”。这种设计带来了几个显著优势一致性对于相同类型的任务如生成Git提交信息每次都能遵循相同的逻辑和标准输出质量稳定。效率省去了反复构思和输入通用提示词的时间一键触发复杂流程。集成度命令可以直接与你的工作环境交互如读取当前git状态、扫描文件系统让AI的上下文更精准。可分享性一套好的命令集可以成为团队或社区的共享资产统一工作方式。2.2 项目架构扩展、命令与技能的层次浏览项目的README和源码结构我们可以梳理出它的三层架构这有助于我们理解其运作方式。第一层Gemini CLI扩展机制这是项目的基石。Gemini CLI从某个版本开始支持extensions扩展允许用户安装第三方功能包。安装命令gemini extensions install repo_url本质上是从一个Git仓库拉取一个符合特定规范的包。这个包通常包含一个gemini-extension.json的清单文件描述了扩展的元信息名称、版本、命令列表等以及具体的命令实现文件通常是.py或.js文件。本项目就是这样一个符合规范的扩展包。第二层自定义命令Custom Commands这是项目最主要的功能呈现形式。在gemini-extension.json中你会看到一系列commands的定义。每个命令都有名称如/code:pda。这里的命名空间code:和命令名pda提供了清晰的分类。描述简短说明命令的用途。执行器指向实际处理该命令的脚本文件路径。参数定义命令可以接受哪些输入参数。当你在终端输入gemini /code:pda时CLI会定位到这个扩展找到对应的执行器脚本运行它。这个脚本会负责收集上下文可能是当前目录的文件、环境变量等构造发送给Gemini API的提示词处理API的返回结果并以友好的格式呈现给你。第三层Agent技能Agent Skills这是更高级的概念在项目后期版本引入。根据Gemini CLI的官方文档“技能”是比“命令”更强大、更自治的一种能力。你可以把“命令”看作一个需要你手动触发的一次性脚本而“技能”则是可以被AI Agent在自主执行复杂任务时主动调用的“工具”或“函数”。例如一个计划写作的Agent在需要检查更新时可以主动调用pcc-check-for-updates这个技能。项目中的技能如cloud-build-investigation通常实现为独立的、功能更专注的模块。它们的设计更强调接口的明确性和结果的机器可读性以便被Agent无缝集成。这代表了AI集成从“人驱动”向“AI自主驱动”的演进方向。2.3 技术选型与实现语言翻看项目的源码目录你会发现一个有趣的现象大部分命令和技能是用Ruby编写的文件后缀为.rb。这与许多以Python为中心的AI生态项目形成了对比。作者选择Ruby我推测有几个原因个人/团队熟悉度这是最重要的因素。使用最熟悉的语言能极大提升开发效率和代码质量。作者Palladius的GitHub简介显示他是一名“Staff Developer Relations Engineer at Google”并且有其他Ruby项目说明Ruby是他的主力语言之一。脚本语言的便利性Ruby和Python一样非常适合编写胶水脚本处理文本、调用系统命令、解析JSON/XML等任务非常方便这正是这些AI命令脚本需要做的核心工作。Gemini CLI的开放性Gemini CLI的扩展机制似乎没有强制规定语言只要最终能通过gemini命令调用即可这给了开发者选择自由。命令脚本的开头通常有#!/usr/bin/env ruby的shebang行确保了可执行性。注意对于想要借鉴此项目开发自己扩展的开发者来说这里的关键启示是不必拘泥于某种特定语言。你可以用Python、Node.js、Go甚至Bash来编写你的命令执行器。核心在于你的脚本能正确接收CLI传递的参数与Gemini API或通过CLI封装交互并返回格式化的结果。项目的结构提供了一个清晰的范本。3. 核心命令深度解析与实战指南这个扩展包包含了从代码开发到运维的多个场景命令。我们挑几个最具代表性、最实用的来深入剖析其原理和用法。3.1/code:pda- 结构化的代码生成工作流这是我认为最具工程思维的一个命令。PDA代表Plan计划, Define定义, Act执行。它不是一个简单的“给我写个XX函数”的命令而是强制你遵循一个严谨的软件设计流程。工作原理拆解Plan阶段当你运行gemini /code:pda时它会首先要求你描述你想要构建什么。然后AI不会直接去写代码而是生成一个实现计划。这个计划可能包括模块划分、关键数据结构设计、API接口定义、潜在的难点和风险。这相当于在编码前先进行高层设计评审。Define阶段基于上一步的计划AI会引导你或自动生成更详细的规格定义。这可能包括函数签名、类图用文字描述、关键算法的伪代码、测试用例描述等。目标是让“要做什么”变得极其清晰无二义性。Act阶段只有当前两步都明确后AI才会生成实际的、可运行的代码。并且代码会包含详细的注释甚至可能附带简单的使用示例。实战示例与心得假设我需要一个Python函数用来安全地删除一个目录及其所有内容但要比shutil.rmtree更安全比如检查目录是否在某个白名单外。# 在终端中执行 $ gemini /code:pda # 随后进入交互流程Plan提示时我会输入“我需要一个安全的目录删除工具函数用于Python脚本。核心需求是防止误删关键系统目录可配置排除列表删除前最好有确认或日志兼容Linux/macOS。”AI在Plan阶段可能会回复一个概要比如“将设计一个SafeDirectoryRemover类。包含1. 初始化时设置黑名单/白名单。2.remove方法执行安全检查。3. 安全检查包括路径解析、与系统关键路径对比、与用户排除列表对比。4. 提供同步/异步删除选项。5. 记录详细日志。”在Define阶段AI可能会给出类的骨架和主要方法签名。最终在Act阶段生成完整的Python代码。实操心得/code:pda的价值在于过程管理。它迫使你在“提需求”和“拿代码”之间加入思考和设计的环节这对于生成复杂、高质量的代码至关重要。直接让AI生成复杂代码往往需要多轮调试而PDA流程通过前置的设计沟通一次生成正确代码的概率大大增加。对于团队协作这个流程产生的“计划”和“定义”文档本身也是宝贵的知识沉淀。3.2/git:commit_push- 自动化Git工作流这是一个能显著提升日常开发效率的命令。我们每天要执行很多次git add,git commit -m “...”,git push。这个命令旨在自动化这个过程并利用AI生成更规范的提交信息。工作原理拆解状态收集脚本首先会运行git status --porcelain和git diff --staged如果已暂存或git diff如果未暂存获取当前工作区的变更摘要。AI分析将变更摘要文件列表、差异内容发送给Gemini并提示它“根据以下的git变更生成一条符合约定式提交Conventional Commits规范的提交信息。格式为type(scope): subject。类型可以是feat, fix, docs, style, refactor, test, chore等。请使主题行简洁明了。”交互确认将AI生成的提交信息呈现给用户确认或编辑。执行操作根据用户确认执行git commit -m “...”。如果配置了还可以继续执行git push。实战示例与心得# 假设你刚修改了src/utils/logger.py修复了一个bug并添加了tests/test_logger.py $ git add . $ gemini /git:commit_push # CLI可能会显示 # 检测到以下变更 # M src/utils/logger.py # A tests/test_logger.py # # AI生成的提交信息 # fix(logger): correct timestamp formatting in debug output # # 添加测试用例以覆盖边界条件。 # # 是否使用此信息提交[Y/n/e] (e为编辑)输入Y提交完成。如果你还希望在提交后自动推送到当前分支可能需要在命令后加参数如gemini /git:commit_push --push这取决于命令的具体实现。注意事项隐私与安全这个命令会将你的代码差异发送给Gemini API。切勿在包含敏感信息密码、密钥、未公开的商业逻辑的代码库中使用。对于公司项目务必确认符合公司的AI使用和数据安全政策。网络依赖提交过程需要调用AI API如果网络不佳会阻塞你的本地操作。习惯培养它生成的约定式提交信息很棒但前提是你的团队也遵循这个规范。否则你可能需要手动编辑或调整提示词模板。备用方案我个人的习惯是对于非常琐碎的修改我仍然会用快速的git commit -m “wip”而对于有明确改动的提交则使用这个命令来获得更清晰的记录。两者结合使用。3.3/common:find_todos- 代码库待办事项管理这是一个简单的“扫描-分析”类命令展示了如何将AI用于代码库的静态分析。工作原理拆解文件扫描脚本使用find或grep -r命令在指定目录默认为当前目录中递归搜索包含TODO、FIXME、XXX、HACK等常见注释标记的代码行。上下文聚合它不只是找到行还会抓取标记所在文件的路径、行号以及标记周围的几行代码作为上下文。AI分类与解释将所有这些“待办项”条目发送给Gemini要求它对每个TODO进行分类如功能增强、缺陷修复、重构、性能优化、技术债并尝试解释或补充这个待办项的具体任务可能是什么。格式化输出将结果以清晰的表格或列表形式输出方便你快速评估代码库中的技术债务。实战示例$ gemini /common:find_todos --path ./src输出可能类似于在 ./src 中共发现 12 个待办项 1. [优化] ./src/api/client.py:45 # TODO: 请求超时设置需要根据网络环境动态调整 AI解读建议实现一个自适应超时算法或从配置中心读取超时配置。 2. [缺陷] ./src/utils/validation.py:102 # FIXME: 边界条件未处理当输入为null时可能崩溃 AI解读应在函数开头添加 if input is None: return default_value 或抛出明确的异常。 3. [重构] ./src/legacy/module.py:23 # HACK: 绕过权限检查因为旧系统兼容性问题下个版本必须重构 AI解读此临时解决方案存在安全风险。建议制定重构计划将新旧权限系统解耦。实操心得这个命令的价值在于将散落的、模糊的注释转化为可管理的任务清单。很多TODO写得含糊不清时间久了连作者都忘了要做什么。AI的解读能帮你重新理解当时的意图。你可以将此命令的输出导入到项目管理工具如Jira, Linear中创建对应的任务卡。建议定期如每两周运行一次作为技术债梳理的例行工作。3.4/gcp:cloud_build_investigation- 云原生调试助手这是一个面向Google Cloud Platform用户的专业级命令尤其适用于SRE和开发者。当Cloud Build构建失败或Cloud Run服务出现问题时查看日志控制台可能信息过载。这个命令旨在扮演一个“专家分析助手”的角色。工作原理拆解基于其技能描述推测输入引导命令可能会要求你提供失败构建的ID、Cloud Run服务名称、项目ID以及时间范围。数据获取脚本在后台使用gcloud命令行工具自动获取相关的构建日志、部署日志、服务配置信息。例如运行gcloud builds log [BUILD_ID]或gcloud run services describe [SERVICE_NAME]。AI智能分析将获取到的原始日志和配置数据可能是很长很乱的文本发送给Gemini。提示词会指示AI“你是一个Google Cloud SRE专家。请分析以下Cloud Build失败日志/Cloud Run服务描述找出最可能的根本原因。按可能性排序列出原因并对每个原因提供证据引用日志行和具体的修复建议。”结构化报告AI返回一个结构化的分析报告包括根本原因、相关日志片段、修复步骤甚至可能给出预防再次发生的建议如修改cloudbuild.yaml配置。实战场景模拟$ gemini /gcp:cloud_build_investigation # 交互提示 # 请输入GCP项目ID: my-awesome-project # 请输入Cloud Build构建ID: 1234-abcd-5678 # 正在获取日志... # 分析中...输出报告可能如下**分析报告构建失败 #1234-abcd-5678** **根本原因可能性最高依赖项权限不足** - **证据**日志第234行显示 ERROR: (gcloud.builds.submit) PERMISSION_DENIED: The caller does not have permission to access artifact registry... - **修复**为Cloud Build服务账号添加 roles/artifactregistry.writer 角色。 gcloud projects add-iam-policy-binding my-awesome-project --memberserviceAccount:[SERVICE_ACCOUNT_EMAIL] --roleroles/artifactregistry.writer **其他可能原因** - Dockerfile中基础镜像不存在...注意事项这类命令威力巨大但高度依赖执行环境。你需要在本地安装并配置好gcloudCLI且已通过gcloud auth login登录并设置默认项目。当前账号或gcloud配置的账号必须有足够的GCP权限来读取构建日志和服务信息。同样需要注意构建日志可能包含内部代码或配置信息需确保符合公司安全规定。4. 安装、配置与高级使用指南4.1 一步步完成安装与验证安装过程在README中已经给出但有些细节值得展开。第一步环境前置检查确保你的Gemini CLI版本至少是0.4.0。这是扩展功能支持的起始版本。gemini -v # 输出应类似gemini version 0.5.1 # 如果版本过低请参考官方文档升级。第二步执行安装命令gemini extensions install https://github.com/palladius/gemini-cli-custom-commands这个命令会克隆指定的GitHub仓库到本地的Gemini CLI扩展目录通常位于~/.config/gemini/extensions/或类似位置。解析仓库中的gemini-extension.json文件注册其中定义的所有命令。如果扩展有依赖比如某些Ruby gem它可能会尝试安装但根据我的经验这类脚本扩展通常将依赖打包或使用系统自带环境具体要看扩展的实现。第三步验证安装成功安装后你可以通过以下方式验证# 方法1查看已安装的扩展列表 gemini extensions list # 你应该能在列表中看到 palladius-common-commands 或类似名称。 # 方法2直接尝试运行一个命令查看帮助 gemini /code:pda --help # 或者新的Gemini CLI可能支持查看扩展命令 gemini --help | grep “palladius”第四步更新与卸载# 更新特定扩展 gemini extensions update palladius-common-commands # 更新所有已安装扩展 gemini extensions update --all # 卸载扩展 gemini extensions uninstall palladius-common-commands4.2 配置与个性化调整默认安装后命令即可使用。但高级用户可能希望进行个性化命令别名如果你觉得/code:pda太长可以尝试在Shell配置文件中如~/.bashrc或~/.zshrc为其创建别名。但注意这需要别名能正确传递参数可能比较复杂。更简单的方法是适应这种命名空间风格。修改默认参数有些命令可能支持环境变量或配置文件来修改默认行为。例如/common:find_todos可能允许你通过环境变量设置要扫描的注释标签TODO,FIXME等。这需要你查阅具体命令的源码或文档在项目的docs/USER_MANUAL.md中。API模型与参数这些命令底层调用的是Gemini API。Gemini CLI本身通常有配置来设置默认的AI模型如gemini-1.5-pro和API端点。你可以通过gemini config来查看和修改这些全局设置这会影响所有扩展命令使用的AI能力。4.3 将扩展命令融入日常工作流单纯安装命令还不够关键在于如何让它成为你肌肉记忆的一部分。场景绑定将特定命令与你的开发阶段绑定。例如每次完成一个功能模块后习惯性地运行/git:commit_push。在开始一项新编码任务前先运行/code:pda来梳理思路。Shell集成虽然不直接创建别名但你可以编写一些简单的Shell包装函数。例如创建一个名为gptodo的函数里面调用gemini /common:find_todos $这样输入更快捷。与IDE/编辑器结合许多现代编辑器如VSCode支持绑定终端命令到快捷键。你可以将为当前文件运行代码检查或生成测试的命令绑定到CtrlShiftT等快捷键上。不过这需要你的命令支持处理当前文件路径作为参数。团队推广如果你觉得某个命令如/git:commit_push生成的提交信息规范对团队有益可以在团队内部分享这个扩展的安装方法甚至基于此定制你们团队自己的扩展统一提交规范。5. 常见问题、故障排查与进阶思考5.1 安装与运行常见问题问题现象可能原因排查与解决步骤gemini extensions install失败报网络错误1. GitHub访问问题2. Gemini CLI版本过低3. 本地扩展目录权限不足1. 检查网络连接尝试ping github.com。2. 确认gemini -v版本≥0.4.0。3. 检查~/.config/gemini/目录的读写权限。安装成功但运行命令时提示command not found1. 扩展未正确注册2. 命令名称输入错误1. 运行gemini extensions list确认扩展存在。2. 运行gemini --help查看所有可用命令确认命令的完整名称注意大小写和冒号。3. 尝试重启终端或重新安装扩展。命令执行时报Ruby相关错误如require’: cannot load such file)扩展依赖的Ruby库未安装1. 查看错误信息确定缺失的gem名称如json,yaml。2. 使用gem install gem_name安装缺失的库。通常基础库如json是Ruby标准库的一部分如果缺失可能是Ruby环境不完整考虑重装Ruby或使用RVM/rbenv管理。命令执行卡住或超时1. Gemini API调用超时2. 命令脚本陷入死循环3. 网络问题1. 检查网络特别是能否访问Google AI Studio API。2. 尝试运行一个更简单的原生gemini对话看API是否正常。3. 对于可能长时间运行的命令如扫描大代码库查看其源码是否有超时设置或进度提示。AI返回的结果质量不佳或不符合预期1. 命令的提示词模板可能不适合你的具体场景2. 输入的上下文信息不足或有误1. 这是使用任何AI工具都会遇到的问题。尝试更精确地描述你的需求。2. 对于某些命令如/git:commit_push确保你在正确的git仓库目录下执行并且变更已暂存(git add)。3. 考虑克隆该扩展的仓库本地修改命令脚本中的提示词模板进阶操作使其更符合你的偏好。5.2 安全与隐私考量再强调这是一个第三方社区扩展不是Google官方出品。虽然作者是Google员工但项目明确标注“仅用于演示目的不适用于生产环境”。在使用时你必须清醒地认识到代码审计如果你在高度敏感的环境中使用理想情况下应该审查你计划使用的每一个命令的源代码都在GitHub仓库里了解它具体执行了什么操作、发送了什么数据。数据泄露风险任何将本地数据代码、日志、文件列表发送到云端AI服务的命令都存在潜在的数据泄露风险。绝对不要在包含商业秘密、个人身份信息、密钥或任何非公开信息的上下文中使用。权限最小化像/gcp:cloud_build_investigation这类命令它会调用gcloud命令。确保你当前gcloud认证的账号只拥有完成该任务所需的最小权限如仅logs.viewer而不是拥有项目所有权的超级管理员账号。5.3 从使用者到贡献者如何定制自己的命令这个项目最大的启发在于它展示了一种模式。当你熟悉了它的用法后很可能会想“这个命令很好但如果它能再帮我做XXX就更好了”或者“我们团队有个特定流程能不能也封装成一个命令”定制路径模仿与修改最直接的方式是Fork这个GitHub仓库。在本地副本中找到一个与你需求类似的命令例如你想做一个/docker:build_optimize来优化Dockerfile。复制它的脚本文件如commands/git/commit_push.rb修改其中的提示词逻辑、上下文获取方式比如从解析Dockerfile变成解析docker-compose.yml然后在gemini-extension.json中注册你的新命令。从头创建你可以创建一个全新的扩展仓库。只需要遵循Gemini CLI扩展的规范一个gemini-extension.json文件以及对应的命令脚本。官方文档和本项目都是绝佳的参考。分享与反馈如果你制作了一个对他人也有用的命令可以考虑向原项目提交Pull Request或者在自己的圈子内分享。开源社区的活力正来源于此。5.4 未来展望Agent技能与自动化项目后期引入的“Agent技能”指向了更未来的方向。目前我们是在主动调用命令是“人驱动AI”。而技能是为“AI驱动AI”准备的。想象一下你给Gemini CLI一个高级目标“为我的项目制定下个季度的开发计划并生成初步的代码框架”。一个具备规划能力的Agent可以自主调用/common:find_todos来评估技术债调用/plan:do来分解任务甚至调用/code:pda来为关键模块生成代码草稿。虽然当前这些技能还在早期阶段且项目的部分技能也已迁移到其他官方扩展但这清晰地勾勒了AI集成进开发工作流的终极形态从被动的工具变为主动的、理解上下文的协作伙伴。palladius/gemini-cli-custom-commands项目无论是作为一套现成的效率工具还是作为一个如何将AI能力“产品化”为命令行接口的杰出范例都为我们迈向下一个阶段提供了宝贵的跳板和灵感。
Gemini CLI自定义命令扩展：提升AI命令行效率的工程实践
1. 项目概述一个为Gemini CLI深度定制的命令集如果你和我一样日常重度依赖命令行并且最近开始尝试用Gemini CLI来提升工作效率那你可能已经发现了一个痛点原生的命令虽然强大但总感觉少了点“私人订制”的味道。那些重复性的、特定于你个人工作流的任务每次都要手动输入冗长的提示词或者在不同的工具间来回切换效率瓶颈很快就出现了。今天要聊的这个项目——palladius/gemini-cli-custom-commands就是来解决这个问题的。它不是一个独立的工具而是一个Gemini CLI的扩展包你可以把它理解为一套由社区开发者主要是项目作者Palladius精心打磨的“快捷指令集”或“技能包”。它的核心价值在于将一系列复杂、多步骤的AI驱动任务封装成一个个简单易记的命令让你在终端里敲几个单词就能调用Gemini完成特定工作。简单来说安装了这个扩展你的gemini命令就获得了一堆超能力。比如你想让AI帮你分析代码库里的所有TODO注释不用再费心组织提示词直接输入/common:find_todos就行或者你需要遵循一个严谨的“计划-定义-执行”流程来生成代码/code:pda命令已经为你搭建好了框架。它把最佳实践和常用场景固化成命令让你能更专注在问题本身而不是与AI的沟通方式上。这个项目特别适合几类人开发者和DevRel开发者关系工程师因为它包含了大量与代码、文档、Git、云平台GCP相关的自动化命令SRE站点可靠性工程师虽然部分功能已迁移但其思路对自动化运维很有启发以及所有希望将AI更深度、更结构化地融入自己命令行工作流的效率追求者。接下来我会带你深入拆解这个项目的设计思路、核心命令的实战用法并分享我在集成和使用过程中的一系列经验与踩过的坑。2. 核心设计思路与架构解析2.1 为什么需要自定义命令从“对话”到“执行”的范式转变在深入代码之前我们得先想明白一个问题用Gemini CLI直接对话不香吗为什么还要搞一套自定义命令这背后其实是一种工作范式的转变。原始模式对话式你有一个需求 - 你在脑中构思如何向AI描述 - 你输入一段可能很冗长且不精确的提示词 - AI返回结果 - 你可能需要多轮交互来修正。这个过程充满了不确定性并且难以复用。比如每次代码审查你都得重新描述一遍你的代码风格偏好。自定义命令模式执行式你有一个明确定义的任务类型 - 你调用一个对应的、预先定义好的命令 - 命令背后是一套精心设计的提示词模板、上下文获取逻辑和输出处理流程 - AI基于这个“标准化流程”返回结果。这就像为你常用的复杂操作编写了一个Shell脚本或函数只不过这个脚本的“核心逻辑”是由AI驱动的。palladius/gemini-cli-custom-commands项目就是基于后一种思路。它的目标不是替代gemini的通用对话能力而是对其能力进行场景化、产品化的封装。每个命令都对应一个具体的、高频的“工作流”。这种设计带来了几个显著优势一致性对于相同类型的任务如生成Git提交信息每次都能遵循相同的逻辑和标准输出质量稳定。效率省去了反复构思和输入通用提示词的时间一键触发复杂流程。集成度命令可以直接与你的工作环境交互如读取当前git状态、扫描文件系统让AI的上下文更精准。可分享性一套好的命令集可以成为团队或社区的共享资产统一工作方式。2.2 项目架构扩展、命令与技能的层次浏览项目的README和源码结构我们可以梳理出它的三层架构这有助于我们理解其运作方式。第一层Gemini CLI扩展机制这是项目的基石。Gemini CLI从某个版本开始支持extensions扩展允许用户安装第三方功能包。安装命令gemini extensions install repo_url本质上是从一个Git仓库拉取一个符合特定规范的包。这个包通常包含一个gemini-extension.json的清单文件描述了扩展的元信息名称、版本、命令列表等以及具体的命令实现文件通常是.py或.js文件。本项目就是这样一个符合规范的扩展包。第二层自定义命令Custom Commands这是项目最主要的功能呈现形式。在gemini-extension.json中你会看到一系列commands的定义。每个命令都有名称如/code:pda。这里的命名空间code:和命令名pda提供了清晰的分类。描述简短说明命令的用途。执行器指向实际处理该命令的脚本文件路径。参数定义命令可以接受哪些输入参数。当你在终端输入gemini /code:pda时CLI会定位到这个扩展找到对应的执行器脚本运行它。这个脚本会负责收集上下文可能是当前目录的文件、环境变量等构造发送给Gemini API的提示词处理API的返回结果并以友好的格式呈现给你。第三层Agent技能Agent Skills这是更高级的概念在项目后期版本引入。根据Gemini CLI的官方文档“技能”是比“命令”更强大、更自治的一种能力。你可以把“命令”看作一个需要你手动触发的一次性脚本而“技能”则是可以被AI Agent在自主执行复杂任务时主动调用的“工具”或“函数”。例如一个计划写作的Agent在需要检查更新时可以主动调用pcc-check-for-updates这个技能。项目中的技能如cloud-build-investigation通常实现为独立的、功能更专注的模块。它们的设计更强调接口的明确性和结果的机器可读性以便被Agent无缝集成。这代表了AI集成从“人驱动”向“AI自主驱动”的演进方向。2.3 技术选型与实现语言翻看项目的源码目录你会发现一个有趣的现象大部分命令和技能是用Ruby编写的文件后缀为.rb。这与许多以Python为中心的AI生态项目形成了对比。作者选择Ruby我推测有几个原因个人/团队熟悉度这是最重要的因素。使用最熟悉的语言能极大提升开发效率和代码质量。作者Palladius的GitHub简介显示他是一名“Staff Developer Relations Engineer at Google”并且有其他Ruby项目说明Ruby是他的主力语言之一。脚本语言的便利性Ruby和Python一样非常适合编写胶水脚本处理文本、调用系统命令、解析JSON/XML等任务非常方便这正是这些AI命令脚本需要做的核心工作。Gemini CLI的开放性Gemini CLI的扩展机制似乎没有强制规定语言只要最终能通过gemini命令调用即可这给了开发者选择自由。命令脚本的开头通常有#!/usr/bin/env ruby的shebang行确保了可执行性。注意对于想要借鉴此项目开发自己扩展的开发者来说这里的关键启示是不必拘泥于某种特定语言。你可以用Python、Node.js、Go甚至Bash来编写你的命令执行器。核心在于你的脚本能正确接收CLI传递的参数与Gemini API或通过CLI封装交互并返回格式化的结果。项目的结构提供了一个清晰的范本。3. 核心命令深度解析与实战指南这个扩展包包含了从代码开发到运维的多个场景命令。我们挑几个最具代表性、最实用的来深入剖析其原理和用法。3.1/code:pda- 结构化的代码生成工作流这是我认为最具工程思维的一个命令。PDA代表Plan计划, Define定义, Act执行。它不是一个简单的“给我写个XX函数”的命令而是强制你遵循一个严谨的软件设计流程。工作原理拆解Plan阶段当你运行gemini /code:pda时它会首先要求你描述你想要构建什么。然后AI不会直接去写代码而是生成一个实现计划。这个计划可能包括模块划分、关键数据结构设计、API接口定义、潜在的难点和风险。这相当于在编码前先进行高层设计评审。Define阶段基于上一步的计划AI会引导你或自动生成更详细的规格定义。这可能包括函数签名、类图用文字描述、关键算法的伪代码、测试用例描述等。目标是让“要做什么”变得极其清晰无二义性。Act阶段只有当前两步都明确后AI才会生成实际的、可运行的代码。并且代码会包含详细的注释甚至可能附带简单的使用示例。实战示例与心得假设我需要一个Python函数用来安全地删除一个目录及其所有内容但要比shutil.rmtree更安全比如检查目录是否在某个白名单外。# 在终端中执行 $ gemini /code:pda # 随后进入交互流程Plan提示时我会输入“我需要一个安全的目录删除工具函数用于Python脚本。核心需求是防止误删关键系统目录可配置排除列表删除前最好有确认或日志兼容Linux/macOS。”AI在Plan阶段可能会回复一个概要比如“将设计一个SafeDirectoryRemover类。包含1. 初始化时设置黑名单/白名单。2.remove方法执行安全检查。3. 安全检查包括路径解析、与系统关键路径对比、与用户排除列表对比。4. 提供同步/异步删除选项。5. 记录详细日志。”在Define阶段AI可能会给出类的骨架和主要方法签名。最终在Act阶段生成完整的Python代码。实操心得/code:pda的价值在于过程管理。它迫使你在“提需求”和“拿代码”之间加入思考和设计的环节这对于生成复杂、高质量的代码至关重要。直接让AI生成复杂代码往往需要多轮调试而PDA流程通过前置的设计沟通一次生成正确代码的概率大大增加。对于团队协作这个流程产生的“计划”和“定义”文档本身也是宝贵的知识沉淀。3.2/git:commit_push- 自动化Git工作流这是一个能显著提升日常开发效率的命令。我们每天要执行很多次git add,git commit -m “...”,git push。这个命令旨在自动化这个过程并利用AI生成更规范的提交信息。工作原理拆解状态收集脚本首先会运行git status --porcelain和git diff --staged如果已暂存或git diff如果未暂存获取当前工作区的变更摘要。AI分析将变更摘要文件列表、差异内容发送给Gemini并提示它“根据以下的git变更生成一条符合约定式提交Conventional Commits规范的提交信息。格式为type(scope): subject。类型可以是feat, fix, docs, style, refactor, test, chore等。请使主题行简洁明了。”交互确认将AI生成的提交信息呈现给用户确认或编辑。执行操作根据用户确认执行git commit -m “...”。如果配置了还可以继续执行git push。实战示例与心得# 假设你刚修改了src/utils/logger.py修复了一个bug并添加了tests/test_logger.py $ git add . $ gemini /git:commit_push # CLI可能会显示 # 检测到以下变更 # M src/utils/logger.py # A tests/test_logger.py # # AI生成的提交信息 # fix(logger): correct timestamp formatting in debug output # # 添加测试用例以覆盖边界条件。 # # 是否使用此信息提交[Y/n/e] (e为编辑)输入Y提交完成。如果你还希望在提交后自动推送到当前分支可能需要在命令后加参数如gemini /git:commit_push --push这取决于命令的具体实现。注意事项隐私与安全这个命令会将你的代码差异发送给Gemini API。切勿在包含敏感信息密码、密钥、未公开的商业逻辑的代码库中使用。对于公司项目务必确认符合公司的AI使用和数据安全政策。网络依赖提交过程需要调用AI API如果网络不佳会阻塞你的本地操作。习惯培养它生成的约定式提交信息很棒但前提是你的团队也遵循这个规范。否则你可能需要手动编辑或调整提示词模板。备用方案我个人的习惯是对于非常琐碎的修改我仍然会用快速的git commit -m “wip”而对于有明确改动的提交则使用这个命令来获得更清晰的记录。两者结合使用。3.3/common:find_todos- 代码库待办事项管理这是一个简单的“扫描-分析”类命令展示了如何将AI用于代码库的静态分析。工作原理拆解文件扫描脚本使用find或grep -r命令在指定目录默认为当前目录中递归搜索包含TODO、FIXME、XXX、HACK等常见注释标记的代码行。上下文聚合它不只是找到行还会抓取标记所在文件的路径、行号以及标记周围的几行代码作为上下文。AI分类与解释将所有这些“待办项”条目发送给Gemini要求它对每个TODO进行分类如功能增强、缺陷修复、重构、性能优化、技术债并尝试解释或补充这个待办项的具体任务可能是什么。格式化输出将结果以清晰的表格或列表形式输出方便你快速评估代码库中的技术债务。实战示例$ gemini /common:find_todos --path ./src输出可能类似于在 ./src 中共发现 12 个待办项 1. [优化] ./src/api/client.py:45 # TODO: 请求超时设置需要根据网络环境动态调整 AI解读建议实现一个自适应超时算法或从配置中心读取超时配置。 2. [缺陷] ./src/utils/validation.py:102 # FIXME: 边界条件未处理当输入为null时可能崩溃 AI解读应在函数开头添加 if input is None: return default_value 或抛出明确的异常。 3. [重构] ./src/legacy/module.py:23 # HACK: 绕过权限检查因为旧系统兼容性问题下个版本必须重构 AI解读此临时解决方案存在安全风险。建议制定重构计划将新旧权限系统解耦。实操心得这个命令的价值在于将散落的、模糊的注释转化为可管理的任务清单。很多TODO写得含糊不清时间久了连作者都忘了要做什么。AI的解读能帮你重新理解当时的意图。你可以将此命令的输出导入到项目管理工具如Jira, Linear中创建对应的任务卡。建议定期如每两周运行一次作为技术债梳理的例行工作。3.4/gcp:cloud_build_investigation- 云原生调试助手这是一个面向Google Cloud Platform用户的专业级命令尤其适用于SRE和开发者。当Cloud Build构建失败或Cloud Run服务出现问题时查看日志控制台可能信息过载。这个命令旨在扮演一个“专家分析助手”的角色。工作原理拆解基于其技能描述推测输入引导命令可能会要求你提供失败构建的ID、Cloud Run服务名称、项目ID以及时间范围。数据获取脚本在后台使用gcloud命令行工具自动获取相关的构建日志、部署日志、服务配置信息。例如运行gcloud builds log [BUILD_ID]或gcloud run services describe [SERVICE_NAME]。AI智能分析将获取到的原始日志和配置数据可能是很长很乱的文本发送给Gemini。提示词会指示AI“你是一个Google Cloud SRE专家。请分析以下Cloud Build失败日志/Cloud Run服务描述找出最可能的根本原因。按可能性排序列出原因并对每个原因提供证据引用日志行和具体的修复建议。”结构化报告AI返回一个结构化的分析报告包括根本原因、相关日志片段、修复步骤甚至可能给出预防再次发生的建议如修改cloudbuild.yaml配置。实战场景模拟$ gemini /gcp:cloud_build_investigation # 交互提示 # 请输入GCP项目ID: my-awesome-project # 请输入Cloud Build构建ID: 1234-abcd-5678 # 正在获取日志... # 分析中...输出报告可能如下**分析报告构建失败 #1234-abcd-5678** **根本原因可能性最高依赖项权限不足** - **证据**日志第234行显示 ERROR: (gcloud.builds.submit) PERMISSION_DENIED: The caller does not have permission to access artifact registry... - **修复**为Cloud Build服务账号添加 roles/artifactregistry.writer 角色。 gcloud projects add-iam-policy-binding my-awesome-project --memberserviceAccount:[SERVICE_ACCOUNT_EMAIL] --roleroles/artifactregistry.writer **其他可能原因** - Dockerfile中基础镜像不存在...注意事项这类命令威力巨大但高度依赖执行环境。你需要在本地安装并配置好gcloudCLI且已通过gcloud auth login登录并设置默认项目。当前账号或gcloud配置的账号必须有足够的GCP权限来读取构建日志和服务信息。同样需要注意构建日志可能包含内部代码或配置信息需确保符合公司安全规定。4. 安装、配置与高级使用指南4.1 一步步完成安装与验证安装过程在README中已经给出但有些细节值得展开。第一步环境前置检查确保你的Gemini CLI版本至少是0.4.0。这是扩展功能支持的起始版本。gemini -v # 输出应类似gemini version 0.5.1 # 如果版本过低请参考官方文档升级。第二步执行安装命令gemini extensions install https://github.com/palladius/gemini-cli-custom-commands这个命令会克隆指定的GitHub仓库到本地的Gemini CLI扩展目录通常位于~/.config/gemini/extensions/或类似位置。解析仓库中的gemini-extension.json文件注册其中定义的所有命令。如果扩展有依赖比如某些Ruby gem它可能会尝试安装但根据我的经验这类脚本扩展通常将依赖打包或使用系统自带环境具体要看扩展的实现。第三步验证安装成功安装后你可以通过以下方式验证# 方法1查看已安装的扩展列表 gemini extensions list # 你应该能在列表中看到 palladius-common-commands 或类似名称。 # 方法2直接尝试运行一个命令查看帮助 gemini /code:pda --help # 或者新的Gemini CLI可能支持查看扩展命令 gemini --help | grep “palladius”第四步更新与卸载# 更新特定扩展 gemini extensions update palladius-common-commands # 更新所有已安装扩展 gemini extensions update --all # 卸载扩展 gemini extensions uninstall palladius-common-commands4.2 配置与个性化调整默认安装后命令即可使用。但高级用户可能希望进行个性化命令别名如果你觉得/code:pda太长可以尝试在Shell配置文件中如~/.bashrc或~/.zshrc为其创建别名。但注意这需要别名能正确传递参数可能比较复杂。更简单的方法是适应这种命名空间风格。修改默认参数有些命令可能支持环境变量或配置文件来修改默认行为。例如/common:find_todos可能允许你通过环境变量设置要扫描的注释标签TODO,FIXME等。这需要你查阅具体命令的源码或文档在项目的docs/USER_MANUAL.md中。API模型与参数这些命令底层调用的是Gemini API。Gemini CLI本身通常有配置来设置默认的AI模型如gemini-1.5-pro和API端点。你可以通过gemini config来查看和修改这些全局设置这会影响所有扩展命令使用的AI能力。4.3 将扩展命令融入日常工作流单纯安装命令还不够关键在于如何让它成为你肌肉记忆的一部分。场景绑定将特定命令与你的开发阶段绑定。例如每次完成一个功能模块后习惯性地运行/git:commit_push。在开始一项新编码任务前先运行/code:pda来梳理思路。Shell集成虽然不直接创建别名但你可以编写一些简单的Shell包装函数。例如创建一个名为gptodo的函数里面调用gemini /common:find_todos $这样输入更快捷。与IDE/编辑器结合许多现代编辑器如VSCode支持绑定终端命令到快捷键。你可以将为当前文件运行代码检查或生成测试的命令绑定到CtrlShiftT等快捷键上。不过这需要你的命令支持处理当前文件路径作为参数。团队推广如果你觉得某个命令如/git:commit_push生成的提交信息规范对团队有益可以在团队内部分享这个扩展的安装方法甚至基于此定制你们团队自己的扩展统一提交规范。5. 常见问题、故障排查与进阶思考5.1 安装与运行常见问题问题现象可能原因排查与解决步骤gemini extensions install失败报网络错误1. GitHub访问问题2. Gemini CLI版本过低3. 本地扩展目录权限不足1. 检查网络连接尝试ping github.com。2. 确认gemini -v版本≥0.4.0。3. 检查~/.config/gemini/目录的读写权限。安装成功但运行命令时提示command not found1. 扩展未正确注册2. 命令名称输入错误1. 运行gemini extensions list确认扩展存在。2. 运行gemini --help查看所有可用命令确认命令的完整名称注意大小写和冒号。3. 尝试重启终端或重新安装扩展。命令执行时报Ruby相关错误如require’: cannot load such file)扩展依赖的Ruby库未安装1. 查看错误信息确定缺失的gem名称如json,yaml。2. 使用gem install gem_name安装缺失的库。通常基础库如json是Ruby标准库的一部分如果缺失可能是Ruby环境不完整考虑重装Ruby或使用RVM/rbenv管理。命令执行卡住或超时1. Gemini API调用超时2. 命令脚本陷入死循环3. 网络问题1. 检查网络特别是能否访问Google AI Studio API。2. 尝试运行一个更简单的原生gemini对话看API是否正常。3. 对于可能长时间运行的命令如扫描大代码库查看其源码是否有超时设置或进度提示。AI返回的结果质量不佳或不符合预期1. 命令的提示词模板可能不适合你的具体场景2. 输入的上下文信息不足或有误1. 这是使用任何AI工具都会遇到的问题。尝试更精确地描述你的需求。2. 对于某些命令如/git:commit_push确保你在正确的git仓库目录下执行并且变更已暂存(git add)。3. 考虑克隆该扩展的仓库本地修改命令脚本中的提示词模板进阶操作使其更符合你的偏好。5.2 安全与隐私考量再强调这是一个第三方社区扩展不是Google官方出品。虽然作者是Google员工但项目明确标注“仅用于演示目的不适用于生产环境”。在使用时你必须清醒地认识到代码审计如果你在高度敏感的环境中使用理想情况下应该审查你计划使用的每一个命令的源代码都在GitHub仓库里了解它具体执行了什么操作、发送了什么数据。数据泄露风险任何将本地数据代码、日志、文件列表发送到云端AI服务的命令都存在潜在的数据泄露风险。绝对不要在包含商业秘密、个人身份信息、密钥或任何非公开信息的上下文中使用。权限最小化像/gcp:cloud_build_investigation这类命令它会调用gcloud命令。确保你当前gcloud认证的账号只拥有完成该任务所需的最小权限如仅logs.viewer而不是拥有项目所有权的超级管理员账号。5.3 从使用者到贡献者如何定制自己的命令这个项目最大的启发在于它展示了一种模式。当你熟悉了它的用法后很可能会想“这个命令很好但如果它能再帮我做XXX就更好了”或者“我们团队有个特定流程能不能也封装成一个命令”定制路径模仿与修改最直接的方式是Fork这个GitHub仓库。在本地副本中找到一个与你需求类似的命令例如你想做一个/docker:build_optimize来优化Dockerfile。复制它的脚本文件如commands/git/commit_push.rb修改其中的提示词逻辑、上下文获取方式比如从解析Dockerfile变成解析docker-compose.yml然后在gemini-extension.json中注册你的新命令。从头创建你可以创建一个全新的扩展仓库。只需要遵循Gemini CLI扩展的规范一个gemini-extension.json文件以及对应的命令脚本。官方文档和本项目都是绝佳的参考。分享与反馈如果你制作了一个对他人也有用的命令可以考虑向原项目提交Pull Request或者在自己的圈子内分享。开源社区的活力正来源于此。5.4 未来展望Agent技能与自动化项目后期引入的“Agent技能”指向了更未来的方向。目前我们是在主动调用命令是“人驱动AI”。而技能是为“AI驱动AI”准备的。想象一下你给Gemini CLI一个高级目标“为我的项目制定下个季度的开发计划并生成初步的代码框架”。一个具备规划能力的Agent可以自主调用/common:find_todos来评估技术债调用/plan:do来分解任务甚至调用/code:pda来为关键模块生成代码草稿。虽然当前这些技能还在早期阶段且项目的部分技能也已迁移到其他官方扩展但这清晰地勾勒了AI集成进开发工作流的终极形态从被动的工具变为主动的、理解上下文的协作伙伴。palladius/gemini-cli-custom-commands项目无论是作为一套现成的效率工具还是作为一个如何将AI能力“产品化”为命令行接口的杰出范例都为我们迈向下一个阶段提供了宝贵的跳板和灵感。
