Skip to content

QUICKSTART.fr.md

Latest commit

 

History

History
342 lines (246 loc) · 17 KB

QUICKSTART.fr.md

File metadata and controls

342 lines (246 loc) · 17 KB
Raw

Quickstart

English · Português (Brasil) · Deutsch · Français · 日本語 · 한국어 · 简体中文 · 繁體中文 · ภาษาไทย

Exécutez le produit complet localement.

Prérequis

  • Node.js : ~24 (Node 24.x). Le repo l’impose via package.json#engines.
  • pnpm : 10.33.x. Le repo fixe pnpm@10.33.2 via packageManager ; utilisez Corepack pour que la bonne version soit sélectionnée automatiquement.
  • OS : macOS, Linux et WSL2 sont les environnements principaux pris en charge. Windows natif devrait fonctionner pour la plupart des workflows, mais WSL2 reste l’option la plus fiable.
  • CLI d’agent locale optionnelle : Open Design prend en charge un registre de runtimes locaux, dont Claude Code, Codex, Devin for Terminal, OpenCode, Cursor Agent, Qwen, Qoder CLI, GitHub Copilot CLI et d’autres. La liste actuelle se trouve dans apps/daemon/src/runtimes/registry.ts. Si aucun n’est installé, utilisez un runtime BYOK configuré dans Settings.

nvm / fnm sont des outils de confort optionnels, pas une étape obligatoire de la configuration du projet. Si vous en utilisez un, installez/sélectionnez Node 24 avant de lancer pnpm :

# nvm
nvm install 24
nvm use 24

# fnm
fnm install 24
fnm use 24

Activez ensuite Corepack et laissez le repo sélectionner pnpm :

corepack enable
corepack pnpm --version   # doit afficher 10.33.2

Démarrage rapide (mode dev)

corepack enable
pnpm install
pnpm tools-dev run web # démarre daemon + web au premier plan
# ouvrez l’URL web affichée par tools-dev

Pour le shell desktop et tous les sidecars gérés en arrière-plan :

pnpm tools-dev # démarre daemon + web + desktop en arrière-plan

Au premier chargement, l’app détecte les runtimes locaux disponibles et propose aussi les runtimes BYOK configurés dans Settings. Choisissez un runtime, une design template et un Design System, puis tapez un prompt et cliquez sur Send. Les runtimes locaux structurés écrivent les fichiers canoniques du projet et diffusent les événements de fichiers/outils ; l’espace de fichiers et la preview se mettent à jour depuis ces écritures. Les exécutions texte uniquement et BYOK renvoient à la place un bloc <artifact> complet que l’hôte parse. Avant de documenter ou de modifier un chemin de stockage d’artifact, vous DEVEZ lire AGENTS.md à la racine, section Daemon data directory contract.

Le catalogue Design Systems est chargé directement depuis les paquets DESIGN.md de design-systems/. Choisissez-en un pour appliquer le langage visuel de la marque à l’artifact.

Le catalogue Templates vient de design-templates/ et regroupe les formats d’artifact pour prototypes, decks, documents, images, vidéo et audio. skills/ reste réservé aux capacités fonctionnelles que l’agent invoque pendant son travail. Associez une template à un Design System pour produire un artifact dans le langage visuel choisi.

Autres scripts

pnpm tools-dev                 # daemon + web + desktop en arrière-plan
pnpm tools-dev start web       # daemon + web en arrière-plan
pnpm tools-dev run web         # daemon + web au premier plan (e2e/dev server)
pnpm tools-dev restart         # redémarre daemon + web + desktop
pnpm tools-dev restart --daemon-port 7457 --web-port 5175
pnpm tools-dev status          # inspecte les runtimes gérés
pnpm tools-dev logs            # affiche les logs daemon/web/desktop
pnpm tools-dev check           # statut + logs récents + diagnostics courants
pnpm tools-dev stop            # arrête les runtimes gérés
pnpm --filter @open-design/daemon build  # build apps/daemon/dist/cli.js pour `od`
pnpm --filter @open-design/web build     # build du paquet web si nécessaire
pnpm typecheck                 # typecheck du workspace

