HamedMP/matrix-os

Matrix 앱 빌더

사용 시점

사용자가 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 및 앱 크래프트를 읽으십시오. 디자인하기 전에 설치된 emil-design-eng 및 apple-design SKILL.md 파일을 발견하고 읽으십시오. 특정 모션 작업에는 animate를 사용하십시오. Matrix 테마/런타임 규칙을 유지하고 앱의 실제 목적에 맞는 레이아웃, 재료 및 모션을 선택하십시오.
• 구조화된 앱 데이터는 임시 로컬 데이터베이스가 아닌 Matrix/Postgres 브리지 API를 통해 저장하십시오.
• 앱 디렉토리 내에 공급자 비밀, API 키 또는 OAuth 토큰을 절대 저장하지 마십시오.
• Matrix 셸에서 앱 지속성을 위해 브라우저 localStorage를 사용하지 마십시오. 샌드박스 처리된 iframe은 SecurityError를 발생시킬 수 있습니다. window.MatrixOS.db를 사용하고 로컬 폴백 경로는 테스트 전용/no-op으로 유지하십시오.
• home/apps/** 아래의 기본 또는 자사 앱의 경우 매니페스트를 결정론적으로 유지하십시오: runtime: "vite", build.output: "dist", storage.tables에 선언된 스키마 열, home/system/icons/의 커밋된 자산을 가리키는 icon.

디자인 워크플로우

스캐폴딩 전에 크래프트 참조와 설치된 디자인 스킬을 읽으십시오. 간결한 디자인 방향과 기본 사용자 흐름을 선택하십시오. 먼저 핵심 상호작용을 구축하고, 목적 있는 피드백을 추가한 다음, 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 이미지와 전체 소유자 기준 경로로 표시하십시오. 예: ![AI adoption chart](~/apps/ai-adoption/chart-light.png). Electron Desktop은 이러한 이미지를 표시하고 파일 미리보기에서 열 수 있습니다. 사용자에게 이미지가 에이전트 터미널에만 나타날 수 있다고 말하지 마십시오. 다른 저장된 파일에는 Markdown 링크를 사용하십시오. 정적 HTML 미리보기는 스크립트 없이 샌드박스 처리됩니다. 대화형 차트를 위해 설치된 앱을 링크하고 채팅 내에서 활성 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를 반환하고 앱이 깨진/플레이스홀더 아이콘을 얻게 됩니다. 따라서 항상:

1. matrix.json에서 "icon": "<slug>"를 설정하십시오 (더 나은 개념 이름이 없는 한 앱 슬러그 사용).
2. Matrix OS 제공 아이콘 스타일을 사용하여 ~/system/icons/<slug>.png를 생성하십시오: 고급스러운 iOS/macOS 스큐어모픽 앱 아이콘 아트워크, 정제된 Apple 같은 제품 렌더링, 밝은 따뜻한 오프화이트 또는 옅은 파스텔 배경, 미묘한 세라믹/유리 질감, 부드러운 베벨, 광택 하이라이트, 사실적인 스튜디오 그림자, 앱을 명확하게 나타내는 단일 크기의 촉각적 3D 개체 또는 기호. Matrix OS의 포레스트, 크림, 엠버, 딥 악센트 색상과 아이콘 패밀리를 정렬하십시오. 텍스트, 로고, 워터마크, 투명 배경, 검은색/어두운 독 배경, 빈 패딩 또는 별도의 보이는 아이콘 프레임을 포함하지 마십시오. Matrix 셸이 최종 코너 반경을 소유합니다. 조명 및 재료 처리는 ~/system/icons/의 제공된 기본 앱 PNG와 일관성을 유지하십시오.

자사/기본 앱의 경우 home/system/icons/의 커밋된 PNG 아이콘을 선호하십시오. SVG는 시스템 크롬 또는 간단한 호환성 폴백에만 허용되며, 새로 생성된 앱 로고에는 허용되지 않습니다.

데이터 (MatrixOS 브리지를 통한 Postgres)

앱은 샌드박스 처리된 null-origin 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로 감싸고 (로그 + 사용자에게 표시되는 오류, 절대 빈 catch 사용 금지), 낙관적으로 로컬 상태를 업데이트하고 onChange에서 조정하십시오.
• 외부/타사 API의 경우 window.MatrixOS.proxyFetch(url)를 사용하십시오 (허용 목록). 절대 원시 fetch를 사용하지 마십시오.
• 셸에서 실행되는 localStorage 폴백을 추가하지 마십시오. 샌드박스에서 예외가 발생합니다. 보호된 try/catch localStorage 경로는 단위 테스트 환경에서만 no-op으로 허용됩니다.

테마 상속

셸은 모든 브리지 앱 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 변경을 롤백하십시오. 브리지가 확인하거나 롤백할 때까지 보류 중인 삭제를 표시 상태에서 필터링하십시오.
• 순서 지정, 최고 점수, 통계 카운터 또는 기록 행을 업데이트하는 종속 쓰기를 직렬화하십시오. 서로의 파생 상태를 덮어쓸 수 있는 두 개의 브리지 쓰기가 경쟁하지 않도록 하십시오.
• 테스트를 위해 브라우저 전용 헬퍼를 보호하십시오. 프로덕션 셸 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 데이터 브리지를 사용할 수 없습니다");

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, 캘린더, 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 오류