cloudbase-guidelines

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CloudBase Development Guidelines

CloudBase 开发指南

💡 Recommended: MCP Installation

💡 推荐：安装MCP

For enhanced CloudBase development experience, we recommend installing CloudBase MCP (Model Context Protocol).

CloudBase MCP provides essential tools for CloudBase development, including environment management, function deployment, database operations, and more. While not required, installing MCP will significantly improve your development workflow.

为提升CloudBase开发体验，我们推荐安装CloudBase MCP（Model Context Protocol）。

CloudBase MCP 为CloudBase开发提供了必备工具，包括环境管理、函数部署、数据库操作等。虽然并非强制要求，但安装MCP将显著优化你的开发工作流。

MCP Configuration Instructions

MCP 配置说明

Most Coding Agents support project-level MCP configuration. The standard JSON configuration structure is:

json

{
  "mcpServers": {
    "cloudbase": {
      "command": "npx",
      "args": ["@cloudbase/cloudbase-mcp@latest"]
    }
  }
}

Project-level configuration file locations:

Cursor:
```
.cursor/mcp.json
```
Claude Code:
```
.mcp.json
```
Windsurf:
```
~/.codeium/windsurf/mcp_config.json
```
(user-level, no project-level JSON config)
Cline: Check Cline settings for project-level MCP configuration file location
GitHub Copilot Chat (VS Code): Check VS Code settings for MCP configuration file location

Format differences:

Continue: Uses YAML format in
```
.continue/mcpServers/
```
folder:

yaml

name: CloudBase MCP
version: 1.0.0
schema: v1
mcpServers:
  - uses: stdio
    command: npx
    args: ["@cloudbase/cloudbase-mcp@latest"]

大多数Coding Agent支持项目级别的MCP配置。标准JSON配置结构如下：

json

{
  "mcpServers": {
    "cloudbase": {
      "command": "npx",
      "args": ["@cloudbase/cloudbase-mcp@latest"]
    }
  }
}

项目级配置文件位置：

Cursor：
```
.cursor/mcp.json
```
Claude Code：
```
.mcp.json
```
Windsurf：
```
~/.codeium/windsurf/mcp_config.json
```
（用户级别，无项目级JSON配置）
Cline：查看Cline设置获取项目级MCP配置文件位置
GitHub Copilot Chat（VS Code）：查看VS Code设置获取MCP配置文件位置

格式差异：

Continue：在
```
.continue/mcpServers/
```
文件夹中使用YAML格式：

yaml

name: CloudBase MCP
version: 1.0.0
schema: v1
mcpServers:
  - uses: stdio
    command: npx
    args: ["@cloudbase/cloudbase-mcp@latest"]

Using mcporter (CLI) When MCP Is Not Available

当无法使用MCP时使用mcporter（CLI）

In environments that do not support MCP (e.g. moltbot) or when users are unsure how to configure MCP, use mcporter as a CLI to call MCP tools. Confirm with the user that Secret ID, Secret Key, and Env ID are set in the mcporter config.

Config: Default

./config/mcporter.json

(override with

--config

). Prefer

--output json

for machine-readable results.

json

{
  "mcpServers": {
    "cloudbase-mcp": {
      "description": "CloudBase MCP",
      "command": "npx",
      "args": ["@cloudbase/cloudbase-mcp@latest"],
      "env": {
        "TENCENTCLOUD_SECRETID": "<your_secret_id>",
        "TENCENTCLOUD_SECRETKEY": "<your_secret_key>",
        "CLOUDBASE_ENV_ID": "<your_env_id>"
      }
    }
  }
}

Quick start:

```
mcporter list
```
— list servers/tools
```
mcporter list <server> --schema
```
— show tool schema
```
mcporter call <server.tool> key=value
```
— call a tool

Call examples:

Selector:

mcporter call linear.list_issues team=ENG limit:5

Function syntax:

mcporter call "linear.create_issue(title: \"Bug\")"

JSON payload:

mcporter call <server.tool> --args '{"limit":5}'

在不支持MCP的环境中（如moltbot），或用户不确定如何配置MCP时，使用mcporter作为CLI工具调用MCP功能。请与用户确认mcporter配置中已设置Secret ID、Secret Key和Env ID。

