1. 为什么我又把 Gemini CLI 捡起来了第一次听说 Gemini CLI 是在一个前端群里有人甩了张截图说谷歌把大模型塞进了终端敲一行命令就能让它读代码、改 bug、写测试。我当时的第一反应是又是一个玩具。毕竟这两年各种 AI 编程助手轮番上阵IDE 插件装了一堆真正能让我少加班的没几个。直到有次赶一个视频动作分类的项目用 PyTorch 训练 UCF101 数据集准确率卡在 70% 上不去调了两天参数人都麻了才想着换个工具试试。Gemini CLI 说白了就是一个跑在命令行里的 AI 编程助手。你在项目根目录敲gemini它就能读取当前目录的代码结构理解你的项目上下文然后跟你对话式地完成代码生成、重构、调试、写文档这些活。它最大的特点是免费额度给得大方对个人开发者和小团队来说基本够日常使用。适合谁呢我觉得三类人最值得试一是经常在终端里干活、懒得切窗口的后端和运维二是想用 AI 辅助但不想为 Copilot 付费的独立开发者三是像我当时那样被某个具体技术问题卡住、需要有人帮忙梳理思路的人。但我要先把丑话说在前头这东西不是装上就万事大吉。我在 UCF101 那个项目里用它前前后后踩了七八个坑有的坑浪费了我一整个下午。所以这篇东西不打算写成官方文档的复读机而是把我实际用下来的经验、踩过的雷、以及怎么绕过去的方法原原本本讲清楚。你如果正准备上手或者已经装了但觉得不好用那这篇应该能帮你省不少时间。2. 装之前先想清楚Gemini CLI 到底解决什么问题2.1 它和 IDE 插件、网页版 AI 的本质区别很多人第一次接触 Gemini CLI会下意识拿它跟 VS Code 里的 AI 插件比。我一开始也这样用了几次才发现两者的定位根本不一样。IDE 插件是贴着编辑器走的你选中一段代码它帮你补全或改写交互发生在文件层面。而 Gemini CLI 是贴着项目走的它站在整个代码仓库的角度看问题能跨文件理解依赖关系能直接执行 shell 命令能帮你跑测试、看日志、分析报错。举个我实际遇到的例子。UCF101 那个项目里数据加载部分用了自定义的 Dataset 类训练脚本里又有一层封装报错信息只显示某个 tensor 维度不对。如果是在 IDE 里我得自己一层层翻文件找问题。但在 Gemini CLI 里我直接把报错贴进去它自己就去读了dataset.py、train.py和model.py然后告诉我问题出在数据增强的 transform 顺序上——先做了归一化又做了随机裁剪导致通道数对不上。这种跨文件的推理能力是它跟 IDE 插件最大的差异。至于网页版 AI区别就更明显了。网页版你得手动复制粘贴代码上下文长度有限而且它看不到你的项目结构。Gemini CLI 直接在你的工作目录里运行读的是真实文件改的是真实代码省掉了来回搬运的功夫。2.2 免费额度背后的真实成本官方说免费额度很慷慨这话不假但有几个隐性成本你得心里有数。第一是网络请求的延迟每次对话都要把上下文发给远端模型项目大的时候首次索引会慢我那个 UCF101 项目大概有四十多个文件第一次跑花了将近一分钟才建立索引。第二是上下文窗口的消耗你让它读的文件越多消耗的 token 越多虽然免费但也有上限我有一天连续问了二十多个问题下午就提示额度用尽了。所以我的建议是别把它当成万能问答机而是当成一个需要你引导的结对伙伴。问问题之前先想清楚要它看哪些文件能不能用更精准的描述减少它的搜索范围。比如与其问我的训练代码为什么这么慢不如问帮我看看 train.py 里 dataloader 的 num_workers 设置是否合理后者它只需要读一个文件响应快答案也准。2.3 哪些场景它真的能提效哪些场景别指望用了一个多月我总结了一张表把常见场景和实际效果列出来你可以对照自己的需求判断。使用场景实际效果我的评价生成样板代码CRUD、配置文件很快基本一次成型强烈推荐解释陌生代码库能理清调用链但细节需自己核对推荐调试报错跨文件定位问题很准强烈推荐写单元测试覆盖基本路径边界情况需补充推荐性能优化建议偏通用需结合 profiling一般复杂算法实现容易出错需反复纠正谨慎使用大规模重构改动范围难控制不推荐这张表是我踩坑踩出来的。特别是最后两项我吃过亏。有次让它帮我重构数据预处理模块它一口气改了六个文件结果引入了一个循环导入排查了半天。后来我学乖了重构这种活还是自己来或者让它只给建议、我来动手。3. 从零上手安装与首次配置的完整流程3.1 环境准备与安装步骤安装本身不复杂但前置条件得先满足。Gemini CLI 依赖 Node.js 环境我建议用 18 以上的 LTS 版本太老的版本会有兼容问题。检查命令很简单node -v npm -v如果版本不够去官网下个新的装上就行。装好之后全局安装 Gemini CLInpm install -g google/gemini-cli这里有个坑我要提前说如果你之前装过其他全局 npm 包可能会遇到权限问题。在 macOS 和 Linux 上如果提示EACCES错误别急着用sudo那样装出来的包后续更新会有一堆麻烦。正确的做法是配置 npm 的全局目录到用户目录下mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH最后那行export记得写进你的.bashrc或.zshrc不然重启终端就失效了。Windows 用户一般不会有这个问题但如果遇到路径相关的报错检查一下环境变量里 npm 的路径有没有配对。3.2 首次启动与认证配置装完之后在任意项目目录下敲gemini就能启动。第一次运行会引导你做认证这一步是整个流程里最容易卡住的地方。它会让你选择认证方式我选的是用个人账号登录浏览器会自动打开一个授权页面点确认之后回到终端就完成了。注意如果你在公司网络环境下浏览器授权那一步可能会因为网络策略失败。我当时的解决办法是换到手机热点上完成首次授权授权信息会缓存在本地之后切回公司网络也能正常用。认证完成后你会看到一个交互式的命令行界面。这时候别急着问问题先做两件事。第一件是确认它读到了正确的项目目录界面上会显示当前工作路径如果不对就用/cd命令切换。第二件是跑一次/help把常用命令过一遍特别是/clear清空上下文、/compact压缩上下文和/quit退出这三个你后面会天天用到。3.3 项目初始化让 AI 真正读懂你的代码这一步是很多人忽略的关键。Gemini CLI 启动后默认只会读取你当前目录下的文件但它并不知道哪些文件重要、哪些可以忽略。如果你直接问问题它可能会去读node_modules或者数据集目录白白浪费上下文。正确的做法是在项目根目录建一个.geminiignore文件语法跟.gitignore一样。我在 UCF101 项目里的配置是这样的node_modules/ data/ucf101/ *.mp4 *.avi checkpoints/ __pycache__/ *.pyc把数据集和模型权重排除掉之后它的响应速度明显快了一截。另外如果项目里有README.md或者架构文档可以在对话开始时主动让它读一下比如输入请先阅读 README.md 和 docs/architecture.md了解项目结构。这样后续的对话它就能带着全局视角来回答准确率高很多。4. 核心功能实操我是怎么用它搞定 UCF101 项目的4.1 用自然语言生成数据加载代码UCF101 是个视频动作分类数据集一万三千多个视频分 101 个类别。用 PyTorch 加载这种数据集最烦的就是写 Dataset 类要处理视频解码、帧采样、数据增强这一堆事。我一开始自己写了个版本跑起来发现内存泄漏查了半天没找到原因。后来我换了个思路直接跟 Gemini CLI 描述需求帮我写一个 PyTorch 的 Dataset 类读取 UCF101 数据集每个视频均匀采样 16 帧返回归一化后的 tensor支持训练和验证两种模式。它给出的代码结构是这样的import torch from torch.utils.data import Dataset import cv2 import os import numpy as np class UCF101Dataset(Dataset): def __init__(self, root_dir, splittrain, num_frames16, transformNone): self.root_dir root_dir self.num_frames num_frames self.transform transform self.samples [] # 读取类别列表和视频路径 with open(os.path.join(root_dir, f{split}list01.txt)) as f: for line in f: parts line.strip().split() if len(parts) 2: video_path os.path.join(root_dir, videos, parts[0]) label int(parts[1]) - 1 self.samples.append((video_path, label)) def __len__(self): return len(self.samples) def __getitem__(self, idx): video_path, label self.samples[idx] frames self._load_video(video_path) frames torch.stack(frames) if self.transform: frames self.transform(frames) return frames, label def _load_video(self, path): cap cv2.VideoCapture(path) total int(cap.get(cv2.CAP_PROP_FRAME_COUNT)) indices np.linspace(0, total - 1, self.num_frames, dtypeint) frames [] for i in indices: cap.set(cv2.CAP_PROP_POS_FRAMES, i) ret, frame cap.read() if ret: frame cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) frame torch.from_numpy(frame).permute(2, 0, 1).float() / 255.0 frames.append(frame) cap.release() return frames这段代码基本能用但有几个地方我做了修改。第一它默认用 OpenCV 逐帧读取速度很慢我换成了decord库解码效率高好几倍。第二均匀采样在动作视频里效果一般我改成了分段随机采样每个片段里随机取一帧这样数据增强的效果更好。第三它没有处理视频读取失败的情况我加了个 try-except失败时返回全零帧并打日志。实操心得AI 生成的代码永远要当成初稿来对待。它给的是骨架血肉得你自己填。特别是涉及性能和数据正确性的地方一定要自己验证。4.2 调试训练过程中的维度报错数据加载搞定之后训练跑起来了但准确率一直在 70% 左右晃悠而且验证集的 loss 忽高忽低。我把报错和训练日志贴给 Gemini CLI它分析后指出两个问题一是 BatchNorm 层的 momentum 设得太小导致训练初期统计量不稳定二是学习率没有做 warmup前几个 epoch 梯度震荡明显。它给的修改建议是把 momentum 从 0.01 调到 0.1并加一个 5 个 epoch 的线性 warmup。我照着改了之后验证集 loss 的波动确实小了很多准确率也慢慢爬到了 75% 以上。但这里有个细节它没提是我自己发现的warmup 的起始学习率不能设成 0否则前几个 step 梯度几乎不更新我设成了初始学习率的十分之一效果才出来。还有一次更隐蔽的坑。训练到第 30 个 epoch 时突然报 CUDA out of memory但 batch size 一直没变过。我把完整报错贴进去它让我检查是否有张量在循环里累积。我回去一看果然在验证循环里忘了加torch.no_grad()导致计算图一直保留显存越占越多。这种问题如果自己查可能得花半小时它几秒钟就定位到了。4.3 生成单元测试与数据校验脚本项目写到后期我想给数据加载模块加单元测试确保不同 split 的样本数对得上。这个活我自己写大概要二十分钟交给它之后两分钟就出了初稿import pytest from dataset import UCF101Dataset def test_dataset_length(): train_ds UCF101Dataset(root_dirdata/ucf101, splittrain) val_ds UCF101Dataset(root_dirdata/ucf101, splitval) assert len(train_ds) 0 assert len(val_ds) 0 # UCF101 官方划分 train 约 9500val 约 3700 assert 9000 len(train_ds) 10000 assert 3500 len(val_ds) 4000 def test_sample_shape(): ds UCF101Dataset(root_dirdata/ucf101, splittrain, num_frames16) frames, label ds[0] assert frames.shape (16, 3, 224, 224) assert 0 label 101这个测试跑起来之后还真发现了一个问题我的验证集划分脚本有个 off-by-one 的错误导致 val 集少了一个样本。虽然不影响大局但这种细节能提前发现心里踏实很多。4.4 用 CLI 做代码审查和文档生成项目收尾阶段我让它对整个仓库做了一次代码审查。命令很简单就是输入请审查当前项目的代码指出潜在的问题和改进建议。它花了大概两分钟读完了所有 Python 文件然后给了一份报告按严重程度分了级。其中有一条我觉得很有价值它指出我的数据增强里用了RandomHorizontalFlip但动作分类任务里左右翻转可能会改变动作的语义比如向左挥手翻转后变成向右挥手标签就不对了。这个点我之前完全没意识到虽然 UCF101 里大部分动作是对称的但严谨起见我还是把翻转的概率调低了。文档生成也是它的强项。我让它根据代码自动生成 README它把项目结构、依赖安装、训练命令、评估指标都写清楚了我只需要补充一些项目背景和实验结果就行。省下来的时间够我多跑两组对比实验。5. 避坑指南那些让我抓狂的瞬间5.1 上下文丢失与记忆错乱用久了你会发现Gemini CLI 的上下文管理是个双刃剑。对话轮次多了之后它会自动压缩历史消息压缩过程中可能丢掉一些关键信息。我有次跟它讨论了半天的数据增强策略中间去改了个配置文件回来再问它它已经不记得之前定的方案了给的答案跟前面矛盾。解决办法有两个。一是重要决策及时落盘让它把结论写进一个NOTES.md文件下次对话先读这个文件。二是善用/compact命令手动压缩在压缩之前把关键上下文用一句话总结出来比如我们之前确定了用分段随机采样batch size 32学习率 1e-3这样压缩后它还能记住要点。5.2 过度自信的错误答案AI 最危险的地方不是它不会而是它不会的时候还特别自信。我在处理视频帧率不一致的问题时问它怎么统一不同视频的帧数它给了一个用cv2.resize直接拉伸时间维度的方案。这个方案听起来合理但实际会把动作的速度改变比如一个 30fps 的视频拉到 16 帧动作会变慢模型学到的特征就偏了。我当时差点就信了幸好留了个心眼去查了原始论文的做法发现标准做法是均匀采样或者分段采样而不是拉伸。所以我的经验是涉及领域知识的建议一定要交叉验证。AI 给的是通用方案但你的具体任务可能有特殊约束这些约束只有你自己最清楚。5.3 文件读写权限与路径陷阱有次我让它帮我写一个批量重命名视频文件的脚本它生成的代码里用了相对路径但我的工作目录和脚本所在目录不一致跑起来直接报文件找不到。更坑的是它生成的删除操作没有加确认如果路径配错了可能误删文件。从那以后我定了个规矩凡是涉及文件写操作、删除操作的代码必须自己逐行审查。让它生成可以但执行之前一定要在测试目录里先跑一遍。另外路径尽量用pathlib而不是字符串拼接跨平台兼容性好很多。5.4 常见问题速查表我把这段时间遇到的问题整理成了一张表方便你快速对照排查。问题现象可能原因解决方法启动时报认证失败网络策略拦截或缓存过期换网络环境重新授权清除本地缓存响应特别慢项目文件太多索引耗时配置 .geminiignore 排除无关目录回答与项目无关工作目录不对用 /cd 切换到正确目录额度突然用尽单次对话上下文过大用 /clear 清空分多次提问生成的代码跑不通依赖版本或环境差异检查 requirements手动补依赖改代码后引入新 bug改动范围失控小步提交每次改动后跑测试中文回答夹杂英文提示词语言不明确明确要求用中文回答提示这张表里的每一条都是我实际遇到过的不是从文档里抄的。特别是额度用尽那条我建议你养成习惯每完成一个独立任务就/clear一次别让无关的上下文一直占着窗口。6. 进阶玩法把它变成你的专属助手6.1 自定义提示词模板Gemini CLI 支持自定义提示词你可以把常用的指令存成模板用快捷键调用。我在项目里配了几个常用的比如审查代码、生成测试、解释这段代码。配置方式是在用户目录下建一个配置文件把模板写进去。这个功能的价值在于减少重复描述。以前我每次让它审查代码都要打一长串要求现在一个快捷键就搞定而且每次的审查标准一致不会这次严下次松。我建议你至少配三个模板一个用于代码审查一个用于生成测试一个用于解释陌生代码。6.2 结合脚本实现半自动化Gemini CLI 本身是交互式的但你可以用 shell 脚本把它包起来实现一些半自动化的流程。比如我写了个脚本每次提交代码之前自动跑一遍让它检查有没有明显的坏味道。虽然不能完全替代人工 review但能拦住一些低级错误。脚本的思路很简单就是把 diff 内容传给 CLI让它输出审查意见然后根据返回结果决定是否继续。这里要注意的是别让它自动修改代码并提交自动化程度越高出问题时越难追溯。我的原则是AI 可以建议但最终的执行权必须在我手里。6.3 多项目切换时的配置管理如果你同时维护多个项目每个项目的技术栈和规范都不一样这时候配置管理就很重要。我的做法是每个项目根目录放一个.gemini配置文件里面写明这个项目的语言、框架、代码风格要求。切换项目时CLI 会自动读取对应配置给出的建议就贴合项目实际。举个例子我的 UCF101 项目配置里写了使用 PyTorch遵循 PEP8注释用中文而另一个前端项目配置里写的是使用 TypeScript遵循 Airbnb 规范注释用英文。这样我就不用每次切换项目都重新交代一遍背景省事很多。7. 我个人的使用体会用了一个多月Gemini CLI 在我工作流里的位置基本固定下来了。它不是我写代码的主力更像是一个随时能问的搭档。遇到不熟悉的库、看不懂的报错、懒得写的样板代码找它准没错。但涉及核心算法、性能关键路径、大规模重构这些活我还是自己动手或者只让它给建议。最大的感受是工具再好也得你会用。同样的 Gemini CLI有人觉得鸡肋有人觉得真香差别就在于会不会提问、会不会验证、会不会管理上下文。我踩过的那些坑本质上都是因为我一开始把它当成了万能的黑盒后来才明白它是个需要引导的助手。如果你正准备上手我的建议是从小任务开始先让它帮你解释一段代码、写一个测试建立信任之后再逐步扩大使用范围。别一上来就让它重构整个项目那样大概率会失望。另外养成随时/clear和及时落盘的习惯这两个小动作能帮你省掉很多麻烦。最后分享一个我最近发现的小技巧在提问的时候把我想要什么和我试过什么一起说清楚它的回答质量会高很多。比如我想提升视频分类准确率已经试过调学习率和加数据增强效果不明显你帮我分析可能的原因比单纯问怎么提升准确率要有效得多。这个技巧适用于所有 AI 助手不只是 Gemini CLI。