page-action-cache 1.0.1

package/docs/INTEGRATION.md

@@ -0,0 +1,387 @@
+# Page Action Cache Extension - 集成到 OpenClaw
+
+本文档说明如何将 `@openclaw/page-action-cache` 扩展集成到 OpenClaw 项目。
+
+## 概述
+
+**page-action-cache** 是一个 **Hooks 类型扩展**，不是 ChannelPlugin。它通过注册 Hooks 来拦截和增强浏览器操作，实现页面操作缓存以降低 token 消耗和操作延迟。
+
+## 扩展类型
+
+- **类型**: Hooks 扩展
+- **ID**: `page-action-cache`
+- **用途**: 浏览器操作缓存
+- **版本**: 1.0.0
+
+## 主要功能
+
+1. **场景识别**: 自动识别常见场景（登录、搜索、支付等）
+2. **缓存存储**: 基于 MD5 hash 和 TTL 的文件存储
+3. **变量系统**: 从用户输入提取变量（用户名、密码等）
+4. **安全策略**: 敏感字段加密、访问控制、日志脱敏
+5. **缓存失效**: DOM 变化检测、结构哈希比较
+6. **用户体验增强**: 缓存状态展示、用户确认、错误反馈
+
+## 集成步骤
+
+### 1. 在主项目 package.json 中添加依赖
+
+在 `/Users/zhoujinyu/Documents/projects/repo/package.json` 中添加：
+
+```json
+{
+  "devDependencies": {
+    "@openclaw/page-action-cache": "workspace:*"
+  }
+}
+```
+
+### 2. 通过配置文件管理（推荐）
+
+使用 OpenClaw 的插件配置系统，通过命令行设置配置：
+
+```bash
+# 添加插件配置
+openclaw config set plugins.entries.page-action-cache.enabled=true
+openclaw config set plugins.entries.page-action-cache.config.enabled=true
+openclaw config set plugins.entries.page-action-cache.config.autoUseCache=true
+openclaw config set plugins.entries.page-action-cache.config.scenarioRecognitionEnabled=true
+```
+
+**配置文件格式：**
+
+```json5
+{
+  plugins: {
+    enabled: true,
+    allow: ["page-action-cache"],
+    entries: {
+      "page-action-cache": {
+        enabled: true,
+        config: {
+          enabled: true,
+          autoUseCache: true,
+          scenarioRecognitionEnabled: true,
+        },
+      },
+    },
+  },
+}
+```
+
+**配置文件位置：**
+
+- **macOS**: `~/.openclaw/config.json`
+- **Linux**: `~/.openclaw/config.json`
+
+**加载配置后重启服务：**
+
+```bash
+# macOS app: 重新打开应用
+# - Linux: systemctl restart openclaw-gateway
+# - 开发环境: 重启网关进程
+```
+
+**注意：** 配置文件需要 OpenClaw 的插件系统支持。如果插件系统不支持此方式，可以使用方法 3（代码初始化）作为替代。
+
+---
+
+### 3. 代码初始化（直接调用）
+
+在 OpenClaw 启动时直接调用扩展初始化函数：
+
+```typescript
+import { initializePageActionCache } from "@openclaw/page-action-cache/hooks-entry";
+
+// 在网关或代理启动时
+initializePageActionCache(gatewayApi, {
+  enabled: true,
+  autoUseCache: true,
+  scenarioRecognitionEnabled: true,
+  cacheLevelStrategy: "auto",
+});
+```
+
+### 4. Hooks 自动注册
+
+扩展通过 `registerPageActionCacheHooks()` 函数自动注册以下 Hooks：
+
+- **before_tool_call**: 场景识别和缓存拦截
+  - 检测 `browser` 工具调用
+  - 识别场景（登录、搜索、支付等）
+  - 返回缓存信息（如果缓存命中）
+
+- **after_tool_call**: 保存 LLM 分析结果
+  - 提取 LLM 返回的场景类型
+  - 解析变量
+  - 保存到缓存（L3/L2/L1）
+
+- **before_prompt_build**: 注入缓存使用指南
+  - 在命中率 > 30% 时注入
+  - 显示缓存统计
+  - 列出已缓存场景
+
+## API 导出
+
+### 核心 API
+
+```typescript
+// 缓存存储
+import { getCacheStore } from "@openclaw/page-action-cache";
+const cacheStore = getCacheStore();
+
+// 保存缓存
+cacheStore.set(url, viewport, actions, {
+  scenario: "login",
+  cacheLevel: "L3",
+  variables: { username: "...", password: "..." },
+});
+
+// 获取缓存
+const entry = cacheStore.get(url, viewport);
+
+// 列出缓存
+const entries = cacheStore.listEntries();
+
+// 清空缓存
+cacheStore.clear();
+```
+
+### 场景识别
+
+```typescript
+import { getScenarioRecognizer } from "@openclaw/page-action-cache";
+const recognizer = getScenarioRecognizer();
+
+// 识别场景
+const match = await recognizer.recognize(userInput, currentUrl);
+if (match) {
+  console.log(`场景: ${match.scenario}, 置信度: ${match.confidence}`);
+}
+```
+
+### 变量解析
+
+```typescript
+import { getVariableResolver } from "@openclaw/page-action-cache";
+const resolver = getVariableResolver();
+
+// 解析变量
+const variables = resolver.resolveVariables(userInput, scenario);
+```
+
+### 操作执行
+
+```typescript
+import { getActionsExecutor } from "@openclaw/page-action-cache";
+const executor = getActionsExecutor();
+executor.setCdpUrl(cdpUrl);
+
+// 执行操作
+const results = await executor.executeBatch(actions, variables);
+```
+
+### 安全策略
+
+```typescript
+import { getSecurityPolicy } from "@openclaw/page-action-cache";
+const policy = getSecurityPolicy();
+
+// 检测敏感操作
+if (policy.isSensitiveAction(action)) {
+  // 加密处理
+}
+
+// 脱敏日志输出
+const sanitizedData = policy.sanitizeForLogging(data);
+```
+
+## 配置选项
+
+扩展接受以下配置选项：
+
+```typescript
+interface CacheConfig {
+  // 全局开关
+  enabled?: boolean; // 是否启用扩展（默认: true）
+  autoUseCache?: boolean; // 是否自动使用缓存（默认: true）
+
+  // 场景识别
+  scenarioRecognitionEnabled?: boolean; // 是否启用场景识别（默认: true）
+  llmClassificationThreshold?: number; // LLM 分类阈值（默认: 70）
+
+  // 缓存策略
+  cacheLevelStrategy?: "auto" | "l3-only" | "l2-only" | "l1-only"; // 缓存层级策略（默认: auto）
+  defaultCacheLevel?: string; // 默认缓存层级（默认: L3）
+
+  // 缓存失效
+  pageChangeDetectionEnabled?: boolean; // 是否启用页面变化检测（默认: true）
+  changeInvalidationThreshold?: number; // 变化失效阈值（默认: 80）
+  invalidationStrategy?: "soft" | "hard"; // 失效策略（默认: soft）
+
+  // 变量系统
+  variableExtractionEnabled?: boolean; // 是否启用变量提取（默认: true）
+  allowUserConfirmVariables?: boolean; // 是否允许用户确认变量（默认: false）
+
+  // 安全
+  encryptSensitiveCache?: boolean; // 是否加密敏感缓存（默认: false）
+  accessControlEnabled?: boolean; // 是否启用访问控制（默认: false）
+  logSanitizationEnabled?: boolean; // 是否启用日志脱敏（默认: true）
+
+  // 用户体验
+  showCacheStatusToUser?: boolean; // 是否向用户显示缓存状态（默认: true）
+  enableUserCacheConfirmation?: boolean; // 是否启用用户缓存确认（默认: false）
+  enableUserForcedRefresh?: boolean; // 是否启用用户强制刷新（默认: true）
+  enableUserCacheErrorReport?: boolean; // 是否启用用户缓存错误报告（默认: true）
+
+  // 统计
+  trackExecutionStats?: boolean; // 是否跟踪执行统计（默认: true）
+  statsUpdateInterval?: number; // 统计更新间隔（秒，默认: 60）
+}
+```
+
+## 支持的场景
+
+扩展内置支持以下场景识别规则：
+
+| 场景       | 关键词                                          | URL 模式                         | 缓存层级 | 置信度 |
+| ---------- | ----------------------------------------------- | -------------------------------- | -------- | ------ |
+| login      | 登录、登陆、注册、进入、login to、sign in、账号 | /login, /signin, /auth, /account | L3       | 90     |
+| logout     | 退出、登出、注销、sign out、logout              | /logout, /signout                | L3       | 90     |
+| search     | 搜索、查找、找、search for、查询                | /search, /query, /list           | L3       | 80     |
+| checkout   | 结账、结算、支付、收银、买单、checkout          | /checkout, /cart, /payment       | L3       | 85     |
+| settings   | 设置、配置、修改、编辑、个人中心                | /settings, /config, /profile     | L3       | 75     |
+| form_fill  | 填写、填表单、提交、submit form                 | -                                | L2       | 70     |
+| navigate   | 打开、进入、跳转、go to、open、navigate         | -                                | L2       | 60     |
+| screenshot | 截图、截图、snapshot、screenshot                | -                                | L1       | 50     |
+
+## 缓存层级
+
+| 层级 | 描述                       | 用途                      |
+| ---- | -------------------------- | ------------------------- |
+| L3   | 场景级缓存（包含变量模板） | 高置信度（≥85）时直接使用 |
+| L2   | 流程级缓存                 | 中等置信度（≥70）时使用   |
+| L1   | 原子级缓存                 | 低置信度或无场景时使用    |
+
+## 开发和构建
+
+### 本地开发
+
+```bash
+cd extensions/page-action-cache
+pnpm build        # 构建扩展
+pnpm test         # 运行测试
+pnpm typecheck    # 类型检查
+```
+
+### 添加到 OpenClaw
+
+1. 确保扩展在 `extensions/page-action-cache` 目录
+2. 在主项目的 `package.json` 中添加 workspace 依赖
+3. 在适当的启动代码中调用 `initializePageActionCache()`
+
+## 发布到 npm
+
+### 使用发布脚本（推荐）
+
+扩展提供了发布脚本来自动处理 npm 发布时的工作区依赖问题：
+
+```bash
+# 从扩展目录运行发布脚本
+cd extensions/page-action-cache
+./scripts/npm_publish.sh
+```
+
+发布脚本会自动：
+
+- 移除 `workspace:*` 依赖（npm 不支持此协议）
+- 构建扩展
+- 发布到 npm
+
+### 手动发布
+
+如果需要手动发布，请按以下步骤：
+
+```bash
+# 1. 构建扩展
+cd extensions/page-action-cache
+pnpm build
+
+# 2. 临时移除工作区依赖
+node -e "
+const fs = require('fs');
+const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+delete pkg.dependencies;
+fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2));
+"
+
+# 3. 发布到 npm
+npm publish --access public
+
+# 4. 恢复原始配置
+git checkout package.json
+```
+
+**重要说明：**
+
+- npm 不支持 `workspace:*` 协议，发布前必须移除工作区依赖
+- 扩展依赖声明在 `peerDependencies` 中，所以移除 `dependencies` 不影响运行时
+- 发布后记得恢复原始 `package.json` 以便本地开发
+
+## 测试
+
+扩展包含集成测试：
+
+```bash
+# 在扩展目录
+cd extensions/page-action-cache
+pnpm test
+
+# 运行集成测试（如果需要）
+cd ../..
+pnpm test integration
+```
+
+## 故障排查
+
+### 扩展未加载
+
+1. 检查依赖是否正确安装
+
+   ```bash
+   npm list | grep page-action-cache
+   ```
+
+2. 检查扩展是否被初始化
+   - 查看日志中是否有 `[PageActionCache] Extension initialized` 消息
+
+### Hooks 未触发
+
+1. 检查 OpenClaw 是否正确调用了 `initializePageActionCache()`
+2. 检查配置中的 `enabled` 选项
+
+### 缓存未命中
+
+1. 检查场景识别是否正确工作
+2. 检查用户输入是否匹配关键词规则
+3. 查看 `cacheStore.getStats()` 输出
+
+### 敏感数据未加密
+
+1. 检查 `encryptSensitiveCache` 配置是否为 `true`
+2. 检查敏感字段列表是否正确
+3. 查看日志输出是否正确脱敏
+
+## 相关文档
+
+- [类型定义](./src/types.ts) - 完整的类型定义
+- [实现文档](./IMPLEMENTATION.md) - 详细的实现说明
+- [测试](./tests/integration.test.ts) - 集成测试
+
+## 版本历史
+
+- **1.0.0** - 初始版本
+  - 完整的 Playwright API 对齐
+  - 场景识别、变量解析、缓存存储
+  - 安全策略、缓存失效
+  - Hooks 自动注册

