大明-IF (Ming Dynasty IF)

拨开历史迷雾，重塑帝国命途。基于大语言模型与 RAG 技术的明朝历史平行推演引擎。

📖 项目简介

大明-IF 是一款创新的历史仿真推演系统。它不仅是一个数据库，更是一个能够理解历史因果、模拟平行时空发展的“智能档案馆”。

本项目以明朝历史为核心，结合 Gemini CLI 强大的推理能力与 ChromaDB 向量知识库，允许用户在每一个关键的历史节点（如：靖难之役、土木堡之变、万历首辅更替等）投下“变量”，观测历史如何像繁花一般分叉生长。

---

✨ 核心特性

• 🏮 极简水墨审美 (Aesthetic Design) 采用“新国风”设计语言，结合 Tailwind CSS 与 玻璃拟态 (Glassmorphism) 布局。每一个界面都经过精心打磨，营造出如宣纸润墨般的沉浸式阅读体验。

• 📜 史实增强推演 (RAG-Powered) 内置数十万字的明代史料（参考《明实录》、《明史》等）。推演引擎在生成内容前会先行检索相关史实，确保每一条“IF”分支都符合当时的人物性格、地理环境与社会逻辑。

• 🛡️ 因果一致性守护 (Causality Shield) 针对大模型在长文本推演中容易出现的“幻觉”问题，本项目内置了严密的因果校验层。它能自动追踪角色状态（如：死亡名单、官职变迁），严防“死而复生”或“时空错位”等逻辑谬误。

• 🌿 动态分叉树 (Branching Timeline) 推演结果不再是线性的，而是以“历史树”的形式展现。你可以自由回溯到任何一个节点，开启完全不同的推演方向。

• 🎭 角色志 (Character Archive) 包含 500+ 位大明人物。每位角色均有精美的水墨风肖像及 AI 深度生成的生平传记（结合史实与推演状态）。

---

🛠️ 技术架构

• 后端: FastAPI (高性能 Python Web 框架)
• 模型: Gemini CLI (深度集成的管道式推理)
• 数据库: ChromaDB (向量检索增强) & SQLite (结构化存储)
• 前端: Vanilla JS + Tailwind CSS (新国风定制化 UI)
• 工程化: 遵循严密的 AI Engineering Memory 复盘机制，确保代码健壮性与安全性。

---

🚀 快速开始

1. 准备环境

确保安装了 Python 3.10+ 以及 Node.js (用于运行 Gemini CLI)。

# 1. 克隆仓库
git clone https://github.com/your-username/Ming-Dynasty-IF.git
cd Ming-Dynasty-IF

# 2. 创建并激活虚拟环境
python -m venv venv
.\venv\Scripts\activate  # Windows
source venv/bin/activate # Linux/macOS

# 3. 安装依赖
pip install -e .

2. 模型配置 (⚠️ 重要)

本项目默认不调用 REST API。推演任务通过本地 gemini 命令行工具执行。请确保您的终端已通过相关 CLI 工具完成登录（如 gemini login）。

3. 运行服务

请始终在项目根目录执行：

python run.py

访问：http://localhost:8000 即可开启推演之旅。

---

🏛️ 工程律令 (Project Tenets)

本项目在开发过程中严格遵守以下律令（详见 AI_Engineering_Memory.md）：

1. 根目录原则：所有执行路径必须从根目录出发，严禁子目录运行。
2. 鉴权优先：所有 API 请求必须经过 Auth.fetchWithAuth 封装。
3. 安全性：强制实施 XSS 脱敏与 SQL 树形越权防御 (VPE Defense)。
4. 审美契约：拒绝 Placeholder，追求极致的“新国风”视觉交互。

---

🤝 参与贡献

我们欢迎各位明史爱好者与开发者加入！无论是修正一个史实错误，还是优化一个推演 Prompt，亦或是贡献一张新的水墨立绘，都是我们宝贵的助力。

---

“史海浩瀚，变幻无穷。于微末之处，窥见大明。”