gemini

@rules/routing.md

Gemini 技能

<output_language>

默认将所有面向用户的交付内容、保存的成果、报告、计划、生成的文档、摘要、交接说明、提交/消息草稿和验证说明设为韩语，即使此规范技能文件是用英语编写的。

保留源代码标识符、CLI 命令、文件路径、架构键、JSON/YAML 字段名、API 名称、包名、专有名词和引用的源文本片段，并使用其必需语言或原始语言。

仅在用户明确要求使用其他语言、现有目标成果必须使用其他语言以保持一致，或机器可读契约要求使用精确的英语标记时，才使用其他语言。如果存在本地化模板或参考资料（例如 *.ko.md 或 *.ko.json），优先将其用于面向用户的成果。

</output_language>

封装官方 Google Gemini CLI，用于推理、研究、计划模式审查和会话续接。必须通过 -p / --prompt 以无头模式调用 CLI——位置参数形式的提示词会打开交互式 REPL。

<instruction_contract>

字段	契约
意图	仅当用户明确要求使用 Gemini CLI 或 Gemini 模型时，构建、运行或说明安全的 gemini CLI 调用。
范围	负责 Gemini CLI 命令格式、无头提示词用法、审批模式选择、仅在用户要求时选择模型、恢复流程、运行前检查和结果摘要。
权限依据	优先遵循用户意图和本地项目规则；涉及当前行为的标志时，以已安装的 CLI 帮助信息和官方 Gemini CLI 文档为准。
证据	答案应以运行前检查、命令格式、CLI 输出、审批模式以及观察到的警告/错误为依据。
工具	仅当用户要求运行 CLI 时才使用 shell 执行；否则提供命令或转交处理。
输出	返回实际使用或建议使用的精确命令，概述输出/警告，并原样保留 CLI/模型标记。
验证	构建命令前检查是否已安装 gemini；非交互式运行使用 -p；明确指定编辑/yolo 模式；仅在用户要求时覆盖模型。
停止条件	构建或运行所请求的 Gemini 命令，并报告结果、警告或阻碍后即停止。

</instruction_contract>

默认值

参数	默认值
模型选择	使用 Gemini CLI 默认值（-m auto），除非用户明确要求 -m pro、-m flash、-m flash-lite 或特定 ID
审批模式	--approval-mode default（每次工具调用都会提示）
无头模式	-p / --prompt
恢复目标	gemini --resume latest（或使用 gemini -r 恢复最近的会话）
输出格式	text（仅当调用方需要结构化输出时才使用 --output-format json）

除非用户明确要求指定模型，否则不要指定 -m。自动路由会为推理选择 Pro，为执行选择 Flash。

路由

仅在请求确实需要 Gemini CLI 或 Gemini 会话时使用此技能。

• 如果请求可能超出范围，在构建命令前阅读 rules/routing.md。
• 如果用户希望进行通用写作、整理运行手册，或在不需要 Gemini CLI 的情况下进行本地编辑，则转交给直接编辑或其他技能。

示例

正面示例：

• “用 Gemini 审查这个架构并列出风险。”
• “运行 gemini -p 并研究当前的 API 行为。”
• “请 Gemini Pro 推理这个设计权衡。”
• “恢复最新的 Gemini 会话并继续分析。”

反面示例：

• “重写这份运行手册，让它更易读。”
• “直接修改这段本地代码。”
• “为这个仓库创建一个新技能。”

边界示例：

• “研究 Gemini CLI 的审批模式并解释。” 仅当用户希望使用 gemini CLI 时才使用此技能；否则转交给研究工作或直接文档处理。

重要：无头模式

运行非交互式 Gemini 时，始终使用 -p / --prompt。位置参数提示词会进入交互式 REPL，导致自动化流程阻塞。

# Correct — non-interactive
gemini --approval-mode default -p "your prompt here"

# Interactive (do not use for automation)
gemini "your prompt here"

如果需要先设置提示词，然后继续进行交互式对话，请改用 -i / --prompt-interactive。-p 用于一次性自动运行。

运行任务

更改审批模式、添加沙箱、选择模型或恢复会话前，请阅读 references/recipes.md，了解具体的命令示例。

选择审批模式

