使用 Cursor 辅助开发 Zion 代码组件

Zion 账号准备

代码组件开发过程中会需要用到你的 Zion 注册邮箱和登录密码。 进入 Zion 编辑器，在右上角头像-账号信息内绑定登录邮箱并设置密码。

安装并登录 Cursor

• 访问 Cursor 官网  下载并安装。
• 注册账户或点击 “Sign in” 登录。

使用 Cursor 新建一个文件夹

此文件夹用来保存我们后续开发 Zion 代码组件产出内容。

1. 打开 Cursor 选择 “Open project” 打开文件列表窗口。

2. 选择新建文件夹，然后打开。

3. 进入 Cursor 编辑器页面。

配置 Cursor rules

• 什么是Cursor rules ？ Cursor Rules 是 Cursor 编辑器的规则配置系统，用于定义 AI 在代码项目开发中的行为规范、代码风格、项目结构和开发流程，让 Cursor 能够按照特定标准生成代码，提升开发效率。 User Rules 适合设置个人开发习惯，Project Rules 适合设置特定项目的开发规范。由于我们要开发 Zion 的代码组件，所以更适合使用 Project Rules。

• 什么时候 Cursor 会遵守 Rules？ Rules Apply 是 Cursor 官方为 Rules 设定的四种不同优先级的规则应用机制，以下是 4 种 Cursor 遵守 Rules 的模式。

  规则应用	作用	适用场景	特点
  Always Apply（始终应用）	规则自动应用到每次聊天和会话	核心规范、必须遵循的规则	优先级最高，AI 无条件执行
  Apply Intelligently（智能应用）	Cursor 根据上下文智能判断是否应用规则	特定技术栈或框架相关的规则	节省上下文空间
  Apply to Specific Files（应用于特定文件）	仅对匹配的文件类型/模式生效	文件类型专属规范，如：只有文件 .js / .py / .html 的时候要遵守的规范	精准控制，防止规则冲突
  Apply Manually（手动应用）	需通过 @ 显式触发才会应用规则	临时规则或特殊场景需求	按需启用，不影响常规交互

1. 打开 Cursor 编辑器，进入首选项-Cursor settings - Rules & Memories 。
2. 在Project rules 区域点击”新建”或”Add Rule”按钮，最左侧会创建 Rules 文件夹。

3. 下载 Zion 官方提供的 Cursor Rules 到本地。点击下载：zion-cursor-rules 

4. 将下载到本地的 Rules 拖入 Cursor 编辑器 左侧 .cursor/rules 目录内，拉入成功左侧会有竖线，若没有出现重新拉入 左侧 .cursor/rules 目录内即可。

配置 Zion MCP

• 什么是 MCP？ MCP（Model Context Protocol）是一个标准化的协议 —— 它提供了一个标准化、统一的方式来连接模型与各种外部资源（如工具、数据等），让所有AI模型都能以一致的方式获取和使用这些资源。

• 什么是 Zion MCP？ Zion MCP 是 Zion 官方提供的 MCP 服务，用于在 Cursor 构建代码组件时实时获取项目配置、数据表结构和字段定义。获取到的数据库结构配合 Zion GraphQL API 规范生成项目的 GraphQL API。

1. 打开 Cursor 编辑器，右上角点击设置进入设置页面 → 选择 Tools & Integrations。

2. 在 MCP Tools 区域点击 “Add Custom MCP” 或者 “New MCP Server” 进入 MCP 规则配置界面。

3. 将以下 Zion MCP 服务配置复制，覆盖上一步打开的文档mcp.json内原有信息，然后保存（Command + S / Ctrl + S）。“Zion”是MCP的服务名称， “https://zion-mcp.functorz.com/mcp ” 是Zion MCP服务地址。

{
  "mcpServers": {
    "zion": {
      "url": "https://zion-mcp.functorz.com/mcp"
    }
  }
}

