aiwf 0.3.8 → 0.3.13

package/.aiwf/02_REQUIREMENTS/M02_Context_Engineering_Enhancement/SPECS_Token_Optimization.md

@@ -1,833 +0,0 @@
-# SPECS: Token Optimization System
-
-## 개요
-
-AIWF의 토큰 사용량을 최적화하기 위한 Context 압축 시스템의 상세 설계 문서입니다. 이 시스템은 중요한 정보를 유지하면서 토큰 사용량을 50% 이상 줄이는 것을 목표로 합니다.
-
-## 1. 토큰 사용량 분석 도구 설계
-
-### 1.1 토큰 카운팅 메커니즘
-
-```javascript
-// 토큰 카운팅 인터페이스
-class TokenCounter {
-  constructor(model = 'gpt-4') {
-    this.model = model;
-    this.encoder = this.getEncoder(model);
-  }
-
-  // 텍스트의 토큰 수 계산
-  countTokens(text) {
-    return this.encoder.encode(text).length;
-  }
-
-  // 파일의 토큰 수 계산
-  countFileTokens(filePath) {
-    const content = fs.readFileSync(filePath, 'utf8');
-    return this.countTokens(content);
-  }
-
-  // 디렉토리의 전체 토큰 수 계산
-  countDirectoryTokens(dirPath) {
-    const files = this.getMarkdownFiles(dirPath);
-    return files.reduce((total, file) => {
-      return total + this.countFileTokens(file);
-    }, 0);
-  }
-
-  // 토큰 분포 분석
-  analyzeTokenDistribution(content) {
-    const sections = this.parseSections(content);
-    return sections.map(section => ({
-      name: section.name,
-      tokens: this.countTokens(section.content),
-      percentage: (this.countTokens(section.content) / this.countTokens(content)) * 100
-    }));
-  }
-}
-```
-
-### 1.2 토큰 사용량 추적 시스템
-
-```javascript
-// 토큰 사용량 추적 인터페이스
-class TokenTracker {
-  constructor() {
-    this.usage = {
-      total: 0,
-      compressed: 0,
-      saved: 0,
-      ratio: 0
-    };
-  }
-
-  // 압축 전후 토큰 수 기록
-  trackCompression(originalTokens, compressedTokens) {
-    this.usage.total = originalTokens;
-    this.usage.compressed = compressedTokens;
-    this.usage.saved = originalTokens - compressedTokens;
-    this.usage.ratio = (this.usage.saved / originalTokens) * 100;
-  }
-
-  // 토큰 사용량 보고서 생성
-  generateReport() {
-    return {
-      originalTokens: this.usage.total,
-      compressedTokens: this.usage.compressed,
-      savedTokens: this.usage.saved,
-      compressionRatio: this.usage.ratio.toFixed(2) + '%',
-      efficiency: this.usage.ratio >= 50 ? 'High' : 'Medium'
-    };
-  }
-}
-```
-
-### 1.3 토큰 분석 대시보드
-
-```javascript
-// 토큰 분석 대시보드
-class TokenDashboard {
-  constructor(projectPath) {
-    this.projectPath = projectPath;
-    this.counter = new TokenCounter();
-    this.tracker = new TokenTracker();
-  }
-
-  // 프로젝트 토큰 분석
-  analyzeProject() {
-    const analysis = {
-      totalTokens: 0,
-      fileBreakdown: {},
-      sectionBreakdown: {},
-      compressionOpportunities: []
-    };
-
-    // 각 디렉토리별 토큰 수 분석
-    const directories = [
-      '.aiwf/01_PROJECT_DOCS',
-      '.aiwf/02_REQUIREMENTS',
-      '.aiwf/03_SPRINTS',
-      '.aiwf/04_GENERAL_TASKS'
-    ];
-
-    directories.forEach(dir => {
-      const tokens = this.counter.countDirectoryTokens(dir);
-      analysis.fileBreakdown[dir] = tokens;
-      analysis.totalTokens += tokens;
-    });
-
-    // 압축 기회 식별
-    analysis.compressionOpportunities = this.identifyCompressionOpportunities();
-
-    return analysis;
-  }
-
-  // 압축 기회 식별
-  identifyCompressionOpportunities() {
-    const opportunities = [];
-    
-    // 반복되는 콘텐츠 식별
-    opportunities.push({
-      type: 'repetitive_content',
-      description: '반복되는 템플릿 내용',
-      potential_savings: '20-30%'
-    });
-
-    // 장문의 설명 식별
-    opportunities.push({
-      type: 'verbose_descriptions',
-      description: '장문의 설명 및 예시',
-      potential_savings: '15-25%'
-    });
-
-    // 오래된 로그 식별
-    opportunities.push({
-      type: 'outdated_logs',
-      description: '오래된 로그 및 히스토리',
-      potential_savings: '10-20%'
-    });
-
-    return opportunities;
-  }
-}
-```
-
-## 2. Context 압축 알고리즘 연구 및 설계
-
-### 2.1 압축 알고리즘 아키텍처
-
-```javascript
-// Context 압축 알고리즘 클래스
-class ContextCompressor {
-  constructor(mode = 'balanced') {
-    this.mode = mode;
-    this.strategies = {
-      aggressive: new AggressiveCompressionStrategy(),
-      balanced: new BalancedCompressionStrategy(),
-      minimal: new MinimalCompressionStrategy()
-    };
-  }
-
-  // 메인 압축 메서드
-  compress(content, options = {}) {
-    const strategy = this.strategies[this.mode];
-    const compressed = strategy.compress(content, options);
-    
-    return {
-      original: content,
-      compressed: compressed.content,
-      metadata: compressed.metadata,
-      compressionRatio: this.calculateRatio(content, compressed.content)
-    };
-  }
-
-  // 압축률 계산
-  calculateRatio(original, compressed) {
-    const originalTokens = new TokenCounter().countTokens(original);
-    const compressedTokens = new TokenCounter().countTokens(compressed);
-    return ((originalTokens - compressedTokens) / originalTokens) * 100;
-  }
-}
-```
-
-### 2.2 압축 전략 인터페이스
-
-```javascript
-// 압축 전략 기본 인터페이스
-class CompressionStrategy {
-  compress(content, options) {
-    throw new Error('compress method must be implemented');
-  }
-
-  decompress(compressed, metadata) {
-    throw new Error('decompress method must be implemented');
-  }
-}
-
-// 적극적 압축 전략 (50-70% 압축)
-class AggressiveCompressionStrategy extends CompressionStrategy {
-  compress(content, options) {
-    let compressed = content;
-    
-    // 1. 반복 콘텐츠 제거
-    compressed = this.removeRepetitiveContent(compressed);
-    
-    // 2. 상세 설명 요약
-    compressed = this.summarizeDescriptions(compressed);
-    
-    // 3. 오래된 로그 제거
-    compressed = this.removeOldLogs(compressed);
-    
-    // 4. 중요도 기반 필터링
-    compressed = this.filterByImportance(compressed, 'high');
-    
-    return {
-      content: compressed,
-      metadata: {
-        strategy: 'aggressive',
-        removedSections: this.getRemovedSections(),
-        compressionLevel: 'high'
-      }
-    };
-  }
-}
-
-// 균형 압축 전략 (30-50% 압축)
-class BalancedCompressionStrategy extends CompressionStrategy {
-  compress(content, options) {
-    let compressed = content;
-    
-    // 1. 반복 콘텐츠 축약
-    compressed = this.condenseRepetitiveContent(compressed);
-    
-    // 2. 장문 설명 압축
-    compressed = this.compressLongDescriptions(compressed);
-    
-    // 3. 중요도 기반 필터링 (medium 이상)
-    compressed = this.filterByImportance(compressed, 'medium');
-    
-    return {
-      content: compressed,
-      metadata: {
-        strategy: 'balanced',
-        compressionLevel: 'medium'
-      }
-    };
-  }
-}
-
-// 최소 압축 전략 (10-30% 압축)
-class MinimalCompressionStrategy extends CompressionStrategy {
-  compress(content, options) {
-    let compressed = content;
-    
-    // 1. 공백 및 포맷팅 최적화
-    compressed = this.optimizeFormatting(compressed);
-    
-    // 2. 오래된 로그만 제거
-    compressed = this.removeOldLogs(compressed);
-    
-    return {
-      content: compressed,
-      metadata: {
-        strategy: 'minimal',
-        compressionLevel: 'low'
-      }
-    };
-  }
-}
-```
-
-## 3. 압축 레벨 및 모드 정의
-
-### 3.1 압축 모드 정의
-
-```javascript
-// 압축 모드 설정
-const COMPRESSION_MODES = {
-  aggressive: {
-    name: 'Aggressive',
-    description: '최대 압축률 (50-70%)',
-    target_ratio: 60,
-    preserves: ['critical_tasks', 'current_sprint', 'requirements'],
-    removes: ['old_logs', 'completed_tasks', 'detailed_examples', 'verbose_descriptions']
-  },
-  
-  balanced: {
-    name: 'Balanced',
-    description: '균형 압축률 (30-50%)',
-    target_ratio: 40,
-    preserves: ['active_tasks', 'requirements', 'recent_logs', 'important_notes'],
-    removes: ['old_logs', 'completed_tasks', 'redundant_content']
-  },
-  
-  minimal: {
-    name: 'Minimal',
-    description: '최소 압축률 (10-30%)',
-    target_ratio: 20,
-    preserves: ['all_tasks', 'all_requirements', 'all_documentation'],
-    removes: ['old_logs', 'formatting_redundancy']
-  }
-};
-```
-
-### 3.2 압축 레벨 시스템
-
-```javascript
-// 압축 레벨 관리 클래스
-class CompressionLevelManager {
-  constructor() {
-    this.levels = {
-      1: { name: 'Conservative', ratio: 15, risk: 'low' },
-      2: { name: 'Standard', ratio: 30, risk: 'low' },
-      3: { name: 'Moderate', ratio: 45, risk: 'medium' },
-      4: { name: 'Aggressive', ratio: 60, risk: 'high' },
-      5: { name: 'Maximum', ratio: 75, risk: 'very_high' }
-    };
-  }
-
-  // 프로젝트 크기에 따른 권장 레벨
-  getRecommendedLevel(projectSize) {
-    if (projectSize < 10000) return 1;
-    if (projectSize < 50000) return 2;
-    if (projectSize < 100000) return 3;
-    if (projectSize < 200000) return 4;
-    return 5;
-  }
-
-  // 레벨별 설정 반환
-  getLevelConfig(level) {
-    return this.levels[level] || this.levels[2];
-  }
-}
-```
-
-## 4. 중요도 기반 정보 필터링 메커니즘
-
-### 4.1 중요도 분류 시스템
-
-```javascript
-// 중요도 분류 클래스
-class ImportanceClassifier {
-  constructor() {
-    this.priorities = {
-      critical: {
-        weight: 1.0,
-        keywords: ['urgent', 'critical', 'blocking', 'error', 'failed'],
-        sections: ['active_tasks', 'current_sprint', 'requirements']
-      },
-      high: {
-        weight: 0.8,
-        keywords: ['important', 'priority', 'deadline', 'milestone'],
-        sections: ['planned_tasks', 'specifications', 'architecture']
-      },
-      medium: {
-        weight: 0.6,
-        keywords: ['enhancement', 'improvement', 'optimize'],
-        sections: ['documentation', 'tests', 'examples']
-      },
-      low: {
-        weight: 0.4,
-        keywords: ['nice-to-have', 'future', 'consider'],
-        sections: ['logs', 'history', 'templates']
-      }
-    };
-  }
-
-  // 콘텐츠 중요도 분석
-  analyzeImportance(content) {
-    const sections = this.parseContentSections(content);
-    
-    return sections.map(section => ({
-      name: section.name,
-      content: section.content,
-      importance: this.calculateImportance(section),
-      tokens: new TokenCounter().countTokens(section.content)
-    }));
-  }
-
-  // 중요도 계산
-  calculateImportance(section) {
-    let score = 0;
-    
-    // 키워드 기반 점수
-    Object.entries(this.priorities).forEach(([level, config]) => {
-      const keywordMatches = config.keywords.filter(keyword => 
-        section.content.toLowerCase().includes(keyword)
-      ).length;
-      score += keywordMatches * config.weight;
-    });
-
-    // 섹션 타입 기반 점수
-    Object.entries(this.priorities).forEach(([level, config]) => {
-      if (config.sections.includes(section.type)) {
-        score += config.weight;
-      }
-    });
-
-    // 점수를 카테고리로 변환
-    if (score >= 1.5) return 'critical';
-    if (score >= 1.0) return 'high';
-    if (score >= 0.5) return 'medium';
-    return 'low';
-  }
-}
-```
-
-### 4.2 정보 필터링 시스템
-
-```javascript
-// 정보 필터링 클래스
-class InformationFilter {
-  constructor(threshold = 'medium') {
-    this.threshold = threshold;
-    this.classifier = new ImportanceClassifier();
-  }
-
-  // 중요도 기반 필터링
-  filterByImportance(content, minImportance = this.threshold) {
-    const analyzedSections = this.classifier.analyzeImportance(content);
-    const importanceOrder = ['critical', 'high', 'medium', 'low'];
-    const minIndex = importanceOrder.indexOf(minImportance);
-    
-    const filteredSections = analyzedSections.filter(section => {
-      const sectionIndex = importanceOrder.indexOf(section.importance);
-      return sectionIndex <= minIndex;
-    });
-
-    return {
-      content: this.reconstructContent(filteredSections),
-      metadata: {
-        originalSections: analyzedSections.length,
-        filteredSections: filteredSections.length,
-        removedSections: analyzedSections.length - filteredSections.length
-      }
-    };
-  }
-
-  // 콘텐츠 재구성
-  reconstructContent(sections) {
-    return sections.map(section => section.content).join('\n\n');
-  }
-}
-```
-
-## 5. 압축/복원 파이프라인 아키텍처
-
-### 5.1 압축 파이프라인
-
-```javascript
-// 압축 파이프라인 클래스
-class CompressionPipeline {
-  constructor(options = {}) {
-    this.stages = [
-      new TokenAnalysisStage(),
-      new ImportanceAnalysisStage(),
-      new CompressionStage(options.mode || 'balanced'),
-      new ValidationStage(),
-      new MetadataGenerationStage()
-    ];
-  }
-
-  // 파이프라인 실행
-  async execute(input) {
-    let result = { content: input };
-    
-    for (const stage of this.stages) {
-      result = await stage.process(result);
-      
-      // 단계별 로깅
-      console.log(`Stage ${stage.name} completed:`, {
-        tokens: new TokenCounter().countTokens(result.content),
-        ratio: result.compressionRatio
-      });
-    }
-    
-    return result;
-  }
-}
-
-// 파이프라인 단계 인터페이스
-class PipelineStage {
-  constructor(name) {
-    this.name = name;
-  }
-
-  async process(input) {
-    throw new Error('process method must be implemented');
-  }
-}
-
-// 토큰 분석 단계
-class TokenAnalysisStage extends PipelineStage {
-  constructor() {
-    super('TokenAnalysis');
-    this.counter = new TokenCounter();
-  }
-
-  async process(input) {
-    const originalTokens = this.counter.countTokens(input.content);
-    
-    return {
-      ...input,
-      originalTokens,
-      tokenDistribution: this.counter.analyzeTokenDistribution(input.content)
-    };
-  }
-}
-
-// 중요도 분석 단계
-class ImportanceAnalysisStage extends PipelineStage {
-  constructor() {
-    super('ImportanceAnalysis');
-    this.classifier = new ImportanceClassifier();
-  }
-
-  async process(input) {
-    const importanceAnalysis = this.classifier.analyzeImportance(input.content);
-    
-    return {
-      ...input,
-      importanceAnalysis
-    };
-  }
-}
-
-// 압축 단계
-class CompressionStage extends PipelineStage {
-  constructor(mode = 'balanced') {
-    super('Compression');
-    this.compressor = new ContextCompressor(mode);
-  }
-
-  async process(input) {
-    const compressed = this.compressor.compress(input.content);
-    
-    return {
-      ...input,
-      content: compressed.compressed,
-      compressionRatio: compressed.compressionRatio,
-      compressionMetadata: compressed.metadata
-    };
-  }
-}
-```
-
-### 5.2 복원 파이프라인
-
-```javascript
-// 복원 파이프라인 클래스
-class DecompressionPipeline {
-  constructor() {
-    this.stages = [
-      new MetadataValidationStage(),
-      new DecompressionStage(),
-      new IntegrityCheckStage()
-    ];
-  }
-
-  // 복원 실행
-  async execute(compressedContent, metadata) {
-    let result = { content: compressedContent, metadata };
-    
-    for (const stage of this.stages) {
-      result = await stage.process(result);
-    }
-    
-    return result;
-  }
-}
-
-// 복원 단계
-class DecompressionStage extends PipelineStage {
-  constructor() {
-    super('Decompression');
-  }
-
-  async process(input) {
-    const strategy = this.getStrategy(input.metadata.strategy);
-    const decompressed = strategy.decompress(input.content, input.metadata);
-    
-    return {
-      ...input,
-      content: decompressed
-    };
-  }
-}
-```
-
-## 6. 성능 벤치마크 시스템
-
-### 6.1 벤치마크 테스트 스위트
-
-```javascript
-// 성능 벤치마크 클래스
-class PerformanceBenchmark {
-  constructor() {
-    this.metrics = {
-      compressionTime: [],
-      decompressionTime: [],
-      compressionRatio: [],
-      memoryUsage: [],
-      accuracy: []
-    };
-  }
-
-  // 압축 성능 테스트
-  async benchmarkCompression(testCases) {
-    const results = [];
-    
-    for (const testCase of testCases) {
-      const startTime = performance.now();
-      const startMemory = process.memoryUsage();
-      
-      const compressor = new ContextCompressor(testCase.mode);
-      const result = compressor.compress(testCase.content);
-      
-      const endTime = performance.now();
-      const endMemory = process.memoryUsage();
-      
-      results.push({
-        testCase: testCase.name,
-        compressionTime: endTime - startTime,
-        memoryUsage: endMemory.heapUsed - startMemory.heapUsed,
-        compressionRatio: result.compressionRatio,
-        originalSize: testCase.content.length,
-        compressedSize: result.compressed.length
-      });
-    }
-    
-    return results;
-  }
-
-  // 정확도 테스트
-  async benchmarkAccuracy(testCases) {
-    const results = [];
-    
-    for (const testCase of testCases) {
-      const compressor = new ContextCompressor(testCase.mode);
-      const compressed = compressor.compress(testCase.content);
-      
-      // 정보 손실 측정
-      const informationLoss = this.measureInformationLoss(
-        testCase.content,
-        compressed.compressed
-      );
-      
-      results.push({
-        testCase: testCase.name,
-        informationLoss,
-        compressionRatio: compressed.compressionRatio,
-        accuracy: 100 - informationLoss
-      });
-    }
-    
-    return results;
-  }
-
-  // 정보 손실 측정
-  measureInformationLoss(original, compressed) {
-    const originalSections = this.extractImportantSections(original);
-    const compressedSections = this.extractImportantSections(compressed);
-    
-    const lostSections = originalSections.filter(section => 
-      !compressedSections.includes(section)
-    );
-    
-    return (lostSections.length / originalSections.length) * 100;
-  }
-
-  // 성능 보고서 생성
-  generatePerformanceReport(results) {
-    return {
-      summary: {
-        averageCompressionTime: this.average(results.map(r => r.compressionTime)),
-        averageCompressionRatio: this.average(results.map(r => r.compressionRatio)),
-        averageMemoryUsage: this.average(results.map(r => r.memoryUsage)),
-        averageAccuracy: this.average(results.map(r => r.accuracy))
-      },
-      detailed: results,
-      recommendations: this.generateRecommendations(results)
-    };
-  }
-}
-```
-
-### 6.2 실시간 성능 모니터링
-
-```javascript
-// 실시간 성능 모니터링 클래스
-class PerformanceMonitor {
-  constructor() {
-    this.metrics = new Map();
-    this.alerts = [];
-  }
-
-  // 성능 메트릭 수집
-  collectMetrics(operation, startTime, endTime, metadata) {
-    const duration = endTime - startTime;
-    const key = `${operation}_${metadata.mode}`;
-    
-    if (!this.metrics.has(key)) {
-      this.metrics.set(key, []);
-    }
-    
-    this.metrics.get(key).push({
-      duration,
-      timestamp: Date.now(),
-      metadata
-    });
-    
-    // 성능 임계값 확인
-    this.checkPerformanceThresholds(key, duration);
-  }
-
-  // 성능 임계값 확인
-  checkPerformanceThresholds(operation, duration) {
-    const thresholds = {
-      compression: 3000, // 3초
-      decompression: 1000, // 1초
-      analysis: 2000 // 2초
-    };
-    
-    const threshold = thresholds[operation.split('_')[0]];
-    
-    if (duration > threshold) {
-      this.alerts.push({
-        type: 'performance_warning',
-        operation,
-        duration,
-        threshold,
-        timestamp: Date.now()
-      });
-    }
-  }
-
-  // 성능 대시보드 데이터 생성
-  getDashboardData() {
-    const data = {};
-    
-    this.metrics.forEach((values, key) => {
-      data[key] = {
-        count: values.length,
-        averageDuration: values.reduce((sum, v) => sum + v.duration, 0) / values.length,
-        lastDuration: values[values.length - 1]?.duration || 0,
-        trend: this.calculateTrend(values)
-      };
-    });
-    
-    return {
-      metrics: data,
-      alerts: this.alerts.slice(-10), // 최근 10개 알림
-      uptime: process.uptime()
-    };
-  }
-}
-```
-
-## 7. 구현 예시 및 사용법
-
-### 7.1 기본 사용법
-
-```bash
-# Context 압축 명령어
-aiwf compress --mode balanced --level 3
-
-# 특정 디렉토리 압축
-aiwf compress --path .aiwf/03_SPRINTS --mode aggressive
-
-# 압축 분석
-aiwf analyze-tokens --report
-
-# 압축 성능 벤치마크
-aiwf benchmark --mode all
-```
-
-### 7.2 프로그래밍 인터페이스
-
-```javascript
-// 압축 시스템 사용 예시
-const compressionSystem = new CompressionSystem({
-  mode: 'balanced',
-  level: 3,
-  preserveCritical: true
-});
-
-// 프로젝트 전체 압축
-const result = await compressionSystem.compressProject('/path/to/project');
-
-console.log('압축 결과:', {
-  originalTokens: result.originalTokens,
-  compressedTokens: result.compressedTokens,
-  compressionRatio: result.compressionRatio,
-  savedTokens: result.savedTokens
-});
-
-// 성능 모니터링
-const monitor = new PerformanceMonitor();
-compressionSystem.setMonitor(monitor);
-```
-
-## 8. 향후 개선 사항
-
-### 8.1 Machine Learning 기반 압축
-
-- AI 모델을 활용한 지능형 압축 전략
-- 사용자 패턴 학습을 통한 개인화된 압축
-- 자동 압축 레벨 조정
-
-### 8.2 분산 압축 시스템
-
-- 대용량 프로젝트를 위한 분산 처리
-- 병렬 압축 알고리즘
-- 클라우드 기반 압축 서비스
-
-### 8.3 실시간 압축
-
-- 실시간 context 압축
-- 스트리밍 압축 지원
-- 증분 압축 알고리즘
-
----
-
-*이 문서는 AIWF Token Optimization System의 설계 문서입니다. 구현 과정에서 세부사항이 조정될 수 있습니다.*