Desktop-Installation

Auf dieser Seite erfahren Sie, wie Sie Hagicode Desktop installieren und verwenden. Es ist der offizielle Desktop-Client und bündelt den standardmäßigen lokalen Installationsablauf und die tägliche Verwaltung an einem Ort.

Empfohlene Methode

Für die persönliche lokale Nutzung unter macOS, Linux und unter Windows ohne Store wird Desktop empfohlen:

• Die Einrichtung beim ersten Start führt durch Download und Start
• Start, Stopp und Version von Hagicode Server werden zentral vom Programm verwaltet
• Die grafische Oberfläche erleichtert die Kontrolle von Status und Vorgängen
• Die integrierte Versionsverwaltung erleichtert den Wechsel zwischen Versionen
• Daten bleiben standardmäßig lokal, sodass Sie die Kontrolle behalten

Unter Windows sollten Sie zuerst die Microsoft Store-Installation in Betracht ziehen. Für Server- oder Team-Bereitstellungen verwenden Sie Docker Compose.

Was ist Hagicode Desktop?

Hagicode Desktop ist die offizielle Desktop-Anwendung von Hagicode und unterstützt Windows, macOS und Linux. Sie lädt Hagicode Server auf Ihrem Rechner herunter, startet und verwaltet ihn und bietet Versionsverwaltung sowie Zugänge für den täglichen Betrieb.

Hauptvorteile

• Integrierte .NET-Laufzeit: Die für den Betrieb von Hagicode Server benötigte .NET-Laufzeit wird mit Desktop ausgeliefert und muss nicht separat installiert werden
• Dienstverwaltung: Integrierte Verwaltung von Hagicode Server, Dienst einfach starten und stoppen
• Versionswechsel: Unterstützung für die Verwaltung mehrerer Versionen, freier Wechsel zwischen verschiedenen Versionen
• Lokaler Betrieb: Alle Daten werden lokal gespeichert, um Ihre Privatsphäre zu schützen
• Versionserkennung: Erkennt verfügbare neue Versionen automatisch

Anwendbare Szenarien

Desktop passt vor allem in diesen Fällen:

• Einzelne Entwickler, die Hagicode lokal nutzen möchten
• Benutzer, die möchten, dass Daten und Projekte auf ihrem eigenen Rechner bleiben
• Benutzer, die eine grafische Oberfläche bevorzugen und keine Bereitstellungskonfiguration von Hand schreiben möchten
• Entwickler, die häufig zwischen verschiedenen Versionen wechseln müssen

Vorbereitung vor der Installation

Desktop enthält kein Node.js und stellt auch keine interne Node-Laufzeitumgebung mehr bereit. Es verwendet node und npm aus dem System-PATH und installiert verwaltete Pakete wie Agent CLIs im globalen npm-Verzeichnis Ihres Rechners. Bereiten Sie vor dem Start Folgendes vor:

Abhängigkeit	Anforderung	Hinweis
Node.js	Version 24 oder höher	Liefert zugleich npm, siehe Node.js installieren
Git	Beliebige aktuelle stabile Version	Wird beim Start geprüft; das „Demoprojekt“ im Dialog „Neues Projekt“ benötigt es, um das Beispiel-Repository zu klonen, siehe Git installieren
Agent CLI	Mindestens eine, bereits angemeldet	Der Assistent listet nur lokal erkannte CLIs auf, siehe AI Agent CLI-Installation

Prüfen Sie zuerst im Terminal die Versionen:

node --version   # Erforderlich: v24.0.0 oder höher
npm --version
git --version

Erst installieren, dann starten – oder Desktop neu starten

Desktop liest den System-PATH beim Start. Wenn Sie Node.js oder Git erst installieren, nachdem Desktop bereits geöffnet war, beenden Sie Desktop vollständig, starten Sie es neu und aktualisieren Sie dann die Abhängigkeitsseite.

Desktop herunterladen

