openclaw-multi-auto 1.4.5 → 1.4.7

package/extensions/page-action-cache/src/hooks.ts

@@ -0,0 +1,332 @@
+/**
+ * Hooks Integration
+ * Hooks 集成 - 注册 OpenClaw Hooks 来拦截和增强浏览器操作
+ */
+
+import type { CacheConfig, PageViewport } from "./types.js";
+import { getCacheStore } from "./cache-store.js";
+import { getScenarioRecognizer } from "./scenario-recognizer.js";
+import { getVariableResolver } from "./variable-resolver.js";
+
+// ============================================================================
+// 默认配置
+// ============================================================================
+
+const DEFAULT_CONFIG: CacheConfig = {
+  // === 全局开关 ===
+  enabled: true,
+  autoUseCache: true,
+
+  // === 场景识别 ===
+  scenarioRecognitionEnabled: true,
+  llmClassificationThreshold: 70,
+
+  // === 缓存策略 ===
+  cacheLevelStrategy: "auto",
+  defaultCacheLevel: "L3",
+
+  // === 缓存失效 ===
+  pageChangeDetectionEnabled: true,
+  changeInvalidationThreshold: 80,
+  invalidationStrategy: "soft",
+  maxVersionsPerEntry: 3,
+
+  // === 变量系统 ===
+  variableExtractionEnabled: true,
+  allowUserConfirmVariables: false,
+
+  // === 安全 ===
+  encryptSensitiveCache: false,
+  accessControlEnabled: false,
+  allowedUserIds: [],
+  logSanitizationEnabled: true,
+
+  // === 用户体验 ===
+  showCacheStatusToUser: true,
+  enableUserCacheConfirmation: false,
+  enableUserForcedRefresh: true,
+  enableUserCacheErrorReport: true,
+
+  // === 统计 ===
+  trackExecutionStats: true,
+  statsUpdateInterval: 60,
+};
+
+// ============================================================================
+// Hooks 注册
+// ============================================================================
+
+/**
+ * 注册页面操作缓存扩展的 Hooks
+ */
+export function registerPageActionCacheHooks(api: any, config?: Partial<CacheConfig>): void {
+  const finalConfig = { ...DEFAULT_CONFIG, ...config };
+
+  if (!finalConfig.enabled) {
+    console.log("[PageActionCache] Extension disabled");
+    return;
+  }
+
+  const cacheStore = getCacheStore();
+  const scenarioRecognizer = getScenarioRecognizer();
+  const variableResolver = getVariableResolver();
+  // UX enhancer for future use
+  // const uxEnhancer = getUXEnhancer();
+
+  // -------------------------------------------------------------------------
+  // before_tool_call hook - 场景识别和缓存拦截
+  // -------------------------------------------------------------------------
+
+  api.registerHook({
+    name: "before_tool_call",
+    priority: 100,
+    description: "页面操作缓存 - 场景识别和缓存拦截",
+
+    async handler(event: any, ctx: any) {
+      if (event.tool.name !== "browser") {
+        return { block: false };
+      }
+
+      const params = event.params;
+      const url = params.url as string;
+      const action = params.action as string;
+
+      // 只缓存特定操作
+      const cacheActions = ["navigate", "click", "type", "press", "hover"];
+      if (!cacheActions.includes(action)) {
+        return { block: false };
+      }
+
+      // 提取用户输入
+      const userInput = extractUserInput(ctx);
+      const currentUrl = url || ctx.currentUrl || "";
+
+      // 场景识别
+      if (finalConfig.scenarioRecognitionEnabled) {
+        const match = await scenarioRecognizer.recognize(userInput, currentUrl);
+
+        if (match && match.confidence >= 80) {
+          // 高置信度匹配，返回 cacheInfo
+          return {
+            block: false,
+            result: {
+              cacheInfo: {
+                exists: true,
+                scenario: match.scenario,
+                confidence: match.confidence,
+                method: match.method,
+                matchedPattern: match.matchedPattern,
+              },
+            },
+          };
+        }
+      }
+
+      // 检查缓存
+      const viewport = extractViewport(ctx, params);
+      const entry = cacheStore.get(url, viewport);
+
+      if (entry) {
+        const stats = cacheStore.getStats();
+        // L3 缓存命中，返回 cacheInfo
+        return {
+          block: false,
+          result: {
+            cacheInfo: {
+              exists: true,
+              cacheLevel: entry.cacheLevel,
+              scenario: entry.scenario,
+              actions: entry.actions,
+              variables: entry.variables,
+              cacheKey: entry.key,
+            },
+            stats: {
+              hitRate: stats.hitRate,
+              savedTokens: stats.savedTokens,
+            },
+          },
+        };
+      }
+
+      return { block: false };
+    },
+  });
+
+  // -------------------------------------------------------------------------
+  // after_tool_call hook - 保存 LLM 分析结果到缓存
+  // -------------------------------------------------------------------------
+
+  api.registerHook({
+    name: "after_tool_call",
+    priority: 100,
+    description: "页面操作缓存 - 保存 LLM 分析结果",
+
+    async handler(event: any, ctx: any) {
+      if (event.tool.name !== "browser") {
+        return;
+      }
+
+      const params = event.params;
+      const url = params.url as string;
+      const action = params.action as string;
+
+      // 只缓存特定操作
+      const cacheActions = ["navigate", "click", "type", "press", "hover"];
+      if (!cacheActions.includes(action)) {
+        return;
+      }
+
+      // 检查 LLM 是否返回了场景类型
+      const result = event.result;
+      const llmScenario = result.scenario as string | undefined;
+
+      if (!llmScenario) {
+        // 没有 LLM 标记的场景，不保存
+        return;
+      }
+
+      // 识别场景并获取变量
+      const userInput = extractUserInput(ctx);
+      const scenarioMatch = await scenarioRecognizer.recognize(userInput, url);
+
+      // 决定缓存层级
+      let cacheLevel: "L3" | "L2" | "L1" = "L3";
+      if (finalConfig.cacheLevelStrategy === "auto" && scenarioMatch) {
+        cacheLevel =
+          scenarioMatch.confidence >= 85
+            ? "L3"
+            : scenarioMatch.confidence >= 70
+              ? "L2"
+              : "L1";
+      } else {
+        cacheLevel = finalConfig.defaultCacheLevel as "L3" | "L2" | "L1";
+      }
+
+      // 解析变量
+      let variables: Record<string, string> | undefined;
+      if (finalConfig.variableExtractionEnabled && scenarioMatch) {
+        variables = variableResolver.resolveVariables(
+          userInput,
+          scenarioMatch.scenario
+        );
+      }
+
+      // 保存到缓存
+      const viewport = extractViewport(ctx, params);
+      const actions = result.actions || [];
+
+      if (actions.length > 0) {
+        cacheStore.set(url, viewport, actions, {
+          scenario: scenarioMatch?.scenario || llmScenario,
+          cacheLevel,
+          variables,
+          description: result.description || `Cached ${llmScenario} actions`,
+          pageType: result.pageType || "mixed",
+        });
+
+        console.log(
+          `[PageActionCache] Saved cache entry: ${scenarioMatch?.scenario || llmScenario} (${cacheLevel})`
+        );
+      }
+    },
+  });
+
+  // -------------------------------------------------------------------------
+  // before_prompt_build hook - 注入缓存使用指南
+  // -------------------------------------------------------------------------
+
+  api.registerHook({
+    name: "before_prompt_build",
+    priority: 50,
+    description: "页面操作缓存 - 注入缓存使用指南",
+
+    async handler(_event: any, _ctx: any) {
+      if (!finalConfig.autoUseCache) {
+        return;
+      }
+
+      const stats = cacheStore.getStats();
+
+      // 只在命中率较高时注入
+      if (stats.hitRate < 30) {
+        return;
+      }
+
+      // 构建缓存使用指南
+      const guide = `
+【页面操作缓存系统】
+
+当前缓存统计：
+- 总条目数：${stats.totalEntries}
+- 总命中：${stats.totalHits}
+- 命中率：${stats.hitRate.toFixed(1)}%
+
+已缓存的场景：
+${cacheStore.getTopScenarios(5)}
+
+使用方式：
+1. 如果工具返回 cacheInfo 信息，优先使用 execute_cached 工具
+2. 执行缓存操作可以大幅降低 token 消耗和操作延迟
+3. 如果页面结构变化，缓存会自动失效
+
+支持的场景：login, logout, search, checkout, settings, form_fill, navigate, screenshot
+
+缓存层级：
+- L3: 场景级缓存（包含变量模板）- 高置信度时直接使用
+- L2: 流程级缓存 - 中置信度时使用
+- L1: 原子级缓存 - 低置信度或无场景时使用
+
+可用的缓存工具：
+- execute_cached: 执行缓存的操作序列
+- cache_stats: 查看缓存统计
+- cache_list: 列出所有缓存
+- cache_clear: 清空缓存
+- scenario_list: 列出所有场景
+- force_refresh: 强制刷新指定缓存
+`;
+
+      return { prependContext: guide };
+    },
+  });
+
+  console.log("[PageActionCache] Hooks registered successfully");
+}
+
+// ============================================================================
+// 辅助函数
+// ============================================================================
+
+/**
+ * 从上下文提取用户输入
+ */
+function extractUserInput(ctx: any): string {
+  // 尝试从上下文中提取用户输入
+  if (ctx.message?.content) {
+    return ctx.message.content;
+  }
+  if (ctx.userInput) {
+    return ctx.userInput;
+  }
+  if (ctx.prompt) {
+    return ctx.prompt;
+  }
+  return "";
+}
+
+/**
+ * 从上下文和参数提取视口尺寸
+ */
+function extractViewport(ctx: any, params: any): PageViewport {
+  // 优先从参数获取
+  if (params.viewport) {
+    return params.viewport;
+  }
+
+  // 其次从上下文获取
+  if (ctx.viewport) {
+    return ctx.viewport;
+  }
+
+  // 默认值
+  return { width: 1920, height: 1080 };
+}

