---

name: cloudbase-platform description: CloudBase platform overview and routing guide. This skill should be used when users need high-level capability selection, platform concepts, console navigation, realtime (broadcast / presence / live database changes), or cross-platform best practices before choosing a more specific implementation skill. version: 2.34.8 alwaysApply: false

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.

Cross-cutting protocols (required before code changes or deployments):

• Change Safety Protocol: references/protocols/change-safety-protocol.md
• Deployment Gate: references/protocols/deployment-gate.md
• Sensitive Runtime Data Protection: references/protocols/sensitive-runtime-data-protection.md

Post-deployment (optional, non-intrusive): after a deployment is verified successful, you may offer at most once to generate anonymized shareables and, in that same offer, optionally submit the work to the case wall (Deployment Share) — see references/protocols/deployment-share.md. Never follow up if declined; never publish or submit on the user's behalf.

Activation Contract

Use this first when

• The user asks which CloudBase capability, service, or tool to use, or needs a high-level understanding of hosting, storage, authentication, cloud functions, or database options.
• The task is about console navigation, cross-platform differences, permission models, or platform-level best practices before implementation.

Read before writing code if

• It is still unclear whether the task belongs to Web, mini program, cloud functions, storage, MySQL / NoSQL, or auth.
• The response needs platform selection, conceptual explanation, or control-plane navigation more than direct implementation steps.

Then also read

• Minimal Web + database demo (BaaS-first, no cloud functions by default) -> ../minimal-web-baas-demo/SKILL.md
  • Stack order for 最小前后端 / Lovable-like demos: Web SDK CRUD > MCP schema > template warmup during credential wait > cloud functions (default count = 0). Capability sniff: connector ready → queryEnv → lock one DB plane → MCP schema → @cloudbase/js-sdk CRUD → preview.
