ApeMan1024/lanhu-design-to-html

Latest recorded source activity: July 7, 2026 at 16:25

SkillsMP catalog refreshed: November 12, 2026 at 12:52

skills collected: 1

GitHub stars: 6
GitHub forks: 1

Install with an AI assistant

Copy this prompt into the AI assistant you're using.

Follow https://skillsmp.com/skill-install/prompt.md to install Agent Skills from https://github.com/ApeMan1024/lanhu-design-to-html.

Repository README

Repository README source: README.md

Read the source README

Expand full README

# Lanhu Design to HTML > 从蓝湖设计稿链接自动获取设计数据、分析图层结构、提取元素样式，并还原为像素级 HTML 页面的通用 Skill，可在各类 Agent 中复用。 ## 简介 `lanhu-design-to-html` 是一个通用 Skill，用于将蓝湖（Lanhu）平台上的设计稿还原为 HTML 页面。它通过 `playwright-cli` 自动化浏览器操作，获取蓝湖页面的 Sketch JSON 设计数据，解析图层结构与样式，批量下载切图到本地，最终生成可独立运行、像素级还原设计稿的 HTML 文件。该 Skill 可在各种 Agent 中通用复用。 ### 核心能力 - 自动打开蓝湖设计稿并处理登录流程（支持 headless / headed 模式切换） - 拦截并解析蓝湖 Sketch JSON，提取所有图层、文本、形状、切图信息 - 批量下载切图到本地 `assets/images/` 目录，生成 URL 到本地路径的映射表 - 根据设计数据生成 HTML 页面，遵循"切图优先"原则实现像素级还原 - 支持多平台单位切换（iOS pt / Android dp / Web px / 微信小程序 rpx） - 本地 HTTP 服务器预览 + 截图对比验证 ## 目录结构 ``` lanhu-design-to-html/ ├── SKILL.md # Skill 主文件（Agent 加载入口） ├── README.md # 本文档 ├── scripts/ # 辅助脚本 │ ├── parse-design.js # Sketch JSON 解析器 │ ├── download-images.js # 切图批量下载器 │ └── generate-html.js # HTML 自动生成器 └── references/ # 详细参考文档 ├── lanhu-workflow.md # 蓝湖设计稿分析工作流 ├── design-data-parser.md # 设计数据解析指南（Sketch JSON 结构） └── html-implementation.md # HTML 实现指南（还原最佳实践） ``` ## 前置要求 | 依赖 | 说明 | 检查命令 | |------|------|---------| | `playwright-cli` | 浏览器自动化工具，用于操作蓝湖页面 | `npx --no-install playwright-cli --version` | | Node.js | 运行解析与下载脚本 | `node --version` | | Python（可选） | 启动本地 HTTP 服务器预览 HTML | `python --version` | ## 工作流程概览 ``` 蓝湖链接 → 打开浏览器 → 获取 Sketch JSON → 解析图层/样式 → 下载切图到本地 → 分析结构 → 生成 HTML → 验证效果 ``` ### 详细步骤 1. **打开蓝湖设计稿** — 以 `--persistent` 模式启动浏览器，导航到蓝湖链接，检测登录状态；未登录时自动切换 `--headed` 模式供用户手动登录 2. **获取 Sketch JSON** — 通过 `playwright-cli requests` 拦截蓝湖页面的 API 请求，定位并获取包含完整设计数据的 Sketch JSON 响应体 3. **解析设计数据** — 运行 `parse-design.js` 解析 Sketch JSON，提取图层树、文本样式、形状属性、切图 URL，生成分析报告与结构化数据 4. **下载切图到本地** — 运行 `download-images.js` 将所有切图下载到 `assets/images/`，生成 `image-map.json` 映射表 5. **分析图层结构** — 根据解析报告识别画板、文本、图片、形状、分组等元素，检查每个元素的切图可用性 6. **生成 HTML** — 按设计数据生成 HTML，遵循切图优先原则，所有切图引用本地路径 7. **验证效果** — 启动本地 HTTP 服务器，在浏览器中打开 HTML 并截图对比设计稿 ## 核心原则 ### 1. 切图优先原则（最重要） **凡设计稿提供了切图的元素，直接用 `<img>` 实现，不要用 CSS 还原。** 切图由设计师从 Sketch 导出，能 100% 还原设计稿视觉效果（含特殊字体、复合边框、阴影、渐变叠加等）。CSS 还原常有偏差，且特殊字体在用户端通常不可用。 **切图来源优先级**： | 优先级 | 字段 | 格式 | 说明 | |--------|------|------|------| | 1（最优） | `image.svgUrl` | SVG | 矢量图，任意分辨率清晰，体积小 | | 2 | `image.imageUrl` | PNG/JPG | 位图切图，设计师导出的标准切图 | | 3 | `ddsImage.imageUrl` | DDS | 蓝湖渲染图，无切图时的兜底 | **适用所有图层类型**：文本图层、形状图层、形状组、图层组、Symbol 组件 — 只要有切图，就用 `<img>` 实现。 ### 2. 切图本地化（硬性要求） **所有切图必须下载到本地 `assets/images/` 目录，HTML 中只引用本地相对路径，严禁使用蓝湖 CDN 链接。** 禁止出现的 CDN 域名/关键词： - `lanhu.oss-cn-beijing.aliyuncs.com` - `alipic.lanhuapp.com` - `SketchPng` / `SketchSvg` **原因**：CDN 链接可能因权限、防盗链或链接失效导致图片无法显示；本地化后页面可离线运行、便于部署、加载更稳定。 ## 快速开始 ### Step 1: 打开蓝湖设计稿 ```bash # 1. 以持久化模式打开浏览器（默认 headless） playwright-cli open --persistent # 2. 导航到蓝湖链接（URL 含 & 时必须用双引号包裹） playwright-cli goto "https://lanhuapp.com/web/#/item/project/detailDetach?pid=XXX&image_id=XXX&project_id=XXX&fromEditor=true&type=image" # 3. 等待页面加载后检测登录状态 Start-Sleep -Seconds 3 playwright-cli eval "document.querySelector('.layers_item, .image-wrapper, canvas') ? 'logged-in' : 'NOT-logged-in'" ``` 若返回 `NOT-logged-in`，需关闭浏览器后以 `--headed` 模式重新打开，让用户在可见窗口中手动登录（扫码或账号密码）。登录完成后重新导航到设计稿链接即可，后续运行会自动保持登录状态。 ### Step 2: 获取 Sketch JSON 设计数据 ```bash # 查看网络请求，找到 SketchJSON 请求编号 playwright-cli requests # 获取响应体（文本直接显示，二进制保存到文件） playwright-cli response-body <request-number> ``` 识别要点：URL 通常包含 `alipic.lanhuapp.com` 或 `SketchJSON`，文件较大（100KB+）。 ### Step 3: 解析设计数据 ```bash node .trae/skills/lanhu-design-to-html/scripts/parse-design.js <response-file-path> ``` **输出文件**： | 文件 | 说明 | |------|------| | `design-analysis.txt` | 人类可读的图层分析报告，含切图可用性标注 | | `design-layers.json` | 结构化的完整图层数据（供下载脚本和 HTML 生成使用） | | `design-summary.json` | 精简摘要（画板信息 + 分类图层列表） | ### Step 4: 下载切图到本地 ```bash node .trae/skills/lanhu-design-to-html/scripts/download-images.js <design-layers.json> <output-dir> ``` **输出文件**： | 文件 | 说明 | |------|------| | `<output-dir>/assets/images/` | 本地切图文件（文件名取自图层名，保留中文，自动去重） | | `<output-dir>/image-map.json` | 原始 URL → 本地相对路径的映射表 | | `<output-dir>/image-download-failures.json` | 下载失败清单（便于重试） | ### Step 5: 生成 HTML 运行 `generate-html.js` 自动生成自包含的 `index.html`： ```bash node .trae/skills/lanhu-design-to-html/scripts/generate-html.js <design-layers.json> <image-map.json> [output.html] ``` 脚本遵循以下原则（已内置，无需手动处理）： - 画板尺寸作为容器（通常 375×812px） - 使用绝对定位或 Flexbox 布局（对同组元素自动检测行/列并使用 Flexbox） - 有切图的元素用 `<img src="./assets/images/xxx.png">` 实现（切图优先，引用本地路径） - 无切图的文本用 CSS 文字样式还原（font-family / size / color / line-height / letter-spacing） - 无切图的形状用 CSS（background / border / border-radius / box-shadow）还原 - 自动校验 HTML 中是否残留蓝湖 CDN 链接 ### Step 6: 验证效果 ```bash # 启动本地 HTTP 服务器 python -m http.server 8765 # 在浏览器中打开 HTML playwright-cli goto "http://localhost:8765/<html-file>" # 调整视口为移动端尺寸 playwright-cli resize 375 812 # 截图对比 playwright-cli screenshot --filename=preview.png ``` **本地化校验**：在 HTML 源码中搜索 `lanhu.oss-cn-beijing.aliyuncs.com`、`alipic.lanhuapp.com`、`SketchPng`、`SketchSvg`，确保结果为 0。 ## 脚本说明 ### parse-design.js — 设计数据解析器解析蓝湖 Sketch JSON，提取图层树结构、文本样式、形状属性、切图 URL，并生成人类可读的分析报告。 **用法**： ```bash node scripts/parse-design.js <response-file-path> [output-dir] ``` **解析内容**： - 画板信息（名称、尺寸、缩放比例） - 文本图层（内容、字体、字号、颜色、对齐、行高、字间距、多样式文本） - 图片/切图图层（PNG / SVG / DDS URL、尺寸、位置） - 形状图层（填充色、渐变、圆角、边框、阴影、透明度） - 分组图层（父子层级关系） - 切图可用性标注（`⭐ 切图可用: 是/否`）及实现建议汇总 ### download-images.js — 切图批量下载器读取 `design-layers.json`，按优先级（SVG > PNG > DDS）收集所有切图 URL，并发下载到本地，生成映射表。 **用法**： ```bash node scripts/download-images.js <design-layers.json> [output-dir] ``` **特性**： - 并发下载（默认 6 并发），自动处理重定向 - 文件名取自图层名（保留中文），自动去重 - 生成 `image-map.json`（URL → 本地路径映射），供 HTML 生成时替换引用 - 失败项记录到 `image-download-failures.json`，支持重试 - 自动识别图片格式（SVG / PNG / JPG / WEBP / GIF） ### generate-html.js — HTML 自动生成器读取 `design-layers.json` 与 `image-map.json`，按"切图优先"原则生成自包含的 `index.html`（CSS 内嵌于 `<style>`）。 **用法**： ```bash node scripts/generate-html.js <design-layers.json> <image-map.json> [output.html] ``` **特性**： - 切图优先：凡有切图（`image.svgUrl` / `image.imageUrl` / `ddsImage.imageUrl`）的元素一律用 `<img>` 实现 - 切图本地化：`<img src>` 一律从 `image-map.json` 查找本地路径，禁止出现蓝湖 CDN 链接 - 无切图文本用 CSS 文字样式还原（font-family / size / color / line-height / letter-spacing） - 无切图形状用 CSS 还原（background / border / border-radius / box-shadow / 渐变 / 透明度） - 布局分析：对同组元素自动检测行/列排列，优先使用 Flexbox（自动计算 gap），其余用绝对定位 - 生成 375×812px 画板容器，所有元素定位在此容器内 - 输出单文件 HTML，CSS 内嵌于 `<style>`，可直接在浏览器打开 - 自动校验 HTML 是否残留蓝湖 CDN 链接，发现则打印警告并以非零码退出 - 切图缺失时不回退 CDN，渲染占位 div 并提示手动补齐 `image-map.json` ## 平台单位切换蓝湖支持多平台样式切换，在设计稿标注视图中切换： | 平台 | 单位 | 换算 | |------|------|------| | iOS | pt | 1px = 1pt | | Android | dp | 1px = 1dp | | Web | px | 1px = 1px | | 微信小程序 | rpx | 1px = 2rpx | | 像素 | px | 1px = 1px | **注意**：Sketch JSON 中的数据始终是 px 单位；切换平台只影响蓝湖界面显示，不影响 JSON 数据。rpx 需手动乘以 2。 ## 常见问题 ### Q: 页面显示"重新登录" / 未登录蓝湖首次使用或登录过期时需手动登录。流程：headless 模式检测未登录 → 关闭浏览器 → `--headed` 模式重新打开 → 用户在可见窗口登录 → 重新导航到设计稿链接。使用 `--persistent` 后登录状态会保存到磁盘，后续运行自动保持登录。 ### Q: URL 中的 `&` 导致命令报错 PowerShell 中 `&` 是命令分隔符，必须用双引号 `"..."` 包裹整个蓝湖链接 URL。 ### Q: 找不到 Sketch JSON 请求确保 URL 中包含 `fromEditor=true` 参数（显示标注视图）。刷新页面后重新查看网络请求，或通过 `performance.getEntriesByType('resource')` 在页面上下文中查找。 ### Q: 切图下载失败 / 某些切图 403 蓝湖 CDN 偶尔限流。处理方式： 1. 删除 `assets/images/` 中的 0 字节文件后重新运行下载脚本 2. 在浏览器中右键手动保存切图，放入 `assets/images/` 并更新 `image-map.json` 3. 切图本地化是硬性要求，不得因下载失败而回退使用 CDN 链接 ### Q: 点击元素没有反应蓝湖设计稿上有 `.layers_item` 覆盖层，需点击覆盖层而非底层图片。使用 `playwright-cli eval` 获取所有 layers_item 的 data-id 和位置。 ### Q: Escape 键导致页面导航变化蓝湖的某些快捷键会触发导航。优先使用点击关闭弹窗，避免使用 Escape。 ## 参考文档 - [蓝湖设计稿分析工作流](references/lanhu-workflow.md) — 详细的浏览器操作步骤、登录处理、网络请求拦截、元素点击、切图获取技巧 - [设计数据解析指南](references/design-data-parser.md) — Sketch JSON 顶层结构、图层数据结构（文本/形状/图片）、解析策略、单位换算 - [HTML 实现指南](references/html-implementation.md) — 切图优先策略详解、尺寸对应、布局策略、元素还原示例、常见组件实现、验证流程 ## 设计稿还原示例以下是一个典型的切图优先实现示例（特殊字体标题）： ```html  <img src="./assets/images/apeman.png" style="position:absolute; top:58px; left:143px; width:84px; height:18px;">  <div style="font-family:'锐字真言体'; font-size:18px;">apeman</div>  <img src="https://lanhu.oss-cn-beijing.aliyuncs.com/SketchPng..."> ``` ## 许可证本 Skill 可在各类 Agent 中自由复用。

Loading the repository README…

Skills in this repository

Web Developers

1 occupation category · 100% classified

skill

occupation

description

updated

lanhu-design-to-html

Web Developers

从蓝湖设计稿链接获取设计信息并还原为HTML页面。Invoke when user provides a lanhuapp.com link, asks to analyze/restore a Lanhu design mockup, or needs to extract design specs from Lanhu.

Source text: Chinese

2026-07-07

Showing 1 of 1 collected skill.