本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：WWW/plugins/yijing_divination/说明.md。
易经占卜（yijing_divination）
版本：1.0.0
状态：⏸ 未启用（站长在「插件管理」开启后可用）
分类：娱乐（
entertainment）最低核心：1.1.26
它是什么
一个纯 PHP 本地排盘的易经占卜工具：时间起卦 + 手动摇卦，输出本卦 / 互卦 / 变卦，
并装好纳甲干支、六亲、世应、六神与旬空。排盘不依赖任何外部历法库、不联网、毫秒级完成。
刻意不做八字、不做紫微 —— 那两套的历法复杂度（真太阳时、节气精确时刻、闰月规则叠加）
远超占卜场景所需，且极易算错。本插件只把「六爻排盘 + 梅花易数」这一件事做扎实。
AI 解读是可选增强：开了才有，且永远不阻塞排盘（见下）。
功能
| 功能 | 说明 |
|---|---|
| 时间起卦 | 公历年月日时 → 农历 → 上卦/下卦/动爻（梅花易数口径） |
| 手动摇卦 | 六爻各选四象（老阴/少阳/少阴/老阳），老阴老阳为动爻 |
| 晚子时进位 | 23:00 起卦按「子时换日」整体进位到次日（日柱、农历、起卦三数一起换） |
| 装卦 | 纳甲、六亲、八宫世应、六神、旬空、变卦六亲（按本卦宫论） |
| 体用生克 | 单动爻时给出体/用与比和·用生体·体生用·体克用·用克体五象 |
| 卦象展示 | 六爻自下而上（初爻在最底），阳爻实线、阴爻断线，全部纯 CSS |
| AI 辅助解卦 | 排盘后入队，前端轮询取结果；未配置 Key 时零外呼 |
| 我的卦例 | 分页列出历史卦例，可回看任意一卦 |
| 后台 | 开关 / 游客 / 每日上限 / 手动摇卦 / AI 六项参数 + 最近 20 条卦例 + 重解 |
目录结构
plugins/yijing_divination/
├── plugin.json # 5 个钩子 + route:admin / system:settings / net:fetch
├── Plugin.php # 排盘算法（纯静态）+ 生命周期 + 设置 + 入队
├── AiWorker.php # AI 消费端（有界预算 + 文件锁 + 租约回收）
├── FrontController.php # index / cast / history / aiPoll
├── AdminController.php # 设置 / 保存 / 重解
├── hook/
│ ├── init_after.php # 惰性建表（marker 门控，命中即零 SQL）
│ ├── route_register.php # 4 条前台路由（含 /api/yijing/ai）
│ ├── admin_route_register.php # 3 条后台路由
│ ├── nav_plugin_links.php # 「应用」入口（左栏 + 顶栏双触发）
│ └── nav_user_menu_items.php # 移动端「我的卦」
├── views/
│ ├── index.php # 起卦页 + 结果
│ ├── _chart.php # 卦象片段（本卦/互卦/变卦/体用）
│ ├── _ai_panel.php # AI 面板（三态 + 轮询挂载点）
│ ├── history.php # 我的卦例
│ └── admin.php # 后台（设置 + 最近卦例，不做 Tab）
├── assets/
│ ├── style.css # 全部视觉（只用 --mn-* 变量，自动适配暗夜星辰）
│ └── script.js # AI 轮询（原生 fetch + 递归 setTimeout）
├── lang/{zh,en,zh_tw}.php # 三语各 136 键，键集合与键序完全一致
└── data/ # 自动生成（SQLite + 队列 + .htaccess / web.config）数据表
插件独立库 data/yijing_divination.sqlite，单表 yj_records：
| 字段 | 用途 |
|---|---|
user_id | 归属（游客卦不落库） |
question | 所问之事（≤120 字） |
cast_type / solar_date / solar_hour | 起卦方式与时刻 |
lunar_text / ganzhi_text | 农历与四柱快照（便于列表直接展示，不必解 JSON） |
ben_name / ben_pattern / bian_name / hu_name / moving_line | 卦名与索引列 |
snapshot | 完整卦象 JSON（结果页只读它，不再重算） |
ai_status / ai_content / ai_error | AI 三态：none / pending / processing / ok / error |
AI 解卦为什么不阻塞
POST /yijing/cast
└─ 排盘（纯函数，< 1ms）→ 落库 → Queue::push() 入插件自有队列 → 302 到结果页
（到这里页面已经返回了）
GET /api/yijing/ai?id=N ← 前端每 2.5s 轮询
└─ 若 ai_status = pending：本次请求内**有界**消费（最多 1 条、25s 预算）
├─ 文件锁拿不到 → 说明别的请求正在解，直接返回 pending
├─ 调大模型（走 Plugin::http，含 net:fetch 权限 + SSRF 防护）
└─ 写回 ai_status = ok / error → 前端拿到终态即 stop()前端 script.js 的防泄漏要点：递归 setTimeout（不用 setInterval，避免慢网络下请求堆积）、
单一 timer 句柄、终态即停、最多 40 次、页面隐藏降频、pagehide 清理。
卦象为什么这么画
- 顺序：数据里 lines 是「初→上」，渲染时倒序输出
<tr>，所以 DOM 顺序就是视觉顺序
（上爻在最顶、初爻在最底），不依赖 flex-direction: column-reverse，打印与老浏览器一致。
- 阳爻：一个伪元素
border-top铺满整行。 - 阴爻：
::before/::after各画半段border-top，中间留 14px 缺口。 - 动爻：改主色（
--mn-primary）；空亡：降透明度（不换色，避免与动爻混淆）。 - 颜色全部取
--mn-*变量 → 亮色主题与「暗夜星辰」暗色主题自动跟随，无需主题覆盖层。
后台配置项
| 键 | 默认 | 说明 |
|---|---|---|
yj_enabled | 1 | 模块总开关 |
yj_guest_enabled | 0 | 允许游客起卦（不落库、无 AI） |
yj_daily_limit | 20 | 每人每日上限，0 = 不限 |
yj_manual_enabled | 1 | 开放手动摇卦 |
yj_ai_enabled | 0 | 启用 AI 解卦（还需填 Key） |
yj_ai_api_url | DeepSeek | OpenAI 兼容的 chat/completions 地址 |
yj_ai_api_key | 空 | 留空 = 保持原值；勾「清除」才清空 |
yj_ai_model | deepseek-chat | 模型名 |
yj_ai_temperature | 0.7 | 0 ~ 2 |
yj_ai_max_tokens | 900 | 100 ~ 4000 |
yj_ai_prompt | 空 | 自定义系统提示词，留空用内置 |
全部键以 yj_ 前缀，uninstall() 逐键 DELETE FROM settings 后 clearCache() + buildCache()。
已知边界
- 农历支持 1900-01-31 ~ 2100-12-31（农历表基准日是 1900-01-31，不是 1900-01-01）；
更早/更晚的日期返回 date_out_of_range，页面提示「日期超出支持范围」。
- 月建用平气近似（各节固定日期），边界日误差 ≤ 1 天 —— 占卜场景可接受。
- 建表有 marker 门控（
data/.yj_schema_v1）：手工删表后必须一并删掉这个 marker，
否则 init_after 认为表还在、不会重建。
