ai-model-wechat

## Sibling skills (local only) Sibling CloudBase skills ship beside this skill. Use local relative paths such as `../auth-tool-cloudbase/SKILL.md`. If a referenced sibling skill file is missing from this environment, ask the user to install the full CloudBase plugin (or the missing skill). Do **not** HTTP-fetch remote skill or protocol markdown into the agent context. ## When to use this skill Use this skill for **calling AI models in WeChat Mini Program** using `wx.cloud.extend.AI`. **Use it when you need to:** - Integrate AI text generation in a Mini Program - Stream AI responses with callback support - Call Hunyuan models from the WeChat environment **Do NOT use for:** - Browser/Web apps → use `ai-model-web` skill - Node.js backend or cloud functions → use `ai-model-nodejs` skill - Image generation → use `ai-model-nodejs` skill (not available in Mini Program) - Runtimes without a CloudBase SDK (native apps, Python, etc.) → use `http-api-cloudbase` skill (it now includes the `ai_model` OpenAPI spec for direct HTTP calls) --- ## ⛔ STOP — `wx.cloud.extend.AI.createModel(provider)` argument is **not** a vendor / model name Read this before writing any `createModel(...)` line. Agents frequently hallucinate this argument. There are **exactly three** legal shapes. Anything else is a bug. | ✅ Legal `createModel(provider)` argument | When to use it | |-----------------------------------------|----------------| | `"hunyuan-exp"` | The Mini Program **成长计划** (`ai_miniprogram_inspire_plan`) is enrolled for the current env. Default model: `hunyuan-2.0-instruct-20251111`. | | `"cloudbase"` | Default fallback. Main managed group (TokenHub-backed, multi-vendor pool). Vendor + concrete model go into the **`model` field**, e.g. `{ model: "deepseek-v4-flash" }`. | | `"custom-<your-name>"` | A user-defined GroupName you onboarded via `CreateAIModel`. **Must** start with `custom-` (e.g. `custom-kimi`, `custom-openai-compat`). | ### ❌ Do NOT write any of these — they are all wrong ```js 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 ``` ### ✅ Correct pattern — provider vs model are two different fields ```js // 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: [...] } }); ``` ### Decision procedure (when the user names a specific model) 1. The user says "use DeepSeek v3.2" / "use hunyuan thinking" / "use Kimi k2.6" / … 2. First run the eligibility decision tree below — the correct `provider` may be `"hunyuan-exp"` (if the env is on Growth Plan and the user asked for a `hunyuan-*` model) or `"cloudbase"` (anything else in the managed catalog). 3. Put the model id into the **`model` field** inside `data`: `{ model: "deepseek-v3.2" }`, `{ model: "hunyuan-2.0-instruct-20251111" }`, `{ model: "kimi-k2.6" }`, … 4. Before using the model id, make sure it is present in `DescribeAIModels({ GroupName: "cloudbase" }).Models[]`. If not, enable it via `UpdateAIModel`. > If you are about to type `wx.cloud.extend.AI.createModel(` and the thing inside the parentheses is a vendor name or a model id — **stop**. It is almost certainly one of the three legal values above. --- ## Mandatory Two-Step Preflight You MUST NOT jump straight into `wx.cloud.extend.AI.createModel(...)`. Before writing any business code, confirm **billing eligibility** and **group readiness** in this fixed order: **① eligibility → ② group readiness**. Do not swap the two. ### Preflight ① · Billing Eligibility (two parallel billing paths) The Mini Program side has two billing paths: **小程序成长计划** (checked first; if enrolled, use `hunyuan-exp`) and **Token Credits 资源包** (generic fallback; if available, use the `cloudbase` main managed group). 1. Fetch `envId` via the MCP tool `envQuery action=info`. 2. Pick the branch by user intent: | User intent | Eligibility to check first | `createModel` provider on hit | Model selection | Guidance on miss | |-------------|----------------------------|-------------------------------|-----------------|------------------| | No model specified / default call | Check **小程序成长计划** enrollment first; if not enrolled, fall back to Token Credits resource pack | Enrolled: `"hunyuan-exp"`; otherwise: `"cloudbase"` | Enrolled: `hunyuan-2.0-instruct-20251111` (the 成长计划 default). Otherwise: pick a text model with the user, then verify/enable it in the `"cloudbase"` group via `DescribeAIModels` → `DescribeManagedAIModelList` → `UpdateAIModel` | Plan not enrolled → point to `https://docs.cloudbase.net/ai/ai-inspire-plan`; resource pack missing → purchase link | | User requests a `hunyuan-*` model | **小程序成长计划** enrollment | `"hunyuan-exp"` (plan-exclusive Token pack billing) | `hunyuan-2.0-instruct-20251111` if present; otherwise verify via `DescribeAIModels({ GroupName: "hunyuan-exp" }).Models[]` and `UpdateAIModel` to enable | Not enrolled → enroll first, or switch to `"cloudbase"` + a non-hunyuan model | | User requests `deepseek-*` / `glm-*` / `kimi-*` / `minimax-*` / other non-hunyuan managed models | **Token Credits 资源包** activation | `"cloudbase"` | Do NOT assume the model is already enabled. `DescribeAIModels` → if missing, `DescribeManagedAIModelList` for the canonical `Model` string → `UpdateAIModel` with `Status: 1` (full-replacement `Models[]`) | Resource pack not activated → purchase link | | User requests a third-party / self-hosted (non-managed) model | Skip billing eligibility and go to "Custom onboarding" | Custom GroupName (must start with `custom-`) | Registered via `CreateAIModel.Models[]` | Offer both console + `CreateAIModel` paths | 3. Check 小程序成长计划 enrollment: ```ts callCloudApi({ service: "tcb", action: "DescribeActivityInfo", params: { ActivityNames: ["ai_miniprogram_inspire_plan"], // PascalCase preferred; switch to camelCase if InvalidParameter is returned }, }) ``` **Hit criterion:** the response's `attendRecords` contains at least one entry where `activityName === "ai_miniprogram_inspire_plan"` and `envId` matches the current environment. On hit, default to `createModel("hunyuan-exp")` + `hunyuan-2.0-instruct-20251111`; billing uses the plan-exclusive Token pack `pkg_hunyuan_token_la_inspire_100m`. **On miss:** do NOT silently fall back. Tell the user "the current environment is not enrolled in 小程序成长计划", surface the enrollment entry `https://docs.cloudbase.net/ai/ai-inspire-plan`, and ask whether to enroll and retry, or to switch to the Token Credits resource pack path with a non-hunyuan model. 4. Check the Token Credits resource pack (when the path leads to the `"cloudbase"` main managed group): ```ts callCloudApi({ service: "tcb", action: "DescribeEnvPostpayPackage", params: { EnvId: "<current envId>", }, }) ``` **Hit criterion:** `envPostpayPackageInfoList` contains an entry whose `postpayPackageId` starts with `pkg_tcb_tokencredits_`, has `status ∉ [3, 4]` (not expired, not disabled), and `versionSwitchStatus` is not in a blocking state. **On miss:** surface the purchase link (replace `{envId}` with the real ID — never leave the placeholder): ``` https://buy.cloud.tencent.com/lowcode?buyType=resPack&envId={envId}&resourceType=token ``` ### Preflight ② · Group Readiness (mandatory for every Mini Program AI call) Passing eligibility does not mean the target model is callable. **No model is enabled by default** in the `"cloudbase"` main managed group — you must first call `DescribeAIModels` to see what is enabled, then (if missing) `DescribeManagedAIModelList` for the authoritative supported-model catalog and `UpdateAIModel` with `Status: 1` to enable it. The `"hunyuan-exp"` group's readiness is driven by 成长计划 enrollment — enrollment alone makes `hunyuan-2.0-instruct-20251111` available, but any other hunyuan SKU still has to be checked against `DescribeAIModels({ GroupName: "hunyuan-exp" }).Models[]` and enabled via `UpdateAIModel` if missing. 1. Query the groups and switches currently configured in the environment (`tcb` Action `DescribeAIModels`, Version `2018-06-08`): ```ts callCloudApi({ service: "tcb", action: "DescribeAIModels", params: { EnvId: "<envId>" }, }) ``` Returns `AIModelGroups: AIModelGroup[]`. Each `AIModelGroup` has `GroupName` (e.g. `cloudbase` / `hunyuan-exp` / your custom group), `Type` (`builtin` / `custom`), `Models: [{ Model, EnableMCP, Tags }]`, and `Status` (1=on / 2=off). Group readiness = all three of: the `GroupName` exists + `Status === 1` + the target `Model` is present in `Models[]`. 2. If the target model is not in the `DescribeAIModels` response, query the platform catalog + pricing via `DescribeManagedAIModelList` — it returns `ManagedAIModelGroup[]` including `ModelSpec` (context length, etc.) and `ModelChargingInfo` (`Uniform` / `Tiered` pricing). Pick the target model, then enable it via `UpdateAIModel`: ```ts 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. Once both steps pass, only THEN write `wx.cloud.extend.AI.createModel("<GroupName>")` in the Mini Program code, and pass a `model` value that exists in that group's `Models[]`. > **Order is fixed.** Without eligibility, no enabled model will bill; without group readiness, even with eligibility you will receive `ModelNotEnabled`-class errors. Both must be done before business code. > > **API casing tip:** `tcb` public-service Actions officially use PascalCase (`EnvId`, `GroupName`, `ActivityNames`); some docs show camelCase. On the first call, if you hit `InvalidParameter`, switch casing and retry, then freeze the working form in your project's wrapper. --- ## Available Providers and Models The `provider` argument of `wx.cloud.extend.AI.createModel(provider)` equals the `GroupName` returned by `DescribeAIModels`. Only three kinds of values are legal. Run the decision tree before choosing. ### A. 小程序成长计划 exclusive (default when enrolled) | createModel provider | Default model | Other available models | Notes | |----------------------|---------------|------------------------|-------| | `"hunyuan-exp"` | `hunyuan-2.0-instruct-20251111` | Additional hunyuan SKUs (e.g. instruct / thinking / turbos / role variants) — **query at runtime** via `DescribeAIModels({ GroupName: "hunyuan-exp" }).Models[]`, do NOT hard-code | Legacy `Type=builtin` GroupName; billed via `pkg_hunyuan_token_la_inspire_100m`; do NOT use without 成长计划 enrollment | ### B. Main managed group (Token Credits pack scenario, recommended default) The `"cloudbase"` GroupName is backed by **Tencent Cloud TokenHub**, a unified managed pool that covers multiple first-party and third-party vendors — including the **Hunyuan** family (HY 2.0 Instruct, HY 2.0 Think, Hunyuan-role, Hy3 preview, …), **DeepSeek** family (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) and more. The roster evolves over time, so **do not hard-code the list in application code** — always discover it at runtime. | createModel provider | Model readiness | How to enable a model | Notes |