玄机先生 · 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（推荐）

1. 把本项目推送到 GitHub 仓库。
2. 在 Render 新建 Blueprint，选择仓库，Render 会读取根目录的 render.yaml 自动创建 Web 服务。
3. 确认环境变量 DEEPSEEK_API_KEY 已配置（render.yaml 中已写入默认值，可在 Render 面板覆盖）。

方式二：手动创建 Web Service

1. Render 新建 Web Service，连接仓库。
2. 配置：
   • 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
3. 添加环境变量 DEEPSEEK_API_KEY（值为你的 Key）。

注意事项

• backend/.env 中的 API Key 属于敏感信息，已被 .gitignore 忽略，请勿提交到版本库。
• 后端通过请求体 "thinking": {"type": "disabled"} 关闭模型思考模式（回复更直接、无思考延迟）。
• 前端依赖（axios/marked/DOMPurify）已本地化，无需联网加载 CDN。
• 关于严谨性：八字/黄历基于 lunar-python 历法库；六爻/梅花/塔罗/灵数/解梦/起名/合婚/抽签/数字为自研确定性算法；紫微斗数、奇门遁甲、大六壬、风水等需专业排盘/实地勘测，本项目未做自动排盘，AI 会如实说明、绝不编造。
• 测算工具按需发放：界面上测算工具不会一开始就显示，而是由 AI 先生了解需求后，判断需要哪项术数，再发放对应工具（回复末尾带 【工具：key】 标记，前端解析后显示）。咨询类问题不发放工具。
• 笔画基准说明：起名/测名的五格数理按康熙笔画（姓名学惯例）；测字起卦按简体（现代通用）笔画（以「数」入卦）。两者用途不同、基准各异，均已注明。库外字会如实提示。
• 传统术数仅供文化参考与心理疏导，不替代医疗、法律与投资决策。