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

package/API.md

@@ -2,13 +2,13 @@
 
 独立工程命令行工具，终端命令名为 epxing。/vite 提供产品构建插件，根入口不提供业务运行时。
 
-本页对应包版本 `0.5.0-beta.4`。导出名、子路径和签名从当前源码、package.json 与类型声明生成。
+本页对应包版本 `0.5.0-beta.6`。导出名、子路径和签名从当前源码、package.json 与类型声明生成。
 
 ## 安装与使用
 
 
 ```sh
-npm install -g @epxing/cli@0.5.0-beta.4
+npm install -g @epxing/cli@0.5.0-beta.6
 ```
 
 
@@ -24,7 +24,7 @@ epxing migrate .
 
 ## 接入约定
 
-工程命令使用当前项目已安装的依赖和脚本。--dir 指定项目目录；创建/迁移默认使用 @epxing 独立包，版本留空查询最新 beta 并固定到具体版本，没有 beta 时使用 latest。--packages-version 可指定数字版本或标签；--epx-frame 仅显式保留旧聚合模式，两者互斥。CLI 采用自己的版本号，独立于其余平台包。完整参数、迁移与发布说明见本包 README。
+工程命令使用当前项目已安装的依赖和脚本。--dir 指定项目目录；创建/迁移默认使用 @epxing 独立包，版本留空查询最新 beta 并固定到具体版本，没有 beta 时使用 latest。--packages-version 可指定数字版本或标签；--epx-frame 仅显式保留旧聚合模式，两者互斥。CLI 采用自己的版本号，独立于其余平台包。创建和升级在可识别的应用入口预留默认注释的 installLegacyFrame 导入与调用；需要旧远程库共享桥时手动启用，要求 core 5.3.0-beta.5 或以上。升级保留已有启用状态，重复升级不重复插入。完整参数、迁移与发布说明见本包 README。
 
 ## 稳定子路径
 

package/README.md

@@ -4,7 +4,11 @@
 
 独立的工程开发工具，包含交互菜单、开发服务、产品库构建、创建、Vue3 迁移、静态检查和升级技能安装。创建和升级默认使用 `@epxing/*` 独立包，版本留空时查询最新 `beta` 并固定到具体版本，没有 `beta` 时使用 `latest`；可用 `--packages-version` 指定版本或标签。CLI 使用自己的版本号。创建和升级会生成产品使用说明；`@epxing/cli/vite` 提供产品构建插件，不依赖聚合包中的构建工具。
 
