mvframe 1.0.79 → 1.0.81

package/.cursor/rules/style-system.mdc

@@ -204,7 +204,41 @@ alwaysApply: true
 
 - `hover`：hover 时 opacity 0.6 + 过渡
 
-## 6. 动画（ani.scss）
+## 6. 组件通用样式（cpt.scss）
+
+### 组件变量
+
+- `--btn-radius`：按钮圆角，与 `BtnGroup` 等组件保持一致
+- `--loading-radius`：Loading 圆角
+- `--card-radius` / `--card-header-border` / `--card-footer-border`：Card 相关变量
+
+### Tag
+
+全局 `.tag` 是通用标签样式，不是单独的 Vue 组件。遇到数量徽标、状态短标签、固定字段小块时，优先复用它，而不是重新写一套 pill/tag CSS。
+
+| 类名 | 用途 |
+|------|------|
+| `tag` | 基础标签：灰底、提示色文字、胶囊圆角 |
+| `tag rect` | 直角矩形标签 |
+| `tag small` | 更小字号标签 |
+| `tag backdrop` | 半透明毛玻璃标签 |
+| `tag primary/red/orange/green/blue/purple/pink/yellow/white/black/body/dark` | 标签颜色变体，色值与 `var.scss` 的全局颜色体系一致 |
+
+使用建议：
+
+- 默认直接在模板中组合类名：`class="tag blue"`、`class="tag rect small"`、`class="tag small backdrop"`
+- 如果只是标签颜色或形态变化，不要重写 scoped tag 样式，直接叠加现有变体
+- 只有在 `tag` 无法覆盖的专属视觉下，才在局部补 scoped 样式
+
+### Tip 按钮与图标
+
+| 类名 | 用途 |
+|------|------|
+| `tipbtn` | hover 时通过 `::after` 显示简易文本提示，文案取 `txt` 属性 |
+| `tipbtn bottom/left/right` | 控制提示方向 |
+| `MvcIcon` | 组件图标类，默认 `flex-shrink: 0` |
+
+## 7. 动画（ani.scss）
 
 | 类名 | 用途 |
 |------|------|

package/README.cn.md

@@ -224,7 +224,7 @@ await notify("需要发送到钉钉的消息");
 
 ## 命令行：项目目录雏形（推荐）
 
-在**空目录或已有 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，并写入 `components.async: ["VTable"]`），同时写入/更新宿主项目 **`AGENTS.md`** 的 MVFrame Codex 规则，并复制 **`/.cursor/rules/*.mdc`**（与 mvframe 仓库内 Cursor 规则一致）。若不存在则附带 `index.html` 与 `vite.config.js`。会**合并** `package.json` 的 `scripts` / `dependencies` / `devDependencies`（与 Vite 模板一致；**同名脚本和包保留你原有值**），初始化 `.env.mvframe-notify.example` / `.env.local.example` 与 `config.notify`，并自动执行 **`yarn install`**，最后请执行 **`yarn dev`**；需要同时启动通知服务时显式执行 **`yarn exec mvframe-d`**。加 `--no-package-json` 可不改动 `package.json` 且跳过安装。
+在**空目录或已有 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，并写入 `components.async: ["VTable"]`），同时写入/更新宿主项目 **`AGENTS.md`** 的 MVFrame Codex 规则，其中包含 **每次 AI 完成开发后执行 `yarn exec mvframe-notify --once --message "..."` 发送完成通知** 的要求，并复制 **`/.cursor/rules/*.mdc`**（与 mvframe 仓库内 Cursor 规则一致）。若不存在则附带 `index.html` 与 `vite.config.js`。会**合并** `package.json` 的 `scripts` / `dependencies` / `devDependencies`（与 Vite 模板一致；**同名脚本和包保留你原有值**），初始化 `.env.mvframe-notify.example` / `.env.local.example` 与 `config.notify`，并自动执行 **`yarn install`**，最后请执行 **`yarn dev`**；需要同时启动通知服务时显式执行 **`yarn exec mvframe-d`**。加 `--no-package-json` 可不改动 `package.json` 且跳过安装。
 
 ```bash
 cd /path/to/your-app

package/README.md

@@ -211,7 +211,7 @@ Send messages with `globalThis.$notify.send("message")` or `import { notify } fr
 
 ## 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, and `components.async: ["VTable"]`). It also writes/updates host-project **`AGENTS.md`** with MVFrame Codex rules, and copies **`/.cursor/rules/*.mdc`** from the package (same as this repo’s Cursor rules). Adds `index.html` and `vite.config.js` only if missing (use `--force` to overwrite). **Merges** `scripts` / `dependencies` / `devDependencies` into `package.json` (existing values win for shared keys), initializes `.env.mvframe-notify.example` / `.env.local.example` and `config.notify`, then runs **`yarn install`**; use `--no-package-json` to skip package changes and install. Then run **`yarn dev`** or explicitly run **`yarn exec mvframe-d`** to start Vite with the notify service.
