Merge pull request #579 from TencentCloudBase/fix/skill-alias-resolution

fix(skills): guide alias→EnvId resolution & align Web SDK quick-start examples

Author: binggg

config/codebuddy-plugin/rules/cloudbase_rules.md

@@ -53,3 +53,8 @@ updatedAt: 2026-03-27T00:00:00.000Z
 
 **7. 环境检查**
 开始工作前调用 `envQuery` 检查云开发环境状态，确保已知晓当前环境 ID。
+
+**8. 环境 ID 使用规则**
+- 在 SDK 初始化、`auth.set_env`、控制台链接和生成配置文件时，必须使用完整 `EnvId`
+- 如果对话里只有环境别名、昵称或其他简写，先用 `envQuery(action=list, alias=..., aliasExact=true)` 解析出完整 `EnvId`
+- 不要把别名式简写直接传给 `auth.set_env`、SDK 初始化、控制台链接或生成配置；如果别名不唯一或不存在，先向用户确认

config/source/editor-config/guides/cloudbase-rules.mdc

@@ -375,6 +375,8 @@ For example, many interfaces require a confirm parameter, which is a boolean typ
 
 ### Environment ID Auto-Configuration Rules
 - When generating project configuration files (such as `cloudbaserc.json`, `project.config.json`, etc.), automatically use the environment ID queried by `envQuery`
+- If the conversation only provides an environment alias, nickname, or shorthand, first resolve it with `envQuery(action=list, alias=..., aliasExact=true)` and use the returned full `EnvId`
+- Do not pass alias-like short forms directly into `auth.set_env`, SDK init, console links, or generated config files; if the alias is ambiguous or missing, stop and ask the user to confirm
 - In code examples involving environment ID, automatically fill in current environment ID, no need for manual user replacement
 - In deployment and preview related operations, prioritize using already queried environment information
 

config/source/guideline/cloudbase/SKILL.md

@@ -133,6 +133,7 @@ When your IDE does not support native MCP, use **mcporter** as the CLI to config
 
 - **When managing or deploying CloudBase, you MUST use MCP and MUST understand tool details first.** Before calling any CloudBase tool, run `npx mcporter describe cloudbase --all-parameters` (or `ToolSearch` in IDE) to inspect available tools and their parameters.
 - You **do not need to hard-code Secret ID / Secret Key / Env ID** in the config. CloudBase MCP supports device-code based login via the `auth` tool, so credentials can be obtained interactively instead of being stored in config.
+- When the environment identifier in the conversation is an alias, nickname, or other short form, **do not pass it directly** to `auth.set_env`, SDK init, console URLs, or generated config files. First resolve it to the canonical full `EnvId` with `envQuery(action=list, alias=..., aliasExact=true)`. If multiple environments match or no exact alias exists, stop and clarify with the user.
 
 ### Quick Start (mcporter CLI)
 - `npx mcporter list` — list configured servers
@@ -146,8 +147,10 @@ When your IDE does not support native MCP, use **mcporter** as the CLI to config
   `npx mcporter call cloudbase.auth action=status --output json`
 - Start device-flow login (future-friendly device-code login; no keys in config):
   `npx mcporter call cloudbase.auth action=start_auth authMode=device --output json`
+- If the user gives an environment alias / nickname / short form instead of the full `EnvId`, resolve it first:
+  `npx mcporter call cloudbase.envQuery action=list alias=demo aliasExact=true fields='["EnvId","Alias","Status","IsDefault"]' --output json`
 - Bind environment after login (envId from CloudBase console):
-  `npx mcporter call cloudbase.auth action=set_env envId=env-xxx --output json`
+  `npx mcporter call cloudbase.auth action=set_env envId=<full-env-id> --output json`
 - Query app-side login config:
   `npx mcporter call cloudbase.queryAppAuth action=getLoginConfig --output json`
 - Patch app-side login strategy:

config/source/skills/SKILL.md

@@ -39,8 +39,7 @@ alwaysApply: true
 
 - If the same path fails 2-3 times, stop retrying and reroute. Check platform skill, auth domain, runtime, and permission model before editing more code.
 - Always specify `EnvId` explicitly in code, configuration, and command examples when initializing CloudBase clients or manager operations. Do not rely on the current CLI-selected environment or implicit defaults.
-- When saving MCP or tool results to a local file with a generic file-writing tool, pass text, not raw objects. For JSON output files, serialize first with `JSON.stringify(result, null, 2)` and write that string as the file content.
-- If the file-writing tool reports that a field such as `content` expected a string but received an object, do not retry with the same raw object. Serialize the object first, then retry once with the serialized text, and make sure the retried call actually passes the serialized string rather than the original object.
+- If the conversation only provides an environment alias, nickname, or other shorthand, resolve it with `envQuery(action=list, alias=..., aliasExact=true)` and use the returned canonical full `EnvId` before calling `auth.set_env`, generating console links, or writing config/code. If the alias is ambiguous or missing, stop and ask the user to confirm.
 
 ### Do NOT use this as
 

