mvframe 1.0.94 → 1.0.96

package/dist/vendor.js

@@ -13477,7 +13477,7 @@ const xr = (e, o = {}) => {
 }, Nr = {
   name: "Matt Avias Frame",
   copyright: "©2026",
-  version: "1.0.94",
+  version: "1.0.96",
   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.94",
+  "version": "1.0.96",
   "author": "matt avis",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -34,6 +34,7 @@
       "import": "./dist/util.js",
       "require": "./dist/util.js"
     },
+    "./style/mixin": "./src/style/chip/mixin.scss",
     "./style": "./dist/css/style.css",
     "./style/cpt": "./dist/css/cpt.css",
     "./package.json": "./package.json"
@@ -43,6 +44,8 @@
     "d": "node scripts/dev-with-notify.js",
     "notify": "node scripts/notify-server.js",
     "build": "node scripts/prebuild.js",
+    "init-rules": "node scripts/init-rules.js",
+    "install-cursor-rules": "node scripts/install-cursor-rules.js",
     "install-cursor-skill": "node scripts/install-cursor-skill.js",
     "install-codex-rules": "node scripts/install-codex-agents.js",
     "scaffold-app": "node scripts/scaffold-app.js",
@@ -53,15 +56,20 @@
     "mvframe-b": "scripts/build-host.js",
     "mvframe-d": "scripts/dev-with-notify.js",
     "mvframe-init-app": "scripts/scaffold-app.js",
+    "mvframe-init-rules": "scripts/init-rules.js",
     "mvframe-install-codex-rules": "scripts/install-codex-agents.js",
