@zhin.js/console 1.0.12 → 1.0.14

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @zhin.js/console
 
+## 1.0.14
+
+### Patch Changes
+
+- d16a69c: fix: test trust publish
+- Updated dependencies [d16a69c]
+  - @zhin.js/client@1.0.6
+  - @zhin.js/core@1.0.18
+  - @zhin.js/http@1.0.9
+
+## 1.0.13
+
+### Patch Changes
+
+- 3bc5d56: fix: 内存优化
+- Updated dependencies [3bc5d56]
+  - @zhin.js/core@1.0.17
+
 ## 1.0.12
 
 ### Patch Changes

package/README.md

@@ -24,10 +24,34 @@ Zhin 机器人框架的 Web 控制台插件，提供开发环境下的可视化
 
 ## 安装
 
+### 开发环境（完整安装）
+
 ```bash
 npm install @zhin.js/console
+# 或
+pnpm add @zhin.js/console
+```
+
+### 生产环境（轻量安装）
+
+**重要**：生产环境不需要 React、Vite 等依赖！
+
+前端代码已在构建时打包到 `dist/` 目录，运行时只需要：
+- `mime`：文件类型识别
+- `ws`：WebSocket 服务器
+
+```bash
+# 生产环境安装（自动跳过 devDependencies）
+npm install @zhin.js/console --production
+# 或
+pnpm add @zhin.js/console --prod
 ```
 
+**效果**：
+- ✅ 磁盘占用：~2MB（vs 开发环境 ~200MB）
+- ✅ 运行时内存：17MB（直接读取静态文件）
+- ✅ 依赖数量：2 个（vs 开发环境 20+ 个）
+
 ## 使用
 
 ### 基本配置
@@ -38,7 +62,7 @@ import '@zhin.js/console'
 ```
 
 插件会自动：
-1. 启动 Vite 开发服务器
+1. 启动 Vite 开发服务器（开发模式）
 2. 配置路由中间件
 3. 设置 WebSocket 连接
 4. 提供静态文件服务
@@ -50,6 +74,125 @@ import '@zhin.js/console'
 http://localhost:8086/vite/
 ```
 
+### 配置选项
+
+在 `zhin.config.yml` 中配置 console 插件：
+
+```yaml
+plugins:
+  console:
+    # 是否启用控制台插件，默认 true
+    enabled: true
+    
+    # 是否延迟加载 Vite（开发模式），默认 false
+    # false: 启动时立即加载 Vite（推荐，确保 addEntry 等功能可用）
+    # true: 首次访问时才启动 Vite（节省 ~23MB 内存，但可能导致其他插件功能异常）
+    lazyLoad: false
+```
+
+#### ⚠️ 关于 lazyLoad 的重要说明
+
+**默认值为 `false`（不延迟加载）**，原因：
+
+1. **其他插件依赖 `addEntry`**：`@zhin.js/adapter-sandbox`、`@zhin.js/adapter-icqq` 等插件需要在启动时调用 `web.addEntry()` 注册前端入口
+2. **WebSocket 需要提前准备**：实时通信功能需要 WebSocket 服务器立即可用
+3. **用户体验更好**：访问控制台时立即可用，无需等待 Vite 启动
+
+**如果你确定不需要这些功能**，可以启用延迟加载节省内存：
+```yaml
+plugins:
+  console:
+    lazyLoad: true  # 节省 ~23MB 启动内存
+```
+- ✅ 启动时内存: **18-20MB**
+- ⚠️ 首次访问控制台: **+23MB**（Vite + React 生态）
+- 💡 适合：不常访问控制台的生产环境
+
+**立即加载模式**：
+```yaml
+plugins:
+  console:
+    lazyLoad: false
+```
+- ⚠️ 启动时内存: **42MB**
+- ✅ 访问控制台: 无延迟
+- 💡 适合：频繁使用控制台的开发环境
+
+**禁用控制台**：
+```yaml
+plugins:
+  console:
+    enabled: false
+```
+- ✅ 内存: **0MB**（不加载）
+- 💡 适合：生产环境或不需要 Web 控制台
+
+## 生产环境优化
+
+### 依赖优化
+
+Console 插件采用**构建时打包**策略：
+
+**构建时**（开发环境）：
+```bash
+# 安装所有依赖（包括 React、Vite）
+pnpm install
+
+# 构建前端到 dist/ 目录
+pnpm --filter @zhin.js/console build:client
+```
+
+**运行时**（生产环境）：
+```bash
+# 只安装生产依赖（mime + ws）
+pnpm install --prod
+
+# 直接读取 dist/ 静态文件，无需 React
+NODE_ENV=production pnpm start
+```
+
+**节省效果**：
+- ✅ 磁盘空间: ~200MB → ~2MB（98% 减少）
+- ✅ 依赖数量: 20+ → 2（90% 减少）
+- ✅ 运行时内存: 保持 17MB（无额外开销）
+
+### 环境变量
+
+```bash
+# 生产模式（使用预构建的静态文件）
+NODE_ENV=production pnpm start
+
+# 开发模式（使用 Vite HMR）
+NODE_ENV=development pnpm dev
+```
+
+### 部署建议
+
+1. **仅 API 服务**：禁用 console 插件
+   ```yaml
+   plugins:
+     console:
+       enabled: false
+   ```
+
+2. **需要 Web 控制台**：使用静态模式
+   ```bash
+   # 构建前端
+   pnpm --filter @zhin.js/console build:client
+   
+   # 生产环境启动（自动使用静态文件）
+   NODE_ENV=production pnpm start
+   ```
+
+3. **开发环境**：使用完整功能
+   ```bash
+   # 安装所有依赖（包括可选依赖）
+   pnpm install
+   
+   # 开发模式启动
+   pnpm dev
+```
+
 ## 核心功能
 
 ### Web 服务器集成

