| --- |
| title: FateForge |
| emoji: ☯ |
| colorFrom: indigo |
| colorTo: gray |
| sdk: docker |
| app_port: 7860 |
| pinned: false |
| license: mit |
| short_description: FateForge · 周易六爻 · 免登录 AI 命理 |
| --- |
| <p align="center"> |
| <a href="https://huggingface.co/spaces/sunye-cn/FateForge"> |
| <img src="https://img.shields.io/badge/🤗%20HF%20Spaces-Live-FFD21E?style=for-the-badge&logo=huggingface&logoColor=black" alt="HF Spaces"> |
| </a> |
| <img src="https://img.shields.io/badge/License-MIT-22C55E?style=for-the-badge" alt="MIT"> |
| <img src="https://img.shields.io/badge/🔌%20Off%20the%20Grid-Local%20Only-0EA5E9?style=for-the-badge" alt="Off the Grid"> |
| <img src="https://img.shields.io/badge/🎨%20Off--Brand-Custom%20Vue%20UI-A855F7?style=for-the-badge" alt="Off-Brand UI"> |
| <img src="https://img.shields.io/badge/📓%20Field%20Notes-Blog%20Published-F97316?style=for-the-badge" alt="Field Notes"> |
| </p> |
| |
| # FateForge |
|
|
| > 大衍之数五十,其用四十有九。缘主此来,所求何事? |
|
|
| **FateForge** 是一个把宋代水墨美学、周易六爻起卦、和小参数大语言模型三者揉在一起的 AI 命理 Web App。 |
| 缘主在首页写下心头的困惑,**六枚铜钱**经由一只静默的玄甲决定起伏;之后由本地 LLM(或 fallback 到本地卦象解读器)给出**直白答案 + 卦象缘由 + 心法建议**, |
| 所有画面以**水墨晕染、行楷、磬音**铺陈,像在翻一本会呼吸的古书。 |
|
|
| 本项目是 [Hugging Face 小型 LLM Hackathon](https://huggingface.co/blog/build-small-hackathon/fateforge-local-llm) 的参赛作品 —— 端到端跑在一个 **2B 参数的 GGUF 量化模型** 上, |
| 向"小模型也能撑起有温度的 AI 应用"这个命题交卷。 |
|
|
| --- |
|
|
| ## 🎥 一分钟演示 |
|
|
| 短视频: <https://www.tiktok.com/@sunye9811/video/7651775539107073310> |
|
|
| 项目心得及项目复盘: <https://huggingface.co/blog/build-small-hackathon/fateforge-local-llm> |
|
|
| --- |
|
|
| ## ✨ 项目亮点 |
|
|
| - **免登录 · 完全本地化** — 输入、起卦、解读、历史都只存在你本机的浏览器里 (`localStorage`),不上传任何云端。 |
| - **真·六爻起卦** — 三枚铜钱 (字=2, 背=3) 自下而上摇六次,生成 64 卦中的任意一卦,含动爻与变卦;卦名/卦辞/象传全部来自经典 (`require.md` 锁定)。 |
| - **7 档吉凶** — 大吉 / 吉 / 中平偏吉 / 中平 / 中平偏凶 / 凶 / 大凶,每一档有专属语气与界面色温 (木 / 火 / 土 / 金 / 水 五行晕染)。 |
| - **小模型优先** — 默认对接 `gemma-2-E2B-it-UD-Q4_K_XL.gguf` (2B 参数, GGUF 量化) 跑在本地 llama-server 上;离线时**自动降级**到 `interpret.py` 的本地卦象解读,仍能保留完整体验。 |
| - **解读深度结合用户问题** — LLM Prompt 强制要求每句话锚定在缘主问题里的具体人物/事件/时间;本地降级会先识别问题主题 (事业/财运/感情/...),给出针对该维度的建议。 |
| - **氛围即叙事** — 吉时页面是水墨金的"顺风"晕染;凶时是水墨红的"迷雾",中间一颗浅黄"遁其一"按钮像迷雾中的明灯;点击后按钮缓缓消失,蒙版揭开,心法一行行浮现 (clip-path 打字机揭示)。 |
| - **全站双语** — 右上角 `EN / 中` 实时切换,所有界面文字 + 卦名 + 卦辞 + LLM 解读语种都跟语言走。 |
|
|
| --- |
|
|
| ## 🖼️ 截图 / 录屏 |
|
|
| | 缘起 | 窥机 (龟甲) | 窥机 (铜钱) | 破迷 (吉) | 破迷 (凶·遁其一) | |
| |:---:|:---:|:---:|:---:|:---:| |
| | 填写问题 | 点龟壳六次 | 铜钱翻转 | 卦象 + 心法 | 蒙版 + 按钮居中 | |
|
|
| 短视频看 TikTok 链接,完整版心得看上面的 HF blog 链接。 |
|
|
| --- |
|
|
| ## 🏗️ 架构 |
|
|
| ``` |
| FateForge/ |
| ├── app.py # 入口: Gradio + FastAPI (HF Spaces Docker SDK) |
| ├── Dockerfile # python:3.11-slim, EXPOSE 7860 |
| ├── requirements.txt # fastapi, uvicorn, httpx, pydantic, gradio |
| ├── README.md # 你正在读的这篇 |
| ├── require.md # 需求规约: 64 卦表 / 7 档吉凶 / 文案质感 (锁版本) |
| └── fateforge/ |
| ├── __init__.py |
| ├── config.py # 端口 / LLM 端点 / 路径 |
| ├── constants.py # HEXAGRAMS (64 卦), HEX_LEVELS (7 档), LLM Prompt |
| ├── divination.py # 铜钱起卦 / 动爻 / 变卦 / 吉凶判定 |
| ├── llm.py # httpx 流式调用 llama-server (OpenAI 兼容) |
| ├── interpret.py # 本地降级解读器: 按问题主题给建议 |
| ├── server.py # FastAPI: /api/cast/seed, /api/read (SSE 流式) |
| └── static/ # 前端 SPA |
| ├── index.html # Vue 3 + Tailwind (CDN) |
| ├── style.css # 1400+ 行水墨主题 |
| ├── app.js # 1270+ 行 Vue 状态机 + i18n |
| └── assets/ # 龟甲 / 铜钱 / 按钮底图 (LFS) |
| ``` |
|
|
| --- |
|
|
| ## 🔮 四关卡流转 |
|
|
| ``` |
| 缘起 (yuanqi) → 窥机 (kuiji) → 破迷 (pomi) → (回到首页) |
| │ │ │ |
| 输入问题 龟壳 × 6 卦象 + 心法 |
| 铜钱 × 3 (动画) 吉时: 直接显示 |
| 六爻成形 凶时: "前路晦暗" → 遁其一按钮 |
| 点击 → 燃烧动画 → 心法浮现 |
| ``` |
|
|
| **吉/中平偏吉/大吉/中平** → 心法直接显示,底部出现"乾坤已定,且乘势启程"按钮 → 点击,模糊遮罩从左下角覆盖 → 返回首页。 |
|
|
| **凶/中平偏凶/大凶** → 解卦正文先被蒙版隐去(只隐约看到字形)→ 中央出现浅黄色"遁其一"按钮 → 点击,清脆磬音响起,按钮 1.2s 缓慢消失 → 蒙版 1s 揭开 → 心法从模糊 → 清晰 → 底部"乾坤未定,且循其一"按钮 → 点击,卡片像被清风吹散,退回首页。 |
|
|
| --- |
|
|
| ## 🚀 本地启动 |
|
|
| ```powershell |
| # 1. 安装依赖 |
| pip install -r requirements.txt |
| |
| # 2. (可选) 启动本地 LLM —— llama-server 默认监听 127.0.0.1:8080 |
| # 没起 LLM 也能跑 —— 会自动降级到 interpret.py |
| llama-server -m gemma-2-E2B-it-UD-Q4_K_XL.gguf --port 8080 |
| |
| # 3. 启动 FateForge |
| python app.py |
| # → 访问 http://127.0.0.1:7860 |
| ``` |
|
|
| ### 环境变量 |
|
|
| | 变量 | 默认值 | 说明 | |
| |---|---|---| |
| | `FATEFORGE_LLM_BASE_URL` | `http://127.0.0.1:8080` | llama-server 端点 | |
| | `FATEFORGE_LLM_MODEL` | `gemma-4-E2B-it-UD-Q4_K_XL.gguf` | 模型名 | |
| | `FATEFORGE_LLM_TIMEOUT` | `180` | 秒 | |
| | `FATEFORGE_HOST` | `0.0.0.0` | 监听地址 (HF Docker 必须 0.0.0.0) | |
| | `FATEFORGE_PORT` | `7860` | 端口 (HF 会注入 PORT, 自动同步) | |
|
|
| --- |
|
|
| ## 🤖 离线降级策略 |
|
|
| 为适配 HF Spaces 没有 GPU / llama-server 的现实, `/api/read` 在 LLM 不可达时会自动 fallback 到 `fateforge/interpret.py`: |
|
|
| 1. **基础卦象描述** — 沿用经典 64 卦的卦辞/象传 |
| 2. **吉凶判定** — `HEX_LEVELS` 表内置 64 卦 × 7 档吉凶的预设 |
| 3. **问题主题识别** — `detect_topic()` 匹配"事业/财运/感情/出行/健康/学业/家宅"关键词 |
| 4. **主题化建议** — `build_remedy()` 开头用 `既然缘主所问的是事业/功名,那接下来:` 锚定到问题维度,给出 1-3 条具体可落地的建议 |
| 5. **流式输出** — 即便降级, 也按字流式输出,前端仍能看到"水墨渗字"效果 |
|
|
| > 在 HF Spaces 上点开这个 Space, **LLM 离线也能完整体验**。 |
|
|
| --- |
|
|
| ## 🎨 视觉与交互细节 |
|
|
| - **五行晕染背景** — 缘起=木(淡青), 窥机=土(淡黄), 破迷=金/火(吉=金, 凶=火, 中平=土), 自渡=水(淡蓝)。每一页都是"从中心向外渐变淡"的水墨 radial-gradient。 |
| - **字体** — 标题用 `Ma Shan Zheng` 行楷,正文用 `KaiTi` 楷体,英文 fallback 到 `Noto Serif`。配色统一为"焦茶墨色 + 浅黄/浅青/浅金晕染",白底调试模式可看宣纸纹理。 |
| - **按钮** — 无边框,只有对应色系 (浅绿/浅黄/浅金) 的 4 层 box-shadow 呼吸光晕,悬停时呼吸加快。 |
| - **凶局过渡** — 蒙版用 `backdrop-filter: blur(22px) saturate(120%)` + 红色内晕, 按钮消失后蒙版 1s 揭开, 心法从焦茶渐变深墨色。 |
| - **手写体提示** — 用户疯狂连点龟壳时,前端数字不会变快 (避免视觉混乱),但后台 `totalTaps` 立即累加, 第 7 次弹水墨选择窗"缘主一卦只能摇六下哦"。 |
|
|
| --- |
|
|
| ## 📚 64 卦数据来源 |
|
|
| `require.md` 是项目的"圣经",锁版本维护: |
|
|
| - 卦序 (1-64) / 卦名 / 上下卦 / 卦辞 / 象传 |
| - 7 档吉凶分类 (大吉/吉/中平偏吉/中平/中平偏凶/凶/大凶) 与判定理由 |
| - 7 个等级对应的 LLM 语气与心法标签 (顺风借力 / 借风起帆 / 潜龙勿用 / 风雨欲来 等) |
| - 文案质感范例 (听天命 / 运在人为的句式与禁忌) |
|
|
| --- |
|
|
| ## 🛠️ 技术栈 |
|
|
| | 层 | 选型 | 理由 | |
| |---|---|---| |
| | 后端 | FastAPI + uvicorn | 异步 SSE 流式输出对接前端 ink-seep 打字机 | |
| | LLM 通信 | httpx (async) | 流式 SSE, 兼容 OpenAI /v1/chat/completions | |
| | 前端框架 | Vue 3 (CDN) | 无构建步骤, 直接运行 | |
| | 样式 | Tailwind CDN + 自写水墨 CSS | 1400+ 行手写 .ink-* 风格 | |
| | 字体 | Google Fonts (Ma Shan Zheng, KaiTi, Noto Serif) | 宋代 / 现代 衬线感 | |
| | 部署 | Docker SDK on HF Spaces | 0.0.0.0:7860, ENV 注入 | |
|
|
| --- |
|
|
| ## 📜 License |
|
|
| MIT |
|
|
