国产大模型聚合编程工具接入指南：OpenAI兼容、路由与避坑

过去一年，团队里最容易被忽略的一笔隐性成本，不是服务器，也不是 IDE 授权，而是"每个人手机和桌面上装着不同 AI 编程工具"这件事。有人用 Codex 风格的 CLI，有人用 Workbuddy 这类编辑器内助手，有人直接开网页版大模型对话。结果就是：同一个项目里，代码补全的风格不统一，review 标准不统一，连"该问哪个模型"都要靠个人经验，团队压根没有沉淀。

最近在开发者圈子里被反复讨论的一类方案，正好踩在这个点上：把 DeepSeek、GLM、豆包、通义千问这些国产一线模型聚合成一个入口，对外暴露统一的 API 和编程助手客户端，每天给一定量的免费积分，让个人开发者和小团队先用起来。标题里"内部人都在悄悄用"多半是营销话术，但它背后指向的问题是真问题——模型更新太快，订阅和 Key 越攒越多，切换成本开始高于模型本身的差异。

这篇文章不打算复述宣传语。我想把这类"国产大模型聚合编程工具"拆开讲清楚三件事：它的技术本质是什么（其实就是一套 OpenAI 兼容网关加一层路由），接入时哪些地方最容易踩坑（协议兼容性、模型名、上下文窗口、积分消耗规则），以及在真实项目里应该怎么用、不该怎么用。

读完你至少能拿到：一套可运行的多模型调用代码，一套从零接通编程助手的操作路径，一份常见报错对照表，以及一套把"免费额度"用成"稳定产能"的工程建议。至于要不要换掉手里的工具，看完第 8 节你会有自己的判断。

1. 这篇文章真正要解决的问题

1.1 三重成本，只有第一层是钱

大部分技术文章聊 AI 编程工具，只聊"哪个模型更强"。但在实际工程里，成本是分层的，而且越往下越难量化。

第一层是订阅成本。一个人同时开着两家以上的代码助手订阅，一个月几十到上百块很正常；团队十个人就是一笔固定支出，还没有发票流程。

第二层是切换成本。模型能力是波动的：某个月的版本在长上下文代码理解上更强，下个月另一个版本在单文件重构上更准。一旦你的工作流绑死在某个客户端里，换模型就意味着换工具、换快捷键、换配置，很多人干脆就不换了，继续用"次优解"。

第三层是认知成本，也是最贵的。团队里张三用 A 模型写单测，李四用 B 模型做 Code Review，两人对"什么算好代码"的隐性标准完全不同。等到出事回溯，你连"这段代码是哪个模型生成的、用了什么提示词"都查不出来。

聚合型工具真正有价值的地方，不是"免费额度"，而是它把前两层成本压平了：一套协议、一个 Key、一个计费口径，模型可以在后面换。至于第三层，工具本身解决不了，得靠工程规范，这个后面第 8 节会详细讲。

1.2 一个判断：协议统一比模型强弱更重要

如果你只记一句话，我希望是这句：在 2026 年选择 AI 编程工具，协议兼容性比单点模型能力更重要。

原因是，国产主流大模型服务商这几年基本都提供了 OpenAI 兼容的 /v1/chat/completions 接口。这意味着你只要写一套调用代码，改一下 base_url 和 model 字段，就能在 DeepSeek、GLM、通义千问、豆包之间来回切换。聚合平台做的事情，本质上是把这层适配再包一层，让你连 base_url 都不用记。

反过来，如果你的工作流依赖某个私有协议（某些厂商的专有 SDK、专有函数调用格式），那你就是在给自己上锁。模型一旦涨价、限流、下线某个版本，迁移成本会高得让你不想动。

1.3 谁最该读，谁可以先跳过

适合读下去的读者画像很清晰：

• 个人开发者或 3 到 10 人的小团队，想用较低成本把 AI 编程助手跑起来；
• 已经在用某一家模型，但想留一条"随时换模型"的后路；
• 需要在 CI 里跑自动化代码审查、单测生成，要求调用方式稳定；
• 对数据流向敏感，必须清楚代码片段会发到哪个服务商。

如果你所在的公司已经有完整的私有化模型部署和内网网关，那这类公网聚合平台对你的价值有限，你更需要的是第 8 节里关于路由和审计的部分。

2. 多模型聚合编程助手的核心概念与能力边界

2.1 它到底是什么：一层薄薄的网关

