快速上手

相关源文件

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

• README.md
• requirements.txt
• _conf_schema.json
• main.py
• LICENSE
• tarot.json
• metadata.yaml
• How-to-add-new-tarot-theme.md
• resources/TouhouTarot/MajorArcana/0-愚者.jpg
• resources/TouhouTarot/MajorArcana/03-女皇.jpg

本项目是一个基于 AstrBot 框架的塔罗牌占卜插件，支持多牌阵和单张牌占卜，并通过 AI 生成详细解析。插件采用读取本地资源的方式运行，需要用户自行下载塔罗牌图片资源并完成配置后方可使用。

环境要求与依赖安装

Python 依赖库

该插件依赖以下 Python 库才能正常运行：

以上依赖定义在 requirements.txt:1-3 中。安装时可通过 pip 命令一次性安装所有依赖：

bash
1pip install -r requirements.txt

AstrBot 框架版本

插件版本为 v0.1.5，适配 AstrBot v3.4.39 版本（README.md:19-22）。使用不兼容的框架版本可能导致插件无法正常加载或运行异常。

操作系统要求

该插件基于纯 Python 实现，无平台特定依赖，理论上支持 Windows、Linux 和 macOS 等主流操作系统。唯一要求是文件系统需支持中文文件名（塔罗牌图片资源包含中文名称）。

资源下载与配置

塔罗牌图片资源获取

由于插件只采用读取本地资源的方式运行（README.md:29-31），用户需要手动下载塔罗牌图片资源并放入指定目录。

资源下载地址：塔罗资源下载 提取码: omBT（README.md:33）

下载完成后，将资源解压到插件的 resources 目录下。资源目录结构应包含以下主题文件夹：

• BilibiliTarot：B站幻星集主题塔罗牌
• TouhouTarot：东方主题塔罗牌（仅包含大阿卡纳）

每个主题目录下应包含 MajorArcana（大阿卡纳）、Cups（圣杯）、Pentacles（星币）、Swords（宝剑）、Wands（权杖）等子目录。

配置文件参数说明

插件配置通过 _conf_schema.json 定义，包含以下可配置项（_conf_schema.json:1-18）：

配置示例（在 AstrBot 管理面板中设置）：

json
1{
2  "chain_reply": true,
3  "resource_path": "./resources",
4  "include_ai_in_chain": true
5}

注意：resource_path 配置项的提示信息中包含了资源下载链接（_conf_schema.json:10），方便用户在配置时查看。

安装步骤

手动安装流程

由于插件暂未提供自动安装方式，需要手动下载并放入插件目录（README.md:27）。完整安装步骤如下：

bash
1# 1. 进入 AstrBot 插件目录
2cd /path/to/astrbot/addons/
3
4# 2. 克隆或下载插件仓库
5git clone https://github.com/XziXmn/astrbot_plugin_tarot.git
6
7# 3. 进入插件目录
8cd astrbot_plugin_tarot
9
10# 4. 安装 Python 依赖
11pip install -r requirements.txt
12
13# 5. 下载塔罗牌资源（需手动完成）
14# 访问 https://www.123912.com/s/UQZ8Vv-uOLav? 提取码:omBT
15# 将下载的资源解压到 resources 目录
16
17# 6. 重启 AstrBot 使插件生效

安装验证

安装完成后，检查以下文件和目录是否存在：

• tarot.json：塔罗牌数据定义文件（必需）
• resources/：塔罗牌图片资源目录
• resources/BilibiliTarot/ 或 resources/TouhouTarot/：至少一个主题目录

基础命令使用

占卜命令

命令格式：占卜 [问题关键词]

功能说明：随机选取牌阵进行占卜并提供 AI 解析。可根据用户输入（如"占卜 情感"）模糊匹配或通过 AI 选择合适的牌阵（如"圣三角牌阵"），随机抽取对应数量的塔罗牌，并生成带颜表情的 AI 解析（README.md:37）。

使用示例：

占卜
占卜 情感
占卜 事业发展

内部处理流程（main.py:152-170）：

