page-action-cache

v2.0.9

Published

2 hours ago

Page Action Cache - OpenClaw extension using Browser Client API

0High
0Medium
0Low

zhoujinyu

Page Action Cache - OpenClaw Extension

页面操作缓存扩展 - OpenClaw 浏览器操作缓存系统

功能特性

1. 场景识别 (Scenario Recognition)

自动识别用户操作场景：登录、搜索、支付、结账、通用
基于URL模式和页面内容关键词
支持自定义规则和关键词扩展

2. 变量提取 (Variable Extraction)

从用户输入中提取动态变量：邮箱、电话、日期、金额等
智能置信度计算
生成变量替换模板

3. 多级缓存 (Multi-Level Cache)

L3 缓存: 持久化缓存，适合稳定的重复操作（如登录）
L2 缓存: 内存缓存，适合频繁访问的操作（如搜索）
L1 缓存: 热点缓存，适合当前会话的操作
自动缓存提升和容量管理
LLM分类支持

4. 缓存失效 (Cache Invalidation)

页面变化检测（HTML、结构、内容哈希）
软/硬失效策略
变化历史追踪
自动清理过期缓存

5. 浏览器动作执行 (Browser Action Execution)

通过 Browser Client API 执行浏览器操作
支持操作：导航、点击、输入、截图、脚本执行
失败跳过机制
执行时间节省计算

技术架构

目录结构

page-action-cache/
├── src/
│   ├── index.ts                    # 主扩展入口
│   ├── types.ts                    # TypeScript 类型定义
│   ├── cache-manager.ts            # 缓存管理器
│   ├── scenario-recognizer.ts      # 场景识别器
│   ├── variable-extractor.ts       # 变量提取器
│   ├── multi-level-cache.ts         # 多级缓存管理器
│   ├── cache-invalidation.ts        # 缓存失效管理器
│   ├── browser-action-executor.ts   # 浏览器动作执行器
│   └── types-mock.d.ts            # 模拟类型定义
├── tests/
│   ├── basic.test.ts               # 基础功能测试
│   ├── scenario-recognizer.test.ts # 场景识别测试
│   ├── variable-extractor.test.ts    # 变量提取测试
│   ├── multi-level-cache.test.ts    # 多级缓存测试
│   ├── cache-invalidation.test.ts   # 缓存失效测试
│   └── integration.test.ts         # 集成测试
├── dist/                          # 编译输出目录
├── package.json                   # 项目配置
├── tsconfig.json                 # TypeScript 配置
├── openclaw.plugin.json          # OpenClaw 插件元数据
└── README.md                     # 项目文档

OpenClaw 集成说明

安装方式

方式一：本地开发目录（推荐用于开发调试）

# 1. 确保 page-action-cache 已构建
cd /Users/zhoujinyu/Documents/projects/page-action-cache
npm install && npm run build

# 2. 在 OpenClaw 配置文件中添加本地扩展引用
# 编辑 ~/.openclaw/openclaw.json 或实例配置文件
{
  "plugins": {
    "entries": {
      "page-action-cache": {
        "path": "/Users/zhoujinyu/Documents/projects/page-action-cache",
        "enabled": true,
        "config": {
          "autoUseCache": true,
          "scenarioRecognitionEnabled": true,
          "cacheLevelStrategy": "auto"
        }
      }
    }
  }
}

方式二：通过 npm 全局安装

# 从 Gitee 仓库安装
npm install -g https://gitee.com/jinyu_zjy/page-action-cache.git

# 或者在已安装的 OpenClaw 中自动发现
npm install page-action-cache --save

OpenClaw 配置示例

基础配置

{
  "plugins": {
    "entries": {
      "page-action-cache": {
        "enabled": true,
        "config": {
          "enabled": true,
          "autoUseCache": true,
          "scenarioRecognitionEnabled": true,
          "llmClassificationThreshold": 0.8,
          "cacheLevelStrategy": "auto",
          "defaultCacheLevel": "L1",
          "pageChangeDetectionEnabled": true,
          "changeInvalidationThreshold": 0.5,
          "invalidationStrategy": "soft",
          "variableExtractionEnabled": true,
          "allowUserConfirmVariables": true,
          "allowUserForcedRefresh": true,
          "enableUserCacheErrorReport": true,
          "trackExecutionStats": true,
          "statsUpdateInterval": 60000
        }
      }
    }
  }
}

使用示例

通过 OpenClaw CLI 使用

# 执行缓存的页面操作
openclaw message send --channel web --content "请帮我登录 https://example.com/login"

# OpenClaw 会自动调用 browser_cache_execute 工具
# 该工具会：
# 1. 识别场景为 'login'
# 2. 从缓存中查找匹配的登录流程
# 3. 如果找到缓存，直接执行缓存的操作
# 4. 如果未找到，执行新的操作并保存到缓存

# 查看缓存统计
openclaw message send --channel web --content "查看缓存统计"

# 清空缓存
openclaw message send --channel web --content "清空登录页面缓存"

通过 Web UI 使用

在 OpenClaw Web UI 中发送消息
AI 会自动调用 page-action-cache 扩展的工具
工具会执行浏览器操作并返回结果
用户可以看到缓存命中情况和节省的时间

工具详细说明

1. browser_cache_execute

执行缓存的页面操作序列

参数:

url (必需): 目标页面 URL
viewport (可选): 视口大小，如 "1920x1080"
scenario (可选): 操作场景（login/search/payment/checkout/general）
actions (可选): 页面操作序列数组
- type: 操作类型（navigate/click/screenshot/type/script）
- params: 操作参数对象
useCache (可选): 是否使用缓存，默认 true
forceRefresh (可选): 是否强制刷新缓存，默认 false
llmClassificationScore (可选): LLM 分类置信度分数 (0-1)

返回示例:

## Cached Execution

Execution completed successfully

- Executed Actions: 4
- Skipped Actions: 0
- Failed Actions: 0
- Saved Time: 1800ms

Cache ID: 1234567890
URL: https://example.com/login
Scenario: login
Cache Level: L3
Access Count: 5

2. browser_cache_stats

查看页面操作缓存的统计信息

参数: 无

返回示例:

## Page Action Cache Statistics

### Overall Performance
- Total Cache Entries: 15
- Total Cache Hits: 42
- Cache Hit Rate: 85.50%

### Multi-Level Cache Distribution
#### L3 Cache
- Size: 8/1000 (0.8% full)
- Average Access Count: 5.2

#### L2 Cache
- Size: 5/200 (2.5% full)
- Average Access Count: 8.4

#### L1 Cache
- Size: 2/50 (4.0% full)
- Average Access Count: 12.0

### Cache Invalidation
- Total Snapshots: 45
- Active Snapshots: 38
- Invalidation Rate: 15.55%

3. browser_cache_clear

清空页面操作缓存

参数:

level (可选): 缓存级别（all/L3/L2/L1），默认 all
url (可选): 特定 URL
viewport (可选): 特定视口

使用示例:

# 清空所有缓存
openclaw message send --channel web --content "清空所有缓存"

# 清空特定级别
openclaw message send --channel web --content "清空L1缓存"

# 清空特定URL的缓存
openclaw message send --channel web --content "清空登录页面缓存"

多实例集成

当使用 OpenClaw 多实例架构时，可以为不同实例配置不同的缓存策略：

实例配置示例

{
  "plugins": {
    "entries": {
      "page-action-cache": {
        "path": "/Users/zhoujinyu/Documents/projects/page-action-cache",
        "enabled": true,
        "config": {
          // 生产实例配置
          "cacheLevelStrategy": "l3-only",
          "pageChangeDetectionEnabled": true,
          "invalidationStrategy": "hard"
        }
      }
    }
  }
}

不同实例可以共享同一个扩展代码，但使用不同的配置参数：

开发实例: 使用 L1 缓存，软失效策略
测试实例: 使用 auto 策略，快速迭代
生产实例: 使用 L3 缓存，硬失效策略，确保稳定性

与 Browser Client API 集成

扩展通过 HTTP API 与 OpenClaw Browser Client 通信：

环境变量:

export OPENCLAW_BROWSER_CLIENT_URL="http://localhost:3000"

API 端点:

POST /api/browser/navigate - 导航到指定 URL
POST /api/browser/click - 点击指定元素
POST /api/browser/type - 输入文本到指定元素
POST /api/browser/screenshot - 截取页面截图
POST /api/browser/execute-script - 执行 JavaScript 脚本

自动发现机制: 扩展会自动尝试连接到以下位置的 Browser Client：

环境变量 OPENCLAW_BROWSER_CLIENT_URL 指定的地址
默认地址 http://localhost:3000
如果都不可用，扩展仍然可以工作，但浏览器操作会被跳过

安装和使用

安装

# 开发目录安装
cd /Users/zhoujinyu/Documents/projects/page-action-cache
npm install

# 构建项目
npm run build

使用

该扩展提供三个工具：

browser_cache_execute: 执行缓存的页面操作序列
browser_cache_stats: 查看缓存统计信息
browser_cache_clear: 清空页面操作缓存

配置选项

{
  "enabled": true,
  "autoUseCache": true,
  "scenarioRecognitionEnabled": true,
  "llmClassificationThreshold": 0.8,
  "cacheLevelStrategy": "auto",
  "defaultCacheLevel": "L1",
  "pageChangeDetectionEnabled": true,
  "changeInvalidationThreshold": 0.5,
  "invalidationStrategy": "soft",
  "variableExtractionEnabled": true,
  "allowUserConfirmVariables": true,
  "allowUserForcedRefresh": true,
  "enableUserCacheErrorReport": true,
  "trackExecutionStats": true,
  "statsUpdateInterval": 60000
}

测试

运行所有测试

npm test

运行特定测试

# 场景识别测试
npm test -- tests/scenario-recognizer.test.ts

# 基础功能测试
npm test -- tests/basic.test.ts

性能优化

缓存策略

命中率优化: 多级缓存自动调整存储位置
容量管理: LRU驱逐策略确保缓存有效性
过期清理: 定期清理过期和低质量缓存

执行优化

失败跳过: 自动跳过高失败率的操作
时间节省: 实时计算缓存带来的性能提升
智能调度: 根据场景和置信度选择最佳缓存级别

开发状态

✅ 已完成的功能:

场景识别系统
变量提取系统
多级缓存系统
缓存失效系统
浏览器动作执行系统
完整的测试覆盖
TypeScript 类型定义
OpenClaw 插件接口实现

⚠️ 已知限制:

依赖 OpenClaw Browser Client API（需要实际的浏览器客户端）
某些高级测试需要实际的浏览器环境
LLM 分类需要外部服务集成

技术栈

语言: TypeScript (ES2022)
模块系统: ESM
测试框架: Vitest
目标环境: Node.js 22+
构建工具: TypeScript Compiler

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request！