📖 English README · 更新说明 / Changelog

目录 · Table of Contents

1. 项目简介 · Introduction
2. 功能亮点 · Key Features
3. 系统架构 · Architecture
4. 命理模块详解 · Module Deep Dive
5. 快速开始 · Quick Start
6. 配置说明 · Configuration
7. 依赖说明 · Dependencies
8. API 参考 · API Reference
9. 项目结构 · Project Structure
10. 开发指南 · Development Guide
11. 常见问题 · Troubleshooting
12. 路线图 · Roadmap
13. 贡献指南 · Contributing
14. 许可证 · License

1. 项目简介 · Introduction

中文

中国术数平台是一套将传统东方术数与现代软件工程深度融合的开源全栈应用。项目以纯 Python 计算引擎为核心，严格依照古籍推算逻辑实现八字四柱、紫微斗数、六爻占卜、奇门遁甲、玄空飞星风水、择日及易经七大术数系统，并通过**多模型 LLM（Claude / OpenAI / DeepSeek / Gemini 等）**提供古籍级别的 AI 流式智能解读。

本项目的核心理念：

• 忠于古法：年柱以立春为界、月柱用五虎遁年起月法、日柱基于经典甲子参考日推算、时柱采五鼠遁日起时法
• 工程严谨：全量 Pydantic v2 数据校验、清晰的模块边界（计算层与 API 层彻底分离）
• AI 赋能：多部古籍经典知识库 + BM25 检索作为多模型提示词上下文，生成有据可查的解读而非泛泛而谈
• 一键启动：Windows / macOS / Linux 三端同等支持，无需手动配置环境

English

Chinese Metaphysics Platform is an open-source full-stack application that bridges traditional Chinese metaphysical arts with modern software engineering. At its heart lies a pure Python calculation engine that implements seven major systems — BaZi Four Pillars, ZiWei DouShu, LiuYao Six Lines, QiMen DunJia, Xuan Kong FengShui, Date Selection, and YiJing — following classical textbook algorithms precisely. A multi-LLM layer (Claude / OpenAI / DeepSeek / Gemini, etc.) then provides AI streaming interpretation grounded in classical source texts.

Core design philosophy:

• Classical Fidelity: Year pillars use LiChun as the boundary; month pillars use the Wu Hu Dun Nian Qi Yue method; day pillars reference the canonical 甲戌 1900-01-01 epoch; hour pillars use the Wu Shu Dun Ri Qi Shi method
• Engineering Rigour: Full Pydantic v2 validation, strict module separation (calculation layer vs. API layer are fully decoupled)
• AI Empowerment: A multi-text classical knowledge base with BM25 retrieval serves as the LLM context, producing citation-backed interpretation rather than generic output
• One-Click Launch: Native launchers for Windows (PowerShell + cmd.exe), macOS, and Linux — no manual environment setup required

2. 功能亮点 · Key Features

✨ 命理计算引擎 · Calculation Engines

🤖 AI 智能解读 · AI Interpretation

• 古籍知识库：内置《穷通宝鉴》《滴天髓》《三命通会》《子平真诠》《增删卜易》《卜筮正宗》《奇门遁甲统宗》《阳宅三要》等多部经典文本库
• 流式输出：Server-Sent Events（SSE）实时流式输出，无需等待全量响应
• 主题匹配：六爻占问自动匹配 12 大主题（婚姻、求财、官司、求医等），精准调用对应古籍规则
• 结构化解读：奇门遁甲提供三奇六仪、伏吟反吟、星门神三维组合解读

3. 系统架构 · Architecture

┌──────────────────────────────────────────────────────────────────┐
│                         Browser / Client                         │
│                      React + Vite  (Port 5173)                   │
│    Agent | BaZi | LiuYao | QiMen | FengShui | DateSel | KB      │
└────────────────────────┬─────────────────────────────────────────┘
                         │  HTTP / SSE (Server-Sent Events)
