你是不是还在因为不会写代码在 Vibe Coding 中陷入僵局？支付不知道怎么接？AI不知道如何调用？后端接口不会写？对象存储服务都不知道啥意思？别慌，我这有一个小小的教程，只需要 5 步即可通过 Cursor + Zion 生成一个AI商业应用MVP 。

流程速览

在 Zion 平台选择「 Cursor AI商业应用 MVP 」模板并创建新项目

在 Zion 平台完成项目的支付配置

在 「Cursor Prompt 生成器」中按照步骤生成 Cursor Prompt

在 Cursor 中粘贴生成的 Prompt

等待约12分钟后即可生成一个接入Zion 服务端的AI商业应用MVP（WEB端）

Demo 案例

这是一个 AI烹饪专家 项目的案例，用户在注册、登陆后可以在网站付费后体验AI分析功能

Zion 是什么？

Zion 是一款不用写代码也可以开发出微信小程序、WEB、AI Agent 的全栈无代码开发工具 。

Zion 拥有全栈无代码开发的能力，你可以在 Zion 上通过可视化的配置完成一个包含前后端的完整项目。

作为一个高自由度的开发工具，Zion 的服务端接口也拥有标准的规范（包括不限于支付服务、AI Agent服务、对象存储服务、数据库服务），结合用户在 Zion 上的自定义配置（数据库配置、AI Agent配置、支付配置）以及各项服务的规范，无需在Zion上搭建前端页面 即可让 Cursor 结合 Zion 的后端开发一个可商用的完整软件产品！

入门步骤

在简单了解 Zion 的能力后，先通过我们的入门步骤感受一下 在 15 分钟左右即可生成一个AI商业应用 MVP 的感觉，在完成入门指引后会有详细介绍。

Zion 准备阶段

注册 Zion 账户 :点此注册

在 Zion 平台选择「 Cursor AI商业应用 MVP 」模板并创建新项目

在 Zion 平台项目编辑页面 - 设置 - 支付设置 - 激活支付宝支付 - 填写支付宝商户号、公钥、私钥（没有可以暂时调过此步骤）

预发布/预览一次基于模版创建好的项目

设置 npm 镜像源

由于一些代码的依赖包默认会从外网下载，为了避免网络原因下载失败，需要在电脑的终端中切换镜像源在国内，本方案中我们推荐由淘宝提供的镜像源。我们推荐将终端命令通过 Cursor 的对话框发送给 Cursor 帮助你完成镜像切换

在终端中复制粘贴以下命令：

npm config set registry https://registry.npmmirror.com

验证是否切换成功

npm config get registry

如果成功切换 将会显示：

使用 Zion 提示词生成工具

下载并打开 「Zion-AI商业应用提示词生成工具」（当前版本v1.0 beta）

下载最新版本的 Zion prompt 模板 当前版本：v-0815

在 Zion 项目编辑页面 - AI 中选择示例 agent 「AI烹饪专家」的「...」按钮拷贝 agent 的 json 配置

第一步：粘贴 AI agent 配置到 「Zion-AI商业应用提示词生成工具」内点击下一步

第二步：在 Zion 项目编辑页面 - 左上角行为流入口-依次选择「createorder」的「...」按钮拷贝行为流的 json 配置

同理在「Zion-AI商业应用提示词生成工具」完成行为流配置粘贴

第3步：选择下载好的 prompt 文件并上传

第4步：生成并复制拼接好的 最终 prompt

Cursor 操作

新建一个空的项目文件夹

用 Cursor 打开新建的文件夹

粘贴 生成出的 prompt 到聊天框区域（不要带有历史对话）

等待项目构建完成！

首先恭喜你顺利按照入门步骤跑通了一遍！（不出意外的话），但是如果完全按照模板走，也太没意思了！所以接下来我将拆解 prompt 中的细节为你揭秘，TA 是如何让 Cursor 开发出你看到的结果的！在你掌握了 prompt 的核心逻辑以及 Zion 的能力后，你就可以通过 Cursor&Zion 开发出不同的业务系统了！

Zion & Cursor Prompt 拆解

示例 prompt

当你按照「Zion-AI商业应用提示词生成工具」的流程配置完成后，你会得到类似如下内容的 prompt

# Zion 项目构建说明书-0815

## AI Agent 配置 （包含项目id）

```json
{
  "id": "mdgu1el9",
  "name": "AI烹饪专家",
  "model": "GPT_4O_MINI",
  "projectExId": "5bRlXJnXZjY",
  "inputArgs": {
    "mdgu1fp1": {
      "type": "IMAGE",
      "nullable": true,
      "displayName": "foods",
      "name": "mdgu1fp1"
    }
  },
  "outputConfig": {
    "isStructured": false,
    "isStreaming": true,
    "maxTokenSize": 10000
  },
  "hasImageInput": true,
  "hasVideoInput": false
}
```

## CreateOrder ActionFlow 配置

```json
{
  "actionFlowId": "554f9b2e-71c3-4ca2-9af3-f9c4b074ef4d",
  "versionId": 7,
  "displayName": "createOrder",
  "inputArgs": {},
  "outputDataBindings": {
    "orderid": {
      "type": "BIGINT",
      "description": "订单ID"
    },
    "goods_name": {
      "type": "TEXT",
      "description": "商品名称"
    },
    "amount": {
      "type": "DECIMAL",
      "description": "订单金额"
    }
  }
}
```

## queryorderstatus ActionFlow 配置

```json
{
  "actionFlowId": "a0bd4be9-b96c-4302-8570-8cd47378dd42",
  "versionId": 4,
  "displayName": "queryOrderStatus",
  "inputArgs": {
    "order_id": {
      "type": "BIGINT",
      "nullable": false,
      "description": "订单ID"
    }
  },
  "outputDataBindings": {
    "status": {
      "type": "TEXT",
      "description": "状态"
    }
  }
}
```

## 项目开发要求

- 在当前目录创建 React 项目（使用 create-react-app，不要创建子目录，必须使用React版本号：18.2.0）
- 使用 npm 时启用详细模式下载包，创建React时启用 -v详细模式下载
- **严格遵循** TypeScript 编码标准

