1. 从一次“读不到文件”的报错说起ReadFile 工具到底在做什么如果你正在读 Gemini cli 的源码大概率会先被它的工具层绕晕tools.ts里一堆抽象基类read-file.ts里又套了 Invocation、Schema、遥测三套逻辑光看 import 就劝退。我最初想搞清楚的问题特别朴素——当模型说“帮我读一下 config.json”这个请求到底是怎么从工具入口一路走到磁盘、再把内容塞回上下文的这就是本篇要拆的 Gemini cli 源码分析主线ReadFile 工具从入口到落盘的完整链路。它不是一个“调用 fs.readFile 就完事”的函数而是一条包含参数校验、路径解析、工作区边界检查、分页截断、遥测上报的流水线。搞懂这条链路你再看 WriteFile、SearchText 这些工具会发现它们几乎是同一套骨架换了个执行体。ReadFile 工具适合谁读三类人一是想给 Gemini cli 写自定义工具的开发者你需要知道基类要求你实现哪些钩子二是做 AI Agent 工具层设计的工程师ReadFile 是“只读工具”的典型样本安全边界怎么划、大文件怎么截断都在这里三是单纯想读懂 CLI 工具层源码的人这条链路足够典型读透一个等于读透一类。先给结论性的阅读地图入口在ReadFileTool的createInvocation执行在ReadFileToolInvocation.execute落盘读取委托给processSingleFileContent安全校验集中在validateToolParamValues遥测在logFileOperation。下面按这条顺序逐个拆每一步都给可复制的定位路径和关键函数清单最后演示一次本地运行验证读取行为。需要说明的是源码分析最怕“只看不跑”。我会在第三节给出可复制的配置片段让你把 Gemini cli 接到一个稳定的模型端点上这样你在读execute时能真实触发一次读取观察截断提示和遥测日志而不是对着代码空想。这也是我读源码的习惯先让它跑起来再顺着日志反推调用栈。2. 读源码前的前置准备把 Gemini cli 接到稳定端点并定位工具目录在动手翻read-file.ts之前建议先把运行环境搭好。原因很实际Gemini cli 的工具层大量依赖Config注入而Config里的模型端点、工作区目录、文件过滤选项都会影响 ReadFile 的行为。如果你只是静态读代码很容易忽略“路径解析依赖 getTargetDir”这种细节跑起来之后一次读取就能暴露这些依赖。前置准备分两步定位源码目录配置模型端点。第一步定位工具目录。Gemini cli 的工具实现通常集中在packages/core/src/tools/下ReadFile 对应read-file.ts基类在tools.ts文件处理在../utils/fileUtils.ts。你可以用下面的命令快速确认结构# 在 Gemini cli 仓库根目录执行 find . -name read-file.ts -not -path */node_modules/* find . -name tools.ts -not -path */node_modules/* find . -name fileUtils.ts -not -path */node_modules/*拿到路径后先别急着逐行读用grep把关键符号列出来建立索引# 列出 ReadFile 相关的关键符号 grep -n class ReadFileTool\|class ReadFileToolInvocation\|createInvocation\|validateToolParamValues\|processSingleFileContent \ packages/core/src/tools/read-file.ts这一步能帮你快速建立“入口—执行—校验—落盘”的符号地图后面读代码时不会迷路。第二步配置模型端点。Gemini cli 需要一个可用的模型服务来驱动工具调用。这里我用 TaoToken 作为接入端点它的 API 地址是https://taotoken.net/api兼容常见的对话与工具调用协议。你需要在环境变量或配置文件中填入 Base URL 和 API Key。以环境变量为例export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_API_KEY你的APIKey如果你用的是 Gemini cli 的 settings 配置可以写成 JSON 片段路径按你本地实际配置文件为准通常是项目根目录下的.gemini/settings.json{ model: { baseUrl: https://taotoken.net/api, apiKey: 你的APIKey, modelId: gemini-2.5-pro } }注意这里的三件套必须齐全Base URL、API Key、Model ID。少任何一个工具调用都会在初始化阶段失败而不是在 ReadFile 执行时报错——这点很容易误判后面排障章节会细说。配置完成后先跑一次最简单的对话确认端点通gemini --prompt 回复 ok如果返回正常说明模型端点没问题接下来读 ReadFile 源码时你就能真实触发一次文件读取。API Key 可以在 TaoToken 的 API Keys 页面创建接入细节参考官方文档即可。前置准备做到这里就够了。核心是源码目录定位清楚模型端点跑通这样你读execute时能对照真实行为而不是纯静态推理。3. 可复制配置与关键函数清单ReadFile 从入口到落盘的链路拆解这一节是全文的技术核心。我会按调用顺序把 ReadFile 工具从入口到落盘的链路拆成五段每段给出可复制的定位命令和关键函数清单。你可以边读边在本地对照。3.1 入口层ReadFileTool 与 createInvocationReadFile 工具的入口是ReadFileTool类它继承自BaseDeclarativeTool。这个基类定义了工具的通用行为框架名称、描述、参数 Schema、以及创建执行实例的工厂方法。关键函数是createInvocationprotected createInvocation( params: ReadFileToolParams, messageBus?: MessageBus, _toolName?: string, _toolDisplayName?: string, ): ToolInvocationReadFileToolParams, ToolResult { return new ReadFileToolInvocation( this.config, params, messageBus, _toolName, _toolDisplayName, ); }这里体现了两个设计点。第一工具定义与执行分离ReadFileTool只负责“声明这个工具长什么样”真正的读取逻辑在ReadFileToolInvocation里。第二依赖注入config从构造函数传入执行实例拿到的是同一个配置对象保证工作区目录、文件过滤选项一致。参数接口ReadFileToolParams很简洁只有三个字段export interface ReadFileToolParams { file_path: string; offset?: number; limit?: number; }file_path必填offset和limit可选用于分页读取大文件。这个设计的好处是职责单一工具只关心“读哪个文件的哪一段”不掺和别的逻辑。3.2 校验层validateToolParamValues 的多层检查在执行之前validateToolParamValues会做四层校验。这是 ReadFile 安全性的关键也是读源码时最容易被跳过、但最不该跳过的一段。第一层基础参数校验file_path去空格后不能为空。第二层工作区边界检查解析后的绝对路径必须落在工作区目录或项目临时目录内。第三层数值范围校验offset不能为负limit必须为正。第四层文件过滤检查如果路径命中 ignore 规则直接拒绝。工作区边界检查的代码大致是这样const isWithinTempDir resolvedPath.startsWith(resolvedProjectTempDir path.sep) || resolvedPath resolvedProjectTempDir; if ( !workspaceContext.isPathWithinWorkspace(resolvedPath) !isWithinTempDir ) { const directories workspaceContext.getDirectories(); return File path must be within one of the workspace directories: ${directories.join(, )} or within the project temp directory: ${projectTempDir}; }这段逻辑的价值在于防目录遍历。如果模型被诱导去读../../etc/passwdpath.resolve会把它解析成工作区外的绝对路径边界检查直接拦下。注意isWithinTempDir用的是startsWith(resolvedProjectTempDir path.sep)加path.sep是为了防止/tmp/project-evil这种前缀伪装。3.3 执行层ReadFileToolInvocation.execute 的路径解析与分页进入execute后第一件事是路径解析this.resolvedPath path.resolve( this.config.getTargetDir(), this.params.file_path, );getTargetDir()返回工作区根目录path.resolve把相对路径转成绝对路径。这一步决定了后续所有文件操作的实际目标。接着调用processSingleFileContent完成真正的落盘读取。这个函数在fileUtils.ts里负责判断文件类型、读取内容、处理截断。返回结果里如果isTruncated为真说明文件太大只读了一部分。这时execute会构造一段对模型友好的提示if (result.isTruncated) { const [start, end] result.linesShown!; const total result.originalLineCount!; const nextOffset this.params.offset ? this.params.offset end - start 1 : end; llmContent IMPORTANT: The file content has been truncated. Status: Showing lines ${start}-${end} of ${total} total lines. Action: To read more of the file, you can use the offset and limit parameters in a subsequent read_file call. For example, to read the next section of the file, use offset: ${nextOffset}. --- FILE CONTENT (truncated) --- ${result.llmContent}; }这段提示的设计很讲究它不只告诉模型“被截断了”还给出下一步的具体参数nextOffset。模型拿到这个提示下一轮就能自动续读不需要人干预。这是 ReadFile 分页机制能闭环的关键。3.4 落盘层processSingleFileContent 与 MIME 识别processSingleFileContent是真正碰磁盘的地方。它做三件事识别 MIME 类型、读取内容、按行截断。MIME 识别通过getSpecificMimeType完成用于区分文本、图片、二进制等不同处理策略。文本文件走行读取图片可能走 base64 编码二进制则直接拒绝或特殊处理。截断逻辑按行计算如果文件行数超过默认上限只返回前 N 行并记录linesShown和originalLineCount。这两个字段回传给execute用于构造上面那段续读提示。3.5 遥测层logFileOperation 的多维上报读取完成后execute会调用logFileOperation上报一次文件操作事件。上报字段包括工具名、操作类型READ、行数、MIME 类型、文件扩展名、编程语言。编程语言通过getProgrammingLanguage推断用于后续统计。const lines typeof result.llmContent string ? result.llmContent.split(\n).length : undefined; const mimetype getSpecificMimeType(this.resolvedPath); const programming_language getProgrammingLanguage({ file_path: this.resolvedPath, }); logFileOperation( this.config, new FileOperationEvent( READ_FILE_TOOL_NAME, FileOperation.READ, lines, mimetype, path.extname(this.resolvedPath), programming_language, ), );遥测层是只读的不影响读取结果但它对理解工具行为很有帮助你可以在日志里看到每次读取的行数、类型、语言反推模型到底读了什么。把五段串起来完整链路是createInvocation创建执行实例 →validateToolParamValues四层校验 →execute解析路径 →processSingleFileContent落盘读取 → 截断判断与续读提示 →logFileOperation上报。这条链路你可以在本地用一次读取验证下一节给具体操作。4. 本地运行验证一次 ReadFile 读取行为的完整观察读完链路必须跑一次才算真懂。这一节演示如何用 Gemini cli 触发一次 ReadFile并观察读取行为、截断提示和遥测日志。先准备一个测试文件故意造一个超过默认行数上限的大文件这样能同时验证正常读取和截断逻辑mkdir -p /tmp/gemini-readfile-demo cd /tmp/gemini-readfile-demo seq 1 500 big.txt echo {name:demo,version:1.0.0} config.jsonbig.txt有 500 行config.json是单行小文件。接下来在 Gemini cli 里发起读取请求。假设你已经按第二节配好了端点直接运行gemini --prompt 读取 config.json 的内容并告诉我 name 字段的值预期结果是模型返回demo。这一步验证的是小文件全量读取路径validateToolParamValues通过processSingleFileContent读取完整内容isTruncated为假直接返回。再读大文件gemini --prompt 读取 big.txt 的前 100 行这时模型会调用 ReadFile传入file_path: big.txt、limit: 100。观察返回内容你应该能看到前 100 行且没有截断提示因为limit显式指定了读取范围。最后测截断路径不传limitgemini --prompt 读取 big.txt 的全部内容如果文件超过默认上限返回内容里会出现IMPORTANT: The file content has been truncated.这段提示并给出nextOffset。你可以让模型继续读gemini --prompt 继续读取 big.txt 的下一段模型会根据上一轮的nextOffset自动传入offset续读下一段。这就是分页闭环的实际效果。如果你想直接观察遥测日志可以在启动时打开调试输出。不同版本的日志开关不同常见的是设置环境变量export DEBUGgemini:telemetry gemini --prompt 读取 config.json日志里会打印FileOperationEvent包含行数、MIME 类型、扩展名、编程语言。对照第三节的遥测代码你能看到每个字段的实际值。验证过程中有两个观察点值得留意。第一路径解析如果你传入../config.json而它落在工作区外会直接被validateToolParamValues拒绝报错信息里会列出允许的工作区目录。第二文件过滤如果工作区配了 ignore 规则命中规则的文件会被shouldIgnoreFile拦下报错提示“ignored by configured ignore patterns”。跑完这三组读取你对 ReadFile 链路的理解就从“读代码”变成“看行为”了。下一节整理常见报错都是我在实际接入和调试时踩过的。5. 常见报错排查401、local proxy failed 与 reading choices 的定位思路读源码和跑验证的过程中报错是常态。这一节按报错类型整理排查思路覆盖 401、local proxy failed、reading choices、OAuth 这几类高频问题。注意这些报错大多不在 ReadFile 本身而在它依赖的模型端点和配置层所以排查时要先分清“是工具层的问题还是接入层的问题”。第一类401 Unauthorized。典型表现是工具调用还没开始就失败日志里出现 401。原因通常是 API Key 缺失、过期或拼写错误。排查步骤先确认环境变量或 settings 里的apiKey是否填对再确认 Base URL 是否指向https://taotoken.net/api。如果用的是 settings JSON检查三件套是否齐全{ model: { baseUrl: https://taotoken.net/api, apiKey: 你的APIKey, modelId: gemini-2.5-pro } }Base URL、API Key、Model ID 缺一不可。很多人只填了 Key 忘了 Model ID结果报错信息看起来像鉴权失败实际是模型未指定。API Key 可以在 TaoToken 的 API Keys 页面重新生成接入文档里有完整的字段说明。第二类local proxy failed。这个报错通常出现在网络层提示本地代理连接失败。排查方向是检查你的运行环境是否有残留的代理配置比如HTTP_PROXY、HTTPS_PROXY环境变量指向了一个不可用的地址。清理这些变量后重试unset HTTP_PROXY HTTPS_PROXY ALL_PROXY如果你在容器或 CI 环境里跑检查容器的网络策略是否允许访问外部端点。这类问题的核心是“请求根本没发出去”和 ReadFile 的代码逻辑无关。第三类reading choices 相关报错。典型表现是解析模型响应时失败日志里出现reading choices或类似字段访问错误。原因是模型返回的响应结构不符合预期可能是端点返回了错误对象而非标准对话结构。排查步骤先用一个最简单的请求确认端点返回格式curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer 你的APIKey \ -H Content-Type: application/json \ -d {model:gemini-2.5-pro,messages:[{role:user,content:ok}]}如果返回结构里没有choices字段说明端点或模型 ID 不匹配。对照官方文档确认模型 ID 写法。第四类OAuth 相关报错。如果你用的是 OAuth 方式接入报错通常出现在 token 刷新阶段。排查方向是检查 token 是否过期、回调地址是否配置正确。这类问题建议直接看接入文档里的 OAuth 章节按步骤重新走一遍授权流程。排查的通用原则先分层再定位。接入层报错401、proxy、OAuth看配置和网络工具层报错路径越界、文件被忽略看validateToolParamValues的返回信息解析层报错reading choices看端点响应结构。分清楚层次排查效率会高很多。6. 把 ReadFile 当作工具层设计的样本后续阅读与接入建议ReadFile 这条链路读透之后你会发现 Gemini cli 的工具层有一套稳定的骨架声明式工具定义 执行实例 多层校验 遥测上报。WriteFile、SearchText、RunCommand 基本都是这个模式差别只在执行体和校验规则。所以后续读其他工具时可以套用同一张阅读地图先找createInvocation再找validateToolParamValues然后看execute的落盘逻辑最后看遥测字段。如果你想自己写一个自定义工具ReadFile 是最好的模板。继承BaseDeclarativeTool定义参数接口和 JSON Schema实现createInvocation返回你的执行实例在execute里完成实际逻辑别忘了在validateToolParamValues里做边界检查。安全边界这块ReadFile 的工作区校验和临时目录白名单值得直接借鉴。接入层面如果你要把 Gemini cli 接到自己的模型端点记住三件套Base URL、API Key、Model ID。Base URL 用https://taotoken.net/apiKey 在 API Keys 页面创建Model ID 按官方文档填。配置写进 settings JSON 或环境变量都行关键是三件套齐全。跑通之后你可以用第四节的验证方法真实触发一次 ReadFile观察截断和遥测行为。读源码这件事最怕停在“看懂了”的层面。我的建议是每读一个工具就跑一次对应的调用对照日志和返回内容验证你的理解。ReadFile 的截断提示、路径校验、遥测字段都是跑一次就能记住的细节。等你把 ReadFile、WriteFile、SearchText 都跑一遍Gemini cli 的工具层设计对你来说就不再是黑盒了。
