【小程序】基于 AI 大语言模型驱动的中国古典诗词 Web 应用详细设计指南

诗心（Poetic Heart）

“以诗为心，以 AI 为笔，让千年诗词与你的心灵相遇”

本项目站内资源源代码下载地址

一、概述

1.1 项目定位

诗心是一款基于 AI 大语言模型驱动的中国古典诗词 Web 应用。用户通过输入关键词、心情描述或上传图片，即可获得 AI 匹配的古典诗词、精美赏析以及诗词卡片生成。应用融合了传统诗词文化与现代 AI 技术，提供沉浸式的诗词体验。

1.2 核心价值

• AI 驱动的诗词匹配：根据用户情绪/场景输入，智能匹配最贴切的古诗词
• 多模态交互：支持文字输入、图片上传、语音朗读等多种交互方式
• 精美卡片生成：7 种视觉风格模板，支持动态天气特效和 3D 倾斜交互
• 诗人对话：与 AI 模拟的古代诗人进行对话交流
• 诗词游戏：诗词接龙等互动游戏
• 收藏与分享：支持诗词卡片收藏、下载和分享

1.3 技术栈

二、系统架构

2.1 整体架构

┌─────────────────────────────────────────────────────┐ │ 客户端（浏览器） │ │ ┌─────────────────────────────────────────────────┐ │ │ │ Next.js App Router │ │ │ │ ┌───────────┐ ┌──────────┐ ┌──────────────┐ │ │ │ │ │ page.tsx │ │ layout │ │ globals.css │ │ │ │ │ │ (主页面) │ │ .tsx │ │ │ │ │ │ │ └───────────┘ └──────────┘ └──────────────┘ │ │ │ │ ┌──────────────────────────────────────────┐ │ │ │ │ │ Components (客户端组件) │ │ │ │ │ │ PoetryCard / KeywordPanel / ImagePanel │ │ │ │ │ │ TranslatePanel / PoetryGamePanel │ │ │ │ │ │ PoetDialoguePanel / ComposePanel │ │ │ │ │ │ PoetryMapPanel / HistoryGallery │ │ │ │ │ └──────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────┘ │ │ │ │ │ HTTP API 调用 │ │ ▼ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ API Routes (服务端) │ │ │ │ /api/poetry/ │ │ │ │ ├── generate/ 诗词生成 │ │ │ │ ├── chat/ 诗人对话 │ │ │ │ ├── translate/ 诗词翻译 │ │ │ │ ├── compose/ 诗词创作 │ │ │ │ ├── quiz/ 诗词问答 │ │ │ │ ├── game/ 诗词游戏 │ │ │ │ └── analyze-image/ 图片解析 │ │ │ └─────────────────────────────────────────────────┘ │ │ │ │ │ LLM API 调用 │ │ ▼ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ @/lib/llm (共享 LLM 工具) │ │ │ │ - createLLM() 创建 LLM 实例 │ │ │ │ - parseJSONFromLLM() 解析 LLM JSON 输出 │ │ │ │ - extractLLMConfig() 提取 LLM 配置 │ │ │ │ - llm.chat() 文本对话 │ │ │ │ - llm.vision() 视觉分析 │ │ │ └─────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────┘

2.2 目录结构

