| name | lanhu-design |
| description | Use for Lanhu (蓝湖) UI design handoffs and lanhuapp.com design project links: list design screens, inspect screenshots and HTML/CSS specs, extract design tokens, download slices/assets, or implement UI. Trigger when the request explicitly mentions 蓝湖, Lanhu, lanhuapp.com, or the bundled Lanhu scripts. Do not use for standalone Figma/Sketch files, generic UI implementation, PRD/Axure docId links, or image editing unrelated to Lanhu. |
| license | MIT; see LICENSE.txt |
| compatibility | Requires Node.js 18+, network access to lanhuapp.com, and a valid LANHU_COOKIE environment variable. |
| metadata | {"author":"oyjt","version":"1.3.0"} |
Lanhu Design
概览
通过内置脚本直接调用蓝湖 HTTP API，读取 UI 设计稿、分析设计规格、获取切图信息，并把切图落到当前项目的资源目录。
需要详细工具契约、返回结构和还原规则时，读取 references/lanhu-design-tools.md。
需要设计还原实现规则（CSS 值保真、DOM 结构映射、切图命名策略、目录选择、倍率指引）时，读取 references/design-implementation-rules.md。
前置条件
所有脚本依赖 LANHU_COOKIE 环境变量。蓝湖没有公开 API 或 OAuth，脚本通过浏览器会话 Cookie 模拟登录用户请求。Cookie 缺失或过期时，脚本调用报认证错误。
获取 Cookie 的步骤：
- 在浏览器打开
https://lanhuapp.com 并登录。
- 按 F12（macOS 为 Cmd+Option+I）打开开发者工具，切换到 Network 标签页。
- 刷新页面，在请求列表中点击任意
lanhuapp.com 请求。
- 在 Request Headers 中找到
Cookie 字段，复制完整值（通常 200–500 字符）。
- 将该值设置为环境变量
LANHU_COOKIE。
注意事项：
- Cookie 会过期（通常数天到数周），出现认证错误时需重新获取。
- Cookie 是敏感凭据，不要提交到版本控制或输出给用户。
- 所有脚本需要 Node.js >= 18（使用原生 fetch）。
脚本列表
| 脚本 | 用途 |
|---|
scripts/get_designs.mjs | 列出蓝湖项目的设计图 |
scripts/get_design_specs.mjs | 获取设计规格 HTML+CSS（主路径：DDS Schema；降级：Sketch JSON） |
scripts/download_design_images.mjs | 下载设计图原图到本地目录（视觉校验用） |
scripts/get_design_slices.mjs | 获取单个设计图的切图/素材元数据 |
scripts/download_slices.mjs | 从切图 JSON 批量下载切图文件 |
scripts/lanhu-client.mjs | 共享 HTTP 客户端模块（被上述脚本引用，不直接运行） |
scripts/design-converter.mjs | 纯转换模块（被 get_design_specs.mjs 引用，不直接运行） |
工作流
- 确认
LANHU_COOKIE 环境变量已设置。如果首次运行脚本返回认证错误，提示用户检查 Cookie 是否已配置且未过期，参考上方「前置条件」重新获取。不要在认证失败后继续调用其他脚本。
- 先判断用户给的是蓝湖 UI 设计项目链接，而不是需求文档链接。UI 设计项目通常是
https://lanhuapp.com/web/#/item/project/stage?tid=xxx&pid=xxx，必须有 pid，tid 可选；不要把带 docId 的 PRD 链接当设计稿处理。
- 运行
node scripts/get_designs.mjs <url> 获取设计图列表。后续分析和切图都以这个列表里的 index、name、id 为准。
- 如果设计图很多，先让用户指定范围；如果用户已经明确说"全部"，再用
all。不要默认一次分析大量设计图。
- 【还原 UI 的强制前置步骤】查看或实现 UI 前，必须先下载并用 Read 工具查看设计图原图：运行
node scripts/download_design_images.mjs <url> --designs <names> --output <dir> 下载原图，--designs 支持序号（逗号分隔）、精确名称或 all，下载后用 Read 工具实际查看。不要跳过看图直接基于 HTML 规格还原——原图是布局、层级、视觉效果的最终核对依据，source="sketch" 降级时更是布局结构的主力参考。
4.5. 获取设计规格 HTML+CSS：运行 node scripts/get_design_specs.mjs <url> --design <name_or_index> 获取规格。返回的 source 字段决定数据权威性，必须先判断：
source="dds"：从 DDS Schema 生成的高精度 flex 布局 HTML+CSS，html 字段是颜色、字号、间距、渐变、圆角、布局等所有参数的权威来源，直接复用、不得主观修改；原图用于核对布局是否错位。source="sketch"：降级路径，html 仅为绝对定位的元素清单，不可当作布局权威。此时以原图视觉为布局主力参考，以 design_tokens / sketch_annotations 的原始数值为精确数值来源。source="sketch" 时，HTML 元素带 data-css，返回还包含 design_scale 和 layer_css_annotations，用于逐图层核对路径、文本、切图和 CSS 标注。image_url_mapping 列出需要下载的图片资源映射表。若返回 dds_error，说明已降级到 sketch，应更依赖原图。- 返回的
source_guidance 字段是针对当前 source 的数据权威性指引，直接按它执行。
- 加
--output <dir> --download-images 可在保存 HTML 的同时自动把引用图片下载到 <dir>/assets/slices/，使保存的 HTML 可直接在浏览器渲染核对。
- 下载切图、图标、图片素材时，运行
node scripts/get_design_slices.mjs <url> --design <name> 获取切图 JSON。单次只传一个设计图名称或序号。
- 下载前确认平台和倍率偏好。用户不指定时推荐 Web 2x，但仍要明确说明选择；常用键包括
1x、2x、3x、ios_1x、ios_2x、ios_3x、android_mdpi、、、、。除 可回退到 外，其它倍率必须由切图 JSON 的 提供，不要复制同一文件伪造成多倍率资源。
设计还原规则
完整规则见 references/design-implementation-rules.md。以下是必须遵守的核心要求。
数据来源优先级（按 get_design_specs.mjs 返回的 source 分级）
还原前必须先看 source 字段，不同来源的权威性完全不同：
source="dds"（高保真，HTML 权威）：
html 字段：颜色、尺寸、间距、字体、圆角、渐变、定位、布局结构的权威来源。直接复制精确的 CSS 属性值，不得修改。design_tokens 字段：补充 HTML 中可能被合并的高风险视觉信息（复合渐变、非均匀圆角、阴影、opacity<100）。- 设计图原图：用于核对布局是否错位、元素是否齐全，不覆盖 HTML 数值。
- 切图元数据（
get_design_slices.mjs）：补充 fills、borders、opacity、rotation、text_style、shadows、border_radius。
source="sketch"（降级，原图为布局主力）：
- 设计图原图：布局结构、层级关系、视觉效果的主力参考。
html 是扁平的绝对定位元素清单，不能当作布局权威，仅用于核对元素是否齐全。
design_tokens / sketch_annotations 字段：颜色、字号、间距、圆角、阴影等精确数值的权威来源。html 字段：仅作元素清单和绝对定位参考，布局意图需结合原图重建。- 切图元数据：同上，补充视觉细节。
禁止修改 CSS 值
- 不要转换色值格式（
rgba() ↔ hex 保持原样）。
- 不要四舍五入或简化数值（如
0.30000001192092896 保持原样）。
- 不要把
linear-gradient 简化成纯色。
- 不要调整
font-family 顺序或删除 fallback 字体。
- 不要把 margin/padding 取整为"干净"的数字。
- 不要用 SVG、CSS shape、emoji 或占位图替换切图。
- 不要省略任何可见的设计元素。
- 不要在最终代码中保留蓝湖远程 CDN URL。
DOM 结构映射
HTML 的 class 名称表达布局意图，需转译为目标框架组件，同时保持 CSS 值不变：
flex-row → 水平排列（React: display:flex，Flutter: Row()，SwiftUI: HStack）flex-col → 垂直排列（React: flex-direction:column，Flutter: Column()，SwiftUI: VStack）justify-between → 两端对齐（space-between / MainAxisAlignment.spaceBetween）relative / absolute → 定位层叠（Flutter: Stack + Positioned，SwiftUI: ZStack）
详细映射表见 references/design-implementation-rules.md。
框架检测与代码生成
实现 UI 前先检测项目类型（读取 package.json、pubspec.yaml、build.gradle、Podfile 等），生成匹配框架的代码（React JSX、Vue SFC、Flutter Widget、SwiftUI View、Android Compose 等）。CSS 属性需按平台做单位映射（px→dp/pt），但不能改变数值精度。未检测到框架时默认生成纯 HTML。各框架的 CSS 属性映射表和资源引用方式见 references/design-implementation-rules.md。
若项目根目录存在 DESIGN.md（或同等职责的设计系统文档），解析规格与落盘代码前必须先读取并遵守其令牌、排版、组件与命名约定；图层级具体数值仍以规格数据为准，冲突时以规格数值保证当前屏还原度并向用户说明取舍。详见 references/design-implementation-rules.md。
生成后保真审计
代码生成后必须逐属性对照设计规格 HTML+CSS 执行保真检查，覆盖 10 项：尺寸约束、裁剪、色值、渐变、绝对定位、字体、间距、图片资源、元素完整性、无远程 URL。对每个差异标注是平台适配还是错误，错误必须修正后交付。完整清单见 references/design-implementation-rules.md。
切图下载
从 get_design_slices.mjs 保存返回结果为 JSON 后，可运行：
node scripts/download_slices.mjs slices.json --output ./src/assets/images/slices/home --scale 2x
常用参数：
--scale 2x：下载 Web 2x，文件名后缀默认 @2x。--scale ios-all：下载 iOS 1x/@2x/@3x。--scale android-all：下载 Android 全套并放入 mipmap-* 子目录。--name-map names.json：提供 {slice_id_or_name_or_layer_path: "semantic_name"}，覆盖自动文件名。--referer https://lanhuapp.com/：需要带 Referer 时使用。
脚本只负责稳定下载和基础去重。语义化命名应优先结合当前项目已有命名规范处理。
全套倍率依赖 scale_urls 中的真实多倍率地址；缺失时脚本会报错而不是复制 download_url。
Photoshop 稿（设计 JSON 根节点 type=ps）的切图登记在 assets[]，脚本会自动按图层 id 提取 png_xxxhd/svg 地址并推导多倍率（PS 稿图层像素尺寸为 @2x 基准）。
切图下载前置步骤
下载切图前，按以下顺序准备：
- 识别项目类型：检查
package.json、pubspec.yaml、*.xcodeproj、build.gradle 等标志文件，判断 React/Vue/Flutter/iOS/Android。
- 确定输出目录：用户指定 > 项目已有资源目录 > 通用默认路径。详细规则见
references/design-implementation-rules.md。
- 确认倍率：用户不指定时推荐 Web 2x，但必须明确告知选择。
- 准备命名映射：根据切图的
layer_path、parent_name 生成语义化英文文件名（icon_、bg_、btn_ 等前缀），沿用项目已有命名风格。命名策略详见 references/design-implementation-rules.md。
完成检查
交付前确认：
- 已先运行
get_designs.mjs 并基于列表匹配目标设计图。
- 还原 UI 前已下载并用 Read 工具实际查看过设计图原图。
- UI 实现已按
source 分级核对：dds 以 HTML+CSS 为权威，sketch 以原图布局 + design_tokens 数值为主，没有用设计截图主观改 DDS 的精确值。
- 已执行生成后保真审计（10 项清单），所有错误已修正，仅保留合理的平台适配差异。
- 生成代码匹配检测到的项目框架，遵循项目已有约定（命名、目录、样式方案）。
- 所有远程图片/切图已下载为本地资源，代码中没有蓝湖 CDN URL。
- 图片资源使用目标框架约定的引用方式（如 React
import、Flutter AssetImage）。
- 切图下载数量、失败数量、输出目录已向用户说明。
- 中间产物已按
references/design-implementation-rules.md 的「临时文件清理规则」处理：先列出候选路径并检查引用，取得用户明确确认后再删除；仅保留被代码引用的切图文件。用户未确认时保留文件并报告路径。
- 工作流中未出现认证错误。如果出现过，已引导用户刷新 Cookie 并重试。
交付输出
最终回复简要列出：处理的设计图和 source、新增或修改的代码/资源路径、切图下载成功与失败数量、执行的验证及结果、仍需用户处理的认证或平台适配事项。不要输出 Cookie、带认证参数的完整请求头或不必要的远程资源 URL。
