mvframe 1.0.4 → 1.0.5

package/.cursor/skills/mvframe-app-init/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: mvframe-app-init
+description: >-
+  Scaffolds or audits Vue 3 + Vite host apps that use MVFrame: install order
+  (Element Plus, mvframe plugin, styles), Frame/menu/routes, Pinia options,
+  global config (iconfont, table.summaryMetric), Vite aliases, and views/layout
+  conventions. Use when the user initializes a project with mvframe, wires a
+  new app to @vue/mvframe, asks for MVFrame bootstrap or “same architecture
+  as mvframe”, or reviews structure against this library’s demo and rules.
+---
+
+# MVFrame 应用初始化与架构对齐
+
+在**消费方项目**（或 monorepo 业务包）中接入 MVFrame 时，按下列顺序与约定执行，并与本仓库 `demo/`、`.cursor/rules/` 保持一致。显式触发：用户说「初始化 / 脚手架 / 接入 mvframe / 与 mvframe 架构统一」。
+
+## 1. 依赖与入口顺序
+
+1. `createApp(App)`
+2. **`app.use(ElementPlus)`**（使用 Form / Table 等依赖 EP 的能力时）
+3. **`import` 本库样式**：`mvframe` 源码路径或 monorepo 下的 `.../src/style/index.scss`
+4. **`app.use(mvframe, options)`** — 见下节
+5. **`app.mount('#app')`**
+
+`mvframe` 默认导出为 **install 函数**；注册顺序在库内为：`config` → 全局组件 → `util` → `directive` → `store` → `router`（见 `src/index.js`），调用方勿拆分或颠倒。
+
+## 2. `app.use(mvframe, options)` 必备形状
+
+```js
+app.use(mvframe, {
+  vueRouter: {
+    routes, // required
+    // guard, useAdmin, adminPermission, noaccess — 按需
+  },
+  pinia: {
+    useTab: true, // 多 Tab + localStorage 恢复时启用
+    // storeChips: import.meta.glob('./pinia/chip/*.js', { eager: true }),
+  },
+  config: {
+    iconfont: { url: '//...', prefix: '...' }, // Frame 挂载时注入 script
+    table: {
+      summaryMetric: { /* 或 (prop) => metric */ }, // 多表共用汇总/$fu 格式，可选
+    },
+    // 会与 src/config/chip/base.js 合并 → globalThis.$config
+  },
+});
+```
+
+- **`globalThis.$router`** 由库在安装路由后赋值。
+- **Store**：组件内 `inject('store')` 取工厂，如 `store.tab()`。
+- **Table 汇总**：单列优先 `summary-metric` prop，否则 `$config.table.summaryMetric`；`$fu` 与 `formatSummaryCell` 共用同一套 metric 配置。
+
+## 3. 根组件与路由表
+
+- 根布局使用 **`Frame`**，传入 `menu: { iconClass, routes }`（与 `demo/App.vue` 一致）；`logo` / `logomini` 用插槽。
+- **路由 `meta`**：至少 `title`（守卫里写 `document.title`）；侧栏图标可用 `meta.icon`。
+- **跳转**：优先 **`name`** 跳转，避免裸 `path`（见 `.cursor/rules/router.mdc`）。
+
+## 4. Vite 对齐（消费方）
+
+与库内一致可减少样式与路径问题：
+
+| 项 | 建议 |
+|----|------|
+| `resolve.alias` | `@` → 业务 `src`；若直接引用 composition：`@cps` → `mvframe/.../composition` 或封装路径 |
+| `css.preprocessorOptions.scss.additionalData` | 注入 mvframe 的 `chip/mixin.scss`（或与业务统一的 mixin） |
+| 类型 | 若用 auto-import，为 `vue` / `vue-router` 生成 d.ts |
+
+## 5. views 与应用层结构（消费方）
+
+遵循 `.cursor/rules/views.mdc`：
+
+- **`views` 下一级目录**：**PascalCase 模块名**；模块默认入口 **`Home.vue`**。
+- **页面子组件**：与 `Xxx.vue` **同级**建 **`Xxx/`** 文件夹；子组件 `defineOptions({ name })` 使用 `{模块}{页面}{语义}` 拼接 PascalCase。
+
+库内全局组件根 class：**`Mvc` + 组件名**；内部子 class **camelCase**（`.cursor/rules/component-hierarchy.mdc`）。业务页优先用库已注册组件名（`Frame`、`Page`、`Table` 等），勿重复注册。
+
+## 6. 自检清单（Agent 生成/审查时用）
+
+- [ ] Element Plus 在 mvframe 之前 `use`
+- [ ] 已引入 `index.scss`（或等价主题入口），且 SCSS 与 mixin 策略与库一致
+- [ ] `routes` 已传入，`Frame` 的 `menu.routes` 同源
+- [ ] 需要多 Tab 时 `pinia.useTab: true`
+- [ ] 需汇总格式化时配置 `config.table.summaryMetric` 或 Table `summary-metric`
+- [ ] 路由跳转以 `name` 为主
+- [ ] 业务 `views` 符合模块 / 同名文件夹 / 子组件命名规则
+
+## 7. 参考文件（本仓库）
+
+- `demo/main.js`、`demo/App.vue`、`demo/routes.js` — 最小可运行骨架
+- `README.md` / `README.cn.md` — 目录与安装总览
+- `.cursor/rules/*.mdc` — 组件 class、样式单位、router、views、util
+
+在 **mvframe 仓库内开发库本身**时，改动以 `src/`、`demo/` 为准；技能主要面向 **引用 mvframe 的业务工程** 的初始化与对齐。
+
+## 安装到业务工程
+
+- **目录雏形（推荐）**：`yarn exec mvframe-init-app` 或 `node <mvframe>/scripts/scaffold-app.js`，生成 `src/views`、`router`、`pinia/chip`、`config` 等并写好 `main.js` + `App.use(mvframe)`；说明见目标项目根 `MVFRAME-SCAFFOLD.md`。
+- **仅 Cursor Skill**：`yarn exec mvframe-install-cursor-skill` 或 `node <mvframe>/scripts/install-cursor-skill.js`（`MVFRAME_CURSOR_SKILL_OUT` 可选）。
+
+详见仓库 `README.md` / `README.cn.md`。

