page-action-cache 1.0.1

package/src/actions-executor.ts

@@ -0,0 +1,441 @@
+/**
+ * Actions Executor
+ * 操作执行器 - 执行缓存的原子化操作
+ */
+
+import type {
+  AtomicAction,
+  ExecutionResult,
+  PwAi,
+  VariableMap,
+  NavigateAction,
+  ClickAction,
+  TypeAction,
+  PressAction,
+  HoverAction,
+  ScreenshotAction,
+  EvaluateAction,
+} from "./types.js";
+
+// ============================================================================
+// Actions Executor 类
+// ============================================================================
+
+/**
+ * 操作执行器
+ */
+export class ActionsExecutor {
+  private pw: PwAi | null = null;
+  private cdpUrl: string = "";
+
+  constructor(cdpUrl?: string) {
+    if (cdpUrl) {
+      this.cdpUrl = cdpUrl;
+    }
+  }
+
+  /**
+   * 设置 Playwright 客户端
+   */
+  setPlaywrightClient(pw: PwAi): void {
+    this.pw = pw;
+  }
+
+  /**
+   * 设置 CDP URL
+   */
+  setCdpUrl(cdpUrl: string): void {
+    this.cdpUrl = cdpUrl;
+  }
+
+  /**
+   * 执行单个操作
+   */
+  async execute(
+    action: AtomicAction,
+    variables?: VariableMap
+  ): Promise<ExecutionResult> {
+    const startTime = Date.now();
+
+    try {
+      // 应用变量
+      const resolvedAction = this.applyVariables(action, variables);
+
+      // 根据操作类型执行
+      switch (resolvedAction.type) {
+        case "navigate":
+          await this.executeNavigate(resolvedAction as NavigateAction);
+          break;
+
+        case "click":
+          await this.executeClick(resolvedAction as ClickAction);
+          break;
+
+        case "type":
+          await this.executeType(resolvedAction as TypeAction);
+          break;
+
+        case "press":
+          await this.executePress(resolvedAction as PressAction);
+          break;
+
+        case "hover":
+          await this.executeHover(resolvedAction as HoverAction);
+          break;
+
+        case "screenshot":
+          await this.executeScreenshot(resolvedAction as ScreenshotAction);
+          break;
+
+        case "scroll":
+        case "wait":
+        case "select":
+        case "focus":
+        case "drag":
+        case "upload":
+          await this.executeEvaluate(resolvedAction as EvaluateAction);
+          break;
+
+        case "composite":
+          // 复合操作暂不实现
+          throw new Error("Composite actions not yet implemented");
+
+        default:
+          throw new Error(`Unsupported action type: ${action.type}`);
+      }
+
+      return {
+        action: action.type,
+        success: true,
+        duration: Date.now() - startTime,
+      };
+    } catch (error) {
+      return {
+        action: action.type,
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+        duration: Date.now() - startTime,
+      };
+    }
+  }
+
+  /**
+   * 批量执行操作
+   */
+  async executeBatch(
+    actions: AtomicAction[],
+    variables?: VariableMap,
+    options?: {
+      fromIndex?: number;
+      toIndex?: number;
+      atomic?: boolean; // 是否原子执行（全部成功或全部失败）
+    }
+  ): Promise<ExecutionResult[]> {
+    const from = options?.fromIndex ?? 0;
+    const to =
+      options?.toIndex !== undefined ? options.toIndex + 1 : actions.length;
+    const atomic = options?.atomic ?? false;
+
+    const results: ExecutionResult[] = [];
+    const actionsToExecute = actions.slice(from, to);
+
+    for (const action of actionsToExecute) {
+      const result = await this.execute(action, variables);
+      results.push(result);
+
+      // 原子执行：失败则停止
+      if (atomic && !result.success) {
+        break;
+      }
+    }
+
+    return results;
+  }
+
+  // -------------------------------------------------------------------------
+  // 具体操作实现
+  // -------------------------------------------------------------------------
+
+  private async executeNavigate(action: NavigateAction): Promise<void> {
+    if (!this.pw) {
+      throw new Error("Playwright client not set");
+    }
+
+    await this.pw.navigateViaPlaywright({
+      cdpUrl: action.cdpUrl || this.cdpUrl,
+      targetId: action.targetId,
+      url: action.url,
+      waitUntil: action.navigationPolicy?.waitUntil || "domcontentloaded",
+      timeout: action.navigationPolicy?.timeout,
+    });
+  }
+
+  private async executeClick(action: ClickAction): Promise<void> {
+    if (!this.pw) {
+      throw new Error("Playwright client not set");
+    }
+
+    await this.pw.clickViaPlaywright({
+      cdpUrl: action.cdpUrl || this.cdpUrl,
+      targetId: action.targetId,
+      ref: action.ref,
+      doubleClick: action.doubleClick,
+      button: action.button || "left",
+      modifiers: action.modifiers,
+      timeoutMs: action.timeoutMs,
+    });
+  }
+
+  private async executeType(action: TypeAction): Promise<void> {
+    if (!this.pw) {
+      throw new Error("Playwright client not set");
+    }
+
+    await this.pw.typeViaPlaywright({
+      cdpUrl: action.cdpUrl || this.cdpUrl,
+      targetId: action.targetId,
+      ref: action.ref,
+      text: action.text,
+      submit: action.submit,
+      slowly: action.slowly,
+      timeoutMs: action.timeoutMs,
+    });
+  }
+
+  private async executePress(action: PressAction): Promise<void> {
+    if (!this.pw) {
+      throw new Error("Playwright client not set");
+    }
+
+    await this.pw.pressKeyViaPlaywright({
+      cdpUrl: action.cdpUrl || this.cdpUrl,
+      targetId: action.targetId,
+      key: action.key,
+      delayMs: action.delayMs,
+    });
+  }
+
+  private async executeHover(action: HoverAction): Promise<void> {
+    if (!this.pw) {
+      throw new Error("Playwright client not set");
+    }
+
+    await this.pw.hoverViaPlaywright({
+      cdpUrl: action.cdpUrl || this.cdpUrl,
+      targetId: action.targetId,
+      ref: action.ref,
+      timeoutMs: action.timeoutMs,
+    });
+  }
+
+  private async executeScreenshot(action: ScreenshotAction): Promise<string> {
+    if (!this.pw) {
+      throw new Error("Playwright client not set");
+    }
+
+    return this.pw.screenshotViaPlaywright({
+      cdpUrl: action.cdpUrl || this.cdpUrl,
+      targetId: action.targetId,
+    });
+  }
+
+  private async executeEvaluate(action: EvaluateAction): Promise<any> {
+    if (!this.pw) {
+      throw new Error("Playwright client not set");
+    }
+
+    return this.pw.evaluateViaPlaywright({
+      cdpUrl: action.cdpUrl || this.cdpUrl,
+      targetId: action.targetId,
+      code: action.evaluate.code,
+      args: action.evaluate.args,
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // 变量替换
+  // -------------------------------------------------------------------------
+
+  /**
+   * 应用变量到操作
+   */
+  private applyVariables(
+    action: AtomicAction,
+    variables?: VariableMap
+  ): AtomicAction {
+    if (!variables) {
+      return action;
+    }
+
+    // 检查是否需要变量替换
+    if (!action.variable) {
+      return action;
+    }
+
+    // 获取变量值
+    const value = variables[action.variable];
+    if (value === undefined) {
+      // 变量未定义，返回原操作
+      return action;
+    }
+
+    // 根据操作类型设置正确的参数
+    const actionType = action.type;
+    if (actionType === "type") {
+      return { ...action, text: value as string };
+    } else if (actionType === "press") {
+      return { ...action, key: value as string };
+    } else if (actionType === "navigate") {
+      return { ...action, url: value as string };
+    } else if (actionType === "scroll" || actionType === "wait" ||
+               actionType === "select" || actionType === "focus" ||
+               actionType === "drag" || actionType === "upload") {
+      // evaluate 操作替换模板变量
+      return this.replaceTemplateVariables(action, variables);
+    } else {
+      // 其他操作替换所有字符串参数中的模板变量
+      return this.replaceTemplateVariables(action, variables);
+    }
+  }
+
+  /**
+   * 替换操作中的模板变量
+   */
+  private replaceTemplateVariables(
+    action: AtomicAction,
+    variables: VariableMap
+  ): AtomicAction {
+    const result: any = { ...action };
+
+    // 替换字符串类型参数中的 ${variable}
+    for (const key of Object.keys(action)) {
+      const value = (action as any)[key];
+      if (typeof value === "string") {
+        result[key] = value.replace(/\$\{([^}]+)\}/g, (match, varName) => {
+          const replacement = variables[varName];
+          return replacement !== undefined ? replacement : match;
+        });
+      }
+    }
+
+    // 特殊处理 evaluate.code（如果存在）
+    if (result.evaluate?.code && typeof result.evaluate.code === "string") {
+      result.evaluate.code = result.evaluate.code.replace(
+        /\$\{([^}]+)\}/g,
+        (match: string, varName: string) => {
+          const replacement = variables[varName];
+          return replacement !== undefined ? replacement : match;
+        }
+      );
+    }
+
+    return result;
+  }
+
+  // -------------------------------------------------------------------------
+  // 格式化输出
+  // -------------------------------------------------------------------------
+
+  /**
+   * 格式化操作列表
+   */
+  formatActions(actions: AtomicAction[]): string {
+    return actions
+      .map((action, i) => this.formatAction(action, i + 1))
+      .join("\n");
+  }
+
+  /**
+   * 格式化单个操作
+   */
+  private formatAction(action: AtomicAction, index: number): string {
+    switch (action.type) {
+      case "navigate":
+        return `${index}. 导航到：${(action as NavigateAction).url}`;
+
+      case "screenshot":
+        return `${index}. 截图`;
+
+      case "click":
+        const btn = (action as ClickAction).button || "left";
+        const dbl = (action as ClickAction).doubleClick ? "双击" : "";
+        const mod = (action as ClickAction).modifiers?.length
+          ? `+${(action as ClickAction).modifiers!.join("+")}`
+          : "";
+        return `${index}. ${dbl}点击（${btn}${mod}）：${action.ref}`;
+
+      case "type":
+        const txt = (action as TypeAction).text
+          ? `="${(action as TypeAction).text}"`
+          : "";
+        const sub = (action as TypeAction).submit ? " [提交]" : "";
+        const slow = (action as TypeAction).slowly ? " [慢速]" : "";
+        return `${index}. 输入：${action.ref}${txt}${sub}${slow}`;
+
+      case "press":
+        const delay = (action as PressAction).delayMs
+          ? `(${(action as PressAction).delayMs}ms)`
+          : "";
+        return `${index}. 按键：${(action as PressAction).key}${delay}${
+          action.ref ? ` @ ${action.ref}` : ""
+        }`;
+
+      case "hover":
+        return `${index}. 悬停：${action.ref}`;
+
+      case "scroll":
+        return `${index}. 滚动：${
+          (action as EvaluateAction).evaluate?.code || "向下滚动"
+        }`;
+
+      case "wait":
+        const waitDelay = action.delay ? `(${action.delay}ms)` : "";
+        return `${index}. 等待：${
+          (action as EvaluateAction).evaluate?.code || "默认等待"
+        }${waitDelay}`;
+
+      case "select":
+        return `${index}. 选择：${action.ref}`;
+
+      case "focus":
+        return `${index}. 聚焦：${action.ref}`;
+
+      case "drag":
+        return `${index}. 拖拽：${action.ref}`;
+
+      case "upload":
+        return `${index}. 上传：${action.ref}`;
+
+      default:
+        return `${index}. ${action.type}：${action.ref || ""}`;
+    }
+  }
+
+  /**
+   * 格式化执行结果
+   */
+  formatExecutionResults(results: ExecutionResult[]): string {
+    return results
+      .map((r, i) => {
+        const icon = r.success ? "✅" : "❌";
+        const time = r.duration ? `(${r.duration}ms)` : "";
+        return `${icon} 操作 ${i + 1}: ${r.action} ${time}${
+          r.error ? ` - ${r.error}` : ""
+        }`;
+      })
+      .join("\n");
+  }
+}
+
+// ============================================================================
+// 单例
+// ============================================================================
+
+let actionsExecutorInstance: ActionsExecutor | null = null;
+
+export function getActionsExecutor(cdpUrl?: string): ActionsExecutor {
+  if (!actionsExecutorInstance) {
+    actionsExecutorInstance = new ActionsExecutor(cdpUrl);
+  }
+  return actionsExecutorInstance;
+}

package/src/cache-invalidator.ts

@@ -0,0 +1,271 @@
+/**
+ * Cache Invalidator
+ * 缓存失效检测器 - 检测页面变化并失效缓存
+ */
+
+import type {
+  PageViewport,
+  PageChangeDetection,
+  PageActionCacheEntry,
+  DOMHashFeatures,
+} from "./types.js";
+
+// ============================================================================
+// Cache Invalidator 类
+// ============================================================================
+
+/**
+ * 缓存失效检测器
+ */
+export class CacheInvalidator {
+  /**
+   * 检测页面是否发生变化
+   */
+  async detectPageChange(
+    html: string,
+    _url: string,
+    _viewport: PageViewport,
+    cachedEntry?: PageActionCacheEntry
+  ): Promise<PageChangeDetection> {
+    // 计算当前 DOM hash
+    const currentHash = this.calculateDOMHash(html);
+
+    if (!cachedEntry || !cachedEntry.pageChangeDetection) {
+      return {
+        hasChanged: true,
+        changeType: "none",
+        confidence: 0,
+        domHash: currentHash,
+        lastCheckedAt: Date.now(),
+      };
+    }
+
+    const cachedHash = cachedEntry.pageChangeDetection.domHash;
+
+    // 比较 hash
+    if (currentHash === cachedHash) {
+      return {
+        hasChanged: false,
+        changeType: "none",
+        confidence: 100,
+        domHash: currentHash,
+        lastCheckedAt: Date.now(),
+      };
+    }
+
+    // 检测变化类型
+    const structureChanged = this.detectStructureChange(html);
+    const contentChanged = this.detectContentChange(html, cachedEntry);
+
+    if (structureChanged || contentChanged) {
+      return {
+        hasChanged: true,
+        changeType: structureChanged ? "structure" : "content",
+        confidence: Math.max(
+          structureChanged ? 80 : 0,
+          contentChanged ? 80 : 0
+        ),
+        domHash: currentHash,
+        lastCheckedAt: Date.now(),
+        details: structureChanged
+          ? "Form/Button count changed"
+          : "Content hash changed",
+      };
+    }
+
+    // hash 不同但结构未变，可能是动态内容
+    return {
+      hasChanged: true,
+      changeType: "content",
+      confidence: 50, // 低置信度，可能是动态内容
+      domHash: currentHash,
+      lastCheckedAt: Date.now(),
+      details: "Hash changed but structure is similar",
+    };
+  }
+
+  /**
+   * 计算 DOM hash
+   */
+  calculateDOMHash(html: string): string {
+    const features = this.extractDOMFeatures(html);
+    return this.combineFeaturesHash(features);
+  }
+
+  /**
+   * 提取 DOM 特征
+   */
+  private extractDOMFeatures(html: string): DOMHashFeatures {
+    return {
+      formCount: this.countElements(html, "form"),
+      buttonCount: this.countElements(html, "button"),
+      linkCount: this.countElements(html, "a"),
+      scriptCount: this.countElements(html, "script"),
+      headingCount:
+        this.countElements(html, "h1") +
+        this.countElements(html, "h2") +
+        this.countElements(html, "h3"),
+    };
+  }
+
+  /**
+   * 计算元素数量
+   */
+  private countElements(html: string, tagName: string): number {
+    const regex = new RegExp(`<${tagName}\\b`, "gi");
+    return (html.match(regex) || []).length;
+  }
+
+  /**
+   * 组合特征为 hash
+   */
+  private combineFeaturesHash(features: DOMHashFeatures): string {
+    const values = [
+      features.formCount,
+      features.buttonCount,
+      features.linkCount,
+      features.scriptCount,
+      features.headingCount,
+    ];
+
+    // 简单 hash 算法
+    let hash = 0;
+    for (const value of values) {
+      hash = ((hash << 5) - hash + value) | 0;
+    }
+    return hash.toString(16);
+  }
+
+  /**
+   * 检测结构变化
+   */
+  private detectStructureChange(html: string): boolean {
+    // 检查表单和按钮数量是否发生显著变化
+    const features = this.extractDOMFeatures(html);
+
+    // 如果表单数量变化，认为是结构变化
+    // 这里简化处理，实际应该与缓存条目比较
+    const hasForm = features.formCount > 0;
+
+    return !hasForm;
+  }
+
+  /**
+   * 检测内容变化
+   */
+  private detectContentChange(
+    html: string,
+    cachedEntry: PageActionCacheEntry
+  ): boolean {
+    // 简化处理：检查 HTML 长度变化
+    const lengthChanged = Math.abs(html.length - (cachedEntry.actions.length * 100)) > 500;
+
+    return lengthChanged;
+  }
+
+  /**
+   * 判断是否应该失效缓存
+   */
+  shouldInvalidate(
+    entry: PageActionCacheEntry,
+    changeResult: PageChangeDetection,
+    threshold: number = 80
+  ): boolean {
+    // 根据页面类型和置信度决定是否失效
+    const pageType = entry.pageType || "mixed";
+
+    if (pageType === "static") {
+      // 静态页面：高置信度时失效
+      return changeResult.hasChanged && changeResult.confidence >= threshold;
+    } else if (pageType === "dynamic") {
+      // 动态页面：只在结构变化时失效
+      return (
+        changeResult.hasChanged && changeResult.changeType === "structure"
+      );
+    } else {
+      // 混合页面：中等置信度时失效
+      return (
+        changeResult.hasChanged && changeResult.confidence >= threshold - 10
+      );
+    }
+  }
+
+  /**
+   * 创建渐进式失效器
+   */
+  createProgressiveInvalidator(): ProgressiveInvalidator {
+    return new ProgressiveInvalidator();
+  }
+}
+
+// ============================================================================
+// Progressive Invalidator 类
+// ============================================================================
+
+/**
+ * 渐进式失效：保留多版本
+ */
+export class ProgressiveInvalidator {
+  private versions: Map<string, string[]> = new Map();
+
+  /**
+   * 添加版本
+   */
+  addVersion(entry: PageActionCacheEntry, versionId: string): void {
+    const key = entry.key;
+
+    if (!this.versions.has(key)) {
+      this.versions.set(key, []);
+    }
+
+    const versions = this.versions.get(key)!;
+    versions.push(versionId);
+
+    // 只保留最近的 N 个版本（默认 3 个）
+    if (versions.length > 3) {
+      versions.shift();
+    }
+  }
+
+  /**
+   * 获取版本列表
+   */
+  getVersions(key: string): string[] {
+    return this.versions.get(key) || [];
+  }
+
+  /**
+   * 生成版本标识
+   */
+  generateVersion(entry: PageActionCacheEntry): string {
+    const time = new Date(entry.createdAt).toISOString().slice(0, 10); // YYYY-MM-DD
+    const pageType = entry.pageType || "unknown";
+
+    return `${pageType}-${entry.scenario}-${time}`;
+  }
+
+  /**
+   * 清理旧版本
+   */
+  cleanupOldVersions(key: string, maxVersions: number = 3): void {
+    const versions = this.getVersions(key);
+
+    if (versions.length > maxVersions) {
+      const toKeep = versions.slice(-maxVersions);
+      this.versions.set(key, toKeep);
+    }
+  }
+}
+
+// ============================================================================
+// 单例
+// ============================================================================
+
+let cacheInvalidatorInstance: CacheInvalidator | null = null;
+
+export function getCacheInvalidator(): CacheInvalidator {
+  if (!cacheInvalidatorInstance) {
+    cacheInvalidatorInstance = new CacheInvalidator();
+  }
+  return cacheInvalidatorInstance;
+}