page-action-cache 1.0.1

package/openclaw.plugin.json

@@ -0,0 +1,208 @@
+{
+  "id": "page-action-cache",
+  "name": "Page Action Cache",
+  "version": "1.0.0",
+  "description": "Caches LLM browser operations to avoid re-analyzing the same DOM. Reduces token consumption and operation latency through scenario recognition (login, search, payment, etc.) and multi-level caching (L3/L2/L1).",
+  "author": "OpenClaw",
+  "license": "MIT",
+  "kind": "extension",
+  "main": "./src/hooks-entry.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./hooks-entry": "./src/hooks-entry.js"
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": {
+        "type": "boolean",
+        "default": true,
+        "description": "Enable or disable the page action cache extension"
+      },
+      "autoUseCache": {
+        "type": "boolean",
+        "default": true,
+        "description": "Automatically use cached actions when available"
+      },
+      "scenarioRecognitionEnabled": {
+        "type": "boolean",
+        "default": true,
+        "description": "Enable automatic scenario recognition (login, search, checkout, etc.)"
+      },
+      "llmClassificationThreshold": {
+        "type": "number",
+        "default": 70,
+        "minimum": 0,
+        "maximum": 100,
+        "description": "Confidence threshold for LLM-based scenario classification (0-100)"
+      },
+      "cacheLevelStrategy": {
+        "type": "string",
+        "enum": ["auto", "l3-only", "l2-only", "l1-only"],
+        "default": "auto",
+        "description": "Cache level strategy: auto (default), l3-only (scenario-level only), l2-only (flow-level only), l1-only (atomic-level only)"
+      },
+      "defaultCacheLevel": {
+        "type": "string",
+        "enum": ["L3", "L2", "L1"],
+        "default": "L3",
+        "description": "Default cache level when no scenario is recognized"
+      },
+      "pageChangeDetectionEnabled": {
+        "type": "boolean",
+        "default": true,
+        "description": "Enable automatic page change detection to invalidate stale caches"
+      },
+      "changeInvalidationThreshold": {
+        "type": "number",
+        "default": 80,
+        "minimum": 0,
+        "maximum": 100,
+        "description": "Page change confidence threshold for cache invalidation (0-100)"
+      },
+      "invalidationStrategy": {
+        "type": "string",
+        "enum": ["soft", "hard"],
+        "default": "soft",
+        "description": "Cache invalidation strategy: soft (mark stale, allow override) or hard (immediately delete)"
+      },
+      "variableExtractionEnabled": {
+        "type": "boolean",
+        "default": true,
+        "description": "Enable automatic variable extraction from user input (username, password, etc.)"
+      },
+      "allowUserConfirmVariables": {
+        "type": "boolean",
+        "default": false,
+        "description": "Allow user confirmation for extracted variables before execution"
+      },
+      "encryptSensitiveCache": {
+        "type": "boolean",
+        "default": false,
+        "description": "Encrypt sensitive cache entries (passwords, tokens) using AES-256-GCM"
+      },
+      "accessControlEnabled": {
+        "type": "boolean",
+        "default": false,
+        "description": "Enable access control for sensitive cache operations"
+      },
+      "logSanitizationEnabled": {
+        "type": "boolean",
+        "default": true,
+        "description": "Automatically redact sensitive data from logs"
+      },
+      "showCacheStatusToUser": {
+        "type": "boolean",
+        "default": true,
+        "description": "Display cache hit/miss status to users"
+      },
+      "enableUserCacheConfirmation": {
+        "type": "boolean",
+        "default": false,
+        "description": "Require user confirmation before using cached actions"
+      },
+      "enableUserForcedRefresh": {
+        "type": "boolean",
+        "default": true,
+        "description": "Allow users to force refresh specific cache entries"
+      },
+      "enableUserCacheErrorReport": {
+        "type": "boolean",
+        "default": true,
+        "description": "Enable user reporting of cache execution errors"
+      },
+      "trackExecutionStats": {
+        "type": "boolean",
+        "default": true,
+        "description": "Track execution statistics (hit rate, saved tokens, saved time)"
+      },
+      "statsUpdateInterval": {
+        "type": "number",
+        "default": 60,
+        "minimum": 10,
+        "description": "Statistics update interval in seconds (minimum 10)"
+      }
+    }
+  },
+  "uiHints": {
+    "enabled": {
+      "label": "Enable Cache Extension",
+      "description": "Enable or disable the page action cache extension"
+    },
+    "autoUseCache": {
+      "label": "Auto Use Cache",
+      "description": "Automatically use cached actions when available"
+    },
+    "scenarioRecognitionEnabled": {
+      "label": "Scenario Recognition",
+      "description": "Enable automatic scenario recognition (login, search, checkout, etc.)"
+    },
+    "cacheLevelStrategy": {
+      "label": "Cache Strategy",
+      "description": "Cache level strategy (auto, l3-only, l2-only, l1-only)"
+    },
+    "encryptSensitiveCache": {
+      "label": "Encrypt Sensitive Data",
+      "description": "Encrypt sensitive cache entries (passwords, tokens)",
+      "sensitive": false
+    },
+    "showCacheStatusToUser": {
+      "label": "Show Cache Status",
+      "description": "Display cache hit/miss status to users"
+    }
+  },
+  "tools": [
+    {
+      "name": "execute_cached",
+      "label": "Execute Cached Actions",
+      "description": "Execute cached page action sequences, skipping LLM analysis. Significantly reduces token consumption and operation latency."
+    },
+    {
+      "name": "cache_stats",
+      "label": "Cache Statistics",
+      "description": "View cache statistics including hit rate, saved tokens, and saved time."
+    },
+    {
+      "name": "cache_list",
+      "label": "List Cache Entries",
+      "description": "List all cached page action entries with their metadata."
+    },
+    {
+      "name": "cache_clear",
+      "label": "Clear Cache",
+      "description": "Clear all cached page action entries."
+    },
+    {
+      "name": "scenario_list",
+      "label": "List Scenarios",
+      "description": "List all recognized scenarios with their match patterns."
+    },
+    {
+      "name": "force_refresh",
+      "label": "Force Refresh Cache",
+      "description": "Force refresh a specific cache entry by URL and viewport."
+    }
+  ],
+  "hooks": [
+    {
+      "name": "before_tool_call",
+      "description": "Scenario recognition and cache interception"
+    },
+    {
+      "name": "after_tool_call",
+      "description": "Save LLM analysis results to cache"
+    },
+    {
+      "name": "before_prompt_build",
+      "description": "Inject cache usage guide into prompts"
+    }
+  ],
+  "runtime": {
+    "node": ">=18.0.0"
+  },
+  "openclaw": {
+    "minVersion": "2026.2.0",
+    "extensions": ["./src/hooks-entry.js"]
+  }
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "page-action-cache",
+  "version": "1.0.1",
+  "description": "Page action caching extension for OpenClaw - caches LLM browser operations to avoid re-analyzing the same DOM",
+  "keywords": [
+    "automation",
+    "browser",
+    "cache",
+    "extension",
+    "openclaw"
+  ],
+  "license": "MIT",
+  "author": "OpenClaw",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openclaw/openclaw.git",
+    "directory": "extensions/page-action-cache"
+  },
+  "files": [
+    "index.ts",
+    "dist/",
+    "src/",
+    "skills/",
+    "docs/",
+    "package.json",
+    "openclaw.plugin.json"
+  ],
+  "type": "module",
+  "main": "src/hooks-entry.js",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./hooks-entry": {
+      "types": "./src/hooks-entry.d.ts",
+      "default": "./src/hooks-entry.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "publish:npm": "./scripts/npm_publish.sh",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.2.0"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "config": {
+    "test": {
+      "include": [
+        "tests/**/*.test.ts"
+      ],
+      "exclude": [
+        "node_modules",
+        "dist",
+        "**/node_modules/**"
+      ]
+    }
+  },
+  "openclaw": {
+    "extensions": [
+      "./src/hooks-entry.js"
+    ]
+  }
+}

