把蓝湖需求文档和设计稿喂给 AI 编程助手（lanhu-mcp）

蓝湖里的需求文档和设计稿，是前端开工前绕不过去的一环。常见流程是这样：打开 Axure 原型页逐条读需求，再在设计稿上量尺寸、记间距、抄颜色，最后把这些信息翻译成页面。AI 编程助手能写代码，却看不到蓝湖里的内容，因为它没有访问蓝湖的通道，你只能手动把信息复制进对话框。

lanhu-mcp 是一个 Python 写的 MCP 服务器，把蓝湖的需求文档和设计稿读给 AI 编程助手，输出需求要点、设计参数与前端代码参考。

它在本地或服务器上跑一个 MCP 服务，用 LANHU_COOKIE 以你的账号身份访问蓝湖。支持 MCP 的 AI 客户端（Cursor、Claude Code、Windsurf、Trae、通义灵码、Cline 等）配好地址之后，就能在对话里直接调用它的工具。返回的内容分三类：需求文档的文本与截图、设计稿的尺寸颜色字体等参数、可下载的切图资源包。

项目对模型有硬性要求：需要图像识别能力，官方列出的是 Claude、GPT、Gemini、Kimi、Qwen、DeepSeek，纯文本模型（如 GPT-3.5、Claude Instant）不能使用。仓库地址是 dsphper/lanhu-mcp，采用 MIT 许可证，主要语言 Python，仓库体积 2705 KB，目前 2470 Star、272 Fork、40 个开放 Issue。

基础用法

安装与依赖

Docker 部署是官方推荐的方式，环境隔离且一条命令拉起。前置只有一个：你得先有蓝湖网页版的 Cookie。

git clone https://github.com/dsphper/lanhu-mcp.git
cd lanhu-mcp
cp .env.example .env
# 编辑 .env，将 LANHU_COOKIE 改为你自己的 Cookie
docker compose up -d --build

Windows 用户用 copy 代替 cp 创建配置文件；旧版 Docker Compose 把 docker compose 换成 docker-compose。

源码运行要求 Python 3.10 以上，macOS 自带的 Python 3.9 不满足，先跑 python3 --version 确认。官方提供了一键安装脚本，会自动装依赖、引导获取 Cookie 并写环境变量。

git clone https://github.com/dsphper/lanhu-mcp.git
cd lanhu-mcp
bash easy-install.sh        # Linux/Mac
# Windows 用 easy-install.bat

脚本默认优先使用阿里云 PyPI，失败时回退到清华和官方源；Chromium 走 npmmirror 的 Chrome for Testing 镜像，并以 Playwright 官方 CDN 兜底。想改下载源，可以设置 PIP_INDEX_URL、PLAYWRIGHT_DOWNLOAD_HOST、PLAYWRIGHT_CHROMIUM_DOWNLOAD_HOST。

手动安装的步骤是建虚拟环境、以可编辑模式装包、再用 Playwright 装 Chromium 浏览器：

python3 -m venv venv
./venv/bin/python -m pip install -e .
./venv/bin/python -m playwright install chromium
cp .env.example .env

最短能跑通的示例

Cookie 从蓝湖网页版拿：登录后打开浏览器开发者工具，从任意请求的请求头里复制 Cookie，填进 .env 的 LANHU_COOKIE。仓库里另有一份独立的获取教程 GET-COOKIE-TUTORIAL.md。

Docker 起好之后，服务监听在 http://localhost:8000/mcp。在支持 MCP 的客户端里加一段配置就能用，Claude Code 的写法是：

{
  "mcpServers": {
    "lanhu": {
      "type": "http",
      "url": "http://localhost:8000/mcp?role=Developer&name=YourName"
    }
  }
}

Cursor、Windsurf 等客户端去掉 type 字段，只留 url。URL 上的 role 和 name 用于协作追踪与 @提醒，部分 AI 开发工具不支持 URL 里出现中文参数值，建议填英文。

不想让服务常驻，可以改成按需拉起。Cursor、Claude Code 这类支持 command / args 的客户端，把启动脚本路径写进配置，客户端要用的时候自己拉进程，Linux 和 macOS 的写法如下：

