1. 蓝湖需求到用例的断点到底卡在哪蓝湖Lanhu在不少团队里承担着「设计稿 需求说明 交互标注」三合一的角色产品把原型和批注往上一挂测试就得开始啃文档。问题在于蓝湖本身是个协作展示平台它不产出结构化数据你没法像查数据库那样把「某个字段的长度限制」「某个按钮的跳转条件」直接捞出来。于是测试同学的日常就变成了打开蓝湖页面一页页翻设计稿把批注复制到 Excel再凭经验补异常场景最后拼成一份用例。这条链路里最耗时的不是写用例本身而是「信息搬运 需求理解」。一个中等复杂度的需求文档光是把散落在各个画板上的交互说明整理成条目就得花掉大半天。更麻烦的是遗漏——蓝湖的批注有时候藏在某个不起眼的弹窗里人工翻的时候很容易漏掉等到提测才发现「这个异常分支没覆盖」。MCPModel Context Protocol的出现给了这条链路一个新的解法。它的核心思路是把蓝湖当成一个「数据源」通过一个本地 MCP 服务把蓝湖的页面内容、批注、字段说明抓取出来转成结构化文本喂给 AI让 AI 完成需求分析和用例设计。这样测试同学的角色就从「搬运工」变成了「审核者」——AI 出初稿你负责校验和补充。我试过把这套流程跑通之后一个包含 3 个主流程、12 个字段校验点的需求从打开蓝湖到拿到一份可用的用例初稿大概 10 分钟出头。当然初稿不能直接用但覆盖度已经能到七八成剩下的就是针对业务特有的边界做补充。这套方案适合谁如果你所在的团队用蓝湖做需求管理测试需要频繁从设计稿里提取校验规则又不想每次都手动整理那这套 MCP AI 的链路值得搭一次。它不替代你的测试思维只是把重复劳动压缩掉。下面我会从环境准备开始把蓝湖 MCP 服务的部署、配置、字段映射规则、验证方法以及实际跑下来会遇到的坑一步步写清楚。你照着做应该能在一个下午之内把链路跑通。2. 蓝湖 MCP 服务部署与 TaoToken 接入前置在动手之前先把两个东西准备好一个是蓝湖 MCP 服务本身它负责从蓝湖抓数据另一个是 AI 侧的接入通道这里用 TaoToken 来做模型调用。两者是独立的MCP 服务跑在本地TaoToken 提供模型能力AI 客户端Cursor、Claude Code 等把两边串起来。2.1 蓝湖 MCP 服务的环境依赖蓝湖 MCP 是一个开源项目仓库地址在 GitHub 上dsphper/lanhu-mcp。它对环境的要求不算高但有几个点必须满足否则后面会报错。首先是 Python 版本要求 3.10 及以上。我建议用虚拟环境避免和你机器上其他项目的依赖打架。创建虚拟环境的命令python -m venv lanhu-env # Windows lanhu-env\Scripts\activate # macOS / Linux source lanhu-env/bin/activate激活之后把项目克隆下来git clone https://github.com/dsphper/lanhu-mcp.git cd lanhu-mcp pip install -r requirements.txt如果requirements.txt里的依赖装不全可以手动补一条命令把核心依赖一次性装上python -m pip install fastapi uvicorn requests python-dotenv playwright beautifulsoup4 pydantic这里有个关键点蓝湖 MCP 依赖 Playwright 来渲染页面因为蓝湖的设计稿是动态加载的纯 requests 抓不到完整内容。所以必须装浏览器引擎python -m playwright install chromium另外如果你需要把生成的用例导出成 Excel还得装 openpyxlpython -m pip install openpyxl装完之后用pip list检查一下确认 fastapi、uvicorn、playwright、openpyxl 都在列表里。2.2 配置蓝湖 Cookie 与 .env 文件蓝湖 MCP 要能访问你的蓝湖项目必须带上你的登录态。这个登录态就是 Cookie。在项目根目录下有一个.env文件如果没有就手动创建内容如下LANHU_COOKIE你的蓝湖Cookie值 LANHU_BASE_URLhttps://lanhuapp.comCookie 的获取方式登录蓝湖网页版打开开发者工具F12在 Network 面板里找任意一个请求复制请求头里的 Cookie 字段。注意这里有个坑——不要在火狐浏览器里取 Cookie火狐的 Cookie 格式和蓝湖 MCP 的解析逻辑有兼容问题取出来会认证失败。用 Chrome 或 Edge 取。Cookie 值要用英文双引号包裹因为里面可能包含特殊字符。复制的时候确保是「纯净」的不要带多余的空格或换行。2.3 TaoToken 接入配置MCP 服务负责抓数据AI 负责分析数据中间需要一个模型调用通道。TaoToken 提供的就是这个通道它的 API 地址是https://taotoken.net/api兼容 OpenAI 的接口格式所以 Cursor、Claude Code 这类工具都能直接接。如果你用的是 Cursor在设置里找到模型配置把 Base URL 填成https://taotoken.net/apiAPI Key 填你在 TaoToken 控制台生成的 KeyModel ID 填你要用的模型比如claude-sonnet-4-20250514或gpt-4o。这三件套——Base URL、Key、Model ID——缺一不可后面在 MCP 配置里也会用到同样的逻辑。TaoToken 的 API Key 在控制台的 API Keys 页面生成生成后复制保存页面上不会再次显示完整 Key。如果你还没生成可以去https://taotoken.net/api-keys操作。2.4 启动蓝湖 MCP 服务配置完成后启动服务python lanhu_mcp_server.py看到类似Uvicorn running on http://0.0.0.0:8000的输出说明服务起来了。默认端口是 8000MCP 的访问路径是/mcp。这里要注意每次使用前都要确保这个服务在运行。如果你关了终端或者重启了机器需要重新激活虚拟环境再启动。我踩过的坑就是忘了启动服务然后在 Cursor 里调用 MCP 一直报连接失败排查了半天才发现是服务没开。3. 可复制的 MCP 配置与蓝湖字段映射规则服务跑起来之后下一步是让 AI 客户端能调用它。不同的客户端配置方式略有差异但核心都是填三样东西MCP 服务的地址、传输方式、以及可选的参数。3.1 Cursor 的 MCP 配置片段在 Cursor 里MCP 配置通常放在settings.json或者通过 UI 添加。如果你手动编辑配置文件路径一般在~/.cursor/mcp.jsonmacOS/Linux或%APPDATA%\Cursor\mcp.jsonWindows。配置内容如下{ mcpServers: { lanhu-mcp: { transport: http, url: http://localhost:8000/mcp?roletesterDevelopernamelucia } } }这里的role和name是查询参数role可以填testerDevelopername填你自己的标识方便在日志里区分调用来源。transport必须是http因为蓝湖 MCP 走的是 HTTP 协议而不是 stdio。配置保存后重启 Cursor在对话窗口里应该能看到 MCP 工具已经加载。你可以输入mcp来触发工具调用。3.2 Claude Code 的接入方式如果你用的是 Claude Code配置方式类似但文件位置不同。Claude Code 的 MCP 配置一般在项目根目录的.mcp.json或者全局配置里。内容格式{ mcpServers: { lanhu-mcp: { type: http, url: http://localhost:8000/mcp?roletesterDevelopernamelucia } } }注意 Claude Code 里字段名是type而不是transport这是两个客户端的小差异。配置好之后Claude Code 会在启动时自动连接 MCP 服务。同时Claude Code 的模型调用也要指向 TaoToken。在 Claude Code 的配置里把 API Base 设成https://taotoken.net/apiKey 用 TaoToken 生成的 Key。这样 Claude Code 既能调 MCP 抓蓝湖数据又能用 TaoToken 的模型做分析。3.3 蓝湖字段映射规则MCP 服务从蓝湖抓回来的数据是原始的结构AI 要能理解需要一套映射规则。这套规则的核心是把蓝湖的页面元素对应到测试关注的信息上。蓝湖的设计稿里每个画板artboard代表一个页面或一个弹窗画板里的图层layer对应具体的 UI 元素。批注annotation则挂在图层上描述交互逻辑或字段约束。MCP 抓取后会把这些信息转成文本大致结构是蓝湖原始字段映射后的测试信息说明artboard.name测试模块画板名称作为模块划分依据layer.name测试对象图层名称对应按钮、输入框等annotation.content校验规则/交互说明批注内容提取为约束条件layer.type元素类型区分输入框、按钮、文本等artboard.children页面元素清单用于遍历生成用例举个例子蓝湖里一个画板叫「登录页」里面有个图层叫「手机号输入框」批注写着「11 位数字必填格式校验」。MCP 抓取后AI 能识别出模块登录页对象手机号输入框规则11位数字必填格式校验。基于这个AI 就能生成对应的用例正常输入 11 位手机号、输入 10 位、输入非数字、留空提交等。这套映射规则不是硬编码的而是通过 prompt 引导 AI 去理解。你在调用时把抓取到的原始文本连同分析要求一起发给模型模型会按照你给的格式输出用例。3.4 调用时的 Prompt 模板配置好之后实际调用时的 prompt 很关键。下面这个模板可以直接用mcp 请帮我分析这个需求文档蓝湖链接 基于以上蓝湖设计稿完成【专家书面评审】包含 1. 需求合理性与完整性 2. 交互逻辑与流程闭环 3. 字段约束与数据校验 4. 异常场景与边界条件覆盖 5. 可测性与测试风险点 最后输出一份标准评审报告 完整功能测试用例格式 用例编号 | 测试模块 | 测试场景 | 输入/操作 | 预期结果 | 优先级 | 测试类型这个模板的好处是把「评审」和「用例生成」拆成两步AI 先做需求分析再基于分析结果生成用例逻辑上更连贯。如果你只要用例可以把评审部分去掉但保留评审能让 AI 的思考更完整用例质量会高一些。4. 验证请求与提取准确率实测配置和 prompt 都准备好之后得实际跑一遍看看提取准确率和用例覆盖度到底怎么样。这一步不能省因为蓝湖的文档质量参差不齐有些批注写得很随意AI 不一定能准确理解。4.1 准备一个真实需求做验证我拿一个电商项目的「优惠券领取」需求做验证。这个需求在蓝湖上有 2 个画板一个是优惠券列表页一个是领取弹窗。批注里写了领取条件、库存限制、每人限领数量、过期时间等规则。先把蓝湖链接拿到然后在 Cursor 里输入mcp 请分析这个蓝湖需求https://lanhuapp.com/web/#/item/project/xxx 重点提取 1. 所有字段的校验规则 2. 领取流程的交互步骤 3. 异常场景库存不足、重复领取、过期 输出格式 - 需求评审要点 - 测试用例表格发送之后MCP 服务会去抓取蓝湖页面内容然后交给模型分析。整个过程大概 30 秒到 1 分钟取决于文档大小和模型响应速度。4.2 提取结果与人工核对AI 返回的结果里需求评审部分列出了 5 个风险点其中 3 个是我原本没想到的比如「优惠券过期后列表是否还展示」「领取失败后的提示文案是否明确」。用例部分生成了 18 条覆盖了正常领取、库存不足、重复领取、过期领取、网络异常等场景。我拿这 18 条和人工整理的用例做对比发现 AI 覆盖了 14 条遗漏的主要是「UI 层面的校验」和「多端一致性」这类需要结合具体实现判断的场景。准确率方面AI 生成的用例里有 2 条预期结果写得不够精确比如「提示错误」没有说明具体文案需要人工补充。整体来看提取准确率在 80% 左右用例覆盖度在 75% 到 85% 之间。这个数字不算完美但考虑到它把「翻文档 整理条目」的时间从几小时压缩到几分钟性价比已经很高了。4.3 提高准确率的几个技巧如果你想让 AI 的输出更准可以在 prompt 里加一些约束。比如注意 - 字段校验规则必须从批注原文提取不要自行推断 - 异常场景要区分「前端校验」和「后端校验」 - 用例的预期结果要具体到文案或状态变化 - 如果批注信息不足标注「需人工确认」而不是猜测另外蓝湖的批注如果写得太简略AI 很难提取出有效信息。这种情况下可以在调用前先人工补充一下批注或者在 prompt 里让 AI 把不确定的地方列出来你再针对性补充。4.4 导出用例到 Excel如果你需要把用例导出成 Excel蓝湖 MCP 支持这个功能。在 prompt 里加上请把生成的用例导出为 Excel 文件保存到当前目录。MCP 服务会调用 openpyxl 生成 xlsx 文件。导出后的文件里用例按模块分 sheet每行一条用例列对应你指定的字段。这个功能在需要把用例导入测试管理平台时特别有用。5. 常见报错排查与配置校验这套链路涉及多个组件任何一个环节出问题都会导致调用失败。下面是我实际遇到过的几个典型报错以及对应的排查方法。5.1 401 认证失败报错信息通常是401 Unauthorized或者Cookie invalid。原因基本是蓝湖 Cookie 过期或格式不对。排查步骤先确认.env文件里的LANHU_COOKIE是不是最新的。蓝湖的 Cookie 有效期不长可能几天就失效了。重新登录蓝湖用 Chrome 取一次新 Cookie替换后重启 MCP 服务。如果换了新 Cookie 还是 401检查一下 Cookie 是不是从火狐取的。火狐的 Cookie 格式和蓝湖 MCP 的解析逻辑不兼容换成 Chrome 或 Edge 重新取。5.2 local proxy failed / 连接被拒绝报错信息类似local proxy failed或Connection refused。这通常是 MCP 服务没启动或者端口被占用。先确认python lanhu_mcp_server.py是不是在运行。如果终端里没有Uvicorn running的输出说明服务没起来。重新激活虚拟环境再启动。如果服务在运行但还是连不上检查端口 8000 是不是被其他程序占用了。用netstat -ano | findstr 8000Windows或lsof -i :8000macOS/Linux看一下。如果被占用可以改 MCP 服务的端口同时更新客户端配置里的 URL。5.3 reading choices 报错这个报错通常出现在 AI 客户端解析 MCP 返回数据的时候信息类似error reading choices。原因是 MCP 返回的数据格式和客户端期望的不一致。排查方法先单独测试 MCP 服务是否正常。用 curl 直接请求curl http://localhost:8000/mcp?roletesterDevelopernamelucia如果返回的是正常的 JSON 数据说明 MCP 服务没问题问题出在客户端配置。检查客户端里的transport或type字段是不是写成了httpURL 是不是完整。如果 curl 也报错说明 MCP 服务本身有问题。检查.env配置和 Playwright 浏览器引擎是否装好。python -m playwright install chromium这条命令如果没执行MCP 抓取页面时会失败。5.4 OAuth 相关报错如果你在 Claude Code 里看到 OAuth 相关的报错比如OAuth token expired这通常是模型调用通道的认证问题不是 MCP 的问题。检查 TaoToken 的 API Key 是不是正确填在了 Claude Code 的配置里。Base URL 应该是https://taotoken.net/apiKey 是你在控制台生成的。如果 Key 过期或额度用完也会报类似的错。去 TaoToken 控制台确认一下 Key 的状态。5.5 配置校验清单为了避免反复踩坑我把关键配置项整理成一个校验清单每次搭环境时对照检查检查项正确值常见错误Python 版本3.103.9 及以下会缺依赖虚拟环境已激活未激活导致依赖装到全局Playwright 引擎chromium 已安装未安装导致抓取失败.env 文件Cookie 用双引号包裹单引号或裸值导致解析失败Cookie 来源Chrome/Edge火狐 Cookie 不兼容MCP 服务运行在 8000 端口未启动或端口被占用客户端 transporthttp写成 stdio 会连接失败TaoToken Base URLhttps://taotoken.net/api漏掉 /api 路径这张表里的每一项我都至少踩过一次尤其是 Cookie 来源和 transport 字段最容易出错。6. 把链路固化下来从临时脚本到日常工具跑通一次不难难的是让它成为日常可用的工具。我的做法是把这套流程固化成一个「启动脚本 固定 prompt」的组合每次用的时候不用重新想配置。启动脚本负责激活虚拟环境、启动 MCP 服务、检查端口。Windows 下可以写一个.bat文件echo off call lanhu-env\Scripts\activate python lanhu_mcp_server.pymacOS/Linux 下写一个.sh#!/bin/bash source lanhu-env/bin/activate python lanhu_mcp_server.py固定 prompt 则存成一个文本文件用的时候直接复制。我习惯把 prompt 分成两个版本一个「快速版」只生成用例一个「完整版」带评审报告。快速版适合需求简单、时间紧的时候用完整版适合复杂需求需要深入分析的时候用。另外蓝湖 MCP 的 Cookie 会过期我建议在脚本里加一个提醒或者每周固定检查一次。如果团队里多人用可以把这个服务部署在一台内网机器上大家共用避免每个人都要配一遍环境。最后说一个实际使用中的经验AI 生成的用例不要直接导入测试管理平台先人工过一遍。重点看三类问题——预期结果是否具体、异常场景是否遗漏、优先级是否合理。过一遍之后用例的可用度会明显提升。这套链路的价值不在于「完全替代人工」而在于把人工从重复劳动里解放出来专注于真正需要判断力的部分。如果你在配置过程中遇到问题可以先检查 MCP 服务是否正常响应再确认 TaoToken 的 Key 和 Base URL 是否正确。接入文档在https://taotoken.net/docAPI Key 在https://taotoken.net/api-keys模型对话入口在https://taotoken.net/chat。需要长期跑编码和 Agent 任务的话Coding Plan 在https://taotoken.net/coding-plan。