### 代码质量要求
- 所有变量和导入必须被使用
- 满足所有可访问性要求
- 通过 ESLint 检查

## 项目概述

创建一个 AI商业应用的MVP版本，集成 Zion.app 的后端 提供的AI Agent和支付服务。用户需要先付费待订单已支付后才能使用AI Agent 服务。使用 Ant Design 5.27.0 版本设计界面。

## 技术配置

### GraphQL 后端

- **URL**: `https://zion-app.functorz.com/zero/5bRlXJnXZjY/api/graphql-v2`
- **协议**: GraphQL

### Apollo GraphQL 客户端配置

- 使用 Apollo GraphQL 客户端与 Zion 后端通信
- 安装 `subscriptions-transport-ws`
- 在分割链接中使用 `@apollo/client/link/ws` 的 `WebSocketLink` 作为 WebSocket 链接
- Apollo Client的HTTP链接配置动态认证头
- 确保 Apollo Provider 包装所有使用 GraphQL hooks 的组件：
1. 创建 Apollo Provider 包装器
2. 将使用 useQuery/useMutation 的组件放在 Provider 内部
3. 避免在 Provider 外部使用任何 GraphQL hooks
4. 使用组件分离模式：Provider 包装器 + 业务组件
## AI Agent调用流程

给定在 Zion 中构建的Agent ID `mdgu1el9`，调用 AI Agent的方式如下：

### 步骤 1: 获取 authToken

#### 登录现有用户

```graphql
mutation login($username: String!, $password: String!) {
  loginWithPassword(name: $username, password: $password) {
    jwt {
      token
    }
  }
}
```

#### 新用户注册（注册后自动登录）

```graphql
mutation AuthenticateWithUsername(
  $username: String!
  $password: String!
  $register: Boolean!
) {
  authenticateWithUsername(
    username: $username
    password: $password
    register: $register
  ) {
    account {
      id
      permissionRoles
    }
    jwt {
      token
    }
  }
}
```

**注意**: 在初始化时检查 localStorage 中的 token，完成登录/注册/登出功能。使用setContext链接动态为除了登陆、注册外的每个HTTP请求添加Authorization: Bearer {token}头，确保登录后的所有GraphQL请求都带有正确的认证信息。

### 步骤 2: 调用 AI

调用 GraphQL API，POST 到 `https://zion-app.functorz.com/zero/5bRlXJnXZjY/api/graphql-v2`

- 授权头应设置为 `Bearer {authToken}`
- 调用变更 `fz_zai_create_conversation`
- 参数:
  - `inputArgs` (Map_String_ObjectScalar!, 实际上是非空 JSON 对象)
  - `zaiConfigId` (String!)
- 返回值是标量 Long，这是会话 ID，用于监听结果
- 如果输入的是媒体文件，入参的格式应该{Agent Config中媒体文件入参的id}_id:oss返回的id
- 严格按照AI agent config 的入参渲染页面，只有单一媒体文件入参的Config就不要有文字输入框

### 步骤 3: 订阅结果

- **订阅固定URL**: `wss://zion-app.functorz.com/zero/5bRlXJnXZjY/api/graphql-subscription`

#### WebSocket 连接

首次订阅或 authToken 更改时（例如用户登陆后），确保重新建立 WebSocket并有传递authToken，并使用最新的 authToken 重新初始化连接。

```json
{
  "id": "1",
  "type": "connection_init",
  "payload": {
    "authToken": "[authToken]"
  }
}
```

#### 实际订阅

```graphql
subscription fz_listen_zai_mdgu1el9($conversationId: Long!) {
  fz_zai_listen_conversation_result(conversationId: $conversationId) {
    data
    reasoningContent
    status
  }
}
```

**变量**:

```json
{
  "conversationId": "[conversationId]"
}
```

#### 状态字段

`status` 字段可以是以下之一：

- `CANCELED`
- `COMPLETED`
- `CREATED`
- `FAILED`
- `IN_PROGRESS`
- `STREAMING`
- `THINKING_CHAIN_STREAMING`

在 `STREAMING` 或 `THINKING_CHAIN_STREAMING` 期间，服务器将通过订阅消息向客户端发送每个单独的 token，通过累积 token 正确处理流式响应。当状态更改为 `COMPLETED` 时，确保使用 data 字段替换整个累积内容。

**data 字段类型**: String

- 输出类型可以从Agent的配置中确定，agent配置会告诉你是流式输出还是json格式输出，基于该类型设计页面
- 当触发Agent执行的时候就立即需要在输出框显示在加载动画和文字效果且输出的区域要有最小高度让用户感知到，如果是流式输出，需要对输出的md格式进行正确的渲染，内容平滑地填充到输出区域


## 步骤 4: 支付宝支付集成指南

### 1. 创建订单

调用 GraphQL API，POST 到 `https://zion-app.functorz.com/zero/5bRlXJnXZjY/api/graphql-v2`

授权头应设置为 `Bearer {authToken}`

调用变更 `fz_invoke_action_flow`，参数：

- `actionFlowId` (String!): "554f9b2e-71c3-4ca2-9af3-f9c4b074ef4d"
- `versionId` (Int!): 7
- `args` (Json!): 包含  的对象

**示例请求**:

```graphql
mutation ExecuteAddOrderFlow($args: Json!) {
  fz_invoke_action_flow(
    actionFlowId: "554f9b2e-71c3-4ca2-9af3-f9c4b074ef4d"
    versionId: 7
    args: $args
  )
}
```

**变量**:

```json
{
  "args": {
    "goods_name": "AI Food Expert Consultation Service",
    "amount": 0.01
  }
}
```

**返回值结构**:

```json
{
  "fz_invoke_action_flow": {
    "amount": 0.01,
    "goods_name": "AI Food Expert Consultation Service",
    "orderid": 116
  }
}
```

### 2. 创建支付宝交易

使用action Flow输出的订单 ID 和 goods_name（不要有自定义订单逻辑），调用Zion提供的alipayTrade接口，确保alipayTrade接口的请求包含Bearer token。


调用变更 `alipayTrade`，参数：

- `bizContent` (Object!): 包含交易详情
- `returnUrl` (String!): 支付后返回 URL

