🦐 PaperShrimp

智能论文筛选与深度精读系统 | 基于多维评估与 LLM 增强的科研助手

PaperShrimp 是一个全自动化的学术论文工作流系统，专为需要追踪前沿研究的研究人员设计。它集成了智能检索、多维评估、AI 深度精读和知识管理四大核心能力，帮助你在信息洪流中精准捕获高价值论文。

---

✨ 核心特性

🔍 智能检索 (Smart Search)

• OR-Batching 防熔断：将数十个关键词打包为少量批处理请求，避免 arXiv API 限流
• 时间边界早停：按提交日期排序，超出时间范围立即停止，提升效率
• 去重与过滤：自动过滤已处理论文，避免重复工作

📊 多维评估 (Multi-dimensional Scoring)

• 四维评分体系：工程应用、架构创新、理论贡献、可靠性，各维度独立评分
• 正则精准匹配：使用单词边界匹配，避免子串误判（如避免 evade 匹配 VAD）
• 否定语境感知：识别 "not open source" 等否定表达，避免误判加分
• 机构光环机制：顶级机构论文降低入围阈值（而非直接加分），防止灌水

🤖 AI 深度精读 (AI Deep Reading)

• Gemini 3.1 Pro 驱动：利用 Google 最强多模态模型进行论文解析
• 结构化输出：9大维度深度分析（核心问题→方案→架构→数据→训练→数据流→贡献→实验→思考）
• 复现级解读：不仅告诉你 "做了什么"，更告诉你 "怎么做的"，助力复现
• 用完即焚：PDF 解析完成后立即清理云端文件，防止存储配额爆炸

📁 知识管理 (Knowledge Management)

• 自动分类归档：按研究领域自动分类到对应目录
• Obsidian 兼容：生成 Markdown 格式笔记，支持 Callout、标签、双向链接
• Registry 追踪：维护已处理论文数据库，支持增量更新

---

🚀 快速开始

1. 环境准备

# 克隆仓库
git clone https://github.com/yourusername/paper-shrimp.git
cd paper-shrimp

# 安装依赖
pip install -r requirements.txt

# 配置 API Key（推荐环境变量方式）
export GEMINI_API_KEY="your-gemini-api-key"
export GEMINI_PROXY_URL="http://your-proxy:port"  # 可选

2. 配置文件

编辑 config.json，定义你的研究兴趣和评分标准：

{
  "research_domains": ["your_domain_1", "your_domain_2"],
  "search_keywords": {
    "your_domain_1": ["keyword1", "keyword2"]
  },
  "scoring": {
    "base_threshold": 70,
    "dimensions": {
      "engineering": {"weight": 1.0, "max_score": 25},
      "architecture": {"weight": 1.0, "max_score": 25},
      "theory": {"weight": 0.8, "max_score": 25},
      "reliability": {"weight": 1.0, "max_score": 25}
    }
  }
}

3. 运行工作流

# 执行完整流程：搜索 → 评估 → 精读 → 生成日报
cd ~/.openclaw/skills/paper-shrimp
python scripts/auto_pipeline.py --run

# 或分阶段执行
python scripts/auto_pipeline.py --search     # 仅搜索
python scripts/auto_pipeline.py --evaluate   # 仅评估
python scripts/auto_pipeline.py --read       # 仅精读

4. 单篇精读

# 通过 arXiv ID 精读
python scripts/single_read.py "2506.08052"

# 模糊搜索并交互选择
python scripts/single_read.py "diffusion policy robot"

# 本地 PDF 直读
python scripts/single_read.py "~/Downloads/paper.pdf"

---

🏗️ 系统架构

┌─────────────────────────────────────────────────────────────────┐
│                     PaperShrimp v5.1                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────────┐ │
│  │   Search    │───▶│  Evaluate   │───▶│   Deep Reading      │ │
│  │             │    │             │    │                     │ │
│  │ • OR-Batch  │    │ • Regex     │    │ • Gemini 3.1 Pro    │ │
│  │ • Early Stop│    │ • 4D Score  │    │ • Structured Output │ │
│  │ • Deduplicate│   │ • Threshold │    │ • Auto Cleanup      │ │
│  └─────────────┘    └─────────────┘    └─────────────────────┘ │
│         │                   │                    │              │
│         ▼                   ▼                    ▼              │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │              Knowledge Vault (Obsidian)                  │   │
│  │  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐          │   │
│  │  │Domain 1│ │Domain 2│ │Domain 3│ │Domain 4│  ...     │   │
│  │  └────────┘ └────────┘ └────────┘ └────────┘          │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

