Установка Desktop

На этой странице описано, как установить и использовать Hagicode Desktop. Это официальный клиент для настольных систем, который объединяет стандартный путь локальной установки и повседневное управление в одном месте.

Рекомендуемый способ

Для личного локального использования в macOS, Linux, а также в Windows без Store рекомендуется Desktop:

• руководство первого запуска проведет вас через загрузку и запуск
• запуск, остановка и версии Hagicode Server управляются из одной программы
• графический интерфейс удобнее для просмотра состояния и выполнения операций
• встроенное управление версиями упрощает переключение между версиями
• данные по умолчанию остаются на вашем компьютере, и вы сами их контролируете

Пользователям Windows в первую очередь стоит рассмотреть установку из Microsoft Store; для серверов и командного развертывания используйте Docker Compose.

Что такое Hagicode Desktop

Hagicode Desktop — это официальное настольное приложение Hagicode, которое работает в Windows, macOS и Linux. Оно скачивает, запускает и обслуживает Hagicode Server на вашем компьютере, а также предоставляет управление версиями и повседневные операции.

Основные преимущества

• Встроенная среда выполнения .NET: .NET, необходимая для запуска Hagicode Server, уже поставляется вместе с Desktop, устанавливать ее отдельно не нужно
• Управление службой: встроенное управление Hagicode Server позволяет легко запускать и останавливать службу
• Переключение версий: поддерживается управление несколькими версиями, между которыми можно свободно переключаться
• Локальная работа: все данные хранятся локально, что защищает вашу конфиденциальность
• Проверка версий: автоматически обнаруживает доступные новые версии

Применимые сценарии

Desktop стоит выбрать в таких случаях:

• индивидуальным разработчикам, которые хотят использовать Hagicode локально
• пользователям, которые хотят, чтобы данные и проекты оставались на их собственном компьютере
• тем, кто предпочитает графический интерфейс и не хочет вручную писать конфигурацию развертывания
• разработчикам, которым нужно часто переключаться между разными версиями

Подготовка перед установкой

Desktop не включает Node.js и больше не предоставляет собственную внутреннюю среду Node. Он использует node и npm из системной переменной PATH и устанавливает управляемые пакеты, например Agent CLI, в глобальный каталог npm на вашем компьютере. Прежде чем начать, подготовьте следующее:

Зависимость	Требование	Описание
Node.js	24 или выше	Вместе с ним устанавливается npm, см. Установка Node.js
Git	Любая актуальная стабильная версия	Проверяется при запуске; «Демо-проект» в диалоге «Новый проект» использует его для клонирования репозитория с примером, см. Установка Git
Agent CLI	Хотя бы один, с выполненным входом	Мастер показывает только те CLI, которые обнаружены на этом компьютере, см. Установка AI Agent CLI

Сначала проверьте версии в терминале:

node --version   # нужна версия v24.0.0 или выше
npm --version
git --version

Сначала установите, потом запускайте, или перезапустите Desktop

Desktop читает системную переменную PATH при запуске. Если вы установили Node.js или Git, когда Desktop уже был открыт, полностью закройте Desktop и запустите его заново, а затем обновите страницу зависимостей.

Скачать Desktop

Быстрая загрузка

Пользователям Windows рекомендуется в первую очередь устанавливать приложение из Microsoft Store; ссылки для ручной загрузки ниже используйте, только если вам нужен установочный пакет, файл определенной версии или Store недоступен.

Выберите версию для вашей операционной системы и скачайте установщик напрямую:

GitHubChina

Если список загрузок не загрузился

Если список установочных пакетов Desktop временно не загружается, точка входа не покажет недействительную ссылку для скачивания, а направит вас на официальную страницу истории версий: index.hagicode.com/desktop/history. Там можно выбрать версию и скачать установочный пакет; также можно воспользоваться GitHub Releases ниже.

Другие способы получения

Установщик Hagicode Desktop можно получить и по следующим каналам:

