企业官网建设流程全解析

从 PRD 到上线：基于 easy-vibe 课程体系从零构建类 Dify 智能体编排平台

【免费下载链接】easy-vibe💻 vibe coding 101｜The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibe

导读

本篇实战指南以 easy-vibe 课程 Stage 2 的综合项目「Plataforma de Agentes Inteligentes tipo Dify」为蓝本，完整讲解如何围绕一份真实的 PRD，从零构建一个复刻 Dify 核心体验的智能体平台：包含用户控制台、管理后台与平台后端，覆盖智能体管理、对话、调用日志、知识库接入等核心能力。读完本文，你将掌握从需求分析、数据建模、前后端骨架生成、逐模块迭代到端到端联调上线的完整工程方法，并学会借助 AI 辅助完成一个"有平台感"的多角色 AI 产品。

1. 项目定位：跑通一条可演示的主链路

本项目来自 easy-vibe 课程 Stage 2 的扩展实战项目，完整作业说明位于 custom-dify-agent-platform 作业文档，其需求规格见仓库中的 PRD 原文（状态：Draft v0.1）。

与 Stage 2 之前的单页面或单功能项目不同，本项目的核心目标是构建一个"有平台感"的 AI 产品，重点不是复刻 Dify 的全部能力，而是跑通下面这条主链路：

• 创建智能体（Agent）
• 配置 Prompt 与模型参数
• 发起对话
• 查看调用日志
• 可选接入知识库

一句话定义：做一个类 Dify 的最小可用智能体编排平台（MVP）。整个项目包含两个子系统：

后端需要支撑的核心能力包括：智能体管理、会话管理、消息存储、模型调用、调用日志记录、知识库接入。

2. 前置知识：开工前需要掌握的能力栈

PRD 和作业文档都明确要求，在开始本实战前，你应当已经掌握以下 Stage 2 前置章节的内容：

• 前端页面设计与组件库使用：UI 设计、现代组件库
• 后端接口设计与开发：AI 辅助编写接口代码
• 数据库基础与 Supabase：从数据库到 Supabase
• Git 工作流与部署：Git 和 GitHub、部署 Web 应用

2.1 为什么用 Supabase 做后端底座

PRD 明确推荐技术选型为Next.js App Router + Supabase Auth + Supabase Postgres + Supabase Storage，模型层由统一后端适配层对接第三方 LLM。这套选型与前置章节 从数据库到 Supabase 完全衔接：Supabase 是基于 PostgreSQL 的新一代 BaaS，将数据库、认证（Auth）、对象存储（Storage）、实时同步（Realtime）和 Edge Functions 打包成开箱即用的服务，让团队把有限资源集中在业务主链路上。其中两个关键机制会直接影响本项目的实现：

• Row Level Security（RLS）：通过auth.uid()编写"行级安全"策略，实现"用户只能访问自己的智能体和会话"这一核心业务规则，从数据库底层拦截越权访问。
• Auth 会话：用户登录后，Supabase 自动为后续所有请求附带认证信息，配合 RLS 完成多用户数据隔离。

2.2 用 LLM 写后端接口的正确姿势

前置章节 AI 辅助编写接口代码 强调：LLM 不怕复杂需求，怕的是模糊需求。高质量 Prompt 必须包含数据库字段定义（Schema）与具体约束。例如为agents表编写创建接口时，应像下面这样提供完整上下文：

"帮我写一个创建智能体的 API。智能体有名称、描述、system_prompt、模型、温度参数和发布状态；名称和模型必填，温度取值范围 0~2；用户输入不合法时要返回明确的错误信息。"

同时要遵循 RESTful 命名（GET /api/agents、POST /api/agents，而不是POST /api/getAgents）、标准化 HTTP 状态码（200/201/400/401/403/404/500），并且永远不要信任前端输入，关键参数校验必须在后端重新执行。

3. 学习目标与四阶段推进路线

完成本实战后，你将能够：

1. 阅读并理解一份真实的 PRD，从中提取开发任务清单；
2. 设计智能体平台的页面架构和数据模型；
3. 实现智能体创建、对话、日志记录的完整链路；
4. 使用 AI 辅助完成平台型产品开发；
5. 完成端到端联调，交付一个可演示的 AI 平台原型。

整个项目按四个阶段推进，每个阶段对应一个明确的产出：

4. 第一阶段：需求分析 —— 先想清楚再动手

作业文档给出了一条硬性警告：如果对 PRD 的关键问题没有明确答案，不要开始写代码——需求理解不清楚是导致返工的最常见原因。

