Gemini CLI 联网实战：google_web_search 与 web_fetch 工具的原理与用法

本文围绕 Gemini CLI（gemini-cli）的 Web 工具教程展开，覆盖两个核心工具——google_web_search（联网搜索）与 web_fetch（抓取指定 URL 内容）——的典型使用场景、完整参数说明与安全机制，并结合开源仓库中的工具实现源码（web-search.ts、web-fetch.ts）拆解引用标注、限速、私有网络拦截与本地回退抓取等底层原理。读完后，你将能够在终端中让 Agent 检索最新文档、读取指定网页并据此生成或修改代码。

前置条件

• 已安装并完成认证的 Gemini CLI；
• 可用的互联网连接。

两个核心工具概览

工具	适用场景	核心参数
google_web_search	需要检索模型训练数据之外的最新信息、新闻、文档	query（string，必填）：要执行的搜索查询
web_fetch	将提示词中给出的具体 URL（最多 20 个）直接喂入上下文进行处理	prompt（string，必填）：包含不超过 20 个 http:// 或 https:// URL 及处理指令

两个工具的参数定义可见工具声明文件 default-legacy.ts，并通过 coreTools.ts 中的 WEB_SEARCH_DEFINITION / WEB_FETCH_DEFINITION 暴露给 Agent 循环。

场景一：研究新技术（google_web_search）

典型 Prompt

设想你要使用一个昨天才发布的库，模型并不知道它，需要"教"给它：

Search for the 'Bun 1.0' release notes and summarize the key changes.

Find the documentation for the 'React Router v7' loader API.

Gemini 会调用 google_web_search 工具查找相关页面并综合成答案。这个"grounding（接地）"过程确保 Agent 不会幻觉出不存在的特性。

源码级原理：搜索如何变成带引用的答案

工具实现位于 web-search.ts，其执行链路为：

1. 发起搜索：WebSearchToolInvocation.execute 将查询以 model: 'web-search' 的名义调用 geminiClient.generateContent（web-search.ts），即搜索由 Gemini API 侧的 Google Search 能力完成，而不是 CLI 本地发起 HTTP 请求。
2. 解析接地元数据：响应中的 groundingMetadata 携带两类数据（web-search.ts）：
   • groundingChunks：每个来源的 uri 与 title，最终在回答末尾拼成 Sources: 列表，格式为 [1] 标题 (URI)；
   • groundingSupports：指出回答中哪些字节区间对应哪个来源，工具据此在正文的精确位置插入 [1]、[2] 等引用标记。
3. 精确插入引用标记：由于 API 返回的 segment 索引是 UTF-8 字节位置，实现中专门使用 TextEncoder/TextDecoder 把响应编码为字节流，按降序插入标记后再解码，避免偏移错位（web-search.ts）。
4. 空结果与错误处理：无结果时返回 No information found.；抛出异常时返回 ToolErrorType.WEB_SEARCH_FAILED 类型的错误结果（web-search.ts）。

场景二：抓取深度上下文（web_fetch）

搜索只能给你摘要，但有时你需要原始细节。web_fetch 工具允许把一个具体 URL 直接喂进 Agent 的上下文。

阅读博客文章

假设你找到一篇恰好解决你 bug 的博客：

Read https://example.com/fixing-memory-leaks and explain how to apply it to my code.

Gemini 会获取页面内容（剔除广告与导航等干扰信息）并基于它回答你的问题。

对比多个来源

也可以一次抓取多个页面来对比方案：

Compare the pagination patterns in https://api.example.com/v1/docs and https://api.example.com/v2/docs.

参数与确认机制

• 工具参数为单个 prompt 字符串，内含最多 20 个 URL 与处理指令（例如"总结 A 页面并抽取 B 页面的关键数据"）。URL 必须是完整、以 http:// 或 https:// 开头的形式，example.com 这种不带协议的写法不合法。
• 每次调用都会触发一个确认对话框，展示解析出的 URL 列表，等待用户批准后才执行（getConfirmationDetails，web-fetch.ts）。
• 在 Plan Mode 下，web_fetch 可用但因涉及访问外部/私有网络地址，始终需要显式用户确认（见 web-fetch.md 与 plan-mode.md）。

源码级原理：一条稳健的抓取管线

实现位于 web-fetch.ts，值得了解的机制包括：

• URL 解析与协议白名单：parsePrompt 按空白分词，用 WHATWG new URL() 校验，只接受 http:/https: 协议，畸形 URL 会直接报参数错误（web-fetch.ts）。
• URL 规范化：normalizeUrl 将主机名转小写、去掉尾部斜杠与默认端口，用于去重（web-fetch.ts）。
• 主机级限速：同一主机名每 60 秒最多 10 次请求（MAX_REQUESTS_PER_WINDOW = 10），超限的 URL 会被跳过并在结果中警告（web-fetch.ts）。
• 私有网络与本地地址拦截：isBlockedHost 拦截 localhost、127.0.0.1 及私有 IP，防止工具被用于探测内网（SSRF 防护），被跳过的 URL 会记录 private_ip_skipped 遥测事件（web-fetch.ts）。
• GitHub 链接优化：convertGithubUrlToRaw 自动把 github.com/.../blob/... 转换为 raw.githubusercontent.com 的原始文件地址，拿到的是纯文本而非 HTML 外壳（web-fetch.ts）。
• 主通道 + 本地回退：主路径通过 Gemini API 的 URL 上下文能力抓取；若主通道失败，工具会回退到从本地机器直接 fetch（超时 10 秒，URL_FETCH_TIMEOUT_MS），HTML 用 html-to-text 转纯文本，单页内容截断到 MAX_CONTENT_LENGTH = 250000 字符（web-fetch.ts）。
• 多 URL 预算分配：回退抓取多个页面时，采用"水填充"式公平算法在总字符预算内为各页面分配配额，短内容页优先拿满，避免单个超长页面挤掉其他来源（web-fetch.ts）。
• 反提示注入包装：所有抓取到的网页内容在回填给模型前会经过 wrapUntrusted 包装，明确其为不可信外部内容（web-fetch.ts）。
• 实验性直接抓取模式：当配置开启 directWebFetch 时，工具参数切换为单个 url，CLI 直接抓取（上限 10MB），支持文本、JSON、HTML，甚至把图片/视频/PDF 以 base64 inlineData 形式交给模型（web-fetch.ts、web-fetch.ts）。

场景三：把网页知识落到代码

真正的威力来自 Web 工具与文件编辑工具的联动。典型工作流三步走：

1. 搜索："How do I implement auth with Supabase?"
2. 抓取："Read this guide: https://supabase.com/docs/guides/auth."
3. 实现："Great. Now use that pattern to create an auth.ts file in my project."

前两步分别触发 google_web_search 与 web_fetch 把最新资料注入上下文，第三步由文件编辑工具落地。生成代码的本地写入可参考 File management 教程。

场景四：排查报错

遇到费解的报错信息时，直接把错误粘进对话：

I'm getting 'Error: hydration mismatch' in Next.js. Search for recent solutions.

Agent 会搜索 GitHub issues、StackOverflow、论坛等来源，找出可能因太新而不在其训练集中的修复方案。

参考资料

• Web search 工具参考（google_web_search）：参数、grounding 与引用行为说明；
• Web fetch 工具参考（web_fetch）：urlContext 处理机制、Plan Mode 行为与回退策略说明；
• File management 教程：将检索生成的代码写入项目；
• 实现源码：web-search.ts、web-fetch.ts，对应测试 web-search.test.ts 与 web-fetch.test.ts，以及集成测试 google_web_search.test.ts。