paper-human-review

name	paper-human-review
description	对边缘分数论文生成信息卡片，支持对话式实时交互（Agent 编排首选）和异步挂起（cron 兜底）。当用户说"人工审阅论文"、"捞回论文"时触发。

Paper Human Review — 对话式交互 + 异步状态机

概述

本 Skill 拦截边缘分数（4-6 分）论文，生成信息卡片供人工审阅。支持两种交互模式：

• 对话式实时交互（Agent 编排模式首选）：Agent 在对话中展示卡片 → 用户回复 accept/reject → Agent 调用 --chat-decide
• 异步状态机（cron 场景兜底）：脚本生成卡片后挂起 → 用户异步编辑 JSON → --merge 恢复

---

⚠️ 关键规则

1. 对话式交互优先：在对话中，Agent 应展示审阅卡片并收集用户决策，不挂起 Pipeline。
2. 异步不阻塞：cron 场景下脚本生成卡片、写入等待状态后立即 Exit 0 退出。
3. 三模式脚本：--init（生成卡片）、--chat-decide（对话式决策）、--merge（文件式决策）。
4. 无边缘论文时跳过：如果没有边缘论文，直接复制高分论文到输出。

---

工作流程

对话式交互流程（Agent 编排模式首选）

Step 1: 初始化审阅

python $PAPER_AGENT_ROOT/scripts/human_review.py --init --run-id {run_id}

脚本返回 JSON，其中 compact_cards 字段包含适合对话展示的精简卡片。

Step 2: Agent 展示卡片

在对话中将 compact_cards 内容展示给用户，示例：

发现 3 篇边缘论文需要您判断：

📄 [1] (5pts) Semantic ID Generation for Recommendation
   ID: 2603.01234 [generative_rec, semantic_id]
   This paper proposes a novel approach to generate semantic...

📄 [2] (4pts) Collaborative Filtering with Transformers
   ID: 2603.05678 [collaborative_filtering]
   We present a transformer-based collaborative filtering...

请回复 accept/reject 决定，例如：
  "accept 1, reject 2"
  或 "accept all" / "reject all"

Step 3: 收集用户决策

等待用户回复。用户可能以多种方式回复：

• "accept 1, reject 2, accept 3"
• "accept 论文A, reject 论文B"
• "accept all"
• "reject all"

Step 4: Agent 解析决策并调用脚本

将用户回复解析为标准 JSON 格式，调用：

python $PAPER_AGENT_ROOT/scripts/human_review.py --chat-decide '[{"arxiv_id":"2603.01234","decision":"accept"},{"arxiv_id":"2603.05678","decision":"reject"}]' --run-id {run_id}

脚本将合并高分论文与捞回论文，输出 skill3_final_selection.json。

---

异步状态机流程（cron 场景兜底）

默认模式 — 生成卡片并挂起

python $PAPER_AGENT_ROOT/scripts/human_review.py --init --run-id {run_id}

脚本将：

1. 从 skill2_scored_results.json 读取边缘区论文
2. 生成信息卡片（Markdown 文件 + stdout 精简格式）
3. 输出 skill3_review_pending.json
4. 如果在 cron 模式，更新 pipeline_state.json 为 waiting_for_human
5. 尝试通过 webhook 通知用户
6. Exit 0 退出，不阻塞

用户异步审阅

用户创建 skill3_human_decisions.json：

[
  {"arxiv_id": "2603.01234", "decision": "accept", "note": "有启发性"},
  {"arxiv_id": "2603.05678", "decision": "reject", "note": "不太相关"}
]

--merge 模式 — 恢复并合并

python $PAPER_AGENT_ROOT/scripts/human_review.py --merge --run-id {run_id}

---

超时处理

如果超过 wait_deadline 仍未收到决策，按 profile.yaml 中的策略处理：

• "discard"（默认）：只保留高分区论文
• "accept"：保留高分区 + 全部边缘论文

python $PAPER_AGENT_ROOT/scripts/human_review.py --timeout --policy discard --run-id {run_id}

---

输出文件

文件	说明	产出模式
skill3_review_cards.md	信息卡片（Markdown 格式）	--init
skill3_review_pending.json	待审阅边缘论文列表	--init
skill3_human_decisions.json	审阅决策	--chat-decide / 用户手动
skill3_final_selection.json	最终选中论文列表	--chat-decide / --merge

---

通知方式

通知渠道	实现方式	优先级
对话展示	Agent 在对话中展示 compact_cards	首选（Agent 编排模式）
Webhook 通知	通过 webhook 推送（cron 场景）	次选
本地 Markdown	写入 skill3_review_cards.md	必须支持（兜底）