@dommaker/harness 1.1.0 → 1.2.0

package/src/monitoring/performance-analyzer.ts

@@ -1,400 +0,0 @@
-/**
- * Performance Analyzer
- *
- * 纯计算，零 Token 成本
- *
- * 功能：
- * - 统计汇总（每小时自动执行）
- * - 异常检测（每日检查）
- * - 趋势分析（对比上一周期）
- *
- * 与 TraceAnalyzer 的区别：
- * - TraceAnalyzer: 分析约束检查结果
- * - PerformanceAnalyzer: 分析操作耗时
- */
-
-import type {
-  PerformanceTrace,
-  PerformanceSummary,
-  PerformanceAnomaly,
-  PerformanceAnalyzerConfig,
-} from '../types/performance';
-import { PerformanceCollector } from './performance-collector';
-import {
-  groupByKey,
-  timeRangeOf,
-  calcAverage,
-  calcPercentile,
-  splitByTime,
-  writeSummaryJson,
-  readSummaryJson,
-  MIN_TREND_SAMPLES,
-} from './analyzer-base';
-
-/**
- * 默认配置
- */
-const DEFAULT_CONFIG: PerformanceAnalyzerConfig = {
-  summaryFile: '.harness/logs/performance-summary.json',
-  periodMs: 3600 * 1000, // 1 小时
-  thresholds: {
-    avgDuration: 5000,     // 平均耗时 > 5s 视为异常
-    exceededRate: 0.3,     // 超阈值率 > 30% 视为异常
-    errorRate: 0.1,        // 错误率 > 10% 视为异常
-  },
-};
-
-/**
- * Performance Analyzer
- *
- * 使用方式：
- * ```typescript
- * const analyzer = new PerformanceAnalyzer(collector);
- * const summaries = analyzer.summarize(traces);
- * const anomalies = analyzer.detectAnomalies(summaries);
- * ```
- */
-export class PerformanceAnalyzer {
-  private config: PerformanceAnalyzerConfig;
-  private collector: PerformanceCollector;
-
-  constructor(collector: PerformanceCollector, config?: Partial<PerformanceAnalyzerConfig>) {
-    this.collector = collector;
-    this.config = { ...DEFAULT_CONFIG, ...config };
-  }
-
-  /**
-   * 生成统计汇总
-   *
-   * 纯计算，零 Token 成本
-   */
-  summarize(traces: PerformanceTrace[]): PerformanceSummary[] {
-    // 按操作类型分组
-    const grouped = groupByKey(traces, t => t.operation);
-
-    const summaries: PerformanceSummary[] = [];
-
-    for (const [operation, group] of grouped) {
-      // 计算时间范围
-      const timeRange = timeRangeOf(group.map(t => t.timestamp));
-
-      // 单次遍历计算核心统计
-      const totalCalls = group.length;
-      let okCount = 0, exceededCount = 0, errorCount = 0;
-      for (const t of group) {
-        if (t.result === 'ok') okCount++;
-        else if (t.result === 'exceeded') exceededCount++;
-        else if (t.result === 'error') errorCount++;
-      }
-
-      // 计算比率
-      const okRate = totalCalls > 0 ? okCount / totalCalls : 0;
-      const exceededRate = totalCalls > 0 ? exceededCount / totalCalls : 0;
-      const errorRate = totalCalls > 0 ? errorCount / totalCalls : 0;
-
-      // 计算耗时统计
-      const durations = group.map(t => t.duration);
-      const avgDuration = calcAverage(durations);
-      const maxDuration = Math.max(...durations);
-      const minDuration = Math.min(...durations);
-      const p95Duration = calcPercentile(durations, 95);
-      const p99Duration = calcPercentile(durations, 99);
-
-      // 计算趋势
-      const recentTrend = this.calculateTrend(group);
-
-      summaries.push({
-        operation,
-        timeRange,
-        totalCalls,
-        okCount,
-        exceededCount,
-        errorCount,
-        avgDuration,
-        maxDuration,
-        minDuration,
-        p95Duration,
-        p99Duration,
-        okRate,
-        exceededRate,
-        errorRate,
-        recentTrend,
-      });
-    }
-
-    return summaries;
-  }
-
-  /**
-   * 分析最近 N 小时的 traces
-   */
-  analyzeRecent(hours: number): PerformanceSummary[] {
-    const traces = this.collector.readRecent(hours);
-    return this.summarize(traces);
-  }
-
-  /**
-   * 分析特定操作
-   */
-  analyzeOperation(operation: string): PerformanceSummary[] {
-    const traces = this.collector.readByOperation(operation);
-    return this.summarize(traces);
-  }
-
-  /**
-   * 检测异常
-   *
-   * 基于阈值检测异常模式
-   */
-  detectAnomalies(summaries: PerformanceSummary[]): PerformanceAnomaly[] {
-    const anomalies: PerformanceAnomaly[] = [];
-    const thresholds = this.config.thresholds!;
-
-    for (const summary of summaries) {
-      // 检测高平均耗时
-      if (summary.avgDuration > thresholds.avgDuration!) {
-        anomalies.push({
-          type: 'high_avg_duration',
-          operation: summary.operation,
-          message: `操作 ${summary.operation} 平均耗时 ${Math.round(summary.avgDuration)}ms，超过阈值 ${thresholds.avgDuration}ms`,
-          data: {
-            currentValue: summary.avgDuration,
-            threshold: thresholds.avgDuration!,
-          },
-          detectedAt: Date.now(),
-          suggestedAction: 'optimize',
-        });
-      }
-
-      // 检测耗时趋势上升
-      if (summary.recentTrend === 'rising') {
-        anomalies.push({
-          type: 'rising_duration',
-          operation: summary.operation,
-          message: `操作 ${summary.operation} 耗时趋势上升`,
-          data: {
-            currentValue: summary.avgDuration,
-            threshold: 0,
-            trend: 'rising',
-          },
-          detectedAt: Date.now(),
-          suggestedAction: 'optimize',
-        });
-      }
-
-      // 检测高超阈值率
-      if (summary.exceededRate > thresholds.exceededRate!) {
-        anomalies.push({
-          type: 'high_exceeded_rate',
-          operation: summary.operation,
-          message: `操作 ${summary.operation} 超阈值率 ${Math.round(summary.exceededRate * 100)}%，超过阈值 ${thresholds.exceededRate! * 100}%`,
-          data: {
-            currentValue: summary.exceededRate,
-            threshold: thresholds.exceededRate!,
-          },
-          detectedAt: Date.now(),
-          suggestedAction: 'adjust_threshold',
-        });
-      }
-
-      // 检测超阈值率上升
-      if (summary.exceededRate > 0.1 && summary.recentTrend === 'rising') {
-        anomalies.push({
-          type: 'rising_exceeded_rate',
-          operation: summary.operation,
-          message: `操作 ${summary.operation} 超阈值率 ${Math.round(summary.exceededRate * 100)}% 且趋势上升`,
-          data: {
-            currentValue: summary.exceededRate,
-            threshold: 0.1,
-            trend: 'rising',
-          },
-          detectedAt: Date.now(),
-          suggestedAction: 'optimize',
-        });
-      }
-
-      // 检测高错误率
-      if (summary.errorRate > thresholds.errorRate!) {
-        anomalies.push({
-          type: 'high_error_rate',
-          operation: summary.operation,
-          message: `操作 ${summary.operation} 错误率 ${Math.round(summary.errorRate * 100)}%，超过阈值 ${thresholds.errorRate! * 100}%`,
-          data: {
-            currentValue: summary.errorRate,
-            threshold: thresholds.errorRate!,
-          },
-          detectedAt: Date.now(),
-          suggestedAction: 'notify_user',
-        });
-      }
-    }
-
-    return anomalies;
-  }
-
-  /**
-   * 对比上一周期
-   *
-   * 计算各指标的环比变化
-   */
-  compareWithPrevious(
-    current: PerformanceSummary[],
-    previous: PerformanceSummary[]
-  ): PerformanceSummary[] {
-    const previousMap = new Map(
-      previous.map(s => [s.operation, s])
-    );
-
-    return current.map(summary => {
-      const prev = previousMap.get(summary.operation);
-
-      if (prev) {
-        summary.changeFromLastPeriod = {
-          avgDurationDelta: summary.avgDuration - prev.avgDuration,
-          exceededRateDelta: summary.exceededRate - prev.exceededRate,
-        };
-      }
-
-      return summary;
-    });
-  }
-
-  /**
-   * 计算趋势
-   *
-   * 对比前半段和后半段的平均耗时
-   */
-  private calculateTrend(traces: PerformanceTrace[]): 'stable' | 'rising' | 'falling' {
-    if (traces.length < MIN_TREND_SAMPLES) {
-      return 'stable';
-    }
-
-    // 分成前后两半（按时间排序）
-    const [firstHalf, secondHalf] = splitByTime(traces);
-
-    // 计算前半段和后半段的平均耗时
-    const firstAvg = calcAverage(firstHalf.map(t => t.duration));
-    const secondAvg = calcAverage(secondHalf.map(t => t.duration));
-
-    // 计算变化率
-    const delta = secondAvg - firstAvg;
-    const changeRate = firstAvg > 0 ? delta / firstAvg : 0;
-
-    // 判断趋势（变化 > 10% 才算显著）
-    if (changeRate > 0.1) {
-      return 'rising';
-    } else if (changeRate < -0.1) {
-      return 'falling';
-    } else {
-      return 'stable';
-    }
-  }
-
-  /**
-   * 保存汇总结果
-   */
-  saveSummary(summaries: PerformanceSummary[]): void {
-    writeSummaryJson(this.config.summaryFile!, summaries);
-  }
-
-  /**
-   * 加载上次汇总结果
-   */
-  loadSummary(): PerformanceSummary[] | null {
-    return readSummaryJson<PerformanceSummary[]>(this.config.summaryFile!);
-  }
-
-  /**
-   * 运行每小时汇总
-   *
-   * 自动执行，零 Token 成本
-   */
-  runHourlySummary(): PerformanceSummary[] {
-    // 分析最近 1 小时
-    const current = this.analyzeRecent(1);
-
-    // 加载上次汇总，对比趋势
-    const previous = this.loadSummary();
-    if (previous) {
-      this.compareWithPrevious(current, previous);
-    }
-
-    // 保存当前汇总
-    this.saveSummary(current);
-
-    return current;
-  }
-
-  /**
-   * 运行每日异常检测
-   *
-   * 返回异常列表，用于触发优化
-   */
-  runDailyAnomalyCheck(): PerformanceAnomaly[] {
-    // 分析最近 24 小时
-    const summaries = this.analyzeRecent(24);
-
-    // 检测异常
-    const anomalies = this.detectAnomalies(summaries);
-
-    return anomalies;
-  }
-
-  /**
-   * 生成报告（文本格式）
-   */
-  generateReport(summaries: PerformanceSummary[], anomalies: PerformanceAnomaly[]): string {
-    const lines: string[] = [];
-
-    lines.push('# Performance Report');
-    lines.push(`Generated: ${new Date().toISOString()}`);
-    lines.push('');
-
-    // 汇总部分
-    lines.push('## Operation Summaries');
-    lines.push('');
-
-    for (const summary of summaries) {
-      const trendEmoji = {
-        rising: '📈',
-        falling: '📉',
-        stable: '➡️',
-      }[summary.recentTrend];
-
-      lines.push(`**${summary.operation}** ${trendEmoji}`);
-      lines.push(`  - Calls: ${summary.totalCalls}`);
-      lines.push(`  - Avg: ${Math.round(summary.avgDuration)}ms`);
-      lines.push(`  - P95: ${Math.round(summary.p95Duration)}ms`);
-      lines.push(`  - P99: ${Math.round(summary.p99Duration)}ms`);
-      lines.push(`  - OK: ${Math.round(summary.okRate * 100)}%`);
-      lines.push(`  - Exceeded: ${Math.round(summary.exceededRate * 100)}%`);
-      lines.push(`  - Errors: ${Math.round(summary.errorRate * 100)}%`);
-      lines.push('');
-    }
-
-    // 异常部分
-    if (anomalies.length > 0) {
-      lines.push('## Anomalies Detected');
-      lines.push('');
-
-      for (const anomaly of anomalies) {
-        lines.push(`⚠️ **${anomaly.type}**: ${anomaly.operation}`);
-        lines.push(`  - ${anomaly.message}`);
-        lines.push(`  - Suggested: ${anomaly.suggestedAction}`);
-        lines.push('');
-      }
-    } else {
-      lines.push('## No Anomalies Detected ✅');
-    }
-
-    return lines.join('\n');
-  }
-}
-
-/**
- * 创建分析器（使用全局收集器）
- */
-export function createPerformanceAnalyzer(config?: Partial<PerformanceAnalyzerConfig>): PerformanceAnalyzer {
-  const collector = new PerformanceCollector();
-  return new PerformanceAnalyzer(collector, config);
-}

