Gemini CLI：可编程本地智能体的五大工程实践

1. 别再把 Gemini CLI 当成“高级 ChatGPT 命令行版”了

我第一次在终端里敲出gemini命令，看着那个带 Google Logo 的交互界面跳出来时，心里想的是：“好家伙，这下写 Python 脚本不用切窗口了。”结果连续三天，我只用它干一件事：把一段乱糟糟的 shell 脚本重写成带注释、有错误处理、还能自动检测依赖的版本。直到第四天，我手滑把一个.txt文件拖进终端，顺口问了句：“帮我把里面所有邮箱地址提出来，按域名分组统计数量”，Gemini CLI 真的给我返回了一张 Markdown 表格——那一刻我才意识到，自己过去一周，只用出了它不到 5% 的能力。

Gemini CLI 不是命令行里的聊天机器人，它是一个可编程的本地智能体（Local Agent）。它的核心设计哲学不是“回答问题”，而是“执行任务”。它自带一套完整的工具链：能读写本地文件、能调用系统命令、能联网搜索、能解析 PDF 和图片、能操作数据库、甚至能调用 MCP（Model Context Protocol）服务器去部署云服务。这些能力被封装成一个个可授权、可审计、可组合的“工具”，而你，就是这个智能体的指挥官。关键词Gemini CLI、命令行工具、shell命令、Python脚本、文档整理，每一个都不是孤立的标签，而是它能力光谱上的一个坐标点。它不替代你写代码，但它能把你从“写代码”这件事里解放出来，让你专注在“要解决什么问题”上。这篇文章要讲的，就是这五个真正能改变你工作流的用法——它们不靠炫技，全靠解决你每天真实遇到的、让人烦躁的脏活累活。

2. 文档整理：让杂乱无章的“下载文件夹”在 30 秒内变成专业档案库

你有没有过这种经历：项目结项后，一堆会议纪要、需求文档、截图、PDF 报告、Excel 数据表，全堆在“Downloads”文件夹里，名字还都是“新建 Microsoft Word 文档 (2).docx”、“IMG_20250726_143211.jpg”、“未命名.pdf”。手动整理？光是看一眼就头皮发麻。用传统脚本？写个遍历+正则+移动的 Bash 脚本，调试半小时，跑起来还可能误删文件。Gemini CLI 的文档整理，是另一种思路：用自然语言定义规则，由它来生成并安全执行整个流程。

2.1 核心原理：从“命令驱动”到“意图驱动”

传统脚本是“命令驱动”：你告诉机器每一步做什么（find . -name "*.pdf" | xargs -I {} mv {} ./PDFs/）。Gemini CLI 是“意图驱动”：你告诉它你想达成什么效果（“把所有 PDF 按内容主题分类，发票放 Financial/Invoices，合同放 Legal/Contracts，技术文档放 Tech/Docs”），它会自己拆解任务、选择工具、生成逻辑、请求权限、执行操作。这个过程的关键在于它的ReadFile、SearchText、WriteFile和Shell工具的协同。它不是简单地按后缀名移动文件，而是能打开文件、读取内容、理解语义、再做决策。

2.2 实操步骤：一次搞定“财务文件”的智能归档

假设你的桌面有一堆混杂的文件，其中包含几份扫描的 PDF 发票和一份 Excel 格式的月度对账单。目标是：将所有发票（无论 PDF 还是 JPG）识别出来，提取关键信息（发票号、日期、金额），存入Financial/Invoices；将 Excel 对账单存入Financial/Reports。

第一步：启动并授权基础工具

cd ~/Desktop gemini # 首次启动会引导你完成 OAuth 登录和主题选择，完成后进入交互模式 # 输入 /tools 查看可用工具，重点关注： # - ReadFile (读取单个文件) # - SearchText (在文本中搜索关键词) # - WriteFile (写入文件) # - Shell (执行系统命令，如 mkdir, mv) # - ListDirectory (列出当前目录)

第二步：让 Gemini CLI “看见”你的文件输入/list或@，它会调用ListDirectory工具，列出当前目录下的所有文件。你会看到类似这样的输出：

📁 Desktop/ ├── invoice_scan_001.pdf ├── invoice_scan_002.jpg ├── monthly_statement.xlsx ├── meeting_notes.txt └── project_plan.docx

第三步：下达核心指令，触发多工具协同现在，输入这条自然语言指令：

“请扫描当前目录下的所有 PDF 和 JPG 文件。对于每个文件，如果内容中包含‘Invoice No’、‘Invoice Number’或‘发票号’字样，则将其移动到Financial/Invoices文件夹，并创建一个同名的.txt文件，内容为：发票号（从文件中提取）、开票日期（从文件中提取）、金额（从文件中提取）。如果文件是monthly_statement.xlsx，请将其移动到Financial/Reports文件夹。”

