OracleLang 是一个基于易经原理的智能算卦插件，为 LangBot 平台开发。它结合《易经》原理与数学模型，通过用户的问题生成卦象，并提供图示和解释。

• 重大改进：LLM 集成重构，使用 LangBot 4.0 内置 LLM API
• 移除：不再需要单独配置 LLM API 密钥、API 类型等
• 新增：支持使用 LangBot 中配置的任何 LLM 模型
• 简化：配置项从 6 个减少到 1 个（llm_enabled），自动使用第一个可用模型
• 优化：移除 aiohttp 依赖，减小插件体积
• 改进：更好的 LLM 调用错误处理和日志记录
• 改进：LLM 默认启用，开箱即用
• 修复：兼容 LangBot 的 get_llm_models() API 返回格式（list[dict] 而非 list[str]）

• 重大更新：迁移到 LangBot 4.0 插件系统
• 新增：使用新的组件化架构（manifest.yaml + components）
• 新增：通过 WebUI 配置插件参数
• 改进：使用新的事件监听器组件处理消息
• 改进：更好的日志记录和错误处理
• 改进：配置管理通过 manifest.yaml 进行
• 注意：此版本需要 LangBot 4.0 或更高版本
• 新增：完整的配置验证功能，在启动时检查配置有效性
• 新增：可配置时区支持，不再硬编码 UTC+8
• 改进：清理和固定依赖版本，移除未使用的依赖（numpy、requests、pyyaml）
• 改进：更好的时区处理，支持夏令时
• 改进：配置错误时提供清晰的错误信息
• 改进：添加完整的测试覆盖

• 改进：优化配置文件管理，自动生成默认配置
• 移除：删除多余的config.yaml.example文件
• 更新：完善README文档，明确配置文件自动生成机制

• 优化：将静态数据从代码中分离，统一到data_constants.py模块
• 改进：完善HEXAGRAM_UNICODE映射表，支持所有64卦显示
• 增加：添加HEXAGRAM_NAMES常量，便于卦象名称查询

• 首次发布
• 支持多种起卦方式
• 实现基本卦象解读功能
• 添加用户使用限制
• 支持历史记录查询

• LangBot 4.0 或更高版本
• Python 3.10+

1. 打开 LangBot WebUI
2. 进入"插件"页面
3. 点击"安装插件"
4. 选择"从 GitHub 安装"
5. 输入仓库地址：https://github.com/ydzat/OracleLang
6. 点击"安装"

1. 克隆本仓库到 LangBot 的 data/plugins 目录下：

cd /path/to/LangBot/data/plugins/
git clone https://github.com/ydzat/OracleLang

2. 在 LangBot WebUI 中启用插件

详细安装说明请参考 LangBot 插件文档

• 多种起卦方式：支持文本、数字、时间等多种起卦方法
• 直观的卦象图示：清晰展示原卦和变卦（如有）
• 专业的卦象解读：提供卦辞、爻辞和整体解释
• 个性化建议：根据卦象给出针对问题的实用建议
• 大语言模型集成：可选使用 LangBot 中配置的 LLM 模型提供更深入的解读
• 历史记录功能：查询个人的算卦历史
• 使用限制管理：防止过度依赖，管理员可调整

如果您不确定如何使用本插件，可以随时查看帮助信息：

@机器人 !suangua 帮助

系统会返回完整的使用说明和示例。

在群聊中需要 @机器人 并发送命令 算卦 加上您的问题，即可进行算卦：

@机器人 !suangua 我今天的工作运势如何？ 
@机器人 !suangua 近期是否适合投资股票？ 
@机器人 !suangua 我与TA的缘分怎样？

在私聊中直接发送命令即可：

!suangua 我今天的工作运势如何？

如果您不提供问题，插件会随缘为您生成一卦：

@机器人 !suangua

OracleLang 支持多种起卦方式：

直接提供问题文本，系统会基于问题内容生成卦象：

@机器人 !suangua 我的事业前景如何

您可以提供一个数字作为起卦依据：

@机器人 !suangua 数字 1234 我的事业发展

数字起卦会基于您提供的数字序列生成卦象，这种方式对于需要稳定结果的情况很有用。

使用当前时间作为起卦依据：

@机器人 !suangua 时间 今日 财运
@机器人 !suangua 时间 今年 财运

时间起卦会使用当前的年、月、日、时、分、秒等时间信息生成卦象，适合日常占卜。

查看您的算卦历史记录：

@机器人 !suangua 历史

系统会返回您最近的5条算卦记录，包括时间、问题和结果摘要。

如果需要知道自己的用户ID（例如用于管理命令或查询限制），可以发送以下命令：

@机器人 !suangua 我的ID

系统会返回您的用户ID。

以下命令仅管理员可用：

@机器人 !suangua 设置 次数 5

将每位用户的每日算卦次数限制调整为5次。