• Web app implementation -> ../web-development/SKILL.md
• Web auth and provider setup -> ../auth-tool-cloudbase/SKILL.md, ../auth-web-cloudbase/SKILL.md
• Mini program development -> ../miniprogram-development/SKILL.md
• WeChat Pay, Official Account OAuth, JSAPI Pay, or Native QR-code Pay through CloudBase Integration Center -> ../cloudbase-wechat-integration/SKILL.md (official docs: https://docs.cloudbase.net/integration/introduce.md)
• Cloud functions -> ../cloud-functions/SKILL.md
• Official HTTP API clients -> ../http-api-cloudbase/SKILL.md
• Document database -> ../cloudbase-document-database-web-sdk/SKILL.md or ../cloudbase-document-database-in-wechat-miniprogram/SKILL.md
• CloudBase PostgreSQL / PG -> ../postgresql-development-cloudbase/SKILL.md
• Realtime / live push / channels / live table change subscriptions / multiplayer sync -> ../postgresql-development-cloudbase/references/realtime.md
  • PG mode only. Run its Step 0 environment probe before writing any realtime code; if the environment has no realtime schema, stop and report rather than working around it.
  • app.realtime() (Broadcast / Presence / Postgres CDC) is not document-database collection.watch(). Do not answer a realtime request with watch() code, or the reverse.
• MySQL relational database / data modeling -> ../relational-database-mcp-cloudbase/SKILL.md or ../data-model-creation/SKILL.md
• Cloud storage -> ../cloud-storage-web/SKILL.md

Do NOT use for

• Direct implementation of web pages, auth flows, functions, or database operations when a more specific skill already fits.
• Low-level API parameter references or SDK recipes that belong in specialized skills.

Common mistakes / gotchas

• Treating this general skill as the default entry point for all CloudBase development.
• Staying here after the correct implementation skill is already clear.
• Mixing platform overview with platform-specific API shapes or SDK details.
• Using this overview skill as a detour in an existing application where the active auth, storage, and data files are already obvious.
• Making code or configuration changes without first following the Change Safety Protocol (cloudbase-platform/references/protocols/change-safety-protocol.md).
• Starting any deployment, publish, custom domain, or CloudRun work without first completing the checks in cloudbase-platform/references/protocols/deployment-gate.md.
• Echoing x-cloudbase-context, full req.headers, or process.env from Cloud Functions / CloudRun (including httpbin-style debug images) — follow references/protocols/sensitive-runtime-data-protection.md.
• Confusing security domains with custom domains: these are two different tools for different purposes. See the "Domain Management Tools" table below for the authoritative split.

When to use this skill

Use this skill for CloudBase platform knowledge when you need to:

• Understand CloudBase storage and hosting concepts
• Compare platform capabilities before implementation
• Understand cross-platform auth differences (Web vs Mini Program)
• Understand database permissions and access control
• Access CloudBase console management pages

This skill provides foundational knowledge that applies to all CloudBase projects, regardless of whether they are Web, Mini Program, or backend services.

---

How to use this skill (for a coding agent)

1. Understand platform differences

   • Web and Mini Program have completely different authentication approaches
   • Must strictly distinguish between platforms
   • Never mix authentication methods across platforms
   • If the workspace is already an application with TODOs or prebuilt handlers, do not stay in platform overview mode. Move quickly to the concrete implementation skill and the existing files that own the flow.

2. Follow best practices

   • Use SDK built-in authentication features (Web)
   • Understand natural login-free feature (Mini Program)
   • Configure appropriate database permissions
   • Prefer @cloudbase/js-sdk direct DB access for browser CRUD; use cloud functions only for secrets, scheduled/background jobs, or elevated cross-collection logic that security rules / RLS cannot express (see ../minimal-web-baas-demo/SKILL.md for the demo default)

3. Use correct SDKs and APIs

   • Different platforms require different SDKs for data models
   • MySQL data models must use models SDK, not collection API
   • PostgreSQL / CloudBase PG work must route to postgresql-development-cloudbase; do not reuse NoSQL app.database() / db.collection(...) snippets or MySQL queryMysqlDatabase / manageMysqlDatabase for PG data paths
   • Use queryEnv tool to get environment ID
   • In an existing Web application with fixed structure, inspect the existing src/lib/backend.*, src/lib/auth.*, src/lib/*service.*, and bound page handlers before broad concept reading.

4. Use the canonical CloudBase MCP setup from the main cloudbase guideline

   • This platform overview intentionally does not duplicate the full MCP / mcporter config block
   • For the canonical config snippet, CLI commands, and auth examples, read the main cloudbase guideline first
   • Keep the same core rules here: prefer MCP when tools are available in this session; if not, configure MCP for next session and use tcb CLI now (../cloudbase-cli/SKILL.md, ../cloudbase/references/tooling-fallback.md). Inspect tool schemas before MCP execution. Do not hard-code Secret ID / Secret Key / Env ID in config
   • Keep the auth split explicit: management-side login uses auth, while application-side auth configuration uses queryAppAuth / manageAppAuth

---

CloudBase Platform Knowledge

Domain Management Tools: Clear Distinction

When working with domain-related tasks, use the correct tool based on the requirement:

| Requirement | Tool | Parameters | Purpose | |-------------|------|------------|---------| | Security Domain (安全域名) | manageEnv(action="addSecurityDomain" \| "removeSecurityDomain") | domains (array of host:port strings) | CORS/request source validation for browser uploads. No certificate involved. (Deprecated alias: envDomainManagement.) | | Reuse existing Custom Domain | queryGateway(listCustomDomains) → manageGateway(createRoute) | domain = existing custom domain; route fields | Expose a service/path on an already-bound custom domain. No certificateId. Prefer this when a custom domain already exists. | | Bind new Custom Domain (自定义域名) | manageGateway(action="bindCustomDomain") | domain (string), certificateId (string) | First-time bind of a new public HTTPS domain. Requires certId from SSL console. | | Delete Custom Domain | manageGateway(action="deleteCustomDomain") | domain (string) | Remove custom domain binding (only after routes on that domain are deleted). | | Disable / enable gateway route | manageGateway(action="disableRoute" \| "enableRoute") | path (required), prefer explicit domain | Toggle Routes[].Enable via ModifyHTTPServiceRoute (not ModifyGatewayRoute). | | Disable static hosting default domain | queryGateway(listRoutes) → manageGateway(disableRoute) | domain = *.tcloudbaseapp.com (DomainType=STATIC_STORE, IsDefault=true), usually path="/" | Turns off public access on the shared hosting CDN default host. Do not use manageHosting. |

Key indicators for choosing the right tool:

• Task mentions "自定义域名访问" but env already has a custom domain → listCustomDomains then createRoute(domain=...) (no certificateId)
• Task mentions "certificate ID" or "SSL" and needs to bind a new domain → manageGateway(action="bindCustomDomain")
• Task mentions "浏览器上传" or "CORS" or "安全域名" → Use manageEnv(action="addSecurityDomain" / "removeSecurityDomain")
• Task mentions "public access" or "HTTPS" with domain → Prefer reuse via createRoute when possible; only bindCustomDomain for first-time domain bind
• Task mentions "关闭/禁用静态托管默认域名" / *.tcloudbaseapp.com → queryGateway(listRoutes) then manageGateway(disableRoute) with that STATIC_STORE domain; never invent ModifyGatewayRoute
• Task asks about the whole onboarding flow (能不能绑、要等多久、解析怎么配、备案是不是前置) or a bound domain is not reachable → follow ../cloud-api-operations/references/recipes/custom-domain.md: run the read-only VerifyHTTPServiceRoute pre-check first, then bind, then poll Status / DNSStatus. That recipe also covers why domain registration / DNS / ICP calls may return UnauthorizedOperation for an account-level identity.

Error Code Troubleshooting: Route Through Official Docs

When a CloudBase tool call fails and the error message contains a specific error code (pattern Category.Code, e.g. OperationDenied.FreePackageDenied, ResourceNotFound.*), always route through the official docs before acting — do not guess the meaning, do not hardcode fix recipes here:

1. Extract the error code from the error message.
2. Look it up: searchKnowledgeBase(mode="docs", action="searchDocs", query="<错误码>") — official docs search covers error-code pages. Act on the documented meaning and the fix steps the doc prescribes (plan limits → upgrade guidance, misconfiguration → config fix, etc.).
3. If docs search returns nothing, fall back to the canonical error-code pages:
   • Error code basics & self-service troubleshooting: https://docs.cloudbase.net/error-code/basic