@capyclaw/tool-host 0.1.0 → 0.1.1

package/src/optimizers/PPT/346/265/201/345/274/217/346/270/262/346/237/223-/347/224/237/344/272/247/347/272/247/344/274/230/345/214/226.md

@@ -1,874 +0,0 @@
-# 🚀 PPT 流式渲染 - 生产级优化方案
-
-**目标**: 确保传输稳定性、低延迟、低性能开销和高准确性
-
----
-
-## 📋 核心优化策略
-
-### 参考：成熟的流式输出实践
-
-```
-LLM 流式输出的成熟技术：
-✅ Server-Sent Events (SSE) - 单向流式传输
-✅ 断点续传 - 支持中断恢复
-✅ 心跳检测 - 检测连接状态
-✅ 缓冲区管理 - 平滑输出
-✅ 错误重试 - 自动恢复
-✅ 优雅降级 - 回退到轮询
-✅ 反压控制 - 防止过载
-
-我们可以借鉴所有这些技术！
-```
-
----
-
-## 🎯 优化维度
-
-### 1. 稳定性优化
-
-#### 1.1 连接管理
-
-```javascript
-class StableConnection {
-  constructor(wsUrl) {
-    this.wsUrl = wsUrl;
-    this.ws = null;
-    this.reconnectAttempts = 0;
-    this.maxReconnectAttempts = 5;
-    this.reconnectDelay = 1000;
-    this.heartbeatInterval = null;
-    this.lastHeartbeat = Date.now();
-  }
-
-  async connect() {
-    return new Promise((resolve, reject) => {
-      this.ws = new WebSocket(this.wsUrl);
-      
-      this.ws.onopen = () => {
-        console.log('✅ WebSocket 连接成功');
-        this.reconnectAttempts = 0;
-        this.startHeartbeat();
-        resolve();
-      };
-      
-      this.ws.onerror = (error) => {
-        console.error('❌ WebSocket 错误:', error);
-        this.handleError(error);
-      };
-      
-      this.ws.onclose = () => {
-        console.log('🔌 WebSocket 断开');
-        this.stopHeartbeat();
-        this.attemptReconnect();
-      };
-    });
-  }
-
-  // 心跳检测
-  startHeartbeat() {
-    this.heartbeatInterval = setInterval(() => {
-      if (this.ws && this.ws.readyState === WebSocket.OPEN) {
-        this.ws.send(JSON.stringify({ type: 'ping' }));
-        this.lastHeartbeat = Date.now();
-      } else {
-        // 连接异常，尝试重连
-        this.attemptReconnect();
-      }
-    }, 5000); // 每5秒心跳
-  }
-
-  stopHeartbeat() {
-    if (this.heartbeatInterval) {
-      clearInterval(this.heartbeatInterval);
-      this.heartbeatInterval = null;
-    }
-  }
-
-  // 自动重连
-  async attemptReconnect() {
-    if (this.reconnectAttempts >= this.maxReconnectAttempts) {
-      console.error('❌ 达到最大重连次数，放弃重连');
-      return;
-    }
-
-    this.reconnectAttempts++;
-    const delay = this.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1);
-    
-    console.log(`🔄 尝试重连 (${this.reconnectAttempts}/${this.maxReconnectAttempts})，延迟 ${delay}ms`);
-    
-    await new Promise(r => setTimeout(r, delay));
-    
-    try {
-      await this.connect();
-      console.log('✅ 重连成功');
-    } catch (error) {
-      console.error('❌ 重连失败:', error);
-      this.attemptReconnect();
-    }
-  }
-
-  // 安全发送
-  safeSend(data) {
-    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
-      this.ws.send(JSON.stringify(data));
-      return true;
-    } else {
-      console.warn('⚠️ WebSocket 未连接，消息将被缓存');
-      return false;
-    }
-  }
-}
-```
-
-#### 1.2 消息确认机制（ACK）
-
-```javascript
-class ReliableMessageQueue {
-  constructor(connection) {
-    this.connection = connection;
-    this.pendingMessages = new Map(); // 待确认消息
-    this.messageId = 0;
-    this.ackTimeout = 5000; // 5秒超时
-  }
-
-  async sendWithAck(message) {
-    const id = ++this.messageId;
-    const payload = { ...message, messageId: id };
-
-    return new Promise((resolve, reject) => {
-      // 发送消息
-      const sent = this.connection.safeSend(payload);
-      
-      if (!sent) {
-        reject(new Error('Connection not ready'));
-        return;
-      }
-
-      // 等待确认
-      const timeout = setTimeout(() => {
-        this.pendingMessages.delete(id);
-        reject(new Error(`Message ${id} timeout`));
-      }, this.ackTimeout);
-
-      this.pendingMessages.set(id, {
-        resolve,
-        reject,
-        timeout,
-        message: payload,
-        timestamp: Date.now()
-      });
-    });
-  }
-
-  handleAck(messageId) {
-    const pending = this.pendingMessages.get(messageId);
-    if (pending) {
-      clearTimeout(pending.timeout);
-      pending.resolve();
-      this.pendingMessages.delete(messageId);
-    }
-  }
-
-  // 重发未确认的消息
-  retryPending() {
-    const now = Date.now();
-    for (const [id, pending] of this.pendingMessages.entries()) {
-      if (now - pending.timestamp > this.ackTimeout) {
-        console.log(`🔄 重发消息 ${id}`);
-        this.connection.safeSend(pending.message);
-        pending.timestamp = now;
-      }
-    }
-  }
-}
-```
-
-### 2. 断点续传机制
-
-#### 2.1 状态持久化
-
-```javascript
-class StreamingStateManager {
-  constructor() {
-    this.sessionId = this.generateSessionId();
-    this.currentIndex = 0;
-    this.completedOps = new Set();
-    this.failedOps = new Set();
-    this.snapshot = null;
-  }
-
-  generateSessionId() {
-    return `ppt_stream_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
-  }
-
-  // 保存检查点
-  saveCheckpoint(index, operation) {
-    this.currentIndex = index;
-    this.completedOps.add(index);
-    
-    // 持久化到本地存储
-    const state = {
-      sessionId: this.sessionId,
-      currentIndex: this.currentIndex,
-      completedOps: Array.from(this.completedOps),
-      failedOps: Array.from(this.failedOps),
-      timestamp: Date.now()
-    };
-    
-    localStorage.setItem(`ppt_stream_${this.sessionId}`, JSON.stringify(state));
-  }
-
-  // 恢复状态
-  restoreState(sessionId) {
-    const stored = localStorage.getItem(`ppt_stream_${sessionId}`);
-    if (stored) {
-      const state = JSON.parse(stored);
-      this.sessionId = state.sessionId;
-      this.currentIndex = state.currentIndex;
-      this.completedOps = new Set(state.completedOps);
-      this.failedOps = new Set(state.failedOps);
-      return state;
-    }
-    return null;
-  }
-
-  // 检查操作是否已完成
-  isCompleted(index) {
-    return this.completedOps.has(index);
-  }
-
-  // 清理状态
-  clearState() {
-    localStorage.removeItem(`ppt_stream_${this.sessionId}`);
-  }
-}
-```
-
-#### 2.2 断点续传实现
-
-```javascript
-async streamEditWithResume(operations, onProgress, resumeSessionId = null) {
-  const stateManager = new StreamingStateManager();
-  
-  // 尝试恢复之前的会话
-  if (resumeSessionId) {
-    const restored = stateManager.restoreState(resumeSessionId);
-    if (restored) {
-      console.log(`🔄 恢复会话: ${resumeSessionId}，从第 ${restored.currentIndex} 个操作继续`);
-    }
-  }
-
-  const total = operations.length;
-  
-  for (let i = 0; i < operations.length; i++) {
-    // 跳过已完成的操作
-    if (stateManager.isCompleted(i)) {
-      console.log(`⏭️  跳过已完成的操作 ${i}`);
-      continue;
-    }
-
-    const operation = operations[i];
-    
-    try {
-      // 执行操作
-      await this.executeOperation(operation);
-      
-      // 保存检查点
-      stateManager.saveCheckpoint(i, operation);
-      
-      // 反馈进度
-      if (onProgress) {
-        onProgress({
-          current: i + 1,
-          total,
-          completed: stateManager.completedOps.size,
-          sessionId: stateManager.sessionId
-        });
-      }
-    } catch (error) {
-      console.error(`❌ 操作 ${i} 失败:`, error);
-      stateManager.failedOps.add(i);
-      
-      // 根据错误类型决定是否继续
-      if (this.isFatalError(error)) {
-        throw error; // 致命错误，中止
-      }
-      // 否则继续下一个操作
-    }
-  }
-
-  // 完成后清理状态
-  stateManager.clearState();
-  
-  return {
-    success: true,
-    sessionId: stateManager.sessionId,
-    completed: stateManager.completedOps.size,
-    failed: stateManager.failedOps.size
-  };
-}
-```
-
-### 3. 性能开销优化
-
-#### 3.1 缓冲区管理
-
-```javascript
-class StreamBuffer {
-  constructor(options = {}) {
-    this.maxSize = options.maxSize || 10;
-    this.flushInterval = options.flushInterval || 100;
-    this.buffer = [];
-    this.flushTimer = null;
-  }
-
-  add(operation) {
-    this.buffer.push(operation);
-    
-    // 达到最大缓冲区大小，立即刷新
-    if (this.buffer.length >= this.maxSize) {
-      this.flush();
-    } else {
-      // 否则定时刷新
-      this.scheduleFlush();
-    }
-  }
-
-  scheduleFlush() {
-    if (this.flushTimer) return;
-    
-    this.flushTimer = setTimeout(() => {
-      this.flush();
-    }, this.flushInterval);
-  }
-
-  flush() {
-    if (this.flushTimer) {
-      clearTimeout(this.flushTimer);
-      this.flushTimer = null;
-    }
-
-    if (this.buffer.length === 0) return;
-
-    const batch = this.buffer.splice(0);
-    
-    // 批量发送
-    this.sendBatch(batch);
-  }
-
-  sendBatch(batch) {
-    // 批量发送到前端
-    this.connection.send({
-      type: 'batch_update',
-      operations: batch,
-      count: batch.length
-    });
-  }
-}
-```
-
-#### 3.2 反压控制
-
-```javascript
-class BackpressureController {
-  constructor(options = {}) {
-    this.maxInFlight = options.maxInFlight || 5;
-    this.inFlight = 0;
-    this.queue = [];
-    this.paused = false;
-  }
-
-  async execute(fn) {
-    // 等待空位
-    while (this.inFlight >= this.maxInFlight || this.paused) {
-      await new Promise(resolve => {
-        this.queue.push(resolve);
-      });
-    }
-
-    this.inFlight++;
-    
-    try {
-      return await fn();
-    } finally {
-      this.inFlight--;
-      this.resume();
-    }
-  }
-
-  pause() {
-    this.paused = true;
-    console.log('⏸️  暂停流式输出');
-  }
-
-  resume() {
-    this.paused = false;
-    
-    // 唤醒等待的任务
-    while (this.queue.length > 0 && this.inFlight < this.maxInFlight) {
-      const resolve = this.queue.shift();
-      resolve();
-    }
-  }
-
-  getStatus() {
-    return {
-      inFlight: this.inFlight,
-      queued: this.queue.length,
-      paused: this.paused
-    };
-  }
-}
-```
-
-### 4. 延迟优化
-
-#### 4.1 预测性渲染
-
-```javascript
-class PredictiveRenderer {
-  constructor() {
-    this.predictions = new Map();
-  }
-
-  // 预测下一个操作
-  predict(currentOp, remainingOps) {
-    // 简单预测：相似操作可能连续
-    const nextOp = remainingOps[0];
-    if (!nextOp) return null;
-
-    if (this.isSimilar(currentOp, nextOp)) {
-      return nextOp;
-    }
-
-    return null;
-  }
-
-  isSimilar(op1, op2) {
-    return op1.type === op2.type;
-  }
-
-  // 预渲染
-  async preRender(operation) {
-    console.log(`🔮 预渲染: ${operation.type}`);
-    
-    // 提前准备资源
-    if (operation.type === 'ppt_add_image') {
-      // 预加载图片
-      await this.preloadImage(operation.data.url);
-    }
-  }
-
-  async preloadImage(url) {
-    return new Promise((resolve, reject) => {
-      const img = new Image();
-      img.onload = () => resolve(img);
-      img.onerror = reject;
-      img.src = url;
-    });
-  }
-}
-```
-
-#### 4.2 增量更新
-
-```javascript
-class IncrementalUpdater {
-  constructor() {
-    this.lastSnapshot = null;
-  }
-
-  // 只发送变化的部分
-  calculateDiff(newState, oldState) {
-    if (!oldState) return newState;
-
-    const diff = {};
-    for (const key in newState) {
-      if (JSON.stringify(newState[key]) !== JSON.stringify(oldState[key])) {
-        diff[key] = newState[key];
-      }
-    }
-
-    return diff;
-  }
-
-  send(connection, newState) {
-    const diff = this.calculateDiff(newState, this.lastSnapshot);
-    
-    if (Object.keys(diff).length > 0) {
-      connection.send({
-        type: 'incremental_update',
-        diff: diff,
-        timestamp: Date.now()
-      });
-    }
-
-    this.lastSnapshot = { ...newState };
-  }
-}
-```
-
-### 5. 准确性保障
-
-#### 5.1 操作验证
-
-```javascript
-class OperationValidator {
-  validate(operation) {
-    // 1. 类型检查
-    if (!operation.type || typeof operation.type !== 'string') {
-      throw new Error('Invalid operation type');
-    }
-
-    // 2. 数据完整性
-    if (!operation.data) {
-      throw new Error('Missing operation data');
-    }
-
-    // 3. 依赖检查
-    if (operation.dependencies) {
-      for (const dep of operation.dependencies) {
-        if (!this.isOperationCompleted(dep)) {
-          throw new Error(`Dependency not met: ${dep}`);
-        }
-      }
-    }
-
-    // 4. 冲突检查
-    if (this.hasConflict(operation)) {
-      throw new Error('Operation conflicts with existing state');
-    }
-
-    return true;
-  }
-
-  hasConflict(operation) {
-    // 检查是否与当前状态冲突
-    // 例如：尝试删除不存在的元素
-    return false;
-  }
-}
-```
-
-#### 5.2 事务性执行
-
-```javascript
-class TransactionalExecutor {
-  constructor() {
-    this.transactions = [];
-    this.currentTransaction = null;
-  }
-
-  async beginTransaction() {
-    this.currentTransaction = {
-      id: Date.now(),
-      operations: [],
-      snapshots: [],
-      status: 'pending'
-    };
-  }
-
-  async execute(operation) {
-    // 保存快照
-    const snapshot = await this.captureSnapshot();
-    this.currentTransaction.snapshots.push(snapshot);
-
-    try {
-      // 执行操作
-      const result = await this.doExecute(operation);
-      this.currentTransaction.operations.push({
-        operation,
-        result,
-        status: 'success'
-      });
-      return result;
-    } catch (error) {
-      // 执行失败，回滚
-      this.currentTransaction.operations.push({
-        operation,
-        error,
-        status: 'failed'
-      });
-      throw error;
-    }
-  }
-
-  async commit() {
-    this.currentTransaction.status = 'committed';
-    this.transactions.push(this.currentTransaction);
-    this.currentTransaction = null;
-  }
-
-  async rollback() {
-    console.log('🔄 回滚事务');
-    
-    // 恢复到最近的快照
-    const lastSnapshot = this.currentTransaction.snapshots[0];
-    await this.restoreSnapshot(lastSnapshot);
-    
-    this.currentTransaction.status = 'rolled_back';
-    this.currentTransaction = null;
-  }
-}
-```
-
-### 6. 中断与恢复
-
-#### 6.1 优雅中断
-
-```javascript
-class GracefulInterrupter {
-  constructor() {
-    this.interrupted = false;
-    this.currentOperation = null;
-    this.completedOperations = [];
-  }
-
-  // 请求中断
-  interrupt() {
-    console.log('⚠️ 收到中断请求');
-    this.interrupted = true;
-  }
-
-  // 检查是否应该中断
-  shouldInterrupt() {
-    return this.interrupted;
-  }
-
-  // 优雅收尾
-  async gracefulShutdown(onProgress) {
-    console.log('🔚 开始优雅收尾...');
-    
-    // 1. 完成当前操作
-    if (this.currentOperation) {
-      console.log('  ⏳ 等待当前操作完成...');
-      await this.currentOperation;
-    }
-
-    // 2. 保存状态
-    console.log('  💾 保存进度...');
-    await this.saveProgress();
-
-    // 3. 通知前端
-    if (onProgress) {
-      onProgress({
-        status: 'interrupted',
-        completed: this.completedOperations.length,
-        message: '操作已中断，进度已保存'
-      });
-    }
-
-    console.log('✅ 优雅收尾完成');
-  }
-
-  // 保存进度
-  async saveProgress() {
-    const state = {
-      completed: this.completedOperations,
-      timestamp: Date.now()
-    };
-    
-    localStorage.setItem('interrupted_progress', JSON.stringify(state));
-  }
-
-  // 恢复进度
-  async restoreProgress() {
-    const stored = localStorage.getItem('interrupted_progress');
-    if (stored) {
-      const state = JSON.parse(stored);
-      this.completedOperations = state.completed;
-      console.log(`🔄 恢复进度: ${this.completedOperations.length} 个已完成操作`);
-      return state;
-    }
-    return null;
-  }
-}
-```
-
-#### 6.2 方向切换处理
-
-```javascript
-class DirectionSwitcher {
-  constructor() {
-    this.currentDirection = null;
-    this.pendingSwitch = null;
-  }
-
-  // 请求切换方向
-  async requestSwitch(newDirection) {
-    console.log(`🔄 请求切换方向: ${this.currentDirection} → ${newDirection}`);
-    
-    this.pendingSwitch = newDirection;
-    
-    // 1. 等待当前批次完成
-    await this.waitForCurrentBatch();
-    
-    // 2. 清理旧方向的资源
-    await this.cleanup(this.currentDirection);
-    
-    // 3. 初始化新方向
-    await this.initialize(newDirection);
-    
-    this.currentDirection = newDirection;
-    this.pendingSwitch = null;
-    
-    console.log(`✅ 方向切换完成: ${newDirection}`);
-  }
-
-  async waitForCurrentBatch() {
-    // 等待当前批次的所有操作完成
-    console.log('  ⏳ 等待当前批次完成...');
-    await new Promise(resolve => setTimeout(resolve, 100));
-  }
-
-  async cleanup(direction) {
-    console.log(`  🧹 清理 ${direction} 的资源...`);
-    // 清理未完成的操作
-    // 回滚部分更改
-  }
-
-  async initialize(direction) {
-    console.log(`  🚀 初始化 ${direction}...`);
-    // 准备新方向的资源
-  }
-}
-```
-
----
-
-## 📊 整合优化器
-
-```javascript
-/**
- * 生产级流式渲染器
- * 集成所有优化策略
- */
-export class ProductionStreamingRenderer {
-  constructor(options = {}) {
-    // 连接管理
-    this.connection = new StableConnection(options.wsUrl);
-    this.messageQueue = new ReliableMessageQueue(this.connection);
-    
-    // 状态管理
-    this.stateManager = new StreamingStateManager();
-    this.validator = new OperationValidator();
-    this.executor = new TransactionalExecutor();
-    
-    // 性能优化
-    this.buffer = new StreamBuffer(options.buffer);
-    this.backpressure = new BackpressureController(options.backpressure);
-    this.predictor = new PredictiveRenderer();
-    this.updater = new IncrementalUpdater();
-    
-    // 中断处理
-    this.interrupter = new GracefulInterrupter();
-    this.switcher = new DirectionSwitcher();
-  }
-
-  async streamEdit(operations, onProgress, options = {}) {
-    // 连接
-    if (!this.connection.ws) {
-      await this.connection.connect();
-    }
-
-    // 恢复会话（如果有）
-    if (options.resumeSessionId) {
-      this.stateManager.restoreState(options.resumeSessionId);
-    }
-
-    // 开始事务
-    await this.executor.beginTransaction();
-
-    try {
-      for (let i = 0; i < operations.length; i++) {
-        // 检查中断
-        if (this.interrupter.shouldInterrupt()) {
-          await this.interrupter.gracefulShutdown(onProgress);
-          break;
-        }
-
-        // 检查方向切换
-        if (this.switcher.pendingSwitch) {
-          await this.switcher.requestSwitch(this.switcher.pendingSwitch);
-        }
-
-        const operation = operations[i];
-
-        // 跳过已完成的
-        if (this.stateManager.isCompleted(i)) continue;
-
-        // 验证操作
-        this.validator.validate(operation);
-
-        // 反压控制
-        await this.backpressure.execute(async () => {
-          // 预测性渲染
-          const nextOp = this.predictor.predict(operation, operations.slice(i + 1));
-          if (nextOp) {
-            this.predictor.preRender(nextOp);
-          }
-
-          // 执行操作
-          this.interrupter.currentOperation = this.executor.execute(operation);
-          await this.interrupter.currentOperation;
-
-          // 保存检查点
-          this.stateManager.saveCheckpoint(i, operation);
-
-          // 反馈进度
-          if (onProgress) {
-            onProgress({
-              current: i + 1,
-              total: operations.length,
-              sessionId: this.stateManager.sessionId,
-              backpressure: this.backpressure.getStatus()
-            });
-          }
-        });
-      }
-
-      // 提交事务
-      await this.executor.commit();
-
-      return {
-        success: true,
-        sessionId: this.stateManager.sessionId
-      };
-
-    } catch (error) {
-      // 回滚事务
-      await this.executor.rollback();
-      throw error;
-    }
-  }
-
-  // 中断流式渲染
-  interrupt() {
-    this.interrupter.interrupt();
-  }
-
-  // 切换方向
-  async switchDirection(newDirection) {
-    await this.switcher.requestSwitch(newDirection);
-  }
-}
-```
-
----
-
-## 🎯 优化效果预期
-
-| 优化项 | 指标 | 优化前 | 优化后 | 提升 |
-|--------|------|--------|--------|------|
-| **稳定性** | 连接成功率 | 95% | 99.9% | +5% |
-| **延迟** | 首次反馈 | 200ms | 50ms | 75% ⬇️ |
-| **性能** | CPU占用 | 30% | 10% | 67% ⬇️ |
-| **准确性** | 操作成功率 | 98% | 99.9% | +2% |
-| **恢复** | 中断恢复率 | 0% | 100% | ∞ ⬆️ |
-
----
-
-**状态**: ✅ 设计完成  
-**下一步**: 实现集成测试  
-**目标**: 生产级稳定性