cloudbase

CloudBase 开发指南

步骤 0 — 确认站点（国内站还是国际站）

CloudBase 有两套独立的账号系统：国内站（cloud.tencent.com）和国际站（tencentcloud.com）。环境、控制台、API 密钥和登录状态不会跨站通用。登录了错误的站点时，通常会表现为*“已登录，但看不到环境”*，而不是明确的错误提示——因此，在安装 MCP、登录或绑定环境之前，先确认站点。

尽可能根据现有信息推断（控制台域名、envId、现有错误）；否则询问用户一次。不要猜测。

	国内站 domestic	国际站 international
远程 MCP（首选）	https://tcb-api.cloud.tencent.com/mcp/v1	https://tcb-api.tencentcloud.com/mcp/v1
本地 stdio MCP	无需设置（TCB_SITE 默认值为国内站）	TCB_SITE=intl + TCB_REGION=ap-singapore
tcb CLI	默认	TCB_IS_INTL=true（或 tcb config set isIntl true）
项目记录 .cloudbase/project.json	省略 site，或设为 "domestic"	"site": "intl"、"region": "ap-singapore"
控制台	tcb.cloud.tencent.com	tcb.tencentcloud.com
默认区域	ap-shanghai	ap-singapore
NoSQL / 文档数据库工具	可用	不可用

• 默认连接远程服务。 两个主机地址都是正式端点：OAuth 负责登录，主机名决定站点，因此无需传递 site 参数。国际站：https://tcb-api.tencentcloud.com/mcp/v1；国内站：https://tcb-api.cloud.tencent.com/mcp/v1。
• 仅在有特定需求时使用本地 stdio——账号通过 CloudBase API 密钥登录、一个会话必须同时覆盖两个站点（远程 URL 只能绑定一个站点），或任务需要使用托管端点未注册的工具。部署函数或应用不是使用本地 stdio 的理由：通过两步上传即可远程完成部署。对比说明：references/mcp-setup.md。
• TCB_IS_INTL（CLI）和 TCB_SITE（MCP）是用于不同工具的不同变量名。设置与当前使用工具相对应的变量；设置错误的变量不会产生任何效果，也不会提示。
• 首次运行时，一次性确认站点并保存设置——CLI 开关作用于整台机器，MCP 开关则针对每个客户端；只有 .cloudbase/project.json 的作用范围是项目，并且 MCP 可在重启后读取它。请遵循 references/site-onboarding.md；后续会话中不要再次询问。

详细信息和可直接复制的配置：references/mcp-setup.md。CLI 详情：references/tooling-fallback.md。首次运行协调流程（触发/跳过、冲突仲裁、MCP 不可用时的回退）：references/site-onboarding.md。

工作流

1. Exploration  →  Read the matching skill completely before writing any code.
                   Search with searchKnowledgeBase(mode="skill"), then Read full SKILL.md.
2. Implementation
   ├── 2a. Resource preparation → Prefer MCP; if MCP tools are missing in THIS session,
   │     configure MCP for next session and use `tcb` CLI now (see tooling-fallback.md)
   └── 2b. Frontend implementation → Write code, install deps, start server, test
3. Close-out  →  Run cloudbase-code-review, fix errors, declare done
                   (after a verified deploy: optionally offer Deployment Share once — see references/deployment-workflow.md §5)

关键约束： 阶段 2a 必须先于前端代码。阶段 3 为必需阶段。

激活约定

路由使用稳定的技能 ID（auth-tool-cloudbase、auth-web-cloudbase、http-api-cloudbase……），并在源文件、生成的构件和安装包中保持一致。

独立技能回退

如果仅提供一个已发布的技能：

• 如果工作区中存在相关文件，优先使用本地相对路径（references/<skill-id>/SKILL.md 或同级技能目录）。
• 不要从远程 raw URL 获取同级技能的 Markdown 文件并放入 Agent 上下文。
• 如果本地缺少必需的同级技能，请让用户安装完整的 CloudBase 技能包或 IDE 插件（npx skills add tencentcloudbase/cloudbase-skills）。如果因缺少 git 而安装失败，请使用 references/mcp-setup.md 中的 tarball 路径，然后继续仅使用本地文件。

从当前技能所在位置使用相对路径 references/...。如果当前会话中 MCP 不可用，请遵循 references/tooling-fallback.md：按照 references/mcp-setup.md 配置 MCP，供下次会话使用；现在则通过 cloudbase-cli 技能使用 tcb CLI 完成登录和管理（阅读 core.md 和匹配的领域参考文档——不要使用 tcb deploy）。如果缺少 npm/npx，请遵循 tooling-fallback.md 中的“No npm/npx”章节。

执行前的通用规则

• 先识别场景，再阅读匹配的技能，然后编写代码或调用 CloudBase API。
• 维护工具包时，优先使用语义化来源；在运行时路由中使用稳定的技能 ID。
• 如果本次会话中有 MCP 或 mcporter，可用它们执行管理任务；执行前先检查工具架构。如果暂时无法使用，不要停滞不前——使用 references/tooling-fallback.md 中的 CLI 备用方案。
• 无论是连接 MCP（本地 stdio 还是远程）、通过 mcporter 在 shell 中调用工具、切换站点／区域／插件，还是修复这个开源仓库，都要阅读 cloudbase-mcp。
• UI 任务：先阅读 ui-design，并在编写界面代码前输出设计规范。
• Auth 任务：先阅读 auth-tool-cloudbase，并在实现前端前启用提供商。
• 区分 Auth 域：管理端登录使用 auth（或在 MCP Auth 不可用时使用 tcb login）；应用侧 Auth 使用 queryAppAuth / manageAppAuth。

通用防护规则

• 在同一路径上失败 2–3 次后，应停止尝试并改用其他路径（平台技能、运行时、Auth 域、权限模型或 SDK 边界）。
• 始终显式指定 EnvId；不要依赖 CLI 选定的环境或隐式环境状态。
• 当环境标识符是别名、昵称或其他短名称时，不要直接将其传给 auth.set_env、SDK 初始化、控制台 URL 或生成的配置。先使用 queryEnv(action=list, alias=..., aliasExact=true) 将其解析为规范的完整 EnvId。如果匹配到多个环境，或没有完全匹配的别名，应停止并向用户确认。
• 将 MCP／工具结果写入文件时，传入序列化文本（JSON.stringify(result, null, 2)），不要传入原始对象。如果写入工具提示 content 需要字符串但收到对象，不要用同一个原始对象重试。先序列化对象，再用序列化后的文本重试一次，并确保重试调用实际传入的是序列化字符串，而非原始对象。
• 将特定场景的注意事项保留在子技能中——不要扩充此入口文件。
• 首次部署前端必须使用 manageApps(action="deployApp", ...)。 不存在 createApp / updateApp 操作——首次部署和重新部署都使用 deployApp，且重新部署时复用相同的 serviceName。manageHosting 仅用于增量更新最初通过 hosting 部署的项目。

工程准则（适用于所有场景）

这些规则优先于便利性。完整说明请参阅 web-development。

• 先准备后端资源，再编写前端代码。 Auth 提供商、数据表、存储域和安全规则应优先使用 MCP 配置；如果本次会话缺少 MCP 工具，则使用 tcb CLI，并在下次会话配置 MCP（参见 references/tooling-fallback.md）。
• 不要使用 any 绕过类型错误。 优先使用 unknown 搭配类型守卫或精确接口。
• 在声称完成前自行验证。 静态验证（tsc / lint / build / tests）和运行时验证（用户可见流程使用 agent-browser）。如果某一层无法运行，应明确说明缺失项。
• 不要掩盖失败。 不要使用空的 try/catch，也不要删除失败的测试来让检查通过。
• ai.createModel(...) / wx.cloud.extend.AI.createModel(provider) 接收的是 GroupName，而非厂商／模型 ID。 有效值包括："cloudbase"、"hunyuan-v3"（旧版套餐组，仅支持 hy3，即将停用）、"hunyuan-exp"（较早的旧版内置组）或 "custom-<name>"。模型 ID 应填写在 generateText / streamText 的 model 字段中。请参阅 ai-model-web / ai-model-nodejs / ai-model-wechat。
• 低能力 STOP 卡： 对于 PostgreSQL / CloudBase PG / app.rdb() / queryPgDatabase / managePgDatabase，应转到 postgresql-development-cloudbase——不要对此路径使用 NoSQL 集合 API 或 MySQL 工具。对于 Web Auth 守卫，使用 auth.getSession() 并要求存在 data.session；不要使用已弃用的 getLoginState() / auth.getUser() 作为登录凭据。

高优先级路由

