企业官网建设流程全解析

Typebot 模型列表更新指南：为 OpenAI 与 Anthropic 块同步最新 AI 模型

【免费下载链接】typebot.io💬 Typebot is a powerful chatbot builder that you can self-host.项目地址: https://gitcode.com/GitHub_Trending/ty/typebot.io

本指南围绕 Typebot 开源仓库中的update-models技能文档，系统讲解如何在packages/forge/blocks/openai与packages/forge/blocks/anthropic两个 Forge 集成块中维护 AI 模型清单。你将掌握：模型常量文件的完整结构与每个数组的用途、模型下拉选项（autoCompleteItems）在界面层的消费链路、通配符形式的图片 URL 支持判定逻辑，以及一套可重复执行的「先取最新列表 → 对比 → 顶部插入新模型 → 保留旧模型 → 更新命名模式」的更新流程。

一、为什么需要手动维护模型列表

Typebot 的 OpenAI 与 Anthropic 集成块在配置面板中提供了模型下拉/自动补全（autoComplete）选项，供用户在创建聊天消息、生成变量时选择模型。这些候选列表并非运行时从各厂商 API 动态拉取，而是硬编码在 Forge 块的常量文件中，作为编辑器界面的静态数据源。

从源码可以看到，模型选项通过option.string.meta({ layout: { autoCompleteItems: models } })暴露给界面：

• OpenAI 块的Ask Model动作在 actions/askModel.ts 中定义，autoCompleteItems直接引用constants.ts中的models数组；
• Anthropic 块的Create Chat Message动作在 actions/createChatMessage.ts 中定义，autoCompleteItems引用anthropicModels数组。

因此，每当上游厂商发布新模型，若不更新这些常量文件，用户在 Typebot 编辑器中就看不到新模型选项。这正是update-models技能存在的意义——它把这一维护工作标准化为固定流程。

二、待修改的文件与核心数据结构

技能文档明确指定了要修改的文件与对应的常量：

需要说明的是：技能文档写作时提到的chatModels、reasoningModels两个数组，在当前仓库源码中已合并为单个models数组（详见下文），更新时以当前源码的实际导出为准。

2.1 OpenAI 块常量文件

packages/forge/blocks/openai/src/constants.ts 是模型更新的核心文件，完整结构如下：

• models（第 18–40 行）：主模型列表，按「最新在前」排序，包含gpt-5.4、gpt-5.4-pro、gpt-5.4-mini、gpt-5.4-nano、gpt-5.3-chat、gpt-5.2-pro、gpt-5.2、gpt-5.1-chat、gpt-5、gpt-5-mini、gpt-5-nano、gpt-4.1系列、gpt-4o/gpt-4o-mini、o3/o4-mini/o3-mini/o1/o1-mini推理模型等。注意该数组同时容纳了聊天模型（Chat）与推理模型（Reasoning），即文档中chatModels与reasoningModels合并后的形态。
• modelsWithImageUrlSupport（第 42–47 行）：支持图片 URL 输入的模型命名模式，使用通配符匹配，如gpt-5*、gpt-4-turbo*、gpt-4o*、gpt-4*vision-preview。
• excludedModelsFromImageUrlSupport（第 49 行）：图片 URL 支持的排除名单，例如gpt-4-turbo-preview（虽匹配gpt-4-turbo*模式但不支持视觉输入，需在此显式排除）。
• defaultOpenAIOptions（第 51–54 行）：默认选项，model: "gpt-4o-mini"、voiceModel: "tts-1"。不建议随意改动默认模型，它决定了新用户的初始体验。
• ttsModels（第 1 行）：语音合成模型列表（gpt-4o-mini-tts、tts-1、tts-1-hd），供Create Speech动作使用。
• transcriptionModels（第 2–7 行）：语音转文字模型列表（gpt-4o-transcribe、gpt-4o-mini-transcribe、gpt-4o-transcribe-diarize、whisper-1），供Create Transcription动作使用。
• openAIVoices（第 9–16 行）：可用音色（alloy、echo、fable、onyx、nova、shimmer），用as const收紧为字面量联合类型。
• maxToolCalls（第 56 行）：单轮执行中最多允许的工具调用轮次数（10），与模型列表无直接关系，但属于该文件的受控常量。

