Files

王冕 a27e3b8e43 feat: sync full workspace including web modules, docs, and configurations to Gitea

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>

2026-06-09 18:12:25 +08:00

5.3 KiB

Raw Blame History

旧架构更新指南（旧版 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 检查（必须）

node -v

未安装或版本过低（建议 < v18）：提示安装/升级并终止

2) Git 检查（必须）

git --version

未安装：提示安装并终止（脚手架需要 git 拉取模板）

3) 迁移前备份（必须）

在执行任何目录改动前，先创建带时间戳的备份目录，例如：

mkdir -p .axhub/make/backups/<timestamp>/

建议备份这些目录（存在才备份）：

src/elements/
src/pages/
assets/docs/
assets/database/
package.json

如果目录不存在，跳过即可，但必须在结果里说明“哪些目录实际存在并被备份”。

将以下目录迁到新架构：

src/elements/ → src/components/
src/pages/ → src/prototypes/
assets/docs/ → src/docs/
assets/database/ → src/database/

迁移原则：

目标目录不存在：直接迁移
目标目录已存在：按“不覆盖用户已有新目录内容”的原则进行合并
如果存在同名冲突：
- 优先保留目标目录中的现有文件
- 把旧目录里的冲突文件转存到备份冲突目录
- 在结果汇报中明确列出冲突项
迁移完成后，删除已经清空的旧目录

注意：

这是物理目录迁移，不是只靠运行时 URL 兼容
因为更新策略通常保留 src/** 和 assets/**，如果不先迁移，脚手架更新后旧目录仍会残留

5) 补写新架构 marker（必须）

迁移完成后，补写 marker：

mkdir -p .axhub/make
cat > .axhub/make/make.json <<'EOF2'
{ "schemaVersion": 1, "projectType": "axhub-make" }
EOF2

写完后，这个项目就视为已迁到新架构。

6) 执行标准更新（必须命令）

npx -y axhub-make --no-start

说明：

必须包含 -y
必须包含 --no-start
这一步必须在“目录迁移 + marker 补写”完成后执行

7) 启动验证

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) 查找升级备份

ls -la .axhub/make/backups/
ls -la package.json.backup.*

2) 恢复迁移目录（仅在确认目录迁移有误时）

优先从：

.axhub/make/backups/<timestamp>/

恢复对应目录（例如 assets/docs/、assets/database/），再重新执行升级流程。

3) 恢复 package.json（仅在确认是依赖问题时）

cp package.json.backup.<timestamp> package.json
npm install
npm run dev

如果仍失败：继续收集 npm install / npm run dev 的报错，按“每次只修一个问题”的方式推进。

5.3 KiB Raw Blame History Unescape Escape