config/source/skills/auth-tool/SKILL.md

@@ -94,7 +94,7 @@ Recommended MCP request:
 ```json
 {
   "success": true,
-  "envId": "env-xxx",
+  "envId": "your-full-env-id",
   "loginMethods": {
     "usernamePassword": true,
     "email": true,
@@ -135,6 +135,7 @@ Parameter mapping for downstream Web auth code:
 - `UserNameLogin` also enables the broader password-login surface exposed by `auth.signInWithPassword({ username|email|phone, password })`
 - `SmsVerificationConfig.Type = "apis"` requires both `Name` and `Method`
 - `EnvId` is always the CloudBase environment ID, not the publishable key
+- If the conversation only contains an environment alias, nickname, or other shorthand, resolve it to the canonical full `EnvId` first before generating auth config, SDK init examples, or console links
 
 Internal behavior of `manageAppAuth(action="patchLoginStrategy")`:
 

config/source/skills/auth-web/SKILL.md

@@ -59,9 +59,8 @@ Keep local `references/...` paths for files that ship with the current skill dir
 
 **Use Case**: Web frontend projects using `@cloudbase/js-sdk@2.24.0+` for user authentication  
 **Key Benefits**: Supabase-like Auth API shape, supports phone, email, anonymous, username/password, and third-party login methods
-**Official `@cloudbase/js-sdk` CDN**: `https://static.cloudbase.net/cloudbase-js-sdk/latest/cloudbase.full.js`
 
-Use the same CDN address as `web-development`. Prefer npm installation in modern bundler projects, and use the CDN form for static HTML, no-build demos, or low-friction examples.
+Use npm installation for modern Web projects. In React, Vue, Vite, and other bundler-based apps, install and import `@cloudbase/js-sdk` from the project dependencies instead of using a CDN script.
 
 ## Prerequisites
 
@@ -71,6 +70,7 @@ Use the same CDN address as `web-development`. Prefer npm installation in modern
 ### Parameter map
 
 - For username-style identifiers, the required precondition is `loginMethods.usernamePassword === true` from `queryAppAuth(action="getLoginConfig")`. If it is false, enable it with `manageAppAuth(action="patchLoginStrategy", patch={ usernamePassword: true })` before wiring frontend auth code.
+- If the conversation only provides an environment alias, nickname, or other shorthand, resolve it with `envQuery(action="list", alias=..., aliasExact=true)` first and use the returned canonical full `EnvId` for SDK init, console links, and generated config. Do not pass alias-like short forms directly into `cloudbase.init({ env })`.
 - Treat CloudBase Web Auth as **Supabase-like**, not “every `supabase-js` auth example is valid unchanged”
 - When `queryAppAuth` / `manageAppAuth` returns `sdkStyle: "supabase-like"` and `sdkHints`, follow those method and parameter hints first
 - `auth.signInWithOtp({ phone })` and `auth.signUp({ phone })` use the phone number in a `phone` field, not `phone_number`
@@ -85,10 +85,11 @@ Use the same CDN address as `web-development`. Prefer npm installation in modern
 ## Quick Start
 
 ```js
+// npm install @cloudbase/js-sdk
 import cloudbase from '@cloudbase/js-sdk'
 
 const app = cloudbase.init({
-  env: `env`, // CloudBase environment ID
+  env: 'your-full-env-id', // Canonical full CloudBase environment ID resolved from envQuery or the console, not an alias or shorthand
   region: `region`,  // CloudBase environment Region, default 'ap-shanghai'
   accessKey: 'publishable key', // required, get from auth-tool-cloudbase
   auth: { detectSessionInUrl: true }, // required
@@ -105,8 +106,9 @@ If the current task has not retrieved a real Publishable Key, omit `accessKey` i
 
 **1. Phone OTP (Recommended)**
 - Automatically use `auth-tool-cloudbase` to turn on `SMS Login` through `manageAppAuth`
+- For phone registration, send the phone number to `auth.signUp({ phone, ... })` first, then call the returned `verifyOtp({ token })`. Do not swap the order.
 ```js
-const { data, error } = await auth.signInWithOtp({ phone: '13800138000' })
+const { data, error } = await auth.signUp({ phone: '13800138000' })
 const { data: loginData, error: loginError } = await data.verifyOtp({ token:'123456' })
 ```
 
@@ -145,7 +147,7 @@ const emailVerifyResult = await emailSignUp.data.verifyOtp({ token: '123456' })
 // Phone Otp
 // Use only when the task explicitly requires phone numbers.
 // Phone Otp
-const phoneSignUp = await auth.signUp({ phone: '13800138000', nickname: 'User' })
+const phoneSignUp = await auth.signUp({ phone: '13800138000', password: 'pass123', nickname: 'User' })
 const phoneVerifyResult = await phoneSignUp.data.verifyOtp({ token: '123456' })
 ```
 
