微信小程序中调用 AI 模型（wx.cloud.extend…

在微信小程序里用 wx.cloud.extend.AI 调文本大模型时，先做计费资格与模型组就绪两步预检，再写 createModel/streamText 业务代码。

适用场景

解决思路

1. 写任何业务代码前，先按固定顺序完成两步预检：① 计费资格（billing eligibility）→ ② 模型组就绪（group readiness），顺序不可颠倒。
2. 预检①-1：用 MCP 工具 queryEnv action=info 获取 envId。
3. 预检①-2：按用户意图选分支——未指定模型/默认调用时先查小程序成长计划是否报名，未报名再回退到 Token Credits 资源包；用户指定 hunyuan-* 模型时查小程序成长计划；用户指定 deepseek-*/glm-*/kimi-*/minimax-* 等非 hunyuan 托管模型时走 Token Credits 资源包；用户指定第三方/自托管（非托管）模型时跳过计费资格，直接走自定义接入。
4. 预检①-3：调用 callCloudApi({ service: "tcb", action: "DescribeActivityInfo", params: { ActivityNames: ["ai_miniprogram_inspire_plan"] } }) 检查成长计划报名；命中标准是 attendRecords 中存在 activityName === "ai_miniprogram_inspire_plan" 且 envId 匹配当前环境；命中则默认 createModel("hunyuan-exp") + hunyuan-2.0-instruct-20251111，计费走 pkg_hunyuan_token_la_inspire_100m；未命中不要静默回退，要告知用户未报名并给出报名入口 https://docs.cloudbase.net/ai/ai-inspire-plan，询问是报名重试还是改用 Token Credits 资源包 + 非 hunyuan 模型。
5. 预检①-4：当路径指向 cloudbase 主托管组时，调用 callCloudApi({ service: "tcb", action: "DescribeEnvPostpayPackage", params: { EnvId: "<current envId>" } }) 检查 Token Credits 资源包；命中标准是 envPostpayPackageInfoList 中存在 postpayPackageId 以 pkg_tcb_tokencredits_ 开头、status ∉ [3,4]（未过期未停用）、且 versionSwitchStatus 非阻塞状态的条目；未命中则给出购买链接 https://buy.cloud.tencent.com/lowcode?buyType=resPack&envId={envId}&resourceType=token（把 {envId} 替换为真实 ID，不要留占位符）。
6. 预检②-1：调用 callCloudApi({ service: "tcb", action: "DescribeAIModels", params: { EnvId: "<envId>" } }) 查询环境已配置的模型组与开关；返回 AIModelGroups，每组含 GroupName、Type（builtin/custom）、Models: [{ Model, EnableMCP, Tags }]、Status（1=on/2=off）；组就绪 = GroupName 存在 + Status === 1 + 目标 Model 在 Models[] 中。
7. 预检②-2：若目标模型不在 DescribeAIModels 结果中，调用 DescribeManagedAIModelList 查询平台目录与价格（含 ModelSpec 上下文长度、ModelChargingInfo 的 Uniform/Tiered 计费），选定目标模型后用 UpdateAIModel 启用：callCloudApi({ service: "tcb", action: "UpdateAIModel", params: { EnvId, GroupName: "cloudbase", Status: 1, Models: [ { Model: "deepseek-v4-flash", EnableMCP: false }, { Model: "deepseek-v3.2", EnableMCP: false } ] } })；注意 Models 是全量替换而非增量，必须把旧列表与新条目合并后再传。
8. 预检②-3：两步都通过后，才在小程序代码里写 wx.cloud.extend.AI.createModel("<GroupName>")，并传入该组 Models[] 中确实存在的 model 值。
9. createModel(provider) 只接受三种合法取值："hunyuan-exp"（成长计划专属，默认模型 hunyuan-2.0-instruct-20251111，其他 hunyuan SKU 需运行时用 DescribeAIModels({ GroupName: "hunyuan-exp" }).Models[] 查询，不要硬编码）、"cloudbase"（主托管组，新项目默认，厂商与具体模型放在 data 的 model 字段）、"custom-<your-name>"（自定义 GroupName，必须以 custom- 开头，如 custom-kimi、custom-openai-compat）。
10. 绝对不要写 createModel("deepseek")、createModel("deepseek-v4-flash")、createModel("hunyuan")、createModel("hunyuan-2.0-instruct-20251111")、createModel("glm")、createModel("kimi")、createModel("minimax")、createModel("custom")、createModel(modelName) —— 这些是厂商名、模型名或占位符，不是 GroupName。
11. 当用户点名具体模型时：先跑资格决策树确定 provider（hunyuan-* 且环境在成长计划则用 "hunyuan-exp"，否则用 "cloudbase"），再把模型 id 放进 data 的 model 字段，如 { model: "deepseek-v3.2" }、{ model: "hunyuan-2.0-instruct-20251111" }、{ model: "kimi-k2.6" }；使用前确认该 id 存在于 DescribeAIModels({ GroupName: "cloudbase" }).Models[]，不存在则用 UpdateAIModel 启用。
12. 自定义接入（不在托管目录中的第三方/自托管/OpenAI 兼容端点）走两条路径之一：路径1 在控制台 https://tcb.cloud.tencent.com/dev?envId={envId}#/ai 注册；路径2 用 callCloudApi + CreateAIModel 注册，参数含 EnvId、GroupName（必须以 custom- 开头）、BaseUrl、Models[]、Remark、Status: 1、Secret（Key 或 ApiKey 二选一，OpenAI 兼容端点通常用 ApiKey）。
13. 自定义接入注册后用 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 批量）。
14. 初始化：在 app.js 的 onLaunch 中调用 wx.cloud.init({ env: "<YOUR_ENV_ID>" })；前置要求是微信基础库 3.7.1+，无需额外安装 SDK。
15. generateText 非流式调用：const model = wx.cloud.extend.AI.createModel("hunyuan-exp"); const res = await model.generateText({ model: "hunyuan-2.0-instruct-20251111", messages: [{ role: "user", content: "hi" }] }); 返回值是原始模型响应（非 JS/Node SDK 的包装格式），用 res.choices[0].message.content 取内容、res.usage 取 token 用量。
16. streamText 流式调用：参数必须包在 data 对象里——const res = await model.streamText({ data: { model: "hunyuan-2.0-instruct-20251111", messages: [{ role: "user", content: "hi" }] }, onText: (text) => {...}, onEvent: ({ data }) => {...}, onFinish: (fullText) => {...} }); 也可用 for await (let str of res.textStream) 异步迭代。
17. 遍历 eventStream 时只在 event.data === "[DONE]" 时 break，否则流会一直等待下一帧。
18. 错误处理：用 try/catch 包住 generateText/streamText 调用，catch 中打印 "Mini Program AI request failed" 与 error；注意区分「未报名/组未就绪」与「调用失败」——前者引导用户报名/购买/UpdateAIModel，后者才是排查提示词、参数或网络。
19. API 差异对照：JS/Node SDK 用 app.ai()，小程序用 wx.cloud.extend.AI；generateText 参数都是直接对象，但小程序返回值是原始 { choices, usage }；streamText 小程序必须包 data: {...}，返回 { textStream, eventStream }；小程序支持 onText/onEvent/onFinish 回调；图片生成仅 Node SDK 支持，小程序不可用。
20. 最佳实践：UI 更新用 onText 回调逐步刷新聊天气泡，不要手动从 eventStream 拼接（容易丢分隔符）；启用更多模型前先用 DescribeManagedAIModelList 查看 ModelChargingInfo 与 ModelSpec.ContextLength 确认价格；检查基础库版本 3.7.1+，低版本 wx.cloud.extend.AI 为 undefined，不要当成模型问题排查。
21. 不要把第三方模型 API Key 硬编码在小程序里；托管目录之外的模型用 CreateAIModel 的 Secret.ApiKey 把密钥存在 CloudBase 侧，小程序只保留 GroupName。
22. TypeScript 下不要用 any 消音：若 wx.cloud.extend.AI 缺类型，为实际用到的切片声明精确 interface，或用本地 .d.ts 增强；禁止 : any、as any、@ts-ignore、@ts-nocheck。
23. 声称完成前先自验：构建小程序，在微信开发者工具模拟器中端到端跑通真实的 streamText/generateText 流程，确认 (a) 文本分片通过 onText 到达、(b) [DONE] 终止流、(c) 控制台无新错误；没有实际运行证据的「应该能跑」不算数。
24. API 大小写提示：tcb 公共服务 Action 官方用 PascalCase（EnvId、GroupName、ActivityNames），部分文档写 camelCase；首次调用若遇 InvalidParameter 就切换大小写重试，然后把可用形式固化到项目封装里。
25. 兄弟技能用本地相对路径引用（如 ../auth-tool-cloudbase/SKILL.md）；若引用的兄弟技能文件在本环境缺失，让用户安装完整 CloudBase 插件（或缺失的技能），不要用 HTTP 把远程技能或协议 markdown 拉进 agent 上下文。

适用边界 · 注意事项

• 浏览器/Web 应用 → 用 ai-model-web 技能。
• Node.js 后端或云函数 → 用 ai-model-nodejs 技能。
• 图片生成 → 用 ai-model-nodejs 技能（小程序不支持）。
• 没有 CloudBase SDK 的运行时（原生 App、Python 等）→ 用 http-api-cloudbase 技能（含 ai_model OpenAPI 规范可直接 HTTP 调用）。