面向 Coding Agents 的 MCP 模型目录：让模型选择实现机器可读

如果编程 Agent 将模型名称硬编码在代码中，最终必然会在凌晨两点触发报警。面向编程 Agent 的 MCP 模型目录改变了这种故障模式。Agent 不再从源代码中读取固定的字符串，而是在请求时读取包含当前模型、成本、模态和状态字段的结构化列表。我们在 TokenLab 维护着类似的目录，并将该目录作为路由的唯一事实来源。在我们的流水线中，模型选择是一个查找过程，而不是一个常量。

为什么编程 Agent 需要机器可读的模型数据

大多数编程 Agent 的集成方式仍然像十年前的 API 集成一样：开发者选择一个模型名称，将其粘贴到配置或环境变量中，然后发布。这种方式在提供商弃用模型、更改定价或发布更好的选项之前都是有效的。一旦发生变动，团队往往缺乏相应的应对流程。

机器可读的目录改变了这种故障模式。当模型退役时，Agent 可以查询目录，识别出模型已移除或被标记为弃用，并回退到已记录的替代方案。无需开发者手动对每个新版本进行基准测试，工具可以在切换前自动比较列出的上下文窗口、模态支持和成本字段。

这也是实现专业模型路由的前提。你可能希望在 DeepSeek V4 Flash 或 Gemini 3.5 Flash 上进行低成本、大容量的补全任务，并为多文件重构预留 Claude Sonnet 5。路由逻辑仍然需要一个事实来源，该来源必须明确哪些模型是当前的、它们的成本是多少以及它们支持什么。没有它，路由规则就会像硬编码的模型名称一样逐渐失效。

TokenLab 曾直接探讨过这个问题。请参阅 agent-readable model truth 以了解更广泛的论点，并参阅 agent-first API 以了解当主要调用者是 Agent 而非人类开发者时，API 设计应如何改变。

关键要点

• 模型目录将模型选择从硬编码字符串转变为运行时查找，从而降低了提供商发布新模型时的维护负担。
• 编程 Agent 通过将不同任务类型（自动补全、重构、测试生成、审查）路由到不同的模型，而非对所有任务使用单一模型，从而获益。
• 用于模型目录数据的 MCP 请求通常遵循 resource-list 或 tool-call 格式；在基于其构建之前，请务必根据提供商的官方文档验证确切的 schema。
• TokenLab 在 /models/data 发布了模型数据中心，并在 /models 发布了模型目录；请将这些地方作为验证当前模型名称的权威来源，而非本文，因为模型阵容更新频繁。

MCP 模型目录条目应包含的内容

对于编程 Agent 而言，有用的目录条目不仅仅需要模型名称。构建者和消费者至少应期望看到以下内容：

• 模型标识符 (Model identifier)：API 期望的确切字符串，因为提供商通常会精确地对名称进行版本控制（此处的不匹配是集成中最常见的 Bug 之一）。
• 提供商 (Provider)：提供该模型的公司或平台，在目录聚合了多个提供商时尤为重要。
• 模态支持 (Modality support)：文本、代码、图像或视频。当目录混合了像 Kimi K2.7 Code 这样的编程模型和像 Nano Banana Pro 这样的图像模型时，需要一个字段让 Agent 根据其实际需求进行过滤。
• 上下文窗口 (Context window)：对于在大型代码库中工作的编程 Agent 来说，token 限制至关重要。
• 成本字段 (Cost fields)：输入和输出 token 的定价，最好分开列出，因为编程 Agent 通常具有非对称的输入密集型工作负载（大文件上下文、小 diff 输出）。
• 状态 (Status)：当前、已弃用或计划退役。这是防止静默故障的关键字段。
• 任务适用性标签 (Task suitability tags)：可选但有用的元数据，例如“coding”、“low-cost routing”或“open-weight”，以便 Agent 无需预先了解每个模型的特性即可进行过滤。

并非所有提供商的目录格式都保证包含这些字段。在 构建集成 之前，请检查你所使用的提供商记录的实际 schema。特别是对于 TokenLab 提供的模型，请验证当前的字段集和更新频率（位于 /models/data），不要假设它们与本文一致。随着新模型和模态的添加，目录 schema 会发生变化。

示例：通过 MCP 请求模型目录

MCP 通常通过 JSON-RPC 2.0 进行通信。客户端请求服务器列出可用模型资源时，发送的请求格式可能如下所示。此示例遵循通用的 MCP resource-list 模式。它并不代表任何特定提供商的实时 schema。在编写生产代码之前，请根据 https://docs.tokenlab.sh 或你所使用的 MCP 服务器的文档确认确切的方法名称和响应字段。

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "resources/list",
  "params": {
    "filter": {
      "modality": "text",
      "tag": "coding"
    }
  }
}

