@jsonstudio/rcc 0.89.1205 → 0.89.1457

package/docs/transformation-tables//351/235/236/346/265/201/345/274/217/345/234/272/346/231/257/345/210/206/346/236/220.md

@@ -0,0 +1,189 @@
+# 非流式场景下的Claude Code Router分析
+
+## 递归调用的位置
+
+### 1. **工具调用后的递归**（主要位置）
+
+```typescript
+// 位置1：工具调用完成后的递归（index.ts:243-250）
+if (data.event === 'message_delta' && toolMessages.length) {
+  // 将工具调用添加到消息历史
+  req.body.messages.push({
+    role: 'assistant',
+    content: assistantMessages
+  })
+  req.body.messages.push({
+    role: 'user', 
+    content: toolMessages
+  })
+  
+  // 🔴 递归调用：重新发送请求到同一个API
+  const response = await fetch(`http://127.0.0.1:${config.PORT}/v1/messages`, {
+    method: "POST",
+    headers: {
+      'x-api-key': config.APIKEY,
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify(req.body), // 包含工具结果的更新后请求
+  })
+}
+```
+
+### 2. **图像分析Agent的递归**（次要位置）
+
+```typescript
+// 位置2：图像分析工具的递归调用（image.agent.ts:132-154）
+const agentResponse = await fetch(`http://127.0.0.1:${context.config.PORT}/v1/messages`, {
+  method: "POST",
+  body: JSON.stringify({
+    model: context.config.Router.image,
+    system: [{ /* 图像分析的system prompt */ }],
+    messages: [
+      {
+        role: 'user',
+        content: imageMessages, // 从缓存中获取的图像数据
+      }
+    ],
+    stream: false, // 🔴 非流式调用
+  }),
+})
+```
+
+## 非流式场景下的状态管理需求
+
+### 1. **图像缓存管理**（主要需求）
+
+```typescript
+// 图像缓存：基于请求ID
+imageCache.storeImage(`${req.id}_Image#${imgId}`, msg.source);
+
+// 图像检索：工具调用时从缓存获取
+const image = imageCache.getImage(`${context.req.id}_Image#${imgId}`);
+```
+
+**为什么需要缓存？**
+- 图像内容被替换为占位符 `[Image #1]`
+- 工具调用时需要重新获取原始图像数据
+- 缓存键基于请求ID确保隔离
+
+### 2. **工具调用参数组装**（次要需求）
+
+在非流式场景下，工具调用参数是完整的，不需要跨事件累积：
+
+```typescript
+// 非流式：工具参数是完整的对象
+{
+  "name": "analyzeImage",
+  "input": {
+    "imageId": ["1", "2"],
+    "task": "描述这张图片"
+  }
+}
+```
+
+### 3. **递归调用的上下文维护**（关键需求）
+
+```typescript
+// 递归调用前：更新消息历史
+req.body.messages.push({
+  role: 'assistant',
+  content: assistantMessages // 工具调用
+})
+req.body.messages.push({
+  role: 'user',
+  content: toolMessages // 工具结果
+})
+
+// 递归调用：发送更新后的完整对话历史
+const response = await fetch(`http://127.0.0.1:${config.PORT}/v1/messages`, {
+  body: JSON.stringify(req.body) // 包含完整对话历史
+})
+```
+
+## 非流式场景的简化分析
+
+### 状态管理的真实需求（修正后）
+
+#### 1. **图像缓存管理**（20%）
+- 请求级别的图像缓存
+- 图像ID生成和检索
+- 缓存清理
+
+#### 2. **递归调用协调**（15%）
+- 消息历史更新
+- 工具结果插入
+- 递归调用触发
+
+#### 3. **工具执行状态**（5%）
+- 当前执行的工具信息
+- 工具结果收集
+
+## 重新评估：静态表 vs 动态处理
+
+### 静态表能解决的（提升到80-85%）：
+
+1. **基础协议转换** ✅
+   - 模型映射
+   - 参数转换
+   - 消息结构转换
+
+2. **工具定义转换** ✅
+   - 工具schema转换
+   - 参数格式转换
+
+3. **错误码映射** ✅
+   - 标准错误响应转换
+
+4. **响应格式转换** ✅
+   - 非流式响应结构转换
+   - 工具结果格式转换
+
+### 需要动态处理的（降低到15-20%）：
+
+1. **图像缓存逻辑**（10%）
+   - 图像ID生成：`${req.id}_Image#${imgId}`
+   - 图像内容替换：`[Image #${imgId}]`
+   - 缓存检索逻辑
+
+2. **递归调用协调**（5%）
+   - 消息历史更新
+   - 工具结果插入
+   - 递归触发逻辑
+
+3. **工具执行**（5%）
+   - 工具调用执行
+   - 结果格式化
+
+## 非流式场景的特殊处理
+
+### 1. **简化的工具调用流程**
+```
+请求接收 → 工具检测 → 工具执行 → 结果插入 → 递归调用 → 响应返回
+```
+
+### 2. **无需流处理状态**
+- 不需要跨事件的状态维护
+- 不需要SSE事件解析
+- 工具参数是完整的JSON对象
+
+### 3. **递归调用是主要复杂度**
+- 单次HTTP请求可能触发多次内部递归调用
+- 每次递归都需要更新消息历史
+- 需要避免无限递归
+
+## 结论
+
+在**非流式场景**下：
+
+1. **静态表能解决80-85%的问题**，主要是协议转换
+2. **只需要15-20%的动态处理**，主要是：
+   - 图像缓存管理
+   - 递归调用协调
+   - 工具执行逻辑
+
+3. **递归调用是主要复杂度来源**：
+   - 工具调用完成后，需要递归调用同一API
+   - 需要维护完整的对话历史
+   - 需要正确处理工具结果的插入
+
+这比流式场景简单很多，状态管理需求大大降低！