-本批测试版本：`@epxing/cli@0.5.0-beta.4`，平台包 `5.3.0-beta.2`，均使用 npm 公网 `beta` 标签。完整流程见文档站“CLI 创建、升级与产品使用”；各包公开 API 随安装包的 `API.md` 提供。
+本批测试版本：`@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 不再添加这些导入；指定旧版本时仍保留显式样式以兼容旧包。标签会先解析成具体版本再选择模板。已有显式导入可以保留，产品覆盖样式放在框架导入之后。
 

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

@@ -1,6 +1,6 @@
 ---
 name: epxing-frontend-vue3-migrate
-description: epx 产品/项目远程库 Vue2/webpack → Vue3/Vite 升级 + 按需打包（lazy/chunks 形态）的完整流程、判据与踩坑清单；也用于排查远程库「构建绿、控制台干净、组件却静默失效」——不渲染 / 注册名错 / 有组件没样式 / 登录拉整包 / 弹窗标题空 / 图表画不出 / 卡片 scoped 样式丢。含 epx-migrate CLI（migrate 迁移、detect-vue3-risks 发布前静态扫风险、verify-components 组件清单对齐）与三方对比环境搭法（本地 dist + 工装 + Web Worker 定时器垫片 + 运行时实证）。触发：产品升级 / Vue3 迁移 / 迁移包对比测试 / 升级后静默失效排查。
+description: epx 产品/项目的前端升级、Vue 升级（vue升级）、升级到 Vue3（升级到vue3）、Vue2 转 Vue3、框架升级与产品升级时使用。由 AI 协同迁移依赖、业务代码及 webpack/Vite 构建，逐组件接入平台主题与全局 CSS 变量并验收；也用于远程库按需打包、迁移包对比及升级后组件不渲染、样式丢失等静默失效排查。不用于无关项目的通用 Vue 升级、平台框架源码重写或后端升级。
 ---
 
 # 产品升级与迁移（独立包 + Vue3 + Vite）
@@ -12,6 +12,21 @@ epx 的产品/项目远程库（`window.library.<pkg>`，由 `FM_SYSTEM_WEBPACK`
 
 独立 CLI 使用 `epxing` 命令，产品默认依赖 `@epxing/core`、`@epxing/components`、`@epxing/business` 等独立包。`upgrade` 是 `migrate` 的别名；版本留空查询最新 beta（无 beta 时回退 latest），并固定具体版本。`--epx-frame` 仅显式保留旧聚合模式。仓库原有 `pnpm epx` 是本地脚本，不等同于已安装的 CLI。
 
+## 自然语言触发与 AI 执行范围
+
+在 epx 产品/项目上下文中，用户说“前端升级”“Vue 升级”“升级到 Vue3”“把人事从 Vue2 升到 Vue3”或“一并升级旧框架”时使用本技能，无需用户先报技能名或 CLI 命令。仅询问升级能力时先解释；要求实际升级时按下述流程推进。
+
+1. 先读取工程清单、应用与组件库入口、构建配置及 Git 状态，判断现有 Vue、框架依赖和构建方式；按「先判断升级类型」选择路径，不对已有 Vue3 工程重复执行 Vue2 转换。
+2. 产品使用 Vue2 版 epx-frame 时，将框架依赖迁至新版独立包与产品代码适配作为同一升级任务，覆盖入口、组件继承、导入、路由、状态管理、插槽及样式。若工程内复制或修改过旧框架源码，先识别差异与公开 API 替代方案，不直接删除或覆盖；超出产品适配的框架源码改造需明确范围后再处理。
+3. CLI 用于确定的机械转换；AI 审阅迁移报告，继续定位并修复可确认的人工项、构建失败和运行差异，不停在给出命令或罗列待办。保留产品业务和自定义内容；遇到缺少业务依据或环境的项，明确原因与下一步，不声称全部完成。
+4. 按下文判据验证平台登录、菜单、配置首页、产品组件及最终库产物。技能匹配不额外授予安装、构建、提交或部署权限，按用户任务授权及项目规则执行。
+
+**主题接入是产品升级的必做项**，包括已经使用 Vue3/独立包的产品。按 [E2](pitfalls.md#e2-产品项目样式必须跟随平台主题轴) 建立全量组件台账，逐个检查主题和全局 CSS 变量、修复可确认的问题，并记录实际验证结果。每个组件都要有结论；没有改代码、CLI 未告警或只是继承平台组件，也不能免检。按用途接入，不给图标、布局、文字、表单等一律加面板装饰。未检、失败或缺环境的组件保持未完成，不能用几个代表页代替全量组件验收。
+
+**跨会话缺陷回归**：同时读取 [G 节](pitfalls.md#g-产品升级的跨会话缺陷回归)，按组件实际能力逐项判断是否适用，复用 E2 台账记录命中项、证据和结论。已有 F 节修法直接引用，不重复机械修复；平台已修复的兼容问题仍要确认目标宿主版本包含修复。具体产品的配置失效和未解决问题只作为定位线索，不能泛化成全产品必须修改的源码规则。
+
+Claude Code 项目技能放在 `.claude/skills/epxing-frontend-vue3-migrate/`，同时保留本文件和 `pitfalls.md`；技能描述供自动匹配，不能保证每次命中。未自动选中时可显式调用 `/epxing-frontend-vue3-migrate`。更新产品已有技能前先比较并保留其自定义内容；仓库修改不会自动更新产品副本或已发布 CLI。
+
 ## 先判断升级类型
 
 | 当前工程 | 操作 |
@@ -63,7 +78,7 @@ epx 的产品/项目远程库（`window.library.<pkg>`，由 `FM_SYSTEM_WEBPACK`
 | ① 依赖迁移 | `MIGRATION-REPORT.md` 的人工清单**逐条看过**——里面写着的坑会真的咬人 |
 | ② .vue 转换 | 使用工程本地 ESLint 校验改动源码；工具链缺失则先恢复并明确未验证项，不临时拉全局 ESLint |
 | ③ 切 Vite | `npm run build:lib` exit 0 **且** `lib/` 里有 `index.js`/`index.css`/`index.deps.json` |
-| ④ dev 壳 | 平台登录、角色、菜单与配置首页可用，产品组件确实显示；核对真实 DOM 和 CSS，不能仅凭注册数量判通过。样式隔离变更还须用最终产物通过 F15 的组件内、组件外及跨页面检查 |
+| ④ dev 壳 | 平台登录、角色、菜单与配置首页可用，产品组件确实显示；核对真实 DOM 和 CSS，不能仅凭注册数量判通过。E2 台账覆盖每个组件，按用途接入主题与全局变量并验证；样式隔离变更还须用最终产物通过 F15 的组件内、组件外及跨页面检查 |
 | ⑤ 按需 | `index.manifest.json` 与入口实际收集的组件集合对齐，复核路径兜底名；源码候选、产物清单和线上参考分别记录 |
 
 第⑤条那个"路径兜底名"是最容易漏的：注册名抽不到就退成 `hrcomponentsSearch` 这种，
@@ -80,6 +95,8 @@ epx 的产品/项目远程库（`window.library.<pkg>`，由 `FM_SYSTEM_WEBPACK`
 | 隔离测试样式正常，实际页面中继承组件的图片/标题失去样式 | 检查平台包装组件及 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 包不依赖旧垫片 |
+| 旧薪酬卡片显示标题时报 `reading 'compTitle'` | 检查 `$configs.propsData.compTitle`；旧库通过 Vue2 垫片兼容，源码升级时改为 `this.compTitle`（模板用 `compTitle`），按 F22 检查其它 propsData 读取 |
+| 列表接口已有 `字段#`，对象/选项列仍显示 ID 或代码 | 检查单写 `renderField` / `renderColumnOperates` 是否还返回 `{ scopedSlots: { default } }`；按 F23 改成 Vue3 插槽对象，并在不依赖旧垫片的产品产物中验收名称和操作列 |
 | 平台已切换字号、圆角或明暗，产品样式仍固定 | 按 E2 迁移硬编码及动态样式，消费平台主题变量；不在产品重新导入整套主题，不删除 scoped |
 | 图片 404，路径是 `/assets/xxx.png` | 嵌套构建没继承 `assetsInlineLimit` |
 | `Cannot read properties of undefined (reading 'i18n')` | recorder-core 执行序（模块图里没有那条边） |