package/README.cn.md

@@ -0,0 +1,206 @@
+# MVFrame
+
+[English](README.md) | **简体中文**
+
+面向 **Vue 3 + Vite** 的管理端场景封装：**布局（Frame）**、**常用业务组件**、**全局工具/指令**、**Pinia 工厂与 Tabs 路由联动**、**可组合的 composition 模块**以及 **SCSS 工具类与主题变量**。工具与部分构建配置针对 SaaS 后台类项目做了取舍，更适合与同类技术栈的项目对齐使用，而非追求完全零依赖的通用库。
+
+---
+
+## 技术栈与依赖
+
+| 类型 | 说明 |
+|------|------|
+| 运行时 | `vue` ^3.3、`vue-router` ^4.6、`pinia` ^3 |
+| 演示 / 开发 | `element-plus`（demo 中用于表单等）、`vite` ^6、`sass-embedded` |
+| 构建 | Library 模式产物为 ES 模块；`vue` / `pinia` / `vue-router` 为 **external**，由上层应用提供 |
+
+`package.json` 中声明的发布入口包括：
+
+- `"."` → `dist/index.js`（主插件，默认导出 `install` 函数）
+- `"./composition"` → `dist/composition.js`（`import { useMap, … } from 'mvframe/composition'`）
+- `"./store"`、`"./directive"`、`"./util"` → 对应 `dist` 下分包
+- `"./style"` → `dist/css/style.css`（由 `src/style/index.scss` 单独入口打包的全量工具类/变量）
+- `"./style/cpt"` → `dist/css/cpt.css`（随组件抽取的样式；一般用 `mvframe/style` 即可）
+
+---
+
+## 仓库目录概览
+
+### `src/` — 库源码
+
+| 路径 | 作用 |
+|------|------|
+| `src/index.js` | **统一安装入口**：依次注册 `config` → 全局组件 `cpt` → `util` → `directive` → `store` → `router` |
+| `src/config/` | 合并默认配置与调用方传入项，挂载 `globalThis.$config`（`chip/base.js` 含 name、copyright、version 等） |
+| `src/cpt/index.js` | 通过 `import.meta.glob("../component/*/index.vue")` **自动全局注册**所有「一层子目录 + `index.vue`」的组件，组件名与**文件夹名**一致（PascalCase，如 `BtnGroup`） |
+| `src/component/` | 全局组件实现，根节点 class 约定为 `Mvc` + 组件名（详见 `.cursor/rules/component-hierarchy.mdc`） |
+| `src/util/index.js` | 挂到 `app.config.globalProperties` 与 `globalThis` 的工具方法（如 `$getLang`、`$fa`、`$copy`、`$deepClone` 等） |
+| `src/directive/index.js` | 全局指令：`v-copy`（支持 `.dblclick`）、`v-focus` |
+| `src/store/` | `createPinia` + 内置 `init` / `tab` / `rmenu`；支持 `storeChips` 动态注册；`provide("store", store)` |
+| `src/router/` | `createWebHistory` 创建路由；可选 `guard`；内置 `guardThis`（`meta.admin`、`afterEach` 中与 `tab` 联动、`document.title`） |
+| `src/composition/` | **按需 import**，导出 `lang` / `dom` / `data` / `media` 等（别名 `@cps` 在 Vite 中指向此目录） |
+| `src/style/` | 样式总入口 `index.scss`，按需 `@use` 各 `chip/*.scss`（变量、间距、字体、布局、组件覆盖等） |
+
+**当前 `src/component/` 下的全局组件（文件夹名即注册名）：**
+
+`BtnGroup`、`Form`、`Frame`、`Icon`、`Input`、`Page`、`Select`、`SelectV2`、`Table`、`Tabs`、`Textarea`
+
+子目录 `chip/` 为各组件内部拆片（如 `Frame/chip/Menu.vue`、`Table/chip/ColumnConfig.vue`），不单独注册。
+
+### `demo/` — 本地预览工程
+
+Vite 在 **`NODE_ENV=development`** 下将 **`root` 设为 `./demo`**（见根目录 `vite.config.js`），用于跑通 Frame + 路由 + 组件演示。
+
+| 文件 | 作用 |
+|------|------|
+| `demo/index.html` | 入口 HTML |
+| `demo/main.js` | 创建应用：`ElementPlus` + 引入 `../src/index.js` + `../src/style/index.scss` + `routes` |
+| `demo/App.vue` | 使用 **`Frame`** 布局，传入 `menu: { iconClass: 'imicon', routes }`，插槽 `logo` / `logomini` |
+| `demo/routes.js` | 演示路由表：`/` → `Overview/Home`（组件与 Table 演示），`/a` → `A/Home`；含多级 `children` 用于侧栏结构 |
+| `demo/views/Overview/Home.vue` | 使用 **`Page`** + **`Tabs`**，`Tabs` 切换 **`FormPanel`** / **`IconPanel`** |
+| `demo/views/Overview/Home/FormPanel.vue` | Form 等表单控件演示 |
+| `demo/views/Overview/Home/IconPanel.vue`、`iconfontAntNames.js` | 图标展示与 Ant 图标名列表 |
+| `demo/auto-imports.d.ts` | `unplugin-auto-import` 生成的类型声明（Vue / vue-router） |
+
+本地开发：
+
+```bash
+yarn install
+yarn dev
+```
+
+默认开发服务器端口为 **8088**（见 `vite.config.js`）。
+
+### 路径别名（开发与库内）
+
+| 别名 | 指向 |
+|------|------|
+| `@` | `src/` |
+| `@cps` | `src/composition/` |
+| `@scss` | `assets/scss`（若存在） |
+
+演示里路由组件使用形如 `import("/views/Overview/Home.vue")` 的路径，解析相对于 **`demo`** 根目录。
+
+---
+
+## 在上层应用中安装
+
+### 1. 安装依赖
+
+业务项目需自行安装并对齐版本：**`vue`、`vue-router`、`pinia`**。若使用 `Form` / `Table` 等与 Element Plus 绑定的能力，还需安装 **`element-plus`** 并在应用中 `app.use(ElementPlus)`。
+
+### 2. 注册 MVFrame
+
+```js
+import { createApp } from "vue";
+import mvframe from "mvframe";
+// 样式：源码依赖 / monorepo 可用包内路径；仅发布 dist 时见下文「样式」小节
+import "mvframe/src/style/index.scss";
+
+const app = createApp(App);
+
+app.use(mvframe, {
+  vueRouter: {
+    routes: yourRoutes,
+    // 可选：自定义 beforeEach 等
+    // guard: (router) => { /* ... */ },
+    // useAdmin: true,
+    // adminPermission: () => true,
+    // noaccess: (next) => next(false),
+  },
+  pinia: {
+    useTab: true, // 为 true 时启用多 Tab 与 localStorage 恢复（tabs / ctab）
+    // storeChips: import.meta.glob("./pinia/chip/*.js", { eager: true }),
+  },
+  config: {
+    // 会与 src/config/chip/base.js 合并后赋给 globalThis.$config
+    iconfont: {
+      url: "//at.alicdn.com/t/c/your_font.js",
+      prefix: "ant",
+    },
+  },
+});
+```
+
+**Frame** 组件在挂载时根据 `globalThis.$config.iconfont.url` 动态插入 `script` 加载图标字体（加载后源码中会删除 `url` 字段以避免重复插入）。
+
+### 3. 全局能力摘要
+
+- **`globalThis.$config`**：应用配置  
+- **`globalThis.$router`**：安装后由本库赋值的 router 实例  
+- **`inject("store")`**：得到 **store 工厂对象**，如 `store.tab()`、`store.rmenu()` 及自定义 chip  
+- **全局组件**：直接使用 `Frame`、`Page`、`Table` 等，无需再注册  
+- **指令**：`v-copy`、`v-focus`  
+- **composition**：`import { ... } from "mvframe/composition"` 或项目内 `@cps` 指向的等价路径  
+
+工具方法完整列表与约定见仓库内 **`.cursor/rules/util.mdc`** 与 **`src/util/index.js`**。
+
+### 4. 样式
+
+- 工具类与变量说明见 `.cursor/rules/style-system.mdc`（`--color-*`、间距、字体、布局类等）。  
+- SCSS 会通过 `vite.config.js` 的 **`additionalData`** 注入 **`src/style/chip/mixin.scss`**，与库同构构建的业务项目可保持一致配置。  
+- 发布包可 **`import 'mvframe/style'`**（即 `dist/css/style.css`）；需与 Element Plus 等并存时仍可在业务工程中链入源码 **`src/style/index.scss`** 以便覆写变量。
+
+---
+
+## 构建库
+
+```bash
+yarn build
+```
+
+生产构建使用 **library 模式**，入口为 `src/index.js`，并对产物启用混淆等插件（见 `vite.config.js`）。**开发时** `NODE_ENV` 为 `development` 时走的是 **demo** 工程，若需本地验证构建结果，请在执行 `vite build` 时使用生产环境变量。
+
+---
+
+## 设计取向与注意
+
+- 布局、路由守卫、Tab、菜单等 **强绑定一套交互模型**；深度定制时可局部 fork `src/router`、`src/store/tab.js` 或外层包一层封装。  
+- **组件 class 与单位**：根节点 `Mvc*` + 子命名 camelCase；组件内尺寸除 1px/2px 外建议 **rem**（根号 16px），与 `style-system.mdc` 一致。  
+- 工具函数、Store、路由在非 setup 场景（如守卫）中通过 **`globalThis`** 或 **`store` / `pinia` 导出**访问，与 `src/router/chip/guard.js` 用法一致。
+
+---
+
+## 命令行：项目目录雏形（推荐）
+
+在**空目录或已有 Vite 工程根目录**执行，生成 `src/views`、`src/component`、`src/api`、`src/assets/img`、`src/assets/style`、`src/router`、`src/pinia/chip`、`src/config` 及示例 `main.js` / `App.vue`（已 `app.use(mvframe, …)` 挂好路由、Pinia `storeChips`、config）。若不存在则附带 `index.html` 与 `vite.config.js`。
+
+```bash
+cd /path/to/your-app
+node /path/to/mvframe/scripts/scaffold-app.js
+# 覆盖已有同名文件：
+node /path/to/mvframe/scripts/scaffold-app.js --force
+
+# 安装 mvframe 后：
+yarn exec mvframe-init-app
+# 或：npx mvframe-init-app
+```
+
+生成说明见项目根 **`MVFRAME-SCAFFOLD.md`**。环境变量 **`MVFRAME_SCAFFOLD_TARGET`** 可指定目标路径。
+
+---
+
+## Cursor Skill（应用初始化）
+
+本仓库自带 **`.cursor/skills/mvframe-app-init`**，消费方项目可复制到自身 `.cursor/skills` 以便 Cursor 识别 MVFrame 接入规范。
+
+在**你的业务项目根目录**执行任一种方式：
+
+```bash
+# 克隆 / monorepo 中指向 mvframe 源码时
+node /path/to/mvframe/scripts/install-cursor-skill.js
+node /path/to/mvframe/scripts/install-cursor-skill.js /path/to/your-app
+
+# 安装 npm 包后（发布包需包含 scripts 与 .cursor/skills，见 package.json files）
+cd /path/to/your-app
+yarn exec mvframe-install-cursor-skill
+# 或：npx mvframe-install-cursor-skill
+```
+
+默认安装到**当前工作目录**下的 `.cursor/skills/mvframe-app-init`。也可设置环境变量 `MVFRAME_CURSOR_SKILL_OUT=/path/to/your-app`。
+
+---
+
+## 协议
+
+ISC（见 `package.json`）。

