Matrix App Builder
Verwendung
Verwenden Sie dies, wenn der Benutzer bittet, eine Matrix OS App zu erstellen, zu bauen, zu reparieren, neu zu gestalten oder zu veröffentlichen.
Unverhandelbare Grundsätze
- Benutzer-Apps in
~/apps/<slug>/erstellen. - Standardmäßig Vite, React 19, TypeScript und
runtime: "vite"verwenden. - CRM-, Roadmap-, Dashboard-, Admin- und datenintensive Apps sind standardmäßig dennoch Vite React SPAs. Verwenden Sie Matrix/Postgres-Bridge-APIs für Daten anstatt Next.js-API-Routen zu erstellen.
- Erstellen Sie kein Next.js,
.next/,app/-Router-Dateien,runtime: "node",serve.startodernpm start, es sei denn, der Benutzer fordert explizit eine Server-Laufzeitumgebung oder Next.js an. - Erstellen Sie keine reinen HTML-Apps, es sei denn, der Benutzer fordert explizit eine reine HTML-App an.
- Erstellen oder aktualisieren Sie immer
matrix.json. Für Apps, die für den Besitzer erstellt wurden, fügen SielistingTrust: "first_party"undscope: "personal"hinzu; fehlende Trust-Blöcke verhindern den Start, selbst wenn der Build erfolgreich ist. Ändern Sie niemals die Bezeichnung heruntergeladener/Store/Community-Apps, um Richtlinien zu umgehen. - Führen Sie immer
pnpm installaus, wenn sich Abhängigkeiten geändert haben, undpnpm build, bevor Sie sagen, dass die App funktioniert. - Überprüfen Sie, ob
dist/index.htmlexistiert. - Verwenden Sie die injizierten Matrix-Theme-Variablen und iframe-sichere Größenangaben. Benutzerdefinierte Apps sollten standardmäßig das Shell-Theme erben; fügen Sie explizites App-Branding nur hinzu, wenn der Benutzer danach fragt oder die App einen klaren inhaltlichen Grund hat.
- Lesen Sie für die UI
matrix-design-system,matrix-app-ui-patternsund App craft. Entdecken und lesen Sie die installiertenemil-design-eng- undapple-design-SKILL.md-Dateien vor dem Design; verwenden Sieanimatefür spezifische Bewegungsarbeit. Beachten Sie die Matrix-Theme/Laufzeitregeln und wählen Sie Layout, Materialien und Bewegung für den tatsächlichen Zweck der App. - Speichern Sie strukturierte App-Daten über Matrix/Postgres-Bridge-APIs, nicht über Ad-hoc-lokale Datenbanken.
- Geben Sie niemals Anbietergeheimnisse, API-Schlüssel oder OAuth-Token in das App-Verzeichnis.
- Verwenden Sie kein
localStoragedes Browsers als App-Persistenz in der Matrix-Shell. Sandbox-Iframes könnenSecurityErrorauslösen; verwenden Siewindow.MatrixOS.dbund halten Sie lokale Fallback-Pfade test-only/no-op. - Halten Sie für Standard- oder First-Party-Apps unter
home/apps/**die Manifeste deterministisch:runtime: "vite",build.output: "dist", Schema-Spalten, die instorage.tablesdeklariert sind, undicon, das auf ein committetes Asset inhome/system/icons/zeigt.
Design-Workflow
Bevor Sie mit dem Gerüstbau beginnen, lesen Sie die Craft-Referenz und die installierten Design-Fähigkeiten. Wählen Sie eine prägnante Designrichtung und einen primären Benutzerfluss. Bauen Sie zuerst die Kerninteraktion, fügen Sie zielgerichtetes Feedback hinzu und überprüfen und verfeinern Sie die laufende App in Matrix. Vermeiden Sie einen generischen Willkommens-Hero, dekorative Statistik-Karten, wiederholte Glas-Container und automatische gestaffelte Eingänge. Dokumentieren Sie, welche Fähigkeiten und Oberflächen Sie tatsächlich überprüft haben.
Standardstruktur
~/apps/<slug>/
matrix.json
package.json
vite.config.ts
tsconfig.json
index.html
src/
main.tsx
App.tsx
App.css
dist/
index.html
Manifest
Verwenden Sie diese Basislinie und passen Sie den App-Namen, die Beschreibung, die Kategorie, das Icon und die Speichertabellen an:
{
"name": "Meine App",
"description": "Eine prägnante App-Beschreibung",
"slug": "meine-app",
"version": "1.0.0",
"runtime": "vite",
"runtimeVersion": "^1.0.0",
"listingTrust": "first_party",
"scope": "personal",
"icon": "meine-app",
"category": "produktivitaet",
"build": {
"command": "pnpm build",
"output": "dist"
},
"storage": {
"tables": {}
}
}
Gültige Speicher-Spalten-Typen umfassen text, boolean, integer, float, timestamptz, jsonb und uuid.
Präsentation von Apps und Diagrammen im Chat
Nach der Überprüfung der App verlinken Sie das besitzerrelative Verzeichnis, zum Beispiel
[KI-Adoption](~/apps/ki-adoption). Electron Desktop löst die installierten App-Verzeichnisse
gegen den App-Katalog auf und öffnet sie über das normale Launcher-Verhalten.
Behaupten Sie nicht, dass ein beliebiger Ordner eine installierte App sei.
Zeigen Sie gespeicherte Diagramme oder Screenshots mit Markdown-Bildern und vollständigen besitzerrelativen
Pfaden an, zum Beispiel .
Electron Desktop kann diese Bilder anzeigen und in der Dateivorschau öffnen; sagen Sie dem Benutzer nicht,
dass Bilder nur im Terminal des Agenten erscheinen können. Verwenden Sie Markdown-Links für
andere gespeicherte Dateien. Statische HTML-Vorschauen sind ohne Skripte sandboxed; verlinken Sie
die installierte App für ein interaktives Diagramm, anstatt eine aktive HTML-Ausführung
innerhalb des Chats zu versprechen. Melden Sie fehlende Dateien oder fehlgeschlagene Vorschauen wahrheitsgemäß.
Namensgebung
nameist das menschliche, Title-Case-Label, das im Launcher, Dock und Titelleiste angezeigt wird — z.B."Kalorien-Tracker","Gewohnheits-Garten". Machen Sie es kurz und echt; zeigen Sie den Slug niemals Benutzern.slugist die kleingeschriebene, mit Bindestrichen versehene ID, die in Pfaden/URLs verwendet wird (^[a-z0-9][a-z0-9-]{0,63}$). Leiten Sie ihn vom Namen ab (kalorien-tracker). Er ist intern — verwenden Sie ihn nirgendwo als Anzeigestring.
Icon (erforderlich – sonst zeigt die App eine defekte Kachel)
Der Launcher lädt das Icon jeder App aus ~/system/icons/<icon>.svg (oder .png) entsprechend dem
Icon-Feld des Manifests. Wenn Sie diese Datei nicht ausliefern, führt /icons/<icon> zu einem 404 und die App erhält ein defektes/Platzhalter-Icon.
Daher immer:
- Setzen Sie
"icon": "<slug>"inmatrix.json(verwenden Sie den App-Slug, es sei denn, Sie haben einen besseren Konzeptnamen). - Erstellen Sie
~/system/icons/<slug>.pngim ausgelieferten Matrix-OS-Icon-Stil: leichtes, hochwertiges iOS/macOS-Skeuomorph-App-Icon-Artwork, verfeinerte Apple-ähnliche Produktdarstellung, heller, warmer, gebrochener Weiß- oder heller Pastellhintergrund, subtile Keramik/Glas-Tiefe, weiche Facetten, glänzende Highlights, realistische Studioschatten und ein einzelnes großes taktiles 3D-Objekt oder Symbol, das die App klar repräsentiert. Halten Sie die Icon-Familie an Matrix-OS-Wald-, Sahne-, Glut- und Tiefen-Akzente ausgerichtet. Fügen Sie keinen Text, Logos, Wasserzeichen, transparente Hintergründe, schwarze/dunkle Dock-Hintergründe, leere Abstände oder einen separaten sichtbaren Icon-Rahmen hinzu; die Matrix-Shell besitzt den endgültigen Eckenradius. Halten Sie die Licht- und Materialbehandlung konsistent mit den ausgelieferten Standard-App-PNGs in~/system/icons/.
Für First-Party/Standard-Apps bevorzugen Sie committete PNG-Icons aus home/system/icons/. SVGs sind nur
für System-Chrome oder einfache Kompatibilitäts-Fallbacks akzeptabel, nicht für neu generierte App-Logos.
Daten (Postgres über die MatrixOS-Bridge)
Apps laufen in einem sandboxed Iframe ohne Herkunft (CSP connect-src 'self'), daher ist ein direkter fetch() nach
/api/bridge/* blockiert und localStorage wirft SecurityError. Persistieren Sie NUR über die
injizierte Bridge:
- Deklarieren Sie Ihre Tabellen in
matrix.jsonstorage.tables(oben). Das Gateway stellt das Postgres-Schema automatisch bereit – beim Start für ausgelieferte Apps und lazy beim ersten Query für Apps, die Sie jetzt bauen, so dass ein frisch gebauter App-db-Aufruf ohne Neustart funktioniert. - Verwenden Sie im Code
window.MatrixOS.db(find/findOne/insert/update/delete/count/onChange). Schützen Sie gegenundefined(es fehlt in Unit-Tests), umschließen Sie jeden Aufruf mittry/catch(loggen + benutzersichtbarer Fehler; niemals einen nackten Catch), aktualisieren Sie den lokalen Zustand optimistisch und gleichen Sie beionChangeab. - Verwenden Sie für externe/Drittanbieter-APIs
window.MatrixOS.proxyFetch(url)(whitelist) – niemals einen rohen Fetch. - Fügen Sie KEINEN
localStorage-Fallback hinzu, der in der Shell läuft; er wirft in der Sandbox. Ein bewachtertry/catch-localStorage-Pfad ist nur als No-Op für die Unit-Test-Umgebung akzeptabel.
Theme-Vererbung
Die Shell injiziert --matrix-*-Token in jeden überbrückten App-Iframe und aktualisiert sie bei Theme-Änderungen. Bauen Sie App-CSS auf diesen Token zuerst auf, mit literalen Farben nur als 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);
}
Verwenden Sie die geerbten Shell-Schriftarten (var(--matrix-font-sans), var(--matrix-font-mono)) anstatt entfernte Schriftarten-Stylesheets zu laden. Verwenden Sie keine applokalen Blau-, Grün- oder Lila-Paletten für die Standard-UI. Wenn explizites App-Branding erforderlich ist, beschränken Sie es auf benannte Marken-Token und behalten Sie Systemsteuerelemente, Fokus-Zustände, Statusfarben und Panels auf den Matrix-Token.
Persistenzregeln
- Deklarieren Sie jedes persistierte Feld in
matrix.jsonstorage.tables, einschließlich Audit-Feldern wiecreated_at, Best-Ergebnis/Bestzeit-Spalten und JSONB-Zustands-Payloads. - Laden Sie beim Start aus dem Bridge-Speicher; führen Sie keine doppelten Fallback-Zeilen ein, nachdem echte Zeilen geladen wurden.
- Machen Sie optimistische UI-Änderungen bei fehlgeschlagenen Creates, Updates, Deletes und Reorders rückgängig. Halten Sie ausstehende Deletes aus dem sichtbaren Zustand herausgefiltert, bis die Bridge sie bestätigt oder zurückrollt.
- Serialisieren Sie abhängige Schreibvorgänge, die Reihenfolge, Best-Ergebnisse, Statistikzähler oder Verlaufszeilen aktualisieren. Vermeiden Sie Rennbedingungen zwischen zwei Bridge-Schreibvorgängen, die den abgeleiteten Zustand gegenseitig überschreiben können.
- Halten Sie reine Browser-Helfer für Tests bewacht. In Produktions-Shell-Iframes sind direkter
localStorage-Zugriff und rohe Bridge-fetch()-Aufrufe keine zuverlässige Persistenz.
First-Party-Standard-Apps
Beim Bearbeiten von gebündelten Standard-Apps in diesem Repository:
- Halten Sie App-Manifeste und Schema in
home/apps/<slug>/matrix.json. - Verwenden Sie den gemeinsam genutzten Standard-App-Vite-Build-Pfad wieder; fügen Sie keine veralteten Pro-Paket/Laufzeit-Felder hinzu, es sei denn, die App benötigt sie wirklich.
- Führen Sie
node scripts/build-default-apps.mjs home/appsvor der Host-Bündelung aus, wenn sich der Quellcode der Standard-App geändert hat. - Bevorzugen Sie das gemeinsame
game-center-Icon für Spiele, es sei denn, ein konkretes ausgeliefertes Icon existiert. - Überprüfen Sie die App-Icon-Slugs gegen
home/system/icons/<slug>.svgoder.png; verlassen Sie sich niemals auf die Laufzeit-Icon-Generierung.
Gerüstbau-Befehle
Bevorzugen Sie das Kopieren der gebündelten Vite-Vorlage von Matrix, wenn sie existiert:
cp -a ~/apps/_template-vite ~/apps/<slug>
cd ~/apps/<slug>
pnpm install --prefer-offline
pnpm build
test -f dist/index.html
Wenn die Vorlage nicht vorhanden ist, erstellen Sie die Standard-Vite-Dateien direkt mit react, react-dom, @vitejs/plugin-react, typescript und vite.
Datenzugriff
Verwenden Sie die injizierte window.MatrixOS.db-Bridge für strukturierte Daten. Rufen Sie /api/bridge/query
nicht direkt aus App-Code auf; Laufzeit-Apps werden als sandboxed srcdoc-Iframes geladen, und direkte Bridge-Abrufe
werden von der CORS/CSP-Grenze der Shell blockiert.
Beispiel CRUD:
const db = window.MatrixOS?.db;
if (!db) throw new Error("Matrix-Datenbrücke ist nicht verfügbar");
const tasks = await db.find("tasks", { orderBy: { created_at: "desc" } });
const created = await db.insert("tasks", { title: "Ausliefern" });
await db.update("tasks", created.id, { done: true });
await db.delete("tasks", created.id);
Integrationen
Wenn die App Gmail, Kalender, GitHub, Slack, Drive oder einen anderen Anbieter benötigt, verwenden Sie Matrix-Integrations-APIs oder die matrix-integrations-Fähigkeit. Die Plattform besitzt die Anbieteranmeldeinformationen. Die App speichert niemals Anbietergeheimnisse.
Verifizierung
Bevor Sie die Fertigstellung melden:
cd ~/apps/<slug>
pnpm build
test -f dist/index.html
node <aufgelöstes-matrix-app-builder-skill-verzeichnis>/scripts/verify-app.mjs "$PWD"
Lösen Sie das Skill-Verzeichnis aus der SKILL.md auf, die Sie geladen haben; das Skript wird daneben ausgeliefert und benötigt keine Abhängigkeiten. Führen Sie es im tatsächlichen App-Verzeichnis aus, nicht in der Vorlage. Es verifiziert das vom Besitzer erstellte Vite-Manifest und den Produktionseinstieg; es ändert niemals das Vertrauen oder beweist einen Live-Login.
Start und Authentifizierung
Matrix stellt die Besitzerauthentifizierung bereit. Bauen Sie keine separate Login-Seite und lesen/kopieren Sie keine Gateway-Anmeldeinformationen in die App. Der native Launcher erhält ein kurzlebiges Token über POST /api/apps/<slug>/session-token; der Start erfolgt über /apps/<slug>/. Fehlendes oder unbekanntes listingTrust führt zu 403 install_blocked_by_policy, nicht zu einem abgelaufenen Login. Eine vorhandene App, die Sie gerade für den Besitzer erstellt haben, kann nach Überprüfung ihrer Herkunft ihre fehlenden Metadaten korrigiert bekommen; bewerben Sie eine importierte App niemals stillschweigend. 401 bedeutet Authentifizierung, 403 Richtlinie, 409 Bereich/Bestätigung, 404 Erkennung und 5xx einen Serverfehler. Melden Sie Fehler genau, anstatt für alle eine Anmeldung zu empfehlen. Deaktivieren Sie keine Authentifizierung, schwächen Sie keine Richtlinie, starten Sie den VPS nicht neu und fügen Sie keinen Server hinzu, um einen Startfehler zu umgehen.
Öffnen Sie dann die App über den Matrix-Launcher unter Verwendung der vorhandenen authentifizierten Sitzung. Überprüfen Sie App-Assets, Icon, Bridge-Operationen, einen Speichern/Erneut-Öffnen-Zyklus und die visuellen/Zustandsprüfungen der Craft-Referenz. Wenn der Browserzugriff nicht verfügbar ist, melden Sie den Start und die visuelle Verifizierung als ausstehend, anstatt zu behaupten, die App funktioniert. Überprüfen Sie die Browser-Konsole/das Netzwerk auf:
needs_build- 404s für App-Bundle- oder Icon-Pfade
- CORS-Fehler von direkten Anbieteraufrufen
- unbehandelte React-Fehler