🎯 适用范围

PaperShrimp 最初为自动驾驶 + 具身智能领域设计，但架构高度模块化，可快速适配任何学术领域：

✅ 适合使用的场景

场景	说明
多领域交叉研究	需要同时追踪多个相关领域（如 CV + NLP + Robotics）
高频论文追踪	每周有大量新论文发布，需要自动筛选
深度阅读需求	不满足于摘要，需要理解方法细节以便复现
知识沉淀	希望将阅读笔记系统化、结构化地管理
团队协作	实验室/团队共享论文库和阅读笔记

⚠️ 不太适合的场景

• 单一领域深耕：如果只需追踪一个狭窄领域，arXiv 的邮件订阅可能更轻量
• 偶尔阅读：非日常科研 workflow 的一部分，手动处理可能更简单
• 非技术领域：当前设计针对 CS/AI 论文，人文社科适配需大量修改

---

🔧 适配其他领域

PaperShrimp 的设计哲学是 "配置驱动，代码无关"。要适配新领域，只需修改 config.json，无需改动代码。

步骤 1：定义研究领域

{
  "research_domains": [
    "heavy_ion_collision",
    "relativistic_hydrodynamics",
    "spin_polarization"
  ]
}

步骤 2：配置关键词

为每个领域定义搜索关键词：

{
  "search_keywords": {
    "heavy_ion_collision": [
      "quark gluon plasma",
      "qgp",
      "ultra-relativistic",
      "lhc heavy ion"
    ],
    "relativistic_hydrodynamics": [
      "viscous hydrodynamics",
      "bjorken flow",
      "isreal-stewart"
    ],
    "spin_polarization": [
      "local polarization",
      "lambda hyperon",
      "spin hydrodynamics"
    ]
  }
}

步骤 3：调整评分标准

根据领域特点调整四维评分的权重和关键词：

{
  "scoring": {
    "dimensions": {
      "engineering": {
        "max_score": 25,
        "criteria": ["open source code", "public dataset", "reproducible workflow"]
      },
      "architecture": {
        "max_score": 25,
        "criteria": ["novel simulation framework", "multi-phase model"]
      },
      "theory": {
        "weight": 1.3,  // 理论物理领域可提高权重
        "max_score": 25,
        "criteria": ["first principle derivation", "analytical solution"]
      },
      "reliability": {
        "max_score": 25,
        "criteria": ["experimental data comparison", "systematic uncertainty analysis"]
      }
    }
  }
}

步骤 4：设置机构光环

定义你关注的顶级机构：

{
  "adaptive_threshold": {
    "high_priority_institutions": [
      "Stanford",
      "MIT",
      "Google Research",
      "Facebook AI Research"
    ]
  }
}

步骤 5：配置分类目录

定义论文归档的分类结构：

{
  "paper_categories": {
    "01_相对论流体力学": ["relativistic_hydrodynamics"],
    "02_自旋极化": ["spin_polarization"],
    "03_直接光子": ["direct_photons"],
    "04_实验数据分析": ["experimental_data"],
    "05_待整理": []
  }
}

完整适配示例：高能重离子碰撞理论

