Research Literature Review

Changelog

All notable changes to the research-literature-review skill will be documented in this file. Historical entries may use the old name systematic-literature-review.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Changed（Skill rename - 2026-06-14）

• Renamed the skill from systematic-literature-review to research-literature-review.
• Kept the old name as a prompt-level compatibility alias in SKILL.md and README.md; system-level legacy directories are cleaned by install-bensz-skills.
• Preserved .systematic-literature-review/ as the stable workspace directory for existing outputs and scripts.

Fixed（检索与摘要补齐的可控性/可复现性 - 2026-01-25）

• multi_query_search.py：未提供查询时不再静默回退到硬编码查询，改为直接报错（避免误跑无关主题）
• openalex_search.py：摘要补齐默认跟随 config.yaml，并支持 CLI 显式覆盖；补齐请求复用 --cache-dir
• multi_source_abstract.py：补齐请求接入 api_cache.py 缓存，减少重复请求与限流风险；修复 OpenAlex abstract_inverted_index=null 导致的崩溃
• select_references.py：摘要长度阈值默认跟随 config.yaml:search.abstract_enrichment.min_abstract_chars，保证“补齐判定/选文规避”口径一致

Fixed（BibTeX Unicode 控制字符清洗 - 2026-01-03）🧹

问题修复：解决 LaTeX 编译时产生的 "Missing character" 警告

• 问题背景（breast-test-05 实例）：
• LaTeX 编译日志显示 31 个 "Missing character" 警告
• 涉及 Unicode 控制字符：U+202C（POP DIRECTIONAL FORMATTING）、U+200E（LEFT-TO-RIGHT MARK）
• 来源：OpenAlex API 返回的作者名称中包含方向控制符

• 解决方案：
• 新增 _sanitize_unicode() 函数（build_reference_bib_from_papers.py 第 24-48 行）
• 移除 Unicode 控制字符（Cc、Cf 类别），保留正常字符和特殊学术字符
• 在 _to_ref() 函数中对 title、venue、authors 调用清洗函数

• 测试验证（test/AUTOv202601030646）：
• 14 个测试用例全部通过
• 真实数据测试：成功清洗 breast-test-05 中的问题字符串

• 影响：
• ✅ 消除 LaTeX 编译时的 Unicode 字符警告
• ✅ 保留特殊学术字符（如 ǹ、ę、中文）
• ✅ 向后兼容：不影响现有 BibTeX 生成流程

---

Fixed（validate_citation_distribution.py SyntaxWarning - 2026-01-03）🔧

问题修复：修复 Python 3.12+ 的 SyntaxWarning

• 问题背景：
• 运行脚本时产生 SyntaxWarning: invalid escape sequence '\c'
• 原因：docstring 中的 \cite 未转义

• 解决方案：
• 将第 28 行 docstring 中的 \cite 改为 \\cite

• 测试验证：
• python3 -W error -c "import scripts.validate_citation_distribution" 无警告

• 影响：
• ✅ 消除 SyntaxWarning
• ✅ 脚本在 -W error 模式下可正常运行

---

Changed（选文分数分布统计透明化 - 2026-01-03）📊

功能增强：在 selection_rationale.yaml 中增加详细的分数分布统计

• 问题背景（breast-test-05 实例）：
• high_score_bucket: 196 容易被误解为「高分文献数量」
• 实际含义是「按分数排序后取前 70% 的文献数量」
• 用户无法直观了解选中文献的实际分数分布

• 解决方案：
• 在 _select_papers() 函数中增加 score_distribution 统计
• 新增字段：
• high_score_count: 高分(≥7)文献数
• mid_score_count: 中分(4-6.9)文献数
• low_score_count: 低分(<4)文献数
• max_score, min_score, avg_score: 分数范围和均值

• 输出示例（修复后）：

  total_candidates: 279
  selected: 90
  high_score_fraction_used: 0.7
  high_score_bucket: 196  # 保留向后兼容
  min_refs: 50
  max_refs: 90
  score_distribution:
    high_score_count: 32
    mid_score_count: 34
    low_score_count: 24
    max_score: 9.4
    min_score: 2.0
    avg_score: 6.13

• 测试验证（test/AUTOv202601030646）：
• 3 个测试用例全部通过
• 向后兼容性验证通过

• 影响：
• ✅ 选文理由更透明，用户可直观了解分数分布
• ✅ 向后兼容：保留 high_score_bucket 字段
• ✅ 便于调试和质量评估

---

Added（成本追踪系统 - AI 驱动的价格获取与 Token 统计 - 2026-01-02）💰

新功能：添加完全可选的 Token 使用与成本追踪系统，帮助用户了解综述项目的 AI 成本。

• 核心特性：
• 单文件架构：所有功能集中在 scripts/pipeline_cost.py
• AI 驱动价格获取：AI 自动联网查询官方价格（OpenAI、Anthropic、智谱清言）
• 项目级数据隔离：每个综述项目独立记录
• 零侵入设计：不影响文献综述核心流程

• AI 驱动价格获取流程：

1. 用户运行：python3 scripts/pipeline_cost.py fetch-prices 2. AI 自动：

• 使用 WebSearch 工具查询官方定价
• 从官网提取准确价格信息
• 生成 YAML 格式
• 保存到 scripts/pipeline_cost.yaml

3. 自动复制到当前项目：.systematic-literature-review/cost/price_config.yaml

• 获取的价格数据（共 14 个模型，2026-01-02 获取）：

OpenAI 模型：

Anthropic 模型：

智谱清言模型：

• 使用方法：

  # 初始化
  python3 systematic-literature-review/scripts/pipeline_cost.py init

  # 记录使用
  python3 systematic-literature-review/scripts/pipeline_cost.py log \
    --tool "Task" \
    --model "claude-opus-4-5" \
    --in 12345 \
    --out 6789 \
    --step "文献检索"

  # 查看统计
  python3 systematic-literature-review/scripts/pipeline_cost.py summary

• 数据存储：
• 项目级使用记录：.systematic-literature-review/cost/token_usage.csv
• 技能级价格缓存：scripts/pipeline_cost.yaml（跨项目共享）
• 项目级价格副本：.systematic-literature-review/cost/price_config.yaml

• 配置（config.yaml 新增）：

  cost_tracking:
    enabled: true                    # 启用/禁用
    model_providers:                 # 关注的模型商
      - OpenAI
      - Anthropic
      - 智谱清言
    price_cache_max_days: 30         # 价格有效期（天）
    currency_rates:
      USD_TO_CNY: 7.2                # 汇率

• 测试验证（test/COSTv202601022318）：
• ✅ 初始化测试：正确创建目录和 CSV
• ✅ Token 记录测试：正确写入 CSV
• ✅ 统计报告测试（不含费用）：数据准确
• ✅ 统计报告测试（含费用）：费用计算正确
• ✅ AI 驱动价格获取测试：成功从 3 个模型商官网获取价格
• ✅ 多模型价格计算验证：手动计算与脚本输出完全一致
• ✅ 价格复制测试：正确复制到项目
• 测试通过率：100%（所有测试场景）

• 影响：
• ✅ 成本透明化：用户可清晰了解每个综述项目的 AI 成本
• ✅ 零侵入设计：完全可选，不影响文献综述核心流程
• ✅ AI 自动化：价格获取完全由 AI 自动完成，无需人工维护
• ✅ 项目级隔离：每个综述项目独立记录，便于成本核算
• ✅ 向后兼容：不使用成本追踪时，功能完全不受影响

• 新增文件：
• scripts/pipeline_cost.py：核心脚本（单文件架构）
• scripts/pipeline_cost.yaml：AI 生成的价格数据（技能级）
• test/COSTv202601022318/TEST_REPORT.md：完整测试报告

• SKILL.md 更新：
• 新增"可选：成本追踪（Token 使用与费用统计）"章节
• 包含初始化、价格获取、记录使用、查看统计的完整说明

• 重要说明：
• 核心特性：AI 驱动的价格获取——在技能的原生 AI 环境中自动完成
• 设计原则："零维护"——AI 自动联网查询官方价格，无需手动更新
• 功能隔离：完全独立于文献综述核心流程，可随时禁用或删除

---

Changed（检索质量评估 - 查询效果可视化与优化建议 - 2026-01-02）🔍

问题修复：解决 Problems_from_breast-test-03.md 第362-379行的"检索质量评估缺失"问题（问题 #12，🟢 轻微问题，优先级 P2）

• 问题背景（breast-test-03 实例）：
• 检索日志显示 8 组查询，共返回 399 篇文献
• 缺少对查询质量的评估：
• 哪些查询召回率高？
• 哪些查询引入了噪声？
• 是否有遗漏的重要主题？

• 根本原因分析：
• multi_query_search.py 仅记录基础统计（returned/unique）
• 缺少查询质量评估逻辑
• 无法识别低效查询并提供优化建议

• 解决方案：轻量级质量评估系统

1. 数据模型扩展（multi_query_search.py 第42-63行）：

• SearchLog 新增质量评估字段：
• dedupe_rate: 去重率（unique / returned）
• quality_score: 质量评分（0-1）
• quality_label: 质量标签（优秀/良好/一般/较差）
• 新增 QualitySummary 数据类：
• 统计各质量等级的查询数量
• 存储改进建议列表

2. 质量评估逻辑（_assess_query_quality() 函数）：

• 评估维度：
• 去重率（权重 60%）：≥80% 优秀，60-80% 良好，40-60% 一般，<40% 较差
• 召回贡献（权重 40%）：≥30 高贡献，15-29 中等，<15 低贡献
• 质量评分公式：

    quality_score = (dedupe_rate * 0.6) + (min(unique / 50, 1.0) * 0.4)

• 质量标签：
• 优秀: score ≥ 0.8
• 良好: 0.6 ≤ score < 0.8
• 一般: 0.4 ≤ score < 0.6
• 较差: score < 0.4

3. 质量汇总与建议（_generate_quality_summary() 函数）：

• 统计各质量等级的查询数量
• 自动生成改进建议：
• 去重率 < 40%：建议优化检索词以提高精确度
• 召回贡献 < 10 篇：建议移除或调整
• 召回贡献 10-15 篇：建议优化或与其他查询合并

4. 检索日志增强（main() 函数）：

• 新增 quality_summary 字段到检索日志
• 输出时显示质量评估汇总
• 最多显示 3 条改进建议

• 测试验证（test/v202601021825）：
• 测试方法：8个测试场景（高质量、中等质量、低质量、边界测试）
• 测试结果：

测试通过率：100%（8/8 场景）

• 检索日志示例（修复后）：

  {
    "total_queries": 8,
    "total_returned": 399,
    "total_unique": 301,
    "queries": [
      {
        "query": "deep learning breast ultrasound",
        "returned": 50,
        "unique": 42,
        "dedupe_rate": 0.84,
        "quality_score": 0.824,
        "quality_label": "优秀"
      }
    ],
    "quality_summary": {
      "excellent": 2,
      "good": 3,
      "fair": 2,
      "poor": 1,
      "recommendations": [
        "查询 'artificial intelligence breast...' 质量较差（去重率 16.0%），建议优化检索词以提高精确度",
        "查询 'medical imaging deep learning...' 贡献一般（15 篇），可考虑优化或与其他查询合并"
      ]
    }
  }

• 影响：
• ✅ 查询质量可视化：用户可清晰看到每个查询的质量评级
• ✅ 优化建议自动化：自动识别低效查询并提供针对性改进建议
• ✅ 检索策略优化：基于质量评估结果调整查询组合，提高整体检索效果
• ✅ 代码质量提升：遵循 KISS、DRY 原则，最小侵入修改
• ✅ 向后兼容：旧版本检索日志可正常读取，新增字段有默认值

• 新增文件：
• test/v202601021825/TEST_PLAN.md：测试计划
• test/v202601021825/TEST_REPORT.md：测试报告
• test/v202601021825/run_tests.sh：自动化测试脚本
• test/v202601021825/scripts/validate_quality_assessment.py：质量评估验证脚本
• test/v202601021825/data/mock_queries_mixed.json：模拟查询数据

• 版本演进：

  v3.9 (breast-test-03)
  └─ 检索质量评估：缺失，无法识别低效查询

  v4.0（本次修复）✅
  └─ 检索质量评估：完整实现，自动生成优化建议
     └─ multi_query_search.py：扩展数据模型，增加质量评估逻辑
     └─ 检索日志：包含质量汇总和改进建议
     └─ 测试覆盖：8个场景全部通过

• 重要说明：
• 核心改进：从"无质量评估"升级为"完整质量评估系统"
• 关键原则："轻量级设计"——基于去重率和召回贡献的简单评分公式，无需额外依赖
• 适用范围：所有使用多查询检索的场景，不受领域或语言限制

---

Removed（清理 checkpoints 遗留设计 - 符合 YAGNI 原则 - 2026-01-02）✂️

技术债清理：移除未使用的 checkpoints/ 目录设计，简化项目结构

