TencentCloudBase/CloudBase-AI-Toolkit

CloudBase All-In-One

工作流程

每个 CloudBase 任务均遵循以下三阶段流程：

1. 探索  →  在编写任何代码之前，完整阅读匹配的技能文档。
            如有需要先搜索，然后完整阅读 SKILL.md 内容。
            只有在理解技能文档中的 API 模式、陷阱和正确用法后，
            才能开始实现。
2. 实现
   ├── 2a. 资源准备 → 优先使用 MCP 准备后端资源
   │     （启用认证提供商、创建数据库表、配置存储域名、
   │      设置安全规则——在编写前端代码之前完成）。
   │     如果在此会话中缺少 MCP 工具，则配置 MCP 以便下次使用，
   │     当前使用 `tcb` CLI（`./cloudbase-cli/SKILL.md`）。
   └── 2b. 前端实现 → 编写代码、安装依赖、启动服务器、测试
3. 收尾  →  运行 cloudbase-code-review，修复所有错误，声明完成

关键约束：

• 第 2a 阶段（资源准备）必须在前端代码之前完成。 优先使用 MCP 工具；如果工具尚未加载（首次会话/重启前），则在配置 MCP 后回退到 tcb CLI。不要编写依赖未创建资源（表、认证提供商、存储桶）的前端代码——评分将失败。
• 不要跳过第 3 阶段。 收尾阶段能够捕获智能体在实现中容易遗漏的常见陷阱。

范围

仅处理构建、集成或维护 CloudBase 应用相关的任务——包括 UI 设计、规范规划及其他开发活动，只要它们服务于 CloudBase 应用。如果请求完全不涉及 CloudBase 应用上下文，请停止并告知用户本技能仅涵盖基于 CloudBase 的开发。

激活契约

首先使用本技能的场景

• 任务是 CloudBase 应用构建、集成或修复，并且工作区已包含应用实现。
• 请求在单个 CloudBase 应用任务中混合了认证、数据库、存储和前端工作。

在广泛探索之前执行以下操作

