# 李白读诗

**Repository Path**: daiyousheng/li-bai-reads-poetry

## Basic Information

- **Project Name**: 李白读诗
- **Description**: “李白读诗”是一个集成了 AI 诗词创作、语音合成（TTS）和数字人表演的综合性平台。本项目旨在通过现代 AI 技术重现唐代诗人李白的风采，让用户不仅能体验 AI 创作的古诗词，还能听到并通过数字分身看到“李白”亲自吟诵。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-03-04
- **Last Updated**: 2026-03-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 李白读诗 (li-bai-reads-poetry)

## 📖 项目介绍

**李白读诗** 是一个集成了 AI 诗词创作、语音合成（TTS）和数字人表演的综合性平台。本项目旨在通过现代 AI 技术重现唐代诗人李白的风采，让用户不仅能体验 AI 创作的古诗词，还能听到并通过数字分身看到“李白”亲自吟诵。

本项目是一个优秀的 **全栈 AI 应用示例**，展示了如何将 React 前端与 Supabase 后端（包括数据库、存储和边缘函数）以及第三方 AI 模型（MiniMax）进行深度集成。

### ✨ 核心功能

1.  **AI 诗词创作**：
    -   基于 **MiniMax-M2.5** 模型。
    -   通过精心设计的 System Prompt，将 AI 角色设定为“唐代大诗人李白”，确保生成的诗词风格豪放、浪漫，且符合格律要求。
2.  **语音合成 (TTS)**：
    -   集成 **MiniMax speech-2.8-hd** 模型。
    -   选用 `male-qn-qingse`（清澈男声）音色，并调整语速为 0.9，以呈现更具韵味的朗诵效果。
    -   生成的音频自动上传至 Supabase Storage 并持久化保存。
3.  **数字分身表演**：
    -   利用 **MiniMax S2V-01** 视频生成模型。
    -   根据诗词内容和预设形象，生成诗人摇头晃脑吟诵、背景山水相映的视频。
    -   支持异步任务处理与状态轮询，确保长耗时生成的流畅体验。

---

## 📸 项目演示

| 诗词创作与朗诵 | 数字分身表演 |
| :---: | :---: |
| ![诗词创作与朗诵](public/images/demo-poem.png) | ![数字分身表演](public/images/demo-video.png) |
| *诗词创作与朗诵界面* | *数字分身视频表演界面* |

> **注意**：为了优化项目体积，建议在打包或上传前对图片资源进行压缩处理（推荐使用 [TinyPNG](https://tinypng.com/) 等工具）。

---

## 🛠 技术栈

本项目采用了现代化的前端技术栈，结合 Serverless 后端架构，适合学习和参考。

### 前端 (Frontend)
-   **核心框架**: [React 18](https://react.dev/) + [Vite](https://vitejs.dev/) + [TypeScript](https://www.typescriptlang.org/)
-   **UI 组件库**: 
    -   [Radix UI](https://www.radix-ui.com/) (无头组件库，提供无障碍交互)
    -   [Tailwind CSS](https://tailwindcss.com/) (原子化 CSS 框架)
    -   **Shadcn UI** (基于 Radix + Tailwind 的设计系统实现)
-   **状态与交互**:
    -   [React Hook Form](https://react-hook-form.com/) + [Zod](https://zod.dev/) (高性能表单与模式校验)
    -   [Motion](https://motion.dev/) (流畅的动画效果)
    -   [Sonner](https://sonner.emilkowal.ski/) (优雅的 Toast 通知)
    -   [Lucide React](https://lucide.dev/) (精美图标库)

### 后端与基础设施 (Backend & Infra)
-   **BaaS 平台**: [Supabase](https://supabase.com/)
    -   **PostgreSQL**: 存储诗词、任务状态等核心数据。
    -   **Storage**: 存储生成的 TTS 音频文件和视频封面等。
    -   **Edge Functions**: 托管后端业务逻辑，安全调用第三方 AI API。
-   **AI 模型服务**: **MiniMax** (通过 Edge Functions 集成)

---

## 🏗 架构亮点与学习点

### 1. 安全的 AI 集成模式 (Edge Functions)
本项目没有在前端直接调用 AI API，而是通过 **Supabase Edge Functions** 进行封装。
-   **安全性**: API Key（如 `INTEGRATIONS_API_KEY`）存储在后端环境变量中，前端无法接触，避免了密钥泄露风险。
-   **逻辑封装**: 复杂的提示词工程（Prompt Engineering）和数据处理逻辑在后端完成，前端只需调用简单的 RPC 接口。

### 2. 清晰的服务层设计
在 `src/db/api.ts` 中封装了与 Supabase 交互的所有逻辑，前端组件只负责展示和交互，不直接处理数据库或 API 细节。这种**关注点分离**的设计使得代码更易维护和测试。

### 3. 异步任务处理
针对视频生成这种耗时操作，项目实现了**异步任务队列模式**：
1.  前端发起生成请求 -> Edge Function 创建任务并返回 Task ID。
2.  前端通过轮询（Polling）机制检查任务状态。
3.  任务完成后获取下载链接。
这种模式有效避免了长连接超时问题，提升了用户体验。

---

## 📂 目录结构

```
├── README.md           # 说明文档
├── components.json     # Shadcn UI 组件配置
├── index.html          # 入口 HTML
├── package.json        # 依赖管理
├── postcss.config.js   # PostCSS 配置
├── public              # 静态资源
│   ├── favicon.png
│   └── images
├── supabase            # Supabase 相关配置与函数
│   └── functions       # Edge Functions (后端逻辑核心)
│       ├── generate-poem       # 诗词生成函数
│       ├── generate-video      # 视频生成函数
│       ├── synthesize-speech   # TTS 语音合成函数
│       └── ...
├── src                 # 前端源码
│   ├── App.tsx         # 根组件
│   ├── components      # UI 组件
│   │   └── ui          # 通用基础组件
│   ├── contexts        # React Context (全局状态)
│   ├── db              # 数据库与 API 服务层
│   ├── hooks           # 自定义 Hooks
│   ├── lib             # 工具函数 (utils)
│   ├── pages           # 页面视图
│   ├── types           # TypeScript 类型定义
│   └── main.tsx        # 入口文件
├── tsconfig.json       # TypeScript 配置
└── vite.config.ts      # Vite 配置
```

---

## 💻 本地开发

### 环境要求
-   Node.js ≥ 20
-   npm ≥ 10

### 快速开始

1.  **克隆项目**
    ```bash
    git clone <repository-url>
    cd <project-directory>
    ```

2.  **安装依赖**
    ```bash
    npm install
    ```

3.  **配置环境变量**
    复制 `.env.example` 为 `.env`，并填入你的 Supabase 项目配置：
    ```env
    VITE_SUPABASE_URL=your_supabase_project_url
    VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
    ```

4.  **启动开发服务器**
    ```bash
    npm run dev
    ```

### 后端服务开发 (Supabase)
如需修改后端逻辑（Edge Functions）：
1.  安装 [Supabase CLI](https://supabase.com/docs/guides/cli)。
2.  登录并关联项目。
3.  在 `supabase/functions` 目录下修改或添加函数。
4.  部署函数：`supabase functions deploy <function_name>`。