@zhin.js/console 1.0.7 → 1.0.8

package/README.md

@@ -15,11 +15,12 @@ Zhin 机器人框架的 Web 控制台插件，提供开发环境下的可视化
 ## 技术架构
 
 - **构建工具**: Vite 7.x
-- **前端框架**: Vue 3 + TypeScript
+- **前端框架**: React 18 + React Router 7 + TypeScript
+- **UI 组件库**: Radix UI + Tailwind CSS
+- **状态管理**: Redux Toolkit + Redux Persist
 - **开发服务器**: 集成到 Koa 路由
 - **WebSocket**: 实时数据同步
-- **组件解析**: unplugin-vue-components
-- **UI组件**: PrimeVue 自动导入
+- **构建优化**: Vendor Chunks 分割，支持插件复用公共依赖
 
 ## 安装
 
@@ -55,13 +56,30 @@ http://localhost:8086/vite/
 
 ```typescript
 interface WebServer {
-  vite: ViteDevServer           // Vite开发服务器
+  vite?: ViteDevServer           // Vite开发服务器
   addEntry(entry: string): () => void  // 添加入口文件
   entries: Record<string, string>      // 入口文件映射
   ws: WebSocketServer          // WebSocket服务器
 }
 ```
 
+### 构建优化
+
+Console 插件采用智能的构建优化策略，显著减少重复打包：
+
+- **Vendor Chunks 分割**: 将公共依赖分割成独立的 JS 文件
+  - `vendor-react.js` - React 核心库 (~190KB)
+  - `vendor-ui.js` - UI 组件库 (~250KB)
+  - `vendor-redux.js` - 状态管理 (~23KB)
+  - 其他分组...
+
+- **插件依赖复用**: 其他插件构建时自动外部化公共依赖
+  - 插件体积减少 ~90% (从 650KB → 30KB)
+  - 浏览器缓存复用，提升加载速度
+  - 开发和生产环境统一体验
+
+详见 [BUILD_OPTIMIZATION.md](./BUILD_OPTIMIZATION.md)
+
 ### 实时数据同步
 
 - 📡 WebSocket 连接管理
