cloudbase-platform

同级技能（仅限本地）

同级 CloudBase 技能与此技能一同提供。请使用 ../auth-tool-cloudbase/SKILL.md 这类本地相对路径。

如果此环境中缺少所引用的同级技能文件，请让用户安装完整的 CloudBase 插件（或缺失的技能）。不要通过 HTTP 将远程技能或协议 Markdown 获取到 Agent 上下文中。

跨领域协议（代码更改或部署前必须阅读）：

• Change Safety Protocol：references/protocols/change-safety-protocol.md
• Deployment Gate：references/protocols/deployment-gate.md
• Sensitive Runtime Data Protection：references/protocols/sensitive-runtime-data-protection.md

部署后（可选，不打扰用户）：确认部署成功后，最多可以主动提出一次生成匿名化分享材料（Deployment Share）——参见 references/protocols/deployment-share.md。在同一条回复中提供卡片、文案和案例墙条目；仅当用户只要求分享材料时才提供。用户拒绝后不得再次跟进；不得代表用户发布或提交。

激活约定

以下情况优先使用此技能

• 用户询问应使用哪种 CloudBase 功能、服务或工具，或需要了解托管、存储、身份验证、云函数或数据库选项的概览。
• 任务涉及控制台导航、跨平台差异、权限模型，或实现前的平台级最佳实践。

编写代码前阅读（如果）

• 仍不确定任务属于 Web、小程序、云函数、存储、MySQL / NoSQL 还是身份验证。
• 回复需要侧重平台选择、概念说明或控制面导航，而非直接的实现步骤。

然后还需阅读

• 最小 Web + 数据库演示（BaaS 优先，默认不使用云函数）→ ../minimal-web-baas-demo/SKILL.md
  • **最小前后端 / 类 Lovable 演示的技术栈顺序：**Web SDK CRUD > MCP schema > 等待凭据期间的模板预热 > 云函数（默认数量 = 0）。功能探测：连接器就绪 → queryEnv → 锁定一个数据库平面 → MCP schema → @cloudbase/js-sdk CRUD → 预览。
• Web 应用实现 → ../web-development/SKILL.md
• Web 身份验证和提供方设置 → ../auth-tool-cloudbase/SKILL.md、../auth-web-cloudbase/SKILL.md
• 小程序开发 → ../miniprogram-development/SKILL.md
• 通过 CloudBase Integration Center 接入微信支付、公众号 OAuth、JSAPI 支付或 Native 二维码支付 → ../cloudbase-wechat-integration/SKILL.md（官方文档：https://docs.cloudbase.net/integration/introduce.md）
• 云函数 → ../cloud-functions/SKILL.md
• 官方 HTTP API 客户端 → ../http-api-cloudbase/SKILL.md
• 文档数据库 → ../cloudbase-document-database-web-sdk/SKILL.md 或 ../cloudbase-document-database-in-wechat-miniprogram/SKILL.md
• CloudBase PostgreSQL / PG → ../postgresql-development-cloudbase/SKILL.md
• 实时功能 / 实时推送 / 通道 / 实时表变更订阅 / 多人同步 → ../postgresql-development-cloudbase/references/realtime.md
  • **仅限 PG 模式。**编写任何实时功能代码前，请先执行该文档的 Step 0 环境探测；如果环境中没有 realtime schema，请停止并报告，不要尝试绕过。
  • app.realtime()（Broadcast / Presence / Postgres CDC）不是文档数据库的 collection.watch()。实时功能请求不得用 watch() 代码作答，反之亦然。
• MySQL 关系型数据库 / 数据建模 → ../relational-database-mcp-cloudbase/SKILL.md 或 ../data-model-creation/SKILL.md
• 云存储 → ../cloud-storage-web/SKILL.md

不要用于

• 已有更具体技能适用时，直接实现网页、身份验证流程、函数或数据库操作。
• 属于专门技能范畴的底层 API 参数参考或 SDK 用法示例。

常见错误 / 注意事项

