企业官网建设流程全解析

做 AI 编码工具最头疼的一件事，就是赌模型。HagiCode 从最初只支持单一后端开始，被用户反复追问“能不能接入 GLM”“能不能走 Gemini CLI”之后，我终于意识到多模型不是加分项，而是生存项。这次改动把 GLM 全系模型正式接入，同时打通了 Gemini CLI 的执行链路，等于给工具装了一根真正的模型“万向节”。下面把整个设计思路、配置方法、踩过的坑一次性讲清楚。

先说结论：如果你想在自己的编码工具链里同时用上 GLM 的中文理解能力和 Gemini 系的长上下文 Agent 能力，HagiCode 这套“抽象层 + 适配器 + 路由策略”的组合是目前比较省心的做法。无论你是写工具、做内部平台，还是单纯想在终端里多个模型换着用，这篇文章都能帮你少走不少弯路。

1. 为什么 HagiCode 要搞多模型

1.1 单一模型后端的死穴

单一模型最大的问题不是能力不够，而是“不可替代性带来的脆弱”。你所有的工作流都压在一个模型供应商身上，一旦对方调整接口、限流策略变化、或者某个版本回归，整个工具链就跟着停摆。我在生产环境遇到过不止一次，凌晨一个模型版本更新导致代码补全风格突变，第二天一堆用户来问“是不是幻觉变严重了”。

另一个问题是成本博弈。不同模型在不同任务上的性价比差异巨大：简单函数补全都是火力覆盖，复杂架构设计时小模型又撑不住。单一后端意味着你永远没有选择权，只能按最高标准买单，或者在能力上限上妥协。这就促成了多模型架构的第一个核心原则——把“模型”从工具代码里彻底剥离出去，让它变成一个可配置的运行时资源。

1.2 GLM 带进来的增量价值

接入 GLM 不是因为“多一个模型多一个噱头”，而是它在几个维度上是真实互补的。首先是中文场景的理解颗粒度，GLM 序列在中文技术文档、注释、需求描述上的表现一直比较稳，尤其对项目里充满中文注释的代码库，上下文理解和代码续写的连贯感明显更自然。其次是成本结构，GLM-4-Flash 这类入门型号自带免费额度，适合做预扫描、批量注解、标题生成这类不算特别“重”的任务，把高成本模型的使用量省下来。

再一个就是 API 兼容性。GLM 官方接口基本沿用了 OpenAI 兼容协议，base_url 一换，请求体几乎不用改。这个特性让它在多模型架构里属于“接入成本最低的一类”，正好适合作为验证抽象层设计的第一个外部 provider。等到 GLM 链路跑顺了，后面再接任何 OpenAI 兼容服务都只是加一段配置的事。

1.3 Gemini CLI 引入的意义

Gemini CLI 的集成思路跟直接调 API 完全是两回事。Gemini CLI 本身就是一个完整的终端 Agent，它自带上下文管理、工具调用、多轮执行能力，甚至能读文件、执行命令、管理会话。HagiCode 如果只是把它当一个模型 API 来调，就浪费了它最大的价值。

所以在设计上，HagiCode 把 Gemini CLI 当成一个外部执行器来处理。这有点像在项目里接入一个“专家系统”，你把任务提交给它，它自己规划步骤、调用工具、返回结果。这样做的好处是：复杂任务可以完全交给 Gemini CLI 的 Agent 循环去跑，HagiCode 只负责分发任务、汇总结果，既保留了 CLI 的独立进化能力，又不用把所有 Agent 逻辑都维护在自己的代码里。

2. 整体架构设计：模型抽象层怎么搭才不翻车

2.1 分层解耦：接口稳定是底线

多模型架构最容易翻车的地方，就是各模型的请求格式、返回格式、错误结构都不一样。如果业务代码里到处是if provider == "openai"这样的分支，后面每加一个模型都要改一堆代码，这种架构活不过三个 provider。

我采用的方式是三层结构：配置层 → 适配器层 → 服务层。配置层管“哪个模型可用、用什么 key、超时多少”；适配器层管“把统一的内部请求转换成各家的 API 格式”；服务层就是 HagiCode 的业务逻辑，只跟内部统一的请求/响应对象打交道，完全不感知后端是哪家。

内部统一接口我起名叫ChatRequest和ChatResponse，字段做了最小化裁剪：模型名、消息列表、温度、最大 token、工具定义。返回结构统一成content + tool_calls + usage + raw四个字段，其中raw保留原始响应，方便排查问题。这样不管接进来的是 GLM、Gemini 还是任何 OpenAI 兼容服务，对上层来说长得都一样。

