feat: 周易算卦系统 — 铜钱法占卜 + AI 流式解读

基于传统铜钱法的六十四卦占卜系统，FastAPI 后端 + 原生前端单页应用。
支持接入任意 OpenAI 兼容 LLM，WebSocket 流式推送 AI 卦辞解读。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.env.example

@@ -0,0 +1,5 @@
+# LLM 配置 — 支持任何 OpenAI 兼容 API
+# 复制为 .env 并修改，或直接运行 ./start.sh 交互式配置
+LLM_BASE_URL=http://localhost:1234/v1
+LLM_API_KEY=lm-studio
+LLM_MODEL=google/gemma-4-26b-a4b

.gitignore

@@ -0,0 +1,6 @@
+.env
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.claude/

README.md

@@ -0,0 +1,121 @@
+# I-Ching · 周易算卦
+
+基于传统铜钱法的周易六十四卦占卜系统，支持 AI 卦辞解读。
+
+## 功能特色
+
+- **铜钱法摇卦** — 模拟三枚铜钱投掷六次，依据传统规则生成本卦与变卦
+- **完整卦象数据** — 六十四卦卦辞、象辞、爻辞，八卦符号与五行属性
+- **AI 卦辞解读** — 接入任意 OpenAI 兼容 LLM（LM Studio / Ollama / DeepSeek / OpenAI 等），WebSocket 流式输出
+- **3D 铜钱动画** — 逐爻翻转动画，逐行揭示卦象，沉浸式体验
+- **六十四卦速查** — 可展开的全卦浏览网格，点击查看完整卦辞与爻辞
+
+## 技术栈
+
+| 层 | 技术 |
+|---|---|
+| 后端 | Python · FastAPI · Uvicorn · OpenAI SDK |
+| 前端 | 原生 HTML / CSS / JS（单文件，无框架） |
+| AI | 任意 OpenAI 兼容 API |
+
+## 项目结构
+
+```
+i-ching/
+├── backend/
+│   ├── main.py              # FastAPI 应用 & API 路由 & WebSocket
+│   ├── divination.py        # 铜钱法算卦核心算法
+│   ├── hexagrams_data.py    # 六十四卦 & 八卦完整数据
+│   └── requirements.txt     # Python 依赖
+├── frontend/
+│   └── index.html           # 单页前端应用
+├── tests/
+│   └── test_divination.py   # 算法 & API & 数据完整性测试
+├── dev-doc/
+│   └── INTERFACE.md         # API 接口契约文档
+├── start.sh                 # 一键安装 & 启动脚本
+├── .env.example             # 环境变量示例
+└── README.md
+```
+
+## 快速开始
+
+### 前置要求
+
+- Python 3.10+
+- （可选）[uv](https://github.com/astral-sh/uv) — 加速依赖安装
+
+### 一键启动
+
+```bash
+./start.sh
+```
+
+首次运行会自动创建虚拟环境、安装依赖，并交互式配置 LLM 连接信息（保存到 `.env`）。
+
+### 手动启动
+
+```bash
+# 1. 创建并激活虚拟环境
+uv venv .venv        # 或 python3 -m venv .venv
+source .venv/bin/activate
+
+# 2. 安装依赖
+uv pip install -r backend/requirements.txt   # 或 pip install -r backend/requirements.txt
+
+# 3. 配置环境变量
+cp .env.example .env
+# 编辑 .env 填入你的 LLM 服务信息
+
+# 4. 启动
+set -a && source .env && set +a
+uvicorn backend.main:app --host 0.0.0.0 --port 8000 --reload
+```
+
+启动后访问 **http://localhost:8000**。
+
+### 环境变量
+
+| 变量 | 说明 | 默认值 |
+|---|---|---|
+| `LLM_BASE_URL` | LLM API 地址 | `http://localhost:1234/v1` |
+| `LLM_API_KEY` | API 密钥 | `lm-studio` |
+| `LLM_MODEL` | 模型名称 | `google/gemma-4-26b-a4b` |
+| `PORT` | 服务端口 | `8000` |
+
+> AI 卦辞解读依赖 LLM 服务，其余功能（摇卦、卦象查询）不受影响。
+
+## API 接口
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `POST` | `/api/divine` | 算卦（可传 `question` 字段） |
+| `GET` | `/api/hexagrams` | 获取六十四卦列表 |
+| `GET` | `/api/hexagrams/{number}` | 获取单卦详情（1-64） |
+| `WebSocket` | `/ws/interpret` | AI 流式解读卦象 |
+
+详细接口契约见 [dev-doc/INTERFACE.md](dev-doc/INTERFACE.md)。
+
+## 算卦原理
+
+采用传统**铜钱法**：每次投掷三枚铜钱，字面（有字）为 3，花面（无字）为 2，三币之和决定爻的阴阳：
+
+| 和值 | 爻 | 性质 |
+|---|---|---|
+| 6 | ⚋ 老阴 | 变爻（阴→阳） |
+| 7 | ⚊ 少阳 | 不变 |
+| 8 | ⚋ 少阴 | 不变 |
+| 9 | ⚊ 老阳 | 变爻（阳→阴） |
+
+投掷六次，由下而上排列六爻，下三爻为下卦，上三爻为上卦，组合成六十四卦之一。若有变爻（6 或 9），则同时生成变卦。
+
+## 测试
+
+```bash
+source .venv/bin/activate
+pytest tests/ -v
+```
+
+## 许可证
+
+MIT

backend/divination.py

@@ -0,0 +1,195 @@
+"""
+周易铜钱摇卦算法
+
+铜钱法规则：
+- 模拟投掷三枚铜钱，共投掷6次（从初爻到上爻）
+- 正面(字)=3，反面(花)=2
+- 三枚铜钱之和：6=老阴(变), 7=少阳, 8=少阴, 9=老阳(变)
+- 老阴(6)和老阳(9)为动爻，会产生变卦
+- 阳爻(7,9)对应二进制1，阴爻(6,8)对应二进制0
+"""
+
+import random
+from .hexagrams_data import (
+    TRIGRAMS,
+    lookup_hexagram_number,
+    get_hexagram_by_number,
+)
+
+
+def coin_toss() -> int:
+    """
+    模拟投掷三枚铜钱
+    每枚铜钱：正面(字)=3, 反面(花)=2
+    返回三枚铜钱之和：6(老阴), 7(少阳), 8(少阴), 9(老阳)
+    """
+    coins = [random.choice([2, 3]) for _ in range(3)]
+    return sum(coins)
+
+
+def divine() -> dict:
+    """
+    完整的摇卦过程：投掷6次铜钱，得到6个爻
+    返回6个爻的值列表（从初爻到上爻）
+    """
+    lines = [coin_toss() for _ in range(6)]
+    return lines
+
+
+def lines_to_binary(lines: list[int]) -> tuple[int, ...]:
+    """
+    将爻值列表转换为二进制表示
+    阳爻(7,9) -> 1, 阴爻(6,8) -> 0
+    """
+    return tuple(1 if line in (7, 9) else 0 for line in lines)
+
+
+def binary_to_trigram_name(binary: tuple[int, ...]) -> str | None:
+    """
+    将三位二进制转换为卦名
+    """
+    for name, data in TRIGRAMS.items():
+        if data["binary"] == binary:
+            return name
+    return None
+
+
+def get_trigrams_from_lines(lines: list[int]) -> tuple[str, str]:
+    """
+    从6个爻值中提取上下卦
+    下卦：初爻到三爻（lines[0:3]）
+    上卦：四爻到上爻（lines[3:6]）
+    """
+    binary = lines_to_binary(lines)
+
+    # 下卦：初爻(0)、二爻(1)、三爻(2)
+    lower_binary = binary[0:3]
+    # 上卦：四爻(3)、五爻(4)、上爻(5)
+    upper_binary = binary[3:6]
+
+    lower_name = binary_to_trigram_name(lower_binary)
+    upper_name = binary_to_trigram_name(upper_binary)
+
+    return upper_name, lower_name
+
+
+def get_changing_lines(lines: list[int]) -> list[int]:
+    """
+    获取动爻位置列表（1-indexed）
+    老阴(6)和老阳(9)为动爻
+    """
+    changing = []
+    for i, line in enumerate(lines):
+        if line in (6, 9):
+            changing.append(i + 1)  # 1-indexed: 1=初爻, 6=上爻
+    return changing
+
+
+def get_changed_lines(lines: list[int]) -> list[int]:
+    """
+    根据动爻计算变卦后的爻值
+    老阳(9) -> 少阴(8)：阳变阴
+    老阴(6) -> 少阳(7)：阴变阳
+    其余不变
+    """
+    changed = []
+    for line in lines:
+        if line == 9:
+            changed.append(8)  # 老阳变阴
+        elif line == 6:
+            changed.append(7)  # 老阴变阳
+        else:
+            changed.append(line)
+    return changed
+
+
+def get_changing_hexagram(lines: list[int]) -> dict | None:
+    """
+    根据动爻计算变卦
+    如果没有动爻则返回None
+    """
+    changing_lines = get_changing_lines(lines)
+    if not changing_lines:
+        return None
+
+    # 计算变卦的爻值
+    changed = get_changed_lines(lines)
+    # 获取变卦的上下卦
+    upper_name, lower_name = get_trigrams_from_lines(changed)
+    if not upper_name or not lower_name:
+        return None
+
+    # 查找变卦
+    number = lookup_hexagram_number(upper_name, lower_name)
+    if number is None:
+        return None
+
+    return get_hexagram_by_number(number)
+
+
+def lookup_hexagram(upper: str, lower: str) -> dict | None:
+    """
+    根据上下卦名查找64卦
+    """
+    number = lookup_hexagram_number(upper, lower)
+    if number is None:
+        return None
+    return get_hexagram_by_number(number)
+
+
+def perform_divination(question: str = "") -> dict:
+    """
+    执行完整的算卦流程
+    返回包含本卦、变卦、动爻等完整信息的结果字典
+    """
+    # 1. 摇卦得到6个爻值
+    lines = divine()
+
+    # 2. 获取上下卦名
+    upper_name, lower_name = get_trigrams_from_lines(lines)
+
+    # 3. 查找本卦
+    hexagram_number = lookup_hexagram_number(upper_name, lower_name)
+    hexagram_data = get_hexagram_by_number(hexagram_number)
+
+    # 4. 获取动爻
+    changing_lines = get_changing_lines(lines)
+
+    # 5. 获取变卦
+    changed_hexagram_data = get_changing_hexagram(lines)
+
+    # 6. 构建上下卦符号
+    upper_symbol = TRIGRAMS[upper_name]["symbol"]
+    lower_symbol = TRIGRAMS[lower_name]["symbol"]
+
+    # 7. 构建返回结果
+    result = {
+        "hexagram": {
+            "number": hexagram_data["number"],
+            "name": hexagram_data["name"],
+            "symbol": f"{upper_symbol}{lower_symbol}",
+            "lines": lines,
+            "upper_trigram": upper_name,
+            "lower_trigram": lower_name,
+        },
+        "judgment": hexagram_data["judgment"],
+        "interpretation": hexagram_data["image"],
+        "changing_lines": changing_lines,
+        "changed_hexagram": None,
+        "lines_text": hexagram_data["lines"],
+        "question": question,
+    }
+
+    # 8. 如果有变卦，添加变卦信息
+    if changed_hexagram_data:
+        changed_upper = changed_hexagram_data["upper_trigram"]
+        changed_lower = changed_hexagram_data["lower_trigram"]
+        changed_upper_symbol = TRIGRAMS[changed_upper]["symbol"]
+        changed_lower_symbol = TRIGRAMS[changed_lower]["symbol"]
+        result["changed_hexagram"] = {
+            "number": changed_hexagram_data["number"],
+            "name": changed_hexagram_data["name"],
+            "symbol": f"{changed_upper_symbol}{changed_lower_symbol}",
+        }
+
+    return result

backend/hexagrams_data.py

@@ -0,0 +1,1204 @@
+"""
+周易六十四卦完整数据
+包含八卦(三爻卦)和六十四卦(六爻卦)的所有信息
+卦辞、象辞、爻辞均采用周易原文
+"""
+
+# ============================================================
+# 八卦数据
+# ============================================================
+
+TRIGRAMS = {
+    "乾": {"symbol": "☰", "nature": "天", "binary": (1, 1, 1)},
+    "兑": {"symbol": "☱", "nature": "泽", "binary": (1, 1, 0)},
+    "离": {"symbol": "☲", "nature": "火", "binary": (1, 0, 1)},
+    "震": {"symbol": "☳", "nature": "雷", "binary": (1, 0, 0)},
+    "巽": {"symbol": "☴", "nature": "风", "binary": (0, 1, 1)},
+    "坎": {"symbol": "☵", "nature": "水", "binary": (0, 1, 0)},
+    "艮": {"symbol": "☶", "nature": "山", "binary": (0, 0, 1)},
+    "坤": {"symbol": "☷", "nature": "地", "binary": (0, 0, 0)},
+}
+
+# ============================================================
+# 六十四卦数据
+# 每卦包含: number, name, symbol, upper_trigram, lower_trigram,
+#           judgment(卦辞), image(象辞), lines(六爻爻辞)
+# 前8卦(乾坤屯蒙需讼师比)爻辞使用完整原文
+# 其余卦卦辞和象辞使用真实原文，爻辞适当简化
+# ============================================================
+
+HEXAGRAMS = [
+    # ---- 第1卦 乾为天 ----
+    {
+        "number": 1,
+        "name": "乾",
+        "symbol": "䷀",
+        "upper_trigram": "乾",
+        "lower_trigram": "乾",
+        "judgment": "乾。元亨利贞。",
+        "image": "天行健，君子以自强不息。",
+        "lines": [
+            "初九：潜龙勿用。",
+            "九二：见龙在田，利见大人。",
+            "九三：君子终日乾乾，夕惕若厉，无咎。",
+            "九四：或跃在渊，无咎。",
+            "九五：飞龙在天，利见大人。",
+            "上九：亢龙有悔。",
+        ],
+    },
+    # ---- 第2卦 坤为地 ----
+    {
+        "number": 2,
+        "name": "坤",
+        "symbol": "䷁",
+        "upper_trigram": "坤",
+        "lower_trigram": "坤",
+        "judgment": "坤。元亨，利牝马之贞。君子有攸往，先迷后得主，利。西南得朋，东北丧朋。安贞吉。",
+        "image": "地势坤，君子以厚德载物。",
+        "lines": [
+            "初六：履霜，坚冰至。",
+            "六二：直方大，不习无不利。",
+            "六三：含章可贞。或从王事，无成有终。",
+            "六四：括囊，无咎无誉。",
+            "六五：黄裳，元吉。",
+            "上六：龙战于野，其血玄黄。",
+        ],
+    },
+    # ---- 第3卦 水雷屯 ----
+    {
+        "number": 3,
+        "name": "屯",
+        "symbol": "䷂",
+        "upper_trigram": "坎",
+        "lower_trigram": "震",
+        "judgment": "屯。元亨利贞，勿用有攸往，利建侯。",
+        "image": "云雷屯，君子以经纶。",
+        "lines": [
+            "初九：磐桓，利居贞，利建侯。",
+            "六二：屯如邅如，乘马班如。匪寇婚媾，女子贞不字，十年乃字。",
+            "六三：即鹿无虞，惟入于林中，君子几不如舍，往吝。",
+            "六四：乘马班如，求婚媾，往吉，无不利。",
+            "九五：屯其膏，小贞吉，大贞凶。",
+            "上六：乘马班如，泣血涟如。",
+        ],
+    },
+    # ---- 第4卦 山水蒙 ----
+    {
+        "number": 4,
+        "name": "蒙",
+        "symbol": "䷃",
+        "upper_trigram": "艮",
+        "lower_trigram": "坎",
+        "judgment": "蒙。亨。匪我求童蒙，童蒙求我。初筮告，再三渎，渎则不告。利贞。",
+        "image": "山下出泉，蒙。君子以果行育德。",
+        "lines": [
+            "初六：发蒙，利用刑人，用说桎梏，以往吝。",
+            "九二：包蒙，吉。纳妇，吉。子克家。",
+            "六三：勿用取女，见金夫，不有躬，无攸利。",
+            "六四：困蒙，吝。",
+            "六五：童蒙，吉。",
+            "上九：击蒙，不利为寇，利御寇。",
+        ],
+    },
+    # ---- 第5卦 水天需 ----
+    {
+        "number": 5,
+        "name": "需",
+        "symbol": "䷄",
+        "upper_trigram": "坎",
+        "lower_trigram": "乾",
+        "judgment": "需。有孚，光亨，贞吉。利涉大川。",
+        "image": "云上于天，需。君子以饮食宴乐。",
+        "lines": [
+            "初九：需于郊，利用恒，无咎。",
+            "九二：需于沙，小有言，终吉。",
+            "九三：需于泥，致寇至。",
+            "六四：需于血，出自穴。",
+            "九五：需于酒食，贞吉。",
+            "上六：入于穴，有不速之客三人来，敬之终吉。",
+        ],
+    },
+    # ---- 第6卦 天水讼 ----
+    {
+        "number": 6,
+        "name": "讼",
+        "symbol": "䷅",
+        "upper_trigram": "��",
+        "lower_trigram": "坎",
+        "judgment": "讼。有孚窒惕，中吉，终凶。利见大人，不利涉大川。",
+        "image": "天与水违行，讼。君子以作事谋始。",
+        "lines": [
+            "初六：不永所事，小有言，终吉。",
+            "九二：不克讼，归而逋，其邑人三百户，无眚。",
+            "六三：食旧德，贞厉，终吉。或从王事，无成。",
+            "九四：不克讼，复即命渝，安贞吉。",
+            "九五：讼，元吉。",
+            "上九：或锡之鞶带，终朝三褫之。",
+        ],
+    },
+    # ---- 第7卦 地水师 ----
+    {
+        "number": 7,
+        "name": "师",
+        "symbol": "䷆",
+        "upper_trigram": "坤",
+        "lower_trigram": "坎",
+        "judgment": "师。贞，丈人吉，无咎。",
+        "image": "地中有水，师。君子以容民畜众。",
+        "lines": [
+            "初六：师出以律，否臧凶。",
+            "九二：在师中，吉，无咎，王三锡命。",
+            "六三：师或舆尸，凶。",
+            "六四：师左次，无咎。",
+            "六五：田有禽，利执言，无咎。长子帅师，弟子舆尸，贞凶。",
+            "上六：大君有命，开国承家，小人勿用。",
+        ],
+    },
+    # ---- 第8卦 水地比 ----
+    {
+        "number": 8,
+        "name": "比",
+        "symbol": "䷇",
+        "upper_trigram": "坎",
+        "lower_trigram": "坤",
+        "judgment": "比。吉。原筮元永贞，无咎。不宁方来，后夫凶。",
+        "image": "地上有水，比。先王以建万国，亲诸侯。",
+        "lines": [
+            "初六：有孚比之，无咎。有孚盈缶，终来有他，吉。",
+            "六二：比之自内，贞吉。",
+            "六三：比之匪人。",
+            "六四：外比之，贞吉。",
+            "九五：显比。王用三驱，失前禽。邑人不诫，吉。",
+            "上六：比之无首，凶。",
+        ],
+    },
+    # ---- 第9卦 风天小畜 ----
+    {
+        "number": 9,
+        "name": "小畜",
+        "symbol": "䷈",
+        "upper_trigram": "巽",
+        "lower_trigram": "乾",
+        "judgment": "小畜。亨。密云不雨，自我西郊。",
+        "image": "风行天上，小畜。君子以懿文德。",
+        "lines": [
+            "初九：复自道，何其咎，吉。",
+            "九二：牵复，吉。",
+            "九三：舆说辐，夫妻反目。",
+            "六四：有孚，血去惕出，无咎。",
+            "九五：有孚挛如，富以其邻。",
+            "上九：既雨既处，尚德载，妇贞厉。月几望，君子征凶。",
+        ],
+    },
+    # ---- 第10卦 天泽履 ----
+    {
+        "number": 10,
+        "name": "履",
+        "symbol": "䷉",
+        "upper_trigram": "乾",
+        "lower_trigram": "兑",
+        "judgment": "履虎尾，不咥人。亨。",
+        "image": "上天下泽，履。君子以辨上下，定民志。",
+        "lines": [
+            "初九：素履往，无咎。",
+            "九二：履道坦坦，幽人贞吉。",
+            "六三：眇能视，跛能履，履虎尾，咥人，凶。武人为于大君。",
+            "九四：履虎尾，愬愬，终吉。",
+            "九五：夬履，贞厉。",
+            "上九：视履考祥，其旋元吉。",
+        ],
+    },
+    # ---- 第11卦 地天泰 ----
+    {
+        "number": 11,
+        "name": "泰",
+        "symbol": "䷊",
+        "upper_trigram": "坤",
+        "lower_trigram": "乾",
+        "judgment": "泰。小往大来，吉亨。",
+        "image": "天地交，泰。后以财成天地之道，辅相天地之宜，以左右民。",
+        "lines": [
+            "初九：拔茅茹，以其汇，征吉。",
+            "九二：包荒，用冯河，不遐遗，朋亡，得尚于中行。",
+            "九三：无平不陂，无往不复，艰贞无咎。勿恤其孚，于食有福。",
+            "六四：翩翩，不富以其邻，不戒以孚。",
+            "六五：帝乙归妹，以祉元吉。",
+            "上六：城复于隍，勿用师。自邑告命，贞吝。",
+        ],
+    },
+    # ---- 第12卦 天地否 ----
+    {
+        "number": 12,
+        "name": "否",
+        "symbol": "䷋",
+        "upper_trigram": "乾",
+        "lower_trigram": "坤",
+        "judgment": "否之匪人，不利君子贞，大往小来。",
+        "image": "天地不交，否。君子以俭德辟难，不可荣以禄。",
+        "lines": [
+            "初六：拔茅茹，以其汇，贞吉，亨。",
+            "六二：包承，小人吉，大人否，亨。",
+            "六三：包羞。",
+            "九四：有命无咎，畴离祉。",
+            "九五：休否，大人吉。其亡其亡，系于苞桑。",
+            "上九：倾否，先否后喜。",
+        ],
+    },
+    # ---- 第13卦 天火同人 ----
+    {
+        "number": 13,
+        "name": "同人",
+        "symbol": "䷌",
+        "upper_trigram": "乾",
+        "lower_trigram": "离",
+        "judgment": "同人于野，亨。利涉大川，利君子贞。",
+        "image": "天与火，同人。君子以类族辨物。",
+        "lines": [
+            "初九：同人于门，无咎。",
+            "六二：同人于宗，吝。",
+            "九三：伏戎于莽，升其高陵，三岁不兴。",
+            "九四：乘其墉，弗克攻，吉。",
+            "九五：同人先号啕而后笑，大师克相遇。",
+            "上九：同人于郊，无悔。",
+        ],
+    },
+    # ---- 第14卦 火天大有 ----
+    {
+        "number": 14,
+        "name": "大有",
+        "symbol": "䷍",
+        "upper_trigram": "离",
+        "lower_trigram": "乾",
+        "judgment": "大有。元亨。",
+        "image": "火在天上，大有。君子以遏恶扬善，顺天休命。",
+        "lines": [
+            "初九：无交害，匪咎，艰则无咎。",
+            "九二：大车以载，有攸往，无咎。",
+            "九三：公用亨于天子，小人弗克。",
+            "九四：匪其彭，无咎。",
+            "六五：厥孚交如，威如，吉。",
+            "上九：自天祐之，吉无不利。",
+        ],
+    },
+    # ---- 第15卦 地山谦 ----
+    {
+        "number": 15,
+        "name": "谦",
+        "symbol": "䷎",
+        "upper_trigram": "坤",
+        "lower_trigram": "艮",
+        "judgment": "谦。亨，君子有终。",
+        "image": "地中有山，谦。君子以裒多益寡，称物平施。",
+        "lines": [
+            "初六：谦谦君子，用涉大川，吉。",
+            "六二：鸣谦，贞吉。",
+            "九三：劳谦，君子有终，吉。",
+            "六四：无不利，撝谦。",
+            "六五：不富以其邻，利用侵伐，无不利。",
+            "上六：鸣谦，利用行师，征邑国。",
+        ],
+    },
+    # ---- 第16卦 雷地豫 ----
+    {
+        "number": 16,
+        "name": "豫",
+        "symbol": "䷏",
+        "upper_trigram": "震",
+        "lower_trigram": "坤",
+        "judgment": "豫。利建侯行师。",
+        "image": "雷出地奋，豫。先王以作乐崇德，殷荐之上帝，以配祖考。",
+        "lines": [
+            "初六：鸣豫，凶。",
+            "六二：介于石，不终日，贞吉。",
+            "六三：盱豫，悔。迟有悔。",
+            "九四：由豫，大有得。勿疑，朋盍簪。",
+            "六五：贞疾，恒不死。",
+            "上六：冥豫，成有渝，无咎。",
+        ],
+    },
+    # ---- 第17卦 泽雷随 ----
+    {
+        "number": 17,
+        "name": "随",
+        "symbol": "䷐",
+        "upper_trigram": "兑",
+        "lower_trigram": "震",
+        "judgment": "随。元亨利贞，无咎。",
+        "image": "泽中有雷，随。君子以向晦入宴息。",
+        "lines": [
+            "初九：官有渝，贞吉。出门交有功。",
+            "六二：系小子，失丈夫。",
+            "六三：系丈夫，失小子。随有求得，利居贞。",
+            "九四：随有获，贞凶。有孚在道，以明，何咎。",
+            "九五：孚于嘉，吉。",
+            "上六：拘系之，乃从维之。王用亨于西山。",
+        ],
+    },
+    # ---- 第18卦 山风蛊 ----
+    {
+        "number": 18,
+        "name": "蛊",
+        "symbol": "䷑",
+        "upper_trigram": "艮",
+        "lower_trigram": "巽",
+        "judgment": "蛊。元亨，利涉大川。先甲三日，后甲三日。",
+        "image": "山下有风，蛊。君子以振民育德。",
+        "lines": [
+            "初六：干父之蛊，有子，考无咎，厉终吉。",
+            "九二：干母之蛊，不可贞。",
+            "九三：干父之蛊，小有悔，无大咎。",
+            "六四：裕父之蛊，往见吝。",
+            "六五：干父之蛊，用誉。",
+            "上九：不事王侯，高尚其事。",
+        ],
+    },
+    # ---- 第19卦 地泽临 ----
+    {
+        "number": 19,
+        "name": "临",
+        "symbol": "䷒",
+        "upper_trigram": "坤",
+        "lower_trigram": "兑",
+        "judgment": "临。元亨利贞。至于八月有凶。",
+        "image": "泽上有地，临。君子以教思无穷，容保民无疆。",
+        "lines": [
+            "初九：咸临，贞吉。",
+            "九二：咸临，吉，无不利。",
+            "六三：甘临，无攸利。既忧之，无咎。",
+            "六四：至临，无咎。",
+            "六五：知临，大君之宜，吉。",
+            "上六：敦临，吉，无咎。",
+        ],
+    },
+    # ---- 第20卦 风地观 ----
+    {
+        "number": 20,
+        "name": "观",
+        "symbol": "䷓",
+        "upper_trigram": "巽",
+        "lower_trigram": "坤",
+        "judgment": "观。盥而不荐，有孚颙若。",
+        "image": "风行地上，观。先王以省方观民设教。",
+        "lines": [
+            "初六：童观，小人无咎，君子吝。",
+            "六二：窥观，利女贞。",
+            "六三：观我生，进退。",
+            "六四：观国之光，利用宾于王。",
+            "九五：观我生，君子无咎。",
+            "上九：观其生，君子无咎。",
+        ],
+    },
+    # ---- 第21卦 火雷噬嗑 ----
+    {
+        "number": 21,
+        "name": "噬嗑",
+        "symbol": "䷔",
+        "upper_trigram": "离",
+        "lower_trigram": "震",
+        "judgment": "噬嗑。亨。利用狱。",
+        "image": "雷电噬嗑。先王以明罚敕法。",
+        "lines": [
+            "初九：屦校灭趾，无咎。",
+            "六二：噬肤灭鼻，无咎。",
+            "六三：噬腊肉，遇毒，小吝，无咎。",
+            "九四：噬干胏，得金矢，利艰贞，吉。",
+            "六五：噬干肉，得黄金，贞厉，无咎。",
+            "上九：何校灭耳，凶。",
+        ],
+    },
+    # ---- 第22卦 山火贲 ----
+    {
+        "number": 22,
+        "name": "贲",
+        "symbol": "䷕",
+        "upper_trigram": "艮",
+        "lower_trigram": "离",
+        "judgment": "贲。亨。小利有攸往。",
+        "image": "山下有火，贲。君子以明庶政，无敢折狱。",
+        "lines": [
+            "初九：贲其趾，舍车而徒。",
+            "六二：贲其须。",
+            "九三：贲如濡如，永贞吉。",
+            "六四：贲如皤如，白马翰如，匪寇婚媾。",
+            "六五：贲于丘园，束帛戋戋，吝，终吉。",
+            "上九：白贲，无咎。",
+        ],
+    },
+    # ---- 第23卦 山地剥 ----
+    {
+        "number": 23,
+        "name": "剥",
+        "symbol": "䷖",
+        "upper_trigram": "艮",
+        "lower_trigram": "坤",
+        "judgment": "剥。不利有攸往。",
+        "image": "山附于地，剥。上以厚下安宅。",
+        "lines": [
+            "初六：剥床以足，蔑贞凶。",
+            "六二：剥床以辨，蔑贞凶。",
+            "六三：剥之，无咎。",
+            "六四：剥床以肤，凶。",
+            "六五：贯鱼，以宫人宠，无不利。",
+            "上九：硕果不食，君子得舆，小人剥庐。",
+        ],
+    },
+    # ---- 第24卦 地雷复 ----
+    {
+        "number": 24,
+        "name": "复",
+        "symbol": "䷗",
+        "upper_trigram": "坤",
+        "lower_trigram": "震",
+        "judgment": "复。亨。出入无疾，朋来无咎。反复其道，七日来复，利有攸往。",
+        "image": "雷在地中，复。先王以至日闭关，商旅不行，后不省方。",
+        "lines": [
+            "初九：不远复，无祗悔，元吉。",
+            "六二：休复，吉。",
+            "六三：频复，厉，无咎。",
+            "六四：中行独复。",
+            "六五：敦复，无悔。",
+            "上六：迷复，凶，有灾眚。用行师，终有大败，以其国君凶，至于十年不克征。",
+        ],
+    },
+    # ---- 第25卦 天雷无妄 ----
+    {
+        "number": 25,
+        "name": "无妄",
+        "symbol": "䷘",
+        "upper_trigram": "乾",
+        "lower_trigram": "震",
+        "judgment": "无妄。元亨利贞。其匪正有眚，不利有攸往。",
+        "image": "天下雷行，物与无妄。先王以茂对时育万物。",
+        "lines": [
+            "初九：无妄，往吉。",
+            "六二：不耕获，不菑畲，则利有攸往。",
+            "六三：无妄之灾，或系之牛，行人之得，邑人之灾。",
+            "九四：可贞，无咎。",
+            "九五：无妄之疾，勿药有喜。",
+            "上九：无妄，行有眚，无攸利。",
+        ],
+    },
+    # ---- 第26卦 山天大畜 ----
+    {
+        "number": 26,
+        "name": "大畜",
+        "symbol": "䷙",
+        "upper_trigram": "艮",
+        "lower_trigram": "乾",
+        "judgment": "大畜。利贞，不家食吉，利涉大川。",
+        "image": "天在山中，大畜。君子以多识前言往行，以畜其德。",
+        "lines": [
+            "初九：有厉，利已。",
+            "九二：舆说辐。",
+            "九三：良马逐，利艰贞。曰闲舆卫，利有攸往。",
+            "六四：童牛之牿，元吉。",
+            "六五：豶豕之牙，吉。",
+            "上九：何天之衢，亨。",
+        ],
+    },
+    # ---- 第27卦 山雷颐 ----
+    {
+        "number": 27,
+        "name": "颐",
+        "symbol": "䷚",
+        "upper_trigram": "艮",
+        "lower_trigram": "震",
+        "judgment": "颐。贞吉。观颐，自求口实。",
+        "image": "山下有雷，颐。君子以慎言语，节饮食。",
+        "lines": [
+            "��九：舍尔灵龟，观我朵颐，凶。",
+            "六二：颠颐，拂经，于丘颐，征凶。",
+            "六三：拂颐，贞凶，十年勿用，无攸利。",
+            "六四：颠颐，吉。虎视眈眈，其欲逐逐，无咎。",
+            "六五：拂经，居贞吉，不可涉大川。",
+            "上九：由颐，厉吉，利涉大川。",
+        ],
+    },
+    # ---- 第28卦 泽风大过 ----
+    {
+        "number": 28,
+        "name": "大过",
+        "symbol": "䷛",
+        "upper_trigram": "兑",
+        "lower_trigram": "巽",
+        "judgment": "大过。栋桡，利有攸往，亨。",
+        "image": "泽灭木，大过。君子以独立不惧，遁世无闷。",
+        "lines": [
+            "初六：藉用白茅，无咎。",
+            "九二：枯杨生稊，老夫得其女妻，无不利。",
+            "九三：栋桡，凶。",
+            "九四：栋隆，吉。有它吝。",
+            "九五：枯杨生华，老妇得其士夫，无咎无誉。",
+            "上六：过涉灭顶，凶，无咎。",
+        ],
+    },
+    # ---- 第29卦 坎为水 ----
+    {
+        "number": 29,
+        "name": "坎",
+        "symbol": "䷜",
+        "upper_trigram": "坎",
+        "lower_trigram": "坎",
+        "judgment": "习坎。有孚，维心亨，行有尚。",
+        "image": "水洊至，习坎。君子以常德行，习教事。",
+        "lines": [
+            "初六：习坎，入于坎窞，凶。",
+            "九二：坎有险，求小得。",
+            "六三：来之坎坎，险且枕，入于坎窞，勿用。",
+            "六四：樽酒簋贰，用缶，纳约自牖，终无咎。",
+            "九五：坎不盈，祗既平，无咎。",
+            "上六：系用徽纆，寘于丛棘，三岁不得，凶。",
+        ],
+    },
+    # ---- 第30卦 离为火 ----
+    {
+        "number": 30,
+        "name": "离",
+        "symbol": "䷝",
+        "upper_trigram": "离",
+        "lower_trigram": "离",
+        "judgment": "离。利贞，亨。畜牝牛，吉。",
+        "image": "明两作，离。大人以继明照于四方。",
+        "lines": [
+            "初九：履错然，敬之无咎。",
+            "六二：黄离，元吉。",
+            "九三：日昃之离，不鼓缶而歌，则大耋之嗟，凶。",
+            "九四：突如其来如，焚如，死如，弃如。",
+            "六五：出涕沱若，戚嗟若，吉。",
+            "上九：王用出征，有嘉折首，获匪其丑，无咎。",
+        ],
+    },
+    # ---- 第31卦 泽山咸 ----
+    {
+        "number": 31,
+        "name": "咸",
+        "symbol": "䷞",
+        "upper_trigram": "兑",
+        "lower_trigram": "艮",
+        "judgment": "咸。亨，利贞，取女吉。",
+        "image": "山上有泽，咸。君子以虚受人。",
+        "lines": [
+            "初六：咸其拇。",
+            "六二：咸其腓，凶，居吉。",
+            "九三：咸其股，执其随，往吝。",
+            "九四：贞吉悔亡，憧憧往来，朋从尔思。",
+            "九五：咸其脢，无悔。",
+            "上六：咸其辅颊舌。",
+        ],
+    },
+    # ---- 第32卦 雷风恒 ----
+    {
+        "number": 32,
+        "name": "恒",
+        "symbol": "䷟",
+        "upper_trigram": "震",
+        "lower_trigram": "巽",
+        "judgment": "恒。亨，无咎，利贞，利有攸往。",
+        "image": "雷风，恒。君子以立不易方。",
+        "lines": [
+            "初六：浚恒，贞凶，无攸利。",
+            "九二：悔亡。",
+            "九三：不恒其德，或承之羞，贞吝。",
+            "九四：田无禽。",
+            "六五：恒其德，贞，妇人吉，夫子凶。",
+            "上六：振恒，凶。",
+        ],
+    },
+    # ---- 第33卦 天山遁 ----
+    {
+        "number": 33,
+        "name": "遁",
+        "symbol": "䷠",
+        "upper_trigram": "乾",
+        "lower_trigram": "艮",
+        "judgment": "遁。亨，小利贞。",
+        "image": "天下有山，遁。君子以远小人，不恶而严。",
+        "lines": [
+            "初六：遁尾，厉，勿用有攸往。",
+            "六二：执之用黄牛之革，莫之胜说。",
+            "九三：系遁，有疾厉，畜臣妾吉。",
+            "九四：好遁，君子吉，小人否。",
+            "九五：嘉遁，贞吉。",
+            "上九：肥遁，无不利。",
+        ],
+    },
+    # ---- 第34卦 雷天大壮 ----
+    {
+        "number": 34,
+        "name": "大壮",
+        "symbol": "䷡",
+        "upper_trigram": "震",
+        "lower_trigram": "乾",
+        "judgment": "大壮。利贞。",
+        "image": "雷在天上，大壮。君子以非礼弗履。",
+        "lines": [
+            "初九：壮于趾，征凶，有孚。",
+            "九二：贞吉。",
+            "九三：小人用壮，君子用罔，贞厉。羝羊触���，羸其角。",
+            "九四：贞吉悔亡，藩决不羸，壮于大舆之輹。",
+            "六五：丧羊于易，无悔。",
+            "上六：羝羊触藩，不能退，不能遂，无攸利，艰则吉。",
+        ],
+    },
+    # ---- 第35卦 火地晋 ----
+    {
+        "number": 35,
+        "name": "晋",
+        "symbol": "䷢",
+        "upper_trigram": "离",
+        "lower_trigram": "坤",
+        "judgment": "晋。康侯用锡马蕃庶，昼日三接。",
+        "image": "明出地上，晋。君子以自昭明德。",
+        "lines": [
+            "初六：晋如摧如，贞吉。罔孚，裕无咎。",
+            "六二：晋如愁如，贞吉。受兹介福，于其王母。",
+            "六三：众允，悔亡。",
+            "九四：晋如鼫鼠，贞厉。",
+            "六五：悔亡，失得勿恤，往吉，无不利。",
+            "上九：晋其角，维用伐邑，厉吉无咎，贞吝。",
+        ],
+    },
+    # ---- 第36卦 地火明夷 ----
+    {
+        "number": 36,
+        "name": "明夷",
+        "symbol": "䷣",
+        "upper_trigram": "坤",
+        "lower_trigram": "离",
+        "judgment": "明夷。利艰贞。",
+        "image": "明入地中，明夷。君子以莅众，用晦而明。",
+        "lines": [
+            "初九：明夷于飞，垂其翼。君子于行，三日不食。有攸往，主人有言。",
+            "六二：明夷，夷于左股，用拯马壮，吉。",
+            "九三：明夷于南狩，得其大首，不可疾贞。",
+            "六四：入于左腹，获明夷之心，于出门庭。",
+            "六五：箕子之明夷，利贞。",
+            "上六：不明晦，初登于天，后入于地。",
+        ],
+    },
+    # ---- 第37卦 风火家人 ----
+    {
+        "number": 37,
+        "name": "家人",
+        "symbol": "䷤",
+        "upper_trigram": "巽",
+        "lower_trigram": "离",
+        "judgment": "家人。利女贞。",
+        "image": "风自火出，家人。君子以言有物而行有恒。",
+        "lines": [
+            "初九：闲有家，悔亡。",
+            "六二：无攸遂，在中馈，贞吉。",
+            "九三：家人嗃嗃，悔厉吉。妇子嘻嘻，终吝。",
+            "六四：富家，大吉。",
+            "九五：王假有家，勿恤，吉。",
+            "上九：有孚威如，终吉。",
+        ],
+    },
+    # ---- 第38卦 火泽睽 ----
+    {
+        "number": 38,
+        "name": "睽",
+        "symbol": "䷥",
+        "upper_trigram": "离",
+        "lower_trigram": "兑",
+        "judgment": "睽。小事吉。",
+        "image": "上火下泽，睽。君子以同而异。",
+        "lines": [
+            "初九：悔亡，丧马勿逐，自复。见恶人，无咎。",
+            "九二：遇主于巷，无咎。",
+            "六三：见舆曳，其牛掣，其人天且劓，无初有终。",
+            "九四：睽孤，遇元夫，交孚，厉无咎。",
+            "六五：悔亡，厥宗噬肤，往何咎。",
+            "上九：睽孤，见豕负涂，载鬼一车，先张之弧，后说之弧，匪寇婚媾，往遇雨则吉。",
+        ],
+    },
+    # ---- 第39卦 水山蹇 ----
+    {
+        "number": 39,
+        "name": "蹇",
+        "symbol": "䷦",
+        "upper_trigram": "坎",
+        "lower_trigram": "艮",
+        "judgment": "蹇。利西南，不利东北。利见大人，贞吉。",
+        "image": "山上有水，蹇。君子以反身修德。",
+        "lines": [
+            "初六：往蹇，来誉。",
+            "六二：王臣蹇蹇，匪躬之故。",
+            "九三：往蹇来反。",
+            "六四：往蹇来连。",
+            "九五：大蹇朋来。",
+            "上六：往蹇来硕，吉。利见大人。",
+        ],
+    },
+    # ---- 第40卦 雷水解 ----
+    {
+        "number": 40,
+        "name": "解",
+        "symbol": "䷧",
+        "upper_trigram": "震",
+        "lower_trigram": "坎",
+        "judgment": "解。利西南，无所往，其来复吉。有攸往，夙吉。",
+        "image": "雷雨作，解。君子以赦过宥罪。",
+        "lines": [
+            "初六：无咎。",
+            "九二：田获三狐，得黄矢，贞吉。",
+            "六三：负且乘，致寇至，贞吝。",
+            "九四：解而拇，朋至斯孚。",
+            "六五：君子维有解，吉。有孚于小人。",
+            "上六：公用射隼于高墉之上，获之，无不利。",
+        ],
+    },
+    # ---- 第41卦 山泽损 ----
+    {
+        "number": 41,
+        "name": "损",
+        "symbol": "䷨",
+        "upper_trigram": "艮",
+        "lower_trigram": "兑",
+        "judgment": "损。有孚，元吉，无咎，可贞，利有攸往。曷之用，二簋可用享。",
+        "image": "山下有泽，损。君子以惩忿窒欲。",
+        "lines": [
+            "初九：已事遄往，无咎，酌损��。",
+            "九二：利贞，征凶，弗损益之。",
+            "六三：三人行则损一人，一人行则得其友。",
+            "六四：损其疾，使遄有喜，无咎。",
+            "六五：或益之十朋之龟，弗克违，元吉。",
+            "上九：弗损益之，无咎，贞吉，利有攸往，得臣无家。",
+        ],
+    },
+    # ---- 第42卦 风雷益 ----
+    {
+        "number": 42,
+        "name": "益",
+        "symbol": "䷩",
+        "upper_trigram": "巽",
+        "lower_trigram": "震",
+        "judgment": "益。利有攸往，利涉大川。",
+        "image": "风雷，益。君子以见善则迁，有过则改。",
+        "lines": [
+            "初九：利用为大作，元吉，无咎。",
+            "六二：或益之十朋之龟，弗克违，永贞吉。王用享于帝，吉。",
+            "六三：益之用凶事，无咎。有孚中行，告公用圭。",
+            "六四：中行，告公从。利用为依迁国。",
+            "九五：有孚惠心，勿问元吉。有孚惠我德。",
+            "上九：莫益之，或击之，立心勿恒，凶。",
+        ],
+    },
+    # ---- 第43卦 泽天夬 ----
+    {
+        "number": 43,
+        "name": "夬",
+        "symbol": "䷪",
+        "upper_trigram": "兑",
+        "lower_trigram": "乾",
+        "judgment": "夬。扬于王庭，孚号有厉。告自邑，不利即戎，利有攸往。",
+        "image": "泽上于天，夬。君子以施禄及下，居德则忌。",
+        "lines": [
+            "初九：壮于前趾，往不胜为咎。",
+            "九二：惕号，莫夜有戎，勿恤。",
+            "九三：壮于頄，有凶。君子夬夬，独行遇雨，若濡有愠，无咎。",
+            "九四：臀无肤，其行次且。牵羊悔亡，闻言不信。",
+            "九五：苋陆夬夬，中行无咎。",
+            "上六：无号，终有凶。",
+        ],
+    },
+    # ---- 第44卦 天风姤 ----
+    {
+        "number": 44,
+        "name": "姤",
+        "symbol": "䷫",
+        "upper_trigram": "乾",
+        "lower_trigram": "巽",
+        "judgment": "姤。女壮，勿用取女。",
+        "image": "天下有风，姤。后以施命诰四方。",
+        "lines": [
+            "初六：系于金柅，贞吉，有攸往，见凶，羸豕孚蹢躅。",
+            "九二：包有鱼，无咎，不利宾。",
+            "九三：臀无肤，其行次且，厉，无大咎。",
+            "九四：包无鱼，起凶。",
+            "九五：以杞包瓜，含章，有陨自天。",
+            "上九：姤其角，吝，无咎。",
+        ],
+    },
+    # ---- 第45卦 泽地萃 ----
+    {
+        "number": 45,
+        "name": "萃",
+        "symbol": "䷬",
+        "upper_trigram": "兑",
+        "lower_trigram": "坤",
+        "judgment": "萃。亨。王假有庙，利见大人，亨，利贞。用大牲吉，利有攸往。",
+        "image": "泽上于地，萃。君子以除戎器，戒不虞。",
+        "lines": [
+            "初六：有孚不终，乃乱乃萃，若号一握为笑，勿恤，往无咎。",
+            "六二：引吉，无咎，孚乃利用禴。",
+            "六三：萃如嗟如，无攸利，往无咎，小吝。",
+            "九四：大吉，无咎。",
+            "九五：萃有位，无咎。匪孚，元永贞，悔亡。",
+            "上六：赍咨涕洟，无咎。",
+        ],
+    },
+    # ---- 第46卦 地风升 ----
+    {
+        "number": 46,
+        "name": "升",
+        "symbol": "䷭",
+        "upper_trigram": "坤",
+        "lower_trigram": "巽",
+        "judgment": "升。元亨，用见大人，勿恤，南征吉。",
+        "image": "地中生木，升。君子以顺德，积小以高大。",
+        "lines": [
+            "初六：允升，大吉。",
+            "九二：孚乃利用禴，无咎。",
+            "九三：升虚邑。",
+            "六四：王用亨于岐山，吉，无咎。",
+            "六五：贞吉，升阶。",
+            "上六：冥升，利于不息之贞。",
+        ],
+    },
+    # ---- 第47卦 泽水困 ----
+    {
+        "number": 47,
+        "name": "困",
+        "symbol": "䷮",
+        "upper_trigram": "兑",
+        "lower_trigram": "坎",
+        "judgment": "困。亨，贞，大人吉，无咎，有言不信。",
+        "image": "泽无水，困。君子以致命遂志。",
+        "lines": [
+            "初六：臀困于株木，入于幽谷，三岁不觌。",
+            "九二：困于酒食，朱绂方来，利用享祀，征凶，无咎。",
+            "六三：困于石，据于蒺藜，入于其宫，不见其妻，凶。",
+            "九四：来徐徐，困于金车，吝，有终。",
+            "九五：劓刖，困于赤绂，乃徐有说，利用祭祀。",
+            "上六：困于葛藟，于臲卼，曰动悔。有悔，征吉。",
+        ],
+    },
+    # ---- 第48卦 水风井 ----
+    {
+        "number": 48,
+        "name": "井",
+        "symbol": "䷯",
+        "upper_trigram": "坎",
+        "lower_trigram": "巽",
+        "judgment": "井。改邑不改井，无丧无得，往来井井。汔至亦未繘井，羸其瓶，凶。",
+        "image": "木上有水，井。君子以劳民劝相。",
+        "lines": [
+            "初六：井泥不食，旧井无禽。",
+            "九二：井谷射鲋，瓮敝漏。",
+            "九三：井渫不食，为我心恻，可用汲，王明，并受其福。",
+            "六四：井甃，无咎。",
+            "九五：井洌，寒泉食。",
+            "上六：井收勿幕，有孚元吉。",
+        ],
+    },
+    # ---- 第49卦 泽火革 ----
+    {
+        "number": 49,
+        "name": "革",
+        "symbol": "䷰",
+        "upper_trigram": "兑",
+        "lower_trigram": "离",
+        "judgment": "革。巳日乃孚，元亨利贞，悔亡。",
+        "image": "泽中有火，革。君子以治历明时。",
+        "lines": [
+            "初九：巩用黄牛之革。",
+            "六二：巳日乃革之，征吉，无咎。",
+            "九三：征凶，贞厉，革言三就，有孚。",
+            "九四：悔亡，有孚改命，吉。",
+            "九五：大人虎变，未占有孚。",
+            "上六：君子豹变，小人革面，征凶，居贞吉。",
+        ],
+    },
+    # ---- 第50卦 火风鼎 ----
+    {
+        "number": 50,
+        "name": "鼎",
+        "symbol": "䷱",
+        "upper_trigram": "离",
+        "lower_trigram": "巽",
+        "judgment": "鼎。元吉，亨。",
+        "image": "木上有火，鼎。君子以正位凝命。",
+        "lines": [
+            "初六：鼎颠趾，利出否，得妾以其子，无咎。",
+            "九二：鼎有实，我仇有疾，不我能即，吉。",
+            "九三：鼎耳革，其行塞，雉膏不食，方雨亏悔，终吉。",
+            "九四：鼎折足，覆公餗，其形渥，凶。",
+            "六五：鼎黄耳金铉，利贞。",
+            "上九：鼎玉铉，大吉，无不利。",
+        ],
+    },
+    # ---- 第51卦 震为雷 ----
+    {
+        "number": 51,
+        "name": "震",
+        "symbol": "䷲",
+        "upper_trigram": "震",
+        "lower_trigram": "震",
+        "judgment": "震。亨。震来虩虩，笑言哑哑。震惊百里，不丧匕鬯。",
+        "image": "洊雷，震。君子以恐惧修省。",
+        "lines": [
+            "初九：震来虩虩，后笑言哑哑，吉。",
+            "六二：震来厉，亿丧贝，跻于九陵，勿逐，七日得。",
+            "六三：震苏苏，震行无眚。",
+            "九四：震遂泥。",
+            "六五：震往来厉，亿无丧，有事。",
+            "上六：震索索，视矍矍，征凶。震不于其躬，于其邻，无咎。婚媾有言。",
+        ],
+    },
+    # ---- 第52卦 艮为山 ----
+    {
+        "number": 52,
+        "name": "艮",
+        "symbol": "䷳",
+        "upper_trigram": "艮",
+        "lower_trigram": "艮",
+        "judgment": "艮其背，不获其身，行其庭，不见其人，无咎。",
+        "image": "兼山，艮。君子以思不出其位。",
+        "lines": [
+            "初六：艮其趾，无咎，利永贞。",
+            "六二：艮其腓，不拯其随，其心不快。",
+            "九三：艮其限，列其夤，厉薰心。",
+            "六四：艮其身，无咎。",
+            "六五：艮其辅，言有序，悔亡。",
+            "上九：敦艮，吉。",
+        ],
+    },
+    # ---- 第53卦 风山渐 ----
+    {
+        "number": 53,
+        "name": "渐",
+        "symbol": "䷴",
+        "upper_trigram": "巽",
+        "lower_trigram": "艮",
+        "judgment": "渐。女归吉，利贞。",
+        "image": "山上有木，渐。君子以居贤德善俗。",
+        "lines": [
+            "初六：鸿渐于干，小子厉，有言，无咎。",
+            "六二：鸿渐于磐，饮食衎衎，吉。",
+            "九三：鸿渐于陆，夫征不复，妇孕不育，凶。利御寇。",
+            "六四：鸿渐于木，或得其桷，无咎。",
+            "九五：鸿渐于陵，妇三岁不孕，终莫之胜，吉。",
+            "上九：鸿渐于陆，其羽可用为仪，吉。",
+        ],
+    },
+    # ---- 第54卦 雷泽归妹 ----
+    {
+        "number": 54,
+        "name": "归妹",
+        "symbol": "䷵",
+        "upper_trigram": "震",
+        "lower_trigram": "兑",
+        "judgment": "归妹。征凶，无攸利。",
+        "image": "泽上有雷，归妹。君子以永终知敝。",
+        "lines": [
+            "初九：归妹以娣，跛能履，征吉。",
+            "九二：眇能视，利幽人之贞。",
+            "六三：归妹以须，反归以娣。",
+            "九四：归妹愆期，迟归有时。",
+            "六五：帝乙归妹，其君之袂，不如其娣之袂良，月��望，吉。",
+            "上六：女承筐无实，士刲羊无血，无攸利。",
+        ],
+    },
+    # ---- 第55卦 雷火丰 ----
+    {
+        "number": 55,
+        "name": "丰",
+        "symbol": "䷶",
+        "upper_trigram": "震",
+        "lower_trigram": "离",
+        "judgment": "丰。亨，王假之，勿忧，宜日中。",
+        "image": "雷电皆至，丰。君子以折狱致刑。",
+        "lines": [
+            "初九：遇其配主，虽旬无咎，往有尚。",
+            "六二：丰其蔀，日中见斗，往得疑疾，有孚发若，吉。",
+            "九三：丰其沛，日中见沫，折其右肱，无咎。",
+            "九四：丰其蔀，日中见斗，遇其夷主，吉。",
+            "六五：来章，有庆誉，吉。",
+            "上六：丰其屋，蔀其家，窥其户，阒其无人，三岁不觌，凶。",
+        ],
+    },
+    # ---- 第56卦 火山旅 ----
+    {
+        "number": 56,
+        "name": "旅",
+        "symbol": "䷷",
+        "upper_trigram": "离",
+        "lower_trigram": "艮",
+        "judgment": "旅。小亨，旅贞吉。",
+        "image": "山上有火，旅。君子以明慎用刑而不留狱。",
+        "lines": [
+            "初六：旅琐琐，斯其所取灾。",
+            "六二：旅即次，怀其资，得童仆贞。",
+            "九三：旅焚其次，丧其童仆，贞厉。",
+            "九四：旅于处，得其资斧，我心不快。",
+            "六五：射雉一矢亡，终以誉命。",
+            "上九：鸟焚其巢，旅人先笑后号啕。丧牛于易，凶。",
+        ],
+    },
+    # ---- 第57卦 巽为风 ----
+    {
+        "number": 57,
+        "name": "巽",
+        "symbol": "䷸",
+        "upper_trigram": "巽",
+        "lower_trigram": "巽",
+        "judgment": "巽。小亨，利有攸往，利见大人。",
+        "image": "随风，巽。君子以申命行事。",
+        "lines": [
+            "初六：进退，利武人之贞。",
+            "九二：巽在床下，用史巫纷若，吉，无咎。",
+            "九三：频巽，吝。",
+            "六四：悔亡，田获三品。",
+            "九五：贞吉悔亡，无不利。无初有终，先庚三日，后庚三日，吉。",
+            "上九：巽在床下，丧其资斧，贞凶。",
+        ],
+    },
+    # ---- 第58卦 兑为泽 ----
+    {
+        "number": 58,
+        "name": "兑",
+        "symbol": "䷹",
+        "upper_trigram": "兑",
+        "lower_trigram": "兑",
+        "judgment": "兑。亨，利贞。",
+        "image": "丽泽，兑。君子以朋友讲习。",
+        "lines": [
+            "初九：和兑，吉。",
+            "九二：孚兑，吉，悔亡。",
+            "六三：来兑，凶。",
+            "九四：商兑未宁，介疾有喜。",
+            "九五：孚于剥，有厉。",
+            "上六：引兑。",
+        ],
+    },
+    # ---- 第59卦 风水涣 ----
+    {
+        "number": 59,
+        "name": "涣",
+        "symbol": "䷺",
+        "upper_trigram": "巽",
+        "lower_trigram": "坎",
+        "judgment": "涣。亨，王假有庙，利涉大川，利贞。",
+        "image": "风行水上，涣。先王以享于帝立庙。",
+        "lines": [
+            "初六：用拯马壮，吉。",
+            "九二：涣奔其机，悔亡。",
+            "六三：涣其躬，无悔。",
+            "六四：涣其群，元吉。涣有丘，匪夷所思。",
+            "九五：涣汗其大号，涣王居，无咎。",
+            "上九：涣其血，去逖出，无咎。",
+        ],
+    },
+    # ---- 第60卦 水泽节 ----
+    {
+        "number": 60,
+        "name": "节",
+        "symbol": "䷻",
+        "upper_trigram": "坎",
+        "lower_trigram": "兑",
+        "judgment": "节。亨。苦节不可贞。",
+        "image": "泽上有水，节。君子以制数度，议德行。",
+        "lines": [
+            "初九：不出户庭，无咎。",
+            "九二：不出门庭，凶。",
+            "六三：不节若，则嗟若，无咎。",
+            "六四：安节，亨。",
+            "九五：甘节，吉，往有尚。",
+            "上六：苦节，贞凶，悔亡。",
+        ],
+    },
+    # ---- 第61卦 风泽中孚 ----
+    {
+        "number": 61,
+        "name": "中孚",
+        "symbol": "䷼",
+        "upper_trigram": "巽",
+        "lower_trigram": "兑",
+        "judgment": "中孚。豚鱼吉，利涉大川，利贞。",
+        "image": "泽上有风，中孚。君子以议狱缓死。",
+        "lines": [
+            "初九：虞吉，有他不燕。",
+            "九二：鹤鸣在阴，其子和之。我有好爵，吾与尔靡之。",
+            "六三：得敌，或鼓或罢，或泣或歌。",
+            "六四：月几望，马匹亡，无咎。",
+            "九五：有孚挛如，无咎。",
+            "上九：翰音登于天，贞凶。",
+        ],
+    },
+    # ---- 第62卦 雷山小过 ----
+    {
+        "number": 62,
+        "name": "小过",
+        "symbol": "䷽",
+        "upper_trigram": "震",
+        "lower_trigram": "艮",
+        "judgment": "小过。亨，利贞，可小事，不可大事。飞鸟遗之音，不宜上，宜下，大吉。",
+        "image": "山上有雷，小过。君子以行过乎恭，丧过乎哀，用过乎俭。",
+        "lines": [
+            "初六：飞鸟以凶。",
+            "六二：过其祖，遇其妣；不及其君，遇其臣，无咎。",
+            "九三：弗过防之，从或戕之，凶。",
+            "九四：无咎，弗过遇之。往厉必戒，勿用永贞。",
+            "六五：密云不雨，自我西郊，公弋取彼在穴。",
+            "上六：弗遇过之，飞鸟离之，凶，是谓灾眚。",
+        ],
+    },
+    # ---- 第63卦 水火既济 ----
+    {
+        "number": 63,
+        "name": "既济",
+        "symbol": "䷾",
+        "upper_trigram": "坎",
+        "lower_trigram": "离",
+        "judgment": "既济。亨，小利贞，初吉终乱。",
+        "image": "水在火上，既济。君子以思患而预防之。",
+        "lines": [
+            "初九：曳其轮，濡其尾，无咎。",
+            "六二：妇丧其茀，勿逐，七日得。",
+            "九三：高宗伐鬼方，三年克之，小人勿用。",
+            "六四：繻有衣袽，终日戒。",
+            "九五：东邻杀牛，不如西邻之禴祭，实受其福。",
+            "上六：濡其首，厉。",
+        ],
+    },
+    # ---- 第64卦 火水未济 ----
+    {
+        "number": 64,
+        "name": "未济",
+        "symbol": "䷿",
+        "upper_trigram": "离",
+        "lower_trigram": "坎",
+        "judgment": "未济。亨，小狐汔济，濡其尾，无攸利。",
+        "image": "火在水上，未济。君子以慎辨物居方。",
+        "lines": [
+            "初六：濡其尾，吝。",
+            "九二：曳其轮，贞吉。",
+            "六三：未济，征凶，利涉大川。",
+            "九四：贞吉，悔亡，震用伐鬼方，三年有赏于大国。",
+            "六五：贞吉，无悔，君子之光，有孚，吉。",
+            "上九：有孚于饮酒，无咎，濡其首，有孚失是。",
+        ],
+    },
+]
+
+# ============================================================
+# 上下卦查找表：通过(上卦名, 下卦名)查找对应的64卦编号
+# ============================================================
+
+# 构建查找字典
+_HEXAGRAM_LOOKUP: dict[tuple[str, str], int] = {}
+for _h in HEXAGRAMS:
+    _HEXAGRAM_LOOKUP[(_h["upper_trigram"], _h["lower_trigram"])] = _h["number"]
+
+
+def lookup_hexagram_number(upper: str, lower: str) -> int | None:
+    """根据上下卦名查找64卦编号"""
+    return _HEXAGRAM_LOOKUP.get((upper, lower))
+
+
+def get_hexagram_by_number(number: int) -> dict | None:
+    """根据编号获取卦数据"""
+    if 1 <= number <= 64:
+        return HEXAGRAMS[number - 1]
+    return None

backend/main.py

@@ -0,0 +1,227 @@
+"""
+I-Ching FastAPI 后端应用
+
+提供以下接口：
+- POST /api/divine     — 算卦
+- GET  /api/hexagrams   — 获取64卦列表
+- GET  /api/hexagrams/{number} — 获取单卦详情
+"""
+
+import os
+import json
+from fastapi import FastAPI, HTTPException, WebSocket
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import FileResponse
+from pydantic import BaseModel
+from openai import AsyncOpenAI
+
+from .divination import perform_divination
+from .hexagrams_data import HEXAGRAMS, TRIGRAMS, get_hexagram_by_number
+
+# LLM 客户端（支持任何 OpenAI 兼容 API，通过环境变量配置）
+lm_client = AsyncOpenAI(
+    base_url=os.environ.get("LLM_BASE_URL", "http://localhost:1234/v1"),
+    api_key=os.environ.get("LLM_API_KEY", "lm-studio"),
+)
+
+# 创建 FastAPI 应用
+app = FastAPI(
+    title="I-Ching API",
+    description="基于铜钱法的周易六十四卦占卜系统",
+    version="1.0.0",
+)
+
+# 配置 CORS，允许前端跨域访问
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # 开发环境允许所有来源
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# ============================================================
+# 请求/响应模型
+# ============================================================
+
+
+class DivineRequest(BaseModel):
+    """算卦请求"""
+    question: str = ""
+
+
+# ============================================================
+# API 接口
+# ============================================================
+
+
+@app.post("/api/divine")
+async def divine(request: DivineRequest):
+    """
+    算卦接口
+    模拟铜钱法摇卦，返回本卦、变卦、爻辞等完整信息
+    """
+    result = perform_divination(question=request.question)
+    return result
+
+
+@app.get("/api/hexagrams")
+async def get_hexagrams():
+    """
+    获取64卦列表
+    返回每卦的编号、名称、符号和卦辞
+    """
+    return [
+        {
+            "number": h["number"],
+            "name": h["name"],
+            "symbol": h["symbol"],
+            "judgment": h["judgment"],
+        }
+        for h in HEXAGRAMS
+    ]
+
+
+@app.get("/api/hexagrams/{number}")
+async def get_hexagram(number: int):
+    """
+    获取单卦详情
+    返回指定编号卦的完整信息
+    """
+    if number < 1 or number > 64:
+        raise HTTPException(status_code=404, detail="卦序号必须在1-64之间")
+
+    hexagram = get_hexagram_by_number(number)
+    if hexagram is None:
+        raise HTTPException(status_code=404, detail="未找到该卦")
+
+    # 添加上下卦的符号信息
+    upper_symbol = TRIGRAMS[hexagram["upper_trigram"]]["symbol"]
+    lower_symbol = TRIGRAMS[hexagram["lower_trigram"]]["symbol"]
+
+    return {
+        **hexagram,
+        "trigram_symbol": f"{upper_symbol}{lower_symbol}",
+        "upper_trigram_info": TRIGRAMS[hexagram["upper_trigram"]],
+        "lower_trigram_info": TRIGRAMS[hexagram["lower_trigram"]],
+    }
+
+
+# ============================================================
+# AI 卦辞解读（WebSocket 长连接）
+# ============================================================
+
+
+def build_interpret_prompt(req: dict) -> str:
+    """根据卦象数据构建解读 prompt"""
+    changing_desc = ""
+    changing_lines = req.get("changing_lines", [])
+    lines_text = req.get("lines_text", [])
+    if changing_lines:
+        changing_texts = [lines_text[p - 1] for p in changing_lines if 1 <= p <= len(lines_text)]
+        changing_desc = f"\n动爻：{', '.join(changing_texts)}"
+        if req.get("changed_hexagram_name"):
+            changing_desc += f"\n变卦：{req['changed_hexagram_name']}"
+
+    question = (req.get("question") or "").strip()
+    name = req.get("hexagram_name", "")
+    number = req.get("hexagram_number", 0)
+    judgment = req.get("judgment", "")
+    image = req.get("image", "")
+
+    if question:
+        return f"""你是一位精通周易的国学大师。求问者带着具体的问题来求卦，你必须紧密围绕这个问题来解读卦象。
+
+【求问者的问题】：{question}
+
+【所得卦象】：第{number}卦 · {name}
+卦辞：{judgment}
+象辞：{image}{changing_desc}
+
+请用通俗易懂的现代中文解读此卦，要求：
+1. 开头点明此卦与「{question}」这个问题的关联
+2. 用卦辞和爻辞的含义，直接回应求问者关心的事情
+3. 给出与问题相关的具体行动建议
+4. 语气温和有智慧，像一位长者在指点迷津
+重点：你的每一段分析都要紧扣求问者的问题「{question}」，不要泛泛而谈。
+控制在200-350字以内。"""
+    else:
+        return f"""你是一位精通周易的国学大师，求问者未提出具体问题，请对所得卦象做综合运势解读。
+
+【所得卦象】：第{number}卦 · {name}
+卦辞：{judgment}
+象辞：{image}{changing_desc}
+
+请用通俗易懂的现代中文解读此卦，要求：
+1. 简要解释卦象的核心含义
+2. 从事业、人际、决策等方面给出综合提示
+3. 给出行动建议
+4. 语气温和有智慧，像一位长者在指点迷津
+控制在200-350字以内。"""
+
+
+@app.websocket("/ws/interpret")
+async def ws_interpret(websocket: WebSocket):
+    """WebSocket 端点：流式推送 AI 卦辞解读"""
+    await websocket.accept()
+    try:
+        raw = await websocket.receive_text()
+        request = json.loads(raw)
+        prompt = build_interpret_prompt(request)
+
+        # 通知前端进入思考阶段
+        await websocket.send_json({"type": "thinking"})
+
+        stream = await lm_client.chat.completions.create(
+            model=os.environ.get("LLM_MODEL", "google/gemma-4-26b-a4b"),
+            messages=[{"role": "user", "content": prompt}],
+            max_tokens=4096,
+            temperature=0.7,
+            stream=True,
+        )
+
+        async for chunk in stream:
+            if not chunk.choices:
+                continue
+            delta = chunk.choices[0].delta
+            # 只推送 content，跳过 reasoning_content
+            if delta.content:
+                await websocket.send_json({"type": "content", "text": delta.content})
+
+        await websocket.send_json({"type": "done"})
+    except Exception as e:
+        try:
+            await websocket.send_json({"type": "error", "text": str(e)})
+        except Exception:
+            pass
+    finally:
+        try:
+            await websocket.close()
+        except Exception:
+            pass
+
+
+# ============================================================
+# 静态文件服务（serve frontend/ 目录）
+# ============================================================
+
+# 获取项目根目录（backend 的上级目录）
+_backend_dir = os.path.dirname(os.path.abspath(__file__))
+_project_root = os.path.dirname(_backend_dir)
+_frontend_dir = os.path.join(_project_root, "frontend")
+
+
+@app.get("/")
+async def serve_index():
+    """返回前端首页"""
+    index_path = os.path.join(_frontend_dir, "index.html")
+    if os.path.exists(index_path):
+        return FileResponse(index_path)
+    return {"message": "I-Ching API 已启动。前端页面尚未部署。"}
+
+
+# 挂载静态文件目录（如果存在）
+if os.path.isdir(_frontend_dir):
+    app.mount("/", StaticFiles(directory=_frontend_dir, html=True), name="frontend")

backend/requirements.txt

@@ -0,0 +1,4 @@
+fastapi>=0.104.0
+uvicorn[standard]>=0.24.0
+pydantic>=2.0.0
+openai>=1.0.0

dev-doc/INTERFACE.md

@@ -0,0 +1,92 @@
+# I-Ching — 接口契约
+
+## 技术栈
+- Backend: Python FastAPI
+- Frontend: HTML + CSS + Vanilla JS (单页应用)
+- Test: pytest
+
+## API 接口
+
+### POST /api/divine
+发起一次算卦
+
+**Request Body:**
+```json
+{
+  "question": "string (可选，用户的问题)"
+}
+```
+
+**Response:**
+```json
+{
+  "hexagram": {
+    "number": 1,
+    "name": "乾",
+    "symbol": "☰☰",
+    "lines": [9, 9, 9, 9, 9, 9],
+    "upper_trigram": "乾",
+    "lower_trigram": "乾"
+  },
+  "judgment": "元亨利贞。",
+  "interpretation": "乾卦象征天...",
+  "changing_lines": [1, 3],
+  "changed_hexagram": {
+    "number": 44,
+    "name": "姤",
+    "symbol": "☰☴"
+  },
+  "lines_text": ["初九：潜龙勿用。", ...],
+  "question": "string"
+}
+```
+
+### GET /api/hexagrams
+获取64卦列表
+
+**Response:**
+```json
+[
+  {"number": 1, "name": "乾", "symbol": "䷀", "judgment": "元亨利贞。"},
+  ...
+]
+```
+
+### GET /api/hexagrams/{number}
+获取单个卦的详细信息
+
+## 数据模型
+
+```python
+@dataclass
+class Trigram:
+    name: str       # 乾/坤/震/巽/坎/离/艮/兑
+    symbol: str     # ☰☷☳☴☵☲☶☱
+    nature: str     # 天/地/雷/风/水/火/山/泽
+
+@dataclass
+class Hexagram:
+    number: int          # 1-64
+    name: str            # 卦名
+    symbol: str          # Unicode 卦符
+    upper_trigram: str   # 上卦
+    lower_trigram: str   # 下卦
+    judgment: str        # 卦辞
+    image: str           # 象辞
+    lines: list[str]     # 六爻爻辞
+
+@dataclass
+class DivinationResult:
+    hexagram: Hexagram
+    lines: list[int]           # 每爻的值 6/7/8/9
+    changing_lines: list[int]  # 动爻位置
+    changed_hexagram: Hexagram | None  # 变卦
+    question: str
+```
+
+## 铜钱摇卦算法
+- 模拟投掷三枚铜钱，6次
+- 正面(字)=3，反面(花)=2
+- 三枚之和: 6=老阴(变), 7=少阳, 8=少阴, 9=老阳(变)
+- 从初爻(底)到上爻(顶)依次排列
+- 老阴(6)和老阳(9)为动爻，会产生变卦

frontend/index.html

@@ -0,0 +1,1201 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>I-Ching · 周易算卦</title>
+<style>
+/* ========== 基础重置与全局样式 ========== */
+* { margin: 0; padding: 0; box-sizing: border-box; }
+
+:root {
+  --bg-dark: #0f0f1a;
+  --bg-card: #1a1a2e;
+  --bg-card-hover: #222240;
+  --gold: #d4a574;
+  --gold-light: #e8c89e;
+  --gold-dim: #a07850;
+  --red: #c0392b;
+  --red-light: #e74c3c;
+  --text: #e0d5c1;
+  --text-dim: #8a8070;
+  --border: #3a3a5e;
+}
+
+body {
+  background: var(--bg-dark);
+  color: var(--text);
+  font-family: "Noto Serif SC", "Songti SC", "SimSun", "STSong", serif;
+  min-height: 100vh;
+  line-height: 1.8;
+}
+
+/* ========== 背景装饰 ========== */
+body::before {
+  content: "";
+  position: fixed;
+  top: 0; left: 0; right: 0; bottom: 0;
+  background:
+    radial-gradient(ellipse at 20% 20%, rgba(212,165,116,0.03) 0%, transparent 50%),
+    radial-gradient(ellipse at 80% 80%, rgba(192,57,43,0.03) 0%, transparent 50%);
+  pointer-events: none;
+  z-index: 0;
+}
+
+.container {
+  max-width: 800px;
+  margin: 0 auto;
+  padding: 20px 16px 60px;
+  position: relative;
+  z-index: 1;
+}
+
+/* ========== 标题区 ========== */
+.header {
+  text-align: center;
+  padding: 40px 0 30px;
+}
+
+.taiji {
+  width: 80px;
+  height: 80px;
+  margin: 0 auto 20px;
+  animation: spin 20s linear infinite;
+}
+
+@keyframes spin {
+  to { transform: rotate(360deg); }
+}
+
+.header h1 {
+  font-size: 2.6em;
+  color: var(--gold);
+  letter-spacing: 0.3em;
+  text-shadow: 0 0 20px rgba(212,165,116,0.3);
+  margin-bottom: 8px;
+}
+
+.header .subtitle {
+  color: var(--text-dim);
+  font-size: 0.95em;
+  letter-spacing: 0.15em;
+}
+
+/* ========== 问卦区 ========== */
+.divine-section {
+  background: var(--bg-card);
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  padding: 30px;
+  margin: 20px 0;
+  text-align: center;
+}
+
+.divine-section label {
+  display: block;
+  color: var(--gold);
+  font-size: 1.1em;
+  margin-bottom: 12px;
+  letter-spacing: 0.1em;
+}
+
+.divine-section textarea {
+  width: 100%;
+  background: rgba(255,255,255,0.04);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  color: var(--text);
+  font-family: inherit;
+  font-size: 1em;
+  padding: 12px 16px;
+  resize: vertical;
+  min-height: 60px;
+  max-height: 150px;
+  transition: border-color 0.3s;
+}
+
+.divine-section textarea:focus {
+  outline: none;
+  border-color: var(--gold-dim);
+}
+
+.divine-section textarea::placeholder {
+  color: var(--text-dim);
+}
+
+.btn-divine {
+  display: inline-block;
+  margin-top: 20px;
+  padding: 14px 50px;
+  background: linear-gradient(135deg, var(--gold-dim), var(--gold));
+  color: var(--bg-dark);
+  font-family: inherit;
+  font-size: 1.2em;
+  font-weight: bold;
+  letter-spacing: 0.2em;
+  border: none;
+  border-radius: 50px;
+  cursor: pointer;
+  transition: all 0.3s;
+  position: relative;
+  overflow: hidden;
+}
+
+.btn-divine:hover:not(:disabled) {
+  transform: translateY(-2px);
+  box-shadow: 0 6px 25px rgba(212,165,116,0.3);
+}
+
+.btn-divine:disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
+/* ========== 摇卦动画区 ========== */
+.coin-area {
+  display: none;
+  text-align: center;
+  padding: 30px 0;
+}
+
+.coin-area.active { display: block; }
+
+.coin-round-label {
+  color: var(--gold);
+  font-size: 1em;
+  margin-bottom: 16px;
+  letter-spacing: 0.1em;
+}
+
+.coin-detail {
+  color: var(--text);
+  font-size: 0.85em;
+  margin-bottom: 12px;
+  opacity: 0.8;
+  min-height: 1.2em;
+}
+
+.coins-row {
+  display: flex;
+  justify-content: center;
+  gap: 30px;
+  margin-bottom: 10px;
+}
+
+/* 铜钱样式 */
+.coin {
+  width: 70px;
+  height: 70px;
+  perspective: 300px;
+}
+
+.coin-inner {
+  width: 100%;
+  height: 100%;
+  position: relative;
+  transform-style: preserve-3d;
+  border-radius: 50%;
+}
+
+.coin-inner.flipping-front {
+  animation: coinFlipFront 0.6s ease-in-out forwards;
+}
+
+.coin-inner.flipping-back {
+  animation: coinFlipBack 0.6s ease-in-out forwards;
+}
+
+/* 落在正面（字）：偶数圈 */
+@keyframes coinFlipFront {
+  0%   { transform: rotateY(0deg); }
+  50%  { transform: rotateY(900deg) scale(1.1); }
+  100% { transform: rotateY(1800deg); }
+}
+
+/* 落在反面（花）：多半圈 */
+@keyframes coinFlipBack {
+  0%   { transform: rotateY(0deg); }
+  50%  { transform: rotateY(900deg) scale(1.1); }
+  100% { transform: rotateY(1980deg); }
+}
+
+.coin-face {
+  position: absolute;
+  width: 100%;
+  height: 100%;
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 1.1em;
+  font-weight: bold;
+  backface-visibility: hidden;
+  border: 3px solid var(--gold);
+  background: radial-gradient(circle at 35% 35%, #c9a96e, #8a6914);
+  color: var(--bg-dark);
+  box-shadow: 0 2px 10px rgba(0,0,0,0.4), inset 0 1px 3px rgba(255,255,255,0.2);
+}
+
+.coin-face.back {
+  transform: rotateY(180deg);
+  background: radial-gradient(circle at 35% 35%, #b8923e, #6b5010);
+}
+
+/* 铜钱中间方孔 */
+.coin-face::after {
+  content: "";
+  position: absolute;
+  width: 16px;
+  height: 16px;
+  border: 2px solid var(--bg-dark);
+  background: rgba(15,15,26,0.6);
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+}
+
+.coin-face.front::after { display: none; }
+
+.coin-face.front {
+  font-size: 1.6em;
+}
+
+/* ========== 结果展示区 ========== */
+.result-section {
+  display: none;
+  margin-top: 20px;
+}
+
+.result-section.active { display: block; }
+
+.result-card {
+  background: var(--bg-card);
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  padding: 30px;
+  margin-bottom: 20px;
+  opacity: 0;
+  transform: translateY(20px);
+  transition: opacity 0.6s, transform 0.6s;
+}
+
+.result-card.visible {
+  opacity: 1;
+  transform: translateY(0);
+}
+
+.result-card h3 {
+  color: var(--gold);
+  font-size: 1.2em;
+  margin-bottom: 16px;
+  padding-bottom: 8px;
+  border-bottom: 1px solid var(--border);
+  letter-spacing: 0.1em;
+}
+
+/* 卦象图形 */
+.hexagram-display {
+  text-align: center;
+  padding: 20px 0;
+}
+
+.hex-name {
+  font-size: 2em;
+  color: var(--gold);
+  margin-bottom: 4px;
+}
+
+.hex-symbol {
+  font-size: 3.5em;
+  line-height: 1;
+  margin-bottom: 10px;
+}
+
+.hex-trigrams {
+  color: var(--text-dim);
+  font-size: 0.95em;
+  margin-bottom: 20px;
+}
+
+.lines-display {
+  display: inline-block;
+  text-align: center;
+}
+
+.line-row {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  margin: 6px 0;
+  opacity: 0;
+  transition: opacity 0.4s;
+}
+
+.line-row.visible { opacity: 1; }
+
+.line-label {
+  width: 40px;
+  text-align: right;
+  font-size: 0.8em;
+  color: var(--text-dim);
+  margin-right: 12px;
+}
+
+.line-graphic {
+  font-size: 1.4em;
+  letter-spacing: 2px;
+  font-weight: bold;
+  color: var(--gold);
+}
+
+.line-graphic.changing {
+  color: var(--red-light);
+  text-shadow: 0 0 8px rgba(231,76,60,0.4);
+}
+
+.line-value {
+  width: 36px;
+  text-align: left;
+  margin-left: 12px;
+  font-size: 0.8em;
+  color: var(--text-dim);
+}
+
+/* 变卦箭头 */
+.change-arrow {
+  text-align: center;
+  font-size: 2em;
+  color: var(--gold);
+  margin: 10px 0;
+  letter-spacing: 0.1em;
+}
+
+/* 卦辞爻辞 */
+.judgment-text {
+  font-size: 1.15em;
+  line-height: 2;
+  color: var(--text);
+  padding: 10px 0;
+}
+
+.lines-text-list {
+  list-style: none;
+  padding: 0;
+}
+
+.lines-text-list li {
+  padding: 8px 0;
+  border-bottom: 1px dashed rgba(58,58,94,0.5);
+  font-size: 0.95em;
+  line-height: 1.8;
+}
+
+.lines-text-list li:last-child { border-bottom: none; }
+
+.lines-text-list li.changing-line {
+  color: var(--red-light);
+  font-weight: bold;
+}
+
+.interpretation-text {
+  font-size: 1em;
+  line-height: 2;
+  color: var(--text);
+}
+.interpretation-text.typing::after {
+  content: '▍';
+  color: var(--gold);
+  animation: blink 1s step-end infinite;
+}
+.interpretation-text.thinking {
+  animation: thinkingPulse 2s ease-in-out infinite;
+}
+@keyframes blink {
+  50% { opacity: 0; }
+}
+@keyframes thinkingPulse {
+  0%, 100% { opacity: 0.5; }
+  50% { opacity: 1; }
+}
+
+/* ========== 64卦速查表 ========== */
+.lookup-section {
+  margin-top: 40px;
+}
+
+.lookup-toggle {
+  width: 100%;
+  background: var(--bg-card);
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  padding: 16px 24px;
+  color: var(--gold);
+  font-family: inherit;
+  font-size: 1.1em;
+  cursor: pointer;
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  transition: background 0.3s;
+  letter-spacing: 0.1em;
+}
+
+.lookup-toggle:hover { background: var(--bg-card-hover); }
+
+.lookup-toggle .arrow {
+  transition: transform 0.3s;
+  font-size: 0.8em;
+}
+
+.lookup-toggle.open .arrow {
+  transform: rotate(180deg);
+}
+
+.lookup-grid {
+  display: none;
+  grid-template-columns: repeat(auto-fill, minmax(110px, 1fr));
+  gap: 8px;
+  padding: 16px 0;
+}
+
+.lookup-grid.open {
+  display: grid;
+}
+
+.hex-card {
+  background: var(--bg-card);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  padding: 12px 8px;
+  text-align: center;
+  cursor: pointer;
+  transition: all 0.2s;
+}
+
+.hex-card:hover {
+  background: var(--bg-card-hover);
+  border-color: var(--gold-dim);
+  transform: translateY(-2px);
+}
+
+.hex-card .card-symbol {
+  font-size: 1.8em;
+  display: block;
+  margin-bottom: 4px;
+}
+
+.hex-card .card-name {
+  font-size: 0.85em;
+  color: var(--gold);
+}
+
+.hex-card .card-num {
+  font-size: 0.7em;
+  color: var(--text-dim);
+}
+
+/* 卦详情模态 */
+.modal-overlay {
+  display: none;
+  position: fixed;
+  top: 0; left: 0; right: 0; bottom: 0;
+  background: rgba(0,0,0,0.7);
+  z-index: 100;
+  align-items: center;
+  justify-content: center;
+  padding: 20px;
+}
+
+.modal-overlay.active {
+  display: flex;
+}
+
+.modal-content {
+  background: var(--bg-card);
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  padding: 30px;
+  max-width: 600px;
+  width: 100%;
+  max-height: 80vh;
+  overflow-y: auto;
+  position: relative;
+}
+
+.modal-close {
+  position: absolute;
+  top: 12px;
+  right: 16px;
+  background: none;
+  border: none;
+  color: var(--text-dim);
+  font-size: 1.8em;
+  cursor: pointer;
+  line-height: 1;
+}
+
+.modal-close:hover { color: var(--text); }
+
+.modal-content h2 {
+  color: var(--gold);
+  font-size: 1.6em;
+  margin-bottom: 6px;
+}
+
+.modal-content .modal-symbol {
+  font-size: 3em;
+  text-align: center;
+  margin: 10px 0;
+}
+
+.modal-content .modal-meta {
+  color: var(--text-dim);
+  font-size: 0.9em;
+  margin-bottom: 16px;
+  text-align: center;
+}
+
+.modal-content h4 {
+  color: var(--gold);
+  margin: 16px 0 8px;
+  font-size: 1em;
+}
+
+.modal-content p, .modal-content li {
+  font-size: 0.95em;
+  line-height: 1.8;
+}
+
+.modal-content ul {
+  list-style: none;
+  padding: 0;
+}
+
+.modal-content ul li {
+  padding: 4px 0;
+  border-bottom: 1px dashed rgba(58,58,94,0.4);
+}
+
+/* ========== 加载与错误提示 ========== */
+.loading {
+  text-align: center;
+  padding: 20px;
+  color: var(--text-dim);
+}
+
+.error-msg {
+  background: rgba(192,57,43,0.15);
+  border: 1px solid var(--red);
+  border-radius: 8px;
+  padding: 14px 20px;
+  color: var(--red-light);
+  margin: 16px 0;
+  display: none;
+}
+
+.error-msg.active { display: block; }
+
+/* ========== 响应式 ========== */
+@media (max-width: 600px) {
+  .container { padding: 12px 10px 40px; }
+  .header h1 { font-size: 1.8em; letter-spacing: 0.15em; }
+  .divine-section { padding: 20px 16px; }
+  .btn-divine { padding: 12px 36px; font-size: 1.05em; }
+  .coins-row { gap: 18px; }
+  .coin { width: 56px; height: 56px; }
+  .result-card { padding: 20px 16px; }
+  .lookup-grid { grid-template-columns: repeat(auto-fill, minmax(90px, 1fr)); }
+  .hex-name { font-size: 1.5em; }
+  .hex-symbol { font-size: 2.5em; }
+}
+</style>
+</head>
+<body>
+
+<div class="container">
+
+  <!-- 标题区 -->
+  <div class="header">
+    <!-- 太极图 SVG -->
+    <svg class="taiji" viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
+      <circle cx="50" cy="50" r="49" fill="none" stroke="#d4a574" stroke-width="1.5"/>
+      <path d="M50,1 A49,49 0 0,1 50,99 A24.5,24.5 0 0,1 50,50 A24.5,24.5 0 0,0 50,1 Z" fill="#d4a574"/>
+      <path d="M50,1 A49,49 0 0,0 50,99 A24.5,24.5 0 0,0 50,50 A24.5,24.5 0 0,1 50,1 Z" fill="#1a1a2e"/>
+      <circle cx="50" cy="25.5" r="6" fill="#1a1a2e"/>
+      <circle cx="50" cy="74.5" r="6" fill="#d4a574"/>
+    </svg>
+    <h1>周易算卦</h1>
+    <p class="subtitle">诚心问卦 · 天机自现</p>
+  </div>
+
+  <!-- 问卦区 -->
+  <div class="divine-section">
+    <label for="question">心中所惑，诚心写下（可不填）</label>
+    <textarea id="question" placeholder="例如：近期事业运势如何？" rows="2" onkeydown="if(event.key==='Enter'&&!event.shiftKey){event.preventDefault();startDivine();}"></textarea>
+    <br>
+    <button class="btn-divine" id="btnDivine" onclick="startDivine()">摇 卦</button>
+  </div>
+
+  <!-- 错误提示 -->
+  <div class="error-msg" id="errorMsg"></div>
+
+  <!-- 摇卦动画区 -->
+  <div class="coin-area" id="coinArea">
+    <div class="coin-round-label" id="coinRoundLabel">第 1 爻 · 摇卦中...</div>
+    <div class="coin-detail" id="coinDetail"></div>
+    <div class="coins-row">
+      <div class="coin"><div class="coin-inner" id="coin1"><div class="coin-face front">字</div><div class="coin-face back">花</div></div></div>
+      <div class="coin"><div class="coin-inner" id="coin2"><div class="coin-face front">字</div><div class="coin-face back">花</div></div></div>
+      <div class="coin"><div class="coin-inner" id="coin3"><div class="coin-face front">字</div><div class="coin-face back">花</div></div></div>
+    </div>
+  </div>
+
+  <!-- 结果展示区 -->
+  <div class="result-section" id="resultSection">
+    <!-- 卦象卡片 -->
+    <div class="result-card" id="cardHexagram">
+      <h3>卦 象</h3>
+      <div class="hexagram-display" id="hexDisplay"></div>
+    </div>
+
+    <!-- 变卦 -->
+    <div class="result-card" id="cardChanged" style="display:none;">
+      <h3>变 卦</h3>
+      <div class="hexagram-display" id="changedDisplay"></div>
+    </div>
+
+    <!-- 卦辞 -->
+    <div class="result-card" id="cardJudgment">
+      <h3>卦 辞</h3>
+      <div class="judgment-text" id="judgmentText"></div>
+    </div>
+
+    <!-- 爻辞 -->
+    <div class="result-card" id="cardLines">
+      <h3>爻 辞</h3>
+      <ul class="lines-text-list" id="linesTextList"></ul>
+    </div>
+
+    <!-- 解读 -->
+    <div class="result-card" id="cardInterp">
+      <h3>卦象解读</h3>
+      <div class="interpretation-text" id="interpText"></div>
+    </div>
+  </div>
+
+  <!-- 64卦速查表 -->
+  <div class="lookup-section">
+    <button class="lookup-toggle" id="lookupToggle" onclick="toggleLookup()">
+      <span>六十四卦速查</span>
+      <span class="arrow">▼</span>
+    </button>
+    <div class="lookup-grid" id="lookupGrid"></div>
+  </div>
+</div>
+
+<!-- 详情模态 -->
+<div class="modal-overlay" id="modal" onclick="closeModalOutside(event)">
+  <div class="modal-content" id="modalContent">
+    <button class="modal-close" onclick="closeModal()">&times;</button>
+    <div id="modalBody"></div>
+  </div>
+</div>
+
+<script>
+/* ========== 全局状态 ========== */
+const API_BASE = window.location.origin;
+let isDivining = false;
+let hexagramsCache = null;
+
+/* ========== 工具函数 ========== */
+
+/** 显示错误信息 */
+function showError(msg) {
+  const el = document.getElementById('errorMsg');
+  el.textContent = msg;
+  el.classList.add('active');
+  setTimeout(function() { el.classList.remove('active'); }, 5000);
+}
+
+/** 安全地创建文本节点 */
+function txt(str) {
+  return document.createTextNode(str || '');
+}
+
+/** 创建元素并设置属性和文本 */
+function el(tag, attrs, textContent) {
+  var e = document.createElement(tag);
+  if (attrs) {
+    Object.keys(attrs).forEach(function(k) {
+      if (k === 'className') e.className = attrs[k];
+      else if (k === 'style') e.style.cssText = attrs[k];
+      else e.setAttribute(k, attrs[k]);
+    });
+  }
+  if (textContent !== undefined) e.textContent = textContent;
+  return e;
+}
+
+/** 根据爻值返回图形文字 */
+function lineGraphic(val) {
+  // 7=少阳, 9=老阳 -> 阳爻; 8=少阴, 6=老阴 -> 阴爻
+  if (val === 7 || val === 9) return '\u2584\u2584\u2584\u2584\u2584\u2584\u2584\u2584\u2584';
+  return '\u2584\u2584\u2584\u2584\u3000\u2584\u2584\u2584\u2584';
+}
+
+/** 判断是否为动爻 */
+function isChanging(val) {
+  return val === 6 || val === 9;
+}
+
+/** 爻位名称 */
+var LINE_NAMES = ['初', '二', '三', '四', '五', '上'];
+
+/** 清除子元素 */
+function clearChildren(parent) {
+  while (parent.firstChild) parent.removeChild(parent.firstChild);
+}
+
+/* ========== 摇卦主流程 ========== */
+
+async function startDivine() {
+  if (isDivining) return;
+  isDivining = true;
+
+  var btn = document.getElementById('btnDivine');
+  var coinArea = document.getElementById('coinArea');
+  var resultSection = document.getElementById('resultSection');
+  var question = document.getElementById('question').value.trim();
+
+  // 重置之前的结果
+  resetResultCards();
+
+  btn.disabled = true;
+  btn.textContent = '摇卦中...';
+  resultSection.classList.remove('active');
+
+  // 先调用后端获取结果，再用结果驱动铜钱动画
+  try {
+    var resp = await fetch(API_BASE + '/api/divine', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ question: question || undefined })
+    });
+
+    if (!resp.ok) throw new Error('\u8BF7\u6C42\u5931\u8D25 (' + resp.status + ')');
+    var data = await resp.json();
+    var lines = data.hexagram.lines; // [6/7/8/9, ...]
+
+    // 用实际爻值驱动6轮铜钱动画
+    coinArea.classList.add('active');
+    var detailEl = document.getElementById('coinDetail');
+    for (var i = 0; i < 6; i++) {
+      var lineVal = lines[i];
+      var headsCount = lineVal - 6; // 字的个数
+      var tailsCount = 3 - headsCount; // 花的个数
+      var coinDesc = headsCount + '字' + tailsCount + '花';
+      var lineType = lineVal === 6 ? '老阴（变）' : lineVal === 7 ? '少阳' :
+                     lineVal === 8 ? '少阴' : '老阳（变）';
+      var yinYang = (lineVal === 7 || lineVal === 9) ? '▬▬▬ 阳爻' : '▬ ▬ 阴爻';
+
+      document.getElementById('coinRoundLabel').textContent =
+        '\u7B2C ' + (i + 1) + ' \u723B \u00B7 \u6447\u5366\u4E2D...';
+      detailEl.textContent = '';
+      await flipCoinsWithResult(lineVal);
+      // 显示本爻结果和计算过程
+      document.getElementById('coinRoundLabel').textContent =
+        '\u7B2C ' + (i + 1) + ' \u723B';
+      detailEl.textContent = coinDesc + ' = ' + lineVal + ' = ' + lineType + ' ' + yinYang;
+      await sleep(800);
+    }
+    detailEl.textContent = '';
+    coinArea.classList.remove('active');
+
+    await showResult(data);
+  } catch (e) {
+    coinArea.classList.remove('active');
+    showError('\u7B97\u5366\u5931\u8D25\uFF1A' + e.message + '\u3002\u8BF7\u68C0\u67E5\u540E\u7AEF\u670D\u52A1\u662F\u5426\u542F\u52A8\u3002');
+  }
+
+  btn.disabled = false;
+  btn.textContent = '\u6447 \u5366';
+  isDivining = false;
+}
+
+/** 重置所有结果卡片状态 */
+function resetResultCards() {
+  var cards = ['cardHexagram', 'cardChanged', 'cardJudgment', 'cardLines', 'cardInterp'];
+  cards.forEach(function(id) {
+    document.getElementById(id).classList.remove('visible');
+  });
+  clearChildren(document.getElementById('hexDisplay'));
+  clearChildren(document.getElementById('changedDisplay'));
+  document.getElementById('judgmentText').textContent = '';
+  clearChildren(document.getElementById('linesTextList'));
+  document.getElementById('interpText').textContent = '';
+}
+
+/** 单轮铜钱翻转动画 */
+/**
+ * 根据爻值确定三枚铜钱的正反面
+ * 字(正面)=3, 花(反面)=2
+ * 6=花花花, 7=字花花, 8=字字花, 9=字字字
+ */
+function getCoinsForLine(lineVal) {
+  // heads 数量: 6→0, 7→1, 8→2, 9→3
+  var headsCount = lineVal - 6;
+  var faces = [false, false, false]; // false=花, true=字
+  for (var i = 0; i < headsCount; i++) faces[i] = true;
+  // 随机打乱顺序，让每次排列不同
+  for (var j = faces.length - 1; j > 0; j--) {
+    var k = Math.floor(Math.random() * (j + 1));
+    var tmp = faces[j]; faces[j] = faces[k]; faces[k] = tmp;
+  }
+  return faces;
+}
+
+function flipCoinsWithResult(lineVal) {
+  var faces = getCoinsForLine(lineVal);
+  return new Promise(function(resolve) {
+    var coins = [
+      document.getElementById('coin1'),
+      document.getElementById('coin2'),
+      document.getElementById('coin3')
+    ];
+    coins.forEach(function(c, idx) {
+      c.classList.remove('flipping-front', 'flipping-back');
+      c.style.transform = '';
+      void c.offsetWidth;
+      c.classList.add(faces[idx] ? 'flipping-front' : 'flipping-back');
+    });
+    setTimeout(resolve, 700);
+  });
+}
+
+function sleep(ms) {
+  return new Promise(function(r) { setTimeout(r, ms); });
+}
+
+/* ========== 渲染结果 ========== */
+
+async function showResult(data) {
+  var resultSection = document.getElementById('resultSection');
+  resultSection.classList.add('active');
+
+  // 构建卦象图（使用安全的 DOM 方法）
+  buildHexagramDisplay(data);
+
+  // 显示卦象卡片（含逐爻动画）
+  document.getElementById('cardHexagram').classList.add('visible');
+  await animateLines();
+
+  // 变卦
+  var cardChanged = document.getElementById('cardChanged');
+  if (data.changed_hexagram) {
+    buildChangedDisplay(data.changed_hexagram);
+    cardChanged.style.display = '';
+    await sleep(300);
+    cardChanged.classList.add('visible');
+  } else {
+    cardChanged.style.display = 'none';
+    cardChanged.classList.remove('visible');
+  }
+
+  // 卦辞
+  document.getElementById('judgmentText').textContent = data.judgment || '';
+  await sleep(300);
+  document.getElementById('cardJudgment').classList.add('visible');
+
+  // 爻辞
+  var list = document.getElementById('linesTextList');
+  clearChildren(list);
+  if (data.lines_text && data.lines_text.length) {
+    data.lines_text.forEach(function(text, i) {
+      var li = el('li', null, text);
+      // 动爻位置高亮（changing_lines 是1-based位置）
+      if (data.changing_lines && data.changing_lines.indexOf(i + 1) !== -1) {
+        li.classList.add('changing-line');
+      }
+      list.appendChild(li);
+    });
+    await sleep(300);
+    document.getElementById('cardLines').classList.add('visible');
+  }
+
+  // AI 解读（WebSocket 长连接）
+  var interpEl = document.getElementById('interpText');
+  interpEl.textContent = '正在请大师解卦...';
+  await sleep(300);
+  document.getElementById('cardInterp').classList.add('visible');
+
+  // 滚动到结果区域
+  resultSection.scrollIntoView({ behavior: 'smooth', block: 'start' });
+
+  // 通过 WebSocket 获取流式解读
+  var question = document.getElementById('question').value.trim();
+  var wsUrl = API_BASE.replace(/^http/, 'ws') + '/ws/interpret';
+  var ws = new WebSocket(wsUrl);
+  var firstContent = true;
+
+  ws.onopen = function() {
+    ws.send(JSON.stringify({
+      question: question || '',
+      hexagram_name: data.hexagram.name,
+      hexagram_number: data.hexagram.number,
+      judgment: data.judgment,
+      image: data.interpretation,
+      lines_text: data.lines_text,
+      changing_lines: data.changing_lines || [],
+      changed_hexagram_name: data.changed_hexagram ? data.changed_hexagram.name : null
+    }));
+  };
+
+  ws.onmessage = function(event) {
+    var msg = JSON.parse(event.data);
+    if (msg.type === 'thinking') {
+      interpEl.textContent = '大师正在沉思中...';
+      interpEl.classList.add('thinking');
+    } else if (msg.type === 'content') {
+      if (firstContent) {
+        interpEl.textContent = '';
+        interpEl.classList.remove('thinking');
+        interpEl.classList.add('typing');
+        firstContent = false;
+      }
+      interpEl.textContent += msg.text;
+    } else if (msg.type === 'done') {
+      interpEl.classList.remove('typing', 'thinking');
+    } else if (msg.type === 'error') {
+      interpEl.classList.remove('typing', 'thinking');
+      interpEl.textContent = '解读出错：' + msg.text;
+    }
+  };
+
+  ws.onclose = function() {
+    interpEl.classList.remove('typing', 'thinking');
+    if (firstContent) {
+      interpEl.textContent = data.interpretation || '解读服务暂不可用';
+    }
+  };
+
+  ws.onerror = function() {
+    interpEl.classList.remove('typing', 'thinking');
+    if (firstContent) {
+      interpEl.textContent = data.interpretation || '解读服务暂不可用';
+    }
+  };
+}
+
+/** 使用安全 DOM 方法构建主卦象显示 */
+function buildHexagramDisplay(data) {
+  var hex = data.hexagram;
+  var lines = hex.lines || [];
+  var container = document.getElementById('hexDisplay');
+  clearChildren(container);
+
+  // 卦符
+  var symbolDiv = el('div', { className: 'hex-symbol' }, hex.symbol || '');
+  container.appendChild(symbolDiv);
+
+  // 卦名
+  var nameDiv = el('div', { className: 'hex-name' },
+    hex.name + '\u5366\uFF08\u7B2C' + hex.number + '\u5366\uFF09');
+  container.appendChild(nameDiv);
+
+  // 上下卦
+  var triDiv = el('div', { className: 'hex-trigrams' },
+    (hex.upper_trigram || '') + ' \u4E0A / ' + (hex.lower_trigram || '') + ' \u4E0B');
+  container.appendChild(triDiv);
+
+  // 爻线显示区
+  var linesDiv = el('div', { className: 'lines-display' });
+
+  // 爻从上（第6）到下（第1）显示
+  for (var i = lines.length - 1; i >= 0; i--) {
+    var val = lines[i];
+    var changing = isChanging(val);
+
+    var row = el('div', { className: 'line-row' });
+    row.setAttribute('data-line-index', i);
+
+    var label = el('span', { className: 'line-label' }, LINE_NAMES[i] + '\u723B');
+    row.appendChild(label);
+
+    var graphic = el('span', {
+      className: 'line-graphic' + (changing ? ' changing' : '')
+    }, lineGraphic(val));
+    row.appendChild(graphic);
+
+    var value = el('span', { className: 'line-value' },
+      val + (changing ? ' \u52A8' : ''));
+    row.appendChild(value);
+
+    linesDiv.appendChild(row);
+  }
+
+  container.appendChild(linesDiv);
+}
+
+/** 逐爻显示动画（从下到上） */
+async function animateLines() {
+  var rows = document.querySelectorAll('#hexDisplay .line-row');
+  // rows 在 DOM 中从上到下排列，即 [上爻, 五爻, ..., 初爻]
+  // 需要从初爻（最后一个）开始显示
+  for (var i = rows.length - 1; i >= 0; i--) {
+    rows[i].classList.add('visible');
+    await sleep(300);
+  }
+}
+
+/** 使用安全 DOM 方法构建变卦显示 */
+function buildChangedDisplay(changed) {
+  var container = document.getElementById('changedDisplay');
+  clearChildren(container);
+
+  var arrow = el('div', { className: 'change-arrow' }, '\u2193 \u53D8\u5366 \u2193');
+  container.appendChild(arrow);
+
+  var symbolDiv = el('div', { className: 'hex-symbol' }, changed.symbol || '');
+  container.appendChild(symbolDiv);
+
+  var nameDiv = el('div', { className: 'hex-name' },
+    changed.name + '\u5366\uFF08\u7B2C' + changed.number + '\u5366\uFF09');
+  container.appendChild(nameDiv);
+}
+
+/* ========== 64卦速查 ========== */
+
+/** 展开/收起速查表 */
+function toggleLookup() {
+  var btn = document.getElementById('lookupToggle');
+  var grid = document.getElementById('lookupGrid');
+  var isOpen = grid.classList.contains('open');
+
+  if (isOpen) {
+    grid.classList.remove('open');
+    btn.classList.remove('open');
+  } else {
+    grid.classList.add('open');
+    btn.classList.add('open');
+    if (!hexagramsCache) loadHexagrams();
+  }
+}
+
+/** 加载64卦列表 */
+async function loadHexagrams() {
+  var grid = document.getElementById('lookupGrid');
+  clearChildren(grid);
+  var loadingDiv = el('div', { className: 'loading', style: 'grid-column:1/-1;' },
+    '\u52A0\u8F7D\u4E2D...');
+  grid.appendChild(loadingDiv);
+
+  try {
+    var resp = await fetch(API_BASE + '/api/hexagrams');
+    if (!resp.ok) throw new Error('\u8BF7\u6C42\u5931\u8D25 (' + resp.status + ')');
+    var list = await resp.json();
+    hexagramsCache = list;
+    renderHexagramGrid(list);
+  } catch (e) {
+    clearChildren(grid);
+    var errDiv = el('div', {
+      className: 'loading',
+      style: 'grid-column:1/-1;color:var(--red-light);'
+    }, '\u52A0\u8F7D\u5931\u8D25\uFF1A' + e.message);
+    grid.appendChild(errDiv);
+  }
+}
+
+/** 渲染卦列表网格 */
+function renderHexagramGrid(list) {
+  var grid = document.getElementById('lookupGrid');
+  clearChildren(grid);
+
+  list.forEach(function(h) {
+    var card = el('div', { className: 'hex-card' });
+    card.onclick = function() { showHexDetail(h.number); };
+
+    var sym = el('span', { className: 'card-symbol' }, h.symbol || '');
+    var name = el('span', { className: 'card-name' }, h.name);
+    var num = el('span', { className: 'card-num' }, '\u7B2C' + h.number + '\u5366');
+
+    card.appendChild(sym);
+    card.appendChild(name);
+    card.appendChild(num);
+    grid.appendChild(card);
+  });
+}
+
+/** 显示单卦详情（使用安全 DOM 方法） */
+async function showHexDetail(number) {
+  var modal = document.getElementById('modal');
+  var body = document.getElementById('modalBody');
+  clearChildren(body);
+  body.appendChild(el('div', { className: 'loading' }, '\u52A0\u8F7D\u4E2D...'));
+  modal.classList.add('active');
+
+  try {
+    var resp = await fetch(API_BASE + '/api/hexagrams/' + number);
+    if (!resp.ok) throw new Error('\u8BF7\u6C42\u5931\u8D25 (' + resp.status + ')');
+    var h = await resp.json();
+
+    clearChildren(body);
+
+    // 卦符
+    body.appendChild(el('div', { className: 'modal-symbol' }, h.symbol || ''));
+
+    // 卦名
+    var title = el('h2', { style: 'text-align:center;' },
+      h.name + '\u5366\uFF08\u7B2C' + h.number + '\u5366\uFF09');
+    body.appendChild(title);
+
+    // 上下卦
+    body.appendChild(el('div', { className: 'modal-meta' },
+      (h.upper_trigram || '') + ' \u4E0A / ' + (h.lower_trigram || '') + ' \u4E0B'));
+
+    // 卦辞
+    if (h.judgment) {
+      body.appendChild(el('h4', null, '\u5366\u8F9E'));
+      body.appendChild(el('p', null, h.judgment));
+    }
+
+    // 象辞
+    if (h.image) {
+      body.appendChild(el('h4', null, '\u8C61\u8F9E'));
+      body.appendChild(el('p', null, h.image));
+    }
+
+    // 爻辞
+    if (h.lines && h.lines.length) {
+      body.appendChild(el('h4', null, '\u7237\u8F9E'));
+      var ul = el('ul');
+      h.lines.forEach(function(line) {
+        ul.appendChild(el('li', null, line));
+      });
+      body.appendChild(ul);
+    }
+  } catch (e) {
+    clearChildren(body);
+    body.appendChild(el('div', {
+      className: 'loading',
+      style: 'color:var(--red-light);'
+    }, '\u52A0\u8F7D\u5931\u8D25\uFF1A' + e.message));
+  }
+}
+
+/** 关闭模态 */
+function closeModal() {
+  document.getElementById('modal').classList.remove('active');
+}
+
+function closeModalOutside(e) {
+  if (e.target === document.getElementById('modal')) closeModal();
+}
+
+// ESC 关闭模态
+document.addEventListener('keydown', function(e) {
+  if (e.key === 'Escape') closeModal();
+});
+</script>
+
+</body>
+</html>

