page-action-cache 1.0.1

package/src/security-policy.ts

@@ -0,0 +1,268 @@
+/**
+ * Security Policy
+ * 安全策略 - 敏感变量检测、加密存储、访问控制
+ */
+
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import type { AtomicAction, PageActionCacheEntry, VariableMap } from "./types.js";
+
+// ============================================================================
+// 配置
+// ============================================================================
+
+const SENSITIVE_FIELDS = new Set([
+  "password",
+  "pwd",
+  "token",
+  "secret",
+  "key",
+  "code",
+  "otp",
+]);
+
+const ENCRYPTION_KEY = "default-key-change-in-production"; // 生产环境应从配置读取
+const ENCRYPTION_ALGORITHM = "aes-256-gcm";
+
+// ============================================================================
+// Security Policy 类
+// ============================================================================
+
+/**
+ * 安全策略
+ */
+export class SecurityPolicy {
+  private allowedUserIds: Set<string>;
+
+  constructor(allowedUserIds: string[] = []) {
+    this.allowedUserIds = new Set(allowedUserIds);
+  }
+
+  // -------------------------------------------------------------------------
+  // 敏感字段检测
+  // -------------------------------------------------------------------------
+
+  /**
+   * 检查操作是否包含敏感变量
+   */
+  isSensitiveAction(action: AtomicAction): boolean {
+    if (!action.variable) {
+      return false;
+    }
+
+    return SENSITIVE_FIELDS.has(action.variable.toLowerCase());
+  }
+
+  /**
+   * 检查变量映射是否包含敏感数据
+   */
+  hasSensitiveData(variables: VariableMap): boolean {
+    for (const key of Object.keys(variables)) {
+      if (SENSITIVE_FIELDS.has(key.toLowerCase())) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * 获取敏感字段列表
+   */
+  getSensitiveFields(): string[] {
+    return Array.from(SENSITIVE_FIELDS);
+  }
+
+  // -------------------------------------------------------------------------
+  // 加密/解密
+  // -------------------------------------------------------------------------
+
+  /**
+   * 加密数据
+   */
+  encrypt(data: string): string {
+    try {
+      const iv = randomBytes(16);
+      const cipher = createCipheriv(
+        ENCRYPTION_ALGORITHM,
+        Buffer.from(ENCRYPTION_KEY),
+        iv
+      );
+
+      let encrypted = cipher.update(data, "utf8", "hex");
+      encrypted += cipher.final("hex");
+      const authTag = cipher.getAuthTag();
+
+      return `${iv.toString("hex")}:${authTag.toString("hex")}:${encrypted}`;
+    } catch (error) {
+      console.error("[SecurityPolicy] Encryption failed:", error);
+      return data; // 失败时返回原数据
+    }
+  }
+
+  /**
+   * 解密数据
+   */
+  decrypt(encrypted: string): string {
+    try {
+      const [ivHex, authTagHex, data] = encrypted.split(":");
+
+      if (!ivHex || !authTagHex || !data) {
+        return encrypted; // 格式错误，返回原数据
+      }
+
+      const iv = Buffer.from(ivHex, "hex");
+      const authTag = Buffer.from(authTagHex, "hex");
+      const decipher = createDecipheriv(
+        ENCRYPTION_ALGORITHM,
+        Buffer.from(ENCRYPTION_KEY),
+        iv
+      );
+
+      decipher.setAuthTag(authTag);
+
+      let decrypted = decipher.update(data, "hex", "utf8");
+      decrypted += decipher.final("utf8");
+
+      return decrypted;
+    } catch (error) {
+      console.error("[SecurityPolicy] Decryption failed:", error);
+      return encrypted; // 失败时返回原数据
+    }
+  }
+
+  /**
+   * 加密缓存条目中的敏感变量
+   */
+  encryptCacheEntry(entry: PageActionCacheEntry): PageActionCacheEntry {
+    if (!entry.variables) {
+      return entry;
+    }
+
+    const encrypted = { ...entry };
+    encrypted.variables = {} as VariableMap;
+
+    for (const [key, value] of Object.entries(entry.variables)) {
+      if (SENSITIVE_FIELDS.has(key.toLowerCase()) && typeof value === "string") {
+        // 敏感字段加密
+        (encrypted.variables as any)[key] = this.encrypt(value);
+      } else {
+        (encrypted.variables as any)[key] = value;
+      }
+    }
+
+    return encrypted;
+  }
+
+  /**
+   * 解密缓存条目中的敏感变量
+   */
+  decryptCacheEntry(entry: PageActionCacheEntry): PageActionCacheEntry {
+    if (!entry.variables) {
+      return entry;
+    }
+
+    const decrypted = { ...entry };
+    decrypted.variables = {} as VariableMap;
+
+    for (const [key, value] of Object.entries(entry.variables)) {
+      if (SENSITIVE_FIELDS.has(key.toLowerCase()) && typeof value === "string") {
+        // 敏感字段解密
+        (decrypted.variables as any)[key] = this.decrypt(value);
+      } else {
+        (decrypted.variables as any)[key] = value;
+      }
+    }
+
+    return decrypted;
+  }
+
+  // -------------------------------------------------------------------------
+  // 访问控制
+  // -------------------------------------------------------------------------
+
+  /**
+   * 检查是否允许访问
+   */
+  canAccessCache(userId?: string): boolean {
+    if (this.allowedUserIds.size === 0) {
+      return true; // 没有限制，允许所有用户
+    }
+
+    if (!userId) {
+      return false; // 没有用户 ID，拒绝访问
+    }
+
+    return this.allowedUserIds.has(userId);
+  }
+
+  /**
+   * 添加允许的用户 ID
+   */
+  addAllowedUserId(userId: string): void {
+    this.allowedUserIds.add(userId);
+  }
+
+  /**
+   * 移除允许的用户 ID
+   */
+  removeAllowedUserId(userId: string): void {
+    this.allowedUserIds.delete(userId);
+  }
+
+  // -------------------------------------------------------------------------
+  // 日志脱敏
+  // -------------------------------------------------------------------------
+
+  /**
+   * 脱敏处理（用于日志输出）
+   */
+  sanitizeForLogging(data: any): any {
+    if (typeof data !== "object" || data === null) {
+      return data;
+    }
+
+    const sanitized: any = Array.isArray(data) ? [] : {};
+
+    for (const [key, value] of Object.entries(data)) {
+      if (SENSITIVE_FIELDS.has(key.toLowerCase())) {
+        // 敏感字段脱敏
+        sanitized[key] = "***REDACTED***";
+      } else if (typeof value === "object") {
+        // 递归处理嵌套对象
+        sanitized[key] = this.sanitizeForLogging(value);
+      } else {
+        sanitized[key] = value;
+      }
+    }
+
+    return sanitized;
+  }
+
+  /**
+   * 脱敏处理操作列表
+   */
+  sanitizeActions(actions: AtomicAction[]): AtomicAction[] {
+    return actions.map((action) => {
+      const sanitized = { ...action };
+
+      // 脱敏操作中的敏感文本
+      if (sanitized.type === "type" && this.isSensitiveAction(action)) {
+        (sanitized as any).text = "***REDACTED***";
+      }
+
+      return sanitized;
+    });
+  }
+}
+
+// ============================================================================
+// 单例
+// ============================================================================
+
+let securityPolicyInstance: SecurityPolicy | null = null;
+
+export function getSecurityPolicy(allowedUserIds?: string[]): SecurityPolicy {
+  if (!securityPolicyInstance) {
+    securityPolicyInstance = new SecurityPolicy(allowedUserIds);
+  }
+  return securityPolicyInstance;
+}

package/src/tools.ts

@@ -0,0 +1,437 @@
+/**
+ * Custom Tools
+ * 自定义工具 - 提供给 LLM 使用的工具接口
+ */
+
+import type {
+  VariableMap,
+  PageViewport,
+} from "./types.js";
+import { getCacheStore } from "./cache-store.js";
+import { getScenarioRecognizer } from "./scenario-recognizer.js";
+import { getUXEnhancer } from "./ux-enhancer.js";
+import { getActionsExecutor } from "./actions-executor.js";
+
+// ============================================================================
+// 工具定义
+// ============================================================================
+
+/**
+ * execute_cached 工具 - 执行缓存的页面操作序列
+ */
+export function createExecuteCachedTool() {
+  return {
+    name: "execute_cached",
+    label: "Execute Cached Actions",
+    description:
+      "执行缓存的页面操作序列，跳过 LLM 分析。大幅降低 token 消耗和操作延迟。",
+    parameters: {
+      type: "object",
+      properties: {
+        cacheKey: {
+          type: "string",
+          description: "缓存键（从 cache_info 中获取）",
+        },
+        fromIndex: {
+          type: "number",
+          description: "从第几个操作开始执行（默认 0）",
+        },
+        toIndex: {
+          type: "number",
+          description: "执行到第几个操作（不指定则执行全部）",
+        },
+        dryRun: {
+          type: "boolean",
+          description: "试运行模式，不实际执行",
+        },
+        force: {
+          type: "boolean",
+          description: "强制执行（忽略页面变化检测）",
+        },
+      },
+    },
+    required: ["cacheKey"],
+  };
+}
+
+/**
+ * execute_cached 工具执行函数
+ */
+export async function executeCached(_toolCallId: string, args: any) {
+  const {
+    cacheKey,
+    fromIndex,
+    toIndex,
+    dryRun = false,
+    force = false,
+  } = args;
+
+  const cacheStore = getCacheStore();
+  const uxEnhancer = getUXEnhancer();
+
+  // 获取缓存条目
+  const entry = cacheStore.listEntries().find((e) => e.key === cacheKey);
+
+  if (!entry) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: "缓存不存在或已过期。请重新分析页面。",
+        },
+      ],
+    };
+  }
+
+  // 检查页面变化（强制模式跳过）
+  if (!force && !dryRun) {
+    // TODO: 实际获取页面 HTML 进行检测
+    // const html = await fetchPageHTML(entry.url, entry.viewport);
+    // const changeResult = await cacheInvalidator.detectPageChange(html, entry.url, entry.viewport, entry);
+
+    // 简化处理：暂时跳过检测
+    console.log(`[execute_cached] Skipping page change detection for ${entry.url}`);
+  }
+
+  // 解析变量
+  let variables: VariableMap = {};
+  if (entry.variables) {
+    variables = entry.variables;
+  }
+
+  // 获取执行器
+  const executor = getActionsExecutor();
+
+  if (dryRun) {
+    // 试运行模式，只返回不执行
+    const actionsToExecute = entry.actions.slice(
+      fromIndex || 0,
+      toIndex !== undefined ? toIndex + 1 : undefined
+    );
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: uxEnhancer.generateDryRunResult(actionsToExecute),
+        },
+      ],
+    };
+  }
+
+  // 逐个执行操作
+  const results = await executor.executeBatch(entry.actions, variables, {
+    fromIndex,
+    toIndex,
+    atomic: true, // 原子执行
+  });
+
+  // 更新缓存统计
+  cacheStore.updateExecutionStats(cacheKey, results);
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: uxEnhancer.generateExecutionReport(results, force),
+      },
+    ],
+  };
+}
+
+/**
+ * cache_stats 工具 - 查看缓存统计
+ */
+export function createCacheStatsTool() {
+  return {
+    name: "cache_stats",
+    label: "Cache Statistics",
+    description: "查看页面操作缓存的统计信息，包括命中率、节省的 token 等。",
+    parameters: {
+      type: "object",
+      properties: {},
+    },
+  };
+}
+
+/**
+ * cache_stats 工具执行函数
+ */
+export async function cacheStats(_toolCallId: string, _args: any) {
+  const uxEnhancer = getUXEnhancer();
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: uxEnhancer.generateStatsReport(),
+      },
+    ],
+  };
+}
+
+/**
+ * cache_list 工具 - 列出所有缓存
+ */
+export function createCacheListTool() {
+  return {
+    name: "cache_list",
+    label: "List Cache Entries",
+    description: "列出所有页面操作缓存条目，包括场景、URL、访问次数等。",
+    parameters: {
+      type: "object",
+      properties: {
+        limit: {
+          type: "number",
+          description: "最多返回的条目数（默认 20）",
+        },
+        filterScenario: {
+          type: "string",
+          description: "按场景过滤（如 login, checkout）",
+        },
+      },
+    },
+  };
+}
+
+/**
+ * cache_list 工具执行函数
+ */
+export async function cacheList(_toolCallId: string, args: any) {
+  const { limit = 20, filterScenario } = args;
+  const cacheStore = getCacheStore();
+
+  let entries = cacheStore.listEntries();
+
+  // 过滤场景
+  if (filterScenario) {
+    entries = entries.filter((e) => e.scenario === filterScenario);
+  }
+
+  // 限制数量
+  entries = entries.slice(0, limit);
+
+  let text = `\n【缓存条目列表】（共 ${entries.length} 条）\n\n`;
+
+  entries.forEach((entry, i) => {
+    text += `${i + 1}. ${entry.scenario} (${entry.cacheLevel})\n`;
+    text += `   URL: ${entry.url}\n`;
+    text += `   访问次数: ${entry.accessCount}\n`;
+    text += `   成功率: ${((entry.successCount / (entry.successCount + entry.failCount || 1)) * 100).toFixed(0)}%\n`;
+    text += `   最后访问: ${new Date(entry.lastAccessTime).toLocaleString()}\n\n`;
+  });
+
+  return {
+    content: [
+      {
+        type: "text",
+        text,
+      },
+    ],
+  };
+}
+
+/**
+ * cache_clear 工具 - 清空缓存
+ */
+export function createCacheClearTool() {
+  return {
+    name: "cache_clear",
+    label: "Clear Cache",
+    description: "清空所有页面操作缓存。慎用！",
+    parameters: {
+      type: "object",
+      properties: {
+        scenario: {
+          type: "string",
+          description: "只清空指定场景的缓存（可选）",
+        },
+      },
+    },
+  };
+}
+
+/**
+ * cache_clear 工具执行函数
+ */
+export async function cacheClear(_toolCallId: string, args: any) {
+  const { scenario } = args;
+  const cacheStore = getCacheStore();
+
+  if (scenario) {
+    // 清空指定场景
+    let count = 0;
+    const entries = cacheStore.listEntries();
+    for (const entry of entries) {
+      if (entry.scenario === scenario) {
+        cacheStore.delete(entry.url, entry.viewport);
+        count++;
+      }
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: `已清空场景 "${scenario}" 的 ${count} 条缓存。`,
+        },
+      ],
+    };
+  } else {
+    // 清空所有缓存
+    cacheStore.clear();
+    return {
+      content: [
+        {
+          type: "text",
+          text: "已清空所有缓存。",
+        },
+      ],
+    };
+  }
+}
+
+/**
+ * scenario_list 工具 - 列出所有场景
+ */
+export function createScenarioListTool() {
+  return {
+    name: "scenario_list",
+    label: "List Scenarios",
+    description: "列出所有支持的缓存场景及其匹配规则。",
+    parameters: {
+      type: "object",
+      properties: {},
+    },
+  };
+}
+
+/**
+ * scenario_list 工具执行函数
+ */
+export async function scenarioList(_toolCallId: string, _args: any) {
+  const scenarioRecognizer = getScenarioRecognizer();
+  const rules = scenarioRecognizer.getRules();
+
+  let text = "\n【支持的缓存场景】\n\n";
+
+  rules.forEach((rule, i) => {
+    text += `${i + 1}. ${rule.scenario}\n`;
+    text += `   关键词: ${rule.keywords.join(", ")}\n`;
+    text += `   URL 模式: ${rule.urlPatterns.join(", ") || "无"}\n`;
+    text += `   缓存层级: ${rule.cacheLevel}\n`;
+    text += `   置信度: ${rule.confidence}\n\n`;
+  });
+
+  return {
+    content: [
+      {
+        type: "text",
+        text,
+      },
+    ],
+  };
+}
+
+/**
+ * force_refresh 工具 - 强制刷新指定缓存
+ */
+export function createForceRefreshTool() {
+  return {
+    name: "force_refresh",
+    label: "Force Refresh Cache",
+    description: "强制刷新指定页面的缓存，下次访问将重新分析。",
+    parameters: {
+      type: "object",
+      properties: {
+        url: {
+          type: "string",
+          description: "页面 URL",
+        },
+        viewport: {
+          type: "object",
+          description: "视口尺寸（可选）",
+          properties: {
+            width: { type: "number" },
+            height: { type: "number" },
+          },
+        },
+      },
+    },
+    required: ["url"],
+  };
+}
+
+/**
+ * force_refresh 工具执行函数
+ */
+export async function forceRefresh(_toolCallId: string, args: any) {
+  const { url, viewport } = args;
+  const cacheStore = getCacheStore();
+
+  const vp: PageViewport = viewport || { width: 1920, height: 1080 };
+
+  const deleted = cacheStore.delete(url, vp);
+
+  if (deleted) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `已强制刷新缓存：${url}`,
+        },
+      ],
+    };
+  } else {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `未找到缓存：${url}`,
+        },
+      ],
+    };
+  }
+}
+
+// ============================================================================
+// 工具注册表
+// ============================================================================
+
+export const CACHE_TOOLS = [
+  {
+    definition: createExecuteCachedTool(),
+    execute: executeCached,
+  },
+  {
+    definition: createCacheStatsTool(),
+    execute: cacheStats,
+  },
+  {
+    definition: createCacheListTool(),
+    execute: cacheList,
+  },
+  {
+    definition: createCacheClearTool(),
+    execute: cacheClear,
+  },
+  {
+    definition: createScenarioListTool(),
+    execute: scenarioList,
+  },
+  {
+    definition: createForceRefreshTool(),
+    execute: forceRefresh,
+  },
+];
+
+/**
+ * 获取所有工具定义
+ */
+export function getToolDefinitions() {
+  return CACHE_TOOLS.map((tool) => ({
+    name: tool.definition.name,
+    label: tool.definition.label,
+    description: tool.definition.description,
+    parameters: tool.definition.parameters,
+  }));
+}