在 AI Agent 越来越常见的当下，开发者真正关心的问题正在变化：模型为什么能“看图”、为什么能执行终端命令，又是如何调用外部工具？Google 官方开源的终端 AI 编程助手 gemini-cli 提供了一份可拆解的样本。素材显示，源码版本基于 google-gemini/gemini-cli main 分支（@google/gemini-cli v0.69.0-nightly,2026-11 快照），Apache-2.0 开源，项目有 ~10 万颗星。从源码看，gemini-cli 的核心并不是让模型直接操作电脑，而是把模型、工具和循环组合成一套文本驱动的系统。
模型不直接“动手”，只输出结构化文本
素材中反复强调，模型每一轮看到的并不是用户终端、文件系统或屏幕，而是一份结构化的 JSON 请求。请求里有用户消息、模型此前发出的工具调用，以及工具返回结果。工具也不是凭空出现：GeminiClient 会在每轮请求前，从工具注册表中取出可用工具，并整理成 functionDeclarations 发给模型。
在工具定义中，每个工具通常包含几个关键信息：
- name：模型在 API 中调用的工具名，例如 read_file；
- description：向模型说明工具用途；
- schema：参数说明，通常为 JSON Schema；
- build/execute：由本地程序构造并执行实际调用。
这意味着，模型与真实世界的接口仍然是一张“文本点菜单”。它不会直接执行代码，真正执行发生在 gemini-cli 这一外围程序里。响应返回后，Turn 类会把内容拆成思考、正文和 functionCall 等事件。即使模型调用了一个本地不存在的工具，系统也会生成错误信息回喂给模型，让其在下一轮自行修正。
“看图”的本质，是把图片编码成 base64
当用户要求 gemini-cli 查看一张图片时，程序并不是让模型直接访问屏幕，而是先把图片读入请求。素材给出两条路径：一条是用户使用 @ 文件引用，atCommandProcessor 会解析输入并调用 read_many_files 读取文件；另一条是模型根据任务主动调用 read_file。
对于图片、PDF、视频等文件，fileUtils 会读取文件内容，并将其转为 base64 字符串，再作为 inlineData 放入请求中。也就是说，从 gemini-cli 的工程视角看，“看图”并不是模型获得了某种神秘视觉入口，而是图片被编码为文本化数据块，交给支持多模态的 Gemini 模型处理。
工具结果返回时，系统还会区分文本和图片。convertToFunctionResponse 会把 text 和 inlineData 分拣处理：如果模型支持多模态函数响应，图片可以嵌入 functionResponse.parts；如果不支持，则作为独立内容块跟在函数响应后面。若工具只返回图片而没有文字，系统还会补上 “Binary content provided (1 item(s)).”，保证响应结构合法。
执行 shell 命令，要经过确认和注入检查
相比读取文件，执行 shell 命令更接近系统权限，因此源码中的安全流程更受关注。当模型发出 run_shell_command 请求时，系统不会立即运行，而是先进入确认逻辑。ShellToolInvocation.shouldConfirmExecute 会根据配置判断是否需要询问用户：如果涉及高危文件或构建文件风险，会要求确认；在 YOLO 全自动模式下可放行；默认情况下，终端会提示用户确认是否执行。
素材还提到，系统会检测命令参数中的命令替换语法，例如 $()、反引号等。一旦识别为命令注入风险，执行会被拦截，相关错误信息也会作为 llmContent 返回给模型。这样模型不仅知道请求失败，也能在后续尝试其他写法。
这部分体现了一个重要边界：模型拥有提出动作建议的能力，但真正执行仍由本地程序和用户审批控制。Agent 的安全性并不只依赖模型自身，而是依赖外围系统对工具调用、参数校验和人工确认的设计。
对行业的意义：能力来自模型之外的工程
从 gemini-cli 源码看，大模型“看图、跑命令、调工具”的能力，并不是单一模型功能的直接延伸，而是一整套工程系统协作的结果。工具声明让模型知道可以做什么，base64 和多模态数据结构让图片进入模型上下文，函数响应让执行结果回到对话流，确认和注入检查则限制危险操作。
素材未单独展开 MCP 的实现细节，但工具注册、函数声明、调用调度和响应回喂，已经勾勒出外部工具接入的共同路径。对于开发者而言，这类源码分析的价值在于看清 Agent 的边界：模型负责生成判断和调用意图，外围程序负责翻译、执行与安全控制。理解这一点，比单纯关注模型参数更能解释 AI 编程助手为何能在真实环境中完成任务。
原创文章，作者：点点，如若转载，请注明出处：https://www.dian8dian.com/du-dong-geminicli-yuan-ma-da-mo-xing-kan-tu-pao-ming-ling
