# 质量评估报告生成器 - 使用说明

## 📚 脚本简介

**质量评估报告生成器** 是一个自动化文献质量评估工具，用于生成标准化的文献质量评估报告（OFM格式）。

**核心功能**：
- 交互式单篇文献评估
- 批量生成多篇文献评估报告
- 自动计算时效性分数和信源权威性分数
- 生成标准OFM格式评估报告

## 🚀 快速开始

### 1. 交互式单篇评估

适用于评估单篇高质量文献，需要详细输入各个维度的分数和评语。

```bash
cd d:\Applications\app\kepano-obsidian-main\raw\教育AI研究\tools
python 质量评估报告生成器.py
```

**操作流程**：
1. 输入文献基本信息（ID、标题、作者、来源、年份、PDF路径）
2. 系统自动计算时效性分数和信源权威性分数
3. 手动输入其他5个维度分数（数据质量、方法严谨性、实证基础、理论框架、影响力）
4. 输入核心发现、优势、局限、适用场景、使用建议（选填）
5. 自动生成评估报告并保存到 `文献库/` 目录

**输出文件**：`文献库/论文质量评估-{文献ID}-{YYYYMMDD}.md`

### 2. 批量评估模式

适用于快速评估多篇文献，采用简化评估方式（平均分）。

```bash
cd d:\Applications\app\kepano-obsidian-main\raw\教育AI研究\tools
python 质量评估报告生成器.py --batch
```

**操作流程**：
1. 从 `文献库/文献索引数据库.json` 读取未评估文献
2. 列出前10篇未评估文献
3. 确认后逐篇评估
4. 系统自动计算时效性分数和信源权威性分数
5. 手动输入5个维度的平均分（数据质量、方法严谨性、实证基础、理论框架、影响力）
6. 生成简化版评估报告并保存

**输出文件**：`文献库/论文质量评估-{文献ID}-{YYYYMMDD}.md`

### 3. 查看帮助

```bash
python 质量评估报告生成器.py --help
```

## 📊 评估维度说明

### 7个维度，总分105分制

| 维度 | 满分 | 评估方式 | 评分标准 |
|------|------|----------|----------|
| **时效性** | 15分 | 自动计算 | 2026年=15分，2025年=12分，2024年=9分，2023年=6分，2022年及以前=3分 |
| **信源权威性** | 20分 | 自动计算 | Nature/Science=20分，顶刊/顶会=18分，一区期刊=16分，其他=12分 |
| **数据质量** | 20分 | 手动输入 | 完整清晰+量化=20分，部分量化=15分，基本描述=10分，缺乏数据=5分 |
| **方法严谨性** | 20分 | 手动输入 | RCT=20分，准实验=15分，问卷调研=10分，理论分析=5分 |
| **实证基础** | 20分 | 手动输入 | 大样本+高效应量=20分，中等样本=15分，小样本=10分，理论分析=5分 |
| **理论框架** | 15分 | 手动输入 | 清晰完整=15分，基本清晰=10分，模糊或缺失=5分 |
| **影响力** | 15分 | 手动输入 | 高引用量+高影响因子=15分，中等=10分，较低=5分 |

### 质量等级划分

| 总分 | 质量等级 | 说明 | 使用建议 |
|------|----------|------|----------|
| ≥95分 | A+级 | 顶尖文献，可作为核心引用源 | 优先引用，重点推荐 |
| 90-94分 | A级 | 高质量文献，可作为重要引用源 | 重要引用，强烈推荐 |
| 85-89分 | A-级 | 良好文献，可作为辅助引用源 | 辅助引用，推荐使用 |
| 80-84分 | B+级 | 合格文献，特定场景有用 | 谨慎使用，特定场景 |
| 70-79分 | B级 | 一般文献，谨慎使用 | 谨慎使用，少量引用 |
| 60-69分 | B-级 | 较差文献，尽量少用 | 尽量少用，避免引用 |
| <60分 | C级 | 低质量文献，不建议引用 | 不建议引用，避免使用 |

## 💡 使用建议

### 何时使用单篇评估模式

- 评估A+级/A级高质量文献
- 需要详细记录各个维度的分数和评语
- 需要生成完整的评估报告（包括核心发现、优势、局限等）

