paper-relevance-scorer

name	paper-relevance-scorer
description	对搜索到的论文进行相关性评分（0-10分），采用三步式 Agent 编排：脚本准备上下文→Agent LLM 打分→脚本后处理。当用户说"给这些论文打分"、"评估论文相关性"时触发。

Paper Relevance Scorer — 三步式相关性打分（Agent 编排模式核心）

概述

本 Skill 是 Agent 编排模式的核心体现。评分流程分为三步：

1. 脚本准备上下文 → 生成 skill2_scoring_context.json
2. Agent LLM 打分 → 逐篇评分，写入 skill2_agent_raw_output.json
3. 脚本后处理 → 解析、加分、分区，输出 skill2_scored_results.json

---

⚠️ 关键规则

1. 严格 JSON 输出：Agent 打分结果必须为纯 JSON 数组，禁止任何 Markdown 修饰符、寒暄语、解释性文字。
2. 逐篇评分：对每篇论文独立评分，输出评分分数、评分理由和语义标签。
3. 容错兜底：如果 Agent 输出格式异常，后处理脚本会自动容错提取 JSON 并降级处理。

---

工作流程

Step 1: 准备打分上下文（脚本）

python $PAPER_AGENT_ROOT/scripts/scorer_utils.py --prepare --run-id {run_id}

脚本将：

1. 从 seed_papers.json 中选取 role: "foundational" 的论文（≤3 篇）
2. 构建 few-shot 正样本（title + abstract + 高分示例）
3. 从 profile.yaml 读取研究方向描述
4. 读取 skill1_search_results.json 中的论文列表
5. 输出 skill2_scoring_context.json（含 papers 列表、few-shot 示例、完整打分 prompt）

Step 2: Agent 执行打分（你来做）

请读取 pipeline_data/{run_id}/skill2_scoring_context.json 中的打分上下文。

对列表中的每篇论文，根据以下信息进行 0-10 分的相关性评分：

评分维度：

• 与用户研究方向（参见 profile.yaml 中的 research_description）的直接相关度
• 方法论创新性
• 与核心论文（seed_papers.json 中 role 为 foundational 的论文）的技术关联度
• 潜在实验价值（对比基线、技术复用）

评分标准校准（Few-shot 正样本）：

以下核心论文应被视为 9-10 分 的标杆。具体示例见 skill2_scoring_context.json 中的 fewshot_examples 字段。

输出格式要求 — 极其重要：

将评分结果写入 pipeline_data/{run_id}/skill2_agent_raw_output.json。

直接输出 JSON 数组。每个元素为一篇论文的打分结果：

[
  {
    "arxiv_id": "2603.01234",
    "relevance_score": 8,
    "scoring_rationale": "该论文提出了与用户研究方向高度相关的新方法...",
    "tags": ["relevant_method", "novel_approach"]
  },
  {
    "arxiv_id": "2603.05678",
    "relevance_score": 3,
    "scoring_rationale": "该论文关注传统协同过滤，与生成式推荐方向关联较弱...",
    "tags": ["collaborative_filtering"]
  }
]

禁止包含任何 Markdown 代码块修饰符（如 ```json） 禁止包含任何解释性文字、过渡句、寒暄语 禁止在 JSON 之前或之后附加任何非 JSON 内容

Step 3: 后处理（脚本）

python $PAPER_AGENT_ROOT/scripts/scorer_utils.py --postprocess --run-id {run_id}

脚本将：

1. 使用容错 JSON 提取器解析 skill2_agent_raw_output.json
2. 对白名单作者论文标注 is_whitelist_author: true 并 +1 分
3. 对顶会论文标注 is_top_venue: true 并 +1 分
4. 按评分排序，分为三个区间（高分区 ≥7 / 边缘区 4-6 / 低分区 ≤3）
5. 输出 skill2_scored_results.json

---

输出文件

文件	说明	产出步骤
skill2_scoring_context.json	评分上下文（papers + few-shot + prompt）	Step 1 (--prepare)
skill2_agent_raw_output.json	Agent LLM 评分原始输出	Step 2 (Agent)
skill2_scored_results.json	最终评分结果（分三区）	Step 3 (--postprocess)

skill2_scored_results.json 格式

{
  "high": [
    {
      "arxiv_id": "2603.01234",
      "title": "...",
      "relevance_score": 9,
      "scoring_rationale": "...",
      "tags": ["generative_rec"],
      "is_whitelist_author": true,
      "is_top_venue": false
    }
  ],
  "edge": [...],
  "low": [...]
}

---

降级策略

场景	处理
Agent 输出夹带 Markdown 修饰符	容错 JSON 提取器自动剥离
Agent 输出完全无法解析	所有论文赋予默认分数 5 + scoring_failed: true
单篇论文缺少必要字段	填充默认值（score=5, rationale="N/A"）
Agent 遗漏某些论文	遗漏论文赋予默认分数 5 + scoring_failed: true