page-analyzer 1.0.0 → 1.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 page-analyzer contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,430 @@
+# page-analyzer
+
+`page-analyzer` 是一个独立的网页分析模块，用于抓取网页、解析 DOM、提取交互元素，并结合 OpenAI 兼容的 LLM 接口生成页面区块与事件分析结果。
+
+它适合用于：
+
+- 分析页面上的链接、按钮、表单、输入框等可交互节点
+- 将页面 DOM 元素转换为结构化 CSV，便于后续分析
+- 基于视觉区块和上下文识别页面主要功能区
+- 通过 LLM 判断节点可能触发的事件类型
+- 为埋点设计、页面巡检、自动化测试或站点地图分析提供基础数据
+
+## 功能概览
+
+- 使用 Playwright 启动 headless Chromium 抓取真实页面内容
+- 自动滚动页面并等待高度稳定，尽量覆盖懒加载内容
+- 解析 HTML 中的重要元素，包括 `a`、`button`、`form`、`input`、`select`、`textarea`、标题、图片和导航区
+- 收集元素文本、链接、表单动作、ARIA 信息、上下文文本、CSS 选择器和视觉区块位置
+- 将交互元素导出为 CSV：`idx,blockIdx,tag,imageAlt,text,context,href`
+- 使用 OpenAI 兼容接口进行页面区块分析和事件类型识别
+- 支持紧凑输出或完整输出，便于在不同场景控制结果体积
+- 支持高级用法：直接传入已抓取的 HTML、blocks、elementGeometries 进行分析
+
+## 安装
+
+从 npm 安装：
+
+```bash
+npm install page-analyzer
+```
+
+如果在本仓库内开发：
+
+```bash
+npm install
+```
+
+Playwright 需要可用的 Chromium。如果运行时提示浏览器缺失，可以执行：
+
+```bash
+npx playwright install chromium
+```
+
+## 环境要求
+
+- Node.js 20.18.1 或更高版本
+- 可访问目标网页的网络环境
+- 一个兼容 OpenAI Chat Completions 格式的 LLM 接口
+
+## 快速开始
+
+```js
+import { analyzeUrl } from 'page-analyzer';
+
+const result = await analyzeUrl('https://example.com', {
+  llm: {
+    apiKey: process.env.LLM_API_KEY,
+    apiEndpoint: process.env.LLM_API_ENDPOINT,
+    model: process.env.LLM_MODEL
+  }
+});
+
+console.log(JSON.stringify(result, null, 2));
+```
+
+示例 `.env`：
+
+```bash
+LLM_API_KEY=your_api_key
+LLM_API_ENDPOINT=https://api.openai.com/v1/chat/completions
+LLM_MODEL=gpt-4o-mini
+```
+
+## 运行测试和示例
+
+本地测试不会调用真实网页或 LLM 接口：
+
+```bash
+npm test
+```
+
+如需手动分析真实页面，可以运行示例脚本。它会读取项目根目录下的 `.env`，分析指定 URL，并把结果写入 `result.json`。
+
+```bash
+npm run analyze -- https://example.com
+```
+
+注意：`npm run analyze` 依赖以下环境变量：
+
+- `LLM_API_KEY`
+- `LLM_API_ENDPOINT`
+- `LLM_MODEL`
+
+缺少这些变量时会抛出配置错误。
+
+## API
+
+### analyzeUrl(url, options)
+
+一站式分析入口。传入 URL 后，模块会自动完成页面抓取、HTML 解析、视觉区块提取、CSV 生成和 LLM 分析。
+
+```js
+import { analyzeUrl } from 'page-analyzer';
+
+const result = await analyzeUrl('https://example.com', {
+  llm: {
+    apiKey: 'sk-...',
+    apiEndpoint: 'https://api.openai.com/v1/chat/completions',
+    model: 'gpt-4o-mini',
+    temperature: 0,
+    maxTokens: 8000,
+    timeout: 600000,
+    maxRetries: 3
+  },
+  showEvents: true,
+  showBlockIdx: true,
+  fullPageScreenshot: true,
+  blockScreenshots: true,
+  waitForImagesLoaded: true,
+  knownEventTypes: ['click_link', 'submit_form'],
+  extractorConfig: {
+    viewportWidth: 1440,
+    viewportHeight: 900,
+    timeoutMs: 30000
+  },
+  parserConfig: {
+    contextLevel: 'full',
+    maxTextLength: 200
+  }
+});
+```
+
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `url` | `string` | 是 | 要分析的页面 URL |
+| `options.llm.apiKey` | `string` | 是 | LLM API key |
+| `options.llm.apiEndpoint` | `string` | 是 | OpenAI 兼容的 Chat Completions endpoint |
+| `options.llm.model` | `string` | 是 | 模型名称 |
+| `options.llm.temperature` | `number` | 否 | LLM 温度，默认 `0` |
+| `options.llm.maxTokens` | `number` | 否 | 最大输出 token 数 |
+| `options.llm.timeout` | `number` | 否 | 单次请求超时时间，默认 `600000` ms |
+| `options.llm.maxRetries` | `number` | 否 | LLM 请求重试次数，默认 `3` |
+| `options.llm.interactionLogger` | `Function` | 否 | LLM 交互日志回调 |
+| `options.knownEventTypes` | `string[]` | 否 | 已知事件类型，用于判断新增事件类型 |
+| `options.parserConfig` | `object` | 否 | HTML 解析配置 |
+| `options.extractorConfig` | `object` | 否 | Playwright 页面抓取配置 |
+| `options.showEvents` | `boolean` | 否 | 是否返回完整事件数组和元素明细 |
+| `options.showBlockIdx` | `boolean` | 否 | 是否返回 CSV 与区块索引相关字段 |
+| `options.fullPageScreenshot` | `boolean` | 否 | 是否保存整页截图到当前运行目录的 `snapshots/` 并返回文件路径 |
+| `options.blockScreenshots` | `boolean` | 否 | 是否在 LLM 合并区块后，保存每个逻辑区块截图到当前运行目录的 `snapshots/` 并返回文件路径 |
+| `options.waitForImagesLoaded` | `boolean` | 否 | 是否在提取区块、分析和截图前等待页面图片加载完成，默认 `false` |
+
+### analyzePageEvents(input)
+
+高级入口。适合你已经有 HTML、视觉区块或元素几何信息，不希望 `page-analyzer` 自己打开浏览器抓取页面的场景。
+
+```js
+import { analyzePageEvents } from 'page-analyzer';
+
+const result = await analyzePageEvents({
+  html: '<html><head><title>Demo</title></head><body><a href="/pricing">Pricing</a></body></html>',
+  url: 'https://example.com',
+  blocks: [],
+  elementGeometries: [],
+  llm: {
+    apiKey: process.env.LLM_API_KEY,
+    apiEndpoint: process.env.LLM_API_ENDPOINT,
+    model: process.env.LLM_MODEL
+  },
+  knownEventTypes: [],
+  parserConfig: {
+    contextLevel: 'lean'
+  },
+  showEvents: true,
+  showBlockIdx: true,
+  domain: 'example.com',
+  nodeId: 'example-root'
+});
+```
+
+主要输入：
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `html` | `string` | 是 | 原始 HTML |
+| `url` | `string` | 是 | 页面 URL，用于解析相对链接 |
+| `blocks` | `Array` | 否 | 视觉区块快照 |
+| `elementGeometries` | `Array` | 否 | 页面中交互元素的几何信息 |
+| `llm` | `object` | 是 | LLM 配置 |
+| `knownEventTypes` | `string[]` | 否 | 已知事件类型 |
+| `parserConfig` | `object` | 否 | HTML 解析配置 |
+| `showEvents` | `boolean` | 否 | 是否返回完整事件数组和元素明细 |
+| `showBlockIdx` | `boolean` | 否 | 是否返回 CSV 与区块索引相关字段 |
+| `domain` | `string` | 否 | 分析上下文中的站点域名 |
+| `nodeId` | `string` | 否 | 当前分析节点 ID |
+
+如果没有传入 `blocks`，模块会根据 CSV 行构造 fallback block，保证 LLM 分析流程仍然可以运行。
+
+## 输出结构
+
+默认输出会保留页面标题、解析指标和紧凑后的区块分析结果：
+
+```js
+{
+  title: 'Example Domain',
+  parseMetrics: {
+    parseMs: 12,
+    contextBuildMs: 5,
+    elementsCount: 10,
+    linksCount: 3,
+    heapUsedMB: 28.4,
+    contextLevel: 'full'
+  },
+  analysis: {
+    block_analysis: {
+      site_summary: '...',
+      blocks: [
+        {
+          blockName: '...',
+          blockDescription: '...',
+          blockSemantics: [],
+          blockCssPath: '...',
+          blockPosition: {}
+        }
+      ],
+      stats: {
+        total_blocks: 4
+      }
+    }
+  }
+}
+```
+
+启用 `showEvents: true` 后，输出会包含更多用于调试和下游处理的字段，例如：
+
+- `elements`：解析出的页面元素明细
+- `csvContent`：交互元素 CSV
+- `links`：页面链接列表
+- `analysis.events_by_node`：按节点输出的事件识别结果
+- `analysis.event_types_summary`：事件类型汇总
+- `analysis.new_event_types`：不在已知类型列表中的新增事件类型
+- `analysis.block_analysis.possible_event_types`：页面可能存在的事件类型
+
+启用 `showBlockIdx: true` 后，区块结果中会额外包含 `blockIdxs`、`blockSemanticGroups`、`rowCount` 等字段，并返回 `csvContent`。
+
+启用 `fullPageScreenshot: true` 后，返回结果会包含 `screenshots.fullPage`，值为整页截图文件路径。
+
+启用 `blockScreenshots: true` 后，模块会在 LLM 合并区块后再截图。返回结果会包含 `screenshots.blocks`，每项包含逻辑区块序号 `blockIdx` 和对应截图 `path`；区块分析结果中的每个 block 也会额外带上 `blockScreenshotPaths`，每个逻辑区块最多对应一张截图。无法通过 `blockCssPath` 截图的隐藏或空区块会被跳过。
+
+启用 `waitForImagesLoaded: true` 后，模块会先滚动页面触发懒加载，再等待当前 DOM 中的 `<img>` 完成加载或失败，之后再提取区块、分析和截图；等待时间受 `extractorConfig.timeoutMs` 控制。
+
+截图参数启用后的新增输出示例：
+
+```js
+{
+  screenshots: {
+    fullPage: '/path/to/page-analyzer/snapshots/example-com-20260507-095500-full-page.png',
+    blocks: [
+      {
+        blockIdx: 0,
+        path: '/path/to/page-analyzer/snapshots/example-com-20260507-095500-block-000.png'
+      }
+    ]
+  }
+}
+```
+
+## 配置项
+
+### extractorConfig
+
+`extractorConfig` 控制 Playwright 抓取和视觉区块提取行为。
+
+| 字段 | 默认值 | 说明 |
+| --- | --- | --- |
+| `timeoutMs` | `30000` | 页面导航、滚动和稳定等待超时时间 |
+| `viewportWidth` | `1440` | 浏览器视口宽度 |
+| `viewportHeight` | `900` | 浏览器视口高度 |
+| `minBlockHeight` | `40` | 最小区块高度 |
+| `minBlockWidthRatio` | `0.25` | 最小区块宽度占视口宽度比例 |
+| `blockMaxHeightRatio` | `1.5` | 最大区块高度占视口高度比例 |
+| `blockMaxDepth` | `15` | 区块提取最大 DOM 深度 |
+| `textPreviewMaxChars` | `1200` | 区块文本预览最大长度 |
+| `waitForImagesLoaded` | `false` | 是否在提取区块、分析和截图前等待页面图片加载完成 |
+
+### parserConfig
+
+`parserConfig` 控制 HTML 元素解析和上下文提取行为。
+
+| 字段 | 默认值 | 说明 |
+| --- | --- | --- |
+| `importantTags` | 内置标签列表 | 要提取的重要 DOM 标签 |
+| `maxTextLength` | `200` | 元素自身文本最大长度 |
+| `maxParentTextLength` | `100` | 父级文本最大长度 |
+| `maxAncestorDepth` | `5` | 祖先上下文最大深度 |
+| `maxNearbyTexts` | `5` | 附近文本最大数量 |
+| `contextLevel` | `full` | 上下文详细程度，可选 `full` 或 `lean` |
+
+## 高级组件
+
+除主 API 外，模块还导出了一些内部组件，方便按需组合：
+
+```js
+import {
+  HtmlParser,
+  PageExtractor,
+  CsvExporter,
+  OpenAiProvider,
+  BaseLlmProvider,
+  EventAnalyzer,
+  assignBlocksToElements
+} from 'page-analyzer';
+```
+
+这些组件可以用于自定义分析流水线，例如只抓页面、只解析 HTML、只生成 CSV，或接入自定义 LLM provider。
+
+## LLM 接口格式
+
+当前内置的 `OpenAiProvider` 会向 `apiEndpoint` 发送 OpenAI Chat Completions 风格请求：
+
+```json
+{
+  "model": "gpt-4o-mini",
+  "messages": [
+    {
+      "role": "user",
+      "content": "..."
+    }
+  ],
+  "temperature": 0
+}
+```
+
+响应中会读取：
+
+```js
+data.choices[0].message.content
+```
+
+因此，只要服务兼容这一请求和响应结构，就可以作为后端 LLM 使用。
+
+## 开发
+
+安装依赖：
+
+```bash
+npm install
+```
+
+运行本地测试：
+
+```bash
+npm test
+```
+
+生成 npm 发布包预览：
+
+```bash
+npm pack --dry-run
+```
+
+发布前检查：
+
+```bash
+npm publish --dry-run
+```
+
+## 项目结构
+
+```text
+page-analyzer/
+  index.js                         # 模块入口，导出主 API 和高级组件
+  page-extractor.js                # Playwright 页面抓取与视觉区块提取
+  html-parser.js                   # HTML 解析与元素上下文提取
+  csv-exporter.js                  # 交互元素 CSV 生成
+  extractors/                      # 区块映射、上下文提取、选择器构建
+  llm/
+    providers/                     # LLM provider
+    analyzers/event-analyzer/      # 页面区块和事件分析逻辑
+    analyzers/prompts/             # LLM prompt 模板
+    utils/                         # 事件 CSV 解析和元数据工具
+  models/                          # 上下文数据模型
+  utils/                           # 文本、URL、选择器工具
+  vendor/                          # 浏览器内区块提取脚本
+  scripts/analyze.js               # 手动真实页面分析脚本
+  test/smoke.test.js               # 本地 smoke test
+```
+
+## 常见问题
+
+### npm run analyze 报 LLM 配置缺失
+
+确认项目根目录存在 `.env`，并且包含：
+
+```bash
+LLM_API_KEY=your_api_key
+LLM_API_ENDPOINT=https://api.openai.com/v1/chat/completions
+LLM_MODEL=gpt-4o-mini
+```
+
+### Playwright 报浏览器不存在
+
+执行：
+
+```bash
+npx playwright install chromium
+```
+
+### 目标页面内容不完整
+
+可以适当调大：
+
+```js
+extractorConfig: {
+  timeoutMs: 60000,
+  viewportHeight: 1200
+}
+```
+
+模块会自动滚动到底部并等待页面高度稳定，但如果目标站点需要登录、验证码、复杂交互或服务端限流，仍然可能拿不到完整内容。
+
+### LLM 返回格式解析失败
+
+事件分析器期望 LLM 返回 CSV section。内部会尝试自动修复格式，但如果模型输出长期不稳定，可以换用更强的模型，或降低温度。
+
+## License
+
+MIT License. See [LICENSE](./LICENSE).