• 问题背景：
• checkpoints/ 目录在代码中被创建，但从未被写入或使用
• 所有状态都保存在 pipeline_state.json（单一文件）
• checkpoints/ 是遗留设计，可能是早期计划的"每个阶段一个检查点文件"，但最终采用了单一状态文件方案
• 配置文件中定义了 checkpoints_dir_name，但代码从未实际使用

• 清理内容：

1. `pipeline_runner.py` 移除 checkpoints_dir（第147-154行）：

• 删除 self.checkpoints_dir 的创建和赋值
• 从目录创建列表中移除 checkpoints_dir
• 状态仍然保存在 hidden_dir / pipeline_state.json

2. `config.yaml` 移除 checkpoints_dir_name（第143-149行）：

• 删除 checkpoints_dir_name: "checkpoints" 配置
• 添加注释说明状态保存在 pipeline_state.json

• 影响：
• ✅ 简化项目结构：移除未使用的目录，减少用户困惑
• ✅ 符合 YAGNI 原则：删除不需要的代码和配置
• ✅ 向后兼容：pipeline_state.json 仍然正常工作，--resume 功能不受影响
• ✅ 代码清晰度提升：明确状态保存机制（单一文件）

• 验证：
• ✅ 所有现有测试通过（test/v202601021808）
• ✅ PipelineRunner 初始化正常，不再创建 checkpoints/ 目录
• ✅ 其他目录（artifacts/, cache/api/, reference/）仍然正常创建

• 重要说明：
• 核心改进：从"遗留空壳目录"升级为"明确的状态管理"
• 状态保存：所有阶段完成状态仍然保存在 pipeline_state.json
• 恢复机制：--resume 功能继续工作，从 pipeline_state.json 读取状态

---

Changed（工作条件警告与验证修复 - PipelineRunner 类变量补全 - 2026-01-02）✅

问题修复：解决 Problems_from_breast-test-03.md 第323-337行的"工作条件中未体现评分分布异常"问题（问题 #10，🟢 轻微问题，优先级 P2）

• 问题背景（breast-test-03 实例）：
• 工作条件显示评分分布：0 / 0 / 301
• 但未明确说明这是一个严重问题
• 仅简单备注：受中文主题降级影响，暂无高分
• 用户可能忽略评分失效的严重性

• 根本原因分析：
• validate_working_conditions.py 第84、87、95、104行引用了 PipelineRunner.WORKING_CONDITIONS_* 类变量
• 但 `PipelineRunner` 类中并未定义这些类变量（代码缺失）
• 导致 validate_working_conditions.py 运行时抛出 AttributeError
• 工作条件骨架缺少评分分布异常警告机制

• 解决方案：

1. `pipeline_runner.py` 添加缺失的类变量（第58-92行）：

• 新增 WORKING_CONDITIONS_HEADINGS：7个工作条件章节标题映射
• 新增 WORKING_CONDITIONS_REQUIRED_H2_KEYS：7个必需 H2 章节键
• 新增 WORKING_CONDITIONS_REQUIRED_H3_KEYS：当前无必需 H3 章节
• 新增 WORKING_CONDITIONS_REQUIRED_KEYWORDS：包含"评分分布"、"高分优先"关键词

2. 扩展工作条件骨架，添加评分分布警告（第260-274行）：

• 在"Relevance Scoring & Selection"章节添加评分分布异常警告模板
• 明确症状："如果所有文献评分均为 1.0（保底评分）"
• 说明原因："中文主题导致脚本评分无法提取有效 token（v3.6 及更早版本）"
• 提供建议："使用 AI 评分（v3.7+）或将主题转为英文"
• 添加"Data Extraction Table"章节，说明数据抽取表路径和内容

3. 验证 `validate_working_conditions.py` 正常运行：

• 不再抛出 AttributeError
• 可正确检测缺少的章节和关键词
• 支持评分分布异常关键词检测

• 测试验证（test/v202601021808）：
• 测试方法：4个场景（类变量验证 + 完整工作条件 + 缺少章节 + 缺少关键词）
• 测试数据：3个测试文件（完整工作条件、缺少章节、缺少关键词）

测试结果：

测试通过率：100%（4/4 场景）

• 影响：
• ✅ validate_working_conditions.py 可正常运行：不再抛出 AttributeError
• ✅ 工作条件骨架包含评分分布警告：用户可识别评分失效问题
• ✅ 代码质量提升：遵循 DRY 原则，单一真相来源
• ✅ 向后兼容：不影响现有工作流，仅修复缺失代码

• 新增文件：
• test/v202601021808/TEST_PLAN.md：测试计划
• test/v202601021808/TEST_REPORT.md：测试报告
• test/v202601021808/run_tests.sh：自动化测试脚本
• test/v202601021808/data/test_valid_wc.md：完整工作条件示例
• test/v202601021808/data/test_missing_section.md：缺少章节示例
• test/v202601021808/data/test_no_keywords.md：缺少关键词示例

• 版本演进：

  v3.5 (breast-test-03)
  └─ 工作条件：缺少评分分布警告
  └─ validate_working_conditions.py：运行时错误（AttributeError）

  v4.1（本次修复）✅
  └─ 工作条件：包含评分分布异常警告模板
     └─ pipeline_runner.py：添加 WORKING_CONDITIONS_* 类变量
     └─ validate_working_conditions.py：正常运行
     └─ 测试覆盖：4个场景全部通过

• 重要说明：
• 核心改进：从"运行时错误"升级为"正常工作"
• 关键原则："单一真相来源"——validate_working_conditions.py 引用 PipelineRunner 的类变量
• 问题可见性：工作条件骨架现在明确提示评分分布异常
• 适用范围：所有使用 Pipeline 或 validate_working_conditions.py 的场景

---

Changed（验证报告章节验证详情 - 动态展示章节信息 - 2026-01-02）✅

问题修复：解决 Problems_from_breast-test-03.md 第303-321行的"验证报告缺少章节验证详情"问题（问题 #9，🟢 轻微问题，优先级 P2）

• 问题背景（breast-test-03 实例）：
• 验证报告显示："章节验证未通过或未执行"
• 实际情况：综述包含所有必需章节（摘要、引言、7个子主题、讨论、展望、结论）
• 用户无法确认章节结构是否正确

• 根本原因分析：
• generate_validation_report.py 第164-183行的章节验证逻辑过于简化
• 仅依赖 review_tex_passed 布尔标志，未提供详细章节列表
• 无法反映实际检测到的章节情况

• 解决方案：

1. `validate_review_tex.py` 输出章节详情（第222-235行）：

• 在验证通过时收集章节信息：abstract、intro、body_count、body_titles、discussion、outlook
• 使用 JSON 格式附加到通过消息：SECTIONS:{json}
• 示例输出：

      ✓ LaTeX review validation passed (cites=94, bib_keys=150) SECTIONS:{"abstract":true,"intro":true,"body_count":7,"body_titles":["CNN 分类方法","迁移学习",...],"discussion":true,"outlook":true}

2. `generate_validation_report.py` 解析章节详情（第35-63行）：

• 扩展 parse_review_tex_result() 函数
• 使用正则表达式提取 SECTIONS: 后的 JSON 数据
• 错误处理：JSON 解析失败时保持 sections 为 None，回退到固定模板

3. `generate_markdown_report` 动态生成报告（第177-224行）：

• 有 sections 数据时：
• 显示每个章节的详细状态（存在/缺失）
• 列出检测到的子主题标题（最多10个）
• 显示子主题数量
• 无 sections 数据但验证通过时：显示固定模板（向后兼容）
• 验证失败时：显示"章节验证未通过或未执行"

• 测试验证（test/v202601021757）：
• 测试方法：4个场景（完整结构、缺少摘要、缺少讨论、缺少子主题）
• 测试数据：5个文件（4个场景文件 + 1个参考文献文件）

测试结果：

验证报告示例（修复后）：

  ## 必需章节验证

  - **摘要**: ✅ 存在
  - **引言**: ✅ 存在
  - **子主题段**: ✅ 7个
    - CNN 分类方法
    - 迁移学习
    - 注意力机制
    - 多模态融合
    - 数据增强
    - 可解释性
    - 临床应用
  - **讨论**: ✅ 存在
  - **展望/结论**: ✅ 存在

• 影响：
• ✅ 验证信息透明化：用户可查看每个章节的检测结果
• ✅ 子主题可见性：列出所有子主题标题，便于确认结构
• ✅ 向后兼容：兼容旧版本输出（无 SECTIONS: 时使用固定模板）
• ✅ 代码质量：遵循 KISS、DRY 原则，修改最小化
• ✅ 测试覆盖：4个场景全部验证通过

• 新增文件：
• test/v202601021757/TEST_PLAN.md：测试计划
• test/v202601021757/TEST_REPORT.md：测试报告
• test/v202601021757/run_tests.sh：自动化测试脚本
• test/v202601021757/data/：测试数据（5个文件）

• 版本演进：

  v3.5 (breast-test-03)
  └─ 验证报告：章节验证未通过或未执行（固定模板）

  v4.0（本次修复）✅
  └─ 验证报告：动态显示章节详情 + 子主题列表
     └─ validate_review_tex.py：输出 SECTIONS: JSON
     └─ generate_validation_report.py：解析并动态生成报告
     └─ 向后兼容：无 SECTIONS: 时使用固定模板

• 重要说明：
• 核心改进：从"固定模板"升级为"动态详情"，列出所有子主题
• 关键原则："验证透明化"——用户可查看每个章节的检测结果
• 向后兼容：兼容旧版本输出，JSON 解析失败时回退到固定模板
• 适用范围：适用于所有系统综述验证，不受领域或语言限制

---

Changed（OpenAlex API 缓存集成 - 检索结果可复用 - 2026-01-02）✅

问题修复：解决 Problems_from_breast-test-03.md 第279-298行的"API 缓存目录为空"问题（问题 #8，🟡 中等问题，优先级 P1）

• 问题背景（breast-test-03 实例）：
• .systematic-literature-review/cache/api/ 目录完全为空
• 检索结果无法复用，重新运行需要重新调用 API
• 浪费 API 配额和时间，无法离线调试或复现检索结果

• 根本原因分析：
• api_cache.py 虽然已实现缓存功能，但环境变量检查过于严格（RuntimeError）
• openalex_search.py 和 multi_query_search.py 未集成缓存逻辑
• Pipeline 虽然创建了缓存目录，但未设置环境变量或传递参数

• 解决方案：轻量级集成，最小侵入

1. `api_cache.py` 简化环境变量依赖（第131-137行）：

• 从 RuntimeError 改为 logger.info() 警告
• 允许使用默认缓存目录 .systematic-literature-review/cache/api
• 不再强制要求设置环境变量

2. `openalex_search.py` 集成 API 缓存：

• 新增 logging 模块导入
• search_openalex() 新增 cache_dir 参数（可选）
• 初始化 CacheStorage（如果提供 cache_dir）
• 在 fetch_with_cursor() 中集成缓存逻辑：
• 优先从缓存获取 API 响应
• 缓存未命中时调用 API 并保存结果
• get_work_by_doi() 新增 cache_dir 参数
• main() 新增 --cache-dir 命令行参数

3. `multi_query_search.py` 传递缓存参数：

• multi_search() 新增 cache_dir 参数
• 传递 cache_dir 给 search_openalex()
• main() 新增 --cache-dir 命令行参数

4. `pipeline_runner.py` 设置环境变量并传递参数：

• 第121-122行：设置环境变量 SYSTEMATIC_LITERATURE_REVIEW_CACHE_DIR
• 第279行：多查询检索传递 --cache-dir 参数
• 第292行：单一查询检索传递 --cache-dir 参数

• 测试验证（test/v202601021736）：
• 测试方法：轻量级功能测试（4个场景）
• 测试数据：真实 OpenAlex API 检索

测试结果：

性能对比：

• 影响：
• ✅ 检索结果可复用：重新运行 Pipeline 不会重复调用 API
• ✅ 节省 API 配额：减少 OpenAlex API 调用次数
• ✅ 提升开发效率：测试和调试时响应更快（80-95% 性能提升）
• ✅ 支持离线调试：缓存文件可用于离线开发
• ✅ 向后兼容：不使用缓存时功能正常，无副作用
• ✅ 代码质量：遵循 KISS、DRY 原则，修改最小化

• 新增文件：
• test/v202601021736/TEST_PLAN.md：详细测试计划
• test/v202601021736/TEST_REPORT.md：测试报告
• test/v202601021736/test_api_cache.sh：自动化测试脚本

• 版本演进：

  v3.5 (breast-test-03)
  └─ API 缓存：目录为空，功能未实现

  v3.9（本次修复）✅
  └─ API 缓存：完整集成，正常工作
     └─ api_cache.py：简化环境变量依赖
     └─ openalex_search.py：集成缓存逻辑
     └─ multi_query_search.py：传递缓存参数
     └─ pipeline_runner.py：设置环境变量
     └─ 性能提升：80-95%