package/README.md

@@ -1,97 +1,100 @@
 # MVFrame
 
-面向 **Vue 3 + Vite** 的管理端场景封装：**布局（Frame）**、**常用业务组件**、**全局工具/指令**、**Pinia 工厂与 Tabs 路由联动**、**可组合的 composition 模块**以及 **SCSS 工具类与主题变量**。工具与部分构建配置针对 SaaS 后台类项目做了取舍，更适合与同类技术栈的项目对齐使用，而非追求完全零依赖的通用库。
+**English** | [简体中文](README.cn.md)
+
+A Vue 3 + Vite oriented admin-shell toolkit: **Frame layout**, **common business components**, **global utilities & directives**, **Pinia wiring with tabs/router**, **composable modules**, and **SCSS utilities & tokens**. Priorities favor SaaS-style admin apps over a fully pluggable, zero-opinion utility library.
 
 ---
 
-## 技术栈与依赖
+## Stack & dependencies
 
-| 类型 | 说明 |
+| Kind | Notes |
 |------|------|
-| 运行时 | `vue` ^3.3、`vue-router` ^4.6、`pinia` ^3 |
-| 演示 / 开发 | `element-plus`（demo 中用于表单等）、`vite` ^6、`sass-embedded` |
-| 构建 | Library 模式产物为 ES 模块；`vue` / `pinia` / `vue-router` 为 **external**，由上层应用提供 |
+| Runtime | `vue` ^3.3, `vue-router` ^4.6, `pinia` ^3 |
+| Demo / dev | `element-plus` (demo forms, etc.), `vite` ^6, `sass-embedded` |
+| Build | Library output is **ESM**; **`vue` / `pinia` / `vue-router` are externals** and must be supplied by the host app |
 