配置： 默认路径为

./config/mcporter.json

（可通过

--config

参数覆盖）。建议使用

--output json

参数以获得机器可读的结果。

json

{
  "mcpServers": {
    "cloudbase-mcp": {
      "description": "CloudBase MCP",
      "command": "npx",
      "args": ["@cloudbase/cloudbase-mcp@latest"],
      "env": {
        "TENCENTCLOUD_SECRETID": "<your_secret_id>",
        "TENCENTCLOUD_SECRETKEY": "<your_secret_key>",
        "CLOUDBASE_ENV_ID": "<your_env_id>"
      }
    }
  }
}

快速入门：

```
mcporter list
```
— 列出服务器/工具
```
mcporter list <server> --schema
```
— 显示工具Schema
```
mcporter call <server.tool> key=value
```
— 调用工具

调用示例：

选择器方式：

mcporter call linear.list_issues team=ENG limit:5

函数语法：

mcporter call "linear.create_issue(title: \"Bug\")"

JSON负载：

mcporter call <server.tool> --args '{"limit":5}'

Quick Reference

快速参考

When Developing a Web Project:

开发Web项目时：

Platform: Read the
```
web-development
```
skill for SDK integration, static hosting, and build configuration
Authentication: Read the
```
auth-web
```
and
```
auth-tool
```
skills - Use Web SDK built-in authentication

Database:

NoSQL:
```
no-sql-web-sdk
```
skill

MySQL:

relational-database-web

and

relational-database-tool

skills

UI Design (Recommended): Read the
```
ui-design
```
skill for better UI/UX design guidelines

平台：阅读
```
web-development
```
技能文档，了解SDK集成、静态托管和构建配置
身份认证：阅读
```
auth-web
```
和
```
auth-tool
```
技能文档 - 使用Web SDK内置的认证功能
数据库：
- NoSQL：参考
```
no-sql-web-sdk
```
  技能文档
- MySQL：参考
```
relational-database-web
```
  和
```
relational-database-tool
```
  技能文档
UI设计（推荐）：阅读
```
ui-design
```
技能文档，获取更优的UI/UX设计指南

When Developing a Mini Program Project:

开发小程序项目时：

Platform: Read the
```
miniprogram-development
```
skill for project structure, WeChat Developer Tools, and wx.cloud usage
Authentication: Read the
```
auth-wechat
```
skill - Naturally login-free, get OPENID in cloud functions
Database:
- NoSQL:
```
no-sql-wx-mp-sdk
```
  skill
- MySQL:
```
relational-database-tool
```
  skill (via tools)
UI Design (Recommended): Read the
```
ui-design
```
skill for better UI/UX design guidelines

平台：阅读
```
miniprogram-development
```
技能文档，了解项目结构、微信开发者工具和wx.cloud的使用
身份认证：阅读
```
auth-wechat
```
技能文档 - 天然免登录，在云函数中获取OPENID
数据库：
- NoSQL：参考
```
no-sql-wx-mp-sdk
```
  技能文档
- MySQL：参考
```
relational-database-tool
```
  技能文档（通过工具操作）
UI设计（推荐）：阅读
```
ui-design
```
技能文档，获取更优的UI/UX设计指南

When Developing a Native App Project (iOS/Android/Flutter/React Native/etc.):

开发原生应用项目时（iOS/Android/Flutter/React Native等）：

⚠️ Platform Limitation: Native apps do NOT support CloudBase SDK - Must use HTTP API
Required Skills:
- ```
http-api
```
  - HTTP API usage for all CloudBase operations
- ```
relational-database-tool
```
  - MySQL database operations (via tools)
- ```
auth-tool
```
  - Authentication configuration
⚠️ Database Limitation: Only MySQL database is supported. If users need MySQL, prompt them to enable it in console: CloudBase Console - MySQL Database

⚠️ 平台限制：原生应用不支持CloudBase SDK - 必须使用HTTP API
必备技能：
- ```
http-api
```
  - 所有CloudBase操作均需使用HTTP API
- ```
relational-database-tool
```
  - MySQL数据库操作（通过工具）
- ```
auth-tool
```
  - 身份认证配置
