@epxing/cli

@epxing/cli

独立的工程开发工具，包含交互菜单、开发服务、工程与产品库构建、创建、Vue3 迁移、静态检查和升级技能安装。CLI 使用自己的版本号，目标平台由 --epx-frame 指定；发布包没有 npm 运行时依赖。启动、构建调用当前工程的脚本及本地依赖；迁移代码与框架仓库的 tools/ 共用，打包时编译为独立 Node 程序。

npm install -g @epxing/cli@0.4.0 --registry https://registry.npmjs.org/
epxing                             # ↑↓ + Enter 选择；Esc / Ctrl+C 取消
epxing dev --port 3000
epxing build --mode prd
epxing lib                         # 产品默认懒加载；平台目录构建完整聚合组件库
epxing lib --full                  # 产品完整打包
epxing lib --lazy                  # 显式选择懒加载，兼容已有命令
epxing create my-product --epx-frame <目标平台版本>
epxing migrate E:/products/old-product --epx-frame <目标平台版本>
epxing migrate E:/products/old-product --epx-frame <目标平台版本> --apply
epxing skill install --dir E:/products/my-product

从 0.4.0 起终端命令改为 epxing，不再注册 epx，因此可与旧 epx-frame CLI 的 epx 共存。包名仍是 @epxing/cli，产品依赖仍是 epx-frame。更新同一个全局 CLI 包时 npm 会替换其旧命令；不要使用 --force 覆盖其他包的命令。工具不在安装阶段运行迁移、下载平台或改产品文件；产品仍需安装目标框架依赖才能开发和构建。

使用 fnm/nvm 时，不同 Node 版本的全局包分别安装。切换到日常使用的 Node 版本后更新 CLI，再用 epxing help 确认开头为 @epxing/cli、epxing --version 确认版本。旧仓库的 pnpm epx 仍是该仓库自己的脚本。

命令

工程命令支持 --dir <目录>，默认从当前目录向上找到最近的 package.json；不会改为 CLI 全局安装目录。没有项目脚本时，dev/build/preview 可使用项目已安装的 Vite，不会自动下载构建工具。工程仍需先安装自身依赖。

产品懒加载构建需要 Vite 库配置（build.lib）、Vue 3 编译器和入口中的 import.meta.glob('./产品目录/**/*.vue', { eager: true })。CLI 使用产品本地 Vite 加载原配置；未接入按需插件时通过临时配置补入共享插件，不修改产品源码或原配置。已有按需插件保留其 eager 等自定义设置。构建后验证本次生成的 index.manifest.json、组件 chunks 和 index.full.js，缺少或沿用旧产物会报错，避免完整包被误判为懒加载成功。部署时上传整个输出目录（包含 CSS、chunks 和兜底包）。--full 会关闭按需插件；--full 与 --lazy 互斥。旧 webpack 产品先迁移到 Vite，或使用 --full 完整打包。自定义非 Vite 脚本须自行生成标准 lib/ 按需产物。直接执行 npm run build:lib 仍由产品原脚本决定构建方式。

0.3.1 同时支持 { eager: true, import: 'default' } 的直接组件入口写法。未显式设置 assetsInlineLimit 时，组件拆分保持 Vite 库模式的默认资源内联行为，避免图片改成平台根路径引用。

--mode/-m、--port/-p 支持旧的 -mprd、-p3000 写法。build 优先匹配 build:<mode>；localize 也匹配 build:local，其余情况向构建脚本传入 --mode。平台 build:component 包含多步构建，不追加 --mode，环境由工程脚本统一配置。

平台 epxing build 保留 --thin、--no-designer、--no-dashboard；产品工程不接受平台裁剪选项。需向工程脚本透传其他参数时使用 --，如 epxing dev -- --host 0.0.0.0。脚本原有的 pre/post 生命周期、自定义环境和多步构建会保留，失败退出码向上传递。

create 和 migrate --apply 自动写入 runtime: "vue3"。带参数直接调用时 --epx-frame 必填，交互引导也会要求输入目标平台。迁移默认预览；apply 要求目标 Git 工作树干净。实际执行 .vue 转换时才按需安装并缓存 gogocode。标识表示迁移目标，仍需完成转换、构建和业务复测。

0.4.0 的迁移会同步适配平台主题：常见静态字号（12/14/16/20px）、圆角（2/4/8px，包括多角简写）和明确的语义颜色改为平台 CSS 变量，保留原值兜底。覆盖 Vue 样式块、template/JSX/render 内联样式和 src 中的 CSS/SCSS/Less；不改 scoped，不导入全局主题，不改圆形、胶囊、图标、打印及动画中的固定设计。动态样式、特殊字号/圆角、缩进式 Sass/Stylus 等列入复核清单，需按技能 E2 继续分析。返回码 2 表示有待复核项；不代表自动修复没有写入。已有 Vue3 工程可运行 epxing theme <目录> 预览，审查后加 --apply；无须重跑依赖迁移。最终产物须验证平台字号、圆角、明暗与密度切换、懒加载和样式隔离。

epxing scan <目录> 扫描静态风险，epxing verify <目录> --online <地址|文件> 对照组件清单。技能安装到 .claude/skills/epxing-frontend-vue3-migrate/，可用 --skills-dir 指定其他客户端要求的位置。已有技能默认不覆盖；确认替换使用 --force。平台基类源码分析仍需准备对应版本源码或文档。

在框架源码仓库发布工具，不需要构建平台 lib/：

cd frontend/frame/packages/cli
npm login --registry https://registry.npmjs.org/
# 发布前调整为未发布过的新版本
# npm version <新的CLI版本> --no-git-tag-version
$previousPublicPublish = $env:EPX_PUBLISH_PUBLIC
try {
  $env:EPX_PUBLISH_PUBLIC = '1'
  npm publish --access public --registry https://registry.npmjs.org/
} finally {
  $env:EPX_PUBLISH_PUBLIC = $previousPublicPublish
}

发布账号需要拥有 @epxing 名称空间的发布权限，并完成 npm 要求的发布身份验证。publishConfig 固定公开发布到 npm 公网；上面的命令仅为这次操作启用共享守卫的显式公开发布开关，并在结束后恢复原值。prepack 自动构建工具并带入当前技能文件。可在框架根执行 pnpm build:cli，或在这里运行 npm pack 生成可独立安装的 tgz。技能与 CLI 同版本交付，平台升级不要求工具同步发版；工具规则、模板或技能更新时才发布新 CLI。新平台若改变接口或构建约定，仍需验证并更新相应工具规则。

在框架根运行 npm --prefix packages/cli test，验证真实 tgz 的离线安装、无平台依赖运行、创建、迁移、扫描和技能安装。

首次发布前，需创建或加入 npm 的 epxing 组织。可用 npm org ls epxing --json --registry https://registry.npmjs.org/ 核对组织角色。若发布返回 403 Two-factor authentication or granular access token with bypass 2fa enabled is required，表示当前发布凭据未满足 npm 要求；仅 npm whoami 成功不代表可以发布。可在 npm 网站创建具有目标 scope 发布权限、启用 Bypass 2FA 的细粒度令牌，并配置到本机用户 npm 设置；令牌不写入项目或发布包。参见 npm 发布身份验证要求。

令牌的 Packages and scopes 权限应选择 Read and write (publish and stage)，范围覆盖 @epxing；Read and write (stage only) 无法直接发布。Organizations 里的读写权限只管理组织、团队和成员，不授予组织包的发布权限。首次创建包时需覆盖相应 scope。参见 npm 令牌权限说明。