@jsonstudio/rcc 0.89.1205 → 0.89.1457

package/docs/refactoring/compatibility-v2-architecture-design.md

@@ -0,0 +1,738 @@
+# Compatibility V2 架构设计方案
+
+## 🎯 设计目标
+
+基于Provider V2的成功架构模式，设计全新的Compatibility V2模块，实现：
+- **配置驱动的转换引擎** - 输入输出双向转换表驱动
+- **Hook系统集成** - 完整的hook生命周期支持
+- **模块化架构** - 清晰的职责分离和可扩展性
+- **向后兼容** - 与现有系统完全兼容
+
+## 🏗️ 整体架构设计
+
+### 架构对比图
+
+```mermaid
+graph TB
+    subgraph "当前Compatibility V1 (问题状态)"
+        A1[glm-compatibility.ts 643行] --> |硬编码逻辑| B1[固定转换]
+        A2[field-mapping.ts 180行] --> |10种类型| B2[复杂映射]
+        A3[各provider兼容层] --> |重复实现| B3[代码重复]
+
+        style A1 fill:#ffcccc
+        style A2 fill:#ffcccc
+        style A3 fill:#ffcccc
+    end
+
+    subgraph "Compatibility V2 (目标架构)"
+        C1[BaseCompatibility] --> D1[配置驱动引擎]
+        C2[TransformationEngine] --> D2[双向转换表]
+        C3[HookIntegration] --> D3[生命周期hooks]
+        C4[ProfileRegistry] --> D4[provider配置档案]
+
+        style C1 fill:#ccffcc
+        style C2 fill:#ccffcc
+        style C3 fill:#ccffcc
+        style C4 fill:#ccffcc
+    end
+```
+
+## 📁 目录结构设计
+
+### 完整目录结构
+```
+（历史实现，已下线）src/providers/compat/v2/
+├── core/                           # 核心抽象层
+│   ├── base-compatibility.ts       # 基础兼容性抽象类
+│   ├── compatibility-factory.ts    # 兼容性工厂
+│   └── standard-compatibility.ts   # 标准兼容性实现
+├── engine/                         # 转换引擎
+│   ├── transformation-engine.ts    # 配置驱动转换引擎
+│   ├── bidirectional-mapper.ts     # 双向映射器
+│   └── field-transformer.ts        # 字段转换器
+├── config/                         # 配置系统
+│   ├── compatibility-profiles.ts   # Provider配置档案
+│   ├── transformation-tables.ts    # 转换表定义
+│   └── compatibility-hooks.ts      # Hook配置
+├── hooks/                          # Hook系统
+│   ├── hooks-integration.ts        # Hook系统集成
+│   ├── compatibility-hooks.ts      # 兼容性专用hooks
+│   └── hook-executor.ts            # Hook执行器
+├── strategies/                     # 转换策略
+│   ├── chat-http-provider.ts       # OpenAI Chat 协议 Provider
+│   ├── glm-strategy.ts             # GLM特定策略
+│   ├── qwen-strategy.ts            # Qwen特定策略
+│   └── iflow-strategy.ts           # Iflow特定策略
+├── utils/                          # 工具类
+│   ├── schema-validator.ts         # Schema验证器
+│   ├── type-converter.ts           # 类型转换器
+│   └── debug-helper.ts             # 调试助手
+├── api/                            # API定义
+│   ├── compatibility-types.ts      # 类型定义
+│   ├── transformation-config.ts    # 转换配置接口
+│   └── hook-config.ts              # Hook配置接口
+└── test/                           # 测试文件
+    ├── unit/                       # 单元测试
+    ├── integration/                # 集成测试
+    └── fixtures/                   # 测试数据
+```
+
+## 🔧 核心组件设计
+
+### 1. BaseCompatibility 基础抽象类
+
+**历史文件**: `src/providers/compat/v2/core/base-compatibility.ts`（现由 `sharedmodule/llmswitch-core/src/conversion/compat/*` 取代）
+**职责**: 提供兼容性模块的通用抽象实现
+
+```typescript
+export abstract class BaseCompatibility implements ICompatibilityV2 {
+  readonly id: string;
+  readonly abstract type: string;
+  readonly config: CompatibilityConfig;
+
+  protected dependencies: ModuleDependencies;
+  protected transformationEngine: TransformationEngine;
+  protected hookIntegration: HookIntegration;
+  protected profile: CompatibilityProfile;
+
+  constructor(config: CompatibilityConfig, dependencies: ModuleDependencies) {
+    this.id = `compatibility-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    this.config = config;
+    this.dependencies = dependencies;
+
+    // 初始化核心组件
+    this.profile = this.loadCompatibilityProfile();
+    this.transformationEngine = new TransformationEngine(this.profile);
+    this.hookIntegration = new HookIntegration(dependencies, this.id);
+  }
+
+  // 抽象方法 - 子类实现
+  protected abstract loadCompatibilityProfile(): CompatibilityProfile;
+  protected abstract createStrategy(): TransformationStrategy;
+
+  // 通用实现
+  async initialize(): Promise<void> {
+    await this.transformationEngine.initialize();
+    await this.hookIntegration.initialize();
+    await this.onInitialize();
+  }
+
+  async processIncoming(request: UnknownObject): Promise<UnknownObject> {
+    const context = this.createContext('incoming');
+
+    // Hook: 请求预处理
+    const preprocessedRequest = await this.hookIntegration.executeHook(
+      'incoming_preprocessing',
+      request,
+      context
+    );
+
+    // 配置驱动转换
+    const transformedRequest = await this.transformationEngine.transform(
+      preprocessedRequest,
+      'incoming',
+      this.createStrategy()
+    );
+
+    // Hook: 转换后处理
+    const finalRequest = await this.hookIntegration.executeHook(
+      'incoming_postprocessing',
+      transformedRequest,
+      context
+    );
+
+    return finalRequest;
+  }
+
+  async processOutgoing(response: UnknownObject): Promise<UnknownObject> {
+    const context = this.createContext('outgoing');
+
+    // Hook: 响应预处理
+    const preprocessedResponse = await this.hookIntegration.executeHook(
+      'outgoing_preprocessing',
+      response,
+      context
+    );
+
+    // 配置驱动转换
+    const transformedResponse = await this.transformationEngine.transform(
+      preprocessedResponse,
+      'outgoing',
+      this.createStrategy()
+    );
+
+    // Hook: 响应后处理
+    const finalResponse = await this.hookIntegration.executeHook(
+      'outgoing_postprocessing',
+      transformedResponse,
+      context
+    );
+
+    return finalResponse;
+  }
+}
+```
+
+> 注：自 ProviderComposite 引入后，生产蓝图不再显式编排 compatibility 节点，兼容处理在 Provider 内部通过 composite 执行；
+> 现有兼容模块（GLM/LMStudio/iFlow 等）可被 openai-family 聚合器以“适配器”方式复用，职责保持为最小字段修剪/映射/黑名单，避免工具语义和 SSE 路径改动。
+
+### 2. 配置驱动转换引擎
+
+**历史文件**: `src/providers/compat/v2/engine/transformation-engine.ts`
+**职责**: 基于配置表的双向转换引擎
+
+```typescript
+export class TransformationEngine {
+  private profile: CompatibilityProfile;
+  private bidirectionalMapper: BidirectionalMapper;
+  private fieldTransformer: FieldTransformer;
+
+  constructor(profile: CompatibilityProfile) {
+    this.profile = profile;
+    this.bidirectionalMapper = new BidirectionalMapper(profile.transformationTables);
+    this.fieldTransformer = new FieldTransformer(profile.fieldConfig);
+  }
+
+  async transform(
+    data: UnknownObject,
+    direction: 'incoming' | 'outgoing',
+    strategy: TransformationStrategy
+  ): Promise<UnknownObject> {
+    // 1. 获取转换表
+    const transformationTable = this.getTransformationTable(direction, strategy.getType());
+
+    // 2. 执行字段映射
+    const mappedData = await this.bidirectionalMapper.map(data, transformationTable);
+
+    // 3. 执行类型转换
+    const transformedData = await this.fieldTransformer.transform(mappedData, direction);
+
+    // 4. 应用策略特定逻辑
+    const strategyProcessedData = await strategy.process(transformedData, direction);
+
+    return strategyProcessedData;
+  }
+
+  private getTransformationTable(
+    direction: 'incoming' | 'outgoing',
+    providerType: string
+  ): TransformationTable {
+    const tables = this.profile.transformationTables;
+
+    if (direction === 'incoming') {
+      return tables.incoming[providerType] || tables.incoming.default;
+    } else {
+      return tables.outgoing[providerType] || tables.outgoing.default;
+    }
+  }
+}
+```
+
+### 3. 双向转换表配置
+
+**历史文件**: `src/providers/compat/v2/config/transformation-tables.ts`
+**职责**: 定义输入输出双向转换配置
+
+```typescript
+export interface TransformationTable {
+  name: string;
+  description: string;
+  version: string;
+  fieldMappings: FieldMapping[];
+  typeConversions: TypeConversion[];
+  conditionalRules: ConditionalRule[];
+}
+
+export interface FieldMapping {
+  sourcePath: string;        // 源字段路径 (如: "usage.prompt_tokens")
+  targetPath: string;        // 目标字段路径 (如: "usage.input_tokens")
+  direction: 'bidirectional' | 'incoming-only' | 'outgoing-only';
+  transform?: string;        // 转换函数名称 (可选)
+  required?: boolean;        // 是否必需字段
+  defaultValue?: any;        // 默认值
+}
+
+export interface TypeConversion {
+  sourceType: string;        // 源类型 (如: "string")
+  targetType: string;        // 目标类型 (如: "number")
+  conversionFunction: string; // 转换函数名称
+  conditions?: {             // 转换条件
+    field?: string;
+    value?: any;
+  };
+}
+
+// GLM Provider 转换表示例
+export const GLM_TRANSFORMATION_TABLES: Record<string, TransformationTable> = {
+  incoming: {
+    name: 'glm-incoming',
+    description: 'GLM请求转换表',
+    version: '1.0.0',
+    fieldMappings: [
+      {
+        sourcePath: 'model',
+        targetPath: 'model',
+        direction: 'bidirectional',
+        required: true
+      },
+      {
+        sourcePath: 'thinking',
+        targetPath: 'thinking.enabled',
+        direction: 'incoming-only',
+        transform: 'convertThinkingConfig'
+      },
+      {
+        sourcePath: 'max_tokens',
+        targetPath: 'max_tokens',
+        direction: 'bidirectional',
+        typeConversion: 'ensureNumber'
+      }
+    ],
+    typeConversions: [
+      {
+        sourceType: 'string',
+        targetType: 'number',
+        conversionFunction: 'stringToNumber',
+        conditions: {
+          field: 'max_tokens'
+        }
+      }
+    ],
+    conditionalRules: [
+      {
+        condition: 'model.startsWith("glm-thinking")',
+        action: 'enableThinkingMode'
+      }
+    ]
+  },
+
+  outgoing: {
+    name: 'glm-outgoing',
+    description: 'GLM响应转换表',
+    version: '1.0.0',
+    fieldMappings: [
+      {
+        sourcePath: 'usage.prompt_tokens',
+        targetPath: 'usage.input_tokens',
+        direction: 'outgoing-only'
+      },
+      {
+        sourcePath: 'usage.completion_tokens',
+        targetPath: 'usage.output_tokens',
+        direction: 'outgoing-only'
+      },
+      {
+        sourcePath: 'usage.total_tokens',
+        targetPath: 'usage.total_tokens',
+        direction: 'bidirectional'
+      },
+      {
+        sourcePath: 'created_at',
+        targetPath: 'created',
+        direction: 'outgoing-only',
+        typeConversion: 'timestampToUnix'
+      },
+      {
+        sourcePath: 'reasoning_content',
+        targetPath: 'reasoning_content',
+        direction: 'outgoing-only',
+        transform: 'processReasoningContent'
+      }
+    ],
+    typeConversions: [],
+    conditionalRules: []
+  }
+};
+```
+
+### 4. Hook系统集成
+
+**历史文件**: `src/providers/compat/v2/hooks/hooks-integration.ts`
+**职责**: 集成兼容性模块的hook系统
+
+```typescript
+export class HookIntegration {
+  private dependencies: ModuleDependencies;
+  private compatibilityId: string;
+  private hookSystem: any;
+  private registeredHooks: Map<string, CompatibilityHook> = new Map();
+
+  constructor(dependencies: ModuleDependencies, compatibilityId: string) {
+    this.dependencies = dependencies;
+    this.compatibilityId = compatibilityId;
+  }
+
+  async initialize(): Promise<void> {
+    // 初始化hook系统 (复用provider v2的hook系统)
+    const { createHooksSystem } = require('../../../../hooks/index.js');
+
+    this.hookSystem = createHooksSystem({
+      maxConcurrentHooks: 8,
+      executionTimeout: 3000,
+      enableHealthCheck: true,
+      snapshotEnabled: true,
+      debugMode: true
+    });
+
+    await this.hookSystem.initialize();
+    await this.registerDefaultHooks();
+  }
+
+  async executeHook(
+    hookName: string,
+    data: UnknownObject,
+    context: CompatibilityContext
+  ): Promise<UnknownObject> {
+    const hook = this.registeredHooks.get(hookName);
+    if (!hook) {
+      return data; // 如果hook不存在，直接返回原数据
+    }
+
+    try {
+      const result = await this.hookSystem.hookManager.executeHook({
+        name: hookName,
+        stage: hook.stage,
+        target: hook.target,
+        priority: hook.priority,
+        async execute(ctx: any, payload: any) {
+          return await hook.execute(payload, context);
+        }
+      }, 'compatibility-v2');
+
+      return result.data || data;
+    } catch (error) {
+      this.dependencies.logger?.logModule(this.compatibilityId, 'hook-execution-error', {
+        hookName,
+        error: error instanceof Error ? error.message : String(error)
+      });
+
+      // 快速失败原则 - 不做fallback
+      throw error;
+    }
+  }
+
+  private async registerDefaultHooks(): Promise<void> {
+    // 注册默认hooks
+    await this.registerHook({
+      name: 'request-validation',
+      stage: 'incoming_preprocessing',
+      target: 'request',
+      priority: 100,
+      execute: async (data: UnknownObject, context: CompatibilityContext) => {
+        return this.validateRequest(data);
+      }
+    });
+
+    await this.registerHook({
+      name: 'response-normalization',
+      stage: 'outgoing_postprocessing',
+      target: 'response',
+      priority: 200,
+      execute: async (data: UnknownObject, context: CompatibilityContext) => {
+        return this.normalizeResponse(data);
+      }
+    });
+
+    await this.registerHook({
+      name: 'debug-logging',
+      stage: 'outgoing_postprocessing',
+      target: 'response',
+      priority: 999,
+      execute: async (data: UnknownObject, context: CompatibilityContext) => {
+        this.logTransformation(context, data);
+        return data;
+      }
+    });
+  }
+}
+```
+
+### 5. Provider策略实现
+
+**历史文件**: `src/providers/compat/v2/strategies/glm-strategy.ts`
+**职责**: GLM特定转换策略实现
+
+```typescript
+export class GLMStrategy implements TransformationStrategy {
+  readonly type = 'glm';
+
+  async process(data: UnknownObject, direction: 'incoming' | 'outgoing'): Promise<UnknownObject> {
+    if (direction === 'incoming') {
+      return this.processIncoming(data);
+    } else {
+      return this.processOutgoing(data);
+    }
+  }
+
+  private async processIncoming(data: UnknownObject): Promise<UnknownObject> {
+    // GLM特有的incoming处理
+    const processed = { ...data };
+
+    // 处理thinking模式配置
+    if ((processed as any).thinking) {
+      (processed as any).thinking = this.normalizeThinkingConfig((processed as any).thinking);
+    }
+
+    // 处理GLM特有参数
+    if ((processed as any).reasoning_content) {
+      // 移除GLM特有字段，避免传递到provider
+      delete (processed as any).reasoning_content;
+    }
+
+    return processed;
+  }
+
+  private async processOutgoing(data: UnknownObject): Promise<UnknownObject> {
+    // GLM特有的outgoing处理
+    const processed = { ...data };
+
+    // 标准化usage字段
+    if ((processed as any).usage) {
+      (processed as any).usage = this.normalizeUsageFields((processed as any).usage);
+    }
+
+    // 标准化时间戳
+    if ((processed as any).created_at) {
+      (processed as any).created = (processed as any).created_at;
+    }
+
+    return processed;
+  }
+
+  private normalizeThinkingConfig(thinking: any): any {
+    // 标准化thinking配置格式
+    if (typeof thinking === 'boolean') {
+      return { enabled: thinking };
+    }
+    if (typeof thinking === 'object') {
+      return {
+        enabled: thinking.enabled ?? true,
+        max_tokens: thinking.max_tokens,
+        temperature: thinking.temperature
+      };
+    }
+    return { enabled: false };
+  }
+
+  private normalizeUsageFields(usage: any): any {
+    // GLM usage字段标准化
+    return {
+      prompt_tokens: usage.prompt_tokens || usage.input_tokens || 0,
+      completion_tokens: usage.completion_tokens || usage.output_tokens || 0,
+      total_tokens: usage.total_tokens || 0
+    };
+  }
+}
+```
+
+## 🔄 向后兼容性保证
+
+### V1到V2迁移适配器
+
+**历史文件**: `src/providers/compat/v2/core/v1-adapter.ts`
+**职责**: 确保现有V1兼容性模块无缝迁移到V2
+
+```typescript
+export class V1CompatibilityAdapter implements ICompatibilityV2 {
+  private v1Implementation: CompatibilityModule;
+  private v2Wrapper: StandardCompatibility;
+
+  constructor(v1Module: CompatibilityModule, dependencies: ModuleDependencies) {
+    this.v1Implementation = v1Module;
+
+    // 创建V2包装器
+    const v2Config = this.convertV1ConfigToV2(v1Module.config);
+    this.v2Wrapper = new StandardCompatibility(v2Config, dependencies);
+  }
+
+  async initialize(): Promise<void> {
+    // 初始化V1模块
+    await this.v1Implementation.initialize();
+    // 初始化V2包装器
+    await this.v2Wrapper.initialize();
+  }
+
+  async processIncoming(request: UnknownObject): Promise<UnknownObject> {
+    // 优先使用V2处理，V1作为fallback
+    try {
+      return await this.v2Wrapper.processIncoming(request);
+    } catch (error) {
+      // 如果V2失败，回退到V1
+      this.dependencies.logger?.logModule('v1-adapter', 'v2-fallback-to-v1', {
+        error: error instanceof Error ? error.message : String(error)
+      });
+      return await this.v1Implementation.processIncoming(request as any);
+    }
+  }
+
+  async processOutgoing(response: UnknownObject): Promise<UnknownObject> {
+    // 优先使用V2处理，V1作为fallback
+    try {
+      return await this.v2Wrapper.processOutgoing(response);
+    } catch (error) {
+      // 如果V2失败，回退到V1
+      this.dependencies.logger?.logModule('v1-adapter', 'v2-fallback-to-v1', {
+        error: error instanceof Error ? error.message : String(error)
+      });
+      return await this.v1Implementation.processOutgoing(response);
+    }
+  }
+
+  private convertV1ConfigToV2(v1Config: ModuleConfig): CompatibilityConfig {
+    // 将V1配置转换为V2格式
+    return {
+      id: v1Config.id,
+      type: 'standard',
+      config: {
+        providerType: this.extractProviderType(v1Config),
+        transformationProfile: this.buildTransformationProfile(v1Config),
+        hookConfig: this.buildHookConfig(v1Config)
+      }
+    };
+  }
+}
+```
+
+## 📊 配置驱动转换示例
+
+### GLM Provider完整转换配置
+
+```json
+{
+  "providerType": "glm",
+  "transformationProfile": {
+    "name": "glm-standard",
+    "version": "1.0.0",
+    "transformationTables": {
+      "incoming": {
+        "fieldMappings": [
+          {
+            "sourcePath": "model",
+            "targetPath": "model",
+            "direction": "bidirectional",
+            "required": true
+          },
+          {
+            "sourcePath": "thinking.enabled",
+            "targetPath": "thinking",
+            "direction": "incoming-only",
+            "transform": "convertThinkingToGLMFormat"
+          },
+          {
+            "sourcePath": "messages",
+            "targetPath": "messages",
+            "direction": "bidirectional",
+            "transform": "validateMessageFormat"
+          }
+        ],
+        "typeConversions": [
+          {
+            "sourceType": "boolean",
+            "targetType": "object",
+            "conversionFunction": "booleanToThinkingConfig",
+            "conditions": {
+              "field": "thinking"
+            }
+          }
+        ]
+      },
+      "outgoing": {
+        "fieldMappings": [
+          {
+            "sourcePath": "usage.input_tokens",
+            "targetPath": "usage.prompt_tokens",
+            "direction": "outgoing-only"
+          },
+          {
+            "sourcePath": "usage.output_tokens",
+            "targetPath": "usage.completion_tokens",
+            "direction": "outgoing-only"
+          },
+          {
+            "sourcePath": "reasoning_content",
+            "targetPath": "reasoning_content",
+            "direction": "outgoing-only",
+            "transform": "extractReasoningBlocks"
+          }
+        ]
+      }
+    }
+  },
+  "hookConfig": {
+    "enabled": true,
+    "hooks": [
+      {
+        "name": "glm-thinking-injector",
+        "stage": "incoming_preprocessing",
+        "enabled": true,
+        "config": {
+          "models": ["glm-thinking-*"],
+          "defaultThinking": true
+        }
+      },
+      {
+        "name": "glm-response-normalizer",
+        "stage": "outgoing_postprocessing",
+        "enabled": true,
+        "config": {
+          "normalizeUsage": true,
+          "normalizeTimestamps": true
+        }
+      }
+    ]
+  }
+}
+```
+
+## 🎯 实施计划
+
+### 第一阶段：核心架构 (3天)
+1. 创建V2目录结构
+2. 实现BaseCompatibility抽象类
+3. 实现TransformationEngine转换引擎
+4. 实现Hook系统集成
+
+### 第二阶段：配置系统 (2天)
+1. 设计转换表配置格式
+2. 实现双向映射器
+3. 创建Provider配置档案
+4. 实现配置验证器
+
+### 第三阶段：策略实现 (3天)
+1. 实现OpenAI标准策略
+2. 实现GLM特定策略
+3. 实现Qwen特定策略
+4. 实现Iflow特定策略
+
+### 第四阶段：兼容性保证 (2天)
+1. 实现V1适配器
+2. 测试向后兼容性
+3. 性能基准测试
+4. 文档和示例
+
+## ✅ 验收标准
+
+### 功能验收
+- [ ] 所有现有兼容性功能正常工作
+- [ ] 配置驱动的转换引擎正常运行
+- [ ] Hook系统完全集成
+- [ ] 向后兼容性100%保证
+
+### 架构验收
+- [ ] 模块职责清晰分离
+- [ ] 配置驱动，无硬编码转换
+- [ ] Hook生命周期完整支持
+- [ ] 符合9大架构原则
+
+### 质量验收
+- [ ] 测试覆盖率 > 95%
+- [ ] 性能不低于V1实现
+- [ ] 配置验证完整
+- [ ] 文档完整清晰
+
+---
+
+**设计完成时间**: 2025-11-01
+**架构模式**: 基于Provider V2成功模式
+**预计实施时间**: 10天
+**向后兼容**: 100%保证