连接 Zion 后端 (BaaS)

Zion 提供基于 PostgreSQL 的全托管后端基础设施。通过 Headless 模式，Zion 将其底层的数据库、身份鉴权、业务逻辑流（Actionflow）以及 AI 智能体编排能力，全部转化为标准、干净的 GraphQL API 对外暴露。

这意味着你可以将 Zion 作为纯粹的 BaaS（后端即服务），无缝接入 React、Vue、Next.js、小程序等任何前端项目。开发者无需编写和维护任何后端路由或服务器环境，即可构建复杂的全栈应用。同时，结合 Zion 专属的 MCP 协议与开发技能（Skill），该架构能够为 Cursor 等 AI 编程助手提供极速的 Vibe Coding 开发体验。

使用 Zion BaaS 的优势

Zion 不仅仅是一个简单的数据库替代品，而是一个生产级的全托管后端（BaaS）。无论你采用传统的开发方式，还是结合 AI 编程助手，Zion 都能为你带来显著的优势：

1. 开箱即用的高性能后端：Zion 提供了基于 PostgreSQL 的底层架构，内置了完善的身份鉴权（Auth）、复杂的业务逻辑流（Actionflow）以及企业级的数据权限控制（RLS）。你无需从零搭建和维护服务器，即可获得高可用、可扩展的后端基础设施。
2. 极简的前端集成体验：你在 Zion 后台可视化搭建的所有数据模型、业务逻辑和 AI 智能体，都会自动转化为标准、干净的 GraphQL 接口。前端无需引入臃肿的 SDK，只需发起简单的 GraphQL 调用，即可完成复杂的业务交付。
3. 与 AI 编程助手的完美融合 (Vibe Coding)：在使用 Cursor 等 AI 助手时，传统的开发方式极易产生“API 幻觉”。而 Zion 提供了专属的 MCP 协议与开发技能（Skill），让 AI 能够通过“接口自省”实时、准确地读取真实的后端结构。这种确定性从根本上消灭了接口幻觉，极大提升了前后端联调的初次通过率。

获取 API 端点与鉴权凭证

接入 Zion 后端的第一步是获取项目的 API 端点。Zion 为每个项目提供统一的 GraphQL 接口地址（需将 {projectExId} 替换为真实的项目 ID）：

HTTP 端点 (用于常规 Query 和 Mutation):

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

WebSocket 端点 (用于 Subscription 实时订阅):

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

💡 提示：本地开发时还需要高权限的 Admin Token。可在 Zion 编辑器顶部导航栏的 「连接后端」 弹窗中一键复制。该弹窗内还内置了 GraphiQL 调试面板，可直接编写并测试 GraphQL 语句，验证后端逻辑。

⚠️ 警告：Admin Token 具有最高权限，仅限本地开发或受信任的服务器环境（如 Node.js 服务端）使用。切勿将其泄露或硬编码在暴露给用户的纯前端客户端代码中。

Vibe Coding：接入 AI 编程助手

如果使用 Cursor、Windsurf、Claude Code 等 AI 编程助手，Zion 提供了专属的 MCP 服务器 与 开发技能 (Skill)。它们能帮助 AI 准确获取 Zion 的后端结构，根据自然语言指令自动生成对应的前端对接代码。

Zion MCP

Zion MCP（Model Context Protocol）服务器允许 AI 助手安全地连接到你的 Zion 账号。

核心能力

1. 接口自省（GraphQL Introspection）：核心能力。AI 可直接调用 get_project_schema 工具，实时读取后端的完整 Schema（包括数据表结构 dataModel、行为流 actionFlows、第三方 API apis 和 AI 智能体配置 zAiConfigs）。这让 AI 能够准确获取后端结构，避免接口幻觉。
2. 项目上下文管理：AI 可使用 get_projects 工具搜索账号下的项目，并通过 set_current_project 自动切换当前开发的项目上下文。
3. 智能 Mock 数据生成：内置 create_and_save_mock_data_recursively 工具。在开发前端列表或详情页时，可直接让 AI 为指定的表生成 Mock 数据。该工具会自动处理复杂的外键依赖和类型转换，并将数据直接插入到 Zion 数据库中，加速前端 UI 调试。
4. 自动鉴权管理：当 Token 过期时，AI 可通过 reauth 工具自动触发 OAuth 重新认证，保持开发流程不中断。

