Que fait Matrix App Builder ?
Quand l'utiliser
Utilisez cette compétence lorsque l'utilisateur demande de construire, créer, corriger, reconcevoir ou publier une application Matrix OS.
Non-négociables
- Construire des applications destinées aux utilisateurs dans
~/apps/<slug>/. - Par défaut, utiliser Vite, React 19, TypeScript et
runtime: "vite". - Les applications CRM, roadmap, tableau de bord, admin et celles avec beaucoup de données restent des SPA Vite React par défaut. Utilisez les API de pont Matrix/Postgres pour les données au lieu de créer des routes API Next.js.
- Ne créez pas de fichiers Next.js,
.next/,app/router,runtime: "node",serve.startounpm startsauf si l'utilisateur demande explicitement un serveur d'exécution ou Next.js. - Ne créez pas d'applications HTML simples sauf si l'utilisateur demande explicitement une application HTML simple.
- Créez ou mettez toujours à jour
matrix.json. Pour les applications construites pour le propriétaire, incluezlistingTrust: "first_party"etscope: "personal"; les blocs de confiance manquants empêchent le lancement même si la construction réussit. Ne renommez jamais les applications téléchargées/communautaires pour contourner la politique. - Exécutez toujours
pnpm installlorsque les dépendances changent etpnpm buildavant de dire que l'application fonctionne. - Vérifiez que
dist/index.htmlexiste. - Utilisez les variables de thème Matrix injectées et un dimensionnement sûr pour les iframes. Les applications personnalisées doivent hériter du thème du shell par défaut ; ajoutez une marque explicite uniquement lorsque l'utilisateur le demande ou que l'application a une raison de domaine claire.
- Pour l'interface utilisateur, lisez
matrix-design-system,matrix-app-ui-patternset App craft. Découvrez et lisez les fichiers SKILL.md installésemil-design-engetapple-designavant de concevoir ; utilisezanimatepour un travail de mouvement spécifique. Respectez les règles du thème/de l'exécution Matrix et choisissez la disposition, les matériaux et le mouvement en fonction de l'objectif réel de l'application. - Stockez les données structurées de l'application via les API de pont Matrix/Postgres, pas via des bases de données locales ad hoc.
- Ne mettez jamais de secrets de fournisseur, de clés API ou de jetons OAuth dans le répertoire de l'application.
- N'utilisez pas le
localStoragedu navigateur comme persistance d'application dans le shell Matrix. Les iframes sandboxées peuvent leverSecurityError; utilisezwindow.MatrixOS.dbet gardez les chemins de repli locaux en mode test uniquement / sans opération. - Pour les applications par défaut ou first-party sous
home/apps/**, gardez les manifests déterministes :runtime: "vite",build.output: "dist", les colonnes de schéma déclarées dansstorage.tables, eticonpointant vers un asset commité danshome/system/icons/.
Workflow de conception
Avant l'échafaudage, lisez la référence de conception et les compétences de conception installées. Choisissez une direction de conception concise et un flux utilisateur principal. Construisez d'abord l'interaction de base, ajoutez des retours intentionnels, puis inspectez et affinez l'application en cours d'exécution dans Matrix. Évitez un héros de bienvenue générique, des cartes de statistiques décoratives, des conteneurs en verre répétés et des entrées échelonnées automatiques. Enregistrez les compétences et les surfaces que vous avez effectivement vérifiées.
Structure standard
~/apps/<slug>/
matrix.json
package.json
vite.config.ts
tsconfig.json
index.html
src/
main.tsx
App.tsx
App.css
dist/
index.html
Manifeste
Utilisez cette base et ajustez le nom, la description, la catégorie, l'icône et les tables de stockage de l'application :
{
"name": "Mon Application",
"description": "Une description concise de l'application",
"slug": "mon-application",
"version": "1.0.0",
"runtime": "vite",
"runtimeVersion": "^1.0.0",
"listingTrust": "first_party",
"scope": "personal",
"icon": "mon-application",
"category": "productivity",
"build": {
"command": "pnpm build",
"output": "dist"
},
"storage": {
"tables": {}
}
}
Les types de colonnes de stockage valides incluent text, boolean, integer, float, timestamptz, jsonb et uuid.
Présentation des applications et des graphiques dans le Chat
Après avoir vérifié l'application, liez son répertoire relatif au propriétaire, par exemple [Adoption IA](~/apps/ai-adoption). Electron Desktop résout les répertoires d'applications installées par rapport au catalogue d'applications et les ouvre via le comportement normal du lanceur. Ne prétendez pas qu'un dossier arbitraire est une application installée.
Affichez les graphiques ou captures d'écran enregistrés avec des images Markdown et des chemins complets relatifs au propriétaire, par exemple . Electron Desktop peut afficher ces images et les ouvrir dans l'aperçu de fichier ; ne dites pas à l'utilisateur que les images ne peuvent apparaître que dans le terminal de l'agent. Utilisez des liens Markdown pour les autres fichiers enregistrés. Les aperçus HTML statiques sont sandboxés sans scripts ; liez l'application installée pour un graphique interactif plutôt que de promettre une exécution HTML active dans le Chat. Signalez honnêtement les fichiers manquants ou les échecs d'aperçu.
Nommage
nameest l'étiquette humaine en casse de titre affichée dans le lanceur, le dock et la barre de titre — par exemple"Calorie Tracker","Habit Garden". Rendez-la courte et réelle ; ne montrez jamais le slug aux utilisateurs.slugest l'identifiant en minuscules avec traits d'union utilisé dans les chemins/URLs (^[a-z0-9][a-z0-9-]{0,63}$). Dérivez-le du nom (calorie-tracker). Il est interne — ne l'utilisez pas comme chaîne d'affichage nulle part.
Icône (obligatoire — sinon l'application affiche une vignette cassée)
Le lanceur charge l'icône de chaque application depuis ~/system/icons/<icon>.svg (ou .png) correspondant au champ icon du manifeste. Si vous ne livrez pas ce fichier, /icons/<icon> génère une 404 et l'application obtient une icône cassée/placeholder. Donc toujours :
- Définissez
"icon": "<slug>"dansmatrix.json(utilisez le slug de l'application sauf si vous avez un meilleur nom de concept). - Créez
~/system/icons/<slug>.pngen utilisant le style d'icône livré avec Matrix OS : artwork d'icône d'application skeuomorphique iOS/macOS premium et léger, rendu de produit raffiné à l'Apple, fond blanc cassé clair ou pastel pâle, profondeur subtile en céramique/verre, biseaux doux, reflets brillants, ombres de studio réalistes et un seul grand objet ou symbole tactile en 3D qui représente clairement l'application. Gardez la famille d'icônes alignée avec les accents forêt, crème, braise et profonds de Matrix OS. N'incluez pas de texte, logos, filigranes, fonds transparents, fonds de dock noirs/foncés, remplissage vide ou un cadre d'icône visible séparé ; le shell Matrix possède le rayon de coin final. Gardez l'éclairage et le traitement des matériaux cohérents avec les PNG d'icônes par défaut livrés dans~/system/icons/.
Pour les applications first-party/par défaut, préférez les icônes PNG commitées de home/system/icons/. Les SVG sont acceptables uniquement pour le chrome système ou les retours de compatibilité simples, pas pour les logos d'application nouvellement générés.
Données (Postgres via le pont MatrixOS)
Les applications s'exécutent dans une iframe sandboxée à origine nulle (CSP connect-src 'self'), donc un fetch() direct vers /api/bridge/* est bloqué et localStorage lève SecurityError. Persistez UNIQUEMENT via le pont injecté :
- Déclarez vos tables dans
matrix.jsonstorage.tables(ci-dessus). La passerelle provisionne le schéma Postgres automatiquement — au démarrage pour les applications livrées, et paresseusement à la première requête pour les applications que vous construisez maintenant, donc les appelsdbd'une application fraîchement construite fonctionnent sans redémarrage. - Dans le code, utilisez
window.MatrixOS.db(find/findOne/insert/update/delete/count/onChange). Protégez contreundefined(absent dans les tests unitaires), enveloppez chaque appel danstry/catch(log + erreur visible par l'utilisateur ; jamais un catch nu), mettez à jour l'état local de manière optimiste et réconciliez viaonChange. - Pour les API externes/tierces, utilisez
window.MatrixOS.proxyFetch(url)(liste blanche) — jamais un fetch brut. - N'ajoutez PAS de fallback
localStoragequi s'exécute dans le shell ; cela lève une erreur dans le sandbox. Un cheminlocalStorageavectry/catchprotégé est acceptable uniquement comme no-op pour l'environnement de test unitaire.
Héritage du thème
Le shell injecte les tokens --matrix-* dans chaque iframe d'application pontée et les met à jour lors des changements de thème. Construisez le CSS de l'application sur ces tokens en premier, avec des couleurs littérales uniquement comme fallbacks :
:root {
--app-bg: var(--matrix-bg, #FAFAF9);
--app-fg: var(--matrix-fg, #32352E);
--app-card: var(--matrix-card, #FCFCF8);
--app-primary: var(--matrix-primary, #434E3F);
--app-primary-fg: var(--matrix-primary-fg, #FAFAF5);
--app-accent: var(--matrix-accent, #D06F25);
--app-success: var(--matrix-success, #3A7D44);
--app-warning: var(--matrix-warning, #E0A12E);
--app-danger: var(--matrix-destructive, #D74A3A);
--app-border: var(--matrix-border, #D8D6C7);
}
Utilisez les polices héritées du shell (var(--matrix-font-sans), var(--matrix-font-mono)) au lieu de charger des feuilles de style de polices distantes. N'utilisez pas de palettes de couleurs bleues, vertes ou violettes locales pour l'interface utilisateur par défaut. Si une marque explicite est nécessaire, limitez-la aux tokens de marque nommés et gardez les contrôles système, les états de focus, les couleurs de statut et les panneaux sur les tokens Matrix.
Règles de persistance
- Déclarez chaque champ persisté dans
matrix.jsonstorage.tables, y compris les champs d'audit tels quecreated_at, les colonnes de meilleur score/meilleur temps et les payloads JSONB d'état. - Chargez depuis le stockage du pont au démarrage ; ne semez pas de lignes de fallback en double après le chargement des lignes réelles.
- Annulez les modifications optimistes de l'interface utilisateur en cas d'échec des créations, mises à jour, suppressions et réorganisations. Gardez les suppressions en attente filtrées de l'état visible jusqu'à ce que le pont confirme ou annule.
- Sérialisez les écritures dépendantes qui mettent à jour l'ordre, les meilleurs scores, les compteurs de statistiques ou les lignes d'historique. Évitez de faire deux écritures pontées qui peuvent se chevaucher.
- Gardez les aides uniquement pour le navigateur protégés pour les tests. Dans les iframes de production du shell, l'accès direct au
localStorageet les appelsfetch()bruts vers le pont ne sont pas une persistance fiable.
Applications par défaut First-Party
Lors de l'édition d'applications par défaut groupées dans ce dépôt :
- Gardez les manifests et schémas d'application dans
home/apps/<slug>/matrix.json. - Réutilisez le chemin de build Vite partagé des applications par défaut ; n'ajoutez pas de champs de package/runtime périmés par application sauf si l'application en a vraiment besoin.
- Exécutez
node scripts/build-default-apps.mjs home/appsavant le travail de bundle hôte lorsque le code source de l'application par défaut a changé. - Préférez l'icône partagée
game-centerpour les jeux sauf si une icône concrète livrée existe. - Vérifiez les slugs d'icônes d'application par rapport à
home/system/icons/<slug>.svgou.png; ne comptez jamais sur la génération d'icônes au moment de l'exécution.
Commandes d'échafaudage
Préférez copier le modèle Vite groupé de Matrix lorsqu'il existe :
cp -a ~/apps/_template-vite ~/apps/<slug>
cd ~/apps/<slug>
pnpm install --prefer-offline
pnpm build
test -f dist/index.html
Si le modèle n'est pas présent, créez directement les fichiers Vite standard avec react, react-dom, @vitejs/plugin-react, typescript et vite.
Accès aux données
Utilisez le pont window.MatrixOS.db injecté pour les données structurées. N'appelez pas /api/bridge/query directement depuis le code de l'application ; les applications d'exécution se chargent comme des iframes srcdoc sandboxées, et les appels directs au pont sont bloqués par la limite CORS/CSP du shell.
Exemple CRUD :
const db = window.MatrixOS?.db;
if (!db) throw new Error("Pont de données Matrix indisponible");
const tasks = await db.find("tasks", { orderBy: { created_at: "desc" } });
const created = await db.insert("tasks", { title: "Lancer" });
await db.update("tasks", created.id, { done: true });
await db.delete("tasks", created.id);
Intégrations
Si l'application a besoin de Gmail, Calendar, GitHub, Slack, Drive ou d'un autre fournisseur, utilisez les API d'intégration Matrix ou la compétence matrix-integrations. La plateforme possède les identifiants des fournisseurs. L'application ne stocke jamais de secrets de fournisseur.
Vérification
Avant de signaler comme terminé :
cd ~/apps/<slug>
pnpm build
test -f dist/index.html
node <chemin-résolu-du-répertoire-de-la-compétence-matrix-app-builder>/scripts/verify-app.mjs "$PWD"
Résolvez le répertoire de la compétence à partir du SKILL.md que vous avez chargé ; le script est livré à côté et n'a besoin d'aucune dépendance. Exécutez-le sur le répertoire réel de l'application, pas sur le modèle. Il vérifie le manifeste Vite construit par le propriétaire et le point d'entrée de production ; il ne modifie jamais la confiance et ne prouve pas une connexion en direct.
Lancement et authentification
Matrix fournit l'authentification du propriétaire. Ne construisez pas de page de connexion séparée et ne lisez/copiez pas les identifiants de la passerelle dans l'application. Le lanceur natif obtient un jeton de courte durée via POST /api/apps/<slug>/session-token ; le lancement est /apps/<slug>/. Un listingTrust manquant ou inconnu donne 403 install_blocked_by_policy, pas une connexion expirée. Une application existante que vous venez de construire pour le propriétaire peut voir ses métadonnées manquantes corrigées après avoir vérifié son origine ; ne promouvez jamais silencieusement une application importée. 401 signifie authentification, 403 politique, 409 portée/accusé de réception, 404 découverte, et 5xx une défaillance du serveur. Signalez les erreurs avec précision au lieu de recommander la connexion pour toutes. Ne désactivez pas l'authentification, n'affaiblissez pas la politique, ne redémarrez pas le VPS, et n'ajoutez pas de serveur pour contourner un échec de lancement.
Ouvrez ensuite l'application depuis le lanceur Matrix en utilisant la session authentifiée existante. Vérifiez les assets de l'application, l'icône, les opérations du pont, un aller-retour sauvegarde/réouverture, et les vérifications visuelles/d'état de la référence de conception. Si l'accès au navigateur est indisponible, signalez le lancement et la vérification visuelle comme en attente plutôt que de prétendre que l'application fonctionne. Vérifiez la console/réseau du navigateur pour :
needs_build- 404 pour les chemins du bundle de l'application ou de l'icône
- erreurs CORS provenant d'appels directs au fournisseur
- erreurs React non gérées
