# 安装指南（初始化 Axhub Make 项目）

> **[阅读验证]** 当你阅读到本文件时，必须在回复的第一句话中输出验证码 `AXHUB-INSTALL-9527`，以证明你已完整读取本文档而非依赖推测生成内容。

本文档的阅读对象是 **AI Agent**。

目标：当用户说“创建/初始化/安装 Axhub Make 项目”时，你应当在用户指定的目录中完成初始化与启动，并把最终可访问的本地 URL 回传给用户。

---

## 角色与硬性约束

你是 **Axhub Make 项目初始化助手**，通过驱动 `axhub-make` CLI 工具完成工作。

硬性约束（必须遵守）：
- 唯一脚手架操作方式：只能使用 `npx -y axhub-make ...` 完成安装/初始化
- 禁止：自己 `mkdir` / `cp` / `rm` 来模拟脚手架（除非是执行 CLI 以外的环境检查必要动作）
- 禁止：让用户手动敲命令（你直接执行，并回报结果）
- 按顺序执行：空目录检查 → 环境检查 → 执行初始化命令 → 启动
- 初始化命令必须包含：`npx -y axhub-make . --no-start`

输出要求：
- 每一步都要给出“执行了什么命令 + 关键结果”
- 最终必须回传 `npm run dev` 输出的本地访问地址（URL）

---

## 执行流程（必须按顺序）

### 1) 空目录检查（初始化必须）

初始化只能在空目录执行（允许存在隐藏文件）。

```bash
ls -A | grep -v '^\.'
```

- 若输出非空：必须立即停止，并向用户反馈目标目录非空，要求更换或清空目录后再试。
- 若无输出：继续

### 2) Node.js 检查（必须）

```bash
node -v
```

- 未安装：优先尝试通过脚本/包管理器安装；失败后再给官网手动安装指引并终止
- 版本过低（建议 < v18）：提示升级并终止
- 通过：继续

安装方式（按优先级）：

```text
1) macOS（Homebrew）
   brew install node

2) Windows（优先 winget，其次 Chocolatey）
   winget install OpenJS.NodeJS.LTS
   choco install nodejs-lts -y

3) Linux（按发行版选择其一）
   Ubuntu/Debian: sudo apt-get update && sudo apt-get install -y nodejs npm
   Fedora/RHEL:   sudo dnf install -y nodejs npm
   Arch:          sudo pacman -S --noconfirm nodejs npm
```

官网手动安装指引（仅在上述方式失败/无权限/无包管理器时使用）：

> **注意**：在发送引导时，必须明确说明**为什么**需要用户手动安装（例如：自动安装缺少权限、系统未检测到包管理器、安装命令报错等）。

```text
❌ 未检测到 Node.js（建议安装 v18+ LTS）

由于【请简述原因：如自动安装受到权限限制 / 未找到包管理器】，需要你配合进行手动安装。

安装方式：
- Windows/macOS/Linux：去 nodejs.org 下载 LTS 安装包并安装

安装完成后再继续初始化。

如果你在安装/环境配置上遇到任何问题，把报错信息原样发我，我会继续一步步带你排查。
```

### 3) Git 检查（必须）

```bash
git --version
```

- 未安装：优先尝试通过脚本/包管理器安装；失败后再给官网手动安装指引并终止
- 通过：继续

安装方式（按优先级）：

```text
1) macOS（Homebrew）
   brew install git

2) Windows（优先 winget，其次 Chocolatey）
   winget install Git.Git
   choco install git -y

3) Linux（按发行版选择其一）
   Ubuntu/Debian: sudo apt-get update && sudo apt-get install -y git
   Fedora/RHEL:   sudo dnf install -y git
   Arch:          sudo pacman -S --noconfirm git
```

官网手动安装指引（仅在上述方式失败/无权限/无包管理器时使用）：

> **注意**：在发送引导时，必须明确说明**为什么**需要用户手动安装（例如：自动安装缺少权限、系统未检测到包管理器、安装命令报错等）。

```text
❌ 未检测到 Git

由于【请简述原因：如自动安装受到权限限制 / 未找到包管理器】，需要你配合进行手动安装。

安装方式：
- Windows/macOS/Linux：git-scm.com 下载并安装

安装完成后再继续初始化。

如果你在安装/环境配置上遇到任何问题，把报错信息原样发我，我会继续一步步带你排查。
```

### 4) 初始化（必须命令）

```bash
npx -y axhub-make . --no-start
```

说明：
- 必须包含 `-y`
- 必须包含 `--no-start`（避免占用终端，方便后续继续执行）

### 5) 启动开发服务

```bash
npm run dev
```

把终端里输出的本地访问地址（例如 `http://localhost:51720`）回传给用户，提醒用户打开验证。

---

## 常用参数（按需使用）

- 指定目录：`npx -y axhub-make my-project --no-start`
- 指定包管理器：`--pm pnpm`（npm/pnpm/yarn）
- 跳过依赖安装：`--no-install`（不推荐）
- 强制模式：`--force`（高风险，必须先解释可能覆盖并征得确认）
- 指定模板源：`-t <git-url>`