项目总览

相关源文件

本页面内容基于以下源文件生成：

• README.md
• metadata.yaml

astrbot_plugin_tarot 是一个基于 AstrBot 框架的塔罗牌占卜插件，支持多牌阵和单张牌占卜，并通过 AI 生成详细解析。该项目实现了从传统塔罗占卜到数字化交互的转换，将 78 张韦特塔罗牌体系与 AI 智能解析相结合，为用户提供趣味性的占卜体验。

该插件的核心价值在于：将复杂的塔罗牌阵系统程序化，支持根据用户输入模糊匹配或通过 AI 智能选择合适的牌阵；同时集成 AI 能力生成带颜表情的个性化解析，使占卜过程更加生动有趣。项目采用本地资源读取方式，确保数据隐私和响应速度。

版本与兼容性

版本差异说明：README 中标注的 v0.1.5 与 metadata.yaml 中的 v0.1.1 存在差异，可能反映了文档更新与元数据配置的同步延迟。实际部署时应以 README 中的版本为准。

核心功能

占卜命令

该插件提供三个核心命令，覆盖不同场景的占卜需求：

占卜命令的智能匹配机制：用户输入如"占卜 情感"时，系统可通过模糊匹配或 AI 选择合适的牌阵（如"圣三角牌阵"），随机抽取对应数量的塔罗牌，并生成带颜表情的 AI 解析（README.md:35-42）。这一机制涉及以下关键流程：

1. 意图识别：解析用户输入的关键词（如"情感"、"事业"）
2. 牌阵匹配：根据关键词匹配最合适的牌阵类型
3. 抽牌逻辑：按牌阵要求随机抽取对应数量的塔罗牌
4. 正逆位判定：为每张牌随机确定正位或逆位
5. AI 解析生成：结合牌面含义与用户问题生成个性化解读

功能架构图

正在加载图表渲染器...

架构说明：

• 用户交互层：接收用户命令输入，支持三种不同的占卜场景
• 核心处理层：实现意图识别、牌阵匹配、抽牌逻辑和 AI 解析的完整链路
• 数据资源层：提供牌阵配置、牌义定义和多主题塔罗牌资源

资源体系

韦特塔罗牌构成

该项目采用标准的韦特塔罗体系，共包含 78 张牌（README.md:43-50）：

宫廷牌说明：国王、皇后、骑士、侍从统称为宫廷牌，在小阿卡纳各系中各占 4 张。

多主题资源支持

项目支持多种塔罗牌主题资源（README.md:46-50）：

资源注意事项：资源包中额外包含的四张王牌不在占卜体系内，不会在占卜时使用，但可供收藏。

配置文件结构

tarot.json 是核心配置文件，定义了牌阵、抽牌规则和牌义解读（README.md:51-62）：

json
1{
2  "spreads": {
3    // 牌阵定义：名称、抽牌数量、是否切牌
4  },
5  "cards": {
6    // 每张牌的正逆位含义与资源路径
7    "major_arcana": { ... },
8    "wands": { ... },
9    "pentacles": { ... },
10    "cups": { ... },
11    "swords": { ... }
12  }
13}

配置要点：

• spreads 字段定义各牌阵的抽牌张数、是否有切牌
• cards 字段定义所有塔罗牌的正逆位含义与资源路径
• 正逆位解读参考《棱镜/耀光塔罗牌中文翻译》及网络资源

核心模块分析

意图识别模块

职责边界：

• 解析用户输入的关键词（如"情感"、"事业"、"学业"）
• 通过模糊匹配或 AI 调用选择最合适的牌阵
• 不负责具体的抽牌和解析逻辑

关键数据结构（推测，需确认）：

python
1# 用户意图结构
2class UserIntent:
3    query: str          # 原始输入
4    keywords: List[str] # 提取的关键词
5    spread_type: str    # 匹配的牌阵类型
6    confidence: float   # 匹配置信度

调用链：

1. 接收用户原始输入
2. 分词提取关键词
3. 遍历牌阵关键词库进行模糊匹配
4. 若匹配失败，调用 AI 进行智能选择
5. 返回牌阵类型给抽牌引擎

牌阵匹配模块

职责边界：

• 根据 tarot.json 中的 spreads 配置加载牌阵定义
• 确定抽牌数量、是否需要切牌
• 不负责实际的抽牌操作

关键配置示例（基于 README.md:51-52 推测）：