4.1 阅读 PRD 时要回答的问题

打开 PRD 文档，重点回答：

• 智能体、会话、日志、知识库，哪些必须进入 MVP？
• 页面和路由清单是否已经拍板？
• 模型调用和日志记录的边界是什么？
• 多租户和复杂工作流是否第一版先不做？

仓库中的 PRD 对这些问题的答案是清晰的，这也是本项目区别于"边写边想"式开发的关键：

• MVP 必做：注册/登录、智能体 CRUD、对话页、会话历史、调用日志页；知识库仅支持文本文件上传与基础检索。
• 第一版明确不做：复杂工作流节点编排 UI、多租户企业权限体系、工具调用沙箱、支付与计费、多模型路由策略。

4.2 确认系统架构

根据 PRD 梳理出的系统总体架构如下：

4.3 角色与权限模型

PRD 定义了两种角色，权限边界非常清晰：

对应到数据层面，profiles表中需要role字段来区分身份，而"只能管理自己的资源"这条规则由 RLS 策略在数据库层兜底。

4.4 页面与路由清单（3 套入口、10 个大页面）

PRD 将前端定义为"3 套入口、10 个大页面"，这是后续生成骨架时的直接依据：

A. 官网前台www.xxx.com

B. 用户控制台app.xxx.com

C. 管理后台admin.xxx.com

4.5 关键状态流

在设计数据模型前，先把业务状态机定清楚：

• 智能体：草稿 → 已配置 → 可用 / 停用
• 会话：新建 → 进行中 → 归档
• 文档：上传中 → 处理中 → 可检索 / 失败
• 调用：成功 / 错误 / 超时

5. 第二阶段：搭建项目骨架 —— 用 AI 生成前后端结构

5.1 生成前端页面的参考提示词

作业文档给出了可以直接复用的提示词模板：

请基于当前 PRD，帮我生成一个类 Dify 智能体平台的前端骨架。 要求： 1. 用户侧包括：登录、智能体列表、智能体配置、对话页、日志页、知识库页 2. 后台侧包括：后台首页、用户概览、资源使用概览 3. 先只生成页面结构和假数据，不接真实接口 4. 风格要像现代 AI 平台

PRD 补充了推荐技术栈：Next.js App Router + TypeScript + Tailwind CSS + shadcn/ui，并列出前端核心组件：智能体卡片列表、Agent 配置表单、对话消息列表、Prompt 调试面板、日志筛选表格、文件上传组件。

5.2 页面结构逐项验证

骨架生成后，不要急着写业务代码，先按清单逐项检查：

• 用户控制台和管理后台入口是否分开
• 智能体列表、配置、对话、日志、知识库页面是否完整
• 管理后台首页、用户概览页面是否可访问
• 假数据是否展示了基本的 UI 状态

5.3 设计数据模型：六张核心表

PRD 直接给出了建议的 SQL 表结构，这是整个后端的根基，必须完整保留并理解每个字段的含义：

profiles ( id uuid primary key, email text, role text, created_at timestamptz ) agents ( id uuid primary key, user_id uuid, name text, description text, system_prompt text, model text, temperature numeric, status text, created_at timestamptz ) chat_sessions ( id uuid primary key, user_id uuid, agent_id uuid, title text, created_at timestamptz ) chat_messages ( id uuid primary key, session_id uuid, role text, content text, token_usage int, created_at timestamptz ) knowledge_documents ( id uuid primary key, user_id uuid, agent_id uuid, filename text, status text, chunk_count int, created_at timestamptz ) run_logs ( id uuid primary key, user_id uuid, agent_id uuid, session_id uuid, model text, latency_ms int, prompt_tokens int, completion_tokens int, status text, error_message text, created_at timestamptz )

对照前置章节 从数据库到 Supabase 中的实践方法：可以在 Supabase 的 SQL Editor 中执行这段 DDL，然后在 Table Editor 中确认表结构；每张业务表都应配套 RLS 策略（例如agents.user_id = auth.uid()），并注意profiles表通过外键关联auth.users，而authschema 下的表不建议手动修改。

5.4 接口草案：前后端联调的契约

PRD 给出了完整的 REST 接口草案，前后端应严格按此契约开发：

其中POST /api/chat/sessions/:id/messages的请求示例为：

{ "agentId": "agent_123", "message": "帮我总结一下这个功能的定位" }

6. 第三阶段：迭代开发 —— 逐模块推进业务闭环

在骨架基础上，按以下顺序逐模块补充功能，每完成一个模块就用自检表验证一次：