• 重要说明：
• 核心改进：从"无缓存"升级为"完整缓存支持"
• 关键原则："轻量级集成"——只修改必要的部分
• 缓存机制：基于 URL + 参数的 MD5 哈希，确保键唯一性
• 适用范围：所有使用 Pipeline 或检索脚本的场景

---

Changed（引用分布失衡修复 - 单篇引用优先原则 - 2026-01-02）✅

问题修复：解决 Problems_from_breast-test-03.md 第32-56行的"引用分布严重失衡"问题（问题 #1，🔴 严重问题，优先级 P0）

• 问题背景（breast-test-03 实例）：
• 单篇引用仅 1.9%（目标 70% ±5%）
• 小组引用（2-4篇）高达 98.1%（目标 25% ±5%）
• 严重违背"专家级人类的自然论述"原则
• 读者无法识别每个观点的具体来源，降低综述的可读性和学术严谨性

• 根本原因分析：
• Prompt 约束模糊性：AI 理解"约 70%"为软约束，走向"2-4 篇保险策略"的极端
• 缺少"强制单篇优先"的硬性机制
• 示例误导："正确模式"示例中小组引用过多
• 缺少明确的"单篇引用场景"和"小组引用场景"划分标准
• 写作时采用"陈述观点 + 2-3 篇文献"的固定模式

• 解决方案：三管齐下优化 Prompt 和写作指南

1. SKILL.md 强化引用分布约束（第91-104行）：

• 从"约 70%"改为"强制执行 + 验证阈值 65%"
• 新增"单篇引用优先原则"：约 70% 的引用应为单篇 \cite{key} 格式
• 明确"单篇引用场景"（优先使用）：
• 引用具体方法、结果、数字时："Zhang 等人使用 ResNet-50 达到 95% 准确率\cite{Zhang2020}。"
• 逐篇对比研究时："ResNet 表现优异\cite{He2016}。DenseNet 进一步提升性能\cite{Huang2017}。"
• 引用核心观点或理论时："注意力机制能够帮助模型聚焦于关键区域\cite{Wang2021}。"
• 明确"小组引用场景"（限制使用，约 25%）：
• 对比并列研究时，且需明确说明各文献的差异化贡献
• 引用互补证据时，且分别说明各文献的独立贡献
• 新增"禁止模式"：
• ❌ "陈述观点 + 堆砌 2-3 篇文献"："多项研究表明\cite{Paper1,Paper2,Paper3}。"
• ❌ 单次引用 >4 个 key（<5% 情况，仅限综述性陈述）
• 新增"验证要求"：写作完成后运行 validate_citation_distribution.py --verbose，如单篇引用 <65% 必须修正

2. expert-review-writing.md 新增"单篇引用优先"章节（第105-177行）：

• 新增"为什么优先单篇引用？"：明确来源、自然节奏、避免模糊、提升可读性
• 新增"单篇引用的标准模式"：
• 引用具体方法/结果（最常见，约占 50%）
• 逐篇对比研究（约占 15%）
• 引用核心观点/理论（约占 5%）
• 新增"何时使用小组引用（2-4篇）？"：仅限对比并列研究、引用互补证据
• 新增"禁止模式（必须避免）"：
• ❌ 错误模式 1：模糊的"多项研究表明"
• ❌ 错误模式 2：堆砌文献无阐述
• ❌ 错误模式 3：单次引用 >4 个 key
• 新增"正确模式（优先单篇）"：提供 2 个正确示例

3. 写作前提示模板优化（SKILL.md 第200-218行）：

• 从"引用分布必须符合人类学术写作习惯"改为"强制执行单篇引用优先原则"
• 明确"写作模式"：

1. 默认使用单篇引用（约占 70%）：禁止使用「多项研究表明\cite{key1,key2,key3}」模式 2. 限制使用小组引用（约占 25%）：必须明确说明各文献的差异化贡献 3. 禁止大组引用（<5%）：仅限综述性陈述，需充分理由

• 新增"验证要求"：写作完成后立即运行验证脚本，如单篇引用 <65% 必须重写

• 测试验证（test/v202601021642）：
• 测试方法：AI 写作模拟（轻量级测试）
• 测试场景：2 个场景（单篇引用优先 + 小组引用限制）
• 测试数据：10 篇模拟文献

测试结果：

验证标准：

测试结论：✅ 测试通过，优化效果显著，可以部署到生产环境

• 影响：
• ✅ 引用分布健康：从严重失衡（单篇 1.9%）改善为健康分布（单篇 90.0%）
• ✅ 符合人类学术写作习惯：每个观点都有明确的文献来源，读者可以追溯
• ✅ 提升综述可读性：避免"多项研究表明"这种模糊表述
• ✅ 强制执行机制：验证阈值 65%，如不达标必须修正
• ✅ 向后兼容：不影响现有工作流，仅强化约束

• 新增文件：
• test/v202601021642/TEST_PLAN.md：测试计划
• test/v202601021642/TEST_REPORT.md：测试报告
• test/v202601021642/data/references.bib：10 篇模拟文献
• test/v202601021642/data/test_scenarios_single.tex：单篇引用场景
• test/v202601021642/data/test_scenarios_group.tex：小组引用场景
• test/v202601021642/scripts/run_automated_test.py：自动化测试脚本

• 版本演进：

  v3.5 (breast-test-03)
  └─ 引用分布：单篇 1.9%，小组 98.1%（严重失衡）

  v3.8（本次优化）✅
  └─ 引用分布：单篇 90.0%，小组 10.0%（健康分布）
     └─ SKILL.md 强化约束：从"约 70%"改为"强制执行 + 验证阈值 65%"
     └─ expert-review-writing.md 新增"单篇引用优先"章节
     └─ 写作前提示模板优化：明确"单篇引用场景"和"小组引用场景"
     └─ 禁止模式：明确禁止"多项研究表明\cite{A,B,C}"

• 重要说明：
• 核心改进：从"软约束"（约 70%）升级为"硬约束"（至少 65% + 验证要求）
• 关键原则："单篇引用优先"——每个观点都有明确的文献来源
• 验证机制：写作完成后立即验证，如单篇引用 <65% 必须修正
• 适用范围：适用于所有系统综述写作，不受领域或语言限制

---

Changed（数据抽取表填充端到端验证 - AI 遵循 Prompt 时功能正常 - 2026-01-02）✅

问题修复：解决 Problems_from_breast-test-03.md 第180-220行的"数据抽取表字段未填充"问题（问题 #5，🔴 严重问题，优先级 P0）

• 问题背景（breast-test-03 实例）：
• 数据抽取表的 Design、Key findings、Limitations 三列完全为空
• 所有 154 篇文献的这三个字段都没有内容
• SKILL.md 要求 AI 评分时"同步提取数据抽取表字段"，但实际执行时 AI 没有输出 extraction 字段

• 根本原因分析：
• ✅ 代码层面：update_working_conditions_data_extraction.py 已正确支持读取 extraction 字段（v3.2 已实现）
• ✅ Prompt 层面：ai_scoring_prompt.md 已包含完整的数据抽取表字段提取说明（v3.2 已实现）
• ❌ 执行层面：breast-test-03 中 AI 评分时没有遵循 Prompt，没有输出 extraction 字段

• 端到端测试（test/v202601021616）：
• 测试流程：OpenAlex 检索 → 去重 → AI 评分 → 生成数据抽取表
• 测试数据：10 篇检索结果，5 篇有摘要，5 篇完成 AI 评分
• 关键验证：确认 AI 遵循 ai_scoring_prompt.md 时会输出 extraction 字段

• 测试结果：

• 数据抽取表示例：

• 核心发现：
• ✅ 功能正常：当 AI 遵循 ai_scoring_prompt.md 时，数据抽取表能正确填充
• ✅ 代码无需修改：update_working_conditions_data_extraction.py 已正确实现
• ⚠️ 关键前提：AI 评分时必须使用完整的 Prompt 并输出 extraction 字段

• 新增文件：
• test/v202601021616/TEST_PLAN.md：端到端测试计划
• test/v202601021616/TEST_REPORT.md：测试报告
• test/v202601021616/artifacts/scored_papers.jsonl：AI 评分结果（包含 extraction 字段）
• test/v202601021616/output/data_extraction_table.md：生成的数据抽取表

• 用户影响：
• ✅ 立即可用：功能已完全可用，确保 AI 评分时使用 references/ai_scoring_prompt.md 中的完整 Prompt
• 📝 遵循 Prompt：AI 必须遵循 Prompt 并输出 extraction 字段
• 🔍 验证输出：评分后检查 scored_papers.jsonl 是否包含 extraction 字段

• 版本演进：

  v2.x (breast-test-01)
  └─ 数据抽取表：三列空白

  v3.0-v3.1
  └─ AI 自主评分 + 子主题分组
  └─ 数据抽取表：三列仍空白（AI 未输出 extraction）

  v3.2（单元测试验证）✅
  └─ AI 评分 Prompt 增加 extraction 章节
  └─ 脚本支持读取 extraction 字段
  └─ 数据抽取表：三列已填充（测试数据验证）

  v3.7（本次端到端测试）✅
  └─ 端到端验证：检索→去重→AI评分→生成数据抽取表
  └─ 确认 AI 遵循 Prompt 时功能正常
  └─ 数据抽取表：三列已填充（真实工作流验证）

• 重要说明：
• breast-test-03 问题确认：原因是 AI 未遵循 Prompt，而非代码问题
• 功能已验证：端到端测试确认当 AI 遵循 Prompt 时功能完全正常
• 无需代码修改：update_working_conditions_data_extraction.py 和 ai_scoring_prompt.md 都已正确实现

---

Removed（弃用脚本评分，统一使用 AI 评分 - 2026-01-02）✂️

架构简化：完全弃用 score_relevance.py 脚本评分，统一使用 AI 评分

• 简化背景：
• 之前的架构试图保留"双轨制"（AI 评分 + 脚本评分）
• 但这增加了维护复杂度，且脚本评分质量远低于 AI（~60-70% vs ~90%）
• 核心洞察：Skill 本身就是在 AI 环境中执行，使用脚本评分是多此一举
• 用户决策："score_relevance.py 那一套逻辑直接弃用。要简化。"

• 简化内容：

• 删除的文件：
• ❌ scripts/score_relevance.py（脚本评分逻辑）
• ❌ test/v202601021536/（脚本评分测试目录）

• pipeline_runner.py 修改（第331-366行）：
• 移除 _score_with_script() 方法
• 简化 run_stage_3_score() 为纯提示函数
• Pipeline 的阶段3 不再执行评分，仅提示用户使用 Skill 交互模式
• 支持检查已存在的评分文件（用于 resume 流程）

• SKILL.md 修改：
• 移除"后备方案：脚本评分"章节（第74-94行）
• 移除"评分效果对比表"和"执行建议"（第164-187行）
• 简化为唯一评分方式：AI 直接评分
• 更新"环境与工具"章节，移除脚本评分引用

• 简化后的架构：

• 用户影响：
• ✅ 使用 Skill：无影响，AI 评分是唯一方式
• ⚠️ 使用 Pipeline：阶段3 会提示使用 Skill 交互模式完成评分
• ✅ 中文主题：完美支持，无兼容性问题
• ✅ 数据抽取：AI 评分同步完成，无额外步骤

• 执行流程：

1. 用户使用 Skill 进行系统综述 2. 到达阶段3时，AI（你）使用 references/ai_scoring_prompt.md 评分 3. 输出 scored_papers.jsonl 4. 如使用 Pipeline，使用 --resume-from 4 跳过阶段3，继续后续流程

• 重要说明：
• 为什么不再支持脚本评分：Skill 在 AI 环境中执行，使用脚本评分是降级方案，没有必要
• Pipeline 如何处理评分：Pipeline 的阶段3 不执行评分，仅检查已存在的评分文件
• 向后兼容性：不影响现有用户，因为 AI 评分质量远高于脚本评分

---

Changed（Pipeline 阶段3 架构优化 - AI 评分优先 - 2026-01-02）🚀

问题修复：解决 Problems_from_breast-test-03.md 第102-137行的"评分机制失效"问题（问题 #3，🔴 严重问题，优先级 P0）

• 问题背景（breast-test-03 实例）：
• 中文主题"深度学习在乳腺超声结节良恶性鉴别中的应用"导致评分失效
• 原有的脚本评分 score_relevance.py 仅支持英文分词，中文主题提取的英文 token 极少
• 所有文献评分均为 1.0（保底评分），评分分布：高/中/低 = 0/0/301
• 影响："高分优先选文"策略完全失效，选文退化为"按排序顺序取前 150 篇"

• 解决方案：统一使用 AI 评分（完全弃用脚本评分）

• AI 评分（唯一方案）：
• 使用 references/ai_scoring_prompt.md 中的完整 Prompt
• AI 直接理解中文主题，进行语义相关性评分
• 不依赖关键词匹配，完全基于语义理解
• 同步提取数据抽取表字段（design/key_findings/limitations）

