Matrix App Builder
使用するタイミング
ユーザーが Matrix OS アプリの構築、作成、修正、再設計、公開を依頼した場合に使用します。
絶対条件
- ユーザー向けアプリは
~/apps/<slug>/に構築します。 - デフォルトは Vite、React 19、TypeScript、
runtime: "vite"とします。 - CRM、ロードマップ、ダッシュボード、管理画面、データ量の多いアプリでも、デフォルトでは Vite React SPA とします。Next.js の API ルートを作成する代わりに、Matrix/Postgres ブリッジ API を使用してデータを扱います。
- ユーザーが明示的にサーバーランタイムまたは Next.js を要求しない限り、Next.js、
.next/、app/ルーターファイル、runtime: "node"、serve.start、npm startを作成しないでください。 - ユーザーが明示的にプレーン HTML アプリを要求しない限り、プレーン HTML アプリを作成しないでください。
- 常に
matrix.jsonを作成または更新します。オーナー向けに構築されたアプリの場合は、listingTrust: "first_party"とscope: "personal"を含めます。信頼ブロックが欠落していると、ビルドが成功しても起動に失敗する可能性があります。ダウンロード/ストア/コミュニティアプリにポリシーを回避するためにラベルを付け替えないでください。 - 依存関係が変更された場合は常に
pnpm installを実行し、アプリが動作すると言う前にpnpm buildを実行します。 dist/index.htmlが存在することを確認します。- 注入された Matrix テーマ変数と iframe セーフなサイズ設定を使用します。カスタムアプリはデフォルトでシェルテーマを継承する必要があります。ユーザーが明示的に要求した場合、またはアプリに明確なドメイン上の理由がある場合にのみ、明示的なアプリブランディングを追加します。
- UI については、
matrix-design-system、matrix-app-ui-patterns、および App craft を参照してください。デザインする前に、インストールされているemil-design-engとapple-designの SKILL.md ファイルを検出して読み取ってください。特定のモーション作業にはanimateを使用します。Matrix テーマ/ランタイムルールを維持し、アプリの実際の目的に合わせてレイアウト、マテリアル、モーションを選択します。 - 構造化アプリデータは、アドホックなローカルデータベースではなく、Matrix/Postgres ブリッジ API を介して保存します。
- プロバイダーのシークレット、API キー、または OAuth トークンをアプリディレクトリ内に決して配置しないでください。
- Matrix シェル内でのアプリの永続化にブラウザの
localStorageを使用しないでください。サンドボックス化された iframe はSecurityErrorをスローする可能性があります。window.MatrixOS.dbを使用し、ローカルフォールバックパスはテスト専用/無操作にしてください。 home/apps/**以下のデフォルトまたはファーストパーティアプリでは、マニフェストを決定論的に保ちます。runtime: "vite"、build.output: "dist"、storage.tablesで宣言されたスキーマ列、iconはhome/system/icons/にあるコミットされたアセットを指します。
デザインワークフロー
スキャフォールディングの前に、クラフトリファレンスとインストールされているデザインスキルを読んでください。簡潔なデザインの方向性と主要なユーザーフローを選択します。最初にコアインタラクションを構築し、意図的なフィードバックを追加してから、Matrix で実行中のアプリを検査および調整します。一般的なウェルカムヒーロー、装飾的な統計カード、繰り返されるガラスコンテナ、自動的なスタッガードエントランスは避けてください。実際に確認したスキルとサーフェスを記録してください。
標準構造
~/apps/<slug>/
matrix.json
package.json
vite.config.ts
tsconfig.json
index.html
src/
main.tsx
App.tsx
App.css
dist/
index.html
マニフェスト
このベースラインを使用し、アプリ名、説明、カテゴリ、アイコン、ストレージテーブルを調整します:
{
"name": "My App",
"description": "A concise app description",
"slug": "my-app",
"version": "1.0.0",
"runtime": "vite",
"runtimeVersion": "^1.0.0",
"listingTrust": "first_party",
"scope": "personal",
"icon": "my-app",
"category": "productivity",
"build": {
"command": "pnpm build",
"output": "dist"
},
"storage": {
"tables": {}
}
}
有効なストレージ列タイプには、text、boolean、integer、float、timestamptz、jsonb、uuid があります。
チャットでのアプリとチャートの表示
アプリを確認した後、そのオーナー相対ディレクトリにリンクします。例:
[AI Adoption](~/apps/ai-adoption)。Electron Desktop は、インストールされたアプリディレクトリをアプリカタログに対して解決し、通常のランチャーの動作で開きます。任意のフォルダがインストールされたアプリであると主張しないでください。
保存されたチャートやスクリーンショットは、Markdown 画像と完全なオーナー相対パスで表示します。例:。Electron Desktop はこれらの画像を表示し、ファイルプレビューで開くことができます。画像はエージェントのターミナルにしか表示できないとユーザーに伝えないでください。その他の保存ファイルには Markdown リンクを使用します。静的 HTML プレビューはスクリプトなしでサンドボックス化されます。インタラクティブなチャートには、Chat 内でのアクティブな HTML 実行を約束するのではなく、インストールされたアプリにリンクしてください。ファイルが見つからない場合やプレビューが失敗した場合は、正直に報告してください。
命名規則
nameは、ランチャー、ドック、タイトルバーに表示される人間向けの Title-Case ラベルです。例:"Calorie Tracker"、"Habit Garden"。短くて現実的な名前にし、スラッグをユーザーに表示しないでください。slugは、パス/URL で使用される小文字のハイフン区切り ID です(^[a-z0-9][a-z0-9-]{0,63}$)。名前から派生させます(calorie-tracker)。これは内部的なものであり、表示文字列としてどこにも使用しないでください。
アイコン(必須 – ないとアプリが壊れたタイルで表示されます)
ランチャーは、マニフェストの icon フィールドに一致する ~/system/icons/<icon>.svg(または .png)から各アプリのアイコンを読み込みます。そのファイルを提供しない場合、/icons/<icon> は 404 になり、アプリは壊れた/プレースホルダーのアイコンになります。 したがって、常に以下を行ってください:
matrix.jsonの"icon"を"<slug>"に設定します(より良いコンセプト名がない限り、アプリスラッグを使用します)。- Matrix OS 出荷アイコンスタイルを使用して
~/system/icons/<slug>.pngを作成します: 軽量プレミアム iOS/macOS スキューモーフィックアプリアイコンアートワーク、洗練された Apple ライクなプロダクトレンダリング、明るい温かみのあるオフホワイトまたは淡いパステル背景、微妙なセラミック/ガラスの奥行き、ソフトなベベル、光沢のあるハイライト、リアルなスタジオシャドウ、アプリを明確に表現する単一の大きな触覚的な 3D オブジェクトまたはシンボル。アイコンファミリーを Matrix OS のフォレスト、クリーム、エンバー、ディープアクセントに合わせてください。テキスト、ロゴ、透かし、透明な背景、黒/暗いドックの背景、空のパディング、または別個の表示可能なアイコンフレームを含めないでください。Matrix シェルが最終的な角丸を所有します。ライティングとマテリアル処理を~/system/icons/の出荷されたデフォルトアプリアイコンの PNG と一貫させてください。
ファーストパーティ/デフォルトアプリの場合、home/system/icons/ からコミットされた PNG アイコンを優先してください。SVG は、システムクロームまたは単純な互換性フォールバックにのみ許容され、新しく生成されたアプロゴには使用しないでください。
データ(MatrixOS ブリッジ経由の Postgres)
アプリはサンドボックス化された null オリジン iframe(CSP connect-src 'self')内で実行されるため、/api/bridge/* への直接の fetch() はブロックされ、localStorage は SecurityError をスローします。注入されたブリッジを介してのみ永続化します:
matrix.jsonのstorage.tables(上記)でテーブルを宣言します。ゲートウェイは Postgres スキーマを自動的にプロビジョニングします。出荷されたアプリの場合は起動時に、現在構築しているアプリの場合は最初のクエリで遅延して行われるため、新しくビルドされたアプリのdb呼び出しは再起動なしで動作します。- コードでは
window.MatrixOS.db(find/findOne/insert/update/delete/count/onChange)を使用します。undefinedをガードし(ユニットテストには存在しません)、すべての呼び出しをtry/catchでラップし(ログ + ユーザー向けエラー。ベアキャッチは不可)、ローカル状態を楽観的に更新し、onChangeで調整します。 - 外部/サードパーティ API には
window.MatrixOS.proxyFetch(url)(許可リスト)を使用します。生の fetch は使用しないでください。 - シェルで実行される
localStorageフォールバックを追加しないでください。サンドボックスでスローされます。ガードされたtry/catchlocalStorage パスは、ユニットテスト環境のための無操作としてのみ許容されます。
テーマの継承
シェルは、すべてのブリッジされたアプリの iframe に --matrix-* トークンを注入し、テーマの変更時にそれらを更新します。アプリの CSS はこれらのトークンを最初に使用して構築し、リテラルカラーはフォールバックとしてのみ使用します:
: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);
}
リモートフォントスタイルシートをロードする代わりに、継承されたシェルフォント(var(--matrix-font-sans)、var(--matrix-font-mono))を使用します。デフォルトの UI にアプリローカルの青、緑、紫のパレットを使用しないでください。明示的なアプリブランディングが必要な場合は、名前付きブランドトークンにスコープし、システムコントロール、フォーカス状態、ステータスカラー、パネルは Matrix トークンに保ちます。
永続化ルール
matrix.jsonのstorage.tablesですべての永続化フィールドを宣言します。これには、created_atなどの監査フィールド、ベストスコア/ベストタイム列、JSONB ステートペイロードが含まれます。- 起動時にブリッジストレージからロードします。実際の行がロードされた後に重複するフォールバック行をシードしないでください。
- 失敗した作成、更新、削除、並べ替えの際は、楽観的 UI の変更をロールバックします。ブリッジが確認またはロールバックするまで、保留中の削除は表示状態からフィルタリングしておきます。
- 順序、ベストスコア、統計カウンター、履歴行を更新する依存書き込みをシリアル化します。互いの派生状態を上書きする可能性のある 2 つのブリッジ書き込みの競合を避けてください。
- ブラウザ専用のヘルパーはテスト用にガードしておきます。本番環境のシェル iframe では、直接の
localStorageアクセスと生のブリッジfetch()呼び出しは信頼できる永続化手段ではありません。
ファーストパーティデフォルトアプリ
このリポジトリ内のバンドルされたデフォルトアプリを編集する場合:
- アプリのマニフェストとスキーマは
home/apps/<slug>/matrix.jsonに保持します。 - 共有のデフォルトアプリ Vite ビルドパスを再利用します。アプリが本当に必要としない限り、古くなったアプリごとのパッケージ/ランタイムフィールドを追加しないでください。
- デフォルトアプリのソースが変更された場合は、ホストバンドル作業の前に
node scripts/build-default-apps.mjs home/appsを実行します。 - ゲームには、具体的な出荷アイコンが存在しない限り、共有の
game-centerアイコンを優先します。 - アプリアイコンのスラッグが
home/system/icons/<slug>.svgまたは.pngに対して検証されていることを確認します。ランタイムでのアイコン生成に依存しないでください。
スキャフォールドコマンド
Matrix のバンドルされた Vite テンプレートが存在する場合は、それをコピーすることを優先します:
cp -a ~/apps/_template-vite ~/apps/<slug>
cd ~/apps/<slug>
pnpm install --prefer-offline
pnpm build
test -f dist/index.html
テンプレートが存在しない場合は、react、react-dom、@vitejs/plugin-react、typescript、vite を使用して、標準の Vite ファイルを直接作成します。
データアクセス
構造化データには、注入された window.MatrixOS.db ブリッジを使用します。アプリコードから /api/bridge/query を直接呼び出さないでください。ランタイムアプリはサンドボックス化された srcdoc iframe として読み込まれ、直接のブリッジフェッチはシェルの CORS/CSP 境界によってブロックされます。
CRUD の例:
const db = window.MatrixOS?.db;
if (!db) throw new Error("Matrix data bridge is unavailable");
const tasks = await db.find("tasks", { orderBy: { created_at: "desc" } });
const created = await db.insert("tasks", { title: "Ship" });
await db.update("tasks", created.id, { done: true });
await db.delete("tasks", created.id);
統合
アプリが Gmail、Calendar、GitHub、Slack、Drive、またはその他のプロバイダーを必要とする場合は、Matrix 統合 API または matrix-integrations スキルを使用します。プラットフォームがプロバイダーの資格情報を所有します。アプリはプロバイダーのシークレットを保存しません。
検証
完了を報告する前に:
cd ~/apps/<slug>
pnpm build
test -f dist/index.html
node <resolved-matrix-app-builder-skill-directory>/scripts/verify-app.mjs "$PWD"
読み込んだ SKILL.md からスキルディレクトリを解決します。スクリプトはその隣に配置され、依存関係は必要ありません。テンプレートではなく、実際のアプリディレクトリで実行します。オーナーがビルドした Vite マニフェストとプロダクションエントリを検証します。トラストを変更したり、ライブログインを証明したりすることはありません。
起動と認証
Matrix はオーナー認証を提供します。別のログインページを構築したり、ゲートウェイの資格情報をアプリに読み取ったりコピーしたりしないでください。ネイティブランチャーは、POST /api/apps/<slug>/session-token を介して短期間のトークンを取得します。起動は /apps/<slug>/ です。listingTrust が欠落しているか不明な場合、期限切れのログインではなく 403 install_blocked_by_policy が返されます。あなたがオーナー向けにビルドしたばかりの既存のアプリは、その起源を確認した後で欠落しているメタデータを修正できます。インポートされたアプリを静かに昇格させないでください。401 は認証、403 はポリシー、409 はスコープ/確認、404 は検出、5xx はサーバー障害を示します。すべての失敗に対してサインインを推奨するのではなく、正確に報告してください。起動障害を回避するために、認証を無効にしたり、ポリシーを弱めたり、VPS を再起動したり、サーバーを追加したりしないでください。
次に、既存の認証済みセッションを使用して、Matrix ランチャーからアプリを開きます。アプリアセット、アイコン、ブリッジ操作、保存/再オープンのラウンドトリップ、およびクラフトリファレンスのビジュアル/状態チェックを確認します。ブラウザアクセスが利用できない場合は、アプリが動作すると主張するのではなく、起動とビジュアル検証が保留中であると報告してください。ブラウザのコンソール/ネットワークで以下を確認します:
needs_build- アプリバンドルまたはアイコンパスに対する 404
- 直接のプロバイダー呼び出しからの CORS エラー
- 未処理の React エラー