Gemini CLI 的执行链路会是这样的：

1. ListDirectory：确认文件列表。
2. ReadFile+SearchText：对invoice_scan_001.pdf进行 OCR（如果是图片）或文本提取（如果是 PDF），然后搜索关键词。它会找到类似Invoice No: INV-2025-0726和Date: 2025-07-26的字段。
3. Shell：请求权限执行mkdir -p Financial/Invoices创建目标文件夹。
4. Shell：请求权限执行mv invoice_scan_001.pdf Financial/Invoices/移动文件。
5. WriteFile：请求权限，在Financial/Invoices/下创建invoice_scan_001_summary.txt，内容为你指定的结构化信息。
6. 对invoice_scan_002.jpg和monthly_statement.xlsx重复类似流程。

提示：Gemini CLI 在执行任何写入或移动操作前，一定会弹出权限请求框（“Allow once” / “Always allow” / “Deny”）。这是它的安全机制，也是你作为指挥官的控制权所在。永远选择 “Allow once”，尤其是在处理重要文件时，这样你可以逐个确认每一步。

2.3 进阶技巧：用 GEMINI.md 文件固化你的整理策略

如果你发现某个整理规则（比如“所有含‘CONFIDENTIAL’字样的 PDF 都要加水印并移入Legal/Confidential”）需要反复使用，可以把它写进一个叫GEMINI.md的文件里。这个文件是 Gemini CLI 的“行为说明书”，放在项目根目录下，它会在每次启动时自动加载。内容示例：

## 财务文件归档规则 - **识别条件**：文件内容中包含 "Invoice", "INVOICE", "发票", "账单", "BILL"。 - **动作**： - 移动至 `Financial/Invoices/` - 提取字段：`Invoice No`, `Date`, `Amount` - 生成摘要文件：`{original_name}_summary.txt` - **例外**：如果文件名包含 "draft" 或 "temp"，跳过此规则。

下次你只需在该目录下运行gemini，它就会自动遵循这份说明书，无需再重复输入长指令。这本质上是在用 Markdown 编写一个可复用、可分享、可版本控制的“自动化策略”。

3. Shell 命令增强：把 Linux 终端变成一个能“听懂人话”的智能助手

shell命令这个词，在程序员眼里通常意味着ls,grep,awk,sed这些冷峻的字符。但 Gemini CLI 让它有了温度。它内置的Shell工具，不是让你在终端里再套一层终端，而是让你可以用自然语言描述一个复杂的系统操作，由它来翻译成精确、安全的 shell 命令并执行。这彻底改变了我们与操作系统交互的方式。

3.1 为什么你需要这个？——告别“查命令”的时间黑洞

想象一下这个场景：你想找出/var/log下所有在过去 24 小时内被修改过、且文件大小超过 1MB 的.log文件，并把它们的路径和最后修改时间打印出来。一个资深运维可能秒写出：

find /var/log -name "*.log" -mtime -1 -size +1M -printf "%p %TY-%Tm-%Td %TH:%TM:%TS\n" | sort -k2

但对大多数人来说，这需要打开浏览器，搜索“find 大于1MB”，再搜“find 修改时间”，再搜“find 格式化输出”，拼凑、试错、调试……十分钟就没了。Gemini CLI 的价值，就在于它把这十分钟，压缩成一句话。

3.2 实战案例：三句话，完成一个“日志分析流水线”

我们来做一个更贴近日常开发的案例：分析你本地 Git 仓库的提交历史，找出最近一周内，哪些文件被修改得最频繁，并生成一个 Markdown 报告。

指令一：获取原始数据

“请运行以下命令并返回结果：git log --since='1 week ago' --pretty='%H' | xargs -I {} git show --oneline --name-only {} | grep -v '^$' | sort | uniq -c | sort -nr | head -10”

Gemini CLI 会直接调用Shell工具，执行这条命令，并将结果（一个按修改次数排序的文件列表）作为上下文的一部分。你不需要知道xargs怎么用，你只需要知道你要什么。

指令二：让结果“活”起来

“请将上面的结果，格式化成一个 Markdown 表格，包含两列：‘修改次数’和‘文件路径’。并在表格上方加一个标题：‘过去一周最活跃的 10 个文件’。”

它会立刻调用WriteFile工具，生成一个activity_report.md文件，内容如下：