+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, and `components.async: ["VTable"]`). It also writes/updates host-project **`AGENTS.md`** with MVFrame Codex rules, including a requirement that AI send a completion message with `yarn exec mvframe-notify --once --message "..."` after each finished development task, and copies **`/.cursor/rules/*.mdc`** from the package (same as this repo’s Cursor rules). Adds `index.html` and `vite.config.js` only if missing (use `--force` to overwrite). **Merges** `scripts` / `dependencies` / `devDependencies` into `package.json` (existing values win for shared keys), initializes `.env.mvframe-notify.example` / `.env.local.example` and `config.notify`, then runs **`yarn install`**; use `--no-package-json` to skip package changes and install. Then run **`yarn dev`** or explicitly run **`yarn exec mvframe-d`** to start Vite with the notify service.
 
 ```bash
 cd /path/to/your-app

package/dist/vendor.js

@@ -7621,7 +7621,7 @@ const Ss = (e, o = {}) => {
 }, Ts = {
   name: "Matt Avias Frame",
   copyright: "©2026",
-  version: "1.0.79",
+  version: "1.0.81",
   author: "Matt Avias",
   date: "2026-02-26",
   /** 默认语言 key，与 `$getLang`、localStorage `lang` 一致；业务在 app.use(mvframe, { config }) 里覆盖 */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mvframe",
   "packageManager": "yarn@4.4.1",
-  "version": "1.0.79",
+  "version": "1.0.81",
   "author": "matt avis",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/scripts/install-codex-agents.js

@@ -18,61 +18,73 @@ const path = require("path");
 
 const BEGIN = "<!-- MVFRAME-CODEX-RULES:BEGIN -->";
 const END = "<!-- MVFRAME-CODEX-RULES:END -->";
+const STYLE_RULES_FILE = path.join(__dirname, "..", ".cursor", "rules", "style-system.mdc");
 
-function renderCodexAgentsSection() {
-  return `${BEGIN}
-# MVFrame Codex Rules
+function stripFrontmatter(markdown) {
+  if (!markdown.startsWith("---")) {
+    return markdown;
+  }
+  const end = markdown.indexOf("\n---", 3);
+  if (end < 0) {
+    return markdown;
+  }
+  return markdown.slice(end + 4).replace(/^\s*\n/, "");
+}
 