1. Рекомендуется для Windows: откройте установку из Microsoft Store и установите приложение через официальный канал магазина
2. Официальная страница релизов: на Hagicode GitHub Releases можно скачать пакеты для ручной установки
3. Официальный сайт: на официальном сайте Hagicode есть ссылки для скачивания и инструкции по установке

Выбор подходящей версии

Выберите установщик, соответствующий вашей операционной системе:

• Windows: в первую очередь используйте Microsoft Store; если нужны файлы для ручной установки, скачайте установщик .exe или пакет .msix
• macOS: скачайте установщик .dmg
• Linux: скачайте установочный пакет .AppImage или .tar.gz

Системные требования

• Windows: Windows 10 или новее (64-разрядная)
• macOS: macOS 10.15 или новее
• Linux: основные дистрибутивы Linux (Ubuntu 20.04+, Fedora 33+ и т. д.)

Что нужно подготовить самостоятельно

Desktop уже включает среду выполнения .NET, необходимую для запуска Hagicode Server, и выполняет инициализацию по умолчанию по поддерживаемому пути с локальной SQLite, поэтому устанавливать .NET отдельно не нужно. Однако Node.js 24+ и Git нужно установить самостоятельно — подробности смотрите в разделе Подготовка перед установкой выше.

Примечания по установке и запуску

Предупреждение macOS Gatekeeper

Если вы уже установили приложение по пути по умолчанию /Applications/Hagicode.app, но при первом запуске видите сообщение «приложение повреждено», «не удается открыть» или похожее предупреждение Gatekeeper, обычная причина — атрибут карантина com.apple.quarantine, который macOS добавляет к приложениям, скачанным из интернета, а не ошибка самого мастера установки Hagicode Desktop.

Выполните в терминале следующую команду. Для нее нужны права администратора; она рекурсивно снимает атрибут карантина с приложения по пути установки по умолчанию:

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

После выполнения команды перезапустите Hagicode Desktop.

Запуск Desktop

После загрузки откройте установщик или пакет приложения, завершите установку и запустите Hagicode Desktop.

Требования к сети

Убедитесь, что сетевое соединение работает. Desktop получает из интернета сведения о версиях и установочный пакет Hagicode Server; если загрузка не удалась, проверьте настройки сети, прокси или брандмауэра и повторите попытку.

Руководство первого запуска

При первом открытии Desktop сначала показывает собственное «руководство первого использования» (в приложении оно называется «Первоначальная настройка»). Оно только устанавливает и запускает Hagicode Server и включает следующие шаги по порядку:

1. Выбор языка: выберите язык Desktop. При первом запуске встроенного бэкенда будет использован соответствующий язык по умолчанию.
2. Приветствие: узнайте, какую подготовку выполнит это руководство.
3. Подтверждение юридических документов: подтвердите текущие версии лицензионного соглашения (EULA) и политики конфиденциальности; официальные документы открываются для чтения в браузере.
4. Скачать Hagicode Server: скачайте последний пакет Server и проверьте его дайджест.

После завершения загрузки вернитесь на главную страницу Desktop и нажмите «Запустить службу», чтобы запустить Hagicode Server, а затем откройте веб-интерфейс по подсказкам на главной странице.

Шаги могут отображаться не все

В некоторых каналах распространения (например, в сборках, где Server уже входит в установочный пакет) или когда после обновления версии нужно только заново подтвердить юридические документы, руководство показывает лишь часть этих шагов.

Первое использование веб-интерфейса

При первом входе в веб-интерфейс появляется мастер инициализации (это не то же самое, что описанное выше руководство первого использования Desktop). Он поможет выбрать язык интерфейса и тему, настроить Hagicoder по умолчанию и создать первый проект. Подробные шаги описаны здесь:

Настройка мастера инициализацииНастройте язык, тему, Hagicoder по умолчанию и первый проект.

Управление версиями

Hagicode Desktop поддерживает управление несколькими версиями, между которыми можно свободно переключаться.

Переключение версии

