# MiroFish Neo4j 二开版
[English](./README.md) | 中文
本项目基于原始开源仓库 [666ghj/MiroFish](https://github.com/666ghj/MiroFish) 进行二次开发。
本版本的核心改动是：将原项目中的 Zep Cloud 图谱记忆与检索依赖替换为本地 Neo4j 后端，使项目可以使用本地图数据库完成实体关系存储、图谱检索、报告工具调用和模拟后的记忆更新，同时保留原 MiroFish 的多智能体模拟流程。
本项目遵守原仓库一致的开源协议：**AGPL-3.0**。
## 主要改动
- 使用本地 Neo4j 替代 Zep Cloud 图谱存储与检索。
- 新增 Neo4j 图谱构建、实体读取、记忆更新和搜索服务。
- 新增图数据库后端工厂，支持按配置切换图谱后端。
- 修复并增强报告工具输出：
- Deep Insight
- Panorama Search
- Quick Search
- 新增 LLM 429 限流等待与重试逻辑。
- 新增足球场景的比分概率计算与报告注入。
- 新增本地 Neo4j Docker Compose 配置。
## 功能说明
- 上传种子文档并抽取实体关系。
- 将抽取结果写入本地 Neo4j 图谱。
- 生成模拟 Agent 和社交行为配置。
- 运行双平台社交模拟。
- 基于图谱检索生成预测报告。
- 在足球比赛场景中输出胜平负概率、最可能比分、期望进球和比分矩阵。
## 项目结构
```text
frontend/ Vue + Vite 前端
backend/ Flask 后端
backend/app/services/ 模拟、报告、图谱与适配服务
backend/app/services/adapters/
Neo4j 图谱适配实现
backend/app/utils/neo4j/ Neo4j 驱动与 Schema 工具
locales/ 多语言文案
static/ 静态图片资源
```
## 环境要求
- Node.js 18+
- Python 3.11 - 3.12
- uv
- Docker（用于快速启动 Neo4j）
- 一个兼容 OpenAI SDK 格式的 LLM API Key
## 环境变量配置
复制示例文件：
```bash
cp .env.example .env
```
最小本地配置示例：
```env
LLM_API_KEY=your_api_key_here
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL_NAME=qwen-plus
GRAPH_BACKEND=neo4j
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=password
NEO4J_DATABASE=neo4j
```
可选的 LLM 限流重试配置：
```env
LLM_RATE_LIMIT_MAX_ATTEMPTS=20
LLM_RATE_LIMIT_INITIAL_DELAY=30
LLM_RATE_LIMIT_MAX_DELAY=180
LLM_RATE_LIMIT_BACKOFF_FACTOR=1.5
```
## 启动 Neo4j
项目提供了本地 Neo4j 的 Docker Compose 文件：
```bash
docker compose -f docker-compose.neo4j.yml up -d
```
默认地址：
- Neo4j Browser：`http://localhost:7474`
- Bolt URI：`bolt://localhost:7687`
- 默认账号：`neo4j / password`
请确保 `.env` 中的 `NEO4J_PASSWORD` 与 Docker Compose 中配置的密码一致。
## 安装依赖
一次性安装前后端依赖：
```bash
npm run setup:all
```
也可以分开安装：
```bash
npm run setup
npm run setup:backend
```
## 运行项目
同时启动前端和后端：
```bash
npm run dev
```
服务地址：
- 前端：`http://localhost:3000`
- 后端 API：`http://localhost:5001`
单独启动：
```bash
npm run backend
npm run frontend
```
## Docker 运行
根目录的 `docker-compose.yml` 可用于启动应用容器。若使用本地 Neo4j 图谱后端，建议先启动 Neo4j：
```bash
docker compose -f docker-compose.neo4j.yml up -d
```
再启动应用：
```bash
docker compose up -d
```
默认会读取根目录下的 `.env`，并映射端口 `3000（前端）/5001（后端）`。
## 基本使用流程
1. 启动 Neo4j。
2. 启动后端和前端。
3. 打开 `http://localhost:3000`。
4. 创建或打开项目。
5. 上传种子文档。
6. 构建图谱。
7. 生成模拟配置。
8. 启动模拟。
9. 生成预测报告。
## 报告检索工具
报告 Agent 可以调用以下图谱检索工具：
- **Deep Insight**：将问题拆解为多个子问题，并收集相关事实、实体和关系链。
- **Panorama Search**：返回图谱中的全景实体和事实。
- **Quick Search**：对图谱事实、节点名称和节点摘要进行轻量关键词搜索。
- **Interview Agents**：结合模拟或图谱上下文生成面向 Agent 的回答。
在 Neo4j 二开版中，检索工具会输出前端可直接解析的文本结构，因此报告时间线能够展示事实、实体和关系链，而不是空白 JSON。
## 足球比分概率报告
当模拟需求或种子数据包含足球、比分、泊松、lambda、xG、expected goals 等信号时，后端会尝试抽取：
- `lambda_home`
- `lambda_away`
- xG / expected goals
- 主客队信息
并生成：
- 主胜 / 平局 / 客胜概率
- 最可能比分 Top Scorelines
- 期望进球
- 比分概率矩阵
该部分会作为确定性计算结果注入报告，避免报告只停留在 LLM 的泛化描述。
## 日志位置
常用本地日志：
```text
log/backend-restart.out.log
log/backend-restart.err.log
log/frontend-direct.out.log
log/frontend-direct.err.log
backend/uploads/reports//agent_log.jsonl
backend/uploads/reports//console_log.txt
```
## 常见问题
### Neo4j 连接失败
确认 Neo4j 已启动，并检查 `.env` 中的 Neo4j 配置是否与 Docker Compose 一致。
```bash
docker compose -f docker-compose.neo4j.yml ps
```
### LLM 返回 429
后端已内置限流重试逻辑。遇到 429 时会根据 `LLM_RATE_LIMIT_*` 配置等待后继续重试。
### Deep Insight / Panorama Search / Quick Search 内容为空
请确认项目已经成功构建图谱。Neo4j 检索会搜索关系事实、节点名称和节点摘要；如果图谱本身没有内容，工具也无法返回有效结果。
### 报告缺少比分预测
请确认模拟需求或种子数据包含足球相关关键词，并提供可抽取的 `lambda_home`、`lambda_away`、xG 或 expected goals 信息。
## 开源协议
本项目继承原仓库协议，使用 **AGPL-3.0**。
如果你部署、分发，或通过网络提供该软件服务，请遵守 AGPL-3.0 的相关要求。
## 致谢
本项目基于 [666ghj/MiroFish](https://github.com/666ghj/MiroFish) 进行二次开发。感谢原作者及所有贡献者的开源工作。