用 OpenCode + Gemini 在终端里让 AI 帮你审代码、重构逻辑

2026-05-13 24 预计阅读时间:1 分钟
来源:realpython.com AI 摘要 原文链接

免责声明:本文为 AI 摘要整理,建议结合原文阅读。摘要可能省略上下文、版本差异或边界条件,不作为官方说明。

预计阅读时间:9 分钟

终端里跑 AI 编程助手,已经不是新鲜事——但大多数方案要么绑 IDE,要么要付费订阅。OpenCode 是一个开源的终端 AI 编程助手,支持多种 LLM 后端,其中最实用的组合是:OpenCode + Gemini 免费 API Key。零成本、纯命令行,直接对本地 Python 项目做代码审查和重构建议。

OpenCode 是什么,为什么值得试

OpenCode 是一个用 Go 写的开源 CLI 工具,定位类似 Cursor 的终端版,但不绑任何 IDE 或付费平台。核心能力:

  • 在终端里以对话方式与 LLM 交互,上下文自动包含你指定的文件
  • 支持多模型后端(Gemini、OpenAI、Anthropic、本地 Ollama 等)
  • 可以直接读取本地代码文件,让 AI 基于真实代码做分析和修改建议
  • 输出代码片段时带语法高亮,方便直接复制

和 Cursor、Copilot 的区别:OpenCode 不嵌入编辑器,而是把终端变成一个"AI 代码顾问"。你不需要换编辑器,不需要改工作流,只需要在旁边开一个终端窗口。

拿到 Gemini 免费 Key 并配置

Gemini API 目前提供免费额度(每分钟 15 次请求、每天 1500 次),对个人开发者日常使用足够。

第一步:获取 API Key

访问 Google AI Studio,登录后点击 "Get API Key",创建一个项目即可拿到 Key。

第二步:配置 OpenCode

OpenCode 的配置文件放在 ~/.config/opencode/config.json,也可以用环境变量。最简单的方式:

# 安装 OpenCode(macOS / Linux)
curl -fsSL https://opencode.ai/install.sh | bash

# 或者用 Go 直接编译
go install github.com/opencode-ai/opencode@latest

# 设置 Gemini API Key
export GOOGLE_API_KEY="你的-gemini-api-key-here"

# 在项目目录启动
cd ~/projects/my-python-app
opencode

启动后 OpenCode 会自动检测当前目录的文件结构,你可以在对话中引用任意文件。

如果想把 Key 写进配置文件持久化:

// ~/.config/opencode/config.json
{
  "provider": {
    "google": {
      "apiKey": "你的-gemini-api-key-here"
    }
  },
  "model": "gemini-2.5-flash"
}

推荐用 gemini-2.5-flash——速度快、免费额度内,对代码分析和重构任务足够胜任。复杂推理场景可以切换到 gemini-2.5-pro,但免费额度消耗更快。

实战:让 AI 审一段 Python 代码并给出重构方案

假设你项目里有个处理 CSV 数据的模块 data_loader.py,逻辑有点乱,想让它帮你审查和重构。

原始代码(data_loader.py):

import csv
from collections import defaultdict

def load_data(path):
    result = []
    with open(path, 'r') as f:
        reader = csv.DictReader(f)
        for row in reader:
            if row['status'] != 'active':
                continue
            if row['amount'] == '' or row['amount'] is None:
                row['amount'] = 0
            else:
                row['amount'] = float(row['amount'])
            result.append(row)
    return result

def summarize(data):
    totals = defaultdict(float)
    for row in data:
        totals[row['category']] += row['amount']
    return totals

在 OpenCode 终端里发起对话:

> /add data_loader.py

> 这段代码有几个问题:amount 字段的空值处理不安全,
  summarize 函数没有处理 category 为空的情况,
  load_data 里缺少异常处理。请审查并给出重构版本,
  要求:用 dataclass 替代裸 dict,加上类型标注,
  补上异常处理和边界情况。

OpenCode 会读取 data_loader.py 的内容,把完整代码作为上下文发给 Gemini,然后返回审查意见和重构代码。你大概率会收到类似这样的建议:

import csv
from collections import defaultdict
from dataclasses import dataclass
from pathlib import Path
from typing import Optional

@dataclass
class Record:
    category: str
    amount: float
    status: str

class DataLoadError(Exception):
    pass

def load_data(path: Path) -> list[Record]:
    if not path.exists():
        raise DataLoadError(f"File not found: {path}")

    records: list[Record] = []
    try:
        with open(path, "r", encoding="utf-8") as f:
            reader = csv.DictReader(f)
            for row in reader:
                if row.get("status", "").strip().lower() != "active":
                    continue
                category = row.get("category", "uncategorized").strip()
                amount = _parse_amount(row.get("amount"))
                records.append(Record(category=category, amount=amount, status="active"))
    except csv.Error as e:
        raise DataLoadError(f"CSV parsing failed: {e}") from e

    return records

def _parse_amount(raw: Optional[str]) -> float:
    if raw is None or raw.strip() == "":
        return 0.0
    try:
        return float(raw.strip())
    except ValueError:
        return 0.0

def summarize(records: list[Record]) -> dict[str, float]:
    totals: dict[str, float] = defaultdict(float)
    for r in records:
        totals[r.category] += r.amount
    return dict(totals)

关键改进点一目了然:dataclass 替代裸 dict、类型标注全覆盖、_parse_amount 抽成独立函数处理脏数据、Path 替代字符串路径、异常链保留原始错误信息。

你可以直接把建议代码复制回 data_loader.py,或者让 OpenCode 帮你写入:

> 把重构版本写入 data_loader.py

几个高频用法

除了代码审查和重构,OpenCode 在终端里还能做这些事:

1. 快速理解陌生代码

> /add src/core/engine.py
> 用中文解释这个文件的核心逻辑,列出关键函数和调用关系

2. 生成测试

> /add data_loader.py
>  load_data  summarize  pytest 测试,覆盖正常路径、
  空文件、字段缺失、amount 为非数字字符串的情况

3. 逐文件排查问题

> /add tests/test_api.py src/api/handlers.py
> test_api.py 里第 3 个测试为什么失败?对比 handlers.py 找原因

/add 命令可以多次使用,把多个文件加入上下文。Gemini 的上下文窗口足够容纳几个中等规模的 Python 文件。

限制和取舍

方面 说明
免费额度 Gemini Flash 每天 1500 次请求,重度使用可能不够;Pro 额度更少
上下文长度 单次对话能容纳的代码量受模型窗口限制,超大文件需要分段处理
不会自动改文件 OpenCode 默认只输出建议,需要你确认后才写入,这是安全设计
终端体验 没有 IDE 内联补全的流畅感,更适合"对话式"场景而非实时补全
模型选择 Gemini 对中文指令响应良好,但复杂多文件推理不如 Claude Sonnet

上手清单

  1. 去 Google AI Studio 拿一个免费 Gemini API Key
  2. 安装 OpenCode,把 Key 写进配置或环境变量
  3. 选一个你想改善的 Python 项目,cd 进去,启动 opencode
  4. /add 把目标文件加入上下文,提一个具体的审查或重构请求
  5. 拿到建议后手动确认再写入——别让 AI 无审查地改你的代码

OpenCode 的价值不是替代你写代码,而是在终端里给你一个随时可问的、懂你项目上下文的代码顾问。免费、开源、不绑 IDE——试试看,最坏的结果也就是发现它不适合你的场景,成本为零。


相关推荐