# 期刊质量评估功能使用指南
## 功能概述
期刊质量评估功能为您提供全面的期刊质量分析，包括影响因子、分区信息、JCI指数等关键指标。该功能采用本地缓存优先的策略，可选择性地调用EasyScholar API进行补全。
## 主要特性
- **本地缓存优先**：首先从本地`journal_info.json`文件查询期刊信息
- **API补全**：当本地没有数据时，可调用EasyScholar API获取最新信息
- **批量处理**：支持对文献列表进行批量期刊质量评估
- **多种指标**：提供影响因子、SCI分区、JCI指数等多维度质量评估
- **智能缓存**：API获取的数据会自动保存到本地缓存
## 可用工具
### 1. get_journal_quality
获取单个期刊的质量评估信息。
**参数：**
- `journal_name` (必需): 期刊名称
- `secret_key` (可选): EasyScholar API密钥，也可通过环境变量`EASYSCHOLAR_SECRET_KEY`设置
**返回结果：**
```json
{
"journal_name": "Nature",
"source": "local_cache",
"quality_metrics": {
"impact_factor": 48.5,
"sci_quartile": "Q1",
"sci_zone": "综合性期刊1区",
"sci_zone_detail": "综合性期刊1区。",
"jci": 11.12,
"impact_factor_5year": 55.0
},
"error": null
}
```
### 2. evaluate_articles_quality
批量评估文献列表的期刊质量。
**参数：**
- `articles` (必需): 文献列表，每个文献需包含`journal_name`字段
- `secret_key` (可选): EasyScholar API密钥
**返回结果：**
```json
{
"evaluated_articles": [
{
"pmid": "123456",
"title": "研究标题",
"journal_name": "Nature",
"authors": ["作者1", "作者2"],
"journal_quality": {
"journal_name": "Nature",
"source": "local_cache",
"quality_metrics": {
"impact_factor": 48.5,
"sci_quartile": "Q1",
"sci_zone": "综合性期刊1区"
},
"error": null
}
}
],
"total_count": 1,
"message": "成功评估 1 篇文献的期刊质量",
"error": null
}
```
## 质量指标说明
### 影响因子 (Impact Factor)
- `impact_factor`: 当前年度影响因子
- `impact_factor_5year`: 5年平均影响因子
### 分区信息
- `sci_quartile`: SCI分区（Q1、Q2、Q3、Q4）
- `sci_zone`: SCI大区（如"综合性期刊1区"、"生物学1区"）
- `sci_zone_detail`: 详细分区信息
### 其他指标
- `jci`: Journal Citation Indicator（期刊引用指标）
## 使用示例
### 示例1：评估单个期刊
```python
# 通过MCP客户端调用
result = get_journal_quality(
journal_name="Nature",
secret_key="your_api_key" # 可选
)
```
### 示例2：批量评估文献质量
```python
# 先搜索文献
articles = search_europe_pmc(
keyword="machine learning",
max_results=5
)
# 然后评估期刊质量
quality_result = evaluate_articles_quality(
articles=articles["articles"],
secret_key="your_api_key" # 可选
)
```
## 配置说明
### 环境变量设置
在系统环境变量或`.env`文件中设置EasyScholar API密钥：
```bash
EASYSCHOLAR_SECRET_KEY=your_secret_key_here
```
### 本地缓存文件
期刊信息缓存位置：`src/resource/journal_info.json`
缓存文件结构：
```json
{
"期刊名称": {
"rank": {
"sciif": 48.5,
"sci": "Q1",
"sciUp": "综合性期刊1区",
"jci": 11.12,
"sciif5": 55.0
}
}
}
```
## EasyScholar API说明
### API接口
- **URL**: `https://www.easyscholar.cc/open/getPublicationRank`
- **方法**: GET
- **参数**:
- `secretKey`: API密钥
- `publicationName`: 期刊名称
### 返回数据结构
- `officialRank`: 官方排名数据
- `customRank`: 自定义排名数据
## 错误处理
### 常见错误及解决方案
1. **API密钥错误**
- 错误信息：`"Key错误"`
- 解决方案：检查API密钥是否正确
2. **期刊未找到**
- 错误信息：`"未找到期刊质量信息"`
- 解决方案：确认期刊名称拼写正确
3. **网络请求失败**
- 错误信息：`"EasyScholar API 请求失败"`
- 解决方案：检查网络连接，稍后重试
## 最佳实践
1. **优先使用本地缓存**：系统会自动优先查询本地缓存，减少API调用
2. **批量处理**：对于多篇文献，使用`evaluate_articles_quality`比逐个调用更高效
3. **API密钥管理**：建议通过环境变量设置API密钥，避免在代码中硬编码
4. **错误处理**：检查返回结果中的`error`字段，妥善处理各种异常情况
## 注意事项
- 本功能需要有效的EasyScholar API密钥才能获取新的期刊信息
- 本地缓存会在API调用成功后自动更新
- 期刊名称需要准确匹配，建议使用标准期刊名称
- API调用有频率限制，建议合理控制调用频次
