Gemini 3.8 Flash：GitHub LLM CLI 接入配置与结构化工作流

一句话结论

simonw/llm-gemini 是一个把 Google Gemini 接入 LLM CLI 的插件；仓库当前实现已注册 exact model gemini-3.8-flash，可用 thinking_level=low|medium|high，并能按仓库的 server-side tool 机制接入 Google Search、URL Context 和 Code Execution。适合把一次性提示、结构化 JSON 输出和可审计的工具调用统一到命令行工作流中。

适用场景

• 适合的任务：代码/文档分析、批量命令行问答、结构化信息抽取、多模态文件描述，以及需要搜索或代码执行工具的受控 Agent 流程。

• 不适合的任务：把 CLI 命令当成权限系统、把工具输出当成事实保证，或让模型未经人工确认执行本机写入、部署和删除操作。

• 适用的模型版本：仓库注册的 gemini-3.8-flash；README 的可用模型列表同时展示完整名 gemini/gemini-3.8-flash，并说明可省略 gemini/ 前缀。因此本文命令使用 exact model gemini-3.8-flash。

• 适用的客户端、Agent 或 API：LLM CLI + llm-gemini Python 插件；插件通过 Gemini API 访问模型。它不是 Google AI Studio、Antigravity 或 IDE 原生 Agent 配置。

• 推荐的推理档位和参数：由仓库实现暴露 low、medium、high 三档 thinking_level。先用 medium 建立质量基线，再按延迟或复杂度改用 low / high；不要把该仓库的通用 LLM 选项映射推断成 Gemini API 的长期兼容承诺。

可直接使用的内容

1. 安装与密钥配置

以下命令来自仓库 README。密钥只应写入 LLM 的本地密钥存储，或通过环境变量注入，不要写入提示词、仓库文件或 shell 脚本。

# 在与 LLM CLI 相同的 Python 环境中安装插件
llm install llm-gemini

# 交互式写入本地 key store；出现提示后粘贴 Gemini API key
llm keys set gemini

# 或使用环境变量（仅对当前进程/会话生效）
export LLM_GEMINI_KEY='YOUR_GEMINI_API_KEY'

用模型列表和一次短请求做连通性检查：

# 应在列表中看到 gemini/gemini-3.8-flash
llm models -q gemini

# exact model ID；-o 使用 LLM CLI 的 key/value option 语法
llm -m gemini-3.8-flash -o thinking_level medium \
  '用三句话说明这段命令的用途，并列出一个需要人工确认的风险。'

如果希望固定默认模型，README 还提供了以下配置方式：

llm models default gemini-3.8-flash
llm '把下面的会议记录整理成三个行动项，每项包含负责人、截止日期和待确认信息。'

2. 用户提示模板：分析、约束、验收

下面是适配 LLM CLI 的用户模板，不是仓库声称的模型 system prompt。把完整任务作为一个字符串传给 CLI；需要引用文件时，可再加 -a 附件参数。

角色：你是一个严谨的技术分析助手。

任务：根据“输入材料”回答“用户问题”。

约束：
1. 只把输入材料中能核对的内容当作事实；缺失信息写“未提供”。
2. 不执行本机写入、删除、部署或发布动作；需要这类动作时先列出命令和风险。
3. 将推断与事实分开标记，并指出仍需人工确认的地方。

输出格式：
{
  "结论": "不超过 3 句",
  "证据": ["与结论直接相关的事实"],
  "建议动作": ["可执行且不改变外部状态的步骤"],
  "待确认": ["信息缺口或风险"]
}

输入材料：
[粘贴材料或通过 -a 提供附件]

用户问题：
[写出一个可验收的问题]

配合仓库 README 的 JSON 输出选项，可以这样运行：

llm -m gemini-3.8-flash \
  -o thinking_level medium \
  -o json_object 1 \
  '请按下方模板分析当前目录中的 API 变更说明。只返回合法 JSON；没有证据的字段填“未提供”。

输出字段：结论、证据、建议动作、待确认。'

3. 多模态与结构化工作流

仓库 README 展示了图片、音频、视频和 YouTube URL 通过 -a 附件进入 Gemini 的方式。对本地文件先做只读分析，再由人工决定是否把结论带入后续操作：

# 图片文字/界面审阅
llm -m gemini-3.8-flash -o thinking_level low \
  '提取图片中可见的错误信息，并按“事实 / 推测 / 待确认”分组。' \
  -a screenshot.png

# 视频时间线摘要；media_resolution 是仓库 README 公开的选项
llm -m gemini-3.8-flash \
  -o thinking_level medium \
  -o media_resolution low \
  '按时间顺序描述视频中的关键变化，不要臆测画面外的信息。' \
  -a recording.mp4

建议将工作流固定为：

