用 Gemini CLI 在终端里接手一个有 bug 的小项目

用 Gemini CLI 在终端里接手一个有 bug 的小项目：先用 GEMINI.md 告诉它项目规则，再让它找出按月汇总算错的原因、补上测试、修好代码，最后用非交互模式让它根据 git diff 写提交说明。全程你只负责审核和批准。

先看清成品

成品是一个修好并有测试的 expense.py。本文已在本机实际验证：起始代码 starter/expense.py 把 2026-10-01 汇总成 10-01（按天而不是按月），参考测试 1 个失败；参考答案 reference/expense.py 测试 2 个全部通过，输出 2026-09 35.50、2026-10 160.10。Gemini CLI 0.65.0 已安装，命令行参数用 --help 核对过。本文环境没有登录 Google 账号，没有实际让 Gemini 修改代码，它的回答每次也会不同，请以你实际看到的为准。

注意：Gemini API 和 Google AI Studio 只在官方“可用地区”列表中的国家和地区提供，请在可用地区合规使用，不要用代理绕过地区限制。Gemini API 条款写明，使用免费服务时提交的内容可能被用于改进 Google 产品，不要上传含身份证号、银行卡号、他人隐私的材料。价格和免费额度以官方价格页为准。

做完之后你会得到什么？

成果	说明
项目规则文件	`GEMINI.md`，每次启动自动读取
修好的代码	按月汇总，用 Decimal 避免小数误差
测试	`test_expense.py`
提交说明	非交互模式根据 diff 生成

需要准备哪些环境？

项目	要求	说明
Node.js	20 或更高	本文使用 22.23.3
Gemini CLI	`npm install -g @google/gemini-cli`	本文使用 0.65.0；也可 `brew install gemini-cli`
登录方式	Google 账号或 `GEMINI_API_KEY`	首次运行时选择
Python	3.10 或更高 + pytest	运行项目测试
Git	任意版本	方便查看和撤销改动

第一步：准备起始项目

1. 项目文件

expense/
├── GEMINI.md
├── expense.py
└── data.csv

expense.py（故意带 bug）：

"""按月汇总记账 CSV。用法：python expense.py data.csv"""
import csv
import sys
from collections import defaultdict


def monthly(rows):
    out = defaultdict(float)
    for r in rows:
        month = r["date"][5:10]          # 期望得到 2026-10 这样的月份
        out[month] += float(r["amount"])
    return dict(out)


def main(path):
    with open(path, encoding="utf-8") as f:
        rows = list(csv.DictReader(f))
    for m, total in sorted(monthly(rows).items()):
        print(m, total)


if __name__ == "__main__":
    main(sys.argv[1])

data.csv：

date,category,amount
2026-09-28,餐饮,35.5
2026-10-01,交通,12
2026-10-01,餐饮,48.2
2026-10-15,日用,99.9

2. 先确认 bug 存在

python expense.py data.csv

本文实际输出：

09-28 35.5
10-01 60.2
10-15 99.9

期望的是按月汇总，显然不对。

3. GEMINI.md

# 项目说明

这是一个按月汇总记账 CSV 的小工具，只用 Python 标准库。

## 约定

- Python 3.10+，不要引入第三方依赖（测试用 pytest 除外）
- 金额用 `decimal.Decimal` 计算，输出保留两位小数
- 测试放在 `test_expense.py`，用 pytest，运行命令：`python -m pytest -q`
- 回答和代码注释使用简体中文
- 修改代码前先说明计划，改完后运行测试

Gemini CLI 会自动读取项目里的 GEMINI.md 作为上下文。不想手写的话，可以在 CLI 里输入 /init 让它生成初稿再修改。

git init && git add . && git commit -m "起始版本"

第二步：怎样和 Gemini CLI 协作？

1. 启动

cd expense
gemini

第一次会让你选择登录方式。进入后输入 /memory show，确认它读到了 GEMINI.md。

2. 先只读分析

建议先用只读的计划模式启动，让它只分析不改动：

gemini --approval-mode plan

粘贴提示词：

python expense.py data.csv 的结果是按天汇总的，但应该按月汇总（例如 2026-10）。
请先阅读 expense.py，说明 bug 的原因，并给出修复和测试计划。先不要修改文件。

期望它指出 r["date"][5:10] 取错了切片，应改为 [:7]，并提到 GEMINI.md 要求的 Decimal。

3. 让它动手

退出后用默认模式重新启动（每次修改文件、执行命令都会请你批准）：

gemini

按刚才的计划修复：
1. 先写 test_expense.py，覆盖跨月数据、0.1+0.2 这类小数、空数据
2. 运行测试，确认失败
3. 修改 expense.py
4. 再运行测试，确认全部通过

每次弹出的修改都看一眼 diff 再批准。

4. 自己验证

python -m pytest -q
python expense.py data.csv
git diff

参考答案（本文实际运行结果）：

2 passed
2026-09 35.50
2026-10 160.10

Gemini 写出的测试数量和细节可能不同，只要覆盖了上面几种情况、结果正确即可。参考答案在本文 -src/reference 里。

第三步：怎样用非交互模式？

-p 会执行一次就退出，适合放进脚本：

git diff | gemini -p "根据这段 diff 写一条中文 Git 提交说明：第一行不超过 50 字，空一行后用要点列出改动。只输出提交说明本身。"

满意后：

git commit -am "修复按月汇总并改用 Decimal"

需要给程序读取时，可以加 --output-format json。

出问题时该怎么调？

1. 它没遵守 GEMINI.md

用 /memory show 检查是否加载；规则写得越具体越好，例如直接写出测试命令。

2. 改坏了

git checkout -- .

CLI 里也可以用 /restore 回到修改前的检查点（需要启用检查点功能，见官方命令文档）。

3. 它想执行你不认识的命令

拒绝，并让它解释这个命令的作用。不要随手使用 --yolo（自动批准所有操作）。

常见问题怎么处理？

现象	原因	解决方法
登录后提示地区不支持	所在地区不可用	只能在可用地区使用
提示额度用完	达到免费请求上限	等待重置或改用付费 API 密钥
修复了但没写测试	提示词不够明确	明确要求“先写测试”
回答是英文	没写语言要求	在 GEMINI.md 写明使用中文
想换模型	默认模型	用 `-m` 指定

项目资源

用途	地址
Gemini CLI 仓库	https://github.com/google-gemini/gemini-cli
GEMINI.md 上下文文件	https://www.geminicli.com/docs/cli/gemini-md
斜杠命令	https://www.geminicli.com/docs/reference/commands
非交互模式	https://www.geminicli.com/docs/cli/headless
Google AI Studio API 密钥	https://aistudio.google.com/apikey
可用地区	https://ai.google.dev/gemini-api/docs/available-regions

建议先完整走一遍“计划模式分析 → 默认模式修改 → 自己跑测试”，体会每一步该检查什么。

熟悉后再用在自己的项目上，从小而明确的任务开始，每次改动都提交，方便回退。