• ai_scoring_prompt.md 更新（第7-30行）：
• 新增"主题语言建议（重要）"章节
• 英文主题（推荐）：AI 语义理解更准确，评分区分度更高
• 中文主题（支持）：AI 可直接理解，无语言限制

• 预期效果对比：

• 重要说明：
• 核心洞察：Skill 本身就是在 AI 环境中执行，使用脚本评分是多此一举
• 架构简化：弃用脚本评分，统一使用 AI 评分，降低维护复杂度
• 最佳实践：
• 中文主题：AI 直接评分，完美语义理解
• 英文主题：AI 直接评分，更高准确率和数据抽取
• 中英混合：AI 直接评分，无语言限制

• 影响：
• ✅ 评分机制对中文主题友好：AI 语义理解，无关键词限制
• ✅ 评分质量大幅提升：从 ~60-70% 提升到 ~90%
• ✅ 数据抽取同步完成：无需额外步骤
• ✅ 架构简化：弃用脚本评分，降低维护负担

---

Changed（引用多样性约束 - 避免引用不均 - 2026-01-02）🌐

问题修复：解决 Problems_from_breast-test-02.md 第376行的"引用多样性"问题（问题 #7，🟢 轻微问题，优先级 P2）

• 问题背景（breast-test-02 实例）：
• 引用集中在少数段落
• 部分段落无引用支撑
• 文献利用率低（149 篇 BibTeX 条目中仅 99 篇被引用，利用率 66%）
• 缺少量化指标检测引用分布均匀性

• 解决方案：扩展 validate_citation_distribution.py 添加引用多样性检测
• 4个量化指标：

1. 零引用段落率：<10%（识别无引用支撑的段落） 2. 段落引用密度方差：<3（检测引用分布不均） 3. 文献利用率：>85%（检测未被引用的文献） 4. 高频文献占比：<15%（检测过度引用，被引用≥5次的文献占比）

• 新增函数：
• parse_paragraphs()：解析 LaTeX 段落并统计每段引用数
• extract_bib_keys()：从 BibTeX 文件提取所有文献 key
• check_citation_diversity()：主检测函数，计算4个指标
• find_zero_cite_paragraphs()：找出零引用段落
• generate_diversity_recommendations()：生成针对性改进建议

• 命令行选项：
• --check-diversity / -d：启用引用多样性检测
• --bib / -b：指定 BibTeX 文件路径（用于文献利用率检测）

• 代码修改：
• 更新 extract_citations() 返回值：从 3 元组 (cite_cmd, n_keys, line_num) 改为 4 元组 (cite_cmd, n_keys, line_num, [keys])
• 同步更新 analyze_distribution() 和 find_violations() 的解包逻辑
• 新增 from statistics import stdev 导入

• 新增文件：
• test/v202601021353/：引用多样性检测测试目录
• TEST_PLAN.md：测试计划（4个场景定义）
• TEST_REPORT.md：测试报告（100% 通过率）
• run_tests.sh：自动化测试脚本
• data/test_good_diversity.tex：健康分布场景（所有指标通过）
• data/test_zero_cite.tex：零引用段落场景（触发警告）
• data/test_concentrated.tex：引用集中场景（触发警告）
• data/test_unused_refs.tex：文献利用率低场景（触发警告）
• data/references.bib：30篇文献（用于场景 B/C/D）
• data/references_small.bib：8篇文献（用于场景 A）

• 写作指南更新：references/expert-review-writing.md 第177-262行
• 新增"引用多样性约束（避免引用不均）"章节
• 包含：为什么需要引用多样性、目标指标、验证工具、改进建议、最佳实践
• 提供完整的 --check-diversity 使用示例和输出解释

• 预期效果对比：

• 测试验证结果（test/v202601021353）：
• ✅ 场景 A（健康分布）：所有指标通过
• ✅ 场景 B（零引用段落）：正确识别 40% 零引用率，触发警告
• ✅ 场景 C（引用集中）：正确识别方差 4.0，触发警告
• ✅ 场景 D（文献利用率低）：正确识别 10% 利用率，触发警告
• 通过率：100%（4/4 场景）

• 使用方法：

  # 基础引用分布检测（原有功能）
  python3 scripts/validate_citation_distribution.py review.tex

  # 启用引用多样性检测（新增功能）
  python3 scripts/validate_citation_distribution.py \
    review.tex \
    --check-diversity \
    --bib references.bib \
    --verbose

• 影响：
• ✅ 问题检测自动化：从人工检查 → 自动检测4个量化指标
• ✅ 改进建议精准化：通用建议 → 针对性问题诊断
• ✅ 测试覆盖充分：4个场景全部验证通过
• ✅ 向后兼容：新功能是可选的（--check-diversity），不影响现有工作流
• ✅ 文档完善：写作指南包含详细的引用多样性章节

---

Changed（LaTeX 模板引用优化 - 2026-01-02）🔧

问题修复：解决 Problems_from_breast-test-02.md 第128-154行的"模板文件重复复制"问题（问题 #5）

• 问题背景（breast-test-02 实例）：
• gbt7714-nsfc.bst 和 nature-reviews-template.tex 被复制到工作目录
• 每次生成综述都会创建这两个文件的副本
• 导致文件冗余、版本混乱、存储浪费

• 解决方案：使用 TEXINPUTS 和 BSTINPUTS 环境变量引用模板文件
• 新增 _setup_tex_inputs() 函数设置环境变量
• 修改 _run() 函数支持环境变量传递
• 移除 _ensure_template() 和 _ensure_bst() 的复制逻辑
• LaTeX 编译时通过环境变量查找模板，无需复制

• 技术细节：
• TEXINPUTS=.//:{template_dir}://：指定 .tex 模板搜索路径
• BSTINPUTS=.//:{template_dir}://：指定 .bst 文件搜索路径
• 跨平台兼容：自动检测平台使用正确的路径分隔符（Unix 用 :，Windows 用 ;）
• 符合 LaTeX/Kpathsea 标准搜索路径规范

• 修改文件：
• scripts/compile_latex_with_bibtex.py：
• 新增 import os（第12行）
• 新增 _setup_tex_inputs() 函数（第34-58行）
• 修改 _run() 函数支持 env 参数（第61-74行）
• 修改 compile_pdf() 函数使用环境变量（第190-211行）
• 移除模板文件复制逻辑

• 测试验证结果（test/v202601021343）：
• ✅ 测试 1：环境变量设置正确
• ✅ 测试 2：跨平台兼容性验证通过
• ✅ 测试 3：代码修改验证通过（所有关键修改点已正确实施）

• 预期效果对比：

• 使用方法：

  # 编译时自动设置环境变量，无需额外操作
  python3 scripts/compile_latex_with_bibtex.py review.tex review.pdf

• 影响：
• ✅ 减少文件冗余：每次综述节省 ~3 MB（模板和 BST 文件）
• ✅ 版本统一：模板更新自动应用到所有新综述
• ✅ 符合 LaTeX 标准：使用标准的 TEXINPUTS 机制
• ✅ 跨平台兼容：支持 Unix、macOS 和 Windows
• ✅ 向后兼容：不影响现有工作流

---

Changed（子主题数量约束 - 避免主题过多 - 2026-01-02）📊

问题修复：解决 Problems_from_breast-test-02.md 第373行的"主题过多"问题（问题 #4）

• 问题背景（breast-test-02 实例）：
• 综述包含 19 个 `\section`（不含摘要、讨论、结论）
• 主题过于分散，缺乏聚焦
• 每个主题的深度不足
• 综述更像"知识点罗列"而非"深度分析"

• 解决方案：
• AI 评分 Prompt 优化：references/ai_scoring_prompt.md 第122-144行
• 新增"写作阶段约束（关键）"章节
• 硬性约束：除摘要/引言/讨论/展望/结论外，必须有且仅有 3-7 个子主题段落
• 明确合并原则：相似方法、相关任务、学习策略
• 禁止行为：创建 10+ 个子主题 section、为单一技术点单独创建 section
• 推荐主题结构示例（5个合并后的主题）

• SKILL.md 更新：第161-171行
• 阶段5"子主题与配额规划"从 "5-7 个" 更新为 "3-7 个（硬性约束）"
• 新增子主题合并原则说明
• 明确禁止创建 10+ 个子主题 section
• 每个子主题至少应有 5 篇支撑文献

• 新增验证脚本：scripts/validate_subtopic_count.py
• 自动识别 LaTeX 中的 \section{} 标记
• 区分标准章节（摘要/引言/讨论/结论等）和子主题章节
• 验证子主题数量是否在 3-7 范围内
• 提供清晰的错误提示和合并建议

• Pipeline 集成：scripts/pipeline_runner.py
• 第471-472行：阶段5提示中新增子主题数量约束警告
• 第542-556行：阶段6中集成 validate_subtopic_count.py 验证

• 新增文件：
• scripts/validate_subtopic_count.py：子主题数量验证脚本
• test/v202601021335/：子主题数量约束测试目录
• TEST_PLAN.md：测试计划
• TEST_REPORT.md：测试报告
• data/test_good.tex：正常情况（4个子主题）
• data/test_too_few.tex：子主题过少（2个）
• data/test_too_many.tex：子主题过多（22个，模拟问题场景）
• data/test_boundary_min.tex：边界最小值（3个）
• data/test_boundary_max.tex：边界最大值（7个）

• 预期效果对比：

• 测试验证结果（test/v202601021335）：
• ✅ 场景 A（正常情况）：4个子主题，验证通过
• ✅ 场景 B（子主题过少）：2个子主题，验证失败+正确提示
• ✅ 场景 C（子主题过多）：22个子主题，验证失败+正确提示
• ✅ 场景 D1（边界最小值）：3个子主题，验证通过
• ✅ 场景 D2（边界最大值）：7个子主题，验证通过

• 使用方法：

  # 独立验证脚本
  python3 scripts/validate_subtopic_count.py --tex review.tex --min-subtopics 3 --max-subtopics 7

  # Pipeline 阶段6自动集成验证
  python3 scripts/pipeline_runner.py --topic "深度学习在乳腺超声结节良恶性鉴别中的应用"

• 影响：
• ✅ 约束明确：AI 评分 Prompt 和 SKILL.md 都明确了 3-7 个硬性约束
• ✅ 提示到位：Pipeline 阶段5 提供子主题数量警告
• ✅ 工具支持：新增验证脚本可自动检测子主题数量
• ✅ 测试覆盖：5个场景全部通过，包括边界测试
• ✅ 向后兼容：验证功能不会阻止 Pipeline 执行，仅提供警告

---

Changed（引用分布约束 - 避免引用堆砌 - 2026-01-02）📝

问题修复：解决 Problems_from_breast-test-02.md 中的引用堆砌问题（问题 #2）

• 问题背景（breast-test-02 实例）：
• 正文存在大量单次引用 10+ 篇文献的情况
• 示例（第41行）：\cite{WGANBasedSynthetic2019,...,TTCNNABreast2022} (13篇)
• 示例（第70行）：单次引用 16 篇文献
• 示例（第92行）：单次引用 15 篇文献
• 多数段落采用"陈述观点 + 堆砌大量文献"的模式
• 严重违背"专家级人类的自然论述"原则

• 解决方案：
• 新增引用分布验证脚本：scripts/validate_citation_distribution.py
• 检测 LaTeX 文件中的 \cite{} 命令分布
• 统计单篇/小组/大组引用比例
• 识别违规引用（>5篇）
• 生成详细报告和改进建议

• 更新写作指南：references/expert-review-writing.md
• 新增"引用分布约束"章节
• 目标分布：70% 单篇，25% 小组（2-4篇），<5% 大组（>4篇）
• 禁止模式：引用堆砌、集中引用
• 推荐模式：自然交替节奏
• 写作技巧：分层引用、按主题分段
• 示例对比（错误 vs 正确）

• 更新 SKILL.md 工作流：
• 阶段7（写作）新增"引用分布约束（重要）"提示
• 单次 \cite{} 默认仅包含 1-2 个 key（约 70% 情况）
• 禁止"陈述观点 + 堆砌 10+ 文献"的模式
• 优先采用"引用 + 阐述 + 再引用 + 再阐述"的自然交替节奏
• 写作前提示模板新增"引用分布约束"章节

• 集成验证功能：scripts/validate_review_tex.py
• 新增 --check-citation-dist 选项：启用引用分布检查
• 新增 --verbose 选项：显示详细报告
• 新增 _check_citation_distribution() 函数

• 新增文件：
• scripts/validate_citation_distribution.py：引用分布验证脚本
• test/v202601021217/：引用分布约束测试目录
• TEST_PLAN.md：测试计划
• TEST_REPORT.md：测试报告
• data/test_poor_citation.tex：引用堆砌示例
• data/test_good_citation.tex：健康引用示例
• data/test_complete_good.tex：完整结构示例
• data/test_references.bib：模拟参考文献

• 预期效果对比：