抛开包装，这类产品的架构可以用一句话概括：统一入口 + 协议适配 + 模型路由 + 额度计量。

用户侧看到的是一个 API Key 或者一个 IDE 插件，请求进来后，网关根据模型名或者路由规则，把请求翻译成对应厂商的格式转发出去，再把结果按统一格式吐回来，同时扣减额度、记录日志。就这么简单。

真正有技术含量的部分在于三件事：

一是协议兼容的完整度。只兼容 chat/completions 是基础，能不能兼容流式输出（SSE）、函数调用（tool calls）、结构化输出（JSON mode）、图片输入，决定了你能不能用它跑 Agent 类任务。

二是上下文窗口的处理。不同模型的上下文长度差异很大，网关要么做截断、要么做摘要、要么直接报错。这三种策略对使用体验的影响完全不同，接入前必须搞清楚。

三是故障转移。某个模型限流或者超时了，是直接失败，还是自动降级到备用模型？这决定了它在生产环境里能不能用。

理解了这层，你就不会把它当成"魔法"，而是当成一个需要做容量规划和降级设计的中间件。

2.2 编程助手的三种形态，别混为一谈

同样是"AI 编程助手"，形态差别很大，接入方式也完全不同：

聚合平台通常三种都提供，但很多人的误区是：以为"插件能用"就等于"API 能用"。实际上插件的提示词是平台调好的，API 则要你自己写系统提示词，效果可能差一大截。这一点在第 6 节的验证环节会专门讲。

2.3 "每日免费积分"到底意味着什么

这是最容易被误解的部分。积分制不是"无限免费"，它有三层隐藏约束：

第一，积分和 token 的换算比例不是 1:1。 不同模型的单价不同，输入和输出的计价也不同。5000 积分可能对应某个轻量模型几十万 token，也可能只对应旗舰模型几万 token。具体比例必须去官方页面看，本文不对具体数值做任何承诺，因为这类规则调整非常频繁。

第二，缓存命中和非命中的消耗差异很大。 大多数厂商对命中缓存的输入 token 打折，如果你的 Agent 每次都在重复发送相同的系统提示词和大段代码，实际消耗会远高于理论计算。

第三，免费额度的调用优先级通常低于付费。 高峰期被限流是常态，所以它适合个人开发和学习，不适合放在对可用性有要求的流水线里。

一个稳妥的心态是：把免费额度当成"评估期资源"，用它来确定"哪个模型适合我的哪类任务"，然后针对高频任务做付费预算，而不是指望免费额度撑起日常开发。

2.4 它的能力边界在哪里

必须说清楚不能指望它做什么：

• 不能替代代码审查的人。 模型可以发现明显的空指针、资源泄漏，但它不理解你的业务约束、历史决策和灰度策略。
• 不能保证生成代码的安全合规。 涉及权限校验、密钥处理、SQL 拼接的部分，生成结果必须人工过一遍。
• 不能处理超大仓库的全局理解。 上下文窗口再大也是有限的，动辄几十万行的仓库，靠一次性塞进去是不现实的，必须做检索增强。
• 不能替你决定架构。 它能给出方案对比，但权衡取舍需要人负责。

把边界划清楚，用起来才不会有落差。

3. 环境准备与前置条件

3.1 基础环境清单

下面是我建议的最小环境，具体版本请以你实际项目和所用 SDK 的官方要求为准，本文重点演示通用思路，不把版本号写死。

3.2 你需要提前准备的三样东西

接口地址（base_url）。 这是接入时最常出错的地方。各家写法不一样，有的带 /v1，有的不带；有的兼容模式路径和原生路径不同。下面列出几个常见服务商的公开地址，作为参考，实际使用时请以官方文档为准：

bash复制# DeepSeek 开放平台
DEEPSEEK_BASE_URL=https://api.deepseek.com

# 智谱 GLM 开放平台
GLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4

# 阿里云百炼（通义千问）OpenAI 兼容模式
QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

# 火山方舟（豆包）OpenAI 兼容模式
DOUBAO_BASE_URL=https://ark.cn-beijing.volces.com/api/v3

模型标识。 这块坑最多。DeepSeek 用 deepseek-chat 这类名字，GLM 用 glm-* 系列，通义千问用 qwen-* 系列，而豆包在方舟平台上通常需要先在控制台创建"推理接入点"，拿到一个以 ep- 开头的接入点 ID 当模型名用。千万不要凭记忆写模型名，一定要去控制台复制。

