Cursor接入Pixso MCP：设计稿转组件

在 Cursor 中用 Pixso 设计稿开发页面，可以按这条顺序做：开启 Pixso 本地 MCP，把服务地址写入项目的 .cursor/mcp.json；把带 item-id 的容器链接交给 Agent，先读取设计与项目组件，再实现一个限定范围的页面；最后运行项目，对照设计修正布局，并逐项测试筛选和异常状态。关键不是让 AI 再画一张相似的页面，而是让结果接得上已有代码。

下面以 React + TypeScript 项目中的商品列表为例：顶部有关键词与分类筛选，中间是商品卡片，底部有分页。通过 Pixso MCP 提供图层、组件与资源上下文，由 Cursor 在当前仓库里完成实现；不另起一套样式系统，也不把整张设计截图当作网页背景。

先把“一页设计”缩小成可交付任务

第一次尝试不要选中整个文件。先在 Pixso 中找到商品列表的完整容器，确认商品卡片、筛选区、分页属于同一页面；删除无用副本不是必要步骤，但要避免把旧版画板链接交给 Agent。若手机布局是另一张画板，分别保留两个容器链接，不要让它从桌面截图猜测全部窄屏规则。

打开前端仓库后，先让 Cursor 阅读项目说明、package.json、页面路由、组件目录和样式变量。存在未提交改动时，先辨认哪些是本轮工作，保留当前可恢复版本；不要用清空目录或重建项目来换取“从零生成”的便利。

这个练习的完成范围是：关键词搜索、分类筛选、重置筛选、商品列表、分页，以及加载、无结果和失败反馈。商品详情、购物车、支付不在本轮范围内。组件名称必须从仓库读取；下面用到的 SearchInput、ProductCard 等是组件职责的例子，不要求把项目里的真实名称改成这些词。

配置 Cursor：本地 MCP 用 HTTP，不用 SSE

Pixso 客户端版本需不低于 2.2.0。登录后打开目标设计文件，通过顶栏左上角的 MCP 配置入口启用服务，并复制界面显示的本地地址。常见地址是 http://127.0.0.1:3667/mcp，但端口可能变化；客户端与 IDE 插件同时提供服务时尤其要留意。以下配置中的地址应替换为你看到的地址。

在项目根目录建立 .cursor/mcp.json。若文件已经存在，把 pixso-local 合并进已有的 mcpServers，不要覆盖其他服务。

{
  "mcpServers": {
    "pixso-local": {
      "url": "http://127.0.0.1:3667/mcp"
    }
  }
}

Cursor 支持项目级 .cursor/mcp.json 和用户目录下的 ~/.cursor/mcp.json。前者用于当前项目，后者用于个人多个项目。选一处配置即可；同一服务以多个名字重复加载，会让排错和工具选择更混乱。

在 Cursor 的 MCP 管理界面检查服务是否启用、工具是否可见。Pixso 本地服务采用 HTTP / Streamable HTTP，不能改成 SSE，也不需要用 npx 启动另一个第三方服务。使用期间保持 Pixso 客户端登录、目标文件打开且页签激活。账号还需要全功能或研发席位，并拥有目标文件的查看权限；修改画布则需要编辑权限。

若 Cursor 在 SSH、容器或云端环境中运行，127.0.0.1 指向实际发起 MCP 请求的那台机器，不一定是你面前的电脑。不要把桌面端口直接暴露到公网来解决问题。可以改用 Pixso 远程地址 https://pixso.cn/mcp，按客户端提示完成 OAuth 授权，并始终通过图层链接定位目标。私有化部署使用所属环境的服务地址，不混用公网服务。

先确认读到的图层，再让 Agent 改文件

选中商品列表容器，右键复制图层链接。链接应包含用于定位节点的 item-id；文件分享链接和仅带 page-id 的页面链接不能替代它。即使本地能读取当前选区，明确链接也更适合持续迭代：切换画布后，下一轮任务不会误落到另一个按钮上。

第一轮只做读取与计划。把下面的任务说明和你的容器链接一起发送给 Cursor Agent：

读取这个 Pixso 商品列表容器，先不要修改设计稿和仓库。确认筛选区、商品卡片、分页的结构；读取布局、间距、文字样式和相关图片。再查看当前 React + TypeScript 项目的组件与路由，列出设计元素能复用哪些现有组件、缺哪些属性、预计修改哪些文件。没有读到的设计或代码不要猜。

这一步可以使用 get_node_dsl 读取图层结构，用 read_components、read_styles、read_variables 补足设计信息，用 take_screenshot 查看对应图层。默认结构信息较轻时，再深入读取卡片或筛选区，不必一开始就把整份文件塞进上下文。工具以当前连接实际返回的列表为准，提示词说清任务比背一长串工具名更重要。

看返回结果时，核对三件事：容器是否就是目标页；商品数量与区域关系是否吻合；它有没有真正查看项目组件。如果答案只是“采用现代卡片布局，整体风格简洁”，还没有得到可执行的组件映射，应继续读取具体节点和文件。

把设计属性映射到现有组件，而不是复制一套样式

例如，设计稿里的筛选按钮有正常、禁用、加载中三种状态。代码里可能已经有 Button 的 disabled 与 loading 属性；此时应该映射属性，而不是生成三个长得相似的按钮。商品卡片同样要拆清图片、名称、价格、标签和点击区域，不能只按屏幕坐标堆绝对定位。