-`package.json` 中声明的发布入口包括：
+`package.json` exports include:
 
-- `"."` → `dist/index.js`（主插件，默认导出 `install` 函数）
-- `"./composition"` → `dist/composition.js`
-- `"./store"`、`"./directive"` → 对应 `dist` 下的分包（与 Rollup `manualChunks` 一致时存在）
-- `"./style"` → `dist/style.css`（**需在构建流程中产出 CSS 后**方可使用；本地开发通常直接引用源码样式，见下文）
+- `"."` → `dist/index.js` (main plugin; default export is the `install` function)
+- `"./composition"` → `dist/composition.js` (e.g. `import { useMap } from 'mvframe/composition'`)
+- `"./store"`, `"./directive"`, `"./util"` → matching chunks under `dist`
+- `"./style"` → `dist/css/style.css` (full toolkit CSS from `src/style/index.scss` entry)
+- `"./style/cpt"` → `dist/css/cpt.css` (component-extracted CSS; usually `import 'mvframe/style'` is enough)
 
 ---
 
-## 仓库目录概览
+## Repository layout
 
-### `src/` — 库源码
+### `src/` — library source
 
-| 路径 | 作用 |
+| Path | Role |
 |------|------|
-| `src/index.js` | **统一安装入口**：依次注册 `config` → 全局组件 `cpt` → `util` → `directive` → `store` → `router` |
-| `src/config/` | 合并默认配置与调用方传入项，挂载 `globalThis.$config`（`chip/base.js` 含 name、copyright、version 等） |
-| `src/cpt/index.js` | 通过 `import.meta.glob("../component/*/index.vue")` **自动全局注册**所有「一层子目录 + `index.vue`」的组件，组件名与**文件夹名**一致（PascalCase，如 `BtnGroup`） |
-| `src/component/` | 全局组件实现，根节点 class 约定为 `Mvc` + 组件名（详见 `.cursor/rules/component-hierarchy.mdc`） |
-| `src/util/index.js` | 挂到 `app.config.globalProperties` 与 `globalThis` 的工具方法（如 `$getLang`、`$fa`、`$copy`、`$deepClone` 等） |
-| `src/directive/index.js` | 全局指令：`v-copy`（支持 `.dblclick`）、`v-focus` |
-| `src/store/` | `createPinia` + 内置 `init` / `tab` / `rmenu`；支持 `storeChips` 动态注册；`provide("store", store)` |
-| `src/router/` | `createWebHistory` 创建路由；可选 `guard`；内置 `guardThis`（`meta.admin`、`afterEach` 中与 `tab` 联动、`document.title`） |
-| `src/composition/` | **按需 import**，导出 `lang` / `dom` / `data` / `media` 等（别名 `@cps` 在 Vite 中指向此目录） |
-| `src/style/` | 样式总入口 `index.scss`，按需 `@use` 各 `chip/*.scss`（变量、间距、字体、布局、组件覆盖等） |
+| `src/index.js` | **Install entry**: registers `config` → global components (`cpt`) → `util` → `directive` → `store` → `router` |
+| `src/config/` | Merges defaults with app options → `globalThis.$config` (`chip/base.js`: name, copyright, version, etc.) |
+| `src/cpt/index.js` | **Auto-registers** every `component/*/index.vue` via `import.meta.glob`; component name equals the **folder** name (PascalCase, e.g. `BtnGroup`) |
+| `src/component/` | Implementations; root class `Mvc` + name (see `.cursor/rules/component-hierarchy.mdc`) |
+| `src/util/index.js` | Global helpers on `app.config.globalProperties` & `globalThis` (`$getLang`, `$fa`, `$copy`, `$deepClone`, …) |
+| `src/directive/index.js` | Directives: `v-copy` (optional `.dblclick`), `v-focus` |
+| `src/store/` | `createPinia` + built-in `init` / `tab` / `rmenu`; optional `storeChips`; `provide("store", store)` |
+| `src/router/` | `createWebHistory` router; optional `guard`; built-in `guardThis` (`meta.admin`, `afterEach` + tabs, `document.title`) |
+| `src/composition/` | **Import on demand**; exports `lang`, `dom`, `data`, `media`, … (Vite alias `@cps` → this folder) |
+| `src/style/` | `index.scss` aggregates `chip/*.scss` (tokens, spacing, typography, layout, overrides) |
 