API Key。 在对应平台的控制台创建，创建后立刻存进环境变量或密钥管理服务，不要写进代码、不要提交到 Git、不要贴在聊天窗口里。

3.3 安全前置：三个必须做的事

第一，给 Key 设置最小可用权限。如果平台支持按项目、按额度、按模型授权，就只开通你要用的那部分。

第二，在 .gitignore 里提前加好忽略项。很多人是在提交之后才发现 Key 泄露的，那时候只能作废重发。

bash复制# 文件路径：.gitignore
.env
.env.local
*.key
secrets/

第三，准备好预算上限。无论是聚合平台还是单个厂商，都应该设置日/月消费告警。Agent 类工具的 token 消耗是普通对话的几十倍，没有上限约束很容易超出预期。

4. 核心流程拆解：从拿到 Key 到跑通第一个任务

4.1 第一步：确认"你要的是哪种接入方式"

这一步很多教程会跳过，但它决定了后面所有操作。先问自己：我需要的是一边写代码一边补全，还是要一个能读整个目录、能执行命令的 Agent，还是要把模型调用嵌进自己的脚本和流水线？

• 只要补全和对话，选 IDE 插件形态，配置项最少；
• 要跨文件重构、批量改代码，选 CLI Agent 形态，但必须理解它的文件写入权限；
• 要嵌进 CI 或者自建工具，选纯 API，灵活性最高也最费事。

我见过最常见的问题，是有人拿纯 API 的 Key 去配插件的配置项，结果插件要求的是另一套专用 Key。这一步先确认清楚，能省掉后面两小时的排查。

4.2 第二步：生成 Key 并做最小连通性测试

拿到 Key 之后，不要直接装插件。先用一行 curl 确认网络能通、Key 有效、模型名存在。这一步能把 80% 的问题在第一步就暴露出来。

bash复制# 文件路径：scripts/smoke_test.sh
# 用法：bash scripts/smoke_test.sh
set -e

: "${LLM_BASE_URL:?请先设置 LLM_BASE_URL}"
: "${LLM_API_KEY:?请先设置 LLM_API_KEY}"
: "${LLM_MODEL:?请先设置 LLM_MODEL}"

curl -sS -X POST "${LLM_BASE_URL}/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${LLM_API_KEY}" \
  -d "{
    \"model\": \"${LLM_MODEL}\",
    \"messages\": [
      {\"role\": \"user\", \"content\": \"只回复两个字：通了\"}
    ],
    \"max_tokens\": 16,
    \"temperature\": 0
  }"

跑通的标准是：返回 JSON 里有 choices[0].message.content，内容是"通了"或者类似的两个字。如果返回 401，是 Key 问题；返回 404，多半是 base_url 路径拼错了（少了 /v1 或者多了 /v1）；返回 400 且提示 model not found，是模型名写错或者没开通。

4.3 第三步：确认上下文窗口和计费口径

连通之后，别急着上生产。先做两件事：

一是探一下上下文上限。用一段长度可控的文本反复试探，找到触发报错的阈值。这个阈值往往比官方标称的小，因为要预留输出空间。

二是看一次真实的用量回执。大多数平台在响应里会返回 usage 字段，包含 prompt_tokens、completion_tokens，有的还返回缓存命中信息。把这些字段打印出来，你才能建立"一次操作花多少钱"的直觉。

4.4 第四步：接入客户端并做一次真实任务验证

插件或 CLI 配置完成后，不要用"你好"来验证，那只能证明链路通，不能证明它对你的代码库有效。用一个真实的、边界清晰的小任务来验证，比如"给这个工具类里的三个方法补 Javadoc"或者"把这个 200 行的类拆成两个文件"。

观察三件事：它有没有读对文件、有没有改错地方、改完之后你要不要回滚。这三个问题能直接告诉你这个工具在你的项目里能不能用。

4.5 第五步：建立用量和质量的观察机制

接入不是终点。建议至少保留两周的记录：每天用了多少积分、跑的是什么类型的任务、返工率大概多少。有了这份数据，你才能回答"这个模型对我的项目到底值不值"。

5. 完整示例与代码实现

下面这套代码是本文的核心，它演示了一个可切换多提供商的最小封装，你在自己的项目里可以直接复用。

5.1 环境变量配置