• 测试验证结果（test/v202601021217）：
• ✅ 脚本可执行性：validate_citation_distribution.py 正常运行
• ✅ 引用堆砌检测：正确识别 8篇文献堆砌违规
• ✅ 健康引用验证：66.7% 单篇引用，符合目标范围
• ✅ 集成验证：validate_review_tex.py --check-citation-dist 正常工作
• ✅ 报告可读性：输出清晰，包含统计和违规列表

• 使用方法：

  # 独立验证脚本
  python3 scripts/validate_citation_distribution.py review.tex

  # 集成验证（包含章节、引用等全面检查）
  python3 scripts/validate_review_tex.py \
    --tex review.tex \
    --bib references.bib \
    --check-citation-dist \
    --verbose

• 影响：
• ✅ 规范明确：写作指南包含详细的引用分布约束
• ✅ 提示到位：SKILL.md 工作流中明确引用约束要求
• ✅ 工具支持：新增验证脚本可自动检测引用堆砌
• ✅ 测试覆盖：单元测试和集成测试均通过
• ✅ 向后兼容：验证功能是可选的，不影响现有工作流

---

Changed（验证报告持久化 - 2026-01-02）📋

核心升级：验证环节结果自动持久化为 Markdown 报告，提升可观测性和可追溯性

• 问题背景（来自基于breast-test-01发现的问题.md）：
• 问题6：验证环节缺失 - 验证脚本存在且正常运行，但验证结果未持久化/未可视化
• 验证结果只在控制台输出，用户无法事后查看验证详情
• 无法追溯具体的验证数值和通过/失败状态

• 解决方案：
• 新增验证报告生成脚本：scripts/generate_validation_report.py
• 汇总 validate_counts.py 和 validate_review_tex.py 的验证结果
• 生成易于阅读的 Markdown 报告
• 包含：验证摘要、字数验证、引用数量验证、引用一致性验证、必需章节验证、总体评估、验证标准说明

• Pipeline 集成：pipeline_runner.py 阶段6 更新
• 新增 _run_script_capture_output() 方法捕获验证脚本输出
• 修改 run_stage_6_validate() 自动调用报告生成脚本
• 报告路径记录到 pipeline_state.json 的 output_files.validation_report

• 配置更新（config.yaml）：
• output.validation_report：{topic}_验证报告.md

• 新增文件：
• scripts/generate_validation_report.py：验证报告生成脚本
• test/v202601020840/：验证报告功能测试目录

• SKILL.md 更新：
• 输出文件列表从"5 件套"更新为"6 件套"（新增验证报告）
• 环境与工具章节添加 generate_validation_report.py
• 健壮性与日志章节说明验证报告功能

• 输出示例：

  ## 验证摘要
  **验证状态**: ✅ PASS

  ## 字数验证
  - **正文字数**: 15,024
    - 中文: 14,732 字
    - 英文: 292 词
  - **目标范围**: 15,000 - 20,000
  - **状态**: ✅ PASS

  ## 引用数量验证
  - **正文唯一引用数**: 80
  - **目标范围**: 80 - 150
  - **状态**: ✅ PASS

• 测试验证（test/v202601020840）：
• ✅ 脚本可执行性验证
• ✅ 报告生成验证
• ✅ 报告格式正确性验证（7个必需章节全部存在）
• ✅ 数据准确性验证（与验证脚本输出一致）
• ✅ 使用 breast-test-01 实际数据进行完整流程测试

• 影响：
• ✅ 用户可事后查看完整的验证结果
• ✅ 验证过程透明化、可追溯
• ✅ 符合"有机更新"原则：新增功能而非修改现有代码
• ✅ 向后兼容：验证脚本保持不变，报告生成是独立功能

• 版本演进：

  v3.2 (breast-test-01)
  └─ 验证环节：存在但结果未记录

  v3.3（本次修复）✅
  └─ 验证环节：自动生成验证报告
     - 验证摘要
     - 字数/引用/章节/一致性详细结果
     - 可追溯的验证标准

Changed（AI 多查询检索策略 - 2026-01-02）🔍

核心升级：从"单一查询检索"升级为"AI 驱动的多查询检索"，提升文献覆盖面

• 问题背景（来自基于breast-test-01发现的问题.md）：
• 问题5：检索策略单一：只用了 1 个查询词，199 篇检索结果可能只是冰山一角
• 潜在遗漏：使用不同术语的文献（如 CAD vs computer-aided diagnosis）、早期关键文献

• 解决方案：
• AI 生成查询变体：使用 references/ai_query_generation_prompt.md 模板，AI 从研究主题自动生成 5-10 个查询变体
• 同义词与术语变体（如 CNN ↔ convolutional neural network）
• 邻近概念扩展（如从 "深度学习" 扩展到 "迁移学习"）
• 限定词变体（添加/移除 review, systematic review 等）
• 方法论变体（ResNet, Transformer, U-Net 等具体架构）

• 多查询并行检索：新增 scripts/multi_query_search.py
• 支持从 JSON 文件读取 AI 生成的查询列表
• 并行执行多个查询，礼貌延迟避免 API 限流
• 自动去重合并（优先 DOI，其次 title+year）
• 生成详细检索日志（每个查询的返回数、新增数）

• Pipeline 集成：pipeline_runner.py 阶段1 更新
• 检查是否存在 {artifacts}/queries_{topic}.json
• 存在则使用多查询检索，否则降级为单一查询
• 新增配置项：search.max_results_per_query（默认 50）、search.max_total_results（默认 500）

• 新增文件：
• references/ai_query_generation_prompt.md：AI 多查询生成 Prompt 模板
• scripts/multi_query_search.py：多查询并行检索脚本

• 配置更新（config.yaml）：
• search.max_results_per_query：50（每查询最大结果数）
• search.max_total_results：500（合并后上限）

• 预期效果：
• 检索结果从 199 篇（单一查询）提升到 500-800 篇（多查询）
• 覆盖更多术语变体和细分方向
• 减少因术语差异导致的文献遗漏

• 测试验证（test/v202601020826）：
• 测试主题：深度学习在乳腺超声结节良恶性鉴别中的应用（与 breast-test-01 相同）
• 验证标准：
• ✅ AI 能生成 5-10 个有差异的查询
• ✅ 多查询检索返回更多文献
• ✅ 检索日志完整
• 测试脚本：test/v202601020826/test_multi_query_search.sh

• 影响：
• ✅ 提升检索召回率，减少文献遗漏
• ✅ 符合"AI 驱动"的 v3.x 设计理念
• ✅ 零额外成本：AI 已运行在环境中，查询生成是"顺手而为"
• ✅ 向后兼容：无查询文件时自动降级为单一查询

Changed（数据抽取表填充 - AI 评分同步提取 - 2026-01-02）🎯

核心升级：AI 评分时同步提取 Design/Key findings/Limitations 字段，实现"一次阅读，多重产出"

• 工作流阶段3：AI 自主评分 + 子主题分组 → `AI 自主评分 + 数据抽取（一次完成）`
• AI 在评分时，同步从摘要中提取三个字段：
• design：研究设计/方法（5-15字，如"ResNet-50+注意力机制"）
• key_findings：关键发现（10-30字，至少含1个数字，如"5000张图像，95.2%准确率"）
• limitations：局限性（5-20字，如"未报告外部验证"、"单中心"）
• 输出字段新增：extraction: {design, key_findings, limitations}

• 新增文件：references/ai_scoring_prompt.md 第124-193行
• 数据抽取表字段提取章节：详细的提取规则和示例
• 提取质量自检：4条自检标准（具体方法/量化指标/基于证据/简洁性）
• 更新 JSON 输出格式：增加 extraction 字段
• 更新所有示例：5个示例都包含完整的 extraction 数据

• 脚本更新：scripts/update_working_conditions_data_extraction.py
• 更新 Row 数据类，新增 design, key_findings, limitations 字段
• 更新 _iter_rows 函数，从 extraction 字段读取数据
• 更新 _render_table 函数，渲染新增的三列
• 更新脚本文档注释，说明 v3.2 的数据流

• SKILL.md 更新：
• 阶段3 标题改为"AI 自主评分 + 数据抽取（一次完成）"
• 增加同步提取字段的说明
• 更新输出字段列表，包含 extraction

• 测试验证结果（test/v202601020812）：
• ✅ Design 填充率：100%（目标 ≥90%）
• ✅ Key findings 填充率：100%（目标 ≥85%）
• ✅ Limitations 填充率：100%（目标 ≥70%）
• ✅ 提取准确率：100%（人工验证20篇）
• ✅ 运行时开销：无（与评分同步完成）

• 问题解决：
• ✅ 完全解决"问题3：数据抽取表未填充"（来自基于breast-test-01发现的问题.md）
• ✅ 从三列空白 → 三列100%填充
• ✅ 满足技能承诺："完整的数据抽取表"

• 影响：
• ✅ 用户可以直接使用数据抽取表进行质量评价
• ✅ AI 写作时有具体数字可引用
• ✅ 符合 PRISMA 系统综述标准
• ✅ 零额外成本：AI 已在阅读摘要，提取是"顺手而为"

Changed（子主题合并规则优化 - 2026-01-02）✅

问题解决：基于测试结果（test/v202601020800），优化 AI 评分 Prompt 的子主题分组规则，解决子主题碎片化问题。

• 新增内容：references/ai_scoring_prompt.md 第69-121行
• 核心子主题列表：15个预定义标签（方法论/学习策略/应用/综述）
• 子主题合并规则：4条合并原则
• 规则1：相似方法必须合并（如 ResNet → CNN分类）
• 规则2：细分任务归入核心类别
• 规则3：学习策略归类
• 规则4：单例子主题处理（自动合并到最相似主题）
• 最终输出要求：5-7个子主题，每主题≥2篇

• 测试验证结果（20篇模拟文献）：
• ✅ 子主题数量：11个 → 5个（54%减少）
• ✅ 每主题平均文献：1.82篇 → 4.00篇（120%提升）
• ✅ 单例子主题：7个 → 1个（86%减少）
• ✅ 语义质量：100%有意义（保持）
• ✅ 评分分布：方差5.88（保持稳定）

• 版本演进：
• v2.x (breast-test-01)：132个子主题，大量无意义标签
• v3.0 (AI自主评分)：11个子主题，100%有意义
• v3.1 (合并规则优化)：5个子主题，100%有意义，所有验证通过

• 影响：
• 提升子主题分组的收敛性和可操作性
• 为后续"子主题与配额规划"提供更清晰的输入
• 不会影响评分质量和其他验证指标

Changed（AI 自主评分 - 2025-01-02）🎯

核心升级：从"脚本驱动评分"改为"AI 自主评分"，充分利用当前环境 AI 的语义理解能力。

• 工作流阶段3：score_relevance.py → AI 自主评分 + 子主题分组
• AI 逐篇阅读 papers_deduped.jsonl 中的标题和摘要
• 按 4 个维度综合评分（任务、方法、模态、应用价值）
• 评分标准：9-10（完美匹配）、7-8（高度相关）、5-6（中等相关）、3-4（弱相关）、1-2（几乎无关）
• 同时分配子主题标签（5-7个，如"CNN分类"、"多模态融合"）
• 输出字段：score、subtopic、rationale、alignment
• 详细评分标准与 Prompt 见 references/ai_scoring_prompt.md

• 新增文件：references/ai_scoring_prompt.md
• 完整的 AI 评分 Prompt 模板
• 单篇评分、批量评分、质量自检 Prompt
• 5 个真实案例示例（完美匹配、高度相关、中等相关、弱相关、几乎无关）
• 最佳实践指南与故障排查

• 后备方案：score_relevance.py --method keyword（保留原有关键词方法作为后备）

• 预期效果：
• ✅ 评分区分度：从所有文献得1分 → 均匀分布1-10分
• ✅ 子主题分组：从132个（碎片化）→ 5-7个（有意义）
• ✅ 准确率提升：从 ~60% → ~90%
• ✅ 零额外成本：直接利用当前环境 AI，无需 API 调用

• SKILL.md 更新：
• 更新 YAML description：强调"AI 逐篇阅读并评分"
• 重写工作流阶段3：详细说明 AI 评分标准与流程
• 调整工作流阶段编号：0_setup → 1_search → 2_dedupe → 3_ai_score → 4_select → 5_subtopics → 6_word_budget → 7_write → 8_validate_export
• 新增"AI 评分与子主题分组"提示模板

Changed（数据抽取迁移 & 旧链路弃用 - 2025-12-30）

• Data Extraction Table：不再嵌入 {主题}_工作条件.md，改为生成/存放于隐藏目录 .systematic-literature-review/reference/data_extraction_table.md，正文仅引用该文件（瘦身工作条件）。update_working_conditions_data_extraction.py 支持独立表格写入，无需骨架 marker。
• 脚本入口：彻底移除旧的 Markdown 链路脚本，统一 LaTeX-first 主线。
• 工作条件校验：validate_working_conditions.py 调整为检查正文是否引用隐藏数据抽取表，而非要求内联表格。
• pipeline_runner.py：阶段 6 生成数据抽取表至隐藏目录，并记录到 state；去掉行数裁剪，默认生成完整表（用户自行节选）。

