塔罗神谕：星月神域莱诺薇为您占卜

命运不语，但会在牌面上留下痕迹。

Tarot Oracle 是一个围绕"仪式感抽牌 + 视觉演出 + AI 解读"设计的 Web 应用。项目基于 Vite + React + TypeScript + Three.js 构建，内置完整塔罗牌素材，并接入 DeepSeek 生成结构化占卜结果。

它不是一个只会"点一下按钮给答案"的页面，而是尽量把抽牌这件事做成一场完整体验：有召唤感、有节奏感，也有可追问的 AI 占卜师对话。

Gitee: https://gitee.com/baifengfeng/tarot-oracle

GitHub: https://github.com/baifengxi/TarotOracle

1. 项目简介

这个项目的核心目标有三件事：

让塔罗占卜从"静态结果页"变成"有舞台感的互动过程"。
让 AI 解读不只是输出一段废话，而是稳定返回可展示的结构化内容。
让前端视觉、抽牌逻辑、牌义数据、模型调用彼此解耦，方便继续扩展。

当前版本已经实现了四个主要体验模块：

每日塔罗运势：单牌抽取，适合日常快速查看今日能量。
命运三相阵：过去 / 现在 / 未来三张牌联动解读。
莱诺薇对话：围绕当前牌面上下文继续追问的 AI 占卜师聊天。
历史记录：本地保存近期占卜结果，方便回看与复盘。

2. 为什么做这个项目

市面上很多 AI 占卜产品的问题并不在"没有结果"，而在"没有过程"。

用户真正记住的，往往不是那一段总结文案，而是从开始召唤、卡牌旋转、命运定格，到最终翻出正位或逆位的那几秒钟。于是这个项目从一开始就不是按工具页去做，而是按"体验型产品"去设计：

用 Three.js 做仪式舞台，让抽牌不是纯平面的切换。
用统一的塔罗牌数据结构管理牌名、正逆位关键词和基础牌义。
用结构化 Prompt + JSON 输出约束模型，减少解读漂移。
在 API 不可用时提供本地兜底文案，保证流程不断。

换句话说，这不是"AI 套一个塔罗壳子"，而是"把塔罗仪式、前端演出和 AI 解读整合成一个完整产品"。

3. 核心功能设计

3.1 每日塔罗运势

每日运势模式是整个产品里最轻量的一种体验。

用户进入页面后，先触发召唤仪式，旋转中的牌阵会在停止后定格一张卡牌，并随机判定正位或逆位。随后系统会根据抽中的牌，生成一份结构化的每日解读，包括：

今日摘要
详细解读
行动建议
注意事项
幸运能量提示

这里还有一个产品细节：每日抽牌采用带种子的方式生成同一天的结果，避免用户反复刷新得到不同答案，破坏"今日签文"的设定。

3.2 命运三相阵

如果说每日运势像"今日签文"，那么三相阵更像一次完整的占卜过程。

用户可以先输入问题，也可以选择 感情 / 事业 / 财务 / 学业 / 人际 / 综合 这样的分类。随后系统会引导用户依次完成三轮抽牌：

第一相：唤醒过往之影
第二相：映照此刻之心
第三相：窥见未来之门

三张牌全部落位后，AI 会基于问题、牌位、正逆位和关键词生成联动解读，输出：

问题回响
三牌之间的命运连线
行动建议
风险提醒
最终结语

3.3 莱诺薇对话

这是项目里很有延展性的一部分。

在传统占卜产品里，结果通常到"展示一段解读"就结束了；但真实用户往往会继续追问，比如：

"结合刚才那三张牌，现在最该优先处理什么？"
"这更像是在提醒放弃，还是暂时观望？"
"如果是感情问题，这张逆位牌更偏向哪一方的状态？"

所以项目增加了一个可持续对话的 AI 占卜师角色 莱诺薇。她会继承最近一次抽牌的上下文，让占卜从一次性输出变成连续交流。

3.4 历史记录

所有占卜结果都会存储到浏览器本地 localStorage 中，当前保留最近 12 条记录。这个设计虽然简单，但足够支持个人使用场景，也为后续扩展账号体系或云端同步留出了空间。

4. 界面与交互思路

这个项目的前端不是标准的 SaaS 风格，而是明显偏向"中世纪神秘卷轴 + 仪式舞台光效"的方向。

整体设计思路包括：

背景不是纯色，而是深色雾感与法阵式层次。
卡牌是绝对主角，UI 负责承托氛围，不喧宾夺主。
交互节奏强调"开始召唤 -> 停止召唤 -> 命运显现"。
结果内容采用模块化纸面面板展示，既保留叙事感，也方便阅读。

在实现上，首页、仪式舞台、牌面展示、解读面板和聊天区域都被拆成独立组件，既能保持视觉一致，也方便后续扩展更多牌阵玩法。

5. 项目架构

5.1 技术栈

Vite
React 18
TypeScript
Three.js
DeepSeek API
localStorage

5.2 目录结构