1. Откройте Hagicode Desktop
2. Перейдите на страницу «Управление версиями»
3. Выберите версию, на которую хотите переключиться
4. Нажмите кнопку «Сменить версию»
5. Дождитесь завершения переключения

Примечания по переключению версий

• При переключении версии Hagicode Server автоматически перезапускается
• Перед переключением обязательно сохраните всю работу
• Конфигурация проектов в разных версиях может отличаться

Запуск и остановка службы

Hagicode Desktop предоставляет простой способ управлять службой Hagicode Server.

Запуск службы

На главной странице приложения Desktop нажмите кнопку «Запустить службу», чтобы запустить Hagicode Server.

Остановка службы

Чтобы остановить Hagicode Server, нажмите кнопку «Остановить службу» на главной странице.

Состояние службы

Приложение Desktop в реальном времени показывает состояние Hagicode Server, в том числе:

• состояние службы (работает / остановлена)
• номер порта службы
• сведения о текущей версии

Дальнейшие шаги

После завершения установки вы можете продолжить следующими шагами:

Настройка мастера инициализацииПосле первого запуска создайте здесь проект и перейдите к стандартной цепочке быстрого старта.

Создать сеанс разговораИзучите проект в режиме только для чтения по умолчанию, а при необходимости переключитесь в режим редактирования.

Создать сеанс предложенийПознакомьтесь с рабочим процессом разработки на основе предложений, который превращает абстрактные идеи в структурированные планы реализации.

Устранение неполадок

Не удалось выполнить установку

Если во время установки возникли проблемы:

1. Проверьте сетевое подключение: убедитесь, что есть доступ в интернет
2. Проверьте место на диске: убедитесь, что на диске достаточно свободного места
3. Запустите от имени администратора: в Windows щелкните установщик правой кнопкой мыши и выберите «Запуск от имени администратора»
4. Посмотрите сообщение установщика: запишите текст ошибки, который показал установщик, и приложите его, когда будете сообщать о проблеме

Не найден Node.js, npm или Git

Если Desktop сообщает, что отсутствует node, npm или git, либо что версия Node.js слишком старая:

1. Убедитесь, что все установлено: выполните в терминале node --version, npm --version и git --version. Для Node.js нужна версия 24 или выше; способы установки описаны в разделах Установка Node.js и Установка Git.
2. Перезапустите Desktop: Desktop читает системную переменную PATH при запуске. После установки полностью закройте Desktop и запустите его заново, а затем обновите страницу зависимостей.
3. Проверьте PATH: если команды работают в терминале, а Desktop их не находит, обычно это значит, что PATH задан только в конфигурации определенной оболочки (например, через nvm или fnm в .bashrc / .zshrc). Используйте установку на уровне системы или убедитесь, что Desktop запускается из среды, которая видит этот PATH.
4. Установите пакет CLI вручную: если Desktop сообщает, что пакет CLI нужно установить вручную, выполните предложенную им команду в терминале вне Desktop, а затем вернитесь в Desktop и обновите страницу. О поведении внешней среды Node / npm и PATH читайте в Как Desktop использует вашу среду Node.

Не удалось запустить службу

Если Hagicode Server не запускается:

1. Проверьте, не занят ли порт: по умолчанию Desktop использует порт 36556 (текущий фактический порт показан на главной странице); убедитесь, что его не занимает другая программа
2. Проверьте настройки брандмауэра: убедитесь, что брандмауэр разрешает Hagicode Server доступ к сети
3. Перезапустите приложение: попробуйте перезапустить Hagicode Desktop
4. Посмотрите журналы: подробные журналы ошибок доступны в приложении Desktop

Нужна дополнительная помощь?

Если вы столкнулись с проблемой, которая здесь не описана:

1. Поищите похожие проблемы в GitHub Issues Desktop
2. Обратитесь за помощью на наш форум сообщества
3. Создайте новый Issue, подробно опишите проблему и приложите версию системы, вывод node --version и журнал Desktop