用于读取和导出 蓝湖 设计稿的命令行工具,同时提供可安装的 Agent Skill。
通过 lanhu 命令可以完成浏览器授权、设计图查询、预览图下载、设计规格提取、切图下载和设计上下文导出。
- 使用系统默认浏览器完成蓝湖登录
- 列出项目中的设计图
- 下载设计预览图
- 导出 HTML、CSS 和 Design Tokens 等设计规格
- 获取并批量下载 Web、iOS、Android 切图
- 一次性导出 AI 编码所需的设计上下文
- 使用
--json输出适合脚本和 Agent 处理的结构化结果
- Node.js 22.12 或更高版本
- macOS、Windows 或 Linux
- 能够访问
lanhuapp.com的网络环境 - 已加入对应蓝湖项目的账号
npx lanhu-design@latest install安装向导会自动:
- 安装或升级全局
lanhuCLI。 - 安装全局 Agent Skill,使 Claude Code、Codex CLI、Cursor 等工具可以发现并使用蓝湖能力。
- 询问是否检查蓝湖登录凭据;已有有效凭据会直接复用,只有缺少或过期时才尝试读取浏览器,必要时打开登录页。
安装完成后可以检查 CLI:
lanhu --version如果安装向导已经确认凭据可用,可以跳过这一步;否则执行:
lanhu authCLI 会优先复用已有凭据。没有可用凭据时,将读取默认浏览器登录状态;如果浏览器尚未登录,CLI 会先显示 3 秒倒计时,再打开蓝湖登录页并等待你完成登录。
macOS 从 Chrome、Edge 等 Chromium 浏览器读取登录状态时,系统可能显示钥匙串授权窗口。CLI 会在弹窗出现前说明用途,请根据需要选择“允许”或“始终允许”。
将设计项目链接保存为变量,后续命令可直接复用:
export LANHU_URL='https://lanhuapp.com/web/#/item/project/stage?tid=xxx&pid=xxx'
lanhu designs "$LANHU_URL"Windows PowerShell:
$env:LANHU_URL='https://lanhuapp.com/web/#/item/project/stage?tid=xxx&pid=xxx'
lanhu designs $env:LANHU_URL| 命令 | 用途 |
|---|---|
lanhu auth |
登录或复用已有登录凭据 |
lanhu auth status |
查看当前凭据状态 |
lanhu auth refresh |
重新打开浏览器并刷新 Cookie |
lanhu auth import |
手动导入 Cookie |
lanhu auth logout |
删除 CLI 保存的凭据 |
登录凭据与 CLI 配置统一保存在用户主目录:
- macOS / Linux:
~/.config/lanhu-design/credentials.json - Windows:
%USERPROFILE%\.config\lanhu-design\credentials.json
正常情况下只需要执行一次 lanhu auth。如果业务命令提示登录过期,请运行:
lanhu auth refresh当系统安全机制禁止读取或解密浏览器 Cookie 时,可以使用内置的手动导入方式:
lanhu auth import命令会通过隐藏输入读取 Cookie,避免将敏感信息直接写入命令行历史。
获取 Cookie 的步骤:
- 在浏览器打开并登录
https://lanhuapp.com。 - 打开开发者工具,进入 Network 面板。
- 刷新页面并选择任意
lanhuapp.com请求。 - 在 Request Headers 中复制完整的
Cookie值。 - 回到终端执行
lanhu auth import并粘贴。
Cookie 是敏感凭据。不要将它提交到 Git、粘贴到 Issue、写入公开日志或发送给他人。
| 命令 | 用途 |
|---|---|
lanhu install |
安装或升级 CLI 和全局 Agent Skill |
lanhu designs "$LANHU_URL" |
列出项目设计图 |
lanhu image "$LANHU_URL" --design 首页 --output .lanhu/images |
下载指定设计图的预览图 |
lanhu specs "$LANHU_URL" --design 首页 --output .lanhu/specs --download-images |
导出设计规格及引用图片 |
lanhu slices "$LANHU_URL" --design 首页 --output .lanhu/slices.json |
获取切图元数据 |
lanhu download .lanhu/slices.json --output src/assets --scale 2x |
批量下载切图 |
lanhu export "$LANHU_URL" --design 首页 --output .lanhu |
导出完整设计上下文 |
运行 lanhu <command> --help 可以查看命令的完整参数,例如:
lanhu specs --help
lanhu download --help所有命令的 --timeout 均以秒为单位;业务请求默认 30 秒,浏览器登录默认等待 120 秒。
lanhu designs "$LANHU_URL"设计图后续可以通过序号、精确名称或 ID 选择。
lanhu image "$LANHU_URL" \
--design "首页" \
--output .lanhu/images预览图适合用于视觉分析和设计还原前的布局确认。
lanhu specs "$LANHU_URL" \
--design "首页" \
--output .lanhu/specs \
--download-images输出包含可用的 HTML、CSS、Design Tokens 和设计图片。数据源可能是高保真的 DDS Schema,也可能是 Sketch/Figma 标注降级结果,命令输出会标明实际来源。
先保存切图元数据:
lanhu slices "$LANHU_URL" \
--design "首页" \
--output .lanhu/slices.json再按目标平台下载:
# Web 2x
lanhu download .lanhu/slices.json --output src/assets --scale 2x
# iOS 全倍率
lanhu download .lanhu/slices.json --output ios-assets --scale ios-all
# Android 全密度
lanhu download .lanhu/slices.json --output android-assets --scale android-all支持的常用倍率:
| 平台 | --scale |
|---|---|
| Web | 1x、2x、3x |
| iOS | ios-all |
| Android | android-all |
多倍率下载只使用蓝湖提供的真实资源地址;缺少对应倍率时会报告错误,不会复制同一图片伪造多倍率文件。
lanhu export "$LANHU_URL" \
--design "首页" \
--output .lanhu \
--scale 2xexport 适合交给 AI 编码助手使用,会集中导出设计图、规格和切图信息。
在任意命令中添加 --json,可以获得稳定的 JSON envelope:
lanhu designs "$LANHU_URL" --json
lanhu auth status --json普通终端模式优先显示便于阅读的操作结果;--json 适合脚本、CI 和 Agent 调用。需要减少非必要输出时可使用 --quiet。
Agent Skill 为 AI 编码助手提供蓝湖任务的识别规则、操作流程和设计还原规范。
推荐使用安装向导,一次安装 CLI 和全局 Agent Skill:
npx lanhu-design@latest install如需跳过登录凭据检查,可以执行:
npx lanhu-design@latest install --no-auth
lanhu auth如果只需要 Agent Skill,可以单独安装:
npx skills add oyjt/lanhu-design安装后可以直接向 AI 描述任务,例如:
帮我列出这个蓝湖项目中的设计图:<蓝湖项目链接>
根据蓝湖项目中的“首页”设计稿还原当前页面,并下载需要的切图。
把“登录页”的切图按 iOS 全倍率下载到项目资源目录。
Skill 会优先使用已安装的 lanhu CLI;未安装 CLI 时,仍可通过仓库内兼容脚本和 LANHU_COOKIE 环境变量运行。
CLI 推荐使用 lanhu auth 管理凭据。自动化环境或旧脚本也可以临时设置 LANHU_COOKIE:
macOS / Linux:
export LANHU_COOKIE='完整 Cookie'Windows PowerShell:
$env:LANHU_COOKIE='完整 Cookie'凭据使用顺序为:显式 --cookie(仅用于调试)、LANHU_COOKIE、CLI 保存的凭据。
不建议把 Cookie 写入项目
.env、仓库配置或 shell 历史。业务命令不会自动扫描浏览器,只有auth和auth refresh会读取浏览器登录状态。
这是 Chromium 解密 Cookie 时的系统安全确认。CLI 会在可能弹窗前显示说明。首次授权后是否再次询问由 macOS 钥匙串权限设置决定。
如果不希望 CLI 访问 Keychain,可以取消授权并使用:
lanhu auth import请确认蓝湖已在系统默认浏览器中登录,然后重新执行 lanhu auth。如果登录位于其他 Profile,可以显式指定:
lanhu auth --browser chrome --profile "Profile 1"支持的浏览器包括 Chrome、Edge、Brave、Arc、Dia、Chromium、Firefox 和 Safari。
如果浏览器已经登录但 CLI 仍然无法读取,请先确认登录所在的 Profile,必要时显式指定:
lanhu auth --browser edge --profile "Profile 1"新版 Chromium 可能使用 App-Bound Encryption,普通进程无法解密。此时可以改用 Firefox 登录,或执行 lanhu auth import。认证失败时,CLI 也会直接给出这两种兜底方式。
lanhu auth refresh如果仍然失败,先在浏览器退出并重新登录蓝湖,再运行刷新命令。
lanhu auth status原有脚本继续保留在 skills/lanhu-design/scripts/,供 Skill 独立运行和旧调用方式使用:
| 脚本 | 用途 |
|---|---|
get_designs.mjs |
列出设计图 |
download_design_images.mjs |
下载设计预览图 |
get_design_specs.mjs |
提取设计规格 |
get_design_slices.mjs |
获取切图元数据 |
download_slices.mjs |
批量下载切图 |
兼容脚本要求 Node.js 18 或更高版本,并通过 LANHU_COOKIE 完成认证。新用户建议优先使用 CLI。
corepack pnpm install
corepack pnpm check项目使用语义化版本和 v* Git 标签发布 npm 包,更新记录见 CHANGELOG.md。仓库维护约定见 AGENTS.md。
本项目基于 lanhu-mcp 开发,感谢原作者对蓝湖 API 和工具链的探索。