4. 返回 Tools & Integrations 配置页面验证是否配置成功（点击一下开关，左侧有小绿点即配置成功）。

Zion MCP 目前提供了 4 个 MCP 内的工具（tools），Zion 在后续会持续迭代 MCP 服务，新增或修改部分 Tools 能力。

• login - 用于 Zion MCP 服务登录。
• get_project - 用于 Zion MCP 服务登录后获取项目列表和项目 ID。
• get_schema - 用于通过项目 ID 获取项目的配置信息。
• search_project - 用于 Zion MCP 服务登录后搜索指定项目名称并获取项目 ID。

描述开发需求

Cursor 会根据我们已经配置好的 Cursor Rules “Zion代码组件需求完善规则文档”在我们在 Chat 对话窗口发送简单需求后通过对话辅助我们完成对代码组件的需求描述，我们需要尽可能的以功能、用途、样式等角度描述清晰你的组件开发需求，Cursor 产出的结果才能更符合你的开发预期。

• Zion代码组件需求完善规则对话示例：开发一个展示 谁是卧底AI版项目 中每个月的玩家对战次数统计柱状图代码组件。
  • 我们通过 Cursor 提问引导最终补充完整开发需求。

## 基本信息
- **组件名称**: UndercoverWinRateChart
- **功能**: 展示谁是卧底AI版游戏中每个月的玩家对战次数统计
- **数据源**: games表
- **展示方式**: 柱状图
 
## 界面要求
- **布局**: 卡片式设计，圆角，毛玻璃效果
- **颜色**: 蓝色渐变主题
- **字体**: 标题20px粗体，其他13px
- **数据**: 显示最近5个月
 
## 交互效果
- **悬停**: 缩放1.02倍，向上移动4px，阴影加深
- **数值**: 鼠标悬停显示详细数值
 
## 参数结构
**输入参数**:
- 图表标题（必填）
- 时间范围（可选，默认5个月）
- 主题颜色（可选，默认蓝色）
 
**输出参数**:
- 图表数据（月份和次数）
- 加载状态
 
**事件触发器**:
- 数据加载完成事件（可选）
 
## 技术选型
- **框架**: React + TypeScript
- **图表**: ECharts
- **样式**: CSS Modules + SCSS

开发计划生成与确认

• Cursor 根据 Zion 代码组件开发规范 Rules，通过 PLAN 模式生成开发计划，用户输入 ACT 后切换到执行模式，实现需求确认到自动化开发的完整流程。可以避免理解偏差，确保开发方向正确并遵循标准化开发流程。
• 确认无问题后回复 ACT（action 行动），进入自动化开发流程。

Cursor 自动化开发

Cursor 会根据生成的开发计划结合已配置好的 Rules 开始自动化开发流程，以下是 Cursor 自动化开发的详细流程：

1. 环境验证与登录

• 该步骤 Cursor 会执行验证命令，验证 Node.js、functorz CLI、tsx 是否已安装，若未安装则会自动安装。所有开发环境准备就绪后，会执行登录命令。
• functorz CLI、MCP 账号为 Zion 平台绑定邮箱，密码为登录密码。

2. 检查当前项目与项目初始化

• 该步骤会检测当前文件夹及父目录内是否存在 Zion 有效项目，根据检测结果由用户决定是否创建新项目。

3. 依赖安装检查并补充 package.json项目基础信息

• Cursor 在 Zion 项目内安装项目依赖并验证项目环境，补充package.json项目基础信息。

4. 通过 Zion MCP 获取项目配置

• Cursor 会根据开发计划按需使用 Zion MCP，若不需要使用则会自动跳过此步骤；若需要获取项目配置信息则会自动登录根据需求获取指定的项目配置信息。
• MCP 账号为 Zion 平台绑定邮箱，密码为登录密码。

5. 开发需求解析确认流程

• Cursor 会自动结合需求和项目配置分析，明确组件名称、功能、props 结构、交互方式，使开发计划与项目配置匹配。

