Desktop 安裝

本頁說明如何安裝和使用 Hagicode Desktop。它是官方桌面用戶端，負責把預設的本機安裝流程與日常管理入口放到同一處。

建議方式

macOS、Linux 以及不走商店的 Windows 使用者，個人本機使用時建議使用 Desktop：

• 首次啟動引導會把下載與啟動流程串起來
• Hagicode Server 的啟動、停止與版本由程式統一管理
• 圖形介面更方便檢視狀態與操作
• 內建版本管理，便於切換不同版本
• 預設資料留在本機，便於自行掌控

Windows 使用者請優先考慮 Microsoft Store 安裝；伺服器或團隊部署請使用 Docker Compose。

什麼是 Hagicode Desktop

Hagicode Desktop 是 Hagicode 的官方桌面應用程式，支援 Windows、macOS 和 Linux。它負責下載、啟動和管理本機的 Hagicode Server，並提供版本管理與日常操作入口。

主要優勢

• 內建 .NET 執行階段：執行 Hagicode Server 所需的 .NET 已隨 Desktop 提供，無需單獨安裝
• 服務管理：內建 Hagicode Server 管理，輕鬆啟動和停止服務
• 版本切換：支援多版本管理，可在不同版本之間自由切換
• 本機執行：所有資料儲存在本機，保護您的隱私
• 版本偵測：自動偵測可用的新版本

適用情境

這些情境可優先使用 Desktop：

• 個人開發者希望在本機使用 Hagicode
• 希望資料和專案都留在自己機器上的使用者
• 偏好圖形介面、不想手寫部署設定的使用者
• 需要頻繁切換不同版本的開發者

安裝前準備

Desktop 不內建 Node.js，也不再提供內部的 Node 執行環境。它會使用系統 PATH 中的 node 與 npm，並把 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。如果在 Desktop 已開啟時才安裝 Node.js 或 Git，請完全結束並重新啟動 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 已內建執行 Hagicode Server 所需的 .NET 執行階段，並依目前支援的本機 SQLite 路徑完成預設初始化，您無需單獨安裝 .NET。但 Node.js 24+ 與 Git 需要您自行安裝，詳見上文的安裝前準備。

安裝與啟動提示

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

下載完成後，開啟安裝程式或應用程式套件完成安裝，再啟動 Hagicode Desktop。

網路需求

確保您的網路連線正常。Desktop 需要從網際網路取得版本資訊和 Hagicode Server 安裝套件；如果下載失敗，請檢查網路、代理或防火牆設定後重試。

首次啟動引導

第一次開啟 Desktop 時，會先進入 Desktop 內建的「首次使用引導」。它只負責把 Hagicode Server 裝好並啟動，依序包括：

1. 選擇語言：選擇 Desktop 使用的語言。首次啟動內建後端時，也會採用對應的預設語言。
2. 歡迎：了解本次引導會完成的準備工作。
3. 確認法律文件：確認目前版本的 EULA 與隱私權政策，正式文件會在瀏覽器中開啟閱讀。
4. 下載 Hagicode Server：下載最新的 Server 安裝套件並驗證其摘要。

下載完成後回到 Desktop 首頁，點擊「啟動服務」即可啟動 Hagicode Server，隨後依首頁提示開啟 Web 介面。

步驟可能不完整

部分發行管道（例如已隨安裝套件提供 Server 的版本），或在版本更新後只需重新確認法律文件時，引導只會顯示其中的部分步驟。

首次使用 Web 介面

首次進入 Web 介面後，會出現 初始化嚮導（與上面的 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 只在某個 shell 設定裡生效（例如透過 nvm 或 fnm 在 .bashrc / .zshrc 中設定）。請改用系統層級安裝，或確保從能讀到該 PATH 的環境啟動 Desktop。
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. 查看 Desktop 的 GitHub Issues 尋找類似問題
2. 前往我們的社群論壇尋求協助
3. 提交新的 Issue，詳細描述您的問題，並附上系統版本、node --version 與 Desktop 日誌