@epxing/cli

完整公开 API、导入方式与示例

独立的工程开发工具，包含交互菜单、开发服务、产品库构建、创建、Vue3 迁移、静态检查和升级技能安装。创建和升级默认使用 @epxing/* 独立包，版本留空选择 npm 最新已发布版本（包含 beta），允许跨旧大版本；默认依赖始终使用 major-N 标签，标签未同步时报错而不回退固定版本。可用 --packages-version 指定版本或标签。创建成功和 upgrade --apply 后自动安装并刷新平台依赖与锁文件，--no-install 可跳过；预览不安装。CLI 使用自己的版本号；@epxing/cli/vite 提供产品构建插件，不依赖聚合包中的构建工具。

仓库旧 pnpm epx create/migrate/upgrade 默认转交独立 CLI，不再隐式注入 epx-frame；安装环境找不到独立 CLI 时明确提示安装，不回退旧聚合模式。只有显式 --epx-frame 保留聚合包。迁移阻塞返回失败状态，不安装旧包，需先处理迁移报告；实际页面和懒加载仍需构建及浏览器验收。

当前正式版本：@epxing/[email protected]，CLI 使用 npm 公网 latest 标签，平台依赖默认使用对应 major-N 标签。CLI 与平台独立版本。完整流程见文档站“CLI 创建、升级与产品使用”；各包公开 API 随安装包的 API.md 提供。

0.6.0 将已验证的独立包迁移、动态大版本依赖、自动安装及浏览器验收技能作为正式版本发布。默认安装命令使用 latest；平台包仍可按原规则选择同一大版本的最新 beta，不与 CLI 的发布通道混淆。

0.5.0-beta.18 默认选择最新已发布平台版本（含 beta），依赖保持 major-N 标签，标签未同步时不退回固定版本。创建成功和升级应用后自动安装／刷新平台依赖及锁文件，预览只读，--no-install 可跳过安装。默认迁移到独立包，仍残留 epx-frame 时不误报完成；随包技能补充全量组件分组、浏览器实测及链接／截图验收要求。

0.5.0-beta.17 强化选择框宽度迁移 F20：AI 先核对本产品同类选择框范围与宽度来源，缺少有效宽度且无其它布局要求时，在产品专属容器内补 202px。AST 扫描增加宽度候选，保留已有 CSS、变量和明确的撑满布局；禁止全局覆盖 .el-select。扫描本身只读，不自动批量改业务源码。

0.5.0-beta.16 扩展随升级技能安装的 AST 扫描，检查 Element Button、Checkbox／Radio 和 Pagination 的高频弃用及旧协议；覆盖模板、JSX 和部分 h/createVNode 调用。技能要求执行扫描，动态配置继续追踪，扫描不自动修改业务源码；尚未接入 CLI migrate 自动调用链。

0.5.0-beta.15 创建与升级默认将平台依赖写为 major-N（如 major-6），跟随该大版本最新公开版本，包含 beta。已有独立包升级保持当前大版本；显式 --packages-version 仍可固定数字版本。lockfile 锁定实际安装版本，刷新依赖使用 npm update。八个平台包的发布流程维护各自的大版本标签。

0.5.0-beta.14 强化 F28 表单上下文透传检查：沿发送端、继承／包装组件、懒加载页签和原生根核对 form prop，补齐逐页签验收与宿主制品核对；保留 class/style、事件和上下文，不自动批量添加 prop 或关闭 attrs 继承。

0.5.0-beta.13 根据考核迁移报告补充插槽作用域、响应式状态、树刷新、异步依赖与移动布局复核。列表只读扫描新增同层插槽参数条件检测，覆盖解构、别名和局部变量遮蔽；模板解析失败非零退出，不自动改写业务条件。新增 F32–F34，明确历史报告对账和未定位问题的验收边界。

0.5.0-beta.12 合并考核升级经验，随技能交付跨产品复核清单及列表插槽、拖拽、图标三个只读扫描脚本。模型与样式按组件复核，覆盖模板、JSX/render、包装与继承链；扫描零命中不能替代未覆盖场景验收。CLI 更新不会覆盖已有产品技能，更新前须比较并保留自定义内容；新建目录可运行 epxing skill install 安装完整技能。

0.5.0-beta.11 将按需库的组件 CSS 放入对应 JS，模块加载完成前同步注入，共享样式去重；index.css 保留空文件兼容已登记 URL，整库兜底自带全部样式。可视化、设计器和预览组件写入预取排除清单，实际使用仍正常加载。新平台选择性预取普通组件；旧平台由新壳关闭后台预取。全量构建仍使用原有整体 CSS。Vite 深层动态导入仍引用的 CSS 文件继续保留并随组件按需加载。

0.5.0-beta.10 关闭产品库构建的 public 目录复制，避免旧 cmaps 和 index.html 混入 lib。创建模板、已有库配置迁移及 CLI 库构建保持一致；应用构建和源 public 文件保留。动态或展开的库配置仍报告人工核对。修复直接执行 npm 库构建时异步懒加载插件进入自身嵌套构建的问题。

0.5.0-beta.9 补齐已有标准库入口携带 --full 的迁移：升级后 build:lib 为 node build-lib.mjs，全量构建保留在 build:lib:full。预览不改文件，自定义构建命令和自定义入口文件继续保留并报告待接入。

0.5.0-beta.8 修复 Node 命令行扫描 HTML 实体时的 document is not defined：迁移、日期与主题扫描使用 Node 版 Vue 解析器，保留模板中的实体与原格式。旧版本遇到该问题时更新 CLI 后重新执行预览，不删除实体或添加假的 document。

0.5.0-beta.7 合并薪酬升级中的对象回显、必填校验和 ID 序列化注意事项，随技能交付参数路径修复脚本。创建与升级的标准工程默认懒加载，使用 npm run build:lib --full 或 npm run build:lib:full 全量构建。epxing skill install 安装该版本技能；已有技能默认受到保护，更新前先比较并保留产品自定义内容。保留主题及全局 CSS 变量逐组件验收与跨会话缺陷回归要求。

创建和升级会在可识别的独立包应用入口中预留默认注释的 import { installLegacyFrame } from '@epxing/core' 与 installLegacyFrame(app)。仅在需要加载依赖 window.frame 的旧远程库时手动取消两处注释，要求 core 5.3.0-beta.5 或以上版本；调用放在所需组件包安装后、远程库加载前。升级保留产品自定义代码及已经启用的调用，重复升级不重复添加提示。

平台包从 5.3.0-beta.2 起自动加载自身样式，产品无需手动引入各包的 style.css。创建和迁移使用此版本时，CLI 不再添加这些导入；指定旧版本时仍保留显式样式以兼容旧包。标签会先解析成具体版本再选择模板。已有显式导入可以保留，产品覆盖样式放在框架导入之后。

npm install -g @epxing/cli --registry https://registry.npmjs.org/
epxing                             # ↑↓ + Enter 选择；Esc / Ctrl+C 取消
epxing dev --port 3000
epxing build --mode prd
epxing lib                         # 产品默认懒加载；平台目录构建完整聚合组件库
epxing lib --full                  # 产品完整打包
npm run build:lib                  # 新建或升级后的标准工程：默认懒加载
npm run build:lib --full          # 标准工程：显式全量（也可用 build:lib:full）
epxing lib --lazy                  # 显式选择懒加载，兼容已有命令
epxing create my-product
epxing migrate ./old-product
epxing migrate ./old-product --apply
epxing migrate ./old-product --transform-vue --to-vite --apply
# 指定固定版本时：epxing create my-product --packages-version 5.3.0-beta.2
epxing skill install --dir E:/products/my-product

从 0.4.0 起终端命令为 epxing，可与旧聚合 CLI 的 epx 共存。新产品直接依赖 @epxing/core、@epxing/components、@epxing/utils 等包。创建后进入目录安装依赖，再运行 npm run dev；默认端口 8080。工具安装阶段不会运行迁移或改产品文件。

新建产品的 src/main.js 使用 createApp({ router: createFrameRouter() })，安装 Components、Business 和产品插件，默认运行平台登录、菜单与系统首页。先在 .env.development.local 配置实际后端和应用参数。产品组件放入自动收集目录，src/index.js 仍是独立产品库入口，不包含本地应用启动代码。

从 0.5.0-beta.4 起，旧 CLI 生成的计数欢迎页在 main.js 与 App.vue 都保持原始模板时可由 upgrade 自动修复；自定义入口不覆盖。epxing scan 的 R4 提示尚未修复的原始欢迎页。升级技能区分 Vue2/webpack、Vue3 聚合包及已有独立包工程，报告补充平台启动验收。

组件校验 epxing verify 优先读取 lib 的清单或产物，无产物时按产品收集入口列源码候选，支持常规静态 glob 与 require.context；无法确定的动态规则要求先构建。源码候选不能代替产物及真实平台验收。

升级 CLI 后可用 epxing skill install --dir <产品目录> 安装新版升级技能。已有技能会受保护而退出；确认并保留产品自定义内容后，才使用 --force 替换。技能和命令随同一 CLI 版本交付。

--epx-frame <版本或spec> 仅用于显式选择旧聚合产品模式，与 --packages-version 互斥。普通命令与无参数交互引导均默认使用独立包，版本输入可直接回车。显式数字版本不查询网络；默认版本与标签需查询 npm，查询失败会退出，可通过固定版本离线生成。迁移遇到动态旧接口等无法确定的内容时返回 2，报告人工清单并保留原包模式；不会只切换一半导入。已有业务路由、store 和 install 注册代码保留；已有自定义 PRODUCT-GUIDE.md 会保留，另写 EPXING-PACKAGES-GUIDE.md。

// vite.config.mjs：由创建模板自动配置；远程库构建启用共享映射。
import { frameDeps, epxShared, lazyLib } from '@epxing/cli/vite'
import epxIcons from '@epxing/icons'
// plugins: [frameDeps(), epxShared(), lazyLib({ root, enabled, glob, pkgName })]

开发和独立应用直接使用 npm 包。远程库构建通过宿主共享 core、组件、工具和 Vue；宿主需要同版本包并完成组件组安装。epxing lib 默认按需构建，--full 完整构建；按需部署必须上传整个 lib/ 目录。npm run build:app 构建新模板的独立应用到 dist/。实体组件需要配置后端、元数据和权限。

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

命令

发布当前工程的 npm 包

epxing publish --dry-run          # 只读查看范围和新版本，不构建或发布
epxing publish                    # 正式版 patch，发布到 latest
epxing publish --stable           # 显式选择正式版，与默认相同
epxing publish --beta             # beta；已有 beta.N 时递增 N
epxing publish --minor            # 中版本，例如 1.2.3 → 1.3.0
epxing publish --major            # 大版本，例如 1.2.3 → 2.0.0
epxing publish --beta --minor     # 下一中版本的 beta.0
epxing publish --version 2.3.0    # 显式指定所有目标包的新版本
epxing publish --no-root --dir .  # 只发布 workspace 子包，不包含根包

默认小版本指 patch（1.2.3 → 1.2.4）。从 beta 转正式版时去掉预发布后缀，例如 1.2.4-beta.2 → 1.2.4。当前包与子包统一版本号：基于目标包中最高的当前版本递增；显式 --version 则指定目标版本，新版本必须高于各包当前版本。workspace 中的独立 CLI 子包 @epxing/cli 不参与联动修改或发布；如进入 CLI 自身目录运行，则只发布 CLI 自己。

范围由当前工程的 package.json workspaces 或 pnpm-workspace.yaml 的 packages 列表决定，包含根包，跳过 private 包；支持普通路径、*、** 及 ! 排除，不猜测未声明的子包。可用 --dir 指定工程、--no-root 排除根包。内部依赖更新到目标版本，workspace 简写保留在源码中，打包时转换成 npm 可安装的范围。

默认注册表为 npm 公网，可用 --registry <地址> 指定。命令保留项目原有 prepublishOnly/prepack 等脚本与发布守卫；本仓内部聚合包的公共发布仍要求显式设置 EPX_PUBLISH_PUBLIC=1，或用 --no-root 排除根包，不自动绕过守卫。先核对预览范围，再执行真实发布。

所有版本检查和 tarball 准备完成后，按依赖顺序发布；正式版使用 latest，beta 使用 beta，明确使用 public 访问级别。开始上传前失败会恢复原 package.json；上传开始后失败保留新版本和 .cache/epxing-publish/<批次>/release.json，记录已成功包，不自动重试或回滚远端。根据记录处理剩余包，避免整批重跑。成功后按项目包管理器刷新 lockfile，并提交版本变化；命令不自动修改 Git，不自动维护额外的 major-N 标签。首次发布或多包发布不是原子操作。

工程命令支持 --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"。省略版本默认选择最新独立包；--packages-version 可固定版本，--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 令牌权限说明。