a27e3b8e43
Optimized the root .gitignore to exclude virtual environments, node modules, and temp folders to ensure clean and lightweight version tracking. Co-authored-by: Cursor <cursoragent@cursor.com>
273 lines
8.3 KiB
Markdown
273 lines
8.3 KiB
Markdown
# 网页数据导出包使用说明
|
||
|
||
本压缩包包含从网页提取的完整数据，用于 AI 辅助页面还原和设计分析。
|
||
|
||
## 📦 文件结构
|
||
|
||
```
|
||
├── README.md # 本说明文件
|
||
├── screenshot.png # 完整页面截图（系统 API 截取）
|
||
├── domlist.json # DOM 结构数据（TOON 格式）
|
||
├── stylePool.json # 样式池数据（TOON 格式）
|
||
├── theme.json # 设计令牌（可选）
|
||
├── content.md # 页面内容 Markdown（可选）
|
||
├── index.html # 参考：生成的 HTML 文件
|
||
├── style.css # 参考：生成的 CSS 文件
|
||
└── assets/
|
||
├── images/ # 图片资源
|
||
└── fonts/ # 字体资源
|
||
```
|
||
|
||
## 🎯 核心文件说明
|
||
|
||
### 1. screenshot.png
|
||
- **用途：** 页面完整截图，用于视觉参考
|
||
- **截取方式：** 使用 Chrome DevTools Protocol (CDP) 系统 API
|
||
- **特点：** 完整页面截图，包含滚动区域，无拼接痕迹
|
||
- **优先级：** ⭐⭐⭐⭐⭐ 最重要的视觉参考
|
||
|
||
### 2. domlist.json（TOON 格式）
|
||
- **用途：** DOM 节点结构映射
|
||
- **格式：**
|
||
```json
|
||
{
|
||
"nodes": {
|
||
"n1": {
|
||
"tag": "div",
|
||
"children": ["n2", "n3"],
|
||
"styleId": "style_1",
|
||
"width": "1200px",
|
||
"height": "800px",
|
||
"text": "文本内容",
|
||
"id": "元素ID",
|
||
"class": "CSS类名",
|
||
"label": "data-label",
|
||
"src": "图片路径"
|
||
}
|
||
},
|
||
"root": "n1"
|
||
}
|
||
```
|
||
- **说明：**
|
||
- `nodes`: 所有节点的映射表
|
||
- `root`: 根节点 ID
|
||
- `width/height`: 从样式中独立存放，精确尺寸
|
||
- `styleId`: 指向 stylePool.json 中的样式
|
||
|
||
### 3. stylePool.json（TOON 格式）
|
||
- **用途：** 去重后的样式池
|
||
- **格式：**
|
||
```json
|
||
{
|
||
"styles": {
|
||
"style_1": {
|
||
"tw": "flex items-center justify-between",
|
||
"custom": {
|
||
"borderRadius": "8px",
|
||
"boxShadow": "0 2px 8px rgba(0,0,0,0.1)"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
- **说明：**
|
||
- `tw`: Tailwind CSS 类名（已优化）
|
||
- `custom`: 无法用 Tailwind 表达的自定义样式
|
||
- 样式已去重，多个节点可共享同一 styleId
|
||
|
||
### 4. theme.json（可选）
|
||
- **用途：** 页面设计令牌（Top 10）
|
||
- **内容：** 颜色、字体、间距、圆角、阴影等
|
||
- **格式：**
|
||
```json
|
||
{
|
||
"colors": {
|
||
"background": [{"value": "#ffffff", "count": 15}],
|
||
"text": [{"value": "#333333", "count": 20}]
|
||
},
|
||
"typography": {
|
||
"families": ["Inter", "Arial"],
|
||
"textStyles": [{"size": "16px", "lineHeight": "1.5"}]
|
||
},
|
||
"spacing": ["8px", "16px", "24px"],
|
||
"radius": ["4px", "8px"],
|
||
"shadow": {
|
||
"box": ["0 2px 8px rgba(0,0,0,0.1)"]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5. content.md（可选）
|
||
- **用途：** 页面文本内容（Markdown 格式）
|
||
- **用途：** 快速理解页面信息结构和文案
|
||
|
||
### 6. index.html 和 style.css（仅供参考）
|
||
- **⚠️ 注意：** 这两个文件仅供参考，不是还原的必需文件
|
||
- **用途：**
|
||
- 快速预览页面效果
|
||
- 理解 DOM 结构和样式关系
|
||
- 验证数据的正确性
|
||
- **说明：**
|
||
- `index.html`: 使用 Tailwind CDN + 自定义样式
|
||
- `style.css`: 包含 @font-face 和自定义样式
|
||
- 可以直接在浏览器中打开查看效果
|
||
- **还原时：** 应该使用 `domlist.json` 和 `stylePool.json`，而不是直接使用这两个文件
|
||
|
||
## 🚀 快速还原指引（推荐）
|
||
|
||
**目标：** 快速生成页面视觉效果，节省 token
|
||
|
||
**数据源优先级：**
|
||
1. ⭐⭐⭐⭐⭐ `screenshot.png` - 视觉参考
|
||
2. ⭐⭐⭐⭐ `theme.json` - 设计令牌
|
||
3. ⭐⭐⭐ `content.md` - 内容结构
|
||
4. ⭐⭐ `index.html` - 参考实现（可选）
|
||
|
||
**操作步骤：**
|
||
|
||
1. **分析截图**
|
||
- 识别页面整体布局（header、main、footer）
|
||
- 识别主要视觉元素（导航、卡片、按钮等）
|
||
- 识别颜色、字体、间距等设计风格
|
||
|
||
2. **提取设计令牌**（从 theme.json）
|
||
- 颜色：背景色、文本色、边框色
|
||
- 字体：字体家族、字号、行高、粗细
|
||
- 间距：margin、padding、gap
|
||
- 其他：圆角、阴影、线宽
|
||
|
||
3. **生成 DOM 结构**
|
||
- 根据截图创建简化的 DOM 层级
|
||
- 不必严格按照 domlist.json
|
||
- 使用 theme.json 中的设计令牌
|
||
|
||
4. **添加资源**
|
||
- 图片：使用 `assets/images/` 中的资源
|
||
- 字体：使用 `assets/fonts/` 或系统字体
|
||
|
||
5. **微调样式**
|
||
- 对比截图调整布局和样式
|
||
- 确保视觉效果接近原页面
|
||
|
||
**优点：**
|
||
- ✅ 快速生成
|
||
- ✅ 节省 token
|
||
- ✅ 视觉效果好
|
||
|
||
## 🎨 精细还原指引（高保真）
|
||
|
||
**目标：** 高保真还原页面结构与样式
|
||
|
||
**数据源优先级：**
|
||
1. ⭐⭐⭐⭐⭐ `screenshot.png` - 视觉参考
|
||
2. ⭐⭐⭐⭐⭐ `domlist.json` - DOM 结构
|
||
3. ⭐⭐⭐⭐⭐ `stylePool.json` - 样式数据
|
||
4. ⭐⭐⭐⭐ `theme.json` - 设计令牌
|
||
5. ⭐⭐ `index.html` - 参考实现（可选）
|
||
|
||
**操作步骤：**
|
||
|
||
1. **分析截图**
|
||
- 页面整体布局、颜色分布、主要元素
|
||
|
||
2. **构建 DOM 树**（从 domlist.json）
|
||
- 按 `children` 严格构建节点层级
|
||
- 保留所有节点属性（id、class、label、src 等）
|
||
- 使用 `width` 和 `height` 设置精确尺寸
|
||
|
||
3. **应用样式**（从 stylePool.json）
|
||
- 每个节点通过 `styleId` 关联样式
|
||
- `tw` 字段：Tailwind CSS 类名
|
||
- `custom` 字段：自定义样式（CSS-in-JS 或 style 属性）
|
||
|
||
4. **添加资源**
|
||
- 图片：`assets/images/` 中的资源，保持原始尺寸
|
||
- 字体：`assets/fonts/` 中的 Web 字体，使用 @font-face
|
||
|
||
5. **微调细节**
|
||
- 对比截图调整节点尺寸、间距、字体、阴影
|
||
- 确保视觉效果高度还原
|
||
|
||
**优点：**
|
||
- ✅ 高保真还原
|
||
- ✅ 结构完整
|
||
- ✅ 样式精确
|
||
|
||
## 💡 使用建议
|
||
|
||
### 选择还原方式
|
||
|
||
- **快速原型：** 使用快速还原指引
|
||
- **生产环境：** 使用精细还原指引
|
||
- **AI Agent：** 使用渐进式还原指引（见下方 🧠 模式）
|
||
- **学习参考：** 打开 `index.html` 查看效果
|
||
|
||
### 注意事项
|
||
|
||
1. **截图优先：** 如果数据与截图冲突，以截图为准
|
||
2. **样式优化：** stylePool 中的样式已优化（Tailwind + 自定义）
|
||
3. **资源路径：** 图片和字体路径需要根据实际部署调整
|
||
4. **响应式：** 原始页面的响应式样式可能未完全保留
|
||
|
||
---
|
||
|
||
## 🧠 渐进式高精度还原（AI Agent 推荐）
|
||
|
||
使用查询脚本实现渐进式数据读取，避免 Context Window 溢出。
|
||
当离线数据不完整时，利用 Playwright 回溯原始页面补充采集。
|
||
|
||
**前置条件：** Node.js >= 18
|
||
|
||
**原始页面 URL：** `manifest.json` → `sourceUrl` 字段。
|
||
当数据不准确时，AI 可通过 Playwright 访问此 URL 获取实时信息。
|
||
|
||
### 渐进式读取
|
||
|
||
```bash
|
||
# Step 1 — 全局概览（~500 tokens）
|
||
node scripts/query-page-data.mjs <dir> summary
|
||
node scripts/query-page-data.mjs <dir> skeleton --depth=2
|
||
|
||
# Step 2 — 按 Section 深入
|
||
node scripts/query-page-data.mjs <dir> subtree n2 --depth=3
|
||
node scripts/query-page-data.mjs <dir> nodes n3,n4,n5 --fields=style,text,selector
|
||
|
||
# Step 3 — 条件反查
|
||
node scripts/query-page-data.mjs <dir> find --tag=button --interactive
|
||
node scripts/query-page-data.mjs <dir> find --text="登录"
|
||
```
|
||
|
||
### 在线回溯（按需）
|
||
|
||
当发现离线数据可疑时，可使用 Playwright（MCP 或 CLI）访问 `sourceUrl`：
|
||
- 每个节点文件 `flat/nodes/{id}.json` 包含 `selector` 字段
|
||
- 该 `selector` 可直接用于 `page.locator(selector)` 定位原始元素
|
||
- 截图、computedStyle、hover 态等均可按需获取
|
||
|
||
### 扁平化文件结构（full/interactive 模式）
|
||
|
||
```
|
||
flat/
|
||
├── skeleton.json # 极简骨架树（含 sourceUrl，< 5KB）
|
||
├── index.json # 反向索引（tag/role/interactive 分类）
|
||
├── nodes/ # 每个节点的完整数据（含 selector + bbox）
|
||
│ ├── n1.json
|
||
│ └── ...
|
||
└── styles/ # 每个样式的完整数据
|
||
├── style_1.json
|
||
└── ...
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 相关资源
|
||
|
||
- **TOON 格式：** https://github.com/toon-format/toon
|
||
- **Tailwind CSS：** https://tailwindcss.com/
|
||
- **Chrome Extension：** Axhub Make
|
||
|
||
---
|
||
|
||
**生成时间：** 2026-04-20T15:28:01.363Z
|
||
**版本：** 3.0（渐进式检索 + 在线回溯）
|