@机器人 !suangua 重置 123456789

重置指定用户ID的当日算卦次数，使其可以继续算卦。

@机器人 !suangua 统计

显示总用户数和总算卦次数等统计信息。

OracleLang 使用多种方法将输入转换为易经中的64卦：

• 将问题文本转换为数值序列（基于字符的ASCII/Unicode值）
• 应用数学算法生成6个爻的阴阳属性（0为阴爻，1为阳爻）
• 确定动爻（变化的爻）
• 生成原卦和变卦（如有动爻）

• 将提供的数字序列作为起卦种子
• 通过数学运算将种子转换为6个爻的阴阳属性
• 确定动爻和变卦

• 使用当前时间的年、月、日、时、分、秒作为起卦种子
• 应用类似的数学算法生成卦象
• 确定动爻和变卦

算卦结果将包含以下内容：

• 卦象图示：使用易经传统符号直观展示原卦和变卦
• 卦辞：源自《易经》的原始卦辞
• 动爻解释：如有动爻，将提供相应的爻辞解释
• 综合解释：结合问题和卦象的整体解读
• 建议：基于卦象给出的实用建议

为避免过度依赖，系统默认限制每位用户每日算卦3次（使用配置的时区计算，默认每天0点重置）。管理员可以通过设置命令调整此限制和重置时间。

在 LangBot 4.0 中，插件配置通过 WebUI 进行管理。安装插件后，在插件页面点击"配置"按钮即可修改以下配置项：

• 每日算卦次数限制 (daily_max): 每位用户每天最多可以算卦的次数（默认：3）
• 每日重置时间 (reset_hour): 每日重置使用次数的时间点，0-23（默认：0，即午夜）
• 时区 (timezone): 用于日期和时间计算的时区（默认：Asia/Shanghai）
  • 支持标准时区名称，如：
    • Asia/Shanghai - 中国标准时间（UTC+8）
    • America/New_York - 美国东部时间
    • Europe/London - 英国时间
    • Asia/Tokyo - 日本时间
  • 完整时区列表请参考 IANA 时区数据库
• 卦象显示风格 (display_style): 卦象的视觉显示风格
  • simple: 简洁
  • traditional: 传统
  • detailed: 详细（默认）
• 管理员用户ID列表 (admin_users): 拥有管理员权限的用户ID列表
• 调试模式 (debug): 启用调试输出（默认：false）

• 启用大模型解释 (llm_enabled): 使用大语言模型提供增强的卦象解释（默认：true，已启用）

注意：

• 从 LangBot 4.0 开始，插件直接使用 LangBot 中配置的 LLM 模型，无需单独配置 API 密钥
• 插件会自动使用 LangBot 中配置的第一个可用模型
• 如果 LangBot 中没有配置任何模型，插件会自动降级到使用传统解释（不影响基本功能）

1. 在 LangBot WebUI 的"模型"页面添加并配置您的 LLM 模型（如 OpenAI、DeepSeek、千帆等）
2. 确保 OracleLang 插件配置中"启用大模型解释"为 true（默认已启用）
3. 保存配置后，插件会自动使用 LangBot 中的第一个可用模型来提供增强的卦象解释

提示：如果您不想使用 LLM 功能，可以在插件配置中将"启用大模型解释"设置为 false。

OracleLang 采用异步处理架构，保证在高并发情况下的稳定性。插件由以下几个核心模块组成：

1. 卦象计算器：负责根据输入生成卦象
2. 卦象解释器：提供卦辞和爻辞解释
3. 卦象渲染器：生成直观的卦象图示
4. 历史记录管理器：存储和检索用户的算卦历史
5. 使用限制管理器：控制用户的使用频率

在 LangBot WebUI 的插件页面，找到 OracleLang 插件，点击"配置"按钮即可修改配置。

请确保您的用户ID已添加到插件配置的"管理员用户ID列表"中。可以通过发送"算卦 我的ID"命令查看您的用户ID。

每次算卦结果都会显示您当日剩余的算卦次数。

大语言模型提供的是参考性解释，结合了易经原理和现代解读。它不是完全权威的，建议结合个人判断。

算卦结果会自动保存到历史记录中，可通过"算卦 历史"命令查看最近5条记录。

• 确保 LangBot 版本为 4.0 或更高
• 检查插件是否已在 WebUI 中启用
• 查看 LangBot 日志以获取错误信息
• 确保所有依赖已正确安装

如有问题或建议，请提交GitHub Issues或联系作者。

本项目采用 GNU Affero General Public License v3.0 (AGPL-3.0) 许可证开源。这意味着：

• 您可以自由使用、修改和分发此软件
• 如果您修改了本软件并在网络上提供服务，您必须公开修改后的源代码
• 任何修改版本必须使用相同的许可证
• 完整许可证文本请参见项目根目录下的LICENSE文件

Copyright (C) 2023 @ydzat