Zion BaaS 使用指南

👋 欢迎使用 Zion BaaS 方案！

核心目标：以 Zion 作为 BaaS 后端，借助 coding agent 快速完成环境搭建与接口调用，专注核心创意的实现。

从未 Coding 过的新手教程入口：Vibe Coding 接入 Zion BaaS Skill 做有真实数据的网站

🚀 Zion BaaS 极速方案介绍

💡 省流摘要：开发者在 Zion 平台快速配置数据模型与 AI Agent，coding agent 即可自动拉取并分析后端 Schema，自动编写出完整的前端页面与接口调用代码，开发者无需手写任何后端代码。

📊 极速开发流转全景图

  [ 1. Zion 平台可视化配置 ]
  ├── 数据库：可视化建表（或使用 AI Copilot 辅助生成）
  ├── 行为流：通过图形化工具编排逻辑
  └── 智能体：AI Agent 编排（配置 Prompt、工具调用与结构化输出）
                 │
                 ▼ (自动生成并暴露统一的后端 GraphQL API 接口)
                 │
  [ 2. 本地 Coding Agent 工作区 ]
  └── 规则导入：克隆 zion-baas-skill 开发规则
                 │
                 ▼ (coding agent 自动运行接口自省，实现数据模型对齐)
                 │
  [ 3. 前端 Vibe Coding 研发 ]
  ├── 开发者：使用自然语言下达前端功能指令
  └── coding agent：自动编写出完全匹配后端的 GraphQL 代码与视图

如果你想把后端逻辑、数据库和服务器部署也全丢给 AI 帮你写，往往会一头撞进以下两个深坑：

• 两头开战，时间根本不够用：一个人既要搓前端 UI，又要费劲去配后端环境、写 API 路由。要是还傻傻地让 AI 帮你独立写后端、搭环境，AI 一旦产生幻觉瞎编接口，本地运行直接满屏红字报错。到头来你连完整的页面都没搓完，时间全被浪费在无穷无尽的前后端联调上了。
• 自己硬磕大模型，费钱又折腾：若自建 AI Agent，开发者不仅需要自掏腰包购买大模型 Token，每次还得手动去重复折腾 SDK 对接、会话历史管理和流式（SSE）传输等繁琐的轮子代码。

Zion (functorz.com) 的 BaaS 模式能够有效解决上述痛点：

1. 可视化配置后端，保障接口一致性：在 Zion 网页编辑器中可视化配置 PostgreSQL 数据库表、权限规则和行为流（Actionflow）。开发者仅负责定义数据模型和业务流，coding agent 只需直接调用生成的接口，规避了前后端 API 无法对齐的问题。
2. 一站式 AI Agent 接入：开发者无需在代码中引入任何大模型 SDK，也不需处理 API 凭证管理和历史上下文存储。在 Zion 平台可视化创建 AI Agent、选择大语言模型并设定 Prompt 即可。Zion 会自动将其封装为 GraphQL 异步流式接口，前端只需调用标准 GraphQL 指令即可直接支持流式文本交互和思考（Reasoning）过程展示。
3. 精准的 AI 代码生成支持：通过配置专属于 Zion 的 Skill 规则文件，coding agent（Cursor / Claude Code / Kimi CLI / Codex / opencode）能够高度精准地编写出符合 Zion GraphQL 协议前端调用代码，将 AI 编造假 API 规范的幻觉降到最低。
4. 免服务器运维与一键托管部署：后端逻辑、数据库及对象存储完全由 Zion 托管，自动生成并暴露统一的 GraphQL 接口地址（不依赖海外服务，避免连接延迟），让选手的精力能完全集中在前端 UI/UX 与核心创意的实现上。

开发者负责定义结构与创意，Zion 与 coding agent 负责搞定代码实现。

1. Zion BaaS 架构与核心概念

在开始编码前，开发者需要了解 Zion 的 BaaS 模式以及 AI 助手的工作方式。

1.1 什么是 Zion

