@epxing/cli 0.3.1 → 0.4.0

package/README.md

@@ -3,40 +3,41 @@
 独立的工程开发工具，包含交互菜单、开发服务、工程与产品库构建、创建、Vue3 迁移、静态检查和升级技能安装。CLI 使用自己的版本号，目标平台由 `--epx-frame` 指定；发布包没有 npm 运行时依赖。启动、构建调用当前工程的脚本及本地依赖；迁移代码与框架仓库的 `tools/` 共用，打包时编译为独立 Node 程序。
 
 ```powershell
-npm install -g @epxing/cli@0.3.1 --registry https://registry.npmjs.org/
-epx                             # ↑↓ + Enter 选择；Esc / Ctrl+C 取消
-epx dev --port 3000
-epx build --mode prd
-epx lib                         # 产品默认懒加载；平台目录构建完整聚合组件库
-epx lib --full                  # 产品完整打包
-epx lib --lazy                  # 显式选择懒加载，兼容已有命令
-epx create my-product --epx-frame <目标平台版本>
-epx migrate E:/products/old-product --epx-frame <目标平台版本>
-epx migrate E:/products/old-product --epx-frame <目标平台版本> --apply
-epx skill install --dir E:/products/my-product
+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
 ```
 
-如已全局安装旧的 `epx-frame` CLI，先用 `npm uninstall -g epx-frame` 释放 `epx` 命令。产品工程里的 `epx-frame` 依赖保留。工具不在安装阶段运行迁移、下载平台或改产品文件；产品仍需安装目标框架依赖才能开发和构建。
+从 0.4.0 起终端命令改为 `epxing`，不再注册 `epx`，因此可与旧 `epx-frame` CLI 的 `epx` 共存。包名仍是 `@epxing/cli`，产品依赖仍是 `epx-frame`。更新同一个全局 CLI 包时 npm 会替换其旧命令；不要使用 `--force` 覆盖其他包的命令。工具不在安装阶段运行迁移、下载平台或改产品文件；产品仍需安装目标框架依赖才能开发和构建。
 
-使用 fnm/nvm 时，不同 Node 版本的全局包分别安装。切换到日常使用的 Node 版本后更新 CLI，再用 `epx help` 确认开头为 `@epxing/cli`、`epx --version` 确认版本。旧仓库的 `pnpm epx` 仍是该仓库自己的脚本。
+使用 fnm/nvm 时，不同 Node 版本的全局包分别安装。切换到日常使用的 Node 版本后更新 CLI，再用 `epxing help` 确认开头为 `@epxing/cli`、`epxing --version` 确认版本。旧仓库的 `pnpm epx` 仍是该仓库自己的脚本。
 
 ## 命令
 
 | 命令 | 行为 |
 | --- | --- |
-| `epx` / `epx menu` | 交互选择操作、工程目录、环境、端口和构建方式；管道支持数字输入 |
-| `epx dev` / `epx serve` | 使用工程 `dev`、`serve` 或 `start` 脚本启动服务 |
-| `epx build` | 使用工程的构建脚本；只有 `build:lib` 的产品自动构建产品库 |
-| `epx lib` / `epx build --lib` / `epx lib --lazy` | 产品默认懒加载，优先 `build:lib:lazy`，否则使用 `build:lib` / `lib`；平台聚合库仍完整构建 |
-| `epx lib --full` / `epx build --lib --full` | 产品完整打包，明确设置 `LAZY_LIB=false`；兼容旧 `--target lib` 脚本 |
-| `epx preview` | 使用 `preview` / `vite:preview`；没有脚本时使用工程本地 Vite |
-| `epx create` | 无参数进入创建引导，也可用参数直接创建 |
-| `epx migrate` / `epx upgrade` | 无参数引导：目标版本、迁移范围、预览、确认应用 |
-| `epx skill install` | 安装技能，支持自定义目录和明确覆盖 |
-| `epx scan` / `epx verify` | 迁移风险扫描 / 本地与线上组件清单校验 |
-| `epx lint [--fix]` / `epx circular` | 执行工程已有的代码检查、循环依赖检查脚本 |
-| `epx remote` / `epx pkg <包名\|all>` | 使用平台已有 `build:remote` / `build:pkg` / `build:pkgs` 脚本 |
-| `epx help` / `epx --version` | 帮助 / 工具版本 |
+| `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，不会自动下载构建工具。工程仍需先安装自身依赖。
 
@@ -46,11 +47,13 @@ epx skill install --dir E:/products/my-product
 
 `--mode/-m`、`--port/-p` 支持旧的 `-mprd`、`-p3000` 写法。build 优先匹配 `build:<mode>`；`localize` 也匹配 `build:local`，其余情况向构建脚本传入 `--mode`。平台 `build:component` 包含多步构建，不追加 `--mode`，环境由工程脚本统一配置。
 
-平台 `epx build` 保留 `--thin`、`--no-designer`、`--no-dashboard`；产品工程不接受平台裁剪选项。需向工程脚本透传其他参数时使用 `--`，如 `epx dev -- --host 0.0.0.0`。脚本原有的 pre/post 生命周期、自定义环境和多步构建会保留，失败退出码向上传递。
+平台 `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。标识表示迁移目标，仍需完成转换、构建和业务复测。
 
