mcpField
C
cloudbase-guidelines

cloudbase-guidelines

github.com/tencentcloudbase云与 DevOps1.2k38 次安装今天更新
代码仓库

关于 cloudbase-guidelines

cloudbase-guidelines 是面向使用 CloudBase 构建 Web、微信小程序和原生应用的编码 Agent 技能，整理了平台开发指引，并说明 MCP 配置与命令行替代方案。

主要功能

  1. 01按平台整理 CloudBase 开发指南
  2. 02认证与数据库选型建议
  3. 03部署流程指引
  4. 04MCP 配置与 mcporter 命令行说明

适用场景

  1. 01规划 CloudBase Web 项目
  2. 02开发微信小程序
  3. 03使用 CloudBase 开发原生应用
  4. 04部署 CloudBase 前后端

MCP 相关

建议为编码 Agent 配置 @cloudbase/cloudbase-mcp 服务；MCP 不可用时，也介绍通过 mcporter 列出和调用 MCP 工具。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/tencentcloudbase/cloudbase-ai-toolkit --skill cloudbase-guidelines

安装后在 Claude Code 中输入/cloudbase-guidelines确认已加载。

详细介绍

CloudBase 开发指南

💡 推荐：安装 MCP

为获得更出色的 CloudBase 开发体验，我们建议安装 CloudBase MCP（模型上下文协议）。

CloudBase MCP 提供了 CloudBase 开发所需的基本工具，包括环境管理、函数部署、数据库操作等。虽然并非必需，但安装 MCP 将显著改善您的开发工作流。

MCP 配置说明

大多数编码 Agent 都支持项目级 MCP 配置。标准 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 格式：
name: CloudBase MCP
version: 1.0.0
schema: v1
mcpServers:
  - uses: stdio
    command: npx
    args: ["@cloudbase/cloudbase-mcp@latest"]
MCP 不可用时使用 mcporter（CLI）

在不支持 MCP 的环境（例如 moltbot）中，或用户不确定如何配置 MCP 时，请使用 mcporter 命令行调用 MCP 工具。请向用户确认，mcporter 配置中已设置 Secret ID、Secret Key 和 Env ID。

**配置：**默认使用 ./config/mcporter.json（可通过 --config 覆盖）。建议使用 --output 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 — 显示工具架构
  • 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}'

快速参考

开发 Web 项目时：
  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 设计指南
开发小程序项目时：
  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 设计指南
开发原生应用项目（iOS/Android/Flutter/React Native 等）时：
  1. ⚠️ 平台限制：原生应用不支持 CloudBase SDK——必须使用 HTTP API
  2. 必需技能：
    • http-api — 用于所有 CloudBase 操作的 HTTP API 用法
    • relational-database-tool — MySQL 数据库操作（通过工具）
    • auth-tool — 身份验证配置
  3. ⚠️ 数据库限制：仅支持 MySQL 数据库。如果用户需要 MySQL，请提示他们在控制台中启用：CloudBase 控制台 - MySQL 数据库

核心功能

1. 身份验证

各平台的身份验证方式：

  • Web 项目：使用 CloudBase Web SDK 内置的身份验证，请参阅 auth-web 技能
  • 小程序项目：无需登录，可在云函数中获取 wxContext.OPENID，请参阅 auth-wechat 技能
  • Node.js 后端：请参阅 auth-nodejs 技能

配置：

  • 用户提及身份验证需求时，请阅读 auth-tool 技能以配置身份验证提供方
  • 在实现前端代码之前，检查并启用所需的身份验证方式
2. 数据库操作

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. 部署

静态托管（Web）：

  • 构建完成后使用 CloudBase 静态托管
  • 部署流程请参阅 web-development 技能
  • 提醒用户，部署后 CDN 缓存会持续几分钟

后端部署：

  • 云函数：请参阅 cloud-functions 技能——创建后无法更改运行时，必须在初始创建时选择正确的运行时
  • CloudRun：请参阅 cloudrun-development 技能——确保后端代码支持 CORS，并为容器类型准备 Dockerfile
4. UI 设计（推荐）

若要获得更好的 UI/UX 设计，可考虑阅读 ui-design 技能，其中提供：

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