pnpm tools-dev est le seul point d’entrée du lifecycle local. N’utilisez pas les anciens alias root supprimés (pnpm dev, pnpm dev:all, pnpm daemon, pnpm preview, pnpm start).

Pendant le développement local, tools-dev démarre d’abord le daemon, transmet son port à apps/web, puis apps/web/next.config.ts réécrit /api/*, /artifacts/* et /frames/* vers ce port daemon. L’app App Router peut ainsi parler au processus Express voisin sans configuration CORS.

Configuration Docker

Exécutez Open Design dans un environnement entièrement conteneurisé sans installer Node.js ou pnpm localement.

Prérequis

  • Docker Desktop
  • Docker Compose v2

Vérifiez que Docker est installé correctement :

docker compose version

Démarrer Open Design

Depuis la racine du dépôt :

  1. Allez dans le répertoire deploy et copiez le modèle d'environnement :

    cd deploy
cp .env.example .env

  2. Générez un token sécurisé :

    openssl rand -hex 32

  3. Ouvrez .env dans votre éditeur, trouvez OD_API_TOKEN= et collez le token généré.

Lancez ensuite le service :

docker compose up -d

Ouvrez l'application dans votre navigateur :

http://localhost:7456

Le premier démarrage peut prendre quelques secondes pendant que Docker télécharge la dernière image.

Commandes Docker courantes

Voir les logs

docker compose logs -f

Redémarrer les conteneurs

docker compose restart

Arrêter les conteneurs

docker compose down

Télécharger la dernière image

docker compose pull
docker compose up -d

Supprimer toutes les données locales de l'application

docker compose down -v

Configuration de l'environnement

Créez un fichier deploy/.env pour remplacer la configuration par défaut. Commencez par l'exemple fourni :

cp deploy/.env.example deploy/.env

Modifiez deploy/.env pour définir votre propre token et ajuster les autres valeurs si nécessaire :

# Port exposé sur l'hôte
OPEN_DESIGN_PORT=7456

# Limite de mémoire du conteneur
OPEN_DESIGN_MEM_LIMIT=384m

# Origines CORS autorisées
OPEN_DESIGN_ALLOWED_ORIGINS=https://yourdomain.com

# Tag de l'image Docker
OPEN_DESIGN_IMAGE=ghcr.io/nexu-io/od:latest

# Token API requis pour la sécurité du daemon
# Générez-en un avec : openssl rand -hex 32
OD_API_TOKEN=

Stockage persistant

Avant de documenter, modifier ou choisir un chemin de stockage persistant du daemon, vous DEVEZ lire AGENTS.md à la racine, section Daemon data directory contract. Ce Quickstart NE DOIT PAS répéter ce contrat ni définir de chemins de stockage.

Remarques

  • Le mode Docker est idéal pour les contributeurs qui ne souhaitent pas d'installation locale de Node.js ou pnpm.
  • Le conteneur expose la build de production du daemon directement sur le port 7456.
  • Pour les workflows de développement et la configuration locale avancée, consultez le reste de ce guide de démarrage rapide.

Checks de génération média / agent dispatcher

Les Skills image, vidéo, audio et HyperFrames appellent la CLI locale od via des variables d’environnement injectées par le daemon lorsqu’il lance un agent :

  • OD_BIN — chemin absolu vers apps/daemon/dist/cli.js.
  • OD_DAEMON_URL — URL du daemon en cours d’exécution.
  • OD_PROJECT_ID — id du projet actif.
  • OD_PROJECT_DIR — dossier de fichiers du projet actif.

Si la génération média échoue avec OD_BIN: parameter not set, apps/daemon/dist/cli.js manquant, ou failed to reach daemon at http://127.0.0.1:0, rebuildez la CLI daemon et redémarrez le runtime géré :

pnpm --filter @open-design/daemon build
pnpm tools-dev restart --daemon-port 7457 --web-port 5175
ls -la apps/daemon/dist/cli.js
curl -s http://127.0.0.1:7457/api/health

Ouvrez ensuite de nouveau le projet depuis l’app Open Design au lieu de reprendre une ancienne session agent dans le terminal. Un agent lancé par le daemon devrait voir des valeurs comme :

echo "OD_BIN=$OD_BIN"
echo "OD_PROJECT_ID=$OD_PROJECT_ID"
echo "OD_PROJECT_DIR=$OD_PROJECT_DIR"
echo "OD_DAEMON_URL=$OD_DAEMON_URL"
ls -la "$OD_BIN"

OD_DAEMON_URL doit être un vrai port daemon comme http://127.0.0.1:7457, pas http://127.0.0.1:0. La valeur :0 est seulement une indication interne "choisir un port libre" au lancement et ne doit pas se retrouver dans les sessions agent.

En mode production daemon-only, le daemon sert lui-même l’export static Next.js à http://localhost:7456; aucun reverse proxy n’est impliqué.

Si vous placez nginx devant le daemon, gardez les routes SSE non bufferisées et non compressées. Un échec courant : la console navigateur affiche net::ERR_INCOMPLETE_CHUNKED_ENCODING 200 (OK) après 80-90 secondes, parce que gzip on dans nginx bufferise les réponses SSE chunked même quand le daemon envoie X-Accel-Buffering: no.

location /api/ {
    proxy_pass http://127.0.0.1:7456;

    proxy_buffering off;
    gzip off;

    proxy_read_timeout 86400s;
    proxy_send_timeout 86400s;
    proxy_http_version 1.1;
    proxy_set_header Connection "";

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Deux modes d’exécution

Mode Valeur du picker Flux d’une requête
Local CLI (par défaut quand le daemon détecte un agent) "Local CLI" Frontend → daemon /api/chat → spawn(<agent>, ...) → événements structurés outils/fichiers sur SSE → fichiers du projet → preview. Les CLI plain-stream utilisent le chemin text-artifact.
Mode API (fallback / aucune CLI) "Anthropic API" / "OpenAI API" / "Atlas Cloud" / "Azure OpenAI" / "Google Gemini" Frontend → daemon /api/proxy/{provider}/stream → SSE provider normalisé en delta/end/error → parser <artifact> → preview

Les deux modes aboutissent au même espace de fichiers et à la même preview sandboxée, mais leur contrat de remise diffère. Les runtimes avec système de fichiers écrivent les fichiers canoniques et ne doivent pas recopier leur source dans <artifact>. Les exécutions plain/texte uniquement et BYOK n’ont pas d’outils de fichiers : leur livrable canonique est le HTML complet dans <artifact>. Le profil d’exécution découle du transport du runtime.

Composition du prompt

À chaque envoi, l’app construit un system prompt à partir de trois couches et l’envoie au provider :

BASE_SYSTEM_PROMPT   (remise fichier ou <artifact> selon le profil d’exécution)
   + active design system body  (DESIGN.md — palette/type/layout)
   + active skill body          (SKILL.md — workflow and output rules)

Changez le Skill ou le Design System dans la barre supérieure : le prochain envoi utilise le nouveau stack. Les contenus sont mis en cache en mémoire par session, donc un choix ne coûte qu’un fetch daemon.

File map

open-design/
├── apps/
│   ├── daemon/                # Node/Express — spawn les agents locaux + sert les APIs
│   │   └── src/
│   │       ├── cli.ts             # entrée bin `od`
│   │       ├── server.ts          # /api/* + static serving
│   │       ├── agents.ts          # exports de compatibilité des modules runtime
│   │       ├── runtimes/
│   │       │   ├── registry.ts    # registre des runtimes pris en charge
│   │       │   └── defs/          # définitions de lancement et d’arguments par runtime
│   │       ├── skills.ts          # loader SKILL.md (frontmatter parser)
│   │       └── design-systems/    # loader DESIGN.md et services
│   │   ├── sidecar/           # wrapper sidecar daemon pour tools-dev
│   │   └── tests/             # tests du package daemon
│   ├── web/                   # Next.js 16 App Router + client React
│       ├── app/               # entrypoints App Router
│       ├── src/               # modules client/runtime React + TypeScript
│       │   ├── App.tsx        # orchestre mode / skill / DS pickers + send
│       │   ├── providers/     # transports daemon + BYOK API
│       │   ├── prompts/       # system, discovery, directions, deck framework
│       │   ├── artifacts/     # parsing text-artifact + manifests d’artifacts
│       │   ├── runtime/       # iframe srcdoc, markdown, helpers d’export
│       │   └── state/         # localStorage + état projet persisté par le daemon
│       ├── sidecar/           # wrapper sidecar web pour tools-dev
│       └── next.config.ts     # rewrites tools-dev + config export prod apps/web/out
│   └── desktop/               # runtime Electron, lancé/inspecté par tools-dev
├── packages/
│   ├── contracts/             # contrats app partagés web/daemon
│   ├── sidecar-proto/         # contrat du protocole sidecar Open Design
│   ├── sidecar/               # primitives runtime sidecar génériques
│   └── platform/              # primitives process/platform génériques
├── tools/dev/                 # lifecycle `pnpm tools-dev` et inspect CLI
├── e2e/                       # UI Playwright + harness intégration externe/Vitest
├── skills/                    # capacités fonctionnelles invoquées pendant le travail
├── design-templates/          # catalogue de rendu : prototypes, decks, docs et médias
├── design-systems/            # paquets de marque basés sur DESIGN.md
├── scripts/sync-design-systems.ts    # réimport depuis le tarball getdesign upstream
├── docs/                      # vision produit + spec
├── pnpm-workspace.yaml        # apps/* + packages/* + tools/* + e2e
└── package.json               # scripts qualité root + bin `od`

Dépannage

  • "no agents found on PATH" — installez l’un des runtimes locaux enregistrés dans apps/daemon/src/runtimes/registry.ts, vérifiez que son exécutable est visible par le daemon, puis utilisez Rescan dans Settings → Execution mode. Ou configurez un runtime BYOK dans Settings.
  • daemon 500 sur /api/chat — vérifiez la fin de stderr dans le terminal daemon ; la CLI a généralement rejeté ses args. Les CLIs n’acceptent pas toutes la même forme d’argv ; consultez la définition correspondante sous apps/daemon/src/runtimes/defs/ si vous devez l’ajuster.
  • la génération média dit que OD_BIN manque ou que l’URL daemon vaut :0 — exécutez les checks du dispatcher média ci-dessus. Ne reprenez pas l’ancienne session CLI ; rouvrez le projet depuis l’app Open Design pour que le daemon injecte des variables OD_* fraîches.
  • Codex charge trop de contexte plugin — démarrez Open Design avec OD_CODEX_DISABLE_PLUGINS=1 pnpm tools-dev pour que les processus Codex lancés par le daemon tournent avec --disable plugins.
  • l’artifact ne rend jamais — identifiez d’abord le profil de remise. Avec un runtime local doté d’un système de fichiers, vérifiez qu’un fichier de projet prévisualisable a été créé et que ses événements ont atteint le daemon ; sa source ne doit pas être dans <artifact>. Pour une exécution plain/texte uniquement ou BYOK, vérifiez la présence d’un unique bloc <artifact> complet, puis repérez dans les logs du daemon la première frontière en échec.

Retour à la vision

Ce Quickstart est la graine exécutable de la spec dans docs/. La spec décrit vers quoi le projet grandit (voir docs/roadmap.md). Points clés :

  • docs/architecture.md décrit le stack livré : Next.js 16 App Router devant, daemon local derrière, et rewrites apps/web/next.config.ts en dev pour que le navigateur parle toujours à la même surface /api.
  • docs/skills-protocol.md décrit le schéma od: complet. Le daemon lit les métadonnées runtime utiles depuis SKILL.md pour router les Skills, composer le prompt, afficher les exemples et configurer les surfaces web / image / vidéo / audio ; le protocole reste la référence pour les champs avancés.
  • docs/agent-adapters.md décrit le contrat d’adapter. Les paramètres de lancement, d’arguments, de modèles et de stream propres à chaque runtime se trouvent sous apps/daemon/src/runtimes/defs/, avec leur enregistrement dans apps/daemon/src/runtimes/registry.ts ; apps/daemon/src/agents.ts reste une surface d’export de compatibilité.
  • docs/modes.md distingue les six onglets New Project des sept modes normalisés du registre (prototype, deck, template, design-system, image, video, audio).