Installation de bureau

Ce guide couvre l’installation et l’utilisation de Hagicode Desktop. Il s’agit du client de bureau officiel et conserve le chemin de configuration local par défaut ainsi que les contrôles quotidiens en un seul endroit.

Méthode recommandée

Pour un usage personnel en local sous macOS, Linux, ou sous Windows sans passer par le Store, Desktop est recommandé :

• le guide de premier lancement enchaîne le téléchargement et le démarrage
• le démarrage, l’arrêt et les versions de Hagicode Server sont gérés par l’application
• l’interface graphique facilite le suivi de l’état et des opérations
• la gestion des versions intégrée facilite le passage d’une version à l’autre
• les données restent locales par défaut, pour que vous en gardiez le contrôle

Sous Windows, envisagez d’abord l’Installation via Microsoft Store ; pour un déploiement serveur ou en équipe, utilisez Docker Compose.

Qu’est-ce que Hagicode Desktop ?

Hagicode Desktop est l’application de bureau officielle de HagiCode, disponible sous Windows, macOS et Linux. Elle télécharge, démarre et gère le Hagicode Server local, et fournit la gestion des versions ainsi que les points d’entrée des opérations quotidiennes.

Principaux avantages

• Runtime .NET intégré : le .NET nécessaire à l’exécution de Hagicode Server est fourni avec Desktop, sans installation séparée
• Gestion des services : gestion intégrée de Hagicode Server, démarrage et arrêt faciles du service
• Changement de version : prise en charge de la gestion multi-versions, basculez librement entre les différentes versions
• Fonctionnement local : toutes les données sont stockées localement, protégeant ainsi votre vie privée
• Détection des versions : détecte automatiquement les nouvelles versions disponibles

Scénarios applicables

Privilégiez Desktop dans les cas suivants :

• développeurs individuels souhaitant utiliser HagiCode localement
• utilisateurs qui veulent garder leurs données et leurs projets sur leur propre machine
• utilisateurs qui préfèrent une interface graphique et ne veulent pas écrire de configuration de déploiement à la main
• développeurs qui doivent fréquemment basculer entre différentes versions

Préparation avant l’installation

Desktop n’embarque pas Node.js et ne fournit plus d’environnement Node interne. Il utilise les commandes node et npm présentes dans le PATH du système, et installe les paquets gérés, tels que les Agent CLI, dans le répertoire global de votre npm local. Avant de commencer, préparez les éléments suivants :

Dépendance	Exigence	Remarques
Node.js	Version 24 ou supérieure	Fournit aussi npm, voir Installer Node.js
Git	N’importe quelle version stable actuelle	Détecté au démarrage ; le « Projet de démonstration » de la boîte de dialogue « Nouveau projet » en a besoin pour cloner le dépôt d’exemple, voir Installer Git
Agent CLI	Au moins un, déjà connecté	L’assistant ne liste que les CLI détectés sur la machine, voir Installation de la CLI de l’agent IA

Vérifiez d’abord les versions dans un terminal :

node --version   # v24.0.0 ou supérieure requise
npm --version
git --version

Installez d’abord, puis lancez ou relancez Desktop

Desktop lit le PATH du système au démarrage. Si vous installez Node.js ou Git alors que Desktop est déjà ouvert, quittez complètement Desktop puis relancez-le, et actualisez ensuite la page des dépendances.

Télécharger Desktop

Téléchargement rapide

Sous Windows, privilégiez l’installation via Microsoft Store ; n’utilisez l’entrée de téléchargement manuel ci-dessous que si vous avez besoin d’un fichier d’installation, d’un fichier de version précise, ou si le Store est indisponible.

Sélectionnez la version adaptée à votre système d’exploitation et téléchargez directement le programme d’installation :

GitHubChina

Si la liste de téléchargement ne se charge pas

Si la liste des paquets d’installation de Desktop ne peut pas être chargée pour le moment, le point d’entrée n’affiche pas de lien de téléchargement invalide et vous redirige vers la page officielle de l’historique des versions : index.hagicode.com/desktop/history. Vous pouvez y choisir une version et télécharger le paquet d’installation ; vous pouvez aussi utiliser directement GitHub Releases ci-dessous.

Autres méthodes de téléchargement

Vous pouvez également obtenir le programme d’installation de Hagicode Desktop à partir des canaux suivants :