Zion 是一款全栈无代码开发平台。虽然它本身自带可视化无代码拖拽画布用于搭建前端，在本方案中，开发者只需将其作为 BaaS（后端即服务） 托管数据库与业务逻辑，前端则由开发者手写并借助 AI 辅助生成。

因此，开发过程只需用到 Zion 的 数据 + 行为 这两块，即 "BaaS 模式"：

模块职责如何使用数据（BaaS）内置关系型数据库（PostgreSQL）可视化建表、配置权限规则行为（逻辑）工作流（Actionflow）+ AI Agent + 外部 API配置业务流逻辑、搭建流式 AI 助手、接入三方服务

1.2 什么是 BaaS 模式

在 BaaS 模式下：开发者自主编写前端（React / Vue / 小程序），后端全部交给 Zion。

传统的后端开发需要开发者设计、编写并部署几十个不同的 API 路由。而在 Zion 的 BaaS 模式中，零手写路由，整个项目的后端就只有这两个统一的连接地址：

HTTP 接口   : https://zion-app.functorz.com/zero/{projectExId}/api/graphql-v2
WebSocket 订阅: wss://zion-app.functorz.com/zero/{projectExId}/api/graphql-subscription

前端只需通过这两个地址，就能搞定一切事情：查数据库、触发工作流、调用 AI、上传文件。

1.3 优秀实战案例

以下是基于 Zion BaaS 模式构建的真实落地案例，涵盖了移动端和 Web 端：

• 「不小众」微信小程序：一款完全以 Zion 作为 BaaS 后端、前端使用微信原生框架开发的小程序，在Nano banana 2 和 GPT-IMAGE-2 爆火时期推出
• howtone.cn（Web 站点）：一款基于 AI Agent、采用 Cursor + Zion BaaS 技术栈开发的小红书内容营销工具。展现了 AI 辅助开发在 Web 端与 Zion 数据库、流式 AI 智能体无缝联调的真实商业化应用成果。

1.4 复杂后端业务逻辑的承载：行为流（Actionflow）

在 1.2 节中我们了解到，BaaS 模式下整个项目的后端被精简为了两个统一的接口地址。此时，一个极其关键的逻辑问题随之产生：既然前端不再手写任何后端 API 路由，那么当我们需要处理复杂的后端业务逻辑（如多表联动更新、支付状态回调、外部 API 对接、大模型长链路调用）时，“后端逻辑”应该写在哪里？

在 Zion 方案中，这些复杂的后端业务逻辑完全由行为流（Actionflow）来承载和托管。

Zion 的行为流为开发者提供了流程化操作编排和多种触发方式。它本质上是一种图形化的后端逻辑编排工具，最终生成为自定义的后端业务“行为”（类似于 Supabase 的 Edge Function 或是传统的云函数与服务器接口）。

💡 核心优势

• 可视化逻辑编排：无需编写任何服务端代码，即可通过拖拽节点实现多步事务处理（如创建订单 → 扣减库存 → 自动赠送优惠券并记录日志）。
• 同步与异步双模式支持：
• 同步模式：在单数据库事务中运行，若中途报错会自动回滚，有运行超时限制，最适合简单的增删改查、逻辑计算或数据校验。
• 异步模式：每个节点在独立的数据库事务中运行，无运行时长限制。在行为流中调用 AI Agent 或第三方外部接口时，必须配置为异步模式。
• 严密的权限管理：行为流原生支持 RBAC（基于角色的权限控制）和 ABAC（基于属性的权限控制），保障你的业务数据调用安全。

1.5 Zion 提供的 Skill 作用与分工

Skill 是一份用于指导 AI 编码工具（Cursor / Claude Code / Kimi CLI / Codex / opencode）的系统规则与规范文档，能够让 AI 准确理解如何与 Zion 后端进行高效交互。

Skill作用类比zion-baas-skill告诉 AI 怎么连接 Zion 后端（GraphQL 规则、认证方式、Actionflow/AI Agent 调用协议）后端的「使用说明书」zion-frontend-dev-skill告诉 AI 怎么写前端（React、小程序、Apollo Client 配置、UI 风格、部署）前端的「代码规范书」

2. 准备工作

