synthia-shared/README.md

Synthia Engine Shared - 共享工具库和核心优化器

# synthia-shared

Synthia Engine Shared - 共享工具库和核心配置系统

## 功能特性

- ⚙️ **配置管理**: 统一的配置加载、验证和合并
- 🔌 **插件系统**: 完整的插件架构和生命周期管理
- 📊 **类型定义**: 共享的类型定义和接口
- 🛠️ **工具函数**: 配置验证、快速检查等实用工具

## 安装

```bash
npm install synthia-shared
```

## 使用方法

### 配置管理

```typescript
import {
  ConfigLoader,
  ConfigValidator,
  defineConfig,
  mergeConfig,
  quickValidate,
} from 'synthia-shared';

// 定义配置
const config = defineConfig({
  name: 'my-project',
  version: '1.0.0',
  description: 'My Synthia Project',
  plugins: [
    '@synthia/cache-system',
    {
      name: 'my-custom-plugin',
      options: {
        option1: 'value1',
      },
    },
  ],
});

// 加载配置
const loader = new ConfigLoader('./');
const loadedConfig = await loader.loadConfig({
  mergeDefaults: true,
  validate: true,
});

// 验证配置
const validator = new ConfigValidator();
const validation = validator.validate(config);

// 快速验证
const isValid = quickValidate(config);
```

### 插件系统

```typescript
import {
  DefaultPluginManager,
  DefaultPluginRegistry,
  SynthiaPlugin,
  PluginCommand,
} from 'synthia-shared';

// 创建插件管理器
const manager = new DefaultPluginManager({
  searchPaths: ['./plugins'],
  installDir: './node_modules',
  enabled: true,
});

// 定义插件
const myPlugin: SynthiaPlugin = {
  metadata: {
    name: 'my-plugin',
    version: '1.0.0',
    description: 'My custom plugin',
  },
  commands: [
    {
      name: 'hello',
      description: 'Say hello',
      action: options => {
        console.log('Hello from plugin!');
      },
    },
  ],
  hooks: {
    beforeBuild: async context => {
      console.log('Before build hook');
    },
  },
};

// 注册插件
await manager.registry.register(myPlugin);

// 加载插件
await manager.loadPlugin('./plugins/my-plugin.js');
```

### 类型定义

```typescript
import type {
  SynthiaConfig,
  PluginConfig,
  PluginCommand,
  BuildContext,
  DevContext,
  PluginAPI,
} from 'synthia-shared';

// 使用类型定义
const config: SynthiaConfig = {
  name: 'my-project',
  version: '1.0.0',
};

const command: PluginCommand = {
  name: 'build',
  description: 'Build the project',
  action: async options => {
    // 构建逻辑
  },
};
```

## 主要模块

### ConfigLoader

配置加载器，提供：

- 支持多种配置文件格式 (JS/TS/JSON)
- 配置文件缓存机制
- 默认配置合并
- 配置验证集成

### ConfigValidator

配置验证器，提供：

- 基本配置字段验证
- 插件配置结构验证
- 详细的错误和警告信息
- 快速验证功能

### DefaultPluginManager

插件管理器，提供：

- 插件动态加载和卸载
- 插件安装和更新
- 插件发现和注册
- 插件生命周期管理

### DefaultPluginRegistry

插件注册器，提供：

- 插件注册和注销
- 命令注册和管理
- 插件状态检查
- 命令冲突检测

### 类型定义

完整的 TypeScript 类型支持：

- `SynthiaConfig`: 主配置接口
- `PluginConfig`: 插件配置类型
- `PluginCommand`: 插件命令定义
- `BuildContext`/`DevContext`: 构建和开发上下文
- `PluginAPI`: 插件 API 接口

## API 参考

### 配置相关

#### `defineConfig(config: SynthiaConfig): SynthiaConfig`

定义 Synthia 配置对象

#### `mergeConfig(...configs: Partial<SynthiaConfig>[]): SynthiaConfig`

合并多个配置对象

#### `quickValidate(config: any): boolean`

快速验证配置是否有效

### 插件相关

#### `DefaultPluginManager`

插件管理器类，负责插件的完整生命周期管理

#### `DefaultPluginRegistry`

插件注册器类，负责插件的注册和命令管理

## 许可证

MIT