场景	首先阅读	然后阅读	首先不要路由到	操作前必须检查
最简 Web BaaS 演示（快速路径）	minimal-web-baas-demo	web-development, no-sql-web-sdk, postgresql-development	cloud-functions, cloudrun, spec-workflow, ui-design	以 BaaS 优先的 Web SDK CRUD，仅使用 MCP schema；除非密钥／定时任务／规则无法表达，否则不使用云函数
Web 登录／注册／身份验证 UI	auth-tool-cloudbase	auth-web, web-development	cloud-functions, http-api	提供商状态和可发布密钥
微信小程序 + CloudBase	miniprogram-development	auth-wechat, no-sql-wx-mp-sdk	auth-web, web-development	项目是否确实使用 CloudBase／wx.cloud
原生 App／Flutter／React Native	http-api-cloudbase	auth-tool, postgresql-development	auth-web, cloudbase-document-database-web-sdk, web-development	SDK 边界、OpenAPI、身份验证方式
Web 项目 + NoSQL 数据库	web-development	no-sql-web-sdk, auth-web	relational-database-tool, http-api	登录状态和数据库访问权限模型
CloudBase PostgreSQL／PG	postgresql-development-cloudbase	auth-tool, auth-web-cloudbase, web-development, miniprogram-development, cloud-storage-web, http-api	relational-database-tool, no-sql-web-sdk	PG schema、usernamePassword 登录、后端／RLS 权限模型。新的关系型数据库工作使用 PostgreSQL
现有 MySQL（不推荐）	relational-database-mcp-cloudbase	relational-database-web	postgresql-development, no-sql-web-sdk	仅当环境中已有 MySQL 时使用。新的关系型数据库工作使用 PostgreSQL
云函数	cloud-functions	auth-tool, ai-model-nodejs	cloudrun-development, auth-web	事件函数还是 HTTP 函数、运行时、scf_bootstrap
CloudRun 后端	cloudrun-development	auth-tool, postgresql-development	cloud-functions	容器边界、Dockerfile、CORS
AI Agent（智能体开发）	cloudbase-agent	cloud-functions, cloudrun-development	cloud-functions, cloudrun-development	AG-UI 协议、scf_bootstrap、SSE 流式传输
AI 模型调用（大模型调用／文本生成／图片生成／流式对话）	ai-model-web	ai-model-nodejs, ai-model-wechat	cloudbase-agent, cloud-functions, cloudrun-development	先运行“调用前必须的资格检查”：DescribeActivityInfo（小程序成长计划） + DescribeEnvPostpayPackage（Token Credits 资源包）
UI 生成	ui-design	web-development, miniprogram-development	cloud-functions	首先明确设计规范
AI 模型（Web）	web-development	ai-model-web, ui-design	ai-model-wechat, http-api	平台和流式交互模式
资源健康检查／故障排查	ops-inspector	cloud-functions, cloudrun-development	ui-design, spec-workflow	已启用 CLS；使用 queryEnv(action=metrics) 查询 QPS／CPU（绝不调用 callCloudApi）；查看日志时指定时间范围
Spec 工作流／架构设计	spec-workflow	cloudbase	web-development, cloud-functions	确认需求、设计和任务

路由提示

• Web 身份验证失败：通常是跳过了提供商配置，而不是缺少前端代码片段。
• 原生 App 失败：通常是使用了 Web SDK 路径，而不是缺少 HTTP API 知识。
• 小程序失败：将 wx.cloud 当作 Web 身份验证／SDK 使用。
• 新的关系型数据库使用 PostgreSQL。MySQL 技能仅适用于环境中已有 MySQL 实例的情况。
• CloudBase PG 失败：回退到 NoSQL 或 MySQL、跳过 username-password 就绪检查，或猜测原始 HTTP 用法，而不是使用 app.rdb()／文档中说明的 OpenAPI。
• AI 模型调用失败：通常是缺少 Token Credits／成长计划——更改代码前运行 DescribeEnvPostpayPackage／DescribeActivityInfo。

MCP + CLI 前置要求

如果当前会话已加载工具，管理／部署时优先使用 CloudBase MCP。配置方法：references/mcp-setup.md。首次会话／工具不可用时的处理方式：references/tooling-fallback.md。

• 首选安装方式： npx plugins add TencentCloudBase/cloudbase-plugin -y --scope user。支持的 --target ID：claude-code、cursor、codex、grok、kimi、github-copilot、vscode。参见 references/mcp-setup.md。如果 plugins add 因 program not found 失败，请使用该文件中的无 Git tarball 方式。
• 使用 npx mcporter list | grep cloudbase 或 IDE MCP 面板进行验证。如果缺少 npm／npx，请参见 references/tooling-fallback.md（安装 Node LTS 或使用 IDE 市场中的 MCP）。如果缺少 MCP，或配置后 MCP 尚未显示，仍需继续操作：完成安装／配置，告知用户重启后即可在下次使用 MCP，并通过 cloudbase-cli 领域技能立即使用 tcb CLI——不要推荐 tcb deploy。
• 如果可用，优先通过 MCP auth 使用设备代码登录；否则使用 tcb login。不要硬编码密钥。

按需参考资料

仅在需要时加载（不要展开此条目）：

• references/tooling-fallback.md — 首次会话／缺少工具时，MCP 与 tcb CLI 的决策树
• references/site-onboarding.md — 网站首次运行引导：触发／跳过、持久化、冲突协调、MCP 不可用时的回退方式
• references/deployment-workflow.md — 部署后端／前端、manageApps 与托管、URL／文档更新、可选的部署后 Deployment Share 邀请（§5）
• references/console-links.md — 创建资源后的控制台哈希路径
• references/scenarios.md — 用户需求 → CloudBase 功能映射
• references/mcp-setup.md — 插件安装（默认全局安装及目标）、IDE MCP／mcporter 配置和身份验证示例
• references/activation-map.yaml — 规范路由契约源文件

参考资料索引

所有打包的参考文件（确保技能 lint 可访问所需文件）：

• activation-map.yaml
• console-links.md
• deployment-workflow.md
• mcp-setup.md
• scenarios.md
• site-onboarding.md
• tooling-fallback.md