ScholarMind - 学术研究智能助手

基于 Semantic Scholar API 的学术文献查询与深度研究工具，包含 CLI 工具、多智能体研究系统和 Web UI。

---

🚀 快速启动（Web UI）

1. 配置环境变量

在项目根目录创建 .env 文件：

# Semantic Scholar API Key（必需）
# 获取地址：https://www.semanticscholar.org/product/api
Semantic_Search_API_KEY=your_semantic_scholar_api_key

# LLM API 配置（深度研究功能需要）
LLM_BASE_URL=https://api.openai.com/v1      # 或其他兼容 OpenAI 的 API
LLM_API_KEY=your_llm_api_key
LLM_MODEL=gpt-4                              # 或 gpt-3.5-turbo, qwen-plus 等

# 可选配置
DEBUG=false

2. 安装依赖

# Python 依赖（后端 + deep_scholar）
pip install -r requirements.txt

# 如果使用 deep_scholar 深度研究，还需要：
pip install agno openai sqlalchemy

# Node.js 依赖（前端）
cd web-ui
npm install

3. 启动服务

⚠️ 启动顺序：先后端，后前端

终端 1：启动后端 API（端口 8000）

cd web-ui/backend
uvicorn api:app --host 0.0.0.0 --port 8000 --reload

成功标志：

✅ Semantic Scholar client initialized
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000

终端 2：启动前端（端口 3000）

cd web-ui
npm run dev

成功标志：

VITE v6.x.x  ready in xxx ms
➜  Local:   http://localhost:3000/

4. 访问 Web UI

打开浏览器访问：http://localhost:3000

---

📁 项目结构

semantic_scholar_api/
├── .env                          # 环境变量配置（需创建）
├── requirements.txt              # Python 依赖
├── scholar.py                    # CLI 统一入口
├── semantic_scholar_client.py    # Semantic Scholar API 客户端
│
├── deep_scholar/                 # 🤖 多智能体深度研究系统
│   ├── config.py                 # 配置管理
│   ├── main.py                   # CLI 入口
│   ├── workflow.py               # 工作流定义
│   ├── agents/                   # 智能体定义
│   │   ├── searcher.py           # 搜索智能体
│   │   ├── analyst.py            # 分析智能体
│   │   ├── writer.py             # 写作智能体
│   │   ├── critic.py             # 评估智能体
│   │   └── team.py               # 团队协调器
│   └── tools/                    # 工具函数
│
└── web-ui/                       # 🌐 Web 界面
    ├── backend/
    │   └── api.py                # FastAPI 后端 API
    ├── App.tsx                   # React 主组件
    ├── components/               # UI 组件
    ├── services/
    │   └── apiService.ts         # API 调用服务
    ├── package.json              # Node.js 依赖
    └── vite.config.ts            # Vite 配置

---

🔧 配置说明

环境变量

变量名	必需	说明	示例
Semantic_Search_API_KEY	✅	Semantic Scholar API 密钥	xxxxxxxx
LLM_BASE_URL	深度研究需要	LLM API 地址	https://api.openai.com/v1
LLM_API_KEY	深度研究需要	LLM API 密钥	sk-xxxxxxxx
LLM_MODEL	深度研究需要	模型名称	gpt-4 / qwen-plus
DEBUG	❌	调试模式	true / false

前端配置（可选）

如需修改后端地址，编辑 web-ui/.env.local：

VITE_API_URL=http://localhost:8000

---

🎯 功能说明

Web UI 功能

功能	说明
学术搜索	搜索论文，支持年份、排序、引用数筛选
深度研究	AI 多智能体协作生成研究报告
论文详情	查看摘要、作者、引用等完整信息
相似论文	基于推荐算法查找相关论文
参考文献	查看论文引用的文献列表
被引文献	查看引用该论文的文献列表

深度研究智能体

智能体	职责
研究协调器	分析任务，决策调用顺序
搜索智能体	检索 Semantic Scholar 论文
分析智能体	分析论文内容和关键发现
写作智能体	撰写结构化研究报告
评估智能体	评估报告质量，提出改进建议

---

📝 CLI 工具使用

scholar.py - 统一入口

# 关键词搜索
python scholar.py keyword "machine learning" -y 2023-2024 -l 20

# 标题搜索
python scholar.py title "Attention is All You Need"

# DOI 查询
python scholar.py doi "10.1038/s41586-021-03819-2" -c -r

# 作者搜索
python scholar.py author search "Yann LeCun"

# 日期搜索
python scholar.py date "LLM" --today

deep_scholar - 深度研究

# 交互模式
python -m deep_scholar.main

# 直接研究
python -m deep_scholar.main -q "LLM Agent 最新进展"

# 仅检索
python -m deep_scholar.main -s "transformer attention"

---

⚠️ 常见问题

1. 后端启动失败：ModuleNotFoundError

# 安装缺失的依赖
pip install fastapi uvicorn python-dotenv agno openai sqlalchemy

2. 深度研究显示"服务不可用"

检查：

1. .env 中 LLM 配置是否正确
2. LLM API 是否可访问
3. 后端日志是否有错误

3. 前端无法连接后端

检查：

1. 后端是否在 8000 端口运行
2. CORS 是否配置正确（后端已默认允许）
3. 前端 VITE_API_URL 配置是否正确

4. API 速率限制

• Semantic Scholar API 有速率限制（1次/秒）
• 客户端已内置自动重试机制
• 如频繁触发，建议申请更高配额

---

📜 License

MIT