cloudbase

CloudBase 开发指南

📁 参考文件位置

所有参考文档文件都位于相对于此文件的 references/ 目录中。

文件结构：

cloudbase/
├── SKILL.md              # This file (main entry)
└── references/           # All reference documentation
    ├── auth-web-cloudbase/SKILL.md              # Web authentication guide
    ├── auth-wechat-miniprogram/SKILL.md         # WeChat authentication guide
    ├── cloudbase-document-database-web-sdk/SKILL.md # NoSQL database for Web
    ├── ui-design/        # UI design guidelines
    └── ...               # Other reference docs

使用方法： 本文提到读取 references/auth-web-cloudbase/SKILL.md 之类的参考文件时，只需读取 references/ 子目录中的对应文件。

---

步骤 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 默认值为 domestic）	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 只能绑定一个站点），或任务需要托管端点未注册的工具。部署函数或应用并非使用本地模式的理由：远程模式也支持通过两步上传完成部署。对比说明：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 或同级技能目录）。
• 不要从远程原始 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，以供下一次会话使用；现在则使用 references/cloudbase-cli/SKILL.md 技能中的 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-tool-cloudbase，并在实现前端之前启用身份提供方。
• 区分认证域：管理登录使用 auth（或在 MCP 认证不可用时使用 tcb login）；应用端认证使用 queryAppAuth／manageAppAuth。

通用防护规则

• 同一路径连续失败 2–3 次后，停止尝试并改换路线（平台技能、运行时、认证域、权限模型、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。

• 先准备后端资源，再编写前端代码。 身份验证提供商、数据表、存储域和安全规则优先使用 MCP；如果本次会话中缺少 MCP 工具，则在配置好下次会话的 MCP 后使用 tcb CLI（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.getSession() 并要求存在 data.session；不要将已弃用的 getLoginState()／auth.getUser() 用作登录凭据。

高优先级路由

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

激活触发条件（源自 references/activation-map.yaml）

• Web 登录 / 注册 / 身份验证界面 — CloudBase Web 登录、Web 注册、身份验证登录页、publishable key、短信登录、邮箱登录
• 微信小程序 + CloudBase — 小程序云开发、wx.cloud、小程序 CloudBase、OPENID、小程序数据库
• 原生 App / Flutter / React Native — Android CloudBase、iOS CloudBase、Flutter CloudBase、React Native CloudBase、原生 App 接入
• Web 项目 + NoSQL 数据库 — Web 文档数据库、CloudBase collection、前端查库、NoSQL Web SDK
• CloudBase PostgreSQL 最佳实践 — PG 访问模式、数据库访问路径、N+1 查询、批量查询、慢查询、EXPLAIN ANALYZE、缺少索引、活动数据库容量
• CloudBase PostgreSQL / PG — CloudBase PG、PostgreSQL、Postgres、PG 模式、JS SDK v3 PostgreSQL、app.rdb()、queryPgDatabase、managePgDatabase、mysqldb OpenAPI、PostgREST、RLS、service_role、auth schema、storage schema、pgvector、关系型数据库、建表
• 已有 MySQL（不推荐） — 已有 MySQL、现有 MySQL 实例、queryMysqlDatabase、manageMysqlDatabase
• 云函数 — 创建云函数、HTTP 云函数、getFunctionLogs、scf_bootstrap、runtime
• CloudRun 后端 — CloudRun 部署、云托管、容器后端、Dockerfile
• AI Agent（智能体开发） — AI Agent、智能体、智能体开发、AG-UI protocol、LangGraph、LangChain、CrewAI、流式 Agent、Agent UI
• 最小化 Web BaaS 示例（快速路径） — 最小前后端、最小可用 demo、最小 fullstack、搭一套 demo、带云数据库的 demo、带云函数 + 云数据库、留言板、Todo 应用、todo app、Notes app、Kanban、Lovable、BaaS demo、最小化 Web BaaS、快速 demo
• UI 生成 — 设计页面、登录页 UI、前端界面、组件样式、原型
• AI 模型（Web） — Web AI 对话、CloudBase AI 流式输出、Web 集成模型
• AI 模型调用（大模型调用 / 文本生成 / 图片生成 / 流式对话） — 大模型调用、AI 模型调用、generateText、streamText、generateImage、文本生成、图片生成、流式对话、hunyuan-exp、deepseek-v4-flash、Token Credits 资源包、小程序成长计划、ai_miniprogram_inspire_plan、callCloudApi AI 模型、CreateAIModel
• 资源健康检查 / 故障排查 — 巡检、诊断、健康检查、资源健康、异常日志、错误检查、故障排查、错误排查
• Spec 工作流 / 架构设计 — 需求文档、技术方案、tasks.md、Spec 工作流

路由提醒

• Web 身份验证失败：通常是跳过了服务商配置，而不是缺少前端代码片段。
• 原生 App 接入失败：通常是使用了 Web SDK 路径，而不是缺少 HTTP API 知识。
• 小程序接入失败：通常是把 wx.cloud 当作 Web 身份验证 / SDK。
• 新建关系型数据库应使用 PostgreSQL。MySQL 技能仅适用于环境中已有 MySQL 实例的情况。
• CloudBase PG 接入失败：通常是回退到 NoSQL 或 MySQL、跳过用户名密码就绪检查，或猜测原始 HTTP 用法，而不是使用 app.rdb() / 文档化的 OpenAPI。
• AI 模型调用失败：通常是缺少 Token Credits / Growth Plan — 修改代码前，先运行 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 marketplace MCP）。如果 MCP 缺失或配置后尚未显示，仍应继续：完成安装 / 配置，告知用户重启后即可在下次使用 MCP，并立即通过 cloudbase-cli domain skills 使用 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 与 hosting 的选择、URL／文档更新、可选的部署后 Deployment Share 提示（§5）
• references/console-links.md — 创建资源后的控制台哈希路径
• references/scenarios.md — 用户需求 → CloudBase 能力映射
• references/mcp-setup.md — 插件安装（全局默认设置与目标）、IDE MCP／mcporter 配置和身份验证示例
• references/activation-map.yaml — 规范路由契约源文件

参考资料索引

所有打包的参考文件（满足 skill lint 可达性要求）：

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