{
  "mcpServers": {
    "lanhu": {
      "command": "/bin/bash",
      "args": [
        "/run-stdio.sh"
      ],
      "env": {
        "LANHU_USER_NAME": "YourName",
        "LANHU_USER_ROLE": "Developer"
      }
    }
  }
}

Windows 把 command 换成 run-stdio.bat 的绝对路径，不需要 args。这个路径要替换成本机项目的绝对路径，在 macOS 或 Linux 下可以进项目目录执行 pwd 拿到。纯本地、不装 Docker 的完整注册步骤在 LOCAL-STDIO.md 里。

确认它跑起来了

HTTP 模式下服务起来之后，浏览器访问 http://localhost:8000/mcp 能看到 MCP 端点响应；Docker 部署用 docker-compose logs -f 看启动日志有没有报错。

更直接的办法是在 AI 客户端里说一句「列出这个蓝湖项目的设计稿」。工具 lanhu_get_designs 能返回设计图列表和预览，说明 Cookie、网络和 MCP 链路都通了。如果这一步失败，日志里的报错是下一步排查的入口，418 和 Session not found 两个错误在下面的坑点一节里单独说。

主要功能

需求与设计数据读取

• 需求文档提取：下载并解析 Axure 页面、资源与已支持的注释字段。lanhu_get_pages 拿页面列表，lanhu_inspect_requirement_region 在需求页里按文字、稳定块 ID、分块 ID 或坐标取局部图，v1.8.6 加入，专门对付「这两个字段」「如下」「红框处」这类指代不清的写法。交互语义能提取多少，取决于蓝湖源数据里本来就有什么。
• 设计稿查看与批量下载：按项目读取设计图列表，批量下载并展示 UI 设计图。这一步同样依赖有效的 LANHU_COOKIE，Cookie 过期会直接失败。
• 切图提取与资源交付：自动识别并导出设计切图和图标资源，图层与素材按 ID 关联。下载后会校验图片尺寸与哈希，并提供可通过 MCP 传输的资源包和客户端安装器，细节写在 DESIGN_CONTEXT.md。切图的业务命名交给大模型结合视觉与工程约定判断，仓库里的稳定部分只有 ID 映射。

分析与交付

• 设计图分析：lanhu_get_ai_analyze_design_result 返回设计图预览、源参数，以及由 Schema 派生出的 HTML+CSS 参考代码。官方提醒生成结果仍要结合原始标注和实际渲染核验，不能直接当成品用。
• 需求页 AI 分析：lanhu_get_ai_analyze_page_result(mode="full") 返回完整页面截图；遇到超长或超大页面，会额外返回带重叠区域、保持原清晰度的分块，并标注页名和源坐标，v1.8.5 起支持。
• 三种分析视角：开发视角给字段规则、业务逻辑与全局流程图；测试视角给测试场景、用例、边界值和校验规则；快速探索给核心功能概览、模块依赖与评审要点。配套的四阶段工作流是全局扫描、分组分析、反向验证、生成交付物，目录和来源信息用来帮你核对有没有遗漏，官方没有把流程提示当成准确率保证。
• 团队留言板：接了同一个 MCP 服务的 AI 助手共享留言板数据，开发 AI 分析过的需求，测试 AI 可以直接查询。留言分「知识库」「任务」等类型，支持飞书通知 @提醒，并自动记录谁的 AI 访问过哪些文档。

参数与配置

常用参数

