CloudBase AI Toolkit

CloudBase Tout-en-Un

Flux de travail

Chaque tâche CloudBase suit ce processus en trois étapes :

1. Exploration  →  Lisez la compétence correspondante en entier avant d'écrire du code.
                   Recherchez-la si nécessaire, puis lisez le contenu complet du SKILL.md.
                   Commencez à implémenter seulement après avoir compris les schémas d'API,
                   les pièges et l'utilisation correcte à partir du document de compétence.
2. Implémentation
   ├── 2a. Préparation des ressources → Privilégiez MCP pour préparer les ressources backend
   │     (activer les fournisseurs d'authentification, créer des tables de base de données, configurer les domaines de stockage,
   │      définir les règles de sécurité — avant d'écrire le code frontend).
   │     Si les outils MCP sont absents dans CETTE session, configurez MCP pour la prochaine fois et
   │     utilisez l'interface CLI `tcb` maintenant (`./cloudbase-cli/SKILL.md`).
   └── 2b. Implémentation frontend → Écrire le code, installer les dépendances, démarrer le serveur, tester
3. Clôture  →  Exécuter cloudbase-code-review, corriger toutes les erreurs, déclarer terminé

Contraintes clés :

• L'étape 2a (préparation des ressources) doit précéder le code frontend. Privilégiez les outils MCP ; lorsqu'ils ne sont pas encore chargés (première session / avant redémarrage), utilisez l'interface CLI tcb après avoir configuré MCP. N'écrivez pas de code frontend qui dépend de ressources non créées (tables, fournisseurs d'authentification, buckets de stockage) — le correcteur échouera.
• Ne sautez pas l'étape 3. La clôture détecte les pièges connus que les agents oublient souvent lors de l'implémentation.

Périmètre

Ne traitez que les tâches qui font partie de la construction, de l'intégration ou de la maintenance d'une application CloudBase — y compris la conception d'interface, la planification des spécifications et d'autres activités de développement lorsqu'elles sont au service d'une application CloudBase. Si la demande n'a aucun contexte d'application CloudBase, arrêtez-vous et dites à l'utilisateur que cette compétence ne couvre que le développement basé sur CloudBase.

Contrat d'activation

À utiliser en premier lorsque

• La tâche est une construction, une intégration ou une réparation d'application CloudBase et l'espace de travail contient déjà une implémentation d'application.
• La demande mélange authentification, base de données, stockage et travail frontend dans une même tâche d'application CloudBase.

À faire avant une exploration large

• Lisez la compétence pertinente avant d'écrire du code. Recherchez la compétence correspondante avec searchKnowledgeBase(mode="skill", skillName=...), puis Read le chemin de fichier retourné pour obtenir le contenu complet du SKILL.md. Ne commencez pas à implémenter en vous basant uniquement sur le résumé du résultat de recherche — le document complet contient les signatures API, les schémas de paramètres et les avertissements sur les pièges.
• Inspectez d'abord les surfaces d'implémentation existantes :
  • src/lib/backend.*
  • src/lib/auth.*
  • src/lib/*service.*
  • les gardes de route
  • les gestionnaires de page liés aux boutons de soumission de formulaire actifs
• Si ces fichiers contiennent des TODOs, implémentez ces TODOs sur place avant de créer de nouveaux assistants, exemples ou pages de remplacement.
• Ne commencez pas par une refonte d'interface ou une sortie de spécification de conception, sauf si l'utilisateur demande explicitement des modifications visuelles.
• Ne commencez pas par des boucles de gestion de projet telles que des TaskCreate / TaskUpdate répétés lorsque la tâche est une réparation ciblée unique. Lisez les fichiers actifs et modifiez-les directement.

Aiguillez rapidement vers les compétences minimales nécessaires

• Démo Web minimale + base de données / chemin BaaS rapide de type Lovable -> ./minimal-web-baas-demo/SKILL.md (par défaut pour les démos minimales frontend/backend ; BaaS-first, pas de fonctions cloud)
• Exécution d'application Web -> ./web-development/SKILL.md
• Préparation du fournisseur d'authentification Web -> ./auth-tool/SKILL.md
• Implémentation de l'authentification Web -> ./auth-web/SKILL.md
• Données d'application CloudBase PostgreSQL / PG -> ./postgresql-development/SKILL.md
• Intégration WeChat Pay / OAuth de compte officiel via le centre d'intégration CloudBase -> ./cloudbase-wechat-integration/SKILL.md
• CRUD de base de données document côté navigateur -> ./no-sql-web-sdk/SKILL.md
• Téléchargement de fichier côté navigateur -> ./cloud-storage-web/SKILL.md
• Aperçu de la plateforme uniquement lorsque la sélection des capacités est encore floue -> ./cloudbase-platform/SKILL.md
• Si vous utilisez searchKnowledgeBase(mode="skill"), transmettez l'ID de répertoire de référence tel que postgresql-development-cloudbase ou minimal-web-baas-demo, pas un alias deviné.

Garde-fous à haut rendement

• Préparez les ressources backend avant d'écrire du code frontend. Privilégiez MCP pour les fournisseurs d'authentification, les tables de base de données, les domaines de stockage et les règles de sécurité. Si les outils MCP sont absents dans cette session, configurez MCP pour la session suivante et utilisez l'interface CLI tcb maintenant — ne restez pas en attente d'un redémarrage. Le code frontend écrit contre des ressources inexistantes entraînera des échecs du correcteur.
• Protocole de sécurité des modifications : Avant toute modification non triviale de code ou de configuration, vous devez suivre strictement cloudbase-platform/references/protocols/change-safety-protocol.md (déclarer l'impact → obtenir la confirmation de l'utilisateur → vérifier après la modification → escalader vers une analyse des causes profondes après 3 occurrences du même symptôme).
• Porte de déploiement : Avant tout déploiement, publication, domaine personnalisé, CloudRun ou travail d'exposition publique, vous devez effectuer les vérifications dans cloudbase-platform/references/protocols/deployment-gate.md et présenter le modèle de déclaration obligatoire.
• Si le même chemin échoue 2 à 3 fois, arrêtez de réessayer et réorientez-vous. Vérifiez la compétence de plateforme, le domaine d'authentification, l'environnement d'exécution et le modèle d'autorisation avant de modifier davantage de code.
• Spécifiez toujours EnvId explicitement dans le code, la configuration et les exemples de commandes lors de l'initialisation des clients CloudBase ou des opérations de gestion. Ne vous fiez pas à l'environnement sélectionné par l'interface CLI actuelle ou aux valeurs par défaut implicites.
• Si la conversation ne fournit qu'un alias d'environnement, un surnom ou une autre abréviation, résolvez-le avec envQuery(action=list, alias=..., aliasExact=true) et utilisez le EnvId complet canonique retourné avant d'appeler auth.set_env, de générer des liens vers la console ou d'écrire du code/config. Si l'alias est ambigu ou manquant, arrêtez-vous et demandez à l'utilisateur de confirmer.

N'UTILISEZ PAS ceci comme

• Raison de lire chaque compétence CloudBase avant de toucher au code.
• Raison de commencer par un aperçu de la plateforme lorsque le code existant révèle déjà la pile et les éléments manquants.

Règles de travail

1. BaaS-first, fonctions en dernier recours :

   • Pour les démos minimales frontend/backend / de type Lovable, aiguillez d'abord vers ./minimal-web-baas-demo/SKILL.md. Ordre : connecteur prêt → échauffement du modèle pendant l'attente des identifiants → envQuery → verrouiller une DB → schéma MCP → @cloudbase/js-sdk CRUD → aperçu. Nombre de fonctions cloud par défaut = 0.
   • Avant d'écrire une fonction cloud ou un service CloudRun, demandez : la surface JS SDK correcte peut-elle gérer cela directement ? Utilisez db.collection(...).get() uniquement pour les collections NoSQL confirmées ; utilisez app.rdb().from(...) pour les tables CloudBase PG ; utilisez auth / storage à partir de la compétence correspondante.
   • Utilisez directement la surface JS SDK correspondante pour : les lectures/écritures de données, les téléchargements de fichiers, les mises à jour en temps réel, les requêtes simples y compris les classements, les listes, les agrégations.
   • Descendez aux fonctions cloud uniquement lorsque : la logique nécessite une application des autorisations côté serveur qui ne peut pas être exprimée dans les règles de base de données/RLS, l'appel de services tiers (paiement, SMS, API externes), ou des tâches d'arrière-plan non déclenchées par l'utilisateur.
   • Descendez à CloudRun uniquement lorsque : des connexions persistantes (WebSocket), des calculs de longue durée, ou des environnements d'exécution personnalisés sont véritablement nécessaires.

2. Application existante avec des TODOs :

   • Traitez-la comme une tâche de réparation ciblée, pas comme une construction sur un champ vierge.
   • Privilégiez le chemin le plus court du code actuel à un flux de travail fonctionnel.

3. Tâches d'authentification :

   • Si l'identifiant du compte est un nom d'utilisateur simple tel que admin, editor, ou une autre chaîne sans @, traitez la connexion usernamePassword comme une condition préalable bloquante.
   • Appelez d'abord queryAppAuth(action="getLoginConfig").
   • Si loginMethods.usernamePassword !== true, appelez immédiatement manageAppAuth(action="patchLoginStrategy", patch={ usernamePassword: true }).
   • Dans le code de connexion Web, utilisez auth.signInWithPassword({ username, password }).
   • Ne supposez pas que auth.signUp({ username, password }) direct sur le Web est disponible pour tous les environnements ou versions du SDK ; vérifiez d'abord sdkHints / le comportement du SDK installé. Si l'enregistrement par nom d'utilisateur est requis et que l'inscription directe n'est pas prise en charge, acheminez l'enregistrement via un chemin API backend ou de gestion qui crée des utilisateurs CloudBase Auth, sans exposer les clés secrètes dans le code du navigateur.
   • N'utilisez jamais signUpWithEmailAndPassword ou signInWithEmailAndPassword pour ces flux de comptes de type nom d'utilisateur.
   • Une fois la préparation confirmée, revenez au gestionnaire frontend actif et terminez le flux de connexion/inscription réel.

4. Tâches de base de données et de stockage :

   • Réutilisez les assistants app, auth, db et de stockage partagés actuels au lieu de créer des wrappers SDK parallèles.
   • Si la tâche mentionne CloudBase PG, PostgreSQL, Postgres, mode PG, JS SDK v3 PostgreSQL, app.rdb(), queryPgDatabase, managePgDatabase, mysqldb OpenAPI, ou RLS, lisez ./postgresql-development/SKILL.md avant de toucher au code de base de données.
   • Pour CloudBase PG, utilisez queryPgDatabase / managePgDatabase pour le schéma et la gestion ; n'acheminez pas le travail PG vers les API MySQL queryMysqlDatabase / manageMysqlDatabase ou les API de collection NoSQL.
   • Pour la recherche OpenAPI, appelez searchKnowledgeBase({ mode: "openapi", apiName: "mysqldb" }) directement. Ne transmettez pas de valeurs action devinées telles que getApiDocs ou listEndpoints ; celles-ci n'appartiennent à aucun mode d'outil pris en charge.
   • Pour le CRUD Web CloudBase PG, privilégiez les API app.rdb() du JS SDK v3 et les API de stockage documentées app.storage.from() avant le HTTP brut.
   • Pour le téléchargement de stockage CloudBase côté navigateur à partir de Vite/preview local, vérifiez d'abord le host:port réel du navigateur dans les domaines de sécurité (envQuery(action="domains"), puis envDomainManagement(action="create") si manquant). Un échec de téléchargement de couverture ne doit pas ignorer silencieusement l'insertion d'article PG suivante.
   • Pour db.collection(...).add(...) du SDK Web CloudBase, persistez l'ID de document créé depuis result._id.
   • Pour les écritures, validez le résultat réel du SDK au lieu de supposer le succès.
   • Carte STOP API héritée : Si la tâche dit PostgreSQL, CloudBase PG, mode PG, app.rdb(), queryPgDatabase, managePgDatabase, PostgREST, ou RLS, n'écrivez pas d'exemples NoSQL de mémoire. Utilisez app.rdb().from(...) pour le CRUD Web, queryPgDatabase / managePgDatabase pour la gestion, et auth.getSession() pour les gardes d'authentification Web. N'utilisez pas app.database(), db.collection(...), .where(), .orderBy(), app.uploadFile(), getLoginState(), ou auth.getUser() comme valeur par défaut pour PG/auth.

5. Tâches de réparation ciblées :

   • La clôture fonctionnelle prime sur l'exploration.
   • Évitez les analyses larges du dépôt, la refonte de l'interface utilisateur et le code de démonstration détaché.
   • Limitez la découverte de fichiers. Privilégiez les lectures directes des fichiers actifs connus plutôt que Glob / une recherche large dans l'ensemble du projet.