Communitygithub.com

HamedMP/matrix-os

Erstellen Sie Matrix OS Apps als Vite React TypeScript-Projekte mit matrix.json-Manifesten, Matrix-Theme-Integration, Postgres-gestützten App-Daten und Produktions-Build-Verifizierung.

Was ist matrix-os?

Diese Fähigkeit ermöglicht es KI-Agenten, vollständige Matrix OS Apps zu erstellen, zu bearbeiten und zu veröffentlichen. Sie definiert einen strengen Workflow mit Vite, React 19 und TypeScript als Standard-Stack und nutzt die Matrix/Postgres-Bridge für persistente Daten, anstatt lokale Datenbanken oder Next.js-Routen zu verwenden. Die Fähigkeit unterstützt die Integration des Matrix-Designsystems, die automatische Theme-Vererbung und die Erstellung von App-Icons im Matrix-Stil. Sie stellt sicher, dass jede App ein `matrix.json`-Manifest besitzt, einen erfolgreichen `pnpm build` durchläuft und über eine verifizierte `dist/index.html` verfügt. Plattformen: Claude Code, Cursor und andere agentenbasierte Entwicklungstools, die SKILL.md verarbeiten.

Funktioniert mit✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/HamedMP/matrix-os/tree/HEAD/skills/matrix/app-builder

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Vorschau

Aus dem Skill-README

KI-Adoptionsdiagramm

Dokumentation

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.start oder npm 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 Sie listingTrust: "first_party" und scope: "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 install aus, wenn sich Abhängigkeiten geändert haben, und pnpm build, bevor Sie sagen, dass die App funktioniert.
  • Überprüfen Sie, ob dist/index.html existiert.
  • 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-patterns und App craft. Entdecken und lesen Sie die installierten emil-design-eng- und apple-design-SKILL.md-Dateien vor dem Design; verwenden Sie animate fü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 localStorage des Browsers als App-Persistenz in der Matrix-Shell. Sandbox-Iframes können SecurityError auslösen; verwenden Sie window.MatrixOS.db und 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 in storage.tables deklariert sind, und icon, das auf ein committetes Asset in home/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 ![KI-Adoptionsdiagramm](~/apps/ki-adoption/diagramm-hell.png). 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

  • name ist 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.
  • slug ist 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:

  1. Setzen Sie "icon": "<slug>" in matrix.json (verwenden Sie den App-Slug, es sei denn, Sie haben einen besseren Konzeptnamen).
  2. Erstellen Sie ~/system/icons/<slug>.png im 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.json storage.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 gegen undefined (es fehlt in Unit-Tests), umschließen Sie jeden Aufruf mit try/catch (loggen + benutzersichtbarer Fehler; niemals einen nackten Catch), aktualisieren Sie den lokalen Zustand optimistisch und gleichen Sie bei onChange ab.
  • 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 bewachter try/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.json storage.tables, einschließlich Audit-Feldern wie created_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/apps vor 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>.svg oder .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

Verwandte Skills