-**当前 `src/component/` 下的全局组件（文件夹名即注册名）：**
+**Globally registered components** (folder name = registration name):
 
-`BtnGroup`、`Form`、`Frame`、`Icon`、`Input`、`Page`、`Select`、`SelectV2`、`Table`、`Tabs`、`Textarea`
+`BtnGroup`, `Form`, `Frame`, `Icon`, `Input`, `Page`, `Select`, `SelectV2`, `Table`, `Tabs`, `Textarea`
 
-子目录 `chip/` 为各组件内部拆片（如 `Frame/chip/Menu.vue`、`Table/chip/ColumnConfig.vue`），不单独注册。
+`chip/` subfolders hold internal pieces (e.g. `Frame/chip/Menu.vue`); they are **not** registered as root components.
 
-### `demo/` — 本地预览工程
+### `demo/` — local preview app
 
-Vite 在 **`NODE_ENV=development`** 下将 **`root` 设为 `./demo`**（见根目录 `vite.config.js`），用于跑通 Frame + 路由 + 组件演示。
+With **`NODE_ENV=development`**, Vite **`root`** is **`./demo`** (see `vite.config.js`) to exercise Frame, routing, and components.
 
-| 文件 | 作用 |
+| File | Role |
 |------|------|
-| `demo/index.html` | 入口 HTML |
-| `demo/main.js` | 创建应用：`ElementPlus` + 引入 `../src/index.js` + `../src/style/index.scss` + `routes` |
-| `demo/App.vue` | 使用 **`Frame`** 布局，传入 `menu: { iconClass: 'imicon', routes }`，插槽 `logo` / `logomini` |
-| `demo/routes.js` | 演示路由表：`/` → `Overview/Home`（组件与 Table 演示），`/a` → `A/Home`；含多级 `children` 用于侧栏结构 |
-| `demo/views/Overview/Home.vue` | 使用 **`Page`** + **`Tabs`**，`Tabs` 切换 **`FormPanel`** / **`IconPanel`** |
-| `demo/views/Overview/Home/FormPanel.vue` | Form 等表单控件演示 |
-| `demo/views/Overview/Home/IconPanel.vue`、`iconfontAntNames.js` | 图标展示与 Ant 图标名列表 |
-| `demo/auto-imports.d.ts` | `unplugin-auto-import` 生成的类型声明（Vue / vue-router） |
+| `demo/index.html` | HTML shell |
+| `demo/main.js` | Boot: `ElementPlus` + `../src/index.js` + `../src/style/index.scss` + `routes` |
+| `demo/App.vue` | **`Frame`** layout, `menu: { iconClass: 'imicon', routes }`, slots `logo` / `logomini` |
+| `demo/routes.js` | Sample routes: `/` → `Overview/Home`, `/a` → `A/Home`; nested `children` for the sidebar |
+| `demo/views/Overview/Home.vue` | **`Page`** + **`Tabs`** switching **`FormPanel`** / **`IconPanel`** |
+| `demo/views/Overview/Home/FormPanel.vue` | Form demo |
+| `demo/views/Overview/Home/IconPanel.vue`, `iconfontAntNames.js` | Icon demo & Ant icon name list |
+| `demo/auto-imports.d.ts` | Types from `unplugin-auto-import` (Vue / vue-router) |
 
