玄机先生 · AI 算命先生
一个前后端分离的 AI 算命先生项目。AI 扮演一位精通八字、六爻、梅花易数、塔罗、生命灵数、黄历择日、起名、解梦、合婚、抽签、数字测吉凶等中西方术数的算命先生，提供问感情、问财运、测事、起名、择日、解梦、做决策、看运势、心理安抚等服务。
核心原则：真把式，绝不做江湖骗子——所有「排盘」都由后端确定性算法精确计算，大模型只负责基于真实排盘数据做自然语言解读，绝不凭空编造干支、卦象。
功能特性
- 前端：原生 HTML / CSS / JavaScript，使用 axios 对接后端；玄学主题（深色墨底 + 金色点缀），移动端适配；支持 SSE 流式输出、Markdown 渲染、多会话历史、深色/浅色主题。
- 后端：使用 uv 管理 Python 项目，基于 FastAPI，对接 DeepSeek 大模型（
deepseek-flash 默认，关闭思考模式）。
- 术数排盘引擎（真实算法）：
- 八字四柱、五行、十神、纳音、大运（基于
lunar-python 历法内核）
- 六爻纳甲装卦（本卦/变卦/六亲/世应）
- 梅花易数（数字/时间/测字起卦）
- 塔罗牌（78 张、多牌阵）
- 生命灵数、黄历择日（宜忌/建除/冲煞/吉神方位）
- 解梦词典、起名（五行补益 + 五格数理 + 字义）、测名（姓名五格数理吉凶）、公司取名（行业 + 吉祥字商号）
- 设置：切换大模型（
deepseek-flash / deepseek-v4-pro）、自定义 API Key（无效自动回退默认 Key）。
- 对话数据：全部存浏览器 localStorage。
术数与适用场景
先生共掌握 15 门术数，各自对应不同的问题类型，互不替代（「测字」不是独立术数，而是梅花易数的一种起卦方式）：
| 术数 | 哪类问题会用它 |
|---|
| 📜 八字 | 问整体命理：性格、事业/财运/婚姻的长期走势、流年大运、起名补五行 |
| 🪙 六爻 | 问具体事情吉凶：项目能否成、该不该跳槽/合作、某段关系走向 |
| 🌸 梅花易数 | 想快速起卦测事：报数字、看时间、写个字（测字）皆可，不拘摇卦仪式 |
| 🎴 塔罗 | 问西式情感/心理/事业：牌阵深入解读倾向与建议 |
| 🔢 生命灵数 | 问性格、天赋、人生课题（西式数字） |
| 📅 黄历择日 | 选吉日/吉时：结婚、开业、搬家、签约 |
| 💭 解梦 | 解释梦境 |
| 📛 起名 | 给人生成名字（中/英/日）；填「旧名字」即为改名 |
| 📝 测名 | 测已有名字的吉凶运势 |
| 🏢 公司取名 | 给公司/店铺/品牌起商号（中/英/日） |
| 🏢 公司测名 | 测已有公司名的吉凶（中/英/日） |
| 💑 合婚 | 问两人配对：情侣/夫妻生肖五行日柱合不合 |
| 🎐 抽签 | 求签问吉凶：求一支签、每日运势、求方向 |
| 📱 数字测吉凶 | 测手机号/车牌号/门牌号的吉凶 |
| ♈ 星座 | 算星座、星座配对、星座运势（西式占星） |
术数算法原理
所有排盘均由后端 Python 确定性算法计算，大模型只负责基于真实数据做自然语言解读，绝不凭空编造。逐个说明如下（实现文件见 backend/app/divination/）。
1. 八字排盘（bazi.py）
适用场景：问整体命运、性格、事业/财运/婚姻的长期走势、流年大运；也用于起名时的五行补益参考。
基于 lunar-python 历法内核（含精确的农历、节气、干支纪日数据）。
- 历法：公历/农历互转；节气按天文计算（非查表）。
- 四柱：
- 年柱：以立春为岁首（非正月初一/元旦）。
- 月柱：以十二节令（立春、惊蛰…）为月界，月干按五虎遁推出。
- 日柱：干支纪日，连续循环推算，精确到日。
- 时柱：以十二时辰（子时 23:00 起）划分，时干按五鼠遁推出。
- 十神：以日干为「我」，与其余干支按五行生克定十神（比肩/劫财/食神/伤官/偏财/正财/七杀/正官/偏印/正印）。
- 纳音（六十甲子纳音五行）、藏干（地支藏干）、地势（十二长生）、旬空（旬中空亡）。
- 命宫 / 身宫 / 胎元 / 胎息：按古法推导。
- 大运：男命阳年、女命阴年顺排，否则逆排；按节气到出生时刻的差值算起运岁数，排 10 步大运。
- 五行统计：四柱八字的干支五行计数，标出缺失五行（仅作喜用神参考，非严格定论）。
2. 六爻纳甲（liuyao.py + bagua.py）
适用场景：问某件具体事情的吉凶成败——项目能否推进、该不该跳槽/合作、某段关系走向、近期某事得失。
自研算法，内置完整的 64 卦、八宫、纳甲数据表。
- 摇卦：三枚铜钱，花记 3、字记 2，三枚相加 → 6 老阴（动）、7 少阳、8 少阴、9 老阳（动）；自下而上摇 6 次得六爻。
- 本卦：6/8 为阴爻、7/9 为阳爻；变卦：动爻（6、9）阴阳反转。
- 装卦：
- 八宫卦：确定卦所属宫（乾/坎/艮/震/巽/离/坤/兑宫）与宫五行，进而定世爻、应爻位置。
- 纳甲：每爻按八纯卦纳甲表配地支。
- 六亲：以本宫五行为「我」，与爻地支五行生克 → 兄弟/父母/子孙/官鬼/妻财。
- 输出本卦、变卦、卦辞、大象、卦宫、世应、六爻纳甲六亲。
3. 梅花易数（meihua.py）
适用场景：想快速起卦测事、不拘摇卦仪式——报几个数字、看当前时间、或写一个字（测字）皆可起卦。
- 先天八卦数：乾 1、兑 2、离 3、震 4、巽 5、坎 6、艮 7、坤 8。
- 起卦：
- 数字起卦：第 1 数÷8 取余得上卦、第 2 数÷8 得下卦、第 3 数÷6 得动爻。
- 时间起卦：年支数 + 农历月 + 农历日得上卦；再加时辰数得下卦；总数÷6 得动爻。
- 测字起卦：输入 1~2 个汉字，按笔画数起卦（用简体笔画，以「数」入卦）。
- 互卦：本卦 2/3/4 爻为下互、3/4/5 爻为上互；变卦：动爻反转。
- 体用：动爻在下卦则上卦为体、下卦为用，反之亦然。
- 测字时附带每个字的笔画、五行（查字库）；拆字解义由大模型结合卦象与字义完成。
4. 塔罗牌（tarot.py）
适用场景：西式占卜，问感情、心理、事业的倾向与建议，牌阵可深入分析。
- 78 张：22 张大阿卡纳（愚者
世界）+ 56 张小阿卡纳（权杖/圣杯/宝剑/星币 × 数字 110 + 侍从/骑士/王后/国王）。
- 牌阵：单张、三牌（过去/现在/未来）、凯尔特十字（10 张）。
- 随机洗牌抽牌，每张随机定正/逆位，附正逆位含义。
5. 生命灵数（numerology.py）
适用场景：问性格、天赋、人生课题（西式数字）。
- 毕达哥拉斯灵数：生日的年月日各位数字相加，归位到 1~9（保留主数 11/22/33）。
- 姓名灵数：英文名按字母数（A=1…I=9，J=1…Z=8）求和归位。
6. 黄历择日（huangli.py）
适用场景：选吉日/吉时——结婚、开业、搬家、签约等择日择时。
基于 lunar-python：干支纪年月日、建除十二值星、九星、彭祖百忌、冲煞、宜忌、吉神凶煞、吉神方位（喜神/财神/福神/贵神）。另按**青龙十二神（黄道黑道）**排出当日十二时辰的吉时/凶时，支持择时。
7. 解梦（dream.py）
适用场景：解释梦境。
内置周公解梦关键词词典，对梦境文本做关键词匹配，命中即返回对应释义，供大模型结合上下文解读。
8. 起名（naming.py）
适用场景：给新生儿、自己或他人起名（中/英/日）；填「旧名字」即为改名（先测旧名、再推新名）。
- 中文：先由八字算五行缺失作补益方向，从姓名用字库按性别+五行+寓意筛选，组合成 2 字名，并计算五格数理（天格/人格/地格/外格/总格，按康熙笔画）。
- 英文：从英文名库返回候选（含音译与含义）。
- 日文：从日文名库返回候选（含含义）。
9. 测名（naming.py）
适用场景：测已有名字的吉凶运势。
- 中文/日文汉字：按康熙笔画算五格数理 + 五行 + 字义，判断吉凶。
- 英文：按毕达哥拉斯灵数（字母→数字）。
10. 公司取名（naming.py）
适用场景：给公司、店铺、品牌起商号（中/英/日）。
- 中文：内置公司吉祥字库（约 60 字，按兴旺/诚信/创新/通达/吉祥/财富/卓越/稳健 8 类标签），按行业+寓意组合 2~4 字商号（去重）。
- 英文/日文：前缀词 + 业务后缀词组合（如 Golden Tech、大和商事）。
11. 公司测名（naming.py）
适用场景：测已有公司名的吉凶（中/英/日）。
- 中文/日文汉字：拆字查康熙笔画、五行、寓意，算总笔画数理（字库外的字如实提示）。
- 英文：字母 → 毕达哥拉斯灵数。
12. 合婚（hehun.py）
适用场景：问两人配对——情侣/夫妻生肖、纳音、日柱、五行是否相合。
- 用
lunar-python 算两人四柱，对比生肖（六合/六冲/三合/相刑/相害）、年柱纳音生克、日柱天干地支关系、五行互补。
13. 抽签（chouqian.py）
适用场景：求签问吉凶、求一支签、每日运势、求方向。
- 内置中式签文库（上上/上吉/中吉/中平/中下/下签），随机抽一支，返回签文 + 解签。
- 说明：签文为项目整理的仿古签文，非观音灵签/关帝灵签等传统签书原文，供文化参考、不冒充传统签书。
14. 数字测吉凶（shuzi.py）
适用场景：测手机号、车牌号、门牌号等数字的吉凶。
- 数字五行（1~9、0 各配五行）+ 八星磁场（天医/生气/延年/伏位/绝命/五鬼/六煞/祸害）组合分析，判断吉凶。
15. 星座（xingzuo.py）
适用场景：算星座、星座配对、星座运势（西式占星）。
- 太阳星座：按出生月日查十二星座区间（完全确定性）。
- 星座配对：按四象（火土风水）相性规则（绝配/相合/相克/一般）。
- 星座运势：按四象给出爱情/事业/财运/健康 + 幸运色/幸运数字。
- 说明：月亮星座、上升星座、本命星盘需精确天文排盘，本项目不提供。
目录结构
fortune-teller/
├── backend/ # FastAPI 后端（uv 管理）
│ ├── pyproject.toml
│ ├── .python-version
│ ├── .env # 本地环境配置（含默认 Key，已 gitignore）
│ ├── .env.example
│ ├── requirements.txt # uv 导出
│ └── app/
│ ├── main.py # 入口：/api/chat、/api/health、术数接口、托管前端
│ ├── config.py # 配置（模型白名单、默认 Key 回退）
│ ├── schemas.py # 请求/响应模型
│ ├── persona.py # 算命先生系统提示词
│ ├── services/deepseek.py # 大模型调用（流式/非流式、模型/Key 切换）
│ └── divination/ # 术数排盘引擎（真实算法）
├── frontend/ # 前端静态资源
│ ├── index.html
│ ├── css/style.css
│ └── js/
│ ├── app.js
│ └── vendor/ # 本地 axios / marked / DOMPurify
├── render.yaml # Render 部署配置
└── README.md
快速开始
1. 安装 uv（如未安装）
pip install uv
2. 安装后端依赖并启动
cd backend
uv sync # 创建虚拟环境并安装依赖
uv run uvicorn app.main:app --reload --port 8000
浏览器访问 http://localhost:8000 即可（前端已由 FastAPI 一并托管）。
也可直接双击打开 frontend/index.html（file:// 协议），前端会自动把请求指向 http://localhost:8000，后端已开启 CORS。
配置说明
后端配置从 backend/.env 读取（缺省值见 app/config.py）：
| 变量 | 说明 | 默认值 |
|---|
DEEPSEEK_API_KEY | 默认 API Key | 见 .env |
DEEPSEEK_BASE_URL | API 地址 | https://api.deepseek.com |
DEEPSEEK_MODEL | 默认模型 | deepseek-flash |
HOST / PORT | 监听地址 | 0.0.0.0 / 8000 |
可选模型：deepseek-flash、deepseek-v4-pro（前端设置里可切换）。
API 接口
GET /api/health
健康检查，返回状态、默认模型与可选模型列表。
POST /api/chat
对话接口（流式 SSE / 非流式）。请求体：
{
"messages": [{ "role": "user", "content": "帮我看看今年的运势" }],
"model": "deepseek-flash",
"api_key": "",
"stream": true
}
术数排盘接口（均为 POST，返回确定性排盘结果）
| 接口 | 说明 |
|---|
/api/divination/bazi | 八字四柱排盘 |
/api/divination/liuyao | 六爻纳甲装卦 |
/api/divination/meihua | 梅花易数起卦 |
/api/divination/tarot | 塔罗抽牌 |
/api/divination/numerology | 生命灵数 |
/api/divination/huangli | 黄历/择日查询 |
/api/divination/dream | 解梦关键词匹配 |
/api/divination/naming | 起名（五行补益 + 五格） |
/api/divination/name_fortune | 测名（姓名五格数理 + 五行吉凶） |
/api/divination/company_naming | 公司取名（行业 + 吉祥字商号） |
/api/divination/company_name_fortune | 公司测名（已有公司名吉凶） |
/api/divination/hehun | 合婚（两人八字配对） |
/api/divination/chouqian | 抽签（签文占卜） |
/api/divination/shuzi | 数字测吉凶（手机号/车牌号） |
/api/divination/xingzuo | 星座（算星座/配对/运势） |
部署到 Render
方式一：Blueprint（推荐）
- 把本项目推送到 GitHub 仓库。
- 在 Render 新建 Blueprint，选择仓库，Render 会读取根目录的
render.yaml 自动创建 Web 服务。
- 确认环境变量
DEEPSEEK_API_KEY 已配置（render.yaml 中已写入默认值，可在 Render 面板覆盖）。
方式二：手动创建 Web Service
- Render 新建 Web Service，连接仓库。
- 配置：
- Root Directory：
backend
- Runtime：Python 3
- Build Command：
pip install -r requirements.txt
- Start Command：
uvicorn app.main:app --host 0.0.0.0 --port $PORT
- 添加环境变量
DEEPSEEK_API_KEY（值为你的 Key）。
注意事项
backend/.env 中的 API Key 属于敏感信息，已被 .gitignore 忽略，请勿提交到版本库。- 后端通过请求体
"thinking": {"type": "disabled"} 关闭模型思考模式（回复更直接、无思考延迟）。
- 前端依赖（axios/marked/DOMPurify）已本地化，无需联网加载 CDN。
- 关于严谨性：八字/黄历基于
lunar-python 历法库；六爻/梅花/塔罗/灵数/解梦/起名/合婚/抽签/数字为自研确定性算法；紫微斗数、奇门遁甲、大六壬、风水等需专业排盘/实地勘测，本项目未做自动排盘，AI 会如实说明、绝不编造。
- 测算工具按需发放：界面上测算工具不会一开始就显示，而是由 AI 先生了解需求后，判断需要哪项术数，再发放对应工具（回复末尾带
【工具：key】 标记，前端解析后显示）。咨询类问题不发放工具。
- 笔画基准说明：起名/测名的五格数理按康熙笔画（姓名学惯例）；测字起卦按简体（现代通用）笔画（以「数」入卦）。两者用途不同、基准各异，均已注明。库外字会如实提示。
- 传统术数仅供文化参考与心理疏导，不替代医疗、法律与投资决策。