package/extensions/page-action-cache/src/index.ts

@@ -0,0 +1,104 @@
+/**
+ * Page Action Cache Extension - Main Exports
+ * 页面操作缓存扩展 - 主要导出
+ */
+
+// ============================================================================
+// 核心模块导出
+// ============================================================================
+
+export { getCacheStore } from "./cache-store.js";
+export { getScenarioRecognizer } from "./scenario-recognizer.js";
+export { getVariableResolver } from "./variable-resolver.js";
+export { getActionsExecutor } from "./actions-executor.js";
+export { getSecurityPolicy } from "./security-policy.js";
+export { getCacheInvalidator } from "./cache-invalidator.js";
+export { getUXEnhancer } from "./ux-enhancer.js";
+
+// ============================================================================
+// 类型导出
+// ============================================================================
+
+export type {
+  AtomicAction,
+  Action,
+  AtomicActionType,
+  NavigateAction,
+  ClickAction,
+  TypeAction,
+  PressAction,
+  HoverAction,
+  ScreenshotAction,
+  EvaluateAction,
+  CompositeAction,
+  PageViewport,
+  VariableMap,
+  CacheLevel,
+  PageType,
+  CacheSource,
+  DOMHashFeatures,
+  PageChangeDetection,
+  PageActionCacheEntry,
+  ScenarioRule,
+  ScenarioMatch,
+  CacheStats,
+  CacheConfig,
+  ExecutionResult,
+  PwAi,
+} from "./types.js";
+
+// ============================================================================
+// Hooks 导出
+// ============================================================================
+
+export { registerPageActionCacheHooks } from "./hooks.js";
+export { initializePageActionCache, pageActionCacheMeta } from "./hooks-entry.js";
+
+// ============================================================================
+// Tools 导出
+// ============================================================================
+
+export {
+  createExecuteCachedTool,
+  executeCached,
+} from "./tools.js";
+
+export {
+  createCacheListTool,
+  cacheList,
+} from "./tools.js";
+
+export {
+  createCacheStatsTool,
+  cacheStats,
+} from "./tools.js";
+
+export {
+  createCacheClearTool,
+  cacheClear,
+} from "./tools.js";
+
+export {
+  createScenarioListTool,
+  scenarioList,
+} from "./tools.js";
+
+export {
+  createForceRefreshTool,
+  forceRefresh,
+} from "./tools.js";
+
+export { CACHE_TOOLS } from "./tools.js";
+
+// ============================================================================
+// Cache Strategy 导出
+// ============================================================================
+
+export {
+  AutoCacheStrategy,
+  L3OnlyCacheStrategy,
+  L2OnlyCacheStrategy,
+  L1OnlyCacheStrategy,
+} from "./cache-strategy.js";
+
+export type { CacheStrategy } from "./cache-strategy.js";