2.2 适配器模式：新模型接入有多快

适配器层是这套设计里最值得抄作业的部分。每个 provider 一个适配器，实现同一个接口：

class ProviderAdapter(ABC): name: str def chat(self, req: ChatRequest) -> ChatResponse: ... def stream(self, req: ChatRequest) -> Iterator[ChatResponse]: ... def count_tokens(self, content: str) -> int: ...

GLM 的适配器是最好写的，因为它的接口几乎就是 OpenAI 协议的翻版，内部直接复用 OpenAI 客户端的参数拼装，只改 base_url 和鉴权头。Gemini CLI 的适配器则是走子进程调用，把请求序列化成命令行参数或 stdin 输入，再解析 CLI 的 stdout 输出。

我在代码里对所有适配器加了“健康检查”接口，启动时并行 ping 一遍各家模型，哪个不通就直接标记为不可用，路由层自动跳过它，避免请求发出去等半天才超时。

2.3 路由与故障转移：别把鸡蛋放一个篮子里

有了抽象层之后，最爽的就是可以随便做策略了。HagiCode 现在的路由规则是：

• 按任务类型路由：代码生成类默认走 GLM（性价比高），复杂重构和跨文件修改走 Gemini CLI（Agent 能力强）。
• 按成本路由：普通问答和注释生成用免费型号，超过一定代码行数或涉及多文件操作才升级到付费大模型。
• 按可用性路由：某个 provider 连续失败超过阈值，自动把流量切到备用模型，同时在日志里打出切换原因。

这个路由策略我一开始想得很复杂，后来发现真正落地时先把“默认模型 + 手动切换 + 失败回退”跑稳，就已经覆盖了 90% 的使用场景。复杂策略可以后续迭代，第一版别被算法绑架。

3. GLM 接入实操：从拿 Key 到跑通第一条请求

3.1 获取 API Key 与模型确认

在 HagiCode 里配置 GLM 之前，第一步是去智谱开放平台完成实名认证并创建 API Key。这个 Key 是一段以id.secret格式拼接的字符串，你只需要把它保存下来，后面全部通过环境变量注入，不要硬编码进配置文件。

模型名的选择有个小坑：官方文档里的模型标识和实际可调用的 ID 有时不完全一样，尤其是带版本后缀的型号。建议先在平台控制台确认你账户下实际可用的模型列表，再填进配置。以我这边的实测为例，glm-4-flash和带视觉能力的glm-4v-flash都是可以直接跑的，具体的版本演进很快，最好的办法是动态拉取模型列表，而不是写死。

3.2 配置 provider 与测试连通性

HagiCode 的配置文件是~/.hagicode/config.yaml，GLM 这段配置如下：

providers: - name: zhipu type: openai_compatible base_url: "https://open.bigmodel.cn/api/paas/v4" api_key_env: ZHIPU_API_KEY models: - name: glm-4-flash api_model: glm-4-flash role: cheap - name: glm-4.5-air api_model: glm-4.5-air role: default

注意api_key_env字段指向环境变量名而不是 Key 本身。然后执行：

export ZHIPU_API_KEY="你的key" hagicode provider verify zhipu

有输出说明连通性没问题。如果提示证书错误或连接失败，先检查是否触发了网络代理，大多数情况是请求被网关挡了，换直连或检查根证书即可解决。第一次调用时建议把temperature设成 0.2，先跑一段代码补全验证输出稳定性，再回到正常参数。

3.3 把 GLM 设为默认模型

验证通过后，在 HagiCode 里切默认模型：

hagicode model use zhipu/glm-4.5-air

切换之后所有不带显式模型参数的请求都会走这个模型。我建议把glm-4-flash这种免费模型放在role: cheap分组，然后在~/.hagicode/rules.yaml里配一条规则：当任务类型是comment或rename时，自动降级到 cheap 模型分组。这样大多数轻量操作根本不消耗付费额度，日积月累省下的 token 数量相当可观。

4. Gemini CLI 集成：让 Agent 干真正的活

4.1 安装 Gemini CLI 并与 HagiCode 配对

Gemini CLI 是 Google 开源的终端 Agent 工具，安装方式很简单，直接通过 npm 全局安装或者用官方推荐的方式，确保终端里能执行gemini命令即可。安装后先手动跑一次gemini完成登录或者配置 API Key，因为 HagiCode 本身不管理 Gemini 的凭据，它只是调用你本地已有的 CLI。

然后回到 HagiCode 配置：