### 何时使用批量评估模式

- 快速评估多篇中低质量文献（B级、C级）
- 时间预算有限，需要提高效率
- 只需了解文献大致质量，无需详细评估

### 评估频率建议

- **A+级/A级文献**：单篇评估，详细记录
- **B级文献**：批量评估，简化记录
- **C级文献**：批量评估或暂不评估

## 📝 评估报告格式

生成的评估报告采用标准OFM格式，包含以下部分：

### Frontmatter
```yaml
---
created: YYYY-MM-DD
title: 论文质量评估 - 文献标题
tags: [质量评估, A+级]
source: 文献来源
category: quality_assessment
---
```

### 内容结构
1. **文献基本信息**：文献ID、标题、作者、来源、年份、PDF路径、评估日期
2. **质量评估得分**：各维度得分、总分、质量等级
3. **核心发现与价值**：核心发现、优势、局限（单篇评估模式）
4. **适用场景与使用建议**：适用场景、使用建议（单篇评估模式）
5. **质量等级说明**：评分标准说明

## 🔧 技术细节

### 依赖要求
- Python 3.6+
- 仅使用标准库（sys, os, json, argparse, datetime, pathlib），无需额外安装

### 路径配置
- **脚本路径**：`tools/质量评估报告生成器.py`
- **文献库目录**：`文献库/`
- **文献库JSON**：`文献库/文献索引数据库.json`
- **输出目录**：`文献库/`

### 文件编码
- 脚本文件：UTF-8编码
- 输出文件：UTF-8编码
- 支持中文输入和输出

## 📊 效率提升

| 评估方式 | 每篇耗时 | 适用场景 |
|---------|----------|----------|
| **完全手动** | 15-20分钟 | 无脚本辅助 |
| **脚本辅助（单篇）** | 3-5分钟 | 详细评估 |
| **脚本辅助（批量）** | 1-2分钟 | 简化评估 |

**效率提升**：约 **4-10倍**（20分钟 → 2-5分钟）

## 🎯 最佳实践

1. **建立评估标准**：预先确定各维度的评分标准，保持评估一致性
2. **分优先级评估**：A+级/A级文献优先评估，详细记录；B级/C级文献批量评估
3. **定期更新评估**：新文献及时评估，保持文献库质量评估覆盖率
4. **善用批评估**：遇到多篇中低质量文献，使用批量评估模式提高效率
5. **记录评估依据**：在评估报告中记录评分依据，便于后续查阅和验证

## ❓ 常见问题

### Q1: 如何修改自动计算的分数规则？

A: 编辑 `tools/质量评估报告生成器.py` 文件中的以下函数：
- `calculate_timeliness_score()`：修改时效性分数计算规则
- `calculate_source_authority()`：修改信源权威性分数计算规则

### Q2: 如何添加新的评估维度？

A: 
1. 在 `__init__()` 方法中的 `self.assessment_dimensions` 添加新维度
2. 在 `generate_single_assessment()` 方法中添加新维度的输入逻辑
3. 在 `calculate_quality_grade()` 方法中调整总分计算
4. 在 `generate_report_content()` 方法中更新报告模板

### Q3: 批量评估时如何修改评估数量？

A: 编辑 `tools/质量评估报告生成器.py` 文件，找到以下代码：
```python
for entry in unassessed[:10]:  # 修改此处的数字
```
将 `10` 改为你想要评估的文献数量。

### Q4: 如何自定义报告模板？

A: 编辑 `tools/质量评估报告生成器.py` 文件中的 `generate_report_content()` 方法，修改报告生成的字符串模板。

## 📚 相关文档

- `.learnings/FEATURE_REQUESTS.md` - 功能需求记录
- `.learnings/LEARNINGS.md` - 学习记录
- `tools/质量评估报告生成器.py` - 脚本源代码
- `文献库/文献索引数据库.json` - 文献库数据

## ✅ 版本信息

- **版本**：v1.0
- **创建日期**：2026-04-25
- **作者**：教育AI研究项目
- **状态**：已测试，可正常使用

---

**如有问题或建议，请联系项目维护者或查看 `.learnings/` 目录中的相关记录。**