6. 代码组件文件目录生成

• Cursor 会根据上一步的需求和项目配置解析结果创建 Zion 代码组件目录。

7. 代码开发流程

• Cursor 会根据开发计划自动进行代码开发。

8. 代码组件集成流程

• Cursor 会将新组件按代码组件规范在代码组件统一导出入口文件中配置，以确保 Zion 平台能正确识别代码组件。

9. 代码合规校验流程

• Cursor 会自动检测 props、三段式、导出、媒体上传等是否完全符合平台规范，若校验失败则会自动修复重新校验。
  • props：组件的输入参数，是组件与外部系统交互的唯一接口。
  • 三段式： Zion 组件开发的核心规范，通过 PropData（输入）、StateData（状态输出）、Event（行为触发器定义）三个标准化接口，实现组件的规范化开发和平台集成。
  • 导出：组件必须使用 export { ComponentName } 方式导出，不能使用 export default 默认导出，这样 Zion 平台才能正确识别和加载组件。

10. 代码组件打包流程

• 当前初始化 Zion 项目内运行打包核心命令本地构建组件，监听本地源代码发生的变化，当编辑保存后，自动运行打包命令。

11. 代码组件测试发布（新创建的组件必须发布后才能进行实施预览操作，数据接口有变更也需要重新发布）

• Cursor 会自动执行发布命令将代码组件发布到 Zion 平台，若存在报错会尝试修复并重新发布。

12. 生成 README.md 帮助文档与 resources 资源

• README.md是组件包和代码组件的使用说明书，包含组件简介、集成步骤、用法示例、GraphQL 说明等信息，可以帮助我们快速配置代码组件。
• Cursor 自动生成组件包README.md和组件README.md并保存，然后创建 resources 资源文件确保组件包和组件在不同场景（如插件市场、画布）中正常加载和显示。

实时预览调试

实时预览（Mirror）是 Zion 平台为开发者提供的高效页面与数据预览、调试工具。通过 Mirror，用户可以在开发过程中实时查看页面效果、模拟不同设备和用户场景、调试数据与权限，极大提升开发与测试效率。 我们通过实时预览可以让代码组件在 Zion 项目真实环境中快速调试代码组件的渲染、交互、数据请求等信息。

1. Cursor 执行预览命令并生成预览端口

   Cursor 会自动执行 Zion 项目的预览命令，启动本地开发服务器。执行成功后，会在终端输出预览地址，通常是 http://localhost:6326 或类似的本地端口地址。这个预览环境会实时监听代码变化，为后续 Zion 实时预览调试提供支持。

2. Zion 项目内组件使用并配置数据变量和行为

• 进入我们的 Zion 项目中，选择添加组件 → 代码组件 → 选择底部的配置代码组件 → 打开我们刚刚发布的代码组件。

• 将发布好的代码组件拖入画布中，根据 README.md 配置帮助文档对右侧数据栏进行配置。
  • 我们根据 README.md 内属性配置要求新建页面变量与其一一对应，发布后每次重新配置或变更都需要重新手动点击右上角发布-更新预览或者同步变更。

3. 开始实时预览调试

• 我们打开 Zion 编辑器页面，进入实时预览界面，选择 Cursor 执行预览命令后生成的端口如：6326（若未执行我们在 Cursor Chat 对话窗口发送：执行预览命令确保执行成功），将渲染交互问题和开发者工具内的报错信息发送给 Cursor 进行修复，直到组件无报错且渲染和数据请求都正常代表调试完成。

4. 预览调试完成并发布

• 组件无报错且渲染和数据请求都正常，可以发送 调试完成无问题 给 Cursor，Cursor 会自动对修改好的代码进行打包、升级版本号（Zion 平台要求同个项目每次发布需要升级版本号，以确保发布成功）、发布。

• 最终生成效果：柱状图代码组件 

🎉🎉🎉 组件开发完成 🎉🎉🎉