**示例请求**:

```graphql
mutation AliPayTrade(
  $outTradeNo: String!
  $productCode: String!
  $subject: String!
  $totalAmount: Float!
  $returnUrl: String!
) {
  alipayTrade(
    bizContent: {
      out_trade_no: $outTradeNo
      product_code: $productCode
      subject: $subject
      total_amount: $totalAmount
    }
    returnUrl: $returnUrl
  )
}
```

**变量**:

```json
{
  "outTradeNo": "116",
  "productCode": "FAST_INSTANT_TRADE_PAY",
  "subject": "AI Food Expert Consultation Service",
  "totalAmount": 0.01,
  "returnUrl": "https://your-domain.com/"
}
```

**返回值结构**:

```json
{
  "alipayTrade": [
    "<form name=\"punchout_form\" method=\"post\" action=\"https://openapi.alipay.com/gateway.do?charset=utf-8&method=alipay.trade.page.pay&sign=...\">\\n<input type=\"hidden\" name=\"biz_content\" value=\"{...}\">\\n<input type=\"submit\" value=\"立即支付\" style=\"display:none\">\\n</form>\\n<script>document.forms[0].submit();</script>",
    "202508050558451234567890"
  ]
}
```

### 3. 渲染支付模态框

-在当前页面使用 iframe 和 srcDoc 渲染支付表单，添加 `sandbox="allow-forms allow-scripts allow-same-origin"` 和 title 属性。
-仅通过 srcDoc 传递所有 HTML。不要使用 dangerouslySetInnerHTML。
-不要打开新页面支付
-在模态框内只能渲染支付宝返回的表单元素
-通过提供的查询订单状态action flow 轮询订单支付状态，应该在订单创建成功后才开始轮询
-支付宝html的高度固定为557

### 4. 查询订单支付状态

通过类似创建订单的行为流的调用方式，查询订单状态，当订单支付状态变更为已支付后自动关闭模态框，允许用户手动关闭模态框



## 在Zion上使用媒体文件

### 处理文件输入

首先需要上传文件获取ID

在此之前先计算文件的MD5哈希值，然后对该原始128位哈希值进行Base64编码，生成：`imgMd5Base64`或`videoMd5Base64`。使用`import { md5 } from 'js-md5';`。

-不能直接编码字符串：需要对字节数组进行 Base64 编码
-十六进制转字节：每2个字符转1个字节
-结果格式：24位 Base64 字符串（如 CXNlpjQsRM0QZgPvCeWtDg==）

### 图像输入：

1. 调用`imagePresignedUrl`。

```graphql
mutation GetImageUploadUrl($md5: String!, $suffix: MediaFormat!, $acl: CannedAccessControlList) {
  imagePresignedUrl(imgMd5Base64: $md5, imageSuffix: $suffix, acl: $acl) {
    imageId
    uploadUrl
    uploadHeaders
    downloadUrl
    contentType
  }
}
```

示例变量：`{ "md5": "[Base64编码的MD5]", "suffix": "PNG", "acl": "PRIVATE" }`

2. 该变更操作返回`imageId`、`uploadUrl`和`uploadHeaders`。

3. 将原始图像文件`PUT`到`uploadUrl`。如果`uploadHeaders`不为空，请将其内容作为请求头包含在请求中。

4. 使用返回的`imageId`作为AI Agent调用中IMAGE输入参数的值。确保`imageId`是Number类型。

### 视频输入：

1. 调用`videoPresignedUrl`。

```graphql
mutation GetVideoUploadUrl($md5: String!, $format: MediaFormat!, $acl: CannedAccessControlList) {
  videoPresignedUrl(videoMd5Base64: $md5, videoFormat: $format, acl: $acl) {
    videoId
    uploadUrl
    uploadHeaders
    downloadUrl
    contentType
  }
}
```

示例变量：`{ "md5": "[Base64编码的MD5]", "format": "MP4", "acl": "PRIVATE" }`

2. 该变更操作返回`videoId`、`uploadUrl`和`uploadHeaders`。

3. 将原始视频文件`PUT`到`uploadUrl`。如果`uploadHeaders`不为空，将其内容作为请求头包含在请求中。

4. 使用返回的`videoId`作为步骤2中VIDEO输入参数的值。确保`videoId`是Number类型。

---

### 参数枚举

#### `CannedAccessControlList`（使用PRIVATE）：
- AUTHENTICATE_READ
- AWS_EXEC_READ
- BUCKET_OWNER_FULL_CONTROL
- BUCKET_OWNER_READ
- DEFAULT
- LOG_DELIVERY_WRITE
- PRIVATE
- PUBLIC_READ
- PUBLIC_READ_WRITE

#### `MediaFormat`：
- CSS
- CSV
- DOC
- DOCX
- GIF
- HTML
- ICO
- JPEG
- JPG
- JSON
- MOV
- MP3
- MP4
- OTHER
- PDF
- PNG
- PPT
- PPTX
- SVG
- TXT
- WAV
- WEBP
- XLS
- XLSX
- XML

接下来，我会为你介绍 prompt 中的详细内容，整个 prompt 由项目个性化配置、项目开发规范约束、项目开发概述、Zion 平台服务端全局接入规范、Zion 项目用户注册登录说明、Zion AI Agent 服务调用流程、Zion 支付宝支付服务调用流程、Zion 文件存储规范构成。Cursor 正是基于 这些 prompt 的描述完成了 AI商业应用MVP 的项目开发

项目个性化配置

项目个性化配置就是在用户在 Zion AI Agent 搭建器、Zion 行为流中的配置内容，由于在 Zion 平台直接拷贝对应配置内容会包含配置中所有子节点的信息，但实际上调用对应服务只需要知晓 输入、输出以及唯一 id 信息，「Zion-AI商业应用提示词生成工具」的核心作用就是提取出服务的输入、输出信息：

AI Agent 配置

在这段 json 配置里核心的内容是 Zion 项目 的唯一id 、Agent 输入/输出的参数详细信息

