page-action-cache 1.0.1

package/src/types.ts

@@ -0,0 +1,482 @@
+/**
+ * Page Action Cache Extension - Type Definitions
+ * Version: 1.0.0
+ *
+ * 完全对齐 Playwright API 的类型定义
+ */
+
+// ============================================================================
+// 基础类型
+// ============================================================================
+
+/**
+ * 页面视口尺寸
+ */
+export interface PageViewport {
+  width: number;
+  height: number;
+}
+
+/**
+ * 变量映射
+ */
+export type VariableMap = Record<string, string>;
+
+// ============================================================================
+// 原子化操作（Playwright 完全对齐）
+// ============================================================================
+
+/**
+ * 原子化操作类型
+ */
+export type AtomicActionType =
+  | "navigate"
+  | "screenshot"
+  | "click"
+  | "type"
+  | "press"
+  | "hover"
+  | "scroll"
+  | "wait"
+  | "select"
+  | "focus"
+  | "drag"
+  | "upload"
+  | "composite";
+
+/**
+ * Playwright 支持的按钮类型
+ */
+export type PlaywrightButton = "left" | "right" | "middle";
+
+/**
+ * Playwright 支持的修饰符
+ */
+export type PlaywrightModifier =
+  | "Alt"
+  | "Control"
+  | "ControlOrMeta"
+  | "Meta"
+  | "Shift";
+
+/**
+ * Playwright 导航策略
+ */
+export interface NavigationPolicy {
+  waitUntil?: "load" | "domcontentloaded" | "networkidle";
+  timeout?: number;
+}
+
+/**
+ * Evaluate 操作参数
+ */
+export interface EvaluateParams {
+  code: string;
+  args?: any[];
+}
+
+/**
+ * 原子化操作基类
+ */
+export interface BaseAtomicAction {
+  type: AtomicActionType;
+  cdpUrl?: string;
+  targetId?: string;
+  ref?: string;
+  variable?: string;
+  order: number;
+  description?: string;
+}
+
+/**
+ * 导航操作
+ */
+export interface NavigateAction extends BaseAtomicAction {
+  type: "navigate";
+  url: string;
+  navigationPolicy?: NavigationPolicy;
+}
+
+/**
+ * 点击操作
+ */
+export interface ClickAction extends BaseAtomicAction {
+  type: "click";
+  ref: string;
+  button?: PlaywrightButton;
+  doubleClick?: boolean;
+  modifiers?: PlaywrightModifier[];
+  timeoutMs?: number;
+}
+
+/**
+ * 输入操作
+ */
+export interface TypeAction extends BaseAtomicAction {
+  type: "type";
+  ref: string;
+  text: string;
+  submit?: boolean;
+  slowly?: boolean;
+  timeoutMs?: number;
+}
+
+/**
+ * 按键操作
+ */
+export interface PressAction extends BaseAtomicAction {
+  type: "press";
+  key: string;
+  delayMs?: number;
+}
+
+/**
+ * 悬停操作
+ */
+export interface HoverAction extends BaseAtomicAction {
+  type: "hover";
+  ref: string;
+  timeoutMs?: number;
+}
+
+/**
+ * 截图操作
+ */
+export interface ScreenshotAction extends BaseAtomicAction {
+  type: "screenshot";
+  screenshotPath?: string;
+}
+
+/**
+ * Evaluate 操作（scroll, wait, select, focus, drag, upload）
+ */
+export type EvaluateActionType =
+  | "scroll"
+  | "wait"
+  | "select"
+  | "focus"
+  | "drag"
+  | "upload";
+
+export interface EvaluateAction extends BaseAtomicAction {
+  type: EvaluateActionType;
+  evaluate: EvaluateParams;
+  delay?: number;  // 等待时间（毫秒）
+}
+
+/**
+ * 复合操作
+ */
+export interface CompositeAction extends BaseAtomicAction {
+  type: "composite";
+  actions: AtomicAction[];
+  atomic?: boolean;
+  rollback?: AtomicAction[];
+  label?: string;
+}
+
+/**
+ * 原子化操作联合类型
+ */
+export type AtomicAction =
+  | NavigateAction
+  | ClickAction
+  | TypeAction
+  | PressAction
+  | HoverAction
+  | ScreenshotAction
+  | EvaluateAction
+  | CompositeAction;
+
+/**
+ * 操作类型（包含复合操作）
+ */
+export type Action = AtomicAction;
+
+// ============================================================================
+// 缓存条目
+// ============================================================================
+
+/**
+ * 缓存层级
+ */
+export type CacheLevel = "L3" | "L2" | "L1";
+
+/**
+ * 页面类型
+ */
+export type PageType = "static" | "dynamic" | "mixed";
+
+/**
+ * 缓存来源
+ */
+export type CacheSource = "llm" | "manual" | "learned";
+
+/**
+ * DOM hash 特征
+ */
+export interface DOMHashFeatures {
+  formCount: number;
+  buttonCount: number;
+  linkCount: number;
+  scriptCount: number;
+  headingCount: number;
+}
+
+/**
+ * 页面变化检测结果
+ */
+export interface PageChangeDetection {
+  hasChanged: boolean;
+  changeType: "structure" | "content" | "none";
+  confidence: number;
+  domHash: string;
+  structureHash?: string;
+  lastCheckedAt: number;
+  details?: string;
+}
+
+/**
+ * 页面操作缓存条目
+ */
+export interface PageActionCacheEntry {
+  // === 标识信息 ===
+  key: string;
+  url: string;
+  viewport: PageViewport;
+
+  // === 缓存层级 ===
+  cacheLevel: CacheLevel;
+
+  // === 场景信息 ===
+  scenario: string;
+  description: string;
+  variables?: VariableMap;
+  urlPattern?: string;
+
+  // === 操作序列 ===
+  actions: AtomicAction[];
+  screenshotPath?: string;
+
+  // === 时间信息 ===
+  createdAt: number;
+  lastAccessTime: number;
+  accessCount: number;
+
+  // === 失效控制 ===
+  expiresAt: number;
+  pageChangeDetection: PageChangeDetection;
+
+  // === 元数据 ===
+  source: CacheSource;
+  version?: number;
+  tags?: string[];
+  variant?: string;
+
+  // === 执行统计 ===
+  successCount: number;
+  failCount: number;
+  avgExecutionTime: number;
+
+  // === 页面类型（用于失效策略） ===
+  pageType?: PageType;
+}
+
+// ============================================================================
+// 场景识别
+// ============================================================================
+
+/**
+ * 场景识别规则
+ */
+export interface ScenarioRule {
+  scenario: string;
+  keywords: string[];
+  urlPatterns: string[];
+  priority: number;
+  cacheLevel: CacheLevel;
+  confidence: number;
+}
+
+/**
+ * 场景匹配结果
+ */
+export interface ScenarioMatch {
+  scenario: string;
+  confidence: number;
+  method: "keyword" | "url" | "llm" | "history" | "learned";
+  matchedPattern?: string;
+}
+
+// ============================================================================
+// 缓存统计
+// ============================================================================
+
+/**
+ * 缓存统计
+ */
+export interface CacheStats {
+  // 基本统计
+  totalEntries: number;
+  totalHits: number;
+  totalMisses: number;
+  hitRate: number;
+
+  // 按层级统计
+  l3Hits: number;
+  l2Hits: number;
+  l1Hits: number;
+
+  // 场景识别统计
+  scenarioMatches: number;
+  llmClassifications: number;
+  learnedAssociations: number;
+
+  // 效果统计
+  savedTokens: number;
+  savedTime: number;
+  avgExecutionTime: number;
+
+  // 用户反馈统计
+  userConfirmations: number;
+  userForcedRefreshes: number;
+  cacheErrors: number;
+}
+
+// ============================================================================
+// 缓存存储
+// ============================================================================
+
+/**
+ * 页面操作缓存存储
+ */
+export interface PageActionCacheStore {
+  version: number;
+  entries: Record<string, PageActionCacheEntry>;
+  scenarios: Map<string, ScenarioMatch>;
+  stats: CacheStats;
+}
+
+// ============================================================================
+// 配置
+// ============================================================================
+
+/**
+ * 缓存配置
+ */
+export interface CacheConfig {
+  // === 全局开关 ===
+  enabled: boolean;
+  autoUseCache: boolean;
+
+  // === 场景识别 ===
+  scenarioRecognitionEnabled: boolean;
+  llmClassificationThreshold: number;
+
+  // === 缓存策略 ===
+  cacheLevelStrategy: "auto" | "l3-only" | "l2-only" | "l1-only";
+  defaultCacheLevel: string;
+
+  // === 缓存失效 ===
+  pageChangeDetectionEnabled: boolean;
+  changeInvalidationThreshold: number;
+  invalidationStrategy: "soft" | "hard";
+  maxVersionsPerEntry: number;
+
+  // === 变量系统 ===
+  variableExtractionEnabled: boolean;
+  allowUserConfirmVariables: boolean;
+
+  // === 安全 ===
+  encryptSensitiveCache: boolean;
+  accessControlEnabled: boolean;
+  allowedUserIds: string[];
+  logSanitizationEnabled: boolean;
+
+  // === 用户体验 ===
+  showCacheStatusToUser: boolean;
+  enableUserCacheConfirmation: boolean;
+  enableUserForcedRefresh: boolean;
+  enableUserCacheErrorReport: boolean;
+
+  // === 统计 ===
+  trackExecutionStats: boolean;
+  statsUpdateInterval: number;
+}
+
+// ============================================================================
+// 执行结果
+// ============================================================================
+
+/**
+ * 操作执行结果
+ */
+export interface ExecutionResult {
+  action: string;
+  success: boolean;
+  error?: string;
+  duration: number;
+}
+
+// ============================================================================
+// Playwright 客户端接口
+// ============================================================================
+
+/**
+ * Playwright 客户端接口
+ */
+export interface PwAi {
+  navigateViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    url: string;
+    waitUntil?: "load" | "domcontentloaded" | "networkidle";
+    timeout?: number;
+  }): Promise<void>;
+
+  clickViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    ref: string;
+    doubleClick?: boolean;
+    button?: "left" | "right" | "middle";
+    modifiers?: Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift">;
+    timeoutMs?: number;
+  }): Promise<void>;
+
+  typeViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    ref: string;
+    text: string;
+    submit?: boolean;
+    slowly?: boolean;
+    timeoutMs?: number;
+  }): Promise<void>;
+
+  pressKeyViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    key: string;
+    delayMs?: number;
+  }): Promise<void>;
+
+  hoverViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    ref: string;
+    timeoutMs?: number;
+  }): Promise<void>;
+
+  screenshotViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+  }): Promise<string>;
+
+  evaluateViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    code: string;
+    args?: any[];
+  }): Promise<any>;
+}