2.2 Anthropic 块常量文件

packages/forge/blocks/anthropic/src/constants.ts 结构更简单：

• anthropicModels（第 1–14 行）：Claude 模型列表，按最新在前排列，如claude-opus-4-6、claude-sonnet-4-6、claude-haiku-4-5、claude-sonnet-4-5、claude-opus-4-5、claude-opus-4-1、claude-sonnet-4-0、claude-opus-4-0，以及claude-3-7-sonnet-latest、claude-3-5-haiku-latest、claude-3-5-sonnet-latest、claude-3-opus-latest等-latest别名。
• modelsWithImageUrlSupport（第 18 行）：Anthropic 侧为单一模式claude-*——即所有 Claude 模型都支持图片输入。
• supportedImageTypes（第 20–25 行）：支持的图片 MIME 类型白名单（image/png、image/jpeg、image/gif、image/webp），同样使用as const。
• defaultAnthropicMaxTokens（第 16 行）：默认最大 Token 数（1024），被createChatMessage.ts中maxTokens选项的defaultValue引用。
• maxToolRoundtrips（第 27 行）：工具调用最大往返次数（10）。

三、模型列表的消费链路：从常量到运行时行为

理解常量如何被消费，才能在更新时预判影响范围。以「图片 URL 支持」为例，helpers/isModelCompatibleWithVision.ts 展示了完整的判定逻辑：

import { wildcardMatch } from "@typebot.io/lib/wildcardMatch"; import { excludedModelsFromImageUrlSupport, modelsWithImageUrlSupport, } from "../constants"; export const isModelCompatibleWithVision = (model: string | undefined) => model && !excludedModelsFromImageUrlSupport.includes(model) ? wildcardMatch(modelsWithImageUrlSupport)(model) : false;

判定规则可以概括为三步：

1. 模型名为空 → 直接返回false；
2. 模型命中excludedModelsFromImageUrlSupport排除名单 → 返回false；
3. 否则用wildcardMatch（来自 lib/wildcardMatch.ts）对modelsWithImageUrlSupport中的通配符模式逐一匹配。

在 OpenAI 的Ask Model运行时（handlers/askModelHandler.ts），该判定结果直接决定消息内容的处理方式：

const messageContent = isModelCompatibleWithVision(model) ? await splitMessageIntoResponsesApiInputItems(message) : message;

即：模型支持视觉时，用户消息会被拆分为适配 Responses API 的多模态输入项；否则按纯文本消息发送。Anthropic 侧也有对称的判定文件 helpers/isModelCompatibleWithVision.ts，复用wildcardMatch与claude-*模式。

这解释了为什么技能文档把modelsWithImageUrlSupport的更新单列为一步：若新模型在 API 侧支持图片输入，却未命中通配符模式（或反过来，某模型命中模式但不支持视觉），都会导致消息组装行为错误——前者丢失多模态能力，后者可能引发请求失败。

此外，OpenAI 块的ttsModels与transcriptionModels分别被 actions/createSpeech.ts 与 actions/createTranscription.ts 的autoCompleteItems引用；Anthropic 的defaultAnthropicMaxTokens则在createChatMessage.ts第 83–90 行作为maxTokens的默认值。运行时行为均有对应测试覆盖，例如 handlers/createTranscriptionHandler.test.ts 与 handlers/createChatCompletionHandler.test.ts。

四、模型更新五步法（标准操作流程）

以下流程直接继承自update-models技能文档，并补充了可执行细节：

步骤 1：获取上游最新模型列表

以models.dev（一个开源的、提供各厂商 API 精确模型 ID 的模型数据库）作为唯一事实来源。按 provider 维度分别抓取 OpenAI 与 Anthropic 的当前模型列表，重点收集新发布模型的官方 API 标识符（model ID）。

关键约束：写入models/anthropicModels的必须是 API 可用的精确模型 ID（例如gpt-4.1、claude-sonnet-4-5），不能使用展示名称或别名，否则块运行时会向厂商 API 发送无效模型名。

步骤 2：与现有列表对比

将抓取结果与当前 packages/forge/blocks/openai/src/constants.ts 的models数组、packages/forge/blocks/anthropic/src/constants.ts 的anthropicModels数组逐项比对，找出：