project/ ├── app/ │ ├── api/ │ │ └── poetry/ │ │ ├── generate/route.ts # 诗词生成 API │ │ ├── chat/route.ts # 诗人对话 API │ │ ├── translate/route.ts # 诗词翻译 API │ │ ├── compose/route.ts # 诗词创作 API │ │ ├── quiz/route.ts # 诗词问答 API │ │ ├── game/route.ts # 诗词游戏 API │ │ └── analyze-image/route.ts # 图片解析 API │ ├── globals.css # 全局样式 │ ├── layout.tsx # 根布局 │ └── page.tsx # 主页面入口 ├── components/ │ └── ui/ # UI 基础组件 │ ├── button.tsx │ ├── input.tsx │ ├── badge.tsx │ ├── tabs.tsx │ ├── card.tsx │ ├── scroll-area.tsx │ ├── separator.tsx │ └── ... ├── hooks/ │ └── use-toast.ts # Toast 通知 Hook ├── lib/ │ ├── llm.ts # LLM 调用封装 │ ├── solar-terms.ts # 节气/农历计算 │ └── utils.ts # 通用工具函数 ├── specs/ # 需求规格文档 │ ├── 2-seed-developer.md │ ├── 3-5-frontend-enhancer.md │ ├── 3-5b-backend-api.md │ ├── 3-a-backend-tts-export.md │ ├── 3-rhythm-tts-highlight.md │ ├── 4-visual-enhancements.md │ ├── 5-css-enhancement-agent.md │ ├── 5-poetry-database-expander.md │ ├── 6-share-card-animations.md │ └── 9-Round9-main.md └── design-system/ # 设计系统文档 ├── color-systems.md ├── spacing-iconography.md └── typography-systems.md

三、功能模块设计

3.1 主页面布局（HomePage）

主页面采用响应式设计，分为桌面端和移动端两种布局：

桌面端布局：

┌────────────────────────────────────────────────────┐ │ Header (日期/节气) │ ├──────────────────────┬─────────────────────────────┤ │ │ │ │ Poetry Card │ Controls Panel │ │ (诗词卡片展示区) │ (功能标签页) │ │ │ - 寻诗 (keyword) │ │ - 水墨/工笔/现代 │ - 解图 (image) │ │ - 7种模板风格 │ - 雅译 (translate) │ │ - 天气特效 │ - 接龙 (game) │ │ - 3D倾斜 │ - 对话 (chat) │ │ - 打字机效果 │ - 写诗 (compose) │ │ │ - 地图 (map) │ │ │ │ ├──────────────────────┴─────────────────────────────┤ │ History Gallery (历史记录) │ │ Favorites (我的收藏) │ ├────────────────────────────────────────────────────┤ │ Footer │ └────────────────────────────────────────────────────┘

移动端布局：

• 单列垂直布局，底部固定标签栏
• 7 个功能入口：寻诗、解图、雅译、接龙、对话、写诗、地图
  
  
  
  

3.2 核心功能模块

3.2.1 诗词卡片（PoetryCard）

功能描述：展示 AI 生成的诗词卡片，包含完整诗词内容、赏析文字和视觉化呈现。

核心特性：

• 7 种视觉风格模板：

  • 🖌️水墨（ink）：传统水墨画风格，深色背景
  • 🎨工笔（gongbi）：精致工笔画风格，金色边框
  • ✨现代（modern）：简约现代风格，圆角设计
  • 🤍极简（minimal）：留白极简风格，细边框
  • 🏺青花（qinghua）：青花瓷风格，天蓝配色
  • 📜竹简（zhujian）：竹简风格，仿古色调
  • 🧣丝绸（silk）：丝绸风格，柔和玫瑰色

• 动态天气特效：

  • 雨效（RainEffect）：垂直雨滴动画
  • 雪效（SnowEffect）：飘雪动画
  • 花瓣效（PetalEffect）：花瓣飘落动画
  • 粒子效（ParticleEffect）：浮动光点

• 3D 倾斜交互：鼠标悬停时卡片随鼠标位置产生 3D 倾斜效果

• 打字机赏析：赏析文字以打字机效果逐字显示，速度 30ms/字

• 朝代色彩映射：

  • 唐 → 琥珀色 | 宋 → 青绿色 | 元 → 石灰色
  • 明 → 玫瑰色 | 清 → 天蓝色 | 魏晋 → 紫罗兰色

• 卡片操作：

  • 🔊 朗读（TTS 语音合成）
  • ❤️ 收藏/取消收藏
  • 📤 分享
  • 📥 下载卡片

数据模型：

