OracleLang 是一个基于传统六爻占卜原理的算卦插件，为 LangBot 平台开发。使用传统的三钱法起卦，模拟投掷硬币生成卦象，并提供专业的卦象解读。
- 重大更新: 升级到 LangBot SDK 0.3.11，命令触发改为自然语言
算卦 - 新增: EventListener 组件支持自然语言触发（无需命令前缀）
- 新增: WebUI 管理面板，展示使用统计
- 新增: 内置 Markdown → 图片渲染（pillowmd），无需额外插件
- 新增: 私聊和群聊的算卦限额/历史记录独立追踪
- 新增: MarkdownFormatter 模块（src/formatter.py），支持完整卦象渲染
- 变更: 输出格式改为「文字/图片」可选，默认图片
- 变更: 深度思考模型（DeepSeek-R1 等）兼容，自动剥离推理内容
- 变更: 命令路由改用 SDK 原生
name="*"catch-all 模式 - 变更: 所有回复使用 Markdown 格式（标题、代码块、粗体）
- 变更: 用户标识加入
{launcher_type}前缀 - 变更: LLM 默认超时设为 120 秒
- 变更: 旧
display_style值自动迁移为图片模式 - 修复: 双回复问题（prevent_default 阻止主 pipeline）
- 移除:
src/config_validator.py（验证逻辑内联到 main.py） - 移除:
set子命令（limit.py 中不存在对应方法）
- 修复：卦名显示顺序修正（上卦在前，下卦在后）
- 新增：七级吉凶判断（大吉、吉、小吉、平、小凶、凶、大凶）
- 优化：LLM 提示词改进，解读更加具体实用
- 直接回答用户问题，不再泛泛而谈
- 给出可执行的具体建议
- 结合动爻爻辞进行针对性分析
- 重大重构：简化为纯六爻三钱法起卦
- 移除：文本起卦、数字起卦、时间起卦等方式
- 新增：完整的起卦过程展示（显示每次投掷结果）
- 新增：动爻标记（⚡）清晰展示
- 改进：更符合传统六爻占卜的起卦方式
- 改进：输出格式优化，展示投掷过程
- 重大改进：LLM 集成重构，使用 LangBot 4.0 内置 LLM API
- 移除：不再需要单独配置 LLM API 密钥
- 简化：配置项从 6 个减少到 1 个（llm_enabled）
- 重大更新：迁移到 LangBot 4.0 插件系统
- 新增：使用新的组件化架构（manifest.yaml + components）
- 首次发布
- LangBot 4.0 或更高版本
- Python 3.11+
- 打开 LangBot WebUI
- 进入「插件」页面
- 点击「从 GitHub 安装」
- 输入仓库地址：
https://github.com/ydzat/OracleLang - 选择版本并安装
- 从 Releases 下载最新的
.lbpkg文件 - 在 LangBot WebUI 插件页面上传安装
- 传统三钱法起卦：模拟投掷3枚硬币，共6次，生成六爻卦象
- 完整起卦过程展示：显示每次投掷的硬币结果和爻的性质
- 动爻标记：清晰展示老阳、老阴等动爻
- 专业卦象解读：提供卦辞、爻辞和整体解释
- LLM 增强解读：可选使用大语言模型提供更深入的个性化解读
- 历史记录：查询个人的算卦历史（私聊和群聊记录独立追踪）
- 使用限制：每日限额管理，防止过度依赖（私聊和群聊限额独立计算）
- Markdown 输出 + 图片渲染：内置 pillowmd 渲染引擎，将 Markdown 格式回复实时渲染为精美图片。也可切换为纯文字模式。
- WebUI 管理面板：在 LangBot WebUI 中查看使用统计和系统状态
三钱法是传统六爻占卜的经典起卦方式：
每爻投掷3枚硬币，根据正反面数量决定爻的性质：
● 正面 ○ 反面
●●● (3正) → 老阳(9) → 阳爻，动爻 ⚡
●●○ (2正) → 少阳(7) → 阳爻
●○○ (1正) → 少阴(8) → 阴爻
○○○ (0正) → 老阴(6) → 阴爻，动爻 ⚡
- 老阳/老阴：为动爻，在变卦中会变化（阳变阴、阴变阳）
- 少阳/少阴：为静爻，不发生变化
直接发送消息即可：
算卦 <您的问题>
示例：
算卦 我今天的工作运势如何？
算卦 近期是否适合投资？
算卦 我与TA的缘分怎样？
算卦 help
算卦 history
算卦 myid
!算卦 reset <用户ID> # 重置用户今日使用次数
!算卦 stats # 查看系统使用统计
普通用户直接输入
算卦即可使用。管理员命令以!算卦前缀触发。
插件内置 pillowmd 渲染引擎，算卦结果自动渲染为精美图片。也可在配置中切换为纯文字模式。
图片模式（默认）：
（算卦结果以图片形式展示，包含标题、卦象、解读、吉凶判断、建议等）
文字模式：
📝 问题: 我今天的工作运势如何？
🎲 起卦过程:
初爻: ●●○ → 少阳(7)
二爻: ●○○ → 少阴(8)
三爻: ●●● → 老阳(9) ⚡
四爻: ○●● → 少阳(7)
五爻: ○○○ → 老阴(6) ⚡
上爻: ●○● → 少阳(7)
━━━━━━ 原卦 ━━━━━━ 变卦
━ ━ ━ ━ ━ ━
━━━━━━ → ━ ━ ━ ⚡
━━━━━━ ━━━━━━
━ ━ ━ ━ ━ ━
━ ━ ━ ━ ━ ━
━━━━━━ ━ ━ ━ ⚡
📌 卦象: 天火同人 → 地水师
✨ 卦辞: 同人于野，亨。利涉大川，利君子贞。
🔄 动爻:
三爻：伏戎于莽，升其高陵，三岁不兴。
五爻：同人先号咷而后笑，大师克相遇。
🎯 吉凶: 小吉
📜 解释: [针对问题的具体解读]
💡 建议: [可执行的具体建议]
今日剩余算卦次数: 2/3
在 LangBot WebUI 的插件配置页面可修改以下选项：
| 配置项 | 说明 | 默认值 |
|---|---|---|
| 每日算卦次数限制 | 每位用户每天最多算卦次数 | 3 |
| 每日重置时间 | 重置使用次数的时间点（0-23） | 0 |
| 启用大模型解释 | 使用 LLM 提供增强解读 | true |
| 大语言模型 | 选择用于解读的 LLM 模型（留空则自动选择） | 无 |
| 输出格式 | 图片 / 文字 | 图片 |
| 时区 | 用于日期计算的时区 | Asia/Shanghai |
| 管理员用户ID | 拥有管理权限的用户ID列表 | [] |
三钱法是随机起卦，每次投掷硬币的结果都是随机的，因此每次算卦会得到不同的卦象。这符合传统占卜的原理——"诚心求卦，卦应心生"。
动爻是指老阳（三个正面）或老阴（三个反面）的爻。动爻在变卦中会发生变化：老阳变阴爻，老阴变阳爻。动爻往往是解卦的重点。
- 确保在 LangBot 中已配置 LLM 模型
- 插件会自动使用第一个可用模型
- 如果没有配置模型，会使用传统解释（不影响基本功能）
在插件配置的「管理员用户ID列表」中添加您的用户ID。可通过 算卦 myid 查看ID。
OracleLang/
├── main.py # 插件主类（含配置验证逻辑）
├── manifest.yaml # 插件配置清单
├── components/
│ ├── commands/
│ │ ├── suangua.py # 命令处理器（管理员命令）
│ │ └── suangua.yaml # 命令配置
│ ├── event_listener/
│ │ └── suangua.py # 事件监听器（自然语言触发）
│ └── page/
│ └── index.py # WebUI 管理面板
├── src/
│ ├── calculator.py # 三钱法卦象计算
│ ├── interpreter.py # 卦象解释器
│ ├── glyphs.py # 卦象渲染（3种风格）
│ ├── formatter.py # Markdown 格式化输出
│ ├── history.py # 历史记录（launcher_type 感知）
│ ├── limit.py # 使用限制（launcher_type 感知）
│ └── data_constants.py # 64卦映射表、八卦、Unicode符号
├── data/
│ └── static/
│ ├── hexagrams.json # 卦象详细数据（运行时生成）
│ └── hexagrams_complete.json # 完整数据源
└── .github/workflows/
└── release.yml # CI/CD 自动打包发布
如有问题或建议，请提交 GitHub Issues。
本项目采用 GNU Affero General Public License v3.0 (AGPL-3.0) 许可证开源。
- 您可以自由使用、修改和分发此软件
- 如果您修改了本软件并在网络上提供服务，您必须公开修改后的源代码
- 任何修改版本必须使用相同的许可证
Copyright (C) 2023-2026 @ydzat