OpenCLI Gemini Adapter 实战指南用浏览器会话在命令行驱动 Gemini Web【免费下载链接】OpenCLIMake Any Website into CLI Use your logged-in browser by AI agent.项目地址: https://gitcode.com/gh_mirrors/ope/OpenCLI本指南围绕 docs/adapters/browser/gemini.md 展开系统讲解 OpenCLI 如何通过已登录的浏览器会话把gemini.google.com消费版 Web UI 变成一套可脚本化的命令行接口opencli gemini。读完本文你将掌握 Gemini 的对话问答、图像生成、模型枚举、Deep Research 启动与报告导出、历史会话管理等全部子命令的用法与参数并理解其背后驱动真实浏览器而非公共 API的实现原理与注意事项。Gemini 适配器是什么Gemini 适配器是 OpenCLI 众多网站适配器之一通过 Browser Bridge 扩展 与正在运行的 Chrome 通信复用你已登录的浏览器会话操作 Gemini 网页。它不调用 Gemini 公共 API而是直接驱动消费版网页自动定位输入框composer、点击模型选择器、读取对话快照、等待回复生成。该适配器对应源码位于 clis/gemini/包含ask、image、models、new、deep-research、deep-research-result、status、history、detail、read共 10 个命令。核心工具函数集中在 utils.js约 2700 行其中定义了域名常量、composer 定位脚本、对话快照读取脚本、回复去噪逻辑等。从 utils.js 可以看到适配器的目标域与入口页export const GEMINI_DOMAIN gemini.google.com; export const GEMINI_APP_URL https://gemini.google.com/app;所有opencli gemini命令的domain均指向该域名并以Strategy.COOKIE策略复用浏览器 Cookie 会话和siteSession: persistent持久站点会话运行。环境要求Prerequisites使用前需满足以下三个条件对应原文档 Prerequisites 章节Chrome 正在运行适配器通过浏览器桥接控制已打开的 Chrome 实例已登录gemini.google.com命令复用的是登录态不会替你处理账号密码已安装 Browser Bridge 扩展它是 OpenCLI 与浏览器页面之间的通信通道。此外可参考 入门指南 和 安装指南 完成 OpenCLI 本身的安装配置。命令总览CommandDescriptionopencli gemini newStart a new Gemini web chatopencli gemini ask prompt [--model value] [--thinking level]Send a prompt and return only the assistant replyopencli gemini image promptGenerate images in Gemini and optionally save them locallyopencli gemini modelsList available Gemini modelsopencli gemini deep-research promptStart a Gemini Deep Research run and confirm itopencli gemini deep-research-result queryExport Deep Research report URL from a Gemini conversationopencli gemini statusCheck Gemini web page availability and login stateopencli gemini history [--limit N]List visible Gemini conversation history from the sidebaropencli gemini detail idOpen a Gemini conversation by id, URL, or sidebar title and read its turnsopencli gemini readRead the turns visible in the current Gemini web conversation从命令的access属性定义于各命令注册处可以看到权限划分只读命令access: readnew、models、status、history、detail、read、deep-research-result写命令access: writeask、image、deep-research。例如 new.js 注册为只读命令并输出Status/Action两列ask.js 注册为写命令、默认纯文本输出status.js 输出Status/Login/Url三列history.js 输出Index/Id/Title/Url四列。快速上手十个命令的实战用法原文档给出了完整的命令行示例下面逐组展开并补充参数说明新建会话opencli gemini new该命令调用startNewGeminiChat(page)优先点击侧边栏 New chat 按钮若按钮不可用则回退为重新加载/app页面源码见 new.js对应startNewGeminiChat返回clicked或navigate两种动作。命令完成后会输出Success / Clicked New chat或Success / Reloaded /app as fallback。问答ask# 发送 prompt只返回助手回复 opencli gemini ask Reply with exactly: HELLO # 指定模型 opencli gemini ask Explain quantum computing in one sentence --model 2.5-flash # 新开会话并延长等待时间 opencli gemini ask Summarize this design in 3 bullets --new true --timeout 90 # 扩展思考模式 opencli gemini ask Explain quantum computing --thinking extended # 标准思考 新会话 opencli gemini ask Hello --new true --thinking standard # 模型 思考等级组合 opencli gemini ask Explain quantum computing in one sentence --model 2.5-pro --thinking extended # 新会话 指定模型 指定思考等级 opencli gemini ask Summarize this design in 3 bullets --new true --model 2.5-flash --thinking standardask的完整执行流程源码见 ask.js值得细说新会话先行若--new true先调用startNewGeminiChat新建会话参数预校验--model必须符合规范 ID 格式见下文--thinking仅接受standard或extended--timeout必须是正整数默认 60 秒模型/思考发现当指定了--model或--thinking时脚本点击模型选择器按钮、等待 React 渲染菜单、读取模型条目后关闭菜单模型选择校验目标模型 ID 存在于发现列表中然后调用selectGeminiModel选中思考等级选择优先按目标模型指定--model时为该模型否则为当前页面模型对应的thinkingValues校验再调用selectGeminiThinking选择发送与等待读取会话快照 →sendGeminiMessage发送 →waitForGeminiSubmission等待提交 →waitForGeminiResponse等待回复。回复以前缀输出纯文本若在超时内未获得回复则返回 [NO RESPONSE] No Gemini response within timeouts.。回复文本会经过 utils.js 的sanitizeGeminiResponseText清洗去除 Gemini can make mistakes、Google Terms 等页面噪音文案并剥离与 prompt 相同的前缀部分。图像生成image# 生成图标指定比例与风格 opencli gemini image Generate a tiny cyan moon icon --rt 1:1 --st icon # 仅在 Gemini 中生成打印页面链接不下载 opencli gemini image A watercolor sunset over a lake --sd true # 自定义图片保存目录 opencli gemini image A flat illustration of a robot --op ~/tmp/gemini-imagesimage命令源码见 image.js有几点实现细节总是新会话每次执行前都会调用startNewGeminiChat确保从干净的对话开始源码硬编码const startFresh true比例与风格会拼进提示词buildImagePrompt会把aspect ratio ratio与style style追加为 Image requirements: ... 段落image.js比例白名单--rt仅接受1:1、16:9、9:16、4:3、3:4、3:2、2:3非法值回退为1:1image.js输出目录解析--op支持~展开与绝对/相对路径默认~/tmp/gemini-imagesimage.js下载逻辑等待图像 URL 出现 → 通过exportGeminiImages导出 base64 → 按 MIME 类型推断扩展名png/webp/gif/jpg→ 保存为gemini_时间戳[_N].ext输出格式不使用表格纯文本输出status / file / link三元组如✅ saved / ~/tmp/gemini-images/gemini_1717....png / 链接--sd true时输出 generated / - / 链接仅保留对话链接不下载超时--timeout默认 240 秒控制整个等待生成过程。若未检测到生成的图片命令会抛出EmptyResultError并提示打开对话链接人工确认image.js。枚举模型models# 列出可用模型 opencli gemini models # 以 JSON 输出便于脚本处理 opencli gemini models -f jsonmodels命令源码见 models.js是只读命令其行为要点与原文档一致从 Gemini Web UI 可见的模型选择器中动态发现可用模型而不是硬编码列表依次执行点击模型选择器按钮 → 等待 React 渲染菜单page.wait(1.0)→ 读取菜单项并解析规范模型 ID → 关闭菜单不会选择模型、更改思考等级、新建会话或提交任何提示词解析逻辑canonicalModelId见 models.js支持从显示文本中提取规范 ID例如3.1 flash-lite→3.1-flash-lite、2.5-flash-thinking→2.5-flash-thinking、Gemini 3.0 Pro experimental→3.0-pro-experimental也兼容带中文描述的条目如3.1 Flash-Lite 极速回答输出两列model规范 ID如2.5-flash、2.5-pro、2.5-flash-lite与thinkingValuesthinkingValues仅在 Gemini 直接在模型条目上暴露思考等级时才填充否则为[]——当前 Gemini UI 通常只对当前激活模型显示思考控件因此该命令不做全模型的推断models.js 注释对此有明确说明当模型选择器无法打开时抛出命令错误用于暴露 Gemini Web UI 的变更仅当选择器成功打开但没有任何模型条目时才返回空列表。Deep Research 启动与报告导出# 启动一次 Gemini Deep Research 运行并确认 opencli gemini deep-research 研究主题 # 从某个会话导出 Deep Research 报告 URL opencli gemini deep-research-result 会话标题或 URLdeep-research源码见 deep-research.js的执行链路是新建会话 → 通过工具菜单选择 Deep Research默认工具标签列表见 utils.js 的GEMINI_DEEP_RESEARCH_DEFAULT_TOOL_LABELS同时兼容英文 Deep Research 与中文 深度研究→ 发送提示词 → 等待提交 → 等待确认按钮默认标签 Start research / 开始研究 等见GEMINI_DEEP_RESEARCH_DEFAULT_CONFIRM_LABELS→ 输出status / url。实现上还包含多重容错提交失败时自动重试一次重新选工具、重新发送确认点击出现假阳性仍在/app根 URL时重试确认若页面先渲染出研究计划卡片会再次点击确认按钮不重复发送 prompt避免产生重复会话通过parseDeepResearchProgress解析回复文本判断是否处于 researching研究中状态。--tool与--confirm参数可覆盖默认标签--timeout默认 180 秒其中提交等待被内部限制在 6~20 秒。deep-research-result源码见 deep-research-result.js用于导出报告query可选可以是会话标题或URL缺省时取最新会话--match contains|exact控制标题匹配模式默认contains若是 URL 且属于gemini.google.com/app/路径直接跳转否则先从侧边栏会话列表解析目标会话等待导出后返回Docs 报告 URL若研究仍在运行返回提示等待重试若已完成但未找到 Docs URL提示在 Gemini UI 中通过 Share Export → Export to Docs 手动导出。状态、历史、详情与阅读# 检查页面可用性与登录状态 opencli gemini status # 列出侧边栏可见的历史会话默认 20 条最多 200 条 opencli gemini history [--limit N] # 按 id / URL / 侧边栏标题打开会话并读取轮次 opencli gemini detail id # 读取当前 Gemini 会话中可见的轮次 opencli gemini readstatus通过getGeminiPageState检测页面 URL、标题、登录态是否存在 Sign in / 登录 链接或 Google 登录跳转、composer 是否可用。isSignedIn为true/false/null三态null表示可见 composer 但未发现显式登录入口按已登录处理status.jshistory从侧边栏收集a[href*/app]链接并展开折叠的 最近 / Recents 分区见 utils.js 的expandGeminiRecentScript过滤掉无 ID 的 New chat 项输出Index / Id / Title / Url--limit必须为 1~200 的整数history.jsread读取当前页面可见的对话轮次输出Index / Role / TextRole取User或Assistant无可读轮次时抛出EmptyResultErrorread.js。轮次提取脚本见 utils.js 的getTurnsScript通过[data-testid*message]、[data-test-id*message]、[class*message]等选择器定位消息节点并结合 DOM 顺序排序、按data-message-author-role等属性推断角色detail接受会话 ID、完整 URL 或侧边栏标题定位后打开并读取轮次。参数详解ask参数OptionDescriptionpromptPrompt to send (required positional argument)--modelGemini model to use (e.g.2.5-flash,2.5-pro). Useopencli gemini modelsto list available values.--timeoutMax seconds to wait for a reply (default:60)--newStart a new chat before sending (default:false)--thinkingThinking level:standardorextended(omitted leave unchanged)关于--model的格式约束源码中的validateAskModelValueask.js规定了两条硬性规则必须包含版本号匹配\d\.\d因此pro、flash、flash-lite这类短别名一律被拒绝必须是X.Y-variant的规范格式正则^\d\.\d-[a-z][a-z-]*$例如2.5-flash、3.1-pro合法2.5flash非法。错误信息会明确提示Short aliases like pro, flash, or flash-lite are not supported. Use a canonical model id (e.g. 2.5-flash).关于--thinking仅接受standard或extended大小写不敏感其余值直接抛ArgumentError。指定后脚本会先按目标模型或当前模型的thinkingValues校验可用性再调用selectGeminiThinking实际操作页面控件若无法在 UI 中选中会给出包含可用取值提示的错误。关于--timeout必须是正整数等待回复期间先等提交waitForGeminiSubmission提交成功后再用剩余时间等回复waitForGeminiResponse两个阶段合计不超过--timeout秒ask.js。image参数OptionDescriptionpromptImage prompt to send (required positional argument)--rtAspect ratio shorthand:1:1,16:9,9:16,4:3,3:4,3:2,2:3--stOptional style shorthand, e.g.icon,anime,watercolor--opOutput directory for downloaded images (default:~/tmp/gemini-images)--sdSkip download and only print the Gemini page link补充说明--rt为白名单校验非法值静默回退为1:1--st为自由文本风格会拼入提示词的 Image requirements 段--op支持~开头路径展开未指定时保存到~/tmp/gemini-images文件名形如gemini_毫秒时间戳.png多图时追加_1、_2后缀--sd为布尔开关开启后不下载仅打印 generated / - / 链接另有未在文档表格中列出的--timeout默认 240 秒用于控制整个生成等待。models输出列ColumnDescriptionmodelCanonical model ID (e.g.2.5-flash,2.5-pro,2.5-flash-lite)thinkingValuesPer-model thinking levels only when Gemini exposes them directly on the model entry; otherwise[]. The current Gemini UI usually exposes thinking controls for the active model, so this command does not infer support for every model.补充行为要点与源码一致models从可见的 Gemini Web UI 模型选择器中动态发现可用模型命令是只读的不选择模型、不改变思考等级、不新建会话、不提交提示词模型 ID 与后续gemini ask --model使用的规范格式一致模型选择器无法打开时抛出命令错误用于暴露 Gemini Web UI 变更仅当选择器打开但无模型条目时返回空列表。关键行为细节以下行为均可在源码中得到印证--new true与--model/--thinking的组合顺序先创建新会话再选择模型与思考等级然后读取快照最后提交提示词ask.js 的注释与调用顺序明确说明了这一点ask --model的可见副作用选定模型后该模型在 Gemini Web UI 中保持选中状态省略--model时不会改变当前模型ask.js其余命令不受--model影响image、deep-research等命令不接受--modelask使用极简输出只返回前缀的助手回复文本而不是表格image同样使用纯文本输出打印status / file / link而非表格image总是从全新会话开始startFresh true硬编码--sd启用时图像保留在 Gemini 中只打印会话链接。会话模型与持久化原文档 Caveats 章节提到的一个关键机制是持久站点会话persistent site session。所有 Gemini 命令注册时都带有siteSession: persistent如 ask.js、image.js含义是连续的gemini ask/gemini image/gemini deep-research-result调用会继续使用同一个 Gemini 页面标签而不是每次新建标签页。这样既减少了重复登录/加载开销也让命令之间可以共享上下文。若希望一次性标签one-shot tab执行可以传入--site-session ephemeral。实现原理网页驱动的关键机制为了让文章不仅会用还能理解为什么这样实现下面补充几个源码层面的核心机制1. composer 定位与操作。适配器通过一组选择器定位输入框utils.js优先匹配.ql-editor[contenteditabletrue]其次按aria-label包含 Gemini 或 prompt for Gemini 的[contenteditable]元素。定位成功后会打上data-opencli-gemini-composer标记以去重并通过焦点管理、InputEvent派发等模拟真实输入prepareComposerScript/insertComposerTextFallbackScript。发送时优先点击附近符合条件的发送按钮否则回退为派发 Enter 键事件submitComposerScript/dispatchComposerEnterScript。2. 快照与增量比对。readGeminiSnapshotScript会采集当前页面的 URL、对话轮次turns、文本行transcriptLines、composer 是否有文本、是否正在生成通过是否存在 Stop response / 停止回答 控件判断等状态utils.js。发送 prompt 前后各取一次快照通过比对增量行/追加轮次来确定哪些内容是本次回复从而精准提取助手输出。3. 回复去噪。sanitizeGeminiResponseText会移除 Gemini can make mistakes、Google Terms、Google Privacy Policy、Opens in a new window 等常见页面噪音utils.js 定义的正则列表确保返回给脚本的是干净的回复文本。4. 会话列表与标题定位。侧边栏会话通过a[href*/app]链接收集并自动展开折叠的 Recents / 最近 分区detail支持按标题匹配contains/exact两种模式定位会话标题会先做空白归一化与小写化再匹配utils.js。常见问题与注意事项Caveats原文档明确了以下边界使用时应特别留意该适配器驱动的是 Gemini 消费版 Web UI而非公共 API。这意味着它依赖页面的 DOM 结构行为可能随 Gemini 前端更新而变化依赖当前浏览器会话若 Gemini 出现登录、同意consent、验证challenge、配额quota或其他门禁 UI命令可能失败DOM 或产品变更风险Gemini 页面变化可能破坏 composer 检测、新会话处理或图片导出行为。models命令在模型选择器无法打开时抛出错误正是为了尽早暴露这类 UI 变更持久会话默认在同一个 Gemini 页面中连续操作需要一次性标签时使用--site-session ephemeral。结合测试用例进一步验证仓库为 Gemini 适配器提供了较完整的测试覆盖可作为行为契约参考commands.test.js命令注册与参数契约测试ask.test.jsask命令的模型校验、thinking 校验等行为测试含validateAskModelValue的导出测试入口见 ask.jsmodels.test.js模型发现脚本与规范 ID 解析测试image.test.js、image-pipeline.test.js图像生成管线测试deep-research.test.js、deep-research-result.test.jsDeep Research 启动与导出测试reply-state.test.js回复状态/快照比对逻辑测试utils.test.js工具函数URL 解析、标题匹配、文本清洗、会话列表等测试。这些测试一方面固化了命令行为另一方面也说明该适配器对 Gemini 网页 DOM 的强依赖——任何 UI 改版都可能需要同步调整脚本。小结OpenCLI 的 Gemini 适配器把浏览器会话变成了可编程接口ask负责纯文本问答、image负责图像生成与本地保存、models动态枚举模型、deep-research/deep-research-result覆盖完整的研究闭环status/history/detail/read则提供会话管理与只读巡检能力。它不依赖 Gemini API 密钥仅需一个已登录的 Chrome 与 Browser Bridge 扩展即可工作非常适合与 OpenCLI 的自动化管线、脚本任务结合使用。唯一需要留意的是它面向网页 DOM 的脆弱性——建议在 Gemini 页面改版后通过opencli gemini status与opencli gemini models快速探测适配器是否仍然可用。【免费下载链接】OpenCLIMake Any Website into CLI Use your logged-in browser by AI agent.项目地址: https://gitcode.com/gh_mirrors/ope/OpenCLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考