interfacePoemData{poem:{title:string;// 诗词标题author:string;// 作者dynasty:string;// 朝代content:string;// 诗词内容matched_line:string;// 匹配的经典诗句};appreciation:string;// AI 赏析visual_prompt:string;// 图像生成提示词tags:string[];// 标签（情绪、主题等）}

3.2.2 关键词寻诗（KeywordPanel）

功能描述：用户输入关键词或心情描述，AI 匹配最贴切的古诗词。

交互流程：

1. 用户输入文字（如"今夜失眠"、“想家了”）
2. 可选择预设心情标签（思念、孤独、春天、豪迈、闲适、离别、忧伤、喜悦）
3. 点击生成，调用/api/poetry/generate接口
4. 展示诗词卡片和赏析

预设心情关键词：

3.2.3 图片解诗（ImagePanel）

功能描述：用户上传图片，AI 通过视觉分析理解图片内容，然后匹配相应的古诗词。

处理流程：

1. 用户上传/拍摄图片
2. 前端将图片转为 base64
3. 调用/api/poetry/analyze-image接口
4. AI 先通过 VLM（视觉语言模型）分析图片内容
5. 再基于分析结果生成匹配的诗词
6. 展示诗词卡片

API 调用链：

图片 base64 → llm.vision(visionMessages) → 图片分析结果 分析结果 → llm.chat(messages) → 诗词生成

3.2.4 雅译（TranslatePanel）

功能描述：诗词翻译功能，支持中英互译。

接口：/api/poetry/translate

3.2.5 诗词接龙（PoetryGamePanel）

功能描述：互动式诗词接龙游戏，AI 出题，用户接龙。

接口：/api/poetry/game

3.2.6 诗人对话（PoetDialoguePanel）

功能描述：与 AI 模拟的古代诗人（李白、杜甫、苏轼等）进行对话交流。

特性：

• 可选择不同朝代、不同风格的诗人
• AI 模拟诗人的性格和语言风格
• 支持多轮对话
• 对话历史可在会话内保持

接口：/api/poetry/chat

数据模型：

interfacePoetData{id:string;name:string;// 诗人姓名dynasty:string;// 朝代style:string;// 诗风personality:string;// 性格描述}interfaceChatMessage{role:"user"|"assistant";content:string;poetName?:string;}

3.2.7 写诗（ComposePanel）

功能描述：AI 辅助诗词创作，用户提供主题或灵感，AI 生成原创诗词。

接口：/api/poetry/compose

3.2.8 诗词地图（PoetryMapPanel）

功能描述：地理维度的诗词探索，根据地理位置发现相关的诗词作品。

交互：点击地图区域可触发关键词诗词生成。

3.2.9 每日诗词（DailyPoemBanner）

功能描述：根据当前日期和节气，展示每日推荐诗词。

依赖：@/lib/solar-terms（节气计算模块）

3.2.10 历史画廊（HistoryGallery）

功能描述：展示用户历史生成的诗词卡片，支持浏览和重新查看。

数据模型：

interfaceCardHistoryItem{id:string;poemTitle:string;poemAuthor:string;poemDynasty:string;poemContent:string;matchedLine:string;appreciation:string;visualPrompt:string;imageUrl:string|null;tags:string;createdAt:string;}

四、API 接口设计

4.1 接口总览

所有 API 路由位于/api/poetry/下，遵循 Next.js App Router 的 Route Handler 模式。

4.2 LLM 调用封装（@/lib/llm）

所有 API 路由统一使用@/lib/llm进行 LLM 调用，核心 API：

// 创建 LLM 实例constllm=awaitcreateLLM(llmConfig);// 文本对话constresponse=awaitllm.chat(messages);// 视觉分析constanalysis=awaitllm.vision(visionMessages);// JSON 解析constdata=parseJSONFromLLM(llmResponse);// 配置提取constllmConfig=extractLLMConfig(requestBody);

五、UI/UX 设计

5.1 视觉语言

设计理念：融合中国传统美学与现代极简设计，营造"诗意栖居"的沉浸体验。

色彩系统：

• 主色调：琥珀色（amber）系列，象征古典温暖
• 辅色调：石灰色（stone）系列，提供中性背景
• 强调色：根据朝代动态变化（唐=琥珀、宋=青绿等）
• 背景：渐变从石色到琥珀色微光

字体系统：

• 标题：思源宋体（Noto Serif CJK SC）
• 正文：苹方（PingFang SC）/ 微软雅黑
• 代码：等宽字体

间距与图标：参考design-system/spacing-iconography.md

5.2 交互动效

5.3 响应式设计

• 桌面端（≥1024px）：双栏布局，左侧卡片 + 右侧控制面板
• 平板端（768-1023px）：卡片与控制面板上下排列
• 移动端（<768px）：单列布局，底部固定标签栏，适配安全区域

六、数据流设计

6.1 诗词生成流程

用户输入关键词/心情 │ ▼ ┌───────────────────┐ │ KeywordPanel │ 前端收集输入 │ / ImagePanel │ └───────┬───────────┘ │ POST /api/poetry/generate ▼ ┌───────────────────┐ │ generate/route │ 提取 LLM 配置 │ .ts │ 构建 System Prompt └───────┬───────────┘ │ createLLM(config) ▼ ┌───────────────────┐ │ @/lib/llm │ 统一 LLM 调用 │ llm.chat() │ └───────┬───────────┘ │ LLM Response ▼ ┌───────────────────┐ │ parseJSONFrom │ 解析 JSON 响应 │ LLM() │ └───────┬───────────┘ │ PoemData JSON ▼ ┌───────────────────┐ │ PoetryCard │ 渲染诗词卡片 │ (前端组件) │ + 天气特效 └───────────────────┘

6.2 状态管理

前端使用 React 本地状态管理，核心状态：

// 页面主状态const[poemData,setPoemData]=useState<PoemData|null>(null);const[isGenerating,setIsGenerating]=useState(false);const[activeTab,setActiveTab]=useState("keyword");const[imageUrl,setImageUrl]=useState<string|null>(null);const[templateId,setTemplateId]=useState<CardTemplateId>("ink");const[favorites,setFavorites]=useState<Map<string,any>>(newMap());const[historyRefreshKey,setHistoryRefreshKey]=useState(0);

七、开发规范

7.1 代码风格

• 使用 TypeScript 严格模式
• 组件使用函数式声明 + Hooks
• 客户端组件标注"use client"
• 使用 Tailwind CSS 原子类，避免内联样式
• 遵循 ESLint 规范（bun run lint零错误通过）

7.2 组件设计原则

1. 单一职责：每个 Panel 组件负责一个独立功能
2. Props 驱动：通过 Props 传递数据和回调
3. 动画分离：天气特效、山脉剪影等独立为子组件
4. 可复用性：PoetryCard 通过 props 控制展示模式

7.3 API 设计原则

1. 统一 LLM 调用：所有 API 路由通过@/lib/llm调用 LLM
2. 错误处理：每个 API 路由包含完整的 try-catch 错误处理
3. System Prompt：每个 API 维护独立的 System Prompt 以确保输出质量
4. JSON 输出：LLM 输出统一为 JSON 格式，通过parseJSONFromLLM解析

八、部署与运维

8.1 环境要求

• 运行时：Node.js 18+ / Bun
• 包管理：bun
• 构建命令：bun run build
• 开发命令：bun run dev

8.2 依赖项

{"dependencies":{"next":"^14","react":"^18","react-dom":"^18","framer-motion":"^11","lucide-react":"latest","@radix-ui/react-tabs":"latest","@radix-ui/react-toggle-group":"latest","@radix-ui/react-radio-group":"latest","@radix-ui/react-collapsible":"latest","embla-carousel-react":"latest","class-variance-authority":"latest","z-ai-web-dev-sdk":"latest"}}

九、附录

9.1 功能状态矩阵