• 在编写任何代码之前阅读相关技能文档。 使用 searchKnowledgeBase(mode="skill", skillName=...) 搜索匹配的技能，然后 Read 返回的文件路径以获取完整的 SKILL.md 内容。不要仅基于搜索结果摘要开始实现——完整文档包含 API 签名、参数模式和陷阱警告。
• 首先检查现有实现面：
  • src/lib/backend.*
  • src/lib/auth.*
  • src/lib/*service.*
  • 路由守卫
  • 绑定到活动表单提交按钮的页面处理程序
• 如果这些文件包含 TODO，请在创建新的辅助函数、示例或替换页面前，就地实现这些 TODO。
• 除非用户明确要求视觉更改，否则不要从 UI 重设计或设计规范输出开始。
• 当任务是单个针对性修复时，不要从重复的 TaskCreate/TaskUpdate 这类项目管理循环开始。读取活动文件并直接编辑它们。

快速路由到最少所需技能

• 最小 Web + 数据库演示 / 类似 Lovable 的 BaaS 快速路径 -> ./minimal-web-baas-demo/SKILL.md（默认用于最小前后端演示；BaaS 优先，无云函数）
• Web 应用执行 -> ./web-development/SKILL.md
• Web 认证提供商就绪 -> ./auth-tool/SKILL.md
• Web 认证实现 -> ./auth-web/SKILL.md
• CloudBase PostgreSQL / PG 应用数据 -> ./postgresql-development/SKILL.md
• 微信支付 / 通过 CloudBase 集成中心的公众号 OAuth -> ./cloudbase-wechat-integration/SKILL.md
• 浏览器端文档数据库 CRUD -> ./no-sql-web-sdk/SKILL.md
• 浏览器端文件上传 -> ./cloud-storage-web/SKILL.md
• 仅当能力选择仍不清晰时查看平台概览 -> ./cloudbase-platform/SKILL.md
• 如果使用 searchKnowledgeBase(mode="skill")，请传递参考目录 ID，例如 postgresql-development-cloudbase 或 minimal-web-baas-demo，而不是猜测的别名。

高收益护栏

• 在编写前端代码之前先准备后端资源。 优先使用 MCP 创建认证提供商、数据库表、存储域和安全规则。如果当前会话缺少 MCP 工具，则为下次会话配置 MCP 并立即使用 tcb CLI——不要等待重启而停滞不前。针对不存在的资源编写前端代码会导致评分失败。
• 变更安全协议：在进行任何非平凡的代码或配置更改之前，必须严格遵守 cloudbase-platform/references/protocols/change-safety-protocol.md（声明影响 → 获取用户确认 → 变更后验证 → 同一症状出现 3 次后升级到根因分析）。
• 部署门禁：在任何部署、发布、自定义域名、CloudRun 或公共暴露工作之前，必须完成 cloudbase-platform/references/protocols/deployment-gate.md 中的检查，并展示强制声明模板。
• 如果同一路径失败 2-3 次，停止重试并重新路由。在修改更多代码之前，检查平台技能、认证域、运行时和权限模型。
• 初始化 CloudBase 客户端或管理操作时，始终在代码、配置和命令示例中显式指定 EnvId。不要依赖当前 CLI 选中的环境或隐式默认值。
• 如果对话仅提供了环境别名、昵称或其他简写，请使用 envQuery(action=list, alias=..., aliasExact=true) 解析它，并在调用 auth.set_env、生成控制台链接或编写配置/代码之前，使用返回的规范完整 EnvId。如果别名含糊不清或缺失，请停止并要求用户确认。

不要将此技能用于

• 在编写代码之前阅读每个 CloudBase 技能的理由。
• 当现有代码已揭示技术栈和缺失部分时，仍从平台概览开始的理由。

工作规则

1. BaaS 优先，云函数作为最后手段：

   • 对于最小前后端 / 类似 Lovable 的演示，首先路由到 ./minimal-web-baas-demo/SKILL.md。顺序：连接器就绪 → 在等待凭证时预热模板 → envQuery → 锁定一个数据库 → MCP 模式 → @cloudbase/js-sdk CRUD → 预览。默认云函数数量 = 0。
   • 在编写任何云函数或 CloudRun 服务之前，询问：正确的 JS SDK 面是否能直接处理此需求？仅对确认的 NoSQL 集合使用 db.collection(...).get()；对 CloudBase PG 表使用 app.rdb().from(...)；使用匹配技能中的 auth/storage。
   • 直接使用匹配的 JS SDK 面进行：数据读/写、文件上传、实时更新、简单查询（包括排行榜、列表、聚合）。
   • 仅在以下情况下才降级到云函数：逻辑需要无法在数据库规则/RLS 中表达的服务端权限执行、调用第三方服务（支付、短信、外部 API）或非用户触发的后台任务。
   • 仅在以下情况下才降级到 CloudRun：确实需要持久连接（WebSocket）、长时间运行的计算或自定义运行时。

2. 包含 TODO 的现有应用：

   • 将其视为针对性修复任务，而不是全新构建。
   • 优先选择从当前代码到工作流程的最短路径。

3. 认证任务：

   • 如果账户标识符是纯用户名如 admin、editor 或另一个不带 @ 的字符串，则将 usernamePassword 登录视为阻塞性前置条件。
   • 首先调用 queryAppAuth(action="getLoginConfig")。
   • 如果 loginMethods.usernamePassword !== true，立即调用 manageAppAuth(action="patchLoginStrategy", patch={ usernamePassword: true })。
   • 在 Web 登录代码中，使用 auth.signInWithPassword({ username, password })。
   • 不要假设所有环境或 SDK 版本都直接支持 Web 端 auth.signUp({ username, password })；首先验证 sdkHints/已安装的 SDK 行为。如果需要用户名注册且直接注册不受支持，则通过后端或管理 API 路径路由注册，该路径创建 CloudBase Auth 用户，且不在浏览器代码中暴露密钥。
   • 对于这些用户名风格的账户流程，切勿使用 signUpWithEmailAndPassword 或 signInWithEmailAndPassword。
   • 确认就绪后，返回活动的前端处理程序并完成实际的登录/注册流程。

4. 数据库和存储任务：

   • 重用当前共享的 app、auth、db 和存储辅助函数，而不是创建并行的 SDK 包装器。
   • 如果任务提及 CloudBase PG、PostgreSQL、Postgres、PG 模式、JS SDK v3 PostgreSQL、app.rdb()、queryPgDatabase、managePgDatabase、mysqldb OpenAPI 或 RLS，请在接触数据库代码之前阅读 ./postgresql-development/SKILL.md。
   • 对于 CloudBase PG，使用 queryPgDatabase/managePgDatabase 进行模式和管理；不要将 PG 工作路由到 MySQL queryMysqlDatabase/manageMysqlDatabase 或 NoSQL 集合 API。
   • 对于 OpenAPI 查找，直接调用 searchKnowledgeBase({ mode: "openapi", apiName: "mysqldb" })。不要传递猜测的 action 值如 getApiDocs 或 listEndpoints；这些不属于任何支持的工具模式。
   • 对于 CloudBase PG Web CRUD，优先使用 JS SDK v3 的 app.rdb() 和文档化的存储 app.storage.from() API，而非原始 HTTP。
   • 对于浏览器端从本地 Vite/预览环境上传 CloudBase 存储，首先检查安全域中的实际浏览器 host:port（通过 envQuery(action="domains")，如果缺失则使用 envDomainManagement(action="create")）。封面上传失败不得静默跳过后续 PG 文章插入。

• 对于 CloudBase Web SDK 的 db.collection(...).add(...)，持久化 result._id 中创建的文档 ID。
• 对于写入操作，验证实际的 SDK 结果，而不是假设成功。
• 遗留 API 停止卡： 如果任务提到 PostgreSQL、CloudBase PG、PG 模式、app.rdb()、queryPgDatabase、managePgDatabase、PostgREST 或 RLS，不要凭记忆编写 NoSQL 示例。对于 Web CRUD 使用 app.rdb().from(...)，对于管理使用 queryPgDatabase/managePgDatabase，对于 Web 认证守卫使用 auth.getSession()。不要使用 app.database()、db.collection(...)、.where()、.orderBy()、app.uploadFile()、getLoginState() 或 auth.getUser() 作为 PG/认证的默认值。

5. 针对性修复任务：
   • 功能闭合优先于探索。
   • 避免广泛的仓库扫描、UI 重设计和分离的演示代码。
   • 保持文件发现范围狭窄。优先直接读取已知的活动文件，而不是对整个项目使用 Glob/广泛搜索。