基于Gemini CLI的自定义斜杠命令：AI自动化终端工作流实战

1. 项目概述：用自定义斜杠命令重塑你的工作流

如果你和我一样，每天在终端里敲命令的时间比在社交软件上还多，那你肯定也幻想过：要是能像在聊天软件里打“/”调出快捷指令一样，在命令行里也能一键完成那些繁琐的日常任务，该有多好。比如，面对一堆杂乱无章的度假照片，不用再手动按日期重命名；或者，拿到一份满是数据的CSV文件，不用再打开Excel写公式，就能直接生成一份带分析的简报。这个幻想，现在通过amitkmaraj/gemini-cli-custom-slash-commands这个项目变成了现实。

简单来说，这是一个为 Google 的 Gemini CLI 工具集打造的、开箱即用的自定义斜杠命令库。它打包了10个高度实用的命令，覆盖了从通用办公到专业开发的多个场景。其核心价值在于，它将大语言模型的智能理解能力，封装成了一个个可以直接在终端里调用的、像ls或cd一样自然的命令。你不是在“询问”AI，而是在“使用”一个更智能的工具。这非常适合那些已经习惯命令行工作流，但又希望引入AI自动化来提升效率的开发者和技术从业者。接下来，我会带你深入拆解这10个命令的设计思路、实现原理，并分享如何将它们无缝集成到你自己的日常工作中去。

2. 核心命令深度解析与设计逻辑

这个项目将10个命令分成了两大类：通用工作流命令和开发者命令。这种分类本身就体现了其设计哲学——AI辅助工具应该渗透到工作的方方面面，而不仅仅是写代码。让我们逐一拆解每个命令背后的真实需求和设计考量。

2.1 通用工作流命令：从信息混乱到井然有序

这六个命令瞄准的是我们每天都会遇到，但又极其消耗心力的“杂事”。它们的价值不在于技术有多高深，而在于精准地解决了痛点。

/photo-rename- 智能照片整理器这个命令的灵感来源太普遍了：手机、相机导出的照片文件名通常是IMG_20241027_123456.jpg这样的乱码。手动整理？几百张照片足以让人崩溃。这个命令的聪明之处在于，它没有简单地按EXIF日期重命名（很多脚本都能做），而是基于视觉内容、日期和元数据进行智能重命名。这意味着，它可能会利用多模态模型“看懂”图片，将IMG_20241027_123456.jpg重命名为2024-10-27_beach_sunset_family.jpg。背后的逻辑是结合了图像识别、时间戳提取和自然语言生成，生成一个对人类友好、且包含语义信息的文件名，极大提升了日后检索的效率。

注意：这个命令的效果高度依赖于输入图片的元数据（EXIF）是否完整。如果是从微信等社交软件下载的、已被剥离元数据的图片，效果可能会打折扣。最佳实践是在导入设备后第一时间运行此命令。

/report-gen- 数据报告生成器数据分析的最后一公里往往是报告撰写。这个命令试图打通从“数据文件”到“见解报告”的自动化管道。它接收一个数据文件（如CSV、JSON），其内部流程很可能是：1. 自动推断数据结构；2. 执行基础统计分析（如平均值、趋势、异常值）；3. 根据数据特性生成文本描述和可视化建议（甚至可能调用图表生成库）。它解决的不是深度建模问题，而是快速生成数据初探报告，让你在向老板汇报前，先有一个结构清晰的草稿。

/email-draft- 专业邮件助手写邮件，尤其是英文商务邮件，对非母语者或追求专业度的人来说是个负担。这个命令的输入是一个简短的主题或要点，输出则是一封格式完整、语气得当的邮件草稿。它的设计关键在于上下文理解与模板适配。当输入“Schedule meeting with marketing team for Q4 planning”时，模型需要理解这是内部协作场景，生成包含礼貌开场、清晰议程提议、时间选择征询和标准结尾的邮件。这比通用的文本补全更进了一步，是带有任务类型识别的结构化生成。