clis: gemini: command: gemini args: ["--no-color"] timeout_seconds: 300

这里的--no-color参数很关键。Gemini CLI 默认会把输出染色，如果你不关掉颜色，HagiCode 解析 stdout 时会被 ANSI 转义序列干扰，轻则格式错乱，重则任务判定失败。我第一次集成时没加这个参数，解析出来的结果里全是\x1b[32m这种前缀，排查了半天才发现是颜色问题。

4.2 子进程调用与流式输出解析

HagiCode 通过子进程调用方式跟 Gemini CLI 交互。核心逻辑分三步：拼接参数、带超时执行、解析输出。具体来说：

import subprocess def run_gemini_cli(prompt: str, timeout: int = 300) -> str: proc = subprocess.Popen( ["gemini", "--no-color", "-p", prompt], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, encoding="utf-8", ) try: out, err = proc.communicate(timeout=timeout) except subprocess.TimeoutExpired: proc.kill() raise TimeoutError("Gemini CLI execution timed out") if proc.returncode != 0: raise RuntimeError(f"Gemini CLI error: {err.strip()}") return out.strip()

这里有一个很重要的问题：Gemini CLI 执行复杂任务时，输出可能既包含最终内容，也包含工具调用的日志。我的经验是让 CLI 用-p（print mode）只输出最终回复，尽量让 Agent 在内部完成思考，对外只暴露结论。如果需要中间过程，再用 verbose 模式配合正则抓取关键节点，否则输出解析会非常痛苦。

我给 Gemini CLI 的适配器还加了一层“任务超时熔断”。因为 CLI 跑大任务时动辄几分钟，一旦卡住会占住 HagiCode 的并发线程，所以超过 300 秒直接强杀，并返回一个结构化错误给上层。宁可任务失败，也不能让它拖垮整个进程。

4.3 双模型混合工作流

把 GLM 和 Gemini CLI 同时接入之后，最有价值的其实是组合使用。比如我常用的一个流程：先用 GLM 对仓库做全量代码扫描，产出无用代码、潜在 bug、待优化点清单；再把这个清单作为提示词喂给 Gemini CLI，让它针对每个问题生成具体的重构方案。

这套流程跑得非常顺，原因在于两个模型各取所长。GLM 的中文理解让它在解读代码注释、理解业务意图时很少跑偏，而且便宜，适合大范围扫描；Gemini CLI 的 Agent 能力让它在定位问题、设计重构方案、执行修改时更接近一个完整的工程师，而不是单纯的语言模型。以前这些问题全部堆在一个模型上，做扫描怕贵、做重构怕弱，现在各干各的，互不干扰。

5. 接入过程中踩过的坑与排查速查表

5.1 六个高频问题实录

多模型接入最怕的不是功能做不出来，而是线上跑着跑着出一些莫名其妙的问题。这几个月下来，我遇到的高频问题主要集中在六个方面。

GLM API 返回 401。这个绝大多数是 Key 配置问题。注意智谱平台的 Key 是id.secret两段式，复制的时候很容易把点号后面的部分漏掉。我用环境变量注入之后好多了，但调试时还是会在.env文件里误加引号导致值变成字面量，建议打印前几位和后几位做核对。

Gemini CLI 输出乱码。就是前面说的 ANSI 颜色问题。除了加--no-color外，还要注意子进程的encoding参数，在 Windows 上务必要指定utf-8，否则中文注释全变问号。

GLM 免费模型限流触发 429。GLM-4-Flash 免费额度对并发限制比较严格，批量任务稍微一多就被限流。解决方式是在适配器里加一个令牌桶，默认每秒 1 个请求、突发 3 个，实测能把限流概率降一个数量级。如果你跑的任务很大，直接换付费模型更省心。

上下文长度超限。这类问题最容易出现在连续对话场景。HagiCode 之前只对写入端做了 token 统计，忽略了返回内容也在增长，结果几轮对话之后突然截断。后来在适配器里统一用count_tokens做输入裁剪，超长时自动摘除最早的中间轮次消息，问题就控制住了。

Gemini CLI 执行超时但进程没退出。遇到过几次任务卡死，subprocess.TimeoutExpired触发后 kill 掉了主进程，但子进程的孙进程还挂着，占着终端输出句柄。现在的做法是启动时加preexec_fn=os.setsid，超时后 kill 整个进程组，彻底清干净。

不同模型对同一请求的响应格式不一致。这一点在接 Gemini CLI 时尤其明显，它的返回天然带了思考痕迹和结构化标签，而 GLM 的返回更接近纯文本。解决方式是在ChatResponse里增加extra字段，把模型特有的信息放进去，上层需要时再取，不需要时忽略，绝不让一个模型的私有格式污染统一结构。

5.2 排查技巧与日志调优方法

排查多模型问题，日志一定要结构化。HagiCode 现在每个请求都有唯一的request_id，日志里记录 provider、model、prompt 截断、耗时、token 用量、错误码六个字段。排查问题时就一句话：按request_id过滤所有日志。

另外我强烈建议开启请求/响应落盘功能，用来做问题复现。响应原始内容以 JSONL 格式存到~/.hagicode/logs/，一次会话一个文件，实际排障效率特别高。遇到模型行为不符合预期时，直接把原始输入输出贴回官方 Playground 验证，很快就能区分是模型问题还是 HagiCode 传参问题。

调优方面，每个 provider 的超时和重试次数应该独立设置，GLM 的默认超时 60 秒基本够，Gemini CLI 大任务要放到 300 秒以上。重试策略统一走指数退避：0.5s → 1s → 2s → 4s，最多 4 次，避免限流恢复后一窝蜂冲上去把网关再次打挂。实测这套策略下，偶发的 429 和 5xx 对用户体验的影响可以压到很低。

5.3 一个容易忽略的配置细节

配置 provider 的模型列表时，models字段里的name是 HagiCode 内部的逻辑名，api_model才是真正发给服务商的 ID。这两个一定要区分清楚。有人图省事把内部名直接写成模型 ID，结果后面换模型版本时，API 侧的模型 ID 变了，内部引用全部要跟着改，非常被动。命名时我习惯把逻辑名做成不带版本号的语义名，比如glm-main，具体 ID 映射到配置里，切换时只动配置不动代码。

这个细节看起来小，后期维护成本差别却很大。多模型架构里，配置就是产品的一部分，把配置设计得可读、可改、可扩展，比写一堆灵活的代码更实际。

6. 性能对比与选型建议

6.1 实测体验：GLM、Gemini CLI 与主流模型横向感受

我不是做跑分的人，更关注真实任务上的体感。以下数据都来自 HagiCode 在实际仓库上的运行结果，不严谨，仅供参考。

单就 HagiCode 的典型使用场景来看，GLM 更适合作为默认主力模型，覆盖面广、延迟低、成本可控。Gemini CLI 更适合按需介入的高复杂度任务，你把它当“外聘专家”而不是“常驻员工”，每轮任务按次付费，整体性价比最高。

6.2 模型选型的三条判断标准

模型选型我总结了三句话。第一句，看任务类型匹配度，不要拿代码生成模型的性能去衡量注释模型的性价比。第二句，看失败成本，如果任务失败影响的是最终交付，就要选你更熟悉、排障经验更多的模型，而不是选排行榜最高的。第三句，看生态集成难度，Gemini CLI 这种自带工具链的 Agent，跟你自研代码的融合成本，远高于一个纯 API 模型，选型时务必把这个算进去。

还有一个容易被忽略的点，是模型更新频率。有的模型一个月发好几个版本，版本间行为差异大，如果产品对稳定性要求高，建议锁定版本号，由人工审核后再升级。HagiCode 现在的做法是把模型分组设成stable和beta，日常流量全走stable，新版本先在beta分组观察几天再说。

7. 后续规划：从多模型到多 Agent 协作

GLM 和 Gemini CLI 的上线只是第一步。既然抽象层已经稳定，后续方向很明确：把“多模型”升级成“多 Agent 协作”。具体想法是让不同模型担任不同的角色，比如 GLM 当上下文分析器负责理解项目背景，Gemini CLI 当执行者负责做实际改动，再加一个小模型当代码评审员，最后把所有结果汇总给开发者做最终决策。

这个方向做起来之后，HagiCode 的角色就不再只是一个编码助手，而更像一个“AI 开发小队的管理者”。规划上我准备优先做两块：一是 Agent 之间的消息协议标准化，让不同模型之间的输出可以直接作为对方的输入；二是任务编排引擎，支持 DAG 形式定义多步骤任务，每个节点指定一个模型执行。等到这两块落地，多模型架构才算是真正闭环了。

我在实际整理这套方案时最大的感受是：不要迷信单一模型的上限，要把模型当作可替换的组件，用架构去对冲模型进化带来的不确定性。今天接入的 GLM、Gemini CLI 是起点，但抽象层一旦稳定，未来任何新模型出现，对 HagiCode 来说都只是加一段配置文件的事。这也正是我坚持做多模型支持的原因——不是追逐热点，而是给工具留足进化空间。