start.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ============================================================
+#  I-Ching — 一键安装 & 启动脚本
+# ============================================================
+
+PORT="${PORT:-8000}"
+VENV_DIR=".venv"
+PROJECT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+cd "$PROJECT_DIR"
+
+# ---------- 颜色输出 ----------
+green()  { printf '\033[32m%s\033[0m\n' "$*"; }
+yellow() { printf '\033[33m%s\033[0m\n' "$*"; }
+red()    { printf '\033[31m%s\033[0m\n' "$*"; }
+
+# ---------- 检查 Python ----------
+if ! command -v python3 &>/dev/null; then
+    red "未找到 python3，请先安装 Python 3.10+"
+    exit 1
+fi
+
+PY_VERSION=$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')
+yellow "Python 版本: $PY_VERSION"
+
+# ---------- 创建虚拟环境 ----------
+if [[ ! -d "$VENV_DIR" ]]; then
+    yellow "创建虚拟环境..."
+    if command -v uv &>/dev/null; then
+        uv venv "$VENV_DIR"
+    else
+        python3 -m venv "$VENV_DIR"
+    fi
+    green "虚拟环境已创建"
+fi
+
+# 激活虚拟环境
+source "$VENV_DIR/bin/activate"
+
+# ---------- 安装依赖 ----------
+yellow "安装依赖..."
+if command -v uv &>/dev/null; then
+    uv pip install -r backend/requirements.txt -q
+else
+    pip install -r backend/requirements.txt -q
+fi
+green "依赖安装完成"
+
+# ---------- LLM 配置 ----------
+ENV_FILE="$PROJECT_DIR/.env"
+
+if [[ -f "$ENV_FILE" ]]; then
+    yellow "加载已有配置 (.env)..."
+    set -a
+    source "$ENV_FILE"
+    set +a
+    green "LLM: $LLM_BASE_URL | 模型: $LLM_MODEL"
+else
+    yellow "首���运行，请配置 LLM 连接信息："
+    yellow "(支持任何 OpenAI 兼容 API：LM Studio / Ollama / OpenAI / DeepSeek 等)"
+    yellow "(直接回车使用默认值)"
+    echo ""
+
+    read -rp "LLM API Base URL [http://localhost:1234/v1]: " input_url
+    LLM_BASE_URL="${input_url:-http://localhost:1234/v1}"
+
+    read -rp "LLM API Key [lm-studio]: " input_key
+    LLM_API_KEY="${input_key:-lm-studio}"
+
+    read -rp "模型名称 [google/gemma-4-26b-a4b]: " input_model
+    LLM_MODEL="${input_model:-google/gemma-4-26b-a4b}"
+
+    cat > "$ENV_FILE" <<ENVEOF
+LLM_BASE_URL=$LLM_BASE_URL
+LLM_API_KEY=$LLM_API_KEY
+LLM_MODEL=$LLM_MODEL
+ENVEOF
+
+    green "配置已保存到 .env（修改配置请编辑此文件或删除后重新运行）"
+    export LLM_BASE_URL LLM_API_KEY LLM_MODEL
+fi
+
+# ---------- 检查 LLM 服务 ----------
+if curl -s --connect-timeout 2 "${LLM_BASE_URL}/models" &>/dev/null; then
+    green "LLM 服务已连接 ($LLM_BASE_URL)"
+else
+    yellow "提示: LLM 服务未检��到 ($LLM_BASE_URL)"
+    yellow "AI 卦辞解读功能��要 LLM 服��运行，其他功��不受影响"
+fi
+
+# ---------- 启动服务 ----------
+green "=========================================="
+green "  I-Ching启动中..."
+green "  访问地址: http://localhost:${PORT}"
+green "  按 Ctrl+C 停止"
+green "=========================================="
+
+exec uvicorn backend.main:app --host 0.0.0.0 --port "$PORT" --reload