package/extensions/page-action-cache/src/scenario-recognizer.ts

@@ -0,0 +1,259 @@
+/**
+ * Scenario Recognizer
+ * 场景识别器 - 多层匹配策略
+ */
+
+import type {
+  ScenarioRule,
+  ScenarioMatch,
+} from "./types.js";
+import { getCacheStore } from "./cache-store.js";
+
+// ============================================================================
+// 精确场景规则
+// ============================================================================
+
+const EXACT_SCENARIO_RULES: ScenarioRule[] = [
+  {
+    scenario: "login",
+    keywords: ["登录", "登陆", "注册", "进入", "login to", "sign in", "账号"],
+    urlPatterns: ["/login", "/signin", "/auth", "/account"],
+    priority: 100,
+    cacheLevel: "L3",
+    confidence: 90,
+  },
+  {
+    scenario: "logout",
+    keywords: ["退出", "登出", "注销", "sign out", "logout"],
+    urlPatterns: ["/logout", "/signout", "/signout"],
+    priority: 100,
+    cacheLevel: "L3",
+    confidence: 90,
+  },
+  {
+    scenario: "search",
+    keywords: ["搜索", "查找", "找", "search for", "查询"],
+    urlPatterns: ["/search", "/query", "/list"],
+    priority: 80,
+    cacheLevel: "L3",
+    confidence: 80,
+  },
+  {
+    scenario: "checkout",
+    keywords: ["结账", "结算", "支付", "收银", "买单", "checkout"],
+    urlPatterns: ["/checkout", "/cart", "/payment"],
+    priority: 90,
+    cacheLevel: "L3",
+    confidence: 85,
+  },
+  {
+    scenario: "settings",
+    keywords: ["设置", "配置", "修改", "编辑", "个人中心"],
+    urlPatterns: ["/settings", "/config", "/profile"],
+    priority: 75,
+    cacheLevel: "L3",
+    confidence: 75,
+  },
+  {
+    scenario: "form_fill",
+    keywords: ["填写", "填表单", "提交", "submit form"],
+    urlPatterns: [], // 不依赖 URL
+    priority: 70,
+    cacheLevel: "L2",
+    confidence: 70,
+  },
+  {
+    scenario: "navigate",
+    keywords: ["打开", "进入", "跳转", "go to", "open", "navigate"],
+    urlPatterns: [],
+    priority: 60,
+    cacheLevel: "L2",
+    confidence: 60,
+  },
+  {
+    scenario: "screenshot",
+    keywords: ["截图", "截图", "snapshot", "screenshot"],
+    urlPatterns: [],
+    priority: 50,
+    cacheLevel: "L1",
+    confidence: 50,
+  },
+];
+
+// ============================================================================
+// Scenario Recognizer 类
+// ============================================================================
+
+/**
+ * 场景识别器
+ */
+export class ScenarioRecognizer {
+  private cacheStore = getCacheStore();
+
+  /**
+   * 多层匹配策略
+   */
+  async recognize(
+    userInput: string,
+    currentUrl: string
+  ): Promise<ScenarioMatch | null> {
+    // 1. 精确规则匹配（高优先级，低误判）
+    const exactMatch = this.matchExactRules(userInput, currentUrl);
+    if (exactMatch && exactMatch.confidence >= 90) {
+      return exactMatch;
+    }
+
+    // 2. 语义理解（使用 LLM）
+    const llmMatch = await this.matchWithLLM(userInput, currentUrl);
+    if (llmMatch && llmMatch.confidence >= 70) {
+      return llmMatch;
+    }
+
+    // 3. 历史学习（相似输入匹配）
+    const historyMatch = this.matchHistory(userInput);
+    if (historyMatch && historyMatch.confidence >= 60) {
+      return historyMatch;
+    }
+
+    return null; // 都不匹配，交给 LLM 分析
+  }
+
+  /**
+   * 精确规则匹配
+   */
+  private matchExactRules(
+    userInput: string,
+    url: string
+  ): ScenarioMatch | null {
+    const normalizedInput = userInput.toLowerCase();
+    const normalizedUrl = url.toLowerCase();
+
+    for (const rule of EXACT_SCENARIO_RULES) {
+      // 关键词匹配
+      for (const keyword of rule.keywords) {
+        if (normalizedInput.includes(keyword.toLowerCase())) {
+          return {
+            scenario: rule.scenario,
+            confidence: rule.priority as number,
+            method: "keyword",
+            matchedPattern: keyword,
+          } as ScenarioMatch;
+        }
+      }
+
+      // URL 模式匹配
+      for (const pattern of rule.urlPatterns) {
+        if (normalizedUrl.includes(pattern.toLowerCase())) {
+          return {
+            scenario: rule.scenario,
+            confidence: rule.priority - 10, // 略低于纯关键词
+            method: "url",
+            matchedPattern: pattern,
+          };
+        }
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * LLM 分类
+   */
+  private async matchWithLLM(
+    _userInput: string,
+    _url: string
+  ): Promise<ScenarioMatch | null> {
+    // TODO: 实现 LLM 分类
+    // 使用 OpenClaw 的 LLM 进行意图分类
+    // 返回场景类型和置信度
+
+    // 暂时返回 null，等待 LLM 集成
+    return null;
+  }
+
+  /**
+   * 历史匹配
+   */
+  private matchHistory(userInput: string): ScenarioMatch | null {
+    const stats = this.cacheStore.getStats();
+
+    // 如果命中率太低，不做历史匹配
+    if (stats.hitRate < 30) {
+      return null;
+    }
+
+    // 在历史记录中查找相似输入
+    // 计算 Jaccard 相似度
+    const scenarioMatch = this.cacheStore.getScenarioMatch("search"); // 示例
+
+    if (scenarioMatch) {
+      const similarity = this.calculateJaccardSimilarity(
+        userInput,
+        scenarioMatch.scenario
+      );
+
+      if (similarity >= 0.6) {
+        return {
+          scenario: scenarioMatch.scenario,
+          confidence: Math.round(similarity * 100),
+          method: "history",
+        };
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * 计算 Jaccard 相似度
+   */
+  private calculateJaccardSimilarity(str1: string, str2: string): number {
+    const set1 = new Set(str1.toLowerCase().split(/\s+/));
+    const set2 = new Set(str2.toLowerCase().split(/\s+/));
+
+    const intersection = new Set([...set1].filter((x) => set2.has(x)));
+    const union = new Set([...set1, ...set2]);
+
+    return intersection.size / union.size;
+  }
+
+  // -------------------------------------------------------------------------
+  // 辅助方法
+  // -------------------------------------------------------------------------
+
+  /**
+   * 获取所有规则
+   */
+  getRules(): ScenarioRule[] {
+    return [...EXACT_SCENARIO_RULES];
+  }
+
+  /**
+   * 添加自定义规则
+   */
+  addRule(rule: ScenarioRule): void {
+    EXACT_SCENARIO_RULES.push(rule);
+  }
+
+  /**
+   * 获取建议的缓存层级
+   */
+  getRecommendedCacheLevel(scenario: string): "L3" | "L2" | "L1" {
+    const rule = EXACT_SCENARIO_RULES.find((r) => r.scenario === scenario);
+    return rule?.cacheLevel || "L1";
+  }
+}
+
+// ============================================================================
+// 单例
+// ============================================================================
+
+let scenarioRecognizerInstance: ScenarioRecognizer | null = null;
+
+export function getScenarioRecognizer(): ScenarioRecognizer {
+  if (!scenarioRecognizerInstance) {
+    scenarioRecognizerInstance = new ScenarioRecognizer();
+  }
+  return scenarioRecognizerInstance;
+}