1. 鉴权：注册、登录、角色区分
2. 智能体管理：创建、编辑、删除、Prompt 配置
3. 对话功能：会话创建、消息收发、模型调用
4. 日志记录：耗时、token 用量、错误记录
5. 知识库接入（加分项）：文档上传、检索、结果注入
6. 管理后台：用户数据、资源使用、调用统计

6.1 模块自检表

6.2 对话链路的实现要点

对话功能是整条主链路的枢纽：前端将消息写入chat_messages，后端调用模型供应商，将"耗时、token 用量、状态"写入run_logs，再返回流式或完整回答。实现时建议把"模型调用适配层"做成独立模块（PRD 的技术选型即"统一后端适配层对接第三方 LLM"），这样未来接入多家模型供应商时只需替换适配层，而不用改动会话与日志逻辑。模型 Key 必须通过环境变量注入，禁止硬编码。

6.3 知识库接入（加分项）：知识库开关模式

作业文档给出了一个务实的 MVP 方案——为每个智能体增加一个"知识库开关"：

• 开启时：先检索知识片段，再将检索结果与用户问题一起发送给模型；
• 关闭时：按普通对话模式响应。

第一版不必追求复杂 RAG，只要做到"检索结果可见、调用链路可解释"即可。knowledge_documents表中的chunk_count、status字段用于跟踪文档切分与处理进度；若想深入了解检索增强的原理与落地形态，可参考本仓库的 Dify 知识库章节 Dify 与知识库接入，其中讲解了 Embedding、Rerank、Top-K 与 Score Threshold 等检索参数的作用。

6.4 关键业务规则

PRD 第 9 节明确了四条必须遵守的业务规则，它们是验收的核心依据：

• 用户只能访问自己的智能体和会话（RLS + 后端双重校验）；
• 删除智能体前需要检查是否有活跃会话；
• 日志中必须记录失败原因（run_logs.error_message不可为空）；
• 知识库文档处理失败要可见（前端展示处理状态）。

7. 第四阶段：联调与上线

7.1 端到端测试场景

至少验证以下两条主链路：

• 注册 → 创建智能体 → 配置 Prompt → 发起对话 → 查看日志
• 管理员登录 → 查看用户数据 → 查看调用统计

7.2 部署前检查清单

• 所有核心接口都做了登录校验
• 智能体归属权限检查通过
• 会话记录、日志记录真实落库
• 模型 Key 使用环境变量，不硬编码
• 错误提示可在前端看到，不只打在控制台

7.3 部署

将项目部署到公网环境，部署流程参考仓库中的 Git 和 GitHub 工作流 与 如何部署 Web 应用（Zeabur）。部署完成后，需要验证线上环境的三件事：登录后可访问核心页面、创建智能体能成功对话、每轮问答都能在数据库查到记录。

8. 交付物与 README 要求

完成项目后需要提交：

• 可访问的线上演示链接
• 源码仓库链接（含 README）
• PRD 文档
• 核心页面截图（智能体管理页、对话页、日志页、后台首页）
• 60 秒演示视频（覆盖创建智能体 → 对话 → 查看日志）

README 至少包含：项目简介、架构说明、技术栈、本地启动步骤、环境变量清单、接口说明。

9. 评分标准：从"能用"到"有平台感"

9.1 提交前最终检查

• 登录后可访问智能体管理、对话、日志页面
• 至少可以创建 1 个智能体并成功对话
• 每轮问答都能在数据库查到记录
• 调用失败时前端可见错误信息且日志已记录
• 项目已部署，README 和演示视频齐全

10. 结语：这个项目练的是什么

这个类 Dify 平台项目与单页面项目最大的区别在于"平台感"：多角色（用户/管理员）、多模块（agents/chat/logs/knowledge/admin）、数据持久化、模型调用链路，四者交织成一个完整的全栈闭环。它把 easy-vibe 课程 Stage 2 的前置知识点——组件库、Supabase、接口开发、Git 工作流、云部署——全部串联起来。建议严格按照"需求分析 → 骨架 → 迭代 → 联调"四个阶段推进，每个模块用自检表验证后再进入下一个，最后以评分标准作为验收尺度，交付一个可演示、可部署、可讲清楚的 AI 平台原型。

参考资料

• custom-dify-agent-platform 作业文档
• 类 Dify 智能体编排平台 PRD
• UI 设计
• 现代组件库
• 从数据库到 Supabase
• AI 辅助编写接口代码
• Git 和 GitHub 工作流
• 部署 Web 应用（Zeabur）
• Dify 与知识库接入

【免费下载链接】easy-vibe💻 vibe coding 101｜The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibe