page-action-cache 1.0.4 → 2.0.0

package/src/multi-level-cache.ts

@@ -0,0 +1,478 @@
+/**
+ * Multi-Level Cache - Page Action Cache
+ * 多级缓存管理器 - L3/L2/L1 缓存层次
+ */
+
+import type { CacheEntry, ScenarioType, CacheActionType } from './types.js';
+
+/**
+ * 缓存级别
+ */
+export type CacheLevel = 'L3' | 'L2' | 'L1';
+
+/**
+ * 缓存级别配置
+ */
+interface CacheLevelConfig {
+  level: CacheLevel;
+  maxSize: number;
+  ttl: number; // milliseconds
+  hitPriority: number;
+  description: string;
+}
+
+/**
+ * 缓存条目扩展
+ */
+interface ExtendedCacheEntry extends CacheEntry {
+  level: CacheLevel;
+  createdAt: number;
+  lastAccessed: number;
+  accessCount: number;
+  expiresAt: number;
+  llmClassificationScore?: number;
+}
+
+/**
+ * 缓存策略
+ */
+type CacheStrategy = 'auto' | 'l3-only' | 'l2-only' | 'l1-only';
+
+/**
+ * 多级缓存管理器
+ */
+export class MultiLevelCache {
+  private levels: Map<CacheLevel, Map<string, ExtendedCacheEntry>> = new Map();
+  private levelConfigs: Map<CacheLevel, CacheLevelConfig> = new Map();
+  private strategy: CacheStrategy = 'auto';
+  private llmThreshold: number = 0.8;
+
+  constructor() {
+    this.initializeLevels();
+  }
+
+  /**
+   * 初始化缓存级别
+   */
+  private initializeLevels(): void {
+    // L3: 持久化缓存，最大容量，最长 TTL
+    this.levelConfigs.set('L3', {
+      level: 'L3',
+      maxSize: 1000,
+      ttl: 30 * 24 * 60 * 60 * 1000, // 30 天
+      hitPriority: 1,
+      description: '持久化缓存，适合稳定的重复操作'
+    });
+
+    // L2: 内存缓存，中等容量，中等 TTL
+    this.levelConfigs.set('L2', {
+      level: 'L2',
+      maxSize: 200,
+      ttl: 7 * 24 * 60 * 60 * 1000, // 7 天
+      hitPriority: 2,
+      description: '内存缓存，适合频繁访问的操作'
+    });
+
+    // L1: 热点缓存，小容量，短 TTL
+    this.levelConfigs.set('L1', {
+      level: 'L1',
+      maxSize: 50,
+      ttl: 1 * 24 * 60 * 60 * 1000, // 1 天
+      hitPriority: 3,
+      description: '热点缓存，适合当前会话的操作'
+    });
+
+    // 初始化各级缓存
+    this.levels.set('L3', new Map());
+    this.levels.set('L2', new Map());
+    this.levels.set('L1', new Map());
+  }
+
+  /**
+   * 设置缓存策略
+   */
+  setStrategy(strategy: CacheStrategy): void {
+    this.strategy = strategy;
+  }
+
+  /**
+   * 设置 LLM 分类阈值
+   */
+  setLLMThreshold(threshold: number): void {
+    this.llmThreshold = Math.max(0, Math.min(1, threshold));
+  }
+
+  /**
+   * 添加缓存条目
+   */
+  addCache(
+    url: string,
+    viewport: string,
+    actions: Array<{
+      type: CacheActionType;
+      params?: any;
+      successCount: number;
+      failCount: number;
+    }>,
+    scenario?: ScenarioType,
+    llmScore?: number
+  ): string {
+    const key = this.getCacheKey(url, viewport);
+    const level = this.determineCacheLevel(scenario, llmScore);
+
+    const entry: ExtendedCacheEntry = {
+      id: Date.now().toString(),
+      url,
+      viewport,
+      actions,
+      scenario: scenario || 'unknown',
+      timestamp: Date.now(),
+      hitRate: 0,
+      savedActions: 0,
+      savedTime: 0,
+      level,
+      createdAt: Date.now(),
+      lastAccessed: Date.now(),
+      accessCount: 0,
+      expiresAt: Date.now() + this.levelConfigs.get(level)!.ttl,
+      llmClassificationScore: llmScore
+    };
+
+    // 确保不超过容量限制
+    this.ensureCapacity(level);
+
+    const cache = this.levels.get(level)!;
+    cache.set(key, entry);
+
+    console.log(`[MultiLevelCache] Added entry to ${level}: ${key}`);
+    return entry.id;
+  }
+
+  /**
+   * 确定缓存级别
+   */
+  private determineCacheLevel(scenario?: ScenarioType, llmScore?: number): CacheLevel {
+    // 如果指定了特定策略
+    if (this.strategy === 'l3-only') return 'L3';
+    if (this.strategy === 'l2-only') return 'L2';
+    if (this.strategy === 'l1-only') return 'L1';
+
+    // 自动策略：根据场景和 LLM 分类分数确定级别
+    if (llmScore !== undefined) {
+      if (llmScore >= this.llmThreshold) {
+        return 'L3'; // 高置信度使用 L3
+      } else if (llmScore >= 0.5) {
+        return 'L2'; // 中等置信度使用 L2
+      }
+    }
+
+    // 根据场景确定级别
+    switch (scenario) {
+      case 'login':
+      case 'payment':
+        return 'L3'; // 敏感操作使用 L3
+
+      case 'search':
+      case 'checkout':
+        return 'L2'; // 重要操作使用 L2
+
+      default:
+        return 'L1'; // 一般操作使用 L1
+    }
+  }
+
+  /**
+   * 查询缓存
+   */
+  queryCache(url: string, viewport: string): ExtendedCacheEntry | null {
+    const key = this.getCacheKey(url, viewport);
+
+    // 按优先级从高到低查询
+    const levelsToCheck: CacheLevel[] = ['L1', 'L2', 'L3'];
+
+    for (const level of levelsToCheck) {
+      if (this.strategy !== 'auto' && !this.strategy.includes(level)) {
+        continue;
+      }
+
+      const cache = this.levels.get(level);
+      if (!cache) continue;
+
+      const entry = cache.get(key);
+      if (entry) {
+        // 检查是否过期
+        if (Date.now() > entry.expiresAt) {
+          cache.delete(key);
+          continue;
+        }
+
+        // 更新访问统计
+        entry.lastAccessed = Date.now();
+        entry.accessCount++;
+
+        // 如果不是当前最高级别，考虑提升
+        if (this.shouldPromote(entry, level)) {
+          this.promoteEntry(entry, level);
+        }
+
+        return entry;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * 判断是否应该提升缓存级别
+   */
+  private shouldPromote(entry: ExtendedCacheEntry, currentLevel: CacheLevel): boolean {
+    if (currentLevel === 'L3') return false;
+
+    // 访问次数超过阈值则提升
+    const accessThreshold = currentLevel === 'L1' ? 5 : 10;
+    if (entry.accessCount >= accessThreshold) {
+      return true;
+    }
+
+    // 成功率高且场景重要则提升
+    const totalAttempts = entry.actions.reduce((sum, a) => sum + a.successCount + a.failCount, 0);
+    if (totalAttempts > 0) {
+      const successRate = entry.actions.reduce((sum, a) => sum + a.successCount, 0) / totalAttempts;
+      if (successRate > 0.9 && (entry.scenario === 'login' || entry.scenario === 'payment')) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * 提升缓存条目到更高级别
+   */
+  private promoteEntry(entry: ExtendedCacheEntry, fromLevel: CacheLevel): void {
+    const targetLevel = fromLevel === 'L1' ? 'L2' : 'L3';
+
+    const sourceCache = this.levels.get(fromLevel);
+    const targetCache = this.levels.get(targetLevel);
+
+    if (!sourceCache || !targetCache) {
+      return;
+    }
+
+    const key = this.getCacheKey(entry.url, entry.viewport || '');
+    sourceCache.delete(key);
+
+    entry.level = targetLevel;
+    entry.expiresAt = Date.now() + this.levelConfigs.get(targetLevel)!.ttl;
+    this.ensureCapacity(targetLevel);
+    targetCache.set(key, entry);
+
+    console.log(`[MultiLevelCache] Promoted entry from ${fromLevel} to ${targetLevel}: ${key}`);
+  }
+
+  /**
+   * 确保缓存容量
+   */
+  private ensureCapacity(level: CacheLevel): void {
+    const config = this.levelConfigs.get(level);
+    if (!config) return;
+
+    const cache = this.levels.get(level);
+    if (!cache) return;
+
+    while (cache.size >= config.maxSize) {
+      this.evictEntry(level);
+    }
+  }
+
+  /**
+   * 驱逐缓存条目（LRU 策略）
+   */
+  private evictEntry(level: CacheLevel): void {
+    const cache = this.levels.get(level);
+    if (!cache || cache.size === 0) return;
+
+    let oldestKey: string | null = null;
+    let oldestTime = Infinity;
+
+    for (const [key, entry] of cache.entries()) {
+      if (entry.lastAccessed < oldestTime) {
+        oldestTime = entry.lastAccessed;
+        oldestKey = key;
+      }
+    }
+
+    if (oldestKey) {
+      cache.delete(oldestKey);
+      console.log(`[MultiLevelCache] Evicted entry from ${level}: ${oldestKey}`);
+    }
+  }
+
+  /**
+   * 删除缓存条目
+   */
+  deleteCache(url: string, viewport: string): boolean {
+    const key = this.getCacheKey(url, viewport);
+    let deleted = false;
+
+    for (const [level, cache] of this.levels.entries()) {
+      if (cache.delete(key)) {
+        deleted = true;
+        console.log(`[MultiLevelCache] Deleted entry from ${level}: ${key}`);
+      }
+    }
+
+    return deleted;
+  }
+
+  /**
+   * 删除 URL 相关的所有缓存
+   */
+  deleteCacheByUrl(url: string): void {
+    const urlPrefix = `${url}:`;
+
+    for (const [_level, cache] of this.levels.entries()) {
+      const keysToDelete: string[] = [];
+
+      for (const key of cache.keys()) {
+        if (key.startsWith(urlPrefix)) {
+          keysToDelete.push(key);
+        }
+      }
+
+      for (const key of keysToDelete) {
+        cache.delete(key);
+      }
+    }
+
+    console.log(`[MultiLevelCache] Deleted cache entries for URL: ${url}`);
+  }
+
+  /**
+   * 清空指定级别的缓存
+   */
+  clearLevel(level: CacheLevel): void {
+    const cache = this.levels.get(level);
+    if (cache) {
+      const count = cache.size;
+      cache.clear();
+      console.log(`[MultiLevelCache] Cleared ${count} entries from ${level}`);
+    }
+  }
+
+  /**
+   * 清空所有缓存
+   */
+  clearAll(): void {
+    for (const [level, cache] of this.levels.entries()) {
+      const count = cache.size;
+      cache.clear();
+      console.log(`[MultiLevelCache] Cleared ${count} entries from ${level}`);
+    }
+  }
+
+  /**
+   * 获取缓存统计
+   */
+  getStats(): {
+    totalEntries: number;
+    totalHits: number;
+    hitRate: number;
+    levelStats: Record<CacheLevel, {
+      size: number;
+      maxCapacity: number;
+      usageRate: number;
+      avgAccessCount: number;
+    }>;
+  } {
+    let totalEntries = 0;
+    let totalHits = 0;
+    const levelStats: Record<CacheLevel, any> = {} as any;
+
+    for (const [level, cache] of this.levels.entries()) {
+      const config = this.levelConfigs.get(level)!;
+      totalEntries += cache.size;
+
+      let levelHits = 0;
+      let totalAccess = 0;
+
+      for (const entry of cache.values()) {
+        totalHits += entry.accessCount;
+        levelHits += entry.accessCount;
+        totalAccess += entry.accessCount;
+      }
+
+      levelStats[level] = {
+        size: cache.size,
+        maxCapacity: config.maxSize,
+        usageRate: cache.size / config.maxSize,
+        avgAccessCount: cache.size > 0 ? levelHits / cache.size : 0
+      };
+    }
+
+    // 计算命中率
+    const totalQueries = this.getQueryCount();
+    const hitRate = totalQueries > 0 ? (totalHits / totalQueries) * 100 : 0;
+
+    return {
+      totalEntries,
+      totalHits,
+      hitRate: Math.round(hitRate * 100) / 100,
+      levelStats
+    };
+  }
+
+  /**
+   * 获取查询计数（用于统计）
+   */
+  private getQueryCount(): number {
+    let count = 0;
+    for (const cache of this.levels.values()) {
+      for (const entry of cache.values()) {
+        count += entry.accessCount;
+      }
+    }
+    return count || 1; // 避免除以零
+  }
+
+  /**
+   * 生成缓存键
+   */
+  private getCacheKey(url: string, viewport: string): string {
+    return `${url}:${viewport}`;
+  }
+
+  /**
+   * 清理过期条目
+   */
+  cleanupExpired(): number {
+    let cleaned = 0;
+    const now = Date.now();
+
+    for (const [_level, cache] of this.levels.entries()) {
+      const expiredKeys: string[] = [];
+
+      for (const [key, entry] of cache.entries()) {
+        if (now > entry.expiresAt) {
+          expiredKeys.push(key);
+        }
+      }
+
+      for (const key of expiredKeys) {
+        cache.delete(key);
+        cleaned++;
+      }
+    }
+
+    if (cleaned > 0) {
+      console.log(`[MultiLevelCache] Cleaned up ${cleaned} expired entries`);
+    }
+
+    return cleaned;
+  }
+}
+
+/**
+ * 单例导出
+ */
+export const multiLevelCache = new MultiLevelCache();

package/src/scenario-recognizer.ts

@@ -0,0 +1,121 @@
+/**
+ * Scenario Recognizer - Page Action Cache
+ * 场景识别器 - 识别用户操作场景
+ */
+
+import type { ScenarioType } from './types.js';
+
+/**
+ * URL 模式匹配规则
+ */
+interface URLPattern {
+  pattern: RegExp;
+  scenario: ScenarioType;
+}
+
+/**
+ * 场景识别规则
+ */
+const SCENARIO_PATTERNS: URLPattern[] = [
+  // 登录场景
+  { pattern: /(login|signin|auth|oauth|sso|account|register|signup)/i, scenario: 'login' },
+
+  // 搜索场景
+  { pattern: /(search|query|find|explore|discover)/i, scenario: 'search' },
+
+  // 支付场景
+  { pattern: /(payment|pay|checkout|billing|invoice|transaction)/i, scenario: 'payment' },
+
+  // 结账场景
+  { pattern: /(cart|basket|order|purchase|buy)/i, scenario: 'checkout' },
+
+  // 电商场景
+  { pattern: /(shop|store|product|item|goods|marketplace)/i, scenario: 'checkout' }
+];
+
+/**
+ * 页面内容关键词
+ */
+const CONTENT_KEYWORDS: Record<ScenarioType, string[]> = {
+  login: ['username', 'password', 'email', 'phone', '登录', '密码', '用户名', '邮箱', '手机号', 'sign in', 'log in'],
+  search: ['search', 'query', '查找', '搜索', '输入', 'input'],
+  payment: ['credit card', 'debit card', 'payment method', '银行卡', '信用卡', '支付方式', 'cvv', 'expiry'],
+  checkout: ['cart', 'total', 'subtotal', 'shipping', '购物车', '总计', '运费', '收货地址'],
+  general: [],
+  unknown: []
+};
+
+/**
+ * 场景识别器
+ */
+export class ScenarioRecognizer {
+  /**
+   * 通过 URL 识别场景
+   */
+  recognizeByUrl(url: string): ScenarioType {
+    for (const { pattern, scenario } of SCENARIO_PATTERNS) {
+      if (pattern.test(url)) {
+        return scenario;
+      }
+    }
+    return 'general';
+  }
+
+  /**
+   * 通过页面内容识别场景
+   */
+  recognizeByContent(content: string): ScenarioType {
+    const lowerContent = content.toLowerCase();
+
+    for (const [scenario, keywords] of Object.entries(CONTENT_KEYWORDS)) {
+      if (keywords.length > 0) {
+        const matchedKeywords = keywords.filter(keyword =>
+          lowerContent.includes(keyword.toLowerCase())
+        );
+        if (matchedKeywords.length >= 2) {
+          return scenario as ScenarioType;
+        }
+      }
+    }
+
+    return 'general';
+  }
+
+  /**
+   * 综合识别（URL + 内容）
+   */
+  recognize(url: string, content?: string): ScenarioType {
+    const urlScenario = this.recognizeByUrl(url);
+
+    if (urlScenario !== 'general' && urlScenario !== 'unknown') {
+      return urlScenario;
+    }
+
+    if (content) {
+      return this.recognizeByContent(content);
+    }
+
+    return urlScenario;
+  }
+
+  /**
+   * 添加自定义场景规则
+   */
+  addCustomRule(pattern: RegExp, scenario: ScenarioType): void {
+    SCENARIO_PATTERNS.unshift({ pattern, scenario });
+  }
+
+  /**
+   * 添加内容关键词
+   */
+  addContentKeyword(scenario: ScenarioType, keywords: string[]): void {
+    if (CONTENT_KEYWORDS[scenario]) {
+      CONTENT_KEYWORDS[scenario].push(...keywords);
+    }
+  }
+}
+
+/**
+ * 单例导出
+ */
+export const scenarioRecognizer = new ScenarioRecognizer();

package/src/types-mock.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Mock OpenClaw Plugin SDK Types
+ * 模拟 OpenClaw 插件 SDK 类型定义
+ */
+
+export interface OpenClawPluginApi {
+  registerTool(tool: {
+    name: string;
+    description: string;
+    execute: (ctx: any) => Promise<any>;
+  }): void;
+  getConfig?: () => any;
+}
+
+export interface PluginContext {
+  params: any;
+  config?: any;
+}

package/src/types.ts

@@ -0,0 +1,66 @@
+/**
+ * Page Action Cache Types
+ * 页面操作缓存类型定义
+ */
+
+/**
+ * 缓存操作类型
+ */
+export type CacheActionType = 'navigate' | 'click' | 'screenshot' | 'type' | 'script';
+
+/**
+ * 场景类型
+ */
+export type ScenarioType = 'login' | 'search' | 'payment' | 'checkout' | 'general' | 'unknown';
+
+/**
+ * 缓存条目
+ */
+export interface CacheEntry {
+  id: string;
+  url: string;
+  viewport?: string;
+  actions: Array<{
+    type: CacheActionType;
+    params?: any;
+    successCount: number;
+    failCount: number;
+  }>;
+  scenario?: ScenarioType;
+  timestamp: number;
+  hitRate: number;
+  savedActions: number;
+  savedTime: number; // ms
+}
+
+/**
+ * 缓存统计
+ */
+export interface CacheStats {
+  totalEntries: number;
+  totalActions: number;
+  hitRate: number;
+  savedActions: number;
+  savedTime: number;
+}
+
+/**
+ * 缓存配置
+ */
+export interface PageActionCacheConfig {
+  enabled: boolean;
+  autoUseCache?: boolean;
+  scenarioRecognitionEnabled?: boolean;
+  llmClassificationThreshold?: number;
+  cacheLevelStrategy?: 'auto' | 'l3-only' | 'l2-only' | 'l1-only';
+  defaultCacheLevel?: 'L3' | 'L2' | 'L1';
+  pageChangeDetectionEnabled?: boolean;
+  changeInvalidationThreshold?: number;
+  invalidationStrategy?: 'soft' | 'hard';
+  variableExtractionEnabled?: boolean;
+  allowUserConfirmVariables?: boolean;
+  allowUserForcedRefresh?: boolean;
+  enableUserCacheErrorReport?: boolean;
+  trackExecutionStats?: boolean;
+  statsUpdateInterval?: number;
+}