Changed（文件收纳到隐藏目录 - 2025-12-30）

• scripts/pipeline_runner.py：默认将 pipeline_state.json、checkpoints 与绝大多数中间产物写入 {work_dir}/.systematic-literature-review/（根目录只保留最终 5 个交付物）。
• scripts/pipeline_runner.py：--resume 支持直接传入 {work_dir}，并兼容旧路径 {work_dir}/pipeline_state.json（自动尝试隐藏目录位置）。
• scripts/api_cache.py：支持通过环境变量 SYSTEMATIC_LITERATURE_REVIEW_CACHE_DIR 指定缓存目录（runner 默认指向隐藏目录下的 cache）。
• test/scripts：回归脚本同步更新新的状态文件位置。
• SKILL.md / references：同步更新文件管理口径与恢复方式说明。
• scripts/organize_run_dir.py：新增可选整理脚本，将旧 run 目录中间产物迁入 .systematic-literature-review/（默认 dry-run）。
• reference/：新增 {work_dir}/.systematic-literature-review/reference/，包含
• reference.bib：本次运行“最大候选库”的 BibTeX
• filter.yaml：从最大候选库到最终 {主题}_参考文献.bib 的筛选轨迹与口径

Changed（文件命名与状态一致性 - 2025-12-30）

• scripts/pipeline_runner.py：新增 --output-stem，将“语义主题”与“文件名前缀”解耦；默认仍使用 {主题} 安全化结果。
• scripts/pipeline_runner.py：Stage 4/5 重新回填 candidate_count（使用实际参与评分/证据检查的文献列表行数），便于复盘与诊断。
• scripts/pipeline_runner.py：Stage 8 在 pipeline_state.json 中记录导出文件路径键名统一为 review_pdf / review_word（与 config.yaml 的 output.* 对齐）。
• SKILL.md：补充 --output-stem 的推荐用法（长主题/中英混排时使用短 slug）。

Changed（coverage-first + Tier 数据抽取表 - 2025-12-30）

• scripts/pipeline_runner.py：证据不足时不再只输出“降级大纲”，改为优先走 coverage_first：仍要求产出 {主题}_review.tex + {主题}_参考文献.bib 并可继续 Stage 7/8（同时保留 degraded_outline 作为补充交付物）。
• scripts/pipeline_runner.py：工作条件骨架新增 Data Extraction Table（数据抽取表） 必需模块，并为自动回填预留 marker 区域。
• scripts/update_working_conditions_data_extraction.py：新增脚本，基于 papers.jsonl + quality_report_{domain}.json 自动回填数据抽取表（包含 Tier 列）。
• scripts/validate_working_conditions.py：新增校验：数据抽取表必须包含 Tier 列。
• config.yaml：新增 writing.* 静态门槛配置（coverage-first 更高的最小唯一引用数；数据抽取表最大行数）。
• scripts/validate_review_tex.py：新增 --min-unique-cites，用于静态约束 .tex 的最小唯一引用数，防止“库里很多但正文引用很少”。
• SKILL.md：更新口径：证据不足时优先覆盖性综述（coverage-first）+ 明确证据边界，并把 Tier 纳入数据抽取表。

Changed (工作条件契约对齐 - 2025-12-30)

• SKILL.md：不再维护 {主题}_工作条件.md 的“最低模块标题清单”，改为以 scripts/pipeline_runner.py 生成的工作条件骨架为准，并以 scripts/validate_working_conditions.py 作为导出前静态门槛。
• scripts/pipeline_runner.py：将工作条件骨架标题抽为 WORKING_CONDITIONS_HEADINGS，作为骨架与校验的单一真实来源。
• scripts/validate_working_conditions.py：彻底以 pipeline_runner.py 的工作条件骨架标题为准做校验（复用 WORKING_CONDITIONS_HEADINGS + required keys），避免与 runner 漂移。

Changed (强制导出 - 2025-12-30)

核心变更：LaTeX-first + PDF/Word 强制衍生

• SKILL.md: 最终输出改为 5 个文件（3 个 AI 生成 + 2 个渲染衍生）
• AI 独立生成：{主题}_工作条件.md + {主题}_review.tex + {主题}_参考文献.bib
• 强制渲染导出：{主题}_review.pdf + {主题}_review.docx

• SKILL.md: 引用格式回归 LaTeX \cite{} + BibTeX（bst）

• scripts/pipeline_runner.py: 端到端流程对齐新输出
• 阶段 1 支持 --auto-search（读取检索计划的 queries/year_slices 做多 query 冷启动，并生成 search_log_openalex.json）
• 阶段 5 在证据不足且 --auto-search 时，默认触发 auto_supplement_search.py 做补充检索（可用 --no-auto-supplement 关闭），随后自动复跑质量评价与证据检查
• 哨兵论文输入支持“标题/作者年”自动解析：必要时调用 resolve_sentinel_dois.py 解析 Crossref → DOI 列表
• 阶段 6 强制等待 {主题}_review.tex + {主题}_参考文献.bib（不存在则中断，便于恢复）
• 阶段 7 验证改为 LaTeX+Bib 一致性校验
• 阶段 8 强制渲染：xelatex+bibtex+xelatex+xelatex 生成 PDF，并用 pandoc 导出 Word

• scripts: 新增/更新（围绕 LaTeX-first）
• scripts/openalex_search.py：OpenAlex 快速检索生成 papers.jsonl
• 新增：get_work_by_doi() 用于把哨兵 DOI 直接补进候选池（提升 coverage 稳定性）
• scripts/compile_latex_with_bibtex.py：LaTeX+BibTeX 渲染 PDF
• scripts/convert_latex_to_word.py：LaTeX+Bib 导出 Word
• scripts/validate_review_tex.py：LaTeX+Bib 最小一致性校验
• scripts/auto_supplement_search.py：从“占位脚本”升级为 OpenAlex-based 补充检索（gaps + expanded_keywords → supplemental queries → 合并候选池）

• scripts/assess_study_quality.py: 质量评价稳定性增强
• 用 API 元数据补齐缺失标题/摘要/venue/year（引文追踪合并的占位条目也可正确评分）
• OpenAlex 元数据补齐 abstract（利用 abstract_inverted_index 重建）
• 阈值/黑名单优先读 config.yaml（config_loader.py），并引入磁盘缓存减少重复 API 请求

• scripts/mcp_searcher.py: 去重策略增强（DOI → URL → title+year）

---

Removed (最终清理 - 2025-01-30)

完全移除旧的"临时文件 + 拆分脚本"工作流

• SKILL.md: 删除第 569-674 行（旧工作流文档）
• 移除"两个最终 Markdown 文件"概念
• 移除"自我验证"与拆分脚本相关的说明
• 统一为"AI 直接生成 4 个最终文件"的工作流

• 旧拆分脚本: 完全删除
• 工作流简化为直接生成，无需后处理拆分

• config.yaml: 移除相关配置节
• 删除 main_markdown 输出配置
• 移除拆分输出相关的脚本引用

• references/script-tools-guide.md: 更新文档
• 移除所有旧拆分方法的引用
• 简化"重要变更说明"为纯粹的新工作流描述

Changed (架构优化 - 2025-01-30)

核心变更：简化工作流，AI 直接生成最终文件

• SKILL.md: AI 直接生成 4 个最终文件
• 新工作流：AI 生成 {主题}_工作条件.md + {主题}_review.md
• 然后基于 review.md 生成 PDF 和 Word
• 符合 KISS 原则，逻辑更清晰，用户更易理解

• scripts/validate_review_draft.py: 支持两种输入格式
• 新格式：{主题}_review.md（纯综述正文，无 ## Review Draft 标记）
• 旧格式：systematic-literature-review_{主题}.md（完整文件，向后兼容）

• scripts/pipeline_runner.py: 适配新工作流
• 阶段 6：提示 AI 生成两个独立文件（{主题}_工作条件.md + {主题}_review.md）
• 阶段 7：验证 {主题}_review.md
• 阶段 8：基于 {主题}_review.md 生成 PDF/Word

• references/script-tools-guide.md: 更新文档以反映新工作流

---

Fixed

Added (P0 核心改进)

• P0-1: 统一配置加载器 (scripts/config_loader.py)
• 消除硬编码阈值，实现配置与代码分离
• 支持环境变量覆盖
• 提供便捷函数获取领域配置

• P0-2: MCP 检索降级机制 (scripts/mcp_searcher.py)
• 统一 MCP 多引擎检索接口（Tavily/SearXNG/Paper Search/DuckDuckGo）
• 按优先级自动降级到备用引擎
• 离线模式支持（生成检索方案）

• P0-3: 完善 Pipeline 中断恢复机制 (scripts/pipeline_runner.py)
• 阶段检查点自动保存
• 自动检测和恢复现有状态
• 友好的恢复提示和错误处理

• P0-4: API 调用缓存机制 (scripts/api_cache.py)
• 基于 URL+参数的智能缓存
• 缓存过期时间（TTL）支持
• 缓存命中率统计

Added (P1 工作流集成)

• P1-1: 自动补充检索循环 (scripts/auto_supplement_search.py)
• 分析证据缺口并自动生成针对性检索策略
• 支持多轮迭代直到满足阈值
• 迭代历史记录

• P1-2: AI 评分 Prompt 与领域检测联动 (scripts/prompt_templates.py)
• 管理跨领域评分 Prompt 模板
• 根据检测到的领域自动选择模板
• 支持 PICO/任务-数据-方法-指标等框架

• P1-3: 动态 Tier 分组 (scripts/dynamic_tier_assignment.py)
• 基于分数分布的动态阈值（百分位数/标准差/K均值）
• 分组统计和可视化
• 降级到固定阈值

• P1-4: 进度条和实时反馈 (scripts/progress_utils.py)
• 统一的进度条接口（基于 tqdm）
• 支持嵌套进度条
• 批处理进度工具

• P1-5: 友好的错误提示 (scripts/error_handling.py)
• 统一的错误消息格式
• 可操作的解决建议
• 错误分类和日志记录

Changed

• 优化 scripts/pipeline_runner.py 的恢复逻辑
• 自动检测现有状态文件
• 更友好的用户交互
• 详细的执行摘要

Technical Debt

• 以下脚本仍包含硬编码阈值，需要迁移到 config_loader.py:
• assess_study_quality.py: DEFAULT_THRESHOLDS
• 其他脚本中的类似硬编码

• 以下功能需要集成新模块:
• assess_study_quality.py 应使用 prompt_templates.py
• assess_study_quality.py 应使用 dynamic_tier_assignment.py
• 所有脚本应使用 progress_utils.py 添加进度条
• 所有脚本应使用 error_handling.py 处理错误

---

[1.0.0] - 2025-12-29

Added

• 初始版本发布
• 三维度质量框架（学术影响力/发表渠道声誉/研究相关性）
• 召回优先原则
• 降级输出策略
• 关键词扩展闭环
• 完整的 8 阶段 Pipeline
• LaTeX/Word 导出支持
• Gold Set 验证方法

Features

• P0 级别脚本（核心缺口填补）:
• assess_study_quality.py: 三维度质量评价自动化
• expand_keywords.py: 关键词扩展闭环
• check_evidence_sufficiency.py: 证据充足性自动验证

• P1 级别脚本（工作流集成）:
• detect_domain.py: 领域自动检测
• generate_degraded_outline.py: 降级输出自动化
• integrate_citation_chase.py: 引文追踪工作流集成
• validate_review_draft.py: 扩展验证检查项（已被后续 LaTeX-first 工作流取代）
• pipeline_runner.py: 完整流程自动化

• P2 级别脚本（次要优化）:
• build_search_plan.py: 离线生成检索计划
• validate_search_strategy.py: 检索策略验证
• check_citation_consistency.py: 引用一致性检查（后续被移除）
• openalex_citation_chase.py: OpenAlex 引文追踪

Documentation

• 完整的 references/ 目录（8个详细文档）
• config.yaml: 统一配置文件
• LaTeX 模板（Nature Reviews 风格）

---

[Future Plans]

Planned

• [ ] 完成技术债务清理（硬编码阈值迁移）
• [ ] 添加单元测试覆盖
• [ ] 扩展 Gold Set 验证到更多领域
• [ ] 实现并行化处理（大规模文献）
• [ ] 添加交互式 CLI 向导
• [ ] 支持更多输出格式（HTML, PowerPoint）
• [ ] 集成更多学术数据库（CNKI, WanFang）

Under Consideration

• [ ] Web UI 界面
• [ ] 云端部署支持
• [ ] 多语言支持（英文/中文）
• [ ] 协作功能（多人协作综述）

---

版本说明

