Desktop 安装

本页说明如何安装和使用 Hagicode Desktop。它是官方桌面客户端，负责把默认本地安装流程与日常管理入口放到同一处。

推荐方式

Desktop 是个人开发与本地使用的默认安装路径，原因如下：

• 安装向导会把默认流程串起来
• 依赖项与服务由程序统一管理
• 图形界面更方便查看状态与操作
• 内置版本管理，便于切换不同版本
• 默认数据留在本地，便于自行控制

什么是 Hagicode Desktop

Hagicode Desktop 是 Hagicode 的官方桌面应用程序，专为 Windows、macOS 和 Linux 系统设计。它集成了 Hagicode 的核心功能，默认安装向导会把首次部署流程顺着带完。

主要优势

• 一键安装：通过安装向导，自动完成所有配置步骤
• 自动运行时准备：默认安装流程已内置所需运行时，无需单独安装 .NET
• 服务管理：内置 Hagicode Server 管理，轻松启动和停止服务
• 版本切换：支持多版本管理，可在不同版本之间自由切换
• 本地运行：所有数据存储在本地，保护您的隐私
• 自动更新：自动检测并下载最新版本

适用场景

这些场景可优先用 Desktop：

• 个人开发者希望在本地使用 Hagicode
• 需要离线使用 Hagicode 的用户
• 希望简化安装过程的非技术用户
• 需要频繁切换不同版本的开发者

下载 Desktop

快速下载

Windows 用户推荐优先使用 Microsoft Store 安装；只有在您需要手动安装包、指定版本文件或 Store 不可用时，再使用下方的手动下载入口。

选择适合您操作系统的版本，直接下载安装程序：

GitHub中国大陆

版本历史 fallback

若当前页面无法从主源、备用源或站内快照成功加载 Desktop 包列表，安装入口会停止提供伪造下载链接，并自动引导您前往 canonical Index 版本历史页：https://index.hagicode.com/desktop/history/。

该历史页会直接读取 https://index.hagicode.com/desktop/index.json，因此当这里跳转后，您仍可继续查看可读版本历史与原始 JSON 数据。若版本页本身也异常，请优先排查 repos/index 的发布结果。

其他获取方式

您还可以从以下渠道获取 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+ 等）

默认安装前置条件

对于最新版本 HagiCode 的默认本地安装流程，通常不需要您单独准备独立 .NET 运行时。Desktop 默认安装程序已经内置所需运行时，并按当前支持的本地 SQLite 路径完成默认初始化。

安装与启动提示

macOS Gatekeeper 提示

如果您已经将应用安装到默认路径 /Applications/Hagicode.app，但首次启动时看到”应用已损坏”、“无法打开”或类似 Gatekeeper 提示，通常是因为 macOS 为从互联网下载的应用附加了 com.apple.quarantine 隔离属性，而不是 Hagicode Desktop 安装向导本身出错。

您可以在终端执行以下命令。该命令需要管理员权限，会递归移除默认安装路径上应用的 quarantine 属性：

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

执行完成后，请重新启动 Hagicode Desktop。

运行 Desktop

下载完成后，打开安装程序或应用包，并请按照界面提示进行操作。Desktop 会在当前受支持的本地路径中准备运行环境、管理 Hagicode Server，并在需要网络下载时显示进度与状态。

网络要求

确保您的网络连接正常。Desktop 可能需要从互联网获取版本信息或组件包；如果下载失败，请检查网络、代理或防火墙设置后重试。

首次使用

首次进入 Hagicode 后，您会进入当前版本的初始化向导。请按照界面提示进行操作；详细的首次设置、项目创建和会话创建说明由快速开始页面承接。

如果您想按最新界面逐步完成首次设置，请直接阅读快速开始中的专门页面：

初始化向导设置点击此处可以查看进入 web 页面之后如何进行初始化

版本管理

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. 查看日志文件：安装程序会生成详细的日志文件，可以帮助诊断问题

依赖项安装失败

如果依赖项安装失败：

1. 检查系统兼容性：确保您的操作系统满足最低要求
2. 检查网络与防火墙设置：确保安装程序可以访问所需下载资源，且未被防火墙拦截
3. 确认安装权限：在 Windows 上可尝试使用”以管理员身份运行”，确保安装程序拥有足够权限
4. 重启应用后重试：关闭并重新打开 Hagicode Desktop，再重新执行安装
5. 查看日志文件：在 Desktop 应用程序中查看详细日志，定位具体失败原因

服务启动失败

如果 Hagicode Server 无法启动：

1. 检查端口占用：确保端口 45000 未被其他程序占用
2. 检查防火墙设置：确保防火墙允许 Hagicode Server 访问网络
3. 重启应用程序：尝试重启 Hagicode Desktop
4. 查看日志：在 Desktop 应用程序中查看详细的错误日志

需要更多帮助？

如果您遇到此处未涵盖的问题：

1. 查看 GitHub Issues 寻找类似问题
2. 访问我们的社区论坛寻求帮助
3. 提交新的 Issue，详细描述您的问题