• 上游新增、本地缺失的模型 ID；
• 上游已下线、本地仍保留的模型 ID（不要急于删除，见步骤 4）。

步骤 3：新模型插入列表顶部

将新增模型追加到数组的最前面，保持「最新在前」的排列约定：

// packages/forge/blocks/openai/src/constants.ts export const models = [ "gpt-5.4", // ← 最新发布的模型放在最前面 "gpt-5.4-pro", "gpt-5.4-mini", // ... 其余按版本新旧依次排列 "o1-mini", // ← 最旧的模型在末尾 ];

新模型置于顶部会让其在编辑器下拉列表中优先展示，符合「推荐使用最新模型」的产品预期。

步骤 4：保留旧模型以维持向后兼容

不要删除任何旧模型。已发布的 Typebot 机器人可能在存量配置中引用了这些模型 ID，从常量中移除会导致已有流程在运行时解析失败。旧模型统一保留在列表底部，直到确认下游兼容性已处理完毕（例如通过配置迁移或废弃流程清理）。

步骤 5：同步更新图片 URL 支持模式

对照步骤 3 新增的模型，检查modelsWithImageUrlSupport中的通配符模式是否仍然覆盖新模型：

• OpenAI 侧（gpt-5*、gpt-4-turbo*、gpt-4o*、gpt-4*vision-preview）：若新模型命名不再落入任何已有模式，需新增对应模式；若某模型命中模式但实际不支持视觉，则加入excludedModelsFromImageUrlSupport排除名单；
• Anthropic 侧（claude-*）：只要新增模型仍遵循claude-前缀命名，通常无需改动；仅当未来出现命名规则变化时才需要调整。

五、更新注意事项与验证

5.1 范围与边界

• 本次流程只改两个constants.ts文件，不要顺手改动schemas.ts——openai/src/schemas.ts 与 anthropic/src/schemas.ts 均由 Forge 框架的parseBlockSchema自动生成（文件头部明确标注 "Do not edit this file manually"），模型数组的变化会自动反映到 schema 中。
• 若新增的是语音/转写类模型，还需同步检查ttsModels与transcriptionModels（仅 OpenAI 侧），它们不在技能文档的默认清单内，但属于同一维护范畴。
• defaultOpenAIOptions.model保持稳定即可，更新模型列表不需要同步提升默认模型。

5.2 命名模式与排除名单的关系

图片支持判定是「通配符模式匹配 + 排除名单」的组合逻辑：先匹配modelsWithImageUrlSupport，再在excludedModelsFromImageUrlSupport中二次过滤。因此更新时需同时审视两处，任何单边修改都可能造成误判。

5.3 验证建议

• 类型检查：models、anthropicModels、openAIVoices、supportedImageTypes中多处使用as const收紧类型，新增项必须满足字面量类型约束，运行类型检查可第一时间暴露拼写错误；
• 单元测试：OpenAI 块的 handler 已有测试覆盖（createChatCompletionHandler.test.ts、createTranscriptionHandler.test.ts），模型列表变更后运行相关测试可验证消息组装与 API 调用路径未受影响；
• 界面验证：启动 builder 应用后，在 OpenAI/Anthropic 块的动作配置面板中确认新模型出现在自动补全候选的最顶部。

六、小结

update-models技能的本质，是把「厂商发布新模型 → 同步到 Typebot 编辑器选项」这一重复性维护工作固化为可执行的标准化流程。它建立在两个精确的常量文件之上：

• packages/forge/blocks/openai/src/constants.ts：models（主模型）、ttsModels、transcriptionModels、modelsWithImageUrlSupport与excludedModelsFromImageUrlSupport（视觉能力）、defaultOpenAIOptions（默认配置）；
• packages/forge/blocks/anthropic/src/constants.ts：anthropicModels、modelsWithImageUrlSupport（claude-*）、supportedImageTypes、defaultAnthropicMaxTokens。

只要遵循「新模型置顶、旧模型保留、同步更新命名模式」的三条铁律，并理解模型列表如何经autoCompleteItems进入编辑器、如何经isModelCompatibleWithVision影响运行时消息组装，就能安全、快速地完成每一次模型同步。

【免费下载链接】typebot.io💬 Typebot is a powerful chatbot builder that you can self-host.项目地址: https://gitcode.com/GitHub_Trending/ty/typebot.io