@zhin.js/client 1.0.3 → 1.0.5

package/README.md

@@ -1,16 +1,23 @@
-# Zhin Client - 动态页面路由系统
+# Zhin Client - 动态页面路由与插件配置系统
 
-基于 React Router 7.0 的动态页面管理系统，支持在 `main.tsx` 中直接进行页面路由操作。
+基于 React Router 7.0 的动态页面管理系统，集成插件配置功能，支持基于 Schema 的自动表单生成。
 
 ## 特性
 
+### 路由系统
 - 🌳 **树形路由结构** - 使用树形结构管理页面路由，支持任意深度的嵌套
 - ✅ **动态页面管理** - 运行时添加、删除、更新页面
 - ✅ **React Router 7.0** - 使用最新的 React Router
 - ✅ **TypeScript 支持** - 完整的类型定义
 - ✅ **WebSocket 集成** - 支持动态加载插件入口脚本
 - ✅ **Redux 状态管理** - 集成 Redux 持久化
-- ✅ **简单易用** - 在 `main.tsx` 中直接操作页面路由
+
+### 配置系统
+- 🔧 **Schema 驱动** - 支持 15 种 Schema 数据类型
+- 📝 **自动表单生成** - 根据 Schema 自动生成配置表单
+- 🎨 **智能 UI 组件** - 针对不同类型自动选择最佳 UI 控件
+- 🔄 **实时配置更新** - 支持配置文件的实时读取和保存
+- 🧩 **模块化设计** - 17 个独立的字段渲染器，易于扩展
 
 ## 安装
 
