extract-page-data

提取页面数据

从任意网页提取结构化数据，用于设计分析、页面重建或内容审核。脚本会自动安装依赖项——只需提供网址即可。

适用场景

• 用户分享网页 URL 并想要截取页面
• 用户想从页面提取设计令牌、CSS 主题或配色方案
• 用户想将页面内容转换为 Markdown 文本
• 用户想了解页面上有哪些链接、按钮和交互元素
• 用户要求导出或分析任意网页的结构
• 用户想截取页面上的特定元素（使用 --selector）

请勿用于 Axure 原型——请改用 extract-axure-data。

快速开始

从相对于此技能目录的 scripts/extract.mjs 运行提取脚本。

# Full page screenshot
node scripts/extract.mjs https://example.com --screenshot

# Screenshot of a specific element
node scripts/extract.mjs https://example.com --screenshot --selector "#hero"

# Extract design tokens (colors, typography, spacing, etc.)
node scripts/extract.mjs https://example.com --theme

# Extract page content as Markdown
node scripts/extract.mjs https://example.com --markdown

# Collect all links and interactive elements
node scripts/extract.mjs https://example.com --links

# Extract everything
node scripts/extract.mjs https://example.com --all

# Export full data pack (screenshot + theme + markdown + links as zip)
node scripts/extract.mjs https://example.com --pack

首次运行时会自动将 Playwright + Chromium 安装到 ~/.cache/page-extractor/。这需要 1-2 分钟，且只会进行一次。

参数

标志	功能	默认值
<url>	网页 URL（必需）	—
--screenshot	截取页面	关闭
--theme	提取设计令牌	关闭
--markdown	将页面转换为 Markdown	关闭
--links	收集交互元素	关闭
--pack	导出完整数据包（zip）	关闭
--all	运行所有提取任务	关闭
--selector SEL	用于限定提取范围的 CSS 选择器	整个页面
-o DIR	输出目录	./page-export
--viewport WxH	视口大小	1280x720
--wait MS	页面加载后的额外等待时间（ms）	0
--scroll	滚动页面以触发延迟加载的内容	关闭
--scroll-step PX	每次滚动的像素数	800
--scroll-delay MS	两次滚动之间的延迟（ms）	200
--no-headless	显示浏览器窗口	无头模式
--connect-cdp URL	连接到正在运行的 Chrome（用于身份验证）	—
--format FMT	截图格式：png 或 jpeg	png
--verbose	详细日志	关闭

输出结构

page-export/
├── screenshot.png       # Page or element screenshot    (--screenshot)
├── theme.json           # Design tokens                 (--theme)
├── content.md           # Page text as Markdown          (--markdown)
├── links.json           # Links and interactive elements (--links)
└── page-data.zip        # Full data pack                 (--pack)
    ├── screenshot.png
    ├── theme.json
    ├── content.md
    ├── links.json
    └── meta.json        # Page metadata (title, url, viewport)

选择器支持

所有提取模式都支持使用 --selector 将范围限定到特定元素：

# Screenshot only the header
node scripts/extract.mjs https://example.com --screenshot --selector "header"

# Extract design tokens from a card component
node scripts/extract.mjs https://example.com --theme --selector ".card"

# Get Markdown from the main content area
node scripts/extract.mjs https://example.com --markdown --selector "main"

# Collect links from the navigation
node scripts/extract.mjs https://example.com --links --selector "nav"

需要身份验证的页面

有些页面需要登录。可使用以下两种方法：

连接到现有 Chrome 会话（推荐——重用 Cookie）：

macOS：

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

Windows：

start chrome --remote-debugging-port=9222

然后在该 Chrome 窗口中登录，再运行：

node scripts/extract.mjs https://example.com --all --connect-cdp http://localhost:9222

显示浏览器窗口（提取期间手动登录）：

node scripts/extract.mjs https://example.com --all --no-headless

依赖项安装

脚本会在首次运行时自动安装依赖项。如果安装失败：

# Manual install
cd ~/.cache/page-extractor
npm install playwright
npx playwright install chromium

# If Chromium download is slow (e.g. behind GFW):
PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright npx playwright install chromium

输出数据格式

theme.json

从计算后的 CSS 样式中提取的设计系统令牌：