1. Recommandé par défaut sous Windows : consultez l’Installation via Microsoft Store pour passer par le canal de distribution officiel du Store
2. Page de publication officielle : consultez les publications GitHub de HagiCode pour télécharger un paquet d’installation manuel
3. Site officiel : visitez le site web HagiCode pour obtenir des liens de téléchargement et des instructions d’installation

Choisir la bonne version

Sélectionnez le programme d’installation correspondant à votre système d’exploitation :

• Windows : privilégiez Microsoft Store ; si vous avez besoin d’un fichier d’installation manuel, téléchargez le programme d’installation .exe ou le paquet .msix
• macOS : téléchargez le programme d’installation .dmg
• Linux : téléchargez le paquet d’installation .AppImage ou .tar.gz

Configuration système requise

• Windows : Windows 10 ou version supérieure (64 bits)
• macOS : macOS 10.15 ou version ultérieure
• Linux : distributions Linux grand public (Ubuntu 20.04+, Fedora 33+, etc.)

Dépendances à préparer vous-même

Desktop embarque le runtime .NET nécessaire à l’exécution de Hagicode Server et effectue l’initialisation par défaut selon le chemin SQLite local actuellement pris en charge ; vous n’avez donc pas à installer .NET séparément. En revanche, Node.js 24+ et Git sont à installer par vos soins, voir Préparation avant l’installation ci-dessus.

Notes d’installation et de lancement

Avis du Gatekeeper macOS

Si vous avez déjà installé l’application dans le chemin par défaut /Applications/Hagicode.app mais que macOS affiche « l’application est endommagée », « ne peut pas être ouverte » ou un avertissement Gatekeeper similaire au premier lancement, la cause habituelle est l’attribut de quarantaine com.apple.quarantine que macOS ajoute aux applications téléchargées sur Internet, et non une défaillance de l’assistant d’installation de Hagicode Desktop lui-même.

Exécutez la commande suivante dans le Terminal. Elle nécessite des privilèges d’administrateur et supprime de manière récursive l’attribut de quarantaine de l’application dans le chemin d’installation par défaut :

sudo xattr -dr com.apple.quarantine /Applications/Hagicode.app

Une fois la commande terminée, relancez Hagicode Desktop.

Lancer Desktop

Une fois le téléchargement terminé, ouvrez le programme d’installation ou le paquet de l’application pour terminer l’installation, puis lancez Hagicode Desktop.

Configuration réseau requise

Assurez-vous que votre connexion réseau fonctionne. Desktop doit récupérer sur Internet les informations de version et le paquet d’installation de Hagicode Server ; si un téléchargement échoue, vérifiez votre réseau, votre proxy ou votre pare-feu, puis réessayez.

Guide du premier lancement

À la première ouverture de Desktop, vous accédez d’abord au guide « Configuration initiale » propre à Desktop. Il se limite à installer et démarrer Hagicode Server, et comprend dans l’ordre :

1. Choisir la langue : choisissez la langue utilisée par Desktop. Le premier démarrage du backend embarqué adopte aussi la langue par défaut correspondante.
2. Bienvenue : découvrez les préparatifs que ce guide va effectuer.
3. Confirmer les documents juridiques : confirmez la version actuelle du CLUF et de la politique de confidentialité ; les documents officiels s’ouvrent dans le navigateur pour lecture.
4. Télécharger Hagicode Server : téléchargez le dernier paquet du Server et vérifiez son empreinte.

Une fois le téléchargement terminé, revenez à la page d’accueil de Desktop et cliquez sur « Démarrer le service » pour démarrer Hagicode Server, puis ouvrez l’interface Web en suivant les indications de la page d’accueil.

Les étapes peuvent être incomplètes

Selon le canal de distribution (par exemple une version dont le paquet d’installation inclut déjà le Server), ou lorsqu’il suffit de reconfirmer les documents juridiques après une mise à jour, le guide n’affiche qu’une partie de ces étapes.

Première utilisation de l’interface Web

À votre première entrée dans l’interface Web, l’assistant d’initialisation apparaît (c’est une étape distincte du guide de premier lancement de Desktop décrit ci-dessus). Il vous accompagne pour choisir la langue et le thème de l’interface, configurer le Hagicoder par défaut et créer votre premier projet. Pour le détail des étapes, lisez :

Assistant de configurationTerminez la configuration de la langue, du thème, du Hagicoder par défaut et du premier projet.

Gestion des versions

Hagicode Desktop prend en charge la gestion multi-versions, vous permettant de basculer librement entre différentes versions.

