hongmaple0820 SCALE Engine Release Workflow
Trigger
当用户说以下关键词时自动激活此技能：
- "发版" / "发布" / "release"
- "提交发版" / "提交发布"
- "push to npm" / "publish"
Purpose
确保发版流程完整执行，包括：
- 文档更新（README 徽章、版本号、更新日志）
- 构建和测试验证
- npm 发布
- Git 推送双仓库
- 验证 npmmirror 同步
Release Checklist
Agent 必须按顺序执行以下检查，不可跳过：
Phase 1: 验证当前状态
# 1. 检查 git 状态
git status
git diff HEAD
# 2. 检查当前版本
cat package.json | grep version
# 3. 运行测试
npm run build
npx vitest run
门禁: 测试必须全部通过，否则停止并报告问题。
Phase 2: 确定版本号
根据变更内容决定版本号：
| 变更类型 | 版本号变化 |
|---|---|
| 新功能（Feature） | minor（0.x.0 → 0.x+1.0）或 patch |
| Bug 修复 | patch（0.x.y → 0.x.y+1） |
| 破坏性变更 | major（0.x.y → 1.0.0） |
| 仅文档更新 | patch |
# 更新版本号
npm version patch --no-git-tag-version # 或 minor / major
Phase 3: 文档同步（CRITICAL - 必须执行）
文档更新是发版的必要步骤，不可跳过！
Agent 必须更新以下文件：
README.md 和 README.en.md
检查并更新所有版本相关内容：
徽章版本号（第 2、8 行）：
<img src="https://img.shields.io/badge/version-{VERSION}-orange?style=flat-square" /> <img src="https://img.shields.io/badge/npm-{VERSION}-cb3837?style=flat-square&logo=npm" />标题版本号（第 11 行）：
# SCALE Engine v{VERSION}测试数量徽章（如有变化）：
<img src="https://img.shields.io/badge/tests-{COUNT}-passing-brightgreen?style=flat-square" />平台数量徽章（如有变化）：
<img src="https://img.shields.io/badge/platforms-{COUNT}-blue?style=flat-square" />更新日志：添加新版本说明：
## v{VERSION} 更新 - [列出本次变更内容] - 测试数量：{COUNT} 通过
package.json
更新 description 字段（如果主要功能有变化）：
"description": "SCALE Engine v{VERSION} - [功能摘要]"
验证文档同步：
# 检查 README 版本号是否与 package.json 一致
grep -E "version-|npm-|# SCALE Engine v" README.md | grep "{VERSION}"
grep -E "version-|npm-|# SCALE Engine v" README.en.md | grep "{VERSION}"
Phase 4: 构建和发布
# 1. 构建
npm run build
# 2. 运行完整测试
npx vitest run
# 3. 发布到 npm（公开包）
npm publish
# 4. 验证发布成功
curl -s "https://registry.npmjs.org/@hongmaple0820/scale-engine/latest" | grep version
Phase 5: Git 推送
# 1. 提交所有更改
git add README.md README.en.md package.json package-lock.json CHANGELOG.md
git commit -m "$(cat <<'EOF'
chore: release v{VERSION}
- Update README badges and version headers
- Update package.json description
- [其他变更内容]
EOF
)"
# 2. 推送到双仓库
git push origin master
git push github master
# 3. 验证推送成功
git log -1 --oneline
Phase 6: 验证 npmmirror 同步
# 检查淘宝镜像同步状态（约 10 分钟后）
curl -s "https://registry.npmmirror.com/@hongmaple0820/scale-engine/latest" | grep version
告诉用户：
npmmirror（淘宝镜像）会自动同步，约 10 分钟后可用。 用户可通过
npm install --registry=https://registry.npmmirror.com快速安装。
Common Mistakes to Avoid
| 错误 | 说明 |
|---|---|
| ❌ 忘记更新 README 徽章 | npm 包的 README 是发布时打包的，必须重新发布才能更新 |
| ❌ 版本号不一致 | README 徽章、标题、package.json 必须全部同步 |
| ❌ 不运行测试 | 测试失败时禁止发布 |
| ❌ 忽略 npmmirror | 中国用户依赖镜像，需告知同步状态 |
Quick Reference Card
发版流程 = 验证 → 版本号 → 文档同步 → 构建 → 测试 → npm发布 → Git推送 → 验证镜像
文档同步必须更新：
✅ README.md 徽章版本号（第 2、8 行）
✅ README.md 标题版本号（第 11 行）
✅ README.en.md 徽章版本号（第 2、8 行）
✅ README.en.md 标题版本号（第 11 行）
✅ package.json description
✅ 更新日志新增版本说明
门禁：
🚫 测试未全部通过 → 禁止发布
🚫 文档版本号不一致 → 禁止发布
Notes
npm 包的 README 不会自动同步 GitHub：发布时打包的 README 是静态的，需要重新发布才能更新 npmjs 上的文档。
npmmirror 自动同步：无需手动推送，约 10 分钟自动同步。
双仓库推送：Gitee（origin）和 GitHub（github）都需要推送。