@@ -361,6 +368,113 @@ routerManager.onRouteAdd((route) => {
 3. **性能考虑** - 大量路由时考虑使用懒加载
 4. **类型安全** - 使用 TypeScript 确保类型安全
 
+## 插件配置系统
+
+### Schema 支持的数据类型
+
+Zhin Client 配置系统完整支持所有 15 种 Schema 数据类型：
+
+#### 基础类型
+- `string` - 字符串（支持枚举/多行/单行）
+- `number` / `integer` - 数字（支持 min/max 限制）
+- `boolean` - 布尔值（开关控件）
+
+#### 特殊类型
+- `percent` - 百分比（滑块 + 数字输入）
+- `date` - 日期（日期选择器）
+- `regexp` - 正则表达式（带验证）
+- `const` - 常量（只读显示）
+
+#### 集合类型
+- `list` - 列表（支持嵌套）
+- `tuple` - 元组（固定字段）
+- `object` - 对象（嵌套结构）
+- `dict` - 字典（JSON 编辑器）
+
+#### 组合类型
+- `union` - 联合类型（多选一）
+- `intersect` - 交叉类型（满足所有）
+
+#### 通用类型
+- `any` - 任意类型（JSON 编辑器）
+- `never` - 永不类型（警告提示）
+
+### 使用插件配置组件
+
+```tsx
+import PluginConfigForm from '@zhin.js/client/components/PluginConfigForm'
+
+<PluginConfigForm
+  pluginName="my-plugin"
+  onClose={() => setDialogOpen(false)}
+  onSuccess={() => refetchPlugin()}
+/>
+```
+
+### 定义插件配置 Schema
+
+```typescript
+import { Schema } from 'zhin.js'
+
+export const config = Schema.object({
+  // 基础类型
+  name: Schema.string('插件名称').required(),
+  enabled: Schema.boolean('是否启用').default(true),
+  port: Schema.number('端口').min(1).max(65535).default(3000),
+  
+  // 特殊类型
+  opacity: Schema.percent('透明度').default(0.8),
+  startDate: Schema.date('开始日期'),
+  pattern: Schema.regexp('匹配模式'),
+  
+  // 集合类型
+  tags: Schema.list(Schema.string(), '标签'),
+  server: Schema.object({
+    host: Schema.string().default('localhost'),
+    port: Schema.number().default(3000)
+  }),
+  
+  // 组合类型
+  mode: Schema.union([
+    Schema.const('auto'),
+    Schema.const('manual')
+  ])
+})
+```
+
+### 配置表单特性
+
+- **自动渲染**: 根据 Schema 类型自动选择合适的 UI 组件
+- **智能分组**: 简单字段直接展示，复杂字段可折叠
+- **嵌套支持**: 完整支持任意深度的嵌套结构
+- **实时验证**: 输入时进行类型验证和格式检查
+- **紧凑布局**: 使用 ScrollArea 和 Accordion 优化空间使用
+
+## 组件架构
+
+### PluginConfigForm 模块结构
+
+```
+PluginConfigForm/
+├── types.ts                      - 类型定义
+├── BasicFieldRenderers.tsx       - 基础类型渲染器 (9个)
+├── CollectionFieldRenderers.tsx  - 集合类型渲染器 (5个)
+├── CompositeFieldRenderers.tsx   - 组合类型渲染器 (2个)
+├── FieldRenderer.tsx             - 字段渲染器主入口
+├── NestedFieldRenderer.tsx       - 嵌套字段渲染器
+└── index.tsx                     - 主组件
+```
+
+17 个独立渲染器，职责单一，易于测试和扩展。
+
+## 注意事项
+
+1. **路由路径唯一性** - 确保路由路径的唯一性，避免冲突
+2. **事件清理** - 记得清理事件监听器，避免内存泄漏
+3. **性能考虑** - 大量路由时考虑使用懒加载
+4. **类型安全** - 使用 TypeScript 确保类型安全
+5. **Schema 定义** - 为插件配置定义清晰的 Schema，提供友好的描述信息
+
 ## 示例项目
 
 查看 `app/src/main.tsx` 中的完整示例。

package/{src → client}/index.ts

@@ -12,7 +12,6 @@ export * as Icons from 'lucide-react'
 
 // WebSocket
 export * from './websocket'
-export { useWebSocket } from './websocket/useWebSocket'
 
 export function cn(...inputs: ClassValue[]) {
   return twMerge(clsx(inputs))

package/{src → client}/store/index.ts

@@ -108,4 +108,25 @@ export {
     unloadScript
 } from './reducers/script'
 
-export type { RouteMenuItem } from './reducers/route'
+// 导出 Config actions 和 selectors
+export { 
+    setConnected,
+    setLoading,
+    setError,
+    updateConfig,
+    updateSchema,
+    updateConfigs,
+    updateSchemas,
+    removeConfig,
+    clearConfigs,
+    selectConfig,
+    selectSchema,
+    selectConfigLoading,
+    selectConfigError,
+    selectConfigConnected,
+    selectAllConfigs,
+    selectAllSchemas
+} from './reducers/config'
+
+export type { RouteMenuItem } from './reducers/route'
+export type { ConfigMessage } from './reducers/config'

package/client/store/reducers/config.ts

@@ -0,0 +1,135 @@
+/**
+ * 配置管理 Redux Slice
+ * 通过 WebSocket 管理插件配置
+ */
+
+import { createSlice, createAsyncThunk, PayloadAction } from '@reduxjs/toolkit'
+
+export interface ConfigState {
+  // 所有插件的配置，按插件名分发
+  configs: Record<string, any>
+  // 所有插件的 Schema，按插件名分发
+  schemas: Record<string, any>
+  // 加载状态
+  loading: Record<string, boolean>
+  // 错误信息
+  errors: Record<string, string | null>
+  // WebSocket 连接状态
+  connected: boolean
+}
+
+const initialState: ConfigState = {
+  configs: {},
+  schemas: {},
+  loading: {},
+  errors: {},
+  connected: false
+}
+
+// WebSocket 消息类型
+export interface ConfigMessage {
+  type: 'config:get' | 'config:set' | 'config:updated' | 'schema:get' | 'schema:updated'
+  pluginName: string
+  data?: any
+  error?: string
+}
+
+const configSlice = createSlice({
+  name: 'config',
+  initialState,
+  reducers: {
+    // WebSocket 连接状态
+    setConnected: (state, action: PayloadAction<boolean>) => {
+      state.connected = action.payload
+    },
+
+    // 设置配置加载状态
+    setLoading: (state, action: PayloadAction<{ pluginName: string; loading: boolean }>) => {
+      const { pluginName, loading } = action.payload
+      state.loading[pluginName] = loading
+    },
+
+    // 设置错误信息
+    setError: (state, action: PayloadAction<{ pluginName: string; error: string | null }>) => {
+      const { pluginName, error } = action.payload
+      state.errors[pluginName] = error
+    },
+
+    // 更新插件配置
+    updateConfig: (state, action: PayloadAction<{ pluginName: string; config: any }>) => {
+      const { pluginName, config } = action.payload
+      state.configs[pluginName] = config
+      state.loading[pluginName] = false
+      state.errors[pluginName] = null
+    },
+
+    // 更新插件 Schema
+    updateSchema: (state, action: PayloadAction<{ pluginName: string; schema: any }>) => {
+      const { pluginName, schema } = action.payload
+      state.schemas[pluginName] = schema
+    },
+
+    // 批量更新配置
+    updateConfigs: (state, action: PayloadAction<Record<string, any>>) => {
+      state.configs = { ...state.configs, ...action.payload }
+    },
+
+    // 批量更新 Schema
+    updateSchemas: (state, action: PayloadAction<Record<string, any>>) => {
+      state.schemas = { ...state.schemas, ...action.payload }
+    },
+
+    // 清除插件配置
+    removeConfig: (state, action: PayloadAction<string>) => {
+      const pluginName = action.payload
+      delete state.configs[pluginName]
+      delete state.schemas[pluginName]
+      delete state.loading[pluginName]
+      delete state.errors[pluginName]
+    },
+
+    // 清除所有配置
+    clearConfigs: (state) => {
+      state.configs = {}
+      state.schemas = {}
+      state.loading = {}
+      state.errors = {}
+    }
+  }
+})
+
+export const {
+  setConnected,
+  setLoading,
+  setError,
+  updateConfig,
+  updateSchema,
+  updateConfigs,
+  updateSchemas,
+  removeConfig,
+  clearConfigs
+} = configSlice.actions
+
+export default configSlice.reducer
+
+// Selectors
+export const selectConfig = (state: { config: ConfigState }, pluginName: string) => 
+  state.config.configs[pluginName]
+
+export const selectSchema = (state: { config: ConfigState }, pluginName: string) => 
+  state.config.schemas[pluginName]
+
+export const selectConfigLoading = (state: { config: ConfigState }, pluginName: string) => 
+  state.config.loading[pluginName] || false
+
+export const selectConfigError = (state: { config: ConfigState }, pluginName: string) => 
+  state.config.errors[pluginName] || null
+
+export const selectConfigConnected = (state: { config: ConfigState }) => 
+  state.config.connected
+
+export const selectAllConfigs = (state: { config: ConfigState }) => 
+  state.config.configs
+
+export const selectAllSchemas = (state: { config: ConfigState }) => 
+  state.config.schemas

package/{src → client}/store/reducers/index.ts

@@ -2,15 +2,18 @@ import { Reducer } from "@reduxjs/toolkit"
 import ui from "./ui"
 import route from "./route"
 import script from "./script"
+import config from "./config"
 
 export interface Reducers {
     ui: ReturnType<typeof ui>
     route: ReturnType<typeof route>
     script: ReturnType<typeof script>
+    config: ReturnType<typeof config>
 }
 
 export const reducers: Record<keyof Reducers, Reducer<any, any>> = {
     ui,
     route,
-    script
+    script,
+    config
 }

package/client/websocket/hooks.ts

@@ -0,0 +1,280 @@
+/**
+ * WebSocket React Hooks
+ * 提供在 React 组件中使用 WebSocket 功能的便捷接口
+ */
+
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import { 
+  useSelector, 
+  useDispatch,
+  selectConfig,
+  selectSchema,
+  selectConfigLoading,
+  selectConfigError,
+  selectConfigConnected,
+  selectAllConfigs,
+  selectAllSchemas,
+  setLoading,
+  setError
+} from '../store'
+import { getWebSocketManager } from './instance'
+import type { UseConfigOptions, UseWebSocketOptions, ConnectionState } from './types'
+
+// ============================================================================
+// WebSocket 连接 Hook
+// ============================================================================
+
+/**
+ * WebSocket 连接状态和基础功能 Hook
+ */
+export function useWebSocket(options: UseWebSocketOptions = {}) {
+  const { autoConnect = true } = options
+  
+  const wsManager = getWebSocketManager()
+  
+  // 从 Redux 获取状态
+  const connected = useSelector(selectConfigConnected)
+  const entries = useSelector((state: any) => state.script?.entries || [])
+  const loadedScripts = useSelector((state: any) => state.script?.loadedScripts || [])
+
+  // 连接控制
+  const connect = useCallback(() => {
+    wsManager.connect()
+  }, [wsManager])
+
+  const disconnect = useCallback(() => {
+    wsManager.disconnect()
+  }, [wsManager])
+
+  // 消息发送
+  const send = useCallback((message: any) => {
+    wsManager.send(message)
+  }, [wsManager])
+
+  const sendRequest = useCallback(async <T = any>(message: any): Promise<T> => {
+    // 临时使用旧方法，后续完善
+    return (wsManager as any).sendRequest(message)
+  }, [wsManager])
+
+  // 状态查询
+  const isConnected = useCallback(() => {
+    return wsManager.isConnected()
+  }, [wsManager])
+
+  const getState = useCallback(() => {
+    // 临时返回连接状态，后续完善
+    return wsManager.isConnected() ? 'connected' : 'disconnected'
+  }, [wsManager])
+
+  // 自动连接
+  useEffect(() => {
+    if (autoConnect && !connected) {
+      connect()
+    }
+  }, [autoConnect, connected, connect])
+
+  return {
+    // 状态
+    connected,
+    entries,
+    loadedScripts,
+    
+    // 方法
+    connect,
+    disconnect,
+    send,
+    sendRequest,
+    isConnected,
+    getState,
+    
+    // WebSocket 实例（高级用法）
+    manager: wsManager
+  }
+}
+
+// ============================================================================
+// 配置管理 Hook
+// ============================================================================
+
+/**
+ * 插件配置管理 Hook
+ */
+export function useConfig(pluginName: string, options: UseConfigOptions = {}) {
+  const { autoLoad = true, autoLoadSchema = true } = options
+  
+  const dispatch = useDispatch()
+  const wsManager = getWebSocketManager()
+
+  // 状态选择器
+  const config = useSelector((state: any) => selectConfig(state, pluginName))
+  const schema = useSelector((state: any) => selectSchema(state, pluginName))
+  const loading = useSelector((state: any) => selectConfigLoading(state, pluginName))
+  const error = useSelector((state: any) => selectConfigError(state, pluginName))
+  const connected = useSelector(selectConfigConnected)
+
+  // 配置操作
+  const getConfig = useCallback(async () => {
+    dispatch(setLoading({ pluginName, loading: true }))
+    dispatch(setError({ pluginName, error: null }))
+
+    try {
+      const result = await wsManager.getConfig(pluginName)
+      return result
+    } catch (error) {
+        console.log('getConfig',error)
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+      dispatch(setError({ pluginName, error: errorMessage }))
+      throw error
+    } finally {
+      dispatch(setLoading({ pluginName, loading: false }))
+    }
+  }, [pluginName, wsManager, dispatch])
+
+  const setConfig = useCallback(async (newConfig: any) => {
+    dispatch(setLoading({ pluginName, loading: true }))
+    dispatch(setError({ pluginName, error: null }))
+
+    try {
+      await wsManager.setConfig(pluginName, newConfig)
+    } catch (error) {
+        console.log('setConfig',error)
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+      dispatch(setError({ pluginName, error: errorMessage }))
+      throw error
+    } finally {
+      dispatch(setLoading({ pluginName, loading: false }))
+    }
+  }, [pluginName, wsManager, dispatch])
+
+  const getSchema = useCallback(async () => {
+    try {
+      return await wsManager.getSchema(pluginName)
+    } catch (error) {
+      console.error(`Failed to get schema for plugin ${pluginName}:`, error)
+      throw error
+    }
+  }, [pluginName, wsManager])
+
+  // 重新加载配置和 Schema
+  const reload = useCallback(async () => {
+    const promises = []
+    
+    if (autoLoad) {
+      promises.push(getConfig())
+    }
+    
+    if (autoLoadSchema) {
+      promises.push(getSchema())
+    }
+    
+    await Promise.all(promises)
+  }, [autoLoad, autoLoadSchema, getConfig, getSchema])
+
+  // 自动加载
+  useEffect(() => {
+    if (connected && autoLoad && !config && !loading) {
+      getConfig().catch(console.error)
+    }
+  }, [connected, autoLoad, config, loading, getConfig])
+
+  useEffect(() => {
+    if (connected && autoLoadSchema && !schema) {
+      getSchema().catch(console.error)
+    }
+  }, [connected, autoLoadSchema, schema, getSchema])
+
+  return useMemo(() => ({
+    // 状态
+    config,
+    schema,
+    loading,
+    error,
+    connected,
+    
+    // 方法
+    getConfig,
+    setConfig,
+    getSchema,
+    reload
+  }), [config, schema, loading, error, connected, getConfig, setConfig, getSchema, reload])
+}
+
+// ============================================================================
+// 批量配置管理 Hook
+// ============================================================================
+
+/**
+ * 所有配置管理 Hook
+ */
+export function useAllConfigs() {
+  const wsManager = getWebSocketManager()
+  
+  const allConfigs = useSelector(selectAllConfigs)
+  const allSchemas = useSelector(selectAllSchemas)
+  const connected = useSelector(selectConfigConnected)
+
+  const refreshAll = useCallback(async () => {
+    try {
+      const [configs, schemas] = await Promise.all([
+        (wsManager as any).getAllConfigs(),
+        (wsManager as any).getAllSchemas()
+      ])
+      
+      return { configs, schemas }
+    } catch (error) {
+      console.error('Failed to refresh all configs:', error)
+      throw error
+    }
+  }, [wsManager])
+
+  return useMemo(() => ({
+    configs: allConfigs,
+    schemas: allSchemas,
+    connected,
+    refreshAll
+  }), [allConfigs, allSchemas, connected, refreshAll])
+}
+
+// ============================================================================
+// 高级 Hook
+// ============================================================================
+
+/**
+ * WebSocket 连接状态监听 Hook
+ */
+export function useWebSocketState() {
+  const wsManager = getWebSocketManager()
+  const [state, setState] = useState(wsManager.getState())
+  
+  useEffect(() => {
+    const checkState = () => {
+      const newState = wsManager.getState()
+      if (newState !== state) {
+        setState(newState)
+      }
+    }
+    
+    const interval = setInterval(checkState, 1000)
+    return () => clearInterval(interval)
+  }, [wsManager, state])
+  
+  return state
+}
+
+/**
+ * WebSocket 消息监听 Hook
+ */
+export function useWebSocketMessages<T = any>(
+  filter?: (message: any) => boolean,
+  handler?: (message: T) => void
+) {
+  const [messages, setMessages] = useState<T[]>([])
+  
+  useEffect(() => {
+    const wsManager = getWebSocketManager()
+    // 这里需要扩展 WebSocketManager 来支持消息监听
+    // 暂时留空，后续可以扩展
+  }, [filter, handler])
+  
+  return messages
+}

package/client/websocket/index.ts

@@ -0,0 +1,48 @@
+/**
+ * WebSocket 客户端模块
+ * 提供统一的 WebSocket 连接管理、消息处理和 React Hook 接口
+ */
+
+// ============================================================================
+// 类型定义
+// ============================================================================
+export * from './types'
+
+// ============================================================================
+// 核心类
+// ============================================================================
+export { WebSocketManager } from './manager'
+export { MessageHandler } from './messageHandler'
+
+// ============================================================================
+// 实例管理
+// ============================================================================
+export { 
+  getWebSocketManager, 
+  destroyWebSocketManager, 
+  resetWebSocketManager 
+} from './instance'
+
+// ============================================================================
+// React Hooks
+// ============================================================================
+export { 
+  useWebSocket,
+  useConfig,
+  useAllConfigs,
+  useWebSocketState,
+  useWebSocketMessages
+} from './hooks'
+
+// ============================================================================
+// 向后兼容的导出（保持与旧代码的兼容性）
+// ============================================================================
+
+// 为了保持与现有代码的兼容性，重新导出一些常用的接口
+import { getWebSocketManager } from './instance'
+
+// 兼容旧的 useConfig 导出
+export { useConfig as useConfigLegacy } from './hooks'
+
+// 兼容旧的 WebSocketManager 默认导出
+export default getWebSocketManager

package/client/websocket/instance.ts

@@ -0,0 +1,46 @@
+/**
+ * WebSocket 实例管理
+ * 提供全局 WebSocket 管理器单例
+ */
+
+import { WebSocketManager } from './manager'
+
+// ============================================================================
+// 全局实例
+// ============================================================================
+
+let globalWebSocketManager: WebSocketManager | null = null
+
+/**
+ * 获取全局 WebSocket 管理器实例
+ */
+export function getWebSocketManager(): WebSocketManager {
+  if (!globalWebSocketManager) {
+    globalWebSocketManager = new WebSocketManager()
+    
+    // 浏览器环境下自动连接
+    if (typeof window !== 'undefined') {
+      globalWebSocketManager.connect()
+    }
+  }
+  
+  return globalWebSocketManager
+}
+
+/**
+ * 销毁全局 WebSocket 管理器
+ */
+export function destroyWebSocketManager(): void {
+  if (globalWebSocketManager) {
+    globalWebSocketManager.disconnect()
+    globalWebSocketManager = null
+  }
+}
+
+/**
+ * 重置 WebSocket 管理器（主要用于测试）
+ */
+export function resetWebSocketManager(): void {
+  destroyWebSocketManager()
+  // 下次调用 getWebSocketManager() 时会创建新实例
+}