/meeting-summary- 会议纪要分析器会议记录通常冗长、杂乱。这个命令的价值是将原始笔记转化为行动导向的摘要。它可能做的事情包括：识别并提取决策点（Decisions）、明确行动项（Action Items）及其负责人（Owners）、归纳关键讨论主题（Key Topics）。这本质上是一个文本摘要和信息抽取任务，但被包装成了一个简单的文件处理命令，让你在散会后能立刻获得一份可执行的会议纪要。

/file-organizer- 智能文件整理~/Downloads和~/Desktop是著名的“数字垃圾场”。这个命令的目标是模拟一个有条理的人的做法。它可能根据文件扩展名、文件内容（通过读取文件头或简单内容分析）、创建日期，甚至文件名中的关键词，将文件移动到诸如Documents/PDFs、Images/Screenshots、Archives等预设或动态创建的目录中。其挑战在于平衡规则的精确性与灵活性，避免误移动重要文件。

/task-prioritizer- 任务优先级管理器面对一长串待办事项，我们常常陷入“先做哪个”的决策瘫痪。这个命令输入一串任务描述，输出一个带优先级、时间估计和紧迫度标签的列表。其背后的逻辑可能结合了任务解析（识别任务类型、复杂度）、基于紧迫性词汇（如“urgent”、“ASAP”）或日期的分类，并参考了类似艾森豪威尔矩阵的时间管理原则。它提供的不是绝对正确的答案，而是一个基于AI的、客观的优先级参考视角，帮助你打破主观偏见，更合理地安排时间。

2.2 开发者命令：将AI融入研发核心流程

这四个命令直接切入软件开发的生命周期，旨在提升代码质量、安全性和开发体验。

/test-gen- 测试用例生成器为现有代码（如一个函数UserAuthService.login）生成测试用例，是AI在开发领域最直观的应用之一。这个命令的强大之处在于“全面性”。一个好的单元测试应包含：正常路径（Happy Path）、各种边界条件（Edge Cases）、错误处理（Error Handling）。该命令会分析函数签名、可能的输入输出，并基于常见缺陷模式生成测试代码。例如，对于登录函数，它会生成测试用例：有效凭证登录成功、错误密码登录失败、空用户名处理、SQL注入尝试防御等。这极大地加速了测试驱动开发（TDD）或为遗留代码补充测试的过程。

/debug-assistant- 调试助手遇到错误信息时，新手往往会直接复制粘贴到搜索引擎。这个命令提供了一个更聚焦、更结构化的调试起点。输入一条错误信息（如TypeError: Cannot read property 'id' of undefined），它不会直接给出答案（因为缺少上下文），而是提供系统化的调试策略。例如，它可能建议：1. 检查变量undefined的来源；2. 回溯调用栈，确认对象是否被正确初始化；3. 建议使用console.log或调试器在关键位置打印状态；4. 列出此类型错误的常见成因。它扮演的是一个经验丰富的同事角色，帮你理清排查思路，而不是替代你思考。

/security-audit- 安全扫描器在快速迭代中，安全漏洞容易被忽视。这个命令对指定代码目录进行快速安全审计。它可能检查：1.硬编码凭证（如密码、API密钥）；2.已知的漏洞函数（如不安全的eval， 已弃用的加密方法）；3.依赖项漏洞（通过集成npm audit或类似工具的建议）；4.常见的Web漏洞模式（如SQL注入、XSS的潜在风险点）。它生成的不是一份替代专业工具（如SonarQube, Snyk）的详尽报告，而是一个快速的风险提示清单，适合在提交代码前作为一道自动化检查关卡。

/cleanup- 代码库清理器随着项目演进，代码库中会积累“技术债”：未使用的变量、函数、导入语句，以及可以优化的代码片段。这个命令像是一个自动化的代码审查员，专注于“整洁度”。它可能识别：1.死代码（从未被调用的函数）；2.重复代码块（建议提取为函数）；3.过于复杂的函数（圈复杂度高，建议重构）；4.不符合项目约定的代码风格。它的输出是一份优化建议列表，开发者可以据此决定是否立即重构或列入技术债清单，有助于长期保持代码库的健康度。

3. 实战部署与深度定制指南

了解了命令能做什么，接下来就是让它们为你所用。项目的Quick Start给出了基础步骤，但要想用得顺手，还需要一些深度配置和技巧。

3.1 环境准备与安装细节