一个合理的响应格式（同样仅作说明，而非验证过的 schema）：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resources": [
      {
        "id": "claude-sonnet-5",
        "provider": "Anthropic",
        "modality": ["text", "code"],
        "context_window": "verify at provider docs",
        "status": "current",
        "tags": ["coding", "review"]
      },
      {
        "id": "deepseek-v4-flash",
        "provider": "DeepSeek",
        "modality": ["text", "code"],
        "context_window": "verify at provider docs",
        "status": "current",
        "tags": ["low-cost", "coding"]
      }
    ]
  }
}

请勿将上述上下文窗口值、确切字段名称或特定模型视为任何实时 API 的确认事实。它们展示了请求和响应的形态，而非定价或能力数据。构建时请从提供商的当前文档或 /models/data 中获取这些数值。

按任务选择模型：决策检查清单

只有当 Agent 或配置 Agent 的开发者拥有将任务类型与模型匹配的规则时，模型目录才有用。下表是一个初始框架，而非基准测试结果。在生产环境中确定路由规则之前，请根据提供商文档和 /models 验证当前的定价和能力声明。

编程 Agent 任务	最看重的因素	待评估的模型示例
自动补全 / 行内建议	低延迟，单次调用成本低	DeepSeek V4 Flash, Gemini 3.5 Flash, Laguna XS 2.1
多文件重构	更大的上下文窗口，强大的代码推理能力	Claude Sonnet 5, DeepSeek V4 Pro
测试生成	格式一致性，中等推理能力	Kimi K2.7 Code, Claude Sonnet 5
代码审查 / PR 总结	强大的推理能力，准确引用 diff 的能力	Claude Sonnet 5, Gemini 3.5 Flash
大批量批处理任务（Linting、文档注释）	token 成本优于原始能力	GLM-5.2, Qwen3.7 Plus, MiniMax M3
开源权重需求（自托管或许可限制）	开源权重，可在托管 API 之外部署	GLM-5.2, DeepSeek V4 Pro, DeepSeek V4 Flash, Qwen3.7 Plus, Kimi K2.7 Code

构建路由逻辑本身的实用检查清单：

1. 目录条目是否包含状态字段，以便在调用失败前检测到弃用？
2. 目录是否将具备编程能力的模型与通用文本或图像模型分开，以便过滤时无需硬编码列表？
3. 你是否可以为每种任务类型设置成本上限，并让 Agent 选择满足该上限的最便宜模型，而不是总是默认选择能力最强（也最昂贵）的选项？
4. 是否为每个任务类别定义了回退模型，以防首选模型不可用或受到速率限制？
5. 你是否在按计划重新检查目录，而不仅仅是在首次集成时检查，因为模型阵容会随时间变化？

TokenLab 在此工作流中的位置

TokenLab 维护着一个模型数据中心（位于 /models/data）和一个模型目录（位于 /models），截至 2026-07-14。请查看这些页面以获取当前模型列表，而不是依赖任何静态文章。模型目录本质上是具有时效性的。在集成之前，请访问 TokenLab 的 API 文档 https://docs.tokenlab.sh 以验证确切的请求和响应 schema。

你可以构建一个在多个模型之间进行路由的编程 Agent。使用 Claude Sonnet 5 进行审查任务，DeepSeek V4 Flash 进行廉价的大容量补全，Kimi K2.7 Code 进行测试生成。将模型标识符视为变量。在请求时根据目录解析它，而不是将其作为常量编译到 Agent 的源代码中。实际步骤是检查 /models/data，并根据 TokenLab API 文档确认你的 MCP 客户端所需的请求格式。只有在完成这些检查后，才将路由逻辑投入生产。

局限性

本文描述了 MCP 模型目录和编程 Agent 路由的一般模式。它并不确认任何特定提供商（包括 TokenLab）是否完全按照这种形式（上下文窗口、成本字段、状态、任务标签）公开上述所有字段。Schema、字段名称和可用模型经常变化。请将本文中的 JSON 示例视为 MCP 通用请求和响应模式的说明，而非任何实时端点的已验证 schema。在发布之前，请根据提供商的当前文档和 /models/data 确认确切的模型标识符、定价和上下文窗口。

常见问题解答

MCP 本身是否定义了标准的模型目录 schema？

MCP 定义了通过 JSON-RPC 进行资源和工具交互的通用模式，但模型目录中的确切字段（定价、上下文窗口、状态）取决于实现 MCP 的服务器选择如何公开这些数据。请与你集成的服务器或提供商核实具体 schema。

编程 Agent 是否应该始终使用当前可用的最强模型？

不一定。自动补全等任务对延迟和成本敏感，而多文件重构则受益于更强的推理能力和更大的上下文。带有任务标签和成本字段的目录允许你按任务进行路由，而不是默认对所有任务使用单一模型。

我应该多久重新检查一次 Agent 所依赖的模型目录？

模型阵容的变化频率很高，仅做一次集成是不够的。构建路由逻辑时应查询目录，而不是永久缓存模型标识符，并定期检查 /models/data 或提供商的文档。

在将路由逻辑投入生产之前，请先查看 /models/data 中的当前列表，并根据 TokenLab API 文档确认你的 MCP 客户端所需的请求格式，以此开始你的工作。