@@ -178,25 +180,21 @@ Do not use email OTP or email-only helpers for these flows unless the task expli
 const handleSendCode = async () => {
   try {
     const { data, error } = await auth.signUp({
-      email,
-      name: username || email.split('@')[0],
+      phone,
+      password: password || undefined,
     })
     if (error) throw error
-    setSignUpData(data)
+    verifyOtpRef.current = data.verifyOtp
   } catch (error) {
     console.error('Failed to send sign-up code', error)
   }
 }
 
 const handleRegister = async () => {
   try {
-    if (!signUpData?.verifyOtp) throw new Error('Please send the code first')
+    if (!verifyOtpRef.current) throw new Error('Please send the code first')
 
-    const { error } = await signUpData.verifyOtp({
-      email,
-      token: code,
-      type: 'signup',
-    })
+    const { error } = await verifyOtpRef.current({ token: code })
     if (error) throw error
   } catch (error) {
     console.error('Failed to complete sign-up', error)

config/source/skills/cloudbase-platform/SKILL.md

@@ -112,8 +112,10 @@ Use this skill for **CloudBase platform knowledge** when you need to:
 1. **SDK Initialization**:
    - CloudBase SDK initialization requires environment ID
    - Can query environment ID via `envQuery` tool
+   - If the user only provides an environment alias, nickname, or other short form, resolve it with `envQuery(action="list", alias=..., aliasExact=true)` first and use the returned full `EnvId`
+   - Do not pass alias-like short forms directly into SDK init, `auth.set_env`, console URLs, or generated config files
    - For Web, always initialize synchronously:
-     - `import cloudbase from "@cloudbase/js-sdk"; const app = cloudbase.init({ env: "xxxx-yyy" });`
+     - `import cloudbase from "@cloudbase/js-sdk"; const app = cloudbase.init({ env: "your-full-env-id" });`
      - Do **not** use dynamic imports like `import("@cloudbase/js-sdk")` or async wrappers such as `initCloudBase()` with internal `initPromise`
    - Then proceed with login, for example using anonymous login
 
@@ -305,6 +307,7 @@ The CloudBase console is updated frequently. If a live, logged-in console shows
 
 - **Base URL Pattern**: `https://tcb.cloud.tencent.com/dev?envId=${envId}#/{path}`
 - **Replace Variables**: Always replace `${envId}` with the actual environment ID queried via `envQuery` tool
+- **Alias Handling**: If the conversation only contains an alias or shorthand, first resolve it with `envQuery(action="list", alias=..., aliasExact=true)` and use the returned `EnvId`; if the alias is ambiguous or missing, ask the user to confirm before generating links
 - **Resource-Specific URLs**: For specific resources (collections, functions, models), replace resource name variables with actual values
 - **Usage**: After creating/deploying resources, provide these console links to users for management operations
 

config/source/skills/web-development/SKILL.md

@@ -117,6 +117,7 @@ Use this section only when the Web project needs CloudBase platform features.
 - Use the CDN only for static HTML pages, quick demos, embedded snippets, or README examples
 - Only use documented CloudBase Web SDK APIs; do not invent methods or options
 - Keep a shared `app` or `auth` instance instead of re-initializing on every call
+- If the user only provides an environment alias, nickname, or other shorthand, resolve it to the canonical full `EnvId` before writing SDK init code, console links, or config files. Do not pass alias-like short forms directly into `cloudbase.init({ env })`.
 
 ### Authentication boundary
 
@@ -134,10 +135,11 @@ Use this section only when the Web project needs CloudBase platform features.
 ### CloudBase quick start
 
 ```js
+// npm install @cloudbase/js-sdk
 import cloudbase from "@cloudbase/js-sdk";
 
 const app = cloudbase.init({
-  env: "xxxx-yyy",
+  env: "your-full-env-id", // Canonical full CloudBase environment ID resolved from envQuery or the console
 });
 
 const auth = app.auth();

scripts/prompts/cloudbase-integrated.md

@@ -14,6 +14,8 @@ When user's application fits the above scenarios, suggest confirming the tech st
 ### 1. Environment Check (MANDATORY - First Step)
 - **Always call `envQuery` tool first** with `action=info` to get environment ID
 - Auto-use queried envId in code/config, no manual input needed
+- If the conversation only gives an environment alias, nickname, or other shorthand, resolve it with `envQuery(action=list, alias=..., aliasExact=true)` and use the returned canonical full `EnvId`
+- Do not pass alias-like short forms directly into SDK init, `auth.set_env`, console URLs, or generated config files. If the alias is ambiguous or missing, stop and clarify with the user
 
 ### 2. Template Download (MANDATORY for New Projects)
 - **MUST call `downloadTemplate` FIRST** when starting new projects - Do NOT manually create files

scripts/skills-repo-template/cloudbase-guidelines/SKILL.md

@@ -91,11 +91,13 @@ mcpServers:
 
 In environments that do not support MCP (e.g. openclaw) or when users are unsure how to configure MCP, use **mcporter** as a CLI to call CloudBase MCP tools.
 
-**When managing or deploying CloudBase, you MUST use MCP and MUST understand tool details first.** Before calling any CloudBase tool, run `npx mcporter describe cloudbase` (or equivalent in your IDE) to inspect the server config and available tools.
+**When managing or deploying CloudBase, you MUST use MCP and MUST understand tool details first.** Before calling any CloudBase tool, run `npx mcporter describe cloudbase --all-parameters` (or equivalent in your IDE) to inspect available tools and their full parameters.
 
 You **do not need to hard-code Secret ID / Secret Key / Env ID** in the config.  
 CloudBase MCP will support device-code based login via the `auth` tool, so credentials can be obtained interactively instead of being stored in config.
 
+When the environment identifier in the conversation is an alias, nickname, or other short form, **do not pass it directly** to `auth.set_env`, SDK init, console URLs, or generated config files. First resolve it to the canonical full `EnvId` with `envQuery(action=list, alias=..., aliasExact=true)`. If multiple environments match or no exact alias exists, stop and clarify with the user.
+
 **Add CloudBase MCP server in `config/mcporter.json` (recommended):**
 
 If `config/mcporter.json` already contains other MCP servers, keep them and only add the `cloudbase` entry under `mcpServers`.
@@ -115,7 +117,7 @@ If `config/mcporter.json` already contains other MCP servers, keep them and only
 
 **Quick start:**
 - `npx mcporter list` — list configured servers
-- **Required:** `npx mcporter describe cloudbase` — inspect CloudBase server config and available tools (must run before managing/deploying CloudBase)
+- **Required:** `npx mcporter describe cloudbase --all-parameters` — inspect CloudBase server config and get full tool schemas with all parameters (must run before managing/deploying CloudBase)
 - `npx mcporter list cloudbase --schema` — get full JSON schema for all CloudBase tools
 - `npx mcporter call cloudbase.help --output json` — discover available CloudBase tools and their schemas
 - `npx mcporter call cloudbase.<tool> key=value` — call a CloudBase tool
@@ -125,8 +127,10 @@ If `config/mcporter.json` already contains other MCP servers, keep them and only
   `npx mcporter call cloudbase.auth action=status --output json`
 - Start device-flow login (future-friendly device-code login; no keys in config):  
   `npx mcporter call cloudbase.auth action=start_auth authMode=device --output json`
+- If the user gives an environment alias / nickname / short form instead of the full `EnvId`, resolve it first:
+  `npx mcporter call cloudbase.envQuery action=list alias=demo aliasExact=true fields='["EnvId","Alias","Status","IsDefault"]' --output json`
 - Bind environment after login (envId from CloudBase console):  
-  `npx mcporter call cloudbase.auth action=set_env envId=env-xxx --output json`
+  `npx mcporter call cloudbase.auth action=set_env envId=<full-env-id> --output json`
 
 ---
 
@@ -174,7 +178,7 @@ If the platform supports long-term memory, persist these scenarios so the agent
 Prefer long-term memory when available: write the scenarios and working rules there so the agent always applies them. When configuring the workspace (e.g. `AGENTS.md`) or long-term memory, add reminders like:
 
 - **CloudBase skills** → Run `npx skills add tencentcloudbase/cloudbase-skills` to install; use `cloudbase` and log in to CloudBase (MCP auth, device-code) for full-stack development.
-- **CloudBase = MCP, understand tools first** → When managing or deploying CloudBase, you MUST use MCP and MUST understand tool details first. Before calling any CloudBase tool, run `npx mcporter describe cloudbase` (or equivalent in your IDE) to inspect the server config and available tools.
+- **CloudBase = MCP, understand tools first** → When managing or deploying CloudBase, you MUST use MCP and MUST understand tool details first. Before calling any CloudBase tool, run `npx mcporter describe cloudbase --all-parameters` (or equivalent in your IDE) to inspect available tools and their full parameters.
 - **mcporter call format** → `npx mcporter call cloudbase.<tool> key=value`, e.g. `npx mcporter call cloudbase.auth action=status --output json`.
 - **CloudBase development and deployment** → Use MCP to automate (environment, functions, database, hosting, etc.).
 - **Development norms** → Read the relevant CloudBase skills (e.g. `cloudbase`, `web-development`, `miniprogram-development`, `cloud-functions`) before writing code.