⚠️ 数据库限制：仅支持MySQL数据库。若用户需要使用MySQL，请提示其在控制台中启用：CloudBase控制台 - MySQL数据库

Core Capabilities

核心能力

1. Authentication

1. 身份认证

Authentication Methods by Platform:

Web Projects: Use CloudBase Web SDK built-in authentication, refer to the
```
auth-web
```
skill
Mini Program Projects: Naturally login-free, get
```
wxContext.OPENID
```
in cloud functions, refer to the
```
auth-wechat
```
skill
Node.js Backend: Refer to the
```
auth-nodejs
```
skill

Configuration:

When user mentions authentication requirements, read the
```
auth-tool
```
skill to configure authentication providers
Check and enable required authentication methods before implementing frontend code

各平台认证方式：

Web项目：使用CloudBase Web SDK内置认证功能，参考
```
auth-web
```
技能文档
小程序项目：天然免登录，在云函数中获取
```
wxContext.OPENID
```
，参考
```
auth-wechat
```
技能文档
Node.js后端：参考
```
auth-nodejs
```
技能文档

配置说明：

当用户提及认证需求时，阅读
```
auth-tool
```
技能文档以配置认证提供商
在实现前端代码前，检查并启用所需的认证方式

2. Database Operations

2. 数据库操作

Web Projects:

NoSQL Database: Refer to the
```
no-sql-web-sdk
```
skill
MySQL Relational Database: Refer to the
```
relational-database-web
```
skill (Web) and
```
relational-database-tool
```
skill (Management)

Mini Program Projects:

NoSQL Database: Refer to the
```
no-sql-wx-mp-sdk
```
skill
MySQL Relational Database: Refer to the
```
relational-database-tool
```
skill (via tools)

Web项目：

NoSQL数据库：参考
```
no-sql-web-sdk
```
技能文档
MySQL关系型数据库：参考
```
relational-database-web
```
技能文档（Web端操作）和
```
relational-database-tool
```
技能文档（管理操作）

小程序项目：

NoSQL数据库：参考
```
no-sql-wx-mp-sdk
```
技能文档
MySQL关系型数据库：参考
```
relational-database-tool
```
技能文档（通过工具操作）

3. Deployment

3. 部署

Static Hosting (Web):

Use CloudBase static hosting after build completion
Refer to the
```
web-development
```
skill for deployment process
Remind users that CDN has a few minutes of cache after deployment

Backend Deployment:

Cloud Functions: Refer to the
```
cloud-functions
```
skill - Runtime cannot be changed after creation, must select correct runtime initially
CloudRun: Refer to the
```
cloudrun-development
```
skill - Ensure backend code supports CORS, prepare Dockerfile for container type

静态托管（Web）：

构建完成后使用CloudBase静态托管
部署流程参考
```
web-development
```
技能文档
提醒用户部署后CDN会有几分钟的缓存

后端部署：

云函数：参考
```
cloud-functions
```
技能文档 - 创建后无法更改运行时，初始创建时必须选择正确的运行时
CloudRun云托管：参考
```
cloudrun-development
```
技能文档 - 确保后端代码支持CORS，容器类型需准备Dockerfile

4. UI Design (Recommended)

4. UI设计（推荐）

For better UI/UX design, consider reading the

ui-design

skill which provides:

Design thinking framework
Frontend aesthetics guidelines
Best practices for creating distinctive and high-quality interfaces

为获得更优的UI/UX设计，建议阅读

ui-design

技能文档，其中包含：

设计思维框架
前端美学指南
创建独特高品质界面的最佳实践

Platform-Specific Skills

平台专属技能

Web Projects

Web项目

```
web-development
```
- SDK integration, static hosting, build configuration
```
auth-web
```
- Web SDK built-in authentication
```
no-sql-web-sdk
```
- NoSQL database operations
```
relational-database-web
```
- MySQL database operations (Web)
```
relational-database-tool
```
- MySQL database management
```
cloud-storage-web
```
- Cloud storage operations
```
ai-model-web
```
- AI model calling for Web apps

