诗心Poetic Heart“以诗为心以 AI 为笔让千年诗词与你的心灵相遇”本项目站内资源源代码下载地址一、概述1.1 项目定位诗心是一款基于 AI 大语言模型驱动的中国古典诗词 Web 应用。用户通过输入关键词、心情描述或上传图片即可获得 AI 匹配的古典诗词、精美赏析以及诗词卡片生成。应用融合了传统诗词文化与现代 AI 技术提供沉浸式的诗词体验。1.2 核心价值AI 驱动的诗词匹配根据用户情绪/场景输入智能匹配最贴切的古诗词多模态交互支持文字输入、图片上传、语音朗读等多种交互方式精美卡片生成7 种视觉风格模板支持动态天气特效和 3D 倾斜交互诗人对话与 AI 模拟的古代诗人进行对话交流诗词游戏诗词接龙等互动游戏收藏与分享支持诗词卡片收藏、下载和分享1.3 技术栈层级技术选型前端框架Next.js 14 (App Router)语言TypeScript样式方案Tailwind CSSUI 组件库Radix UI shadcn/ui 风格封装动画引擎Framer Motion图标库Lucide ReactAI 能力z-ai-web-dev-sdkLLM 调用共享工具/lib/llmLLM 调用封装、/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 语音合成❤️ 收藏/取消收藏 分享 下载卡片数据模型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 匹配最贴切的古诗词。交互流程用户输入文字如今夜失眠、“想家了”可选择预设心情标签思念、孤独、春天、豪迈、闲适、离别、忧伤、喜悦点击生成调用/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/translate3.2.5 诗词接龙PoetryGamePanel功能描述互动式诗词接龙游戏AI 出题用户接龙。接口/api/poetry/game3.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/compose3.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 模式。路由方法功能输入输出/generatePOST诗词生成{ keyword, mood }PoemData/chatPOST诗人对话{ messages, poetId }ChatMessage/translatePOST诗词翻译{ text, sourceLang, targetLang }翻译结果/composePOST诗词创作{ theme, style, length }创作诗词/quizPOST诗词问答{ question, answer }问答结果/gamePOST诗词游戏{ action, context }游戏状态/analyze-imagePOST图片解析{ imageBase64 }PoemData4.2 LLM 调用封装/lib/llm所有 API 路由统一使用/lib/llm进行 LLM 调用核心 API// 创建 LLM 实例constllmawaitcreateLLM(llmConfig);// 文本对话constresponseawaitllm.chat(messages);// 视觉分析constanalysisawaitllm.vision(visionMessages);// JSON 解析constdataparseJSONFromLLM(llmResponse);// 配置提取constllmConfigextractLLMConfig(requestBody);五、UI/UX 设计5.1 视觉语言设计理念融合中国传统美学与现代极简设计营造诗意栖居的沉浸体验。色彩系统主色调琥珀色amber系列象征古典温暖辅色调石灰色stone系列提供中性背景强调色根据朝代动态变化唐琥珀、宋青绿等背景渐变从石色到琥珀色微光字体系统标题思源宋体Noto Serif CJK SC正文苹方PingFang SC/ 微软雅黑代码等宽字体间距与图标参考design-system/spacing-iconography.md5.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 本地状态管理核心状态// 页面主状态const[poemData,setPoemData]useStatePoemData|null(null);const[isGenerating,setIsGenerating]useState(false);const[activeTab,setActiveTab]useState(keyword);const[imageUrl,setImageUrl]useStatestring|null(null);const[templateId,setTemplateId]useStateCardTemplateId(ink);const[favorites,setFavorites]useStateMapstring,any(newMap());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 dev8.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 功能状态矩阵功能模块开发状态说明诗词卡片展示✅ 完成7 种模板 天气特效关键词寻诗✅ 完成8 种心情预设图片解诗✅ 完成VLM 视觉分析雅译✅ 完成中英互译诗词接龙✅ 完成互动游戏诗人对话✅ 完成多诗人模拟写诗✅ 完成AI 辅助创作诗词地图✅ 完成地理探索每日诗词✅ 完成节气联动历史画廊✅ 完成浏览历史收藏管理✅ 完成本地收藏TTS 朗读✅ 完成语音合成卡片下载✅ 完成图片导出卡片分享✅ 完成社交分享LLM 统一封装✅ 完成/lib/llm
【小程序】基于 AI 大语言模型驱动的中国古典诗词 Web 应用详细设计指南
发布时间：2026/6/7 16:55:31
诗心Poetic Heart“以诗为心以 AI 为笔让千年诗词与你的心灵相遇”本项目站内资源源代码下载地址一、概述1.1 项目定位诗心是一款基于 AI 大语言模型驱动的中国古典诗词 Web 应用。用户通过输入关键词、心情描述或上传图片即可获得 AI 匹配的古典诗词、精美赏析以及诗词卡片生成。应用融合了传统诗词文化与现代 AI 技术提供沉浸式的诗词体验。1.2 核心价值AI 驱动的诗词匹配根据用户情绪/场景输入智能匹配最贴切的古诗词多模态交互支持文字输入、图片上传、语音朗读等多种交互方式精美卡片生成7 种视觉风格模板支持动态天气特效和 3D 倾斜交互诗人对话与 AI 模拟的古代诗人进行对话交流诗词游戏诗词接龙等互动游戏收藏与分享支持诗词卡片收藏、下载和分享1.3 技术栈层级技术选型前端框架Next.js 14 (App Router)语言TypeScript样式方案Tailwind CSSUI 组件库Radix UI shadcn/ui 风格封装动画引擎Framer Motion图标库Lucide ReactAI 能力z-ai-web-dev-sdkLLM 调用共享工具/lib/llmLLM 调用封装、/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 语音合成❤️ 收藏/取消收藏 分享 下载卡片数据模型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 匹配最贴切的古诗词。交互流程用户输入文字如今夜失眠、“想家了”可选择预设心情标签思念、孤独、春天、豪迈、闲适、离别、忧伤、喜悦点击生成调用/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/translate3.2.5 诗词接龙PoetryGamePanel功能描述互动式诗词接龙游戏AI 出题用户接龙。接口/api/poetry/game3.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/compose3.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 模式。路由方法功能输入输出/generatePOST诗词生成{ keyword, mood }PoemData/chatPOST诗人对话{ messages, poetId }ChatMessage/translatePOST诗词翻译{ text, sourceLang, targetLang }翻译结果/composePOST诗词创作{ theme, style, length }创作诗词/quizPOST诗词问答{ question, answer }问答结果/gamePOST诗词游戏{ action, context }游戏状态/analyze-imagePOST图片解析{ imageBase64 }PoemData4.2 LLM 调用封装/lib/llm所有 API 路由统一使用/lib/llm进行 LLM 调用核心 API// 创建 LLM 实例constllmawaitcreateLLM(llmConfig);// 文本对话constresponseawaitllm.chat(messages);// 视觉分析constanalysisawaitllm.vision(visionMessages);// JSON 解析constdataparseJSONFromLLM(llmResponse);// 配置提取constllmConfigextractLLMConfig(requestBody);五、UI/UX 设计5.1 视觉语言设计理念融合中国传统美学与现代极简设计营造诗意栖居的沉浸体验。色彩系统主色调琥珀色amber系列象征古典温暖辅色调石灰色stone系列提供中性背景强调色根据朝代动态变化唐琥珀、宋青绿等背景渐变从石色到琥珀色微光字体系统标题思源宋体Noto Serif CJK SC正文苹方PingFang SC/ 微软雅黑代码等宽字体间距与图标参考design-system/spacing-iconography.md5.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 本地状态管理核心状态// 页面主状态const[poemData,setPoemData]useStatePoemData|null(null);const[isGenerating,setIsGenerating]useState(false);const[activeTab,setActiveTab]useState(keyword);const[imageUrl,setImageUrl]useStatestring|null(null);const[templateId,setTemplateId]useStateCardTemplateId(ink);const[favorites,setFavorites]useStateMapstring,any(newMap());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 dev8.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 功能状态矩阵功能模块开发状态说明诗词卡片展示✅ 完成7 种模板 天气特效关键词寻诗✅ 完成8 种心情预设图片解诗✅ 完成VLM 视觉分析雅译✅ 完成中英互译诗词接龙✅ 完成互动游戏诗人对话✅ 完成多诗人模拟写诗✅ 完成AI 辅助创作诗词地图✅ 完成地理探索每日诗词✅ 完成节气联动历史画廊✅ 完成浏览历史收藏管理✅ 完成本地收藏TTS 朗读✅ 完成语音合成卡片下载✅ 完成图片导出卡片分享✅ 完成社交分享LLM 统一封装✅ 完成/lib/llm
