企业官网建设流程全解析

“打开 Cursor 让 Agent 写页面，写完总要被设计师追着问一句‘还原了吗’”，这个画面我相信很多前端都熟。不是我们不想还原，而是设计标注在蓝湖里，AI 看不到，信息全靠人肉搬运，搬一次漏一次。把 Cursor 接到蓝湖上之后，Agent 能直接读设计稿的图层、尺寸、配色和字号数据，还原度自己心里有数，设计师也终于不用追着问了。这篇文章就把我怎么做到的、中间踩过哪些坑，完整拆给你。

1. 先搞清楚这事的价值：让 AI 真正“看见”设计稿

1.1 设计师那句“还原了吗”，到底在问什么

蓝湖本身不是一个普通的图片托管平台，它的核心价值是“标注”。设计师上传一张设计稿，通过标注工具可以标出每个元素的宽度、高度、圆角、颜色、字号、行高、内外边距，甚至可以直接生成下载切图的资源地址。这些数据本质上就是前端写代码时需要的那套参数：布局尺寸、视觉样式、交互状态、导出资源。

但在很长一段时间里，这套数据和 Cursor 之间是割裂的。我写页面时的流程通常是：切到蓝湖网页，找到对应画板，眯着眼睛看标注，记住几个关键值，再切回 Cursor 写代码。一个页面涉及几十个节点，靠“看”是记不住的，于是只能来回切窗口。更麻烦的是，如果设计稿在评审后又改了，蓝湖上的标注更新了，但我的代码还停留在旧版本，最后被设计师质问“还原了吗”时，我甚至没法第一时间确认自己到底还原到什么程度。

说白了，那句话背后是信息不对称。设计师以为前端能看到最新标注，前端却可能还在凭记忆写样式，最后全凭肉眼比对。问题不在态度，在于链路断了——设计标注在蓝湖，AI 编程工具却读不到。

1.2 接入之后工作流变成什么样

把 Cursor 接到蓝湖之后，整个协作流程发生了很实际的变化。设计师还是照常上传蓝湖，标注照常生成，但前端这边不再需要手动搬运数据。我在 Cursor 里打开项目代码，通过 MCP 工具直接拉取蓝湖画板上的标注信息，Agent 写代码时能参考真实的设计数据，而不是凭空猜测。

现在我的工作流是这样的：设计师上传新设计稿并标注 → 我在 Cursor 里让 Agent 调用 MCP 工具读取对应 boards 的数据 → 写出组件样式，把标注里的颜色、字号、间距直接映射成代码值 → 写完再让 Agent 拉取一次标注做差异对比，生成一份“标注值 vs 实际值”的清单，确认没问题再回复设计师。

这个流程最大的变化是：还原度的判断从“主观视线对比”变成了“客观数据比对”。我不需要再靠感觉回答“还原了吗”，打开差异清单就能直接说“主色一致、字号一致、间距差 2px 已经修正”。设计师也意识到前端拿到的是一份有依据的自检结果，追着问的次数自然就少了。蓝湖在这里面的位置很关键——设计稿本身没变，但它的标注数据被真正用起来了。

2. MCP 是什么，为什么蓝湖能接到 Cursor 上

2.1 用大白话理解 MCP

MCP 的全称是 Model Context Protocol，模型上下文协议。听起来抽象，你可以把它理解成给 AI 工具插上的一根“标准电源线”。Cursor 本身是通用模型，它只知道行业里常见的代码模式，但它不知道你公司的蓝湖里有哪些设计稿，也不知道某个画板的具体标注。MCP 解决的就是这个“数据访问”问题：某个服务方通过统一的协议，把数据接口暴露给 AI 客户端，客户端需要时直接调用。

类比生活场景：Cursor 是台手机，MCP Server 是手机上的 App，而协议就是 App Store 的统一安装规范。你不用为了每个数据源单独定制一套接入方式，只要对方实现了 MCP 协议，Cursor 就能识别并调用它暴露的“工具”。这些工具可以是“读取项目列表”“读取画板数据”“查询图层标注”，本质上是把蓝湖的开放能力包装成 AI 能理解并调用的函数。

这种设计的好处在于通用性。MCP 不是 Cursor 私有功能，符合协议的客户端都能接。Cursor 能用，Codex CLI 也能用，如果你后来想换工具，蓝湖侧的 MCP 服务不需要重构，只需要在新工具里做同样的配置。这也是我为什么愿意花一下午把服务搭起来，而不是去给 Cursor 写一个临时脚本。