bash复制# 文件路径：.env
# 注意：此文件必须加入 .gitignore，禁止提交到代码仓库

# 聚合网关（如果使用统一入口）
GATEWAY_BASE_URL=https://your-gateway.example.com/v1
GATEWAY_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx

# 直连 DeepSeek
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx

# 直连智谱 GLM
GLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4
GLM_API_KEY=xxxxxxxxxxxxxxxxxxxx

# 直连通义千问（百炼兼容模式）
QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
QWEN_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx

# 直连豆包（方舟平台，模型名为推理接入点 ID）
DOUBAO_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
DOUBAO_API_KEY=xxxxxxxxxxxxxxxxxxxx
DOUBAO_MODEL=ep-xxxxxxxxxxxx-xxxxx

所有地址和模型名都请以你所用平台的官方文档为准，上面只是常见形态的示意。

5.2 多模型路由封装

python复制# 文件路径：scripts/llm_router.py
# 依赖：pip install openai python-dotenv

import os
import sys
import time
from dataclasses import dataclass
from typing import Optional

from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()


@dataclass
class Provider:
    name: str
    base_url: str
    api_key: str
    model: str


def build_providers() -> dict:
    """从环境变量构建提供商表，缺失配置的直接跳过，避免启动即崩。"""
    raw = {
        "gateway": ("GATEWAY_BASE_URL", "GATEWAY_API_KEY", "GATEWAY_MODEL"),
        "deepseek": ("DEEPSEEK_BASE_URL", "DEEPSEEK_API_KEY", "DEEPSEEK_MODEL"),
        "glm": ("GLM_BASE_URL", "GLM_API_KEY", "GLM_MODEL"),
        "qwen": ("QWEN_BASE_URL", "QWEN_API_KEY", "QWEN_MODEL"),
        "doubao": ("DOUBAO_BASE_URL", "DOUBAO_API_KEY", "DOUBAO_MODEL"),
    }
    providers = {}
    for name, (url_key, key_key, model_key) in raw.items():
        base_url = os.getenv(url_key)
        api_key = os.getenv(key_key)
        model = os.getenv(model_key)
        if base_url and api_key and model:
            providers[name] = Provider(name, base_url.rstrip("/"), api_key, model)
    return providers


def call_once(provider: Provider, prompt: str, timeout: int = 60) -> str:
    """单次调用，带超时和错误兜底。"""
    client = OpenAI(
        api_key=provider.api_key,
        base_url=provider.base_url,
        timeout=timeout,
        max_retries=0,
    )
    resp = client.chat.completions.create(
        model=provider.model,
        messages=[{"role": "user", "content": prompt}],
        temperature=0,
    )
    usage = getattr(resp, "usage", None)
    if usage is not None:
        print(
            f"[usage] provider={provider.name} "
            f"prompt={usage.prompt_tokens} completion={usage.completion_tokens}",
            file=sys.stderr,
        )
    return resp.choices[0].message.content or ""


def call_with_fallback(providers: dict, order: list, prompt: str) -> str:
    """按优先级依次尝试，失败自动降级到下一个。"""
    last_error: Optional[Exception] = None
    for name in order:
        provider = providers.get(name)
        if provider is None:
            continue
        for attempt in range(2):
            try:
                return call_once(provider, prompt)
            except Exception as exc:  # noqa: BLE001
                last_error = exc
                print(f"[warn] {name} 第 {attempt + 1} 次失败: {exc}", file=sys.stderr)
                time.sleep(1 + attempt)
    raise RuntimeError(f"全部提供商均失败，最后一次错误: {last_error}")


if __name__ == "__main__":
    providers = build_providers()
    if not providers:
        raise SystemExit("没有可用的提供商配置，请检查 .env")

    question = "用三句话说明什么是幂等性，不要用代码。"
    answer = call_with_fallback(providers, ["gateway", "deepseek", "qwen", "glm"], question)
    print(answer)

这段代码的关键设计点值得解释一下。

build_providers 选择"缺配置就跳过"而不是"缺配置就报错"，是因为多人协作时，每个人手上的 Key 不可能完全一致。跳过策略让代码在任何人的机器上都能跑起来，只是可用的模型少一些。

call_with_fallback 里的降级顺序是有讲究的。把聚合网关放第一位，是因为它内部通常已经做过一次路由和重试；把响应速度快的模型放在前面，把长上下文强的模型放后面，这样常见任务走快路径，复杂任务才走慢路径。