text 复制代码

TarotOracle/
├── cards/                     # 塔罗牌图片素材
├── docs/                      # 产品、UI、接口设计文档
├── src/
│   ├── components/            # 页面与展示组件
│   ├── config/                # DeepSeek 配置与占卜师设定
│   ├── data/                  # 塔罗牌静态数据
│   ├── services/              # 抽牌、存储、AI 调用
│   ├── styles/                # 全局样式
│   ├── types/                 # 类型定义
│   ├── App.tsx                # 核心页面状态与流程编排
│   └── main.tsx
├── package.json
└── vite.config.ts

5.3 架构分层

UI Components

首页 / 仪式舞台 / 卡牌视图 / 解读面板 / 对话区
App State Orchestration

视图切换、抽牌流程、加载状态、上下文拼接
Domain Services
tarotDraw.ts

抽牌与正逆位逻辑
deepseek.ts

结构化解读与流式对话
storage.ts

本地历史记录
tarotCards.ts

塔罗牌数据
DeepSeek API
localStorage

5.4 核心实现拆解

1. 抽牌逻辑层

src/services/tarotDraw.ts 负责：

每日抽牌的种子稳定性
三张牌模式下的去重抽取
正位 / 逆位的生成
将静态牌面数据转换成前端可直接使用的 DrawnCard

2. AI 解读层

src/services/deepseek.ts 负责两件事：

结构化占卜结果生成
占卜师流式对话

这里比较关键的一点是，项目没有把模型返回结果直接当纯文本展示，而是通过 JSON 输出约束，要求模型返回明确字段。这样前端可以稳定渲染摘要、建议、警示、幸运提示等模块。

同时，为了提高可用性，项目还实现了本地 fallback：如果没有配置 API Key，或者接口调用失败，系统会自动使用本地牌义生成基础解读，不会让页面卡死。

3. 视觉演出层

src/components/ThreeRitualScene.tsx 使用 Three.js 绘制仪式舞台，通过法阵、旋转卡牌、呼吸感光效来完成"召唤感"的核心氛围。

这层的价值不只是"好看"，更重要的是把用户从普通页面操作带进一种更有沉浸感的使用心境里。

4. 本地状态与历史层

src/App.tsx 负责整体流程编排，src/services/storage.ts 负责历史记录的本地持久化。

目前这个架构非常适合继续往下拓展，比如：

新的牌阵模式
登录与云端记录
分享海报生成
多角色占卜师设定

6. 界面展示

6.1 首页 Hero

6.2 每日塔罗运势

召唤舞台：

召唤结果：

莱诺薇AI占卜解读：

6.3 命运三相阵

命运三相阵主界面：

命运三相阵抽取卡牌：

命运三相莱诺薇AI占卜解读:

6.4 莱诺薇对话

AI 占卜师对话截图主界面：

AI 占卜师对话：

6.5 历史记录

7. 从产品到代码，这个项目解决了什么问题

这个项目并不复杂到像一个大型商业系统，但它很好地练习了"产品想法如何落到前端实现"这件事。

这个项目主要验证了三件事：

如何把一个偏感性、偏氛围型的主题，做成真正可交互的 Web 产品。
如何让大模型输出变得结构化、稳定、可控，而不是纯聊天式散文。
如何在体验感与工程可维护性之间做平衡，而不是只追某一边。

所以如果你把它看成一个作品集项目，它能体现的是：

前端体验设计能力
React 组件拆分能力
业务状态编排能力
大模型接入与 fallback 设计能力
UI 氛围表达能力

8. 本地运行方式

8.1 安装依赖

bash 复制代码

npm install

8.2 启动开发环境

bash 复制代码

npm run dev

8.3 配置 DeepSeek

在项目根目录创建 .env.local，参考 .env.example 填写：

env 复制代码

VITE_DEEPSEEK_API_KEY=your_api_key
VITE_DEEPSEEK_MODEL=deepseek-v4-pro
VITE_DEEPSEEK_API_BASE=https://api.deepseek.com

如果未配置 API Key，项目依然可以运行，只是会退回到本地基础解读逻辑。

9. 后续可扩展方向

如果继续打磨，这个项目还可以往下面几个方向发展：

增加更多牌阵，比如爱情十字阵、关系解析阵、周运势阵
增加用户账户体系，实现跨设备占卜记录同步
生成分享海报，把牌面与摘要输出为可传播图片
支持音效、环境粒子与更完整的仪式动画
加入"今日不可重复占卜"的更强约束与提示机制
做一套真正移动端优先的触控交互优化

10. 结语

Tarot Oracle 不只是一个"接了模型接口的前端项目"，更是一场把视觉叙事、交互节奏、业务逻辑和 AI 输出控制结合起来的实践。

如果说普通应用是在解决效率问题，那这个项目更像是在探索另一件事：如何让一个数字产品保留一点仪式感、情绪张力和想象空间。

如果你也在做 AI + 前端体验类项目，希望这份实现和这篇文案能给你一些灵感。