{
  "colors": {
    "background": [{"value": "rgb(255,255,255)", "count": 42, "tags": ["div"]}],
    "text": [{"value": "rgb(51,51,51)", "count": 28, "tags": ["p","span"]}],
    "border": [{"value": "rgb(221,221,221)", "count": 12}]
  },
  "typography": {
    "families": [{"value": "\"Inter\", sans-serif", "count": 56}],
    "textStyles": [{"size": "14px", "lineHeight": "22px", "weight": "400", "count": 20}]
  },
  "spacing": [{"value": "16px", "count": 15}],
  "radius": [{"value": "4px", "count": 8}],
  "lineWidth": [{"value": "1px", "count": 10}],
  "shadow": {
    "box": [{"value": "0 2px 8px rgba(0,0,0,0.1)", "count": 5}],
    "text": []
  },
  "transitions": [{"value": "all 0.2s ease", "count": 38, "tags": ["button","a"]}],
  "animations": [{"value": "fadeIn|0.3s|ease", "count": 5, "tags": ["div"]}],
  "cssVariables": {
    "--color-primary": "#6366f1",
    "--radius": "0.5rem",
    "--font-sans": "Inter, sans-serif"
  },
  "assets": {
    "backgroundImages": [{"value": "url(hero.webp)", "count": 1, "tags": ["section"]}],
    "images": [
      {"src": "https://example.com/logo.svg", "alt": "Logo", "position": "static", "zIndex": "auto", "siblingImgCount": 1},
      {"src": "https://example.com/hero.png", "alt": "", "position": "absolute", "zIndex": "2", "siblingImgCount": 2}
    ],
    "svgCount": 12
  }
}

links.json

页面上的交互元素：

{
  "pageUrl": "https://example.com",
  "pageTitle": "Example",
  "links": [
    {"type": "a", "text": "Home", "href": "https://example.com/", "visible": true},
    {"type": "button", "text": "Sign Up", "visible": true},
    {"type": "form", "href": "https://example.com/login", "visible": true}
  ],
  "totalLinks": 3,
  "visibleLinks": 3
}

自定义

提取逻辑采用模块化设计。每项功能都位于 scripts/ 下独立的文件中：

文件	用途	自定义内容
lib/browser.mjs	Playwright 浏览器管理	更改浏览器启动参数、代理
lib/screenshot.mjs	截图	修改滚动行为、格式
lib/theme.mjs	设计令牌提取	调整令牌类别、数量上限
lib/markdown.mjs	HTML → Markdown	更改转换规则
lib/links.mjs	元素收集	添加新的元素类型
lib/pack.mjs	Zip 打包	更改数据包内容
inject/extract-theme.js	注入浏览器的主题逻辑	修改要提取的 CSS 属性
inject/extract-markdown.js	注入浏览器的 Markdown 逻辑	自定义文本提取
inject/extract-links.js	注入浏览器的链接逻辑	添加自定义选择器

主题克隆工作流

当用户想克隆或复刻网站的设计语言时，请按以下顺序运行：

步骤 1：提取所有数据

node extract.mjs <url> --all --scroll --viewport 1440x900

步骤 2：解读 theme.json

字段	对应项	CSS 变量
colors.background[0]	主表面	--color-bg
colors.text[0]	正文	--color-text
colors.text[1]	强调色 / 品牌色	--color-primary
typography.families[0]	主字体	Google Fonts 导入
spacing（前 5 项）	间距比例	--spacing-1 …
radius[0]	默认圆角	--radius-base
transitions[0]	悬停时长	应用于 .card, a, button
cssVariables	设计令牌（如果存在 :root 变量）	直接使用变量名

步骤 3：生成 CSS 变量

:root {
  --color-bg:       <colors.background[0].value>;
  --color-text:     <colors.text[0].value>;
  --color-primary:  <colors.text[1].value>;
  --font-sans:      <typography.families[0].value>;
  --radius-base:    <radius[0].value>;
  --transition:     <transitions[0].value>;
}

如果 cssVariables 非空，优先使用其中的变量名——它们体现了原始设计系统的意图。

步骤 4：还原动画

• transitions[0].value → 在交互元素上应用为 transition: <value>
• animations → 按动画名称重建 @keyframes 块；应用于进入页面的元素

步骤 5：处理分层素材

在 assets.images 中，position: absolute 且 zIndex > 0 的图像属于叠加层。 使用父元素的 CSS position: relative 和叠加层的 position: absolute 进行还原。

使用 Playwright 查缺补漏

导出数据是尽力而为的快照，有时需要返回原始页面补充信息（例如悬停态样式、懒加载内容、动画效果等）。可使用 Playwright CLI 进行交互式补充采集。

# 打开页面并获取快照
playwright-cli open https://example.com
playwright-cli snapshot

# 交互后采集（如 hover 态）
playwright-cli hover e15
playwright-cli screenshot --filename=hover-state.png

# 获取元素属性
playwright-cli eval "el => getComputedStyle(el).backdropFilter" e5

playwright-cli close

完整命令参考：Playwright CLI 官方技能文档

何时需要 Playwright

场景	Playwright 的用途
截图模糊/不完整	对指定元素进行高分辨率截图
样式数据缺失	获取完整的 computedStyle
hover/focus/active 状态	触发交互后采集样式
懒加载内容	滚动触发后截图
动画/过渡效果	定时截图或录屏
响应式断点校验	设置 viewport 后截图

故障排除

问题	解决方法
截图为空白	页面需要时间渲染——添加 --wait 2000
缺少懒加载内容	使用 --scroll 触发懒加载
需要登录	使用 --connect-cdp（参见上文“已认证页面”）
Playwright 安装失败	手动安装，或设置 PLAYWRIGHT_DOWNLOAD_HOST
选择了错误的元素	先用浏览器 DevTools 检查选择器