```
web-development
```
- SDK集成、静态托管、构建配置
```
auth-web
```
- Web SDK内置认证
```
no-sql-web-sdk
```
- NoSQL数据库操作
```
relational-database-web
```
- MySQL数据库操作（Web端）
```
relational-database-tool
```
- MySQL数据库管理
```
cloud-storage-web
```
- 云存储操作
```
ai-model-web
```
- Web应用调用AI模型

Mini Program Projects

小程序项目

```
miniprogram-development
```
- Project structure, WeChat Developer Tools, wx.cloud
```
auth-wechat
```
- Authentication (naturally login-free)
```
no-sql-wx-mp-sdk
```
- NoSQL database operations
```
relational-database-tool
```
- MySQL database operations
```
ai-model-wechat
```
- AI model calling for Mini Program

```
miniprogram-development
```
- 项目结构、微信开发者工具、wx.cloud使用
```
auth-wechat
```
- 身份认证（天然免登录）
```
no-sql-wx-mp-sdk
```
- NoSQL数据库操作
```
relational-database-tool
```
- MySQL数据库操作
```
ai-model-wechat
```
- 小程序调用AI模型

Native App Projects

原生应用项目

```
http-api
```
- HTTP API usage (MANDATORY - SDK not supported)
```
relational-database-tool
```
- MySQL database operations (MANDATORY)
```
auth-tool
```
- Authentication configuration

```
http-api
```
- HTTP API使用（必须 - 不支持SDK）
```
relational-database-tool
```
- MySQL数据库操作（必须）
```
auth-tool
```
- 身份认证配置

Universal Skills

通用技能

```
cloudbase-platform
```
- Universal CloudBase platform knowledge
```
ui-design
```
- UI design guidelines (recommended)
```
spec-workflow
```
- Standard software engineering process

```
cloudbase-platform
```
- CloudBase平台通用知识
```
ui-design
```
- UI设计指南（推荐）
```
spec-workflow
```
- 标准软件工程流程

Professional Skill Reference

专业技能参考

Platform Development Skills

平台开发技能

Web:
```
web-development
```
- SDK integration, static hosting, build configuration
Mini Program:
```
miniprogram-development
```
- Project structure, WeChat Developer Tools, wx.cloud
Cloud Functions:
```
cloud-functions
```
- Cloud function development, deployment, logging, HTTP access
CloudRun:
```
cloudrun-development
```
- Backend deployment (functions/containers)
Platform (Universal):
```
cloudbase-platform
```
- Environment, authentication, services

Web：
```
web-development
```
- SDK集成、静态托管、构建配置
小程序：
```
miniprogram-development
```
- 项目结构、微信开发者工具、wx.cloud使用
云函数：
```
cloud-functions
```
- 云函数开发、部署、日志、HTTP访问
CloudRun云托管：
```
cloudrun-development
```
- 后端部署（函数/容器）
平台（通用）：
```
cloudbase-platform
```
- 环境、认证、服务

Authentication Skills

身份认证技能

Web:
```
auth-web
```
- Use Web SDK built-in authentication
Mini Program:
```
auth-wechat
```
- Naturally login-free, get OPENID in cloud functions
Node.js:
```
auth-nodejs
```
Auth Tool:
```
auth-tool
```
- Configure and manage authentication providers

Web：
```
auth-web
```
- 使用Web SDK内置认证
小程序：
```
auth-wechat
```
- 天然免登录，在云函数中获取OPENID
Node.js：
```
auth-nodejs
```
认证工具：
```
auth-tool
```
- 配置和管理认证提供商

Database Skills

数据库技能

NoSQL (Web):
```
no-sql-web-sdk
```
NoSQL (Mini Program):
```
no-sql-wx-mp-sdk
```
MySQL (Web):
```
relational-database-web
```
MySQL (Tool):
```
relational-database-tool
```

NoSQL（Web）：
```
no-sql-web-sdk
```
NoSQL（小程序）：
```
no-sql-wx-mp-sdk
```
MySQL（Web）：
```
relational-database-web
```
MySQL（工具）：
```
relational-database-tool
```

Storage Skills

存储技能

Cloud Storage (Web):
```
cloud-storage-web
```
- Upload, download, temporary URLs, file management

云存储（Web）：
```
cloud-storage-web
```
- 上传、下载、临时URL、文件管理