平台专属技能

Web 项目
  • 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 模型调用
小程序项目
  • miniprogram-development - 项目结构、微信开发者工具、wx.cloud
  • auth-wechat - 身份验证（无需登录）
  • no-sql-wx-mp-sdk - NoSQL 数据库操作
  • relational-database-tool - MySQL 数据库操作
  • ai-model-wechat - 小程序的 AI 模型调用
原生应用项目
  • http-api - HTTP API 用法（必需——不支持 SDK）
  • relational-database-tool - MySQL 数据库操作（必需）
  • auth-tool - 身份验证配置
通用技能
  • cloudbase-platform - 通用 CloudBase 平台知识
  • ui-design - UI 设计指南（推荐）
  • spec-workflow - 标准软件工程流程

专业技能参考

平台开发技能
  • Web：web-development - SDK 集成、静态托管、构建配置
  • 小程序：miniprogram-development - 项目结构、微信开发者工具、wx.cloud
  • 云函数：cloud-functions - 云函数开发、部署、日志、HTTP 访问
  • CloudRun：cloudrun-development - 后端部署（函数/容器）
  • 平台（通用）：cloudbase-platform - 环境、身份验证、服务
身份验证技能
  • Web：auth-web - 使用 Web SDK 内置的身份验证
  • 小程序：auth-wechat - 无需登录，可在云函数中获取 OPENID
  • Node.js：auth-nodejs
  • 身份验证工具：auth-tool - 配置和管理身份验证提供方
数据库技能
  • NoSQL（Web）：no-sql-web-sdk
  • NoSQL（小程序）：no-sql-wx-mp-sdk
  • MySQL（Web）：relational-database-web
  • MySQL（工具）：relational-database-tool
存储技能
  • 云存储（Web）：cloud-storage-web - 上传、下载、临时 URL、文件管理
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 设计技能
  • ui-design - 设计思维框架、前端美学指南（推荐用于 UI 工作）
工作流技能
  • 规范工作流：spec-workflow - 标准软件工程流程（需求、设计、任务）

核心行为规则

  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 数据库。

部署工作流

当用户请求部署到 CloudBase 时：

  1. 检查现有部署：

    • 阅读 README.md，检查是否已有部署信息
    • 找出之前部署的服务及其 URL
    • 判断这是新部署还是更新现有服务

  2. 后端部署（如适用）：

    • 仅对于 Node.js 云函数：使用 createFunction 工具直接部署
      • 判断标准：函数目录包含 index.js，其中以云函数格式导出：exports.main = async (event, context) => {}
    • 其他语言的后端服务（Java、Go、PHP、Python、Node.js）：部署到 Cloud Run
    • 确保后端代码默认支持 CORS
    • 准备 Dockerfile 以便容器化部署
    • 使用 manageCloudRun 工具部署
    • 将 MinNum 实例数设为至少 1，以降低冷启动延迟

  3. 前端部署（如适用）：

    • 后端部署完成后，使用返回的 API 地址更新前端 API 端点
    • 构建前端应用
    • 使用托管工具部署到 CloudBase 静态托管

  4. 显示部署 URL：

    • 显示后端部署 URL（如适用）
    • 显示路径末尾带斜杠（/）的前端部署 URL
    • 为前端 URL 添加随机查询字符串，确保 CDN 缓存刷新

  5. 更新文档：

    • 将部署信息和服务详情写入 README.md
    • 包含后端 API 端点和前端访问 URL
    • 记录使用的 CloudBase 资源（函数、cloud run、托管、数据库等）
    • 这有助于后续更新和维护

CloudBase 控制台入口

创建或部署资源后，提供相应的控制台管理页面链接。所有控制台 URL 均遵循以下格式：https://tcb.cloud.tencent.com/dev?envId=${envId}#/{path}

核心功能入口
  1. 概览（概览）：#/overview - 主控制台
  2. 模板中心（模板中心）：#/cloud-template/market - 项目模板
  3. 文档型数据库（文档型数据库）：#/db/doc - NoSQL 集合：#/db/doc/collection/${collectionName}，模型：#/db/doc/model/${modelName}
  4. MySQL 数据库（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

评论

支持 Markdown