{
  "version": "5.1",
  "user": "your_name",
  "research_domains": [
    "heavy_ion_collision",
    "relativistic_hydrodynamics",
    "spin_polarization",
    "direct_photons"
  ],
  "search_keywords": {
    "heavy_ion_collision": [
      "heavy ion collision",
      "quark gluon plasma",
      "qgp",
      "heavy ion physics",
      "ultra-relativistic",
      "lhc heavy ion",
      "rhic"
    ],
    "relativistic_hydrodynamics": [
      "relativistic hydrodynamics",
      "viscous hydrodynamics",
      "fluid dynamics qcd",
      "bjorken flow",
      "ganne-mcmullan",
      "isreal-stewart"
    ],
    "spin_polarization": [
      "spin polarization",
      "local polarization",
      "global polarization",
      "lambda hyperon polarization",
      "spin hydrodynamics",
      "spin-orbit coupling heavy ion"
    ],
    "direct_photons": [
      "direct photon",
      "thermal photon",
      "photon production",
      "dilepton",
      "electromagnetic probes",
      "photon elliptic flow"
    ]
  },
  "scoring": {
    "base_threshold": 70,
    "dimensions": {
      "engineering": {
        "weight": 0.7,
        "max_score": 25,
        "criteria": ["open source code", "public dataset", "reproducible workflow"]
      },
      "architecture": {
        "weight": 1.0,
        "max_score": 25,
        "criteria": ["novel hydrodynamic model", "multi-phase simulation", "event-by-event"]
      },
      "theory": {
        "weight": 1.3,
        "max_score": 25,
        "criteria": ["analytical derivation", "first principle calculation", "qcd derivation"]
      },
      "reliability": {
        "weight": 1.1,
        "max_score": 25,
        "criteria": ["experimental data comparison", "systematic uncertainty analysis", "multiple energy scans"]
      }
    },
    "bonus": {
      "hydro_spin_combined": 5,
      "experimental_collaboration": 3
    }
  },
  "adaptive_threshold": {
    "enabled": true,
    "base_threshold": 70,
    "threshold_range": [60, 80],
    "high_priority_domains": [
      "heavy_ion_collision",
      "relativistic_hydrodynamics",
      "spin_polarization"
    ],
    "high_priority_institutions": [
      "CERN",
      "BNL",
      "GSI",
      "MIT",
      "University of Illinois",
      "Ohio State University",
      "Frankfurt Institute",
      "McGill University",
      "Weizmann Institute",
      "Central China Normal University"
    ]
  },
  "auto_reading": {
    "enabled": true,
    "no_confirmation": true,
    "trigger_conditions": {
      "score_above": 70,
      "institution_match": true,
      "domain_match": true
    }
  },
  "paper_categories": {
    "01_相对论流体力学": ["relativistic_hydrodynamics"],
    "02_自旋极化": ["spin_polarization"],
    "03_直接光子": ["direct_photons"],
    "04_实验数据分析": ["experimental_data"],
    "05_待整理": []
  }
}

---

📁 目录结构

paper-shrimp/
├── scripts/
│   ├── auto_pipeline.py          # 全自动流程主控
│   ├── single_read.py             # 单篇精读网关
│   ├── daily_search.py            # OR-Batching 搜索
│   ├── batch_evaluate.py          # 四维评分评估
│   ├── gemini_deep_read_v8.py     # Gemini 精读核心
│   └── generate_daily_report.py   # 日报生成
├── config.json                    # 领域配置（用户定制）
├── SKILL.md                       # 详细使用手册
├── README.md                      # 本文件
└── requirements.txt               # Python 依赖

~/Desktop/paper_reading/           # 论文库（自动创建）
├── 01_相对论流体力学/
├── 02_自旋极化/
├── 03_直接光子/
├── 04_实验数据分析/
├── assets/                        # PDF 存储
├── inbox/                         # 搜索结果与评估数据
└── registry.json                  # 论文注册表

---

📝 定制 System Prompt

gemini_deep_read_v8.py 中的 build_system_prompt() 函数定义了 LLM 分析论文时的角色和输出格式。不同领域需要不同的专家角色和分析重点，建议根据你的研究方向修改：

修改位置

# scripts/gemini_deep_read_v8.py
def build_system_prompt(title: str, authors: List[str], arxiv_id: str) -> str:
    return f"""你是一位顶尖的[你的领域]研究员，专注于[具体方向]..."""

高能重离子碰撞理论示例

