用途 本技能用于在 Node.js 后端、云函数或 CloudRun 服务中，通过 @cloudbase/node-sdk 调用 AI 模型。它适合真正需要服务端执行的 AI 调用：图像生成（仅该 SDK 支持）、长时间运行的智能体任务、跨多个工具的编排、定时任务，以及必须将密钥保留在服务端的流程。
运行时选择 路由首先由运行时平面决定，具体模型（deepseek-、glm-、hunyuan-、kimi- 等）只影响 model 字段。若用户构建网页/前端 AI 聊天界面，不要用后端代理包装该 SDK，应改用 ai-model-web 从浏览器直接调用模型；微信小程序应改用 ai-model-wechat；没有 CloudBase SDK 的运行时（Python、Go、PHP、curl 等）应改用 http-api-cloudbase，其中包含 ai_model OpenAPI 规范，可直接通过 HTTP 调用 AI 模型端点，不要用 HTTP 代理包装该 SDK。
主要能力 支持将 AI 文本生成集成到后端服务、使用混元图像模型生成图像、从 CloudBase 云函数或 CloudRun 调用 AI 模型，以及服务端 AI 处理（智能体编排、批处理任务、定时任务）。图像生成使用独立入口 ai.createImageModel("hunyuan-image")，仅 Node SDK 支持。
createModel 参数规则 ai.createModel(...) 的参数不是厂商名或模型名，只有三种合法形式："cloudbase"（服务端项目的主托管组，由 TokenHub 支持的多厂商池，厂商与具体模型放入 generateText / streamText 的 model 字段，例如 { model: "deepseek-v4-flash" }）；"hunyuan-exp"（仅当 DescribeAIModels 明确返回该旧版内置组时使用）；"custom-<your-name>"（通过 CreateAIModel 接入的用户自定义 GroupName，必须以 custom- 开头，例如 custom-kimi、custom-openai-compat）。厂商名（"deepseek"、"glm"、"kimi"、"openai"、"moonshot" 等）、具体模型 id、裸占位符 "custom" 或保存模型 id 的变量都是错误写法。图像生成是独立入口，不要与 createModel(...) 混用。
使用方式与预检 在服务端调用任何 AI API 前，必须执行两步预检：① 资格检查，通过 MCP 工具 queryEnv（action=info）获取 EnvId，再调用 callCloudApi(service="tcb", action="DescribeEnvPostpayPackage", params={ EnvId }) 确认存在 postpayPackageId 以 pkg_tcb_tokencredits_ 开头且状态不在 [3, 4] 的条目；文本生成与图像生成共用同一 Token Credits 资源包。若不满足，应停止写代码并向用户提示购买链接，而不是输出 SDK 代码让用户调试运行时错误。② 组就绪检查，调用 DescribeAIModels 确认目标 GroupName 存在且 Status=1、目标 Model 在其 Models[] 中；若缺失，先用 DescribeManagedAIModelList 确认平台支持的准确 Model 名称（区分大小写，不要猜测拼写）与定价，再通过 UpdateAIModel 启用（注意 Models 是全量替换，需连同已启用模型一起重发，Status: 1）。所有 Action 使用 service=tcb、Version=2018-06-08，参数为 PascalCase，仅在 InvalidParameter 时回退 camelCase。
安装与初始化 安装命令：npm install @cloudbase/node-sdk。AI 功能要求版本 3.16.0 或以上，可用 npm list @cloudbase/node-sdk 检查。云函数内初始化示例：const tcb = require('@cloudbase/node-sdk'); const app = tcb.init({ env: '<YOUR_ENV_ID>' }); exports.main = async (event, context) => { const ai = app.ai(); }; 普通 Node.js 服务器初始化需传入 env、secretId、secretKey。
云函数超时配置 使用 AI 模型的云函数（尤其是 generateImage() 和大型文本生成）应设置更长超时。通过 MCP 工具 manageFunctions(action="createFunction") 创建时，在 func 对象内设置 func.timeout（单位秒，范围 1–900，默认 20 秒通常过短）。推荐值：文本生成 60–120 秒，流式 60–120 秒，图像生成 300–900 秒（推荐 900 秒），组合操作 900 秒。
可用模型组 "cloudbase" 是主托管组，Type 为 builtin，由腾讯云 TokenHub 支持，覆盖混元、DeepSeek、智谱 GLM、Kimi、MiniMax 等多个厂商，模型名单会演进，不应硬编码具体 SKU，应在运行时发现。默认不启用任何模型，必须先调用 DescribeAIModels 查看环境实际启用的模型；若目标模型缺失，调用 DescribeManagedAIModelList 获取权威目录与定价，再 UpdateAIModel 启用。"hunyuan-exp" 是保留兼容的旧版内置组，默认模型 hunyuan-2.0-instruct-20251111，其他混元 SKU 需运行时发现，新项目应优先使用 cloudbase。用户自定义 GroupName 通过 CreateAIModel 接入，必须以 custom- 开头。
自定义接入 当用户需要非托管文本模型（自托管、企业内部、第三方 OpenAI 兼容端点等）时，可引导其完成接入，包括控制台流程、完整 CreateAIModel 载荷及后续管理步骤，详见 custom-onboarding.md。自定义 GroupName 必须以 custom- 开头；自定义模型计费由第三方提供商承担，不消耗 Token Credits 资源包。
API 参考与最佳实践 完整的 generateText / streamText / generateImage 代码示例、错误处理模式、图像生成参数和 TypeScript 类型定义见 api-reference.md，该文件与 SKILL.md 是 @cloudbase/node-sdk AI 接口的权威参考，写代码前应先查阅方法签名；若方法或字段未记录，应停止并询问，或通过 MCP 工具检查实时契约，不要猜测。其他实践包括：启用新托管模型前向用户展示定价（ModelSpec 与 ModelChargingInfo）；图像生成单独规划超时与配额（HTTP 函数网关上限 60 秒，需用异步任务加轮询模式）；长文本交互优先使用流式（streamText + for await 增量返回，并在 catch 中处理中断）；服务端固定 @cloudbase/node-sdk >= 3.16.0。
限制 本技能仅适用于 Node.js 后端与 CloudBase 环境；浏览器/Web 应用、微信小程序、无 CloudBase SDK 的运行时均有对应替代技能。图像生成仅 Node SDK 支持。模型是否启用、支持哪些模型及定价均需通过 MCP 工具实时查询，不能凭记忆推断。