-This project uses MVFrame. When editing Vue, JS, TS, SCSS, or CSS in this host app, prefer the framework globals before adding local implementations.
+function shiftMarkdownHeadings(markdown, level = 1) {
+  return markdown.replace(/^(#{1,6})\s+/gm, (_all, hashes) => {
+    const nextLevel = Math.min(6, hashes.length + level);
+    return `${"#".repeat(nextLevel)} `;
+  });
+}
+
+function getSharedStyleRulesForCodex() {
+  const raw = fs.readFileSync(STYLE_RULES_FILE, "utf8");
+  const withoutFrontmatter = stripFrontmatter(raw).trim();
+  const withoutRootTitle = withoutFrontmatter.replace(/^#\s+mvframe\s+样式系统\s*\n*/i, "");
+  return shiftMarkdownHeadings(withoutRootTitle, 1).trim();
+}
 
-## Global Components
+function renderCodexAgentsSection() {
+  return `${BEGIN}
+# MVFrame Codex 规则
 
-- Prefer MVFrame global components in templates without local imports: \`Frame\`, \`Page\`, \`Table\`, \`Form\`, \`Input\`, \`Textarea\`, \`Select\`, \`SelectV2\`, \`Tabs\`, \`BtnGroup\`, \`Icon\`, \`Loading\`, \`Drawer\`, \`DrawerArea\`, \`Login\`, \`Lang\`.
-- Do not rebuild an equivalent control with raw DOM, \`el-*\` combinations, or third-party components unless the MVFrame component cannot express the behavior.
-- For segmented controls, single-choice button groups, login forms, page shells, tables, drawers, loading masks, and framework navigation, check the MVFrame component first.
+本项目使用 MVFrame。在该宿主项目中编辑 Vue、JS、TS、SCSS 或 CSS 时，新增本地实现前，优先检查并复用框架已有的全局能力。
 
-## Global Style Utilities
+## 全局组件
 
-- Before writing scoped CSS, inline \`:style\`, or new SCSS utility code, check whether MVFrame global classes already cover it.
-- MVFrame styles must be imported once from the app entry: \`import "mvframe/style"\` and \`import "mvframe/style/cpt"\`. If utility classes appear missing, fix the import before duplicating CSS.
-- Prefer utility classes in templates for common layout, spacing, sizing, typography, color, border, scroll, hover, radius, and positioning work.
+- 模板内优先直接使用 MVFrame 全局组件，不要重复本地 import：\`Frame\`、\`Page\`、\`Table\`、\`Form\`、\`Input\`、\`Textarea\`、\`Select\`、\`SelectV2\`、\`Tabs\`、\`BtnGroup\`、\`Icon\`、\`Loading\`、\`Drawer\`、\`DrawerArea\`、\`Login\`、\`Lang\`。
+- 除非 MVFrame 组件确实无法表达该交互，否则不要用原生 DOM、\`el-*\` 组合或第三方组件去重造等价控件。
+- 遇到分段切换、单选按钮组、登录表单、页面外壳、表格、抽屉、加载遮罩、框架导航等场景，先检查 MVFrame 组件是否已经覆盖。
 
-Common utility classes:
+## 全局样式工具类
 
-| Need | Prefer |
-|------|--------|
-| flex layout | \`flexMode\`, \`flexV\`, \`flex1\`, \`flexGrow\`, \`noShrink\`, \`minw0\`, \`minh0\` |
-| flex alignment | \`hl\`, \`hc\`, \`hr\`, \`hb\`, \`ha\`, \`vl\`, \`vc\`, \`vr\`, \`vs\` |
-| wrapping / gaps | \`flexWrap\`, \`grid\`, \`g2\` ... \`g40\` |
-| spacing | \`p{N}\`, \`pt{N}\`, \`pr{N}\`, \`pb{N}\`, \`pl{N}\`, \`m{N}\`, \`mt{N}\`, \`mr{N}\`, \`mb{N}\`, \`ml{N}\` where N is one of \`0,2,4,6,8,10,12,16,20,24,30,32,36,40,48\` |
-| sizing | \`w{N}\`, \`h{N}\`, \`minw{N}\`, \`maxw{N}\`, \`minh{N}\`, \`maxh{N}\`, \`wp25\`, \`wp50\`, \`wp75\`, \`wp100\`, \`hp100\`, \`vh100\` |
-| text | \`fs{N}\`, \`lh{N}\`, \`fw300\`, \`fw500\`, \`fw700\`, \`txt-c\`, \`txt-r\`, \`txt-nowrap\`, \`txt-nowrap{N}\`, \`txt-wrap\`, \`txt-prewrap\` |
-| color / background | \`txt-h1\`, \`txt-h2\`, \`txt-p\`, \`txt-tip\`, \`txt-gray\`, \`txt-primary\`, \`bg-primary\`, \`bg-page-header\`, \`border\`, \`border-t\`, \`border-b\`, \`border-none\` |
-| positioning / effects | \`relative\`, \`abs\`, \`absFull\`, \`absCenter\`, \`sticky\`, \`z1\`, \`z2\`, \`z9\`, \`radius{N}\`, \`radiusP50\`, \`hover\`, \`trans-all\`, \`backdrop\` |
-| interaction / scroll | \`point\`, \`grab\`, \`yscroll\`, \`xscroll\`, \`nobar\`, \`noscroll\`, \`noselect\`, \`noevent\`, \`hide\` |
+${getSharedStyleRulesForCodex()}
 
-Spacing rule: do not add odd-pixel \`margin\` or \`padding\` such as \`3px\`, \`5px\`, \`7px\`, \`9px\`, or \`11px\`. Use the MVFrame spacing classes or rem values aligned with the spacing scale.
+## 全局方法
 
-Scoped styles are still allowed for component-specific behavior, complex selectors, custom brand visuals, third-party overrides, or values not covered by the utility system. Keep those scoped rules narrow and combine them with MVFrame classes.
+- 优先使用 MVFrame 全局方法，不要重复 import 或本地封装等价 helper：\`globalThis.$d\`、\`$fa\`、\`$fu\`、\`$pm\`、\`$db\`、\`$copy\`、\`$deepClone\`、\`$getLang\`、\`$getImg\`、\`$sc\`、\`$c.info\`。
+- 在模板里，如果这些方法已经通过 Vue globalProperties 注入，直接调用即可。
+- 对普通 JS 模块，优先使用 \`globalThis.$xxx\`；只有确实需要显式 import 时，再使用 MVFrame 的子路径导出。
 
-## Global Methods
+## 路由、Store 与 Maps
 
-- Prefer MVFrame globals instead of repeated imports or local helpers: \`globalThis.$d\`, \`$fa\`, \`$fu\`, \`$pm\`, \`$db\`, \`$copy\`, \`$deepClone\`, \`$getLang\`, \`$getImg\`, \`$sc\`, \`$c.info\`.
-- In templates, call global methods directly when they are provided through Vue globalProperties.
-- For ordinary JS modules, use \`globalThis.$xxx\` or the exported MVFrame subpath only when a direct import is explicitly needed.
+- 路由跳转优先使用 route \`name\`，不要优先写死 \`path\`。
+- 使用项目已经接好的 MVFrame store factory 模式：组件内用 \`inject("store")\`，setup 代码或守卫里用 \`import { store, pinia } from "mvframe/store"\`。
+- 涉及 MVFrame maps / i18n maps 时，优先使用 \`useMap\`、\`getMaps\`、\`patchMaps\`、\`mapLang\`、\`mapLangPath\`，来源为 \`mvframe/maps\`。
 
-## Router, Store, And Maps
+## 编辑检查清单
 
-- Prefer route \`name\` navigation over raw \`path\` navigation.
-- Use the MVFrame store factory pattern already wired by the app: \`inject("store")\` in components or \`import { store, pinia } from "mvframe/store"\` in setup code and guards.
-- For MVFrame maps/i18n maps, prefer \`useMap\`, \`getMaps\`, \`patchMaps\`, \`mapLang\`, and \`mapLangPath\` from \`mvframe/maps\`.
+- 新增结构前，先判断是否已有合适的 MVFrame 全局组件。
+- 新增 CSS 前，先判断是否已有合适的 MVFrame 工具类。
+- 引入新的 helper 库前，先判断 MVFrame 是否已经提供等价全局方法。
+- 如果最终仍需新增本地 CSS 或 helper，保持小而专，限定在当前组件范围内。
 
-## Editing Checklist
+## 完成后通知
 
-- Before adding markup, check whether a MVFrame global component fits.
-- Before adding CSS, check whether MVFrame utility classes fit.
-- Before importing a helper library, check whether a MVFrame global helper already exists.
-- If local CSS or a new helper is still needed, keep it small and specific to the component.
+- 每次完成一个开发任务后，都要在宿主项目根目录发送一条简洁的完成通知：\`yarn exec mvframe-notify --once --message "<项目或模块>: <本次改动与当前结果>"\`。
+- notify 文案保持简短、可投递、可扫读；包含受影响模块或页面、本次完成的主要工作，以及当前验证结果（如果已有）。
+- 如果缺少 \`.env.mvframe-notify\`、钉钉 notify 未配置，或命令执行失败，不要伪造成功；需要在最终回复里明确说明通知未发送成功。
 ${END}
 `;
 }

package/scripts/scaffold-app.js

@@ -924,7 +924,7 @@ await notify("需要发送到钉钉的消息");
 
 ## Codex 规则（\`AGENTS.md\`）
 
-初始化脚本会写入/更新项目根 **\`AGENTS.md\`** 的 MVFrame 区块，供 Codex 在宿主项目内优先使用 **MVFrame 全局组件、全局方法与全局样式工具类**。该区块带有 \`MVFRAME-CODEX-RULES\` 标记，重复执行脚手架会更新这段内容，不会覆盖你在 \`AGENTS.md\` 中的其它规则。
+初始化脚本会写入/更新项目根 **\`AGENTS.md\`** 的 MVFrame 区块，供 Codex 在宿主项目内优先使用 **MVFrame 全局组件、全局方法与全局样式工具类**，并要求 **每次 AI 完成开发后调用 \`yarn exec mvframe-notify --once --message "..."\` 发送完成通知**。该区块带有 \`MVFRAME-CODEX-RULES\` 标记，重复执行脚手架会更新这段内容，不会覆盖你在 \`AGENTS.md\` 中的其它规则。
 
 仅安装 Codex 规则：