package/docs/README.md

@@ -0,0 +1,183 @@
+# Page Action Cache Extension
+
+页面操作缓存扩展 - 降低 token 消耗和操作延迟。
+
+## 简介
+
+Page Action Cache 扩展为 OpenClaw 提供智能的浏览器操作缓存功能。通过识别常见场景（登录、搜索、支付等）并缓存相应的操作序列，扩展可以避免重复分析相同的 DOM 结构，大幅降低 token 消耗和操作延迟。
+
+## 功能特性
+
+### 🎯 场景识别
+
+自动识别常见用户场景并匹配缓存：
+
+- **登录/登出** - 识别登录和登出操作
+- **搜索** - 识别搜索查询操作
+- **支付** - 识别结账和支付流程
+- **设置** - 识别配置修改操作
+- **表单填写** - 识别表单提交操作
+- **导航** - 识别页面导航操作
+
+### 💾 缓存存储
+
+- **MD5 Hash** - 基于 URL + 视口尺寸的哈希值作为缓存键
+- **TTL 失效** - 支持基于时间的缓存过期
+- **文件存储** - 持久化存储在 `~/.openclaw/cache/page-actions/`
+- **统计跟踪** - 自动记录命中率、token 节省等
+
+### 🔄 缓存失效
+
+- **DOM 变化检测** - 检测页面结构变化
+- **结构哈希** - 比较表单、按钮、链接等元素
+- **自动刷新** - 高置信度变化时自动失效旧缓存
+
+### 🛡️ 安全策略
+
+- **敏感字段加密** - AES-256-GCM 加密密码、token 等敏感数据
+- **访问控制** - 可配置允许访问的用户 ID
+- **日志脱敏** - 自动脱敏敏感字段输出到日志
+
+### 📊 用户体验增强
+
+- **缓存状态展示** - 向用户显示缓存命中/未命中状态
+- **用户确认** - 可选的用户缓存确认机制
+- **错误反馈** - 缓存错误的详细反馈
+
+## 快速开始
+
+### 安装依赖
+
+```bash
+# 在 OpenClaw 项目根目录
+pnpm install
+```
+
+### 初始化扩展
+
+```typescript
+import { initializePageActionCache } from "@openclaw/page-action-cache/hooks-entry";
+
+// 使用默认配置
+initializePageActionCache(gatewayApi, {
+  enabled: true,
+  autoUseCache: true,
+  scenarioRecognitionEnabled: true,
+  cacheLevelStrategy: "auto",
+});
+```
+
+### 使用缓存 API
+
+```typescript
+import { getCacheStore } from "@openclaw/page-action-cache";
+
+// 保存缓存
+cacheStore.set(url, viewport, actions, {
+  scenario: "login",
+  cacheLevel: "L3",
+  variables: { username: "...", password: "..." },
+});
+
+// 获取缓存
+const entry = cacheStore.get(url, viewport);
+if (entry) {
+  console.log(`✅ 缓存命中: ${entry.scenario} (${entry.cacheLevel})`);
+}
+```
+
+## 配置选项
+
+扩展支持以下配置：
+
+| 选项                         | 类型                                          | 默认值 | 说明                 |
+| ---------------------------- | --------------------------------------------- | ------ | -------------------- |
+| `enabled`                    | boolean                                       | true   | 是否启用扩展         |
+| `autoUseCache`               | boolean                                       | true   | 是否自动使用缓存     |
+| `scenarioRecognitionEnabled` | boolean                                       | true   | 是否启用场景识别     |
+| `cacheLevelStrategy`         | "auto" \| "l3-only" \| "l2-only" \| "l1-only" | "auto" | 缓存层级策略         |
+| `pageChangeDetectionEnabled` | boolean                                       | true   | 是否启用页面变化检测 |
+| `variableExtractionEnabled`  | boolean                                       | true   | 是否启用变量提取     |
+| `encryptSensitiveCache`      | boolean                                       | false  | 是否加密敏感缓存     |
+
+## 缓存层级说明
+
+| 层级   | 描述                       | 用途                       |
+| ------ | -------------------------- | -------------------------- |
+| **L3** | 场景级缓存（包含变量模板） | 高置信度（≥85%）时直接使用 |
+| **L2** | 流程级缓存                 | 中等置信度（≥70%）时使用   |
+| **L1** | 原子级缓存                 | 低置信度或无场景时使用     |
+
+## 支持的场景
+
+| 场景       | 关键词示例                    | 缓存层级 |
+| ---------- | ----------------------------- | -------- |
+| login      | 登录、账号、login to、sign in | L3       |
+| logout     | 退出、登出、sign out          | L3       |
+| search     | 搜索、查找、search for        | L3       |
+| checkout   | 结账、支付、checkout          | L3       |
+| settings   | 设置、配置                    | L3       |
+| form_fill  | 填写、提交、form              | L2       |
+| navigate   | 打开、进入、go to             | L2       |
+| screenshot | 截图、screenshot              | L1       |
+
+## 工作原理
+
+```
+用户输入 → 场景识别 → 检查缓存 → 返回 LLM 或缓存操作
+         ↓                        ↓                  ↓
+       (关键词匹配)              (哈希查找)      (执行缓存)
+```
+
+### 场景识别流程
+
+1. **关键词匹配** - 匹配预定义的关键词（最快）
+2. **URL 模式匹配** - 匹配 URL 模式
+3. **LLM 分类** - 使用 LLM 进行意图分类（未来）
+4. **历史学习** - 基于历史匹配学习新场景
+
+### 缓存决策流程
+
+1. 检查缓存是否存在
+2. 检查缓存是否过期
+3. 检查页面是否发生变化
+4. 根据置信度决定是否使用缓存
+
+## 发布和构建
+
+### 发布到 npm
+
+扩展提供了自动发布脚本：
+
+```bash
+cd extensions/page-action-cache
+./scripts/npm_publish.sh
+```
+
+发布脚本会处理 npm 不支持的 `workspace:*` 协议问题。
+
+### 手动构建和发布
+
+```bash
+# 构建扩展
+cd extensions/page-action-cache
+pnpm build
+
+# 运行测试
+pnpm test
+
+# 类型检查
+pnpm typecheck
+```
+
+**注意：** 发布到 npm 时需要先移除 `package.json` 中的 `workspace:*` 依赖，因为 npm 不支持此协议。
+
+## 更多文档
+
+- [集成指南](./INTEGRATION.md) - 如何集成到 OpenClaw
+- [实现文档](./IMPLEMENTATION.md) - 详细的技术实现
+- [类型定义](../src/types.ts) - 完整的类型定义
+
+## 版本
+
+当前版本: 1.0.0

