@jsonstudio/rcc 0.89.1205 → 0.89.1348

package/docs/MODULE_ENHANCEMENT_SYSTEM.md

@@ -0,0 +1,666 @@
+# RouteCodex Progressive Module Enhancement System
+
+## Overview
+
+The RouteCodex Progressive Module Enhancement System provides a simple, declarative way to add debugging capabilities to existing modules one by one while maintaining full backward compatibility. This system makes it easy for developers to incrementally enhance their modules with comprehensive debugging without breaking existing functionality.
+
+## Key Features
+
+- **Non-intrusive**: Existing modules continue working without any changes
+- **Configuration-driven**: JSON-based configuration for enabling/disabling debugging per module
+- **Progressive rollout**: Add debugging to modules one at a time
+- **Type-safe**: Full TypeScript support with comprehensive type definitions
+- **Performance-aware**: Configurable logging levels and performance tracking
+- **Integration-ready**: Seamlessly integrates with existing DebugCenter and DebugEventBus
+
+## Architecture
+
+The enhancement system consists of several key components:
+
+1. **Module Enhancement Factory** - Core factory that wraps modules with debugging
+2. **Enhancement Configuration Manager** - Manages JSON-based configuration
+3. **Enhancement Registry** - Tracks all enhanced modules
+4. **Module Templates** - Pre-built templates for common module types
+5. **Integration Scripts** - CLI tools for progressive enhancement
+
+## Quick Start
+
+### 1. Basic Enhancement
+
+```typescript
+import { ModuleEnhancementFactory } from '../src/modules/enhancement/module-enhancement-factory.js';
+import { DebugCenter } from 'rcc-errorhandling';
+
+// Create factory
+const factory = new ModuleEnhancementFactory(debugCenter);
+
+// Enhance your module
+const enhanced = factory.createEnhancedModule(
+  originalModule,
+  'my-provider',
+  'provider',
+  {
+    enabled: true,
+    level: 'detailed',
+    consoleLogging: true,
+    debugCenter: true
+  }
+);
+
+// Use enhanced module
+await enhanced.enhanced.processIncoming(request);
+```
+
+### 2. Configuration-Driven Enhancement
+
+```typescript
+import { EnhancementConfigManager } from '../src/modules/enhancement/enhancement-config-manager.js';
+
+// Create configuration manager
+const configManager = new EnhancementConfigManager(debugCenter);
+
+// Enhance using configuration
+const enhanced = await configManager.enhanceModule(
+  originalModule,
+  'my-provider',
+  'provider'
+);
+```
+
+### 3. CLI Enhancement Tool
+
+```bash
+# Add enhancement to a module
+node scripts/enhance-module.js add src/providers/core/runtime/chat-http-provider.ts
+
+# Auto-detect modules
+node scripts/enhance-module.js auto-detect
+
+# List enhanced modules
+node scripts/enhance-module.js list
+
+# Enable/disable debugging
+node scripts/enhance-module.js enable lmstudio-provider
+node scripts/enhance-module.js disable lmstudio-provider
+```
+
+## Configuration
+
+### JSON Configuration File
+
+The system uses a JSON configuration file (`enhancement-config.json`) to control debugging behavior:
+
+```json
+{
+  "version": "1.0.0",
+  "global": {
+    "enabled": true,
+    "defaults": {
+      "enabled": true,
+      "level": "detailed",
+      "consoleLogging": true,
+      "debugCenter": true,
+      "maxLogEntries": 1000,
+      "performanceTracking": true,
+      "requestLogging": true,
+      "errorTracking": true,
+      "transformationLogging": true
+    },
+    "modules": {
+      "lmstudio-provider": {
+        "moduleId": "lmstudio-provider",
+        "moduleType": "provider",
+        "enabled": true,
+        "level": "detailed",
+        "consoleLogging": true,
+        "debugCenter": true
+      },
+      "pipeline-manager": {
+        "moduleId": "pipeline-manager",
+        "moduleType": "pipeline",
+        "enabled": true,
+        "level": "verbose",
+        "consoleLogging": true,
+        "debugCenter": true
+      }
+    },
+    "autoDetection": {
+      "enabled": true,
+      "patterns": [
+        "src/modules/pipeline/modules/**/*.ts",
+        "src/modules/pipeline/core/**/*.ts",
+        "src/server/**/*.ts"
+      ],
+      "excludeDirs": [
+        "node_modules",
+        "dist",
+        "tests"
+      ]
+    },
+    "performance": {
+      "enabled": true,
+      "thresholds": {
+        "warning": 1000,
+        "critical": 5000
+      }
+    }
+  },
+  "environments": {
+    "development": {
+      "enabled": true,
+      "defaults": {
+        "enabled": true,
+        "level": "verbose",
+        "consoleLogging": true,
+        "debugCenter": true
+      }
+    },
+    "production": {
+      "enabled": true,
+      "defaults": {
+        "enabled": false,
+        "level": "basic",
+        "consoleLogging": false,
+        "debugCenter": true
+      }
+    }
+  }
+}
+```
+
+### Environment-Specific Configuration
+
+The system supports environment-specific overrides:
+
+- **development**: Full debugging enabled with verbose logging
+- **production**: Minimal debugging for performance
+- **test**: Verbose logging for testing scenarios
+
+## Module Types
+
+The system supports enhancement for different module types:
+
+### Provider Modules
+```typescript
+const enhanced = factory.createEnhancedModule(
+  providerModule,
+  'my-provider',
+  'provider',
+  config
+);
+```
+
+### Pipeline Modules
+```typescript
+const enhanced = factory.createEnhancedModule(
+  pipelineModule,
+  'my-pipeline',
+  'pipeline',
+  config
+);
+```
+
+### Compatibility Modules
+```typescript
+const enhanced = factory.createEnhancedModule(
+  compatibilityModule,
+  'my-compatibility',
+  'compatibility',
+  config
+);
+```
+
+### Workflow Modules
+```typescript
+const enhanced = factory.createEnhancedModule(
+  workflowModule,
+  'my-workflow',
+  'workflow',
+  config
+);
+```
+
+### HTTP Server Modules
+```typescript
+const enhanced = factory.createEnhancedModule(
+  serverModule,
+  'my-server',
+  'http-server',
+  config
+);
+```
+
+## Enhancement Features
+
+### Debug Logging
+- Structured logging with timestamps and request IDs
+- Configurable log levels (none, basic, detailed, verbose)
+- Automatic log rotation and size management
+- Request/response correlation
+
+### Performance Tracking
+- Execution time measurement for all methods
+- Performance threshold monitoring
+- Automatic performance metrics collection
+- Integration with DebugEventBus
+
+### Error Tracking
+- Comprehensive error logging with stack traces
+- Error categorization and analysis
+- Automatic error reporting to DebugCenter
+- Request context preservation
+
+### Request/Response Logging
+- Full request/response capture with sensitive data filtering
+- Request lifecycle tracking
+- Response time analysis
+- Content size monitoring
+
+### Transformation Logging
+- Data transformation tracking
+- Before/after transformation capture
+- Transformation rule execution logging
+- Performance impact analysis
+
+## Integration Examples
+
+### Enhancing LM Studio Provider
+
+**Before:**
+```typescript
+export class LMStudioProviderSimple implements ProviderModule {
+  async processIncoming(request: any): Promise<any> {
+    // Direct processing
+    const response = await this.sendChatRequest(request);
+    return response;
+  }
+}
+```
+
+**After:**
+```typescript
+export class EnhancedLMStudioProvider implements ProviderModule {
+  private enhancedModule: EnhancedModule<this> | null = null;
+  private configManager: EnhancementConfigManager;
+
+  async initialize(): Promise<void> {
+    this.enhancedModule = await this.configManager.enhanceModule(
+      this,
+      this.id,
+      'provider'
+    );
+  }
+
+  async processIncoming(request: any): Promise<any> {
+    if (!this.enhancedModule) {
+      return this.originalProcessIncoming(request);
+    }
+    return this.enhancedModule.enhanced.processIncoming(request);
+  }
+}
+```
+
+### Progressive Enhancement Pattern
+
+```typescript
+class MyModule {
+  private enhanced: EnhancedModule<this> | null = null;
+
+  constructor(private config: ModuleConfig, private dependencies: ModuleDependencies) {
+    // Initialize enhancement manager
+    this.enhancementManager = new EnhancementConfigManager(
+      dependencies.debugCenter
+    );
+  }
+
+  async initialize(): Promise<void> {
+    // Create enhanced version
+    this.enhanced = await this.enhancementManager.enhanceModule(
+      this,
+      this.id,
+      'provider'
+    );
+
+    // Continue with original initialization
+    await this.originalInitialize();
+  }
+
+  async processIncoming(request: any): Promise<any> {
+    // Use enhanced version if available, fallback to original
+    if (this.enhanced) {
+      return this.enhanced.enhanced.processIncoming(request);
+    }
+    return this.originalProcessIncoming(request);
+  }
+}
+```
+
+## CLI Tool Usage
+
+### Adding Enhancement to a Module
+
+```bash
+# Basic enhancement
+node scripts/enhance-module.js add src/providers/core/runtime/my-provider.ts
+
+# With custom module ID and type
+node scripts/enhance-module.js add ./my-module.ts my-module provider
+
+# Dry run to see changes
+node scripts/enhance-module.js add ./my-module.ts --dry-run
+```
+
+### Managing Enhanced Modules
+
+```bash
+# List all modules
+node scripts/enhance-module.js list
+
+# Show configuration
+node scripts/enhance-module.js config
+
+# Enable enhancement for a module
+node scripts/enhance-module.js enable my-provider
+
+# Disable enhancement for a module
+node scripts/enhance-module.js disable my-provider
+
+# Remove enhancement
+node scripts/enhance-module.js remove my-provider
+```
+
+### Auto-Detection
+
+```bash
+# Auto-detect modules for enhancement
+node scripts/enhance-module.js auto-detect
+
+# Auto-detect with custom patterns
+node scripts/enhance-module.js auto-detect --config custom-config.json
+```
+
+## Templates
+
+The system provides templates for common module types:
+
+### Provider Template
+```typescript
+import { EnhancedProviderModule } from '../src/modules/enhancement/templates/provider-template.js';
+
+export class MyProvider extends EnhancedProviderModule {
+  // Automatically gets all debugging capabilities
+  // Just implement the provider-specific logic
+}
+```
+
+### Pipeline Template
+```typescript
+import { EnhancedPipelineManager } from '../src/modules/enhancement/templates/pipeline-template.js';
+
+export class MyPipelineManager extends EnhancedPipelineManager {
+  // Enhanced with debugging out of the box
+}
+```
+
+## Debugging Integration
+
+The enhancement system seamlessly integrates with RouteCodex's debugging infrastructure:
+
+### DebugEventBus Integration
+```typescript
+// Enhanced modules automatically publish to DebugEventBus
+const eventBus = DebugEventBus.getInstance();
+eventBus.subscribe(event => {
+  console.log('Debug event:', event);
+});
+```
+
+### DebugCenter Integration
+```typescript
+// All enhanced modules send events to DebugCenter
+debugCenter.processDebugEvent({
+  sessionId: 'request-123',
+  moduleId: 'my-provider',
+  operationId: 'processIncoming',
+  timestamp: Date.now(),
+  type: 'start',
+  position: 'middle',
+  data: { /* debug data */ }
+});
+```
+
+## Performance Considerations
+
+### Minimal Overhead
+- Zero overhead when disabled
+- Conditional logging based on configuration
+- Efficient log rotation and cleanup
+
+### Configurable Levels
+```typescript
+const config: EnhancementConfig = {
+  enabled: true,
+  level: 'basic', // Minimal logging
+  consoleLogging: false, // No console output
+  debugCenter: true, // Still send to DebugCenter
+  maxLogEntries: 100 // Limit memory usage
+};
+```
+
+### Production Optimization
+```typescript
+// Production configuration
+const productionConfig: EnhancementConfig = {
+  enabled: false, // Completely disabled
+  level: 'none',
+  consoleLogging: false,
+  debugCenter: false
+};
+```
+
+## Testing Enhanced Modules
+
+```typescript
+import { EnhancedModule } from '../src/modules/enhancement/module-enhancement-factory.js';
+
+describe('Enhanced Provider', () => {
+  let enhanced: EnhancedModule<MyProvider>;
+
+  beforeEach(async () => {
+    const original = new MyProvider(config, dependencies);
+    const factory = new ModuleEnhancementFactory(debugCenter);
+
+    enhanced = factory.createEnhancedModule(
+      original,
+      'test-provider',
+      'provider',
+      { enabled: true, level: 'verbose' }
+    );
+
+    await enhanced.enhanced.initialize();
+  });
+
+  it('should process requests with debugging', async () => {
+    const response = await enhanced.enhanced.processIncoming(testRequest);
+
+    // Check that debugging occurred
+    expect(enhanced.logger.getStatistics().totalLogs).toBeGreaterThan(0);
+
+    // Verify response
+    expect(response).toBeDefined();
+  });
+
+  it('should capture performance metrics', async () => {
+    await enhanced.enhanced.processIncoming(testRequest);
+
+    const stats = enhanced.logger.getStatistics();
+    expect(stats.performanceTracking).toBe(true);
+  });
+});
+```
+
+## Migration Guide
+
+### Step 1: Identify Modules to Enhance
+```bash
+# Auto-detect modules
+node scripts/enhance-module.js auto-detect
+```
+
+### Step 2: Start with Non-Critical Modules
+```bash
+# Enhance a test module first
+node scripts/enhance-module.js add src/modules/test-module.ts --dry-run
+```
+
+### Step 3: Gradually Roll Out
+```bash
+# Enable one by one
+node scripts/enhance-module.js enable module1
+node scripts/enhance-module.js enable module2
+```
+
+### Step 4: Monitor and Adjust
+```bash
+# Check logs and performance
+node scripts/enhance-module.js list
+```
+
+## Best Practices
+
+### 1. Start Small
+- Begin with non-critical modules
+- Use basic logging levels initially
+- Monitor performance impact
+
+### 2. Use Environment-Specific Configs
+```typescript
+const config = process.env.NODE_ENV === 'production'
+  ? productionConfig
+  : developmentConfig;
+```
+
+### 3. Monitor Log Sizes
+```typescript
+const stats = enhanced.logger.getStatistics();
+if (stats.totalLogs > 10000) {
+  enhanced.logger.clearLogs();
+}
+```
+
+### 4. Use Selective Enhancement
+```typescript
+// Only enhance specific methods
+const config: EnhancementConfig = {
+  enabled: true,
+  requestLogging: true,
+  errorTracking: true,
+  transformationLogging: false // Skip this for performance
+};
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Module not found in configuration**
+```bash
+# Check configuration
+node scripts/enhance-module.js config
+
+# Auto-detect modules
+node scripts/enhance-module.js auto-detect
+```
+
+**Performance degradation**
+```typescript
+// Reduce logging level
+const config: EnhancementConfig = {
+  enabled: true,
+  level: 'basic',
+  maxLogEntries: 100
+};
+```
+
+**Memory usage high**
+```typescript
+// Clear logs periodically
+enhanced.logger.clearLogs();
+
+// Reduce max entries
+const config: EnhancementConfig = {
+  maxLogEntries: 500
+};
+```
+
+### Debug Mode
+```typescript
+// Enable verbose logging for troubleshooting
+const config: EnhancementConfig = {
+  enabled: true,
+  level: 'verbose',
+  consoleLogging: true,
+  debugCenter: true
+};
+```
+
+## API Reference
+
+### ModuleEnhancementFactory
+
+```typescript
+class ModuleEnhancementFactory {
+  constructor(debugCenter: DebugCenter);
+
+  createEnhancedModule<T>(
+    module: T,
+    moduleId: string,
+    moduleType: string,
+    config?: EnhancementConfig
+  ): EnhancedModule<T>;
+}
+```
+
+### EnhancementConfigManager
+
+```typescript
+class EnhancementConfigManager {
+  constructor(debugCenter: DebugCenter, configPath?: string);
+
+  async enhanceModule<T>(
+    module: T,
+    moduleId: string,
+    moduleType: string,
+    config?: EnhancementConfig
+  ): Promise<EnhancedModule<T>>;
+
+  async loadConfig(configPath?: string): Promise<void>;
+  async saveConfig(config?: EnhancementConfigFile): Promise<void>;
+
+  getConfig(): EnhancementConfigFile | null;
+  getModuleConfig(moduleId: string): ModuleEnhancementConfig | null;
+}
+```
+
+### EnhancedModule
+
+```typescript
+interface EnhancedModule<T> {
+  readonly original: T;
+  readonly enhanced: T;
+  readonly logger: PipelineDebugLogger;
+  readonly config: EnhancementConfig;
+  readonly metadata: {
+    moduleId: string;
+    moduleType: string;
+    enhanced: boolean;
+    enhancementTime: number;
+  };
+}
+```
+
+## Conclusion
+
+The RouteCodex Progressive Module Enhancement System provides a comprehensive solution for adding debugging capabilities to existing modules incrementally. By using configuration-driven enhancement and maintaining backward compatibility, developers can gradually improve their debugging capabilities without disrupting existing functionality.
+
+The system's modular design, type safety, and integration with existing debugging infrastructure make it an essential tool for maintaining and debugging complex RouteCodex applications.

package/docs/PORTS.md

@@ -0,0 +1,36 @@
+# 端口与监听地址（输入端口）说明
+
+## 配置文件
+
+推荐在 `~/.routecodex/config.json` 里配置：
+
+```jsonc
+{
+  "httpserver": {
+    "host": "127.0.0.1",
+    "port": 5555
+  }
+}
+```
+
+## CLI 行为差异（rcc vs routecodex）
+
+### `rcc`（release 包）
+
+- **严格按配置文件端口启动**（`httpserver.port`）
+- 若端口缺失/非法：`rcc start` 直接失败
+
+### `routecodex`（dev worktree）
+
+- 默认端口固定为 `5555`
+- 可用环境变量覆盖：
+  - `ROUTECODEX_PORT` 或 `RCC_PORT`
+- 也可用 `routecodex start --port <port>` 覆盖（dev package only）
+
+## 常用排查
+
+```bash
+rcc status
+curl http://127.0.0.1:5555/ready
+```
+