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-designSKILL.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 圖片和完整的擁有者相對路徑顯示已儲存的圖表或螢幕截圖,例如 。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,應用程式會得到一個破損/佔位圖示。 因此請務必:
- 在
matrix.json中設定"icon": "<slug>"(除非有更好的概念名稱,否則使用應用程式 slug)。 - 使用 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/catchlocalStorage 路徑可以作為無操作的方式被接受。
主題繼承
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 錯誤