┌────────────────────────▼─────────────────────────────────────────┐
│                  FastAPI Application  (Port 8888)                 │
│                                                                   │
│  /agent (SSE)  /bazi  /liuyao  /qimen  /fengshui  /date-sel      │
│                                                                   │
│          Pydantic v2 Schemas  (models/)                          │
│                                                                   │
│  ┌──────────┬──────────┬──────────┬──────────┬──────────────┐   │
│  │  bazi/   │ liuyao/  │  qimen/  │fengshui/ │date_select.. │   │
│  │ chart    │ divin.   │ algorithm│ calculat.│ selector     │   │
│  │ analyzer │ najia    │ analyzer │ flying_* │ twelve_offic.│   │
│  │ forecast │ interpret│ purpose  │          │              │   │
│  └──────────┴──────────┴──────────┴──────────┴──────────────┘   │
│                  calendar/ (ganzhi + solar_terms)                 │
│                  constants.py (single source of truth)           │
│                                                                   │
│         knowledge/  (Classical Text Library + BM25 RAG)            │
│    穷通宝鉴 · 滴天髓 · 三命通会 · 增删卜易 · 卜筮正宗            │
└──────────────────────────────┬───────────────────────────────────┘
                               │  HTTPS  (httpx async)
                  ┌────────────▼──────────────┐
                  │    Multi-LLM Providers    │
                  │   Streaming SSE response   │
                  └───────────────────────────┘

技术选型 · Technology Stack

4. 命理模块详解 · Module Deep Dive

🀄 八字模块 · BaZi (Four Pillars of Destiny)

排盘算法 Chart Construction

分析功能 Analysis Capabilities

• 十神矩阵：100 组天干对的完整十神映射（比肩/劫财/食神/伤官/偏财/正财/七杀/正官/偏印/正印）
• 五行强弱：旺/相/休/囚/死 五种季节状态评估
• 格局判定：主要格局 + 从弱/从旺等特殊格局自动识别
• 神煞：完整神煞表含禄神、羊刃（B-12 修正版本）
• 纳音五行：60 甲子纳音全表（海中金至大海水）
• 大运：精确日数 ÷ 3 推算起运年龄（B-08 精确修正，阳男阴女顺行，阴男阳女逆行）
• 流年流月六亲动态推演

☯ 六爻模块 · LiuYao (Six Lines Divination)

经典依据：《增删卜易》《卜筮正宗》《易隐》《火珠林》《黄金策》

起卦方式 Divination Methods

核心分析 Core Analysis

• 纳甲装卦（六爻完整天干地支纳入）
• 世爻/应爻确定，六亲（父母/兄弟/子孙/妻财/官鬼），六神（青龙/朱雀/勾陈/腾蛇/白虎/玄武）
• 动爻/变爻，本卦 → 变卦自动生成
• 日月冲克、空亡判断
• 用神确定，12 大主题自动匹配对应古籍规则

主题关键词自动匹配 Topic Auto-matching

🧭 奇门遁甲模块 · QiMen DunJia

基于三元九局（Sanyuan Jiuju）算法，完整实现奇门排盘。

核心算法 Core Algorithm

• 阳遁/阴遁判定（冬至→夏至 = 阳遁，夏至→冬至 = 阴遁）
• 局数推算（1–9 局，基于节气位置）
• 元（上/中/下元）确定
• 九宫完整布局：九星 + 八门 + 八神 + 天干

天干解读矩阵 Stem Interpretation Matrix

用途专项分析 Purpose Analysis
6 大主题（求财/感情/事业/出行/健康/学业）各自提供：宫位判断、吉凶星门组合、具体建议。

特殊格局检测

• 伏吟（宫与星同，主静滞不动）
• 反吟（相冲之宫，主反复无常）

🏡 风水模块 · FengShui

融合八宅风水与玄空飞星两大体系。

八宅分析 Eight Mansion

• 命卦推算（传统男减女加公式，2000 年后调整版本）
• 东四命（1/3/4/9 宫）vs 西四命（2/5/6/7/8 宫）
• 八方位吉凶：生气/延年/天医/伏位（四吉）vs 五鬼/绝命/六煞/祸害（四凶）

玄空飞星 Xuan Kong Flying Stars

📅 择日模块 · Date Selection

建除十二神 Twelve Officers
建/除/满/平/定/执/破/危/成/收/开/闭 — 依日柱地支与月柱地支关系推算，各有宜忌。

用途专项筛选 Purpose Criteria

三煞方位：依流年地支推算，动土修缮忌犯三煞方。

5. 快速开始 · Quick Start

前置要求 · Prerequisites

💡 Windows 用户：安装 Python 时务必勾选 ✅ "Add Python to PATH"

克隆与启动 · Clone & Start

Windows — PowerShell（推荐）

# 克隆项目
git clone https://github.com/your-username/bagua-divination.git
cd bagua-divination

# 首次运行：允许本地脚本执行
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

# 一键启动（自动安装依赖 + 启动前后端）
.\start.ps1

Windows — Command Prompt (cmd.exe)

git clone https://github.com/your-username/bagua-divination.git
cd bagua-divination
start.bat

macOS / Linux