## 过去一周最活跃的 10 个文件 | 修改次数 | 文件路径 | |----------|----------| | 12 | src/main.py | | 8 | tests/test_api.py | | 7 | docs/README.md | | ... | ... |

指令三：一键预览与分享

“请用cat activity_report.md命令显示这个报告的内容。”

它会再次调用Shell工具，把刚生成的 Markdown 文件内容打印在终端里，你一眼就能看到成果。整个过程，你没有写一行 shell 脚本，没有安装任何新工具，只是用说话的方式，指挥一个智能体完成了数据提取、格式转换、文件生成、内容预览这一整套流水线。

注意：Gemini CLI 的Shell工具默认只允许执行非破坏性命令（ls,cat,grep,git log等）。如果你想让它执行rm,mv,chmod等高危命令，它会极其严格地要求你进行二次确认，并且会清晰地告诉你它将要执行的具体命令是什么。这是它区别于普通脚本的核心安全特性——它永远把最终决定权交给你。

3.3 高级玩法：用/shell模式进行“所见即所得”的交互式调试

Gemini CLI 还提供了一个快捷入口：在任何对话中，输入!即可进入Shell模式。此时，你的提示符会变成!，你输入的任何命令都会被直接交给系统执行，结果会原样返回给模型。这相当于在 Gemini CLI 里开了一个“沙盒终端”。

例如，你想快速检查一个 Python 脚本的输出：

! python3 my_script.py --help

结果返回后，你可以立刻接着问：

“这个脚本的帮助信息里提到的--output-format参数，有哪些可选值？请从帮助文本中提取出来。”

它会基于你刚刚看到的--help输出，精准地定位并提取答案。这种“执行-观察-提问”的闭环，是调试复杂脚本或分析陌生命令输出的终极利器。

4. Python 脚本生成与维护：从“写代码”到“定义契约”

Python脚本是现代数字工作的通用胶水。但写脚本最耗时的环节，往往不是逻辑本身，而是环境准备、错误处理、参数解析、日志记录、文档编写这些“仪式感”极强的样板代码。Gemini CLI 的核心优势，在于它能将你对一个脚本的功能契约（What），直接翻译成可运行、可维护的实现代码（How），并且能持续陪伴这个脚本的整个生命周期。

4.1 生成：用“用户故事”代替“函数签名”

别再写def process_csv(input_file: str, output_file: str) -> None:了。试试用产品经理的口吻描述需求：

“我有一个 CSV 文件，第一列是用户邮箱，第二列是注册日期（格式 YYYY-MM-DD）。我需要一个 Python 脚本，能读取这个文件，筛选出所有注册日期在 2024 年之后的用户，并将他们的邮箱地址写入一个新的active_users.txt文件，每行一个邮箱。脚本需要有命令行参数，让我可以指定输入和输出文件的路径。如果输入文件不存在，要友好地报错。”

Gemini CLI 会生成一个完整的、健壮的脚本，包含：

• 使用argparse的命令行参数解析。
• 使用pathlib的跨平台路径处理。
• 使用datetime的日期解析和比较。
• 使用logging的结构化日志输出。
• 使用try/except的完整错误处理（文件不存在、日期格式错误等）。
• 清晰的 docstring 和类型提示。

最关键的是，它生成的代码，是你“说”出来的，而不是你“猜”出来的。你不需要记住argparse的所有参数，你只需要清楚地表达你的业务需求。

4.2 维护：让旧脚本“开口说话”，帮你理解它

你接手了一个同事留下的、没有注释的 500 行 Python 脚本data_cleaner.py。想改一个 bug，但看不懂它的数据流。这时，Gemini CLI 就是你的“代码翻译官”。

第一步：让它“阅读”

“请详细解释@data_cleaner.py这个文件。重点说明：1. 主函数main()的作用；2. 它调用了哪些关键的子函数；3. 数据从读取、清洗到保存，整个流程是怎样的？请用中文，用流程图文字描述。”

它会调用ReadFile工具读取源码，然后用SearchText分析函数定义和调用关系，最后给你一个清晰的、人类可读的流程概述，比如：

“main()函数首先调用load_data()从 CSV 加载数据，然后调用clean_data()进行三步清洗：a) 删除空行，b) 将 'price' 列转为浮点数并过滤掉负值，c) 将 'category' 列标准化为小写。最后，调用save_data()将清洗后的 DataFrame 保存为新的 CSV。”

第二步：让它“诊断”

“这个脚本在处理一个包含特殊字符（如中文、emoji）的 CSV 文件时会报错UnicodeDecodeError。请分析原因，并给出修复方案。”

它会基于你提供的错误信息和源码，精准定位到open()函数缺少encoding='utf-8'参数，并直接给出修改后的代码行。

