Communitygithub.com

HamedMP/matrix-os

建立 Matrix OS 應用程式,使用 Vite React TypeScript 專案、matrix.json 清單、Matrix 主題整合、Postgres 支援的應用程式資料,以及生產建置驗證。

matrix-os 是什麼?

這是 Matrix OS 的專用技能,用於建置、建立、修復、重新設計或發佈 Matrix OS 應用程式。它強制使用 Vite、React 19 和 TypeScript 作為預設執行環境,並要求始終建立或更新 `matrix.json` 清單。應用程式透過 Matrix/Postgres 橋接 API 將結構化資料儲存在 Postgres 中,而非使用瀏覽器的 `localStorage`,因其在沙盒化 iframe 中會拋出 `SecurityError`。該技能提供了詳細的設計工作流程,強調 Matrix 主題變數繼承、正確的圖示建立(需在 `~/system/icons/` 中提供實際圖示檔案),以及透過 `window.MatrixOS.db` 進行資料存取。它支援 VSCode、Claude Code 和 Cursor,並透過嚴格的非協商事項來確保與 Matrix OS 平台的相容性,例如避免建立 Next.js 應用程式,除非使用者明確要求伺服器執行環境。

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

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

預覽

來自技能 README

AI adoption chart

說明文件

Matrix 應用程式建置器

使用時機

當使用者要求建置、建立、修復、重新設計或發佈 Matrix OS 應用程式時使用。