在开始之前，确认以下都已就绪：

• 已有 Zion 账号（functorz.com）
• 已在 Zion 创建一个项目（空项目或使用任意模板创建的项目均可）
• 已安装支持 Skill 的 coding agent（Cursor / Claude Code / Kimi CLI / Codex / opencode）
• 获取项目的 projectExId（进入项目编辑器后，在浏览器地址栏 project/ 与 /editor 之间找到那段 ID，如 abc123def456）

3. 安装开发 Skill

为了让开发者完全不需要区分操作系统，也不需要区分不同的 AI 编码工具，本套方案全面支持了由 Vercel 社区推出的开源 Agent 统一 Skill 包管理器：skills。

你只需在项目根目录运行一行统一的 npx 命令，它就会自动下载并把开发 Skill 安装到 Cursor / Claude Code / Kimi CLI / Codex / opencode 等所有主流 coding agent 中：

3.1 极速一键安装（全平台通用）

无论你是 macOS / Linux 还是 Windows，只需在项目根目录的终端（Terminal 或 PowerShell）中运行以下指令：

npx skills add https://github.com/timqin-m/zion-baas-skill --all && npx skills add https://github.com/timqin-m/zion-frontend-dev-skill --all

💡 这个命令做了什么？

• npx skills add <完整 URL> --all 会全自动把 Zion 的前端/后端两套 Skill 克隆、打包并软链接（Symlink）到本地项目的所有 Agent 目录（如 .cursor/skills/、.opencode/skills/ 等），实现一步到位！

3.2 手动命令安装（备用方案）

如果你的开发环境中 npx 安装遇到了网络波动，也可以使用下述原生 Git 循环脚本进行手动克隆：

macOS / Linux 手动命令：

for agent in .cursor .claudecode .kimi .codex .opencode; do mkdir -p "$agent/skills" && rm -rf "$agent/skills/zion-baas-skill" "$agent/skills/zion-frontend-dev-skill" && git clone https://github.com/timqin-m/zion-baas-skill.git "$agent/skills/zion-baas-skill" && git clone https://github.com/timqin-m/zion-frontend-dev-skill.git "$agent/skills/zion-frontend-dev-skill"; done

Windows (PowerShell) 手动命令：

