minimal-web-baas-demo

同级技能（仅本地）

同级的 CloudBase 技能会与此技能一同提供。使用 ../web-development/SKILL.md 这样的本地相对路径。

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

最小 Web BaaS 示例（快速路径）

目标：几分钟内获得可交互的 Web + 数据库预览，而不是搭建云函数中间件栈。

此技能相当于 CloudBase Sites SessionStart Rule 5（优先使用 BaaS 进行数据持久化）。

激活约定

适用于以下场景

• 用户要在 CloudBase Web 上创建最小全栈 / 前后端 demo、留言板、Todo、Notes、Kanban，或类似 Lovable/Supabase 的快速应用。
• 用户说“带云函数+云数据库”，但实际需求是 CRUD + 预览（应理解为 Web SDK → 数据库）。

不适用于以下场景

• 微信小程序（wx.cloud）——使用 ../miniprogram-development/SKILL.md。
• 真正的服务端工作负载：支付回调、短信服务商、第三方密钥、cron/ETL、WebSockets——使用 ../cloud-functions/SKILL.md 或 ../cloudrun-development/SKILL.md。
• 需要 ../spec-workflow/SKILL.md 的大型多模块产品。

硬性规则（与 Sites SessionStart Rule 5 保持一致）

1. 优先使用 BaaS 数据路径

   • **Schema / 管理：**优先使用 MCP 管理工具。不要让用户在控制台创建集合/表。如果此会话中没有 MCP 工具，请配置好 MCP 以供下次使用，并通过 tcb CLI（../cloudbase-cli/SKILL.md）执行同等的 Schema / 管理操作。
     • NoSQL：writeNoSqlDatabaseStructure（创建集合 / 索引）+ 按需使用权限工具；CLI：使用 cloudbase-cli 中的 NoSQL 命令。
     • PostgreSQL：遵循 ../postgresql-development-cloudbase/SKILL.md（queryPgDatabase / managePgDatabase / 迁移）；MCP 不可用时，使用 tcb db pg … 实现 CLI 等效操作。
   • **读取 / 写入：**在浏览器中使用 @cloudbase/js-sdk。
     • NoSQL：app.database() → db.collection(...).get()/add()/update()/watch(...)。
     • PG：app.rdb().from(...)。
   • 优先使用模板辅助工具（通常位于 src/utils/cloudbase.ts）。不要自行设计第二套 SDK 封装。

2. 默认禁止使用云函数

   • Todo / Notes / Chat / Kanban /“最小前后端 demo” → 不使用云函数。
   • 即使用户说“带云函数”，也应交付 Web SDK → DB，并用一句话说明 CRUD 无需云函数。
   • 仅在以下条件同时满足时才创建云函数：
     • (a) 逻辑无法通过数据库安全规则 / RLS 实现，并且
     • (b) 需要服务端密钥 / 第三方 API 密钥，或者属于由计划任务 / 后台作业触发、而非由用户点击触发的作业。

3. 依赖管理规范

   • 浏览器端：仅使用 @cloudbase/js-sdk。
   • 前端代码中绝不要安装 @cloudbase/node-sdk（或随意的 stub）。

4. 先预览，再部署

   • 在静态托管 / CloudApp 部署之前，先实现本地列表 + 添加（或同等 CRUD）功能。
   • 仅在用户明确提出要求时，才处理自定义域名、DNS、回滚操作手册。
   • 除非用户要求测试，否则跳过 Playwright / agent-browser。

5. 此路径的 UI 规范

   • 复用模板外观。对于最小 demo，不要加载 ui-design 四部分规范，除非用户要求重新设计视觉效果。
   • “给我做一个 X 应用” = X 就是首页（HomePage / App），而不是欢迎页旁的嵌套 demo 路由。

6. NoSQL CRUD 前先建立匿名（或真实）会话——js-sdk 3.x + publishable key

   • 使用 accessKey 初始化 @cloudbase/js-sdk 3.x 时，在执行任何 NoSQL app.database() get / add / update / watch 操作之前，调用 await auth.signInAnonymously()（或建立等效的已认证会话）。
   • 跳过此步骤会导致 gateway 401。单独调用 checkLogin() / getSession() 不会创建可用于写入的会话。
   • 最小示例：

const auth = app.auth
const { error } = await auth.signInAnonymously()
if (error) throw error
const db = app.database()
await db.collection('messages').get()

能力探测顺序（合作伙伴 + Agent）

每个最简 Web + DB 演示都按此顺序执行。**不要调整顺序。**云函数不能进入关键路径。