-`epx scan <目录>` 扫描静态风险，`epx verify <目录> --online <地址|文件>` 对照组件清单。技能安装到 `.claude/skills/epxing-frontend-vue3-migrate/`，可用 `--skills-dir` 指定其他客户端要求的位置。已有技能默认不覆盖；确认替换使用 `--force`。平台基类源码分析仍需准备对应版本源码或文档。
+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/`：
 

package/dist/THIRD_PARTY_NOTICES.txt

@@ -19,3 +19,28 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
+
+
+@vue/compiler-dom
+
+The MIT License (MIT)
+
+Copyright (c) 2018-present, Yuxi (Evan) You
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/dist/cli.mjs

@@ -112,7 +112,7 @@ async function interactive (cwd, action) {
     }
     if (action === 'check') {
       action = await prompts.select('检查类型', choices([
-        ['源码迁移风险扫描', 'scan'], ['本地 / 线上组件清单核对', 'verify'], ['项目代码检查', 'lint'], ['项目循环依赖检查', 'circular']
+        ['源码迁移风险扫描', 'scan'], ['本地 / 线上组件清单核对', 'verify'], ['项目代码检查', 'lint'], ['项目循环依赖检查', 'circular'], ['产品主题适配（预览）', 'theme']
       ]))
     }
     if (action === 'advanced') {
@@ -121,7 +121,7 @@ async function interactive (cwd, action) {
       ]))
     }
     const dir = await prompts.required('工程目录', '.')
-    if (action === 'scan' || action === 'verify') {
+    if (['scan', 'verify', 'theme'].includes(action)) {
       const online = action === 'verify' ? await prompts.text('线上 JS 地址或文件（留空仅列本地组件）') : ''
       return dispatch([action, dir, ...(online ? ['--online', online] : [])])
     }
@@ -167,22 +167,23 @@ export async function main (argv = process.argv.slice(2), cwd = process.env.INIT
   if (['help', '--help', '-h'].includes(command)) {
     console.log(`@epxing/cli · 工程开发与升级工具（独立于平台版本）
 
