NBA球迷大全 v1.0.0：对话问答+数据浏览系统（DeepSeek+RAG+SQLite）

README.md

@@ -0,0 +1,113 @@
+# 🏀 NBA球迷大全
+
+面向球迷的 NBA 信息问答系统：对话即可查询比赛、球员、球队、新闻、人物、百科等准确信息。
+基于 **大模型（DeepSeek）+ 结构化查询（SQLite）+ RAG 向量检索（Chroma + bge-large-zh）** 混合架构，
+数据全部来自内置数据库，回答准确可溯源。
+
+## ✨ 功能
+
+- 💬 **智能对话**：自然语言提问，自动路由到数据库/向量库，返回带来源的准确回答
+  - 例：「2026年总决赛谁赢了」「库里本赛季场均数据」「约基奇和字母哥谁得分多」「雷霆为什么能夺冠」
+- 🏟️ **数据浏览**：球队 / 球员 / 比赛（含技术统计）/ 新闻 / 人物 / 排名 六大浏览页面
+- 🧠 **RAG 检索**：新闻与百科向量化存储，语义检索 + Rerank 精排
+- 🔧 **Function Calling**：8 个查询工具（球队/球员/比赛/单场详情/排名/新闻/人物/百科），多轮工具调用 + 实体覆盖补全
+- 🧵 **多轮对话**：支持上下文指代（「他拿过几个MVP？」→ 上一话题对象）
+
+## 🏗️ 系统架构
+
+```
+用户提问
+  │
+  ▼
+┌─────────────┐   工具调用(8个)   ┌──────────────────┐
+│  DeepSeek    │ ───────────────► │  tools.py 查询层   │
+│  deepseek-   │ ◄─────────────── │  · SQLite 结构化   │
+│  v4-flash    │   工具结果回填    │  · Chroma 向量检索  │
+└─────────────┘                  └──────────────────┘
+      │ 最终答案（数据准确 + 来源标注）
+      ▼
+  前端（对话 + 数据浏览）
+```
+
+| 模块 | 技术 | 说明 |
+|------|------|------|
+| 对话大脑 | DeepSeek `deepseek-v4-flash`（函数调用） | 意图理解、工具选择、答案生成 |
+| 结构化数据 | SQLite（本地） | 球队/球员/比赛/统计/排名/新闻/人物 |
+| 向量检索 | Chroma（16010，REST） | 新闻/百科语义检索（cosine） |
+| Embedding | bge-large-zh-v1.5（16011，1024维） | 中文语义向量 |
+| Rerank | bge-reranker-v2-m3（16011） | 检索精排（可选） |
+| 前端 | 原生 HTML/JS（无构建） | 深色球赛风，对话 + 六大浏览页 |
+
+## 📁 目录结构
+
+```
+nba-fan-hub/
+├── api.py            # Flask 服务（REST API + 静态页）
+├── chat.py           # 对话管线（工具路由 + 兜底 + 覆盖补全）
+├── tools.py          # 8 个查询工具（SQL + 向量），含绰号别名/模糊匹配
+├── llm.py            # DeepSeek 调用（思考模式 reasoning_content 回传）
+├── vector_store.py   # Embedding + Chroma + Rerank（纯 REST，零额外依赖）
+├── db.py             # SQLite 连接与建表
+├── seed.py           # 种子数据入口（幂等，可 --rebuild-vector）
+├── seed_*.py         # 模拟数据（30队/154球员/54比赛/46新闻百科/38人物）
+├── static/           # 前端页面
+├── data/             # nba_fan.db（自动生成）
+└── start.sh          # 启停脚本（start/stop/restart/status/seed）
+```
+
+## 🚀 快速开始
+
+```bash
+# 1. 灌数据（首次或数据更新后）
+./start.sh seed              # 或 python3 seed.py --rebuild-vector
+
+# 2. 启动
+./start.sh start             # http://<IP>:16090
+./start.sh status            # 查看状态
+```
+
+依赖：`flask`、`requests`（openclaw conda 环境已具备）。外部依赖服务：
+- 大模型：DeepSeek API（key 配置于 `config.py`）
+- 向量库：Chroma @ `121.40.164.32:16010`
+- Embedding/Rerank：@ `121.40.164.32:16011`
+
+## 🔌 REST API
+
+| 接口 | 说明 |
+|------|------|
+| `POST /api/chat` | 对话 `{message, history}` → `{reply, sources, used_tools}` |
+| `GET /api/teams[?q=]` `GET /api/teams/<id>` | 球队列表/详情（含阵容+近期比赛） |
+| `GET /api/players[?q=]` `GET /api/players/<id>` | 球员列表/详情 |
+| `GET /api/games[?q=&status=]` `GET /api/games/<id>` | 比赛列表/详情（含技术统计） |
+| `GET /api/standings?conf=西部/东部` | 排名 |
+| `GET /api/news[?q=&kind=]` `GET /api/news/<id>` | 新闻/百科 |
+| `GET /api/persons[?q=&role=]` | 人物（coach/commentator/host/agent/gm/legend） |
+| `GET /api/health` | 健康检查 + 数据统计 |
+
+## 🧩 扩展设计（重点）
+
+数据库采用「运动-联赛-球队-球员」分层，新增球类/联赛/人物角色无需改代码：
+
+| 扩展需求 | 怎么做 |
+|----------|--------|
+| **新增 CBA** | `sports` 已含 basketball；`leagues` 表加一行 `CBA`，灌入 CBA 球队/球员/比赛即可，全部工具自动生效 |
+| **新增足球** | `sports` 表加 `football`；`leagues` 加英超/西甲等；球员/球队表字段通用（位置、数据字段可增列） |
+| **新增人物角色**（教练/经纪人/评论员/主持人/总经理/球探…） | `persons.role` 是自由字符串，新增角色直接入库即可 |
+| **新增查询工具** | `tools.py` 加一个函数 + 注册进 `TOOLS`/`TOOL_HANDLERS` 即自动接入对话 |
+| **向量库隔离** | Chroma 按集合名隔离（`nba_fan_knowledge_v1` → `cba_...`），互不影响 |
+| **数据更新** | 修改 `seed_*.py` 后 `./start.sh seed --rebuild-vector` 一键重建 |
+
+## 🧠 对话管线要点
+
+1. **工具优先**：系统提示词强制「数据问题先查库」，8 个工具返回结构化 JSON
+2. **思考模式兼容**：DeepSeek 思考模型要求回传 `reasoning_content`，已处理
+3. **文本工具调用兜底**：模型偶尔把工具调用写成正文，正则解析 + 未知工具名智能映射
+4. **实体覆盖补全**：多实体问题（「约基奇和字母哥…」）自动拆词补查，杜绝漏数据
+5. **多层兜底**：LLM 异常 → 关键词预检索注入；最终轮仍异常 → 工具结果摘要
+6. **诚实原则**：查不到如实说明，常识补充与数据库数据明确区分
+
+## 📊 数据规模（模拟数据，2025-26 赛季）
+
+30 支球队 · 154 名球员（含绰号别名）· 54 场比赛（常规赛/季后赛/总决赛/夏季联赛）· 93 条技术统计 · 46 篇新闻/百科 · 38 位人物
+
+> ⚠️ 数据为演示用模拟数据（2026 总决赛剧情：雷霆 4-2 凯尔特人，SGA FMVP），接入真实数据源时仅需替换 seed 数据。