AI Skills

AI技能

AI Model (Web):
```
ai-model-web
```
- Text generation and streaming via @cloudbase/js-sdk
AI Model (Node.js):
```
ai-model-nodejs
```
- Text generation, streaming, and image generation via @cloudbase/node-sdk ≥3.16.0
AI Model (WeChat):
```
ai-model-wechat
```
- Text generation and streaming with callbacks via wx.cloud.extend.AI

AI模型（Web）：
```
ai-model-web
```
- 通过@cloudbase/js-sdk实现文本生成与流式输出
AI模型（Node.js）：
```
ai-model-nodejs
```
- 通过@cloudbase/node-sdk ≥3.16.0实现文本生成、流式输出与图片生成
AI模型（微信）：
```
ai-model-wechat
```
- 通过wx.cloud.extend.AI实现带回调的文本生成与流式输出

UI Design Skill

UI设计技能

ui-design
- Design thinking framework, frontend aesthetics guidelines (recommended for UI work)

ui-design
- 设计思维框架、前端美学指南（UI工作推荐）

Workflow Skills

工作流技能

Spec Workflow:
```
spec-workflow
```
- Standard software engineering process (requirements, design, tasks)

规范工作流：
```
spec-workflow
```
- 标准软件工程流程（需求、设计、任务）

Core Behavior Rules

核心行为准则

Project Understanding: Read current project's README.md, follow project instructions
Development Order: Prioritize frontend first, then backend
Backend Strategy: Prefer using SDK to directly call CloudBase database, rather than through cloud functions, unless specifically needed
Deployment Order: When there are backend dependencies, prioritize deploying backend before previewing frontend
Authentication Rules: Use built-in authentication functions, distinguish authentication methods by platform
- Web Projects: Use CloudBase Web SDK built-in authentication (refer to
```
auth-web
```
  )
- Mini Program Projects: Naturally login-free, get OPENID in cloud functions (refer to
```
auth-wechat
```
  )
- Native Apps: Use HTTP API for authentication (refer to
```
http-api
```
  )
Native App Development: CloudBase SDK is NOT available for native apps, MUST use HTTP API. Only MySQL database is supported.

项目理解：阅读当前项目的README.md，遵循项目说明
开发顺序：优先开发前端，再开发后端
后端策略：除非有特殊需求，否则优先使用SDK直接调用CloudBase数据库，而非通过云函数
部署顺序：当存在后端依赖时，优先部署后端，再预览前端
认证规则：使用内置认证功能，根据平台区分认证方式
- Web项目：使用CloudBase Web SDK内置认证（参考
```
auth-web
```
  ）
- 小程序项目：天然免登录，在云函数中获取OPENID（参考
```
auth-wechat
```
  ）
- 原生应用：使用HTTP API进行认证（参考
```
http-api
```
  ）
原生应用开发：原生应用不支持CloudBase SDK，必须使用HTTP API。仅支持MySQL数据库。

Deployment Workflow

部署工作流

When users request deployment to CloudBase:

Check Existing Deployment:
- Read README.md to check for existing deployment information
- Identify previously deployed services and their URLs
- Determine if this is a new deployment or update to existing services
Backend Deployment (if applicable):
- Only for nodejs cloud functions: deploy directly using
```
createFunction
```
  tools
  - Criteria: function directory contains
```
index.js
```
    with cloud function format export:
```
exports.main = async (event, context) => {}
```
- For other languages backend server (Java, Go, PHP, Python, Node.js): deploy to Cloud Run
- Ensure backend code supports CORS by default
- Prepare Dockerfile for containerized deployment
- Use
```
manageCloudRun
```
  tool for deployment
- Set MinNum instances to at least 1 to reduce cold start latency
Frontend Deployment (if applicable):
- After backend deployment completes, update frontend API endpoints using the returned API addresses
- Build the frontend application
- Deploy to CloudBase static hosting using hosting tools
Display Deployment URLs:
- Show backend deployment URL (if applicable)
- Show frontend deployment URL with trailing slash (/) in path
- Add random query string to frontend URL to ensure CDN cache refresh
Update Documentation:
- Write deployment information and service details to README.md
- Include backend API endpoints and frontend access URLs
- Document CloudBase resources used (functions, cloud run, hosting, database, etc.)
- This helps with future updates and maintenance

