hydra-ai 模型维护自动化深入解析 AI SDK Model Manager Skill 的完整工作流【免费下载链接】hydra-aiGenerative UI SDK for React项目地址: https://gitcode.com/GitHub_Trending/hy/hydra-ai在基于 AI SDKVercel AI SDK构建 LLM 应用时模型配置的维护是一项高频且琐碎的工作OpenAI、Google、Anthropic、Groq、Mistral 等厂商持续发布新模型SDK 的 TypeScript 类型定义随之更新而你的模型配置文件往往滞后于上游。hydra-aiTambo Cloud仓库中的.claude/skills/ai-sdk-model-manager/SKILL.md正是为了解决这个问题而设计它定义了一套九步自动化工作流覆盖 AI SDK 包升级、缺失模型识别、新模型调研、用户确认、配置写入、类型校验、文档更新、质量检查与 PR 创建。读完本文你将掌握如何在多 Provider 的 LLM 配置仓库中以源码级精度同步最新模型并理解 Tambo Cloud 的模型注册表packages/core/src/llms/models/与文档体系docs/content/docs/reference/llm-providers/之间的完整对应关系。Skill 的定位与适用场景ai-sdk-model-manager是仓库内internal: true的内部技能见 SKILL.md其核心使命是让模型定义与最新 AI SDK 发布保持同步。它在如下场景中应当被触发需要检查ai-sdk/*系列包是否可升级OpenAI、Google、Anthropic 或其他厂商发布了新模型代码中出现了模型 ID 不在 SDK 类型定义中的 TypeScript 报错希望确保平台支持最新的模型能力。从仓库现状看这个维护工作并非虚设packages/backend/package.json中锁定了ai-sdk/anthropic、ai-sdk/google、ai-sdk/groq、ai-sdk/mistral、ai-sdk/openai、ai-sdk/openai-compatible与ai-sdk/provider等依赖见 packages/backend/package.json而packages/core/src/llms/models/下维护着 openai、gemini、anthropic、mistral、cerebras、groq 六套模型定义文件二者共同构成了SDK 版本为真源、模型文件为消费方的依赖关系。Skill 操作的仓库文件地图Skill 明确声明其工作范围覆盖四类文件理解这张地图是执行后续步骤的前提文件/目录作用备注packages/core/src/llms/models/*.ts各 Provider 的模型配置定义openai.ts、gemini.ts、anthropic.ts、mistral.ts、cerebras.ts、groq.ts新增模型的主要落点packages/backend/package.jsonAI SDK 依赖清单是版本的真源source of truthnpm outdated/npm install的施力对象docs/content/docs/reference/llm-providers/*.mdx模型文档页openai.mdx、google.mdx、groq.mdx 等以及 reasoning-models.mdx 等概念页与模型配置一一对应README.md主文档其中的 Supported LLM Providers 章节需同步更新面向用户的入口需要指出的是SKILL.md 中写到的docs/content/docs/models/*.mdx在仓库中的实际位置是docs/content/docs/reference/llm-providers/例如 openai.mdx、groq.mdx执行维护时请以实际目录为准。此外packages/core/src/llms/llm.config.ts是模型注册表的聚合入口它把各 models 文件统一挂载到llmProviderConfig上见 llm.config.ts这是理解配置文件如何被平台消费的关键一环。九步工作流全解析Step 1更新 AI SDK 包维护的第一步是让 SDK 依赖本身保持最新。Skill 给出的命令如下cd packages/backend npm outdated | grep ai-sdk npm install ai-sdk/openailatest ai-sdk/googlelatest ai-sdk/groqlatest ai-sdk/anthropiclatest ai-sdk/mistrallatestnpm outdated | grep ai-sdk用于精确筛选出ai-sdk/*系列中落后于 latest 的包随后一次性升级。在 Tambo Cloud 中这一步之所以必须发生在packages/backend而非packages/core是因为 AI SDK 依赖只在 backend 侧声明核心包packages/core/package.json的 dependencies 中并无ai-sdk/*见 packages/core/package.json这也印证了 SKILL.md 将其定义为版本真源的设计。升级后新的模型 ID 会以字符串字面量联合类型的形式出现在 SDK 的index.d.ts中这正是下一步比对的基础。Step 2识别缺失模型升级完成后需要逐一检查各 Provider SDK 类型定义中新增的模型 ID# 检查 SDK 类型中包含哪些模型 cat node_modules/ai-sdk/openai/dist/index.d.ts | grep type.*ModelId cat node_modules/ai-sdk/google/dist/index.d.ts | grep type.*ModelId cat node_modules/ai-sdk/groq/dist/index.d.ts | grep type.*ModelId将这些 ID 与当前模型配置逐一比对找出SDK 有、配置无的模型。在 Tambo Cloud 中配置侧的模型 ID 是受类型约束的以 openai.ts 为例文件开头通过type RawModelIds ParametersOpenAIProvider[languageModel][0]直接从ai-sdk/openai的 Provider 类型中提取出全部合法模型 ID再经 typeutils.ts 中的NarrowStrings工具类型过滤掉宽泛的string得到只含字面量的OpenAIModelId。gemini.ts、anthropic.ts、groq.ts、mistral.ts 均遵循同一模式。这意味着一个有趣的闭环如果某个模型 ID 不在 SDK 类型中你在配置文件里写下它就会直接触发 TS 报错反过来一旦 SDK 升级带来了新的字面量 IDTypeScript 类型系统会自动放行你添加该模型。因此类型检查既是 Step 6 的验证手段也是 Step 2 的识别工具——当你尝试添加一个 ID 而 TS 报错时几乎可以断定该模型尚未进入 SDK 或 ID 拼写有误。Step 3调研新模型找到缺失模型后Skill 建议启动researcher 子代理subagent并行收集信息因为子代理具备联网搜索能力可以同时调研多个模型。需要收集的字段包括官方文档链接模型能力推理 reasoning、视觉 vision、函数调用 function calling 等上下文窗口大小对应inputTokenLimit定价档位最佳使用场景发布日期与状态experimental / stable / deprecated。这一步骤的质量直接决定 Step 5 中notes、docLink、inputTokenLimit等字段的准确性。Skill 的原则是宁可标记为 unknown 待验证也不要猜测。Step 4向用户汇报并确认在改动任何文件之前必须将调研结果整理后呈现给用户等待明确批准。SKILL.md 给出了汇报格式示例Found the following new models in updated AI SDK packages: OpenAI: - gpt-6-preview (200k context, experimental reasoning model) - gpt-4.2-turbo (1M context, improved function calling) Google: - gemini-3.5-pro (2M context, advanced reasoning) Which models would you like to add? (all/none/specific)说明上例中的gpt-6-preview、gemini-3.5-pro是 SKILL.md 用于演示汇报格式的占位示例并非仓库当前真实存在的模型。仓库实际的 OpenAI 模型以gpt-5.4、gpt-5.4-pro、gpt-5.3-chat-latest、gpt-5.2、o3-2025-04-16等为代表见 openai.tsGoogle 侧以gemini-3-pro-preview、gemini-2.5-pro、gemini-2.5-flash为代表见 gemini.ts。执行维护时应以SDK 类型中真实存在的 ID为准。确认选项为 all / none / specific未获批准前不进行任何写入。Step 5添加选中模型含字段规范获得用户批准后Skill 建议为分布在多个 Provider 上的模型并行启动子代理各自编辑对应的 models 文件如 OpenAI、Google、Groq 各一个子代理以缩短整体耗时。每个新增模型必须包含如下字段这些字段与 llm-config-types.ts 中LlmModelConfigInfo接口的定义完全对应字段类型/取值含义apiNamestring实际发起 API 调用时使用的模型 ID必须与 SDK 类型定义逐字一致displayNamestring面向用户的可读名称statusuntested \| tested \| known-issues集成状态新模型一律标记为untestednotesstring能力与适用场景的简要描述docLinkstring厂商官方文档链接tamboDocLinkstringTambo 自身文档链接通常为https://docs.tambo.coinputTokenLimitnumber上下文窗口大小token 数modelSpecificParamsLlmParameterMetadata该模型特有的参数元数据如推理、思考相关modelParamsDefaultsProviderSpecificParamsProvider 特有参数的默认值可选isDefaultModelboolean是否为默认模型可选supportsSkillsboolean是否支持 Provider skillsOpenAI shell tool、Anthropic code_execution 等必填commonParametersDefaultsCommonParametersDefaults通用参数默认值可选其中modelSpecificParams的定义来自LlmParameterMetadata见 llm-config-types.ts每个参数项由description、uiTypenumber | string | boolean | array | object与example组成。仓库中的真实用例OpenAI 侧定义了reasoningEffort与reasoningSummary两个推理参数见 openai.ts并为gpt-5.4配置了默认值{ reasoningEffort: low, reasoningSummary: auto }见 openai.tsGoogle 侧则定义了thinkingConfig示例为{ thinkingBudget: 8192, includeThoughts: true }见 gemini.ts。这些推理参数的使用方式在 reasoning-models.mdx 文档中有面向用户的说明。SKILL.md 给出的添加示例占位演示gpt-6-preview: { apiName: gpt-6-preview, displayName: gpt-6-preview, status: untested, notes: Experimental next-generation reasoning model with extended context, docLink: https://platform.openai.com/docs/models/gpt-6-preview, tamboDocLink: https://docs.tambo.co, inputTokenLimit: 200000, modelSpecificParams: reasoningParameters, },对照仓库真实条目如 openai.ts 中的gpt-5.4可以看到结构完全一致且真实条目还会补充supportsSkills、modelParamsDefaults等字段。另外注意各文件的组织约定模型按版本新版本在前排序如注释所述 Minor versions (e.g., 5.1) are considered newer than their base versions (e.g., 5)见 openai.ts。添加完成后还要留意packages/core/src/llms/llm.config.ts的聚合逻辑——例如当前groqModels已定义见 groq.ts但llmProviderConfig中因Groq 仍存在一些问题而暂未挂载见 llm.config.ts 的注释。如果本次维护涉及启用/停用某个 Provider需要同步修改聚合配置。Step 6验证 TypeScript 类型任何模型 ID 或字段改动都必须通过类型检查因为模型 ID 的类型是从 SDK 直接推导的cd packages/core npm run check-typescheck-types脚本对应tsc --noEmit见 packages/core/package.json。若报错几乎总是模型 ID 与 SDK 定义不一致——回到 Step 2 的grep结果逐字核对即可。Step 7更新文档代码之外文档必须同步。Skill 建议在涉及多个文档文件时并行启动子代理处理对象包括README.md—— 若新增了 Provider 或重要模型更新 Supported LLM Providers 章节docs/content/docs/reference/llm-providers/*.mdx—— 在对应 Provider 页面补充新模型内容包括模型名称与描述、关键能力、上下文窗口、示例用例、厂商文档链接。仓库中的文档与配置保持着高度一致的对应关系例如 groq.mdx 中llama-4-scout-17b-16e-instruct的 Status: Untested / Context Window: 128K tokens 与 groq.ts 中同模型的status: untested、inputTokenLimit: 131072完全呼应。新增模型时保持这种配置-文档双写的一致性是质量红线。Step 8运行质量检查提交前在packages/core下依次执行npm run lint npm run check-types npm run test对应脚本为 eslint、tsc --noEmit与 jest见 packages/core/package.json。这确保新增配置既通过静态检查也不破坏既有测试。Step 9创建 Pull Request最后按约定格式创建 PRgh pr create --title feat(models): add [model names] support --body $(cat EOF Updated AI SDK packages and added support for newly released models: Models added: - [list models here] Package updates: - ai-sdk/openai: X.X.X → X.X.X - ai-sdk/groq: X.X.X → X.X.X All type checks passing, documentation updated. EOF )PR 标题规范新增模型用feat(models):仅升级依赖用deps(core):。设计原则与错误处理SKILL.md 沉淀了七条维护准则值得在任何 LLM 配置仓库中复用善用子代理提效—— 调研用 researcher 子代理并行搜集信息编辑用并行子代理分文件写入先调研后添加—— 不猜测模型能力与上下文限制与 SDK 类型严格一致—— 模型 ID 必须逐字匹配node_modules中的类型定义新模型标记为untested—— 由团队验证后再提升为tested保留官方文档链接——docLink必须指向厂商官方文档保持保守—— 只添加用户明确批准的模型文档全面更新—— 不止改代码所有相关文档一并同步。对应的错误处理路径同样明确症状处理方式添加模型后出现类型错误核对模型 ID 是否与 SDK TypeScript 定义逐字一致SDK 中找不到模型厂商可能尚未发布等待下一次 SDK 更新模型名冲突采用 SDK 偏好的命名约定上下文窗口未知查阅厂商文档或标记为 unknown 并注明待验证维护节奏与注意事项SKILL.md 建议周期性运行本技能每月一次或每当有厂商发布新模型时触发。此外还有几点长期维护经验提交前务必git diff检查确保只包含预期改动部分模型存在特殊要求API 访问权限、定价档位等应在notes字段中注明若 SDK 中模型被重命名需要同时更新配置对象的 key 与apiName并为旧条目添加弃用deprecation说明。总结AI SDK Model Manager Skill 是一份可以直接落地的模型维护 SOP它以packages/backend/package.json中的 AI SDK 依赖为版本真源通过 SDK 类型定义驱动模型 ID 的识别与校验以packages/core/src/llms/models/为配置落点最终同步到docs/content/docs/reference/llm-providers/文档与 README。九步流程覆盖了从发现新模型到合入主仓库的完整闭环而仓库中类型推导、字段元数据、聚合配置与文档映射等实现细节则为这一流程提供了可验证的工程基础。无论你是 hydra-ai 的维护者还是其他基于 AI SDK 构建多 Provider 应用的技术团队都可以将这套方法论迁移到自己的模型配置治理中。【免费下载链接】hydra-aiGenerative UI SDK for React项目地址: https://gitcode.com/GitHub_Trending/hy/hydra-ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考