# Zion AI Agent 配置文件
{
  "id": "mdgu1el9",
  "name": "AI烹饪专家",
  "model": "GPT_4O_MINI",
  "projectExId": "5bRlXJnXZjY",
  
  "inputArgs": {
    "mdgu1fp1": {
      "type": "IMAGE",
      "nullable": true,
      "displayName": "foods",
      "name": "mdgu1fp1"
    }
  },
  
  "outputConfig": {
    "isStructured": false,
    "isStreaming": true,
    "maxTokenSize": 10000
  },
  
  "hasImageInput": true,
  "hasVideoInput": false
}

# 字段说明：
# - id: Zion AI Agent 唯一标识符
# - name: AI Agent 显示名称
# - model: 使用的AI模型名称
# - projectExId: 所属项目的唯一标识符
# - inputArgs: 输入参数配置
#   - type: 参数类型 (IMAGE=图片类型)
#   - nullable: 是否允许为空
#   - displayName: 参数显示名称
#   - name: 参数唯一标识符
# - outputConfig: 输出配置
#   - isStructured: 是否为结构化输出
#   - isStreaming: 是否为流式输出
#   - maxTokenSize: 最大输出Token数量
# - hasImageInput: 是否支持图片输入
# - hasVideoInput: 是否支持视频输入

行为流（Action Flow）配置

在这段 json 配置里核心的内容是 行为流的唯一 id 和版本号、行为流输入/输出的参数详细信息，在入门的项目配置中，我们配置了两个行为流，分别是创建订单和查询订单状态

# Zion ActionFlow 配置文件

{
  "actionFlowId": "554f9b2e-71c3-4ca2-9af3-f9c4b074ef4d",
  "versionId": 6,
  "displayName": "createorder",
  "inputArgs": {},
  "outputDataBindings": {
    "orderid": {
      "type": "BIGINT",
      "description": "订单ID"
    },
    "goods_name": {
      "type": "TEXT",
      "description": "商品名称"
    },
    "amount": {
      "type": "DECIMAL",
      "description": "订单金额"
    }
  }
}

{
  "actionFlowId": "a0bd4be9-b96c-4302-8570-8cd47378dd42",
  "versionId": 3,
  "displayName": "queryorderstatus",
  "inputArgs": {
    "order_id": {
      "type": "BIGINT",
      "nullable": false,
      "description": "订单ID"
    }
  },
  "outputDataBindings": {
    "status": {
      "type": "TEXT",
      "description": "状态"
    }
  }
}

# 字段说明：
# - actionFlowId: ActionFlow 唯一标识符
# - versionId: 版本号
# - displayName: ActionFlow 显示名称
# - inputArgs: 输入参数配置
#   - type: 参数数据类型
#   - nullable: 是否允许为空 (可选字段)
#   - description: 参数描述
# - outputDataBindings: 输出参数配置
#   - type: 输出数据类型
#   - description: 输出参数描述

# 数据类型说明：
# - BIGINT: 大整数类型
# - TEXT: 文本类型
# - DECIMAL: 小数类型

项目开发规范约束

## 项目开发要求
- 在当前目录创建 React 项目（使用 create-react-app，不要创建子目录，必须使用React版本号：18.2.0）
- 使用 npm 时启用详细模式下载包，创建React时启用 -v详细模式下载
- **严格遵循** TypeScript 编码标准
### 代码质量要求
- 所有变量和导入必须被使用
- 满足所有可访问性要求
- 通过 ESLint 检查

项目开发概述

## 项目概述

创建一个 AI商业应用的MVP版本，集成 Zion.app 的后端 提供的AI Agent和支付服务。用户需要先付费待订单已支付后才能使用AI Agent 服务。使用 Ant Design 5.27.0 版本设计界面。

Zion 平台服务端全局接入规范

Zion 的项目是基于 GraphQL API进行数据通讯，所以我们需要在 prompt 中强调 Cursor 需要构建出 GraphQL 客户端以及 Zion 的后端通讯URL（包括基础的通讯和 WebSocket通讯方式），项目后端的通讯URL中的下划线 id 就是你的项目唯一 id 了，这也是为什么在项目个性化配置中需要获取到项目唯一 id

## 技术配置
### GraphQL 后端
- **URL**: `https://zion-app.functorz.com/zero/5bRlXJnXZjY/api/graphql-v2`
- **协议**: GraphQL
### Apollo GraphQL 客户端配置
- 使用 Apollo GraphQL 客户端与 Zion 后端通信
- 安装 `subscriptions-transport-ws`
- 在分割链接中使用 `@apollo/client/link/ws` 的 `WebSocketLink` 作为 WebSocket 链接
- Apollo Client的HTTP链接配置动态认证头
- 确保 Apollo Provider 包装所有使用 GraphQL hooks 的组件：
1. 创建 Apollo Provider 包装器
2. 将使用 useQuery/useMutation 的组件放在 Provider 内部
3. 避免在 Provider 外部使用任何 GraphQL hooks
4. 使用组件分离模式：Provider 包装器 + 业务组件

Zion 项目用户注册登录说明

Zion 的项目默认提供用户名、密码的用户注册登录模式，登录成功后会返回用户的 access_token , 在项目的接口请求中采用 JWT 鉴权的方式进行用户鉴权 ，Zion 提供了 RBAC + ABAC 的权限管理能力，你可以在 Zion 服务端能力介绍查看详细介绍

#### 登录现有用户

```graphql
mutation login($username: String!, $password: String!) {
  loginWithPassword(name: $username, password: $password) {
    jwt {
      token
    }
  }
}
```

#### 新用户注册（注册后自动登录）

```graphql
mutation AuthenticateWithUsername(
  $username: String!
  $password: String!
  $register: Boolean!
) {
  authenticateWithUsername(
    username: $username
    password: $password
    register: $register
  ) {
    account {
      id
      permissionRoles
    }
    jwt {
      token
    }
  }
}
```

**注意**: 在初始化时检查 localStorage 中的 token，完成登录/注册/登出功能。使用setContext链接动态为除了登陆、注册外的每个HTTP请求添加Authorization: Bearer {token}头，确保登录后的所有GraphQL请求都带有正确的认证信息。

Zion AI Agent 服务调用流程

