page-action-cache 1.0.1

package/docs/API.md

@@ -0,0 +1,555 @@
+# Page Action Cache API Reference
+
+完整的 API 参考文档。
+
+## 目录
+
+- [缓存存储 API](#缓存存储-api-cachestore)
+- [场景识别 API](#场景识别-api-scenariorecognizer)
+- [变量解析 API](#变量解析-api-variableresolver)
+- [操作执行 API](#操作执行-api-actionsexecutor)
+- [安全策略 API](#安全策略-api-securitypolicy)
+- [缓存失效 API](#缓存失效-api-cacheinvalidator)
+- [用户体验 API](#用户体验-api-uxenhancer)
+- [Hooks API](#hooks-api-hooks)
+- [缓存策略 API](#缓存策略-api-cachestrategy)
+
+---
+
+## 缓存存储 API (CacheStore)
+
+### 初始化
+
+```typescript
+import { getCacheStore } from "@openclaw/page-action-cache";
+
+const cacheStore = getCacheStore();
+```
+
+### 主要方法
+
+#### `set(url, viewport, actions, metadata): string`
+
+保存缓存条目。
+
+```typescript
+const key = cacheStore.set(
+  "https://example.com/login",
+  { width: 1920, height: 1080 },
+  [
+    { type: "click", ref: "#username", order: 1 },
+    { type: "type", ref: "#password", text: "...", order: 2 },
+    { type: "click", ref: "#submit", order: 3 }
+  ],
+  {
+    scenario: "login",
+    cacheLevel: "L3",
+    description: "登录操作",
+    variables: { username: "user" }
+  }
+);
+```
+
+**参数:**
+- `url: string` - 页面 URL
+- `viewport: PageViewport` - 视口尺寸
+- `actions: AtomicAction[]` - 操作序列
+- `metadata: CacheEntryMetadata` - 元数据
+
+**返回值:** 缓存键 (MD5 hash)
+
+---
+
+#### `get(url, viewport): PageActionCacheEntry | null`
+
+获取缓存条目。
+
+```typescript
+const entry = cacheStore.get(
+  "https://example.com/login",
+  { width: 1920, height: 1080 }
+);
+```
+
+**返回值:** 缓存条目，如果不存在则返回 `null`
+
+---
+
+#### `listEntries(): PageActionCacheEntry[]`
+
+列出所有缓存条目。
+
+```typescript
+const entries = cacheStore.listEntries();
+```
+
+---
+
+#### `delete(url, viewport): boolean`
+
+删除缓存条目。
+
+```typescript
+const deleted = cacheStore.delete(
+  "https://example.com/login",
+  { width: 1920, height: 1080 }
+);
+console.log(`删除: ${deleted}`);
+```
+
+---
+
+#### `clear(): void`
+
+清空所有缓存。
+
+```typescript
+cacheStore.clear();
+```
+
+---
+
+#### `getStats(): CacheStats`
+
+获取缓存统计信息。
+
+```typescript
+const stats = cacheStore.getStats();
+console.log(`命中率: ${stats.hitRate}%`);
+console.log(`节省 tokens: ${stats.savedTokens}`);
+console.log(`节省时间: ${stats.savedTime}ms`);
+```
+
+**统计字段:**
+- `totalEntries` - 总条目数
+- `totalHits` - 总命中数
+- `totalMisses` - 总未命中数
+- `hitRate` - 命中率 (0-100)
+- `l3Hits` - L3 缓存命中数
+- `l2Hits` - L2 缓存命中数
+- `l1Hits` - L1 缓存命中数
+- `scenarioMatches` - 场景识别匹配数
+- `savedTokens` - 节省的 tokens 数量
+- `savedTime` - 节省的时间（毫秒）
+
+---
+
+## 场景识别 API (ScenarioRecognizer)
+
+### 初始化
+
+```typescript
+import { getScenarioRecognizer } from "@openclaw/page-action-cache";
+
+const recognizer = getScenarioRecognizer();
+```
+
+### 主要方法
+
+#### `recognize(userInput, currentUrl): Promise<ScenarioMatch | null>`
+
+识别用户场景。
+
+```typescript
+const match = await recognizer.recognize(
+  "请帮我登录",
+  "https://example.com/page"
+);
+
+if (match) {
+  console.log(`场景: ${match.scenario}`);
+  console.log(`置信度: ${match.confidence}`);
+  console.log(`方法: ${match.method}`);
+}
+```
+
+**返回值:** 场景匹配结果，包含：
+- `scenario` - 场景名称
+- `confidence` - 置信度 (0-100)
+- `method` - 匹配方法
+- `matchedPattern` - 匹配的模式
+
+---
+
+## 变量解析 API (VariableResolver)
+
+### 初始化
+
+```typescript
+import { getVariableResolver } from "@openclaw/page-action-cache";
+
+const resolver = getVariableResolver();
+```
+
+### 主要方法
+
+#### `resolveVariables(userInput, scenario): VariableMap`
+
+从用户输入解析变量。
+
+```typescript
+const variables = resolver.resolveVariables(
+  "用户名是 admin，密码是 secret123",
+  "login"
+);
+
+console.log(variables);
+// { username: "admin", password: "secret123" }
+```
+
+---
+
+#### `validateVariables(variables, scenario): boolean`
+
+验证变量是否有效。
+
+```typescript
+const isValid = resolver.validateVariables(variables, "login");
+```
+
+---
+
+#### `mergeVariables(base, override): VariableMap`
+
+合并变量映射。
+
+```typescript
+const merged = resolver.mergeVariables(baseVariables, overrideVariables);
+```
+
+---
+
+## 操作执行 API (ActionsExecutor)
+
+### 初始化
+
+```typescript
+import { getActionsExecutor } from "@openclaw/page-action-cache";
+
+const executor = getActionsExecutor(cdpUrl);
+executor.setPlaywrightClient(pwClient);
+```
+
+### 主要方法
+
+#### `execute(action, variables?): Promise<ExecutionResult>`
+
+执行单个操作。
+
+```typescript
+const result = await executor.execute(action, {
+  username: "...",
+  password: "..."
+});
+```
+
+---
+
+#### `executeBatch(actions, variables?, options?): Promise<ExecutionResult[]>`
+
+批量执行操作。
+
+```typescript
+const results = await executor.executeBatch(actions, variables, {
+  fromIndex: 0,
+  toIndex: 2,
+  atomic: true  // 全部成功或全部失败
+});
+```
+
+---
+
+#### `formatActions(actions): string`
+
+格式化操作列表为可读字符串。
+
+```typescript
+const text = executor.formatActions(actions);
+console.log(text);
+```
+
+---
+
+#### `formatExecutionResults(results): string`
+
+格式化执行结果。
+
+```typescript
+const text = executor.formatExecutionResults(results);
+console.log(text);
+```
+
+---
+
+## 安全策略 API (SecurityPolicy)
+
+### 初始化
+
+```typescript
+import { getSecurityPolicy } from "@openclaw/page-action-cache";
+
+const policy = getSecurityPolicy();
+```
+
+### 主要方法
+
+#### `isSensitiveAction(action): boolean`
+
+检查操作是否包含敏感变量。
+
+```typescript
+const isSensitive = policy.isSensitiveAction({
+  type: "type",
+  ref: "#password",
+  variable: "password",
+  text: "..."
+});
+// true - 密码字段，应该加密
+```
+
+---
+
+#### `encrypt(data): string`
+
+加密数据。
+
+```typescript
+const encrypted = policy.encrypt("sensitive-data");
+```
+
+---
+
+#### `decrypt(encrypted): string`
+
+解密数据。
+
+```typescript
+const decrypted = policy.decrypt(encrypted);
+```
+
+---
+
+#### `sanitizeForLogging(data): any`
+
+脱敏数据用于日志输出。
+
+```typescript
+const sanitized = policy.sanitizeForLogging({
+  username: "...",
+  password: "..."
+});
+// { username: "...", password: "***REDACTED***" }
+```
+
+---
+
+## 缓存失效 API (CacheInvalidator)
+
+### 初始化
+
+```typescript
+import { getCacheInvalidator } from "@openclaw/page-action-cache";
+
+const invalidator = getCacheInvalidator();
+```
+
+### 主要方法
+
+#### `detectPageChange(html, url, viewport, cachedEntry?): Promise<PageChangeDetection>`
+
+检测页面是否发生变化。
+
+```typescript
+const detection = await invalidator.detectPageChange(
+  html,
+  url,
+  viewport,
+  cachedEntry
+);
+
+if (detection.hasChanged) {
+  console.log(`页面已变化: ${detection.changeType}`);
+  console.log(`置信度: ${detection.confidence}`);
+}
+```
+
+---
+
+## 用户体验 API (UXEnhancer)
+
+### 初始化
+
+```typescript
+import { getUXEnhancer } from "@openclaw/page-action-cache";
+
+const enhancer = getUXEnhancer();
+```
+
+### 主要方法
+
+#### `generateStatsReport(): string`
+
+生成统计报告。
+
+```typescript
+const report = enhancer.generateStatsReport();
+console.log(report);
+```
+
+---
+
+#### `formatCacheEntry(entry): string`
+
+格式化缓存条目。
+
+```typescript
+const text = enhancer.formatCacheEntry(entry);
+```
+
+---
+
+## Hooks API (Hooks)
+
+### 初始化
+
+```typescript
+import { registerPageActionCacheHooks } from "@openclaw/page-action-cache";
+
+// 注册 hooks
+registerPageActionCacheHooks(api, config);
+```
+
+### 注册的 Hooks
+
+#### `before_tool_call`
+
+- **触发时机:** 在任何工具调用之前
+- **用途:** 场景识别和缓存拦截
+- **返回值:** `{ block: false, result?: { cacheInfo, stats } }`
+
+**示例响应:**
+
+```typescript
+{
+  block: false,
+  result: {
+    cacheInfo: {
+      exists: true,
+      scenario: "login",
+      confidence: 90,
+      method: "keyword",
+      cacheLevel: "L3",
+      actions: [...],
+      cacheKey: "abc123..."
+    },
+    stats: {
+      hitRate: 75.5,
+      savedTokens: 15000
+    }
+  }
+}
+```
+
+---
+
+#### `after_tool_call`
+
+- **触发时机:** 在工具调用完成之后
+- **用途:** 保存 LLM 分析结果到缓存
+- **返回值:** 无返回值
+
+**功能:**
+- 提取 LLM 返回的场景类型
+- 解析用户输入中的变量
+- 根据场景匹配决定缓存层级
+- 保存到缓存存储
+
+---
+
+#### `before_prompt_build`
+
+- **触发时机:** 在构建提示之前
+- **用途:** 注入缓存使用指南
+- **返回值:** `{ prependContext?: string }`
+
+**示例响应:**
+
+```typescript
+{
+  prependContext: `
+【页面操作缓存系统】
+
+当前缓存统计：
+- 总条目数：42
+- 总命中：28
+- 命中率：66.7%
+
+已缓存的场景：
+1. login (命中率: 85%)
+2. search (命中率: 72%)
+3. checkout (命中率: 68%)
+
+使用方式：
+1. 如果工具返回 cacheInfo 信息，优先使用缓存的操作
+2. 执行缓存操作可以大幅降低 token 消耗和操作延迟
+`
+}
+```
+
+---
+
+## 缓存策略 API (CacheStrategy)
+
+### 策略类型
+
+#### `AutoCacheStrategy`
+
+自动选择缓存层级。
+
+```typescript
+import { AutoCacheStrategy } from "@openclaw/page-action-cache";
+
+const strategy = new AutoCacheStrategy();
+```
+
+---
+
+#### `L3OnlyCacheStrategy`
+
+仅使用 L3 缓存。
+
+```typescript
+import { L3OnlyCacheStrategy } from "@openclaw/page-action-cache";
+
+const strategy = new L3OnlyCacheStrategy();
+```
+
+---
+
+#### `L2OnlyCacheStrategy`
+
+仅使用 L2 和 L3 缓存。
+
+```typescript
+import { L2OnlyCacheStrategy } from "@openclaw/page-action-cache";
+
+const strategy = new L2OnlyCacheStrategy();
+```
+
+---
+
+#### `L1OnlyCacheStrategy`
+
+仅使用 L1、L2 和 L3 缓存。
+
+```typescript
+import { L1OnlyCacheStrategy } from "@openclaw/page-action-cache";
+
+const strategy = new L1OnlyCacheStrategy();
+```
+
+---
+
+## 类型定义
+
+所有 API 都使用统一的类型定义。详见 [类型定义](../src/types.ts)。