我花了一个周末把一个社区活跃的 Gemini-Cli 实现从头到尾读了一遍。这篇不聊模型参数也不聊提示词技巧只聊 Gemini-Cli 的源码架构从你敲下gemini chat开始到终端里一个字符一个字符滚出答案为止这条链路到底由哪些模块组成每个模块在干什么以及为什么这样设计。文章适合想把 CLI 工具做扎实的开发者也包括那些准备给 AI 应用套一层命令行外壳的人。1. 命令行客户端不是简单API封装项目定位与架构目标很多人以为 Gemini-Cli 就是拿官方 SDK 包一层fmt.Println实际上源码读下来最大的发现是这个项目的价值几乎全部集中在 CLI 工程性上而不是模型调用本身。模型调用只是其中一小块。这也是为什么架构上把它当“终端应用”来做而不是当“脚本”来做。1.1 为什么需要独立的CLI外壳直接写一个调用 Gemini API 的脚本和做一个可维护的 CLI 客户端差距非常大。脚本只需要十几行但一旦要支持多轮对话、会话保存、流式输出、中断恢复、管道输入、配置切换复杂度就会指数上升。CLI 外壳需要解决的核心问题包括命令行的生命周期管理进程启动、参数解析、信号捕获、退出码。标准输入输出交互终端模式和管道模式的行为完全不同。会话状态的持久化用户关闭终端后再打开历史对话得还在。动态配置系统密钥、模型、温度、上下文字数都要能随时切换。流式数据的实时渲染边读边写而不是等全部结果回来再一次性输出。所以源码架构必须围绕这些工程问题来设计而不是围绕 API 封装来设计。我读到的这个实现里入口层和 API 层之间还夹着 session、config、stream 三套并列的子系统这已经是比较清晰的思路了。1.2 源码目录结构从入口到功能模块的映射先看整体目录这对理解后面所有模块都很重要。一套典型的 Gemini-Cli 源码目录大概长这样gemini-cli/ ├── cmd/ │ ├── root.go │ ├── chat.go │ ├── models.go │ └── config.go ├── internal/ │ ├── api/ │ │ ├── client.go │ │ ├── request.go │ │ └── stream.go │ ├── session/ │ │ ├── manager.go │ │ ├── message.go │ │ └── store.go │ ├── config/ │ │ ├── loader.go │ │ └── defaults.go │ ├── stream/ │ │ ├── reader.go │ │ └── renderer.go │ └── ui/ │ ├── spinner.go │ └── markdown.go ├── pkg/ │ └── gemini/ │ ├── types.go │ └── client.go ├── main.go └── go.mod这个目录结构反映了一个重要的架构决策cmd只负责命令注册和参数绑定真正的业务逻辑全部下沉到internal包。pkg/gemini是唯一可以对外导出的包负责 Gemini API 的类型定义和底层封装。internal/api则负责发请求、处理响应、解析流。分这么细是为了让cmd里的命令处理器保持很薄方便测试和替换。实际读代码的时候你会发现cmd里几乎没有业务逻辑每个 Cobra 命令都是先初始化一个client然后调用session最后通过stream渲染结果。这一层“薄”得非常彻底。2. 入口层与命令分发一次“gemini chat”调用如何穿过main函数理解 Gemini-Cli 源码架构从入口开始是最顺的。一个 CLI 程序再复杂入口也只有一条路径拿到用户输入的命令行参数构建出可执行的命令树然后一路分发下去。2.1 命令注册与子命令识别我读的这个实现使用 Cobra 做命令框架入口代码非常典型。main.go只做一件事调用根命令的Execute()。package main import gemini-cli/cmd func main() { cmd.Execute() }cmd/root.go里定义rootCmd并挂子命令// cmd/root.go var rootCmd cobra.Command{ Use: gemini, Short: Gemini CLI interface, SilenceUsage: true, SilenceErrors: true, } func Execute() { if err : rootCmd.Execute(); err ! nil { // 让上层统一处理错误输出和退出码 fmt.Fprintln(os.Stderr, Error:, err) os.Exit(1) } } func init() { rootCmd.AddCommand(chatCmd) rootCmd.AddCommand(modelsCmd) rootCmd.AddCommand(configCmd) rootCmd.PersistentFlags().StringVarP(cfgFile, config, c, , config file path) }这里有两个值得注意的点SilenceUsage和SilenceErrors设置为true表示命令执行出错时不打印完整 usage避免在对话流式输出到一半时刷屏。PersistentFlags把--config挂在根命令上子命令自动继承。这种设计保证了任何子命令执行前都能先拿到自定义配置文件路径。2.2 参数解析与运行时依赖注入chatCmd的RunE函数是核心。这里做的事情很多解析用户的--model、--temperature、--session参数初始化配置对象再创建 API client 和 session manager。我把它简化一下来看// cmd/chat.go var chatCmd cobra.Command{ Use: chat [message], Short: Start an interactive chat session, RunE: func(cmd *cobra.Command, args []string) error { cfg, err : config.Load(cfgFile) if err ! nil { return err } // 命令行参数覆盖配置文件 if model ! { cfg.Model model } if temperature ! 0 { cfg.Temperature temperature } client : api.NewClient(cfg) mgr : session.NewManager(cfg, client) if len(args) 0 { return mgr.RunOnce(args[0]) } return mgr.RunInteractive() }, }这里的架构关键点在于RunE本身不理解会话逻辑只负责“组装零件”。session.NewManager(cfg, client)传入的是接口而不是具体实现这让后续替换 API 客户端或者 mock 测试变得特别容易。3. 会话状态机多轮对话的上下文是怎么被组织的聊完了入口进入目录里最核心的模块internal/session。Gemini-Cli 跟普通的 HTTP 请求工具最大的区别是它必须维护多轮对话状态。一个 Chat Session 从用户输入开始到模型响应结束再进入下一轮整个过程本质上是一个状态机。3.1 消息模型与session对象源码里定义的消息结构并不复杂但是边界非常清晰// internal/session/message.go type Message struct { Role string json:role // user | model | function Parts []Part json:parts // 文本与函数调用块 Time time.Time json:time } type Session struct { ID string json:id Model string json:model CreatedAt time.Time json:created_at UpdatedAt time.Time json:updated_at History []Message json:history }这个Message结构对 Gemini API 的role和parts做了几乎一对一的映射但是额外加了Time字段方便后续做会话管理和过期清理。Session 对象持有的不是简单的字符串列表而是结构化的消息这直接决定了后续上下文截断策略能不能优雅实现。3.2 上下文窗口截断策略的实现一旦多轮对话变长就会撞上模型的上下文窗口限制。源码里没有粗暴地把历史全部清空而是实现了一个基于 token 估算的截断器逻辑可以概括为// internal/session/compactor.go func compactHistory(s *Session, maxTokens int) { var tokensPerMsg []int total : 0 for i, msg : range s.History { t : estimateTokens(msg) tokensPerMsg append(tokensPerMsg, t) total t } if total maxTokens { return } // 至少保留首条 system 消息 keepIdx : []int{0} current : tokensPerMsg[0] for i : len(s.History) - 1; i 0; i-- { if current tokensPerMsg[i] maxTokens { break } keepIdx append(keepIdx, i) current tokensPerMsg[i] } // 重建历史system 末尾最近消息 kept : []Message{s.History[0]} for i : len(keepIdx) - 1; i 1; i-- { kept append(kept, s.History[keepIdx[i]]) } s.History kept }这个实现选择“从尾部往前保留”因为它假设用户更关心最近的对话内容。首条消息一般是 system 指令或角色设定所以无条件保留。这是我读源码时最欣赏的地方之一没有硬编码“只保留最后10条”而是真正考虑了 token 预算。会话状态机的另一部分是 session manager 的状态流转空闲 → 等待用户输入 → 调用模型 → 渲染输出 → 回到空闲。manager 里还维护着一个互斥锁防止流式输出还没结束时用户就输入了下一条命令导致消息顺序错乱。4. 模型网关与流式传输SSE事件循环和渲染器的协同整个源码架构里我最想单独拆出来的是internal/api和internal/stream的协作方式。因为后面的 UI 渲染、中断恢复、错误提示全都要依赖流式传输这一层设计得是否干净。4.1 API Client的接口抽象源码给 API 客户端定义了一个非常小、非常好 mock 的接口// internal/api/client.go type Client interface { Send(ctx context.Context, req *gemini.GenerateContentRequest) (*gemini.GenerateContentResponse, error) Stream(ctx context.Context, req *gemini.GenerateContentRequest) (-chan gemini.StreamChunk, error) }注意这里把“一次性请求”和“流式请求”拆成了两个方法。流式请求返回的是一个-chan gemini.StreamChunk而不是简单的[]Response。这个 channel 是整条流水线的核心。进行流式请求时client 底层使用 HTTP 长连接通过 SSEServer-Sent Events接受服务端推送的 JSON。源码里会启动一个后台 goroutine 读取 http.Response.Body把每个 chunk 解析成StreamChunk然后推送到 channel 里。这个设计让上层渲染器完全不用关心 HTTP 细节。4.2 流式读取从SSE chunk到渲染回调internal/stream/reader.go负责消化 channel。它做的事情是把StreamChunk转换成下一层 UI 能理解的事件// internal/stream/reader.go type Event struct { Type EventType // TextDelta / ToolCall / Finish / Error Content string } func ReadEvents(ctx context.Context, ch -chan gemini.StreamChunk) -chan Event { out : make(chan Event) go func() { defer close(out) for { select { case -ctx.Done(): return case chunk, ok : -ch: if !ok { return } if chunk.Error ! nil { out - Event{Type: EventError, Content: chunk.Error.Error()} continue } for _, cand : range chunk.Candidates { for _, part : range cand.Content.Parts { if part.Text ! { out - Event{Type: EventTextDelta, Content: part.Text} } if part.FunctionCall ! nil { out - Event{Type: EventToolCall, Content: part.FunctionCall.String()} } } } if chunk.UsageMetadata ! nil chunk.UsageMetadata.TotalTokenCount 0 { out - Event{Type: EventUsage, Content: fmt.Sprintf(%d, chunk.UsageMetadata.TotalTokenCount)} } } } }() return out }这里把“数据读取”和“数据展示”彻底分离了。reader只负责把StreamChunk翻译成语义化Event至于文本是直接输出还是走 Markdown 渲染那是renderer的事。这样拆分最直接的好处是如果用户不需要 Markdown只需要--raw模式renderer 可以立刻切换成纯文本模式如果用户要 JSON 结构化输出reader 也可以把事件重新序列化。我在源码里看到的问题处理、中断退出、token 统计都被这些事件囊括进去了。5. 配置优先级与环境适配Key管理、模型切换与本地缓存Gemini-Cli 能适应不同使用场景关键不是代码写得多炫而是配置系统设计得足够灵活。源码里internal/config负责这一整套体系它的优先级规则非常清晰。5.1 配置文件的读取与合并顺序我读到的实现支持四层配置来源优先级从高到低如下优先级配置来源说明1命令行参数--model、--temperature直接覆盖一切2环境变量GEMINI_API_KEY、GEMINI_MODEL等3用户配置~/.config/gemini-cli/config.yaml4内置默认值默认模型、默认温度、默认超时时间这个设计思路非常“实用优先”。命令行参数只覆盖单次调用环境变量适合在 CI 或容器里用用户配置是日常使用的主战场内置默认值则保证从零开始也能跑通。config/loader.go里有一段关键代码负责将不同来源合并// internal/config/loader.go func Load(customPath string) (*Config, error) { cfg : Default() if err : mergeFile(cfg, findUserConfig(customPath)); err ! nil { return nil, err } if err : mergeEnv(cfg); err ! nil { return nil, err } return cfg, nil }mergeEnv会逐个读取GEMINI_前缀的环境变量并把它们写入配置结构。这个方法只处理字符串到字符串的映射真正的类型转换在applyEnvValue里用反射来做虽然有点绕但好处是不需要为每个字段写if分支。5.2 多会话缓存与历史记录存储会话缓存不在内存里存着就完事而是会落到磁盘。源码里默认的数据目录是~/.local/share/gemini-cli/sessions/每个 session 一个 JSON 文件。这么做的一个直接影响是用户中断进程、重启终端下一次打开还能恢复。持久化这里有一个细节不是每轮对话都立刻写入磁盘而是在流式输出结束后统一写一次。源码里用一个defer保证即使是中断信号也会在退出前做最后保存。这种延迟写入策略减少了磁盘 IO但代价是如果进程被kill -9强杀最后一次对话可能丢失。我看的这套实现是刻意接受的权衡。配置和缓存分离也是架构上的亮点。~/.config管密钥和偏好~/.local/share管数据这符合 XDG 规范。在多用户服务器上跑这个工具时不会出现配置目录权限打架的问题。6. 阅读源码时我注意到的三个边界坑与改进建议最后这部分不是源码的章节拆解而是我在实际读代码时觉得最值得展开的边界场景。坦白说一个 CLI 项目做得好不好往往就是看这些边角处理得怎么样。6.1 超时重试与限流处理Gemini API 在服务端负载较高时会返回 429 或 503。我在源码里看到了一套很朴素的指数退避逻辑最多重试 3 次每次等待时间翻倍并且把Retry-After响应头考虑进去。var backoff []time.Duration{500 * time.Millisecond, 1 * time.Second, 2 * time.Second} func (c *client) SendWithRetry(ctx context.Context, req *gemini.GenerateContentRequest) (*gemini.GenerateContentResponse, error) { var lastErr error for i : 0; i len(backoff); i { if i 0 { select { case -time.After(backoff[i-1]): case -ctx.Done(): return nil, ctx.Err() } } resp, err : c.rawSend(ctx, req) if err ! nil { if isRetryable(err) { lastErr err continue } return nil, err } return resp, nil } return nil, lastErr }这段代码有两个值得学习的地方一是ctx贯穿整个调用链用户按 CtrlC 时能立刻中断退避等待二是只对429和5xx做重试对4xx直接返回错误避免把认证错误也拿去重试浪费配额。6.2 TTY检测与管道模式源码里最有意思的地方是在RunInteractive和RunOnce之间做的一次环境检测如果stdin不是 TTY就直接进入管道模式。比如echo 你好 | gemini chat此时不会启动交互式提示符而是一次性处理输入然后退出。这个检测用到了golang.org/x/term包。实际代码大概是if term.IsTerminal(int(os.Stdin.Fd())) { mgr.RunInteractive() } else { data, _ : io.ReadAll(os.Stdin) mgr.RunOnce(string(data)) }这个处理非常符合 Unix 哲学同样一条命令在终端里是交互式聊天在脚本里就是非交互式数据处理工具。源码里还专门为管道模式加了--pipe参数强制走非交互路径方便在 shell 管道里使用。6.3 可复用中间件设计我看源码时还注意到一个细节所有输出渲染都经过ui模块而不是直接打印。ui暴露了一个RenderEvent接口任何事件都可以注册自己的渲染函数。我一开始觉得这有点过度设计但读到最后发现这个接口让日志、错误、模型输出、token 统计都能走同一套事件机制。如果你要在自己的项目里参考 Gemini-Cli我比较建议保持这种“事件流 渲染器”的架构即使没有多终端需求也值得。后续不管是接入 TUI 还是输出 JSON都不用改动核心逻辑。单独说几个我在阅读过程中踩过或想提醒的点不要在主流程里直接fmt.Println。所有输出都应该通过 stream 事件或 ui 层否则流式渲染时会出现顺序错乱。会话写盘要避免频繁全量序列化。对话很长时JSON 序列化会拖慢退出速度可以考虑按增量追加日志。API Key 的默认来源要兼容环境变量。很多用户会习惯用.env或系统密钥管理源码里留一个GEMINI_API_KEY的兜底非常有必要。考虑给每个 session 增加一个退出码状态。比如流式输出被用户中断时退出码应该跟正常结束不一样这样脚本才能感知到。Gemini-Cli 的源码架构不像大型分布式系统那样复杂但它把终端应用里最容易做烂的几个边缘场景都安排得明明白白。我读完之后最大的收获是真正决定一个 AI CLI 工具好不好用的往往不是模型调用写得多漂亮而是入口、会话、流式传输、配置这四层墙垒得够不够稳。后面如果你想把它接进自己的项目建议也从这四个模块入手不要一上来就写http.Post。