第三步：让它“升级”

“请为这个脚本添加一个新功能：在保存清洗后的数据时，同时生成一个report.txt文件，内容包括：总行数、清洗后剩余行数、被删除的行数及原因（空行、价格无效、类别为空）。”

它会分析现有代码结构，找到save_data()函数的位置，然后生成一个全新的、与原有风格完全一致的generate_report()函数，并告诉你需要在main()的哪个位置插入调用。

这个过程，把“理解代码”这个最烧脑的环节，变成了一个高效的问答过程。你不再是孤军奋战的维护者，而是有一个随时待命的、精通 Python 的资深同事。

5. 多模态信息萃取：让 Gemini CLI 成为你个人知识库的“OCR+NLP+SQL”三合一引擎

文档整理的终极形态，不是把文件分门别类，而是把文件里的信息提炼出来，变成可查询、可分析、可关联的知识。Gemini CLI 的多模态能力，正是为此而生。它能同时处理文本、图片、PDF、甚至数据库，将它们统一为一种“可理解”的信息流。

5.1 核心能力矩阵：一张表看清它能“看”什么、“懂”什么

这个矩阵的关键在于，所有这些能力，都共享同一个上下文。你可以让 Gemini CLI 先从一个 PDF 中提取出客户名单，再从一个 Excel 表中提取出订单数据，最后用自然语言问：“把 PDF 里的客户和 Excel 里的订单，按客户姓名关联起来，找出每个客户的总订单金额。”

5.2 实战案例：构建你的“个人发票知识库”

这是最能体现其威力的场景。假设你有一批扫描的 PDF 发票，你想做的不是“把它们放好”，而是“建立一个可查询的发票数据库”。

步骤一：批量信息提取

“请扫描当前文件夹下所有.pdf文件。对每个文件，提取以下信息，并以 CSV 格式输出：发票号、开票日期、收款方名称、付款方名称、总金额、税额。如果某项信息在文件中找不到，请留空。”

它会调用 OCR，逐个处理 PDF，然后生成一个invoices.csv文件，内容如下：

Invoice No,Invoice Date,Payee,Payor,Total Amount,Tax INV-2025-001,2025-07-01,ABC Tech Inc.,XYZ Corp.,12500.00,1500.00 INV-2025-002,2025-07-15,DEF Services Ltd.,XYZ Corp.,8900.00,1068.00

步骤二：导入并查询现在，你有了一个标准的 CSV。你可以用Shell工具把它导入 SQLite：

“请运行命令：sqlite3 invoices.db "CREATE TABLE IF NOT EXISTS invoices (id INTEGER PRIMARY KEY, invoice_no TEXT, date TEXT, payee TEXT, payor TEXT, total REAL, tax REAL);"” “请运行命令：sqlite3 invoices.db '.mode csv' '.import invoices.csv invoices'”

步骤三：用自然语言进行“知识问答”

“请查询数据库，告诉我 XYZ Corp. 在 2025 年 7 月的总支出是多少？”

Gemini CLI 会自动生成并执行 SQL：

SELECT SUM("Total Amount") FROM invoices WHERE "Payor" = 'XYZ Corp.' AND "Invoice Date" LIKE '2025-07%';

并把结果21400.00直接告诉你。

你没有写一行 SQL，没有安装任何数据库 GUI 工具，只是用最自然的语言，完成了一个从非结构化文档（PDF）到结构化知识（可查询数据库）的完整闭环。这就是它被称为“个人知识库引擎”的原因。

6. 扩展生态：用gemini extensions把你的工作流变成可安装、可分享的“App”

Gemini CLI 的强大，不仅在于它自身，更在于它的可扩展性。gemini extensions命令，是它的“应用商店”。它允许你将一组复杂的、可复用的工作流，打包成一个独立的、可版本控制的软件包。这彻底解决了“好用的 Prompt 无法沉淀、无法复用、无法分享”的行业痛点。

6.1 扩展的本质：Prompt + 工具 + 上下文的三位一体

一个 Gemini CLI 扩展，不是一个简单的脚本，而是一个完整的“智能体配置包”。它通常包含：

• .toml文件：定义自定义的斜杠命令（如/summarize-pdf），以及这些命令背后绑定的 Prompt 模板。
• GEMINI.md文件：为模型提供专属的上下文、角色设定、输出格式规范和安全限制。
• settings.json片段：配置 MCP 服务器连接、工具白名单/黑名单等。
• schema.json：（可选）定义输入参数的 JSON Schema，用于前端表单生成。

