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 four** legal shapes. Anything else is a bug. | ✅ Legal `createModel(provider)` argument | When to use it | |-----------------------------------------|----------------| | `"cloudbase"` | **Default, including 小程序成长计划.** Main managed group (TokenHub-backed, multi-vendor pool). Growth Plan quota draws on `cloudbase` + `hy3` — enable `hy3` first. Vendor + concrete model go into the **`model` field**, e.g. `{ model: "deepseek-v4-flash" }`. | | `"hunyuan-v3"` | **Legacy plan group, being retired.** Only `hy3` is available and no new models are added. Existing plan-enrolled code keeps working; new code uses `cloudbase` + `hy3`. | | `"hunyuan-exp"` | Older legacy builtin group — only if `DescribeAIModels` still returns it. Its default `hunyuan-2.0-instruct-20251111` went **offline on 2026-05-31**; never target that id. | | `"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 (enable hy3 in the console first) const model = wx.cloud.extend.AI.createModel("cloudbase"); // ← provider / GroupName await model.streamText({ data: { model: "hy3", 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 provider is `"cloudbase"` in almost every case, including Growth Plan environments (`cloudbase` + `hy3`). `"hunyuan-v3"` only appears in existing code that already used it; `"hunyuan-exp"` only if `DescribeAIModels` still returns that older group. 3. Put the model id into the **`model` field** inside `data`: `{ model: "deepseek-v3.2" }`, `{ model: "hy3" }`, `{ 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 four 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) and **Token Credits 资源包** (generic fallback). Both settle through the `cloudbase` main managed group — on the plan, the model is `hy3` and the plan quota is drawn first; `hunyuan-v3` is the legacy plan group that only draws plan quota and is being retired. 1. Fetch `envId` via the MCP tool `queryEnv 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 | `"cloudbase"` in both cases | Enrolled: `hy3` (the 成长计划 text model — enable it in the `"cloudbase"` group first). 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 | `"cloudbase"` (+ `hy3` for the plan quota) | Verify the exact `Model` in `DescribeAIModels({ GroupName: "cloudbase" }).Models[]` and enable it via `UpdateAIModel` if missing | Enrolled but the model is missing → enable it; not enrolled → point to the plan page, or use `"cloudbase"` + the resource pack | | 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, use `createModel("cloudbase")` + `model: "hy3"` (enable `hy3` in the group first); the call draws the plan's free quota. Legacy code on `createModel("hunyuan-v3")` + `hy3` still works but that group is being retired — migrate it to `cloudbase`. ⚠️ **The gifted Token is source-scoped.** It applies to **Mini Program client calls** and **administrator-identity calls** (console playground, calls made inside a cloud function) only. A call from any other origin does not draw on it and settles against the environment's resource-point pool instead — which is what a user sees as "the Token pack did not apply, resource points were charged". When a report sounds like that, check the call origin before touching the code or the model config. Same rule for the Token Credits pack path below. **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. Growth Plan enrollment does not skip this check: `hy3` must still be present and enabled in the `cloudbase` group. Legacy `"hunyuan-v3"` exposes only `hy3` and is being retired — treat it as read-only compatibility, not the default. 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 the four kinds of values below are legal. Run the decision tree before choosing. ### A. 小程序成长计划 (default when enrolled) — provider is `cloudbase`, model is `hy3` | createModel provider | Default model | Other available models | Notes | |----------------------|---------------|------------------------|-------| | `"cloudbase"` | `hy3` | Whatever else the env has enabled in `DescribeAIModels({ GroupName: "cloudbase" }).Models[]` — query at runtime, do NOT hard-code | Plan quota draws first when the call origin allows it; enable `hy3` via `UpdateAIModel` before the first call | | `"hunyuan-v3"` | `hy3` | None — this group only exposes `hy3` | Legacy plan group, being retired. Existing code works; migrate to `cloudbase` + `hy3` | | `"hunyuan-exp"` | — | Whatever the env still returns | Older legacy builtin. Its original default `hunyuan-2.0-instruct-20251111` is offline (2026-05-31) — do not target it | ### B. Main managed group (Token Credits pack scenario, recommended default)