git clone https://github.com/your-username/bagua-divination.git
cd bagua-divination
chmod +x start.sh
./start.sh

启动后访问 · Access After Starting

启动成功后，终端将打印如下信息：
After a successful start, the terminal prints:

  ╔══════════════════════════════════════════════╗
  ║          中国术数平台 · Chinese Metaphysics Platform           ║
  ║  八字 · 六爻 · 奇门遁甲 · 风水 · 择日       ║
  ╚══════════════════════════════════════════════╝

  ● Backend API  →  http://localhost:8888
  ● API Docs     →  http://localhost:8888/docs
  ● Frontend     →  http://localhost:5173

所有命令 · All Commands

智能缓存：启动脚本对 requirements.txt 和 package.json 进行 MD5 哈希比对，内容未变更时跳过重复安装，大幅加快二次启动速度。
Smart caching: The launcher compares MD5 hashes of requirements.txt and package.json — dependencies are skipped unless files have changed, making subsequent starts much faster.

6. 配置说明 · Configuration

cp .env.example .env
# 然后编辑 .env / Then edit .env

完整配置项 · All Options

# ─── 服务器 Server ───────────────────────────────────────────────
APP_HOST=0.0.0.0          # 监听地址，0.0.0.0 允许局域网访问
APP_PORT=8888             # 后端端口
DEBUG=false               # true 时开启详细日志

# ─── AI 功能 AI Agent ────────────────────────────────────────────
# 用于 /api/v1/agent/* 的多模型流式解读
# Required for multi-LLM streaming at /api/v1/agent/*
ANTHROPIC_API_KEY=sk-ant-...

# ─── CORS 跨域 ───────────────────────────────────────────────────
# 生产环境请改为实际域名 / Change to your domain in production
CORS_ORIGINS=["http://localhost:5173"]

获取 API Key · Getting an API Key

1. 前往 console.anthropic.com 注册账号
2. 进入 API Keys → Create Key
3. 复制 sk-ant-... 密钥填入 .env