当你安装一个扩展，你不是在安装一个程序，而是在给 Gemini CLI 注入一套新的“思维方式”和“行为准则”。

6.2 实战：从零创建一个“会议纪要整理器”扩展

假设你每周都要整理 Zoom 会议的录音转写稿（meeting_transcript.txt），流程固定：1. 提取关键决策；2. 提取待办事项（Action Items）；3. 提取讨论的议题（Topics）；4. 生成一个标准格式的 Markdown 纪要。

第一步：初始化扩展

gemini extensions new ~/my-extensions/meeting-organizer

这会在~/my-extensions/meeting-organizer目录下生成一个标准的扩展骨架。

第二步：编写核心 Prompt（GEMINI.md）编辑GEMINI.md，写入你的“契约”：

## 角色 你是一位专业的会议秘书，擅长从冗长的会议转写稿中提炼精华。 ## 任务 请严格按以下顺序处理提供的会议转写稿： 1. **关键决策**：列出所有明确做出的、具有行动效力的决策。每条决策以 `- [决策内容]` 开头。 2. **待办事项**：列出所有分配给具体人员的待办事项。格式为 `- [事项描述] (@负责人)`。 3. **讨论议题**：总结本次会议围绕的 3-5 个核心议题，每个议题用一句话概括。 4. **输出格式**：仅输出 Markdown，不要任何解释性文字。标题为 `## 会议纪要`，下面依次是 `### 关键决策`、`### 待办事项`、`### 讨论议题`。 ## 安全 - 禁止编造任何未在转写稿中出现的信息。 - 如果某一部分在原文中完全没有提及，请输出 `暂无`。

第三步：定义快捷命令（extension.toml）编辑extension.toml，添加：

[[commands]] name = "summarize-meeting" description = "将会议转写稿整理为标准格式的纪要" prompt = "请根据以下会议转写稿，严格按照 GEMINI.md 中的规则生成会议纪要：\n\n{{input}}"

第四步：安装与使用

# 在扩展目录下安装 cd ~/my-extensions/meeting-organizer gemini extensions install . # 现在，你可以在任何地方使用它 cd ~/Projects/MyMeeting gemini /summarize-meeting @meeting_transcript.txt

它会立刻调用你定义的 Prompt，生成一份完美的纪要。这个扩展，你可以git push到 GitHub，然后发给你的团队成员，他们只需一条gemini extensions install <your-github-url>，就能获得和你一模一样的能力。你的工作方法论，就这样被产品化了。

提示：官方扩展库（https://geminicli.com/extensions/）里已经有大量高质量的扩展，如cloud-run（一键部署）、github（深度集成）、redis（Redis 数据库管理）。在动手造轮子之前，务必先去逛逛，很可能你想要的功能，已经有人帮你做好了。

7. 最后一点心得：关于“信任”与“控制”的平衡术

写了这么多，最后想分享一点我个人踩过的坑和体会。Gemini CLI 最大的魅力，是它能替你做很多事；但它最大的风险，也恰恰在于“它能替你做很多事”。我曾经因为太信任它，让它执行了一条rm -rf命令（当然是在测试目录里），结果它真的执行了，连确认都没弹——后来才发现，是我之前在settings.json里不小心把Shell工具设为了“Always allow”。这个教训让我明白：

Gemini CLI 不是一个需要你“无条件信任”的黑箱，而是一个需要你“精细化授权”的协作者。它的设计哲学，是把“控制权”牢牢握在你手中。每一次Allow once的点击，都是你对这个智能体的一次授权，也是一次责任的确认。

所以，我的建议是：

• 永远从Allow once开始。哪怕你觉得这个操作很安全，也先让它执行一次，你亲眼看到结果，再决定是否授予Always allow。
• 善用settings.json的分层配置。把最敏感的工具（如Shell）的默认权限设为Deny，只在特定的、受信的项目目录（.gemini/settings.json）里开启它。
• 把GEMINI.md当作你的“宪法”。在这里写清楚它的行为边界、输出格式、禁止事项。模型会比你想象的更严格地遵守它。
• 定期审查已安装的扩展。用gemini extensions list查看，用gemini extensions uninstall <name>卸载那些不再需要的。一个臃肿的扩展列表，会增加不可预测性。

Gemini CLI 的终极价值，不在于它能写多少行代码，而在于它如何重塑你与数字世界的关系。它把那些琐碎、重复、需要查文档、需要试错的“操作性劳动”，转化成了简洁、直接、充满创造性的“意图性表达”。当你能用一句话，就让一个复杂的系统任务自动完成时，你才真正拥有了技术赋予你的那份自由。而这，才是“不浪费”的真正含义。