# StarRailKG

**Repository Path**: CloseRecover/star-rail-kg

## Basic Information

- **Project Name**: StarRailKG
- **Description**: 浙江大学知识图谱课程期末大作业项目
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-19
- **Last Updated**: 2025-12-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 崩坏：星穹铁道 知识图谱应用

<div align="center">

**基于Neo4j的《崩坏：星穹铁道》角色与装备关系智能问答系统**

[![License](https://img.shields.io/badge/license-木兰2-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.8+-green.svg)](https://www.python.org/)
[![Neo4j](https://img.shields.io/badge/neo4j-5.0+-orange.svg)](https://neo4j.com/)
[![Vue](https://img.shields.io/badge/vue-3.2-brightgreen.svg)](https://vuejs.org/)

</div>

---

## 📖 项目介绍

《崩坏：星穹铁道》（StarRail） 是米哈游开发的一款"崩坏"系列星际冒险主题的回合制角色扮演游戏。玩家扮演"开拓者"乘坐星穹列车穿梭宇宙，探索不同世界并解决"星核"引发的危机。

本项目构建了一个基于知识图谱的智能问答系统，对游戏中的**角色（Character）**、**光锥（Lightcone）**、**材料（Material）**、**命途（Path）**、**阵营（Faction）**等实体及其关系进行建模，实现了基于自然语言的游戏信息检索和推荐功能。

### 核心特性

- 🕷️ **数据爬取**：从B站Wiki自动爬取游戏数据
- 🔄 **数据处理**：自动修复数据缺失和重复问题
- 🗄️ **知识图谱**：使用Neo4j云数据库存储实体关系
- 🤖 **智能问答**：支持自然语言查询游戏信息
- 🎨 **可视化**：提供Web界面进行交互式查询
- 📊 **统计分析**：支持阵营、命途等维度的数据统计

---

## 🛠️ 技术栈

### 后端
- **Python 3.8+** - 核心开发语言
- **Flask** - 轻量级Web框架
- **Neo4j** - 图数据库（云部署）
- **Scrapy** - 数据爬取框架
- **Pandas** - 数据处理

### 前端
- **Vue 3** - 前端框架
- **Vite** - 构建工具
- **Bootstrap 5** - UI组件库
- **Axios** - HTTP客户端

### 数据库
- **Neo4j Aura** - 云端图数据库
  - URI: `neo4j+s://78a2c543.databases.neo4j.io`
  - 在线控制台: https://console.neo4j.io

---

## 📁 项目结构

```
star-rail_-kg/
├── StarRail/                      # 知识图谱数据
│   ├── properties/               # 实体属性CSV
│   │   ├── characters.csv       # 80个角色数据 ✅
│   │   ├── lightcones.csv       # 149个光锥数据
│   │   ├── materials.csv        # 114个材料数据
│   │   ├── paths.csv            # 7个命途 ✅ (已去重)
│   │   └── factions.csv         # 18个阵营数据
│   └── relations/               # 关系CSV
│       ├── character2path.csv   # 角色-命途关系 ✅
│       ├── character2faction.csv # 角色-阵营关系
│       ├── lightcone2path.csv   # 光锥-命途关系 ✅
│       ├── lightcone2material.csv # 光锥-材料关系
│       └── material2material.csv # 材料同类关系
│
├── starrail_wiki_spider/         # Scrapy爬虫模块
│   ├── data/                    # 爬取的JSON数据
│   │   ├── character.json
│   │   ├── lightcone.json
│   │   └── material.json
│   ├── spiders/                 # 爬虫脚本
│   ├── json2csv.py             # JSON转CSV
│   ├── json2relation.py        # 关系提取
│   └── README.md               # 爬虫使用说明
│
├── ToNeo4j/                      # Neo4j数据导入模块
│   ├── import_to_neo4j.py      # 数据导入脚本 ⭐
│   ├── query_examples.py       # 查询示例
│   ├── test_connection.py      # 连接测试
│   ├── fix_character_names.py  # 角色名修复脚本
│   ├── fix_duplicate_paths.py  # Path去重脚本
│   └── DATA_FIX_SUMMARY.md     # 数据修复总结 📄
│
├── back_end/                     # Flask后端服务
│   ├── app.py                  # Flask应用入口
│   ├── db.py                   # Neo4j连接配置
│   ├── handler.py              # 查询处理器
│   ├── query_examples.py       # 查询示例库
│   └── requirements.txt        # Python依赖
│
├── front_end/                    # Vue前端应用
│   ├── src/                    # 源代码
│   │   ├── App.vue
│   │   ├── components/
│   │   └── views/
│   ├── public/                 # 静态资源
│   ├── package.json            # npm依赖
│   └── vite.config.js          # Vite配置
│
├── starrail.jsonld              # JSON-LD知识图谱
├── requirements.txt             # 项目依赖
├── LICENSE                      # MIT许可证
└── README.md                    # 本文档

✅ = 已修复/优化的文件
⭐ = 核心文件
📄 = 重要文档
```

---

## 📊 数据统计

### 知识图谱规模

| 实体类型 | 数量 | 说明 |
|---------|------|------|
| 角色 (Character) | 80 | 游戏可玩角色，name字段已全部填充 |
| 光锥 (Lightcone) | 149 | 角色装备的武器 |
| 材料 (Material) | 114 | 角色和光锥升级材料 |
| 命途 (Path) | 7 | 角色/光锥的路径分类（已去重） |
| 阵营 (Faction) | 18 | 角色所属组织 |
| **总节点数** | **368** | |

### 关系统计

| 关系类型 | 数量 | 说明 |
|---------|------|------|
| 角色→命途 | 66 | Path ID已统一 |
| 角色→阵营 | 79 | |
| 光锥→命途 | 127 | Path ID已统一 |
| 光锥→材料 | 438 | 升级需求材料 |
| 材料→材料 | 3,753 | 同类素材关系 |
| **总关系数** | **4,463** | |

---

## 🚀 快速开始

### 环境要求

- Python 3.8+
- Node.js 16+ 和 npm
- Neo4j Aura账号（已配置云数据库）

### 1. 克隆项目

```bash
git clone <repository-url>
cd star-rail_-kg
```

### 2. 安装依赖

#### Python依赖（后端）
```bash
# 激活虚拟环境
source /root/kg/kghw/bin/activate

# 安装依赖
pip install -r requirements.txt
```

#### Node依赖（前端）
```bash
cd front_end
npm install
```

### 3. 导入数据到Neo4j

**重要**：数据已经修复并优化，可直接导入。

```bash
# 激活虚拟环境
source /root/kg/kghw/bin/activate

# 测试数据库连接
cd ToNeo4j
python test_connection.py

# 导入数据（会清空现有数据）
python import_to_neo4j.py
```

导入完成后会显示：
```
=== 数据库统计信息 ===
角色节点: 80
光锥节点: 149
材料节点: 114
命途节点: 7
阵营节点: 18
总关系数: 4463

数据导入完成!
```

### 4. 验证数据

运行查询示例验证数据完整性：

```bash
python query_examples.py
```

---

## 💻 运行应用

### 方式一：仅后端（API服务）

```bash
# 激活虚拟环境
source /root/kg/kghw/bin/activate

# 启动Flask服务器
cd back_end
python app.py
```

服务器将运行在 `http://localhost:5001`

**API端点**：
- `GET /` - 健康检查
- `POST /query` - 自然语言查询接口

### 方式二：前后端完整应用

#### 启动后端（终端1）
```bash
source /root/kg/kghw/bin/activate
cd back_end
python app.py
```

#### 启动前端（终端2）
```bash
cd front_end
npm run dev
```

前端应用将运行在 `http://localhost:5173`（Vite默认端口）

### 方式三：使用Neo4j Browser

直接访问Neo4j在线控制台进行可视化查询：
1. 访问 https://console.neo4j.io
2. 登录并选择实例 "My instance"
3. 打开 Neo4j Browser
4. 运行Cypher查询

---

## 🔍 支持的查询

### 关于角色的查询

| 问题 | 示例 |
|------|------|
| 某角色属于什么命途？ | "停云属于什么命途" |
| 某角色属于什么阵营？ | "景元属于什么阵营" |
| 哪些角色属于某命途？ | "哪些角色属于同谐命途" |
| 哪些角色属于某阵营？ | "哪些角色属于仙舟罗浮阵营" |
| 某角色的详细信息？ | "三月七的详细信息是什么" |

### 关于光锥的查询

| 问题 | 示例 |
|------|------|
| 某光锥适用什么命途？ | "但战斗还未结束光锥适用什么命途" |
| 哪些光锥适用某命途？ | "哪些光锥适用巡猎命途" |
| 某光锥需要哪些材料？ | "于夜色中光锥需要哪些材料" |

### 关于材料的查询

| 问题 | 示例 |
|------|------|
| 某材料的详细信息？ | "万相果实材料的详细信息" |
| 某材料的同类素材？ | "一曲合弦的幻景材料的同类素材有哪些" |

### 复杂组合查询

| 问题 | 示例 | 说明 |
|------|------|------|
| 某角色可用哪些光锥？ | "停云可以使用哪些光锥" | 基于命途匹配 |
| 各阵营角色数量统计 | "各阵营的角色数量统计" | 聚合统计 |
| 各命途角色数量统计 | "各命途的角色数量统计" | 聚合统计 |

### Cypher查询示例

```cypher
// 查询停云可用的光锥（基于命途匹配）
MATCH (c:Character)-[:属于命途]->(p:Path)<-[:适用命途]-(l:Lightcone)
WHERE c.name CONTAINS '停云'
RETURN c.name as 角色, p.name as 命途, collect(l.name) as 可用光锥

// 查询仙舟罗浮的所有5星角色
MATCH (c:Character)-[:属于阵营]->(f:Faction)
WHERE f.name = '仙舟「罗浮」' AND c.rarity = '5星'
RETURN c.name, c.releaseDate
ORDER BY c.releaseDate

// 统计各命途的角色数量
MATCH (c:Character)-[:属于命途]->(p:Path)
RETURN p.name as 命途, count(c) as 角色数量
ORDER BY 角色数量 DESC
```

---

## 🔧 开发指南

### 数据爬取（可选）

如果需要重新爬取数据：

```bash
# 激活虚拟环境
source /root/kg/kghw/bin/activate

# 运行爬虫
cd starrail_wiki_spider
scrapy crawl starrail_spider

# 转换为CSV
python json2csv.py

# 提取关系
python json2relation.py
```

详见 `starrail_wiki_spider/README.md`

### 数据修复

项目已包含数据修复脚本，解决了以下问题：

#### ✅ 已修复的问题

1. **角色名称缺失** - 44个角色的name字段为空
   - 修复脚本：`ToNeo4j/fix_character_names.py`
   - 修复脚本：`ToNeo4j/manual_fix_names.py`
   - 状态：✅ 所有80个角色名已填充

2. **Path节点重复** - 导致组合查询失败
   - 修复脚本：`ToNeo4j/fix_duplicate_paths.py`
   - 状态：✅ 从14个节点减少到7个

3. **材料查询问题** - 精确匹配失败
   - 修复：使用CONTAINS模糊匹配
   - 状态：✅ 查询已优化

详见 `ToNeo4j/DATA_FIX_SUMMARY.md`

### 添加新查询模式

编辑 `back_end/handler.py`：

```python
patterns = [
    '你的新问句模式(.+)',
    # ...
]

queries = [
    """
    你的Cypher查询语句
    """,
    # ...
]
```

### 前端开发

```bash
cd front_end

# 开发模式（热重载）
npm run dev

# 构建生产版本
npm run build

# 预览生产版本
npm run preview
```

---

## 📚 相关文档

- [数据修复总结](ToNeo4j/DATA_FIX_SUMMARY.md) - 数据问题诊断与修复过程
- [爬虫使用说明](starrail_wiki_spider/README.md) - 数据爬取和处理指南
- [Neo4j官方文档](https://neo4j.com/docs/) - 图数据库参考
- [Cypher查询语言](https://neo4j.com/docs/cypher-manual/) - 查询语法
- [Flask文档](https://flask.palletsprojects.com/) - 后端框架
- [Vue 3文档](https://vuejs.org/) - 前端框架

---

## ⚠️ 注意事项

### 数据库连接

- 当前使用Neo4j Aura免费版（2GB内存 + 4GB存储）
- 连接信息配置在 `back_end/db.py` 和 `ToNeo4j/import_to_neo4j.py`
- ⚠️ **请勿将密码提交到公开仓库**，建议使用环境变量

### 数据质量

- 数据来源于B站Wiki（https://wiki.biligame.com/sr/）
- 部分角色数据可能不完整（gender, combatType等字段）
- 定期更新可能需要重新爬取数据

### 性能优化

- 免费版Neo4j有资源限制，复杂查询可能较慢
- 使用 `LIMIT` 限制返回结果数量
- 为常用查询字段创建索引（项目已自动创建约束）

---

## 🎯 后续优化建议

### 数据层面
- [ ] 补充缺失的角色属性（gender, combatType等）
- [ ] 添加角色-材料关系（升级需求）
- [ ] 完善材料的description和intro字段
- [ ] 定期更新游戏新版本数据

### 功能层面
- [ ] 实现更多复杂查询（路径寻找、关系推荐）
- [ ] 添加图算法分析（中心性、社区发现等）
- [ ] 实现真正的自然语言理解（集成NLP模型）
- [ ] 添加角色推荐系统（基于命途和阵营）

### 工程层面
- [ ] 使用环境变量管理数据库密码
- [ ] 添加单元测试
- [ ] 实现前端UI优化
- [ ] 部署到云服务器（Vercel/Heroku）
- [ ] 添加API文档（Swagger）

---

## 🤝 贡献

欢迎提交Issue和Pull Request！

### 开发流程

1. Fork本仓库
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交Pull Request

---

## 📄 许可证

本项目采用 木兰2 许可证 - 详见 [LICENSE](LICENSE) 文件

---

## 👥 作者

- 知识图谱构建与数据修复
- Flask后端开发
- Neo4j数据库设计

---

## 🙏 致谢

- 数据来源：[B站游戏Wiki](https://wiki.biligame.com/sr/)
- 游戏开发：米哈游
- 图数据库：Neo4j

---

## 📞 联系方式

- 项目主页：<repository-url>
- 问题反馈：[Issues](issues)
- Neo4j控制台：https://console.neo4j.io

---

<div align="center">

**⭐ 如果这个项目对你有帮助，请给一个Star！⭐**

Made with ❤️ for StarRail Players

</div>