• Unreleased: 正在开发中的功能
• [x.y.z]: 已发布的版本
• x: 主版本号（不兼容的 API 变更）
• y: 次版本号（向后兼容的功能新增）
• z: 修订号（向后兼容的问题修正）

贡献指南

如果您想为 systematic-literature-review 技能做贡献：

1. 遵循有机更新哲学（见 AGENTS.md） 2. 保持 P0/P1/P2 优先级 3. 更新 CHANGELOG.md 4. 添加相应的测试和文档

联系方式

• Issue Tracker: GitHub Issues
• Discussions: GitHub Discussions

人类寿命与生活方式（Premium 级）工作条件

Meta

• 主题：人类寿命与生活方式（Lifestyle factors and human longevity）
• 证据偏好：循证医学研究为主，优先大型前瞻性队列研究，其次系统综述/Meta 分析、随机对照试验（如有），并在讨论中强调因果推断与偏倚来源。
• 时间范围：以 2015–2025 年为主；允许极少数更早但具有“奠基性/方法学关键性”的证据（在正文引用中严格控制数量）。
• 档位：Premium（目标正文字数 10000–15000；目标引用 key 数 80–150）。
• 工作目录：longevity-lifestyle-01/

Search Plan

本项目使用多查询并行检索（OpenAlex），围绕“寿命/死亡结局 + 生活方式暴露 + 队列/循证研究”构建查询变体，以提升覆盖与降低无关主题比例。

查询文件：

• longevity-lifestyle-01/.systematic-literature-review/artifacts/queries_longevity_lifestyle_01.json

查询要点（示例）：

• 综合生活方式评分（healthy lifestyle score）与寿命/全因死亡
• 运动/体能/久坐与全因死亡（含加速度计研究、剂量-反应）
• 饮食模式（地中海/植物性/超加工食品等）与死亡风险
• 睡眠与昼夜节律与死亡/健康老龄化
• 烟草与酒精（含方法学争议的更新证据）
• 心理社会因素（孤独/社会隔离等）与死亡
• 衰老标志物（表观遗传钟等）与生活方式（机制与中间表型）

Search Log

检索输出：

• 候选文献库：longevity-lifestyle-01/.systematic-literature-review/artifacts/papers_longevity_lifestyle_01.jsonl
• 检索日志：longevity-lifestyle-01/.systematic-literature-review/artifacts/search_log_longevity_lifestyle_01.json

本次检索（多查询）合并后上限为 500 条候选记录；随后进入去重与评分阶段。

Dedup

去重输出：

• 去重后候选库：longevity-lifestyle-01/.systematic-literature-review/artifacts/papers_deduped_longevity_lifestyle_01.jsonl
• 去重映射：longevity-lifestyle-01/.systematic-literature-review/artifacts/dedupe_map_longevity_lifestyle_01.json

去重策略：

• 以 DOI 及标题相似度为核心，辅以 token Jaccard 与年份窗口进行合并，尽量减少同一研究的多来源重复记录。

Relevance Scoring & Selection

评分文件：

• longevity-lifestyle-01/.systematic-literature-review/artifacts/scored_papers_longevity_lifestyle_01.jsonl

评分与标注原则（面向本综述主题的定制）：

• 以“寿命/全因死亡/健康寿命/衰弱”等结局信号 + “生活方式暴露（饮食、运动/久坐、睡眠、烟酒、心理社会因素等）”为核心相关性依据。
• 对“明确的前瞻性队列/系统综述/Meta 分析/随机试验/孟德尔随机化/指南”给予加权；对非人群研究、与生活方式无关的疾病管理型指南给予惩罚。
• 时间偏好：2015–2025 年为主；2015 年以前文献在评分上被系统性降权（除非同时具备强结局 + 强暴露 + 高证据等级特征）。
• 子主题标签用于写作结构归纳，控制在 3–7 个主子主题范围内。

选文输出（按评分高优先 + 数量上限控制）：

• 选中文献：longevity-lifestyle-01/.systematic-literature-review/artifacts/selected_papers_longevity_lifestyle_01.jsonl
• 选文理由：longevity-lifestyle-01/.systematic-literature-review/artifacts/selection_rationale_longevity_lifestyle_01.yaml
• BibTeX：longevity-lifestyle-01/longevity_lifestyle_01_参考文献.bib

说明：

• BibTeX 由流水线自动生成，个别条目可能缺失 DOI/作者信息（已保留并在生成日志中提示）。正文写作时优先使用元数据更完整、且符合 2015–2025 时间窗口的研究作为关键证据。

Review Structure

正文（LaTeX）结构规划：

• 摘要
• 引言：寿命/健康寿命概念、生活方式与寿命关联的证据谱系、方法学关键点（混杂/反向因果/测量误差）
• 子主题（控制 3–7 个）：

1) 综合生活方式评分与寿命差异 2) 饮食与营养模式（含超加工食品、植物性饮食、膳食质量） 3) 运动、体能与久坐（含剂量-反应与年龄差异） 4) 睡眠与昼夜节律 5) 烟草与酒精 6) 心理社会因素与环境（孤独/社会隔离等） 7) 面向不同年龄段的人群达成长寿的最佳实践（周计划、可操作指标；结合指南/共识）

• 讨论：证据等级与因果推断、跨人群外推性、组合干预与“可行性边界”
• 展望：精细化暴露测量（可穿戴/多组学）、个体化处方与真实世界评估
• 结论：可行动要点与研究空白

Data Extraction Table（数据抽取表）

数据抽取表路径（含 score/subtopic 及简单字段抽取）：

• longevity-lifestyle-01/.systematic-literature-review/reference/data_extraction_table.md

Validation

字数预算与验证：

• 字数预算：longevity-lifestyle-01/.systematic-literature-review/artifacts/word_budget_final.csv（目标总字数约 12500）
• 最终硬校验由流水线阶段 6 触发，包含：
• 正文字数（10000–15000）
• 唯一引用 key 数（80–150）
• 必需章节存在
• \cite{key} 与 .bib 的 key 一致性

系统综述验证报告

生成时间: 2026-01-03 19:47:38 档位: premium

---

验证摘要

验证状态: ✅ PASS

---

字数验证

• 正文字数: 10,001
• 中文: 9,825 字
• 英文: 176 词
• 目标范围: 10,000 - 15,000
• 状态: ✅ PASS

引用数量验证

• 正文唯一引用数: 80
• 目标范围: 80 - 150
• 状态: ✅ PASS

引用一致性验证

• 正文引用 key 数量: 80
• BibTeX 条目数量: 154
• 状态: ✅ PASS 所有正文引用都在 BibTeX 中

必需章节验证

• 摘要: ✅ 存在
• 引言: ✅ 存在
• 子主题段: ✅ 7个
• 综合生活方式评分与寿命差异：组合暴露的价值与局限
• 饮食与营养：从饮食模式到加工度与食物环境
• 运动、体能与久坐：最稳定的“长寿杠杆”
• 睡眠与昼夜节律：被低估的长寿“基础设施”
• 烟草与酒精：确定性风险与方法学争议
• 心理社会因素与环境：孤独、社会连接与“社会处方”
• 面向不同年龄段的人群达成长寿的最佳实践：可执行的周计划
• 讨论: ✅ 存在
• 展望/结论: ✅ 存在

---

总体评估

✅ 所有验证项通过，系统综述已满足质量标准，可以继续导出 PDF/Word。

---

验证标准说明

档位 (premium) 验证阈值：

必需章节: 摘要、引言、至少1个子主题段、讨论、展望/结论

---

报告由 `generate_validation_report.py` 自动生成

Research Literature Review（相关性驱动版）— 用户使用指南

本 README 面向使用者：如何触发并正确使用 research-literature-review skill。执行指令与硬性规范在 SKILL.md；默认参数在 config.yaml。

旧名兼容

• 当前正式名：research-literature-review
• 旧名：systematic-literature-review
• 兼容状态：旧名 prompt 暂时仍会触发本 skill；安装新版本时系统级旧目录会被清理，不再保留 wrapper 目录。
• 历史工作区：.systematic-literature-review/ 保持不变，这是稳定产物目录，不等同于 skill 新名称。

快速开始

请用 research-literature-review 这个skill写一篇"xxx主题"的Premium级综述。 参考文献以近2023-2025年为主，更早之前的文献，如果特别相关、特别重要的，也可以纳入。要有一个小节，专门讨论出未来3年较有前景的研究方向。工作目录名为 XXX-01。

💡 示例：查看 examples/ 目录，包含本 skill 实际生成的专家级综述示例，可参考输出格式和质量标准。

设计理念

• AI 自定检索词 → 去重 → 标题/摘要 1–10 分相关性与子主题自动分组 → 高分优先选文 → 自动生成"综/述"字数预算（70% 引用段 + 30% 无引用段，3 次采样均值，空 ID 行支持无引用大纲） → 资深领域专家自由写作。
• 档位仅影响默认字数/参考范围（可覆盖），支持三档：Premium（旗舰级）、Standard（标准级）、Basic（基础级）。
• 强制导出 PDF/Word；硬校验：必需章节、字数 min/max、参考文献数 min/max、\cite 与 bib 对齐；可选校验字数预算覆盖率/总和。
• 最高原则：AI 不得偷懒或短视地为了速度做错误事；不确定必须说明；最终润色仅做衔接与结构调整，不得改动文献题目/摘要所含事实/数字。
• 稳健性：恢复状态时校验 papers 路径；Bib 自动转义 &、补充缺失字段并大小写无关去重 key；模板/.bst 缺失会自动回退同步。
• 多语言支持（v4.0 新增）：支持将综述翻译为多种语言（en/zh/ja/de/fr/es），自动修复 LaTeX 渲染错误，保留引用和结构不变。详见多语言支持。

字数预算的设计哲学

word_budget_final.csv 采用柔性指导而非刚性约束的设计：

• 为什么不严格限制？ 如果 AI 被强制按每篇文献的精确字数写作，会产生机械、割裂的文本，失去学术综述应有的流畅性和连贯性。
• 实际作用：字数预算作为 AI 写作时的重要参考，帮助 AI 理解各章节的相对权重和文献的重要性排序，但允许 AI 根据内容需要灵活调整。
• 预期偏差：各章节实际字数与预算偏差 ±30% 是正常的，这正是"资深领域专家自由写作"的体现。
• 硬性约束：只有总字数范围（如 6000-10000）和参考文献数范围（如 50-90）是硬性校验，确保综述的整体规模符合档位要求。

这种设计让 AI 既有章法可循，又保留了人类专家写作时的自然节奏和判断力。

关于摘要补全功能

OpenAlex 摘要缺失现状

基于对 51 个系统综述项目、共 24,315 篇文献的统计分析，我们发现从 OpenAlex 下载的文献中：

核心发现：近三分之一的文献在 OpenAlex 中没有摘要信息，且不同主题的缺失率差异显著（3.8% - 44.6%）。

摘要补全实际效果

基于对 23 个系统综述项目的统计分析，摘要补全功能的实际效果如下：

关键发现：

• 约 21.6% 的缺失摘要能够成功补全
• 补全效果高度依赖于文献领域和可获取性
• 即使补全率不高，补全的摘要对高相关文献的评估仍有重要价值
• 免费数据源（Semantic Scholar 等）存在访问限制，导致部分项目补全失败

为什么默认开启摘要补全？

尽管摘要补全会延长整体工作时间（通常增加 20-40%），但我们强烈建议保持此功能开启，理由如下：

1. 提升文献评估准确性：完整的摘要是 AI 进行相关性评分（1-10 分）和子主题分组的关键依据。缺失摘要会导致评分偏差，可能错误排除高相关文献或纳入低相关文献。

2. 保证综述质量：没有摘要的文献难以进行深度分析和批判性评估，直接影响综述的学术价值和可信度。

3. 性价比权衡：

• 关闭摘要补全：节省时间，但约 28.5% 的文献缺失摘要，影响评估准确性
• 开启摘要补全：延长 20-40% 时间，平均可补全 21.6% 的缺失摘要，显著提升文献覆盖质量
• 实际价值：即使只能补全部分摘要，这些摘要往往对应高相关文献，对综述质量影响 disproportionately 大

4. 不可逆性影响：文献筛选阶段的错误会通过后续所有环节放大，后期补救成本远高于前期摘要补全成本。

配置说明

在 config.yaml 中通过以下参数控制：

search:
  abstract_enrichment:
    enabled: true          # 是否启用摘要补齐（建议保持开启）
    stage: post_selection  # 默认：仅对 selected_papers 补齐，避免检索阶段全局补齐导致慢与 cache 膨胀
    max_papers_total: 200
    retry_rounds: 3
    min_abstract_chars: 80
    timeout_seconds: 3

cache:
  api:
    enabled: true          # 默认开启：提升稳定性、降低重复运行成本
    mode: minimal          # 默认：不缓存 OpenAlex 原始分页响应；需要更强可复现性可切 full

建议：除非时间极端受限且可接受质量损失，否则请保持 enabled: true。

档位选择指南

三档位对照表

如何选择合适的档位？