Schneller Download

Unter Windows wird empfohlen, zuerst die Installation über den Microsoft Store zu nutzen. Verwenden Sie den manuellen Download weiter unten nur, wenn Sie ein Installationspaket manuell benötigen, eine bestimmte Version als Datei brauchen oder der Store nicht verfügbar ist.

Wählen Sie die für Ihr Betriebssystem passende Version und laden Sie den Installer direkt herunter:

GitHubChina

Wenn die Download-Liste nicht geladen werden kann

Wenn die Liste der Desktop-Installationspakete hier vorübergehend nicht geladen werden kann, zeigt der Installationseinstieg keinen ungültigen Download-Link an, sondern verweist Sie auf die offizielle Versionsverlaufsseite: index.hagicode.com/desktop/history. Dort können Sie eine Version auswählen und das Installationspaket herunterladen. Alternativ nutzen Sie direkt die unten genannten GitHub Releases.

Andere Download-Methoden

Sie können das Hagicode Desktop-Installationsprogramm auch über die folgenden Kanäle beziehen:

1. Standardempfehlung für Windows: Besuchen Sie die Microsoft Store-Installation und nutzen Sie den offiziellen Store-Vertriebskanal
2. Offizielle Veröffentlichungsseite: Besuchen Sie Hagicode GitHub Releases, um manuelle Installationspakete herunterzuladen
3. Offizielle Website: Besuchen Sie die Hagicode-Website, um Download-Links und Installationshinweise zu erhalten

Wählen Sie die richtige Version

Wählen Sie das passende Installationsprogramm für Ihr Betriebssystem:

• Windows: Verwenden Sie bevorzugt den Microsoft Store; wenn Sie eine manuelle Installationsdatei benötigen, laden Sie das .exe-Installationsprogramm oder das .msix-Paket herunter
• macOS: Laden Sie das .dmg-Installationsprogramm herunter
• Linux: Laden Sie das .AppImage- oder das .tar.gz-Installationspaket herunter

Systemanforderungen

• Windows: Windows 10 oder höher (64-Bit)
• macOS: macOS 10.15 oder höher
• Linux: Gängige Linux-Distributionen (Ubuntu 20.04+, Fedora 33+ usw.)

Abhängigkeiten, die Sie selbst bereitstellen müssen

Desktop enthält bereits die .NET-Laufzeit, die für den Betrieb von Hagicode Server erforderlich ist, und führt die Standardinitialisierung über den derzeit unterstützten lokalen SQLite-Pfad durch, sodass Sie .NET nicht separat installieren müssen. Node.js 24+ und Git müssen Sie jedoch selbst installieren; Details finden Sie oben unter Vorbereitung vor der Installation.

Installations- und Starthinweise

Hinweis zum macOS Gatekeeper

Wenn Sie die App bereits im Standardpfad /Applications/Hagicode.app installiert haben, beim ersten Start aber „App ist beschädigt“, „kann nicht geöffnet werden“ oder eine ähnliche Gatekeeper-Meldung sehen, liegt die Ursache in der Regel am Quarantäneattribut com.apple.quarantine, das macOS aus dem Internet heruntergeladenen Apps hinzufügt, und nicht an einem Fehler des Hagicode Desktop-Installationsassistenten selbst.

Führen Sie im Terminal den folgenden Befehl aus. Er erfordert Administratorrechte und entfernt rekursiv das Quarantäneattribut der App im Standardinstallationspfad:

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

Starten Sie Hagicode Desktop nach Abschluss des Befehls neu.

Desktop ausführen

Öffnen Sie nach dem Herunterladen das Installationsprogramm oder das Anwendungspaket, schließen Sie die Installation ab und starten Sie anschließend Hagicode Desktop.

Netzwerkanforderungen