-  epx / epx menu             交互菜单（↑↓ + Enter；管道支持数字输入）
-  epx dev [-m <模式>] [-p <端口>] [--dir <工程目录>]
-  epx build [-m <模式>] [--thin] [--no-designer] [--no-dashboard] [--dir <目录>]
-  epx lib [--full | --lazy] [-m <模式>] [--dir <目录>]  产品默认懒加载，--full 完整打包；平台聚合库保持完整
-  epx build --lib            同 epx lib
-  epx preview [-p <端口>] [--dir <目录>]
-  epx create <名称|路径> --epx-frame <目标版本> [--dir <目录>]
-  epx migrate [项目目录] --epx-frame <目标版本> [--apply] [--transform-vue] [--to-vite]
-  epx scan [项目目录]
-  epx verify [项目目录] [--online <线上JS地址|文件>]
-  epx skill install [--dir <项目目录>] [--skills-dir <技能目录>] [--force]
-  epx lint [--fix] [--dir <目录>]
-  epx circular [--dir <目录>]
-  epx remote [--dir <平台目录>]
-  epx pkg <包名|all> [--dir <平台目录>]
-  epx --version
+  epxing / epxing menu             交互菜单（↑↓ + Enter；管道支持数字输入）
+  epxing dev [-m <模式>] [-p <端口>] [--dir <工程目录>]
+  epxing build [-m <模式>] [--thin] [--no-designer] [--no-dashboard] [--dir <目录>]
+  epxing lib [--full | --lazy] [-m <模式>] [--dir <目录>]  产品默认懒加载，--full 完整打包；平台聚合库保持完整
+  epxing build --lib            同 epxing lib
+  epxing preview [-p <端口>] [--dir <目录>]
+  epxing create <名称|路径> --epx-frame <目标版本> [--dir <目录>]
+  epxing migrate [项目目录] --epx-frame <目标版本> [--apply] [--transform-vue] [--to-vite]
+  epxing scan [项目目录]
+  epxing theme [项目目录] [--apply]  主题变量补修，默认只读；迁移时自动执行
+  epxing verify [项目目录] [--online <线上JS地址|文件>]
+  epxing skill install [--dir <项目目录>] [--skills-dir <技能目录>] [--force]
+  epxing lint [--fix] [--dir <目录>]
+  epxing circular [--dir <目录>]
+  epxing remote [--dir <平台目录>]
+  epxing pkg <包名|all> [--dir <平台目录>]
+  epxing --version
 
 dev / build / lib 等执行当前工程的 package.json 脚本，使用工程本地依赖。
 工程命令可用 -- 后的参数透传给脚本；serve / upgrade 分别是 dev / migrate 的别名。
@@ -196,14 +197,14 @@ create、migrate 不带参数时进入引导；直接带参数时 --epx-frame
     return 0
   }
   if (command === 'skill') {
-    if (args.shift() !== 'install') throw new Error('用法：epx skill install [--dir <项目目录>]')
+    if (args.shift() !== 'install') throw new Error('用法：epxing skill install [--dir <项目目录>]')
     return installSkill(args, cwd)
   }
   if (command === 'create') {
     const target = requireTarget(args)
     const chosenDir = takeOption(args, '--dir')
     const nameOrPath = args.shift()
-    if (!nameOrPath || args.length || nameOrPath.startsWith('-')) throw new Error('用法：epx create <名称|路径> --epx-frame <目标版本> [--dir <目录>]')
+    if (!nameOrPath || args.length || nameOrPath.startsWith('-')) throw new Error('用法：epxing create <名称|路径> --epx-frame <目标版本> [--dir <目录>]')
     const dir = path.resolve(cwd, chosenDir || nameOrPath)
     const name = /[\\/]/.test(nameOrPath) ? path.basename(path.resolve(cwd, nameOrPath)) : nameOrPath
     const { scaffold } = await import(pathToFileURL(path.join(payload, 'tools/epx-create/scaffold.mjs')).href)
@@ -217,13 +218,19 @@ create、migrate 不带参数时进入引导；直接带参数时 --epx-frame
     const dir = dirs[0] || '.'
     return runTool('epx-migrate/migrate.mjs', [path.resolve(cwd, dir), ...args.filter(arg => arg !== dir), '--epx-frame', target], cwd)
   }
+  if (command === 'theme') {
+    const apply = args.includes('--apply')
+    args = args.filter(arg => arg !== '--apply')
+    if (args.length > 1 || args.some(arg => arg.startsWith('-'))) throw new Error('用法：epxing theme [项目目录] [--apply]')
+    return runTool('epx-migrate/fix-theme-styles.mjs', [path.resolve(cwd, args[0] || '.'), ...(apply ? ['--apply'] : [])], cwd)
+  }
   if (command === 'scan' || command === 'verify') {
     const online = command === 'verify' ? takeOption(args, '--online') : null
-    if (args.length > 1 || args.some(arg => arg.startsWith('-'))) throw new Error(`用法：epx ${command} [项目目录]${command === 'verify' ? ' [--online <地址|文件>]' : ''}`)
+    if (args.length > 1 || args.some(arg => arg.startsWith('-'))) throw new Error(`用法：epxing ${command} [项目目录]${command === 'verify' ? ' [--online <地址|文件>]' : ''}`)
     const script = command === 'scan' ? 'detect-vue3-risks.mjs' : 'verify-components.mjs'
     return runTool('epx-migrate/' + script, [path.resolve(cwd, args[0] || '.'), ...(online ? ['--online', online] : [])], cwd)
   }