在这段 prompt 中我们介绍了如何调用你在 Zion 平台构建的AI Agent 并根据输入/输出的参数配置动态渲染页面，因为AI Agent存在流式输出的返回方式，需要通过 Websocket 和 Zion后端进行通讯 ，我们也提供了对应的通讯方式和返回规范。

## AI Agent调用流程

给定在 Zion 中构建的Agent ID `mdgu1el9`，调用 AI Agent的方式如下：

### 步骤 1: 获取 authToken


### 步骤 2: 调用 AI

调用 GraphQL API，POST 到 `https://zion-app.functorz.com/zero/5bRlXJnXZjY/api/graphql-v2`

- 授权头应设置为 `Bearer {authToken}`
- 调用变更 `fz_zai_create_conversation`
- 参数:
  - `inputArgs` (Map_String_ObjectScalar!, 实际上是非空 JSON 对象)
  - `zaiConfigId` (String!)
- 返回值是标量 Long，这是会话 ID，用于监听结果
- 如果输入的是媒体文件，入参的格式应该{Agent Config中媒体文件入参的id}_id:oss返回的id
- 严格按照AI agent config 的入参渲染页面，只有单一媒体文件入参的Config就不要有文字输入框

### 步骤 3: 订阅结果

- **订阅固定URL**: `wss://zion-app.functorz.com/zero/5bRlXJnXZjY/api/graphql-subscription`

#### WebSocket 连接

首次订阅或 authToken 更改时（例如用户登陆后），确保重新建立 WebSocket并有传递authToken，并使用最新的 authToken 重新初始化连接。

```json
{
  "id": "1",
  "type": "connection_init",
  "payload": {
    "authToken": "[authToken]"
  }
}
```

#### 实际订阅

```graphql
subscription fz_listen_zai_mdgu1el9($conversationId: Long!) {
  fz_zai_listen_conversation_result(conversationId: $conversationId) {
    data
    reasoningContent
    status
  }
}
```

**变量**:

```json
{
  "conversationId": "[conversationId]"
}
```

#### 状态字段

`status` 字段可以是以下之一：

- `CANCELED`
- `COMPLETED`
- `CREATED`
- `FAILED`
- `IN_PROGRESS`
- `STREAMING`
- `THINKING_CHAIN_STREAMING`

在 `STREAMING` 或 `THINKING_CHAIN_STREAMING` 期间，服务器将通过订阅消息向客户端发送每个单独的 token，通过累积 token 正确处理流式响应。当状态更改为 `COMPLETED` 时，确保使用 data 字段替换整个累积内容。

**data 字段类型**: String

- 输出类型可以从Agent的配置中确定，agent配置会告诉你是流式输出还是json格式输出，基于该类型设计页面
- 当触发Agent执行的时候就立即需要在输出框显示在加载动画和文字效果且输出的区域要有最小高度让用户感知到，如果是流式输出，需要对输出的md格式进行正确的渲染，内容平滑地填充到输出区域

Zion 支付宝支付服务调用流程

在这段 prompt 中我们详细描述了如何接入 Zion 支付宝支付能力，从创建系统订单再到创建支付宝支付订单最后渲染支付二维码的全流程

## 步骤 4: 支付宝支付集成指南

### 1. 创建订单

调用 GraphQL API，POST 到 `https://zion-app.functorz.com/zero/5bRlXJnXZjY/api/graphql-v2`

授权头应设置为 `Bearer {authToken}`

调用变更 `fz_invoke_action_flow`，参数：

- `actionFlowId` (String!): "554f9b2e-71c3-4ca2-9af3-f9c4b074ef4d"
- `versionId` (Int!): 4
- `args` (Json!): 包含  的对象

**示例请求**:

```graphql
mutation ExecuteAddOrderFlow($args: Json!) {
  fz_invoke_action_flow(
    actionFlowId: "554f9b2e-71c3-4ca2-9af3-f9c4b074ef4d"
    versionId: 4
    args: $args
  )
}
```

**变量**:

```json
{
  "args": {
    "goods_name": "AI Food Expert Consultation Service",
    "amount": 0.01
  }
}
```

**返回值结构**:

```json
{
  "fz_invoke_action_flow": {
    "amount": 0.01,
    "goods_name": "AI Food Expert Consultation Service",
    "orderid": 116
  }
}
```

### 2. 创建支付宝交易

使用action Flow输出的订单 ID（不要有自定义订单逻辑），调用Zion提供的alipayTrade接口，确保alipayTrade接口的请求包含Bearer token。


调用变更 `alipayTrade`，参数：

- `bizContent` (Object!): 包含交易详情
- `returnUrl` (String!): 支付后返回 URL

**示例请求**:

```graphql
mutation AliPayTrade(
  $outTradeNo: String!
  $productCode: String!
  $subject: String!
  $totalAmount: Float!
  $returnUrl: String!
) {
  alipayTrade(
    bizContent: {
      out_trade_no: $outTradeNo
      product_code: $productCode
      subject: $subject
      total_amount: $totalAmount
    }
    returnUrl: $returnUrl
  )
}
```

**变量**:

```json
{
  "outTradeNo": "116",
  "productCode": "FAST_INSTANT_TRADE_PAY",
  "subject": "AI Food Expert Consultation Service",
  "totalAmount": 0.01,
  "returnUrl": "https://your-domain.com/"
}
```

**返回值结构**:

```json
{
  "alipayTrade": [
    "<form name=\"punchout_form\" method=\"post\" action=\"https://openapi.alipay.com/gateway.do?charset=utf-8&method=alipay.trade.page.pay&sign=...\">\\n<input type=\"hidden\" name=\"biz_content\" value=\"{...}\">\\n<input type=\"submit\" value=\"立即支付\" style=\"display:none\">\\n</form>\\n<script>document.forms[0].submit();</script>",
    "202508050558451234567890"
  ]
}
```

### 3. 渲染支付模态框

-在当前页面使用 iframe 和 srcDoc 渲染支付表单，添加 `sandbox="allow-forms allow-scripts allow-same-origin"` 和 title 属性。
-仅通过 srcDoc 传递所有 HTML。不要使用 dangerouslySetInnerHTML。
-不要打开新页面支付
-在模态框内只能渲染支付宝返回的表单元素
-通过提供的查询订单状态action flow 轮询订单支付状态，应该在订单创建成功后才开始轮询
-支付宝html的高度固定为557

