page-action-cache 1.0.1

package/docs/IMPLEMENTATION.md

@@ -0,0 +1,1792 @@
+# 页面操作缓存 Extension - 实现文档
+
+## 概述
+
+本扩展实现了 OpenClaw 浏览器操作结果的智能缓存功能，通过原子化操作指令、多层缓存策略、智能场景识别和智能缓存失效机制，避免 LLM 重复分析相同页面，大幅降低 token 消耗和操作延迟。
+
+### 核心功能
+
+1. **原子化操作指令** - 将 LLM 分析结果转换为可直接复用的操作序列
+2. **智能场景识别** - 多层场景识别（规则+LLM+历史），准确匹配用户意图
+3. **多层缓存策略** - L3(场景)→L2(流程)→L1(原子)，智能匹配和淘汰
+4. **智能缓存失效** - DOM hash 监控、版本管理、渐进式失效
+5. **智能变量系统** - 从用户输入提取变量，安全替换到操作模板
+6. **效果追踪** - token 节省、时间加速、命中率、操作成功率
+
+### 问题分析
+
+```
+问题 1: 每次操作网页都要把 DOM 信息给 LLM → Token 消耗大
+问题 2: LLM 响应慢 → 整体操作慢
+
+解决方案：
+- 首次访问：LLM 分析 DOM → 生成完整操作序列 + 选择器 → 保存到缓存
+- 后续访问：检查缓存 → 直接使用保存的操作序列 → 跳过 DOM 分析 → 10x 加速
+```
+
+---
+
+## 目录结构
+
+```
+extensions/page-action-cache/
+├── package.json                    # 插件元数据和依赖
+├── index.ts                       # 插件入口点
+├── src/
+│   ├── types.ts                 # TypeScript 类型定义
+│   ├── cache-store.ts           # 缓存存储（JSON 文件）
+│   ├── cache-strategy.ts         # 缓存策略接口和实现
+│   ├── scenario-recognizer.ts    # 场景识别器
+│   ├── variable-resolver.ts      # 变量解析器
+│   ├── cache-invalidator.ts      # 缓存失效检测器
+│   ├── hooks.ts                # Hooks 注册和处理器
+│   ├── tools.ts                # 自定义缓存管理工具
+│   ├── actions-executor.ts       # 操作执行器
+│   ├── security-policy.ts        # 安全策略
+│   └── ux-enhancer.ts          # 用户体验增强
+├── skills/
+│   └── page-action-cache/
+│       └── SKILL.md            # LLM 使用指南
+└── tests/
+    ├── cache-store.test.ts
+    ├── scenario-recognizer.test.ts
+    ├── hooks.test.ts
+    └── actions-executor.test.ts
+```
+
+---
+
+## 一、数据结构设计
+
+### 1.1 缓存条目
+
+```typescript
+/**
+ * 页面操作缓存条目（支持多层缓存）
+ */
+interface PageActionCacheEntry {
+  // === 懴识信息 ===
+  key: string;                   // 缓存键：scenario|url|viewport|type
+  url: string;                   // 页面 URL（标准化）
+  viewport: PageViewport;        // 视口尺寸
+
+  // === 缓存层级 ===
+  cacheLevel: "L3" | "L2" | "L1";
+  // L3: 场景级缓存
+  // L2: 流程级缓存
+  // L1: 原子操作级缓存
+
+  // === 场景信息 ===
+  scenario: string;              // 场景名称（如 login, checkout）
+  description: string;           // 场景描述（如 "登录 example.com"）
+  variables?: VariableMap;       // 场景变量（如 username, password）
+  urlPattern?: string;          // URL 模式（用于匹配）
+
+  // === 操作序列 ===
+  actions: AtomicAction[];     // 原子化操作序列
+  screenshotPath?: string;       // 关联的截图路径
+
+  // === 时间信息 ===
+  createdAt: number;              // 创建时间戳
+  lastAccessTime: number;         // 最后访问时间
+  accessCount: number;           // 访问次数
+
+  // === 失效控制 ===
+  expiresAt: number;            // 过期时间戳
+  pageChangeDetection: PageChangeDetection; // 页面变化检测结果
+
+  // === 元数据 ===
+  source: "llm" | "manual" | "learned";    // 来源
+  version?: number;             // 缓存版本号
+  tags?: string[];             // 标签（如 login, checkout）
+  variant?: string;            // 变体标识（A/B 测试）
+
+  // === 执行统计 ===
+  successCount: number;          // 成功执行次数
+  failCount: number;            // 失败次数
+  avgExecutionTime: number;       // 平均执行时间（毫秒）
+}
+
+/**
+ * 变量映射
+ */
+interface VariableMap {
+  username?: string;
+  password?: string;
+  email?: string;
+  phone?: string;
+  code?: string;
+  token?: string;
+  custom?: Record<string, string>;
+}
+
+/**
+ * 视口尺寸
+ */
+interface PageViewport {
+  width: number;
+  height: number;
+}
+
+/**
+ * 原子化操作（完全对齐 Playwright API）
+ *
+ * 设计原则：
+ * 1. 参数名与 Playwright API 完全一致（如 ref, targetId, cdpUrl）
+ * 2. 支持的 Playwright 操作直接映射，不支持的操作使用 evaluate 实现
+ * 3. 所有操作支持 ref（元素引用）和 targetId（标签页 ID）
+ * 4. 变量替换使用 ${variable} 模板语法
+ */
+interface AtomicAction {
+  // === 通用参数 ===
+  type: "navigate" | "screenshot" | "click" | "type" | "press" |
+        "hover" | "scroll" | "wait" | "select" | "focus" | "drag" | "upload";
+  cdpUrl?: string;            // CDP 端点 URL（必需，从配置获取）
+  targetId?: string;          // 目标标签页 ID
+  ref?: string;               // 元素引用 ID（Playwright API 使用 ref 而非 selector）
+  variable?: string;          // 引用变量（如 ${username}），执行时替换
+  order: number;              // 执行顺序
+  description?: string;        // 操作描述
+
+  // === 导航参数 (type="navigate") ===
+  url?: string;               // 目标 URL
+
+  // === 点击参数 (type="click") ===
+  button?: "left" | "right" | "middle";  // 按钮标识
+  doubleClick?: boolean;       // 是否双击
+  modifiers?: Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift">;  // 修饰符
+  timeoutMs?: number;         // 超时时间（毫秒）
+
+  // === 输入参数 (type="type") ===
+  text?: string;              // 要输入的文本（可以是变量 ${username}）
+  submit?: boolean;           // 是否触发表单提交
+  slowly?: boolean;           // 是否慢速输入
+
+  // === 按键参数 (type="press") ===
+  key?: string;               // 要按的键（如 Enter, Escape, Tab）
+  delayMs?: number;           // 按键延迟（毫秒）
+
+  // === 悬停参数 (type="hover") ===
+
+  // === evaluate 操作参数（scroll, wait, select, focus, drag, upload） ===
+  // 这些操作使用 Playwright 的 evaluate API 实现
+  evaluate?: {
+    code: string;             // JavaScript 代码
+    args?: any[];            // 传递给代码的参数
+  };
+}
+
+/**
+ * Playwright 支持的按钮类型（完全对齐）
+ */
+type PlaywrightButton = "left" | "right" | "middle";
+
+/**
+ * Playwright 支持的修饰符（完全对齐）
+ */
+type PlaywrightModifier = "Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift";
+
+/**
+ * Playwright 导航策略参数
+ */
+interface NavigationPolicy {
+  waitUntil?: "load" | "domcontentloaded" | "networkidle";
+  timeout?: number;
+}
+
+/**
+ * 扩展的导航操作（包含导航策略）
+ */
+interface NavigateAction extends AtomicAction {
+  type: "navigate";
+  url: string;
+  targetId?: string;
+  navigationPolicy?: NavigationPolicy;
+}
+
+/**
+ * 扩展的点击操作（完全对齐 Playwright clickViaPlaywright）
+ */
+interface ClickAction extends AtomicAction {
+  type: "click";
+  ref: string;               // 元素引用（必需）
+  doubleClick?: boolean;
+  button?: PlaywrightButton;
+  modifiers?: PlaywrightModifier[];
+  timeoutMs?: number;
+}
+
+/**
+ * 扩展的输入操作（完全对齐 Playwright typeViaPlaywright）
+ */
+interface TypeAction extends AtomicAction {
+  type: "type";
+  ref: string;               // 元素引用（必需）
+  text: string;              // 输入文本（可以是变量 ${username}）
+  submit?: boolean;
+  slowly?: boolean;
+  timeoutMs?: number;
+}
+
+/**
+ * 扩展的按键操作（完全对齐 Playwright pressKeyViaPlaywright）
+ */
+interface PressAction extends AtomicAction {
+  type: "press";
+  ref?: string;              // 元素引用（可选，全局按键不需要）
+  key: string;              // 按键（必需）
+  delayMs?: number;
+}
+
+/**
+ * 扩展的悬停操作（完全对齐 Playwright hoverViaPlaywright）
+ */
+interface HoverAction extends AtomicAction {
+  type: "hover";
+  ref: string;               // 元素引用（必需）
+  timeoutMs?: number;
+}
+
+/**
+ * 复合操作（支持原子性）
+ */
+interface CompositeAction extends AtomicAction {
+  type: "composite";
+  actions: AtomicAction[];    // 子操作序列
+  atomic?: boolean;          // 是否原子操作（全部成功或全部失败）
+  rollback?: AtomicAction[];   // 失败时回滚操作
+  label?: string;             // 复合操作标签
+}
+
+/**
+ * 操作类型（包含复合操作）
+ */
+type Action = AtomicAction | CompositeAction;
+```
+
+### 1.2 页面变化检测
+
+```typescript
+/**
+ * 页面变化检测结果
+ */
+interface PageChangeDetection {
+  hasChanged: boolean;        // 页面是否发生变化
+  changeType: "structure" | "content" | "none";
+  confidence: number;           // 置信度 0-100
+  domHash: string;            // 当前 DOM hash
+  structureHash?: string;      // 结构特征 hash
+  lastCheckedAt: number;      // 最后检查时间
+  details?: string;            // 变化详情
+}
+
+/**
+ * DOM hash 特征
+ */
+interface DOMHashFeatures {
+  formCount: number;          // 表单数量
+  buttonCount: number;        // 按钮数量
+  linkCount: number;          // 链接数量
+  scriptCount: number;        // 脚本数量
+  headingCount: number;       // 标题数量
+}
+```
+
+### 1.3 场景识别规则
+
+```typescript
+/**
+ * 场景识别规则
+ */
+interface ScenarioRule {
+  scenario: string;           // 场景名称
+  keywords: string[];         // 关键词列表
+  urlPatterns: string[];      // URL 模式列表
+  priority: number;           // 优先级（数字越大越优先）
+  cacheLevel: "L3" | "L2";  // 建议的缓存层级
+  confidence: number;         // 最小置信度要求
+}
+
+/**
+ * 场景匹配结果
+ */
+interface ScenarioMatch {
+  scenario: string;
+  confidence: number;         // 置信度 0-100
+  method: "keyword" | "url" | "llm" | "history" | "learned";
+  matchedPattern?: string;   // 匹配的模式或规则
+}
+```
+
+### 1.4 缓存存储结构
+
+```typescript
+interface PageActionCacheStore {
+  version: number;               // 缓存格式版本
+  entries: Record<string, PageActionCacheEntry>;
+  scenarios: Map<string, ScenarioMatch>;  // 场景匹配历史
+  stats: CacheStats;
+}
+
+interface CacheStats {
+  // 基本统计
+  totalEntries: number;
+  totalHits: number;
+  totalMisses: number;
+  hitRate: number;
+
+  // 按层级统计
+  l3Hits: number;            // 场景级缓存命中
+  l2Hits: number;            // 流程级缓存命中
+  l1Hits: number;            // 原子级缓存命中
+
+  // 场景识别统计
+  scenarioMatches: number;     // 总匹配次数
+  llmClassifications: number;  // LLM 分类次数
+  learnedAssociations: number;  // 历史学习次数
+
+  // 效果统计
+  savedTokens: number;        // 估算节省的 token 数
+  savedTime: number;           // 估算节省的时间（毫秒）
+  avgExecutionTime: number;   // 平均执行时间
+
+  // 用户反馈统计
+  userConfirmations: number;  // 用户确认缓存使用的次数
+  userForcedRefreshes: number;  // 用户强制刷新的次数
+  cacheErrors: number;        // 缓存执行错误次数
+}
+```
+
+---
+
+## 二、缓存策略设计
+
+### 2.1 多层缓存架构
+
+```mermaid
+graph TD
+    A[缓存请求] --> B{匹配缓存层级}
+
+    B -->|L3: 场景级| C[优先使用]
+    B -->|L2: 流程级| D{置信度>70%时使用]
+    B -->|L1: 原子级| E[置信度>50%时使用]
+
+    C --> F[检查页面变化]
+    C -->|无变化| G[执行缓存操作]
+    C -->|有变化| H[失效缓存]
+
+    G --> I{记录统计]
+    H --> J[更新场景匹配]
+```
+
+### 2.2 缓存层级对比
+
+| 层级 | 缓存内容 | 优势 | 劣势 | TTL |
+|------|---------|------|------|-----|
+| **L3: 场景级** | scenario + actions + 变量 | 高语义 | 复杂度高 | 7 天 | 静态页 |
+| **L2: 流程级** | 多场景固定序列 | 中语义 | 复杂度中 | 1-3 天 | 常见流程 |
+| **L1: 原子级** | 单个原子操作 | 灵活组合 | 复杂度低 | 30 分钟 | 通用 |
+
+### 2.3 混合匹配策略
+
+```typescript
+/**
+ * 场景识别器
+ */
+class ScenarioRecognizer {
+  /**
+   * 多层匹配策略
+   */
+  async recognize(
+    userInput: string,
+    currentUrl: string,
+    cacheStore: PageActionCacheStore
+  ): 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 {
+    for (const rule of EXACT_SCENARIO_RULES) {
+      for (const keyword of rule.keywords) {
+        if (userInput.includes(keyword)) {
+          return {
+            scenario: rule.scenario,
+            confidence: rule.priority,
+            method: "keyword",
+            matchedPattern: keyword
+          };
+        }
+      }
+
+      for (const pattern of rule.urlPatterns) {
+        if (url.includes(pattern)) {
+          return {
+            scenario: rule.scenario,
+            confidence: rule.priority - 10,  // 略低于纯关键词
+            method: "url",
+            matchedPattern: pattern
+          };
+        }
+      }
+    }
+
+    return null;
+  }
+
+  private async matchWithLLM(userInput: string, url: string): Promise<ScenarioMatch | null> {
+    // 使用 OpenClaw 的 LLM 进行意图分类
+    // 返回场景类型和置信度
+  }
+
+  private matchHistory(userInput: string): ScenarioMatch | null {
+    // 在历史记录中查找相似输入
+    // 计算 Jaccard 相似度
+    // 返回最佳匹配和相似度
+  }
+}
+
+// 精确场景规则
+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
+  }
+];
+```
+
+### 2.4 变量解析器
+
+```typescript
+/**
+ * 变量解析器
+ */
+class VariableResolver {
+  /**
+   * 从用户输入提取变量
+   */
+  resolveVariables(
+    userInput: string,
+    scenario: string
+  ): VariableMap {
+    // 基于场景类型使用不同的解析策略
+    const resolver = this.getResolver(scenario);
+    return resolver.resolve(userInput);
+  }
+
+  private getResolver(scenario: string): VariableResolver {
+    switch (scenario) {
+      case "login":
+      case "login_with_vars":
+        return new LoginVariableResolver();
+      case "checkout":
+        return new CheckoutVariableResolver();
+      case "settings":
+        return new SettingsVariableResolver();
+      default:
+        return new GenericVariableResolver();
+    }
+  }
+}
+
+/**
+ * 登录变量解析器
+ */
+class LoginVariableResolver {
+  resolve(userInput: string): VariableMap {
+    const result: VariableMap = {};
+
+    // 解析 "用户名 xxx 密码 xxx"
+    const usernameMatch = /(?:用户名|账号|username|user)[:：\s]*([\u4e00-\u9fa5]+)/g.exec(userInput);
+    if (usernameMatch) {
+      result.username = usernameMatch[1];
+    }
+
+    const passwordMatch = /(?:密码|password|pwd)[:：\s]*(.+)/g.exec(userInput);
+    if (passwordMatch) {
+      result.password = passwordMatch[1];
+    }
+
+    return result;
+  }
+}
+
+// 示例
+// 输入："用 alice 账号登录，密码 secret123"
+// 解析结果：{ username: "alice", password: "secret123" }
+```
+
+---
+
+### 2.5 智能缓存失效
+
+```typescript
+/**
+ * 缓存失效策略
+ */
+class CacheInvalidationDetector {
+  private cacheStore: PageActionCacheStore;
+
+  /**
+   * 检测页面是否发生变化
+   */
+  async detectPageChange(
+    url: string,
+    viewport: PageViewport,
+    cachedEntry?: PageActionCacheEntry
+  ): Promise<PageChangeDetection> {
+    // 计算当前 DOM hash
+    const currentHash = await this.calculateDOMHash(url, viewport);
+
+    if (!cachedEntry || !cachedEntry.pageChangeDetection) {
+      return {
+        hasChanged: true,
+        changeType: "none",
+        confidence: 0,
+        domHash: currentHash
+      };
+    }
+
+    const cachedHash = cachedEntry.pageChangeDetection.domHash;
+    const structureChanged = await this.detectStructureChange(currentHash, cachedHash);
+    const contentChanged = await this.detectContentChange(currentHash, cachedHash);
+
+    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"
+      };
+    }
+
+    return {
+      hasChanged: false,
+      changeType: "none",
+      confidence: 100,
+      domHash: currentHash,
+      lastCheckedAt: Date.now()
+    };
+  }
+
+  private async calculateDOMHash(url: string, viewport: PageViewport): Promise<string> {
+    // 获取页面并计算 hash
+    const html = await this.fetchPageHTML(url, viewport);
+    const features = this.extractDOMFeatures(html);
+
+    // 组合多个特征的 hash
+    return this.combineFeaturesHash(features);
+  }
+
+  private extractDOMFeatures(html: string): DOMHashFeatures {
+    // 解析 HTML 提取特征
+    return {
+      formCount: this.countForms(html),
+      buttonCount: this.countButtons(html),
+      linkCount: this.countLinks(html),
+      scriptCount: this.countScripts(html),
+      headingCount: this.countHeadings(html)
+    };
+  }
+
+  private combineFeaturesHash(features: DOMHashFeatures): string {
+    // 使用简单 hash 算法组合特征
+    const values = [
+      features.formCount,
+      features.buttonCount,
+      features.linkCount,
+      features.scriptCount,
+      features.headingCount
+    ];
+    return this.hashValues(values);
+  }
+
+  private hashValues(values: number[]): string {
+    let hash = 0;
+    for (const value of values) {
+      hash = ((hash << 5) - hash) + value;
+      hash = hash | 0;
+    }
+    return hash.toString(16);
+  }
+
+  shouldInvalidate(entry: PageActionCacheEntry, changeResult: PageChangeDetection): boolean {
+    // 根据页面类型和置信度决定是否失效
+    if (!entry.pageType) return false;
+
+    const threshold = entry.pageType === "static" ? 95 : 80;
+    return changeResult.hasChanged && changeResult.confidence >= threshold;
+  }
+
+  async invalidate(url: string, viewport: PageViewport, strategy: "soft" | "hard"): Promise<void> {
+    // 策略：soft（保留旧版本）/hard（立即删除）
+    await this.cacheStore.delete(url, viewport);
+
+    if (strategy === "hard") {
+      // 硬失效：删除所有匹配的场景
+    await this.cacheStore.deleteByPattern(url);
+    }
+  }
+}
+
+/**
+ * 渐进式失效：保留多版本
+ */
+class ProgressiveInvalidator {
+  private versions: Map<string, string[]> = new Map();
+
+  invalidate(entry: PageActionCacheEntry, changeResult: PageChangeDetection): void {
+    const version = this.generateVersion(entry);
+    const key = entry.key;
+
+    if (!this.versions.has(key)) {
+      this.versions.set(key, []);
+    }
+
+    const versions = this.versions.get(key)!;
+    versions.push(version);
+
+    // 只保留最近的 N 个版本（默认 3 个）
+    if (versions.length > 3) {
+      versions.shift();
+    }
+
+    entry.version = versions.length;
+  }
+
+  private 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}`;
+  }
+}
+```
+
+---
+
+## 三、核心模块实现要点
+
+### 3.1 场景识别器 (scenario-recognizer.ts)
+
+**功能**：
+- 多层匹配：精确规则 → LLM 分类 → 历史学习
+- 置信度评分：返回 0-100 的置信度
+- 匹配方法标识：keyword, url, llm, history, learned
+- 场景类型预定义：login, logout, search, checkout, settings, form_fill 等
+
+**关键实现**：
+- `EXACT_SCENARIO_RULES`：精确定义的规则和优先级
+- `recognize()` 方法：返回最佳匹配或 null
+- 上下文感知：结合当前 URL 和历史记录
+
+---
+
+### 3.2 变量解析器 (variable-resolver.ts)
+
+**功能**：
+- 场景特定的变量解析器
+- 支持的解析器：login, checkout, settings, form_fill, search 等
+- 正则表达式模式匹配
+- 变量验证和清理
+
+**关键实现**：
+- `LoginVariableResolver`：解析用户名和密码
+- `CheckoutVariableResolver`：解析支付信息
+- `SettingsVariableResolver`：解析配置项
+- `GenericVariableResolver`：通用键值对解析
+
+---
+
+### 3.3 缓存失效检测器 (cache-invalidator.ts)
+
+**功能**：
+- DOM hash 计算：提取页面结构特征并生成 hash
+- 页面变化检测：结构变化、内容变化
+- 渐进式失效：保留多个版本，避免误删
+- 失效策略：根据页面类型和置信度决定
+
+**关键实现**：
+- `extractDOMFeatures()`：解析 HTML 提取特征
+- `combineFeaturesHash()`：组合多个特征为 hash
+- `shouldInvalidate()`：基于页面类型和置信度决定是否失效
+- `invalidate()`：支持 soft/hard 两种策略
+
+---
+
+### 3.4 安全策略 (security-policy.ts)
+
+**功能**：
+- 敏感变量检测：识别 password, token, code 等敏感字段
+- 缓存存储加密：敏感数据加密存储
+- 访问控制：基于用户 ID 的访问控制
+- 日志脱敏：输出日志时自动脱敏
+
+**关键实现**：
+- `isSensitiveAction()`：检查操作是否包含敏感变量
+- `encryptCacheEntry()`：加密敏感缓存条目
+- `canAccessCache()`：检查访问权限
+- `sanitizeForLogging()`：移除敏感信息的日志
+
+---
+
+### 3.5 用户体验增强 (ux-enhancer.ts)
+
+**功能**：
+- 缓存状态展示：向用户展示缓存命中情况
+- 用户确认机制：让用户确认是否使用缓存
+- 强制刷新：用户可以强制刷新特定页面的缓存
+- 错误反馈：用户可以报告缓存执行错误
+- 使用统计：追踪缓存效果
+
+**关键实现**：
+- `showCacheStatus()`：展示缓存匹配结果和操作列表
+- `confirmCacheUsage()`：用户确认是否使用缓存
+- `forceRefreshCache()`：强制刷新缓存
+- `reportCacheError()`：报告缓存错误
+
+---
+
+## 四、执行逻辑
+
+### 4.1 首次访问（无缓存）
+
+```
+1. 用户输入："登录 example.com"
+2. 场景识别器匹配 → 场景: login
+3. before_prompt_build hook 注入：检测到场景并提示 LLM
+4. LLM 决定使用场景 → 调用场景特定工具
+5. 工具返回：
+   - 缓存存在？否 → 使用 LLM 生成操作
+   - 缓存存在？是 → 返回场景变量和操作模板
+6. LLM 决定不使用缓存 → 正常调用 browser 工具
+7. after_tool_call hook：
+   - 缓存存在 → 保存到 L3 级缓存（包含变量）
+   - 缓存不存在 → 保存到 L1 级缓存（纯操作）
+```
+
+### 4.2 后续访问（有缓存）
+
+```
+1. 用户输入："登录 example.com"
+2. 场景识别器匹配 → 场景: login（confidence: 95）
+3. before_tool_call hook 注入：传递缓存信息给 LLM
+4. LLM 收到缓存信息：
+   - cacheInfo.exists = true
+   - cacheInfo.actions = [...]
+   - cacheInfo.variables = { username: "xxx", password: "xxx" }
+5. LLM 分析并决定：
+   - 使用缓存：调用 execute_cached 工具
+   - 不使用缓存：调用 browser 工具重新分析
+6. execute_cached 工具执行：
+   - 验证缓存未过期
+   - 检查页面变化（DOM hash）
+   - 逐个执行原子操作
+   - 返回执行结果
+7. Agent 根据结果继续
+```
+
+### 4.3 变量传递机制（Playwright 对齐版本）
+
+```typescript
+// LLM 返回的操作（带变量）- Playwright 参数名
+{
+  actions: [
+    { type: "type", ref: "#username", variable: "username", order: 1 },
+    { type: "type", ref: "#password", variable: "password", order: 2 },
+    { type: "press", key: "Tab", order: 3 },  // 切换焦点
+    { type: "click", ref: "#submit-btn", order: 4 }
+  ]
+}
+
+// 用户输入
+"登录 example.com，用户名 alice，密码 secret123"
+
+// 变量解析后
+{
+  variables: { username: "alice", password: "secret123" }
+}
+
+// 执行时替换（Playwright 对齐参数）
+{
+  actualActions: [
+    { type: "type", ref: "#username", text: "alice", order: 1 },
+    { type: "type", ref: "#password", text: "secret123", order: 2 },
+    { type: "press", key: "Tab", order: 3 },
+    { type: "click", ref: "#submit-btn", order: 4 }
+  ]
+}
+
+// 调用 Playwright API（示例）
+await pw.typeViaPlaywright({
+  cdpUrl: config.cdpUrl,
+  targetId: context.targetId,
+  ref: "#username",
+  text: "alice"
+});
+
+await pw.typeViaPlaywright({
+  cdpUrl: config.cdpUrl,
+  targetId: context.targetId,
+  ref: "#password",
+  text: "secret123"
+});
+
+await pw.pressKeyViaPlaywright({
+  cdpUrl: config.cdpUrl,
+  targetId: context.targetId,
+  key: "Tab"
+});
+
+await pw.clickViaPlaywright({
+  cdpUrl: config.cdpUrl,
+  targetId: context.targetId,
+  ref: "#submit-btn",
+  button: "left"
+});
+```
+
+---
+
+## 五、工具定义
+
+### 5.1 execute_cached（核心工具）
+
+```typescript
+{
+  name: "execute_cached",
+  label: "Execute Cached Actions",
+  description: "执行缓存的页面操作序列，跳过 LLM 分析",
+
+  parameters: {
+    type: "object",
+    properties: {
+      cacheKey: {
+        type: "string",
+        description: "缓存键（从 cache_info 中获取）"
+      },
+      fromIndex: {
+        type: "number",
+        description: "从第几个操作开始执行（默认 0）"
+      },
+      toIndex: {
+        type: "number",
+        description: "执行到第几个操作（不指定则执行全部）"
+      },
+      dryRun: {
+        type: "boolean",
+        description: "试运行模式，不实际执行"
+      },
+      force: {
+        type: "boolean",
+        description: "强制执行（忽略页面变化检测）"
+      }
+    }
+  },
+
+  execute: async (toolCallId, args) => {
+    const { cacheKey, fromIndex, toIndex, dryRun, force } = args;
+
+    // 获取缓存条目
+    const entry = await cacheStore.getEntry(cacheKey);
+
+    if (!entry) {
+      return {
+        content: [{ type: "text", text: "缓存不存在或已过期" }]
+      };
+    }
+
+    // 检查页面变化（强制模式跳过）
+    if (!force) {
+      const changeResult = await cacheInvalidator.detectPageChange(
+        entry.url,
+        entry.viewport,
+        entry
+      );
+
+      if (changeResult.hasChanged) {
+        const strategy = entry.pageType === "static" ? "soft" : "hard";
+        await cacheInvalidator.invalidate(
+          entry.url,
+          entry.viewport,
+          strategy
+        );
+
+        return {
+          content: [{
+            type: "text",
+            text: `页面已变化，缓存已失效 (${changeResult.changeType})\n` +
+                  `置信度：${changeResult.confidence}%`
+          }]
+        };
+      }
+    }
+
+    // 解析并替换变量
+    const variables = entry.variables || {};
+    const actionsToExecute = applyVariables(
+      entry.actions.slice(fromIndex || 0, toIndex !== undefined ? toIndex + 1 : undefined),
+      variables
+    );
+
+    if (dryRun) {
+      // 试运行模式，只返回不执行
+      return {
+        content: [{
+          type: "text",
+          text: `试运行模式：将执行 ${actionsToExecute.length} 个操作\n` +
+                formatActions(actionsToExecute)
+        }]
+      };
+    }
+
+    // 逐个执行操作
+    const results = [];
+    for (let i = fromIndex || 0; i < actionsToExecute.length; i++) {
+      const action = actionsToExecute[i];
+      const result = await actionsExecutor.execute(action);
+
+      results.push({
+        action: action.type,
+        success: result.success,
+        error: result.error,
+        duration: result.duration
+      });
+
+      // 检查原子性，失败则停止
+      if (action.atomic && !result.success) {
+        break;
+      }
+    }
+
+    // 更新缓存统计
+    await cacheStore.updateExecutionStats(cacheKey, results);
+
+    return {
+      content: [{
+        type: "text",
+        text: `执行完成：成功 ${results.filter(r => r.success).length}/${results.length} 个操作\n` +
+              formatExecutionResults(results)
+      }]
+    };
+  }
+}
+
+/**
+ * 应用变量替换到操作（Playwright 对齐版本）
+ *
+ * 变量替换规则：
+ * 1. 查找 action 中的 variable 字段
+ * 2. 根据操作类型将变量值设置到正确的参数：
+ *    - type 操作：设置 text 参数
+ *    - press 操作：设置 key 参数
+ *    - navigate 操作：设置 url 参数
+ * 3. 支持模板语法：${variable}
+ * 4. 未定义的变量会导致操作跳过
+ */
+function applyVariables(actions: Action[], variables: VariableMap): Action[] {
+  return actions.map(action => {
+    if (!action.variable) return action;
+
+    // 获取变量值
+    const value = variables[action.variable as string];
+    if (value === undefined) {
+      // 变量未定义，跳过此操作
+      return { ...action, skip: true };
+    }
+
+    // 根据操作类型设置正确的参数
+    switch (action.type) {
+      case "type":
+        // type 操作使用 text 参数
+        return { ...action, text: value };
+
+      case "press":
+        // press 操作使用 key 参数
+        return { ...action, key: value };
+
+      case "navigate":
+        // navigate 操作使用 url 参数
+        return { ...action, url: value };
+
+      case "select":
+      case "upload":
+        // 这些操作也可能使用 evaluate.code 中的变量
+        if (action.evaluate?.code) {
+          return {
+            ...action,
+            evaluate: {
+              ...action.evaluate,
+              code: action.evaluate.code.replace(/\$\{([^}]+)\}/g, (match, varName) => {
+                return variables[varName] || match;
+              })
+            }
+          };
+        }
+        break;
+
+      default:
+        // 其他操作尝试在所有字符串参数中替换变量
+        return replaceTemplateVariables(action, variables);
+    }
+
+    return action;
+  }).filter(a => !(a as any).skip);
+}
+
+/**
+ * 在操作的字符串参数中替换模板变量
+ */
+function 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) {
+    result.evaluate.code = result.evaluate.code.replace(/\$\{([^}]+)\}/g, (match, varName) => {
+      const replacement = variables[varName];
+      return replacement !== undefined ? replacement : match;
+    });
+  }
+
+  return result;
+}
+
+/**
+ * 格式化操作列表（Playwright 对齐版本）
+ */
+function formatActions(actions: Action[]): string {
+  return actions.map((action, i) => {
+    const base = action;
+    switch (action.type) {
+      case "navigate":
+        return `${i + 1}. 导航到：${base.url}`;
+      case "screenshot":
+        return `${i + 1}. 截图`;
+      case "click":
+        const btn = base.button || "left";
+        const dbl = base.doubleClick ? "双击" : "";
+        const mod = base.modifiers?.length ? `+${base.modifiers.join("+")}` : "";
+        return `${i + 1}. ${dbl}点击（${btn}${mod}）：${base.ref}`;
+      case "type":
+        const txt = base.text || base.value ? `="${base.text || base.value}"` : "";
+        const sub = base.submit ? " [提交]" : "";
+        const slow = base.slowly ? " [慢速]" : "";
+        return `${i + 1}. 输入：${base.ref}${txt}${sub}${slow}`;
+      case "press":
+        const delay = base.delayMs ? `(${base.delayMs}ms)` : "";
+        return `${i + 1}. 按键：${base.key}${delay}${base.ref ? ` @ ${base.ref}` : ""}`;
+      case "hover":
+        return `${i + 1}. 悬停：${base.ref}`;
+      case "scroll":
+        return `${i + 1}. 滚动：${base.evaluate?.code || "向下滚动"}`;
+      case "wait":
+        const waitDelay = base.delay ? `(${base.delay}ms)` : "";
+        return `${i + 1}. 等待：${base.evaluate?.code || "默认等待"}${waitDelay}`;
+      case "select":
+        return `${i + 1}. 选择：${base.ref}`;
+      case "focus":
+        return `${i + 1}. 聚焦：${base.ref}`;
+      case "drag":
+        return `${i + 1}. 拖拽：${base.ref}`;
+      case "upload":
+        return `${i + 1}. 上传：${base.ref}`;
+      default:
+        return `${i + 1}. ${action.type}：${base.ref}`;
+    }
+  }).join('\n');
+}
+
+function 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');
+}
+
+interface ExecutionResult {
+  action: string;
+  success: boolean;
+  error?: string;
+  duration?: number;
+}
+```
+
+### 5.2 其他工具
+
+```typescript
+// cache_stats: 查看缓存统计
+// cache_clear: 清空缓存
+// cache_list: 列出所有缓存
+// scenario_list: 列出所有场景
+// force_refresh: 强制刷新指定缓存
+```
+
+---
+
+## 六、Playwright API 对齐说明
+
+### 6.1 设计原则
+
+本扩展采用 **方案 A：完全对齐** 策略，确保原子操作接口与 Playwright API 完全兼容。
+
+**核心原则**：
+1. **参数名一致**：使用 Playwright 的参数名（`ref` 而非 `selector`，`targetId` 用于标签页指定）
+2. **类型一致**：枚举类型与 Playwright API 完全匹配
+3. **直接映射**：支持的操作直接映射到 Playwright 函数
+4. **扩展兼容**：不支持的操作通过 `evaluate` 扩展
+
+### 6.2 操作映射表
+
+| 缓存操作类型 | Playwright API | 函数签名 | 状态 |
+|------------|----------------|---------|------|
+| `navigate` | `navigateViaPlaywright` | `{ cdpUrl, targetId, url, ...navigationPolicy }` | ✅ 完全对齐 |
+| `click` | `clickViaPlaywright` | `{ cdpUrl, targetId, ref, button, doubleClick, modifiers, timeoutMs }` | ✅ 完全对齐 |
+| `type` | `typeViaPlaywright` | `{ cdpUrl, targetId, ref, text, submit, slowly, timeoutMs }` | ✅ 完全对齐 |
+| `press` | `pressKeyViaPlaywright` | `{ cdpUrl, targetId, key, delayMs }` | ✅ 完全对齐 |
+| `hover` | `hoverViaPlaywright` | `{ cdpUrl, targetId, ref, timeoutMs }` | ✅ 完全对齐 |
+| `screenshot` | `screenshotViaPlaywright` | `{ cdpUrl, targetId }` | ✅ 完全对齐 |
+| `scroll` | `evaluateViaPlaywright` | `{ code: "window.scrollTo(...)" }` | ✅ 通过 evaluate |
+| `wait` | `evaluateViaPlaywright` | `{ code: "await new Promise(r => setTimeout(r, delay))" }` | ✅ 通过 evaluate |
+| `select` | `evaluateViaPlaywright` | `{ code: "element.value = '...'" }` | ✅ 通过 evaluate |
+| `focus` | `evaluateViaPlaywright` | `{ code: "element.focus()" }` | ✅ 通过 evaluate |
+| `drag` | `evaluateViaPlaywright` | `{ code: "element.dragAndDrop(...)" }` | ✅ 通过 evaluate |
+| `upload` | `evaluateViaPlaywright` | `{ code: "element.uploadFile(...)" }` | ✅ 通过 evaluate |
+
+### 6.3 参数名对照表
+
+| 旧参数名 | 新参数名（Playwright） | 说明 |
+|---------|---------------------|------|
+| `selector` | `ref` | 元素引用 ID |
+| `value` | `text` (type) / `key` (press) / `url` (navigate) | 根据操作类型确定 |
+| `count` | - | 使用 doubleClick 替代 |
+| `delay` | `delayMs` (press) / `timeoutMs` (其他) | 统一使用 Ms 后缀 |
+| N/A | `cdpUrl` | CDP 端点 URL（必需） |
+| N/A | `targetId` | 目标标签页 ID |
+
+### 6.4 枚举类型对照
+
+#### 按钮类型
+```typescript
+// Playwright 支持的按钮
+type PlaywrightButton = "left" | "right" | "middle";
+
+// 使用示例
+{ type: "click", ref: "#btn", button: "left" }
+```
+
+#### 修饰符
+```typescript
+// Playwright 支持的修饰符
+type PlaywrightModifier = "Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift";
+
+// 使用示例
+{ type: "click", ref: "#btn", modifiers: ["Control", "Shift"] }
+```
+
+#### 导航策略
+```typescript
+interface NavigationPolicy {
+  waitUntil?: "load" | "domcontentloaded" | "networkidle";
+  timeout?: number;
+}
+
+// 使用示例
+{
+  type: "navigate",
+  url: "https://example.com",
+  navigationPolicy: {
+    waitUntil: "domcontentloaded",
+    timeout: 30000
+  }
+}
+```
+
+### 6.5 执行器实现
+
+```typescript
+/**
+ * 操作执行器（Playwright 对齐版本）
+ */
+class ActionsExecutor {
+  private pw: PwAi;  // Playwright 客户端
+
+  async execute(action: AtomicAction): Promise<ExecutionResult> {
+    const startTime = Date.now();
+
+    try {
+      // 根据操作类型调用对应的 Playwright 函数
+      switch (action.type) {
+        case "navigate":
+          await this.executeNavigate(action as NavigateAction);
+          break;
+
+        case "click":
+          await this.executeClick(action as ClickAction);
+          break;
+
+        case "type":
+          await this.executeType(action as TypeAction);
+          break;
+
+        case "press":
+          await this.executePress(action as PressAction);
+          break;
+
+        case "hover":
+          await this.executeHover(action as HoverAction);
+          break;
+
+        case "screenshot":
+          await this.executeScreenshot(action);
+          break;
+
+        case "scroll":
+        case "wait":
+        case "select":
+        case "focus":
+        case "drag":
+        case "upload":
+          await this.executeEvaluate(action);
+          break;
+
+        default:
+          throw new Error(`Unsupported action type: ${action.type}`);
+      }
+
+      return {
+        success: true,
+        duration: Date.now() - startTime
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: String(error),
+        duration: Date.now() - startTime
+      };
+    }
+  }
+
+  private async executeNavigate(action: NavigateAction): Promise<void> {
+    await this.pw.navigateViaPlaywright({
+      cdpUrl: action.cdpUrl,
+      targetId: action.targetId,
+      url: action.url,
+      ...action.navigationPolicy
+    });
+  }
+
+  private async executeClick(action: ClickAction): Promise<void> {
+    await this.pw.clickViaPlaywright({
+      cdpUrl: action.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> {
+    await this.pw.typeViaPlaywright({
+      cdpUrl: action.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> {
+    await this.pw.pressKeyViaPlaywright({
+      cdpUrl: action.cdpUrl,
+      targetId: action.targetId,
+      key: action.key,
+      delayMs: action.delayMs
+    });
+  }
+
+  private async executeHover(action: HoverAction): Promise<void> {
+    await this.pw.hoverViaPlaywright({
+      cdpUrl: action.cdpUrl,
+      targetId: action.targetId,
+      ref: action.ref,
+      timeoutMs: action.timeoutMs
+    });
+  }
+
+  private async executeScreenshot(action: AtomicAction): Promise<void> {
+    await this.pw.screenshotViaPlaywright({
+      cdpUrl: action.cdpUrl,
+      targetId: action.targetId
+    });
+  }
+
+  private async executeEvaluate(action: AtomicAction): Promise<void> {
+    if (!action.evaluate?.code) {
+      throw new Error(`evaluate action missing code for type ${action.type}`);
+    }
+
+    // 使用 Playwright 的 evaluate API 执行自定义代码
+    const result = await this.pw.evaluateViaPlaywright({
+      cdpUrl: action.cdpUrl,
+      targetId: action.targetId,
+      code: action.evaluate.code,
+      args: action.evaluate.args
+    });
+
+    return result;
+  }
+}
+
+interface ExecutionResult {
+  success: boolean;
+  error?: string;
+  duration: number;
+}
+```
+
+### 6.6 完整示例
+
+```typescript
+// 登录场景的缓存操作（Playwright 对齐版本）
+const loginActions: AtomicAction[] = [
+  {
+    type: "navigate",
+    url: "https://example.com/login",
+    order: 1,
+    description: "导航到登录页面"
+  },
+  {
+    type: "type",
+    ref: "#username",
+    variable: "username",  // 使用变量
+    order: 2,
+    description: "输入用户名"
+  },
+  {
+    type: "type",
+    ref: "#password",
+    variable: "password",  // 使用变量
+    order: 3,
+    description: "输入密码"
+  },
+  {
+    type: "press",
+    key: "Enter",  // 或者点击登录按钮
+    order: 4,
+    description: "提交登录表单"
+  },
+  {
+    type: "wait",
+    evaluate: {
+      code: "new Promise(r => setTimeout(r, 1000))"
+    },
+    order: 5,
+    description: "等待登录完成"
+  }
+];
+
+// 执行时的实际操作（变量替换后）
+const actualActions = applyVariables(loginActions, {
+  username: "alice",
+  password: "secret123"
+});
+// 结果：
+// [
+//   { type: "navigate", url: "https://example.com/login", order: 1 },
+//   { type: "type", ref: "#username", text: "alice", order: 2 },
+//   { type: "type", ref: "#password", text: "secret123", order: 3 },
+//   { type: "press", key: "Enter", order: 4 },
+//   { type: "wait", evaluate: { code: "..." }, order: 5 }
+// ]
+```
+
+---
+
+## 七、Hooks 集成要点
+
+### 6.1 before_tool_call hook
+
+```typescript
+api.registerHook({
+  name: "before_tool_call",
+  priority: 100,
+  description: "场景识别和缓存拦截器",
+
+  async handler(event, ctx) {
+    if (event.tool.name !== "browser") return;
+
+    const params = event.params;
+    const url = params.url as string;
+    const action = params.action as string;
+
+    // 只缓存特定操作
+    if (!config.cacheActions.includes(action)) return;
+
+    // 场景识别
+    const userInput = extractUserInput(ctx);
+    const currentUrl = url || ctx.currentUrl;
+    const match = await scenarioRecognizer.recognize(userInput, currentUrl);
+
+    if (!match) {
+      // 无匹配，返回 cacheInfo（不拦截）
+      return {
+        block: false,
+        result: {
+          cacheInfo: {
+            exists: false,
+            confidence: 0
+          }
+        }
+      };
+    }
+
+    // 高置信度匹配，返回 cacheInfo（不拦截，让 LLM 决定）
+    if (match.confidence >= 80) {
+      return {
+        block: false,
+        result: {
+          cacheInfo: {
+            exists: match.cacheLevel ? true : false,
+            scenario: match.scenario,
+            confidence: match.confidence,
+            method: match.method,
+            matchedPattern: match.matchedPattern
+          }
+        }
+      };
+    }
+
+    // 检查缓存
+    const viewport = extractViewport(ctx, params);
+    const entry = await cacheStore.get(url, viewport);
+
+    if (entry && entry.cacheLevel === "L3") {
+      // L3 缓存命中，返回 cacheInfo
+      return {
+        block: false,
+        result: {
+          cacheInfo: {
+            exists: true,
+            cacheLevel: "L3",
+            scenario: entry.scenario,
+            actions: entry.actions,
+            variables: entry.variables
+          }
+        }
+      };
+    }
+
+    return { block: false };
+  }
+});
+```
+
+### 6.2 after_tool_call hook
+
+```typescript
+api.registerHook({
+  name: "after_tool_call",
+  priority: 100,
+  description: "保存 LLM 分析结果到缓存",
+
+  async handler(event, ctx) {
+    if (event.tool.name !== "browser") return;
+
+    const params = event.params;
+    const url = params.url as string;
+    const action = params.action as string;
+
+    // 只缓存特定操作
+    if (!config.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);
+
+    // 决定缓存层级
+    const cacheLevel = scenarioMatch.confidence >= 85 ? "L3" :
+                     scenarioMatch.confidence >= 70 ? "L2" : "L1";
+
+    // 解析变量
+    const variables = await variableResolver.resolveVariables(userInput, scenarioMatch.scenario);
+
+    // 保存到缓存
+    await cacheStore.set(url, viewport, result.actions, {
+      scenario: scenarioMatch.scenario,
+      cacheLevel,
+      variables,
+      actions: result.actions as AtomicAction[]
+    });
+  }
+});
+```
+
+### 6.3 before_prompt_build hook
+
+```typescript
+api.registerHook({
+  name: "before_prompt_build",
+  priority: 50,
+
+  async handler(event, ctx) {
+    if (!config.enabled || config.autoUseCache === false) return;
+
+    const stats = cacheStore.getStats();
+
+    // 只在命中率较高时注入
+    if (stats.hitRate < 30) return;
+
+    // 构建缓存使用指南
+    const guide = `
+【页面操作缓存系统】
+
+当前缓存统计：
+- 总条目数：${stats.totalEntries}
+- 总命中：${stats.totalHits}
+  命中率：${stats.hitRate}%
+
+已缓存的场景：
+${cacheStore.getTopScenarios(5)}
+
+使用方式：
+1. 如果工具返回 cacheInfo 信息，优先使用缓存
+2. 执行缓存操作可以大幅降低 token 消耗和操作延迟
+3. 如果页面结构变化，缓存会自动失效
+
+支持的场景：login, logout, search, checkout, settings, form_fill
+
+缓存层级：
+- L3: 场景级缓存（包含变量模板）- 高置信度时直接使用
+- L2: 流程级缓存 - 中置信度时使用
+- L1: 原子级缓存 - 低置信度或无场景时使用
+`;
+
+    return { prependContext: guide };
+  }
+});
+```
+
+---
+
+## 八、配置选项
+
+```typescript
+interface CacheConfig {
+  // === 全局开关 ===
+  enabled: boolean;
+  autoUseCache: boolean;
+
+  // === 场景识别 ===
+  scenarioRecognitionEnabled: boolean;
+  llmClassificationThreshold: number;  // LLM 分类阈值
+
+  // === 缓存策略 ===
+  cacheLevelStrategy: "auto" | "l3-only" | "l2-only" | "l1-only";
+  defaultCacheLevel: string;  // 默认使用的层级
+
+  // === 缓存失效 ===
+  pageChangeDetectionEnabled: boolean;
+  changeInvalidationThreshold: number;  // 变化失效阈值
+  invalidationStrategy: "soft" | "hard";
+  maxVersionsPerEntry: number;  // 每个缓存保留的最大版本数
+
+  // === 变量系统 ===
+  variableExtractionEnabled: boolean;
+  allowUserConfirmVariables: boolean;
+
+  // === 安全 ===
+  encryptSensitiveCache: boolean;
+  accessControlEnabled: boolean;
+  allowedUserIds: string[];
+  logSanitizationEnabled: boolean;
+
+  // === 用户体验 ===
+  showCacheStatusToUser: boolean;
+  enableUserCacheConfirmation: boolean;
+  enableUserForcedRefresh: boolean;
+  enableUserCacheErrorReport: boolean;
+
+  // === 统计 ===
+  trackExecutionStats: boolean;
+  statsUpdateInterval: number;  // 统计更新间隔（秒）
+}
+```
+
+---
+
+## 九、完整流程图
+
+```mermaid
+graph TD
+    A[用户输入] --> B{场景识别器}
+
+    B -->|精确规则匹配| C{匹配置信度≥90}
+    B -->|LLM 分类| D{匹配置信度≥70}
+    B -->|历史学习| E{匹配置信度≥60}
+    B --> F{无匹配}
+
+    C -->|置信度≥80| G[返回缓存信息]
+    C -->|置信度<80| H[不返回缓存]
+
+    G --> I{LLM 决定}
+
+    I -->| J[调用 execute_cached?}
+
+    J -->|否| K[调用 browser 工具]
+
+    J -->|是| L{验证缓存并检测变化}
+
+    L --> M[执行缓存操作]
+
+    M --> N[记录执行统计]
+
+    N --> O{页面变化?}
+
+    O -->|是| P[失效缓存]
+    O -->|否| Q[保持缓存]
+```
+
+---
+
+## 十、关键问题检查
+
+### ✅ 已解决的问题
+
+| 问题 | 解决方案 | 优先级 |
+|------|---------|--------|
+| **变量传递** | 多个解析器支持不同场景 | P0 |
+| **场景识别** | 多层匹配（规则+LLM+历史） | P0 |
+| **缓存失效** | DOM hash + 渐进式失效 | P1 |
+| **并发控制** | 文件锁 + 版本控制 | P1 |
+| **安全性** | 敏感变量检测 + 加密存储 | P0 |
+| **用户体验** | 状态展示 + 确认机制 | P1 |
+| **Playwright 对齐** | 参数名与 Playwright API 完全一致（ref, targetId, cdpUrl 等） | P0 |
+
+---
+
+## 十一、实现优先级
+
+### 阶段 1：核心功能（P0）
+
+1. 原子操作缓存（L1 级）
+2. 基本场景识别
+3. 变量解析器
+4. 安全策略
+5. Hooks 集成
+
+### 阶段 2：场景级缓存（P1）
+
+1. 精确规则匹配
+2. 场景模板
+3. 变量模板
+4. 场景学习
+
+### 阶段 3：智能失效（P1）
+
+1. DOM hash 计算
+2. 页面变化检测
+3. 渐进式失效
+
+### 阶段 4：用户体验增强（P2）
+
+1. 缓存状态展示
+2. 用户确认机制
+3. 强制刷新
+
+---
+
+**文档版本**: 5.0.0
+**最后更新**: 2026-03-14
+**更新内容**: 完成代码实现、测试和 Playwright 完全对齐