Lanhu UI MCP

面向 UI 还原 Agent 的蓝湖 MCP，只暴露两个工具：

• lanhu_ui_region：读取准确元素、文本样式、布局提示和参考裁剪。
• lanhu_ui_assets：下载蓝湖切图并返回独立图层实例、组合顺序和覆盖率。

两个工具都接收包含 pid 与 image_id（或 docId）的蓝湖详情 URL。

安装

需要 Python 3.10 或更高版本。

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
Copy-Item .env.example .env

将登录蓝湖后的完整 Cookie 写入 .env：

LANHU_COOKIE=你的完整Cookie

启动：

python -m lanhu_ui_mcp

工具

lanhu_ui_assets

下载蓝湖切图模式中的真实切图。默认返回最多 20 个切图实例；数量更多时使用 cursor 继续分页。

每个实例包含：

• instance_id
• layer_id
• parent_id
• bbox
• z_index
• path
• role
• render_order
• discovery_source
• discovery_confidence

相同远程图片只保存一份本地文件，但每个图层实例都会独立返回，不会按 URL 合并。 存在蓝湖导出标记时 discovery_source=lanhu_export_metadata；缺少导出标记时才使用 embedded_asset_fallback，并明确返回降级警告。

响应中的 composition.backgrounds 标明背景切图必须叠加的子切图， composition.render_sequence 给出完整渲染顺序。

可通过 used_assets 传入页面实际使用的 layer_id 或本地路径，返回：

• pending_instance_count：仍未分页下载的实例数量，不代表下载失败。
• download_failures：当前页真实下载失败的资源摘要。
• implementation_usage：传入 used_assets 后才计算的实现使用覆盖率。

lanhu_ui_region

返回元素参数和实现建议。常用参数：

• profile=compact|implementation|raw
• collapse_slices=true
• visible_only=true
• crop_image=true
• clip={x,y,width,height}
• query=关键词
• cursor / limit

首次查询完整画布时，响应包含 region_overview：

• top_level_regions：顶级区域摘要及可继续查询的 region_id。
• text_summary：重要文本样本和坐标。
• risk_warnings：分页遗漏、背景叠加和定位风险。

详细图层通过 region_id、cursor 和 limit 分页查询。

bbox 是设计测量数据，不表示必须绝对定位。实现页面时优先使用正常文档流、 Flexbox 或 Grid；只有 layout_hint 明确建议时才使用 absolute、fixed 或 sticky。 表单、列表和纵向区块会附带 padding、gap、margin、对齐方式与 child_order。

切图内部图层默认折叠，避免重复实现。覆盖数据分为：

• asset_coverage：当前区域切图实例的检索情况。
• retrieval_coverage：切图、普通文本、形状和覆盖层的查询情况。
• implementation_coverage：只有下游提供实际实现证据后才能计算；区域读取默认 返回 checked: false。

完整遗漏列表只写入查询 JSON。MCP 响应仅返回数量和最多 5 个样例，避免分页后 又通过覆盖率字段把全部图层塞回上下文。

背景或大切图通过 required_non_asset_layers 标明仍需单独实现的文本、形状和覆盖层。

文本图层在 implementation/raw profile 中返回 text_spec：

• 可实现的段落与换行。
• 字体、字号、字重、行高、字间距、颜色和对齐方式。
• 文本容器宽高、换行和空白处理建议。

PNG/WebP 等栅格切图返回像素坐标 alpha_bbox 和设计坐标 visual_bbox； SVG 返回基于 viewBox 的 visual_bbox，用于区分透明边缘、阴影和设计图层 bbox。

通用语义与布局推断

• 不使用页面文案或行业词汇推断表单、列表、背景、fixed 或 sticky。
• 优先读取 role、semanticRole、layoutRole、componentType、 controlType、position 等图层元数据。
• 元数据缺失时，仅根据包含、重叠、对齐、间距和重复尺寸等几何结构推断。
• fixed/sticky 必须有显式元数据；无法确认时保守返回普通流式布局或 unknown。
• form 由显式角色或通用控件组合识别，list 由显式角色或重复结构识别， 与中文、英文及具体业务内容无关。

参考裁剪

区域截图统一标记为：

{
  "role": "reference_crop",
  "formal_page_resource": false,
  "usage": "visual comparison only"
}

reference_crop 仅用于视觉对比，禁止作为正式页面图片。兼容字段 paths.crop 暂时保留，并与 paths.reference_crop 指向同一文件。

数据与兼容性

当前 schema_version 为 7。

• JSON 使用严格 UTF-8 编码，不转义中文。
• 非有限浮点数会转换为 null，确保 JSON 合法。
• 读取时兼容 UTF-8 BOM。
• lanhu_ui_region 写入前执行 UTF-8、严格 JSON round-trip 和结构 Schema 校验， 并在 validation 中返回结果。
• 两个工具名称和调用参数继续可用。
• v7 调整了覆盖率响应：visible_content_coverage 改为 retrieval_coverage，implemented/unimplemented 改为 returned/missing；消费方应检查 schema_version。
• 旧缓存会因 Schema 版本变化自动重新生成。
• measurement_hint 保留旧版绝对坐标，css_hint 面向实际布局实现。

内部按职责拆分：

• schema_adapter.py：将蓝湖/Sketch Schema 转为统一图层记录。
• region_pipeline.py：区域过滤、布局分析和检索覆盖率。
• asset_pipeline.py：切图分页、下载、去重、可见边界和使用校验。
• contracts.py：Schema v7、UTF-8、JSON、bbox、ID 和渲染顺序校验。
• projections.py：限制 MCP 响应体积；完整数据保留在本地 JSON。

缓存目录结构：

.lanhu-cache/<project>/designs/<design>/
├── raw-schema.json
├── original.png
├── overview.json
├── regions.json
├── design-tokens.json
├── assets.json
├── queries/
└── downloaded-slices/

验证

.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m ruff check lanhu_ui_mcp tests
.\.venv\Scripts\python.exe -m mypy lanhu_ui_mcp
.\.venv\Scripts\python.exe -m compileall -q lanhu_ui_mcp tests