@@ -95,6 +112,8 @@ epx 的产品/项目远程库（`window.library.<pkg>`，由 `FM_SYSTEM_WEBPACK`
 > 内联事件多语句补分号、`:prop.sync`→`v-model`、删 `node-sass`/`fibers`、`--to-vite` 生成 vite.config（含 resolve.extensions）、
 > 第三方 Vue2-only 库 ⑥ 告警、`verify-components` 与线上组件清单对齐。**留给人工的就是 F 节那几类**：元素级 slot/slot-scope 结构转换、换库、编译残留定位。
 
+**列表升级必查**：逐项检查重写的 `renderField`、`renderColumnOperates` 及父类回退分支，按 [F23](pitfalls.md#f23-列表已有字段名称却显示-id代码旧单写插槽返回协议) 转换残留的旧插槽对象；即使 CLI 无告警、构建成功，也须在不依赖旧方法归一化的 Vue3 产品中验证 `字段#` 名称和操作列，未验证不得将此项标为完成。
+
 > **本轮新增（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 <项目>`）仅提示待复核模式：R1 = extends+scoped+无 template+裸类选择器，退出码 2 可用于 CI 提醒复核。命中不证明样式失效，未命中也不证明隔离安全；不要为消除告警批量删 scoped 或替换成 `:deep()`，按 F15 用实际产物验证。
@@ -153,6 +172,8 @@ epx 的产品/项目远程库（`window.library.<pkg>`，由 `FM_SYSTEM_WEBPACK`
 3. **`chunks/` 的 `import()` 需要文件服务给 CORS 头**，跨域没配会整库降级。
 4. `index.deps.json` **必须与 index.js 同目录同名一并上传**，漏传不报错但精确 ensure 会静默退化。
 5. 样式隔离有改动时，逐个核对修改的 style 块和最终 CSS；完成 F15 的组件外同名元素及跨页面验收。构建和静态扫描通过不能替代这一步；未测项明确记录为待验证。
+6. 核对 E2 主题台账与入口收集、内部子组件及最终产物清单，确保每个组件有检查与运行结论。未检查、未验证、适配失败或缺少业务依据的项逐条列明，不得将升级标记为全部完成；未发现样式问题的组件也要保留核查证据。
+7. 按 G 节核对适用的交互、上下文、浮层、表格、设计器和性能问题。区分已检查不适用、已验证通过、已改待验证和阻塞；临时浏览器修正、平台兼容单测或旧会话交付记录，不能作为当前产品新制品已通过的证据。
 
 ## 常见错误