Merge branch 'main' of https://github.com/vbenjs/vue-vben-admin into dev

2025-04-30 15:50:05 +08:00 · 2025-04-30 15:50:05 +08:00 · e02b5590dd
parent 6cfe9e0300 20c15f352f
commit e02b5590dd
21 changed files with 1419 additions and 931 deletions
--- a/.lintstagedrc.mjs
+++ b/.lintstagedrc.mjs
@ -15,6 +15,6 @@ export default {
  ],
  'package.json': ['prettier --cache --write'],
  '{!(package)*.json,*.code-snippets,.!(browserslist)*rc}': [
-    'prettier --cache --write--parser json',
+    'prettier --cache --write --parser json',
  ],
 };
--- a/.node-version
+++ b/.node-version
@ -1 +1 @@
-20.14.0
+22.1.0
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@ -14,7 +14,7 @@
  "editor.tabSize": 2,
  "editor.detectIndentation": false,
  "editor.cursorBlinking": "expand",
-  "editor.largeFileOptimizations": false,
+  "editor.largeFileOptimizations": true,
  "editor.accessibilitySupport": "off",
  "editor.cursorSmoothCaretAnimation": "on",
  "editor.guides.bracketPairs": "active",
@ -91,6 +91,7 @@
    "**/bower_components": true,
    "**/.turbo": true,
    "**/.idea": true,
+    "**/.vitepress": true,
    "**/tmp": true,
    "**/.git": true,
    "**/.svn": true,
@ -112,6 +113,8 @@
    "**/yarn.lock": true
  },

+  "typescript.tsserver.exclude": ["**/node_modules", "**/dist", "**/.turbo"],
+
  // search
  "search.searchEditor.singleClickBehaviour": "peekDefinition",
  "search.followSymlinks": false,
--- a/internal/vite-config/src/typing.ts
+++ b/internal/vite-config/src/typing.ts
@ -3,149 +3,328 @@ import type { ConfigEnv, PluginOption, UserConfig } from 'vite';
 import type { PluginOptions } from 'vite-plugin-dts';
 import type { Options as PwaPluginOptions } from 'vite-plugin-pwa';

+/**
+ * ImportMap 配置接口
+ * @description 用于配置模块导入映射，支持自定义导入路径和范围
+ * @example
+ * ```typescript
+ * {
+ *   imports: {
+ *     'vue': 'https://unpkg.com/vue@3.2.47/dist/vue.esm-browser.js'
+ *   },
+ *   scopes: {
+ *     'https://site.com/': {
+ *       'vue': 'https://unpkg.com/vue@3.2.47/dist/vue.esm-browser.js'
+ *     }
+ *   }
+ * }
+ * ```
+ */
 interface IImportMap {
+  /** 模块导入映射 */
  imports?: Record<string, string>;
+  /** 作用域特定的导入映射 */
  scopes?: {
    [scope: string]: Record<string, string>;
  };
 }
+
+/**
+ * 打印插件配置选项
+ * @description 用于配置控制台打印信息
+ */
 interface PrintPluginOptions {
  /**
-   * 打印的数据
+   * 打印的数据映射
+   * @description 键值对形式的数据，将在控制台打印
+   * @example
+   * ```typescript
+   * {
+   *   'App Version': '1.0.0',
+   *   'Build Time': '2024-01-01'
+   * }
+   * ```
   */
  infoMap?: Record<string, string | undefined>;
 }

+/**
+ * Nitro Mock 插件配置选项
+ * @description 用于配置 Nitro Mock 服务器的行为
+ */
 interface NitroMockPluginOptions {
  /**
-   * mock server 包名
+   * Mock 服务器包名
+   * @default '@vbenjs/nitro-mock'
   */
  mockServerPackage?: string;

  /**
-   * mock 服务端口
+   * Mock 服务端口
+   * @default 3000
   */
  port?: number;

  /**
-   * mock 日志是否打印
+   * 是否打印 Mock 日志
+   * @default false
   */
  verbose?: boolean;
 }

+/**
+ * 归档插件配置选项
+ * @description 用于配置构建产物的压缩归档
+ */
 interface ArchiverPluginOptions {
  /**
   * 输出文件名
-   * @default dist
+   * @default 'dist'
   */
  name?: string;
  /**
   * 输出目录
-   * @default .
+   * @default '.'
   */
  outputDir?: string;
 }

 /**
- * importmap 插件配置
+ * ImportMap 插件配置
+ * @description 用于配置模块的 CDN 导入
 */
 interface ImportmapPluginOptions {
  /**
   * CDN 供应商
-   * @default jspm.io
+   * @default 'jspm.io'
+   * @description 支持 esm.sh 和 jspm.io 两种 CDN 供应商
   */
  defaultProvider?: 'esm.sh' | 'jspm.io';
-  /** importmap 配置 */
+  /**
+   * ImportMap 配置数组
+   * @description 配置需要从 CDN 导入的包
+   * @example
+   * ```typescript
+   * [
+   *   { name: 'vue' },
+   *   { name: 'pinia', range: '^2.0.0' }
+   * ]
+   * ```
+   */
  importmap?: Array<{ name: string; range?: string }>;
-  /** 手动配置importmap */
+  /**
+   * 手动配置 ImportMap
+   * @description 自定义 ImportMap 配置
+   */
  inputMap?: IImportMap;
 }

 /**
- * 用于判断是否需要加载插件
+ * 条件插件配置
+ * @description 用于根据条件动态加载插件
 */
 interface ConditionPlugin {
-  // 判断条件
+  /**
+   * 判断条件
+   * @description 当条件为 true 时加载插件
+   */
  condition?: boolean;
-  // 插件对象
+  /**
+   * 插件对象
+   * @description 返回插件数组或 Promise
+   */
  plugins: () => PluginOption[] | PromiseLike<PluginOption[]>;
 }