### 4. 查询订单支付状态

通过类似创建订单的行为流的调用方式，查询订单状态，当订单支付状态变更为已支付后自动关闭模态框，允许用户手动关闭模态框

Zion 文件存储规范

在这段 prompt 中详细描述了 Zion 平台支持的文件存储类型和上传规则

## 在Zion上使用媒体文件

### 处理文件输入

首先需要上传文件获取ID

在此之前先计算文件的MD5哈希值，然后对该原始128位哈希值进行Base64编码，生成：`imgMd5Base64`或`videoMd5Base64`。使用`import { md5 } from 'js-md5';`。

-不能直接编码字符串：需要对字节数组进行 Base64 编码
-十六进制转字节：每2个字符转1个字节
-结果格式：24位 Base64 字符串（如 CXNlpjQsRM0QZgPvCeWtDg==）

### 图像输入：

1. 调用`imagePresignedUrl`。

```graphql
mutation GetImageUploadUrl($md5: String!, $suffix: MediaFormat!, $acl: CannedAccessControlList) {
  imagePresignedUrl(imgMd5Base64: $md5, imageSuffix: $suffix, acl: $acl) {
    imageId
    uploadUrl
    uploadHeaders
    downloadUrl
    contentType
  }
}
```

示例变量：`{ "md5": "[Base64编码的MD5]", "suffix": "PNG", "acl": "PRIVATE" }`

2. 该变更操作返回`imageId`、`uploadUrl`和`uploadHeaders`。

3. 将原始图像文件`PUT`到`uploadUrl`。如果`uploadHeaders`不为空，请将其内容作为请求头包含在请求中。

4. 使用返回的`imageId`作为AI Agent调用中IMAGE输入参数的值。确保`imageId`是Number类型。

### 视频输入：

1. 调用`videoPresignedUrl`。

```graphql
mutation GetVideoUploadUrl($md5: String!, $format: MediaFormat!, $acl: CannedAccessControlList) {
  videoPresignedUrl(videoMd5Base64: $md5, videoFormat: $format, acl: $acl) {
    videoId
    uploadUrl
    uploadHeaders
    downloadUrl
    contentType
  }
}
```

示例变量：`{ "md5": "[Base64编码的MD5]", "format": "MP4", "acl": "PRIVATE" }`

2. 该变更操作返回`videoId`、`uploadUrl`和`uploadHeaders`。

3. 将原始视频文件`PUT`到`uploadUrl`。如果`uploadHeaders`不为空，将其内容作为请求头包含在请求中。

4. 使用返回的`videoId`作为步骤2中VIDEO输入参数的值。确保`videoId`是Number类型。

---

### 参数枚举

#### `CannedAccessControlList`（使用PRIVATE）：
- AUTHENTICATE_READ
- AWS_EXEC_READ
- BUCKET_OWNER_FULL_CONTROL
- BUCKET_OWNER_READ
- DEFAULT
- LOG_DELIVERY_WRITE
- PRIVATE
- PUBLIC_READ
- PUBLIC_READ_WRITE

#### `MediaFormat`：
- CSS
- CSV
- DOC
- DOCX
- GIF
- HTML
- ICO
- JPEG
- JPG
- JSON
- MOV
- MP3
- MP4
- OTHER
- PDF
- PNG
- PPT
- PPTX
- SVG
- TXT
- WAV
- WEBP
- XLS
- XLSX
- XML

Zion 服务端能力介绍

在了解完 prompt 的构成后，我们将继续介绍 Cursor + Zion 能够快速构建AI商业应用MVP背后的核心服务，帮助你理解这个方案的基础能力来源。以下服务仅为 Zion 能力的一部分，如果你想体验 Zion 的无代码开发能力，可以前往 Zion 帮助文档 或 Zion B站视频讲解 进一步了解 。

Zion AI 智能体搭建器

Zion 内置 AI 能力，开发者可创建高度定制化的 Agent，灵活定义 Prompt、RAG、工具调用等，结合 Zion 的前端编排与后端数据处理，快速搭建商业级 AI 应用。在当前MVP方案中我们构建了一个最简单的AI烹饪专家智能体，基于用户上传的餐食图片给出毒辣点评。

帮助文档入口：配置和使用 AI | Zion 帮助中心

通过 Cursor 调用 Zion AI Agent 的优势

• 可视化配置AI Agent（自定义大模型、RAG配置、结构化输出配置、工具调用配置）
• 一站式管理业务数据、AI会话数据
• Zion 会及时更新最新的实用大模型供你选择

Zion 行为流

Zion 平台的行为流为用户提供了流程化操作编排和多种触发方式的工具，最终产出为自定义“行为”，类似于市面上的工作流编辑、自动化流程产品。在当前MVP方案中我们基于Zion行为流能力构建了 创建订单、查询订单状态、更新用户AI权限、支付宝支付回调多种行为流功能。

帮助文档入口：行为流 | Zion 帮助中心

通过 Cursor 调用 Zion 行为流的优势

• 可视化配置行为流逻辑
• Zion 行为流支持异步、同步两种调用方式供开发者按需选择
• Zion 行为流支持 RBAC+ABAC 的权限管理 ，让你的业务数据拥有安全保障

Zion 支付服务

Zion 集成了 微信小程序支付、微信H5支付、支付宝电脑网站支付三类支付服务。在当前MVP方案中我们采用了支付宝电脑网站支付服务

帮助文档入口：Zion 支付配置全解：微信支付与支付宝接入与优化指南 | Zion 帮助中心

Zion 支付宝支付服务在本次方案中的调用流程

通过 Cursor 调用 Zion 支付服务的优势

• 可视化配置支付回调逻辑
• 无需进行繁琐的加签、验签流程

Zion 可视化数据库

Zion 提供了数据库搭建可视化以及数据库管理可视化能力，让用户可以清晰的看到当前业务系统中的不同数据表、字段、关联信息以及不同表存储的数据详情。在当前MVP方案中我们构建了一个最简单数据存储系统，包括AI产品信息表、订单表以及 Zion 为支付服务、AI服务默认提供的支付记录、AI会话记录表。

