gemini-guide

Gemini 指南

使用 Google Gemini 构建应用时，查阅 Gemini API 文档和 SDK 模式。本技能将 Gemini 文档带给 Claude——它不会调用 Gemini。

技能	方向	工具
gemini-guide（本技能）	Gemini 文档 -> Claude	WebFetch、本地文档
gemini-peer-review	代码 -> Gemini	直接调用 Gemini API

文档来源

按以下优先级顺序查阅：

优先级	来源	适用场景
1	GitHub codegen_instructions	始终最新的 SDK 模式 — 获取 https://raw.githubusercontent.com/googleapis/js-genai/refs/heads/main/codegen_instructions.md
2	通过 WebFetch 获取 Google AI 文档	官方文档 — https://ai.google.dev/gemini-api/docs/{topic}（添加 .md.txt 可获取 Markdown 格式）
3	本地缓存文档（如位于 ~/Documents/google-gemini-context/）	预先获取的主题 — 24 个 JS、24 个 Python、7 个通用主题

查询工作流

用户询问 Gemini 相关主题时：

1. 先检查更正说明：阅读 references/deprecated-patterns.md——编写代码前先了解不该推荐哪些内容
2. 获取最新 SDK 模式：获取 GitHub 上的 codegen_instructions.md，以掌握始终最新的模式
3. 将查询映射到主题：阅读 references/topic-index.md——如果 ~/Documents/google-gemini-context/ 中存在本地文档，则阅读对应文件；否则使用 WebFetch 访问 https://ai.google.dev/gemini-api/docs/{topic}.md.txt
4. 综合整理：结合文档，给出清晰且包含可运行代码示例的回答。始终采用步骤 1 中的正确模式。

快速更正

以下是最常见的错误。即使不阅读完整参考资料，也要应用这些更正：

Claude 可能会建议	正确写法
@google/generative-ai	@google/genai
google-generativeai（Python）	google-genai
GoogleGenerativeAI	GoogleGenAI
genAI.getGenerativeModel()	ai.models.generateContent()
model.startChat() / chat.sendMessage()	ai.chats.create() / chat.send()
generationConfig	config
stream=True（方法参数）	config={"stream": True}
gemini-pro	gemini-2.5-flash
gemini-pro-vision	gemini-2.5-flash（统一的多模态模型）
4 个安全类别	5 个类别（包括 HARM_CATEGORY_CIVIC_INTEGRITY）
HARM_CATEGORY_DANGEROUS_CONTENT	HARM_CATEGORY_DANGEROUS（不含 _CONTENT）
X-Goog-Api-Key（首字母大写）	x-goog-api-key（小写）
每日速率限制	没有每日限制——只有每分钟限制（RPM、TPM）

正确的初始化方式（JS）

import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({});  // auto-reads GEMINI_API_KEY env var
const response = await ai.models.generateContent({
  model: "gemini-2.5-flash",
  contents: "Your prompt"
});

正确的初始化方式（Python）

from google import genai
client = genai.Client()  # auto-reads GEMINI_API_KEY env var
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Your prompt"
)

本地文档（可选）

如果你有位于 ~/Documents/google-gemini-context/ 的本地缓存，其中包含：

目录	内容
javascript/	24 个主题文件——快速入门、函数调用、流式传输、结构化输出等
python/	24 个主题文件——与 JavaScript 相同的主题
common/	7 个跨语言文件——安全、定价、速率限制、错误、身份验证、区域、OpenAI 兼容性
rest-api/	REST 端点文档
MODELS.md	当前模型 ID、功能、令牌限制、速率限制
googlegenai-gemini-api.md	全面的 SDK 指南（608 行，JS + Python）

如果本地文档不可用，则使用 WebFetch 查阅 Google AI 文档（添加 .md.txt 可获取 Markdown 格式）。

当前模型

模型	ID	适用场景
Gemini 2.5 Pro	gemini-2.5-pro	复杂推理、高级编码
Gemini 2.5 Flash	gemini-2.5-flash	大多数任务（推荐默认使用）
Gemini 2.5 Flash-Lite	gemini-2.5-flash-lite-preview-06-17	预算有限、低延迟
Gemini 2.0 Flash	gemini-2.0-flash	快速推理
Text Embedding	text-embedding-004	语义搜索、RAG（768 维）

如需完整的模型详情，请查看 ~/Documents/google-gemini-context/MODELS.md（如果可用），或访问 https://ai.google.dev/gemini-api/docs/models。

维护

如果发现信息似乎有误或已过时：

1. 检查 GitHub 的 codegen_instructions.md（始终保持最新）
2. 对照 https://ai.google.dev/gemini-api/docs/models 核实模型 ID
3. 向用户指出过时的文档

参考文件

何时	阅读
将查询映射到文档文件时	references/topic-index.md
编写代码前检查已弃用模式时	references/deprecated-patterns.md