ai-model-wechat

同级技能（仅本地）

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

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

何时使用此技能

使用此技能通过 wx.cloud.extend.AI 在微信小程序中调用 AI 模型。

需要以下操作时使用：

• 在小程序中集成 AI 文本生成
• 通过回调支持流式传输 AI 响应
• 从微信环境调用 Hunyuan 模型

以下情况不要使用：

• 浏览器/Web 应用 → 使用 ai-model-web 技能
• Node.js 后端或云函数 → 使用 ai-model-nodejs 技能
• 图像生成 → 使用 ai-model-nodejs 技能（小程序中不可用）
• 没有 CloudBase SDK 的运行时（原生应用、Python 等）→ 使用 http-api-cloudbase 技能（该技能现在包含 ai_model OpenAPI 规范，可用于直接进行 HTTP 调用）

---

⛔ 停止 — wx.cloud.extend.AI.createModel(provider) 参数不是供应商或模型名称

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

✅ 合法的 createModel(provider) 参数	使用时机
"hunyuan-exp"	当前环境已加入小程序成长计划（ai_miniprogram_inspire_plan）。默认模型：hunyuan-2.0-instruct-20251111。
"cloudbase"	默认回退选项。主托管分组（由 TokenHub 支持的多供应商池）。供应商和具体模型应填入 model 字段，例如 { model: "deepseek-v4-flash" }。
"custom-<your-name>"	通过 CreateAIModel 接入的用户自定义 GroupName。必须以 custom- 开头（例如 custom-kimi、custom-openai-compat）。

❌ 请勿写入以下内容——这些都不正确

wx.cloud.extend.AI.createModel("deepseek")                   // wrong — vendor, not GroupName
wx.cloud.extend.AI.createModel("deepseek-v4-flash")          // wrong — model id goes in `model`
wx.cloud.extend.AI.createModel("hunyuan")                    // wrong — vendor family
wx.cloud.extend.AI.createModel("hunyuan-2.0-instruct-20251111")  // wrong — model name
wx.cloud.extend.AI.createModel("glm") / "kimi" / "minimax"   // wrong — vendor names
wx.cloud.extend.AI.createModel("custom")                     // wrong — placeholder
wx.cloud.extend.AI.createModel(modelName)                    // wrong — do not reuse the model-id variable

✅ 正确模式——provider 和 model 是两个不同的字段

// Growth Plan branch
const model = wx.cloud.extend.AI.createModel("hunyuan-exp"); // ← provider / GroupName
await model.streamText({
  data: { model: "hunyuan-2.0-instruct-20251111", messages: [...] }  // ← concrete model id
});

// Token Credits branch
const model = wx.cloud.extend.AI.createModel("cloudbase");
await model.streamText({
  data: { model: "deepseek-v4-flash", messages: [...] }
});

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

1. 用户说“使用 DeepSeek v3.2”/“使用 hunyuan thinking”/“使用 Kimi k2.6”/……
2. 首先运行以下资格判定流程——正确的 provider 可能是 "hunyuan-exp"（如果环境已加入成长计划，且用户请求的是 hunyuan-* 模型），也可能是 "cloudbase"（托管目录中的其他模型）。
3. 将模型 ID 放入 data 中的 model 字段：{ model: "deepseek-v3.2" }、{ model: "hunyuan-2.0-instruct-20251111" }、{ model: "kimi-k2.6" }……
4. 使用模型 ID 之前，请确保它已包含在 DescribeAIModels({ GroupName: "cloudbase" }).Models[] 中。如果没有，请通过 UpdateAIModel 启用。

