Lanhu MCP Server 实战演示指南:从 AI 需求分析到跨团队协作的完整工作流

原创2026-10-04 10:51:131,681 阅读
文章标签:MCP 服务AI 应用人工智能开发工具

Lanhu MCP Server 实战演示指南:从 AI 需求分析到跨团队协作的完整工作流

本篇指南以仓库 DEMO.md 为核心骨架,围绕 Lanhu MCP Server 的五大典型使用场景展开:AI 自动分析蓝湖 Axure 需求文档、团队知识库与任务留言板、UI 设计稿批量查看、切图智能下载,以及不同 AI 客户端之间的跨角色协作。读完本文,你将掌握每个场景的对话式操作方式、底层工具调用链与源码实现依据,并能 3 步完成环境启动、连接 Cursor/Windsurf 等 MCP 客户端,把"需求分析一次、全员复用"真正落地到日常研发流程中。

快速体验:3 步跑通 Lanhu MCP Server

在进入具体场景之前,先完成环境的安装与客户端接入。以 Linux/macOS 为例(Windows 对应使用 .bat 脚本),操作如下:

# 1. 克隆项目
git clone https://gitcode.com/gh_mirrors/la/lanhu-mcp
cd lanhu-mcp

# 2. 快速启动(自动安装依赖、引导配置 Cookie)
./quickstart.sh  # Mac/Linux
# 或 quickstart.bat  # Windows

# 3. 在 AI 客户端(如 Cursor、Claude Code、Windsurf)的 MCP 配置中添加:
{
  "mcpServers": {
    "lanhu": {
      "url": "http://localhost:8000/mcp?role=Developer&name=YourName"
    }
  }
}

⚠️ 注意:部分 AI 工具不支持 URL 中文参数,建议使用英文的 role 与 name。

启动后即可开始对话,例如直接向 AI 发送:

帮我看看这个需求文档:[粘贴蓝湖URL]

