ai-model-nodejs

同级技能（仅限本地）

同级 CloudBase 技能与此技能一同提供。请使用 ../auth-tool-cloudbase/SKILL.md 这样的本地相对路径。

如果当前环境中缺少所引用的同级技能文件，请让用户安装完整的 CloudBase 插件（或缺少的技能）。不要通过 HTTP 获取远程技能或协议 Markdown 并加载到 Agent 上下文中。

何时使用此技能

通过 @cloudbase/node-sdk 从 Node.js 后端、云函数或 CloudRun 服务调用 AI 模型时，请使用此技能。

🧭 运行时平面匹配。 当 AI 调用确实应在服务器端执行时，应使用此技能：例如图像生成（唯一支持此功能的 SDK）、长时间运行的 Agent 任务、跨多个工具的编排、定时任务，或必须将密钥保留在服务器端的流程。如果用户正在构建网页／前端 AI 聊天界面，请勿通过后端代理封装此 SDK——应转到 ai-model-web，并直接在浏览器中调用模型。微信小程序请使用 ai-model-wechat。首先根据运行时平面决定路由；具体模型（deepseek-*、glm-*、hunyuan-*、kimi-* 等）只影响 model 字段。

在以下情况下使用此技能：

• 将 AI 文本生成集成到后端服务
• 使用 Hunyuan Image 模型生成图像
• 从 CloudBase 云函数或 CloudRun 调用 AI 模型
• 执行服务器端 AI 处理（Agent 编排、批处理任务、定时任务）

请勿用于：

• 浏览器／Web 应用 → 使用 ai-model-web 技能
• 微信小程序 → 使用 ai-model-wechat 技能
• 不支持 CloudBase SDK 的运行时（Python、Go、PHP、curl 等）→ 使用 http-api-cloudbase 技能（该技能现已包含用于直接 HTTP 调用 AI 模型端点的 ai_model OpenAPI 规范；请勿通过 HTTP 代理封装此 SDK）

---

⛔ 停止——ai.createModel(...) 参数不是供应商／模型名称

编写任何 createModel(...) 行之前，请先阅读此内容。Agent 经常会臆造此参数。合法形式恰好有三种。其他任何形式都是错误。

✅ 合法的 ai.createModel(...) 参数	使用场景
"cloudbase"	服务器端项目的主要托管组（由 TokenHub 提供支持的多供应商池）。供应商和具体模型应填写在 generateText／streamText 的 model 字段中，例如 { model: "deepseek-v4-flash" }。默认情况下不会启用任何模型——请务必先检查 DescribeAIModels，若缺少目标模型，则在调用 SDK 之前使用 UpdateAIModel 启用它。
"hunyuan-exp"	仅当 DescribeAIModels 明确返回当前环境的此旧版内置组时使用。
"custom-<your-name>"	通过 CreateAIModel 接入的用户自定义 GroupName。必须以 custom- 开头（例如 custom-kimi、custom-openai-compat）。

图像生成使用单独的入口：ai.createImageModel("hunyuan-image")。请勿将其与 createModel(...) 混用。

❌ 错误的参数形式

任何不属于上述三种合法值的形式：供应商名称（"deepseek"、"glm"、"kimi"、"openai"、"moonshot" 等）、具体模型 ID（"deepseek-v4-flash"、"hunyuan-2.0-instruct-20251111"）、单独的占位符 "custom"，或保存模型 ID 的变量。这些都是 createModel(...) 中的错误参数。

✅ 正确模式——GroupName 和 Model 是两个不同的字段

const model = ai.createModel("cloudbase");          // ← GroupName
await model.generateText({
  model: "deepseek-v4-flash",                       // ← concrete model id
  messages: [...]
});

决策流程（用户指定特定模型时）