max_retries=0 加上外层自己控制重试次数，目的很明确：避免 SDK 内部重试和外层重试叠加，导致一次请求实际发了六次、额度扣了六份。

5.3 代码审查脚本：把模型接进 CI

单纯对话没什么意思，真正能省时间的是把它嵌进流程。下面这个脚本读取 git 暂存区的 diff，让模型做一次结构化审查，输出 JSON 便于后续处理。

python复制# 文件路径：scripts/review_staged.py
# 用法：python scripts/review_staged.py

import json
import subprocess
import sys

from dotenv import load_dotenv
from openai import OpenAI
import os

load_dotenv()

MAX_DIFF_CHARS = 12000  # 控制输入规模，避免一次消耗过多额度

SYSTEM_PROMPT = """你是一名严格的代码审查员。
只报告以下几类问题：空指针风险、资源未释放、SQL 拼接导致注入、
异常被吞掉、并发下的共享状态、日志中泄露敏感信息。
不要评论代码风格和命名。输出严格的 JSON 数组，每个元素包含
file、line_hint、severity、issue、suggestion 五个字段。
如果没有问题，输出空数组 []。"""


def get_staged_diff() -> str:
    result = subprocess.run(
        ["git", "diff", "--cached", "--unified=3"],
        capture_output=True,
        text=True,
        check=False,
    )
    return result.stdout


def main() -> int:
    diff = get_staged_diff()
    if not diff.strip():
        print("暂存区没有变更，跳过。")
        return 0

    if len(diff) > MAX_DIFF_CHARS:
        diff = diff[:MAX_DIFF_CHARS]
        print(f"[warn] diff 过长，已截断到 {MAX_DIFF_CHARS} 字符", file=sys.stderr)

    client = OpenAI(
        api_key=os.environ["QWEN_API_KEY"],
        base_url=os.environ["QWEN_BASE_URL"],
        timeout=90,
    )
    resp = client.chat.completions.create(
        model=os.environ["QWEN_MODEL"],
        messages=[
            {"role": "system", "content": SYSTEM_PROMPT},
            {"role": "user", "content": f"以下是 diff：\n\n{diff}"},
        ],
        temperature=0,
    )

    content = (resp.choices[0].message.content or "").strip()
    content = content.removeprefix("```json").removeprefix("```").removesuffix("```").strip()

    try:
        issues = json.loads(content)
    except json.JSONDecodeError:
        print("[error] 模型返回的不是合法 JSON，原文如下：", file=sys.stderr)
        print(content, file=sys.stderr)
        return 2

    if not issues:
        print("未发现命中规则的问题。")
        return 0

    for item in issues:
        print(
            f"[{item.get('severity', 'info')}] {item.get('file', '?')} "
            f"{item.get('line_hint', '')}: {item.get('issue', '')}"
        )
        print(f"  建议：{item.get('suggestion', '')}")
    return 1


if __name__ == "__main__":
    sys.exit(main())

这个脚本有三个地方是踩过坑之后加上的，值得单独说。

MAX_DIFF_CHARS 截断。 不加这个，一次大重构的 diff 可能几十万字符，直接超出上下文窗口，报错还算好的，最怕的是被静默截断，你收到"未发现问题"的结论，实际上模型根本没看到后半段。

JSON 清洗。 即使你在系统提示词里明确说"只输出 JSON"，模型仍有概率包一层 markdown 代码块。removeprefix 这套处理是必要的防御。

退出码设计。 发现问题返回 1，让 CI 步骤变红；解析失败返回 2，和"真有问题"区分开。这样在流水线里你能一眼看出是人该修代码，还是提示词该调。

5.4 接入 CLI 型助手的配置

如果你用的是支持自定义端点的 CLI 助手，通常通过环境变量注入。下面是一份通用的配置模板，具体变量名请对照你所使用工具的官方文档：

bash复制# 文件路径：~/.zshrc 或 ~/.bashrc
# 说明：以下变量名因工具而异，请以对应工具的官方文档为准

# 通用形态：自定义 API 端点
export OPENAI_BASE_URL="https://your-gateway.example.com/v1"
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxx"

# 部分 CLI 工具使用专属前缀，例如：
export ANTHROPIC_BASE_URL="https://your-gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="sk-xxxxxxxxxxxxxxxxxxxx"