标志	使用时机
--approval-mode default	常规研究、推理和标准 Gemini 用法
--approval-mode auto_edit	仅在用户明确要求 Gemini 编辑文件时使用
--approval-mode plan	只读规划或分析，不修改代码（仅允许写入 plans 目录中的 Markdown 文件）
--approval-mode yolo	仅在用户明确批准全自动运行后使用。优先使用此写法——单独使用 --yolo 标志已弃用。

命令规范

• 从 gemini --approval-mode default -p "your prompt here" 开始。
• 仅在用户明确要求使用特定 Gemini 模型时，才添加 -m <pro|flash|flash-lite|auto|model-id>。
• 常规编辑使用 --approval-mode auto_edit，而非全自动批准。
• 使用 --approval-mode yolo 前先征求用户同意。优先使用 --approval-mode auto_edit 或 --sandbox。
• 当任务风险较高或需要更严格的本地限制时，添加 --sandbox（-s）。
• 当 Gemini 需要当前文件夹之外的上下文时，使用 --include-directories /path/a,/path/b 传入其他工作区。
• 仅当调用方会以编程方式解析响应时，才使用 --output-format json。

恢复会话

gemini --resume latest -p "your follow-up prompt"
gemini --list-sessions
gemini --delete-session 2

--resume 可接受 latest、--list-sessions 列出的索引，或完整的会话 UUID。在交互式会话中，使用 /resume 打开 Session Browser，使用 /rewind 回退。

恢复会话时，保留现有的会话行为；除非用户提出要求，否则不要更改模型或审批模式。

完成后

• 总结结果，包括任何警告或部分输出。
• 告知用户可以使用 gemini --resume latest（或 gemini -r）恢复会话。
• 询问用户是要继续、调整提示词，还是切换回直接操作。

严格评估

将 Gemini 视为同事，而非权威。

• 有把握时，相信自己的知识。对于错误说法，应直接提出异议。
• 对存在分歧的内容，先查阅当前来源或文档，再决定是否接受 Gemini 的说法。
• 牢记知识截止时间——Gemini 可能不了解近期发布的版本或 API 变更。
• 时效性很重要时，请 Gemini 提供当前来源，并通过文档或一手来源核实重要说法。
• 确实存在歧义时，让用户决定。

预检

构建任何命令前，先确认 CLI 已安装且位于 PATH 中：

command -v gemini >/dev/null 2>&1 || { echo "gemini CLI not found"; exit 1; }

如果检查失败，请转到下方的错误处理中的安装流程，而不要构建 gemini ... 命令。

错误处理

• command not found: gemini：告知用户使用 npm install -g @google/gemini-cli（或 brew install gemini-cli）安装。
• 身份验证错误：运行 gemini 并完成登录流程，或设置 GEMINI_API_KEY。对于 Vertex AI，请设置 GOOGLE_API_KEY 和 GOOGLE_GENAI_USE_VERTEXAI=true。
• 429 / 速率限制：Gemini 3 的免费层级限制为 60 次请求/分钟、1000 次请求/天——请稍后重试或升级。
• 404 / 找不到模型：不带 -m 重试，或从 gemini --help 和官方文档中选择 pro、flash 或 flash-lite。
• 403 / 拒绝访问：检查当前使用的身份验证方式，并使用受支持的模型或账号配置重试。
• 找不到会话：运行 gemini --list-sessions。
• 退出代码 42 表示输入错误（标志或提示词无效）；53 表示超出轮次限制。

版本说明

• 目标行为对应 Gemini CLI v0.40.0；最低支持版本为 v0.21.1（Gemini 3 路由）。
• --yolo 已弃用；规范写法为 --approval-mode yolo。
• 规划模式默认启用；可通过 --approval-mode plan 或会话内的 /plan 显式触发。
• 在非 TTY 环境中，以及提供 -p 时，都会自动启用无头模式。

<validation_checklist>

• 请求明确需要 Gemini CLI、Gemini 模型或 Gemini 会话。
• 在构建可运行的命令前，先检查 command -v gemini 或同等的预检项。
• 非交互式运行使用 -p / --prompt；自动化时不使用位置参数提示词。
• 除非用户明确指定模型，否则省略模型标志。
• 仅在文档规定的条件下使用 auto_edit 和 yolo 审批模式。
• 最终输出包含命令格式、观察到的结果、警告，以及任何安装、身份验证、速率限制或模型方面的阻碍。

</validation_checklist>