Web/前端应用直接调用 AI 模型时，用…

当 React/Vue/Next/Nuxt/静态站点/SPA/仪表盘/AI 聊天 UI 等浏览器端应用需要接入 AI 文本生成或流式输出时，用 @cloudbase/js-sdk 从浏览器直接调用模型，并在写代码前完成资格与分组就绪检查。

适用场景

解决思路

1. 确认这是 Web/前端场景后，默认用 @cloudbase/js-sdk 在浏览器直接调用模型；不要先提议 Node.js / 云函数 / CloudRun 代理，只有用户明确要求后端调用、图片生成或确实需要服务端密钥、长任务时才切到 ai-model-nodejs。
2. 兄弟技能（如 ../auth-tool-cloudbase/SKILL.md）只用本地相对路径引用；若文件缺失，让用户安装完整 CloudBase 插件或缺失技能，不要用 HTTP 把远程技能/协议 markdown 拉进 agent 上下文。
3. 写任何 AI 相关 SDK 代码前，先执行强制两步 preflight：① 资格（Token Credits 资源包）② 分组就绪（group readiness）。直接吐 createModel(...) 再让用户调试运行时报错代价高得多。
4. Step 0：调用 MCP 工具 queryEnv（action=info），从响应读取 EnvId，后续所有检查与购买链接都用这个 EnvId。
5. Preflight ①：调用 callCloudApi(service="tcb", action="DescribeEnvPostpayPackage", params={ EnvId })；通过条件为 envPostpayPackageInfoList 至少有一条、其 postpayPackageId 以 pkg_tcb_tokencredits_ 开头、且 status 不在 [3,4]（3/4 通常表示过期/停用，以实时响应为准）。
6. Preflight ① 不通过时立刻停止写代码，并向用户说明：当前环境没有活跃的 Token Credits 资源包，请先购买再调用任何 AI API，链接为 https://buy.cloud.tencent.com/lowcode?buyType=resPack&envId={envId}&resourceType=token（替换为真实 envId），等用户完成后重新检查。
7. Preflight ②：调用 callCloudApi(service="tcb", action="DescribeAIModels", params={ EnvId }) 获取 AIModelGroups，检查目标 GroupName 是否存在且 Status=1（1=开/2=关），并确认目标 Model 在该组 Models[] 中；若 cloudbase 组本身缺失或 Status=2 也要处理。
8. 不要假设任何模型已默认启用——包括 deepseek-v4-flash、hunyuan-* 等；目标模型不在 Models[] 中时不要调用 createModel，先走目录查询与启用流程。
9. 需要启用托管模型时，先调用 callCloudApi(service="tcb", action="DescribeManagedAIModelList", params={ EnvId }) 获取权威目录（Model 精确拼写、ModelSpec 上下文长度/最大输入输出 token、ModelChargingInfo 输入/输出/缓存价格与计费单位），不要凭记忆猜模型名或厂商前缀，并先把价格告知用户再启用。
10. 启用/添加模型用 callCloudApi(service="tcb", action="UpdateAIModel", params={ EnvId, GroupName: "cloudbase", Models: [...], Status: 1 })；注意 Models 是全量替换，必须把 DescribeAIModels 已显示启用的模型一起重发，再追加新模型。
11. 用户指定某个托管模型时，仍保持 createModel("cloudbase") 不变，把模型 id 放进 generateText/streamText 的 model 字段（如 { model: "deepseek-v3.2" }、{ model: "hunyuan-2.0-instruct-20251111" }、{ model: "kimi-k2.6" }、{ model: "glm-5" }）；先用 DescribeManagedAIModelList 校验精确拼写（区分大小写），不要猜。
12. cloudbase 组由腾讯云 TokenHub 托管，覆盖 Hunyuan、DeepSeek、GLM、Kimi、MiniMax 等多厂商统一池，名单会演进；不要在应用代码里硬编码具体 SKU，运行时发现。hunyuan-exp 组的默认模型为 hunyuan-2.0-instruct-20251111，其余 SKU 必须通过 DescribeAIModels({ GroupName: "hunyuan-exp" }).Models[] 在运行时发现，不要硬编码其他 ID。
13. 若目标模型不在托管目录，走自定义接入（custom onboarding），不要阻塞用户。可选控制台流程：https://tcb.cloud.tencent.com/dev?envId={envId}#/ai。
14. 也可用 callCloudApi(service="tcb", action="CreateAIModel", params={ EnvId, GroupName: "custom-<your-name>"（必须以 custom- 开头，绝不能以 cloudbase 开头）, BaseUrl: "<OpenAI 兼容端点，如 https://api.moonshot.cn/v1>", Models: [{ Model: "<模型名>", EnableMCP: true }], Remark, Status: 1, Secret: { ApiKey: "<用户提供的厂商密钥>" } }) 进行编程式接入。
15. 自定义接入后用 DescribeAIModels 确认分组就绪，再调用 ai.createModel("<刚注册的 GroupName>")；用 UpdateAIModel 增删模型、轮换密钥或修改 BaseUrl（Models 仍是全量替换），用 DeleteAIModel 删除自定义分组（builtin 分组不可删除）。自定义模型由第三方厂商计费，不消耗 Token Credits 资源包。
16. 安装依赖：npm install @cloudbase/js-sdk。
17. 初始化使用同步方式与顶层 import：import cloudbase from "@cloudbase/js-sdk"; const app = cloudbase.init({ env: "<YOUR_ENV_ID>", accessKey: import.meta.env.VITE_PUBLISHABLE_KEY })，accessKey 通过 queryAppAuth / manageAppAuth 自动开通并写入 .env.local。
18. 登录校验必须用 auth.getSession()，不要用已废弃的 getLoginState()——accessKey 会让 getLoginState() 在未真正登录时也返回 uid，造成误判；getSession() 在无真实登录时 data.session === undefined，且要检查 session.user.is_anonymous，未登录或匿名则跳转登录页并 return。
19. 不要用匿名登录作为默认：新环境默认禁用匿名登录，且匿名用户默认被拒绝 AI 模型调用权限，只有非 AI 只读 demo 且用户明确接受时才可用。登录提供方配置（手机短信、邮箱、微信开放平台、用户名密码、OAuth）交给 auth-tool-cloudbase 技能，浏览器端登录流程（登录表单、回调、会话守卫）交给 auth-web-cloudbase 技能。
20. 非流式调用：const model = ai.createModel("cloudbase"); const result = await model.generateText({ model: "deepseek-v4-flash", messages: [{ role: "user", content: "..." }] })，读取 result.text、result.usage（prompt_tokens/completion_tokens/total_tokens）、result.messages、result.rawResponses。前提是两步 preflight 已通过且目标模型已确认在 DescribeAIModels({ GroupName: "cloudbase" }).Models[] 中。
21. 流式调用：const res = await model.streamText({ model, messages })；方式一 for await (let text of res.textStream) 迭代增量文本（推荐）；方式二 for await (let data of res.dataStream) 迭代带元数据的完整响应块；方式三 await res.messages / await res.usage 取最终消息历史与 token 用量。
22. AI 调用要用 try/catch 包裹并优雅处理错误。
23. 按类型定义传参：BaseChatModelInput 中 model、messages 必填，temperature、topP 可选；消息类型 ChatModelMessage 的 role 为 user/system/assistant；GenerateTextResult 含 text/messages/usage/rawResponses/error，StreamTextResult 含 textStream/dataStream/messages/usage/error。
24. createModel 只接受三种合法值："cloudbase"（主托管组，厂商与具体模型放到 model 字段）、"hunyuan-exp"（旧内置组，仅当 DescribeAIModels 明确返回时使用，主要见于小程序成长计划）、custom-<name>（通过 CreateAIModel 注册的用户自定义组）。禁止写 createModel("deepseek")、createModel("deepseek-v4-flash")、createModel("hunyuan")、createModel("hunyuan-2.0-instruct-20251111")、createModel("glm")、createModel("kimi")、createModel("minimax")、createModel("openai")、createModel("moonshot")、createModel("custom")、createModel(modelName)；写括号前若发现里而是厂商名、模型名或猜测值就停下来。
25. 不要臆造 SDK 方法名或参数：以本技能文档、类型定义或 MCP 实时契约为准，未文档化的方法或字段要停下来询问，不要猜。
26. 长响应优先使用流式（streamText）以改善感知延迟和交互性。
27. accessKey 只能使用 publishable key，绝不能使用 secret key，保证密钥安全。
28. 在应用入口尽早初始化 SDK，让路由前 auth 与 ai 都已就绪。
29. 配置自定义模型时区分“preflight 失败”和“模型调用失败”：前者意味着用户需要购买资源包或调用 UpdateAIModel 启用模型，后者是 prompt、参数或网络问题，要给不同的排查指引。
30. TypeScript 不要用 any 压制 SDK 类型错误：SDK 自带类型，出错时用 unknown + 类型守卫、为实际消费的结构写精确 interface，或在本地 .d.ts 做类型增强；禁止 : any、as any、@ts-ignore、@ts-nocheck。
31. 声称完成前必须自测：运行 tsc --noEmit + 项目构建 + 用 agent-browser 打开页面并实际触发 AI 调用，确认（a）文本流到达 UI、（b）没有新的 console 错误、（c）result.usage 非零；没有证据就说“应该能跑”不可接受。
32. 所有 callCloudApi 调用使用 service=tcb、Version=2018-06-08，参数为 PascalCase（EnvId/GroupName/Models/Status）；仅在返回 InvalidParameter 时回退 camelCase，并以实时响应为准。

适用边界 · 注意事项

• 不适用于 Node.js 后端或云函数场景——改用 ai-model-nodejs 技能。
• 不适用于微信小程序（改用 ai-model-wechat）和图片生成（仅 Node SDK 支持，改用 ai-model-nodejs）。
• 不适用于没有 CloudBase SDK 的运行时（原生 App、Python、Go 等，改用 http-api-cloudbase），也不适用于没有 CloudBase 环境或未购买 Token Credits 资源包的情况。