Changer de version

1. Ouvrez Hagicode Desktop
2. Allez sur la page « Gestion des versions »
3. Sélectionnez la version vers laquelle basculer
4. Cliquez sur le bouton « Changer de version »
5. Attendez que le changement soit terminé

Notes sur le changement de version

• Changer de version redémarre automatiquement Hagicode Server
• Assurez-vous de sauvegarder tout votre travail avant de changer
• Les configurations du projet peuvent différer selon les versions

Démarrer et arrêter le service

Hagicode Desktop fournit un moyen simple de gérer le service Hagicode Server.

Démarrer le service

Sur la page d’accueil de l’application Desktop, cliquez sur le bouton « Démarrer le service » pour démarrer Hagicode Server.

Arrêter le service

Pour arrêter Hagicode Server, cliquez sur le bouton « Arrêter le service » sur la page d’accueil.

État du service

L’application Desktop affiche en temps réel l’état d’exécution de Hagicode Server, notamment :

• l’état du service (en cours d’exécution / arrêté)
• le numéro de port du service
• les informations sur la version actuelle

Étapes suivantes

Une fois l’installation terminée, vous pouvez continuer avec les étapes suivantes :

Assistant de configurationAprès le premier lancement, créez votre projet ici et poursuivez dans le parcours de démarrage rapide de référence.

Créer une session de conversationComprenez le projet en mode lecture seule par défaut, puis passez en mode édition uniquement si nécessaire.

Créer une session de propositionDécouvrez le flux de développement piloté par les propositions, qui transforme des idées abstraites en plans d'implémentation structurés.

Dépannage

Échec de l’installation

Si vous rencontrez des problèmes lors de l’installation :

1. Vérifiez la connexion réseau : assurez-vous que vous pouvez accéder à Internet
2. Vérifiez l’espace disque : assurez-vous de disposer de suffisamment d’espace disque
3. Exécutez en tant qu’administrateur : sous Windows, faites un clic droit sur le programme d’installation et choisissez « Exécuter en tant qu’administrateur »
4. Lisez les messages du programme d’installation : notez le message d’erreur affiché par le programme d’installation et joignez-le lorsque vous signalez un problème

Node.js, npm ou Git introuvable

Si Desktop signale l’absence de node, npm ou git, ou indique que la version de Node.js est trop ancienne :

1. Vérifiez l’installation : exécutez node --version, npm --version et git --version dans un terminal. Node.js doit être en version 24 ou supérieure ; pour l’installation, voir Installer Node.js et Installer Git.
2. Redémarrez Desktop : Desktop lit le PATH du système au démarrage. Après l’installation, quittez complètement Desktop puis relancez-le, et actualisez ensuite la page des dépendances.
3. Vérifiez le PATH : si la commande fonctionne dans un terminal mais que Desktop ne la trouve pas, c’est généralement que le PATH n’est défini que dans la configuration d’un shell donné (par exemple via nvm ou fnm dans .bashrc / .zshrc). Utilisez plutôt une installation au niveau du système, ou lancez Desktop depuis un environnement qui lit ce PATH.
4. Installez manuellement le paquet CLI : lorsque Desktop indique qu’un paquet CLI doit être installé manuellement, exécutez la commande fournie dans un terminal en dehors de Desktop, puis revenez dans Desktop et actualisez. Pour le comportement de l’environnement Node / npm externe et du PATH, voir Comment Desktop utilise votre environnement Node.

Échec du démarrage du service

Si Hagicode Server ne démarre pas :

1. Vérifiez l’occupation du port : Desktop utilise par défaut le port 36556 (la page d’accueil affiche le port réellement utilisé) ; assurez-vous qu’il n’est pas occupé par un autre programme
2. Vérifiez les paramètres du pare-feu : assurez-vous que le pare-feu autorise l’accès réseau de Hagicode Server
3. Redémarrez l’application : essayez de redémarrer Hagicode Desktop
4. Consultez les journaux : consultez les journaux d’erreurs détaillés dans l’application Desktop

Besoin de plus d’aide ?

Si vous rencontrez des problèmes non abordés ici :

1. Consultez les GitHub Issues de Desktop pour trouver des problèmes similaires
2. Visitez notre forum de la communauté pour obtenir de l’aide
3. Ouvrez une nouvelle Issue en décrivant précisément votre problème et en joignant la version de votre système, le résultat de node --version et les journaux de Desktop