首先，确保你的环境符合要求。Gemini CLI 是一个Node.js工具，所以你需要先安装Node.js（建议LTS版本）和npm。

# 1. 安装或更新Gemini CLI npm install -g @google/gemini-cli@latest

这里有一个关键点：@latest标签会安装最新的稳定版。但如果你所处的网络环境对Google服务访问不稳定，安装过程可能会很慢或失败。此时，可以考虑配置npm镜像源，或者使用--verbose标志查看详细日志以排查网络问题。

安装完成后，验证是否成功：

gemini --version

3.2 命令库的两种部署模式

项目提供了两种部署模式，选择哪种取决于你的使用场景：

模式一：项目作用域（推荐用于团队协作）

cp -r .gemini /path/to/your/project/

这种方式将.gemini目录（包含所有命令定义）复制到你的项目根目录。好处是：命令与项目绑定，版本可控。当你在项目目录下执行gemini命令时，它会自动加载本项目自定义的命令。非常适合团队项目，确保所有成员都使用同一套自动化脚本。你可以将此目录提交到版本控制系统（如Git）中。

模式二：用户作用域（个人全局使用）

cp -r .gemini/commands ~/.gemini/commands/

这种方式将命令复制到你的用户主目录下的.gemini/commands文件夹中。好处是：在任何终端、任何目录下，你都可以使用这些命令，真正实现了“全局工具箱”。适合个人用来管理跨项目的通用任务，比如整理个人照片、起草通用邮件等。

实操心得：我个人的做法是混合使用。将/debug-assistant、/test-gen、/security-audit这类开发通用命令放在用户作用域。而将/report-gen（针对特定项目的数据格式）、/cleanup（针对特定项目的代码规范）这类高度项目定制化的命令放在项目作用域。这样既保持了灵活性，又做到了针对性。

3.3 命令的解剖与定制化改造

每个命令本质上都是一个TOML格式的配置文件。让我们以/email-draft为例，深入看看它的内部结构（以下为推测和示例，实际文件需查看项目源码）：

# .gemini/commands/email-draft.toml [[commands]] name = "email-draft" description = "Drafts professional emails with proper tone, structure, and templates." prompt = """ You are a professional email assistant. The user will provide a brief subject or key points for an email. Your task is to draft a complete, professional email in English. Include: a polite greeting, a clear body structured around the user's points, a professional closing, and a signature placeholder. Tone should be formal but friendly. User input: {input} """ shell = "echo '{response}' | pbcopy" # macOS 复制到剪贴板 # shell = "echo '{response}' | clip" # Windows 复制到剪贴板 # shell = "echo '{response}'" # Linux， 仅输出到终端

关键部分解析：

1. prompt: 这是命令的灵魂。它定义了给AI模型的“角色”和“任务指令”。{input}是一个占位符，会被你实际输入的内容替换。一个精心设计的prompt是命令好用的关键。
2. shell: 这是命令执行的后继动作。上面例子展示了如何根据操作系统，将AI生成的邮件草稿直接复制到系统剪贴板，这样你就能立刻粘贴到邮件客户端中，效率极高。

定制化实战：假设你觉得默认的邮件语气太正式，想要一个更偏向内部团队、轻松一点的版本。你可以直接复制一份email-draft.toml并修改：

# .gemini/commands/email-internal.toml [[commands]] name = "email-internal" description = "Drafts casual internal team emails." prompt = """ You are drafting an email for internal team communication. The user will provide the main points. Draft a concise, friendly, and action-oriented email. Use a casual tone (e.g., 'Hi team,' 'Thanks,' 'Cheers'). Avoid overly formal language. Focus on clarity and next steps. User input: {input} """ shell = "echo '{response}' | pbcopy"

现在，你就有了两个命令：/email-draft用于对外正式邮件，/email-internal用于对内轻松沟通。

更高级的定制：集成外部工具shell字段的威力远不止echo。你可以集成任何命令行工具。例如，改进/photo-rename，让它不仅在AI层面重命名，还实际调用exiftool和mv命令来执行文件操作（请注意，原项目可能已包含类似逻辑，此处为扩展举例）：

