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项目时:

  1. Platform: Read the
    web-development
    skill for SDK integration, static hosting, and build configuration
  2. Authentication: Read the
    auth-web
    and
    auth-tool
    skills - Use Web SDK built-in authentication
  3. Database:
    • NoSQL:
      no-sql-web-sdk
      skill
    • MySQL:
      relational-database-web
      and
      relational-database-tool
      skills
  4. UI Design (Recommended): Read the
    ui-design
    skill for better UI/UX design guidelines
  1. 平台:阅读
    web-development
    技能文档,了解SDK集成、静态托管和构建配置
  2. 身份认证:阅读
    auth-web
    auth-tool
    技能文档 - 使用Web SDK内置的认证功能
  3. 数据库
    • NoSQL:参考
      no-sql-web-sdk
      技能文档
    • MySQL:参考
      relational-database-web
      relational-database-tool
      技能文档
  4. UI设计(推荐):阅读
    ui-design
    技能文档,获取更优的UI/UX设计指南

When Developing a Mini Program Project:

开发小程序项目时:

  1. Platform: Read the
    miniprogram-development
    skill for project structure, WeChat Developer Tools, and wx.cloud usage
  2. Authentication: Read the
    auth-wechat
    skill - Naturally login-free, get OPENID in cloud functions
  3. Database:
    • NoSQL:
      no-sql-wx-mp-sdk
      skill
    • MySQL:
      relational-database-tool
      skill (via tools)
  4. UI Design (Recommended): Read the
    ui-design
    skill for better UI/UX design guidelines
  1. 平台:阅读
    miniprogram-development
    技能文档,了解项目结构、微信开发者工具和wx.cloud的使用
  2. 身份认证:阅读
    auth-wechat
    技能文档 - 天然免登录,在云函数中获取OPENID
  3. 数据库
    • NoSQL:参考
      no-sql-wx-mp-sdk
      技能文档
    • MySQL:参考
      relational-database-tool
      技能文档(通过工具操作)
  4. UI设计(推荐):阅读
    ui-design
    技能文档,获取更优的UI/UX设计指南

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

开发原生应用项目时(iOS/Android/Flutter/React Native等):

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

  1. ⚠️ 平台限制:原生应用不支持CloudBase SDK - 必须使用HTTP API
  2. 必备技能
    • http-api
      - 所有CloudBase操作均需使用HTTP API
    • relational-database-tool
      - MySQL数据库操作(通过工具)
    • auth-tool
      - 身份认证配置
  3. ⚠️ 数据库限制:仅支持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

核心行为准则

  1. Project Understanding: Read current project's README.md, follow project instructions
  2. Development Order: Prioritize frontend first, then backend
  3. Backend Strategy: Prefer using SDK to directly call CloudBase database, rather than through cloud functions, unless specifically needed
  4. Deployment Order: When there are backend dependencies, prioritize deploying backend before previewing frontend
  5. 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
      )
  6. Native App Development: CloudBase SDK is NOT available for native apps, MUST use HTTP API. Only MySQL database is supported.
  1. 项目理解:阅读当前项目的README.md,遵循项目说明
  2. 开发顺序:优先开发前端,再开发后端
  3. 后端策略:除非有特殊需求,否则优先使用SDK直接调用CloudBase数据库,而非通过云函数
  4. 部署顺序:当存在后端依赖时,优先部署后端,再预览前端
  5. 认证规则:使用内置认证功能,根据平台区分认证方式
    • Web项目:使用CloudBase Web SDK内置认证(参考
      auth-web
    • 小程序项目:天然免登录,在云函数中获取OPENID(参考
      auth-wechat
    • 原生应用:使用HTTP API进行认证(参考
      http-api
  6. 原生应用开发:原生应用不支持CloudBase SDK,必须使用HTTP API。仅支持MySQL数据库。

Deployment Workflow

部署工作流

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

核心功能入口

  1. Overview (概览):
    #/overview
    - Main dashboard
  2. Template Center (模板中心):
    #/cloud-template/market
    - Project templates
  3. Document Database (文档型数据库):
    #/db/doc
    - NoSQL collections:
    #/db/doc/collection/${collectionName}
    , Models:
    #/db/doc/model/${modelName}
  4. MySQL Database (MySQL 数据库):
    #/db/mysql
    - Tables:
    #/db/mysql/table/default/
  5. Cloud Functions (云函数):
    #/scf
    - Function detail:
    #/scf/detail?id=${functionName}&NameSpace=${envId}
  6. CloudRun (云托管):
    #/platform-run
    - Container services
  7. Cloud Storage (云存储):
    #/storage
    - File storage
  8. AI+:
    #/ai
    - AI capabilities
  9. Static Website Hosting (静态网站托管):
    #/static-hosting
  10. Identity Authentication (身份认证):
    #/identity
    - Login:
    #/identity/login-manage
    , Tokens:
    #/identity/token-management
  11. Weida Low-Code (微搭低代码):
    #/lowcode/apps
  12. Logs & Monitoring (日志监控):
    #/devops/log
  13. Extensions (扩展功能):
    #/apis
  14. Environment Settings (环境配置):
    #/env
  1. 概览
    #/overview
    - 主仪表盘
  2. 模板中心
    #/cloud-template/market
    - 项目模板
  3. 文档型数据库
    #/db/doc
    - NoSQL集合:
    #/db/doc/collection/${collectionName}
    ,模型:
    #/db/doc/model/${modelName}
  4. MySQL数据库
    #/db/mysql
    - 表:
    #/db/mysql/table/default/
  5. 云函数
    #/scf
    - 函数详情:
    #/scf/detail?id=${functionName}&NameSpace=${envId}
  6. CloudRun云托管
    #/platform-run
    - 容器服务
  7. 云存储
    #/storage
    - 文件存储
  8. AI+
    #/ai
    - AI能力
  9. 静态网站托管
    #/static-hosting
  10. 身份认证
    #/identity
    - 登录管理:
    #/identity/login-manage
    ,令牌管理:
    #/identity/token-management
  11. 微搭低代码
    #/lowcode/apps
  12. 日志监控
    #/devops/log
  13. 扩展功能
    #/apis
  14. 环境配置
    #/env