-  throw new Error(`未知命令：${command}，运行 epx help 查看用法。`)
+  throw new Error(`未知命令：${command}，运行 epxing help 查看用法。`)
 }
 
 let isMain = false

package/dist/lib-build.mjs

@@ -38,7 +38,7 @@ function configInScript (script) {
 function verifyLazy (outDir, previousStamp) {
   const file = path.join(outDir, 'index.manifest.json')
   if (!fs.existsSync(file) || manifestStamp(outDir) === previousStamp || !fs.existsSync(path.join(outDir, 'index.full.js'))) {
-    throw new Error('没有生成新的按需库清单和完整兜底包，不能视为懒加载构建成功。请检查构建脚本或使用 epx lib --full。')
+    throw new Error('没有生成新的按需库清单和完整兜底包，不能视为懒加载构建成功。请检查构建脚本或使用 epxing lib --full。')
   }
   const manifest = JSON.parse(fs.readFileSync(file, 'utf8'))
   const entries = Object.entries(manifest.components || {})

package/dist/lib-vite-config.mjs

@@ -37,7 +37,7 @@ export async function configureLibrary (env, options) {
       if (!file) throw new Error('无法确定产品库入口 build.lib.entry')
       const source = fs.readFileSync(path.resolve(root, file), 'utf8')
       const match = /import\.meta\.glob\(\s*(['"])([^'"]+)\1\s*,\s*\{\s*(?:import\s*:\s*['"]default['"]\s*,\s*)?eager\s*:\s*true\s*(?:,\s*import\s*:\s*['"]default['"]\s*)?,?\s*\}\s*\)/.exec(source)
-      if (!match) throw new Error('按需库需要入口中的 eager import.meta.glob；请先迁移产品入口，或使用 epx lib --full。')
+      if (!match) throw new Error('按需库需要入口中的 eager import.meta.glob；请先迁移产品入口，或使用 epxing lib --full。')
       config.plugins.push(lazyLib({ enabled: true, glob: match[2], pkgName }))
     }
   }

package/dist/project.mjs

@@ -34,7 +34,7 @@ function npmEntry () {
     } catch (error) { /* 继续查找 */ }
   }
   const found = candidates.find(file => file && fs.existsSync(file))
-  if (!found) throw new Error('未找到 npm-cli.js。请使用带 npm 的 Node.js 环境运行 epx。')
+  if (!found) throw new Error('未找到 npm-cli.js。请使用带 npm 的 Node.js 环境运行 epxing。')
   return found
 }
 
