Lanhu MCP Server 实战演示指南:从 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():
- URL 校验:
parse_design_reference()(lanhu_design/service.py)要求链接必须是https://lanhuapp.com的完整设计 URL,并从 fragment 中解析pid、tid、image_id等参数; - 拉取设计信息:调用
https://lanhuapp.com/api/project/image获取设计图版本列表; - 版本选择与原始数据归一化:
select_version()支持指定版本或latest;原始 JSON 经normalize_design()归一化为标准结构; - 快照缓存:以 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() 完成:
- 素材筛选:
kind参数支持exported_asset(设计师导出的切图)、render_fallback(渲染兜底)、image_fill(图片填充)与all; - 变体选择:
select_variants()根据format_preference(如original)选择最合适的资源变体; - 下载与校验:
download_assets()按target_dpr(默认 2.0,适配 Retina 屏)下载原分辨率素材,随后validate_downloaded_variant()对每个文件校验图片尺寸/哈希,失败项单独计入failed列表,而不是静默丢弃; - 打包交付:生成
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。