不可協商事項

  • 在 ~/apps/<slug>/ 中建置面向使用者的應用程式。
  • 預設使用 Vite、React 19、TypeScript 和 runtime: "vite"。
  • CRM、路線圖、儀表板、管理後台和資料密集型應用程式預設仍為 Vite React SPA。使用 Matrix/Postgres 橋接 API 進行資料存取,不要建立 Next.js 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 安全尺寸。自訂應用程式預設應繼承 Shell 主題;僅在使用者要求或應用程式有明確的領域原因時,才加入明確的應用程式品牌。
  • 對於 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 Shell 中使用瀏覽器 localStorage 作為應用程式持久化方式。沙盒化 iframe 可能拋出 SecurityError;請使用 window.MatrixOS.db,並將本地回退路徑保留為僅測試/無操作。
  • 對於 home/apps/** 下的預設或第一方應用程式,保持清單確定性:runtime: "vite"、build.output: "dist"、在 storage.tables 中宣告 schema 欄位,以及 icon 指向 home/system/icons/ 中已提交的資源。

設計工作流程

在建立專案之前,請閱讀 craft 參考文件和已安裝的設計技能。選擇簡潔的設計方向和主要使用者流程。先建立核心互動,加入有目的的反馈,然後在 Matrix 中檢查和優化正在執行的應用程式。避免使用一般性的歡迎主視覺、裝飾性的統計卡片、重複的 glass 容器以及自動的錯開入場動畫。記錄您實際檢查過的技能和表面。

標準結構

~/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 圖片和完整的擁有者相對路徑顯示已儲存的圖表或螢幕截圖,例如 ![AI adoption chart](~/apps/ai-adoption/chart-light.png)。Electron Desktop 可以顯示這些圖片並在檔案預覽中開啟;不要告訴使用者圖片只能出現在代理的終端機中。對其他已儲存的檔案使用 Markdown 連結。靜態 HTML 預覽會在不含腳本的情況下被沙盒化;連結已安裝的應用程式以獲得互動式圖表,而不是承諾在對話中執行 HTML。如實報告遺失的檔案或預覽失敗。

命名

  • name 是顯示在啟動器、Dock 和標題列中的人類可讀、Title-Case 標籤——例如 "Calorie Tracker"、"Habit Garden"。讓它簡短且真實;永遠不要向使用者顯示 slug。
  • slug 是在路徑/URL 中使用的小寫、連字符 id(^[a-z0-9][a-z0-9-]{0,63}$)。從名稱衍生(calorie-tracker)。它是內部使用的——在任何地方都不要將其用作顯示字串。

圖示(必填——否則應用程式會顯示破損的圖塊)

啟動器會從 ~/system/icons/<icon>.svg(或 .png)載入每個應用程式的圖示,並比對清單中的 icon 欄位。如果您沒有提供該檔案,/icons/<icon> 會回傳 404,應用程式會得到一個破損/佔位圖示。 因此請務必:

  1. 在 matrix.json 中設定 "icon": "<slug>"(除非有更好的概念名稱,否則使用應用程式 slug)。
  2. 使用 Matrix OS 已出貨的圖示風格建立 ~/system/icons/<slug>.png: 光面高級 iOS/macOS 擬物化應用程式圖示藝術品、精緻的 Apple 風格產品渲染、明亮的暖色米白或柔和粉彩背景、微妙的陶瓷/玻璃深度、柔和的斜面、光澤高光、逼真的工作室陰影,以及一個清晰代表應用程式的單一大型觸覺 3D 物體或符號。保持圖示系列與 Matrix OS 的森林、奶油、餘燼和深色強調色一致。不要包含文字、標誌、浮水印、透明背景、黑色/深色 Dock 背景、空的內邊距或單獨的可見圖示框架;Matrix Shell 擁有最終的圓角半徑。保持光影和材質處理與 ~/system/icons/ 中已出貨的預設應用程式 PNG 一致。

對於第一方/預設應用程式,優先使用來自 home/system/icons/ 的已提交 PNG 圖示。SVG 僅適用於系統 chrome 或簡單的相容性備援,不適用於新產生的應用程式標誌。

資料(透過 MatrixOS 橋接的 Postgres)

應用程式在沙盒化、空來源的 iframe 中執行(CSP connect-src 'self'),因此對 /api/bridge/* 的直接 fetch() 呼叫會被阻擋,而 localStorage 會拋出 SecurityError。僅透過注入的橋接進行持久化:

  • 在 matrix.json 的 storage.tables 中宣告您的資料表(如上所述)。閘道會自動配置 Postgres schema——對已出貨的應用程式在啟動時進行,對您現在建立的應用程式則在首次查詢時懶加載,因此新建立的應用程式的 db 呼叫無需重新啟動即可運作。
  • 在程式碼中使用 window.MatrixOS.db(find/findOne/insert/update/delete/count/onChange)。對 undefined 進行防護(單元測試中不存在),將每個呼叫包裝在 try/catch 中(記錄日誌 + 使用者可見的錯誤;永遠不要使用空的 catch),樂觀地更新本地狀態,並在 onChange 時進行協調。
  • 對於外部/第三方 API,請使用 window.MatrixOS.proxyFetch(url)(已加入白名單)——永遠不要使用原始 fetch。
  • 不要在 Shell 中加入會執行的 localStorage 回退;它在沙盒中會拋出錯誤。僅在單元測試環境中,一個有防護的 try/catch localStorage 路徑可以作為無操作的方式被接受。

主題繼承

Shell 會將 --matrix-* 標記注入每個橋接的應用程式 iframe,並在主題變更時更新它們。首先在這些標記上建立應用程式 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);
}

使用繼承的 Shell 字型(var(--matrix-font-sans)、var(--matrix-font-mono)),而不要載入遠端字型樣式表。不要對預設 UI 使用應用程式的本地藍色、綠色或紫色調色盤。如果需要明確的應用程式品牌,請將其限定在命名的品牌標記中,並讓系統控制項、焦點狀態、狀態顏色和面板保持使用 Matrix 標記。

持久化規則

  • 在 matrix.json 的 storage.tables 中宣告每個持久化欄位,包括稽核欄位,例如 created_at、最佳分數/最佳時間欄位和 JSONB 狀態有效載荷。
  • 在啟動時從橋接儲存載入;不要在有真實資料列載入後再植入重複的回退資料列。
  • 在失敗的建立、更新、刪除和重新排序操作上回滾樂觀的 UI 變更。將待刪除的項目從可見狀態中過濾掉,直到橋接確認或回滾。
  • 序列化那些會更新排序、最佳分數、統計計數器或歷史記錄列的相依寫入。避免兩個橋接寫入競速,導致彼此覆蓋衍生的狀態。
  • 將僅限瀏覽器的輔助工具保留為測試用。在生產環境的 Shell iframe 中,直接的 localStorage 存取和原始的橋接 fetch() 呼叫不是可靠的持久化方式。

第一方預設應用程式

在此儲存庫中編輯捆綁的預設應用程式時:

  • 將應用程式清單和 schema 保留在 home/apps/<slug>/matrix.json 中。
  • 重複使用共享的預設應用程式 Vite 建置路徑;除非應用程式確實需要,否則不要加入過時的各應用程式套件/執行環境欄位。
  • 當預設應用程式原始碼變更時,在進行主機捆綁工作之前執行 node scripts/build-default-apps.mjs home/apps。
  • 除非存在具體的已出貨圖示,否則對遊戲優先使用共享的 game-center 圖示。
  • 驗證應用程式圖示 slug 是否對應 home/system/icons/<slug>.svg 或 .png;永遠不要依賴執行階段的圖示產生。

Scaffold 指令

當存在 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 載入,直接的橋接擷取會被 Shell 的 CORS/CSP 邊界阻擋。

範例 CRUD:

const db = window.MatrixOS?.db;
if (!db) throw new Error("Matrix 資料橋接不可用");

const tasks = await db.find("tasks", { orderBy: { created_at: "desc" } });
const created = await db.insert("tasks", { title: "發佈" });
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 <已解析之 matrix-app-builder 技能目錄>/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 啟動器開啟應用程式。驗證應用程式資源、圖示、橋接操作、儲存/重新開啟的往返,以及 craft 參考文件的視覺/狀態檢查。如果無法使用瀏覽器存取,請如實報告啟動和視覺驗證為待定,而不是聲稱應用程式可運作。檢查瀏覽器控制台/網路:

  • needs_build
  • 應用程式 bundle 或圖示路徑的 404
  • 來自直接提供者呼叫的 CORS 錯誤
  • 未處理的 React 錯誤

相關技能