package/src/monitoring/performance-collector.ts

@@ -1,326 +0,0 @@
-/**
- * Performance Collector
- *
- * 轻量设计，零 Token 成本
- *
- * 功能：
- * - 记录操作耗时（追加写入）
- * - 批量读取 traces（按时间范围过滤）
- * - 文件滚动（防止文件过大）
- *
- * 与 TraceCollector 的区别：
- * - TraceCollector: 记录约束检查结果
- * - PerformanceCollector: 记录操作耗时
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import type {
-  PerformanceTrace,
-  PerformanceTraceFilter,
-  PerformanceCollectorConfig,
-} from '../types/performance';
-
-/**
- * 默认配置
- */
-const DEFAULT_CONFIG: PerformanceCollectorConfig = {
-  logFile: '.harness/logs/performance.log',
-  maxFileSize: 10 * 1024 * 1024, // 10MB
-  enabled: true,
-};
-
-/**
- * Performance Collector
- *
- * 使用方式：
- * ```typescript
- * const collector = new PerformanceCollector();
- * collector.recordOk('extract', 150);
- * collector.recordExceeded('invokeSkillAgent', 35000, 30000);
- * ```
- */
-export class PerformanceCollector {
-  private config: PerformanceCollectorConfig;
-  private logFile: string;
-
-  constructor(config?: Partial<PerformanceCollectorConfig>) {
-    this.config = { ...DEFAULT_CONFIG, ...config };
-    this.logFile = this.config.logFile!;
-    this.ensureDirectory();
-  }
-
-  /**
-   * 确保日志目录存在
-   */
-  private ensureDirectory(): void {
-    const dir = path.dirname(this.logFile);
-    if (!fs.existsSync(dir)) {
-      fs.mkdirSync(dir, { recursive: true });
-    }
-  }
-
-  /**
-   * 记录一条性能数据
-   *
-   * 轻量操作：
-   * - 追加写入（不读取现有内容）
-   * - 单行 JSON（便于批量处理）
-   * - 零 Token 成本
-   */
-  record(trace: PerformanceTrace): void {
-    if (!this.config.enabled) return;
-
-    // 检查文件大小，必要时滚动
-    this.checkFileSize();
-
-    // 追加写入
-    const line = JSON.stringify(trace);
-    fs.appendFileSync(this.logFile, line + '\n', 'utf-8');
-  }
-
-  /**
-   * 快捷方法：记录正常执行
-   */
-  recordOk(
-    operation: string,
-    duration: number,
-    metadata?: Record<string, unknown>
-  ): void {
-    this.record({
-      operation,
-      timestamp: Date.now(),
-      duration,
-      result: 'ok',
-      metadata,
-    });
-  }
-
-  /**
-   * 快捷方法：记录超阈值
-   */
-  recordExceeded(
-    operation: string,
-    duration: number,
-    threshold: number,
-    metadata?: Record<string, unknown>
-  ): void {
-    this.record({
-      operation,
-      timestamp: Date.now(),
-      duration,
-      result: 'exceeded',
-      threshold,
-      metadata,
-    });
-  }
-
-  /**
-   * 快捷方法：记录错误
-   */
-  recordError(
-    operation: string,
-    duration: number,
-    error: Error | string,
-    metadata?: Record<string, unknown>
-  ): void {
-    this.record({
-      operation,
-      timestamp: Date.now(),
-      duration,
-      result: 'error',
-      metadata: {
-        ...metadata,
-        error: error instanceof Error ? error.message : error,
-      },
-    });
-  }
-
-  /**
-   * 批量读取 traces
-   *
-   * 支持过滤条件：
-   * - 时间范围
-   * - 操作类型
-   * - 结果类型
-   */
-  read(filter?: PerformanceTraceFilter): PerformanceTrace[] {
-    if (!fs.existsSync(this.logFile)) {
-      return [];
-    }
-
-    const content = fs.readFileSync(this.logFile, 'utf-8');
-    const lines = content.split('\n').filter(l => l.trim());
-
-    let traces = lines.map(line => JSON.parse(line) as PerformanceTrace);
-
-    // 应用过滤条件
-    if (filter) {
-      traces = this.applyFilter(traces, filter);
-    }
-
-    return traces;
-  }
-
-  /**
-   * 读取最近 N 小时的 traces
-   */
-  readRecent(hours: number): PerformanceTrace[] {
-    const start = Date.now() - hours * 3600 * 1000;
-    return this.read({ timeRange: { start, end: Date.now() } });
-  }
-
-  /**
-   * 读取特定操作的 traces
-   */
-  readByOperation(operation: string): PerformanceTrace[] {
-    return this.read({ operation });
-  }
-
-  /**
-   * 应用过滤条件
-   */
-  private applyFilter(traces: PerformanceTrace[], filter: PerformanceTraceFilter): PerformanceTrace[] {
-    return traces.filter(trace => {
-      // 操作类型
-      if (filter.operation && trace.operation !== filter.operation) {
-        return false;
-      }
-
-      // 结果
-      if (filter.result && trace.result !== filter.result) {
-        return false;
-      }
-
-      // 时间范围
-      if (filter.timeRange) {
-        if (trace.timestamp < filter.timeRange.start) {
-          return false;
-        }
-        if (filter.timeRange.end && trace.timestamp > filter.timeRange.end) {
-          return false;
-        }
-      }
-
-      // 项目路径
-      if (filter.projectPath && trace.projectPath !== filter.projectPath) {
-        return false;
-      }
-
-      // 会话 ID
-      if (filter.sessionId && trace.sessionId !== filter.sessionId) {
-        return false;
-      }
-
-      // 任务 ID
-      if (filter.taskId && trace.taskId !== filter.taskId) {
-        return false;
-      }
-
-      // 角色 ID
-      if (filter.roleId && trace.roleId !== filter.roleId) {
-        return false;
-      }
-
-      return true;
-    });
-  }
-
-  /**
-   * 检查文件大小，必要时滚动
-   */
-  private checkFileSize(): void {
-    if (!fs.existsSync(this.logFile)) {
-      return;
-    }
-
-    const stats = fs.statSync(this.logFile);
-    if (stats.size >= this.config.maxFileSize!) {
-      this.rotateFile();
-    }
-  }
-
-  /**
-   * 滚动文件
-   *
-   * 将当前文件重命名为带时间戳的备份
-   */
-  private rotateFile(): void {
-    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-    const backupFile = this.logFile.replace('.log', `-${timestamp}.log`);
-
-    // 重命名当前文件
-    fs.renameSync(this.logFile, backupFile);
-
-    // 创建新文件
-    fs.writeFileSync(this.logFile, '', 'utf-8');
-  }
-
-  /**
-   * 清理旧备份文件
-   *
-   * 删除超过 maxAge 天的备份文件
-   */
-  cleanupOldFiles(maxAgeDays: number = 30): number {
-    const dir = path.dirname(this.logFile);
-    if (!fs.existsSync(dir)) {
-      return 0;
-    }
-
-    const files = fs.readdirSync(dir);
-    const baseName = path.basename(this.logFile);
-    const backupFiles = files.filter(f => f.endsWith('.log') && f !== baseName);
-
-    const cutoffTime = Date.now() - maxAgeDays * 24 * 3600 * 1000;
-    let deletedCount = 0;
-
-    for (const file of backupFiles) {
-      const filePath = path.join(dir, file);
-      const stats = fs.statSync(filePath);
-
-      if (stats.mtimeMs < cutoffTime) {
-        fs.unlinkSync(filePath);
-        deletedCount++;
-      }
-    }
-
-    return deletedCount;
-  }
-
-  /**
-   * 获取日志文件统计信息
-   */
-  getStats(): {
-    fileExists: boolean;
-    fileSize: number;
-    totalRecords: number;
-    oldestRecord?: number;
-    newestRecord?: number;
-  } {
-    if (!fs.existsSync(this.logFile)) {
-      return { fileExists: false, fileSize: 0, totalRecords: 0 };
-    }
-
-    const stats = fs.statSync(this.logFile);
-    const content = fs.readFileSync(this.logFile, 'utf-8');
-    const lines = content.split('\n').filter(l => l.trim());
-
-    let oldest: number | undefined;
-    let newest: number | undefined;
-
-    if (lines.length > 0) {
-      const firstTrace = JSON.parse(lines[0]) as PerformanceTrace;
-      const lastTrace = JSON.parse(lines[lines.length - 1]) as PerformanceTrace;
-      oldest = firstTrace.timestamp;
-      newest = lastTrace.timestamp;
-    }
-
-    return {
-      fileExists: true,
-      fileSize: stats.size,
-      totalRecords: lines.length,
-      oldestRecord: oldest,
-      newestRecord: newest,
-    };
-  }
-}