2.2 接入方案选型：官方桥接还是自建脚本

接到蓝湖的方法，大致有两条路。

第一条是直接用现成的 MCP 桥接服务。如果蓝湖开放平台已经提供了官方 MCP 服务，或者社区有人做了比较稳定的适配，那最省事的做法就是把它配置到 Cursor 里，用 npx 启动包或者远程 SSE 地址接入。好处是零代码、升级由维护方负责，坏处是字段和权限范围不一定符合你的内部约定，遇到公司私有部署或者自定义字段时就有点束手束脚。

第二条是自己写轻量 MCP Server，封装蓝湖开放 API。这个方案的启动成本没那么吓人：一个 Node.js 脚本，用@modelcontextprotocol/sdk注册几个工具，每个工具内部用fetch请求蓝湖开放接口，然后把 JSON 数据塞给 Cursor 的上下文。好处是可控性极高，想暴露哪些项目、哪些字段完全自己说了算，尤其适合公司内多个业务线想统一“以标注为唯一事实来源”的场景。

我最终选了自建，核心原因是想对“工具语义”做裁剪。直接把整张设计稿的所有图层丢给 Agent，很容易撑爆上下文，让模型迷失在无关数据里。自建服务里我可以只暴露“项目列表”“画板列表”“画板标注摘要”这几个高度聚合的工具，让 Agent 拿到的都是有效信息。下文整个落地过程，都是按自建这条路走的，你也可以根据自己情况换成官方方案，核心逻辑完全一致。

3. 实操：部署一个能用的蓝湖 MCP 服务

3.1 准备蓝湖开放平台凭证

动手之前先解决权限问题。蓝湖开放平台会为开发者提供应用凭证，一般是在个人中心或开放平台后台创建应用后拿到 API Key / Secret，部分接口还需要 Token 鉴权。具体入口和名称会随平台改版变化，但思路一样：需要一组能标识“你是这个项目的授权开发者”的密钥，后续所有 MCP 工具发起的 API 请求都带上它。

如果你所在团队用的是企业版蓝湖，建议先找管理员确认数据权限范围。不要一上来就申请全量项目空间权限，能只读你负责的某个项目组就够了，因为 MCP 工具会给 AI 暴露项目列表，权限开得越大，Agent 能看到的敏感设计就越多。公司内部一般都有规范，老老实实按最小权限申请，对大家都安全。

拿到凭证后立刻放进本地环境变量，不要写死在代码里。项目里的.cursor/mcp.json即使被你加入.gitignore，也难保某次手滑提交上去。我习惯在终端里export LANHU_API_TOKEN=xxx再启动 Cursor，或者在 MCP 配置的 env 字段里引用本地绝对路径下的 env 文件，总之别让明文 token 出现在仓库历史里。

3.2 用 Node.js 写一个轻量 MCP Server

项目结构很简单，两个文件就能跑起来：package.json和index.js。依赖安装一个官方 SDK 和校验库即可。

mkdir lanhu-mcp cd lanhu-mcp npm init -y npm install @modelcontextprotocol/sdk zod

接下来是核心代码。我写的这个 Server 只做三件事：读项目列表、读设计稿的画板列表、读画板的具体标注。先把骨架搭出来。

// index.js import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { z } from "zod"; const server = new McpServer({ name: "lanhu-mcp", version: "1.0.0", }); const LANHU_API_BASE = "https://api.lanhuapp.com/api"; const API_TOKEN = process.env.LANHU_API_TOKEN; async function lanhuGet(pathname) { const res = await fetch(`${LANHU_API_BASE}${pathname}`, { headers: { Authorization: `Bearer ${API_TOKEN}`, "Content-Type": "application/json", }, }); if (!res.ok) { throw new Error(`Lanhu API error: ${res.status} ${res.statusText}`); } return res.json(); } server.registerTool( "lanhu_get_projects", { description: "获取当前蓝湖账号有权限的项目列表，返回项目的 id、名称、更新时间", }, async () => { const data = await lanhuGet("/projects"); return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }], }; } ); // 省略后面两个工具，见下文说明 const transport = new StdioServerTransport(); await server.connect(transport); console.error("lanhu-mcp server running");

使用 StdioServerTransport 是为了能被 Cursor 以“本地命令”方式拉起：Cursor 启动一个 Node 进程，走标准输入输出和 Server 通信。注意不要把调试日志写到 stdout，这里日志我特意用console.error输出到 stderr，原因就是 stdout 被协议占用了。

3.3 注册工具：到底暴露哪些数据才够用

