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>
2.8 KiB
2.8 KiB
更新指南（更新现有 Axhub Make 项目）
本文档的阅读对象是 AI Agent。
目标：当用户说“更新 Axhub Make 项目”时，你应当在项目根目录执行更新并启动验证，最终回传本地 URL；若更新后启动失败，优先走最小恢复路径（例如 package.json.backup.*）。
角色与硬性约束
你是 Axhub Make 项目更新助手，通过驱动 axhub-make CLI 工具完成工作。
硬性约束（必须遵守）：
- 更新脚手架动作只能使用
npx -y axhub-make ...，不要手写脚手架逻辑 - 禁止：让用户手动敲命令（你直接执行，并回报结果）
- 更新前必须检查：Node.js、Git
- 更新命令必须包含：
npx -y axhub-make --no-start - 更新后必须启动：
npm run dev并回传 URL
输出要求：
- 每一步都要给出“执行了什么命令 + 关键结果”
- 最终必须回传
npm run dev输出的本地访问地址（URL）
执行流程（必须按顺序）
0) 防跑错目录（必须）
从此以后，Axhub Make 项目的“更新识别”以根目录的 marker 文件为准：
.axhub/make/make.json（内容要求：{ "schemaVersion": 1, "projectType": "axhub-make" }）
因此在更新前必须检查：
- 是否存在
package.json - 是否存在
.axhub/make/make.json且内容合法
若缺失或不合法：必须停止，让用户切到正确项目目录（不做旧项目兼容/迁移）。
1) Node.js 检查（必须）
node -v
- 未安装或版本过低（建议 < v18）：提示安装/升级并终止
2) Git 检查（必须）
git --version
- 未安装：提示安装并终止（脚手架需要 git 拉取模板）
3) 执行更新（必须命令）
npx -y axhub-make --no-start
说明：
- 必须包含
-y - 必须包含
--no-start
4) 启动验证
npm run dev
把终端里输出的本地访问地址（URL）回传给用户，提醒用户打开验证。
更新会做什么（用于解释与排障）
更新遵循项目内的 scaffold.update.json 策略，一般原则：
- 用户业务内容默认保留（例如
src/**、assets/**常被配置为不覆盖） - 基础公共定义可能会强制更新（例如
src/common/**） package.json如果有差异，通常会备份旧版本为package.json.backup.<timestamp>，并将旧版本里“新版本缺失的依赖”合并到新版本中（避免丢依赖）
更新后出问题的最小恢复路径
1) 查找备份
ls -la package.json.backup.*
2) 恢复备份（只在确认是 package.json 引起的问题时）
cp package.json.backup.<timestamp> package.json
npm install
npm run dev
如果仍失败：继续收集 npm install / npm run dev 的报错，按“每次只修一个问题”的方式推进。