-本地开发：
+Local dev:
 
 ```bash
 yarn install
 yarn dev
 ```
 
-默认开发服务器端口为 **8088**（见 `vite.config.js`）。
+Dev server port **8088** (see `vite.config.js`).
 
-### 路径别名（开发与库内）
+### Path aliases
 
-| 别名 | 指向 |
-|------|------|
+| Alias | Points to |
+|------|-----------|
 | `@` | `src/` |
 | `@cps` | `src/composition/` |
-| `@scss` | `assets/scss`（若存在） |
+| `@scss` | `assets/scss` (if present) |
 
-演示里路由组件使用形如 `import("/views/Overview/Home.vue")` 的路径，解析相对于 **`demo`** 根目录。
+Demo routes use paths like `import("/views/Overview/Home.vue")` resolved from the **`demo`** root.
 
 ---
 
-## 在上层应用中安装
+## Using in a host application
 
-### 1. 安装依赖
+### 1. Install peer-style deps
 
-业务项目需自行安装并对齐版本：**`vue`、`vue-router`、`pinia`**。若使用 `Form` / `Table` 等与 Element Plus 绑定的能力，还需安装 **`element-plus`** 并在应用中 `app.use(ElementPlus)`。
+Align versions of **`vue`**, **`vue-router`**, **`pinia`**. For `Form` / `Table` tied to Element Plus, add **`element-plus`** and `app.use(ElementPlus)`.
 
