@epxing/cli 0.5.0-beta.6 → 0.5.0-beta.8

package/API.md

@@ -2,13 +2,13 @@
 
 独立工程命令行工具，终端命令名为 epxing。/vite 提供产品构建插件，根入口不提供业务运行时。
 
-本页对应包版本 `0.5.0-beta.6`。导出名、子路径和签名从当前源码、package.json 与类型声明生成。
+本页对应包版本 `0.5.0-beta.8`。导出名、子路径和签名从当前源码、package.json 与类型声明生成。
 
 ## 安装与使用
 
 
 ```sh
-npm install -g @epxing/cli@0.5.0-beta.6
+npm install -g @epxing/cli@0.5.0-beta.8
 ```
 
 

package/README.md

@@ -1,111 +1,115 @@
-# @epxing/cli
-
-[完整公开 API、导入方式与示例](./API.md)
-
-独立的工程开发工具，包含交互菜单、开发服务、产品库构建、创建、Vue3 迁移、静态检查和升级技能安装。创建和升级默认使用 `@epxing/*` 独立包，版本留空时查询最新 `beta` 并固定到具体版本，没有 `beta` 时使用 `latest`；可用 `--packages-version` 指定版本或标签。CLI 使用自己的版本号。创建和升级会生成产品使用说明；`@epxing/cli/vite` 提供产品构建插件，不依赖聚合包中的构建工具。
-
-本批测试版本：`@epxing/cli@0.5.0-beta.6`，平台包 `5.3.0-beta.5`，均使用 npm 公网 `beta` 标签。CLI 与平台独立版本，本次不升级平台包。完整流程见文档站“CLI 创建、升级与产品使用”；各包公开 API 随安装包的 `API.md` 提供。
-
-`0.5.0-beta.6` 更新随包交付的产品升级技能：主题及全局 CSS 变量按用途逐组件接入，建立全量组件验收台账，并检查跨会话归纳的 16 类交互、布局、上下文及配置缺陷。`epxing skill install` 安装该版本技能；已有技能默认受到保护，更新前先比较并保留产品自定义内容。本次不新增自动批量修复规则。
-
-创建和升级会在可识别的独立包应用入口中预留默认注释的 `import { installLegacyFrame } from '@epxing/core'` 与 `installLegacyFrame(app)`。仅在需要加载依赖 `window.frame` 的旧远程库时手动取消两处注释，要求 core 5.3.0-beta.5 或以上版本；调用放在所需组件包安装后、远程库加载前。升级保留产品自定义代码及已经启用的调用，重复升级不重复添加提示。
-
-平台包从 `5.3.0-beta.2` 起自动加载自身样式，产品无需手动引入各包的 `style.css`。创建和迁移使用此版本时，CLI 不再添加这些导入；指定旧版本时仍保留显式样式以兼容旧包。标签会先解析成具体版本再选择模板。已有显式导入可以保留，产品覆盖样式放在框架导入之后。
-
-```powershell
-npm install -g @epxing/cli@beta --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
-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`。
-
-```js
-// 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` 仍是该仓库自己的脚本。
-
-## 命令
-
-| 命令 | 行为 |
-| --- | --- |
-| `epxing` / `epxing menu` | 交互选择操作、工程目录、环境、端口和构建方式；管道支持数字输入 |
-| `epxing dev` / `epxing serve` | 使用工程 `dev`、`serve` 或 `start` 脚本启动服务 |
-| `epxing build` | 使用工程的构建脚本；只有 `build:lib` 的产品自动构建产品库 |
-| `epxing lib` / `epxing build --lib` / `epxing lib --lazy` | 产品默认懒加载，优先 `build:lib:lazy`，否则使用 `build:lib` / `lib`；平台聚合库仍完整构建 |
-| `epxing lib --full` / `epxing build --lib --full` | 产品完整打包，明确设置 `LAZY_LIB=false`；兼容旧 `--target lib` 脚本 |
-| `epxing preview` | 使用 `preview` / `vite:preview`；没有脚本时使用工程本地 Vite |
-| `epxing create` | 无参数进入创建引导，也可用参数直接创建 |
-| `epxing migrate` / `epxing upgrade` | 无参数引导：目标版本、迁移范围、预览、确认应用 |
-| `epxing skill install` | 安装技能，支持自定义目录和明确覆盖 |
-| `epxing scan` / `epxing verify` | 迁移风险扫描 / 本地与线上组件清单校验 |
-| `epxing theme [目录] [--apply]` | 补修产品/项目主题样式，默认只读预览；迁移时自动执行 |
-| `epxing lint [--fix]` / `epxing circular` | 执行工程已有的代码检查、循环依赖检查脚本 |
-| `epxing remote` / `epxing pkg <包名\|all>` | 使用平台已有 `build:remote` / `build:pkg` / `build:pkgs` 脚本 |
-| `epxing help` / `epxing --version` | 帮助 / 工具版本 |
-
-工程命令支持 `--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/`：
-
-```powershell
-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 发布身份验证要求](https://docs.npmjs.com/requiring-2fa-for-package-publishing-and-settings-modification/)。
-
-令牌的 `Packages and scopes` 权限应选择 `Read and write (publish and stage)`，范围覆盖 `@epxing`；`Read and write (stage only)` 无法直接发布。`Organizations` 里的读写权限只管理组织、团队和成员，不授予组织包的发布权限。首次创建包时需覆盖相应 scope。参见 [npm 令牌权限说明](https://docs.npmjs.com/creating-and-viewing-access-tokens/)。
+# @epxing/cli
+
+[完整公开 API、导入方式与示例](./API.md)
+
+独立的工程开发工具，包含交互菜单、开发服务、产品库构建、创建、Vue3 迁移、静态检查和升级技能安装。创建和升级默认使用 `@epxing/*` 独立包，版本留空时查询最新 `beta` 并固定到具体版本，没有 `beta` 时使用 `latest`；可用 `--packages-version` 指定版本或标签。CLI 使用自己的版本号。创建和升级会生成产品使用说明；`@epxing/cli/vite` 提供产品构建插件，不依赖聚合包中的构建工具。
+
+本批测试版本：`@epxing/cli@0.5.0-beta.8`，平台包 `5.3.0-beta.5`，均使用 npm 公网 `beta` 标签。CLI 与平台独立版本，本次不升级平台包。完整流程见文档站“CLI 创建、升级与产品使用”；各包公开 API 随安装包的 `API.md` 提供。
+
+`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 不再添加这些导入；指定旧版本时仍保留显式样式以兼容旧包。标签会先解析成具体版本再选择模板。已有显式导入可以保留，产品覆盖样式放在框架导入之后。
+
+```powershell
+npm install -g @epxing/cli@beta --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`。
+
+```js
+// 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` 仍是该仓库自己的脚本。
+
+## 命令
+
+| 命令 | 行为 |
+| --- | --- |
+| `epxing` / `epxing menu` | 交互选择操作、工程目录、环境、端口和构建方式；管道支持数字输入 |
+| `epxing dev` / `epxing serve` | 使用工程 `dev`、`serve` 或 `start` 脚本启动服务 |
+| `epxing build` | 使用工程的构建脚本；只有 `build:lib` 的产品自动构建产品库 |
+| `epxing lib` / `epxing build --lib` / `epxing lib --lazy` | 产品默认懒加载，优先 `build:lib:lazy`，否则使用 `build:lib` / `lib`；平台聚合库仍完整构建 |
+| `epxing lib --full` / `epxing build --lib --full` | 产品完整打包，明确设置 `LAZY_LIB=false`；兼容旧 `--target lib` 脚本 |
+| `epxing preview` | 使用 `preview` / `vite:preview`；没有脚本时使用工程本地 Vite |
+| `epxing create` | 无参数进入创建引导，也可用参数直接创建 |
+| `epxing migrate` / `epxing upgrade` | 无参数引导：目标版本、迁移范围、预览、确认应用 |
+| `epxing skill install` | 安装技能，支持自定义目录和明确覆盖 |
+| `epxing scan` / `epxing verify` | 迁移风险扫描 / 本地与线上组件清单校验 |
+| `epxing theme [目录] [--apply]` | 补修产品/项目主题样式，默认只读预览；迁移时自动执行 |
+| `epxing lint [--fix]` / `epxing circular` | 执行工程已有的代码检查、循环依赖检查脚本 |
+| `epxing remote` / `epxing pkg <包名\|all>` | 使用平台已有 `build:remote` / `build:pkg` / `build:pkgs` 脚本 |
+| `epxing help` / `epxing --version` | 帮助 / 工具版本 |
+
+工程命令支持 `--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/`：
+
+```powershell
+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 发布身份验证要求](https://docs.npmjs.com/requiring-2fa-for-package-publishing-and-settings-modification/)。
+
+令牌的 `Packages and scopes` 权限应选择 `Read and write (publish and stage)`，范围覆盖 `@epxing`；`Read and write (stage only)` 无法直接发布。`Organizations` 里的读写权限只管理组织、团队和成员，不授予组织包的发布权限。首次创建包时需覆盖相应 scope。参见 [npm 令牌权限说明](https://docs.npmjs.com/creating-and-viewing-access-tokens/)。

package/dist/cli.mjs

@@ -48,14 +48,17 @@ function installSkill (args, cwd) {
   const unknown = args.filter(arg => arg !== '--force')
   if (unknown.length) throw new Error(`不支持的参数：${unknown.join(' ')}`)
   const dest = path.join(custom ? path.resolve(dir, custom) : path.join(dir, '.claude/skills'), skillName)
-  const files = ['SKILL.md', 'pitfalls.md']
+  const files = ['SKILL.md', 'pitfalls.md', 'scripts/fix-eval-paths.cjs']
   if (!force && files.some(file => fs.existsSync(path.join(dest, file)))) {
     throw new Error(`技能已存在：${dest}。如需替换，核对自定义内容后使用 --force。`)
   }
   // 先读齐资源，再写入，避免缺少发布资源时只安装一半。
   const contents = files.map(file => fs.readFileSync(path.join(payload, 'skills', skillName, file)))
   fs.mkdirSync(dest, { recursive: true })
-  files.forEach((file, index) => fs.writeFileSync(path.join(dest, file), contents[index]))
+  files.forEach((file, index) => {
+    fs.mkdirSync(path.dirname(path.join(dest, file)), { recursive: true })
+    fs.writeFileSync(path.join(dest, file), contents[index])
+  })
   console.log(`✓ 已安装技能：${dest}`)
   return 0
 }