package/docs/v2-architecture/IMPLEMENTATION-ROADMAP.md

@@ -0,0 +1,367 @@
+# V2 Architecture Implementation Roadmap
+
+## 📋 Overview
+
+This roadmap outlines the implementation plan for V2 pipeline architecture with the following key phases:
+
+1. **V2 Basic Architecture** - Core virtual pipeline components
+2. **Dynamic Connection System** - Runtime module connection
+3. **V1/V2 Migration System** - Gradual switching mechanism
+4. **ProviderComposite (3.5)** - Internalize compatibility into Provider with protocol guards, type-only providers
+5. **Configuration & Validation** - Migration tools and validation
+6. **Testing & Optimization** - Comprehensive testing and performance tuning
+
+## 🚀 Phase 1: V2 Basic Architecture (3-4 days)
+
+### 1.1 Core Module Registry Implementation
+**Files**: `src/modules/pipeline/v2/core/module-registry.ts`
+
+**Tasks**:
+- [ ] Implement V2ModuleRegistry with factory pattern
+- [ ] Add instance caching and lifecycle management
+- [ ] Implement lazy loading and cleanup mechanisms
+- [ ] Add module type validation and error handling
+
+**Acceptance Criteria**:
+- Module types can be registered and retrieved
+- Instances are created on-demand with proper caching
+- Memory management prevents leaks
+- Comprehensive error handling and logging
+
+### 1.2 Static Instance Pool Implementation
+**Files**: `src/modules/pipeline/v2/core/static-instance-pool.ts`
+
+**Tasks**:
+- [ ] Implement StaticInstancePool for multi-configuration modules
+- [ ] Add configuration hashing and deduplication
+- [ ] Implement preload mechanism based on route analysis
+- [ ] Add instance health monitoring and recycling
+
+**Acceptance Criteria**:
+- Multiple configurations per module type supported
+- Same configurations share instances (deduplication)
+- Preload works based on route table analysis
+- Idle instances are properly cleaned up
+
+### 1.3 Dynamic Router Implementation
+**Files**: `src/modules/pipeline/v2/core/dynamic-router.ts`
+
+**Tasks**:
+- [ ] Implement DynamicRouter with request pattern matching
+- [ ] Add route priority mechanisms (fail fast on unmatched routes)
+- [ ] Implement module chain building logic
+- [ ] Add request routing performance optimization
+
+**Acceptance Criteria**:
+- Requests are correctly routed based on patterns
+- Route priorities are respected
+- Fail fast on unmatched routes (no fallback)
+- Performance meets benchmarks
+
+### 1.4 Virtual Module Chain Implementation
+**Files**: `src/modules/pipeline/v2/core/virtual-module-chain.ts`
+
+**Tasks**:
+- [ ] Implement VirtualModuleChain for temporary connections
+- [ ] Add VirtualModuleConnection for lightweight linking
+- [ ] Implement chain execution and cleanup
+- [ ] Add connection state management
+
+**Acceptance Criteria**:
+- Module chains can be built and executed
+- Connections are established and cleaned properly
+- Chain execution follows module order
+- Resources are properly released after execution
+
+## 🔗 Phase 2: Dynamic Connection System (2-3 days)
+
+### 2.1 Dynamic Connector Implementation
+**Files**: `src/modules/pipeline/v2/core/dynamic-connector.ts`
+
+**Tasks**:
+- [ ] Implement DynamicConnector for runtime connections
+- [ ] Add connection establishment and teardown
+- [ ] Implement error handling and recovery
+- [ ] Add connection monitoring and metrics
+
+**Acceptance Criteria**:
+- Dynamic connections are established on-demand
+- Connections are properly torn down after execution
+- Connection errors are handled gracefully
+- Performance metrics are collected
+
+### 2.2 Connection State Management
+**Files**: `src/modules/pipeline/v2/core/module-connection.ts`
+
+**Tasks**:
+- [ ] Implement ModuleConnection and InstanceConnection
+- [ ] Add connection health monitoring
+- [ ] Implement connection lifecycle callbacks
+- [ ] Add connection metadata and debugging support
+
+**Acceptance Criteria**:
+- Connection states are properly tracked
+- Health monitoring works correctly
+- Lifecycle callbacks fire appropriately
+- Debugging information is available
+
+### 2.3 Hybrid Router Implementation
+**Files**: `src/modules/pipeline/v2/core/hybrid-router.ts`
+
+**Tasks**:
+- [ ] Implement HybridDynamicRouter with static instance integration
+- [ ] Add configuration resolution with conditional selection (fail fast on unmatched conditions)
+- [ ] Implement module chain building from static pool
+- [ ] Add request processing with connection management
+
+**Acceptance Criteria**:
+- Static instances are properly utilized
+- Configurations are resolved correctly
+- Module chains use static instances efficiently
+- Request processing maintains performance
+
+## 🔄 Phase 3: V1/V2 Migration System (2-3 days)
+
+### 3.1 V2 Pipeline Assembler Implementation
+**Files**: `src/modules/pipeline/v2/config/v2-pipeline-assembler.ts`
+
+**Tasks**:
+- [ ] Implement V2PipelineAssembler with simplified logic
+- [ ] Add configuration validation and instance verification
+- [ ] Implement prerun route validation
+- [ ] Add data flow simulation and validation
+
+**Acceptance Criteria**:
+- V2 configurations are properly validated
+- Static instances are verified before use
+- Prerun validation catches configuration issues
+- Data flow simulation works correctly
+
+### 3.2 V1 Configuration Migration
+**Files**: `src/modules/pipeline/v2/config/v1-migrator.ts`
+
+**Tasks**:
+- [ ] Implement V1ToV2Migrator for automatic conversion
+- [ ] Add route table conversion from V1 format
+- [ ] Implement provider and compatibility config extraction
+- [ ] Add migration report generation
+
+**Acceptance Criteria**:
+- V1 configurations convert to V2 format correctly
+- Route tables maintain V1 behavior in V2
+- All required module types are extracted
+- Migration reports are comprehensive
+
+### 3.3 Mode Switch Implementation
+**Files**: `src/core/v1-v2-switch.ts`
+
+**Tasks**:
+- [ ] Implement V1V2ModeSwitch with gradual switching
+- [ ] Add compatibility validation before switch
+- [ ] Implement traffic shifting mechanism
+- [ ] Add manual rollback workflow and structured error logging
+
+**Acceptance Criteria**:
+- Modes can be switched without service interruption
+- Compatibility validation prevents breaking changes
+- Traffic can be shifted gradually
+- No auto recovery; errors surface immediately with full context
+
+## ⚙️ Phase 4: Configuration & Validation (1-2 days)
+
+### 3.5 ProviderComposite & Type-only Providers
+**Files**: `src/providers/core/composite/*`, `src/providers/core/runtime/*`, `docs/providers/*`
+
+**Tasks**:
+- [x] Internalize compatibility into Provider (ProviderComposite)
+- [x] Add protocol guards and minimal shape checks (Fail Fast)
+- [x] OpenAI-family aggregator (glm/lmstudio/iflow reuse; qwen safe path)
+- [x] Factory protocol-first selection; normalize legacy providerType
+- [x] Docs for design/testing/migration
+
+**Acceptance Criteria**:
+- Pipeline no longer needs explicit compatibility nodes
+- Provider reads runtime metadata and enforces protocol guards
+- SSE boundary respected (Provider→Host JSON only)
+- Legacy configs run with warnings; brand handled via providerId/extensions
+
+### 4.1 Configuration Schema Implementation
+**Files**: `src/config/v2-config-schema.ts`
+
+**Tasks**:
+- [ ] Implement V2SystemConfig interface
+- [ ] Add RouteDefinition and ModuleSpecification types
+- [ ] Implement configuration validation rules
+- [ ] Add schema documentation and examples
+
+**Acceptance Criteria**:
+- V2 configuration schema is complete
+- Validation rules prevent invalid configurations
+- Documentation is clear and comprehensive
+- Examples cover common use cases
+
+### 4.2 Configuration Library Implementation
+**Files**: `src/config/v2-config-library.ts`
+
+**Tasks**:
+- [ ] Implement V2ConfigLibrary with predefined configurations
+- [ ] Add provider, compatibility, and llmSwitch configs
+- [ ] Implement configuration lookup and resolution
+- [ ] Add configuration validation and defaults
+
+**Acceptance Criteria**:
+- Predefined configurations cover all providers
+- Configuration lookup is efficient and reliable
+- Validation catches configuration errors
+- Default values are sensible
+
+### 4.3 Prerun Validation Tools
+**Files**: `src/tools/pre-run-validator.ts`
+
+**Tasks**:
+- [ ] Implement PreRunValidator for comprehensive testing
+- [ ] Add route validation and data flow testing
+- [ ] Implement performance validation
+- [ ] Add detailed validation reporting
+
+**Acceptance Criteria**:
+- All routes can be validated before switching
+- Data flow validation catches compatibility issues
+- Performance validation meets requirements
+- Validation reports are detailed and actionable
+
+### 4.4 Warmup Manager Implementation
+**Files**: `src/modules/pipeline/v2/core/warmup-manager.ts`
+
+**Tasks**:
+- [ ] Implement WarmupManager with intelligent preloading
+- [ ] Add priority-based instance loading
+- [ ] Implement instance validation and health checks
+- [ ] Add warmup metrics and reporting
+
+**Acceptance Criteria**:
+- System startup is optimized with warmup
+- Critical modules are loaded first
+- Instance health is verified during warmup
+- Warmup reports show startup status
+
+## 🧪 Phase 5: Testing & Optimization (2-3 days)
+
+### 5.1 Unit Testing
+**Tasks**:
+- [ ] Write unit tests for all V2 components
+- [ ] Test configuration migration and validation
+- [ ] Test dynamic connection and routing
+- [ ] Test mode switching and compatibility
+
+**Acceptance Criteria**:
+- Unit test coverage > 90%
+- All critical paths are tested
+- Edge cases are handled correctly
+- Tests run reliably in CI/CD
+
+### 5.2 Integration Testing
+**Tasks**:
+- [ ] Test V1/V2 mode switching end-to-end
+- [ ] Test configuration migration with real configs
+- [ ] Test dynamic routing with various request types
+- [ ] Test performance under load
+
+**Acceptance Criteria**:
+- Mode switching works without issues
+- Configuration migration preserves behavior
+- Dynamic routing performs correctly
+- System meets performance requirements
+
+### 5.3 Performance Testing
+**Tasks**:
+- [ ] Benchmark V1 vs V2 performance
+- [ ] Test connection establishment overhead
+- [ ] Measure memory usage with static pools
+- [ ] Optimize bottlenecks identified in testing
+
+**Acceptance Criteria**:
+- V2 performance matches or exceeds V1
+- Connection overhead is minimal
+- Memory usage is efficient
+- No performance regressions
+
+### 5.4 Documentation and Examples
+**Tasks**:
+- [ ] Write comprehensive API documentation
+- [ ] Create migration guide and examples
+- [ ] Document configuration options
+- [ ] Create troubleshooting guide
+
+**Acceptance Criteria**:
+- Documentation is complete and accurate
+- Migration guide is easy to follow
+- Examples cover common scenarios
+- Troubleshooting guide is helpful
+
+## 📊 Success Metrics
+
+### Functional Metrics
+- [ ] All V1 configurations successfully migrate to V2
+- [ ] V2 routing produces identical results to V1
+- [ ] Mode switching completes without service interruption
+- [ ] Prerun validation catches all configuration issues
+
+### Performance Metrics
+- [ ] V2 response time ≤ V1 response time + 5ms
+- [ ] Connection establishment time < 1ms
+- [ ] Memory usage increase < 20%
+- [ ] Warmup completion time < 30 seconds
+
+### Quality Metrics
+- [ ] Unit test coverage > 90%
+- [ ] Integration test success rate = 100%
+- [ ] Zero critical bugs in production
+- [ ] Documentation completeness score > 95%
+- [ ] No fallback logic anywhere in V2 codebase (Fail Fast validation)
+- [ ] All tool processing goes through llmswitch-core only
+- [ ] Configuration validation passes 100% (no hardcoded values)
+
+### "No Fallback" Validation Checklist
+- [ ] RouteTable has no fallbackStrategies
+- [ ] ModuleSpecification has no fallback property
+- [ ] HybridRouter throws errors on condition mismatch (no fallback resolution)
+- [ ] Error handling logs and metrics only (no auto recovery)
+- [ ] Mode switching requires explicit operator action
+- [ ] All configuration uses env vars with defaults (no hardcoded URLs/keys)
+- [ ] Instance pool validation rejects invalid configs immediately
+
+## 🚨 Risk Mitigation
+
+### Technical Risks
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|------------|
+| Performance regression | Medium | High | Comprehensive benchmarking and optimization |
+| Memory leaks | Low | High | Rigorous testing and monitoring |
+| Configuration migration issues | Medium | High | Extensive validation and rollback mechanism |
+| Dynamic connection failures | Low | Medium | Robust error handling and retry logic |
+
+### Operational Risks
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|------------|
+| Service disruption during switch | Low | High | Gradual switching with rollback capability |
+| Compatibility issues | Medium | Medium | Extensive prerun validation and testing |
+| Increased complexity | High | Low | Comprehensive documentation and training |
+
+## 📅 Timeline
+
+| Phase | Duration | Start Date | End Date | Dependencies |
+|-------|----------|-------------|-----------|--------------|
+| Phase 1: V2 Basic Architecture | 3-4 days | Day 1 | Day 4 | None |
+| Phase 2: Dynamic Connection System | 2-3 days | Day 5 | Day 7 | Phase 1 |
+| Phase 3: V1/V2 Migration System | 2-3 days | Day 8 | Day 10 | Phase 1, 2 |
+| Phase 4: Configuration & Validation | 1-2 days | Day 11 | Day 12 | Phase 3 |
+| Phase 5: Testing & Optimization | 2-3 days | Day 13 | Day 15 | All previous phases |
+
+**Total Duration**: 15 days
+**Buffer Time**: 3 days (for unforeseen issues)
+**Target Completion**: 18 days
+
+---
+
+*This roadmap serves as the implementation guide for V2 architecture. All phases should be completed sequentially with proper testing and validation at each stage.*