-### 2. 注册 MVFrame
+### 2. Register MVFrame
 
 ```js
 import { createApp } from "vue";
 import mvframe from "mvframe";
-// 样式：源码依赖 / monorepo 可用包内路径；仅发布 dist 时见下文「样式」小节
+// Styles: use package path when depending on source / monorepo; published `dist`-only—see “Styles”
 import "mvframe/src/style/index.scss";
 
 const app = createApp(App);
@@ -99,18 +102,18 @@ const app = createApp(App);
 app.use(mvframe, {
   vueRouter: {
     routes: yourRoutes,
-    // 可选：自定义 beforeEach 等
+    // optional: custom beforeEach, etc.
     // guard: (router) => { /* ... */ },
     // useAdmin: true,
     // adminPermission: () => true,
     // noaccess: (next) => next(false),
   },
   pinia: {
-    useTab: true, // 为 true 时启用多 Tab 与 localStorage 恢复（tabs / ctab）
+    useTab: true, // multi-tab + localStorage restore for `tabs` / `ctab`
     // storeChips: import.meta.glob("./pinia/chip/*.js", { eager: true }),
   },
   config: {
-    // 会与 src/config/chip/base.js 合并后赋给 globalThis.$config
+    // merged with src/config/chip/base.js → globalThis.$config
     iconfont: {
       url: "//at.alicdn.com/t/c/your_font.js",
       prefix: "ant",
@@ -119,45 +122,83 @@ app.use(mvframe, {
 });
 ```
 
-**Frame** 组件在挂载时根据 `globalThis.$config.iconfont.url` 动态插入 `script` 加载图标字体（加载后源码中会删除 `url` 字段以避免重复插入）。
+**Frame** injects a `<script>` for icon fonts from `globalThis.$config.iconfont.url` on mount (implementation removes `url` afterward to avoid duplicate injection).
 
-### 3. 全局能力摘要
+### 3. Globals at a glance
 
-- **`globalThis.$config`**：应用配置  
-- **`globalThis.$router`**：安装后由本库赋值的 router 实例  
-- **`inject("store")`**：得到 **store 工厂对象**，如 `store.tab()`、`store.rmenu()` 及自定义 chip  
-- **全局组件**：直接使用 `Frame`、`Page`、`Table` 等，无需再注册  
-- **指令**：`v-copy`、`v-focus`  
-- **composition**：`import { ... } from "mvframe/composition"` 或项目内 `@cps` 指向的等价路径  
+- **`globalThis.$config`** — merged app config  
+- **`globalThis.$router`** — router instance assigned by this library after install  
+- **`inject("store")`** — store **factory** (`store.tab()`, `store.rmenu()`, custom chips)  
+- **Global components** — use `Frame`, `Page`, `Table`, … without local registration  
+- **Directives** — `v-copy`, `v-focus`  
+- **Composition** — `import { ... } from "mvframe/composition"` or your `@cps` alias  
 
-工具方法完整列表与约定见仓库内 **`.cursor/rules/util.mdc`** 与 **`src/util/index.js`**。
+Full helper list: `.cursor/rules/util.mdc` and `src/util/index.js`.
 
-### 4. 样式
+### 4. Styles
 