• LANHU_COOKIE：必需项，蓝湖网页版请求头里的 Cookie。
• SERVER_HOST / SERVER_PORT：服务监听地址与端口，默认 0.0.0.0 和 8000。
• DATA_DIR：数据存储目录，默认 ./data。
• HTTP_TIMEOUT：HTTP 请求超时时间，单位秒，默认 30。
• VIEWPORT_WIDTH / VIEWPORT_HEIGHT：浏览器视口宽高，默认 1920 和 1080。
• DEBUG：调试模式，取值 true 或 false。
• FEISHU_WEBHOOK_URL：飞书机器人 webhook，可以走环境变量，也可以改代码里的 DEFAULT_FEISHU_WEBHOOK 常量。
• FEISHU_USER_ID_MAP：用户 ID 映射字典，@提醒功能用它做匹配。
• LANHU_USER_NAME / LANHU_USER_ROLE：用户姓名与角色，HTTP 模式下等价于 URL 上的 name 与 role 查询参数。
• LANHU_DISABLE_SYSTEM_PROXY：设为 1 时，run-stdio 脚本会清除继承的代理并设置 NO_PROXY=*，v1.8.7 为 SOCKS 代理和 IDE 注入代理干扰 httpx 的情况加的开关。

配置文件

仓库里给了两份模板：.env.example 和 config.example.env，前者用于常规部署，后者是更完整的环境变量说明。Docker 部署的编排写在 docker-compose.yml，镜像构建用 Dockerfile。数据与下载产物默认落在 DATA_DIR 指向的目录。几份配置文件之间的加载优先级，仓库里没有说明。

实际使用中的坑

仓库的 Issue 列表里有不少真实故障，挑几条典型的看，它们基本都指向同一个薄弱环节：蓝湖那边的接口和数据结构一变，本地的工具就跟着挂。

• 切图读不出来（已解决）：调用工具返回未查询到切图，可蓝湖页面上明明看得到。原因是蓝湖的 MasterJSON 结构变了，函数 get_design_slices_info 原来从 sketch_data 里遍历 info 数组取切图的路子失效。这条 Issue 有 13 条评论。
• 读不到设计图里的颜色与标注信息（待解决）：有用户直接问能不能读取文本控件的大小、颜色等标注信息，10 条评论，目前没有结论。
• Trae 连接报 Session not found（已解决）：让 lanhu-mcp 帮忙分析 UI 时，lanhu_get_designs 调用失败，10 条评论。
• store_schema_revise 失败: 版本数据不存在（待解决）：结构化导出链路卡在这里，图层、文本等信息拿不到。有人用 MasterGO 的蓝湖插件上传设计稿后必现，因为该插件没有「设计图转代码」开关；换 figma 上的蓝湖插件并打开这个开关，就能正常拿到结构化 HTML/CSS。另有用户接入 GPT-5.2 后，设计图列表和下载正常，结构化导出同样失败。

几个同类怎么选

两个对比项解决的不是同一件事，放在这里只是给做 MCP 选型的读者一个参照。lanhu-mcp 真正的短板是它的全部能力都绑在蓝湖这一件事上：一旦团队改用 figma 或 MasterGO 的原生流程，或者你不愿意维护一份随时会过期的 Cookie，这个项目就帮不上忙，而对比项都不依赖某个在线账号。反过来，如果你的需求和设计稿就躺在蓝湖里，它能省掉的那段人工抄写没有别的替代。

合规限制

lanhu-mcp 用的是你自己的蓝湖 Cookie，请求的是蓝湖的接口，读到的是团队账号本来就有权访问的内容。这类工具只适合在自有账号、自有项目或已获得明确授权的目标上使用。拿别人的 Cookie 跑，或者越权读取不属于你的项目里的设计稿和需求文档，可能违反蓝湖的服务条款，也可能带来法律与平台规则层面的风险；把切图和源码交付物二次分发，还要看原始设计资产的授权范围。

适合谁

适合正在用蓝湖做需求与设计交付、团队里已经有 Cursor、Claude Code、Windsurf、Trae 这类 MCP 客户端的团队。开发想让 AI 直接读需求文档的字段规则，测试想从同一份需求里生成用例，前端想拿到尺寸颜色参数和切图资源包，这三种人用同一台服务就能各自取到自己要的东西。

不适合两种情况。一种是设计资产不在蓝湖上，这个项目的能力全部围绕蓝湖构建，换平台就得换工具。另一种是团队不愿意把蓝湖账号的 Cookie 放到服务端，HTTP 模式下 Cookie 存在运行环境里，这是使用前必须先和团队确认的事。模型侧也要提前确认：用的是纯文本模型的话，图像分析相关的工具跑不起来。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 9.0 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。