@@ -114,7 +114,7 @@ export function projectPlan (command, options, project) {
   let libraryMode
   const platform = project.pkg.name === 'epx-frame' || !!scripts['build:component']
   if (options.lib) {
-    if (command !== 'build') throw new Error('--lib 用于 epx build；也可直接使用 epx lib')
+    if (command !== 'build') throw new Error('--lib 用于 epxing build；也可直接使用 epxing lib')
     command = 'lib'
   }
   if (command === 'build' && !scripts.build && scripts['build:lib']) command = 'lib'
@@ -124,7 +124,7 @@ export function projectPlan (command, options, project) {
   if (options.port && !['dev', 'preview'].includes(command)) throw new Error('--port 仅用于 dev 或 preview')
   if (options.lazy && command !== 'lib') throw new Error('--lazy 仅用于 lib 或 build --lib')
   if (options.fix && command !== 'lint') throw new Error('--fix 仅用于 lint')
-  if ((options.thin || options.noDesigner || options.noDashboard) && (command !== 'build' || !platform)) throw new Error('平台裁剪选项仅用于平台源码中的 epx build')
+  if ((options.thin || options.noDesigner || options.noDashboard) && (command !== 'build' || !platform)) throw new Error('平台裁剪选项仅用于平台源码中的 epxing build')
   if (options.mode && !['dev', 'build', 'lib', 'preview'].includes(command)) throw new Error('--mode 仅用于 dev、build、lib 或 preview')
   if (command === 'dev') {
     script = pick('dev', 'serve', 'start')
@@ -146,19 +146,19 @@ export function projectPlan (command, options, project) {
       env.LAZY_LIB = options.full ? 'false' : 'true'
       script = options.full ? pick('build:lib:full', 'build:lib', 'lib', 'build:lib:lazy') : pick('build:lib:lazy', 'build:lib', 'lib')
       if (!script && /--target(?:=|\s+)lib\b/.test(scripts.build || '')) {
-        if (!options.full) throw new Error('旧 webpack 产品请先迁移到 Vite，或使用 epx lib --full 完整打包')
+        if (!options.full) throw new Error('旧 webpack 产品请先迁移到 Vite，或使用 epxing lib --full 完整打包')
         script = 'build'
       }
     }
     if (!script) throw new Error('当前工程缺少库构建脚本。产品请提供 build:lib（按需库可用 build:lib:lazy），平台使用 build:component。')
-    if (script === 'build:component' && options.mode) throw new Error('平台聚合库包含多步构建，请在 build:component 中配置环境；epx lib 不向该聚合脚本追加 --mode。')
+    if (script === 'build:component' && options.mode) throw new Error('平台聚合库包含多步构建，请在 build:component 中配置环境；epxing lib 不向该聚合脚本追加 --mode。')
   } else if (command === 'preview') {
     script = pick('preview', 'vite:preview')
     if (!script) binary = 'vite'
   } else if (command === 'remote') script = pick('build:remote')
   else if (command === 'pkg') {
     const name = options.positional[0]
-    if (!name || !/^[a-z][a-z0-9-]*$/.test(name)) throw new Error('用法：epx pkg <包名|all> [--dir <平台目录>]')
+    if (!name || !/^[a-z][a-z0-9-]*$/.test(name)) throw new Error('用法：epxing pkg <包名|all> [--dir <平台目录>]')
     script = name === 'all' ? pick('build:pkgs') : pick('build:pkg')
     if (name !== 'all') env.PKG = name
   } else if (command === 'lint') {

package/dist/skills/epxing-frontend-vue3-migrate/SKILL.md

@@ -10,6 +10,8 @@ description: epx 产品/项目远程库 Vue2/webpack → Vue3/Vite 升级 + 按
 epx 的产品/项目远程库（`window.library.<pkg>`，由 `FM_SYSTEM_WEBPACK` 配 url、运行时加载）
 从 Vue2/webpack 迁到 Vue3/Vite，并可选切到「清单 + 组件按需加载」形态的完整流程与踩坑清单。
 
+独立 CLI 从 `@epxing/cli@0.4.0` 起使用 `epxing` 命令（包名不变，平台依赖仍为 `epx-frame`）。例如 `epxing migrate <产品目录> --epx-frame <目标版本> --apply`；同时执行日期格式和主题样式迁移。已升级工程可用 `epxing theme <目录> --apply` 单独补修。仓库原有 `pnpm epx` 是本地脚本，不等同于全局命令。
+
 **核心判断：这条链上的失败几乎全是静默的。** 构建绿、控制台干净、组件就是不出来。
 所以每一步都要有**判据**，别靠"看着没报错"。
 
@@ -41,7 +43,7 @@ epx 的产品/项目远程库（`window.library.<pkg>`，由 `FM_SYSTEM_WEBPACK`
 | ① 依赖迁移 | `MIGRATION-REPORT.md` 的人工清单**逐条看过**——里面写着的坑会真的咬人 |
 | ② .vue 转换 | `npx eslint src --ext .js,.jsx,.vue` 能跑（迁移会删掉 eslint 生态，先修工具链） |
 | ③ 切 Vite | `npm run build:lib` exit 0 **且** `lib/` 里有 `index.js`/`index.css`/`index.deps.json` |
-| ④ dev 壳 | 浏览器里 `#app.__vue_app__._context.components` 能数到你的组件个数；对自定义页、继承组件和多分支 render，核对实际根节点的样式命名空间及关键元素的 `getComputedStyle` |
+| ④ dev 壳 | 浏览器里 `#app.__vue_app__._context.components` 能数到你的组件个数；对自定义页、继承组件和多分支 render，核对实际 DOM 与 CSS 选择器是否匹配。样式隔离变更还须用最终产物通过 F15 的组件内、组件外及跨页面检查 |
 | ⑤ 按需 | `index.manifest.json` 组件数 == `.vue` 文件数，**且路径兜底名 0 个** |
 
 第⑤条那个"路径兜底名"是最容易漏的：注册名抽不到就退成 `hrcomponentsSearch` 这种，
@@ -55,6 +57,10 @@ epx 的产品/项目远程库（`window.library.<pkg>`，由 `FM_SYSTEM_WEBPACK`
 | `__epxInstalledLibs__` 有记录但 app 里 0 个组件 | 记账写在 install 之前，产品幂等守卫空转 |
 | 注册名变成 `xxxcomponentsYyy` | `extractName` 没抽到 `name`（按需形态特有） |
 | 组件出来了但完全没样式 | 先查样式表是否加载、实际 DOM 能否匹配选择器；常见原因是 CSS 与 chunk 不同批（`data-v` hash 对不上），或根节点漏了 `.epx-xxx` 样式命名空间（F19） |
+| 隔离测试样式正常，实际页面中继承组件的图片/标题失去样式 | 检查平台包装组件及 Element Plus 插槽的完整渲染链；根有 `data-v-*` 不代表插槽内后代也有。按 F15 核对选择器与继承值，在有效专属容器内局部使用 `:deep()` |
+| 升级后工具栏 `el-select` 把相邻按钮挤到下一行 | Element Plus 选择框默认宽度为 100%；Vue3 产品不再走旧 render 垫片的宽度兜底，按 F20 在产品工具栏显式设置宽度和布局 |
+| 日期选择器显示错误日期，但绑定值/数据时点正确 | 控件还用 fecha 的 `yyyy-MM-dd`，Element Plus 使用 Day.js 的 `YYYY-MM-DD`；按 F21 自动修复产品/项目源码，原生 Vue3 包不依赖旧垫片 |
+| 平台已切换字号、圆角或明暗，产品样式仍固定 | 按 E2 迁移硬编码及动态样式，消费平台主题变量；不在产品重新导入整套主题，不删除 scoped |
 | 图片 404，路径是 `/assets/xxx.png` | 嵌套构建没继承 `assetsInlineLimit` |
 | `Cannot read properties of undefined (reading 'i18n')` | recorder-core 执行序（模块图里没有那条边） |
 | `[vuex] duplicate getter key` | 库被装了两次（本地 + 远程） |
@@ -71,7 +77,13 @@ epx 的产品/项目远程库（`window.library.<pkg>`，由 `FM_SYSTEM_WEBPACK`
 
 > **本轮新增（postAppoint 实证）**：
 > - `fix-jsx-vue2` 除自动改 4 类 JSX 属性（`domProps*`/`nativeOn*`/`scopedSlots=`），现在还**报告** `<script>` 区的 `slot="xxx"` 具名插槽（第 5 类，需人工改 `v-slots`——因要重组 JSX 结构故不自动改；甄别见 F14）；
-> - 新增 `detect-vue3-risks.mjs`（`node tools/epx-migrate/detect-vue3-risks.mjs <项目>`）：发布前静态扫 scoped 整块失效等风险（R1 = extends+scoped+无 template+裸类选择器；已改 `:deep()` 的不误报；退出码 2 可 CI 拦），见 F15。
+> - `detect-vue3-risks.mjs`（`node tools/epx-migrate/detect-vue3-risks.mjs <项目>`）仅提示待复核模式：R1 = extends+scoped+无 template+裸类选择器，退出码 2 可用于 CI 提醒复核。命中不证明样式失效，未命中也不证明隔离安全；不要为消除告警批量删 scoped 或替换成 `:deep()`，按 F15 用实际产物验证。
+
+**样式隔离默认保留**：JSX/render、无 template 或继承组件均不能作为删除 scoped 的依据；隔离测试正常也不能排除实际页面中包装组件/插槽链造成的作用域失配。用最终产物检查实际页面的失效元素、祖先和选择器，确认后优先保留 scoped，在有对应作用域属性的专属容器内对必要后代使用 `:deep()`。若确须去掉 scoped，根命名空间、全部选择器隔离和组件外回归须同时完成，不可留下“先去 scoped、稍后补隔离”的中间结果。详见 F15。
+
+**日期格式必须自动补修（产品和项目都适用，含已标识 `runtime: vue3` 的工程）**：迁移器会在不依赖 gogocode 的阶段修复日期控件 `format`、`value-format/valueFormat` 的静态旧 token，覆盖 template、JSX 和常见 render 写法，并将文件/行号写入报告。仅补日期问题时，在平台工程运行 `node tools/epx-migrate/fix-date-formats.mjs <目标工程> --apply`，不用重跑整个依赖迁移。默认不带 `--apply` 为只读预览。
+
+执行技能时，若自动修复器或发布前扫描发现动态格式变量、配置对象、函数/展开属性，继续追踪实际来源并修复能确认的旧格式；不能只记录“人工检查”便算完成。无法确认用途或缺少源配置的项才保留为未解决，并写明原因。不要全仓替换 `yyyy/dd`，也不改后端协议、其它日期库、分钟 `mm` 或星期 `ddd/dddd`。用最终产物核对初始回显、选择后的绑定值和请求日期一致；例如 `2026-10-20` 不能显示成 `2026-02-01`。详见 [F21](pitfalls.md#f21-element-plus-日期格式-token-迁移遗漏hr-历史组织机构图)。
 
 ## 迁移完怎么验：迁移包 vs 线上 三方对比（postAppoint / recruit / hr 实证）
 
@@ -90,6 +102,8 @@ epx 的产品/项目远程库（`window.library.<pkg>`，由 `FM_SYSTEM_WEBPACK`
 **运行时实证判据（别靠肉眼 / 文本 / 静态 grep）**：
 - 组件在不在：`#app.__vue_app__._context.components` 数量 / 组件实例的 `$slots` 键；
 - 样式生不生效：`getComputedStyle(el)` 比对（容器高度是否塌陷 0、色值 / 尺寸是否对齐线上）；
+- 样式是否泄漏：涉及 scoped、`:deep()` 或全局样式变更时，用最终懒加载产物记录外部同名元素（如 `.avatar`、`.container`）加载组件前后的计算样式；覆盖组件加载后、离开页面及进入其他页面的状态。组件内有效且组件外不受影响，才能验收（F15）；
+- 工具栏选择框与按钮：核对选择框宽度、父容器布局及 `getBoundingClientRect()` 的纵向中心位置；按 F20 检查升级后不再享有的旧垫片默认值，同时确认表单内整行选择框仍按设计占满可用宽度；
 - 差异定性：`el-table` 固定列会复制一份 DOM（Vue2 Element UI 行数翻倍、Vue3 Element Plus 不翻）——比对「共 N 条 / 首行文本」而非 DOM 元素数，否则把「翻倍」误当差异；
 - **静态 grep 到 Vue2 写法 ≠ 运行时一定失效**：失效与否取决于消费方 / 是否被平台全局样式兜住 / 组件运行时兼容（如 JSX `slot=` 在 el-popover reference 失效、在 el-dropdown 正常），必须运行时实证再判改不改。
 
@@ -118,6 +132,7 @@ epx 的产品/项目远程库（`window.library.<pkg>`，由 `FM_SYSTEM_WEBPACK`
    `FM_SYSTEM_WEBPACK` 里仍只配那两条 url，其余按相对路径取。
 3. **`chunks/` 的 `import()` 需要文件服务给 CORS 头**，跨域没配会整库降级。
 4. `index.deps.json` **必须与 index.js 同目录同名一并上传**，漏传不报错但精确 ensure 会静默退化。
+5. 样式隔离有改动时，逐个核对修改的 style 块和最终 CSS；完成 F15 的组件外同名元素及跨页面验收。构建和静态扫描通过不能替代这一步；未测项明确记录为待验证。
 
 ## 常见错误