a27e3b8e43
Optimized the root .gitignore to exclude virtual environments, node modules, and temp folders to ensure clean and lightweight version tracking. Co-authored-by: Cursor <cursoragent@cursor.com>
153 lines
4.8 KiB
Markdown
153 lines
4.8 KiB
Markdown
# 安装指南（初始化 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>`
|