1. 随机选择一个塔罗牌主题
2. 加载 tarot.json 中的牌阵和卡牌数据
3. 根据用户输入匹配或随机选择牌阵
4. 发送"启用{牌阵名}，正在洗牌中..."提示
5. 抽取对应数量的塔罗牌并生成结果

单张牌抽取

命令格式：塔罗牌

功能说明：抽取一张塔罗牌，提供简短回应和 AI 解析，适合快速占卜（README.md:39）。

群聊转发切换

命令格式：开启/关闭群聊转发

功能说明：切换群聊转发模式（README.md:41）。开启后，多张塔罗牌结果将以合并转发消息的形式发送，避免刷屏。

插件初始化验证

初始化流程

插件在加载时会执行以下初始化操作（main.py:17-30）：

1. 读取配置文件中的 resource_path、chain_reply、include_ai_in_chain 参数
2. 创建资源目录（如果不存在）
3. 检查 tarot.json 文件是否存在
4. 输出初始化日志

初始化成功日志示例：

Tarot 插件初始化完成，资源路径: /path/to/resources, AI 解析加入转发: True

资源完整性检查

插件在运行时会进行以下资源检查（main.py:27-29）：

• tarot.json 文件检查：如果文件缺失，插件将抛出异常并记录错误日志："tarot.json 文件缺失，请确保资源完整！"
• 主题目录检查：在选择主题时，如果本地塔罗牌主题为空，将抛出异常（main.py:32-37）

资源检查失败日志示例：

ERROR - tarot.json 文件缺失，请确保资源完整！
ERROR - 本地塔罗牌主题为空，请检查资源目录！

常见问题与排错

问题 1：插件加载失败，提示 tarot.json 文件缺失

原因：插件目录中缺少 tarot.json 数据定义文件。

解决方案：

1. 检查插件目录是否完整
2. 确认 tarot.json 文件存在于插件根目录
3. 重新下载插件或从仓库获取该文件

验证方法：

bash
1ls -la /path/to/astrbot_plugin_tarot/tarot.json

问题 2：占卜时提示"本地塔罗牌主题为空"

原因：resources 目录为空或不包含任何有效的主题文件夹。

解决方案：

1. 确认已下载塔罗牌图片资源
2. 检查 resources 目录下是否包含 BilibiliTarot 或 TouhouTarot 等主题文件夹
3. 确认配置文件中的 resource_path 路径正确

验证方法：

bash
1ls -la /path/to/astrbot_plugin_tarot/resources/

问题 3：图片显示为"图片不存在"

原因：塔罗牌图片资源不完整，缺少某些卡牌的图片文件。

解决方案：

1. 检查日志中提示的具体图片路径
2. 确认对应主题目录下包含所有必需的子目录（MajorArcana、Cups、Pentacles、Swords、Wands）
3. 重新下载完整的资源包

日志示例（main.py:71-72）：

WARNING - 图片 TouhouTarot/MajorArcana/0-愚者 不存在！

问题 4：AI 解析生成失败

原因：AstrBot 框架未正确配置 LLM 提供商，或 API 调用失败。

解决方案：

1. 确认 AstrBot 已配置有效的 LLM 提供商
2. 检查 API 密钥和网络连接
3. 查看日志中的详细错误信息

日志示例（main.py:149-150）：

ERROR - 生成 AI 解析失败: [错误详情]

问题 5：群聊转发消息无法正常显示

原因：chain_reply 配置项设置为 false，或平台不支持合并转发功能。

解决方案：

1. 检查配置文件中 chain_reply 是否为 true
2. 确认使用的消息平台支持合并转发功能
3. 尝试使用"开启群聊转发"命令动态切换

下一步建议

完成快速上手后，可以进行以下进阶操作：

1. 添加自定义塔罗牌主题：参考 How-to-add-new-tarot-theme.md 文档，创建个性化的塔罗牌主题资源

2. 自定义牌阵配置：修改 tarot.json 文件中的 formations 字段，添加或调整牌阵定义

3. 调整 AI 解析风格：通过修改 main.py 中的 system_prompt 参数，定制占卜师的解析风格

4. 扩展塔罗牌含义：在 tarot.json 的 cards 字段中添加或修改卡牌的正逆位含义解释

详细的配置说明和高级用法，请参阅项目 README 和源代码注释。