• 将这个通用技能当作所有 CloudBase 开发的默认入口。
• 已明确正确的实现技能后，仍停留在这里。
• 将平台概览与特定平台的 API 形式或 SDK 细节混为一谈。
• 在现有应用中，认证、存储和数据相关文件已一目了然时，仍绕道使用这个概览技能。
• 未先遵循变更安全协议（cloudbase-platform/references/protocols/change-safety-protocol.md），就修改代码或配置。
• 未先完成 cloudbase-platform/references/protocols/deployment-gate.md 中的检查，就开始部署、发布、配置自定义域名或开展 CloudRun 相关工作。
• 从 Cloud Functions / CloudRun 回显 x-cloudbase-context、完整的 req.headers 或 process.env（包括 httpbin 风格的调试镜像）——请遵循 references/protocols/sensitive-runtime-data-protection.md。
• 混淆安全域名与自定义域名：这是两个用途不同的工具。权威的区分方式请参见下方的“域名管理工具”表格。

何时使用此技能

在需要以下 CloudBase 平台知识时，请使用此技能：

• 了解 CloudBase 存储和托管概念
• 在实施前比较平台功能
• 了解跨平台认证差异（Web 与小程序）
• 了解数据库权限和访问控制
• 访问 CloudBase 控制台管理页面

此技能提供适用于所有 CloudBase 项目的基础知识，无论项目面向 Web、小程序还是后端服务。

---

如何使用此技能（面向编码 Agent）

1. 了解平台差异

   • Web 和小程序采用完全不同的身份验证方式
   • 必须严格区分不同平台
   • 切勿混用不同平台的身份验证方法
   • 如果工作区已经是一个带有 TODO 或预构建处理器的应用，不要停留在平台概览模式。应尽快转向具体的实现技能，以及负责该流程的现有文件。

2. 遵循最佳实践

   • 使用 SDK 内置的身份验证功能（Web）
   • 了解小程序免登录功能
   • 配置适当的数据库权限
   • 浏览器端 CRUD 优先使用 @cloudbase/js-sdk 直接访问数据库；仅在处理密钥、定时／后台任务，或安全规则／RLS 无法表达的高权限跨集合逻辑时使用云函数（参见 ../minimal-web-baas-demo/SKILL.md 中的演示默认方案）

