安装指南

HagiCode 提供两种安装方式。先按使用场景选一条路径，再确认这条路径需要的前置条件，最后进入对应的安装页。

选择安装方式

你的场景	推荐方式
Windows 个人本地使用	Microsoft Store 安装
macOS / Linux 个人本地使用，或 Windows 无法使用商店	Desktop 安装

Microsoft Store 安装Windows 默认推荐入口，通过官方商店完成安装与后续更新。

Desktop 安装图形化安装与管理流程。适合 macOS / Linux，以及需要手动下载安装包的 Windows 用户。

安装前准备

不同路径需要的前置条件不同：

安装方式	Node.js	Git
Microsoft Store / Desktop	需自行安装 24 或更高版本	需自行安装

Desktop 不再内置 Node.js

Desktop 只内置运行 HagiCode Server 所需的 .NET 运行时，不再提供 Node.js。它会在系统 PATH 中查找 node 与 npm，并把 Agent CLI 等托管包安装到你本机 npm 的全局目录。请在首次启动 Desktop 之前先装好 Node.js 24 或更高版本，详见 安装 Node.js。

安装 Git

Desktop 会在启动时检测 node、npm 与 git，主界面“新建项目”对话框里的“演示项目”也需要通过 Git 克隆官方示例仓库。请按你的系统选择一种方式安装：

• Windows：运行 winget install --id Git.Git -e，或从 git-scm.com 下载安装程序。
• macOS：运行 xcode-select --install，或使用 Homebrew 运行 brew install git。
• Debian / Ubuntu：运行 sudo apt-get install -y git。
• Fedora：运行 sudo dnf install -y git。

安装完成后重新打开终端，确认命令可用：

node --version
npm --version
git --version

装好之后再启动 Desktop

Desktop 在启动时读取系统 PATH。如果你是在 Desktop 已经打开的情况下才安装 Node.js 或 Git，请完全退出并重新启动 Desktop。

Agent CLI

HagiCode 通过本机已安装并完成登录的 Agent CLI 工作。初始化向导只会列出本机已检测到的 CLI，所以请在进入向导之前至少装好并登录一个。当前支持的 CLI、安装方式与官方入口，统一维护在 AI Agent CLI 安装。

相关软件安装

安装 Node.js准备 Node.js 24+ 与 npm，Desktop 与大多数 Agent CLI 都依赖它。

OpenSpec 介绍前往 OpenSpec 独立文档站，了解安装方式、核心概念与规范驱动工作流。

安装 AI Agent CLI查看当前支持的 Agent CLI，区分一键安装与手动安装 / 认证。

下一步

1. 按上表选择安装方式，并先完成前置条件。
2. 完成安装并首次启动，随后按 初始化向导设置 创建默认 Hagicoder 与第一个项目。
3. 想了解 OpenSpec 提案流程，可阅读 OpenSpec 介绍 与 创建提案会话。