# Lanhu UI MCP

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

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

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

## 安装

需要 Python 3.10 或更高版本。

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

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

```dotenv
LANHU_COOKIE=你的完整Cookie
```

启动：

```powershell
python -m lanhu_ui_mcp
```

## 工具

### `lanhu_ui_assets`

切图输出支持按需选择显示倍率和格式：

- `density=auto|1x|2x|3x|source`，默认 `auto`；未明确指定时，所有满足条件的位图统一输出 `2x`。
- `format=source|png|webp`，默认 `source`。
- 每个实例返回 `source_pixel_ratio`、`available_densities`、`recommended_density` 和实际 `pixel_ratio`；完整选择原因保存在页面 manifest。
- 可选倍率仍通过 `available_densities` 完整提供；显式传入倍率时按指定倍率输出。
- 源文件始终保留，派生图按参数缓存；源图不足目标倍率时不放大，而是保留源图并写入 `density_policy.fallbacks`。SVG 始终按矢量源文件返回。

下载蓝湖切图模式中的真实切图。默认返回最多 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` 由显式角色或重复结构识别，
  与中文、英文及具体业务内容无关。
- 普通兄弟元素的几何重叠不会直接触发 absolute，而是写入
  `ignored_overlaps`，包含双方 layer ID、重叠率、交集 bbox 和 z-index。
- 有序兄弟重叠继续使用 Flow/Flex；`child_margins.overlap_before` 给出重叠量，
  下游仅在视觉还原需要时使用负 margin 或 transform。
- 只有显式 absolute/fixed/sticky、装饰覆盖层或越界装饰元素才输出定位建议；
  实际定位元素通过 `overlap_with` 和 `overlap_evidence` 标明关联对象。

### 参考裁剪

区域截图统一标记为：

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

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

## 数据与兼容性

当前 `schema_version` 为 `8`。

- 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。

缓存目录结构：

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

## 验证

```powershell
.\.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
```