1. 用户说“使用 DeepSeek v3.2”／“使用 hunyuan instruct”／“使用 Kimi k2.6”／“使用 GLM-5”／……
2. createModel("cloudbase") 保持不变。
3. 将模型 ID 填入 model 字段：{ model: "deepseek-v3.2" }、{ model: "hunyuan-2.0-instruct-20251111" }、{ model: "kimi-k2.6" }、{ model: "glm-5" }、……
4. 切勿假设模型已启用。 调用 SDK 前，先确认它存在于 DescribeAIModels({ GroupName: "cloudbase" }).Models[] 中。如果不存在，调用 DescribeManagedAIModelList 确认平台支持的确切 Model 名称（区分大小写——切勿猜测拼写），然后通过 UpdateAIModel 启用它，并设置 Status: 1（请记住，Models 会被整体替换）。

如果你正准备输入 ai.createModel(，而括号内的是供应商名称、模型名称或猜测值——请停下。它几乎肯定不属于上述三个合法值。

---

强制两步预检（编写任何 SDK 代码之前）

在服务器上调用任何 AI API 之前，先执行两步预检：①资格检查，②分组就绪检查。文本生成和图像生成使用同一份 Token Credits 资源包，两者在生成代码前都必须完成预检。

步骤 0：获取环境 ID

调用 MCP 工具 queryEnv，设置 action=info，并从响应中读取 EnvId。

---

预检 ① — 资格检查（Token Credits 资源包）

调用 MCP 工具：

callCloudApi(service="tcb", action="DescribeEnvPostpayPackage", params={ EnvId })

通过条件（必须全部满足）：

• envPostpayPackageInfoList 至少包含一个条目

• 该条目的 postpayPackageId 以 pkg_tcb_tokencredits_ 开头

• 该条目的 status 不在 [3, 4] 中（3 / 4 通常表示已过期／已停用；以实时响应为准）

• ❌ 未满足 → 停止编写代码，并向用户显示以下内容（将 {envId} 替换为实际 ID）：

  当前环境没有有效的 Token Credits 资源包。请先购买资源包，再调用任何 AI API： https://buy.cloud.tencent.com/lowcode?buyType=resPack&envId={envId}&resourceType=token

  完成后请告知我，我会重新检查资源包状态。

• ✅ 已满足 → 继续预检 ②。

按照约定，参数使用 PascalCase。如果调用返回 InvalidParameter，则回退为 camelCase（envId），并以实时响应为准。

---

预检 ② — 分组就绪状态（DescribeAIModels → 如有需要则调用 UpdateAIModel）

仅符合资格还不够。**此时还不要写 createModel("cloudbase")。**请先确认目标 GroupName 在当前环境中存在且 Status=1，并且目标 Model 包含在其 Models[] 中。

1. 列出当前环境中配置的分组：

   callCloudApi(service="tcb", action="DescribeAIModels", params={ EnvId })
   

   返回包含 GroupName、Type（builtin / custom）、Models: [{ Model, EnableMCP, Tags }]、Status（1 / 2）、BaseUrl、Secret、Remark 的 AIModelGroups: AIModelGroup[]。主要托管分组的 GroupName 为 cloudbase。

2. **绝不要假设某个模型已启用。**检查目标分组的 AIModelGroups[?].Models[].Model。如果你计划使用的文本模型（例如 deepseek-v4-flash，或用户指定的其他模型）不在 cloudbase 分组的 Models[] 中，请跳到第 4 步并启用它——此时不要调用 createModel("cloudbase")。图像生成使用 createImageModel("hunyuan-image") + model: "hunyuan-image"；调用前也要确认该模型已启用。

3. 用户指定了托管目录中的模型（例如 deepseek-v3.2、hunyuan-2.0-instruct-20251111）：检查 cloudbase 分组的 Models[] 中是否已有该 Model。如果没有，请跳到第 4 步。不要猜测准确的模型 ID——先在 DescribeManagedAIModelList 中确认规范拼写。

4. 启用／添加托管模型（务必先检查权威目录和定价）：

   callCloudApi(service="tcb", action="DescribeManagedAIModelList", params={ EnvId })
   

   返回包含 GroupName、Remark 和 Models: [{ Model, EnableMCP, ModelSpec, ModelChargingInfo }] 的 ManagedAIModelGroup[]。这是受支持模型名称和定价的唯一可信来源——不要凭记忆推断。调用 UpdateAIModel 时，请使用这里的确切 Model 字符串。ModelChargingInfo 包含输入／输出价格和计费单位。启用前，请向用户说明价格。

   然后启用（注意：Models 会完整替换现有列表——务必将已启用的模型与新模型一起重新传入）：

   callCloudApi(service="tcb", action="UpdateAIModel", params={
     EnvId,
     GroupName: "cloudbase",
     Models: [
       // resend every model that DescribeAIModels already showed as enabled
       { Model: "<already-enabled model>" },
       // append the newly-requested one, using the exact spelling from DescribeManagedAIModelList
       { Model: "<target model>" }
     ],
     Status: 1
   })
   

5. 请求的模型不在托管目录中（通过 DescribeManagedAIModelList 未找到）→ 跳到下一节，自定义接入（托管目录之外的模型）。

所有 Action 均使用 service=tcb、Version=2018-06-08。参数采用 PascalCase；仅在遇到 InvalidParameter 时才改用 camelCase。

---

可用的提供商和模型

ai.createModel(<GroupName>) 只接受三种合法值；ai.createImageModel("hunyuan-image") 是专用的图像生成入口。

1. "cloudbase" — 主要托管分组（推荐）

• GroupName: "cloudbase"，Type: "builtin"，Remark: "腾讯云开发"（Tencent CloudBase）
• 由腾讯云 TokenHub 提供支持，这是一个统一的托管资源池，涵盖多个厂商的模型——混元（HY 2.0 Instruct、HY 2.0 Think、Hunyuan-role、Hy3 preview，…）、DeepSeek（DeepSeek-V4-Pro、DeepSeek-V4-Flash、Deepseek-v3.2、Deepseek-v3.1、Deepseek-r1-0528、Deepseek-v3-0324，…）、智谱 GLM（GLM-5、GLM-5-Turbo、GLM-5.1、GLM-5V-Turbo）、Kimi（K2.5、K2.6）、MiniMax（M2.5、M2.7）等。模型列表会持续更新——不要硬编码特定 SKU；请在运行时发现可用模型。
• **默认情况下没有启用任何模型。**务必先调用 DescribeAIModels，查看当前环境实际启用的模型；如果缺少目标模型，请调用 DescribeManagedAIModelList 获取权威目录和定价，然后调用 UpdateAIModel（Status: 1，Models 完整替换）启用模型，再调用 SDK。
• 权威目录和定价：DescribeManagedAIModelList
• 环境中已启用的模型集合：DescribeAIModels

2. "hunyuan-exp" — 为兼容性保留的旧版内置组

• 默认模型：hunyuan-2.0-instruct-20251111；其他 hunyuan SKU 必须在运行时通过 DescribeAIModels({ GroupName: "hunyuan-exp" }).Models[] 查询发现——不要对其他 ID 进行硬编码
• 仅当 DescribeAIModels 确实返回此组且 Status=1 时才直接使用。新项目应优先选择 cloudbase

3. 用户自定义 GroupName

• 通过 CreateAIModel 接入（见下一节）。自定义 GroupName 必须以 custom- 开头（例如 custom-kimi、custom-moonshot、custom-openai-compat）。此命名约定可避免与平台未来可能引入的内置 / 厂商 GroupName（如 cloudbase、hunyuan-exp、deepseek、glm、kimi、minimax）发生冲突
• 示例：createModel("custom-kimi")、createModel("custom-openai-compat")

图像生成（独立 API）

• ai.createImageModel("hunyuan-image") + model: "hunyuan-image"。仅 Node SDK 支持

绝不要使用诸如 createModel("deepseek") 或 createModel("custom") 这样的猜测值，除非 DescribeAIModels 明确返回了完全相同的 GroupName。

---

自定义接入（托管目录之外的模型）

当用户需要使用非托管文本模型（自托管、企业内部、第三方 OpenAI 兼容端点等）时，不要阻止。引导用户完成接入——包括控制台流程、完整的 CreateAIModel 负载和后续管理步骤：custom-onboarding.md。自定义 GroupName 必须以 custom- 开头；自定义模型的费用由第三方提供商承担，不会从 Token Credits 资源包中扣除。

---

安装

npm install @cloudbase/node-sdk

⚠️ AI 功能要求版本不低于 3.16.0。 使用 npm list @cloudbase/node-sdk 检查。

---

初始化

在 CloudBase 云函数中

const tcb = require('@cloudbase/node-sdk');
const app = tcb.init({ env: '<YOUR_ENV_ID>' });

exports.main = async (event, context) => {
  const ai = app.ai();
  // Use AI features
};

AI 模型的云函数配置

⚠️ 重要： 创建使用 AI 模型的云函数时（尤其是调用 generateImage() 和生成长文本时），请设置较长的超时时间——这些操作可能耗时较长。

使用 MCP 工具 manageFunctions(action="createFunction")：

兼容旧版：如果旧版提示词仍写着 createFunction，请保留相同的负载结构，但通过 manageFunctions(action="createFunction") 执行。

在 func 对象中设置 timeout：

• 参数：func.timeout（数字）
• 单位：秒
• 范围：1 – 900
• 默认值：20 秒（通常不足以完成 AI 操作）

建议的超时时间：

• 文本生成（generateText）：60 – 120 秒
• 流式生成（streamText）：60 – 120 秒
• 图像生成（generateImage）：300 – 900 秒（建议：900 秒）
• 组合操作：900 秒（允许的最大值）

在常规 Node.js 服务中

const tcb = require('@cloudbase/node-sdk');
const app = tcb.init({
  env: '<YOUR_ENV_ID>',
  secretId: '<YOUR_SECRET_ID>',
  secretKey: '<YOUR_SECRET_KEY>'
});

const ai = app.ai();

---

SDK API 参考（按需查阅）

如需查看完整的 generateText / streamText / generateImage 代码示例、错误处理模式、图像生成参数以及完整的 TypeScript 类型定义，请阅读 api-reference.md。该文件与本 SKILL.md 一起，构成 @cloudbase/node-sdk 的 AI 功能权威参考——编写代码前，请先在其中查阅方法签名。如果其中未记录某个方法或字段，请停止并询问，或通过 MCP 工具检查实时接口约定。不要猜测。

---

最佳实践

1. 编写业务代码前，先执行两步预检 — ① 资格检查：调用 queryEnv → callCloudApi(tcb, DescribeEnvPostpayPackage)，确认已购买 Token Credits 资源包（文本和图像共用同一资源包）；② 分组就绪检查：对 cloudbase 分组调用 DescribeAIModels 并检查其 Models[]，调用 DescribeManagedAIModelList 获取权威的支持模型目录；如果目标模型缺失，则使用完整替换的 Models[] 和 Status: 1 调用 UpdateAIModel。如果未购买资源包，应返回购买链接 https://buy.cloud.tencent.com/lowcode?buyType=resPack&envId={envId}&resourceType=token，而不是输出 SDK 代码让用户调试运行时错误。
2. 绝不要假定任何模型已启用 — 无论是 deepseek-v4-flash、hunyuan-image，还是其他模型。务必先调用 DescribeAIModels 验证；如果目标模型缺失，则通过 DescribeManagedAIModelList 查找准确的 Model 字符串（不要猜测拼写），然后调用 UpdateAIModel 启用它。
3. createModel 只接受三种值 — "cloudbase"（主托管分组）、"hunyuan-exp"（旧版内置分组），或通过 CreateAIModel 注册的自定义 GroupName（必须以 custom- 开头，例如 custom-kimi、custom-openai-compat）。绝不要猜着写 createModel("deepseek") / createModel("kimi") / createModel("custom")——前两个是厂商或模型名称，最后一个只是占位符。createImageModel("hunyuan-image") 是独立的图像 API——保持原样。
4. 不要臆造 SDK 方法名或参数。 本技能（SKILL.md + references/api-reference.md）是 @cloudbase/node-sdk AI 接口的权威参考——编写代码前，先在其中查阅方法签名。如果其中未记载某个方法或字段，请停止并询问，或通过 MCP 工具检查实时接口定义。不要猜测。
5. 启用新的托管模型前，先展示价格 — DescribeManagedAIModelList 会返回 ModelSpec（上下文长度、最大输入/输出 Token 数）和 ModelChargingInfo（输入 / 输出 / 缓存价格、计费单位）。调用 UpdateAIModel 前，先向用户展示价格。
6. 针对图像生成，分别规划超时和配额 — generateImage 的单次调用成本高于文本生成，耗时也更长。对于云函数，将 timeout 设为 900s。HTTP 函数网关的超时上限为 60s，因此应采用异步任务 + 轮询模式。限制每位用户的并发数和调用频率，避免一次失败就耗尽整个 Token 资源包。
7. 长交互优先使用流式响应 — 在 HTTP 函数或云函数的 SSE 场景中，使用 streamText + for await (const chunk of result.textStream) 将数据块逐步发送回客户端。在 catch 中处理流中断，并关闭底层响应。
8. 服务器端固定使用 @cloudbase/node-sdk >= 3.16.0 — 图像生成仅从此版本开始支持。使用 npm ls @cloudbase/node-sdk 验证云函数 / Cloud Run 运行时实际加载的版本——本地与生产环境的版本可能不一致。
9. 在配置中集中管理模型名称，不要散落为字面值。 将选用的文本 / 图像模型保存在单个常量中，并从 DescribeAIModels / DescribeManagedAIModelList 获取模型信息。托管模型目录会持续更新；使用单一事实来源可以降低升级成本。对于不在托管目录中的模型，请遵循 Custom Onboarding 部分——绝不要在业务代码中硬编码第三方 API 密钥（应由 CloudBase 通过 CreateAIModel.Secret.ApiKey 管理）。
10. 区分“预检失败”和“模型调用失败” — 前者表示资源包未激活，或目标模型尚未通过 UpdateAIModel 启用（应引导用户购买 / 启用）；后者则是参数问题或上游错误。不要用同一个通用提示框处理两者。
11. 生产环境不要记录完整提示词或生成的文本 — 只记录 usage.total_tokens 和一小段前缀。提示词可能泄露敏感内容；Token 数量可能泄露成本信息。
12. TypeScript：不要使用 any 来绕过 SDK 类型错误。 Node SDK 自带类型；请使用 unknown + 类型守卫缩小类型，针对所使用的数据结构编写精确的 interface，或在本地 .d.ts 中扩展类型。绝不要使用 : any、as any、@ts-ignore、@ts-nocheck。请参阅 web-development 技能中的 Engineering constitution——其中的要求同样适用于后端 TypeScript。
13. 声称完成前，先自行验证。 运行 tsc --noEmit 和项目构建，并实际调用函数（本地调用 / manageFunctions(action="invokeFunction") / 直接发送 HTTP 请求），确认 usage.total_tokens > 0 且返回文本不是错误封装。“应该能用”但没有真实往返验证，不算有效证据。

参考索引

所有打包的参考文件（技能 lint 可达性检查所需）：

• api-reference.md — generateText / streamText / generateImage 示例、错误处理模式、图像参数、TypeScript 类型定义
• custom-onboarding.md — 管理目录之外的模型接入流程（控制台流程 + CreateAIModel）