+/**
+ * 通用插件配置选项
+ * @description 所有插件共用的基础配置
+ */
 interface CommonPluginOptions {
-  /** 是否开启devtools */
+  /**
+   * 是否开启开发工具
+   * @default false
+   */
  devtools?: boolean;
-  /** 环境变量 */
+  /**
+   * 环境变量
+   * @description 自定义环境变量
+   */
  env?: Record<string, any>;
-  /** 是否注入metadata */
+  /**
+   * 是否注入元数据
+   * @default true
+   */
  injectMetadata?: boolean;
-  /** 是否构建模式 */
+  /**
+   * 是否为构建模式
+   * @default false
+   */
  isBuild?: boolean;
-  /** 构建模式 */
+  /**
+   * 构建模式
+   * @default 'development'
+   */
  mode?: string;
-  /** 开启依赖分析 */
+  /**
+   * 是否开启依赖分析
+   * @default false
+   * @description 使用 rollup-plugin-visualizer 分析依赖
+   */
  visualizer?: boolean | PluginVisualizerOptions;
 }

+/**
+ * 应用插件配置选项
+ * @description 用于配置应用构建时的插件选项
+ */
 interface ApplicationPluginOptions extends CommonPluginOptions {
-  /** 开启后，会在打包dist同级生成dist.zip */
+  /**
+   * 是否开启压缩归档
+   * @default false
+   * @description 开启后会在打包目录生成 zip 文件
+   */
  archiver?: boolean;
-  /** 压缩归档插件配置 */
+  /**
+   * 压缩归档插件配置
+   * @description 配置压缩归档的行为
+   */
  archiverPluginOptions?: ArchiverPluginOptions;
-  /** 开启 gzip|brotli 压缩 */
+  /**
+   * 是否开启压缩
+   * @default false
+   * @description 支持 gzip 和 brotli 压缩
+   */
  compress?: boolean;
-  /** 压缩类型 */
+  /**
+   * 压缩类型
+   * @default ['gzip']
+   * @description 可选的压缩类型
+   */
  compressTypes?: ('brotli' | 'gzip')[];
-  /** 在构建的时候抽离配置文件 */
+  /**
+   * 是否抽离配置文件
+   * @default false
+   * @description 在构建时抽离配置文件
+   */
  extraAppConfig?: boolean;
-  /** 是否开启html插件  */
+  /**
+   * 是否开启 HTML 插件
+   * @default true
+   */
  html?: boolean;
-  /** 是否开启i18n */
+  /**
+   * 是否开启国际化
+   * @default false
+   */
  i18n?: boolean;
-  /** 是否开启 importmap CDN  */
+  /**
+   * 是否开启 ImportMap CDN
+   * @default false
+   */
  importmap?: boolean;
-  /** importmap 插件配置 */
+  /**
+   * ImportMap 插件配置
+   */
  importmapOptions?: ImportmapPluginOptions;
-  /** 是否注入app loading */
+  /**
+   * 是否注入应用加载动画
+   * @default true
+   */
  injectAppLoading?: boolean;
-  /** 是否注入全局scss */
+  /**
+   * 是否注入全局 SCSS
+   * @default true
+   */
  injectGlobalScss?: boolean;
-  /** 是否注入版权信息 */
+  /**
+   * 是否注入版权信息
+   * @default true
+   */
  license?: boolean;
-  /** 是否开启nitro mock */
+  /**
+   * 是否开启 Nitro Mock
+   * @default false
+   */
  nitroMock?: boolean;
-  /** nitro mock 插件配置 */
+  /**
+   * Nitro Mock 插件配置
+   */
  nitroMockOptions?: NitroMockPluginOptions;
-  /** 开启控制台自定义打印 */
+  /**
+   * 是否开启控制台打印
+   * @default false
+   */
  print?: boolean;
-  /** 打印插件配置 */
+  /**
+   * 打印插件配置
+   */
  printInfoMap?: PrintPluginOptions['infoMap'];
-  /** 是否开启pwa */
+  /**
+   * 是否开启 PWA
+   * @default false
+   */
  pwa?: boolean;
-  /** pwa 插件配置 */
+  /**
+   * PWA 插件配置
+   */
  pwaOptions?: Partial<PwaPluginOptions>;
-  /** 是否开启vxe-table懒加载 */
+  /**
+   * 是否开启 VXE Table 懒加载
+   * @default false
+   */
  vxeTableLazyImport?: boolean;
 }

+/**
+ * 库插件配置选项
+ * @description 用于配置库构建时的插件选项
+ */
 interface LibraryPluginOptions extends CommonPluginOptions {
-  /** 开启 dts 输出 */
+  /**
+   * 是否开启 DTS 输出
+   * @default true
+   * @description 生成 TypeScript 类型声明文件
+   */
  dts?: boolean | PluginOptions;
 }

+/**
+ * 应用配置选项类型
+ */
 type ApplicationOptions = ApplicationPluginOptions;

+/**
+ * 库配置选项类型
+ */
 type LibraryOptions = LibraryPluginOptions;

+/**
+ * 应用配置定义函数类型
+ * @description 用于定义应用构建配置
+ */
 type DefineApplicationOptions = (config?: ConfigEnv) => Promise<{
+  /** 应用插件配置 */
  application?: ApplicationOptions;
+  /** Vite 配置 */
  vite?: UserConfig;
 }>;

+/**
+ * 库配置定义函数类型
+ * @description 用于定义库构建配置
+ */
 type DefineLibraryOptions = (config?: ConfigEnv) => Promise<{
+  /** 库插件配置 */
  library?: LibraryOptions;
+  /** Vite 配置 */
  vite?: UserConfig;
 }>;

+/**
+ * 配置定义类型
+ * @description 应用或库的配置定义
+ */
 type DefineConfig = DefineApplicationOptions | DefineLibraryOptions;

 export type {
--- a/package.json
+++ b/package.json
@ -99,7 +99,7 @@
    "node": ">=20.10.0",
    "pnpm": ">=9.12.0"
  },
