hehaiguang1123
a6f05ab2d5
- Phase 0: AGENTS.md cleanup (dedup quotes, renumber sections, merge qmd) - Phase 1: typed relations (manage-relations.py, graph-search.py, check-staleness.py, detect-conflicts.py) - Phase 2: frontmatter validator, weekly lint, knowledge promotion, git hooks - Fix .gitignore to track tools/ and .githooks/ - Fix git remote URL (remove plaintext token) - New wiki pages: 504 pages, 34 raw sources
206 lines
7.6 KiB
Markdown
206 lines
7.6 KiB
Markdown
# 质量评估报告生成器 - 使用说明
|
||
|
||
## 📚 脚本简介
|
||
|
||
**质量评估报告生成器** 是一个自动化文献质量评估工具，用于生成标准化的文献质量评估报告（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/` 目录中的相关记录。**
|