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>
203 lines
5.3 KiB
Markdown
203 lines
5.3 KiB
Markdown
# 旧架构更新指南（旧版 Axhub Make 项目升级到新架构）
|
||
|
||
本文档的阅读对象是 **AI Agent**。
|
||
|
||
目标：当用户明确表示要更新一个**旧架构 Axhub Make 项目**时，你应当先完成旧目录结构迁移，再执行标准更新，最后启动验证并回传本地 URL。
|
||
|
||
这里的“旧架构”特指：项目里还没有新版本 marker，且目录结构仍停留在旧命名方式，例如：
|
||
- `src/elements/`
|
||
- `src/pages/`
|
||
- `assets/docs/`
|
||
- `assets/database/`
|
||
|
||
升级后的目标新结构为：
|
||
- `src/components/`
|
||
- `src/prototypes/`
|
||
- `src/docs/`
|
||
- `src/database/`
|
||
|
||
---
|
||
|
||
## 角色与硬性约束
|
||
|
||
你是 **Axhub Make 旧架构升级助手**，通过驱动 `axhub-make` CLI 工具完成工作。
|
||
|
||
硬性约束（必须遵守）：
|
||
- 更新脚手架动作只能使用 `npx -y axhub-make ...`，不要手写脚手架逻辑替代更新命令
|
||
- 禁止：让用户手动敲命令（你直接执行，并回报结果）
|
||
- 更新前必须检查：Node.js、Git
|
||
- 在执行 `npx -y axhub-make --no-start` 之前，必须先完成旧目录迁移
|
||
- 更新后必须启动：`npm run dev` 并回传 URL
|
||
- 每一步都要汇报“执行了什么命令 + 关键结果”
|
||
|
||
---
|
||
|
||
## 执行流程（必须按顺序）
|
||
|
||
### 0) 识别旧架构项目（必须）
|
||
|
||
先检查：
|
||
- 是否存在 `package.json`
|
||
|
||
然后检查是否**缺少合法 marker**：
|
||
- `.axhub/make/make.json`
|
||
|
||
并结合旧目录特征进行识别。
|
||
|
||
满足以下条件时，才能按本规则继续：
|
||
- 没有合法的 `.axhub/make/make.json`
|
||
- 且至少存在以下任一旧目录：
|
||
- `src/elements/`
|
||
- `src/pages/`
|
||
- `assets/docs/`
|
||
- `assets/database/`
|
||
|
||
如果已经存在合法的 `.axhub/make/make.json`，说明它属于**新架构项目**，应改为使用 `rules/update-guide.md`，不要走本规则。
|
||
|
||
如果既没有 marker，也没有旧目录特征，则停止并提示用户切到正确项目目录。
|
||
|
||
### 1) Node.js 检查（必须）
|
||
|
||
```bash
|
||
node -v
|
||
```
|
||
|
||
- 未安装或版本过低（建议 < v18）：提示安装/升级并终止
|
||
|
||
### 2) Git 检查（必须）
|
||
|
||
```bash
|
||
git --version
|
||
```
|
||
|
||
- 未安装：提示安装并终止（脚手架需要 git 拉取模板）
|
||
|
||
### 3) 迁移前备份（必须）
|
||
|
||
在执行任何目录改动前，先创建带时间戳的备份目录，例如：
|
||
|
||
```bash
|
||
mkdir -p .axhub/make/backups/<timestamp>/
|
||
```
|
||
|
||
建议备份这些目录（存在才备份）：
|
||
- `src/elements/`
|
||
- `src/pages/`
|
||
- `assets/docs/`
|
||
- `assets/database/`
|
||
- `package.json`
|
||
|
||
如果目录不存在，跳过即可，但必须在结果里说明“哪些目录实际存在并被备份”。
|
||
|
||
### 4) 迁移旧目录到新目录（必须）
|
||
|
||
将以下目录迁到新架构：
|
||
- `src/elements/` → `src/components/`
|
||
- `src/pages/` → `src/prototypes/`
|
||
- `assets/docs/` → `src/docs/`
|
||
- `assets/database/` → `src/database/`
|
||
|
||
迁移原则：
|
||
- 目标目录不存在：直接迁移
|
||
- 目标目录已存在：按“不覆盖用户已有新目录内容”的原则进行合并
|
||
- 如果存在同名冲突：
|
||
- 优先保留目标目录中的现有文件
|
||
- 把旧目录里的冲突文件转存到备份冲突目录
|
||
- 在结果汇报中明确列出冲突项
|
||
- 迁移完成后，删除已经清空的旧目录
|
||
|
||
注意：
|
||
- 这是**物理目录迁移**，不是只靠运行时 URL 兼容
|
||
- 因为更新策略通常保留 `src/**` 和 `assets/**`，如果不先迁移，脚手架更新后旧目录仍会残留
|
||
|
||
### 5) 补写新架构 marker（必须）
|
||
|
||
迁移完成后，补写 marker：
|
||
|
||
```bash
|
||
mkdir -p .axhub/make
|
||
cat > .axhub/make/make.json <<'EOF2'
|
||
{ "schemaVersion": 1, "projectType": "axhub-make" }
|
||
EOF2
|
||
```
|
||
|
||
写完后，这个项目就视为**已迁到新架构**。
|
||
|
||
### 6) 执行标准更新（必须命令）
|
||
|
||
```bash
|
||
npx -y axhub-make --no-start
|
||
```
|
||
|
||
说明：
|
||
- 必须包含 `-y`
|
||
- 必须包含 `--no-start`
|
||
- 这一步必须在“目录迁移 + marker 补写”完成后执行
|
||
|
||
### 7) 启动验证
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
把终端里输出的本地访问地址（URL）回传给用户，提醒用户打开验证。
|
||
|
||
---
|
||
|
||
## 为什么旧架构需要单独处理
|
||
|
||
旧架构项目没有 `.axhub/make/make.json`，无法通过新规则中的 marker 检查。
|
||
|
||
同时，更新策略通常会保留：
|
||
- `src/**`
|
||
- `assets/**`
|
||
|
||
这意味着脚手架不会自动把这些旧目录改名：
|
||
- `src/elements/`
|
||
- `src/pages/`
|
||
- `assets/docs/`
|
||
- `assets/database/`
|
||
|
||
所以对旧架构项目，必须先迁移目录，再执行标准更新。
|
||
|
||
---
|
||
|
||
## 升级后预期结果
|
||
|
||
升级完成后，项目应满足：
|
||
- 存在 `.axhub/make/make.json`
|
||
- 原有业务内容已经迁到：
|
||
- `src/components/`
|
||
- `src/prototypes/`
|
||
- `src/docs/`
|
||
- `src/database/`
|
||
- 可以继续使用标准更新规则 `rules/update-guide.md`
|
||
|
||
---
|
||
|
||
## 出问题时的最小恢复路径
|
||
|
||
### 1) 查找升级备份
|
||
|
||
```bash
|
||
ls -la .axhub/make/backups/
|
||
ls -la package.json.backup.*
|
||
```
|
||
|
||
### 2) 恢复迁移目录（仅在确认目录迁移有误时）
|
||
|
||
优先从：
|
||
- `.axhub/make/backups/<timestamp>/`
|
||
|
||
恢复对应目录（例如 `assets/docs/`、`assets/database/`），再重新执行升级流程。
|
||
|
||
### 3) 恢复 package.json（仅在确认是依赖问题时）
|
||
|
||
```bash
|
||
cp package.json.backup.<timestamp> package.json
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
如果仍失败：继续收集 `npm install` / `npm run dev` 的报错，按“每次只修一个问题”的方式推进。
|