0. Connector pre-enabled (or shortest Trust path)     ← host / partner packaging
1. Template warmup // parallel with credential wait   ← downloadTemplate + install
2. queryEnv(action="info")                            ← sniff env + RuntimeBackends
3. Lock ONE DB plane (NoSQL | PG | MySQL)             ← no mid-flight thrash
4. MCP schema + minimal permissions                   ← writeNoSql* / PG migrate / MySQL manage
5. Browser @cloudbase/js-sdk CRUD                     ← app.database() / app.rdb()
6. Local preview (list + add)                         ← then ask before deploy
7. Cloud functions                                    ← skip (count = 0) unless secrets/cron/rules-cannot-express

此路径的技术栈优先级：Web SDK CRUD > MCP schema > 模板预热 > 云函数。

标准操作手册

1. 在获取凭据的同时预热模板（参见下方合作伙伴说明）：downloadTemplate（默认使用 react，如有要求则使用 vue）→ npm install / pnpm install。
2. queryEnv(action="info") → 锁定一个数据库方案（NoSQL 或 PG 或 MySQL）。不要在不同方案间反复切换。
3. MCP：创建集合 / 表并设置最小权限。
4. 前端：确保会话已建立（auth.signInAnonymously() 或同等方式），然后使用 @cloudbase/js-sdk 接入列表和创建功能（参见硬性规则 6）。
5. 启动 / 报告预览 URL；部署前先询问。
6. 此路径的云函数数量 = 0。

按需获取技能（仅在需要时获取）

需求	技能
Web 脚手架 / 托管	../web-development/SKILL.md
NoSQL 浏览器 CRUD	../cloudbase-document-database-web-sdk/SKILL.md
PG 浏览器 CRUD + MCP schema	../postgresql-development-cloudbase/SKILL.md
认证提供方就绪情况	../auth-tool-cloudbase/SKILL.md 然后 ../auth-web-cloudbase/SKILL.md
MCP 连接、使用 mcporter 从 shell 调用工具、插件标志	../cloudbase-mcp/SKILL.md

本地技能文件不可用时，优先使用 searchKnowledgeBase(mode="skill", skillName="minimal-web-baas-demo")（或同级目录 ID）。会话开始时不要转储所有 CloudBase 技能。

WorkBuddy / 合作伙伴打包说明（XDF 及其他）

任何合作伙伴托管环境（WorkBuddy、CodeBuddy 连接器、垂直领域专家提示词、ISV 封装）都应将此技能视为精简快速路径说明。沿用上述探测顺序；不要另创以云函数优先的演示路径。

托管环境能力	建议打包方式
完整的 CloudBase Sites 插件	依靠 SessionStart Rule 5 注入；对于非 Sites 工作目录演示，按需使用此技能。空工作目录预览优先使用设置了 CLOUDBASE_SITES_AUTO_INIT=1 的 Sites。切勿猜测 5173——读取 .cloudbase-sites/preview.json。
WorkBuddy / 连接器托管环境	尽可能为租户预先启用 CloudBase MCP 连接器；注入一段指向此处的简短系统说明；在等待凭据 / Trust 时预热 downloadTemplate + npm install（不要闲等）。可选的 SessionStart additionalContext 可以指向此技能——不要另行打包独立的模板预热插件。
专家 / 垂直领域提示词（ISV）	打包精简套件：专家 Agent Markdown（不含 frontmatter hooks）+ 可选设置 / hooks。将任何“必须云函数中转 / 前端绝不直连库”的表述替换为这份 BaaS 优先约定。

WorkBuddy SessionStart：https://www.workbuddy.ai/docs/cli/hooks（使用与 CodeBuddy/Claude Code 相同的 additionalContext schema）。除非主动选择启用，否则空目录的 Sites 自动初始化保持被动状态——不要假设仅启用 Sites 就会在等待凭据期间预热模板。

不要因自定义域名或组织 DNS 状况而阻塞首次预览。DNS 问题应在预览后处理。

一屏式合作伙伴粘贴内容（可选）

For 最小前后端 / Lovable-like demos: FIRST call
searchKnowledgeBase(mode="skill", skillName="minimal-web-baas-demo"), then Read.
Do not rely only on ad-hoc expert-prompt brief text.
Order: connector ready → template warmup during credential wait → queryEnv →
lock one DB → MCP schema → auth.signInAnonymously() (or session) →
@cloudbase/js-sdk CRUD → preview.
Do not dump all CloudBase skills. Do not create cloud functions for CRUD.
NoSQL without session → gateway 401.