json
1{
2  "圣三角牌阵": {
3    "card_count": 3,
4    "has_cut_card": false,
5    "positions": ["过去", "现在", "未来"]
6  },
7  "凯尔特十字": {
8    "card_count": 10,
9    "has_cut_card": true,
10    "positions": [...]
11  }
12}

抽牌引擎

职责边界：

• 从 78 张牌池中随机抽取指定数量的牌
• 为每张牌随机确定正位或逆位
• 加载对应主题的图片资源

关键算法：

输入: 牌阵配置（抽牌数量）
输出: 抽取的牌列表（含正逆位）

1. 初始化牌池 = 78张牌
2. 对于每次抽牌:
   a. 从牌池随机选择一张
   b. 从牌池移除该牌
   c. 随机决定正位/逆位（50%概率）
   d. 加载对应主题的图片资源
3. 返回抽牌结果列表

错误处理：

• 牌池不足时抛出异常
• 资源路径无效时降级到默认主题

AI 解析模块

职责边界：

• 接收抽牌结果和用户问题
• 调用 AI 接口生成个性化解析
• 添加颜表情增强趣味性

输入输出结构（推测，需确认）：

python
1# 输入
2class ParseInput:
3    cards: List[Card]     # 抽取的牌（含正逆位）
4    spread: Spread        # 牌阵信息
5    question: str         # 用户问题
6
7# 输出
8class ParseOutput:
9    interpretation: str   # AI 生成的解析文本
10    emoji_expression: str # 颜表情

关键数据流

占卜命令完整调用链

正在加载图表渲染器...

流程说明：

1. 命令解析：识别用户输入的命令类型和参数
2. 意图识别：提取关键词并匹配牌阵
3. 牌阵匹配：根据 tarot.json 确定抽牌规则
4. 抽牌执行：随机抽牌并判定正逆位
5. AI 解析：生成个性化解读文本
6. 结果输出：整合图片和文本返回给用户

单张牌占卜简化流程

单张牌占卜（塔罗牌 命令）跳过牌阵匹配环节，直接进入抽牌和解析：

用户输入 → 命令识别 → 抽取单张牌 → AI 简短解析 → 返回结果

技术栈

目录结构

基于项目特性和资源说明，推测的核心目录结构（需确认）：

astrbot_plugin_tarot/
├── README.md                 # 项目说明文档
├── metadata.yaml             # 插件元数据
├── main.py                   # 插件入口（推测）
├── tarot.json               # 牌阵与牌义配置
├── How-to-add-new-tarot-theme.md  # 主题贡献指南
└── resources/               # 塔罗牌资源目录
    ├── WaiteTarot/          # 韦特标准主题
    │   ├── major/           # 大阿卡纳
    │   ├── wands/           # 权杖
    │   ├── pentacles/       # 星币
    │   ├── cups/            # 圣杯
    │   └── swords/          # 宝剑
    ├── BilibiliTarot/       # B站幻星集主题
    └── TouhouTarot/         # 东方主题

需要确认：具体目录结构和文件命名需查看实际仓库。

适用场景

项目来源

该项目改自以下开源项目（README.md:64-70）：

核心改进：将原 NoneBot/Hoshino 框架的塔罗牌功能移植到 AstrBot 框架，并增加了 AI 解析能力。

报告阅读路线图

正在加载图表渲染器...

推荐阅读顺序：

1. 项目总览（当前）：了解项目整体架构和核心功能
2. 安装与配置：学习如何部署和配置插件
3. 命令详解：深入了解各命令的使用方法和参数
4. 资源体系：掌握塔罗牌资源和主题的配置方法
5. 开发指南：参与项目开发，添加新的塔罗牌主题

项目核心能力量化

安装说明

当前版本需要手动安装（README.md:25-32）：

1. 下载插件代码放入 AstrBot 插件目录
2. 下载塔罗资源文件（下载链接，提取码: omBT）
3. 在配置文件中配置资源地址
4. 重启 AstrBot 加载插件

注意事项：插件采用读取本地资源的方式，需确保资源路径配置正确。

贡献指南

项目欢迎社区贡献新的塔罗牌主题资源（README.md:23-24）。详细的主题添加方法请参考 How-to-add-new-tarot-theme.md。

贡献流程：

1. 准备符合规格的塔罗牌图片资源
2. 按照指南创建主题目录结构
3. 提交 Pull Request 到项目仓库