cloudbase-guidelines
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseCloudBase 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: (user-level, no project-level JSON config)
~/.codeium/windsurf/mcp_config.json - 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 folder:
.continue/mcpServers/
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:(用户级别,无项目级JSON配置)
~/.codeium/windsurf/mcp_config.json - Cline:查看Cline设置获取项目级MCP配置文件位置
- GitHub Copilot Chat(VS Code):查看VS Code设置获取MCP配置文件位置
格式差异:
- Continue:在文件夹中使用YAML格式:
.continue/mcpServers/
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 (override with ). Prefer for machine-readable results.
./config/mcporter.json--config--output jsonjson
{
"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:
- — list servers/tools
mcporter list - — show tool schema
mcporter list <server> --schema - — call a tool
mcporter call <server.tool> key=value
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 jsonjson
{
"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 - — 显示工具Schema
mcporter list <server> --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 skill for SDK integration, static hosting, and build configuration
web-development - Authentication: Read the and
auth-webskills - Use Web SDK built-in authenticationauth-tool - Database:
- NoSQL: skill
no-sql-web-sdk - MySQL: and
relational-database-webskillsrelational-database-tool
- NoSQL:
- UI Design (Recommended): Read the skill for better UI/UX design guidelines
ui-design
- 平台:阅读技能文档,了解SDK集成、静态托管和构建配置
web-development - 身份认证:阅读和
auth-web技能文档 - 使用Web SDK内置的认证功能auth-tool - 数据库:
- NoSQL:参考技能文档
no-sql-web-sdk - MySQL:参考和
relational-database-web技能文档relational-database-tool
- NoSQL:参考
- UI设计(推荐):阅读技能文档,获取更优的UI/UX设计指南
ui-design
When Developing a Mini Program Project:
开发小程序项目时:
- Platform: Read the skill for project structure, WeChat Developer Tools, and wx.cloud usage
miniprogram-development - Authentication: Read the skill - Naturally login-free, get OPENID in cloud functions
auth-wechat - Database:
- NoSQL: skill
no-sql-wx-mp-sdk - MySQL: skill (via tools)
relational-database-tool
- NoSQL:
- UI Design (Recommended): Read the skill for better UI/UX design guidelines
ui-design
- 平台:阅读技能文档,了解项目结构、微信开发者工具和wx.cloud的使用
miniprogram-development - 身份认证:阅读技能文档 - 天然免登录,在云函数中获取OPENID
auth-wechat - 数据库:
- NoSQL:参考技能文档
no-sql-wx-mp-sdk - MySQL:参考技能文档(通过工具操作)
relational-database-tool
- NoSQL:参考
- UI设计(推荐):阅读技能文档,获取更优的UI/UX设计指南
ui-design
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 usage for all CloudBase operations
http-api - - MySQL database operations (via tools)
relational-database-tool - - Authentication configuration
auth-tool
- ⚠️ 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
- 必备技能:
- - 所有CloudBase操作均需使用HTTP API
http-api - - MySQL数据库操作(通过工具)
relational-database-tool - - 身份认证配置
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 skill
auth-web - Mini Program Projects: Naturally login-free, get in cloud functions, refer to the
wxContext.OPENIDskillauth-wechat - Node.js Backend: Refer to the skill
auth-nodejs
Configuration:
- When user mentions authentication requirements, read the skill to configure authentication providers
auth-tool - 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 skill
no-sql-web-sdk - MySQL Relational Database: Refer to the skill (Web) and
relational-database-webskill (Management)relational-database-tool
Mini Program Projects:
- NoSQL Database: Refer to the skill
no-sql-wx-mp-sdk - MySQL Relational Database: Refer to the skill (via tools)
relational-database-tool
Web项目:
- NoSQL数据库:参考技能文档
no-sql-web-sdk - MySQL关系型数据库:参考技能文档(Web端操作)和
relational-database-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 skill for deployment process
web-development - Remind users that CDN has a few minutes of cache after deployment
Backend Deployment:
- Cloud Functions: Refer to the skill - Runtime cannot be changed after creation, must select correct runtime initially
cloud-functions - CloudRun: Refer to the skill - Ensure backend code supports CORS, prepare Dockerfile for container type
cloudrun-development
静态托管(Web):
- 构建完成后使用CloudBase静态托管
- 部署流程参考技能文档
web-development - 提醒用户部署后CDN会有几分钟的缓存
后端部署:
- 云函数:参考技能文档 - 创建后无法更改运行时,初始创建时必须选择正确的运行时
cloud-functions - CloudRun云托管:参考技能文档 - 确保后端代码支持CORS,容器类型需准备Dockerfile
cloudrun-development
4. UI Design (Recommended)
4. UI设计(推荐)
For better UI/UX design, consider reading the skill which provides:
ui-design- 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项目
- - SDK integration, static hosting, build configuration
web-development - - Web SDK built-in authentication
auth-web - - NoSQL database operations
no-sql-web-sdk - - MySQL database operations (Web)
relational-database-web - - MySQL database management
relational-database-tool - - Cloud storage operations
cloud-storage-web - - AI model calling for Web apps
ai-model-web
- - SDK集成、静态托管、构建配置
web-development - - Web SDK内置认证
auth-web - - NoSQL数据库操作
no-sql-web-sdk - - MySQL数据库操作(Web端)
relational-database-web - - MySQL数据库管理
relational-database-tool - - 云存储操作
cloud-storage-web - - Web应用调用AI模型
ai-model-web
Mini Program Projects
小程序项目
- - Project structure, WeChat Developer Tools, wx.cloud
miniprogram-development - - Authentication (naturally login-free)
auth-wechat - - NoSQL database operations
no-sql-wx-mp-sdk - - MySQL database operations
relational-database-tool - - AI model calling for Mini Program
ai-model-wechat
- - 项目结构、微信开发者工具、wx.cloud使用
miniprogram-development - - 身份认证(天然免登录)
auth-wechat - - NoSQL数据库操作
no-sql-wx-mp-sdk - - MySQL数据库操作
relational-database-tool - - 小程序调用AI模型
ai-model-wechat
Native App Projects
原生应用项目
- - HTTP API usage (MANDATORY - SDK not supported)
http-api - - MySQL database operations (MANDATORY)
relational-database-tool - - Authentication configuration
auth-tool
- - HTTP API使用(必须 - 不支持SDK)
http-api - - MySQL数据库操作(必须)
relational-database-tool - - 身份认证配置
auth-tool
Universal Skills
通用技能
- - Universal CloudBase platform knowledge
cloudbase-platform - - UI design guidelines (recommended)
ui-design - - Standard software engineering process
spec-workflow
- - CloudBase平台通用知识
cloudbase-platform - - UI设计指南(推荐)
ui-design - - 标准软件工程流程
spec-workflow
Professional Skill Reference
专业技能参考
Platform Development Skills
平台开发技能
- Web: - SDK integration, static hosting, build configuration
web-development - Mini Program: - Project structure, WeChat Developer Tools, wx.cloud
miniprogram-development - Cloud Functions: - Cloud function development, deployment, logging, HTTP access
cloud-functions - CloudRun: - Backend deployment (functions/containers)
cloudrun-development - Platform (Universal): - Environment, authentication, services
cloudbase-platform
- Web:- SDK集成、静态托管、构建配置
web-development - 小程序:- 项目结构、微信开发者工具、wx.cloud使用
miniprogram-development - 云函数:- 云函数开发、部署、日志、HTTP访问
cloud-functions - CloudRun云托管:- 后端部署(函数/容器)
cloudrun-development - 平台(通用):- 环境、认证、服务
cloudbase-platform
Authentication Skills
身份认证技能
- Web: - Use Web SDK built-in authentication
auth-web - Mini Program: - Naturally login-free, get OPENID in cloud functions
auth-wechat - Node.js:
auth-nodejs - Auth Tool: - Configure and manage authentication providers
auth-tool
- Web:- 使用Web SDK内置认证
auth-web - 小程序:- 天然免登录,在云函数中获取OPENID
auth-wechat - 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): - Upload, download, temporary URLs, file management
cloud-storage-web
- 云存储(Web):- 上传、下载、临时URL、文件管理
cloud-storage-web
AI Skills
AI技能
- AI Model (Web): - Text generation and streaming via @cloudbase/js-sdk
ai-model-web - AI Model (Node.js): - Text generation, streaming, and image generation via @cloudbase/node-sdk ≥3.16.0
ai-model-nodejs - AI Model (WeChat): - Text generation and streaming with callbacks via wx.cloud.extend.AI
ai-model-wechat
- AI模型(Web):- 通过@cloudbase/js-sdk实现文本生成与流式输出
ai-model-web - AI模型(Node.js):- 通过@cloudbase/node-sdk ≥3.16.0实现文本生成、流式输出与图片生成
ai-model-nodejs - AI模型(微信):- 通过wx.cloud.extend.AI实现带回调的文本生成与流式输出
ai-model-wechat
UI Design Skill
UI设计技能
- - Design thinking framework, frontend aesthetics guidelines (recommended for UI work)
ui-design
- - 设计思维框架、前端美学指南(UI工作推荐)
ui-design
Workflow Skills
工作流技能
- Spec Workflow: - Standard software engineering process (requirements, design, tasks)
spec-workflow
- 规范工作流:- 标准软件工程流程(需求、设计、任务)
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
- Web Projects: Use CloudBase Web SDK built-in authentication (refer to
- 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
- Web项目:使用CloudBase Web SDK内置认证(参考
- 原生应用开发:原生应用不支持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 tools
createFunction- Criteria: function directory contains with cloud function format export:
index.jsexports.main = async (event, context) => {}
- Criteria: function directory contains
- 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 tool for deployment
manageCloudRun - Set MinNum instances to at least 1 to reduce cold start latency
- Only for nodejs cloud functions: deploy directly using
-
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.jsexports.main = async (event, context) => {}
- 判定条件:函数目录包含
- 对于其他语言的后端服务(Java、Go、PHP、Python、Node.js):部署到CloudRun云托管
- 确保后端代码默认支持CORS
- 为容器化部署准备Dockerfile
- 使用工具进行部署
manageCloudRun - 将最小实例数设置为至少1,以降低冷启动延迟
- 仅针对Node.js云函数:使用
-
前端部署(如适用):
- 后端部署完成后,使用返回的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 (概览): - Main dashboard
#/overview - Template Center (模板中心): - Project templates
#/cloud-template/market - Document Database (文档型数据库): - NoSQL collections:
#/db/doc, Models:#/db/doc/collection/${collectionName}#/db/doc/model/${modelName} - MySQL Database (MySQL 数据库): - Tables:
#/db/mysql#/db/mysql/table/default/ - Cloud Functions (云函数): - Function detail:
#/scf#/scf/detail?id=${functionName}&NameSpace=${envId} - CloudRun (云托管): - Container services
#/platform-run - Cloud Storage (云存储): - File storage
#/storage - AI+: - AI capabilities
#/ai - Static Website Hosting (静态网站托管):
#/static-hosting - Identity Authentication (身份认证): - Login:
#/identity, Tokens:#/identity/login-manage#/identity/token-management - Weida Low-Code (微搭低代码):
#/lowcode/apps - Logs & Monitoring (日志监控):
#/devops/log - Extensions (扩展功能):
#/apis - Environment Settings (环境配置):
#/env
- 概览:- 主仪表盘
#/overview - 模板中心:- 项目模板
#/cloud-template/market - 文档型数据库:- NoSQL集合:
#/db/doc,模型:#/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