配置完之后一定要新开一个终端窗口再测试，因为环境变量不会自动同步到已经打开的会话里。这是新手最常卡住的地方之一。

5.5 一个容易被忽略的检查脚本

最后补一个小工具，用来批量探测哪些模型名在你当前的 Key 下可用。它能省掉大量"猜模型名"的时间。

python复制# 文件路径：scripts/probe_models.py
import os

from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()

CANDIDATES = {
    "deepseek": ["deepseek-chat", "deepseek-reasoner"],
    "glm": ["glm-4-plus", "glm-4-air"],
    "qwen": ["qwen-plus", "qwen-coder-plus"],
}


def probe(provider_key: str, model: str) -> str:
    base_url = os.getenv(f"{provider_key.upper()}_BASE_URL")
    api_key = os.getenv(f"{provider_key.upper()}_API_KEY")
    if not base_url or not api_key:
        return "未配置"
    try:
        client = OpenAI(api_key=api_key, base_url=base_url, timeout=20, max_retries=0)
        client.chat.completions.create(
            model=model,
            messages=[{"role": "user", "content": "hi"}],
            max_tokens=4,
        )
        return "可用"
    except Exception as exc:  # noqa: BLE001
        return f"不可用: {type(exc).__name__}"


if __name__ == "__main__":
    for provider, models in CANDIDATES.items():
        for model in models:
            print(f"{provider:10s} {model:24s} {probe(provider, model)}")

注意这里的 CANDIDATES 只是示例，模型名会随平台版本调整，真实使用时请从控制台的模型列表里复制当前有效的名称。

6. 运行结果与效果验证

6.1 验证脚本本身的运行

bash复制# 安装依赖
pip install openai python-dotenv

# 跑最小连通性测试
export LLM_BASE_URL="https://api.deepseek.com"
export LLM_API_KEY="sk-xxxxxxxxxxxxxxxxxxxx"
export LLM_MODEL="deepseek-chat"
bash scripts/smoke_test.sh

正常返回形如：

json复制{
  "id": "chatcmpl-xxxxxxxx",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "deepseek-chat",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "通了" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 12, "completion_tokens": 2, "total_tokens": 14 }
}

判断成功的标准有三个，缺一不可：HTTP 状态码 200、choices[0].message.content 非空、usage 字段存在。第三个字段很多人忽略，但它意味着你能拿到计量数据，做成本核算的前提。

6.2 路由脚本的验证

bash复制python scripts/llm_router.py

预期在标准错误输出里看到类似 [usage] provider=deepseek prompt=28 completion=64 的日志，标准输出里是与幂等性相关的三句话。如果你故意把 DEEPSEEK_API_KEY 改错一位，应该能看到 [warn] deepseek 第 1 次失败: ... 然后自动降级到 qwen 并成功返回——这证明降级链路是有效的。

6.3 代码审查脚本的验证

bash复制git add scripts/llm_router.py
python scripts/review_staged.py
echo "退出码: $?"

预期输出是问题列表或者"未发现命中规则的问题"，退出码为 0 或 1。不要用一段明显有问题的代码去测，比如故意写个 SQL 拼接，看看它能不能识别出来，这个动作能直观告诉你提示词写得够不够严。

6.4 失败时第一步看哪里

按这个顺序排查，基本能在两分钟内定位：

1. 看 HTTP 状态码，401/403 是鉴权，404 是路径，429 是限流，5xx 是服务端。
2. 看错误响应体里的 error.message，多数平台会给出明确原因。
3. 检查 base_url 结尾有没有多余的斜杠、有没有漏掉 /v1。
4. 检查模型名是不是从控制台抄的，有没有多空格。
5. 检查环境变量是否在当前 shell 生效，echo $LLM_BASE_URL 直接打出来看。

7. 常见问题与排查方法

表格里最后一条值得单独强调。CLI 型 Agent 通常有读写文件和执行命令的权限，一旦上下文理解出错，它可能改错文件甚至删掉内容。稳妥的做法是：在 Git 干净的工作区里运行，或者干脆在容器里跑，并且每次批量操作前先提交一次。

8. 最佳实践与工程建议

8.1 按任务类型做模型路由，而不是按"哪个最强"

很多人纠结"到底选 DeepSeek 还是 GLM"，这个问题本身问错了。正确的问题是：我的哪类任务，应该交给哪类模型。

一个实用的分层策略：