这张表中的代码接口要由实际仓库决定。若设计按钮的品牌色是一个语义变量，优先沿用项目中的对应 token，不把颜色值重复写入十几个文件。设计与代码名称不同并非错误，关键是确认映射，并让后续修改继续沿用这条关系。需要长期维护规则时，可接着阅读给 Cursor 添加 UI 规范的方法；MCP 负责拿到设计上下文，Skill 或项目规则负责规定如何使用它，两者不能相互替代。

如果团队使用 Pixso DSM，可以先维护组件别名、属性及对应代码解析配置，再让 Agent 读取组件配置数据。DSM 不是在任意仓库里自动发现所有组件的替代品；没有配置时，也可以先通过上表人工确认映射，把第一次实现范围控制在这个页面。

分两轮实现：先布局，再接筛选状态

第一轮：生成能接进项目的页面骨架

具备企业版对应全功能或研发席位、且文件位于企业空间时，可以使用 design_to_code 获取 D2C+ 代码结果，再对接仓库组件。普通 MCP 连接并不自动获得 D2C+ 权益；未具备该条件时，Cursor 也可使用获准读取的设计信息和自身编程能力实现页面，但应明确这是 Agent 写代码，不是调用已经成功的 D2C+ 结果。

按刚才确认的组件映射实现商品列表。沿用现有 React + TypeScript、路由和样式方案，不添加新 UI 库。先完成布局与静态数据展示，复用项目组件；若可调用 design_to_code，先生成目标容器的 React 代码并说明要怎样接入。只改计划中的文件，不改全局主题，不重做导航。图片使用设计导出的资源，不用整页截图替代 DOM。

这一轮看 diff，而不只看预览。检查是否重复生成项目已有组件、引入不需要的依赖、修改了无关页面，以及图片路径是否指向可交付的项目资源。设计里的图片可通过导出工具取得；不能仅把工具返回的临时地址写进代码，便认定资源已经随项目交付。

第二轮：让筛选结果与页面反馈一致

下面是这个商品列表的练习数据结构，不是 Pixso 的 API。可以据此让 Agent 对接项目实际接口：

type ProductQuery = {
  keyword: string;
  categoryId: string | null;
  page: number;
  pageSize: number;
};
type Product = {
  id: string;
  name: string;
  imageUrl: string;
  priceInCents: number;
};
type ProductPage = {
  items: Product[];
  total: number;
};

先选择明确的交互约定：本例点击“查询”才提交关键词；分类变化也通过查询按钮一起提交；应用新筛选时页码回到 1；“重置”恢复空关键词与全部分类。输入框中尚未提交的内容和当前结果所用条件要分开保存，否则读者刚输入两个字，页面标题可能就声称已经展示新的筛选结果。

为商品列表补齐查询交互。把正在编辑的筛选条件与已经提交的查询条件分开。提交新条件时回到第一页；翻页保留已提交的条件；重置后查询全部分类。请求期间给出反馈，失败保留条件并可重试。连续请求发生时，只接受最新请求的结果，防止旧响应覆盖新结果。请沿用项目现有数据请求方式，不新增第二套状态库。

对空列表要区分原因：没有任何商品时，页面解释当前没有可展示内容；筛选无结果时，应保留筛选条件并提供重置入口；接口失败时，不能把它伪装成“没有商品”。加载态也不等于清空一切：是否保留上次结果由产品交互约定决定，但要让用户知道当前看到的是旧结果还是新结果。

用具体差异改第二版，不再发送“更像设计稿”

运行项目现有启动命令，在浏览器里看桌面与窄屏。让 Agent 先读取 package.json 确认实际脚本，再执行已有的类型检查、测试和构建；项目没有某条脚本时，不要伪造一条“测试全部通过”的结论。

视觉对比需要相同条件：商品数量、标题长短、图片比例和浏览器宽度先一致。设计图用六个短标题，浏览器用三条超长标题时，截图差异不全是 CSS 问题。把问题定位到对象、现象和预期：

只修商品卡片区：长标题把价格挤到了不同高度，卡片在同一行的价格应对齐；保留完整可访问名称，视觉标题最多两行。窄屏筛选按钮被挤到容器外，改为允许筛选区换行，不缩小文字解决。保持现有颜色、导航和筛选请求逻辑不变。修改后重新检查桌面与窄屏，并列出改动文件。

列数随可用宽度变化，不必机械照抄画板坐标。图片保持一致比例和合理裁切；长名称、无图片、较长价格等内容也要能容纳。筛选器与重置按钮应能用键盘到达，当前焦点可见；商品卡片有多个动作时，不把整张卡片嵌套成互相冲突的链接。

遇到问题，按发生的环节排查

交接前，把目标设计链接、组件映射、改动文件、启动方法和仍未接入的真实接口留在项目说明中。完成的标准不是“Cursor 生成了很多代码”，而是接手者能够运行这一页、理解它复用了什么，并继续调整设计而不影响其他页面。

准备开始时，先在 Pixso 里选定一个完整业务容器，再把链接和现有仓库交给 Cursor。第一次只完成一个页面；组件和状态跑通后，再扩展到相邻流程。