输入（文本/附件）
  -> Gemini 3.8 Flash 分析（thinking_level 明确记录）
  -> JSON/表格化输出
  -> 人工检查证据与待确认项
  -> 单独的、经过授权的执行步骤
  -> 记录结果和失败原因

4. 受控 server-side tool 工作流

仓库 README 给出 -T CodeExecution、-T GoogleSearch 和 -T URLContext 的调用语法；仓库实现还把 gemini-3.8-flash 放入对应的 Gemini 3 能力判断中。下面的 exact-model 命令是依据同一仓库实现对 README 示例的 3.8 适配：

# 让模型在 Gemini 的服务端沙箱中计算；仍需审阅生成的代码和结果
llm -m gemini-3.8-flash \
  -o thinking_level medium \
  -T CodeExecution \
  '只用 Python 计算 (13 的阶乘) * 3，返回计算过程摘要和最终数字。'

# 需要时启用 Google Search；不要把搜索结果直接当作已核实结论
llm -m gemini-3.8-flash \
  -o thinking_level high \
  -T GoogleSearch \
  '检索指定主题的最新公开信息，逐条列出来源线索、日期和仍需人工核对的事实。'

# URL Context 用于读取提示中给出的 URL；控制 URL 范围并检查敏感内容
llm -m gemini-3.8-flash \
  -o thinking_level medium \
  -T URLContext \
  '只总结这个 URL 中与版本变更相关的段落，并返回原文标题和页面日期。'

工具调用的最小验收规则：

1. 先用无工具请求确认任务和输出字段。
2. 只开启当前任务所需的一个工具，并明确搜索/URL/代码范围。
3. 将工具结果与模型结论分开记录；失败时不得补猜。
4. 涉及外部写入、部署、付款或删除时停止在建议命令，等待人工授权。

测试/工作流步骤

1. 固定 Python 环境，安装 llm-gemini，并用 llm models -q gemini 确认 gemini/gemini-3.8-flash 已注册。

2. 用 thinking_level=medium 运行一条短文本 smoke test；记录 exact model、输入类型、选项和响应是否成功。

3. 用上面的 JSON 模板跑一组代表性任务，检查 JSON 合法性、证据覆盖、缺失信息标记和待确认项。

4. 再单独测试图片/音频/视频附件；只在确有必要时启用 CodeExecution、GoogleSearch 或 URLContext，并记录工具失败。

5. 用 llm logs -c --json 查看当前会话的结构化日志和（若有）Gemini grounding metadata；导出前删除提示词中的密钥、个人数据和内部 URL。

6. 若要把插件源码纳入生产依赖，锁定已审核的仓库 commit 或发布版本，并在升级后重复模型注册、推理档位、工具和失败降级测试。

原始证据与数据

适用边界与安全边界

• main 分支和插件版本会变化；本文采集的是 2026-09-08 浏览到的仓库状态，生产环境应锁定经过审查的 commit/版本，并重新确认 exact model 是否仍出现在 register_models。

• README 的部分工具示例使用 gemini-3.6-flash；本文将同一语法用于 3.8，是由 llm_gemini.py 的能力集合和模型注册代码支持的仓库内适配，不等于 Google 或插件作者为每个工具发布了独立的 3.8 兼容性声明。

• 插件的通用 LLM 选项会被转换到 Gemini 请求字段；不要把 temperature、top_p、top_k、max_output_tokens 等选项的“能传入”误解成当前模型/API 对其语义或组合提供保证。优先只设置仓库明确暴露且经 smoke test 验证的 thinking_level。

• API key 具有调用权限和费用风险。不要把 key 放进 Markdown、Git、提示词、日志或工单；共享 llm logs 前先脱敏，并为生产 key 设置最小权限和轮换机制。

• Code Execution 虽在 Gemini 服务端沙箱中运行，仍应审阅生成代码、输入数据和结果；不要把它当成本机安全边界，也不要根据输出自动执行本机命令。

• Google Search 与 URL Context 会引入外部内容、时效性和潜在提示注入；限制可访问 URL/主题，保留来源和日期，并把外部文本视为不可信输入。

• includeThoughts、grounding metadata 或工具事件可能进入响应/日志。不要将包含内部上下文、个人数据、私有 URL 或敏感业务信息的原始日志发送给第三方。

• 模型调用、工具调用和 JSON 输出都可能失败。失败时命令行脚本应保留原始输入和错误状态，停止在人工可审阅的结果，不要以“模型已完成”作为上线或写入依据。

来源摘录或观察（仅做合规短引）

仓库 README 将模型列为 gemini/gemini-3.8-flash: Gemini 3.8 Flash；对应实现进一步把它注册为可用模型，并为该模型暴露 low、medium、high 三个 thinking level。本文只据此说明 LLM CLI 的接入和工作流，不将仓库的适配代码扩展为所有 Gemini 客户端的兼容性承诺。