如何接入

• 对于 Cursor / Windsurf / Cline (VS Code)： 将以下 JSON 配置添加到对应编辑器的 MCP 配置文件中（例如使用 Cline 插件时，直接配置 mcpServers 即可）：

  {
    "mcpServers": {
      "zion": {
        "command": "npx",
        "args": ["-y", "zion-mcp"]
      }
    }
  }

  (注：Cursor 用户也可在 Zion 的「连接后端」弹窗中点击「一键安装」按钮自动完成配置。)

• 对于 Claude Code： 在终端运行以下命令：

  claude mcp add zion -- npx -y zion-mcp

• 对于 Codex： 在终端运行以下命令：

  codex mcp add zion --command npx --args "-y,zion-mcp"

Zion 开发技能 (Skill)

Skill 是 Zion 官方维护的 AI 开发规范集合（zion-baas-skill）。

核心能力

安装后，AI 助手将遵循 Zion 后端的专属规则与底层协议细节：

1. 底层数据操作协议 (GraphQL Rules)：
   • 严格的过滤语法：规范了使用 Zion 独有的“操作符优先 (Operator-First)”模式构建复杂的 where 查询（例如：{"_eq": {"bigint_operand": {"left_operand": {"column": "id"}, "right_operand": {"literal": "1"}}}}）。
   • 公式与函数：定义了如何在查询中使用 Zion 内置的数十种函数（如 CONCAT, EXTRACT_DATE, GEO_DISTANCE 等）。
   • 聚合与排序：定义了 [table]_aggregate 的统计用法及多级关联排序逻辑。
2. 行为流协议 (Actionflow Protocol)：
   • 同步行为流：定义了使用 fz_invoke_action_flow 发起 Mutation 并直接获取结果的调用方式。
   • 异步行为流：定义了对于耗时任务，需先调用 fz_create_action_flow_task 获取 taskId，再通过 fz_listen_action_flow_result 订阅 WebSocket 监听状态（CREATED -> PROCESSING -> COMPLETED）的流程。
3. AI 智能体协议 (AI Agent Protocol)：
   • 流式输出与推理：定义了通过 fz_zai_create_conversation 创建会话，并订阅 fz_zai_listen_conversation_result 来平滑处理状态流转（IN_PROGRESS -> STREAMING -> COMPLETED），以及提取 reasoningContent 展示思考过程的规范。
   • 结构化输出：定义了处理带有 JSONSchema 约束的非流式结构化返回的规范。
   • 多轮对话：定义了使用 fz_zai_send_ai_message 继续对话或 fz_zai_stop_responding 中止生成的规范。
4. 文件上传规范 (Binary Asset Upload)：
   • 约束了两步走上传流程：先计算文件 MD5 并调用 imagePresignedUrl 等接口获取直传 URL 和文件 ID；然后通过 HTTP PUT 将二进制流上传至 OSS，最后将文件 ID 存入业务表。
5. 第三方 API 集成：
   • 规范了如何正确调用导入的外部 API，并安全地解析 field_200_json 和 responseCode。

如何接入

• 对于 Cursor / Windsurf / Cline (VS Code)： 复制以下提示词（Prompt），发送给 AI 聊天窗口即可：

  请仔细阅读并安装以下仓库的开发技能:
  https://github.com/functorz-tech/zion-baas-skill

• 对于 Claude Code / Codex 等支持 CLI 的工具： 在终端运行以下命令进行全局安装：

  npx skills add https://github.com/functorz-tech/zion-baas-skill -g

开发工作流建议

接入完成后，可按照以下流程高效推进项目：

1. 后端可视化搭建：在 Zion 网页端完成数据库表、行为流（Actionflow）和 AI 智能体的可视化配置。
2. 配置 AI 助手：按照上述指南，在你的 AI 编程助手（如 Cursor）中配置好 Zion MCP，并安装 Zion 开发技能 (Skill)。
3. AI 读取上下文：在 AI 编程助手中，告知 AI 你的 projectExId，并让其通过 MCP 读取最新的后端 GraphQL 结构。
4. 自然语言开发：直接下达前端开发指令。例如：“我后台配置好了一个名为’分析图片’的 AI 智能体。请帮我写个页面，并在用户上传后流式展示 AI 智能体的分析结果。” AI 将根据读取到的接口结构，自动生成对应的前端对接代码。