TencentCloudBase/CloudBase-AI-Toolkit

CloudBase 一體化解決方案

工作流程

每一項 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 階段。 結案階段能捕捉到實作過程中 AI 經常遺漏的已知陷阱。

適用範圍

僅處理屬於建置、整合或維護 CloudBase 應用程式的任務 — 包括 UI 設計、規格規劃及其他開發活動，前提是這些活動是為 CloudBase 應用服務。如果請求完全沒有 CloudBase 應用程式的背景，請停止並告知使用者此技能僅涵蓋基於 CloudBase 的開發。

啟用合約

在以下情況優先使用此技能

• 任務為建置、整合或修復 CloudBase 應用，且工作區已包含應用實作。
• 請求在同一個 CloudBase 應用任務中混合了身分驗證、資料庫、儲存與前端工作。

在廣泛探索之前，請先執行以下操作

• 在撰寫任何程式碼之前，先閱讀相關技能文件。 使用 searchKnowledgeBase(mode="skill", skillName=...) 搜尋對應的技能，然後 Read 回傳的檔案路徑以取得完整的 SKILL.md 內容。請勿僅依據搜尋結果摘要就開始實作 — 完整文件中包含 API 簽章、參數結構及陷阱警告。
• 先檢查現有的實作表面：
  • src/lib/backend.*
  • src/lib/auth.*
  • src/lib/*service.*
  • 路由守衛
  • 綁定於現有表單提交按鈕的頁面處理程式
• 如果這些檔案包含 TODOs，請先在原地完成這些 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) 解析，並使用回傳的標準完整 EnvId，再呼叫 auth.set_env、產生主控台連結或撰寫設定/程式碼。如果別名不明確或遺失，請中斷並要求使用者確認。

請勿將此技能用於

• 作為在接觸程式碼前閱讀所有 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），或非使用者觸發的背景任務。
   • 僅在真正需要持久連線（WebSocket）、長時間運算或自訂執行時期時，才使用 CloudRun。

2. 含 TODOs 的現有應用程式：

   • 將其視為目標修復任務，而非全新建置。
   • 優先選擇從當前程式碼到工作流程的最短路徑。

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 / 廣泛搜尋。