三个关键配置点需要特别说明:

  • role(角色)参数:用于标识当前用户的团队角色。从源码看,服务器在 lanhu_mcp_server.py 的 get_user_info() 中通过 FastMCP 的 get_http_request 读取请求查询参数 role 与 name,随后用于协作追踪与 @提醒。角色会被 normalize_role()(lanhu_mcp_server.py)归一化到内部标准角色,合法的内置角色集合 VALID_ROLES 定义在 lanhu_mcp_server.py:<a href="https://link.gitcode.com/i/b3ceb5edadfee21888f478675847cb90" target="_blank">"后端", "前端", "客户端", "开发", "运维", "产品", "项目经理"],并可通过 [lanhu_mcp_server.py 的 ROLE_MAPPING_RULES 扩展关键词映射(例如 php后端、iOS开发 等别名会归一到标准角色)。
  • name(姓名)参数:用于协作追踪与 @提醒,留言时 mentions 需要匹配真实姓名。
  • Cookie 配置:必须先在 config.example.env(或 .env)中配置 LANHU_COOKIE,获取方式参考 GET-COOKIE-TUTORIAL.md。quickstart.sh 会检查 Python 版本(需 3.10+)、创建虚拟环境并以国内镜像优先安装依赖。

场景一:需求文档分析(开发视角)

用户输入

把蓝湖产品文档的分享链接直接交给 AI:

帮我看看这个登录模块的需求:
https://lanhuapp.com/web/#/item/project/product?tid=xxx&pid=xxx&docId=xxx

STAGE 1:全局扫描

AI 首先对文档做整体扫描,输出模块结构总览,并询问用户希望以何种视角分析:

老板,二狗收到!正在快速浏览所有页面...

📊 文档结构分析:
| 模块名 | 包含页面 | 核心功能 | 业务流程 |
|--------|---------|---------|---------|
| 用户认证 | 登录、注册、找回密码 | 用户认证 | 登录→首页 |
| 个人中心 | 个人信息、修改密码 | 用户管理 | 查看/编辑资料 |
| 订单管理 | 订单列表、订单详情 | 订单处理 | 查询/取消订单 |

请问您希望二狗以什么角度来分析?

1️⃣ 【开发视角】- 详细技术文档 ⭐推荐
   适合:开发人员看需求,准备写代码
   输出:详细字段规则、业务流程图、异常处理

2️⃣ 【测试视角】- 测试用例和验证点
   适合:测试人员写测试用例

3️⃣ 【快速探索】- 全局评审视角
   适合:需求评审会议、快速了解需求

这三种视角与 README.md 描述的三种分析模式一一对应:开发视角输出详细字段规则、业务逻辑、全局流程图;测试视角输出测试场景、用例、边界值、校验规则;快速探索输出核心功能概览、模块依赖、评审要点。

用户选择

选开发视角,帮我分析"用户认证"模块

STAGE 2:详细分析

AI 针对选定模块输出变更类型识别、核心要点、功能清单、字段规则与待确认事项:

老板,开始分析"用户认证"模块...

🔍 变更类型识别:
- 类型:🔄修改
- 判断依据:文档中提到"优化登录流程"、"新增记住密码功能"
- 结论:在现有登录基础上新增功能

📋 本组核心 3 点:
1. 登录验证:手机号+密码 或 手机号+验证码两种方式
2. 记住密码:新增功能,30天免登录
3. 错误控制:3次失败锁定30分钟

📊 功能清单表:
| 功能点 | 描述 | 输入 | 输出 | 业务规则 | 异常处理 |
|--------|------|------|------|----------|----------|
| 密码登录 | 手机号密码登录 | 手机号/密码/记住我 | 用户token/用户信息 | 验证格式、校验密码 | 3次锁定 |
| 验证码登录 | 手机号验证码登录 | 手机号/验证码 | 用户token/用户信息 | 60秒防重发 | 验证码5分钟过期 |
| 记住密码 | 30天免登录 | 勾选记住我 | 长效token | 设备绑定 | token过期重新登录 |

📋 字段规则表:
| 字段名 | 必填 | 类型 | 长度/格式 | 校验规则 | 错误提示 |
|--------|------|------|-----------|----------|----------|
| phone | ✅ | string | 11位 | 1开头手机号 | "请输入正确的手机号" |
| password | ✅ | string | 6-20位 | 字母+数字 | "密码必须包含字母和数字" |
| code | ✅ | string | 4位 | 纯数字 | "请输入4位验证码" |
| remember | ❌ | boolean | - | true/false | - |

⚠️ 待确认事项:
• ⚠️ 记住密码的token有效期文档说30天,但技术实现建议7天,请产品确认
• ⚠️ 锁定30分钟是否支持手动解锁(如客服介入)?

分析完成!继续分析其他模块吗?

值得注意,这里 AI 将"业务结论"与"待确认事项"分开呈现,这正对应 README.md 强调的核对机制:服务器只负责提取事实,业务语义与用户逐条核对,不把流程提示当成准确率保证。

STAGE 3 & 4:生成交付文档

所有模块分析完毕后,AI 汇总生成完整的需求交付文档:

老板,所有模块分析完毕!现在生成完整需求文档...

# 需求文档总结

## 📊 文档概览
- 总页面数:8页
- 模块数:3个
- 变更类型:🔄修改 2个,🆕新增 1个
- 待确认项:3个

## 🎯 需求性质分析
| 类型 | 模块数 | 模块列表 | 判断依据 |
|------|-------|---------|---------|
| 🔄 修改 | 2 | 用户认证、个人中心 | 文档提到"优化"、"在现有基础上" |
| 🆕 新增 | 1 | 订单管理 | 文档提到"全新功能" |

## 🌍 全局业务流程图

开始
  ↓
[用户打开APP]
  ↓
是否已登录?
  ├─是→ [进入首页]
  └─否→ [显示登录页面]
         ↓
      选择登录方式
         ├─密码登录
         │   ↓
         │ 输入手机号+密码
         │   ↓
         │ 是否勾选记住我?
         │   ├─是→ 生成30天token
         │   └─否→ 生成24小时token
         │       ↓
         │   密码正确?
         │       ├─是→ [登录成功] → [进入首页]
         │       └─否→ 错误次数+1
         │              ↓
         │           错误次数≥3?
         │              ├─是→ [锁定30分钟]
         │              └─否→ [提示重新输入]
         │
         └─验证码登录
             ↓
           [发送验证码]
             ↓
           输入验证码
             ↓
           验证码正确?
             ├─是→ [登录成功] → [进入首页]
             └─否→ [提示验证码错误]

(详细的字段规则、模块说明省略...)

## ⚠️ 待确认事项
1. 记住密码token有效期:文档30天 vs 技术建议7天
2. 账号锁定后是否支持客服手动解锁
3. 订单列表的分页大小:文档未说明

老板,需求文档已整理完毕!开发看完能写代码!

源码印证:四阶段工作流背后的工具链

"全局扫描 → 分组分析 → 反向验证 → 生成交付物"的四阶段工作流(README.md)由一组 MCP 工具驱动(完整工具清单见 README.md):

  • lanhu_list_product_documents:定位原型或需求文档;
  • lanhu_get_pages:获取原型页面列表,是分析需求文档前必调用的工具;
  • lanhu_get_ai_analyze_page_result:分析原型页面内容,长页返回完整图与横向完整的细节分块;
  • lanhu_inspect_requirement_region:按文字、块 ID、分块 ID 或坐标返回局部视觉证据,用于处理"这两个字段""红框处"等模糊指代。

整体服务器基于 FastMCP 构建(mcp = FastMCP("Lanhu Axure Extractor"),见 lanhu_mcp_server.py),并以"二狗"(ErGou)助手人格提供中文交互、TODO 驱动的工作流体验(README.md)。

场景二:团队协作留言板

团队留言板是本项目"打破 AI IDE 孤岛"的核心创新:每个开发者自己的 AI 助手都连接同一个 MCP 服务器,分析结果、踩坑经验可以沉淀为共享知识。

后端开发发布知识库

帮我发个留言,分享一下刚解决的 Redis 问题

标题:Redis连接池配置优化
内容:生产环境遇到 Redis 超时,排查后发现是连接池配置不当。
解决方案:
- maxTotal 调整为 20
- maxIdle 调整为 10
- testOnBorrow 设置为 true
效果:超时率从 5% 降至 0.1%

留言类型:知识库

AI 执行:

老板,已发布知识库!以后团队其他人遇到类似问题,AI 可以直接搜到这个解决方案!

测试人员查询知识

搜索所有关于"Redis"的知识库

AI 返回:

找到 2 条知识库:

1️⃣ Redis连接池配置优化(小王-后端,2025-01-15)
   生产环境遇到 Redis 超时,排查后发现是...

2️⃣ Redis缓存穿透解决方案(小张-后端,2025-01-10)
   使用布隆过滤器解决缓存穿透...

老板,找到这些经验,要查看详情吗?

产品经理发起查询任务

帮我发个留言,@后端小王

标题:请帮忙查询测试环境数据
内容:请帮我查一下 user 表中 status='test' 的用户有多少条?
留言类型:任务
@小王

AI 执行:

老板,留言已发布!

✅ 已发送飞书通知给 @小王
📋 消息类型:任务(安全限制:只能查询,不能修改)

小王的 AI 会收到通知,帮他执行查询~

消息类型设计与安全机制

留言板共支持五种消息类型(README.md),类型决定了搜索策略与生命周期:

类型 用途 搜索策略 生命周期
📢 normal 普通通知 按时间衰减 7天后归档
📋 task 查询任务(安全限制:只读) 完成后归档 任务生命周期
❓ question 需要回答的问题 未回答置顶 解答后归档
🚨 urgent 紧急通知 强制推送 24小时后降级
💡 knowledge 知识库(核心) 永久可搜索 永久保存

task(任务)类型有严格的安全边界:允许查询代码位置、数据库表结构、测试方法、TODO 等只读操作;禁止修改代码、删除文件、执行命令、提交代码。

从源码看,消息的发布、检索、@提及与飞书通知是分离实现的:lanhu_say / lanhu_say_list / lanhu_say_detail / lanhu_say_edit / lanhu_say_delete 负责留言的完整生命周期;mentions 参数匹配协作成员,并通过 send_feishu_notification()(lanhu_mcp_server.py)推送飞书机器人通知;lanhu_get_members 则自动记录每个协作者的访问历史(name、role、first_seen、last_seen),实现团队透明化。搜索场景还可以组合 filter_type、search_regex、limit 参数,例如 lanhu_say_list(url='all', filter_type='knowledge', search_regex='测试|test|单元测试', limit=20),避免返回内容过多导致 token 溢出。

场景三:UI 设计稿查看

用户输入

帮我看看首页的设计稿:
https://lanhuapp.com/web/#/item/project/stage?tid=xxx&pid=xxx

AI 执行

AI 先获取该项目的设计图列表,并向用户确认查看范围:

老板,这个项目有 12 张设计图,设计师很用心!

您是要:
1. 全部下载(完整了解UI)
2. 先看关键页面(告诉我哪几张~)

等您指示!

用户选择

先看首页、登录页、个人中心这三张

AI 返回

老板,设计稿已下载!

📊 共 3 张设计图:
1. 首页设计 (1920x1080)
2. 登录页 (750x1334)
3. 个人中心 (750x1334)

[图片1:首页设计]
[图片2:登录页]
[图片3:个人中心]

这些设计很不错!需要我分析设计规范或导出切图吗?

源码印证:设计稿下载的底层实现

设计稿查看的入口工具是 lanhu_get_designs(查看设计稿前必调用)与 lanhu_get_ai_analyze_design_result。其底层实现在 lanhu_design/service.py 的 DesignService.prepare():

  1. URL 校验:parse_design_reference()(lanhu_design/service.py)要求链接必须是 https://lanhuapp.com 的完整设计 URL,并从 fragment 中解析 pid、tid、image_id 等参数;
  2. 拉取设计信息:调用 https://lanhuapp.com/api/project/image 获取设计图版本列表;
  3. 版本选择与原始数据归一化:select_version() 支持指定版本或 latest;原始 JSON 经 normalize_design() 归一化为标准结构;
  4. 快照缓存:以 schema 版本、项目、团队、设计、版本、原始数据哈希等组合生成快照 ID,并将参考图与归一化 JSON 原子写入本地缓存目录,之后同一快照可直接复用,避免重复下载。

prepare() 还会返回画布尺寸、字体需求(font_requirements)、节点总数与资源统计等元信息,供大模型结合画面理解设计语义——服务器提供确定性证据,业务命名与组件语义由大模型结合视觉和工程约定决定,这正是 lanhu_design/media.py 文档字符串所强调的"不根据图层名称推断组件语义"的设计原则。

场景四:切图智能下载

用户输入

帮我下载"首页设计"的所有切图

AI 执行流程

1. 环境检测

正在检测项目类型...
✅ 检测到 package.json,这是一个 React 项目
✅ 发现 src/assets/images/ 目录

2. 智能规划

二狗的下载计划:
📁 输出目录:src/assets/images/slices/homepage/
🏷️ 命名规则:基于图层路径的语义化命名
📦 共发现 23 个切图

3. 批量下载

开始下载...
[1/23] ✅ status_bar_battery_icon_26x14.png
[2/23] ✅ navbar_logo_120x40.png
[3/23] ✅ btn_primary_background_200x50.png
...
[23/23] ✅ footer_wechat_qrcode_100x100.png

✅ 全部完成!23 个切图已保存到:
   src/assets/images/slices/homepage/

老板,切图都下载好了!文件名都是语义化的,直接用吧~

源码印证:切图的"检测 → 规划 → 下载 → 校验"闭环

演示中的三步流程对应两类核心工具:lanhu_get_design_slices 获取切图信息(识别图标、素材),lanhu_export_design_assets 执行实际下载与校验。后端由 lanhu_design/service.py 的 DesignService.export() 完成:

  1. 素材筛选:kind 参数支持 exported_asset(设计师导出的切图)、render_fallback(渲染兜底)、image_fill(图片填充)与 all;
  2. 变体选择:select_variants() 根据 format_preference(如 original)选择最合适的资源变体;
  3. 下载与校验:download_assets() 按 target_dpr(默认 2.0,适配 Retina 屏)下载原分辨率素材,随后 validate_downloaded_variant() 对每个文件校验图片尺寸/哈希,失败项单独计入 failed 列表,而不是静默丢弃;
  4. 打包交付:生成 manifest.json 与 bundle.zip,交付时通过 MCP 读取 bundle_resource,并在客户端用 python -m lanhu_design.install 安装到目标工程目录。

对应测试 tests/test_design_slices.py 验证了切图信息的提取逻辑,例如识别 isAsset 标记的素材图层及其 png_xxxhd 等倍率图片。此外 lanhu_design/media.py 定义了严格的资源边界:单文件不超过 64 MiB、解码像素上限 8000 万、标注节点上限 500,保证下载与解析过程可控、防资源炸弹。

场景五:跨 AI 协作

这是前四个场景能力的组合:不同角色、不同 AI 客户端(Cursor、Windsurf、Claude Code)通过同一个 MCP 服务器实现上下文共享。

后端 AI(小王)分析需求后

# 小王的 Cursor
@测试小李 登录接口分析完了

标题:登录接口需求分析结果
内容:
- 手机号必填,11位数字
- 密码6-20位,必须包含字母+数字
- 验证码4位纯数字,5分钟有效
- 错误3次锁定30分钟

[消息类型:knowledge]

测试 AI(小李)收到通知

# 小李的 Windsurf
[收到飞书通知] 小王 @了你

查看留言详情...

太好了!有了小王的分析,我可以直接写测试用例:

✅ 正向场景:
- 正确手机号+密码 → 登录成功
- 正确手机号+验证码 → 登录成功

⚠️ 异常场景:
- 错误密码3次 → 锁定30分钟
- 验证码过期 → 提示重新获取
- 边界值测试:密码5位/21位 → 提示格式错误

不用重新看需求文档了,省了好多时间!

该场景的关键机制在场景二中已铺垫:knowledge 类型消息永久可搜索、@提醒 触发飞书通知、mentions_me 判断消息是否与自己相关(lanhu_mcp_server.py 的 _check_mentions_me() 会先用 normalize_role() 归一化双方角色再匹配)。由此实现 README 中描述的目标:需求分析一次、全员复用,踩坑经验永久保存,打破"每个 AI 都在重复工作"的上下文断层。

性能对比与用户反馈

演示文档 DEMO.md 给出了一组典型场景下的对比示例(数据为演示示意,实际收益取决于文档复杂度、网络与模型能力):

场景 传统方式 使用 Lanhu MCP 节省时间
需求分析 30分钟手动阅读 5分钟AI分析 83%
查找历史经验 10分钟搜聊天记录 10秒搜知识库 98%
设计稿下载 手动下载+重命名15分钟 AI自动下载30秒 96%
跨角色沟通 开会/消息反复确认20分钟 AI直接查询5分钟 75%

用户反馈:

"以前每个人的 AI 都要重新分析需求,现在一次分析,全员复用,效率提升太明显了!"—— 后端开发 小王

"测试人员的 AI 可以直接用开发的分析结果写用例,不用重复理解需求了"—— 测试工程师 小李

"踩过的坑保存成知识库,新人的 AI 也能查到,避免重复踩坑"—— 技术 Leader 老张

使用前提与注意事项

  • 必须使用支持视觉能力的 AI 模型(如 Claude、GPT、Gemini、Kimi、Qwen、DeepSeek 等视觉版本)。需求分析与设计稿理解高度依赖图像识别能力,纯文本模型无法正常使用(README.md)。
  • Cookie 凭证:服务通过公开网页接口与蓝湖平台交互,需使用合法账号的 LANHU_COOKIE;请勿将含 Cookie 的配置文件提交到公开仓库,建议在内网部署或配置防火墙(README.md)。
  • URL 参数注意:MCP 配置 URL 中的 role / name 参数部分 AI 工具不支持中文值,建议使用英文(如 Developer、Tester、Product)。
  • 长页处理:full 模式遇到长页会保留原完整截图并默认附加前 4 张细节分块,若提示仍有后续分块,可用 tile_offset 继续读取,tile_limit 每页最多 12(README.md)。
  • 按需启动(stdio):本地客户端(Cursor、Claude Code 等)也可配置 run-stdio.sh 按需拉起服务,无需常驻 HTTP 进程;此时通过 LANHU_USER_ROLE、LANHU_USER_NAME 环境变量传入角色与姓名(README.md)。

小结

从 DEMO.md 的五个演示场景可以看到 Lanhu MCP Server 的完整能力闭环:需求分析(场景一)产出结构化交付物,留言板(场景二)沉淀知识与任务,设计稿查看(场景三)与切图下载(场景四)打通设计与工程,而跨 AI 协作(场景五)则将前三者的成果在团队层面复用。结合 lanhu_mcp_server.py 与 lanhu_design/service.py 的源码,可以确认每条演示路径背后都有对应的 MCP 工具与确定性校验逻辑支撑。更多配置细节可参考 README.md、config.example.env 与 DEPLOY.md。

登录后查看全文
lanhu-mcp