Stellen Sie sicher, dass Ihre Netzwerkverbindung funktioniert. Desktop muss Versionsinformationen und das Hagicode Server-Installationspaket aus dem Internet abrufen. Wenn ein Download fehlschlägt, prüfen Sie Ihre Netzwerk-, Proxy- oder Firewall-Einstellungen und versuchen Sie es erneut.

Ersteinrichtung beim ersten Start

Beim ersten Öffnen von Desktop erscheint zunächst die Desktop-eigene „Erstmalige Einrichtung“. Sie sorgt nur dafür, dass Hagicode Server installiert und gestartet wird, und umfasst der Reihe nach:

1. Sprache auswählen: Wählen Sie die Sprache von Desktop. Beim ersten Start des integrierten Backends wird ebenfalls die entsprechende Standardsprache verwendet.
2. Willkommen: Verschaffen Sie sich einen Überblick über die Vorbereitungen, die diese Einrichtung abschließt.
3. Rechtliche Dokumente bestätigen: Bestätigen Sie die aktuellen Fassungen von EULA und Datenschutzrichtlinie. Die offiziellen Dokumente werden zum Lesen im Browser geöffnet.
4. Hagicode Server herunterladen: Laden Sie das neueste Server-Paket herunter und prüfen Sie dessen Prüfsumme (Digest).

Kehren Sie nach Abschluss des Downloads zur Desktop-Startseite zurück und klicken Sie auf „Dienst starten“, um Hagicode Server zu starten. Öffnen Sie anschließend gemäß den Hinweisen auf der Startseite die Weboberfläche.

Schritte können unvollständig sein

Bei manchen Vertriebskanälen (zum Beispiel Versionen, bei denen das Server-Paket bereits im Installationspaket enthalten ist) oder wenn nach einem Versionsupdate nur die rechtlichen Dokumente erneut bestätigt werden müssen, zeigt die Einrichtung nur einen Teil dieser Schritte an.

Erste Nutzung der Weboberfläche

Beim ersten Aufruf der Weboberfläche erscheint der Initialisierungsassistent (nicht zu verwechseln mit der oben beschriebenen „Erstmaligen Einrichtung“ von Desktop). Er führt Sie durch die Wahl von Oberflächensprache und Thema, die Einrichtung des Standard-Hagicoders und die Erstellung Ihres ersten Projekts. Die einzelnen Schritte finden Sie hier:

Assistent zum EinrichtenLegen Sie Oberflächensprache, Thema, den Standard-Hagicoder und Ihr erstes Projekt fest.

Versionsverwaltung

Hagicode Desktop unterstützt die Verwaltung mehrerer Versionen, sodass Sie frei zwischen verschiedenen Versionen wechseln können.

Version wechseln

1. Öffnen Sie Hagicode Desktop
2. Gehen Sie zur Seite „Versionsverwaltung“
3. Wählen Sie die Version aus, zu der Sie wechseln möchten
4. Klicken Sie auf die Schaltfläche „Version wechseln“
5. Warten Sie, bis der Wechsel abgeschlossen ist

Hinweise zum Versionswechsel

• Beim Wechsel der Version wird Hagicode Server automatisch neu gestartet
• Stellen Sie sicher, dass Sie vor dem Wechsel alle Arbeiten speichern
• Projektkonfigurationen können sich je nach Version unterscheiden

Dienst starten und stoppen

Hagicode Desktop bietet eine einfache Möglichkeit, den Hagicode Server-Dienst zu verwalten.

Dienst starten

Klicken Sie auf der Startseite der Desktop-Anwendung auf die Schaltfläche „Dienst starten“, um Hagicode Server zu starten.

Dienst stoppen

Um Hagicode Server zu stoppen, klicken Sie auf der Startseite auf die Schaltfläche „Stoppen Sie den Dienst“.

Dienststatus

Die Desktop-Anwendung zeigt den Betriebsstatus von Hagicode Server in Echtzeit an, einschließlich:

• Dienststatus (läuft/gestoppt)
• Port des Dienstes
• Aktuelle Versionsinformationen