# 假设的增强版 photo-rename.toml 部分逻辑 [[commands]] name = "photo-rename-advanced" description = "AI-rename photos and organize into date-based folders." prompt = "...（AI生成新文件名的prompt）..." shell = """ # 假设AI输出格式为：new_filename.jpg NEW_NAME=$(gemini run --prompt-file .gemini/commands/prompts/photo-rename.txt -- "{input}") # 使用exiftool获取拍摄日期，创建目录 DATE_DIR=$(exiftool -d "%Y-%m" -CreateDate -s -s -s "{input}" | head -1) mkdir -p "./organized_photos/$DATE_DIR" # 移动并重命名文件 mv "{input}" "./organized_photos/$DATE_DIR/$NEW_NAME" echo "Moved to: ./organized_photos/$DATE_DIR/$NEW_NAME" """

这个例子展示了如何将AI的智能与现有强大的命令行工具链结合，构建出真正强大的自动化工作流。

4. 构建你自己的专属斜杠命令库

掌握了现有命令的用法和定制方法后，你就可以发挥创造力，打造完全贴合自己需求的命令了。这个过程可以分为几个步骤。

4.1 从需求到设计：定义你的命令

首先，明确你要解决什么问题。一个好的自定义命令通常有这些特征：高频（经常做）、重复（步骤固定）、耗神（需要思考或繁琐操作）。例如：

• 痛点：每次部署后，都要手动登录服务器查看服务日志，检查是否启动成功。
• 命令构思：/deploy-check， 输入服务器IP和服务名，自动SSH登录，执行tail -f或systemctl status，并将关键信息返回。

设计时，想清楚输入输出：

• 输入：是文件路径、一段文本、一个错误信息，还是多个参数？
• 处理：AI主要扮演什么角色？是分析、生成、总结，还是决策？
• 输出：是纯文本显示、复制到剪贴板、生成一个文件，还是执行一个系统操作？

4.2 编写有效的Prompt：与AI清晰沟通

Prompt是命令成败的关键。写Prompt就像给一个非常聪明但缺乏背景知识的实习生布置工作。原则是：清晰、具体、有约束。

一个反面例子（模糊）：

帮我写点代码。

一个正面例子（清晰）：

你是一个经验丰富的Python开发者。请编写一个函数，用于安全地解析用户输入的JSON字符串。函数名为 `safe_parse_json`， 输入是一个字符串 `json_str`， 输出是一个Python字典。如果解析成功，返回字典；如果解析失败（包括JSON格式错误和解码错误），捕获所有 `json.JSONDecodeError` 异常，并返回 `None`。请只给出函数代码，不需要解释。

对于斜杠命令的Prompt，一个通用的结构是：

1. 角色设定：You are a...
2. 任务描述：Your task is to...
3. 输入输出格式：The user will provide... You should output...
4. 约束条件：The tone should be...,Do not include...,Focus on...
5. 用户输入占位符：User input: {input}

4.3 实现与集成：编写TOML配置

根据你的设计，创建.toml文件。以下是一个模拟/deploy-check的简单示例：

# .gemini/commands/deploy-check.toml [[commands]] name = "deploy-check" description = "Check service status on a remote server after deployment." prompt = """ You are a DevOps engineer. The user will provide a server IP address and a service name. Generate a concise, ready-to-run SSH command that will: 1. Connect to the server. 2. Check the status of the specified service using `systemctl status [service-name]`. 3. If the service is active, also fetch the last 5 lines of its main log (typically via `journalctl -u [service-name] -n 5`). Format the entire command as a single line. Only output the command. Example Input: 192.168.1.10 nginx Example Output: ssh user@192.168.1.10 \"systemctl status nginx && echo '--- Logs ---' && journalctl -u nginx -n 5\" User input: {input} """ shell = """ # 解析用户输入，假设输入格式为“IP 服务名” read -r IP SERVICE <<< "{input}" # 使用AI生成的命令模板，这里为了安全，我们固定用户名为‘deploy’ COMMAND=$(gemini run --prompt-file .gemini/commands/prompts/deploy-check.txt -- "$IP $SERVICE") echo "Running: $COMMAND" eval "$COMMAND" """

