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 技能（该技能现已包含 ai_model OpenAPI 规范，可直接通过 HTTP 调用 AI 模型端点；切勿将此 SDK 封装在 HTTP 代理之后）

---

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

编写任何 createModel(...) 代码前，请先阅读此内容。Agent 经常会凭空编造此参数。合法形式恰好只有四种，其他形式都是错误。

✅ 合法的 ai.createModel(...) 参数	适用情况
"cloudbase"	服务端项目的主要托管组（由 TokenHub 支持的多供应商池）。供应商和具体模型应填写在 generateText / streamText 的 model 字段中，例如 { model: "deepseek-v4-flash" }。默认没有启用任何模型——务必先检查 DescribeAIModels；如果缺少目标模型，请先通过 UpdateAIModel 启用，再调用 SDK。
"hunyuan-v3"	**正在弃用的旧版方案组。**仅提供 hy3，平台不会为其新增模型。已使用此组的现有代码仍可继续运行——新代码应使用 cloudbase + { model: "hy3" }。
"hunyuan-exp"	仅当 DescribeAIModels 明确返回当前环境的这个旧版内置组时使用。其原始默认模型 hunyuan-2.0-instruct-20251111 已于 2026-05-31 下线——切勿使用该 ID。
"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: "hy3" }、{ 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、hy3）：检查 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: "腾讯云开发"（腾讯云 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-v3" — 旧版计划组（正在停用）

• 仅有 hy3；该组不会新增模型，并且正在逐步退出。迁移目标是 cloudbase + { model: "hy3" }
• 对现有代码仍然有效——不要将 createModel("hunyuan-v3")“修正”为 createModel("hy3")；hy3 是模型 ID，不是 GroupName
• 使用资源点计划时，如果调用来源允许，cloudbase 会优先结算免费额度，否则使用计划额度；hunyuan-v3 则只会使用免费额度

3. "hunyuan-exp" — 较早的旧版内置组（为兼容性保留）

• 仅当 DescribeAIModels 实际返回此组且 Status=1 时才使用。新项目应优先选择 cloudbase
• 其原始默认模型 hunyuan-2.0-instruct-20251111 已于 2026-05-31 下线——切勿指定该模型 ID。该组仍公开的模型必须从 DescribeAIModels({ GroupName: "hunyuan-exp" }).Models[] 获取

4. 用户自定义 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 s
• 流式生成（streamText）：60 – 120 s
• 图像生成（generateImage）：300 – 900 s（建议：900 s）
• 组合操作：900 s（允许的最大值）

在常规 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 获取权威的支持模型目录；如果缺少目标模型，则通过 UpdateAIModel 使用完整替换的 Models[] 和 Status: 1 启用它。如果缺少资源包，应返回购买链接 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-v3"（旧版套餐分组，仅限 hy3，即将退役）、"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，确认云函数／云托管运行时实际加载的版本 — 本地环境和生产环境可能存在偏差。
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）