MCP Server 里最考验设计能力的不是写代码，而是决定“暴露什么”。我见过有人把蓝湖接口一层层全部透传，结果 AI 每次调用都返回几 MB 数据，不仅浪费 token，模型还会被无关图层干扰。

我最终保留了三个工具：

第一个是lanhu_get_projects，负责拿到项目列表，让 Agent 确认“这份设计稿在哪个项目下”。

第二个是lanhu_get_boards，传入 projectId 后返回该项目下所有设计稿和画板信息。画板可以理解成一个页面或一个组件，比如“商品卡片”“登录页”“个人中心”，每个 board 都有独立 id。

第三个是lanhu_get_board_annotations，这是最关键的工具。传入 projectId 和 boardId，返回该画板下所有图层的标注摘要。我在服务端做了字段过滤，只保留还原设计稿最需要的：图层名称、x/y/width/height、填充色、圆角、字体族、字号、行高、字重、内外边距、切图资源链接。

server.registerTool( "lanhu_get_board_annotations", { projectId: z.string(), boardId: z.string(), }, async ({ projectId, boardId }) => { const data = await lanhuGet(`/projects/${projectId}/boards/${boardId}/layers`); const summary = data.layers.map((layer) => ({ name: layer.name, type: layer.type, width: layer.width, height: layer.height, fill: layer.fill, radius: layer.radius, fontFamily: layer.fontFamily, fontSize: layer.fontSize, fontWeight: layer.fontWeight, lineHeight: layer.lineHeight, padding: layer.padding, margin: layer.margin, sliceUrl: layer.sliceUrl, })); return { content: [{ type: "text", text: JSON.stringify(summary, null, 2) }], }; } );

实际里的蓝湖接口字段可能比我这里写得更嵌套，比如填充色有的在style.fill里，字号有的是字符串有的是数字。你接的时候先拿一个真实画板跑一遍接口，把 JSON 结构打出来看，再写映射函数，一次到位。这里给的是思路，不是照抄作业。

3.4 本地跑通并验证再挂给 Cursor

MCP Server 写完别急着挂到 Cursor，先在本地把链路验证一遍。最直接的方式是用官方 Inspector 调试器。

npx @modelcontextprotocol/inspector node index.js

启动后 Inspector 会打开一个本地调试面板，你能看到注册的所有工具，并可以手动调用它们。先调用lanhu_get_projects，如果返回了项目列表，说明 token 和网络都通了；再尝试调用其他两个工具，确认参数和返回结构没有问题。这一步能省下后面在 Cursor 里排错的大量时间。

还有一种快速验证方式，直接用 Node 写一小段测试脚本调lanhuGet("/projects")并打印结果，确认蓝湖 API 本身没问题。如果代码层面的问题，再回到 SDK 层面查。个人经验：八成的问题都出在 API 鉴权和字段名上，跟 MCP 协议没关系。先在最小闭环里把 API 吃透，再谈协议。

4. 把 MCP 服务接到 Cursor 里

4.1 Cursor 的 MCP 配置入口和 mcp.json

Cursor 支持两种 MCP 配置方式。一种是全局的：打开 Cursor Settings，找到 MCP 面板，手动添加 Server。这种适合你希望所有项目都能读蓝湖的场景。另一种是项目级的：在项目根目录放一个.cursor/mcp.json文件，只对这个项目生效。我推荐项目级配置，因为蓝湖的项目权限、设计规范往往跟业务项目强绑定，换项目时不会把上一个项目的配置带过去。

配置内容很简单：

{ "mcpServers": { "lanhu": { "command": "node", "args": ["/Users/yourname/lanhu-mcp/index.js"], "env": { "LANHU_API_TOKEN": "你的蓝湖token" } } } }

几个细节需要注意。command用 Node 的绝对路径更保险，别直接用裸node，因为 Cursor 启动进程时的 PATH 可能和你终端里不一样，尤其用 nvm 管理 Node 版本的人特别容易踩这个坑。args里的脚本路径用绝对路径。env里除了LANHU_API_TOKEN，如果你的蓝湖接口还需要其他参数，也可以一并放进去，比如企业版 URL 可以加LANHU_API_BASE覆盖默认的 API 地址。

配置完成后重启 Cursor，或者执行一次命令面板里的 Reload Window。再打开 MCP 面板，如果看到lanhu这个 Server 状态是绿色的，说明连接成功。

4.2 在 Agent 对话里如何触发蓝湖工具

