page-action-cache 2.0.9 → 2026.2.1

package/README.md

@@ -1,37 +1,18 @@
 # Page Action Cache - OpenClaw Extension
 
-页面操作缓存扩展 - OpenClaw 浏览器操作缓存系统
+页面操作缓存扩展 - 为 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 执行浏览器操作
-- 支持操作：导航、点击、输入、截图、脚本执行
-- 失败跳过机制
-- 执行时间节省计算
+### 1. 页面快照缓存
+- 存储页面快照和角色引用
+- 支持快速查询和失效
+- 自动清理过期缓存（5分钟 TTL）
+- LRU 容量管理（最多 50 个条目）
+
+### 2. 配置选项
+- **enabled**: 启用/禁用插件
+- **autoUseCache**: 自动使用缓存
 
 ## 技术架构
 
@@ -39,348 +20,144 @@
 ```
 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                     # 项目文档
+│   ├── index.ts           # 主扩展入口
+│   └── types.ts          # TypeScript 类型定义
+├── tests/                # 测试文件
+├── dist/                 # 编译输出目录
+├── package.json          # 项目配置
+├── tsconfig.json         # TypeScript 配置
+├── openclaw.plugin.json # OpenClaw 插件元数据
+└── README.md            # 项目文档
 ```
 
-## OpenClaw 集成说明
+## 安装和使用
 
-### 安装方式
+### 开发环境安装
 
-#### 方式一：本地开发目录（推荐用于开发调试）
 ```bash
-# 1. 确保 page-action-cache 已构建
+# 1. 确保已构建
 cd /Users/zhoujinyu/Documents/projects/page-action-cache
-npm install && npm run build
+npm run build
 
-# 2. 在 OpenClaw 配置文件中添加本地扩展引用
+# 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"
-        }
+        "autoUseCache": true
       }
     }
   }
 }
 ```
 
-#### 方式二：通过 npm 全局安装
+### 全局安装
+
 ```bash
 # 从 Gitee 仓库安装
 npm install -g https://gitee.com/jinyu_zjy/page-action-cache.git
-
-# 或者在已安装的 OpenClaw 中自动发现
-npm install page-action-cache --save
-```
-
-### OpenClaw 配置示例
-
-#### 基础配置
-```json
-{
-  "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 使用
-```bash
-# 执行缓存的页面操作
-openclaw message send --channel web --content "请帮我登录 https://example.com/login"
+## 工具说明
 
-# OpenClaw 会自动调用 browser_cache_execute 工具
-# 该工具会：
-# 1. 识别场景为 'login'
-# 2. 从缓存中查找匹配的登录流程
-# 3. 如果找到缓存，直接执行缓存的操作
-# 4. 如果未找到，执行新的操作并保存到缓存
+### 1. page_snapshot_cache
+缓存和检索页面快照以加速重复操作
 
-# 查看缓存统计
-openclaw message send --channel web --content "查看缓存统计"
+**参数**:
+- `url` (必需): 页面 URL
+- `snapshot` (可选): 要存储的页面快照
+- `refs` (可选): 角色引用映射
+- `invalidate` (可选): 失效该 URL 的缓存，默认 false
 
-# 清空缓存
-openclaw message send --channel web --content "清空登录页面缓存"
+**返回示例**:
+```
+Cache stored for https://example.com
 ```
 
-#### 通过 Web UI 使用
-1. 在 OpenClaw Web UI 中发送消息
-2. AI 会自动调用 page-action-cache 扩展的工具
-3. 工具会执行浏览器操作并返回结果
-4. 用户可以看到缓存命中情况和节省的时间
-
-### 工具详细说明
-
-#### 1. browser_cache_execute
-执行缓存的页面操作序列
+### 2. page_cache_stats
+查看页面快照缓存统计信息
 
-**参数**:
-- `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
+## Page Snapshot Cache Statistics
 
-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
+- Total Entries: 15
+- Total Hits: 42
+- Hit Rate: 85.50%
+- Avg Hit Count: 2.8
+- Cleaned Entries: 3
+- Oldest Entry: 2026-03-16T10:30:00.000Z
+- Newest Entry: 2026-03-16T11:00:00.000Z
 ```
 