package/client/src/pages/dashboard-plugin-detail.tsx

@@ -13,6 +13,10 @@ interface PluginDetail {
   description: string
   commands: Array<{
     name: string
+    desc?: string[]
+    usage?: string[]
+    examples?: string[]
+    help?: string
   }>
   components: Array<{
     name: string
@@ -210,11 +214,35 @@ export default function DashboardPluginDetail() {
               <Separator size="4" />
               <Flex direction="column" gap="2" className="max-h-60 overflow-y-auto">
                 {plugin.commands.map((cmd, index) => (
-                  <Box key={index} className="rounded-lg bg-gray-50 dark:bg-gray-900 p-2">
-                    <Flex direction="column" gap="1">
-                      <Flex align="center" gap="2">
-                        <Code size="2">{cmd.name}</Code>
-                      </Flex>
+                  <Box key={index} className="rounded-lg bg-gray-50 dark:bg-gray-900 p-3">
+                    <Flex direction="column" gap="2">
+                      <Code size="2" weight="bold">{cmd.name}</Code>
+                      
+                      {cmd.desc && cmd.desc.length > 0 && (
+                        <Flex direction="column" gap="1">
+                          {cmd.desc.map((desc, i) => (
+                            <Text key={i} size="1" color="gray">{desc}</Text>
+                          ))}
+                        </Flex>
+                      )}
+                      
+                      {cmd.usage && cmd.usage.length > 0 && (
+                        <Flex direction="column" gap="1">
+                          <Text size="1" weight="bold" color="blue">用法:</Text>
+                          {cmd.usage.map((usage, i) => (
+                            <Code key={i} size="1" variant="soft">{usage}</Code>
+                          ))}
+                        </Flex>
+                      )}
+                      
+                      {cmd.examples && cmd.examples.length > 0 && (
+                        <Flex direction="column" gap="1">
+                          <Text size="1" weight="bold" color="green">示例:</Text>
+                          {cmd.examples.map((example, i) => (
+                            <Code key={i} size="1" variant="soft" color="green">{example}</Code>
+                          ))}
+                        </Flex>
+                      )}
                     </Flex>
                   </Box>
                 ))}