foreach ($d in ".cursor", ".claudecode", ".kimi", ".codex", ".opencode") { New-Item -ItemType Directory -Force -Path "$d/skills" | Out-Null; Remove-Item -Recurse -Force -ErrorAction SilentlyContinue "$d/skills/zion-baas-skill", "$d/skills/zion-frontend-dev-skill"; git clone https://github.com/timqin-m/zion-baas-skill.git "$d/skills/zion-baas-skill"; git clone https://github.com/timqin-m/zion-frontend-dev-skill.git "$d/skills/zion-frontend-dev-skill" }

3.3 💡 AI 自动安装（备用方案）

如果你不想打开任何终端，也可以直接在项目根目录下，打开 AI 聊天框发送以下指令给 coding agent 自动安装：

请帮我在本地自动完成 Zion 两个 Skill 的安装配置：
1. 在项目根目录下创建对应我当前编辑器（如 Cursor / Claude Code 等）的 Skill 存放文件夹。
2. 将后端 Skill 仓库克隆至该文件夹下的 zion-baas-skill 目录：https://github.com/timqin-m/zion-baas-skill
3. 将前端 Skill 仓库克隆至该文件夹下的 zion-frontend-dev-skill 目录：https://github.com/timqin-m/zion-frontend-dev-skill

安装完成后，coding agent 将自动感知并应用对应的 Skill。在开发过程中，coding agent 会通过接口自省（GraphQL Introspection）自动获取你后端的数据库表与业务结构，实现完全无感的数据模型对齐！

4. 在 Zion 平台配置后端

打开 functorz.com，进入项目编辑器，按需完成以下配置。

4.1 创建数据库表（必须）

路径：左侧「数据」

📖 详细参考：数据管理指南 | Zion 帮助中心

💡 数据建模提示：

在 Zion 平台中，开发者既可以通过可视化操作面板手动精细地配置数据表、字段与关联关系，也可以使用数据面板中的 AI 数据库助手（AI Copilot） 辅助快速建模。

如果选择使用 AI Copilot，可以直接用自然语言下达建表指令，例如：

“帮我建一个博客系统的数据表，包含文章（post）和评论（comment）表。文章需要有标题、内容、状态（draft/published）和封面图；评论表需要外键关联到文章表。”

AI 助手会自动帮你生成对应的数据模型、匹配字段类型并创建外键关系。数据表设计完毕后，请点击右上角“更新后端”。

生成的表结构（以博客系统为例，供核对）：

表名字段类型说明posttitle文本文章标题postcontent文本文章内容poststatus文本发布状态（draft/published）postcover_image_id整数封面图 ID（关联系统 FZ_Image 资源 ID，而非 URL）commentpost_id整数（外键）关联到 post 表的 idcommentcontent文本评论内容

4.2 配置权限（可选）

路径：左侧「权限」

📖 详细参考：权限管理系统 | Zion 帮助中心

4.3 配置 行为流（Actionflow）

路径：左侧「Actionflow」→「创建」

📖 详细参考：行为流 | Zion 帮助中心

配置完后记录其名称，后续直接告诉 AI 即可。

4.4 配置 AI Agent

路径：左侧「AI Agent」→「创建」

📖 详细参考：配置和使用 AI | Zion 帮助中心

设置 Prompt、选择大语言模型、定义输入输出参数（如 Tools 调用、流式输出与 JSON 结构化输出）。

4.5 配置支付服务（可选）

路径：左侧「支付」

📖 详细参考：支付配置全解 | Zion 帮助中心

Zion 集成了微信小程序支付、微信 H5 支付及支付宝支付等主流服务。

• 优势：支持可视化配置支付回调逻辑，开发者无需在代码中编写繁琐的加签、验签与回调校验。

5. 让 AI 写代码

5.1 极简启动指令（Prompt 模板）

得益于本地的 Zion 开发 Skill，AI 已经具备了通过本地接口自省直接获取项目最新后端结构的能力。开发者不需要充当“传话筒”去手动复制粘贴任何表结构字段或复杂的配置 ID。首发 Prompt 可以极其简单：

我正在使用 Zion 方案作为项目的后端技术栈，项目 projectExId 为 <你的projectExId>。

请通过接口自省（Introspection）自动读取并分析我当前的后端 GraphQL 结构。
然后帮我编写前端代码，搭建一个博客系统，包含：
1. 文章列表页（按创建时间倒序，只显示已发布状态的文章）
2. 文章详情页（内容 + 评论列表）
3. 发表评论功能（需要登录）

发送该指令后，coding agent 会通过自省自动阅读并分析最新的后端设计，并自动编排好所有 GraphQL 语句与前端 UI 代码。

5.2 四类典型场景

在接下来的功能迭代中，开发者可以直接通过极简的自然语言给 AI 派发任务：

场景一：纯数据库 CRUD 交互

• 你的 Prompt：“帮我写个用户管理列表，支持按注册时间排序。”
• AI 自动执行的动作：自动自省并匹配对应的数据库表、检索其字段规范 → 生成精准的 GraphQL 查询语句 → 编写前端 React 代码。

场景二：接入 AI Agent 智能体

• 你的 Prompt：“我后台配置好了一个名为'分析图片'的 AI Agent。请帮我写个页面，放一个图片上传组件，并在用户上传后流式展示 AI Agent 的分析结果。”
• AI 自动执行的动作：在本地/云端检索并确认名为“分析图片”的 AI Agent 对应的结构与参数 Key → 自动构造 fz_zai_create_conversation 并处理 IN_PROGRESS → STREAMING → COMPLETED 的流式 WebSockets 订阅展示。

场景三：触发行为流（Actionflow）

• 你的 Prompt：“我后台创建并发布了'创建订单'的行为流。请在前端做个下单表单，点击后异步触发该行为流，并实时展示返回结果。”
• AI 自动执行的动作：在 Schema 中定位到“创建订单”对应的真实标识 → 识别其输入参数结构并生成表单验证 → 自动构造 fz_create_action_flow_task 变轨，并通过 fz_listen_action_flow_result 实时监听。

场景四：文件/多媒体资产上传

• 你的 Prompt：“需要实现图片上传功能，上传成功后，把返回的图片 ID 保存到 post 表的 cover_image_id 字段中。”
• AI 自动执行的动作：自动定位文件上传协议 → 编写 File MD5 Base64 计算代码 → 自动构造 imagePresignedUrl 获取凭证、完成 HTTP PUT 物理二进制流上传 → 将返回的 imageId 存储到数据库。

6. 前端 UI 极速美化（最佳实践）

如果想让 AI 生成的界面更加美观，可以直接前往各大开源 UI 灵感库，复制其优秀的 UI Prompt 或组件代码丢给 AI 进行一键修改：

• 初阶（整体视觉设计与风格更换）：DesignPrompts
• 进阶（局部精美样式迭代）：21st.dev
• 高阶（局部炫酷动效组件）：ReactBits

7. 常见坑点速查

7.1 依赖包下载失败

因为外网网络波动，如果依赖包下载频频报错，可在 Chat 中让 AI 切换淘宝/国内镜像源：

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

7.2 第一次运行报错

不要慌，页面报错大多来自前端。

直接打开浏览器开发者工具（F12），查看 Console 里的红色报错详情，并完整复制粘贴发给 AI，让 AI 自动进行一键修复。

8. 核心概念速查（参考手册）

开发过程中有关于 API 协议的不确定细节，可以参考以下规范：

8.1 GraphQL 接口地址与认证

HTTP   : https://zion-app.functorz.com/zero/{projectExId}/api/graphql-v2
WSS    : wss://zion-app.functorz.com/zero/{projectExId}/api/graphql-subscription

8.2 行为流（Actionflow）调用流程

由于代码全部由 AI 自动编写，你无需关注具体的 GraphQL 语法，只需理解其运行逻辑架构：

1. 同步模式流程图

[前端] --- 发起调用请求 (Mutation) ---> [Zion 行为流执行逻辑] ---> 直接返回结果

2. 异步模式流程图

[前端] --- Step 1: 创建任务 (Mutation) ---> [Zion 后端]
                                              │ (返回 taskId)
                                              ▼
[前端] <--- Step 2: 建立订阅 (Subscription) -- [监听状态：CREATED -> PROCESSING -> COMPLETED]
                                              │ (COMPLETED 时携带返回结果)
                                              ▼
                                         [结束，渲染视图]

8.3 AI Agent 调用流程

[前端] --- Step 1: 创建会话 (Mutation) ---> [Zion 后端]
                                              │ (返回 conversationId)
                                              ▼
[前端] <--- Step 2: 建立流式订阅 (Subscription) -- [监听状态：IN_PROGRESS -> STREAMING -> COMPLETED]
                                              │ (STREAMING 逐字返回，COMPLETED 返回完整文本与生图 ID)
                                              ▼
                                         [继续会话: 发送消息 (Mutation)]

8.4 文件资产上传流程

[前端] --- Step 1: 计算文件 MD5 (Base64) ---> 向 Zion 请求上传地址 (Mutation)
                                                    │ (返回: imageId + uploadUrl + Headers)
                                                    ▼
[前端] --- Step 2: 发起 HTTP PUT 请求 -------------> 上传二进制流至 uploadUrl
                                                    │ (上传成功后)
                                                    ▼
[前端] --- Step 3: 关联存储 -----------------------> 将 imageId 保存至你数据库表的 *_id 字段

关键开发原则：

• 依靠 Skill 规范 AI 调用：让 AI 掌握后端的调用逻辑，规避幻觉。
• 一站式 AI Agent：免去繁杂 SDK 拼装，一键选用并一站式集成。
• 可视化行为流：支持同步、异步多模式和严密权限保护，灵活编排核心逻辑。
• 坚持后端先行：先在 Zion 平台或借助 AI Copilot 设计好数据与逻辑，再引导 AI 进行前端开发。