-#### 2. browser_cache_stats
-查看页面操作缓存的统计信息
+### 3. page_cache_clear
+清空页面快照缓存
 
 **参数**: 无
 
 **返回示例**:
 ```
-## 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%
+Cleared 15 cache entries
 ```
 
-#### 3. browser_cache_clear
-清空页面操作缓存
+## 使用示例
 
-**参数**:
-- `level` (可选): 缓存级别（all/L3/L2/L1），默认 all
-- `url` (可选): 特定 URL
-- `viewport` (可选): 特定视口
+### 通过 OpenClaw CLI 使用
 
-**使用示例**:
-```
-# 清空所有缓存
-openclaw message send --channel web --content "清空所有缓存"
+```bash
+# 存储页面快照
+openclaw message send --channel web --content "page_snapshot_cache https://example.com --snapshot '...' --refs {...}"
 
-# 清空特定级别
-openclaw message send --channel web --content "清空L1缓存"
+# 查询缓存
+openclaw message send --channel web --content "page_snapshot_cache https://example.com"
 
-# 清空特定URL的缓存
-openclaw message send --channel web --content "清空登录页面缓存"
+# 查看统计
+openclaw message send --channel web --content "page_cache_stats"
+
+# 清空缓存
+openclaw message send --channel web --content "page_cache_clear"
 ```
 
-### 多实例集成
+### 通过 Web UI 使用
+1. 在 OpenClaw Web UI 中发送消息
+2. AI 会自动调用 page-action-cache 扩展的工具
+3. 工具会执行缓存操作并返回结果
+4. 用户可以看到缓存命中情况和统计信息
 
-当使用 OpenClaw 多实例架构时，可以为不同实例配置不同的缓存策略：
+## 配置示例
 
-#### 实例配置示例
+### 基础配置
 ```json
 {
   "plugins": {
     "entries": {
       "page-action-cache": {
-        "path": "/Users/zhoujinyu/Documents/projects/page-action-cache",
         "enabled": true,
-        "config": {
-          // 生产实例配置
-          "cacheLevelStrategy": "l3-only",
-          "pageChangeDetectionEnabled": true,
-          "invalidationStrategy": "hard"
-        }
+        "autoUseCache": true
       }
     }
   }
 }
 ```
 
-不同实例可以共享同一个扩展代码，但使用不同的配置参数：
-- **开发实例**: 使用 L1 缓存，软失效策略
-- **测试实例**: 使用 auto 策略，快速迭代
-- **生产实例**: 使用 L3 缓存，硬失效策略，确保稳定性
-
-### 与 Browser Client API 集成
-
-扩展通过 HTTP API 与 OpenClaw Browser Client 通信：
-
-**环境变量**:
-```bash
-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：
-1. 环境变量 `OPENCLAW_BROWSER_CLIENT_URL` 指定的地址
-2. 默认地址 `http://localhost:3000`
-3. 如果都不可用，扩展仍然可以工作，但浏览器操作会被跳过
-
-## 安装和使用
-
-### 安装
-```bash
-# 开发目录安装
-cd /Users/zhoujinyu/Documents/projects/page-action-cache
-npm install
-
-# 构建项目
-npm run build
-```
-
-### 使用
-该扩展提供三个工具：
-
-1. **browser_cache_execute**: 执行缓存的页面操作序列
-2. **browser_cache_stats**: 查看缓存统计信息
-3. **browser_cache_clear**: 清空页面操作缓存
-
-### 配置选项
-```json
-{
-  "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
-}
-```
-
-## 测试
-
-### 运行所有测试
-```bash
-npm test
-```
-
-### 运行特定测试
-```bash
-# 场景识别测试
-npm test -- tests/scenario-recognizer.test.ts
-
-# 基础功能测试
-npm test -- tests/basic.test.ts
-```
-
 ## 性能优化
 
 ### 缓存策略