def build_system_prompt(title: str, authors: List[str], arxiv_id: str) -> str:
    return f"""你是一位顶尖的高能核物理研究员，专注于相对论重离子碰撞、QGP物态和自旋极化现象。请仔细阅读这篇PDF论文，严格按照下方的结构输出一份深入、详细、有厚度的论文解读报告。

🎯 **特殊要求（极度重要）**：必须对论文的**核心物理图像和数学推导进行深入解读**，以让读者能够理解：
1. 物理模型的假设条件及其适用性
2. 关键公式（如粘滞流体方程、自旋演化方程）的推导逻辑
3. 与实验数据（如LHC、RHIC）的对比分析方法
4. 参数敏感性分析和不确定性来源

## Report Structure

### 1. 🎯 核心问题
> [!question] 研究动机与挑战
> * **物理背景**：本文研究的QGP性质或重离子碰撞现象在核物理中的位置
> * **理论/实验缺口**：现有理论（如理想流体vs粘滞流体）或实验测量的不足
> * **本文目标**：要解决的物理问题（如确定粘滞系数、验证自旋-涡旋耦合）

### 2. 💡 理论框架
> [!summary] 物理模型与创新
> * **核心模型**：使用的理论框架（如Bjorken流、Gubser解、CEP相变）
> * **创新点**：相对于标准理论（如Israel-Stewart方程）的改进

### 3. 🏗️ 数学结构
> [!example] 公式与推导细节
> * **控制方程**：能量-动量张量、守恒方程的具体形式
> * **关键近似**：所做的物理假设（如纵向boost不变性、Navier-Stokes近似）
> * **边界/初始条件**：冻结面参数、初始熵密度分布等

### 4. 🗄️ 数值实现
> [!note] 计算方法与工具
> * **模拟代码**：使用的流体动力学代码（如MUSIC、CLVisc、iEBE）
* **网格设置**：时空离散化、数值稳定性处理
> * **粒子化**：Cooper-Frye公式、 hadron cascade 后置处理

### 5. 🏋️ 参数标定
> [!info] 参数确定与灵敏度
> * **自由参数**：比热比、粘滞系数、初始条件参数
> * **标定数据**：用于拟合的实验观测量（如椭圆流v2、平均横动量）
> * **灵敏度分析**：参数不确定性对结果的影响

### 6. 🔄 计算流程
> [!tip] 模拟步骤与数据流
> * **初始条件**：Glauber模型或IP-Glasma产生的能量密度分布
> * **流体演化**：从τ₀到τ_freeze的时空演化
> * **粒子产生**：强子谱计算与衰变链
> * **与实验对比**：观测量提取与误差分析

### 7. 🏆 物理结论与局限
> [!warning] 价值评价
> * **核心贡献**：对QGP性质的新认识或理论突破
> * **理论局限**：模型假设的适用范围、忽略效应（如强子相互作用、电磁场）

### 8. 📊 与实验对比
> [!success] 验证结果
> * **对比数据**：LHC (Pb-Pb, Xe-Xe)、RHIC (Au-Au, Cu-Cu) 不同能量点
> * **观测量**：径向流、椭圆流、直接光子谱、超子极化等
> * **拟合质量**：χ²/ndf、系统误差评估

### 9. 🧠 物理启示
> [!quote] 发散与启示
> * **与标准模型的关系**：与 lattice QCD、有效场论的关联
> * **开放问题**：仍待解决的物理难题（如初始磁场、自旋输运系数）
> * **我的研究启发**：结合我的研究方向（如相对论流体力学修正、自旋极化机制），本文能带来什么启发？
"""

其他领域参考

领域	角色设定	重点分析维度
凝聚态物理	凝聚态理论专家	哈密顿量、能带结构、对称性破缺
宇宙学	宇宙学研究员	FRW度规、扰动理论、CMB约束
粒子物理	粒子唯象学家	拉格朗日量、散射振幅、对撞机信号
生物物理	生物物理建模专家	统计力学方法、分子动力学、实验验证

---

⚙️ 高级配置

自动精读触发条件

{
  "auto_reading": {
    "enabled": true,
    "no_confirmation": true,
    "trigger_conditions": {
      "score_above": 70,
      "institution_match": true,
      "domain_match": true
    }
  }
}

自适应阈值

{
  "adaptive_threshold": {
    "enabled": true,
    "base_threshold": 70,
    "threshold_range": [60, 80],
    "high_priority_domains": ["your_p0_domain"],
    "high_priority_institutions": ["Top Lab"]
  }
}

---

🔒 隐私与安全

• API Keys: 通过环境变量注入，代码中仅使用占位符
• 本地处理: PDF 下载到本地后处理，不上传到第三方（除 Gemini API）
• 云端清理: Gemini 解析完成后立即删除云端文件

---

🤝 贡献指南

欢迎提交 Issue 和 PR！特别期待以下贡献：

• 适配更多学术领域的 config.json 示例
• 改进评分算法的规则
• 支持更多 LLM 提供商（Claude、GPT-4 等）
• 多语言支持

---

📄 许可证

MIT License - 为科研之路持续进化 🦐

---

🙏 致谢

• arXiv 提供开放的学术论文 API
• Google Gemini 提供强大的多模态理解能力
• Obsidian 提供优秀的知识管理工具

---

"在信息洪流中，让 AI 帮你筛选，让深度阅读回归本质。"