OracleLang by ydzat

# OracleLang 六爻算卦插件

OracleLang 是一个基于传统六爻占卜原理的算卦插件，为 [LangBot](https://github.com/langbot-app/LangBot) 平台开发。使用传统的**三钱法**起卦，模拟投掷硬币生成卦象，并提供专业的卦象解读。

## 更新日志

### 3.1.0 (2026-02-23)
- **修复**：卦名显示顺序修正（上卦在前，下卦在后）
- **新增**：七级吉凶判断（大吉、吉、小吉、平、小凶、凶、大凶）
- **优化**：LLM 提示词改进，解读更加具体实用
  - 直接回答用户问题，不再泛泛而谈
  - 给出可执行的具体建议
  - 结合动爻爻辞进行针对性分析

### 3.0.0 (2026-02-23)
- **重大重构**：简化为纯六爻三钱法起卦
- 移除：文本起卦、数字起卦、时间起卦等方式
- 新增：完整的起卦过程展示（显示每次投掷结果）
- 新增：动爻标记（⚡）清晰展示
- 改进：更符合传统六爻占卜的起卦方式
- 改进：输出格式优化，展示投掷过程

### 2.1.0 (2025-11-07)
- **重大改进**：LLM 集成重构，使用 LangBot 4.0 内置 LLM API
- 移除：不再需要单独配置 LLM API 密钥
- 简化：配置项从 6 个减少到 1 个（llm_enabled）

### 2.0.0 (2025-11-06)
- **重大更新**：迁移到 LangBot 4.0 插件系统
- 新增：使用新的组件化架构（manifest.yaml + components）

### 1.0.0 (2025-04-24)
- 首次发布

## 系统要求

- LangBot 4.0 或更高版本
- Python 3.11+

## 安装

### 方法一：从 GitHub 安装（推荐）

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

### 方法二：手动上传

1. 从 [Releases](https://github.com/ydzat/OracleLang/releases) 下载最新的 `.lbpkg` 文件
2. 在 LangBot WebUI 插件页面上传安装

## 功能特点

- **传统三钱法起卦**：模拟投掷3枚硬币，共6次，生成六爻卦象
- **完整起卦过程展示**：显示每次投掷的硬币结果和爻的性质
- **动爻标记**：清晰展示老阳、老阴等动爻
- **专业卦象解读**：提供卦辞、爻辞和整体解释
- **LLM 增强解读**：可选使用大语言模型提供更深入的个性化解读
- **历史记录**：查询个人的算卦历史
- **使用限制**：每日限额管理，防止过度依赖

## 三钱法原理

三钱法是传统六爻占卜的经典起卦方式：

```
每爻投掷3枚硬币，根据正反面数量决定爻的性质：

● 正面  ○ 反面

●●● (3正) → 老阳(9) → 阳爻，动爻 ⚡
●●○ (2正) → 少阳(7) → 阳爻
●○○ (1正) → 少阴(8) → 阴爻
○○○ (0正) → 老阴(6) → 阴爻，动爻 ⚡
```

- **老阳/老阴**：为动爻，在变卦中会变化（阳变阴、阴变阳）
- **少阳/少阴**：为静爻，不发生变化

## 使用方法

### 基本用法

```
!suangua <您的问题>
```

示例：
```
!suangua 我今天的工作运势如何？
!suangua 近期是否适合投资？
!suangua 我与TA的缘分怎样？
```

### 查看帮助

```
!suangua help
```

### 查看历史记录

```
!suangua history
```

### 查看用户ID

```
!suangua myid
```

### 管理员命令

```
!suangua reset <用户ID>   # 重置用户今日使用次数
!suangua stats            # 查看系统使用统计
```

## 输出示例

```
📝 问题: 我今天的工作运势如何？

🎲 起卦过程:
  初爻: ●●○ → 少阳(7)
  二爻: ●○○ → 少阴(8)
  三爻: ●●● → 老阳(9) ⚡
  四爻: ○●● → 少阳(7)
  五爻: ○○○ → 老阴(6) ⚡
  上爻: ●○● → 少阳(7)

━━━━━━  原卦        ━━━━━━  变卦
━ ━ ━               ━ ━ ━
━━━━━━      →       ━ ━ ━  ⚡
━━━━━━              ━━━━━━
━ ━ ━               ━ ━ ━
━ ━ ━               ━ ━ ━
━━━━━━              ━ ━ ━  ⚡

📌 卦象: 天火同人 → 地水师
✨ 卦辞: 同人于野，亨。利涉大川，利君子贞。
🔄 动爻:
  三爻：伏戎于莽，升其高陵，三岁不兴。
  五爻：同人先号咷而后笑，大师克相遇。
🎯 吉凶: 小吉
📜 解释: [针对问题的具体解读]
💡 建议: [可执行的具体建议]

今日剩余算卦次数: 2/3
```

## 配置说明

在 LangBot WebUI 的插件配置页面可修改以下选项：

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| 每日算卦次数限制 | 每位用户每天最多算卦次数 | 3 |
| 每日重置时间 | 重置使用次数的时间点（0-23） | 0 |
| 启用大模型解释 | 使用 LLM 提供增强解读 | true |
| 卦象显示风格 | simple/traditional/detailed | detailed |
| 时区 | 用于日期计算的时区 | Asia/Shanghai |
| 管理员用户ID | 拥有管理权限的用户ID列表 | [] |

## 常见问题

### 1. 为什么每次算卦结果不同？

三钱法是随机起卦，每次投掷硬币的结果都是随机的，因此每次算卦会得到不同的卦象。这符合传统占卜的原理——"诚心求卦，卦应心生"。

### 2. 什么是动爻？

动爻是指老阳（三个正面）或老阴（三个反面）的爻。动爻在变卦中会发生变化：老阳变阴爻，老阴变阳爻。动爻往往是解卦的重点。

### 3. LLM 解释不工作？

- 确保在 LangBot 中已配置 LLM 模型
- 插件会自动使用第一个可用模型
- 如果没有配置模型，会使用传统解释（不影响基本功能）

### 4. 如何成为管理员？

在插件配置的「管理员用户ID列表」中添加您的用户ID。可通过 `!suangua myid` 查看ID。

## 技术架构

```
OracleLang/
├── main.py                 # 插件主类
├── manifest.yaml           # 插件配置清单
├── components/
│   └── commands/
│       ├── suangua.py      # 命令处理器
│       └── suangua.yaml    # 命令配置
├── src/
│   ├── calculator.py       # 三钱法卦象计算
│   ├── interpreter.py      # 卦象解释器
│   ├── glyphs.py          # 卦象渲染
│   ├── history.py         # 历史记录
│   ├── limit.py           # 使用限制
│   └── data_constants.py  # 64卦数据
└── data/
    └── static/
        └── hexagrams.json  # 卦象详细数据
```

## 反馈与支持

如有问题或建议，请提交 [GitHub Issues](https://github.com/ydzat/OracleLang/issues)。

## 许可证

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

- 您可以自由使用、修改和分发此软件
- 如果您修改了本软件并在网络上提供服务，您必须公开修改后的源代码
- 任何修改版本必须使用相同的许可证

Copyright (C) 2023-2026 @ydzat