-- **命中率优化**: 多级缓存自动调整存储位置
-- **容量管理**: LRU驱逐策略确保缓存有效性
-- **过期清理**: 定期清理过期和低质量缓存
-
-### 执行优化
-- **失败跳过**: 自动跳过高失败率的操作
-- **时间节省**: 实时计算缓存带来的性能提升
-- **智能调度**: 根据场景和置信度选择最佳缓存级别
-
-## 开发状态
-
-✅ **已完成的功能**:
-- 场景识别系统
-- 变量提取系统
-- 多级缓存系统
-- 缓存失效系统
-- 浏览器动作执行系统
-- 完整的测试覆盖
-- TypeScript 类型定义
-- OpenClaw 插件接口实现
-
-⚠️ **已知限制**:
-- 依赖 OpenClaw Browser Client API（需要实际的浏览器客户端）
-- 某些高级测试需要实际的浏览器环境
-- LLM 分类需要外部服务集成
+- **TTL 过期**: 5 分钟后自动失效
+- **LRU 驱逐**: 超过容量时删除最旧的条目
+- **访问计数**: 跟踪每个缓存的命中次数
+- **自动清理**: 每次操作时检查并清理过期缓存
+
+### 预期性能提升
+| 场景 | 无缓存 | 有缓存 | 提升 |
+|--------|--------|--------|------|
+| 首次访问 | ~5s | ~5s | 0% (需存储) |
+| 再次访问 | ~5s | ~50ms | 99% |
+| 缓存命中 | 正常 | 正常 | 0% (直接用 refs) |
 
 ## 技术栈
 
@@ -389,6 +166,23 @@ npm test -- tests/basic.test.ts
 - **测试框架**: Vitest
 - **目标环境**: Node.js 22+
 - **构建工具**: TypeScript Compiler
+- **OpenClaw SDK**: openclaw/plugin-sdk
+
+## 开发状态
+
+### 已完成的功能
+- ✅ OpenClaw Plugin SDK 集成
+- ✅ 内存缓存实现
+- ✅ TTL 过期管理
+- ✅ LRU 容量管理
+- ✅ 统计信息工具
+- ✅ 缓存清空工具
+- ✅ TypeScript 类型定义
+
+### 已知限制
+- 缓存存储在内存中，进程重启后清空
+- 目前不支持跨进程持久化
+- 不支持页面变化检测（简化版本）
 
 ## 许可证
 
@@ -396,4 +190,4 @@ MIT
 
 ## 贡献
 
-欢迎提交 Issue 和 Pull Request！
+欢迎提交 Issue 和 Pull Request！

package/dist/index.d.ts

@@ -1,11 +1,28 @@
 /**
  * Page Action Cache - OpenClaw Extension
- * 页面操作缓存扩展 - OpenClaw 扩展
+ * 页面操作缓存扩展
  */
-import type { OpenClawPluginApi } from './types-mock.js';
+interface OpenClawPluginApi {
+    registerTool(tool: {
+        name: string;
+        description: string;
+        inputSchema: unknown;
+        execute: (params: unknown) => Promise<unknown>;
+    }): void;
+    getToolContext?: () => {
+        config?: Record<string, unknown>;
+    };
+}
+/**
+ * 插件配置接口
+ */
+export interface PageActionCacheConfig {
+    enabled: boolean;
+    autoUseCache?: boolean;
+}
 /**
  * 主扩展入口
  */
-export declare function register(api: OpenClawPluginApi): void;
-export declare const registerTools: typeof register;
+export default function register(api: OpenClawPluginApi): void;
+export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAOzD;;GAEG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,iBAAiB,GAAG,IAAI,CAicrD;AAGD,eAAO,MAAM,aAAa,iBAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,UAAU,iBAAiB;IACzB,YAAY,CAAC,IAAI,EAAE;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,OAAO,CAAC;QACrB,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;KAChD,GAAG,IAAI,CAAC;IACT,cAAc,CAAC,EAAE,MAAM;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;CAC7D;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAoDD;;GAEG;AACH,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,GAAG,EAAE,iBAAiB,GAAG,IAAI,CAiP7D"}