O que Matrix App Builder faz?
Quando Usar
Use esta skill quando o usuário pedir para construir, criar, corrigir, redesenhar ou publicar um aplicativo Matrix OS.
Inegociáveis
- Construa aplicativos voltados para o usuário em
~/apps/<slug>/. - Padrão: Vite, React 19, TypeScript e
runtime: "vite". - CRM, roadmap, dashboard, admin e aplicativos com muitos dados ainda são SPAs Vite React por padrão. Use APIs de ponte Matrix/Postgres para dados em vez de criar rotas de API Next.js.
- Não crie Next.js,
.next/, arquivos de rotaapp/,runtime: "node",serve.startounpm starta menos que o usuário solicite explicitamente um runtime de servidor ou Next.js. - Não crie aplicativos HTML simples a menos que o usuário peça explicitamente por um aplicativo HTML simples.
- Sempre crie ou atualize
matrix.json. Para aplicativos construídos para o proprietário, inclualistingTrust: "first_party"escope: "personal"; blocos de confiança ausentes impedem o lançamento mesmo se o build for bem-sucedido. Nunca renomeie aplicativos baixados/da comunidade para contornar a política. - Sempre execute
pnpm installquando as dependências mudarem epnpm buildantes de afirmar que o aplicativo funciona. - Verifique se
dist/index.htmlexiste. - Use variáveis de tema Matrix injetadas e dimensionamento seguro para iframe. Aplicativos personalizados devem herdar o tema do shell por padrão; adicione branding explícito do aplicativo apenas quando o usuário solicitar ou o aplicativo tiver um motivo claro de domínio.
- Para UI, leia
matrix-design-system,matrix-app-ui-patternse App craft. Descubra e leia os arquivos SKILL.md instalados deemil-design-engeapple-designantes de projetar; useanimatepara trabalhos de movimento específicos. Preserve as regras de tema/runtime do Matrix e escolha layout, materiais e movimento para o propósito real do aplicativo. - Armazene dados estruturados do aplicativo através de APIs de ponte Matrix/Postgres, não bancos de dados locais ad hoc.
- Nunca coloque segredos de provedores, chaves de API ou tokens OAuth dentro do diretório do aplicativo.
- Não use
localStoragedo navegador como persistência de aplicativo no shell Matrix. Iframes com sandbox podem lançarSecurityError; usewindow.MatrixOS.dbe mantenha caminhos de fallback locais apenas para teste/sem operação. - Para aplicativos padrão ou de primeira parte em
home/apps/**, mantenha manifestos determinísticos:runtime: "vite",build.output: "dist", colunas de esquema declaradas emstorage.tableseiconapontando para um asset commitado emhome/system/icons/.
Fluxo de Trabalho de Design
Antes de criar a estrutura, leia a referência de craft e as skills de design instaladas. Escolha uma direção de design concisa e o fluxo de usuário principal. Construa a interação central primeiro, adicione feedback proposital, depois inspecione e refine o aplicativo em execução no Matrix. Evite um banner de boas-vindas genérico, cartões de estatística decorativos, containers de vidro repetidos e entradas escalonadas automáticas. Registre quais skills e superfícies você realmente verificou.
Estrutura Padrão
~/apps/<slug>/
matrix.json
package.json
vite.config.ts
tsconfig.json
index.html
src/
main.tsx
App.tsx
App.css
dist/
index.html
Manifesto
Use esta base e ajuste o nome do aplicativo, descrição, categoria, ícone e tabelas de armazenamento:
{
"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": {}
}
}
Tipos de coluna de armazenamento válidos incluem text, boolean, integer, float, timestamptz, jsonb e uuid.
Apresentação de aplicativos e gráficos no Chat
Após verificar o aplicativo, vincule seu diretório relativo ao proprietário, por exemplo
[AI Adoption](~/apps/ai-adoption). O Electron Desktop resolve diretórios de aplicativos instalados
em relação ao catálogo de aplicativos e os abre através do comportamento normal do launcher.
Não afirme que uma pasta arbitrária é um aplicativo instalado.
Exiba gráficos ou capturas de tela salvos com imagens Markdown e caminhos completos relativos ao proprietário,
por exemplo .
O Electron Desktop pode exibir essas imagens e abri-las na Visualização de Arquivos; não diga ao
usuário que as imagens só podem aparecer no terminal do agente. Use links Markdown para
outros arquivos salvos. Pré-visualizações HTML estáticas são isoladas sem scripts; vincule
o aplicativo instalado para um gráfico interativo em vez de prometer execução HTML ativa
dentro do Chat. Relate arquivos ausentes ou falhas de pré-visualização com veracidade.
Nomenclatura
nameé o rótulo legível por humanos, em Title Case, mostrado no launcher, dock e barra de título — ex."Calorie Tracker","Habit Garden". Torne-o curto e real; nunca mostre o slug para os usuários.slugé o identificador em letras minúsculas, hifenizado, usado em caminhos/URLs (^[a-z0-9][a-z0-9-]{0,63}$). Derive-o do nome (calorie-tracker). É interno — não o use como string de exibição em lugar nenhum.
Ícone (obrigatório — ou o aplicativo mostra um tile quebrado)
O launcher carrega o ícone de cada aplicativo de ~/system/icons/<icon>.svg (ou .png) correspondente ao campo icon do manifesto.
Se você não enviar esse arquivo, /icons/<icon> retorna 404 e o aplicativo fica com um ícone quebrado/substituto.
Portanto, sempre:
- Defina
"icon": "<slug>"emmatrix.json(use o slug do aplicativo a menos que tenha um nome de conceito melhor). - Crie
~/system/icons/<slug>.pngusando o estilo de ícone enviado do Matrix OS: arte de ícone de aplicativo skeuomórfico premium iOS/macOS claro, renderização de produto refinada ao estilo Apple, fundo off-white claro ou pastel pálido, profundidade sutil de cerâmica/vidro, chanfros suaves, realces brilhantes, sombras de estúdio realistas e um único objeto ou símbolo 3D tátil grande que represente claramente o aplicativo. Mantenha a família de ícones alinhada com os acentos floresta, creme, brasa e profundos do Matrix OS. Não inclua texto, logotipos, marcas d'água, fundos transparentes, fundos de dock pretos/escuros, preenchimento vazio ou uma moldura de ícone visível separada; o shell Matrix é dono do raio de canto final. Mantenha a iluminação e o tratamento de material consistentes com os PNGs de aplicativo padrão enviados em~/system/icons/.
Para aplicativos de primeira parte/padrão, prefira ícones PNG commitados de home/system/icons/. SVGs são aceitáveis
apenas para chrome do sistema ou fallbacks de compatibilidade simples, não para logotipos de aplicativo recém-gerados.
Dados (Postgres via ponte MatrixOS)
Os aplicativos são executados em um iframe com sandbox e origem nula (CSP connect-src 'self'), portanto um fetch() direto para
/api/bridge/* é bloqueado e localStorage lança SecurityError. Persista SOMENTE através da
ponte injetada:
- Declare suas tabelas em
storage.tablesdomatrix.json(acima). O gateway provisiona o esquema Postgres automaticamente — na inicialização para aplicativos enviados, e lazy na primeira consulta para aplicativos que você construir agora, portanto, chamadasdbde um aplicativo recém-construído funcionam sem qualquer reinicialização. - No código, use
window.MatrixOS.db(find/findOne/insert/update/delete/count/onChange). Proteja contraundefined(está ausente em testes de unidade), envolva cada chamada emtry/catch(log + erro visível ao usuário; nunca um catch vazio), atualize o estado local de forma otimista e reconcilie emonChange. - Para APIs externas/de terceiros, use
window.MatrixOS.proxyFetch(url)(na lista de permissões) — nunca um fetch bruto. - NÃO adicione um fallback de
localStorageque execute no shell; ele lança no sandbox. Um caminhotry/catchprotegido para localStorage é aceitável apenas como uma operação nula para o ambiente de teste de unidade.
Herança de Tema
O shell injeta tokens --matrix-* em cada iframe de aplicativo com ponte e os atualiza em alterações de tema. Construa o CSS do aplicativo nesses tokens primeiro, com cores literais apenas como 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);
}
Use as fontes do shell herdadas (var(--matrix-font-sans), var(--matrix-font-mono)) em vez de carregar folhas de estilo de fonte remotas. Não use paletas azul, verde ou roxo locais do aplicativo para UI padrão. Se for necessário branding explícito do aplicativo, escope-o a tokens de marca nomeados e mantenha controles do sistema, estados de foco, cores de status e painéis nos tokens Matrix.
Regras de Persistência
- Declare cada campo persistido em
storage.tablesdomatrix.json, incluindo campos de auditoria comocreated_at, colunas de melhor pontuação/melhor tempo e payloads de estado JSONB. - Carregue do armazenamento da ponte na inicialização; não propague linhas de fallback duplicadas após o carregamento de linhas reais.
- Reverta alterações otimistas de UI em criações, atualizações, exclusões e reordenações com falha. Mantenha exclusões pendentes filtradas do estado visível até que a ponte confirme ou reverta.
- Serialize gravações dependentes que atualizam ordenação, melhores pontuações, contadores de estatísticas ou linhas de histórico. Evite que duas gravações da ponte corram e possam sobrescrever o estado derivado uma da outra.
- Mantenha ajudantes apenas do navegador protegidos para testes. Em iframes de shell de produção, o acesso direto a
localStoragee chamadasfetch()brutas da ponte não são persistência confiável.
Aplicativos Padrão de Primeira Parte
Ao editar aplicativos padrão agrupados neste repositório:
- Mantenha manifestos e esquemas de aplicativos em
home/apps/<slug>/matrix.json. - Reutilize o caminho de build Vite do aplicativo padrão compartilhado; não adicione campos de pacote/runtime desatualizados por aplicativo a menos que o aplicativo realmente precise deles.
- Execute
node scripts/build-default-apps.mjs home/appsantes do trabalho de pacote do host quando o código-fonte do aplicativo padrão mudar. - Prefira o ícone compartilhado
game-centerpara jogos, a menos que exista um ícone concreto enviado. - Verifique slugs de ícones de aplicativos em relação a
home/system/icons/<slug>.svgou.png; nunca confie na geração de ícones em tempo de execução.
Comandos de Scaffold
Prefira copiar o template Vite agrupado do Matrix quando ele existir:
cp -a ~/apps/_template-vite ~/apps/<slug>
cd ~/apps/<slug>
pnpm install --prefer-offline
pnpm build
test -f dist/index.html
Se o template não estiver presente, crie os arquivos Vite padrão diretamente com react, react-dom, @vitejs/plugin-react, typescript e vite.
Acesso a Dados
Use a ponte window.MatrixOS.db injetada para dados estruturados. Não chame /api/bridge/query
diretamente do código do aplicativo; aplicativos em tempo de execução carregam como iframes srcdoc com sandbox, e fetches diretos da ponte
são bloqueados pelo limite CORS/CSP do shell.
Exemplo CRUD:
const db = window.MatrixOS?.db;
if (!db) throw new Error("Ponte de dados Matrix indisponível");
const tasks = await db.find("tasks", { orderBy: { created_at: "desc" } });
const created = await db.insert("tasks", { title: "Enviar" });
await db.update("tasks", created.id, { done: true });
await db.delete("tasks", created.id);
Integrações
Se o aplicativo precisar de Gmail, Agenda, GitHub, Slack, Drive ou outro provedor, use APIs de integração Matrix ou a skill matrix-integrations. A plataforma gerencia as credenciais do provedor. O aplicativo nunca armazena segredos de provedores.
Verificação
Antes de relatar como concluído:
cd ~/apps/<slug>
pnpm build
test -f dist/index.html
node <caminho-resolvido-do-diretório-da-skill-matrix-app-builder>/scripts/verify-app.mjs "$PWD"
Resolva o diretório da skill a partir do SKILL.md que você carregou; o script é enviado junto a ele e não precisa de dependências. Execute-o no diretório real do aplicativo, não no template. Ele verifica o manifesto Vite construído pelo proprietário e a entrada de produção; nunca altera a confiança ou prova um login ativo.
Lançamento e autenticação
O Matrix fornece autenticação do proprietário. Não construa uma página de login separada nem leia/copie credenciais de gateway para o aplicativo. O launcher nativo obtém um token de curta duração através de POST /api/apps/<slug>/session-token; o lançamento é /apps/<slug>/. listingTrust ausente ou desconhecido resulta em 403 install_blocked_by_policy, não em um login expirado. Um aplicativo existente que você acabou de construir para o proprietário pode ter seus metadados ausentes corrigidos após verificar sua origem; nunca promova silenciosamente um aplicativo importado. 401 significa autenticação, 403 política, 409 escopo/reconhecimento, 404 descoberta e 5xx uma falha de servidor. Relate falhas com precisão em vez de recomendar login para todas elas. Não desabilite a autenticação, enfraqueça a política, reinicie o VPS ou adicione um servidor para contornar uma falha de lançamento.
Em seguida, abra o aplicativo a partir do launcher Matrix usando a sessão autenticada existente. Verifique ativos do aplicativo, ícone, operações da ponte, um ciclo de ida e volta salvar/reabrir e as verificações visuais/de estado da referência de craft. Se o acesso ao navegador não estiver disponível, relate a verificação de lançamento e visual como pendente em vez de afirmar que o aplicativo funciona. Verifique o console/rede do navegador para:
needs_build- 404s para pacotes de aplicativos ou caminhos de ícone
- erros CORS de chamadas diretas de provedores
- erros React não tratados
