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

诗心（Poetic Heart）

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

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

一、概述

1.1 项目定位

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

1.2 核心价值

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

1.3 技术栈

层级	技术选型
前端框架	Next.js 14+ (App Router)
语言	TypeScript
样式方案	Tailwind CSS
UI 组件库	Radix UI + shadcn/ui 风格封装
动画引擎	Framer Motion
图标库	Lucide React
AI 能力	z-ai-web-dev-sdk（LLM 调用）
共享工具	`@/lib/llm`（LLM 调用封装）、`@/lib/solar-terms`（节气计算）

二、系统架构

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 语音合成）
- ❤️ 收藏/取消收藏
- 📤 分享
- 📥 下载卡片

数据模型：

typescript 复制代码

interface PoemData {
  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 匹配最贴切的古诗词。

交互流程：

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

预设心情关键词：

心情	图标	配色
思念	🌙	紫罗兰→紫色
孤独	🌧️	石板灰→灰色
春天	🌸	翡翠绿→绿色
豪迈	⛰️	红色→橙色
闲适	🌬️	青绿→青色
离别	🪶	琥珀→黄色
忧伤	🌧️	蓝色→靛蓝
喜悦	☀️	玫瑰→粉色

3.2.3 图片解诗（ImagePanel）

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

处理流程：

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

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

数据模型：

typescript 复制代码

interface PoetData {
  id: string;
  name: string;       // 诗人姓名
  dynasty: string;    // 朝代
  style: string;      // 诗风
  personality: string; // 性格描述
}

interface ChatMessage {
  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）

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

数据模型：

typescript 复制代码

interface CardHistoryItem {
  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 模式。

路由	方法	功能	输入	输出
`/generate`	POST	诗词生成	`{ keyword, mood }`	`PoemData`
`/chat`	POST	诗人对话	`{ messages, poetId }`	`ChatMessage`
`/translate`	POST	诗词翻译	`{ text, sourceLang, targetLang }`	翻译结果
`/compose`	POST	诗词创作	`{ theme, style, length }`	创作诗词
`/quiz`	POST	诗词问答	`{ question, answer }`	问答结果
`/game`	POST	诗词游戏	`{ action, context }`	游戏状态
`/analyze-image`	POST	图片解析	`{ imageBase64 }`	`PoemData`

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

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

typescript 复制代码

// 创建 LLM 实例
const llm = await createLLM(llmConfig);

// 文本对话
const response = await llm.chat(messages);

// 视觉分析
const analysis = await llm.vision(visionMessages);

// JSON 解析
const data = parseJSONFromLLM(llmResponse);

// 配置提取
const llmConfig = extractLLMConfig(requestBody);

五、UI/UX 设计

5.1 视觉语言

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

色彩系统：

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

字体系统：

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

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

5.2 交互动效

动效类型	实现方式	应用场景
卡片 3D 倾斜	Framer Motion + mouseMove	诗词卡片悬停
打字机文字	setInterval 逐字显示	赏析文字展示
天气特效	CSS + Framer Motion	雨/雪/花瓣/粒子
山脉剪影	SVG Path 动画	卡片背景
浮动云朵	CSS Transform	卡片背景
音频波形	5 条柱状动画	TTS 朗读中
水墨笔触	SVG stroke-dasharray	空状态
磁贴按钮	Framer Motion spring	底部导航

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 本地状态管理，核心状态：

typescript 复制代码

// 页面主状态
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>>(new Map());
const [historyRefreshKey, setHistoryRefreshKey] = useState(0);

七、开发规范

7.1 代码风格

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

7.2 组件设计原则

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

7.3 API 设计原则

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

八、部署与运维

8.1 环境要求

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

8.2 依赖项

json 复制代码

{
  "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 功能状态矩阵

功能模块	开发状态	说明
诗词卡片展示	✅ 完成	7 种模板 + 天气特效
关键词寻诗	✅ 完成	8 种心情预设
图片解诗	✅ 完成	VLM 视觉分析
雅译	✅ 完成	中英互译
诗词接龙	✅ 完成	互动游戏
诗人对话	✅ 完成	多诗人模拟
写诗	✅ 完成	AI 辅助创作
诗词地图	✅ 完成	地理探索
每日诗词	✅ 完成	节气联动
历史画廊	✅ 完成	浏览历史
收藏管理	✅ 完成	本地收藏
TTS 朗读	✅ 完成	语音合成
卡片下载	✅ 完成	图片导出
卡片分享	✅ 完成	社交分享
LLM 统一封装	✅ 完成	`@/lib/llm`

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

诗心（Poetic Heart）

一、概述

1.1 项目定位

1.2 核心价值

1.3 技术栈

二、系统架构

2.1 整体架构

2.2 目录结构

三、功能模块设计

3.1 主页面布局（HomePage）

3.2 核心功能模块

3.2.1 诗词卡片（PoetryCard）

3.2.2 关键词寻诗（KeywordPanel）

3.2.3 图片解诗（ImagePanel）

3.2.4 雅译（TranslatePanel）

3.2.5 诗词接龙（PoetryGamePanel）

3.2.6 诗人对话（PoetDialoguePanel）

3.2.7 写诗（ComposePanel）

3.2.8 诗词地图（PoetryMapPanel）

3.2.9 每日诗词（DailyPoemBanner）

3.2.10 历史画廊（HistoryGallery）

四、API 接口设计

4.1 接口总览

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

五、UI/UX 设计

5.1 视觉语言

5.2 交互动效

5.3 响应式设计

六、数据流设计

6.1 诗词生成流程

6.2 状态管理

七、开发规范

7.1 代码风格

7.2 组件设计原则

7.3 API 设计原则

八、部署与运维

8.1 环境要求

8.2 依赖项

九、附录

9.1 功能状态矩阵

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