当用户请求部署到CloudBase时：

检查现有部署：
- 阅读README.md查看现有部署信息
- 确认已部署的服务及其URL
- 判断是新部署还是对现有服务的更新
后端部署（如适用）：
- 仅针对Node.js云函数：使用
```
createFunction
```
  工具直接部署
  - 判定条件：函数目录包含
```
index.js
```
    ，且以云函数格式导出：
```
exports.main = async (event, context) => {}
```
- 对于其他语言的后端服务（Java、Go、PHP、Python、Node.js）：部署到CloudRun云托管
- 确保后端代码默认支持CORS
- 为容器化部署准备Dockerfile
- 使用
```
manageCloudRun
```
  工具进行部署
- 将最小实例数设置为至少1，以降低冷启动延迟
前端部署（如适用）：
- 后端部署完成后，使用返回的API地址更新前端API端点
- 构建前端应用
- 使用托管工具部署到CloudBase静态托管
展示部署URL：
- 展示后端部署URL（如适用）
- 展示前端部署URL，路径末尾需包含斜杠（/）
- 向前端URL添加随机查询字符串，确保CDN缓存刷新
更新文档：
- 将部署信息和服务详情写入README.md
- 包含后端API端点和前端访问URL
- 记录使用的CloudBase资源（函数、云托管、托管、数据库等）
- 这将有助于后续的更新和维护

CloudBase Console Entry Points

CloudBase控制台入口

After creating/deploying resources, provide corresponding console management page links. All console URLs follow the pattern:

https://tcb.cloud.tencent.com/dev?envId=${envId}#/{path}

创建/部署资源后，提供对应的控制台管理页面链接。所有控制台URL遵循以下格式：

https://tcb.cloud.tencent.com/dev?envId=${envId}#/{path}

Core Function Entry Points

核心功能入口

Overview (概览):
```
#/overview
```
- Main dashboard
Template Center (模板中心):
```
#/cloud-template/market
```
- Project templates

Document Database (文档型数据库):

#/db/doc

- NoSQL collections:

#/db/doc/collection/${collectionName}

, Models:

#/db/doc/model/${modelName}

MySQL Database (MySQL 数据库):
```
#/db/mysql
```
- Tables:
```
#/db/mysql/table/default/
```

Cloud Functions (云函数):

#/scf

- Function detail:

#/scf/detail?id=${functionName}&NameSpace=${envId}

CloudRun (云托管):
```
#/platform-run
```
- Container services
Cloud Storage (云存储):
```
#/storage
```
- File storage
AI+:
```
#/ai
```
- AI capabilities
Static Website Hosting (静态网站托管):
```
#/static-hosting
```

Identity Authentication (身份认证):

#/identity

- Login:

#/identity/login-manage

, Tokens:

#/identity/token-management

Weida Low-Code (微搭低代码):
```
#/lowcode/apps
```
Logs & Monitoring (日志监控):
```
#/devops/log
```
Extensions (扩展功能):
```
#/apis
```
Environment Settings (环境配置):
```
#/env
```

概览：
```
#/overview
```
- 主仪表盘
模板中心：
```
#/cloud-template/market
```
- 项目模板

文档型数据库：

#/db/doc

- NoSQL集合：

#/db/doc/collection/${collectionName}

，模型：

#/db/doc/model/${modelName}

MySQL数据库：
```
#/db/mysql
```
- 表：
```
#/db/mysql/table/default/
```

云函数：

#/scf

- 函数详情：

#/scf/detail?id=${functionName}&NameSpace=${envId}

CloudRun云托管：
```
#/platform-run
```
- 容器服务
云存储：
```
#/storage
```
- 文件存储
AI+：
```
#/ai
```
- AI能力
静态网站托管：
```
#/static-hosting
```

身份认证：

#/identity

- 登录管理：

#/identity/login-manage

，令牌管理：

#/identity/token-management

微搭低代码：
```
#/lowcode/apps
```
日志监控：
```
#/devops/log
```
扩展功能：
```
#/apis
```
环境配置：
```
#/env
```