package/skills/page-action-cache/SKILL.md

@@ -0,0 +1,216 @@
+# 页面操作缓存扩展 - 使用指南
+
+**版本**: 1.0.0
+**更新日期**: 2026-03-13
+
+## 概述
+
+## 概述
+
+本技能提供了页面操作缓存功能，可以缓存 LLM 分析浏览器页面后生成的操作序列。当再次访问相同页面时，直接使用缓存的操作，无需重新分析 DOM，大幅降低 token 消耗和操作延迟。
+
+## 核心优势
+
+- **节省 Token**: 避免每次操作都发送 DOM 给 LLM 分析
+- **加速执行**: 跳过 LLM 分析，直接执行缓存的操作
+- **智能匹配**: 多层场景识别（规则+LLM+历史）
+- **安全可靠**: 自动检测页面变化，缓存失效
+
+## 可用工具
+
+### 1. execute_cached - 执行缓存操作
+
+**用途**: 执行缓存的页面操作序列
+
+**参数**:
+- `cacheKey` (必需): 缓存键（从 cache_info 中获取）
+- `fromIndex` (可选): 从第几个操作开始执行（默认 0）
+- `toIndex` (可选): 执行到第几个操作（不指定则执行全部）
+- `dryRun` (可选): 试运行模式，不实际执行
+- `force` (可选): 强制执行（忽略页面变化检测）
+
+**示例**:
+```
+使用缓存登录 example.com，cacheKey: abc123
+```
+
+### 2. cache_stats - 查看缓存统计
+
+**用途**: 查看缓存命中统计、节省的 token 等
+
+**参数**: 无
+
+**示例**:
+```
+查看缓存统计信息
+```
+
+### 3. cache_list - 列出所有缓存
+
+**用途**: 列出所有缓存条目及其详情
+
+**参数**:
+- `limit` (可选): 最多返回的条目数（默认 20）
+- `filterScenario` (可选): 按场景过滤（如 login, checkout）
+
+**示例**:
+```
+列出所有登录相关的缓存
+```
+
+### 4. cache_clear - 清空缓存
+
+**用途**: 清空缓存条目
+
+**参数**:
+- `scenario` (可选): 只清空指定场景的缓存
+
+**示例**:
+```
+清空所有缓存
+清空登录场景的缓存
+```
+
+### 5. scenario_list - 列出所有场景
+
+**用途**: 列出所有支持的缓存场景及其匹配规则
+
+**参数**: 无
+
+**示例**:
+```
+列出所有支持的缓存场景
+```
+
+### 6. force_refresh - 强制刷新缓存
+
+**用途**: 强制刷新指定页面的缓存
+
+**参数**:
+- `url` (必需): 页面 URL
+- `viewport` (可选): 视口尺寸
+
+**示例**:
+```
+强制刷新 example.com/login 的缓存
+```
+
+## 使用流程
+
+### 场景 1: 首次访问页面
+
+```
+用户: "登录 example.com"
+↓
+LLM: 分析页面 DOM，生成操作序列
+↓
+系统: 自动保存到缓存（L3 级）
+```
+
+### 场景 2: 再次访问相同页面
+
+```
+用户: "登录 example.com"
+↓
+系统: 检测到缓存匹配（置信度 95%）
+↓
+LLM: 收到 cacheInfo，决定使用缓存
+↓
+系统: 使用 execute_cached 工具执行缓存操作
+↓
+结果: 节省 5000 tokens，加速 2 秒
+```
+
+### 场景 3: 页面发生变化
+
+```
+用户: "登录 example.com"
+↓
+系统: 检测页面结构变化
+↓
+系统: 自动失效缓存
+↓
+LLM: 重新分析页面，生成新操作
+↓
+系统: 保存新的缓存
+```
+
+## 支持的场景
+
+| 场景 | 关键词 | 缓存层级 |
+|------|---------|---------|
+| login | 登录、登陆、注册、sign in | L3 |
+| logout | 退出、登出、注销、logout | L3 |
+| search | 搜索、查找、search | L3 |
+| checkout | 结账、结算、支付、checkout | L3 |
+| settings | 设置、配置、修改 | L3 |
+| form_fill | 填写、填表单、提交 | L2 |
+| navigate | 打开、进入、跳转 | L2 |
+| screenshot | 截图、screenshot | L1 |
+
+## 缓存层级
+
+- **L3: 场景级** - 包含变量模板（如 username, password），高置信度时使用
+- **L2: 流程级** - 固定操作序列，中等置信度时使用
+- **L1: 原子级** - 单个操作，低置信度时使用
+
+## 注意事项
+
+1. **页面变化检测**: 系统会自动检测页面结构变化，如果检测到变化会自动失效缓存
+2. **变量替换**: 支持变量模板（如 ${username}），执行时自动从用户输入提取
+3. **敏感数据**: 密码等敏感数据会自动脱敏存储
+4. **试运行**: 使用 dryRun 参数可以预览操作而不执行
+5. **强制执行**: 使用 force 参数可以跳过页面变化检测（谨慎使用）
+
+## 最佳实践
+
+1. **优先使用缓存**: 当工具返回 cacheInfo 时，优先使用 execute_cached 工具
+2. **检查命中统计**: 定期查看 cache_stats，了解缓存效果
+3. **及时清理**: 使用 cache_clear 清理不再需要的缓存
+4. **测试新功能**: 使用 dryRun 模式测试缓存操作
+5. **处理变化**: 当页面变化导致操作失败时，使用 force_refresh 刷新缓存
+
+## 故障排查
+
+### 问题 1: 缓存未命中
+
+**原因**:
+- 首次访问该页面
+- 缓存已过期
+- 页面结构发生变化
+
+**解决**:
+- 使用 scenario_list 查看支持的场景
+- 使用 cache_list 查看现有缓存
+- 使用 force_refresh 强制刷新
+
+### 问题 2: 缓存执行失败
+
+**原因**:
+- 页面结构发生变化
+- 元素选择器失效
+- 操作顺序错误
+
+**解决**:
+- 查看执行结果中的错误信息
+- 使用 force_refresh 刷新缓存
+- 调整操作序列
+
+### 问题 3: 变量未替换
+
+**原因**:
+- 用户输入中不包含变量值
+- 变量名不匹配
+
+**解决**:
+- 确保用户输入包含变量值（如 "用户名 alice"）
+- 使用变量提取测试验证
+
+## 统计信息含义
+
+- **总条目数**: 当前缓存的页面操作条目数量
+- **总命中**: 缓存命中的总次数
+- **命中率**: 缓存命中占总请求的百分比
+- **L3/L2/L1 命中**: 各层级缓存命中的次数
+- **节省 Token**: 估算节省的 token 数量
+- **节省时间**: 估算节省的时间（毫秒）