@@ -82,20 +100,45 @@ interface WebServer {
 
 ```javascript
 {
-  root: '@zhin.js/client/app',
+  root: 'plugins/console/client',
   base: '/vite/',
   plugins: [
-    vue(),
-    Components({
-      resolvers: [PrimeVueResolver()]
-    })
+    react(),
+    tailwindcss()
   ],
   server: {
     middlewareMode: true
+  },
+  build: {
+    rollupOptions: {
+      output: {
+        manualChunks: {
+          // 自动分割 vendor chunks
+          'vendor-react': ['react', 'react-dom'],
+          'vendor-ui': ['@radix-ui/themes', 'lucide-react'],
+          'vendor-redux': ['@reduxjs/toolkit', 'redux-persist'],
+          // ...
+        }
+      }
+    }
   }
 }
 ```
 
+### 插件客户端构建
+
+使用 `zhin-client` 工具构建插件客户端代码：
+
+```bash
+# 在插件目录下
+npx zhin-client build
+
+# 或使用相对路径
+node ../../plugins/console/lib/bin.js build
+```
+
+配置会自动外部化公共依赖，生成轻量级的插件代码。
+
 ### 路由配置
 
 - 支持所有路由通过 Vite 处理
@@ -108,18 +151,38 @@ interface WebServer {
 ### 项目结构
 
 ```
-src/
-├── index.ts             # 主入口，集成Vite服务器
-└── types/               # TypeScript类型定义
+console/
+├── app/                 # 构建工具
+│   ├── index.ts        # Console 插件主入口
+│   ├── build.ts        # 构建逻辑 (buildConsoleClient, buildPluginClient)
+│   ├── dev.ts          # Vite 开发服务器
+│   ├── websocket.ts    # WebSocket 管理
+│   └── bin.ts          # CLI 工具
+├── client/             # 前端应用
+│   ├── src/            # React 应用源码
+│   ├── index.html      # SPA 入口
+│   └── ...
+├── dist/               # 构建产物
+│   ├── assets/
+│   │   ├── vendor-react-*.js       # React vendor chunk
+│   │   ├── vendor-ui-*.js          # UI vendor chunk
+│   │   └── ...
+│   └── index.html
+└── lib/                # TypeScript 编译产物
 ```
 
 ### 构建
 
 ```bash
-npm run build  # 构建插件
-npm run clean  # 清理构建文件
+npm run build         # 构建插件 (TypeScript)
+npm run build:client  # 构建客户端 (React SPA)
+npm run clean         # 清理构建文件
 ```
 
+构建产物说明：
+- `lib/` - Node.js 运行的插件代码
+- `dist/` - 浏览器加载的客户端代码，包含分割的 vendor chunks
+
 ## WebSocket API
 
 ### 消息类型
@@ -138,16 +201,18 @@ npm run clean  # 清理构建文件
 ## 依赖项
 
 ### 核心依赖
-- `@vitejs/plugin-vue` - Vue插件支持
-- `koa-connect` - Koa中间件集成
-- `vue` - Vue框架
+- `@vitejs/plugin-react` - React 插件支持
+- `@tailwindcss/vite` - Tailwind CSS 集成
+- `koa-connect` - Koa 中间件集成
+- `react` / `react-dom` - React 框架
+- `react-router` - 路由管理
+- `@reduxjs/toolkit` - 状态管理
+- `@radix-ui/themes` - UI 组件库
 - `vite` - 构建工具
 
 ### 对等依赖
-- `@zhin.js/client` - 客户端代码
-- `@zhin.js/http` - HTTP服务器
-- `unplugin-vue-components` - 组件自动导入
-- `@primevue/auto-import-resolver` - PrimeVue组件解析
+- `@zhin.js/client` - 客户端基础库
+- `@zhin.js/http` - HTTP 服务器
 
 ## 使用场景
 

package/app/bin.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+import { buildCurrentPlugin, buildConsoleClient } from "./build.js";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+async function main() {
+  try {
+    switch (command) {
+      case "build":
+        // 构建当前目录的插件客户端代码
+        console.log("🔨 Building plugin client...");
+        await buildCurrentPlugin();
+        break;
+
+      case "build:console":
+        // 构建 console 插件的客户端代码
+        console.log("🔨 Building console client...");
+        const consoleRoot = path.resolve(
+          path.dirname(fileURLToPath(import.meta.url)),
+          ".."
+        );
+        await buildConsoleClient({ consoleRoot });
+        break;
+
+      default:
+        console.log(`
+Zhin.js Client Builder
+
+Usage:
+  zhin-client build          Build current plugin's client code
+  zhin-client build:console  Build console plugin's client code (SPA mode)
+
+Examples:
+  # Build a plugin (single file mode)
+  cd my-plugin && zhin-client build
+
+  # Build console (SPA mode)
+  zhin-client build:console
+        `);
+        process.exit(1);
+    }
+  } catch (error) {
+    console.error("❌ Build failed:", error);
+    process.exit(1);
+  }
+}
+
+main();

package/app/build.ts

@@ -0,0 +1,211 @@
+import { build, searchForWorkspaceRoot } from "vite";
+import react from "@vitejs/plugin-react";
+import tailwindcss from "@tailwindcss/vite";
+import path from "path";
+import fs from "fs";
+
+export interface BuildOptions {
+  /** 插件根目录 */
+  pluginRoot: string;
+  /** 输出目录，默认为 pluginRoot/dist */
+  outDir?: string;
+  /** 是否启用 tailwindcss，默认 true */
+  enableTailwind?: boolean;
+}
+
+export interface ConsoleBuildOptions {
+  /** Console 插件根目录 */
+  consoleRoot: string;
+  /** 输出目录，默认为 consoleRoot/dist */
+  outDir?: string;
+}
+
+/**
+ * 查找插件的客户端入口文件
+ * @param pluginRoot 插件根目录
+ * @returns 入口文件路径，如果不存在则返回 null
+ */
+function findClientEntry(pluginRoot: string): string | null {
+  const possibleEntries = [
+    path.join(pluginRoot, "client/index.tsx"),
+    path.join(pluginRoot, "client/index.ts"),
+    path.join(pluginRoot, "src/main.tsx"),
+    path.join(pluginRoot, "src/main.ts"),
+  ];
+
+  for (const entry of possibleEntries) {
+    if (fs.existsSync(entry)) {
+      return entry;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * 验证构建环境
+ * @param pluginRoot 插件根目录
+ * @throws 如果环境不满足构建要求
+ */
+function validateBuildEnvironment(pluginRoot: string): void {
+  if (!fs.existsSync(pluginRoot)) {
+    throw new Error(`Plugin root directory does not exist: ${pluginRoot}`);
+  }
+
+  const entry = findClientEntry(pluginRoot);
+  if (!entry) {
+    throw new Error(
+      `No client entry file found in ${pluginRoot}. Looking for: client/index.tsx, client/index.ts, src/main.tsx, or src/main.ts`
+    );
+  }
+}
+
+/**
+ * 构建插件的客户端代码（单文件模式）
+ * 用于构建普通插件的 client/index.tsx 文件
+ * 
+ * 策略：将公共依赖配置为 external，运行时从 console 加载的 vendor chunks 中复用
+ * @param options 构建选项
+ */
+export async function buildPluginClient(options: BuildOptions): Promise<void> {
+  const {
+    pluginRoot,
+    outDir = path.join(pluginRoot, "dist"),
+    enableTailwind = true,
+  } = options;
+
+  // 验证构建环境
+  validateBuildEnvironment(pluginRoot);
+
+  const entry = findClientEntry(pluginRoot);
+  if (!entry) {
+    throw new Error(`No client entry file found in ${pluginRoot}`);
+  }
+
+  const plugins = [react()];
+  if (enableTailwind) {
+    plugins.push(tailwindcss());
+  }
+
+  // 构建配置 - 库模式
+  const clientRoot = path.dirname(entry);
+
+  await build({
+    root: clientRoot,
+    plugins,
+    build: {
+      outDir,
+      emptyOutDir: true,
+      lib: {
+        entry,
+        formats: ["es"],
+        fileName: "index",
+      },
+      rollupOptions: {
+        makeAbsoluteExternalsRelative: true,
+        external:[
+          'react',
+          'react-dom',
+          'react/jsx-runtime',
+          'clsx',
+          'tailwind-merge',
+          'lucide-react',
+          '@radix-ui/themes'
+        ],
+      },
+    },
+    resolve:{
+      dedupe: [
+        "react",
+        "react-dom",
+        "clsx",
+        "tailwind-merge",
+      ],
+      alias: {
+        "@": path.resolve(pluginRoot, "client/src"),
+      },
+    }
+  });
+
+  console.log(`✅ Plugin client code built successfully: ${outDir}`);
+  console.log(`📦 External dependencies will be loaded from console vendor chunks`);
+}
+
+/**
+ * 构建 Console 插件的客户端代码（SPA 应用模式）
+ * Console 有完整的 index.html 和 src 目录结构
+ * @param options Console 构建选项
+ */
+export async function buildConsoleClient(
+  options: ConsoleBuildOptions
+): Promise<void> {
+  const { consoleRoot, outDir = path.join(consoleRoot, "dist") } = options;
+
+  const clientRoot = path.join(consoleRoot, "client");
+
+  // 检查 client 目录是否存在
+  if (!fs.existsSync(clientRoot)) {
+    throw new Error(`Console client directory does not exist: ${clientRoot}`);
+  }
+
+  // 检查 index.html 是否存在
+  const indexHtml = path.join(clientRoot, "index.html");
+  if (!fs.existsSync(indexHtml)) {
+    throw new Error(`index.html not found in: ${clientRoot}`);
+  }
+
+  const workspaceRoot = searchForWorkspaceRoot(consoleRoot);
+  const consoleClientRoot=path.resolve(workspaceRoot, "plugins/client/client")
+  const plugins = [react(), tailwindcss()];
+
+  await build({
+    root: clientRoot,
+    plugins,
+    build: {
+      outDir,
+      emptyOutDir: true,
+      // 设置最小 chunk 大小，避免过度分割
+      chunkSizeWarningLimit: 1000,
+      // SPA 应用模式，不是库模式
+      rollupOptions: {
+        input: indexHtml,
+        // 保留导出签名
+        preserveEntrySignatures: 'strict',
+        output: {
+          // 确保文件名稳定，不使用哈希，方便插件引用
+          chunkFileNames: '[name].js',
+          entryFileNames: '[name].js',
+          assetFileNames: '[name].[ext]',
+        },
+      },
+    },
+    resolve: {
+      dedupe: [
+        "react",
+        "react-dom",
+        "clsx",
+        "tailwind-merge",
+        "@reduxjs/toolkit",
+        "react-router",
+        "react-redux",
+        "redux-persist",
+      ],
+      alias: {
+        "@zhin.js/client": consoleClientRoot,
+        "@": path.resolve(clientRoot, "src"),
+      },
+    },
+  });
+
+  console.log(`✅ Console client built successfully: ${outDir}`);
+}
+
+/**
+ * 构建当前目录的插件客户端代码
+ */
+export async function buildCurrentPlugin(): Promise<void> {
+  const currentDir = process.cwd();
+  await buildPluginClient({
+    pluginRoot: currentDir,
+  });
+}

package/app/dev.ts

@@ -0,0 +1,83 @@
+import { ViteDevServer, createServer, searchForWorkspaceRoot } from "vite";
+import react from "@vitejs/plugin-react";
+import tailwindcss from "@tailwindcss/vite";
+import path from "path";
+
+export interface DevServerOptions {
+  /** 客户端代码根目录 */
+  root: string;
+  /** 基础路径，默认 /vite/ */
+  base?: string;
+  /** 是否启用 tailwindcss，默认 true */
+  enableTailwind?: boolean;
+}
+
+/**
+ * 创建 Vite 开发服务器
+ * @param options 开发服务器选项
+ * @returns Vite 开发服务器实例
+ */
+export async function createViteDevServer(
+  options: DevServerOptions
+): Promise<ViteDevServer> {
+  const { root, base = "/vite/", enableTailwind = true } = options;
+
+  const plugins = [react()];
+  if (enableTailwind) {
+    plugins.push(tailwindcss());
+  }
+
+  return await await createServer({
+    root,
+    base,
+    plugins: [react(), tailwindcss()],
+    server: {
+      middlewareMode: true,
+      fs: {
+        strict: false,
+        // 添加文件访问过滤，避免访问特殊文件
+        allow: [
+          // 允许访问的目录
+          root,
+          searchForWorkspaceRoot(root),
+          path.resolve(process.cwd(), 'node_modules'),
+          path.resolve(process.cwd(), 'client'),
+          path.resolve(process.cwd(), 'src'),
+        ],
+        // 拒绝访问某些文件模式
+        deny: [
+          '**/.git/**',
+          '**/node_modules/.cache/**',
+          '**/*.socket',
+          '**/*.pipe',
+          '**/Dockerfile*',
+          '**/.env*',
+        ],
+      },
+    },
+    resolve: {
+      dedupe: [
+        "react",
+        "react-dom",
+        "clsx",
+        "tailwind-merge",
+        "@reduxjs/toolkit",
+        "react-router",
+        "react-redux",
+        "redux-persist",
+      ],
+      alias: {
+        "@zhin.js/client": path.resolve(root, "../../client/client"),
+        "@": path.resolve(root, "../client/src"),
+      },
+    },
+    optimizeDeps: {
+      include: ["react", "react-dom"],
+    },
+    build: {
+      rollupOptions: {
+        input: root + "/index.html",
+      },
+    },
+  });
+}