⚠️ 注意：AI 顾问（/api/v1/agent/*）需有效 API Key。
八字/六爻/奇门/风水/择日五个计算模块无需 API Key 即可独立运行。
The five calculation modules work without an API Key — only the AI streaming features require one.

生产部署 · Production Deployment

APP_HOST=0.0.0.0
APP_PORT=8888
DEBUG=false
CORS_ORIGINS=["https://yourdomain.com"]
ANTHROPIC_API_KEY=sk-ant-...

建议在 Nginx 前置反向代理，并通过 systemd 或 supervisor 管理进程。
Recommended: place Nginx as a reverse proxy and manage the process with systemd or supervisor.

7. 依赖说明 · Dependencies

Python 后端 · Backend (requirements.txt)

pip install -r requirements.txt

前端 · Frontend

基于 React 18 + Vite，启动脚本自动安装。手动安装：

cd frontend
npm install
npm audit fix      # 修复 dev 依赖中的安全漏洞（无破坏性）
npm run dev        # 开发模式 Development
npm run build      # 生产构建 Production build
npm run preview    # 预览生产构建 Preview

关于 npm 漏洞提示：npm install 后可能看到 vite/postcss 等漏洞提示。这些都是 dev/build 工具相关（path traversal in dev server、CSS 字符串化 XSS 等），不影响生产构建后的部署。运行 npm audit fix 即可自动升级到修复版本（不会引入 breaking change）。

8. API 参考 · API Reference

完整交互式文档：启动后访问 http://localhost:8888/docs

健康检查 · Health Check

GET /health

八字 · BaZi

请求示例 Request Example — POST /api/v1/bazi/chart：

{
  "year": 1990,
  "month": 6,
  "day": 15,
  "hour": 14,
  "minute": 30,
  "gender": "male",
  "name": "张三",
  "use_true_solar_time": false
}

字段说明 Field Notes

六爻 · LiuYao

请求示例 — POST /api/v1/liuyao/divine：

{
  "method": "coin",
  "question": "问近期财运如何？"
}

手动输入示例（爻值 6=老阴/7=少阳/8=少阴/9=老阳，从初爻到上爻）：

{
  "method": "manual",
  "question": "问婚姻",
  "yao_values": [7, 8, 9, 7, 6, 8]
}

奇门遁甲 · QiMen DunJia

用途参数值 Purpose Values：求财 / 感情 / 事业 / 出行 / 健康 / 学业

风水 · FengShui

择日 · Date Selection

AI 顾问 · AI Agent (SSE)

所有 /agent/* 端点返回 Content-Type: text/event-stream。
前端接收示例：

const response = await fetch('/api/v1/agent/consult', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ query: '...' })
});
const reader = response.body.getReader();
// 逐块读取 SSE 流 / Read SSE stream chunk by chunk

知识库 · Knowledge Base

9. 项目结构 · Project Structure

bagua_project_build/
│
├── start.ps1              Windows PowerShell 启动器（彩色输出 + 进程管理）
├── start.bat              Windows cmd.exe 启动器（MD5 哈希缓存加速）
├── start.sh               macOS / Linux 启动器（自动创建 .venv）
│
├── main.py                FastAPI 应用入口，路由注册
├── config.py              Pydantic-Settings 配置（读取 .env）
├── requirements.txt       Python 依赖清单
├── .env / .env.example    环境变量模板
│
├── api/                   HTTP 路由层（纯 I/O，不含业务逻辑）
│   ├── agent.py           AI Agent SSE 流式端点               ★
│   ├── bazi.py            八字 API 路由
│   ├── liuyao.py          六爻 API 路由
│   ├── qimen.py           奇门 API 路由
│   ├── fengshui.py        风水 API 路由
│   ├── date_selection.py  择日 API 路由
│   └── knowledge.py       知识库 API 路由
│
├── core/                  纯计算引擎（无 HTTP 依赖，可独立单元测试）
│   │
│   ├── constants.py       全局常量库（天干/地支/五行/十神/纳音/神煞等）
│   │
│   ├── bazi/              四柱八字
│   │   ├── chart.py       排盘（立春/五虎遁/五鼠遁算法）
│   │   ├── analyzer.py    十神/格局/神煞分析
│   │   ├── forecaster.py  大运/流年/流月推算（精确日数折算）
│   │   ├── applications.py  命理实际应用建议
│   │   └── day_master_profiles.py  日主性格特征库（10 种日主）
│   │
│   ├── liuyao/            六爻占卜
│   │   ├── divination.py  铜钱/蓍草/时间/手动起卦
│   │   ├── hexagram_data.py  六十四卦完整数据（卦名/卦辞/爻辞）
│   │   ├── interpreter.py    卦象解读（12 主题自动匹配古籍规则）
│   │   └── najia.py       纳甲系统（世应/六亲/六兽）
│   │
│   ├── qimen/             奇门遁甲
│   │   ├── algorithm.py   三元九局核心算法（阳遁/阴遁/局数/九宫布局）
│   │   ├── analyzer.py    九宫综合分析
│   │   └── purpose_analysis.py  用途分析（6 主题 + 三奇六仪矩阵）
│   │
│   ├── fengshui/          风水
│   │   ├── calculator.py  命卦/宅卦/八宅方位吉凶
│   │   └── flying_stars.py  玄空飞星（九星属性/年飞星/化煞建议）
│   │
│   ├── date_selection/    择日
│   │   ├── selector.py    吉日筛选（6 种用途 × 多维条件）
│   │   └── twelve_officers.py  建除十二神推算
│   │
│   └── calendar/          历法工具
│       ├── ganzhi.py      干支推算（60 甲子索引计算）
│       └── solar_terms.py  节气计算（基于 ephem 高精度天文算法）
│
├── models/                Pydantic v2 数据模型
│   ├── common.py          通用基础模型
│   ├── bazi.py            八字模型（含 PillarDetail/DayunPeriod/LiunianDetail 等）
│   ├── liuyao.py          六爻模型（含 YaoDetail/DivinationResponse 等）
│   ├── qimen.py           奇门模型
│   └── fengshui.py        风水模型
│
├── knowledge/             古籍知识库
│   ├── manager.py         知识管理器（检索/过滤/格式化）
│   └── classical_texts.py  经典文本库              ★
│                           穷通宝鉴 / 滴天髓 / 三命通会 / 子平真诠
│                           增删卜易 / 卜筮正宗 / 奇门遁甲统宗
│                           阳宅三要 / 八宅明镜 / 协纪辨方
│
└── frontend/              React + Vite 前端
    ├── package.json
    ├── vite.config.js
    └── src/
        ├── pages/
        │   ├── Agent/         AI 顾问聊天（SSE 流式渲染）          ★
        │   ├── Bazi/          八字排盘与分析
        │   ├── LiuYao/        六爻占卜
        │   ├── QiMen/         奇门遁甲
        │   ├── FengShui/      风水分析
        │   ├── DateSelection/ 择日选择
        │   └── Knowledge/     古籍知识库浏览
        ├── components/        公共组件库
        ├── store/             状态管理
        └── api/client.js      API 请求封装

10. 开发指南 · Development Guide

本地开发模式 · Local Dev Mode

# 后端（热重载）
cd bagua_project_build
source .venv/bin/activate       # macOS/Linux
# .venv\Scripts\activate        # Windows
uvicorn main:app --reload --port 8888

# 前端（另开终端）
cd frontend
npm run dev

分层架构原则 · Layered Architecture Principles

api/       ← 只做 HTTP I/O，参数验证，调用 core 层
core/      ← 纯计算，无 HTTP 依赖，返回 dict / dataclass
models/    ← Pydantic schema，api 层用于序列化/反序列化
knowledge/ ← 静态文本，供 core 层和 agent 层引用

遵循此分层可确保 core/ 中的所有计算函数可独立进行单元测试。

新增 API 端点 · Adding a New Endpoint

1. 在 core/ 中实现纯计算逻辑（无任何 HTTP 依赖）
2. 在 models/ 中定义 Pydantic Request / Response 模型
3. 在 api/ 中创建路由文件，调用 core 层
4. 在 main.py 中注册新路由

扩展古籍知识库 · Extending the Knowledge Base

编辑 knowledge/classical_texts.py，按现有格式添加新条目：

NEW_TEXT_ENTRY = {
    "title": "古籍名称",
    "source": "书名",
    "content": [
        "原文片段一...",
        "原文片段二...",
    ]
}

代码规范 · Code Style

• Python：PEP 8，类型注解全覆盖，每模块含 docstring
• 命名：命理术语保留中文拼音（tiangan/dizhi/shishen），方法名英文
• 注释：关键算法附中英双语注释
• 提交：遵循 Conventional Commits 规范（见贡献指南）

11. 常见问题 · Troubleshooting

Windows

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

netstat -ano | findstr :8888
taskkill /f /pid <PID>

Get-Content $env:TEMP\bagua_run\backend.log  -Wait
Get-Content $env:TEMP\bagua_run\frontend.log -Wait

macOS / Linux

chmod +x start.sh

python3 --version   # 需要 3.10+

# macOS (Homebrew)
brew install python@3.11

# Ubuntu / Debian
sudo apt update && sudo apt install python3.11 python3.11-venv

cd frontend
rm -rf node_modules package-lock.json
npm cache clean --force
npm install

cd bagua_project_build
source .venv/bin/activate
python -m uvicorn main:app --reload --port 8888

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: YOUR_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5-20251001","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

12. 路线图 · Roadmap

• 紫微斗数 — 十四主星、十二宫位完整排盘
• 梅花易数 — 体用卦，数字/时间起卦
• 铁板神数 — 结合八字与序数推演
• 用户账号系统 — 本地命盘保存与历史记录
• 多语言界面 — 繁体中文 / English UI
• 移动端优化 — PWA 支持，响应式布局
• Docker 镜像 — 一键容器化部署
• 古籍扩充 — 更多经典文本片段入库
• PDF 导出 — 命盘报告导出与分享链接

13. 贡献指南 · Contributing

欢迎任何形式的贡献：Bug 修复、新功能、文档改进、古籍知识库扩充。
All contributions are welcome: bug fixes, new features, documentation, or knowledge base additions.

贡献流程 · Workflow

# 1. Fork 并克隆
git clone https://github.com/your-username/bagua-divination.git

# 2. 创建功能分支
git checkout -b feature/your-feature-name

# 3. 提交（遵循 Conventional Commits）
git commit -m "feat: add purple star astrology module"
git commit -m "fix: correct DaYun start age for yin-female chart"
git commit -m "docs: add LiuYao topic matching examples to README"

# 4. Push 并创建 Pull Request
git push origin feature/your-feature-name

提交规范 · Commit Convention

报告问题 · Reporting Issues

提交 Issue 请包含：操作系统及版本 · Python/Node.js 版本 · 完整错误日志 · 复现步骤

14. 许可证 · License

本项目基于 MIT 许可证 开源发布。
This project is released under the MIT License.

MIT License — Copyright (c) 2024-2026 Chinese Metaphysics Platform Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

免责声明 Disclaimer：本系统所有命理推演结果仅供文化研究与娱乐参考，不构成任何专业的医疗、法律、财务建议。传统命理学属中华文化遗产，请理性对待推演结果。
All divination results from this system are for cultural research and entertainment purposes only and do not constitute medical, legal, or financial advice. Traditional Chinese metaphysics is part of cultural heritage — please interpret results rationally.