如果你正准备输入 wx.cloud.extend.AI.createModel(，且括号内的是供应商名称或模型 ID——请停止。它几乎肯定属于上述三种合法值之一。

---

强制执行的两步预检

不得直接开始调用 wx.cloud.extend.AI.createModel(...)。编写任何业务代码之前，请按固定顺序确认计费资格和分组就绪状态：① 资格 → ② 分组就绪状态。不要颠倒顺序。

预检 ① · 计费资格（两条并行计费路径）

小程序侧有两条计费路径：小程序成长计划（优先检查；若已加入，则使用 hunyuan-exp）和 Token Credits 资源包（通用回退路径；若可用，则使用 cloudbase 主托管组）。

1. 通过 MCP 工具 queryEnv action=info 获取 envId。

2. 根据用户意图选择分支：

用户意图	优先检查的资格	命中时 createModel 的 provider	模型选择	未命中时的指引
未指定模型／默认调用	先检查是否已加入 小程序成长计划；若未加入，则回退到 Token Credits 资源包	已加入："hunyuan-exp"；否则："cloudbase"	已加入：hunyuan-2.0-instruct-20251111（成长计划默认模型）。否则：与用户一起选择文本模型，然后通过 DescribeAIModels → DescribeManagedAIModelList → UpdateAIModel 在 "cloudbase" 组中验证／启用该模型	未加入计划 → 引导至 https://docs.cloudbase.net/ai/ai-inspire-plan；缺少资源包 → 提供购买链接
用户请求 hunyuan-* 模型	小程序成长计划资格	"hunyuan-exp"（计划专属 Token 资源包计费）	如果存在 hunyuan-2.0-instruct-20251111，则使用该模型；否则通过 DescribeAIModels({ GroupName: "hunyuan-exp" }).Models[] 验证，并通过 UpdateAIModel 启用	未加入 → 先加入计划，或切换到 "cloudbase" + 非 hunyuan 模型
用户请求 deepseek-*／glm-*／kimi-*／minimax-*／其他非 hunyuan 托管模型	Token Credits 资源包激活状态	"cloudbase"	不要假定模型已启用。执行 DescribeAIModels → 若未找到，通过 DescribeManagedAIModelList 获取规范的 Model 字符串 → 使用 Status: 1 调用 UpdateAIModel（完整替换 Models[]）	未激活资源包 → 提供购买链接
用户请求第三方／自托管（非托管）模型	跳过计费资格检查，转到“自定义接入”	自定义 GroupName（必须以 custom- 开头）	通过 CreateAIModel.Models[] 注册	提供控制台和 CreateAIModel 两种路径

3. 检查是否已加入小程序成长计划：

callCloudApi({
  service: "tcb",
  action: "DescribeActivityInfo",
  params: {
    ActivityNames: ["ai_miniprogram_inspire_plan"], // PascalCase preferred; switch to camelCase if InvalidParameter is returned
  },
})

**命中条件：**响应的 attendRecords 中至少有一条记录满足 activityName === "ai_miniprogram_inspire_plan"，且 envId 与当前环境匹配。命中后，默认使用 createModel("hunyuan-exp") + hunyuan-2.0-instruct-20251111；计费使用计划专属 Token 资源包 pkg_hunyuan_token_la_inspire_100m。

**未命中时：**不要静默回退。告知用户“当前环境未加入小程序成长计划”，提供加入入口 https://docs.cloudbase.net/ai/ai-inspire-plan，并询问用户是要加入后重试，还是切换到使用非 hunyuan 模型的 Token Credits 资源包路径。

4. 检查 Token Credits 资源包（当路径指向 "cloudbase" 主托管组时）：

callCloudApi({
  service: "tcb",
  action: "DescribeEnvPostpayPackage",
  params: {
    EnvId: "<current envId>",
  },
})

命中条件：envPostpayPackageInfoList 中有一条记录的 postpayPackageId 以 pkg_tcb_tokencredits_ 开头，status ∉ [3, 4]（未过期、未禁用），且 versionSwitchStatus 不处于阻止状态。

**未命中时：**提供购买链接（将 {envId} 替换为真实 ID — 不要保留占位符）：

https://buy.cloud.tencent.com/lowcode?buyType=resPack&envId={envId}&resourceType=token

预检 ② · 分组就绪状态（每次小程序 AI 调用都必须执行）

通过资格审核并不意味着可以调用目标模型。"cloudbase" 主托管组中默认不启用任何模型——你必须先调用 DescribeAIModels 查看启用情况；如果缺少目标模型，再调用 DescribeManagedAIModelList 获取权威的受支持模型目录，并通过 UpdateAIModel 设置 Status: 1 将其启用。"hunyuan-exp" 组的就绪状态取决于是否加入成长计划——仅加入成长计划即可使用 hunyuan-2.0-instruct-20251111，但其他 hunyuan SKU 仍须通过 DescribeAIModels({ GroupName: "hunyuan-exp" }).Models[] 检查；如果缺少，则通过 UpdateAIModel 启用。

1. 查询环境中当前配置的分组和开关（tcb Action DescribeAIModels，Version 2018-06-08）：

callCloudApi({
  service: "tcb",
  action: "DescribeAIModels",
  params: { EnvId: "<envId>" },
})

返回 AIModelGroups: AIModelGroup[]。每个 AIModelGroup 都包含 GroupName（例如 cloudbase / hunyuan-exp / 你的自定义分组）、Type（builtin / custom）、Models: [{ Model, EnableMCP, Tags }] 和 Status（1=开启 / 2=关闭）。分组就绪 = 以下三项全部满足：存在 GroupName + Status === 1 + 目标 Model 存在于 Models[] 中。

2. 如果 DescribeAIModels 的响应中没有目标模型，则通过 DescribeManagedAIModelList 查询平台目录和价格——该接口会返回包含 ModelSpec（上下文长度等）和 ModelChargingInfo（Uniform / Tiered 定价）的 ManagedAIModelGroup[]。选择目标模型，然后通过 UpdateAIModel 启用：

callCloudApi({
  service: "tcb",
  action: "UpdateAIModel",
  params: {
    EnvId: "<envId>",
    GroupName: "cloudbase",
    Status: 1, // 1=on, 2=off
    Models: [
      { Model: "deepseek-v4-flash", EnableMCP: false },
      { Model: "deepseek-v3.2", EnableMCP: false },   // append the new model to enable
    ],
    // ⚠️ `Models` is a FULL REPLACEMENT, not incremental; merge the old list + new entries before passing.
  },
})

3. 仅当以上两步均通过后，才能在小程序代码中编写 wx.cloud.extend.AI.createModel("<GroupName>")，并传入该分组 Models[] 中存在的 model 值。

顺序固定。 未通过资格审核时，不会为任何已启用的模型计费；分组未就绪时，即使通过资格审核，也会收到 ModelNotEnabled 类错误。必须在编写业务代码前完成两项操作。

API 大小写提示： tcb 公共服务 Action 正式使用 PascalCase（EnvId、GroupName、ActivityNames）；部分文档会使用 camelCase。首次调用时，如果遇到 InvalidParameter，请切换大小写形式后重试，然后将可用形式固定在项目的封装中。

---

可用的提供方和模型

wx.cloud.extend.AI.createModel(provider) 的 provider 参数等于 DescribeAIModels 返回的 GroupName。只允许使用三种类型的值。选择前请先执行决策树。

A. 小程序成长计划专属（加入后默认为此项）

createModel provider	默认模型	其他可用模型	说明
"hunyuan-exp"	hunyuan-2.0-instruct-20251111	其他 hunyuan SKU（例如 instruct / thinking / turbos / 角色变体）——运行时查询 DescribeAIModels({ GroupName: "hunyuan-exp" }).Models[]，切勿硬编码	旧版 Type=builtin GroupName；通过 pkg_hunyuan_token_la_inspire_100m 计费；未加入成长计划时切勿使用

B. 主要托管组（Token Credits 套餐场景，推荐默认选项）

"cloudbase" GroupName 由 Tencent Cloud TokenHub 支持，这是一个统一的托管模型池，涵盖多个第一方和第三方供应商，包括 Hunyuan 系列（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 等）、Zhipu GLM（GLM-5、GLM-5-Turbo、GLM-5.1、GLM-5V-Turbo）、Kimi（K2.5、K2.6）、MiniMax（M2.5、M2.7）等。模型列表会随时间变化，因此不要在应用代码中硬编码列表——始终在运行时发现可用模型。

createModel provider	模型就绪情况	如何启用模型	备注
"cloudbase"	默认不启用任何模型——始终先检查 DescribeAIModels({ GroupName: "cloudbase" }).Models[]	1）通过 DescribeManagedAIModelList 获取权威目录和定价（不要猜测 Model 字符串）。2）调用 UpdateAIModel，设置 Status: 1，并传入包含目标模型的完整替换版 Models[]	统一托管组（Type=builtin），备注为 "腾讯云开发"，依赖 pkg_tcb_tokencredits_* 资源包

⚠️ 常见的小程序错误：编写 createModel("deepseek") / createModel("hunyuan") / createModel("glm") / createModel("kimi") / createModel("minimax") / createModel("custom")。这些都不对——它们是供应商 / 模型名称，不是 provider / GroupName。provider 必须是 DescribeAIModels 返回的某个 GroupName 值。新项目始终使用统一的 "cloudbase" 托管组，并通过 model 字段选择具体的供应商模型。

C. 不在托管目录中 → 自定义接入

涉及第三方 / 可自托管 / 兼容 OpenAI 的端点（未出现在 A/B 中的任何模型）不走上述计费路径。你必须先通过“自定义接入”注册一个 Type=custom 的 GroupName。请参阅下一节。

---

自定义接入（不在托管目录中时）

当用户指定的模型既不在成长计划（hunyuan-exp）中，也不在主要托管组（cloudbase）目录中时（例如，企业自建的兼容 OpenAI 端点、第三方模型服务），请选择以下两种路径之一。使用“第三方 / 可自托管 / 兼容 OpenAI 的端点”等中性措辞——不要点名特定竞品品牌。

路径 1 · 在控制台注册

引导用户前往 CloudBase 控制台的 AI 模型页面：

https://tcb.cloud.tencent.com/dev?envId={envId}#/ai

将 {envId} 替换为真实的环境 ID，并让用户填写模型名称、端点、API 密钥等信息。

路径 2 · 通过 callCloudApi + CreateAIModel 注册

tcb Action CreateAIModel（版本 2018-06-08）会在当前环境中创建一个 Type=custom 的 AI 模型组：

callCloudApi({
  service: "tcb",
  action: "CreateAIModel",
  params: {
    EnvId: "<current envId>",
    GroupName: "custom-openai-compat",  // ⚠️ MUST start with "custom-" (e.g. custom-kimi, custom-moonshot) to avoid colliding with built-in / vendor GroupNames; this becomes the value passed to createModel(provider)
    BaseUrl: "https://api.example.com/v1",
    Models: [
      { Model: "gpt-4o-mini", EnableMCP: false },
      { Model: "gpt-4o",       EnableMCP: false },
    ],
    Remark: "Internal OpenAI-compatible endpoint",
    Status: 1,                         // 1=on, 2=off
    Secret: {
      // Key / ApiKey: pick one; OpenAI-compatible endpoints usually use ApiKey
      ApiKey: "<vendor-api-key>",
    },
  },
})

注册后：

• 运行 DescribeAIModels，确认 GroupName 已存在且 Status=1，目标 Model 也已出现在 Models[] 中。
• 在小程序中，调用 wx.cloud.extend.AI.createModel("custom-openai-compat")，并将已注册的模型名称（例如 "gpt-4o-mini"）作为 model 字段传入。
• 后续添加或修改模型时，使用 UpdateAIModel（请记住，Models 是完整替换；Status 使用 1/2 表示开/关）。要删除整个自定义组，请使用 DeleteAIModel（仅限自定义组；通过 GroupNames.N 批量操作）。
• 所有调用仍会走环境的计费路径。如果此类自定义模型也需要 Token 结算，必须先确认是否符合条件。

---

前提条件

• 微信基础库 3.7.1+
• 无需额外安装 SDK

---

初始化

// app.js
App({
  onLaunch: function() {
    wx.cloud.init({ env: "<YOUR_ENV_ID>" });
  }
})

---

generateText() - 非流式

⚠️ **与 JS/Node SDK 不同：**返回值是原始模型响应。

**前提条件：**已完成“Mandatory Two-Step Preflight”，并且已通过 DescribeAIModels 确认目标模型已启用（如果缺少，则通过 UpdateAIModel 启用）。以下示例假设当前环境已加入小程序成长计划，并使用 createModel("hunyuan-exp") + hunyuan-2.0-instruct-20251111。如果资格分支选择了资源包，请将提供方替换为 "cloudbase"，并将 model 设置为用户选择且刚通过 UpdateAIModel 启用的模型——切勿假设 deepseek-v4-flash 已经启用。

const model = wx.cloud.extend.AI.createModel("hunyuan-exp");

const res = await model.generateText({
  model: "hunyuan-2.0-instruct-20251111",  // plan-enrolled default
  messages: [{ role: "user", content: "hi" }],
});

// ⚠️ Return value is the RAW model response, NOT wrapped like JS/Node SDK
console.log(res.choices[0].message.content);  // access via choices array
console.log(res.usage);                        // token usage

---

streamText() - 流式

⚠️ **与 JS/Node SDK 不同：**参数必须包装在 data 对象中；支持回调。

**前提条件：**已完成“Mandatory Two-Step Preflight”，并且已启用目标模型。以下示例使用成长计划分支；对于资源包分支，请将 createModel("hunyuan-exp") 替换为 createModel("cloudbase")，并将 model 设置为用户选择且刚通过 UpdateAIModel 启用的模型（默认没有启用任何模型）。

const model = wx.cloud.extend.AI.createModel("hunyuan-exp");

// ⚠️ Parameters MUST be wrapped in a `data` object
const res = await model.streamText({
  data: {                              // ⚠️ Required wrapper
    model: "hunyuan-2.0-instruct-20251111",  // plan-enrolled default
    messages: [{ role: "user", content: "hi" }]
  },
  onText: (text) => {                  // Optional: incremental text callback
    console.log("New text:", text);
  },
  onEvent: ({ data }) => {             // Optional: raw event callback
    console.log("Event:", data);
  },
  onFinish: (fullText) => {            // Optional: completion callback
    console.log("Done:", fullText);
  }
});

// Async iteration is also available
for await (let str of res.textStream) {
  console.log(str);
}

// Check for completion via eventStream
for await (let event of res.eventStream) {
  console.log(event);
  if (event.data === "[DONE]") {       // ⚠️ Check for [DONE] to stop
    break;
  }
}

---

错误处理模式

**前提条件：**已完成“Mandatory Two-Step Preflight”。对于资源包分支，请使用 "cloudbase" + 刚通过 DescribeAIModels / UpdateAIModel 确认或启用的具体文本模型——默认没有启用任何模型。

const model = wx.cloud.extend.AI.createModel("cloudbase");

try {
  const res = await model.generateText({
    model: "deepseek-v4-flash",
    messages: [{ role: "user", content: "Write a welcome message" }],
  });

  console.log(res.choices[0].message.content);
} catch (error) {
  console.error("Mini Program AI request failed", error);
}

---

API 对比：JS/Node SDK 与微信小程序

特性	JS/Node SDK	微信小程序
命名空间	app.ai()	wx.cloud.extend.AI
generateText 参数	直接对象	直接对象
generateText 返回值	{ text, usage, messages }	原始：{ choices, usage }
streamText 参数	直接对象	⚠️ 包装在 data: {...} 中
streamText 返回值	{ textStream, dataStream }	{ textStream, eventStream }
回调	不支持	onText、onEvent、onFinish
图像生成	仅 Node SDK	不支持

---

类型定义

streamText() 输入

interface WxStreamTextInput {
  data: {                              // ⚠️ Required wrapper object
    model: string;
    messages: Array<{
      role: "user" | "system" | "assistant";
      content: string;
    }>;
  };
  onText?: (text: string) => void;     // incremental text callback
  onEvent?: (prop: { data: string }) => void;  // raw event callback
  onFinish?: (text: string) => void;   // completion callback
}

streamText() 返回值

interface WxStreamTextResult {
  textStream: AsyncIterable<string>;   // incremental text stream
  eventStream: AsyncIterable<{         // raw event stream
    event?: unknown;
    id?: unknown;
    data: string;                      // "[DONE]" when complete
  }>;
}

generateText() 返回值

// Raw model response (OpenAI-compatible format)
interface WxGenerateTextResponse {
  id: string;
  object: "chat.completion";
  created: number;
  model: string;
  choices: Array<{
    index: number;
    message: {
      role: "assistant";
      content: string;
    };
    finish_reason: string;
  }>;
  usage: {
    prompt_tokens: number;
    completion_tokens: number;
    total_tokens: number;
  };
}

---

最佳实践

1. 编写业务代码前，先完成两步预检。 固定顺序：① 调用 DescribeActivityInfo / DescribeEnvPostpayPackage 检查计费资格 → ② 调用 DescribeAIModels 检查分组是否就绪（如有需要，调用 DescribeManagedAIModelList 获取模型目录和定价，然后调用 UpdateAIModel 启用目标模型）。只有两项检查均通过后，才能编写 wx.cloud.extend.AI.createModel(...)。
2. createModel(provider) 只接受三类值——"hunyuan-exp"（成长计划专属的旧版分组）、"cloudbase"（主要托管分组，新项目的默认选项），或用于自定义接入的 GroupName（必须以 custom- 开头，例如 custom-kimi、custom-openai-compat，避免与内置名称或厂商名称冲突）。切勿编写 createModel("deepseek")（除非 DescribeAIModels 确实返回了名为 deepseek 的旧版内置分组）、createModel("hunyuan")、createModel("kimi") 或 createModel("custom")——这些是模型／厂商名称或占位符，不是 GroupName。
3. model 字段必须来自 DescribeAIModels。 传入所选分组的 Models[].Model 列表中实际存在的值。主要托管分组默认只启用了 deepseek-v4-flash；如需使用其他模型，先调用 UpdateAIModel。
4. 混元模型严格绑定成长计划。 要使用 hunyuan-* 模型，必须已加入成长计划。若尚未加入，请引导用户访问 https://docs.cloudbase.net/ai/ai-inspire-plan，或切换为 "cloudbase" + deepseek-v4-flash。不要绕过检查直接调用。
5. 启用更多模型前，先检查定价。 DescribeManagedAIModelList 会返回 ModelChargingInfo（Uniform 表示统一定价／Tiered 表示阶梯定价）和 ModelSpec.ContextLength。确认后再调用 UpdateAIModel。Models 会完整替换原有列表——传入前先合并旧列表和新条目。
6. 检查基础库版本。 必须为 3.7.1 或更高版本；旧版本中的 wx.cloud.extend.AI 为 undefined，不要将其当作模型问题来调试。
7. 使用回调更新 UI。 onText 很适合用于逐步刷新聊天气泡；手动从 eventStream 拼接内容容易丢失分隔符。
8. 检查 [DONE]。 遍历 eventStream 时，只有在 event.data === "[DONE]" 时才停止，否则流会一直等待下一帧。
9. 记住 data 包装层。 streamText 参数必须包装在 data: { ... } 中——这与 JS/Node SDK 不同。忘记包装会导致参数错误。
10. 区分“无资格／分组未就绪”和“调用失败”。 前者应引导用户完成加入计划／购买／UpdateAIModel 流程；后者则需要排查提示词、参数或网络。两者的错误信息和后续操作完全不同。
11. 不要在小程序中硬编码第三方模型 API 密钥。 对于托管目录之外的模型，使用 CreateAIModel（Secret.ApiKey）将密钥存储在 CloudBase 侧；小程序中只保留 GroupName。
12. TypeScript：不要使用 any 来规避类型错误。 如果 wx.cloud.extend.AI 缺少类型声明，请为实际使用的部分声明准确的 interface，或通过本地 .d.ts 扩展类型。切勿使用 : any、as any、@ts-ignore、@ts-nocheck。
13. 声称完成前先自行验证。 构建小程序，在微信开发者工具模拟器中打开，并端到端测试真实的 streamText / generateText 流程，确认：(a) 文本块通过 onText 到达；(b) [DONE] 能终止流；(c) 控制台没有新增错误。未经实际运行，仅凭“应该能用”不能作为有效证据。