-- 工具类与变量说明见 `.cursor/rules/style-system.mdc`（`--color-*`、间距、字体、布局类等）。  
-- SCSS 会通过 `vite.config.js` 的 **`additionalData`** 注入 **`src/style/chip/mixin.scss`**，与库同构构建的业务项目可保持一致配置。  
-- 若 NPM 包仅发布 `dist` 且未包含 `style.css`，需在业务工程中从 Git 路径或 monorepo 链入 **`src/style/index.scss`**，或自行扩展库的 Vite 构建以导出 CSS。
+- Utility classes & tokens: `.cursor/rules/style-system.mdc` (`--color-*`, spacing, typography, layout).  
+- `vite.config.js` **`additionalData`** injects **`src/style/chip/mixin.scss`**; mirror this in apps that compile the same SCSS tree.  
+- Published packages can use **`import 'mvframe/style'`** (`dist/css/style.css`). For SCSS overrides, still link **`src/style/index.scss`** from Git/monorepo when needed.
 
 ---
 
-## 构建库
+## Building the library
 
 ```bash
 yarn build
 ```
 
-生产构建使用 **library 模式**，入口为 `src/index.js`，并对产物启用混淆等插件（见 `vite.config.js`）。**开发时** `NODE_ENV` 为 `development` 时走的是 **demo** 工程，若需本地验证构建结果，请在执行 `vite build` 时使用生产环境变量。
+Production uses **library mode** with entry `src/index.js` and obfuscation-related plugins (see `vite.config.js`). **`NODE_ENV=development`** points Vite at the **demo** app; to verify a real build locally, run production **`vite build`** (or your script that sets production env).
+
+---
+
+## Design notes
+
+- Layout, guards, tabs, and menu behavior are **opinionated**; heavy customization may mean forking `src/router`, `src/store/tab.js`, or wrapping from the app.  
+- **CSS naming & units**: root `Mvc*`, children camelCase; prefer **rem** for sizes other than 1px/2px (16px root)—see `style-system.mdc`.  
+- Use **`globalThis`** or **`store` / `pinia` exports** outside `setup` (e.g. guards), as in `src/router/chip/guard.js`.
+
+---
+
+## CLI: project skeleton
+
+From an **empty folder or existing Vite root**, generates `src/views`, `src/component`, `src/api`, `src/assets/img`, `src/assets/style`, `src/router`, `src/pinia/chip`, `src/config`, plus starter `main.js` / `App.vue` with `app.use(mvframe, …)` (routes, Pinia `storeChips`, config). Adds `index.html` and `vite.config.js` only if missing (use `--force` to overwrite).
+
+```bash
+cd /path/to/your-app
+node /path/to/mvframe/scripts/scaffold-app.js
+node /path/to/mvframe/scripts/scaffold-app.js --force
+
+yarn exec mvframe-init-app
+# or: npx mvframe-init-app
+```
+
+See **`MVFRAME-SCAFFOLD.md`** in the target project. Set **`MVFRAME_SCAFFOLD_TARGET`** to point at the project root.
 
 ---
 
-## 设计取向与注意
+## Cursor Skill (app scaffold)
+
+This repo ships **`.cursor/skills/mvframe-app-init`**. Copy it into your app’s **`.cursor/skills`** so Cursor can pick up MVFrame integration conventions.
+
+From **your app root**, run either:
+
+```bash
+# Full checkout / monorepo path to mvframe
+node /path/to/mvframe/scripts/install-cursor-skill.js
+node /path/to/mvframe/scripts/install-cursor-skill.js /path/to/your-app
+
+# After installing the npm package (the tarball must include `scripts/` and `.cursor/skills`—see `package.json` `files`)
+cd /path/to/your-app
+yarn exec mvframe-install-cursor-skill
+# or: npx mvframe-install-cursor-skill
+```
 
-- 布局、路由守卫、Tab、菜单等 **强绑定一套交互模型**；深度定制时可局部 fork `src/router`、`src/store/tab.js` 或外层包一层封装。  
-- **组件 class 与单位**：根节点 `Mvc*` + 子命名 camelCase；组件内尺寸除 1px/2px 外建议 **rem**（根号 16px），与 `style-system.mdc` 一致。  
-- 工具函数、Store、路由在非 setup 场景（如守卫）中通过 **`globalThis`** 或 **`store` / `pinia` 导出**访问，与 `src/router/chip/guard.js` 用法一致。
+Default target is **`./.cursor/skills/mvframe-app-init`** under the current working directory. Override with **`MVFRAME_CURSOR_SKILL_OUT=/path/to/your-app`**.
 
 ---
 
-## 协议
+## License
 
-ISC（见 `package.json`）。
+ISC (see `package.json`).