+    "mvframe-install-cursor-rules": "scripts/install-cursor-rules.js",
     "mvframe-install-cursor-skill": "scripts/install-cursor-skill.js",
     "mvframe-notify": "scripts/notify-server.js"
   },
   "files": [
     "dist/*",
+    "src/style/chip/mixin.scss",
     "scripts/build-host.js",
     "scripts/dev-with-notify.js",
+    "scripts/init-rules.js",
     "scripts/install-codex-agents.js",
+    "scripts/install-cursor-rules.js",
     "scripts/install-cursor-skill.js",
     "scripts/notify-server.js",
     "scripts/scaffold-app.js",

package/scripts/init-rules.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * 一次初始化宿主项目的 MVFrame Codex + Cursor 规则。
+ *
+ * 用法：
+ *   node path/to/mvframe/scripts/init-rules.js
+ *   node path/to/mvframe/scripts/init-rules.js /abs/path/to/your-project
+ *   yarn exec mvframe-init-rules
+ *
+ * 环境变量（可选）：
+ *   MVFRAME_INIT_RULES_OUT=/path/to/project  等价于第一个参数
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { upsertCodexAgents } = require("./install-codex-agents.js");
+const { installCursorRules } = require("./install-cursor-rules.js");
+
+function main() {
+  const argPath = process.argv.find((a, i) => i >= 2 && !a.startsWith("--"));
+  const projectRoot = path.resolve(
+    process.env.MVFRAME_INIT_RULES_OUT || argPath || process.cwd(),
+  );
+
+  if (!fs.existsSync(projectRoot)) {
+    console.error("[mvframe] 目录不存在:", projectRoot);
+    process.exit(1);
+  }
+
+  installCursorRules(projectRoot);
+  upsertCodexAgents(projectRoot);
+
+  console.log("[mvframe] 已完成 MVFrame 规则初始化：");
+  console.log("  - Cursor: .cursor/rules/*.mdc");
+  console.log("  - Codex: AGENTS.md");
+  console.log("[mvframe] 请重开 Cursor / 开启新 Codex 会话，确保新规则被重新读取。");
+}
+
+if (require.main === module) {
+  main();
+}

package/scripts/install-cursor-rules.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * 将 MVFrame 包内 `.cursor/rules/*.mdc` 补充到目标工程的 `.cursor/rules/`。
+ * 若宿主项目已存在同名规则文件，则保留宿主文件，不覆盖。
+ *
+ * 用法：
+ *   node path/to/mvframe/scripts/install-cursor-rules.js
+ *   node path/to/mvframe/scripts/install-cursor-rules.js /abs/path/to/your-project
+ *
+ * 环境变量（可选）：
+ *   MVFRAME_CURSOR_RULES_OUT=/path/to/project  等价于第一个参数
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+function installCursorRules(projectRoot) {
+  const targetRoot = path.resolve(projectRoot);
+  const rulesSrc = path.join(__dirname, "..", ".cursor", "rules");
+
+  if (!fs.existsSync(rulesSrc)) {
+    console.warn(
+      "[mvframe] 未找到包内 .cursor/rules（请使用含该目录的 mvframe 版本），跳过 Cursor 规则复制",
+    );
+    return;
+  }
+
+  const entries = fs.readdirSync(rulesSrc, { withFileTypes: true });
+  for (const ent of entries) {
+    if (!ent.isFile() || !ent.name.endsWith(".mdc")) continue;
+    const src = path.join(rulesSrc, ent.name);
+    const dest = path.join(targetRoot, ".cursor", "rules", ent.name);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    if (fs.existsSync(dest)) {
+      console.log("[mvframe] 已存在 Cursor 规则，跳过：");
+      console.log("  ", dest);
+      continue;
+    }
+    fs.copyFileSync(src, dest);
+    console.log("[mvframe] 已写入 Cursor 规则：");
+    console.log("  ", dest);
+  }
+
+  console.log("[mvframe] Cursor 打开该项目后会读取 .cursor/rules/*.mdc。");
+}
+
+function main() {
+  const argPath = process.argv.find((a, i) => i >= 2 && !a.startsWith("--"));
+  const projectRoot = path.resolve(
+    process.env.MVFRAME_CURSOR_RULES_OUT || argPath || process.cwd(),
+  );
+
+  if (!fs.existsSync(projectRoot)) {
+    console.error("[mvframe] 目录不存在:", projectRoot);
+    process.exit(1);
+  }
+
+  installCursorRules(projectRoot);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  installCursorRules,
+};

package/scripts/scaffold-app.js

@@ -17,6 +17,7 @@ const fs = require("fs");
 const path = require("path");
 const { execFileSync } = require("child_process");
 const { upsertCodexAgents } = require("./install-codex-agents.js");
+const { installCursorRules } = require("./install-cursor-rules.js");
 
 const FORCE = process.argv.includes("--force") || process.argv.includes("-f");
 const NO_PKG = process.argv.includes("--no-package-json") || process.argv.includes("-n");
@@ -54,27 +55,6 @@ function appendGitignoreLines(lines) {
   console.log("[mvframe-init] 已更新 .gitignore");
 }
 
-/**
- * 将本包 `.cursor/rules/*.mdc` 复制到目标工程，与 mvframe 仓库内 Cursor 规则保持一致。
- * 发布包需在 `package.json` 的 `files` 中包含 `.cursor/rules`。
- */
-function copyCursorRulesFromPackage() {
-  const rulesSrc = path.join(__dirname, "..", ".cursor", "rules");
-  if (!fs.existsSync(rulesSrc)) {
-    console.warn(
-      "[mvframe-init] 未找到包内 .cursor/rules（请使用含该目录的 mvframe 版本），跳过 Cursor 规则复制",
-    );
-    return;
-  }
-  const entries = fs.readdirSync(rulesSrc, { withFileTypes: true });
-  for (const ent of entries) {
-    if (!ent.isFile() || !ent.name.endsWith(".mdc")) continue;
-    const content = fs.readFileSync(path.join(rulesSrc, ent.name), "utf8");
-    const rel = path.join(".cursor", "rules", ent.name);
-    write(rel.replace(/\\/g, "/"), content);
-  }
-}
-
 /** 与 main.js / vite.config 模板一致；版本号与 mvframe 本仓库对齐思路，可随发布调整 */
 // @vue/shared 为 Vue 3 内部包，传递依赖在部分包管理器下未提升时 Vite 解析失败，故写入直连依赖
 const SCAFFOLD_DEPENDENCIES = {
@@ -187,7 +167,7 @@ function main() {
     fs.mkdirSync(path.join(target, d), { recursive: true });
   }
 
-  copyCursorRulesFromPackage();
+  installCursorRules(target);
   upsertCodexAgents(target);
   appendGitignoreLines([".env.local", ".env.mvframe-notify"]);
 
@@ -594,7 +574,8 @@ export {};
     "src/assets/style/index.scss",
     `/* 项目全局样式入口（main.js 已 import 本文件） */
 /* MVFrame：main.js 已 import "mvframe/style" 与 "mvframe/style/cpt"（发布包 CSS），勿在此处再 @import 同一路径，避免重复。 */
-/* 若需在 SCSS 内 @use 变量/mixin，可指向 node_modules 内 mvframe 源码路径或 monorepo workspace 路径。 */
+/* 若需在业务 SCSS 内复用 mvframe 断点 / mixin，直接：@use "mvframe/style/mixin" as *; */
+/* 例如：@include media-down(sm) { ... } */
 
 body {
   margin: 0;
@@ -867,6 +848,30 @@ yarn exec mvframe-d
 
 \`src/main.js\` 已包含 \`import "mvframe/style"\` 与 \`import "mvframe/style/cpt"\`（分别对应工具类/变量与 **Mvc\*** 组件 scoped 等样式），一般 **无需** 在 \`index.scss\` 再引一遍 mvframe 的 dist CSS，以免重复。项目级覆盖写在 \`src/assets/style/index.scss\` 即可。
 
+宿主项目如需在 SCSS 内复用 MVFrame 断点，直接：
+
+\`\`\`scss
+@use "mvframe/style/mixin" as *;
+
+.Panel {
+  padding: 1.5rem;
+
+  @include media-down(sm) {
+    padding: 1rem;
+  }
+}
+\`\`\`
+
+发布包的 \`mvframe/style\` 还额外提供响应式工具类：\`{断点}-{up|down|only}-{工具类}\`，如 \`md-down-hide\`、\`lg-up-flexMode\`、\`xs-only-block\`。适合直接写在 template 上；复杂宽高/间距调整仍建议在业务 SCSS 里配合 media mixin 写。
+
+做 Grid 列数切换时，也可以直接在容器上写断点列数类，例如：
+
+\`\`\`html
+<div class="grid col2 md2 lg3 sm1 g16"></div>
+\`\`\`
+
+表示默认 2 列，\`sm\` 1 列，\`md\` 2 列，\`lg\` 3 列。
+
 ## 表单 Label
 
 \`Input\`、\`Textarea\`、\`Select\`、\`SelectV2\` 支持统一的 label 接口：
@@ -951,6 +956,12 @@ await notify("需要发送到钉钉的消息");
 
 初始化脚本会写入/更新项目根 **\`AGENTS.md\`** 的 MVFrame 区块，供 Codex 在宿主项目内优先使用 **MVFrame 全局组件、全局方法与全局样式工具类**，并要求 **每次 AI 完成开发后调用 \`yarn exec mvframe-notify --once --message "..."\` 发送完成通知**。该区块带有 \`MVFRAME-CODEX-RULES\` 标记，重复执行脚手架会更新这段内容，不会覆盖你在 \`AGENTS.md\` 中的其它规则。
 
+同时初始化 Codex + Cursor 两侧规则：
+
+\`\`\`bash
+yarn exec mvframe-init-rules
+\`\`\`
+
 仅安装 Codex 规则：
 
 \`\`\`bash
@@ -959,7 +970,13 @@ yarn exec mvframe-install-codex-rules
 
 ## Cursor 规则（\`.cursor/rules\`）
 
-初始化脚本会把 **mvframe 包内**与仓库一致的 **\`*.mdc\`** 写入目标项目 **\`/.cursor/rules/\`**（\`component-hierarchy\`、\`script-setup\`、\`style-system\`、\`views\`、\`router\`、\`global-components\`、\`data\`、\`util\`）。若目录或文件已存在且未加 \`--force\` / \`-f\`，则跳过对应文件。
+初始化脚本会把 **mvframe 包内**与仓库一致的 **\`*.mdc\`** 补充到目标项目 **\`/.cursor/rules/\`**（\`component-hierarchy\`、\`script-setup\`、\`style-system\`、\`views\`、\`router\`、\`global-components\`、\`data\`、\`util\`）。若宿主项目已存在同名规则文件，则保留宿主文件，仅补缺失项。
+
+仅安装 Cursor 规则：
+
+\`\`\`bash
+yarn exec mvframe-install-cursor-rules
+\`\`\`
 
 npm 包需在 \`files\` 中包含 \`.cursor/rules\`；使用本地 \`file:\` / 源码链接时同样可用。
 

package/src/style/chip/mixin.scss

@@ -0,0 +1,141 @@
+@use "sass:list";
+@use "sass:map";
+
+// 响应式断点：xs < 40rem，sm 40rem~47.99875rem，md 48rem~63.99875rem，
+// lg 64rem~79.99875rem，xl 80rem~95.99875rem，xxl >= 96rem。
+$media-breakpoints: (
+  "xs": 0,
+  "sm": 40rem,
+  "md": 48rem,
+  "lg": 64rem,
+  "xl": 80rem,
+  "xxl": 96rem,
+) !default;
+
+@function media-breakpoint($name) {
+  $value: map.get($media-breakpoints, $name);
+  @if $value == null {
+    @error "[mvframe media] Unknown breakpoint `#{$name}`. Available: #{map.keys($media-breakpoints)}";
+  }
+  @return $value;
+}
+
+@function media-next($name) {
+  $keys: map.keys($media-breakpoints);
+  $index: list.index($keys, $name);
+
+  @if $index == null {
+    @error "[mvframe media] Unknown breakpoint `#{$name}`. Available: #{$keys}";
+  }
+  @if $index == list.length($keys) {
+    @return null;
+  }
+  @return list.nth($keys, $index + 1);
+}
+
+@function media-range-max($name) {
+  $next: media-next($name);
+  @if $next == null {
+    @return null;
+  }
+  @return calc(#{media-breakpoint($next)} - 0.02px);
+}
+
+@mixin media-up($name) {
+  $min: media-breakpoint($name);
+  @if $min == 0 {
+    @content;
+  } @else {
+    @media (min-width: #{$min}) {
+      @content;
+    }
+  }
+}
+
+@mixin media-down($name) {
+  $max: media-range-max($name);
+  @if $max == null {
+    @content;
+  } @else {
+    @media (max-width: #{$max}) {
+      @content;
+    }
+  }
+}
+
+@mixin media-only($name) {
+  $min: media-breakpoint($name);
+  $max: media-range-max($name);
+
+  @if $min == 0 and $max == null {
+    @content;
+  } @else if $min == 0 {
+    @media (max-width: #{$max}) {
+      @content;
+    }
+  } @else if $max == null {
+    @media (min-width: #{$min}) {
+      @content;
+    }
+  } @else {
+    @media (min-width: #{$min}) and (max-width: #{$max}) {
+      @content;
+    }
+  }
+}
+
+@mixin media-between($from, $to) {
+  $keys: map.keys($media-breakpoints);
+  $from-index: list.index($keys, $from);
+  $to-index: list.index($keys, $to);
+
+  @if $from-index == null or $to-index == null {
+    @error "[mvframe media] Unknown breakpoint in `media-between(#{$from}, #{$to})`. Available: #{$keys}";
+  }
+  @if $from-index > $to-index {
+    @error "[mvframe media] `media-between` expects `$from <= $to`, got `#{$from}` > `#{$to}`.";
+  }
+
+  $min: media-breakpoint($from);
+  $max: media-range-max($to);
+
+  @if $min == 0 and $max == null {
+    @content;
+  } @else if $min == 0 {
+    @media (max-width: #{$max}) {
+      @content;
+    }
+  } @else if $max == null {
+    @media (min-width: #{$min}) {
+      @content;
+    }
+  } @else {
+    @media (min-width: #{$min}) and (max-width: #{$max}) {
+      @content;
+    }
+  }
+}
+
+// 发光阴影效果：::after 伪元素，可被 @include 复用
+@mixin glow-shadow-after($css-var) {
+  position: relative;
+  isolation: isolate;
+  &::after {
+    content: "";
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    opacity: 0.25;
+    background-color: var(#{$css-var});
+    transform: translateY(20%);
+    pointer-events: none;
+    filter: blur(0.625rem);
+    z-index: -1;
+  }
+}
+@mixin hover-box-shadow() {
+  box-shadow: 0 0.5rem 0.5rem
+    color-mix(in srgb, var(--color-body) 6%, rgba(0, 0, 0, 0.05));
+}