tests/__init__.py

@@ -0,0 +1 @@
+# 测试包初始化文件

tests/test_divination.py

@@ -0,0 +1,522 @@
+from __future__ import annotations
+
+import dataclasses
+from typing import Any
+
+import pytest
+
+
+# 八卦名称的接口契约
+TRIGRAM_NAMES = {"乾", "坤", "震", "巽", "坎", "离", "艮", "兑"}
+
+
+def _fail(message: str) -> None:
+    """统一输出更清晰的测试失败信息。"""
+    pytest.fail(message, pytrace=False)
+
+
+def _import_divination_module():
+    """延迟导入算卦模块，避免在收集阶段直接报错。"""
+    try:
+        import backend.divination as divination
+    except ModuleNotFoundError as exc:
+        _fail(f"无法导入 `backend.divination`：{exc}")
+    except Exception as exc:  # pragma: no cover - 用于提供更清晰的错误信息
+        _fail(f"导入 `backend.divination` 失败：{exc}")
+    return divination
+
+
+def _import_hexagrams_data_module():
+    """延迟导入卦象数据模块。"""
+    try:
+        import backend.hexagrams_data as hexagrams_data
+    except ModuleNotFoundError as exc:
+        _fail(f"无法导入 `backend.hexagrams_data`：{exc}")
+    except Exception as exc:  # pragma: no cover - 用于提供更清晰的错误信息
+        _fail(f"导入 `backend.hexagrams_data` 失败：{exc}")
+    return hexagrams_data
+
+
+def _import_main_module():
+    """延迟导入 FastAPI 应用模块。"""
+    try:
+        import backend.main as main
+    except ModuleNotFoundError as exc:
+        _fail(f"无法导入 `backend.main`：{exc}")
+    except Exception as exc:  # pragma: no cover - 用于提供更清晰的错误信息
+        _fail(f"导入 `backend.main` 失败：{exc}")
+    return main
+
+
+def _get_field(obj: Any, field_name: str) -> Any:
+    """兼容 dataclass / Pydantic / 普通对象 / dict 的字段读取。"""
+    if isinstance(obj, dict):
+        if field_name not in obj:
+            raise AssertionError(f"缺少字段 `{field_name}`")
+        return obj[field_name]
+
+    if dataclasses.is_dataclass(obj):
+        return getattr(obj, field_name)
+
+    model_dump = getattr(obj, "model_dump", None)
+    if callable(model_dump):
+        data = model_dump()
+        if field_name in data:
+            return data[field_name]
+
+    to_dict = getattr(obj, "dict", None)
+    if callable(to_dict):
+        data = to_dict()
+        if field_name in data:
+            return data[field_name]
+
+    if hasattr(obj, field_name):
+        return getattr(obj, field_name)
+
+    raise AssertionError(f"缺少字段 `{field_name}`")
+
+
+def _get_collection(module: Any, *names: str) -> Any:
+    """从模块中读取约定的数据集合。"""
+    for name in names:
+        if hasattr(module, name):
+            return getattr(module, name)
+    _fail(f"模块 `{module.__name__}` 中缺少数据集合：{', '.join(names)}")
+
+
+def _collection_values(collection: Any) -> list[Any]:
+    """将 list / tuple / dict 等集合统一为值列表。"""
+    if isinstance(collection, dict):
+        return list(collection.values())
+    if isinstance(collection, (list, tuple, set)):
+        return list(collection)
+    _fail(f"不支持的数据集合类型：{type(collection)!r}")
+
+
+def _get_hexagrams(data_module: Any) -> list[Any]:
+    """读取 64 卦数据。"""
+    collection = _get_collection(data_module, "HEXAGRAMS", "hexagrams")
+    return _collection_values(collection)
+
+
+def _get_trigrams(data_module: Any) -> list[Any]:
+    """读取八卦数据。如果是 dict（key=卦名），自动将 key 注入 value 的 'name' 字段。"""
+    collection = _get_collection(data_module, "TRIGRAMS", "trigrams")
+    if isinstance(collection, dict):
+        result = []
+        for name, value in collection.items():
+            if isinstance(value, dict):
+                entry = {**value, "name": name}
+            else:
+                entry = value
+            result.append(entry)
+        return result
+    return _collection_values(collection)
+
+
+def _get_coin_toss(divination_module: Any) -> tuple[str, Any]:
+    """查找单次摇爻函数。"""
+    for name in ("coin_toss", "toss_coins", "toss_coin", "throw_coins", "cast_line"):
+        func = getattr(divination_module, name, None)
+        if callable(func):
+            return name, func
+    _fail(
+        "`backend.divination` 需要暴露单次摇爻函数，"
+        "例如 `coin_toss()`，以便验证铜钱结果范围。"
+    )
+
+
+def _get_lookup_func(divination_module: Any):
+    """查找根据上下卦定位六十四卦的函数。"""
+    for name in (
+        "lookup_hexagram",
+        "get_hexagram_by_trigrams",
+        "find_hexagram_by_trigrams",
+        "hexagram_lookup",
+    ):
+        func = getattr(divination_module, name, None)
+        if callable(func):
+            return func
+    _fail(
+        "`backend.divination` 需要暴露按上下卦查找卦象的函数，"
+        "例如 `lookup_hexagram(upper, lower)`。"
+    )
+
+
+def _lookup_hexagram(divination_module: Any, upper: str, lower: str) -> Any:
+    """兼容不同参数写法调用卦象查找函数。"""
+    lookup = _get_lookup_func(divination_module)
+
+    try:
+        return lookup(upper=upper, lower=lower)
+    except TypeError:
+        try:
+            return lookup(upper, lower)
+        except TypeError as exc:
+            _fail(f"卦象查找函数调用失败：{exc}")
+
+
+def _get_divine_func(divination_module: Any):
+    """读取主算卦函数，优先使用 perform_divination（返回完整结果）。"""
+    for name in ("perform_divination", "divine"):
+        func = getattr(divination_module, name, None)
+        if callable(func):
+            return func
+    _fail("`backend.divination` 中缺少 `divine()` 或 `perform_divination()` 函数。")
+
+
+def _call_divine(divination_module: Any, question: str | None = None) -> Any:
+    """兼容是否接收 question 参数的 divine() 调用。"""
+    divine = _get_divine_func(divination_module)
+
+    if question is None:
+        try:
+            return divine()
+        except TypeError:
+            return divine("")
+
+    try:
+        return divine(question=question)
+    except TypeError:
+        try:
+            return divine(question)
+        except TypeError as exc:
+            _fail(f"`divine()` 调用失败：{exc}")
+
+
+def _patch_coin_sequence(monkeypatch: pytest.MonkeyPatch, divination_module: Any, sequence: list[int]) -> None:
+    """将随机摇卦替换为固定爻序列，确保测试稳定。"""
+    func_name, _ = _get_coin_toss(divination_module)
+    values = iter(sequence)
+
+    def fake_coin_toss() -> int:
+        try:
+            return next(values)
+        except StopIteration:
+            _fail("固定摇卦序列已耗尽，说明 `divine()` 调用次数超过 6 次。")
+
+    monkeypatch.setattr(divination_module, func_name, fake_coin_toss)
+
+
+def _get_result_lines(result: Any) -> list[int]:
+    """从 DivinationResult 中读取六爻值。"""
+    # perform_divination 返回嵌套结构: result["hexagram"]["lines"]
+    if isinstance(result, dict) and "hexagram" in result:
+        hexagram = result["hexagram"]
+        if isinstance(hexagram, dict) and "lines" in hexagram:
+            return hexagram["lines"]
+    lines = _get_field(result, "lines")
+    assert isinstance(lines, list), "DivinationResult.lines 必须是 list"
+    return lines
+
+
+def _get_result_changing_lines(result: Any) -> list[int]:
+    """读取动爻位置列表。"""
+    changing_lines = _get_field(result, "changing_lines")
+    assert isinstance(changing_lines, list), "DivinationResult.changing_lines 必须是 list"
+    return changing_lines
+
+
+def _get_result_changed_hexagram(result: Any) -> Any:
+    """读取变卦。"""
+    return _get_field(result, "changed_hexagram")
+
+
+def _assert_hexagram_fields(hexagram: Any) -> None:
+    """校验 Hexagram 数据模型必备字段。"""
+    number = _get_field(hexagram, "number")
+    name = _get_field(hexagram, "name")
+    symbol = _get_field(hexagram, "symbol")
+    upper_trigram = _get_field(hexagram, "upper_trigram")
+    lower_trigram = _get_field(hexagram, "lower_trigram")
+    judgment = _get_field(hexagram, "judgment")
+    image = _get_field(hexagram, "image")
+    lines = _get_field(hexagram, "lines")
+
+    assert isinstance(number, int) and 1 <= number <= 64
+    assert isinstance(name, str) and name
+    assert isinstance(symbol, str) and symbol
+    assert isinstance(upper_trigram, str) and upper_trigram in TRIGRAM_NAMES
+    assert isinstance(lower_trigram, str) and lower_trigram in TRIGRAM_NAMES
+    assert isinstance(judgment, str) and judgment
+    assert isinstance(image, str) and image
+    assert isinstance(lines, list) and len(lines) == 6
+    assert all(isinstance(line, str) and line for line in lines)
+
+
+def _assert_trigram_fields(trigram: Any) -> None:
+    """校验 Trigram 数据模型必备字段。"""
+    name = _get_field(trigram, "name")
+    symbol = _get_field(trigram, "symbol")
+    nature = _get_field(trigram, "nature")
+
+    assert isinstance(name, str) and name in TRIGRAM_NAMES
+    assert isinstance(symbol, str) and symbol
+    assert isinstance(nature, str) and nature
+
+
+def _assert_divine_api_response(payload: dict[str, Any]) -> None:
+    """校验 POST /api/divine 的响应结构。"""
+    assert isinstance(payload, dict)
+
+    required_top_level_fields = {
+        "hexagram",
+        "judgment",
+        "interpretation",
+        "changing_lines",
+        "changed_hexagram",
+        "lines_text",
+        "question",
+    }
+    assert required_top_level_fields.issubset(payload.keys())
+
+    hexagram = payload["hexagram"]
+    assert isinstance(hexagram, dict)
+    assert {"number", "name", "symbol", "lines", "upper_trigram", "lower_trigram"}.issubset(hexagram.keys())
+    assert isinstance(hexagram["number"], int) and 1 <= hexagram["number"] <= 64
+    assert isinstance(hexagram["name"], str) and hexagram["name"]
+    assert isinstance(hexagram["symbol"], str) and hexagram["symbol"]
+    assert isinstance(hexagram["upper_trigram"], str) and hexagram["upper_trigram"] in TRIGRAM_NAMES
+    assert isinstance(hexagram["lower_trigram"], str) and hexagram["lower_trigram"] in TRIGRAM_NAMES
+    assert isinstance(hexagram["lines"], list) and len(hexagram["lines"]) == 6
+    assert all(line in {6, 7, 8, 9} for line in hexagram["lines"])
+
+    assert isinstance(payload["judgment"], str) and payload["judgment"]
+    assert isinstance(payload["interpretation"], str) and payload["interpretation"]
+    assert isinstance(payload["changing_lines"], list)
+    assert all(isinstance(pos, int) and 1 <= pos <= 6 for pos in payload["changing_lines"])
+
+    changed_hexagram = payload["changed_hexagram"]
+    if changed_hexagram is not None:
+        assert isinstance(changed_hexagram, dict)
+        assert {"number", "name", "symbol"}.issubset(changed_hexagram.keys())
+        assert isinstance(changed_hexagram["number"], int) and 1 <= changed_hexagram["number"] <= 64
+        assert isinstance(changed_hexagram["name"], str) and changed_hexagram["name"]
+        assert isinstance(changed_hexagram["symbol"], str) and changed_hexagram["symbol"]
+
+    assert isinstance(payload["lines_text"], list) and len(payload["lines_text"]) == 6
+    assert all(isinstance(text, str) and text for text in payload["lines_text"])
+    assert isinstance(payload["question"], str)
+
+
+@pytest.fixture(scope="module")
+def divination_module():
+    """提供 backend.divination 模块。"""
+    return _import_divination_module()
+
+
+@pytest.fixture(scope="module")
+def hexagrams_data_module():
+    """提供 backend.hexagrams_data 模块。"""
+    return _import_hexagrams_data_module()
+
+
+@pytest.fixture(scope="module")
+def main_module():
+    """提供 backend.main 模块。"""
+    return _import_main_module()
+
+
+@pytest.fixture()
+def client(main_module):
+    """创建 FastAPI TestClient。"""
+    from fastapi.testclient import TestClient
+
+    app = getattr(main_module, "app", None)
+    if app is None:
+        _fail("`backend.main` 中缺少 FastAPI 实例 `app`。")
+    return TestClient(app)
+
+
+# ----------------------------
+# 算卦逻辑测试
+# ----------------------------
+
+
+def test_coin_toss(divination_module):
+    """铜钱投掷结果必须落在 6/7/8/9 范围内。"""
+    _, coin_toss = _get_coin_toss(divination_module)
+    results = [coin_toss() for _ in range(100)]
+
+    assert results, "coin_toss() 应至少返回一个结果"
+    assert all(result in {6, 7, 8, 9} for result in results)
+
+
+def test_divine_returns_six_lines(divination_module):
+    """divine() 应返回 6 个爻值。"""
+    result = _call_divine(divination_module)
+    lines = _get_result_lines(result)
+
+    assert len(lines) == 6
+
+
+def test_line_values_valid(divination_module):
+    """每爻值都必须是 6/7/8/9。"""
+    result = _call_divine(divination_module)
+    lines = _get_result_lines(result)
+
+    assert all(line in {6, 7, 8, 9} for line in lines)
+
+
+def test_changing_lines_identified(divination_module, monkeypatch):
+    """6 和 9 必须被识别为动爻，且位置按自下而上从 1 开始计数。"""
+    expected_lines = [6, 7, 8, 9, 8, 7]
+    _patch_coin_sequence(monkeypatch, divination_module, expected_lines)
+
+    result = _call_divine(divination_module, question="测试动爻识别")
+    lines = _get_result_lines(result)
+    changing_lines = _get_result_changing_lines(result)
+    changed_hexagram = _get_result_changed_hexagram(result)
+
+    assert lines == expected_lines
+    assert changing_lines == [1, 4]
+    assert changed_hexagram is not None
+
+
+def test_no_changing_lines(divination_module, monkeypatch):
+    """没有 6/9 时，不应生成变卦。"""
+    expected_lines = [7, 8, 7, 8, 7, 8]
+    _patch_coin_sequence(monkeypatch, divination_module, expected_lines)
+
+    result = _call_divine(divination_module, question="测试无动爻")
+    changing_lines = _get_result_changing_lines(result)
+    changed_hexagram = _get_result_changed_hexagram(result)
+
+    assert changing_lines == []
+    assert changed_hexagram is None
+
+
+def test_hexagram_lookup(divination_module):
+    """乾上乾下应查到第一卦乾卦。"""
+    hexagram = _lookup_hexagram(divination_module, upper="乾", lower="乾")
+
+    assert hexagram is not None
+    assert _get_field(hexagram, "number") == 1
+    assert _get_field(hexagram, "name") == "乾"
+    assert _get_field(hexagram, "upper_trigram") == "乾"
+    assert _get_field(hexagram, "lower_trigram") == "乾"
+
+
+def test_all_trigram_combinations(divination_module, hexagrams_data_module):
+    """8x8 的所有上下卦组合都必须能查到对应卦象。"""
+    trigrams = _get_trigrams(hexagrams_data_module)
+    trigram_names = {_get_field(trigram, "name") for trigram in trigrams}
+    seen_numbers = set()
+
+    assert trigram_names == TRIGRAM_NAMES
+
+    for upper in trigram_names:
+        for lower in trigram_names:
+            hexagram = _lookup_hexagram(divination_module, upper=upper, lower=lower)
+            assert hexagram is not None, f"未找到上卦={upper}、下卦={lower} 的卦象"
+            assert _get_field(hexagram, "upper_trigram") == upper
+            assert _get_field(hexagram, "lower_trigram") == lower
+            seen_numbers.add(_get_field(hexagram, "number"))
+
+    assert len(seen_numbers) == 64
+
+
+# ----------------------------
+# API 端点测试
+# ----------------------------
+
+
+def test_divine_endpoint(client):
+    """POST /api/divine 应返回符合契约的算卦结果。"""
+    response = client.post("/api/divine", json={})
+
+    assert response.status_code == 200
+    _assert_divine_api_response(response.json())
+
+
+def test_divine_with_question(client):
+    """带问题发起算卦时，响应中应保留原问题。"""
+    question = "今年事业如何？"
+    response = client.post("/api/divine", json={"question": question})
+
+    assert response.status_code == 200
+    payload = response.json()
+    _assert_divine_api_response(payload)
+    assert payload["question"] == question
+
+
+def test_hexagrams_list(client):
+    """GET /api/hexagrams 应返回 64 卦列表。"""
+    response = client.get("/api/hexagrams")
+
+    assert response.status_code == 200
+    payload = response.json()
+
+    assert isinstance(payload, list)
+    assert len(payload) == 64
+
+    numbers = set()
+    for item in payload:
+        assert {"number", "name", "symbol", "judgment"}.issubset(item.keys())
+        assert isinstance(item["number"], int) and 1 <= item["number"] <= 64
+        assert isinstance(item["name"], str) and item["name"]
+        assert isinstance(item["symbol"], str) and item["symbol"]
+        assert isinstance(item["judgment"], str) and item["judgment"]
+        numbers.add(item["number"])
+
+    assert numbers == set(range(1, 65))
+
+
+def test_hexagram_detail(client):
+    """GET /api/hexagrams/1 应返回乾卦详情。"""
+    response = client.get("/api/hexagrams/1")
+
+    assert response.status_code == 200
+    payload = response.json()
+
+    assert payload["number"] == 1
+    assert payload["name"] == "乾"
+    assert payload["upper_trigram"] == "乾"
+    assert payload["lower_trigram"] == "乾"
+    assert isinstance(payload["symbol"], str) and payload["symbol"]
+    assert isinstance(payload["judgment"], str) and payload["judgment"]
+    assert isinstance(payload["image"], str) and payload["image"]
+    assert isinstance(payload["lines"], list) and len(payload["lines"]) == 6
+
+
+def test_hexagram_not_found(client):
+    """不存在的卦序号应返回 404。"""
+    response = client.get("/api/hexagrams/99")
+
+    assert response.status_code == 404
+
+
+# ----------------------------
+# 数据完整性测试
+# ----------------------------
+
+
+def test_64_hexagrams_exist(hexagrams_data_module):
+    """必须提供完整 64 卦数据。"""
+    hexagrams = _get_hexagrams(hexagrams_data_module)
+    numbers = {_get_field(hexagram, "number") for hexagram in hexagrams}
+
+    assert len(hexagrams) == 64
+    assert numbers == set(range(1, 65))
+
+
+def test_hexagram_has_required_fields(hexagrams_data_module):
+    """每一卦都必须包含接口契约定义的必备字段。"""
+    hexagrams = _get_hexagrams(hexagrams_data_module)
+
+    for hexagram in hexagrams:
+        _assert_hexagram_fields(hexagram)
+
+
+def test_trigrams_complete(hexagrams_data_module):
+    """八卦数据必须完整，且字段齐全。"""
+    trigrams = _get_trigrams(hexagrams_data_module)
+    names = set()
+
+    assert len(trigrams) == 8
+
+    for trigram in trigrams:
+        _assert_trigram_fields(trigram)
+        names.add(_get_field(trigram, "name"))
+
+    assert names == TRIGRAM_NAMES