package/index.ts

@@ -0,0 +1,118 @@
+/**
+ * Page Action Cache Extension
+ * 页面操作缓存扩展入口
+ *
+ * 功能：
+ * - 缓存 LLM 生成的浏览器操作序列
+ * - 避免重复分析相同页面
+ * - 大幅降低 token 消耗和操作延迟
+ *
+ * 使用方法：
+ * 1. 安装扩展：npm install @openclaw/page-action-cache
+ * 2. 在配置中启用扩展
+ * 3. LLM 会自动使用缓存的操作序列
+ */
+
+import type { CacheConfig } from "./src/types.js";
+import { registerPageActionCacheHooks } from "./src/hooks.js";
+import { getToolDefinitions } from "./src/tools.js";
+
+// ============================================================================
+// 扩展元数据
+// ============================================================================
+
+export const metadata = {
+  name: "Page Action Cache",
+  version: "1.0.0",
+  description:
+    "缓存 LLM 浏览器操作序列，避免重复分析相同页面，大幅降低 token 消耗",
+  author: "OpenClaw",
+  license: "MIT",
+};
+
+// ============================================================================
+// 默认配置
+// ============================================================================
+
+const DEFAULT_CONFIG: CacheConfig = {
+  enabled: true,
+  autoUseCache: true,
+  scenarioRecognitionEnabled: true,
+  llmClassificationThreshold: 70,
+  cacheLevelStrategy: "auto",
+  defaultCacheLevel: "L3",
+  pageChangeDetectionEnabled: true,
+  changeInvalidationThreshold: 80,
+  invalidationStrategy: "soft",
+  maxVersionsPerEntry: 3,
+  variableExtractionEnabled: true,
+  allowUserConfirmVariables: false,
+  encryptSensitiveCache: false,
+  accessControlEnabled: false,
+  allowedUserIds: [],
+  logSanitizationEnabled: true,
+  showCacheStatusToUser: true,
+  enableUserCacheConfirmation: false,
+  enableUserForcedRefresh: true,
+  enableUserCacheErrorReport: true,
+  trackExecutionStats: true,
+  statsUpdateInterval: 60,
+};
+
+// ============================================================================
+// 扩展初始化
+// ============================================================================
+
+/**
+ * 扩展初始化函数
+ */
+export function activate(api: any, config?: Partial<CacheConfig>): void {
+  console.log(`[PageActionCache] Initializing v${metadata.version}...`);
+
+  const finalConfig = { ...DEFAULT_CONFIG, ...config };
+
+  // 注册 Hooks
+  registerPageActionCacheHooks(api, finalConfig);
+
+  // 注册自定义工具
+  const toolDefinitions = getToolDefinitions();
+  for (const toolDef of toolDefinitions) {
+    api.registerTool?.(toolDef);
+    console.log(`[PageActionCache] Registered tool: ${toolDef.name}`);
+  }
+
+  console.log("[PageActionCache] Extension activated successfully");
+}
+
+/**
+ * 扩展停用函数
+ */
+export function deactivate(): void {
+  console.log("[PageActionCache] Deactivating...");
+  // 清理资源
+  console.log("[PageActionCache] Extension deactivated");
+}
+
+// ============================================================================
+// 导出（用于测试和调试）
+// ============================================================================
+
+export * from "./src/types.js";
+export { getCacheStore } from "./src/cache-store.js";
+export { getScenarioRecognizer } from "./src/scenario-recognizer.js";
+export { getVariableResolver } from "./src/variable-resolver.js";
+export { getCacheInvalidator } from "./src/cache-invalidator.js";
+export { getSecurityPolicy } from "./src/security-policy.js";
+export { getUXEnhancer } from "./src/ux-enhancer.js";
+export { getActionsExecutor } from "./src/actions-executor.js";
+export { getCacheStrategyFactory } from "./src/cache-strategy.js";
+
+// ============================================================================
+// 默认导出（OpenClaw 扩展系统使用）
+// ============================================================================
+
+export default {
+  metadata,
+  activate,
+  deactivate,
+};