Nächste Schritte

Nach Abschluss der Installation können Sie mit den folgenden Schritten fortfahren:

Assistent zum EinrichtenLegen Sie nach dem ersten Start hier Ihr Projekt an und gelangen Sie in den aktuellen Schnellstart-Ablauf.

Gesprächssitzung erstellenVerstehen Sie das Projekt im standardmäßigen schreibgeschützten Modus und wechseln Sie bei Bedarf in den Bearbeitungsmodus.

Vorschlagssitzung erstellenLernen Sie den vorschlagsgetriebenen Entwicklungsworkflow kennen, der abstrakte Ideen in strukturierte Umsetzungspläne verwandelt.

Fehlerbehebung

Installationsfehler

Wenn während der Installation Probleme auftreten:

1. Netzwerkverbindung prüfen: Stellen Sie sicher, dass Sie auf das Internet zugreifen können
2. Festplattenspeicher prüfen: Stellen Sie sicher, dass genügend Speicherplatz vorhanden ist
3. Als Administrator ausführen: Klicken Sie unter Windows mit der rechten Maustaste auf das Installationsprogramm und wählen Sie „Als Administrator ausführen“
4. Hinweise des Installationsprogramms beachten: Notieren Sie die Fehlermeldung des Installationsprogramms und fügen Sie sie bei, wenn Sie ein Problem melden

Node.js, npm oder Git wird nicht gefunden

Wenn Desktop meldet, dass node, npm oder git fehlt oder die Node.js-Version zu niedrig ist:

1. Installation bestätigen: Führen Sie im Terminal node --version, npm --version und git --version aus. Node.js muss in Version 24 oder höher vorliegen. Installationshinweise finden Sie unter Node.js installieren und Git installieren.
2. Desktop neu starten: Desktop liest den System-PATH beim Start. Beenden Sie Desktop nach der Installation vollständig, starten Sie es neu und aktualisieren Sie dann die Abhängigkeitsseite.
3. PATH prüfen: Wenn der Befehl im Terminal funktioniert, Desktop ihn aber nicht findet, ist der PATH meist nur in einer bestimmten Shell-Konfiguration gesetzt (zum Beispiel über nvm oder fnm in .bashrc / .zshrc). Verwenden Sie stattdessen eine systemweite Installation oder starten Sie Desktop aus einer Umgebung, die diesen PATH kennt.
4. CLI-Paket manuell installieren: Wenn Desktop meldet, dass ein CLI-Paket manuell installiert werden muss, führen Sie den angezeigten Befehl in einem Terminal außerhalb von Desktop aus und aktualisieren Sie danach die Ansicht in Desktop. Zum Verhalten bei externer Node-/npm-Umgebung und PATH siehe Wie Desktop Ihre Node-Umgebung verwendet.

Dienststartfehler

Wenn Hagicode Server nicht startet:

1. Portbelegung prüfen: Desktop verwendet standardmäßig Port 36556 (die Startseite zeigt den tatsächlich verwendeten Port an). Stellen Sie sicher, dass er nicht von einem anderen Programm belegt ist
2. Firewall-Einstellungen prüfen: Stellen Sie sicher, dass die Firewall Hagicode Server den Netzwerkzugriff erlaubt
3. Anwendung neu starten: Versuchen Sie, Hagicode Desktop neu zu starten
4. Protokolle ansehen: Detaillierte Fehlerprotokolle finden Sie in der Desktop-Anwendung

Benötigen Sie weitere Hilfe?

Wenn Sie auf Probleme stoßen, die hier nicht behandelt werden:

1. Suchen Sie in den GitHub Issues von Desktop nach ähnlichen Problemen
2. Besuchen Sie unser Community-Forum, um Hilfe zu erhalten
3. Erstellen Sie ein neues Issue, beschreiben Sie Ihr Problem ausführlich und geben Sie Systemversion, node --version und das Desktop-Protokoll an