• 补全和行内建议：选延迟最低的轻量模型，用户等不起。
• 单文件修改和单测生成：选代码能力均衡的中档模型，性价比最高。
• 跨文件重构和架构讨论：选长上下文能力强、推理链完整的模型，慢一点可以接受。
• 批量脚本化任务：选价格最低的模型，用并发换时间。

把这个映射写成配置文件，代码里按任务类型取模型，比在代码里硬编码一堆 if 要好维护得多。

8.2 上下文管理是决定效果的第一因素

同一个模型，上下文给得好和给得差，效果能差一个档次。三条经验：

第一，系统提示词要短且稳定。长而多变的系统提示词既费钱又容易让模型分心，而且会破坏缓存命中。

第二，只给必要的文件。不要把整个目录塞进去，用检索或者显式的文件列表。模型的注意力是有限资源。

第三，显式告诉它"不要做什么"。比如"不要修改 import 顺序"、"不要新增第三方依赖"、"遇到不确定的地方停下来提问"。这些约束能显著降低返工率。

8.3 把密钥管理当成正经事

不要在代码里写 Key，不要在配置文件里写 Key，不要在聊天工具里贴 Key。推荐顺序是：密钥管理服务 > 系统环境变量 > 本地 .env 文件（且必须 gitignore）。

更进一步，如果平台支持，给每个环境、每个人分配独立的 Key，这样出问题能定位到人，也方便单独吊销。

8.4 给 Agent 划出安全边界

涉及这几类操作时，必须有人工确认环节：删除文件、执行数据库变更、修改权限配置、发布到生产环境、执行任何 rm -rf 或 DROP 类命令。

一个简单有效的方法是限定工作目录。让 Agent 只在某个子目录内活动，超出范围的操作直接拒绝。另外，涉及数据库的操作永远遵循：先在测试环境验证、执行前备份、准备好回滚脚本、用最小权限账号连接。

8.5 建立可观测性，别做黑盒使用者

至少记录这几项：每次调用的模型名、输入输出 token 数、耗时、是否命中降级。这些数据积累两周，你就能回答"哪个模型在我的场景里性价比最高"这个问题，而这正是聚合平台最大的价值所在——它让你有条件做对比实验。

建议在日志里做脱敏处理，不要把完整的代码片段和业务数据落盘到日志系统里。

8.6 团队协作层面的两条约定

一是统一提示词版本。把系统提示词放进代码仓库，像管理代码一样管理它，改动走 review。否则每个人手里的提示词都不一样，输出质量无从比较。

二是明确 AI 生成代码的责任归属。提交代码的人对代码负责，AI 只是工具。这条约定听起来是废话，但很多团队出事之后才开始补。

8.7 对"免费额度"保持清醒

免费额度适合三类用途：评估阶段跑通链路、低频的辅助任务、个人学习。不适合放在对可用性敏感的自动化流水线里，也不适合处理包含敏感信息的代码。

如果你打算长期用，建议提前算一笔账：按每周的实际 token 消耗估一下付费成本，和订阅制工具对比。很多时候结论是混合使用——高频任务用便宜模型，关键任务用强模型，整体成本反而比全订阅低。

9. 写到最后的几点实话

回到标题里那个说法。所谓"平替 Codex 和 Workbuddy"，本质上不是某一个产品打败了另一个产品，而是接入方式变了：从"绑定某个客户端"变成"绑定某个协议"。协议是通用的，客户端是可替换的，模型也是可替换的。这个变化对开发者的实际意义，比任何一次模型版本的分数提升都更持久。

但也不要被"每日免费"冲昏头。免费额度是有成本的，成本体现在限流、优先级和规则变动上。真正该带走的能力，是本文第 5 节那套路由封装和第 8 节那套路由策略——有了它们，换平台只是改几行环境变量的事。

如果你想继续往下走，有三个方向值得投入：一是把上下文管理做扎实，研究检索增强在代码库上的落地；二是把评测做起来，用你自己的项目构建一套小规模评测集，而不是看公开榜单；三是把安全边界固化下来，尤其是 Agent 的文件和命令权限。

最后提醒一句：本文涉及的接口地址、模型名称、额度规则都属于变化频繁的信息，动手前请务必以对应平台的官方文档为准。代码示例可以照着跑，但生产环境接入前，请在测试分支和测试环境里完整验证一遍，确认回滚方案可用之后再上线。