-  "packageManager": "pnpm@9.15.9",
+  "packageManager": "pnpm@10.10.0",
  "pnpm": {
    "peerDependencyRules": {
      "allowedVersions": {
--- a/packages/@core/ui-kit/form-ui/src/form-render/expandable.ts
+++ b/packages/@core/ui-kit/form-ui/src/form-render/expandable.ts
@ -2,13 +2,18 @@ import type { FormRenderProps } from '../types';

 import { computed, nextTick, onMounted, ref, useTemplateRef, watch } from 'vue';

-import { breakpointsTailwind, useBreakpoints } from '@vueuse/core';
+import {
+  breakpointsTailwind,
+  useBreakpoints,
+  useElementVisibility,
+} from '@vueuse/core';

 /**
 * 动态计算行数
 */
 export function useExpandable(props: FormRenderProps) {
  const wrapperRef = useTemplateRef<HTMLElement>('wrapperRef');
+  const isVisible = useElementVisibility(wrapperRef);
  const rowMapping = ref<Record<number, number>>({});
  // 是否已经计算过一次
  const isCalculated = ref(false);
@ -31,6 +36,7 @@ export function useExpandable(props: FormRenderProps) {
      () => props.showCollapseButton,
      () => breakpoints.active().value,
      () => props.schema?.length,
+      () => isVisible.value,
    ],
    async ([val]) => {
      if (val) {
--- a/packages/@core/ui-kit/popup-ui/src/drawer/drawer.vue
+++ b/packages/@core/ui-kit/popup-ui/src/drawer/drawer.vue
@ -82,17 +82,17 @@ const {
  zIndex,
 } = usePriorityValues(props, state);

-watch(
-  () => showLoading.value,
-  (v) => {
-    if (v && wrapperRef.value) {
-      wrapperRef.value.scrollTo({
-        // behavior: 'smooth',
-        top: 0,
-      });
-    }
-  },
-);
+// watch(
+//   () => showLoading.value,
+//   (v) => {
+//     if (v && wrapperRef.value) {
+//       wrapperRef.value.scrollTo({
+//         // behavior: 'smooth',
+//         top: 0,
+//       });
+//     }
+//   },
+// );

 function interactOutside(e: Event) {
  if (!closeOnClickModal.value || submitting.value) {
@ -266,19 +266,13 @@ const getForceMount = computed(() => {
        ref="wrapperRef"
        :class="
          cn('relative flex-1 overflow-y-auto p-3', contentClass, {
-            'overflow-hidden': showLoading,
+            'pointer-events-none': showLoading || submitting,
          })
        "
      >
-        <VbenLoading
-          v-if="showLoading || submitting"
-          class="size-full"
-          spinning
-        />
-
        <slot></slot>
      </div>
-
+      <VbenLoading v-if="showLoading || submitting" spinning />
      <SheetFooter
        v-if="showFooter"
        :class="
--- a/packages/@core/ui-kit/popup-ui/src/modal/modal.vue
+++ b/packages/@core/ui-kit/popup-ui/src/modal/modal.vue
@ -123,17 +123,17 @@ watch(
  { immediate: true },
 );

-watch(
-  () => [showLoading.value, submitting.value],
-  ([l, s]) => {
-    if ((s || l) && wrapperRef.value) {
-      wrapperRef.value.scrollTo({
-        // behavior: 'smooth',
-        top: 0,
-      });
-    }
-  },
-);
+// watch(
+//   () => [showLoading.value, submitting.value],
+//   ([l, s]) => {
+//     if ((s || l) && wrapperRef.value) {
+//       wrapperRef.value.scrollTo({
+//         // behavior: 'smooth',
+//         top: 0,
+//       });
+//     }
+//   },
+// );

 function handleFullscreen() {
  props.modalApi?.setState((prev) => {
@ -274,18 +274,13 @@ function handleClosed() {
        ref="wrapperRef"
        :class="
          cn('relative min-h-40 flex-1 overflow-y-auto p-3', contentClass, {
-            'overflow-hidden': showLoading || submitting,
+            'pointer-events-none': showLoading || submitting,
          })
        "
      >
-        <VbenLoading
-          v-if="showLoading || submitting"
-          class="size-full h-auto min-h-full"
-          spinning
-        />
        <slot></slot>
      </div>
-
+      <VbenLoading v-if="showLoading || submitting" spinning />
      <VbenIconButton
        v-if="fullscreenButton"
        class="hover:bg-accent hover:text-accent-foreground text-foreground/80 flex-center absolute right-10 top-3 hidden size-6 rounded-full px-1 text-lg opacity-70 transition-opacity hover:opacity-100 focus:outline-none disabled:pointer-events-none sm:block"
--- a/packages/effects/access/src/accessible.ts
+++ b/packages/effects/access/src/accessible.ts
@ -42,7 +42,15 @@ async function generateAccessible(
        delete route.component;
      }
      // 根据router name判断，如果路由已经存在，则不再添加
-      if (!names?.includes(route.name)) {
+      if (names?.includes(route.name)) {
+        // 找到已存在的路由索引并更新，不更新会造成切换用户时，一级目录未更新，homePath 在二级目录导致的404问题
+        const index = root.children?.findIndex(
+          (item) => item.name === route.name,
+        );
+        if (index !== undefined && index !== -1 && root.children) {
+          root.children[index] = route;
+        }
+      } else {
        root.children?.push(route);
      }
    } else {
--- a/packages/effects/common-ui/src/components/page/page.vue
+++ b/packages/effects/common-ui/src/components/page/page.vue
@ -12,7 +12,8 @@ defineOptions({
  name: 'Page',
 });

-const { autoContentHeight = false } = defineProps<PageProps>();
+const { autoContentHeight = false, heightOffset = 0 } =
+  defineProps<PageProps>();

 const headerHeight = ref(0);
 const footerHeight = ref(0);
@ -26,7 +27,7 @@ const docRef = useTemplateRef<HTMLDivElement>('docRef');
 const contentStyle = computed<StyleValue>(() => {
  if (autoContentHeight) {
    return {
-      height: `calc(var(${CSS_VARIABLE_LAYOUT_CONTENT_HEIGHT}) - ${headerHeight.value}px - ${docHeight.value}px)`,
+      height: `calc(var(${CSS_VARIABLE_LAYOUT_CONTENT_HEIGHT}) - ${headerHeight.value}px - ${docHeight.value}px - ${typeof heightOffset === 'number' ? `${heightOffset}px` : heightOffset})`,
      overflowY: shouldAutoHeight.value ? 'auto' : 'unset',
    };
  }
--- a/packages/effects/common-ui/src/components/page/types.ts
+++ b/packages/effects/common-ui/src/components/page/types.ts
@ -8,4 +8,10 @@ export interface PageProps {
  autoContentHeight?: boolean;
  headerClass?: string;
  footerClass?: string;
+  /**
+   * Custom height offset value (in pixels) to adjust content area sizing
+   * when used with autoContentHeight
+   * @default 0
+   */
+  heightOffset?: number;
 }
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@ -30,13 +30,13 @@ catalog:
  '@intlify/unplugin-vue-i18n': ^6.0.8
  '@jspm/generator': ^2.5.1
  '@manypkg/get-packages': ^2.2.2
-  '@nolebase/vitepress-plugin-git-changelog': ^2.16.0
+  '@nolebase/vitepress-plugin-git-changelog': ^2.17.0
  '@playwright/test': ^1.52.0
  '@pnpm/workspace.read-manifest': ^1000.1.4
  '@stylistic/stylelint-plugin': ^3.1.2
  '@tailwindcss/nesting': 0.0.0-insiders.565cd3e
  '@tailwindcss/typography': ^0.5.16
-  '@tanstack/vue-query': ^5.74.6
+  '@tanstack/vue-query': ^5.74.7
  '@tanstack/vue-store': ^0.7.0
  '@tinymce/tinymce-vue': ^6.1.0
  '@form-create/ant-design-vue': ^3.2.22
@ -114,7 +114,7 @@ catalog:
  find-up: ^7.0.0
  get-port: ^7.1.0
  globals: ^16.0.0
-  h3: ^1.15.1
+  h3: ^1.15.3
  happy-dom: ^17.4.4
  html-minifier-terser: ^7.2.0
  husky: ^9.1.7
@ -129,7 +129,7 @@ catalog:
  lucide-vue-next: ^0.503.0
  medium-zoom: ^1.1.0
  naive-ui: ^2.41.0
-  nitropack: ^2.11.9
+  nitropack: ^2.11.11
  nprogress: ^0.2.0
  ora: ^8.2.0
  pinia: ^3.0.2
@ -180,7 +180,7 @@ catalog:
  vite-plugin-html: ^3.2.2
  vite-plugin-lazy-import: ^1.0.7
  vite-plugin-pwa: ^1.0.0
-  vite-plugin-vue-devtools: ^7.7.5
+  vite-plugin-vue-devtools: ^7.7.6
  vitepress: ^1.6.3
  vitepress-plugin-group-icons: ^1.5.2
  vitest: ^3.1.2
@ -193,7 +193,7 @@ catalog:
  vue-tippy: ^6.7.0
  vue-tsc: 2.1.10
  vxe-pc-ui: ^4.5.14
-  vxe-table: ^4.12.5
+  vxe-table: ^4.13.14
  watermark-js-plus: ^1.6.0
  zod: ^3.24.3
  zod-defaults: ^0.1.3
--- a/scripts/clean.mjs
+++ b/scripts/clean.mjs
@ -1,31 +1,33 @@
 import { promises as fs } from 'node:fs';
-import { join } from 'node:path';
+import { join, normalize } from 'node:path';

 const rootDir = process.cwd();

 /**
 * 递归查找并删除目标目录
 * @param {string} currentDir - 当前遍历的目录路径
+ * @param {string[]} targets - 要删除的目标列表
 */
 async function cleanTargetsRecursively(currentDir, targets) {
  const items = await fs.readdir(currentDir);

  for (const item of items) {
    try {
-      const itemPath = join(currentDir, item);
+      const itemPath = normalize(join(currentDir, item));
+      const stat = await fs.lstat(itemPath);
+
      if (targets.includes(item)) {
        // 匹配到目标目录或文件时直接删除
        await fs.rm(itemPath, { force: true, recursive: true });
        console.log(`Deleted: ${itemPath}`);
-      }
-      const stat = await fs.lstat(itemPath);
-      if (stat.isDirectory()) {
+      } else if (stat.isDirectory()) {
+        // 只对目录进行递归处理
        await cleanTargetsRecursively(itemPath, targets);
      }
-    } catch {
-      // console.error(
-      //   `Error handling item ${item} in ${currentDir}: ${error.message}`,
-      // );
+    } catch (error) {
+      console.error(
+        `Error handling item ${item} in ${currentDir}: ${error.message}`,
+      );
    }
  }
 }
@ -33,9 +35,9 @@ async function cleanTargetsRecursively(currentDir, targets) {
 (async function startCleanup() {
  // 要删除的目录及文件名称
  const targets = ['node_modules', 'dist', '.turbo', 'dist.zip'];
-
  const deleteLockFile = process.argv.includes('--del-lock');
  const cleanupTargets = [...targets];
+
  if (deleteLockFile) {
    cleanupTargets.push('pnpm-lock.yaml');
  }
@ -46,8 +48,9 @@ async function cleanTargetsRecursively(currentDir, targets) {

  try {
    await cleanTargetsRecursively(rootDir, cleanupTargets);
-    console.log('Cleanup process completed.');
+    console.log('Cleanup process completed successfully.');
  } catch (error) {
    console.error(`Unexpected error during cleanup: ${error.message}`);
+    process.exit(1);
  }
 })();
--- a/scripts/deploy/Dockerfile
+++ b/scripts/deploy/Dockerfile
@ -1,4 +1,4 @@
-FROM node:20-slim AS builder
+FROM node:22-slim AS builder

 # --max-old-space-size
 ENV PNPM_HOME="/pnpm"
@ -13,6 +13,7 @@ WORKDIR /app
 # copy package.json and pnpm-lock.yaml to workspace
 COPY . /app

+# 安装依赖
 RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install --frozen-lockfile
 RUN pnpm run build --filter=\!./docs

@ -20,12 +21,17 @@ RUN echo "Builder Success 🎉"

 FROM nginx:stable-alpine AS production

-RUN echo "types { application/javascript js mjs; }" > /etc/nginx/conf.d/mjs.conf
+# 配置 nginx
+RUN echo "types { application/javascript js mjs; }" > /etc/nginx/conf.d/mjs.conf \
+    && rm -rf /etc/nginx/conf.d/default.conf
+
+# 复制构建产物
 COPY --from=builder /app/playground/dist /usr/share/nginx/html

+# 复制 nginx 配置
 COPY --from=builder /app/scripts/deploy/nginx.conf /etc/nginx/nginx.conf

 EXPOSE 8080

-# start nginx
+# 启动 nginx
 CMD ["nginx", "-g", "daemon off;"]
--- a/scripts/turbo-run/README.md
+++ b/scripts/turbo-run/README.md
@ -1,3 +1,59 @@
 # @vben/turbo-run

-turbo-run is a command line tool that allows you to run multiple commands in parallel.
+`turbo-run` 是一个命令行工具，允许你在多个包中并行运行命令。它提供了一个交互式的界面，让你可以选择要运行命令的包。
+
+## 特性
+
+- 🚀 交互式选择要运行的包
+- 📦 支持 monorepo 项目结构
+- 🔍 自动检测可用的命令
+- 🎯 精确过滤目标包
+
+## 安装
+
+```bash
+pnpm add -D @vben/turbo-run
+```
+
+## 使用方法
+
+基本语法：
+
+```bash
+turbo-run [script]
+```
+
+例如，如果你想运行 `dev` 命令：
+
+```bash
+turbo-run dev
+```
+
+工具会自动检测哪些包有 `dev` 命令，并提供一个交互式界面让你选择要运行的包。
+
+## 示例
+
+假设你的项目中有以下包：
+
+- `@vben/app`
+- `@vben/admin`
+- `@vben/website`
+
+当你运行：
+
+```bash
+turbo-run dev
+```
+
+工具会：
+
+1. 检测哪些包有 `dev` 命令
+2. 显示一个交互式选择界面
+3. 让你选择要运行命令的包
+4. 使用 `pnpm --filter` 在选定的包中运行命令
+
+## 注意事项
+
+- 确保你的项目使用 pnpm 作为包管理器
+- 确保目标包在 `package.json` 中定义了相应的脚本命令
+- 该工具需要在 monorepo 项目的根目录下运行
--- a/scripts/turbo-run/src/run.ts
+++ b/scripts/turbo-run/src/run.ts
@ -25,7 +25,7 @@ export async function run(options: RunOptions) {

  let selectPkg: string | symbol;
  if (selectPkgs.length > 1) {
-    selectPkg = await select<any, string>({
+    selectPkg = await select<string>({
      message: `Select the app you need to run [${command}]:`,
      options: selectPkgs.map((item) => ({
        label: item?.packageJson.name,
--- a/scripts/vsh/README.md
+++ b/scripts/vsh/README.md
@ -1,3 +1,56 @@
 # @vben/vsh

-shell 脚本工具集合
+一个 Shell 脚本工具集合，用于 Vue Vben Admin 项目的开发和管理。
+
+## 功能特性
+
+- 🚀 基于 Node.js 的现代化 Shell 工具
+- 📦 支持模块化开发和按需加载
+- 🔍 提供依赖检查和分析功能
+- 🔄 支持循环依赖扫描
+- 📝 提供包发布检查功能
+
+## 安装
+
+```bash
+# 使用 pnpm 安装
+pnpm add -D @vben/vsh
+
+# 或者使用 npm
+npm install -D @vben/vsh
+
+# 或者使用 yarn
+yarn add -D @vben/vsh
+```
+
+## 使用方法
+
+### 全局安装
+
+```bash
+# 全局安装
+pnpm add -g @vben/vsh
+
+# 使用 vsh 命令
+vsh [command]
+```
+
+### 本地使用
+
+```bash
+# 在 package.json 中添加脚本
+{
+  "scripts": {
+    "vsh": "vsh"
+  }
+}
+
+# 运行命令
+pnpm vsh [command]
+```
+
+## 命令列表
+
+- `vsh check-deps`: 检查项目依赖
+- `vsh scan-circular`: 扫描循环依赖
+- `vsh publish-check`: 检查包发布配置
--- a/scripts/vsh/src/check-circular/index.ts
+++ b/scripts/vsh/src/check-circular/index.ts
@ -4,77 +4,167 @@ import { extname } from 'node:path';

 import { getStagedFiles } from '@vben/node-utils';

-import { circularDepsDetect, printCircles } from 'circular-dependency-scanner';
+import { circularDepsDetect } from 'circular-dependency-scanner';

-const IGNORE_DIR = [
-  'dist',
-  '.turbo',
-  'output',
-  '.cache',
-  'scripts',
-  'internal',
-  'packages/effects/request/src/',
-  'packages/@core/ui-kit/menu-ui/src/',
-  'packages/@core/ui-kit/popup-ui/src/',
-].join(',');
+// 默认配置
+const DEFAULT_CONFIG = {
+  allowedExtensions: ['.cjs', '.js', '.jsx', '.mjs', '.ts', '.tsx', '.vue'],
+  ignoreDirs: [
+    'dist',
+    '.turbo',
+    'output',
+    '.cache',
+    'scripts',
+    'internal',
+    'packages/effects/request/src/',
+    'packages/@core/ui-kit/menu-ui/src/',
+    'packages/@core/ui-kit/popup-ui/src/',
+  ],
+  threshold: 0, // 循环依赖的阈值
+} as const;

-const IGNORE = [`**/{${IGNORE_DIR}}/**`];
+// 类型定义
+type CircularDependencyResult = string[];
+
+interface CheckCircularConfig {
+  allowedExtensions?: string[];
+  ignoreDirs?: string[];
+  threshold?: number;
+}

 interface CommandOptions {
+  config?: CheckCircularConfig;
  staged: boolean;
  verbose: boolean;
 }

-async function checkCircular({ staged, verbose }: CommandOptions) {
-  const results = await circularDepsDetect({
-    absolute: staged,
-    cwd: process.cwd(),
-    ignore: IGNORE,
+// 缓存机制
+const cache = new Map<string, CircularDependencyResult[]>();
+
+/**
+ * 格式化循环依赖的输出
+ * @param circles - 循环依赖结果
+ */
+function formatCircles(circles: CircularDependencyResult[]): void {
+  if (circles.length === 0) {
+    console.log('✅ No circular dependencies found');
+    return;
+  }
+
+  console.log('⚠️ Circular dependencies found:');
+  circles.forEach((circle, index) => {
+    console.log(`\nCircular dependency #${index + 1}:`);
+    circle.forEach((file) => console.log(`  → ${file}`));
  });
+}

-  if (staged) {
-    let files = await getStagedFiles();
+/**
+ * 检查项目中的循环依赖
+ * @param options - 检查选项
+ * @param options.staged - 是否只检查暂存区文件
+ * @param options.verbose - 是否显示详细信息
+ * @param options.config - 自定义配置
+ * @returns Promise<void>
+ */
+async function checkCircular({
+  config = {},
+  staged,
+  verbose,
+}: CommandOptions): Promise<void> {
+  try {
+    // 合并配置
+    const finalConfig = {
+      ...DEFAULT_CONFIG,
+      ...config,
+    };

-    const allowedExtensions = new Set([
-      '.cjs',
-      '.js',
-      '.jsx',
-      '.mjs',
-      '.ts',
-      '.tsx',
-      '.vue',
-    ]);
+    // 生成忽略模式
+    const ignorePattern = `**/{${finalConfig.ignoreDirs.join(',')}}/**`;

-    // 过滤文件列表
-    files = files.filter((file) => allowedExtensions.has(extname(file)));
+    // 检查缓存
+    const cacheKey = `${staged}-${process.cwd()}-${ignorePattern}`;
+    if (cache.has(cacheKey)) {
+      const cachedResults = cache.get(cacheKey);
+      if (cachedResults) {
+        verbose && formatCircles(cachedResults);
+      }
+      return;
+    }

-    const circularFiles: string[][] = [];
+    // 检测循环依赖
+    const results = await circularDepsDetect({
+      absolute: staged,
+      cwd: process.cwd(),
+      ignore: [ignorePattern],
+    });

-    for (const file of files) {
-      for (const result of results) {
-        const resultFiles = result.flat();
-        if (resultFiles.includes(file)) {
-          circularFiles.push(result);
+    if (staged) {
+      let files = await getStagedFiles();
+      const allowedExtensions = new Set(finalConfig.allowedExtensions);
+
+      // 过滤文件列表
+      files = files.filter((file) => allowedExtensions.has(extname(file)));
+
+      const circularFiles: CircularDependencyResult[] = [];
+
+      for (const file of files) {
+        for (const result of results) {
+          const resultFiles = result.flat();
+          if (resultFiles.includes(file)) {
+            circularFiles.push(result);
+          }
        }
      }
+
+      // 更新缓存
+      cache.set(cacheKey, circularFiles);
+      verbose && formatCircles(circularFiles);
+    } else {
+      // 更新缓存
+      cache.set(cacheKey, results);
+      verbose && formatCircles(results);
    }
-    verbose && printCircles(circularFiles);
-  } else {
-    verbose && printCircles(results);
+
+    // 如果发现循环依赖，只输出警告信息
+    if (results.length > 0) {
+      console.log(
+        '\n⚠️ Warning: Circular dependencies found, please check and fix',
+      );
+    }
+  } catch (error) {
+    console.error(
+      '❌ Error checking circular dependencies:',
+      error instanceof Error ? error.message : error,
+    );
  }
 }

-function defineCheckCircularCommand(cac: CAC) {
+/**
+ * 定义检查循环依赖的命令
+ * @param cac - CAC实例
+ */
+function defineCheckCircularCommand(cac: CAC): void {
  cac
    .command('check-circular')
-    .option(
-      '--staged',
-      'Whether it is the staged commit mode, in which mode, if there is a circular dependency, an alarm will be given.',
-    )
-    .usage(`Analysis of project circular dependencies.`)
-    .action(async ({ staged }) => {
-      await checkCircular({ staged, verbose: true });
+    .option('--staged', 'Only check staged files')
+    .option('--verbose', 'Show detailed information')
+    .option('--threshold <number>', 'Threshold for circular dependencies', {
+      default: 0,
+    })
+    .option('--ignore-dirs <dirs>', 'Directories to ignore, comma separated')
+    .usage('Analyze project circular dependencies')
+    .action(async ({ ignoreDirs, staged, threshold, verbose }) => {
+      const config: CheckCircularConfig = {
+        threshold: Number(threshold),
+        ...(ignoreDirs && { ignoreDirs: ignoreDirs.split(',') }),
+      };
+
+      await checkCircular({
+        config,
+        staged,
+        verbose: verbose ?? true,
+      });
    });
 }

-export { defineCheckCircularCommand };
+export { type CheckCircularConfig, defineCheckCircularCommand };
--- a/scripts/vsh/src/check-dep/index.ts
+++ b/scripts/vsh/src/check-dep/index.ts
@ -4,82 +4,192 @@ import { getPackages } from '@vben/node-utils';

 import depcheck from 'depcheck';

-async function runDepcheck() {
-  const { packages } = await getPackages();
-  await Promise.all(
-    packages.map(async (pkg) => {
-      if (
-        [
-          '@vben/backend-mock',
-          '@vben/commitlint-config',
-          '@vben/eslint-config',
-          '@vben/lint-staged-config',
-          '@vben/node-utils',
-          '@vben/prettier-config',
-          '@vben/stylelint-config',
-          '@vben/tailwind-config',
-          '@vben/tsconfig',
-          '@vben/vite-config',
-          '@vben/vite-config',
-          '@vben/vsh',
-        ].includes(pkg.packageJson.name)
-      ) {
-        return;
-      }
+// 默认配置
+const DEFAULT_CONFIG = {
+  // 需要忽略的依赖匹配
+  ignoreMatches: [
+    'vite',
+    'vitest',
+    'unbuild',
+    '@vben/tsconfig',
+    '@vben/vite-config',
+    '@vben/tailwind-config',
+    '@types/*',
+    '@vben-core/design',
+  ],
+  // 需要忽略的包
+  ignorePackages: [
+    '@vben/backend-mock',
+    '@vben/commitlint-config',
+    '@vben/eslint-config',
+    '@vben/lint-staged-config',
+    '@vben/node-utils',
+    '@vben/prettier-config',
+    '@vben/stylelint-config',
+    '@vben/tailwind-config',
+    '@vben/tsconfig',
+    '@vben/vite-config',
+    '@vben/vsh',
+  ],
+  // 需要忽略的文件模式
+  ignorePatterns: ['dist', 'node_modules', 'public'],
+};

-      const unused = await depcheck(pkg.dir, {
-        ignoreMatches: [
-          'vite',
-          'vitest',
-          'unbuild',
-          '@vben/tsconfig',
-          '@vben/vite-config',
-          '@vben/tailwind-config',
-          '@types/*',
-          '@vben-core/design',
-        ],
-        ignorePatterns: ['dist', 'node_modules', 'public'],
-      });
-
-      // 删除file:前缀的依赖提示，该依赖是本地依赖
-      Reflect.deleteProperty(unused.missing, 'file:');
-      Object.keys(unused.missing).forEach((key) => {
-        unused.missing[key] = (unused.missing[key] || []).filter(
-          (item: string) => !item.startsWith('/'),
-        );
-        if (unused.missing[key].length === 0) {
-          Reflect.deleteProperty(unused.missing, key);
-        }
-      });
-
-      if (
-        Object.keys(unused.missing).length === 0 &&
-        unused.dependencies.length === 0 &&
-        unused.devDependencies.length === 0
-      ) {
-        return;
-      }
-      console.error(
-        '\n',
-        pkg.packageJson.name,
-        '\n missing:',
-        unused.missing,
-        '\n dependencies:',
-        unused.dependencies,
-        '\n devDependencies:',
-        unused.devDependencies,
-      );
-    }),
-  );
+interface DepcheckResult {
+  dependencies: string[];
+  devDependencies: string[];
+  missing: Record<string, string[]>;
 }

-function defineDepcheckCommand(cac: CAC) {
+interface DepcheckConfig {
+  ignoreMatches?: string[];
+  ignorePackages?: string[];
+  ignorePatterns?: string[];
+}
+
+interface PackageInfo {
+  dir: string;
+  packageJson: {
+    name: string;
+  };
+}
+
+/**
+ * 清理依赖检查结果
+ * @param unused - 依赖检查结果
+ */
+function cleanDepcheckResult(unused: DepcheckResult): void {
+  // 删除file:前缀的依赖提示，该依赖是本地依赖
+  Reflect.deleteProperty(unused.missing, 'file:');
+
+  // 清理路径依赖
+  Object.keys(unused.missing).forEach((key) => {
+    unused.missing[key] = (unused.missing[key] || []).filter(
+      (item: string) => !item.startsWith('/'),
+    );
+    if (unused.missing[key].length === 0) {
+      Reflect.deleteProperty(unused.missing, key);
+    }
+  });
+}
+
+/**
+ * 格式化依赖检查结果
+ * @param pkgName - 包名
+ * @param unused - 依赖检查结果
+ */
+function formatDepcheckResult(pkgName: string, unused: DepcheckResult): void {
+  const hasIssues =
+    Object.keys(unused.missing).length > 0 ||
+    unused.dependencies.length > 0 ||
+    unused.devDependencies.length > 0;
+
+  if (!hasIssues) {
+    return;
+  }
+
+  console.log('\n📦 Package:', pkgName);
+
+  if (Object.keys(unused.missing).length > 0) {
+    console.log('❌ Missing dependencies:');
+    Object.entries(unused.missing).forEach(([dep, files]) => {
+      console.log(`  - ${dep}:`);
+      files.forEach((file) => console.log(`    → ${file}`));
+    });
+  }
+
+  if (unused.dependencies.length > 0) {
+    console.log('⚠️ Unused dependencies:');
+    unused.dependencies.forEach((dep) => console.log(`  - ${dep}`));
+  }
+
+  if (unused.devDependencies.length > 0) {
+    console.log('⚠️ Unused devDependencies:');
+    unused.devDependencies.forEach((dep) => console.log(`  - ${dep}`));
+  }
+}
+
+/**
+ * 运行依赖检查
+ * @param config - 配置选项
+ */
+async function runDepcheck(config: DepcheckConfig = {}): Promise<void> {
+  try {
+    const finalConfig = {
+      ...DEFAULT_CONFIG,
+      ...config,
+    };
+
+    const { packages } = await getPackages();
+
+    let hasIssues = false;
+
+    await Promise.all(
+      packages.map(async (pkg: PackageInfo) => {
+        // 跳过需要忽略的包
+        if (finalConfig.ignorePackages.includes(pkg.packageJson.name)) {
+          return;
+        }
+
+        const unused = await depcheck(pkg.dir, {
+          ignoreMatches: finalConfig.ignoreMatches,
+          ignorePatterns: finalConfig.ignorePatterns,
+        });
+
+        cleanDepcheckResult(unused);
+
+        const pkgHasIssues =
+          Object.keys(unused.missing).length > 0 ||
+          unused.dependencies.length > 0 ||
+          unused.devDependencies.length > 0;
+
+        if (pkgHasIssues) {
+          hasIssues = true;
+          formatDepcheckResult(pkg.packageJson.name, unused);
+        }
+      }),
+    );
+
+    if (!hasIssues) {
+      console.log('\n✅ Dependency check completed, no issues found');
+    }
+  } catch (error) {
+    console.error(
+      '❌ Dependency check failed:',
+      error instanceof Error ? error.message : error,
+    );
+  }
+}
+
+/**
+ * 定义依赖检查命令
+ * @param cac - CAC实例
+ */
+function defineDepcheckCommand(cac: CAC): void {
  cac
    .command('check-dep')
-    .usage(`Analysis of project circular dependencies.`)
-    .action(async () => {
-      await runDepcheck();
+    .option(
+      '--ignore-packages <packages>',
+      'Packages to ignore, comma separated',
+    )
+    .option(
+      '--ignore-matches <matches>',
+      'Dependency patterns to ignore, comma separated',
+    )
+    .option(
+      '--ignore-patterns <patterns>',
+      'File patterns to ignore, comma separated',
+    )
+    .usage('Analyze project dependencies')
+    .action(async ({ ignoreMatches, ignorePackages, ignorePatterns }) => {
+      const config: DepcheckConfig = {
+        ...(ignorePackages && { ignorePackages: ignorePackages.split(',') }),
+        ...(ignoreMatches && { ignoreMatches: ignoreMatches.split(',') }),
+        ...(ignorePatterns && { ignorePatterns: ignorePatterns.split(',') }),
+      };
+
+      await runDepcheck(config);
    });
 }

-export { defineDepcheckCommand };
+export { defineDepcheckCommand, type DepcheckConfig };
--- a/scripts/vsh/src/index.ts
+++ b/scripts/vsh/src/index.ts
@ -2,40 +2,73 @@ import { colors, consola } from '@vben/node-utils';

 import { cac } from 'cac';

+import { version } from '../package.json';
 import { defineCheckCircularCommand } from './check-circular';
 import { defineDepcheckCommand } from './check-dep';
 import { defineCodeWorkspaceCommand } from './code-workspace';
 import { defineLintCommand } from './lint';
 import { definePubLintCommand } from './publint';

-try {
-  const vsh = cac('vsh');
+// 命令描述
+const COMMAND_DESCRIPTIONS = {
+  'check-circular': 'Check for circular dependencies',
+  'check-dep': 'Check for unused dependencies',
+  'code-workspace': 'Manage VS Code workspace settings',
+  lint: 'Run linting on the project',
+  publint: 'Check package.json files for publishing standards',
+} as const;

-  // vsh lint
-  defineLintCommand(vsh);
+/**
+ * Initialize and run the CLI
+ */
+async function main(): Promise<void> {
+  try {
+    const vsh = cac('vsh');

-  // vsh publint
-  definePubLintCommand(vsh);
+    // Register commands
+    defineLintCommand(vsh);
+    definePubLintCommand(vsh);
+    defineCodeWorkspaceCommand(vsh);
+    defineCheckCircularCommand(vsh);
+    defineDepcheckCommand(vsh);

-  // vsh code-workspace
-  defineCodeWorkspaceCommand(vsh);
+    // Handle invalid commands
+    vsh.on('command:*', ([cmd]) => {
+      consola.error(
+        colors.red(`Invalid command: ${cmd}`),
+        '\n',
+        colors.yellow('Available commands:'),
+        '\n',
+        Object.entries(COMMAND_DESCRIPTIONS)
+          .map(([cmd, desc]) => `  ${colors.cyan(cmd)} - ${desc}`)
+          .join('\n'),
+      );
+      process.exit(1);
+    });

-  // vsh check-circular
-  defineCheckCircularCommand(vsh);
+    // Set up CLI
+    vsh.usage('vsh <command> [options]');
+    vsh.help();
+    vsh.version(version);

-  // vsh check-dep
-  defineDepcheckCommand(vsh);
-
-  // Invalid command
-  vsh.on('command:*', () => {
-    consola.error(colors.red('Invalid command!'));
+    // Parse arguments
+    vsh.parse();
+  } catch (error) {
+    consola.error(
+      colors.red('An unexpected error occurred:'),
+      '\n',
+      error instanceof Error ? error.message : error,
+    );
    process.exit(1);
-  });
-
-  vsh.usage('vsh');
-  vsh.help();
-  vsh.parse();
-} catch (error) {
-  consola.error(error);
-  process.exit(1);
+  }
 }
+
+// Run the CLI
+main().catch((error) => {
+  consola.error(
+    colors.red('Failed to start CLI:'),
+    '\n',
+    error instanceof Error ? error.message : error,
+  );
+  process.exit(1);
+});
 @ -1 +1 @@
 .14.0
 .1.0