MCP 配置好之后，很多人会直接问：“帮我把这个商品卡片做了”，结果 Agent 半天没调用工具，还是用训练数据里的通用模式硬写。原因很简单，模型并不知道这里有个蓝湖工具可以用。

想让 Agent 正确触发 MCP，提问时要把需求说清楚，并且提示它去读取蓝湖数据。比较有效的话术是把“数据来源”和“动作”绑定在一起，比如：

“请通过 lanhu_get_projects 找到项目 xx 下名为‘商品卡片’的 board，然后读取它的标注，按标注实现页面中的商品卡片组件，包括背景、圆角、字体、间距。”

关键词要给足，包括“蓝湖”“项目”“board”“标注”这些词，Agent 看到后就会去匹配工具。你也可以更直接一点：“调用 lanhu 工具读取，不要凭经验猜。”我自己用下来，这句话是性价比最高的一句。

另外注意，要用 Agent 模式而不是普通 Chat 模式。普通对话模式下 Cursor 通常不会主动调用外部工具，只有 Agent 模式才会执行多步工具调用。我在第一次试用时就是开着 Chat 窗口问的，工具列表明明在，模型就是不调，换成 Agent 后一切正常。

4.3 让 Agent 做“还原度自检”

配置到位后，我这边的最高频用法是“写完代码后自查”。比如写完一个页面的全部样式，我会让 Agent 做一次官方对照检查：

“调用 lanhu_get_board_annotations，把刚刚实现的页面涉及的几个关键标注再读一遍，和当前代码中的实际值做对照，输出一张差异表：标注值、代码值、是否一致。有差异就直接修正。”

这一步是真正终结“还原了吗”这种灵魂拷问的杀手锏。以前我只能说“应该差不多”，现在能直接甩出一张表：主色 #FF6600 一致，标题字号 20px 一致，卡片圆角 12px 一致，只有间距差 2px 已自动修正。信息具体到这种程度，设计师自然不会再来追问。

把“MCP 读取标注 + 差异自检”当成一个固定动作，就像提交代码前要跑一遍格式化一样。虽然每次会多花十几秒，但它的收益是实打实的：返工率下降，信任感上升。

5. 实际使用技巧与避坑经验

5.1 让 MCP 服务顺手产出 Design Token

蓝湖标注返回的是“画板上的具体值”，但代码里更理想的是“语义化变量”。比如某个蓝色 #4F62C0 在标注里反复出现，如果每一次都让 AI 直接写十六进制，后续改主题色就要全局替换。

我后来在 MCP 服务里加了一个lanhu_get_design_tokens工具，作用是把某个项目所有画板的标注汇总，自动聚类出高频颜色、常用字号、间距序列，输出成类似 CSS 变量的结构。这样 Agent 在写代码时，会倾向于用--color-primary: #4F62C0;这种形式，而不是在组件里散落魔法值。

具体实现也不复杂：在服务端读完项目的多个 board 后，把fill和fontSize字段收集起来统计频次，按出现次数排序返回。这个工具的价值在项目中期尤其大，设计规范越是统一，AI 生成的代码越规范。

5.2 token、上下文与调用频率的管理

蓝湖接口一般有频率限制，MCP 工具如果在一个会话里被高频调用，很容易触发限流。控制方式是让 Agent 尽量少做“全量拉取”，改为“按需读取”。比如只需要改一个商品卡片，就不要把整个项目的所有设计稿标注都读一遍。提示词里可以明确“只读取名为商品卡片的 board”。

上下文长度也是考量。一个复杂的画板可能有几十个图层，即使我只返回了过滤后的摘要字段，数据量依然不小。如果 Agent 在同一轮要处理这些数据，又要写代码，再叠加长上下文编辑，很容易出现“上下文超长”的提示。你可以让 Agent 分两步：先读标注数据，再基于结果写代码，中间隔开一条指令，给它一个缓冲。

另外，给 Agent 的标注数据如果量太大，可以考虑在服务端做聚合。比如我加了一个“只返回尺寸和颜色”的开关，用它生成快速比对就够了，而不需要每次都看全量图层。

5.3 团队协作方式怎么跟着变

技术落地只是一半，另一半是工作流的配合。我接入蓝湖 MCP 后，和设计师约定了一条规则：任何设计修改都以蓝湖标注更新为准，前端不再接受私聊里口头说的“颜色再浅一点”“间距稍微大点”。原因是 MCP 读取的是蓝湖数据，设计稿更新到蓝湖上，AI 才能读到真实值。