提示：覆盖默认参数

所有档位的字数和参考文献数均可通过提示词覆盖，例如：

请做"Transformer 在 NLP 中的应用"综述，标准级，正文 8000-10000 字，参考文献 70-90 篇。

提示词示例

子主题与段落配额由 AI 自动决定

最小可用

请用 research-literature-review 做主题"AI for protein design"的文献综述，基础级，近五年英文。

指定输出范围

请做"Transformer 在金融风控中的应用"综述，旗舰级，正文 12000-14000 字，参考文献 100-130 篇。

明确写作风格

请做"癌症免疫检查点抑制剂疗效预测生物标志物"的综述，旗舰级，字数范围默认，写作风格偏 Nature Reviews，子主题由你自动决定。

校验不够时的有机扩写

请在 {子主题名} 段内有机扩写，保持原主张和引用不变，只补充 2–3 条具体证据/数字/反例与衔接句；本段目标约 {目标字数} 字，当前不足 {差额} 字。原文如下：{原段落全文}

按预算写作（含无引用段落）

请读取 .bensz-api/skills/research-literature-review/{yyyy-mm-dd-hh-mm}-{safe_topic}/.systematic-literature-review/artifacts/word_budget_final.csv，引用段按每篇文献的“综/述”字数预算写，无引用段（文献ID为空，如摘要/结论/展望）按该行预算控制长度；可合并引用但需贴近预算总字数。

运行与校验（维护者）

• 自动流程：python scripts/pipeline_runner.py --topic "主题" --work-dir runs/主题

阶段：0_setup → 0.5_subtopics（写作前由 AI 给出并记录） → 1_search → 2_dedupe → 3_score → 4_select → 4.5_word_budget → 5_write → 6_validate（含有机扩写与可选预算校验） → 7_export

• 校验：validate_counts.py（字数/引用 min/max）、validate_review_tex.py（必需章节 + cite/bib 对齐）
• 导出：compile_latex_with_bibtex.py {topic}_review.tex {topic}_review.pdf；convert_latex_to_word.py ...；如需自定义模板可在 config.yaml.latex.template_path_override 或 CLI --template 指定路径（缺失会回退到内置模板并同步 .bst）。

关键文件

• SKILL.md：工作流、输入输出、最高原则与硬校验
• config.yaml：档位字数/参考范围、高分优先比例、搜索默认参数
• scripts/score_relevance.py：子主题自动分组 + 1–10 分
• scripts/select_references.py：按高分优先比例和目标数量选文，生成 Bib
• scripts/plan_word_budget.py：三次采样生成字数预算 run1/2/3 + final（含无引用空 ID 行）
• scripts/validate_word_budget.py：可选校验预算列/覆盖率/总和
• scripts/update_working_conditions_data_extraction.py：记录 score/subtopic 到数据抽取表

注意事项

• 必需章节：摘要、引言、>=1 个子主题段落、讨论、展望、结论。
• 只有字数/参考数与引用一致性是硬门槛；其余结构/密度不再强制。
• 输出文件仍采用 LaTeX-first：{topic}_review.tex/.bib → .pdf/.docx。
• 字数不足时优先在最短/缺证据的子主题段内做“有机扩写”，不新增子主题，不改原主张与引用；最终整体润色仅做衔接与结构优化，不得篡改文献事实/数字/元数据。
• resume 时若 papers 路径无效会自动清理并重新检索；中文主题缺少英文 token 会降级为字母/原始主题匹配并提示。

WHICHMODEL - 模型选择最佳实践

本节由 which-model skill 自动调研生成，最后更新：2026-01-03

场景一：文献检索与相关性评分

• 推荐模型：Claude Sonnet 4.5
• 推荐参数：
• 推理强度：medium
• Thinking 模式：开
• Temperature：0.3（确保评分稳定性）
• Max Tokens：8192
• 理由：文献评分需要理解学术论文的标题和摘要，进行语义相关性判断（1-10分）和子主题分组。Sonnet 4.5 在学术文本理解上表现优异，且性价比高，适合批量处理（50-200篇文献）。[来源：Anthropic 官方文档 - Claude Sonnet 4.5 在代码分析和学术理解上的性能提升]

场景二：综述正文写作（资深专家风格）

• 推荐模型：Claude Opus 4.5
• 推荐参数：
• 推理强度：high
• Thinking 模式：开
• Temperature：0.7（平衡学术严谨性与表达流畅性）
• Max Tokens：16384（支持长文本生成）
• 理由：综述写作需要深度合成（Synthesis）、批判性评估和逻辑架构能力。Opus 4.5 在复杂推理和长文本生成上性能最强，能确保学术质量和连贯性。[来源：Claude AI in Academic Writing - Opus 在复杂学术任务上的优势]

场景三：引用一致性核查

• 推荐模型：Claude Sonnet 4.5
• 推荐参数：
• 推理强度：medium
• Thinking 模式：开
• Temperature：0.1（最小化随机性，确保一致性）
• Max Tokens：4096
• 理由：引用对齐需要精确的语义匹配（正文片段 vs 题目/摘要），不需要复杂推理。Sonnet 4.5 在语义相似度任务上表现优异，且速度更快。[来源：Semantic Evaluation with Embeddings - Sonnet 在文本匹配任务上的表现]

场景四：快速调研（Basic 档位）

• 推荐模型：Claude Haiku 4.5
• 推荐参数：
• 推理强度：low
• Thinking 模式：关
• Temperature：0.5
• Max Tokens：4096
• 理由：Basic 档位（3000-6000字，30-60篇文献）对深度要求较低，Haiku 4.5 能提供快速、经济的解决方案。[来源：Choosing the right model - 从 Haiku 开始的渐进式升级策略]

通用原则

1. 评分阶段用 Sonnet：批量文献评分（50-200篇）需要平衡速度与准确性，Sonnet 4.5 是最佳选择 2. 写作阶段用 Opus：综述正文生成需要最强推理能力和连贯性，Opus 4.5 值得额外成本 3. 核查阶段用 Sonnet：语义匹配任务不需要最强推理，Sonnet 4.5 足够且更快 4. 快速任务用 Haiku：Basic 档位或早期验证可用 Haiku 4.5 节省成本 5. Thinking 模式建议：学术任务（评分、写作、核查）都建议开启 Thinking 模式，以确保推理质量

更新记录

• 2026-01-03：初始调研，基于 Anthropic 官方文档和第三方评测

多语言支持

概述

research-literature-review 现在支持将综述正文翻译为多种语言，并自动修复 LaTeX 渲染错误，确保 PDF 和 Word 正确输出。

支持的语言

使用示例

日语综述

请用 research-literature-review 做"AI for protein design"的日语综述，旗舰级。

德语综述

请用 research-literature-review 做"Transformer in NLP"的德语综述，标准级。

法语综述

请做"癌症免疫治疗"的法语综述，旗舰级，12000-14000 字。

工作流程

1. 语言检测：从用户输入中自动检测目标语言 2. AI 翻译：翻译正文内容，保留所有 \cite{key} 引用和 LaTeX 结构 3. 备份原文：自动备份为 {topic}_review.tex.bak 4. 覆盖原 tex：翻译后覆盖原 {topic}_review.tex 5. 智能修复编译：循环编译直到成功或触发终止条件 6. 导出 PDF/Word：成功后生成两种格式

错误处理

• 可修复错误：自动修复或提示 AI 修复（缺少宏包、字体缺失、语法错误等）
• 不可修复错误：立即停止并报告（文件权限、内存溢出等）
• 循环检测：避免重复无效修复
• 超时保护：单次编译 5 分钟，总计 30 分钟
• 失败兜底：输出错误报告 + broken 文件，可恢复备份

恢复原文

如果翻译或编译失败，可以恢复原文：

python scripts/multi_language.py --tex-file review.tex --restore

详细文档

详见 `references/multilingual-guide.md`

AI 评分迁移完成清单

历史更新核对表，仅保留仍有参考价值的完成项。

已完成的核心变更

• SKILL.md 已切到 AI 自主评分
• references/ai_scoring_prompt.md 已成为主评分模板
• 写作阶段已按 AI 评分与子主题分组重构
• 旧关键词脚本评分只保留为后备

当前口径

• 评分方式：AI 直接读标题与摘要
• 评分目标：1-10 分 + 5-7 个稳定子主题
• 主要收益：更高区分度、更少碎片化、评分与写作更连贯

仍需关注

• 实战中抽查评分分布
• 抽查子主题是否过细
• 必要时微调 Prompt，而不是回退到冗长规则文档

AI 多查询生成 Prompt 模板

用于让 AI 基于主题自动生成 5-15 组查询变体，服务多源检索。

Prompt

你是学术文献检索专家。请根据以下主题生成多组英文查询，用于 OpenAlex、PubMed、IEEE Xplore 等数据库。

主题：{topic}
领域：{domain}
时间范围：{time_range}
目标参考文献数：{target_refs}

生成原则：
1. 覆盖同义词与术语变体
2. 适度扩展邻近概念
3. 根据需要加入 review / validation / cohort 等限定词
4. 如主题涉及具体技术，补充架构名或学习策略变体
5. 避免过少（<5）或过多（>25）查询

输出 JSON：
{
  "queries": [
    {
      "query": "...",
      "rationale": "核心查询/同义词变体/方法变体/限定词变体/时间切片"
    }
  ]
}

自检

• 查询之间要有明确差异
• 尽量使用英文标准术语
• 避免晦涩到几乎没有结果的组合
• AI 生成失败时，最差也要退回单一查询

AI 自动评分 Prompt 模板

用于让宿主 AI 直接阅读标题与摘要并生成 scored_papers.jsonl。目标是高区分度评分 + 稳定子主题 + 同步数据抽取。

使用前提

• 优先用英文主题；中文主题也可，但要尽量明确研究对象、任务和方法。
• 输入至少包含：topic、title、abstract、year、venue、authors、doi

评分 Prompt（最小版）

你是一位学术文献评审专家。请评估以下论文与研究主题的相关性，并输出严格 JSON。

研究主题：{topic}
时间范围：{time_range}
核心问题：{core_question}

论文信息：
- DOI: {doi}
- 标题: {title}
- 摘要: {abstract}
- 年份: {year}
- 期刊/会议: {venue}
- 作者: {authors}

评分维度：
1. 任务匹配度
2. 方法匹配度
3. 数据模态匹配度
4. 应用价值

评分标准：
- 9.0-10.0：相同任务 + 相同方法 + 相同模态
- 7.0-8.9：相同任务，方法或模态略有差异
- 5.0-6.9：同领域但任务/方法/模态差异明显
- 3.0-4.9：仅部分概念或技术重叠
- 1.0-2.9：几乎无关

子主题规则：
- 仅当 score >= 5.0 时填写 subtopic
- score < 5.0 时，subtopic 必须为 ""
- 子主题应尽量收敛到 5-7 个簇，避免细分过度

请同步提取：
- design：研究设计/方法（5-15字）
- key_findings：关键结果（尽量含数字）
- limitations：局限性；若无证据则填“未明确提及”

只输出 JSON：
{
  "doi": "{doi}",
  "score": 0.0,
  "subtopic": "",
  "rationale": "",
  "alignment": {
    "task": "完全匹配/部分匹配/不匹配",
    "method": "完全匹配/部分匹配/不匹配",
    "modality": "完全匹配/部分匹配/不匹配"
  },
  "extraction": {
    "design": "",
    "key_findings": "",
    "limitations": ""
  }
}

子主题收敛规则

• 相似 CNN 架构统一并到 CNN分类
• Transformer / Attention / ViT 统一并到 Transformer分类
• 弱监督 / 半监督 / 多实例学习统一并到 弱监督学习
• 迁移学习 / 微调 / 预训练统一并到 迁移学习
• 单例子主题优先并入最接近的大类

输出质量自检

• 高分论文大约 20-40%
• 中分论文大约 40-60%
• 低分论文大约 10-30%
• 子主题总数控制在 5-7 个
• design 不能只写“深度学习”
• key_findings 尽量含样本量或性能指标
• limitations 没证据时写“未明确提及”

开发验证指南

面向维护者。核心目标是验证“检索策略能否覆盖应被找到的代表性文献”。

Gold Set 方法

• Gold Set = 已知必须被检索到的代表性文献集
• 构建原则：
• 代表性
• 时间 cutoff 一致
• 权威性

验证重点

• 优先看 Recall，而不是 Precision
• 先问三件事：

1. 覆盖率是否达标 2. 缺失是否集中在某个子主题/年份/venue 3. 缺口是否能映射到一个确定的扩容动作

最小流程

1. 构建或读取 Gold Set 2. 用真实检索结果对比覆盖率 3. 记录缺失 DOI 或论文 4. 决定是扩 Query、补切片、做 citation chase，还是补 metadata

常见症状与动作

相关入口

• references/ai_query_generation_prompt.md
• references/mcp-literature-search-engines.md
• scripts/openalex_citation_chase.py