帮助文档入口：数据管理指南 | Zion 帮助中心

Zion 权限管理

权限系统是商业化软件的核心基础设施，通过精细化权限控制，有效防止数据泄露和未授权访问，保障系统和数据的完整性与安全性。Zion 提供基于角色（RBAC）和属性（ABAC）的权限管理体系，支持灵活、细粒度的权限配置。在当前MVP方案中我们约束了已登录且拥有AI调用权限的用户才能正常使用AI Agent 服务

帮助文档入口：权限管理系统 | Zion 帮助中心

通过 Zion 实现权限管理的优势

可视化的配置 RBAC + ABAC

Zion 对象存储服务

Zion 提供了基于阿里云的项目媒体文件的存储服务 ，在当前MVP方案中我们将用户的餐食图片上传到了Zion 的对象存储空间内

帮助文档入口：升级项目和算力购买 | Zion 帮助中心

使用 Zion 对象存储的优势

• 快速上传媒体文件
• Zion 的媒体文件路径执行了防盗链措施，媒体文件在OSS上的URL会动态更新

Zion Log 服务

Zion 日志服务可以帮助开发者快速定位到系统服务端的请求报错、返回细节，提升开发效率。我们可以清晰的从图中的日志上看到某个时间点的接口调用详情

帮助文档入口

Zion 日志服务 ｜ Zion帮助中心

Zion 算力升级服务

Zion 在不同的版本项目之间存在 RPS 的不同限制，你可以在以下三个帮助文档中查看 Zion 平台不同版本项目的资源赠送额度和服务器算力升级指引，当你在 Zion 的后端服务遇到高并发请求场景 可通过 Zion 平台的算力升级服务完成当前项目后端所在服务器的资源配置升级

升级项目和算力购买 | Zion 帮助中心

付费版本服务器升级与迁移指南 | Zion 帮助中心

RPS（每秒请求数）详解 | Zion 部署与运维 | Zion 帮助中心

Zion & Cursor 无代码平台中的详细配置流程

在了解完 Zion 服务端的能力后，我们来看看「 Cursor AI商业应用 MVP 」模板内具体是如何配置的

Zion 可视化数据库配置

配置区域指引：进入项目编辑器 - 左上角数据库入口 - 数据模型

账户表

Zion 的账户表为系统默认表，我们在账户表中额外加入了「can_use_ai 」字段，并且选择了布尔类型（True/ False），用于表明用户是否存在 AI 服务调用权限

我的订单表

我们在当前项目中添加了一张「我的订单」表，并添加了「订单金额」、「订单状态」、「商品名称」字段以记录订单数据

在 Zion 中如果需要开通任意支付能力，用户必须先在自己的业务数据库中构建一张订单表，在配置支付功能的时候必须选择这张订单表，以建立订单表和支付记录表的关联

在构建好「我的订单」表后，我们选择了「账户」表对「我的订单」表建立了「1对N」关系关联，含义是「一个账户可能拥有多条订单记录」

产品表

我们在当前项目中添加了一张「产品」表，并添加了「价格」、「产品名」字段以存储 AI 服务的服务名称和价格

Zion 行为流配置

配置区域指引：进入项目编辑器 - 左上角行为流入口

createOrder

我们在行为流内创建了「createOrder」行为流，用于触发在拉起支付宝支付前的「创建订单」的操作，这个行为流中包含了几个信息，你可以逐一点击行为流的节点查看：

输入（行为流默认节点）：不需要任何配置

getUserID（行为流已经封装好的行为）：用于获取已登陆用户的唯一 ID

queryGoodsPrice（我们自行配置的行为）：用于查询「产品」表中 AI 服务的价格信息

createOrder（我们自行配置的行为）:用于创建订单

输出（行为流默认节点）：用于输出创建订单成功后的 orderid （订单 id）、 goods_name（AI 产品名称） 、amount（订单金额）

queryOrderStatus

我们在行为流内创建了「queryOrderStatus」行为流，用于触发在拉起支付宝支付后页面的「查询订单状态」的操作，这个行为流中包含了几个信息，你可以逐一点击行为流的节点查看：

输入（行为流默认节点）：用于输入需要查询的 order_id

queryQrderStatus（我们自行配置的行为）:用于根据 order_id 查询订单状态

输出（行为流默认节点）：用于输出 status （订单状态）

updateUserAiAccess

我们在行为流内创建了「updateUserAiAccess」行为流，这个行为流和上述两个行为流不同，属性是「数据库触发器」，用于在用户成功调用AI服务后（「会话」表「数据增加时」），修改「账户」表中「can_user_ai」为「false」。这个行为流中包含了几个信息，你可以逐一点击行为流的节点查看：

行为流入参（我们自行配置的内容）：触发了「会话」表「数据增加」的账户 ID

输入（行为流默认节点）：用于输入新增「会话」的账户 ID

updateUserAiAccess（我们自行配置的行为）:用于根据 账户 ID 修改「账户」表中「can_user_ai」为「false」

输出（行为流默认节点）：不需要配置输出

Zion 支付配置

配置区域指引：在 Zion WEB项目编辑器模式下 - 设置 - 支付 - 支付宝支付 - 激活 - 选择「我的订单」表 - 完成支付宝商户号、商户私钥 、支付宝公钥 的配置

在支付激活成功后可以看到系统表新增「支付」、「周期性支付」、「退款」三张表

支付回调配置

在支付激活成功后，行为流内会新增如图所示三个有关支付的行为流，支付宝系统会在确认收到用户的钱后通过 Zion 的支付回调行为流告知支付结果。

我们在「支付宝支付或退款」行为流内的 「Success」节点下配置我们的系统在收到用户的钱后的行为配置。

我们配置了「updateOrderStatus」节点用于修改订单的状态为「已支付」

我们配置了「updateUserAiAccess」节点用于开启用户的AI调用权限

Zion AI 智能体配置

配置区域指引：进入项目编辑器 - 左上角 AI 入口

在当前MVP方案中我们构建了一个最简单的AI烹饪专家智能体，基于用户上传的餐食图片给出毒辣点评。

我们在「输入」的地方添加了一个「图片」类型的「foods」