这条规则执行后，沟通效率提升很明显。以前设计师改个按钮文案都要直接发消息，前端改了之后又发现配色也变了，来回折腾。现在所有变更都沉淀在蓝湖上，我只需要在 Cursor 里重新拉取一次标注，Agent 会自动发现新旧差异。设计师也轻松，不用追着前端逐个人同步，标注更新即全局可见。

这个转变本质上把“人与人的沟通”转成了“系统与系统的同步”。前端从设计师本人那里接收需求，改成从蓝湖数据源接收需求，减少了一级口头转述，出错率自然下降。

6. 常见问题速查与排错记录

6.1 MCP 显示 connected 但调用工具超时

这是我在接入时遇到的第一个坑。MCP 面板显示 lanhu 是绿色 connected，但让 Agent 调用工具时一直转圈，最后提示 timeout。排查了一圈，问题出在网络代理上：蓝湖 API 域名走了系统代理，而本地 Node 进程被代理拖慢，最后接口请求失败。

解决方案：给 MCP 命令的环境变量里加上NO_PROXY或在代码里用undici的 Agent 配置绕过代理。如果你也遇到类似情况，先单独用curl带着同样的 token 请求一下蓝湖接口，如果 curl 正常但 Node 里慢，基本就是代理环境变量的问题。

6.2 鉴权失败 401/403，token 明明刚拿到

另一个高频问题：按文档获取的 token，放在代码里请求却返回 401。多数情况是 token 的权限维度不对，或者项目数据没有授权给当前应用。我在本地验证时遇到过一种情况：应用申请了“项目只读”权限，但接口路径需要的是“数据导出”权限，最后去开放平台后台多勾选一个权限就通了。

如果返回 403，还要检查项目 id 是不是 belong 到 token 所属的账号空间。跨企业看项目设计稿基本都会被拒。最稳妥的排错路径：先用一个已知有效的项目，通过接口文档里的直接调用页测试鉴权，确认没问题了再改回 MCP 服务里的代码。

6.3 Cursor 侧的几个常见小问题

这里整理几个高频的 Cursor 小问题，顺手帮你排除干扰。

第一个是“too many computers used within the last 24 hours”的提示。这是 Cursor 账号的设备登录限制，同一个账号在 24 小时内被太多新设备激活时会触发。解决方法是去 Cursor 官网的账号设置里管理已登录设备，不常用的解绑后等 24 小时自动恢复。我遇到过同行频繁在几台设备间切换开发环境触发这个提示，建议固定主力设备，别反复登录。

第二个是想要中文界面。Cursor 设置里可以直接搜语言相关设置，通常跟随系统语言，如果你希望强制中文，把系统语言改成中文启动即可。注意这跟用中文写提示词是两回事，界面语言只影响菜单栏，不影响 AI 回复语言。

第三个是下载插件。有人问蓝湖怎么装成 Cursor 插件，其实不需要插件，MCP 服务本身就是 Cursor 的标准扩展方式。跟装插件相比，MCP 更轻量，不占用 Cursor 的插件生态位，也不容易冲突。

6.4 如果用的是 Codex CLI，怎么接蓝湖

如果你用的不是 Cursor 而是 Codex CLI，配置思路完全一样，因为 MCP 是标准协议。Codex 有自己读取 MCP 配置的方式，一般也是在一个配置文件里列出mcpServers，字段和 Cursor 大体相似，只是路径和启动方式略有差异。搜索“codex 如何连接蓝湖”时看到不少人也在问这个，本质就是把上面这套 MCP Server 启动命令交给 Codex 去拉起，双方连接的是同一个服务。

如果你同时用 Cursor 和 Codex，不需要部署两份蓝湖 MCP 服务，同一个本地 Node 进程可以被不同客户端启动。只要配置文件里的 command/args/env 一致，两边都能拉起来。这也是当初选 MCP 而不是写死到某个 IDE 里的最大收获。

一点个人体会

整个接入过程做完，最大感受是：这件事对前端开发效率的提升，比换键盘、换显示器都明显。它把“设计标注”从一个需要人工搬运的数据源，变成了 AI 可以随时调用的信息系统。我再也不用靠记忆和截图去做视觉还原，还原工作第一次有了可以执行的标准。

最后再分享一个扩展思路：同一个 MCP Server 不只是服务于 Cursor，也可以把项目里的 Design Token 输出挂到 CI 里做视觉回归的基础数据，或者让 MCP 服务定时更新蓝湖标注，触发组件库的自动同步。这个方向继续做下去，设计师和前端之间就真的只剩“这版功能真不错”的对话了。