3. 使用正确的 SDK 和 API

   • 不同平台的数据模型需要使用不同的 SDK
   • MySQL 数据模型必须使用 models SDK，而不是集合 API
   • PostgreSQL／CloudBase PG 相关工作必须交由 postgresql-development-cloudbase 处理；PG 数据路径不得复用 NoSQL app.database()／db.collection(...) 代码片段，也不得使用 MySQL 的 queryMysqlDatabase／manageMysqlDatabase
   • 使用 queryEnv 工具获取环境 ID
   • 在结构固定的现有 Web 应用中，广泛阅读概念文档之前，先检查现有的 src/lib/backend.*、src/lib/auth.*、src/lib/*service.* 以及绑定的页面处理器。

4. 使用主 cloudbase 指南中的规范 CloudBase MCP 配置

   • 本平台概览有意不重复完整的 MCP／mcporter 配置块
   • 规范配置示例、CLI 命令和身份验证示例，请先阅读主 cloudbase 指南
   • 保留此处相同的核心规则：本会话中有可用工具时优先使用 MCP；否则，为下个会话配置 MCP，并在当前会话使用 tcb CLI（../cloudbase-cli/SKILL.md、../cloudbase/references/tooling-fallback.md）。执行 MCP 前检查工具架构。不要在配置中硬编码 Secret ID／Secret Key／Env ID
   • 明确区分身份验证用途：管理端登录使用 auth，而应用端身份验证配置使用 queryAppAuth／manageAppAuth

---

CloudBase 平台知识

域名管理工具：明确区分

处理与域名相关的任务时，请根据需求使用正确的工具：

需求	工具	参数	用途
安全域名	manageEnv(action="addSecurityDomain" | "removeSecurityDomain")	domains（host:port 字符串数组）	验证浏览器上传的 CORS/请求来源。不涉及证书。（已弃用的别名：envDomainManagement。）
复用现有自定义域名	queryGateway(listCustomDomains) → manageGateway(createRoute)	domain = 现有自定义域名；路由字段	在已绑定的自定义域名上公开服务/路径。无需 certificateId。 如果已存在自定义域名，优先使用此方式。
绑定新的自定义域名	manageGateway(action="bindCustomDomain")	domain（字符串）、certificateId（字符串）	首次绑定新的公网 HTTPS 域名。需要从 SSL 控制台获取 certId。
删除自定义域名	manageGateway(action="deleteCustomDomain")	domain（字符串）	移除自定义域名绑定（仅在删除该域名上的路由后操作）。
禁用 / 启用网关路由	manageGateway(action="disableRoute" | "enableRoute")	path（必填），优先显式指定 domain	通过 ModifyHTTPServiceRoute 切换 Routes[].Enable（而非 ModifyGatewayRoute）。
禁用静态托管默认域名	queryGateway(listRoutes) → manageGateway(disableRoute)	domain = *.tcloudbaseapp.com（DomainType=STATIC_STORE、IsDefault=true），通常为 path="/"	关闭共享托管 CDN 默认主机的公网访问。不要使用 manageHosting。

选择正确工具的关键指标：

• 任务提到“自定义域名访问”，但环境中已有自定义域名 → 先调用 listCustomDomains，再调用 createRoute(domain=...)（无需 certificateId）
• 任务提到“证书 ID”或“SSL”，并且需要绑定一个新域名 → manageGateway(action="bindCustomDomain")
• 任务提到“浏览器上传”、“CORS”或“安全域名” → 使用 manageEnv(action="addSecurityDomain" / "removeSecurityDomain")
• 任务提到带域名的“公网访问”或“HTTPS” → 尽可能优先通过 createRoute 复用；仅在首次绑定域名时使用 bindCustomDomain
• 任务提到“关闭/禁用静态托管默认域名”或 *.tcloudbaseapp.com → 调用 queryGateway(listRoutes)，然后针对该 STATIC_STORE 域名调用 manageGateway(disableRoute)；绝不要自行编造 ModifyGatewayRoute
• 任务询问完整的接入流程（能不能绑、要等多久、解析怎么配、备案是不是前置），或已绑定域名无法访问 → 按照 ../cloud-api-operations/references/recipes/custom-domain.md 操作：先运行只读的 VerifyHTTPServiceRoute 预检查，然后绑定，接着轮询 Status / DNSStatus。该操作指南还说明了为什么域名注册 / DNS / ICP 调用可能因账户级身份而返回 UnauthorizedOperation。

错误码故障排查：通过官方文档处理

当 CloudBase 工具调用失败，且错误消息包含特定错误码（格式为 Category.Code，例如 OperationDenied.FreePackageDenied、ResourceNotFound.*）时，在采取任何操作前，务必先查阅官方文档——不要猜测错误含义，也不要在此处硬编码修复方案：

1. 从错误消息中提取错误码。
2. 查询错误码：searchKnowledgeBase(mode="docs", action="searchDocs", query="<错误码>")——官方文档搜索涵盖错误码页面。根据文档说明的含义和修复步骤采取行动（套餐限制 → 升级指引，配置错误 → 修正配置等）。
3. 如果文档搜索没有结果，请转而查阅以下权威错误码页面：
   • 错误码基础知识与自助故障排查：https://docs.cloudbase.net/error-code/basic
   • 控制面云 API 错误码：https://cloud.tencent.com/document/product/876/34823
4. 切勿凭记忆断言各套餐支持的功能或错误码的含义——只有官方文档和控制台中的套餐对比才是权威来源。例如，对于 Web 安全域名的套餐要求，应引用 https://cloud.tencent.com/document/product/876/127357，而不是自行假设哪个套餐支持此功能。

计费与服务停止类错误码需要特别处理：错误码本身的字面含义具有误导性，因此应先诊断再采取行动。 如果失败原因为 InsufficientBalance（云函数会以 HTTP 410 返回此错误）、EXCEED_REQUEST_LIMIT，或者服务单纯处于不可用状态，请注意：InsufficientBalance 看起来像是账户问题，实际并非如此：耗尽的是环境资源点数，它会在账户余额之前扣减（套餐额度 → 资源包 → 按量付费），充值无法恢复这些点数。无服务器服务的官方状态码表建议“充值后重试”，因此照此说明操作的用户会被引导去给账户充值，而故障依然存在。

先诊断，再给出建议——以下四种原因需要分别处理：免费体验点数耗尽／付费套餐点数耗尽／套餐已过期／账户确实欠费，只有最后一种情况需要充值。运行 manageEnv(action="usage") 查看当前周期环境的点数使用情况，并同时通过 callCloudApi 的 billing 读取账户余额；两者均为只读操作。决策表、各套餐的解决方法以及控制台入口见 credits-exhaustion。请在任何建议中牢记以下两点：免费体验版无法购买资源包或启用按量付费（升级到付费套餐是唯一途径）；套餐名称必须准确写为“免费体验版 / 个人版 / 标准版 / 企业版 / 企业高级版”。

记录操作结果

当任务明确要求将操作步骤或结果记录到文件（例如 RESULT.json）时：先完成工具调用，再写入完整记录，其中应包含每次尝试（操作、成功／失败状态、消息），以及包含总数／成功数／失败数的 summary。不要在工具调用完成前凭记忆写入文件。

存储与托管

1. 静态托管与云存储：

   • CloudBase 静态托管和云存储是两个不同的存储桶
   • 通常，可公开访问的文件可以存储在静态托管中，该服务会提供公开的网址
   • 静态托管支持配置自定义域名（需要在控制台操作）
   • 云存储适用于有隐私要求的文件，可通过临时文件 URL 获取临时访问地址
   • 如果任务需要使用 COS SDK 轮询、查询文件元数据或获取已上传对象的临时 URL，请使用云存储工具（manageStorage / queryStorage），而不是 manageHosting(action="upload")

2. 静态托管域名：

   • 可通过 queryHosting(action="websiteConfig") 获取 CloudBase 静态托管域名和网站文档配置
   • 将静态托管文件路径与其组合，构造最终访问地址
   • 默认共享主机的格式类似 <envId>-<appId>.tcloudbaseapp.com（DomainType=STATIC_STORE，在 queryGateway(listRoutes) 中通常为 IsDefault=true）
   • 要停用该默认公共主机：manageGateway(action="disableRoute", domain="<that-host>", path="/")（或使用 updateRoute 并设置 enable=false）。可使用 enableRoute 重新启用。不要查找 manageHosting 的停用默认域名操作；不要调用不存在的 ModifyGatewayRoute——该 API 为 ModifyHTTPServiceRoute
   • 重要：如果访问地址是目录，末尾必须带 /

3. 云存储公共 URL：

   • 重要：manageStorage(action=upload) 和 queryStorage(action=url) 返回的 temporaryUrl 是临时签名 URL，会过期（默认 1 小时）。不要将其用作永久公共 URL。
   • 要获取云存储对象的永久公共访问 URL：
     1. 调用 queryEnv(action=info) 获取环境详情
     2. 从 EnvInfo.Storages[0].CdnDomain 提取存储 CDN 域名（例如 your-env-id.tcb.qcloud.la）
     3. 构造公共 URL：https://{CdnDomain}/{cloudPath}
   • 示例：如果 CdnDomain 为 env-xxx.tcb.qcloud.la，且 cloudPath 为 uploads/avatar.jpg，则公共 URL 为 https://env-xxx.tcb.qcloud.la/uploads/avatar.jpg
   • 注意：只有当存储桶 ACL 允许公开读取时，才能访问公共 URL（默认值为 PRIVATE，需要使用签名 URL）

4. 共享存储桶（ExternalStorage）环境：

   • 某些环境会将文件存储在与其他环境共享的 COS 存储桶中，并在各自独立的目录前缀（BasePath）下隔离。可通过 queryEnv(action="info") 检测：当 EnvInfo.Storages[0].Bucket 为空且 Storages[0].ExternalStorage.Enabled === true 时，云存储使用的是共享存储桶；静态托管可通过检查 EnvInfo.StaticStorages[0] 进行同样的判断。存储和托管可以使用不同的存储桶和 BasePath。
   • 路径保持逻辑路径。 存储和托管工具会自行添加 BasePath，因此传入的 cloudPath 应与普通环境中的写法完全一致，切勿在前面添加 BasePath 或存储桶名称。例如，BasePath 为 tenant-a 时，应使用 cloudPath="images/a.png" 上传，而不是 "tenant-a/images/a.png"（否则会将文件嵌套到 tenant-a/tenant-a/ 下）。构造托管和 CDN URL 时也应使用逻辑路径——域名会解析到 BasePath，若在托管 URL 中添加 BasePath，则会返回 404。
   • manageHosting(action="setWebsiteDocument") 会更改存储桶级别的设置，影响存储桶中的所有环境，因此在共享存储桶托管中会失败。使用 queryHosting(action="websiteConfig") 仍可读取配置。请告知用户此设置由平台管理，不要重试。
   • 存储安全规则按环境维护，而不是作为 COS 存储桶 ACL 维护，因此请像普通环境一样读取和更新这些规则。
   • 删除共享存储桶环境后文件会如何处理，由平台决定。不要承诺保留或删除其 BasePath 目录。

环境与身份验证

1. SDK 初始化：

   • 初始化 CloudBase SDK 需要环境 ID。
   • 可通过 queryEnv 工具查询环境 ID。
   • 如果用户只提供环境别名、昵称或其他简短形式，请先使用 queryEnv(action="list", alias=..., aliasExact=true) 解析，并使用返回的完整 EnvId。
   • 不要将类似别名的简短形式直接传入 SDK 初始化、auth.set_env、控制台 URL 或生成的配置文件。
   • 对于 Web，始终同步初始化：
     • import cloudbase from "@cloudbase/js-sdk"; const app = cloudbase.init({ env: "your-full-env-id" });
     • 不要使用 import("@cloudbase/js-sdk") 这样的动态导入，也不要使用内部包含 initPromise 的 initCloudBase() 等异步包装器。
   • 然后使用已验证的方法登录（用户名／密码、手机、电子邮件或 WeChat）。

2. 环境管理（通过 manageEnv）： manageEnv 工具提供 CloudBase 环境的完整生命周期管理。

   操作	描述	关键参数
   listPackages	查询可用套餐	（无）
   create	创建新环境（需要确认）	alias、packageId、resources、duration、region、externalStorage
   modifyPlan	更改套餐（升级／降级，需要确认）	envId、packageId
   renew	续费环境（需要确认）	envId、duration

   使用指定资源创建环境：

   manageEnv(action="create", alias="my-env", packageId="baas_personal",
             resources=["storage","function","postgresql"], confirm="yes")
   

   • resources（可选，仅创建时）：控制要启用哪些 CloudBase 功能：
     • storage — 云存储
     • function — 云函数
     • postgresql — PostgreSQL 关系型数据库（PG 模式）
   • 如果省略，默认启用全部三项。MCP 始终向 CreateEnv 发送非空的 Resources。
   • 不提供 flexdb（文档数据库）：新环境创建时不会配置 NoSQL 租户。不要传入此参数，否则会被架构拒绝。要确认环境是否实际具有 NoSQL，请读取 queryEnv(action="info") → EnvInfo.RuntimeBackends，不要自行假设。
   • 区域可选：传入 region（例如 region="ap-shanghai"）以选择环境的创建区域。该值会作为**X-TC-Region 请求上下文应用，而不是 CreateEnv 请求体字段——因此不要**将 Region 放入 params。省略时使用当前会话区域（cloudBaseOptions.region → TCB_REGION → 项目配置／rc 绑定 → 站点默认值：国内站点为 ap-shanghai，国际站点为 ap-singapore）。对应的 CLI 命令：tcb env create --region ap-shanghai。
   • ⚠️ 如果传入 region，在确认调用中也要传入相同的值并附带 confirm="yes"；否则第二次调用会回退到会话区域，环境可能创建在与你确认的摘要不同的区域。
   • externalStorage（可选，仅创建时）：{ bucketName, region, basePath } 会在现有共享 COS 存储桶上创建环境的云存储，而不是使用专用存储桶，并将其文件隔离在 basePath 下（在该存储桶中必须唯一）。传入此对象时，必须提供全部三个字段。仅当用户提供了存储桶时才使用此参数——通常适用于平台在一个账户下创建多个环境的场景，因为每个环境使用一个存储桶会触及账户的 COS 存储桶配额；切勿自行编造存储桶名称。此参数不涵盖静态托管：启用托管时由平台选择托管存储桶，且无法通过此工具设置。
   • ⚠️ 与 region 一样，在 confirm="yes" 调用中也要重复传入相同的 externalStorage。确认调用只读取自身的参数，因此省略该参数会导致环境使用专用存储桶创建。

   manageEnv(action="create", alias="tenant-a", packageId="baas_personal",
             externalStorage={ bucketName: "shared-bucket-1250000000", region: "ap-shanghai", basePath: "tenant-a" },
             confirm="yes")
   

   • ⚠️ 所有付费操作（create／modifyPlan／renew）都必须传入 confirm="yes"。 创建前查询可用套餐：

   manageEnv(action="listPackages")
   

   • ⚠️ 此列表仅包含控制台在新购／新环境菜单中提供的套餐：baas_personal（个人版）、baas_pf_standard（标准版）、baas_pf_enterprise（企业版）、baas_pf_enterprise_senior（企业高级版）、baas_trial（体验版）、baas_integration（集成版）。套餐系列（default / basic / trial / vip）与这组套餐并非一一对应——starter（入门版）、baas_team（团队版）和 enterprise_basic（企业基础版）等旧套餐与当前套餐属于相同系列，因此会被有意排除。平台仍接受其他有效的 packageId，因此实际创建结果才是权威依据。

   更改套餐（使用 listPackages 中的 packageId）：

   manageEnv(action="modifyPlan", envId="your-env-id", packageId="<packageId>", confirm="yes")
   

   续期环境：

   manageEnv(action="renew", envId="your-env-id", duration=1, confirm="yes")
   

身份验证最佳实践

重要：不同平台的身份验证方式完全不同，必须严格区分！

Web 身份验证

• 必须使用 SDK 内置的身份验证功能：CloudBase Web SDK 提供完整的身份验证功能
• 推荐方式：使用 auth.getVerification() 进行短信登录；详情请参阅 Web 身份验证相关文档
• 禁止行为：不要使用云函数实现登录身份验证逻辑
• 会话管理：进行路由守卫和登录验证时，使用 auth.getSession() 并要求存在 data.session；不要使用已弃用的 getLoginState()，也不要将 auth.getUser() / auth.getCurrentUser() 作为真实登录的凭据。
• 服务提供方和登录方式设置：使用 queryAppAuth / manageAppAuth，而非 MCP auth 工具
• 默认禁用匿名登录。 仅凭可发布的 accessKey 不会创建经过网关身份验证的匿名会话。使用 @cloudbase/js-sdk 3.x 时，在执行 NoSQL app.database() CRUD 操作之前，调用 await auth.signInAnonymously()（或建立等效的经过身份验证的会话），否则网关会返回 401。如果应用使用 AuthGuard 或 RLS 进行访问控制，并且允许匿名访问，请确保设置了 is_anonymous 检查。
• ⚠️ PG RLS：使用 auth.uid()，不要使用 current_user。 为 CloudBase PostgreSQL 编写 RLS 策略时，用户身份必须使用 auth.uid()（返回 JWT sub／实际用户 ID，类型为 text，而非 uuid，这与 Supabase 不同）。所有者列建议使用 varchar(64) / text；如果列的类型为 uuid，则使用 auth.uid()::uuid 进行转换，否则会出现 operator does not exist: uuid = text。不要使用 current_user 或 current_setting(...)——这些 PostgreSQL 内置函数返回的是数据库角色名称（例如 authenticated），而非 CloudBase 身份验证用户 ID。CloudBase PG 提供四个身份验证辅助函数：auth.uid()、auth.role()、auth.email()、auth.jwt()。使用 SELECT proname FROM pg_proc WHERE pronamespace = 'auth'::regnamespace 验证这些函数是否可用。

小程序身份验证

• 免登录功能：小程序 CloudBase 天然免登录，无需登录流程
• 用户标识符：在云函数中通过 wx-server-sdk 获取 wxContext.OPENID
• 用户管理：在云函数中根据 openid 管理用户数据
• 禁止行为：不要生成登录页面或登录流程代码

云函数

1. Node.js 云函数：
   • Node.js 云函数需要包含 package.json，声明所需依赖
   • 可以使用 manageFunctions(action="createFunction") 创建函数
   • 使用 manageFunctions(action="updateFunctionCode") 部署云函数
   • 优先在云端安装依赖，不要上传 node_modules
   • functionRootPath 指云函数目录的父目录，例如 cloudfunctions 目录

数据库权限

⚠️ 严重：务必先配置权限，再编写数据库操作代码！

1. 权限模型：

   • CloudBase 数据库访问受权限控制
   • 默认的基础权限包括：
     • READONLY：所有人都可以读取，只有创建者/管理员可以写入
     • PRIVATE：只有创建者/管理员可以读取和写入
     • ADMINWRITE：所有人都可以读取，只有管理员可以写入（⚠️ 不适用于 Web SDK 写入！）
     • ADMINONLY：只有管理员可以读取和写入
     • CUSTOM：使用自定义规则进行精细控制

2. 平台兼容性（严重）：

   • ⚠️ Web SDK 不能将 ADMINWRITE 或 ADMINONLY 用于写入操作
   • ✅ 对于 Web 应用中的用户生成内容，请使用 CUSTOM 规则
   • ✅ 对于由管理员管理的数据（产品、设置），请使用 READONLY
   • ✅ 无论权限类型如何，云函数都拥有完整访问权限

3. 配置工作流：

   Create collection → Configure security rules → Write code → Test
   

   • 使用 managePermissions(action="updateResourcePermission") 配置资源权限
   • 如果刚刚更改了权限，请在几秒后重试（通常在约 30 秒内生效）。不要盲目等待 2-5 分钟。如果仍然失败，请先重新检查实际规则结构和当前客户端写入模式——大多数失败是规则配置错误，而不是缓存问题。
   • 详细示例仅适用于 resourceType="noSqlDatabase"，请参阅 no-sql-web-sdk/security-rules.md；不要将 doc._openid、auth.openid、查询子集验证或 create / update / delete JSON 模板视为适用于函数、存储或 SQL 表的通用规则
   • 官方参考资料：
     • 安全规则概述：https://cloud.tencent.com/document/product/876/41802
     • NoSQL 数据库安全规则：https://docs.cloudbase.net/database/security-rules
     • 云函数安全规则：https://docs.cloudbase.net/cloud-function/security-rules
     • 存储安全规则：https://docs.cloudbase.net/storage/security-rules

兼容性说明：

• 规范插件名称：permissions
• 旧版插件别名 security-rule、security-rules、secret-rule、secret-rules 和 access-control 仍会解析到 permissions 插件
• 旧版工具 readSecurityRule / writeSecurityRule 已移除；请优先使用 queryPermissions / managePermissions

4. 常见场景：

   • 电商产品：READONLY（管理员通过云函数管理）
   • 购物车：使用 auth.uid 检查的 CUSTOM（用户管理自己的购物车）
   • 订单：使用所有权验证的 CUSTOM
   • 系统日志：PRIVATE 或 ADMINONLY

5. 跨集合操作：

   • 当权限模型允许时，优先使用安全规则 / RLS 和客户端 SDK
   • 当操作需要提升权限、服务器密钥或规则无法表达的多集合逻辑时，使用云函数
   • 对于最小化 Web 演示（Todo / Notes / Kanban / 最小前后端），不要为 CRUD 引入云函数——请遵循 ../minimal-web-baas-demo/SKILL.md

角色管理（MCP）

CloudBase MCP 通过 queryPermissions 和 managePermissions 提供角色管理功能（CLI 等效命令：tcb role）。完整操作列表请参阅各工具的 Schema。

⚠️ 严重：角色策略和资源权限是两个相互独立的系统，二者不会自动同步。

• 资源权限（安全规则）控制对特定资源（表、集合、函数、存储）的访问
• 角色（身份维度）控制策略包和成员分配

查询（queryPermissions）：listRoles、getRole（按 roleId / roleIdentity / roleName 查询）。 管理（managePermissions）：createRole、updateRole、deleteRoles、addRoleMembers、removeRoleMembers、addRolePolicies、removeRolePolicies。

managePermissions(action="createRole", roleName="Developer", roleIdentity="developer",
                  policies=["FunctionsAccess"], memberUids=["user-uid-1"])

⚠️ 只能删除自定义角色。系统角色为只读。

另请参阅：cloudbase-cli/references/permission.md 中的 CLI 等效命令

3. 云函数优化：
   • 浏览器 CRUD 不应默认使用云函数中间件层；优先使用 @cloudbase/js-sdk → 数据库（参见 ../minimal-web-baas-demo/SKILL.md）
   • 确实需要云函数时，应尽量减少函数数量，并将每个函数的用途限定为处理密钥、提升权限或后台任务

数据模型

1. 获取数据模型操作对象：

   • 小程序：需要 @cloudbase/wx-cloud-client-sdk，初始化 const client = initHTTPOverCallFunction(wx.cloud)，使用 client.models
   • 云函数：需要 @cloudbase/[email protected]+，初始化 const app = cloudbase.init({env})，使用 app.models
   • Web：需要 @cloudbase/js-sdk，初始化 const app = cloudbase.init({env})，登录后使用 app.models

2. 数据模型查询：

   • 可调用 MCP manageDataModel 工具来：
     • 查询模型列表
     • 获取模型详细信息（包括 Schema 字段）
     • 获取特定模型的 SDK 使用文档

3. MySQL 数据模型调用规则：

   • MySQL 数据模型不能使用集合方法调用，必须使用数据模型 SDK
   • 错误：db.collection('model_name').get()
   • 正确：app.models.model_name.list({ filter: { where: {} } })
   • 使用 manageDataModel 工具的 docs 方法获取特定 SDK 的使用方法

控制台管理

创建或部署资源后，提供相应的控制台链接。所有控制台 URL 均遵循以下模式：https://tcb.cloud.tencent.com/dev?envId=${envId}#/{path} — 使用通过 queryEnv 解析出的实际 EnvId 替换 ${envId}（先解析别名；请参阅下文的“环境与身份验证”），并将资源名称替换为实际值。

CloudBase 控制台会频繁更新。如果已登录的控制台页面显示的 hash 路径与此列表不同，应优先使用控制台当前显示的路径，而非过时文档中的路径，然后更新此技能以保持一致。

入口（一行一个）

• 概览：#/overview
• 模板中心：#/cloud-template/market
• 文档数据库：#/db/doc · 集合 #/db/doc/collection/${collectionName} · 模型 #/db/doc/model/${modelName}
• MySQL 数据库：#/db/mysql · 表 #/db/mysql/table/default/（必须先在控制台启用）
• PostgreSQL 数据库：#/db/postgres · 数据编辑器 #/db/postgres/data-editor · SQL 编辑器 #/db/postgres/sql-editor · 设置 #/db/postgres/setting（实例规格、账号密码）· 任务 #/db/postgres/tasks（异步任务列表：规格变更、共享转专享升级）· 备份 #/db/postgres/backups · 迁移 #/db/postgres/migrations
• 云函数：#/scf · 详情 #/scf/detail?id=${functionName}&NameSpace=${envId}
• CloudRun：#/platform-run（需先为每个环境开通此能力 — manageCloudRun(action="initEnv")，然后轮询 queryCloudRun(action="envStatus")，直至状态为 normal；环境可以存在但未开通 CloudRun，这种情况下 CloudRun API 仍会成功返回，但字段为空）
• 云存储：#/storage
• AI+：#/ai
• 静态托管：#/static-hosting（备用链接：https://console.cloud.tencent.com/tcb/hosting）
• 身份认证：#/identity · 登录管理 #/identity/login-manage · Token 管理 #/identity/token-management
• 微搭低代码：#/lowcode/apps
• 日志与监控：#/devops/log
• 环境设置：#/env/env-setting（环境信息、QPS 超额情况、预览状态）
• HTTP 访问：#/env/http-access（安全域名、CORS、环境变量、配额）
• ICP 备案：#/env/filing-manage（此环境是否符合备案资源条件：套餐等级、剩余有效期超过 6 个月、CloudRun 固定 IP；未满足的项目会显示各自的“续费”／“启用固定 IP”按钮）

对于配置页面（例如登录管理），应引导用户完成设置流程，而不只是提供链接。

参考索引

所有打包的参考文件（技能 lint 可达性所必需）：

• protocols/change-safety-protocol.md
• protocols/deployment-gate.md
• protocols/deployment-share.md
• protocols/sensitive-runtime-data-protection.md