我们在「预置提示」区域配置了「角色」和「任务详情」信息

我们选择了纯文本的流式输出方式

Zion 权限管理配置

配置区域指引：进入项目编辑器 - 左上角 AI 入口

在当前 MVP 方案中，我们只允许用户 「can_use_ai」字段属性为「真/true」的角色调用AI agent

并禁止任何用户篡改自己的 AI 调用权限

常见问题

如何获取支付宝商户的密钥

用支付宝账号扫码登录支付宝开放平台

支付宝开放平台链接：https://open.alipay.com/develop/manage

创建网页应用（网页应用的地址URL必须是你在阿里云已经购买且备案的域名，如果使用Zion的测试域名 支付宝平台有极大概率会封禁你的签约权限长达30天，该域名不需要你有实际的业务在运转）

API管理 - 立即接入 - 接入”电脑网站支付“能力 - 选择你创建好的网页应用

在控制台 - 开发设置 - 接口加签方式 - 选择密钥（普通使用）- 根据提示生成商户私钥和支付宝公钥

获取 APPID

将取到的商户私钥、支付宝公钥、AppId配置到 Zion 设置 - 支付设置内

我第一次生成项目就报错了

当你遇到通过 prompt 第一次生成失败，不要慌，从页面上复制对应的报错粘贴给到 Cursor 等待修复即可，如果你希望能进一步理解报错，请认真查看 Cursor 修复的描述 ，对于你后续的Vibe Coding 有一些帮助

还没有注册支付宝商户号如何走通流程？

先前往 设置 - 权限管理 - 已登陆用户 - Agent -高级筛选 - 删除 AI 的调用限制

在Cursor 的对话框中描述：我目前没有支付的商户号，在支付的步骤模拟支付成功的交互后跳转到AI分析的页面

你就可以看到模拟的支付页面并在点击按钮后进入到AI分析页面

如何在一个项目内接入多个 AI Agent 或 其他行为流 ？

多个 AI Agent 本质上是需要告诉 Cursor 我们额外的 AI Agent 配置 ，你可以进入：Zion Prompt 生成工具 中选择，配置提取 - AI Agent 配置 ，将提取出来的 Agent 配置 告诉给 Cursor 。 Cursor 会基于我们前期提供的 AI Agent 接入的规则自行接入。

行为流（Action Flow）同理，通过复制对应行为流的 Json 告诉 Cursor 你需要在哪个环节执行。

如何把应用部署到互联网上？

当我们基于前面的所有流程开发完项目后，你的项目只能在http://localhost:xxxx（你的应用端口号）访问，无法分享你的应用到互联网上。

所以接下来，为你推荐一款快速部署项目的神器：Zeabur

Zeabur 是一款为Vibe Coding 而生的云部署产品｜ 快速开始 - Zeabur

当你注册并登陆到 Zeabur 后，选择通过 Cursor 进行部署

在页面中点击新建项目并选择一个地区

点击从 Cursor 部署

点击后会从 Cursor 中弹出 打开 Zeabur 的弹窗，点击打开即可

Zeabur 智能体会引导你完成部署操作（操作过于简单！我都不知道写啥了...）

tips：如果遇到 Zeabur 在选择地区的时候没有响应 你可以发消息给 TA 继续下一步

按照 智能体提示 新建项目 等待部署完成

最后你将获得一个可供测试的公网域名！

我想拓展更多的功能

当你已经完全掌握了这个方案背后的原理（即 Zion 服务端对接的流程），你大概率想继续完善你的产品（不局限于 AI agent 调用 、支付接入、用户登陆注册），可能会有以下类似的需求：

纯前端的需求，例如：

我想让用户体验AI的地方更好看

我想在用户先上传图片，在付费后立即开始调用AI

....

当你遇到不需要和数据库有任何交互的需求时，你可以直接和 Cursor 对话来实现你的想法

后端的需求（需要和数据库有交互的需求），例如：

我想增加一个用户反馈bug的表单

我想增加一个 AI 分析记录的看板

...

你有以下两个解决方案，但不管是哪一个解决方案你都需要提前在 Zion 上设计好你的数据模型：

方案1：仔细查看 Zion 行为流的配置参考 ，利用行为流的 “接口自定义” 能力编辑好你的业务中涉及到的接口。

以 「我想增加一个用户反馈bug的表单」为例，你需要先在通过 Zion 可视化数据库配置完成 bug 反馈数据库表的创建

通过 Zion 行为流配置完成 「提交 bug」的行为流配置

复制「提交 bug」的行为流

进入：Zion Prompt 生成工具 中选择，配置提取 - 行为流配置 ，将提取出来的行为流配置 告诉给 Cursor 。 Cursor 会基于我们前期提供的行为流接入的规则自行接入。

方案2: 利用 Zion 的 GraphQL 生成规则 和 Zion MCP 服务生成你需求的接口请求参数

以 「我想增加一个用户反馈bug的表单」为例，你需要先在通过 Zion 可视化数据库配置完成 bug 反馈数据库表的创建

在Cursor 内增加 zion-gql-api-rules 和 Zion-mcp-rules

暂时无法在飞书文档外展示此内容

接入 Zion MCP 服务

在你描述出你的需求后，Cursor 会基于 Zion MCP 服务获取到当前项目的数据库设计信息 并 结合 zion-gql-api-rules 生成接口请求的参数，随后 Cursor 会完成项目的开发

有关 Zion MCP 服务 和 Cursor Rules 的介绍在用 Cursor 生成你的 Zion 代码组件 这个最佳实践中有详细描述

Cursor & Zion 最佳实践征集计划

本方案仅实现了 「WEB 前端框架接入Zion 服务端」这一个载体场景 ，但 Cursor 做为一款出色的 AI 驱动的代码生成工具，也可以生成 包括小程序、APP 等不同客户端的代码，如果你已经熟练掌握了 Cursor & Zion 的接入方案，我们欢迎你分享基于此套方案的延伸产出物

试试看 Kiro / Trae / lovable 也按照方案的思路去生成？

试试看 ios APP / Windows APP / 支付宝小程序 / 抖音小程序 也接上 Zion 的服务端 ？

试试看 拓展产品更多的功能