腾讯云 CloudBase

使用腾讯云 CloudBase 开发时遇到的核心问题

在使用腾讯云 CloudBase 构建全栈应用时，开发者常面临一个关键挑战：如何在复杂的技术栈和多个后端服务间做出正确的技术决策与集成。具体场景包括：

• 路由混乱：面对 Web 认证、微信小程序、关系型数据库、云函数、云托管以及 AI 模型调用等多种场景时，不清楚应该优先参考哪个技术文档或使用哪套 API。
• 集成顺序错误：例如，在编写前端认证 UI 代码之前，没有先配置好后端认证提供商，导致流程中断。
• 工具链选择困难：不清楚在当前会话中应优先使用 MCP 工具、tcb CLI 还是其他 SDK，以及它们之间的依赖关系和回退策略。
• 违反隐式规则：例如，在首次部署 Web 前端时错误地使用了托管更新接口，而非专用的应用创建流程。

技能的工作机制：结构化指南与强制规则

该技能（@tencent-adm/cloudbase）并非一个简单的代码片段集合，而是一套高度结构化的开发决策框架。它通过以下核心机制来解决上述问题：

1. 基于场景的路由表：提供了一个详细的路由表，将常见的开发需求（如“Web 登录”、“云函数开发”、“AI 模型调用”）映射到具体的、应首先阅读的子技能文档（如 auth-web-cloudbase、cloud-functions、ai-model-web）。这强制开发者在动手前先获取正确的上下文。

1. 强制性工作流与前置条件：定义了不可跳过的阶段。例如，阶段 2a 必须在前端代码之前完成（通常涉及后端资源准备），且某些步骤是强制的。这确保了开发遵循安全的、正确的顺序。

1. 全局规则与工程宪法：设定了一系列超越便利性的基础规则，例如：

- 始终明确指定 EnvId，禁止依赖隐式环境状态。
- 在编写前端代码前，必须先准备好后端资源（如认证提供商、数据库表、存储桶），优先通过 MCP 工具完成。
- 禁止使用 any 来绕过类型错误。
- 完成工作后必须进行自验证（包括静态类型检查和运行时测试）。

1. 清晰的工具链回退策略：明确了在首选工具（如 MCP）不可用时，如何通过 tcb CLI 和本地参考文件继续工作，避免开发流程停滞。

适用边界与关键注意事项

尽管该技能提供了全面的指引，开发者仍需注意其适用范围和几个关键点：

• 专注于 CloudBase 生态：其路由和规则紧密围绕腾讯云 CloudBase 的服务（如云函数、云托管、关系型数据库、文档数据库）和集成模式（如微信小程序、Web SDK、OpenAPI）。
• 前端部署的特殊性：对于 Web 项目的首次前端部署，必须使用 manageApps(action="createApp", ...)。之后的更新才可使用 manageHosting。这是常见的一个坑点。
• AI 模型调用的资格检查：在调用大模型 API 之前，必须先运行 DescribeEnvPostpayPackage（检查 Token Credits 资源包）和 DescribeActivityInfo（检查小程序成长计划资格），否则调用可能失败。
• 技术栈区分：需要严格区分 CloudBase PostgreSQL 路径（使用 app.rdb()、queryPgDatabase）和传统的 NoSQL/MySQL 路径。混淆这两者会导致权限模型和 SDK 使用上的根本错误。