这个例子中，AI负责生成具体的检查命令，而shell脚本负责安全地解析输入并执行。请注意：在实际生产环境中，直接eval来自AI的命令存在安全风险。更安全的做法是使用固定的命令模板，让AI只填充IP和服务名等参数。

4.4 测试与迭代：让命令更可靠

新命令创建后，务必进行充分测试。

1. 功能测试：用各种典型的输入案例测试，看输出是否符合预期。
2. 边界测试：输入空值、错误格式、极端情况，看命令是否健壮（是优雅报错还是崩溃）。
3. 集成测试：在真实的终端环境中运行，检查与其它工具（如SSH客户端）的交互是否顺畅。
4. Prompt调优：如果AI输出不理想，回到Prompt设计步骤，增加更明确的指令或示例（Few-shot Learning）。

5. 常见问题、排错与效能提升技巧

在实际使用和自定义过程中，你肯定会遇到一些问题。这里记录了一些常见坑点和解决方案。

5.1 安装与基础使用问题

Q1: 运行gemini命令提示“command not found”。A1: 这通常是Node.js全局安装路径未添加到系统PATH环境变量导致。解决方法：

• 查找npm全局安装路径：npm config get prefix
• 将该路径下的bin文件夹（如/usr/local/bin）添加到你的shell配置文件（如~/.bashrc,~/.zshrc）的PATH中：export PATH="$PATH:/usr/local/bin"
• 执行source ~/.zshrc（或你的shell配置文件）使更改生效。

Q2: 复制命令库后，运行自定义斜杠命令无反应或报错。A2: 首先检查命令文件是否在正确的位置且Gemini CLI能识别。

• 运行gemini list-commands。这个命令应该列出所有可用的斜杠命令，包括你自定义的。如果没出现，检查.gemini/commands目录的路径是否正确。
• 确保TOML文件语法正确。一个常见的错误是TOML格式不对，比如漏了引号或括号。可以使用在线的TOML验证器检查文件。

Q3: AI响应速度慢或超时。A3: Gemini CLI的背后是Google的AI模型，响应速度受网络和模型负载影响。

• 网络问题：检查你的网络连接，特别是到Google服务的连通性。
• 使用更小的模型（如果CLI支持）：查看Gemini CLI文档，看是否有参数可以指定更快的模型（如gemini-1.5-flash相比gemini-1.5-pro更快）。
• 优化Prompt：过于复杂或开放的Prompt会导致模型思考时间变长。尽量让任务具体、指令清晰。

5.2 命令定制与脚本编写中的陷阱

Q4: 在shell脚本中，如何安全地使用AI生成的文本？A4: 这是最大的安全隐患。永远不要盲目执行AI生成的代码或命令。

• 策略一：仅用于生成文本。像/email-draft那样，输出只用于复制粘贴，不自动执行。
• 策略二：严格限制AI的输出格式。在Prompt中强制要求AI输出特定格式（如JSON），然后在shell脚本中用jq等工具安全解析，再用解析后的参数调用你信任的、预定义好的命令模板。
• 策略三：增加人工确认环节。在shell脚本中，用read -p "Execute this command? (y/N): "让用户确认后再执行eval。

Q5: 自定义命令的Prompt效果不理想，输出格式混乱或答非所问。A5: Prompt工程需要耐心调试。

• 提供示例：在Prompt中加入1-2个清晰的输入输出示例（Few-shot Learning），能极大地引导模型。
• 明确格式：使用“输出必须是纯文本”、“以Markdown列表形式输出”、“不要包含任何额外解释”等指令。
• 分步思考：对于复杂任务，可以要求模型“请按以下步骤思考：1... 2...”。虽然CLI可能不支持链式调用，但清晰的步骤指示能提升单次回答质量。
• 迭代测试：准备一组测试用例，每次修改Prompt后都跑一遍，观察改进或退化。

Q6: 如何让命令处理多个文件或复杂参数？A6: 原生命令可能只支持简单参数。你可以通过编写更复杂的shell包装脚本来增强。

• 处理多个文件：在shell字段中，使用for file in *; do ... done循环遍历当前目录或指定模式的文件。
• 复杂参数解析：使用getopts（在bash中）或直接解析{input}字符串。例如，将输入-i input.txt -o output.txt拆分成不同的变量。

5.3 效能提升与高级玩法

技巧一：组合命令，构建工作流单个命令能力有限，但组合起来威力无穷。你可以通过shell脚本将多个斜杠命令串联。 例如，创建一个weekly-report.sh脚本：

#!/bin/bash # 1. 用 /file-organizer 整理本周数据文件 echo "整理文件中..." gemini run /file-organizer ./weekly_data/ # 2. 用 /report-gen 生成报告草稿 REPORT=$(gemini run /report-gen ./weekly_data/processed/summary.csv) # 3. 用 /email-draft 生成邮件正文 EMAIL_BODY=$(gemini run /email-draft "Attached is the weekly sales report. Key findings: [to be filled]") # 4. 将报告和邮件正文组合，保存或发送 echo "$REPORT" > weekly_report.md echo "$EMAIL_BODY" > email_draft.txt echo "周报工作流完成！"

技巧二：集成到现有工具链

• 与Git结合：在pre-commit钩子中集成/security-audit和/cleanup， 在代码提交前自动检查。
• 与IDE/编辑器结合：虽然Gemini CLI在终端运行，但你可以通过编辑器插件（如VSCode的Terminal）快速调用特定命令。或者，将AI生成的代码（如来自/test-gen）直接插入到当前编辑的文件中。

技巧三：管理你的命令库随着自定义命令增多，管理变得重要。

• 版本控制：将你的.gemini/commands目录纳入Git管理，记录每次Prompt的改进。
• 文档化：在每个命令的TOML文件里，用description字段写清楚用途。甚至可以创建一个README-commands.md文件，记录所有自定义命令的用法和示例。
• 分享与协作：将你的命令库推送到GitHub等平台，与团队共享。也可以从社区发现他人分享的优秀命令，汲取灵感。

6. 安全、成本与最佳实践考量

在享受自动化便利的同时，我们必须清醒地认识到几个关键问题。

安全第一

1. 数据隐私：你通过Gemini CLI发送的数据（文件内容、错误日志、任务列表）会上传到Google的服务器进行处理。切勿处理高度敏感、机密或个人身份信息（PII）。对于公司内部代码，避免使用/security-audit扫描包含核心算法或未加密密钥的代码库，除非你完全信任该服务的数据处理政策。
2. 命令执行：如前所述，绝对避免在shell脚本中直接、无条件地执行AI生成的命令。始终秉持“最小权限”和“人工监督”原则。

成本意识Gemini CLI通常有免费额度，但超出后会产生费用。频繁、大量地使用这些命令（尤其是处理长文本或大量文件）可能会消耗你的API配额或产生费用。最佳实践是：

• 本地预处理：对于/photo-rename， 可以先在本地用脚本提取好EXIF日期，只将图片描述部分交给AI。
• 批量操作谨慎：不要一次性对成千上万个文件运行AI命令。先小规模测试，或设计脚本进行分批处理。
• 关注使用量：定期查看你的Gemini API使用情况面板。

最佳实践总结

1. 始于模仿，终于创新：先熟练使用项目提供的10个命令，理解其模式，再动手创建自己的。
2. Prompt即代码：像对待代码一样对待你的Prompt。写清楚、做测试、版本管理、持续重构。
3. 人机协同，而非替代：将这些命令视为强大的“副驾驶”。它们能处理繁琐劳动、提供灵感草案、辅助排查，但最终决策、复杂逻辑判断和成果审核必须由你完成。
4. 保持简洁与专注：一个命令最好只做一件事，并把它做好。避免创建功能过于复杂、臃肿的“瑞士军刀”式命令。
5. 融入现有习惯：不要为了用AI而打乱你高效的工作流。寻找现有流程中那些重复、枯燥的环节，用斜杠命令进行“精准爆破”和增强。

回过头看，gemini-cli-custom-slash-commands项目的精髓不在于这10个命令本身，而在于它展示了一种范式：将AI能力封装成可组合、可定制的命令行工具。它降低了AI的使用门槛，让其从聊天界面走进了生产力工具的核心地带。真正的价值，始于你开始思考：“我每天重复的哪件事，可以交给这样一个‘/’命令？” 然后，动手去实现它。这个过程本身，就是一次极佳的学习和自动化思维训练。