Upload folder using huggingface_hub

.claude/settings.local.json

@@ -0,0 +1,39 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(pip install *)",
+      "Bash(python direction_analyzer.py)",
+      "Bash(python repo_evaluator.py)",
+      "Bash(python test_agents.py)",
+      "WebSearch",
+      "mcp__filesystem__read_media_file",
+      "Bash(python -c \"import run; print\\('run.py 导入成功'\\)\")",
+      "Bash(python -c \"from app import format_report; print\\('app.py 导入成功'\\)\")",
+      "Bash(python -c ' *)",
+      "Bash(ls -la *.txt *.md .gitignore)",
+      "Bash(cat requirements.txt)",
+      "Bash(python run.py https://arxiv.org/abs/2011.08785)",
+      "Bash(export GITHUB_TOKEN=\"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\")",
+      "Bash(timeout 15 python app.py.)",
+      "Bash(python -c \"import gradio; print\\(f'Gradio {gradio.__version__}'\\)\")",
+      "Bash(python run.py https://arxiv.org/abs/1706.03762)",
+      "Bash(python app.py)",
+      "Bash(taskkill //F //IM python.exe)",
+      "Read(//dev/**)",
+      "Bash(tasklist)",
+      "Bash(python -u app.py)",
+      "Bash(mkdir -p \"C:\\\\Users\\\\Yuan Xin\\\\.cache\\\\huggingface\\\\gradio\\\\frpc\")",
+      "Bash(curl -L -o \"C:\\\\Users\\\\Yuan Xin\\\\.cache\\\\huggingface\\\\gradio\\\\frpc\\\\frpc_windows_amd64_v0.3\" \"https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_windows_amd64.exe\")",
+      "Bash(where ngrok *)",
+      "Bash(export HF_ENDPOINT=https://hf-mirror.com)",
+      "Bash(curl -L -o \"C:\\\\Users\\\\Yuan Xin\\\\.cache\\\\huggingface\\\\gradio\\\\frpc\\\\frpc_windows_amd64_v0.3\" \"https://hf-mirror.com/frpc-gradio-0.3/resolve/main/frpc_windows_amd64.exe\")",
+      "Bash(python *)",
+      "Bash(curl -L -o \"C:\\\\Users\\\\Yuan Xin\\\\AppData\\\\Local\\\\Programs\\\\Python\\\\Python311\\\\Lib\\\\site-packages\\\\gradio\\\\frpc_windows_amd64_v0.3\" \"https://hf-mirror.com/frpc-gradio-0.3/resolve/main/frpc_windows_amd64.exe\")",
+      "Bash(curl *)",
+      "Bash(gradio deploy *)",
+      "Bash(pip freeze *)",
+      "Bash(huggingface-cli whoami *)",
+      "Bash(hf auth *)"
+    ]
+  }
+}

.env.backup

@@ -0,0 +1,2 @@
+GITHUB_TOKEN=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
+NGROK_AUTH_TOKEN=3DHp7jn8WuHK6PhtgOTTAcmptnT_5ZdsV7VpfD6WQTKDeYD9r

.gitignore

@@ -0,0 +1,16 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.egg-info/
+
+# Environment
+.env
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db

.gradio/certificate.pem

@@ -0,0 +1,31 @@
+-----BEGIN CERTIFICATE-----
+MIIFazCCA1OgAwIBAgIRAIIQz7DSQONZRGPgu2OCiwAwDQYJKoZIhvcNAQELBQAw
+TzELMAkGA1UEBhMCVVMxKTAnBgNVBAoTIEludGVybmV0IFNlY3VyaXR5IFJlc2Vh
+cmNoIEdyb3VwMRUwEwYDVQQDEwxJU1JHIFJvb3QgWDEwHhcNMTUwNjA0MTEwNDM4
+WhcNMzUwNjA0MTEwNDM4WjBPMQswCQYDVQQGEwJVUzEpMCcGA1UEChMgSW50ZXJu
+ZXQgU2VjdXJpdHkgUmVzZWFyY2ggR3JvdXAxFTATBgNVBAMTDElTUkcgUm9vdCBY
+MTCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBAK3oJHP0FDfzm54rVygc
+h77ct984kIxuPOZXoHj3dcKi/vVqbvYATyjb3miGbESTtrFj/RQSa78f0uoxmyF+
+0TM8ukj13Xnfs7j/EvEhmkvBioZxaUpmZmyPfjxwv60pIgbz5MDmgK7iS4+3mX6U
+A5/TR5d8mUgjU+g4rk8Kb4Mu0UlXjIB0ttov0DiNewNwIRt18jA8+o+u3dpjq+sW
+T8KOEUt+zwvo/7V3LvSye0rgTBIlDHCNAymg4VMk7BPZ7hm/ELNKjD+Jo2FR3qyH
+B5T0Y3HsLuJvW5iB4YlcNHlsdu87kGJ55tukmi8mxdAQ4Q7e2RCOFvu396j3x+UC
+B5iPNgiV5+I3lg02dZ77DnKxHZu8A/lJBdiB3QW0KtZB6awBdpUKD9jf1b0SHzUv
+KBds0pjBqAlkd25HN7rOrFleaJ1/ctaJxQZBKT5ZPt0m9STJEadao0xAH0ahmbWn
+OlFuhjuefXKnEgV4We0+UXgVCwOPjdAvBbI+e0ocS3MFEvzG6uBQE3xDk3SzynTn
+jh8BCNAw1FtxNrQHusEwMFxIt4I7mKZ9YIqioymCzLq9gwQbooMDQaHWBfEbwrbw
+qHyGO0aoSCqI3Haadr8faqU9GY/rOPNk3sgrDQoo//fb4hVC1CLQJ13hef4Y53CI
+rU7m2Ys6xt0nUW7/vGT1M0NPAgMBAAGjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNV
+HRMBAf8EBTADAQH/MB0GA1UdDgQWBBR5tFnme7bl5AFzgAiIyBpY9umbbjANBgkq
+hkiG9w0BAQsFAAOCAgEAVR9YqbyyqFDQDLHYGmkgJykIrGF1XIpu+ILlaS/V9lZL
+ubhzEFnTIZd+50xx+7LSYK05qAvqFyFWhfFQDlnrzuBZ6brJFe+GnY+EgPbk6ZGQ
+3BebYhtF8GaV0nxvwuo77x/Py9auJ/GpsMiu/X1+mvoiBOv/2X/qkSsisRcOj/KK
+NFtY2PwByVS5uCbMiogziUwthDyC3+6WVwW6LLv3xLfHTjuCvjHIInNzktHCgKQ5
+ORAzI4JMPJ+GslWYHb4phowim57iaztXOoJwTdwJx4nLCgdNbOhdjsnvzqvHu7Ur
+TkXWStAmzOVyyghqpZXjFaH3pO3JLF+l+/+sKAIuvtd7u+Nxe5AW0wdeRlN8NwdC
+jNPElpzVmbUq4JUagEiuTDkHzsxHpFKVK7q4+63SM1N95R1NbdWhscdCb+ZAJzVc
+oyi3B43njTOQ5yOf+1CceWxG1bQVs5ZufpsMljq4Ui0/1lvh+wjChP4kqKOJ2qxq
+4RgqsahDYVvTH9w7jXbyLeiNdd8XM2w9U/t7y0Ff/9yi0GE44Za4rF2LN9d11TPA
+mRGunUHBcnWEvgJBQl9nJEiU0Zsnvgc/ubhPgXRR4Xq37Z0j4r7g1SgEEzwxA57d
+emyPxgcYxn/eR44/KJ4EBs+lVDR3veyJm+kXQ99b21/+jh5Xos1AnX5iItreGCc=
+-----END CERTIFICATE-----

.gradio/flagged/dataset1.csv

@@ -0,0 +1,4 @@
+论文 arxiv 链接,研究方向全景研报,timestamp
+,"## ⚠️ 请输入 arxiv 论文链接
+
+示例: `https://arxiv.org/abs/2011.08785`",2026-05-05 10:05:48.041973

README.md

@@ -1,13 +1,14 @@
 ---
 title: ResearchRadar
-emoji: 🚀
-colorFrom: yellow
-colorTo: gray
+app_file: app.py
 sdk: gradio
 sdk_version: 6.14.0
-python_version: '3.13'
-app_file: app.py
-pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# ResearchRadar — 研究方向全景 + 开源代码评估
+
+输入一篇 AI 论文的 arxiv 链接，自动生成研究方向全景研报：
+
+1. **研究方向全景** — 子领域定位 + 方法族谱系 + 开源覆盖度
+2. **开源实现评估** — 六维度打分（环境配置、文档、代码、社区、依赖、对比实验适配度）
+3. **对比实验推荐** — 按就绪度分组（可直接用 / 需修改 / 仅参考）

ResearchRadar_Week1_Demo_方案.md

@@ -0,0 +1,1225 @@
+# ResearchRadar 项目任务书
+
+> 读者：甲、乙（研一，均为 Python 入门水平）
+> 用途：第一周演示汇报 + 后续 6 周开发的执行依据
+> 汇报对象：导师 + 投资人 | 时长：6 分钟
+
+---
+
+## 一、项目定义
+
+### 1.1 我们要解决什么问题
+
+AI 研究者读到一篇论文后，想在该方向开展研究、写论文跑对比实验，面临三个递进的痛点：
+
+| 痛点 | 具体描述 | 人工耗时 |
+|------|----------|----------|
+| **摸清方向难** | 读完一篇论文，想知道这个研究方向有哪些主流方法族、各自有什么开源实现、目前前沿在哪里——信息分散在 GitHub、PapersWithCode、知乎、各实验室主页，拼凑全景图极费时间 | 1~2 天 |
+| **找对代码难** | 即便找到一堆仓库，也分不清哪个是"官方实现"、哪个是"社区最热复现"、哪个只是"只有 README 的空壳" | 半天~1 天 |
+| **评估能不能跑难** | 看中一个仓库想拿来跑对比实验，装了两天环境发现依赖崩了、数据集没公开、训练脚本跑不通 | 半天~1 天 |
+
+**ResearchRadar 做的事情**：输入一篇论文的 arxiv 链接，自动完成「摸清研究方向全景 → 找到高质量开源实现 → 评估可复现性 → 推荐最适合拿来做对比实验的仓库」。
+
+### 1.2 输入与输出
+
+```
+输入：一篇论文的 arxiv URL（如 https://arxiv.org/abs/1706.03762）
+  ↓
+输出：一份"研究方向全景研报"，包含：
+  1. 研究方向解读：这篇论文属于什么子领域、该领域有哪些主流方法族
+  2. 开源实现全景图：每个方法族下有哪些高质量仓库（含 star、维护状态、方法类型）
+  3. 每个仓库的可复现性评分（0-100）+ 五维度明细 + 判定理由
+  4. 对比实验推荐：哪些仓库可以直接拿来跑 baseline / 对比实验，为什么
+```
+
+### 1.3 核心价值链（三层）
+
+```
+论文输入
+  ↓
+┌─────────────────────────────────────────────┐
+│  第一层：研究方向解析                         │
+│  LLM 理解论文 → 识别子领域 → 梳理方法族谱系    │
+│  输出：该方向的"研究地图"                     │
+├─────────────────────────────────────────────┤
+│  第二层：开源代码发现                         │
+│  针对每个方法族搜索 GitHub → 去重 → 初筛       │
+│  输出：按方法族分类的候选仓库列表               │
+├─────────────────────────────────────────────┤
+│  第三层：可复现性评估 + 对比实验适配度         │
+│  抓 README + 依赖 → LLM 多维度评分             │
+│  输出：排名 + 推荐 + 风险提示                  │
+└─────────────────────────────────────────────┘
+  ↓
+研报输出（研究方向全景 + 代码推荐 + 复现风险评估）
+```
+
+**三层缺一不可**：不解析方向就搜不准代码，不评估就不知道能不能跑，最终目标是为研究者写论文跑对比实验提供可靠的后备代码库。
+
+---
+
+## 二、系统架构
+
+### 2.1 总体架构图
+
+```
+                          ┌──────────────────────────────────────────┐
+                          │            ResearchRadar 系统              │
+                          │                                          │
+  用户输入 arxiv URL ──→  │  ┌──────────────────────────────────┐    │
+                          │  │  第一层：研究方向解析（Agent）      │    │
+                          │  │                                  │    │
+                          │  │  1. arxiv API → 论文元信息         │    │
+                          │  │  2. LLM → 子领域识别 + 方法族梳理  │    │
+                          │  │  3. LLM → 为每个方法族生成搜索词   │    │
+                          │  │  输出：研究方向 "地图"              │    │
+                          │  └──────────────┬───────────────────┘    │
+                          │                 ↓                        │
+                          │  ┌──────────────────────────────────┐    │
+                          │  │  第二层：开源代码发现（Workflow）   │    │
+                          │  │                                  │    │
+                          │  │  1. GitHub Search → 多关键词搜索  │    │
+                          │  │  2. 去重 + 按方法族归类            │    │
+                          │  │  3. 初筛（star/更新时间/语言）     │    │
+                          │  │  输出：按方法族分类的候选仓库列表   │    │
+                          │  └──────────────┬───────────────────┘    │
+                          │                 ↓                        │
+                          │  ┌──────────────────────────────────┐    │
+                          │  │  第三层：评估与推荐（Agent）       │    │
+                          │  │                                  │    │
+                          │  │  对每个候选仓库：                  │    │
+                          │  │  1. 抓 README + 依赖文件（Workflow）│   │
+                          │  │  2. LLM → 可复现性五维度评分       │    │
+                          │  │  3. LLM → 对比实验适配度评估       │    │
+                          │  │  4. 综合排序 + 生成推荐理由        │    │
+                          │  └──────────────┬───────────────────┘    │
+                          │                 ↓                        │
+                          │      研究方向全景研报（Markdown）         │
+                          └──────────────────────────────────────────┘
+```
+
+### 2.2 架构中的两类组件
+
+按照路线大纲的约定，整个系统包含两类组件：
+
+| 类型 | 定义 | 本系统中的对应 |
+|------|------|---------------|
+| **Workflow**（路径写死） | 确定性流程，不涉及 LLM 决策 | 论文信息抓取、GitHub 搜索、依赖文件扫描、仓库元信息抓取、去重归类 |
+| **Agent**（LLM 决策） | 需要 LLM 理解和判断的节点 | 研究方向解析、方法族梳理、搜索词生成、可复现性评分、对比实验适配度评估 |
+
+**Week 1 只实现 Workflow + 最简单的 Agent**（baseline 方案，单次 LLM 调用出评分，不涉及回环）。对于三层架构，Week 1 三个层都会实现但每层只保留最简版本：
+- 第一层：1 次 LLM 调用完成方向解析 + 关键词生成
+- 第二层：直接用关键词搜 GitHub，不加方法族归类（归类逻辑 Week 3 加）
+- 第三层：1 次 LLM 调用完成可复现性评分 + 对比实验适配度（合并为一个 prompt）
+
+---
+
+## 三、技术选型
+
+| 项 | 选型 | 理由 |
+|----|------|------|
+| **编程语言** | Python 3.10+ | 两人都会，生态最好 |
+| **LLM 调用** | DeepSeek API（OpenAI SDK） | 你们有无限额度的 key，中文能力强，便宜 |
+| **论文信息** | arxiv REST API | 免费、无需认证、覆盖所有 AI 论文 |
+| **代码搜索** | GitHub Search REST API | 免费（带 token 30次/分钟），可按关键词、语言、star 筛选 |
+| **数据抓取** | `requests` + 标准库 | 不引入爬虫框架 |
+| **UI** | Gradio | 路线大纲已定死，轻量够用 |
+| **状态管理** | Python dict | 不引入任何状态管理框架 |
+| **包管理** | pip + requirements.txt | 两人都在 Windows 上，简单第一 |
+
+---
+
+## 四、第一周 MVP 范围
+
+### 4.1 MVP 目标
+
+**一句话**：`python run.py <arxiv_url>` 能跑通完整链路——从论文到推荐仓库。
+
+### 4.2 MVP 包含什么（7 个模块）
+
+```
+模块 1: 论文信息抓取           arxiv API → 标题、摘要、作者、分类
+模块 2: 研究方向解析 + 关键词   LLM → 子领域识别 + 方法族梳理 + 搜索词生成（1 次调用完成）
+模块 3: GitHub 代码搜索        GitHub Search API → 多关键词搜索，去重，按 star 排序
+模块 4: 仓库详情抓取           对 top 5 候选仓库：抓 README + 依赖文件 + 元信息
+模块 5: 可复现性 + 适配度评估  LLM → 六维度评分（可复现性 5 维 + 对比实验适配度）
+模块 6: 排序推荐               综合加权排序，生成推荐理由
+模块 7: Gradio 研报输出        结构化 Markdown：方向全景 + 仓库排行 + 推荐建议
+```
+
+### 4.3 MVP 不包含什么
+
+- ❌ Issue 抓取与分析（模块过大，Week 2 加）
+- ❌ Agent 回环机制（Week 4 加）
+- ❌ 流式输出（Week 5 加）
+- ❌ 多轮并发（始终串行，先跑通再优化）
+- ❌ 复杂的错误恢复（网络挂了就报错，不吞异常）
+
+---
+
+## 五、甲的任务（数据层）
+
+甲负责 **所有与外部 API 打交道** 的模块：论文信息、代码搜索、仓库详情抓取、评测集建设。
+
+### 5.1 模块 1：论文信息抓取 `paper_fetcher.py`
+
+**做什么**：输入 arxiv URL → 输出论文标题、摘要、作者、分类标签。
+
+**技术要点**：
+- arxiv API 端点：`http://export.arxiv.org/api/query?id_list={arxiv_id}&max_results=1`
+- 返回 Atom XML 格式，用标准库 `xml.etree.ElementTree` 解析，**不引入额外依赖**
+- **必须加 User-Agent 请求头**，否则 arxiv 可能拒绝请求
+- arxiv ID 从 URL 中提取：`https://arxiv.org/abs/1706.03762` → `1706.03762`，兼容 `abs`、`pdf` 等前缀
+
+```python
+# paper_fetcher.py
+import urllib.request
+import urllib.error
+import xml.etree.ElementTree as ET
+import re
+
+def extract_arxiv_id(url: str) -> str:
+    """从 arxiv URL 提取论文 ID
+    支持格式:
+    - https://arxiv.org/abs/1706.03762
+    - https://arxiv.org/abs/1706.03762v2
+    - https://arxiv.org/pdf/1706.03762.pdf
+    - arxiv:1706.03762
+    - 1706.03762
+    """
+    # 尝试匹配 URL 格式
+    match = re.search(r'arxiv\.org/(?:abs|pdf)/(\d{4}\.\d{4,5})(?:v\d+)?(?:\.pdf)?', url)
+    if match:
+        return match.group(1)
+    # 尝试匹配 arxiv:ID 或直接 ID 格式
+    match = re.search(r'(?:arxiv:)?(\d{4}\.\d{4,5})', url)
+    if match:
+        return match.group(1)
+    raise ValueError(f"无法从 URL 提取 arxiv ID: {url}")
+
+def fetch_paper_info(arxiv_url: str) -> dict:
+    """从 arxiv 获取论文元信息
+    返回: {"arxiv_id": str, "title": str, "abstract": str,
+           "authors": [str, ...], "categories": [str, ...], "published": str}
+    """
+    arxiv_id = extract_arxiv_id(arxiv_url)
+    api_url = f"http://export.arxiv.org/api/query?id_list={arxiv_id}&max_results=1"
+
+    req = urllib.request.Request(api_url, headers={"User-Agent": "ResearchRadar/1.0"})
+    try:
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            xml_text = resp.read().decode("utf-8")
+    except urllib.error.HTTPError as e:
+        raise RuntimeError(f"arxiv API 请求失败 (HTTP {e.code})，请检查论文 ID 是否正确")
+    except urllib.error.URLError as e:
+        raise RuntimeError(f"无法连接 arxiv API，请检查网络: {e.reason}")
+
+    root = ET.fromstring(xml_text)
+    ns = {
+        "atom": "http://www.w3.org/2005/Atom",
+        "arxiv": "http://arxiv.org/schemas/atom",
+    }
+
+    entry = root.find("atom:entry", ns)
+    if entry is None:
+        raise ValueError(f"arxiv 未找到论文 {arxiv_id}，请检查 ID 是否正确")
+
+    title_el = entry.find("atom:title", ns)
+    summary_el = entry.find("atom:summary", ns)
+    title = title_el.text.strip().replace("\n", " ") if title_el is not None and title_el.text else ""
+    abstract = summary_el.text.strip().replace("\n", " ") if summary_el is not None and summary_el.text else ""
+
+    authors = [
+        a.find("atom:name", ns).text
+        for a in entry.findall("atom:author", ns)
+        if a.find("atom:name", ns) is not None
+    ]
+    categories = [
+        c.get("term", "") for c in entry.findall("atom:category", ns)
+    ]
+    published_el = entry.find("atom:published", ns)
+    published = published_el.text if published_el is not None and published_el.text else ""
+
+    return {
+        "arxiv_id": arxiv_id,
+        "title": title,
+        "abstract": abstract,
+        "authors": authors,
+        "categories": categories,
+        "published": published,
+    }
+```
+
+### 5.2 模块 3：GitHub 代码搜索 `repo_searcher.py`
+
+**做什么**：给定一个关键词列表 → 搜索 GitHub 返回相关仓库列表。
+
+**技术要点**：
+- GitHub Search API：`GET /search/repositories?q={query}&sort=stars&order=desc&per_page=5`
+- 搜索 query 构造：用关键词 + 限定条件（language:python、stars 门槛）
+- **搜索接口限速更严**：带 token 30 次/分钟，不带 token 10 次/分钟。你们两人各申请一个 token，在代码里轮换
+- 返回结果去重（同一个 repo 可能被不同关键词搜到多次）
+
+```python
+# repo_searcher.py
+import requests
+import os
+
+GITHUB_TOKENS = [
+    os.getenv("GITHUB_TOKEN_1", ""),
+    os.getenv("GITHUB_TOKEN_2", ""),
+]
+GITHUB_TOKENS = [t for t in GITHUB_TOKENS if t]  # 过滤空值
+_token_index = 0
+
+def _get_token():
+    """轮换使用两个 token，降低限速风险"""
+    global _token_index
+    if not GITHUB_TOKENS:
+        return ""
+    token = GITHUB_TOKENS[_token_index]
+    _token_index = (_token_index + 1) % len(GITHUB_TOKENS)
+    return token
+
+def _get_headers():
+    token = _get_token()
+    if token:
+        return {"Authorization": f"Bearer {token}", "Accept": "application/vnd.github.v3+json"}
+    return {"Accept": "application/vnd.github.v3+json"}
+
+def search_repos(keywords: list[str], max_per_keyword: int = 5, language: str = "python") -> list[dict]:
+    """用关键词列表搜索 GitHub 仓库
+    返回: 去重后的仓库列表，按 star 降序排列
+    """
+    seen = set()
+    results = []
+
+    for kw in keywords:
+        # 构造查询：关键词 + Python + 至少 5 个 star（过滤空壳仓库）
+        query = f"{kw} language:{language} stars:>=5"
+        url = "https://api.github.com/search/repositories"
+        params = {"q": query, "sort": "stars", "order": "desc", "per_page": max_per_keyword}
+
+        try:
+            resp = requests.get(url, headers=_get_headers(), params=params, timeout=15)
+            if resp.status_code == 403 and "rate limit" in resp.text.lower():
+                print(f"[警告] GitHub 搜索限速，跳过关键词: {kw}")
+                continue
+            resp.raise_for_status()
+            data = resp.json()
+        except Exception as e:
+            print(f"[警告] 搜索关键词 '{kw}' 失败: {e}")
+            continue
+
+        for item in data.get("items", []):
+            full_name = item["full_name"]
+            if full_name not in seen:
+                seen.add(full_name)
+                results.append({
+                    "full_name": full_name,
+                    "html_url": item["html_url"],
+                    "description": item.get("description", ""),
+                    "stars": item.get("stargazers_count", 0),
+                    "language": item.get("language", ""),
+                    "topics": item.get("topics", []),
+                    "updated_at": item.get("updated_at", ""),
+                    "match_keyword": kw,
+                })
+
+    # 按 star 降序
+    results.sort(key=lambda r: r["stars"], reverse=True)
+    return results
+```
+
+### 5.3 模块 5（的一部分）：仓库详情抓取 `repo_fetcher.py`
+
+**做什么**：给定一个 GitHub 仓库的 owner/repo → 抓 README、依赖文件、元信息。
+
+这与之前方案的内容一致，但需要注意：现在是**批量抓取**（一个论文对应 5 个候选仓库），需要处理部分仓库抓取失败的情况——不能因为一个仓库失败了就让整个流程崩溃。
+
+```python
+# repo_fetcher.py
+import os
+import base64
+import requests
+
+GITHUB_TOKENS = [
+    os.getenv("GITHUB_TOKEN_1", ""),
+    os.getenv("GITHUB_TOKEN_2", ""),
+]
+GITHUB_TOKENS = [t for t in GITHUB_TOKENS if t]
+_token_index = 0
+
+def _get_token():
+    global _token_index
+    if not GITHUB_TOKENS:
+        return ""
+    token = GITHUB_TOKENS[_token_index]
+    _token_index = (_token_index + 1) % len(GITHUB_TOKENS)
+    return token
+
+API_BASE = "https://api.github.com"
+
+DEPENDENCY_FILENAMES = [
+    "requirements.txt", "environment.yml", "environment.yaml",
+    "setup.py", "setup.cfg", "pyproject.toml",
+    "Pipfile", "Pipfile.lock", "Dockerfile", "Makefile", "CMakeLists.txt",
+]
+
+def _github_get(owner: str, repo: str, endpoint: str) -> dict | None:
+    """统一的 GitHub API GET 请求"""
+    headers = {"Accept": "application/vnd.github.v3+json"}
+    token = _get_token()
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+
+    url = f"{API_BASE}/repos/{owner}/{repo}/{endpoint}" if endpoint else f"{API_BASE}/repos/{owner}/{repo}"
+    resp = requests.get(url, headers=headers, timeout=15)
+    if resp.status_code == 404:
+        return None
+    if resp.status_code in (403, 429):
+        raise RuntimeError(f"GitHub API 限速或拒绝访问: {resp.status_code}")
+    resp.raise_for_status()
+    return resp.json()
+
+def fetch_readme(owner: str, repo: str) -> str | None:
+    """抓取 README 内容（已解码的纯文本）"""
+    data = _github_get(owner, repo, "readme")
+    if not data:
+        return None
+    content = data.get("content", "")
+    try:
+        return base64.b64decode(content).decode("utf-8", errors="replace")
+    except Exception:
+        return None
+
+def fetch_dependencies(owner: str, repo: str) -> dict[str, str]:
+    """抓取所有依赖文件，返回 {文件名: 内容}"""
+    result = {}
+    contents = _github_get(owner, repo, "contents") or []
+    for item in contents:
+        name = item.get("name", "")
+        if name in DEPENDENCY_FILENAMES:
+            file_data = _github_get(owner, repo, f"contents/{name}")
+            if file_data and file_data.get("content"):
+                try:
+                    decoded = base64.b64decode(file_data["content"]).decode("utf-8", errors="replace")
+                    result[name] = decoded
+                except Exception:
+                    pass
+    return result
+
+def fetch_issues(owner: str, repo: str, max_count: int = 30) -> list[dict]:
+    """抓取最近的 Issues（为 Week 2 预留接口，Week 1 可以不调用）"""
+    issues = []
+    page = 1
+    while len(issues) < max_count:
+        params = {"state": "all", "sort": "created", "direction": "desc",
+                  "per_page": min(30, max_count - len(issues)), "page": page}
+        resp = requests.get(
+            f"{API_BASE}/repos/{owner}/{repo}/issues",
+            headers=_get_headers(),
+            params=params,
+            timeout=15,
+        )
+        if resp.status_code != 200:
+            break
+        page_items = resp.json()
+        if not page_items:
+            break
+        for item in page_items:
+            if "pull_request" not in item:  # GitHub Issues API 会混入 PR，需要过滤
+                issues.append({
+                    "title": item.get("title", ""),
+                    "state": item.get("state", ""),
+                    "created_at": item.get("created_at", ""),
+                    "body": (item.get("body") or "")[:500],  # 截断，只要前 500 字符
+                    "comments": item.get("comments", 0),
+                })
+        page += 1
+    return issues
+
+def _get_headers():
+    token = _get_token()
+    headers = {"Accept": "application/vnd.github.v3+json"}
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    return headers
+```
+
+### 5.4 评测集建设
+
+**这是整个项目最重要的资产**。评测集分两部分：
+
+**Part A：代码发现评测集（10 篇论文）**
+
+每篇论文标注：已知的最佳开源实现（ground truth 仓库）。
+
+```json
+{
+  "paper_arxiv_id": "1706.03762",
+  "paper_title": "Attention Is All You Need",
+  "paper_keywords_human": ["transformer", "attention mechanism", "seq2seq", "neural machine translation"],
+  "known_implementations": [
+    {"full_name": "huggingface/transformers", "relevance": "official"},
+    {"full_name": "tensorflow/tensor2tensor", "relevance": "official"},
+    {"full_name": "jadore801120/attention-is-all-you-need-pytorch", "relevance": "community"}
+  ]
+}
+```
+
+**Part B：可复现性评测集（20 个仓库）**
+
+沿用路线大纲的方案：10 个正样本 + 10 个负样本。
+
+```json
+{
+  "repo_url": "https://github.com/xxx/yyy",
+  "ground_truth": "reproducible",
+  "evidence": ["证据1", "证据2"],
+  "rationale": "为什么这样标注"
+}
+```
+
+**Week 1 最低要求**：Part A 标完 3 篇论文（用于 demo），Part B 标完 6-8 个仓库。不需要在 demo 时展示评测集，但标注工作是整个项目的基准。
+
+---
+
+## 六、乙的任务（LLM + 集成层）
+
+乙负责 **所有与 LLM 交互** 的模块：关键词提取、可复现性评估、主流程编排、Gradio 界面。
+
+### 6.1 模块 2：研究方向解析 + 搜索词生成 `direction_analyzer.py`
+
+**做什么**：输入论文标题 + 摘要 → LLM 一次性完成三件事：(1) 识别该论文所属子领域，(2) 梳理该领域的主流方法族，(3) 生成针对每个方法族的 GitHub 搜索词。
+
+**为什么比单纯提取关键词更好**：
+- 研究者不只需要"一个官方实现"，他要知道这个方向有几条技术路线、每条路线有哪些代表实现
+- 比如输入 Transformer 论文，应该输出「vanilla Transformer / BERT 系 / GPT 系 / T5 系 / ViT 系」等方法族
+- 这直接对应研究者的实际需求——写论文跑对比实验时需要覆盖多个 baseline
+
+```python
+# direction_analyzer.py
+import json
+import re
+from openai import OpenAI
+
+client = OpenAI(
+    api_key="your-deepseek-api-key",
+    base_url="https://api.deepseek.com",
+)
+
+DIRECTION_SYSTEM_PROMPT = """你是一个 AI 研究领域的导航专家。你的任务是：给定一篇论文，帮助研究者快速了解该方向的前沿开源生态。
+
+## 你的分析框架
+
+请完成以下三个层次的分析：
+
+### 层次 1：子领域定位
+- 这篇论文属于 AI/ML 的哪个具体子领域？（如 "Transformer-based Neural Machine Translation" 而非笼统的 "Deep Learning"）
+- 该子领域在 2024-2025 年的主流趋势是什么？（1-2 句话）
+
+### 层次 2：方法族谱系
+- 该子领域目前有哪些主流方法族/变体？
+- 每个方法族的代表工作是什么？
+- 输出 3-6 个方法族，每个包含方法名 + 一句话说明
+
+### 层次 3：搜索策略
+- 为每个方法族生成 2-3 个 GitHub 搜索查询
+- 查询应使用英文，包含：方法名 + 关键词 + "implementation" 或 "pytorch" 或 "official"
+- 额外生成 2-3 个覆盖全领域的宽泛搜索
+
+## 输出格式（严格 JSON，不要任何额外文字）
+{
+  "subfield": "子领域名称（中英文均可）",
+  "subfield_trend": "该子领域当前主流趋势（1-2 句中文）",
+  "method_families": [
+    {
+      "family_name": "方法族名称",
+      "description": "一句话说明",
+      "representative_work": "代表论文或工作",
+      "search_queries": ["搜索词1", "搜索词2"]
+    }
+  ],
+  "broad_queries": ["全领域宽泛搜索词1", "全领域宽泛搜索词2"]
+}
+"""
+
+def analyze_direction(title: str, abstract: str) -> dict:
+    """从论文标题和摘要中解析研究方向并生成搜索策略"""
+    user_prompt = f"""## 论文标题
+{title}
+
+## 论文摘要
+{abstract[:2000]}
+
+请分析该论文的研究方向并生成搜索策略。"""
+
+    response = client.chat.completions.create(
+        model="deepseek-chat",
+        messages=[
+            {"role": "system", "content": DIRECTION_SYSTEM_PROMPT},
+            {"role": "user", "content": user_prompt},
+        ],
+        temperature=0.4,  # 稍高温度让方法族梳理更有创造力
+        max_tokens=1500,
+    )
+    raw = response.choices[0].message.content.strip()
+    return _parse_json(raw)
+
+def _parse_json(raw: str) -> dict:
+    """安全解析 JSON，容忍 LLM 的格式问题"""
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        pass
+    match = re.search(r'```(?:json)?\s*([\s\S]*?)```', raw)
+    if match:
+        try:
+            return json.loads(match.group(1).strip())
+        except json.JSONDecodeError:
+            pass
+    match = re.search(r'\{[\s\S]*\}', raw)
+    if match:
+        try:
+            return json.loads(match.group(0))
+        except json.JSONDecodeError:
+            pass
+    raise ValueError(f"方向解析 LLM 返回格式无法解析: {raw[:300]}")
+```
+
+### 6.2 模块 5：可复现性 + 对比实验适配度评估 `repo_evaluator.py`
+
+**做什么**：输入一个仓库的 README + 依赖文件 + 元信息 + 所属方法族 → LLM 输出六维度评分（可复现性 5 维 + 对比实验适配度 1 维）。
+
+**为什么新增「对比实验适配度」维度**：很多仓库能跑（可复现），但不适合直接拿来跑对比实验——比如它只实现了推理没有训练、数据集用的是私有数据、或者 benchmark 指标不是领域标准指标。研究者需要的是"能直接加入论文 experiment section 的代码"。
+
+```python
+# repo_evaluator.py
+import json
+import re
+from openai import OpenAI
+
+client = OpenAI(
+    api_key="your-deepseek-api-key",
+    base_url="https://api.deepseek.com",
+)
+
+EVAL_SYSTEM_PROMPT = """你是一个 AI 论文代码可复现性与对比实验适配度评估专家。
+
+你的任务是评估一个 GitHub 仓库在以下两个方面的表现：
+- **可复现性**：这个仓库的代码能否被他人成功跑通？
+- **对比实验适配度**：这个仓库适不适合直接拿来写论文做对比实验（baseline / comparison）？
+
+## 评估框架（六维度）
+
+### 可复现性（五维度，合计 0-80 分）
+
+1. **环境配置完整性（0-15 分）**
+   - 15 分：提供了完整的依赖文件（requirements.txt / environment.yml），版本号明确
+   - 8-14 分：有依赖文件但部分版本号缺失或模糊
+   - 0-7 分：没有依赖文件或严重不完整
+
+2. **文档质量（0-20 分）**
+   - 16-20 分：有清晰的安装步骤、训练/推理命令、数据集获取方式
+   - 8-15 分：有基本说明但关键步骤缺失
+   - 0-7 分：README 空洞，没有可执行的命令
+
+3. **代码可用性（0-20 分）**
+   - 16-20 分：有完整的训练/推理脚本、配置文件，入口清晰
+   - 8-15 分：有核心代码但缺少关键组件（如只有推理没有训练）
+   - 0-7 分：代码残缺
+
+4. **社区活跃度（0-10 分）**
+   - 8-10 分：Star > 500，最近半年有更新
+   - 4-7 分：有一定关注度但更新不频繁
+   - 0-3 分：长期不更新，Star < 10
+
+5. **依赖健康度（0-15 分）**
+   - 12-15 分：依赖全是主流活跃包，无已知兼容性问题
+   - 6-11 分：有少量过时依赖但可升级
+   - 0-5 分：依赖已停止维护（如 TF 1.x）或已知无法安装
+
+### 对比实验适配度（一维度，0-20 分）
+
+6. **对比实验适配度（0-20 分）**
+   - 16-20 分：提供标准 benchmark 评估脚本 + 预训练权重 + 公开数据集，可以直接跑出论文常用指标
+   - 10-15 分：有训练脚本和评估代码，但需要自己准备数据或微调配接
+   - 0-9 分：只有推理、使用私有数据集、没有标准化评估流程
+
+## 输出格式（严格 JSON，不要任何额外文字）
+{
+  "reproducibility_score": 整数（0-80，可复现性五项求和）,
+  "benchmark_fitness_score": 整数（0-20，对比实验适配度）,
+  "overall_score": 整数（0-100，六项总和）,
+  "verdict": "reproducible" | "partially" | "not_reproducible",
+  "env_score": 整数,
+  "doc_score": 整数,
+  "code_score": 整数,
+  "community_score": 整数,
+  "dep_score": 整数,
+  "benchmark_score": 整数,
+  "reasoning": "200字以内的中文分析，必须区分'能不能跑'和'适不适合跑对比实验'两个层面",
+  "risks": ["风险1", "风险2"],
+  "benchmark_readiness": "ready" | "partial" | "not_ready",
+  "suggested_use": "可以直接作为对比实验 baseline" | "需要少量修改后可用于对比实验" | "仅适合参考代码实现，不适合直接跑对比实验"
+}
+
+## 判定规则
+- overall_score >= 70 → verdict = "reproducible"
+- 40 <= overall_score < 70 → verdict = "partially"
+- overall_score < 40 → verdict = "not_reproducible"
+
+- benchmark_score >= 16 → benchmark_readiness = "ready"
+- 10 <= benchmark_score < 16 → benchmark_readiness = "partial"
+- benchmark_score < 10 → benchmark_readiness = "not_ready"
+"""
+
+def evaluate_repo(repo: dict, readme: str | None, dependencies: dict[str, str],
+                  method_family: str = "") -> dict:
+    """评估单个仓库的可复现性和对比实验适配度"""
+    readme_text = (readme or "README 未找到")[:2500]
+    deps_text = "\n\n".join(
+        f"### {fname}\n```\n{content[:1000]}\n```"
+        for fname, content in dependencies.items()
+    ) or "未找到依赖文件"
+
+    family_hint = f"\n该方法属于: {method_family}" if method_family else ""
+
+    user_prompt = f"""## 仓库信息
+- 名称: {repo.get('full_name', '')}
+- URL: {repo.get('html_url', '')}
+- Stars: {repo.get('stars', 0)}
+- 描述: {repo.get('description', '')}
+- 最后更新: {repo.get('updated_at', '')}
+- 语言: {repo.get('language', '')}{family_hint}
+
+## README
+{readme_text}
+
+## 依赖文件
+{deps_text}
+
+请评估该仓库的可复现性和对比实验适配度。"""
+
+    response = client.chat.completions.create(
+        model="deepseek-chat",
+        messages=[
+            {"role": "system", "content": EVAL_SYSTEM_PROMPT},
+            {"role": "user", "content": user_prompt},
+        ],
+        temperature=0.3,
+        max_tokens=1500,
+    )
+    raw = response.choices[0].message.content.strip()
+    return _parse_json(raw)
+
+def _parse_json(raw: str) -> dict:
+    """安全 JSON 解析"""
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        pass
+    match = re.search(r'```(?:json)?\s*([\s\S]*?)```', raw)
+    if match:
+        try:
+            return json.loads(match.group(1).strip())
+        except json.JSONDecodeError:
+            pass
+    match = re.search(r'\{[\s\S]*\}', raw)
+    if match:
+        try:
+            return json.loads(match.group(0))
+        except json.JSONDecodeError:
+            pass
+    raise ValueError(f"评估 LLM 返回格式无法解析: {raw[:300]}")
+```
+
+def evaluate_repo(repo: dict, readme: str | None, dependencies: dict[str, str]) -> dict:
+    """评估单个仓库的可复现性"""
+    readme_text = (readme or "README 未找到")[:2500]
+    deps_text = "\n\n".join(
+        f"### {fname}\n```\n{content[:1000]}\n```"
+        for fname, content in dependencies.items()
+    ) or "未找到依赖文件"
+
+    user_prompt = f"""## 仓库信息
+- 名称: {repo.get('full_name', '')}
+- URL: {repo.get('html_url', '')}
+- Stars: {repo.get('stars', 0)}
+- 描述: {repo.get('description', '')}
+- 最后更新: {repo.get('updated_at', '')}
+- 语言: {repo.get('language', '')}
+
+## README
+{readme_text}
+
+## 依赖文件
+{deps_text}
+
+请评估该仓库的可复现性。"""
+
+    response = client.chat.completions.create(
+        model="deepseek-chat",
+        messages=[
+            {"role": "system", "content": EVAL_SYSTEM_PROMPT},
+            {"role": "user", "content": user_prompt},
+        ],
+        temperature=0.3,
+        max_tokens=1200,
+    )
+    raw = response.choices[0].message.content.strip()
+    return _parse_json(raw)
+
+def _parse_json(raw: str) -> dict:
+    """安全 JSON 解析，同 direction_analyzer 中的实现"""
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        pass
+    match = re.search(r'```(?:json)?\s*([\s\S]*?)```', raw)
+    if match:
+        try:
+            return json.loads(match.group(1).strip())
+        except json.JSONDecodeError:
+            pass
+    match = re.search(r'\{[\s\S]*\}', raw)
+    if match:
+        try:
+            return json.loads(match.group(0))
+        except json.JSONDecodeError:
+            pass
+    raise ValueError(f"评估 LLM 返回格式无法解析: {raw[:300]}")
+```
+
+### 6.3 模块 6：主流程 `run.py`
+
+**这是整个项目的中央调度器**。按三层架构串联所有模块。
+
+```python
+# run.py
+import sys
+from paper_fetcher import fetch_paper_info
+from direction_analyzer import analyze_direction
+from repo_searcher import search_repos
+from repo_fetcher import fetch_readme, fetch_dependencies
+from repo_evaluator import evaluate_repo
+
+def run(arxiv_url: str, top_n: int = 5) -> dict:
+    """主入口：从论文到"研究方向全景 + 代码推荐"的完整链路
+
+    返回 dict:
+    - paper: 论文信息
+    - direction: 研究方向解析结果（子领域 + 方法族 + 搜索词）
+    - repos: 评估后的仓库列表（按 overall_score 降序）
+    """
+    # ===== 第一层：研究方向解析 =====
+    print(f"[1/5] 正在获取论文信息...")
+    paper = fetch_paper_info(arxiv_url)
+    print(f"  论文: {paper['title'][:80]}...")
+
+    print(f"[2/5] 正在解析研究方向...")
+    direction = analyze_direction(paper["title"], paper["abstract"])
+    print(f"  子领域: {direction.get('subfield', '未知')}")
+    print(f"  方法族: {len(direction.get('method_families', []))} 个")
+
+    # 汇总所有搜索词（方法族搜索 + 宽泛搜索）
+    all_queries = []
+    for mf in direction.get("method_families", []):
+        all_queries.extend(mf.get("search_queries", []))
+    all_queries.extend(direction.get("broad_queries", []))
+    print(f"  生成 {len(all_queries)} 个搜索查询")
+
+    # ===== 第二层：开源代码发现 =====
+    print(f"[3/5] 正在搜索 GitHub 仓库...")
+    candidates = search_repos(all_queries, max_per_keyword=5)
+    candidates = candidates[:top_n]
+    print(f"  去重后找到 {len(candidates)} 个候选仓库")
+
+    if not candidates:
+        return {
+            "paper": paper,
+            "direction": direction,
+            "repos": [],
+            "error": "未找到相关开源仓库",
+        }
+
+    # ===== 第三层：可复现性 + 对比实验适配度评估 =====
+    print(f"[4/5] 正在评估 {len(candidates)} 个候选仓库...")
+    evaluated = []
+    for i, repo in enumerate(candidates):
+        full_name = repo["full_name"]
+        owner, name = full_name.split("/", 1)
+        # 尝试将仓库匹配到对应的方法族（简单规则：描述中包含方法族名称）
+        matched_family = _match_family(repo, direction.get("method_families", []))
+        print(f"  ({i+1}/{len(candidates)}) 评估 {full_name} [{matched_family or '未归类'}]...")
+
+        try:
+            readme = fetch_readme(owner, name)
+            deps = fetch_dependencies(owner, name)
+            evaluation = evaluate_repo(repo, readme, deps, matched_family)
+        except Exception as e:
+            evaluation = {
+                "overall_score": 0,
+                "reproducibility_score": 0,
+                "benchmark_fitness_score": 0,
+                "verdict": "error",
+                "reasoning": f"评估失败: {str(e)[:100]}",
+                "env_score": 0, "doc_score": 0, "code_score": 0,
+                "community_score": 0, "dep_score": 0, "benchmark_score": 0,
+                "risks": [], "benchmark_readiness": "not_ready",
+                "suggested_use": "评估失败，请手动检查",
+            }
+
+        evaluated.append({
+            **repo,
+            "method_family": matched_family,
+            "evaluation": evaluation,
+        })
+
+    # 按综合评分降序
+    evaluated.sort(key=lambda r: r["evaluation"].get("overall_score", 0), reverse=True)
+
+    print(f"[5/5] 生成研报...")
+    return {
+        "paper": paper,
+        "direction": direction,
+        "repos": evaluated,
+    }
+
+def _match_family(repo: dict, families: list[dict]) -> str:
+    """简单的仓库→方法族匹配：基于描述和 topics"""
+    desc = (repo.get("description") or "").lower()
+    topics = " ".join(repo.get("topics", [])).lower()
+    text = desc + " " + topics
+
+    for mf in families:
+        family_name = mf.get("family_name", "").lower()
+        if family_name and family_name in text:
+            return mf["family_name"]
+    return ""
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("用法: python run.py <arxiv_url>")
+        print("示例: python run.py https://arxiv.org/abs/1706.03762")
+        sys.exit(1)
+
+    result = run(sys.argv[1])
+
+    if result.get("error"):
+        print(f"\n❌ {result['error']}")
+    else:
+        # 使用 app.py 中的 format_report 输出
+        from app import format_report
+        print(format_report(result))
+```
+
+### 6.4 Gradio 界面 `app.py`
+
+```python
+# app.py
+import gradio as gr
+from run import run
+
+def diagnose(arxiv_url: str) -> str:
+    """Gradio 回调：输入 arxiv URL → 输出研究方向全景研报"""
+    url = arxiv_url.strip()
+    if not url:
+        return "## 请输入 arxiv 论文链接"
+
+    try:
+        result = run(url)
+    except ValueError as e:
+        return f"## 输入格式错误\n\n{str(e)}"
+    except RuntimeError as e:
+        return f"## API 请求失败\n\n{str(e)}"
+    except Exception as e:
+        return f"## 运行出错\n\n```\n{str(e)}\n```"
+
+    if result.get("error"):
+        return f"## 未找到相关代码\n\n{result['error']}"
+
+    return format_report(result)
+
+def format_report(result: dict) -> str:
+    """将 run() 的结果格式化为"研究方向全景研报" Markdown"""
+    paper = result["paper"]
+    direction = result["direction"]
+    repos = result["repos"]
+
+    # ===== 研报头部 =====
+    md = f"""# ResearchRadar 研究方向全景研报
+
+---
+
+## 一、论文信息
+
+| 项目 | 内容 |
+|------|------|
+| **标题** | {paper['title']} |
+| **arXiv ID** | [{paper['arxiv_id']}](https://arxiv.org/abs/{paper['arxiv_id']}) |
+| **作者** | {', '.join(paper['authors'][:5])}{'...' if len(paper['authors']) > 5 else ''} |
+| **发表时间** | {paper.get('published', 'N/A')[:10]} |
+| **分类** | {', '.join(paper['categories']) if paper.get('categories') else 'N/A'} |
+
+---
+
+## 二、研究方向全景
+
+### 子领域定位
+**{direction.get('subfield', '未知')}**
+
+### 当前趋势
+{direction.get('subfield_trend', '暂无分析')}
+
+### 方法族谱系
+
+| # | 方法族 | 说明 | 代表工作 |
+|---|--------|------|----------|
+"""
+    for i, mf in enumerate(direction.get("method_families", [])):
+        md += f"| {i+1} | **{mf.get('family_name', '')}** | {mf.get('description', '')} | {mf.get('representative_work', '')} |\n"
+
+    md += """
+---
+
+## 三、开源实现评估排名
+
+"""
+    # ===== 仓库排名 =====
+    for i, repo in enumerate(repos):
+        ev = repo["evaluation"]
+        verdict_icon = {
+            "reproducible": "✅", "partially": "⚠️",
+            "not_reproducible": "❌", "error": "💥"
+        }.get(ev.get("verdict", ""), "❓")
+        readiness_icon = {
+            "ready": "🟢", "partial": "🟡", "not_ready": "🔴"
+        }.get(ev.get("benchmark_readiness", ""), "⚪")
+
+        family_tag = f" `[{repo.get('method_family', '未归类')}]`" if repo.get("method_family") else ""
+
+        md += f"""### {i+1}. [{repo['full_name']}]({repo['html_url']}){family_tag}
+
+{verdict_icon} 可复现性: **{ev.get('reproducibility_score', ev.get('overall_score', 'N/A'))}/80** | {readiness_icon} 对比实验适配度: **{ev.get('benchmark_fitness_score', ev.get('benchmark_score', 'N/A'))}/20** | 综合: **{ev.get('overall_score', 'N/A')}/100**
+
+| 维度 | 得分 | 满分 | 说明 |
+|------|:----:|:----:|------|
+| 环境配置 | {ev.get('env_score', 'N/A')} | 15 | 依赖文件完整度 |
+| 文档质量 | {ev.get('doc_score', 'N/A')} | 20 | 安装/训练/数据说明 |
+| 代码可用性 | {ev.get('code_score', 'N/A')} | 20 | 训练+推理脚本完整性 |
+| 社区活跃 | {ev.get('community_score', 'N/A')} | 10 | Star + 更新频率 |
+| 依赖健康 | {ev.get('dep_score', 'N/A')} | 15 | 依赖包可用性 |
+| **对比实验** | **{ev.get('benchmark_score', 'N/A')}** | **20** | **标准化评估 + 预训练权重** |
+
+⭐ Star: {repo.get('stars', 0)} | 匹配: `{repo.get('match_keyword', '')}`
+
+**分析**: {ev.get('reasoning', 'N/A')}
+
+**对比实验建议**: {ev.get('suggested_use', 'N/A')}
+
+"""
+        if ev.get("risks"):
+            md += "**风险点**: " + " | ".join(f"`{r}`" for r in ev["risks"]) + "\n"
+        md += "\n---\n\n"
+
+    # ===== 对比实验推荐总结 =====
+    ready_repos = [r for r in repos if r["evaluation"].get("benchmark_readiness") == "ready"]
+    partial_repos = [r for r in repos if r["evaluation"].get("benchmark_readiness") == "partial"]
+
+    md += """## 四、对比实验推荐总结
+
+"""
+    if ready_repos:
+        md += "### 🟢 可直接用于对比实验\n\n"
+        for r in ready_repos:
+            md += f"- **[{r['full_name']}]({r['html_url']})** — {r['evaluation'].get('suggested_use', '')}\n"
+        md += "\n"
+
+    if partial_repos:
+        md += "### 🟡 需要少量修改后可用\n\n"
+        for r in partial_repos:
+            md += f"- **[{r['full_name']}]({r['html_url']})** — {r['evaluation'].get('suggested_use', '')}\n"
+        md += "\n"
+
+    not_ready = [r for r in repos if r["evaluation"].get("benchmark_readiness") not in ("ready", "partial")]
+    if not_ready:
+        md += "### 🔴 仅适合参考代码实现\n\n"
+        for r in not_ready:
+            md += f"- **[{r['full_name']}]({r['html_url']})** — {r['evaluation'].get('suggested_use', r['evaluation'].get('reasoning', 'N/A')[:80])}...\n"
+        md += "\n"
+
+    md += """
+---
+
+> ResearchRadar · 研究方向全景 + 开源代码评估 + 对比实验推荐
+"""
+
+    return md
+
+DEMO_EXAMPLES = [
+    ["https://arxiv.org/abs/1706.03762"],  # Attention Is All You Need (Transformer)
+    ["https://arxiv.org/abs/2010.11929"],  # An Image is Worth 16x16 Words (ViT)
+    ["https://arxiv.org/abs/2006.11239"],  # Denoising Diffusion Probabilistic Models (DDPM)
+]
+
+demo = gr.Interface(
+    fn=diagnose,
+    inputs=gr.Textbox(
+        label="论文 arxiv 链接",
+        placeholder="https://arxiv.org/abs/1706.03762",
+        lines=1,
+    ),
+    outputs=gr.Markdown(label="研究方向全景研报"),
+    title="ResearchRadar — 研究方向全景 + 开源代码评估",
+    description="输入一篇 AI 论文的 arxiv 链接，AI 帮你摸清研究方向全景，找到最适配的开源实现，评估能否直接用于对比实验。",
+    examples=DEMO_EXAMPLES,
+    theme="soft",
+)
+
+if __name__ == "__main__":
+    demo.launch(server_name="0.0.0.0", share=False)
+```
+
+---
+
+## 七、数据流与控制流
+
+### 7.1 完整链路（三层架构）
+
+```
+用户输入 arxiv URL
+        │
+        ▼
+┌──────────────────────────────────────────┐
+│  paper_fetcher.fetch_paper_info()        │  ← arxiv API
+│  输出: {title, abstract, authors, ...}   │
+└──────────────┬───────────────────────────┘
+               │
+               ▼
+┌──────────────────────────────────────────┐
+│  direction_analyzer.analyze_direction()  │  ← DeepSeek API (1 次)
+│  输出: {subfield, method_families[],     │
+│         broad_queries[]}                 │
+│  ※ 同时完成子领域识别 + 方法族梳理 +     │
+│     搜索词生成                            │
+└──────────────┬───────────────────────────┘
+               │
+               ▼
+┌──────────────────────────────────────────┐
+│  repo_searcher.search_repos()            ��  ← GitHub Search API (N 次)
+│  输入: 所有方法族搜索词 + 宽泛搜索词      │
+│  输出: 去重排序后的候选仓库 top 5         │
+└──────────────┬───────────────────────────┘
+               │
+               ▼ (对每个候选仓库循环)
+┌──────────────────────────────────────────┐
+│  repo_fetcher.fetch_readme()             │  ← GitHub Content API
+│  repo_fetcher.fetch_dependencies()       │
+│  输出: {readme, dependencies}            │
+└──────────────┬───────────────────────────┘
+               │
+               ▼
+┌──────────────────────────────────────────┐
+│  repo_evaluator.evaluate_repo()          │  ← DeepSeek API (每个仓库 1 次)
+│  输出: 六维度评分（可复现性 5 维 +       │
+│        对比实验适配度 1 维）              │
+└──────────────┬───────────────────────────┘
+               │
+               ▼
+┌──────────────────────────────────────────┐
+│  按 overall_score 降序                    │
+│  format_report() → 研究方向全景研报       │
+│  包含：方向解读 + 方法族谱系 + 仓库排行   │
+│        + 对比实验推荐                     │
+└──────────────────────────────────────────┘
+```
+
+### 7.2 API 调用次数估算（单次运行）
+
+| 步骤 | API | 调用次数 |
+|------|-----|:--------:|
+| 论文信息 | arxiv API | 1 |
+| 研究方向解析 | DeepSeek | 1 |
+| GitHub 搜索 | GitHub Search | N（方法族×2 + 宽泛×2 ≈ 10 次） |
+| 仓库详情（×5） | GitHub Content | 5 |
+| 可复现性+适配度评估（×5） | DeepSeek | 5 |
+
+**单次运行总耗时估算**：约 25-45 秒（串行执行）。主要耗时在 GitHub 搜索（10 次 × 每次约 1-2 秒）和 5 个仓库的评估（5 次 LLM 调用 × 每次 3-5 秒）。
+
+---
+
+## 八、关键节点与里程碑
+
+| 周次 | 目标 | 甲（数据层） | 乙（LLM+集成层） | 交付物 |
+|:----:|------|-------------|-----------------|--------|
+| **Week 1** | 地基 + 三层 MVP | `paper_fetcher.py` + `repo_searcher.py` + `repo_fetcher.py` + 评测集 Part A 标 3 篇 + Part B 标 6 个 | `direction_analyzer.py` + `repo_evaluator.py` + `run.py` + `app.py` + 架构图 | `python run.py <arxiv_url>` 完整链路 + 研究方向全景研报 |
+| **Week 2** | 端到端链路 | Workflow 优化（LLM 判断依赖是否还能装）、加 Tavily 社区搜索、加 Issue 抓取 | Agent C 初版（水贴/真Bug 分类，不做回环）、完善方法族归类逻辑 | 完整链路 + 评测集基线准确率 |
+| **Week 3** | 准确率攻关 | 持续扩充评测集（论文→仓库 ground truth）、优化数据采集质量 | Prompt 调优、方法族识别准确率、六维权重用评测集反推 | 研究方向识别准确率 ≥ 80%、可复现性准确率 ≥ 75% |
+| **Week 4** | 回环 + 增强搜索 | Gradio 界面升级（方法族分块展示）、增加 PapersWithCode 数据源 | Agent C 回环机制、Agent D 边界分数再迭代 | 带回环版，准确率 ≥ 80% |
+| **Week 5** | UI 升级 + 结营准备 | 录制 demo 视频、整理汇报材料（准备 2 篇论文的完整全景研报对比） | 流式输出、按方法族分块展示 | 结营答辩材料 |
+| **Week 6** | 缓冲 | 查漏补缺、评测集新问题修复 | 同上 | 最终答辩 |
+
+---
+
+## 九、文件结构
+
+```
+ResearchRadar/
+├── paper_fetcher.py         # 甲：arxiv 论文信息抓取
+├── repo_searcher.py         # 甲：GitHub 代码搜索（多关键词去重）
+├── repo_fetcher.py          # 甲：仓库详情抓取（README + 依赖 + Issues）
+├── direction_analyzer.py    # 乙：LLM 研究方向解析 + 方法族梳理 + 搜索词生成
+├── repo_evaluator.py        # 乙：LLM 可复现性（5维）+ 对比实验适配度（1维）评估
+├── run.py                   # 乙：三层主流程调度
+├── app.py                   # 乙：Gradio 界面 + 研究方向全景研报格式化
+├── eval.py                  # 甲：评测脚本（方向识别准确率 + 可复现性准确率）
+├── test_set/
+│   ├── papers.json          # Part A：论文→研究方向 ground truth + 已知实现仓库
+│   └── repos.json           # Part B：仓库→可复现性 ground truth
+├── requirements.txt         # 项目依赖：requests, gradio, openai
+└── README.md
+```
+
+**`requirements.txt`**：
+```
+requests>=2.31
+gradio>=4.0
+openai>=1.0
+```
+
+---
+
+## 十、第一周五天时间线
+
+| 天 | 甲 | 乙 |
+|----|----|-----|
+| **周一** | 写 `paper_fetcher.py`，在 5 篇论文上测试 arxiv API。申请 GitHub Token | 写 `direction_analyzer.py` prompt，用 3-5 篇论文测试：子领域识别是否合理？方法族是否覆盖全？搜索词质量如何？ |
+| **周二** | 写 `repo_searcher.py` + `repo_fetcher.py`，联调搜索→抓取链路。两个 token 都配好轮换 | 写 `repo_evaluator.py` prompt，用 5 个已知仓库测试六维评分是否合理，特别注意"可复现"和"适配度"有没有区分开 |
+| **周三** | 准备 3 篇 demo 论文 + 标 Part A 评测集（方向 + 方法族 + 已知实现仓库），确保每篇搜到的仓库有代表性 | 写 `run.py` 完整三层链路 + `app.py` 全景研报格式化，下午与甲联调 |
+| **周四** | 标 Part B 评测集（6-8 个仓库），处理边界 case（论文搜不到、仓库没 README、方向识别错误） | debug 整条链路：时间消耗、JSON 解析失败、API 异常处理。准备 PPT 三层架构图 |
+| **周五上午** | 完整走一遍 demo 流程 + 准备讲稿（3 篇论文各讲什么故事：方向全景→代码发现→对比实验推荐） | 同上，联调 + 答辩预演 |
+| **周五下午** | **汇报** | **汇报** |
+
+---
+
+## 十一、你们需要决定的事情
+
+在开始写代码之前，下面几个问题需要甲和乙坐下来对清楚。不用一次回答完，可以边写边决定：
+
+1. **甲和乙各自申请 GitHub Token 了吗？** 搜索接口限速很严（30次/分钟），两个 token 轮换是最低配置。如果没有，周一第一件事就去 [github.com/settings/tokens](https://github.com/settings/tokens) 各申请一个 Fine-grained token（只勾选 public repo 读权限）。
+
+2. **DeepSeek API key 现在就能用吗？** 谁拿着 key？周一上午先用最简单的 `curl` 或 Python 脚本验证 key 有效。这件事阻塞所有 LLM 模块。
+
+3. **3 篇 demo 论文选什么？** 建议选一篇经典论文（如 Transformer、ResNet、DDPM，方法族丰富、开源实现多、演示效果好），再从你们各自方向各选一篇。关键是要确保每篇论文都能搜到 3+ 个仓库，否则 demo 时没东西展示。
+
+4. **方向解析（direction_analyzer）的评测标准怎么定？** 这是整个系统最"主观"的模块。子领域定位对不对？方法族全不全？搜索词好不好？你们需要定一个简单的判定规则，比如"子领域由人工确认正确"、"方法族至少覆盖 3 个该领域的公认主流方向"。
+
+5. **"对比实验适配度"的 ground truth 怎么标？** 这个比"可复现性"更难标注。可复现性可以试着装环境跑一下，适配度需要判断"这个仓库能直接跑出论文里的指标吗"。建议先用你们自己熟悉的仓库标 5 个，再扩展到 20 个。
+
+6. **论文太新搜不到代码怎么处理？** 新论文（如 2025 年的）往往没有开源实现，但这恰恰是工具的价值——提前告诉你"这个方向还没有成熟代码，你可能要从头实现"。演示时如果遇到这种情况，你应该怎么讲这个故事？
+
+---
+
+> **最后一句**：你们是研一小白，这完全不丢人。6 分钟演示，评委不会被花哨 UI 打动，但会被「清楚的逻辑 + 真实的数据 + 诚实的局限」说服。别伪装，别造假。你们的价值是"帮研究者节省从论文到跑通对比实验的时间"，这个价值一句话就能讲清楚。

ResearchRadar_乙_任务书.md

@@ -0,0 +1,1575 @@
+# ResearchRadar 乙（决策+集成层）任务书
+
+> 角色：乙 — LLM 决策模块 + 主流程调度 + Gradio 界面
+> 目标：第一周结束前，`python run.py <arxiv_url>` 能跑通完整三层链路，输出研究方向全景研报
+> 前置条件：DeepSeek API key 已验证可用
+
+---
+
+## 〇、先理解你要搭建的是什么——Agent 与 Workflow 的本质
+
+> 你是小白，这不丢人。很多写了好几年代码的人也没搞懂 Agent 到底是什么。这一节可能是整个任务书最重要的部分。
+
+### 0.1 Agent 是什么（用你能听懂的话）
+
+**Agent = 一个有判断能力的函数**。跟普通函数的唯一区别是：它不靠写死的规则做判断，而是把信息丢给 LLM，让 LLM 来"帮你看一眼然后做决定"。
+
+用你熟悉的场景举例：
+
+- **不需要 Agent 的事**：你去 GitHub 看一个仓库有多少 star。这就是用眼睛看，不需要动脑子。写成代码就是 `requests.get(url) → resp.json()["stargazers_count"]`。这是 **Workflow**。
+
+- **需要 Agent 的事**：给你 100 条 GitHub Issue，让你判断哪些是真 bug 哪些是"大佬求代码"的水贴。这需要理解 Issue 的内容，需要动脑子。但 100 条你人工看不过来，所以写一个函数，把 Issue 文本丢给 DeepSeek，让它帮你分类。这就是 **Agent**。
+
+**Agent 的本质就是一个 Python 函数，函数体里有这一行**：
+
+```python
+response = client.chat.completions.create(
+    model="deepseek-chat",
+    messages=[{"role": "system", "content": "你是XX专家..."},
+              {"role": "user", "content": "帮我判断..."}],
+)
+# LLM 返回的判断结果就是 Agent 的"决策"
+return response.choices[0].message.content
+```
+
+**不需要 LangChain，不需要 LangGraph，不需要任何框架。** 你们路线大纲里说的"4 个函数 + 一个 dict + if/else，300 行能搞定"就是这个意思。
+
+### 0.2 Workflow 是什么
+
+**Workflow = 一条写死的流水线**。每一步做什么是确定的，不需要 LLM 来做选择。
+
+```python
+# 这就是一个 Workflow：3 步，每一步做什么是写死的
+def workflow_example(url):
+    data = requests.get(url).json()        # 步骤 1：抓数据
+    cleaned = clean_data(data)             # 步骤 2：清洗
+    return cleaned                         # 步骤 3：返回
+```
+
+Workflow 里没有 `if LLM说A就走B` 这种逻辑。路径是确定的。
+
+### 0.3 你的项目里：哪个是 Agent，哪个是 Workflow
+
+整个 ResearchRadar 系统可以按这个标准重新标注：
+
+```
+用户输入 arxiv URL
+        │
+        ▼
+┌────────────────────────────────────────────┐
+│  paper_fetcher.fetch_paper_info()          │  ← WORKFLOW（甲）
+│  做的事情：调 arxiv API，解析 XML，返回 dict │
+│  不需要 LLM，路径写死                        │
+└──────────────┬─────────────────────────────┘
+               │
+               ▼
+┌────────────────────────────────────────────┐
+│  direction_analyzer.analyze_direction()    │  ← AGENT（乙 ★ 你负责）
+│  做的事情：LLM 理解论文 → 判断子领域 →      │
+│           梳理方法族 → 生成搜索词             │
+│  需要 LLM：是的，LLM 在做"判断"              │
+└──────────────┬─────────────────────────────┘
+               │
+               ▼
+┌────────────────────────────────────────────┐
+│  repo_searcher.search_repos()              │  ← WORKFLOW（甲）
+│  做的事情：用搜索词调 GitHub API，           │
+│           去重，按 star 排序                 │
+│  不需要 LLM，就是循环调 API                   │
+└──────────────┬─────────────────────────────┘
+               │
+               ▼
+┌────────────────────────────────────────────┐
+│  repo_fetcher.fetch_readme()               │  ← WORKFLOW（甲）
+│  repo_fetcher.fetch_dependencies()         │
+│  做的事情：调 GitHub API，base64 解码，      │
+│           返回文件内容                       │
+│  不需要 LLM                                 │
+└──────────────┬─────────────────────────────┘
+               │
+               ▼
+┌────────────────────────────────────────────┐
+│  repo_evaluator.evaluate_repo()            │  ← AGENT（乙 ★ 你负责）
+│  做的事情：LLM 阅读 README + 依赖文件 →     │
+│           判断可复现性 + 对比实验适配度       │
+│  需要 LLM：是的，LLM 在做"评分判断"          │
+└──────────────┬─────────────────────────────┘
+               │
+               ▼
+          Markdown 研报
+```
+
+**一句话总结**：整个系统 = 甲的 3 个 Workflow + 你的 2 个 Agent + 1 个调度器（run.py）把它们串起来。
+
+### 0.4 Agent 和 Workflow 的搭建思路对比
+
+| | Workflow（甲负责） | Agent（你负责） |
+|------|------|------|
+| **核心工作** | 搞清楚 API 怎么调、返回什么格式、怎么解析 | 设计一段文字（prompt），告诉 LLM 它是什么角色、要判断什么、输出什么格式 |
+| **难度在哪** | 各种异常处理（API 挂了、限速了、数据格式变了） | LLM 返回的 JSON 格式不对、评分不符合常识、不同论文的输出质量不稳定 |
+| **调试方式** | `print()` 看 API 返回了什么 | 手工换 3-5 篇论文/仓库测试，看 LLM 的判断是否合理 |
+| **你需要的技能** | 会用 `requests` 库、会看 API 文档 | 会写清晰的 prompt、会处理 LLM 输出格式 |
+
+### 0.5 你的 4 个文件各自是什么
+
+| 你的文件 | 类型 | 简短说明 |
+|----------|------|----------|
+| `direction_analyzer.py` | **Agent** | 里面只有一个核心函数 `analyze_direction()`，它调 LLM 做方向判断 |
+| `repo_evaluator.py` | **Agent** | 里面只有一个核心函数 `evaluate_repo()`，它调 LLM 做评分判断 |
+| `run.py` | **调度器** | 既不是 Agent 也不是 Workflow，是一段"胶水代码"，按顺序调用 Workflow 和 Agent，把数据在它们之间传递 |
+| `app.py` | **界面** | 包装一个 Gradio 壳，让用户能输入 URL 看到研报 |
+
+### 0.6 你和甲的接口约定
+
+甲负责搭 Workflow 给你提供数据，你负责搭 Agent 做判断。你只需要知道甲的函数签名：
+
+| 甲的文件 | 你调用的函数 | 输入 | 输出 |
+|----------|-------------|------|------|
+| `paper_fetcher.py` | `fetch_paper_info(url)` | arxiv URL 字符串 | `{"arxiv_id", "title", "abstract", "authors", "categories", "published"}` |
+| `repo_searcher.py` | `search_repos(keywords, max_per_keyword=5)` | 关键词字符串列表 | `[{"full_name", "html_url", "description", "stars", "topics", ...}, ...]` |
+| `repo_fetcher.py` | `fetch_readme(owner, repo)` | owner 字符串, repo 字符串 | README 文本 或 None |
+| `repo_fetcher.py` | `fetch_dependencies(owner, repo)` | owner 字符串, repo 字符串 | `{"requirements.txt": "...", "environment.yml": "...", ...}` |
+
+**你要向甲确认的**：以上 4 个函数名和参数名不要改，否则 `run.py` 调不通。
+
+### 0.7 工业缺陷异常检测领域适配
+
+你们暂定的领域是**工业缺陷异常检测**（Industrial Defect Anomaly Detection）。这个领域很适合 ResearchRadar，因为：
+
+- 有明确的方法族谱系：基于重构的（AutoEncoder/VAE）、基于嵌入的（PaDiM/PatchCore）、基于师生网络的（STFPM/EfficientAD）、基于合成缺陷的（DRAEM/Defect-GAN）
+- 有公认的数据集：MVTec AD、BTAD、KSDD2
+- 有高质量开源项目：OpenVINO anomalib、PaDiM、PatchCore、EfficientAD
+- 是 CV 领域的活跃子方向，GitHub 上能找到足够多的候选仓库
+
+以下是你调试 prompt 时建议用的测试论文（选这个领域的经典论文）：
+
+| 论文 | arxiv ID | 为什么适合测试 |
+|------|----------|---------------|
+| PaDiM (2021) | `2011.08785` | 嵌入方法族代表，GitHub 实现多 |
+| PatchCore (2022) | `2106.08265` | 嵌入方法族，有 anomalib 官方实现 |
+| EfficientAD (2023) | `2303.14535` | 师生网络，较新，实现相对少（测试"搜不到代码"的情况） |
+| DRAEM (2021) | `2108.07610` | 合成缺陷方法，有官方代码 |
+| DeepSVDD (2018) | 非 arxiv，ICML 2018 | 经典单类分类方法，多个社区实现 |
+
+---
+
+## 一、Agent 1：`direction_analyzer.py` — 研究方向解析
+
+> **类型：Agent** | 这是你负责的第一个 Agent
+> **核心判断**：给定论文标题+摘要，LLM 判断它属于什么子领域、该领域有哪些方法族、应该用什么搜索词
+
+### 1.1 这个 Agent 要解决什么问题
+
+以往的方案是"从论文标题+摘要提取关键词搜 GitHub"。但这不够——研究者需要的不是一堆关键词，而是**对该研究方向的系统理解**。
+
+比如输入一篇工业缺陷检测的论文（如 PaDiM），这个 Agent 应该输出：
+- 子领域：Unsupervised Industrial Defect Detection / Anomaly Detection
+- 方法族：基于嵌入的（PaDiM/PatchCore）、基于重构的（AutoEncoder/VAE）、基于师生网络的（STFPM/EfficientAD）、基于合成缺陷的（DRAEM）
+- 搜索词：每个方���族的 GitHub 搜索词
+
+**这整个判断过程就是 Agent 的"决策"**——它不是从数据库查出来的，是 LLM 根据论文内容理解后做出的判断。
+
+### 1.2 这个 Agent 的搭建思路
+
+```
+步骤 1：写 System Prompt（告诉 LLM 它是什么角色、要输出什么）
+步骤 2：写 User Prompt 模板（把论文标题和摘要填入模板）
+步骤 3：调 OpenAI SDK 发送给 DeepSeek
+步骤 4：解析 LLM 返回的 JSON
+步骤 5：用 3-5 篇论文测试，看 LLM 的方向判断是否合理
+```
+
+**搭建的关键不在于代码（代码不到 50 行），在于 Prompt 写得好不好。** Prompt 决定了 Agent 的判断质量。
+
+### 1.3 完整代码
+
+```python
+# direction_analyzer.py
+# ============================================================
+# 类型：AGENT（乙负责）
+# 功能：LLM 解析研究方向 → 子领域 + 方法族谱系 + GitHub 搜索词
+# ============================================================
+import json
+import re
+from openai import OpenAI
+
+# 配置
+DEEPSEEK_API_KEY = "sk-a115c4388d444cf688d323855edb36da"
+DEEPSEEK_BASE_URL = "https://api.deepseek.com"
+MODEL = "deepseek-chat"
+
+client = OpenAI(api_key=DEEPSEEK_API_KEY, base_url=DEEPSEEK_BASE_URL)
+
+# ============================================================
+# System Prompt —— 这是整个模块的灵魂，调优主要调这里
+# ============================================================
+DIRECTION_SYSTEM_PROMPT = """你是一个 AI 研究领域的导航专家。你的任务是：给定一篇论文的标题和摘要，帮助研究者快速了解该方向的前沿开源生态。
+
+## 你的分析框架
+
+### 层次 1：子领域定位
+- 这篇论文属于 AI/ML/CV/NLP 的哪个具体子领域？
+- 不要给出笼统的答案（如 "Deep Learning"），要给出具体子领域（如 "Transformer-based Neural Machine Translation"）
+- 说明该子领域在 2024-2025 年的主流趋势（1-2 句话，中文）
+
+### 层次 2：方法族谱系
+- 该子领域目前有哪些主流方法族/变体/技术路线？
+- 每个方法族的代表工作是什么（论文或知名项目名）？
+- 输出 3-6 个方法族，不要太多（太多搜索会慢），也不要太少（太少覆盖面不够）
+- 每个方法族一句话说明其核心特点
+
+### 层次 3：搜索策略
+- 为每个方法族生成 2-3 个 GitHub 搜索查询
+- 搜索查询使用英文，格式：方法名 + 技术关键词 + 搜索限定词
+- 搜索限定词使用：implementation, pytorch, official, tensorflow, code
+- 额外生成 3 个覆盖全领域的宽泛搜索
+- 宽泛搜索不限定具体方法名，用子领域名+限定词
+
+## 搜索查询质量要求
+- 好的查询示例："vision transformer implementation pytorch"
+- 好的查询示例："denoising diffusion probabilistic model official code"
+- 坏的查询示例："transformer"（太宽泛）
+- 坏的查询示例："a novel approach for image classification using deep learning"（太多废话）
+
+## 输出格式（严格 JSON，不要任何额外文字，不要 markdown 代码块标记）
+{
+  "subfield": "具体子领域名称",
+  "subfield_trend": "该子领域 2024-2025 的主流趋势（1-2 句中文）",
+  "method_families": [
+    {
+      "family_name": "方法族简称",
+      "description": "一句话核心特点",
+      "representative_work": "代表论文或知名项目",
+      "search_queries": ["搜索词1", "搜索词2", "搜索词3"]
+    }
+  ],
+  "broad_queries": ["宽泛搜索1", "宽泛搜索2", "宽泛搜索3"]
+}
+"""
+
+def analyze_direction(title: str, abstract: str) -> dict:
+    """从论文标题和摘要中解析研究方向并生成搜索策略。
+
+    Args:
+        title: 论文标题
+        abstract: 论文摘要（会自动截断到 2500 字符）
+
+    Returns:
+        dict: 包含 subfield, subfield_trend, method_families, broad_queries
+    """
+    # 截断摘要，防止超出 token 限制
+    abstract_truncated = abstract[:2500] if abstract else "（摘要不可用）"
+    title_clean = title.strip() if title else "（标题不可用）"
+
+    user_prompt = f"""## 论文标题
+{title_clean}
+
+## 论文摘要
+{abstract_truncated}
+
+请分析该论文的研究方向并生成搜索策略。"""
+
+    response = client.chat.completions.create(
+        model=MODEL,
+        messages=[
+            {"role": "system", "content": DIRECTION_SYSTEM_PROMPT},
+            {"role": "user", "content": user_prompt},
+        ],
+        temperature=0.4,  # 0.4 给方法族梳理保留一些多样性
+        max_tokens=2000,
+        # 如果 DeepSeek 支持 response_format，取消下面这行的注释可以提升 JSON 遵守率
+        # response_format={"type": "json_object"},
+    )
+    raw = response.choices[0].message.content.strip()
+    return _parse_json_safe(raw)
+
+
+def _parse_json_safe(raw: str) -> dict:
+    """安全解析 LLM 返回的 JSON，处理各种常见的格式问题。
+
+    LLM 可能返回：
+    1. 纯 JSON：{"subfield": "..."}
+    2. markdown 包���：```json\n{...}\n```
+    3. 带前缀文字：这是分析结果：\n{...}
+    4. 格式错误：缺少引号、尾部逗号等
+    """
+    # 策略 1：直接解析
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        pass
+
+    # 策略 2：提取 markdown 代码块
+    match = re.search(r'```(?:json)?\s*([\s\S]*?)```', raw)
+    if match:
+        try:
+            return json.loads(match.group(1).strip())
+        except json.JSONDecodeError:
+            pass
+
+    # 策略 3：提取第一个 { ... } 对象（贪婪匹配最外层）
+    match = re.search(r'\{[\s\S]*\}', raw)
+    if match:
+        try:
+            return json.loads(match.group(0))
+        except json.JSONDecodeError:
+            pass
+
+    # 策略 4：全部失败，抛出异常（带上原始内容方便调试）
+    raise ValueError(
+        f"direction_analyzer: 无法解析 LLM 返回的 JSON。\n"
+        f"原始返回（前 500 字符）:\n{raw[:500]}"
+    )
+
+
+# ============================================================
+# 自测代码 —— 写完后运行 python direction_analyzer.py 验证
+# ============================================================
+if __name__ == "__main__":
+    # 测试用例 1：Transformer（经典论文，方法族丰富）
+    print("=" * 60)
+    print("测试 1：Transformer 论文")
+    print("=" * 60)
+    result = analyze_direction(
+        "Attention Is All You Need",
+        "The dominant sequence transduction models are based on complex recurrent "
+        "or convolutional neural networks... We propose a new simple network "
+        "architecture, the Transformer, based solely on attention mechanisms."
+    )
+    print(f"子领域: {result.get('subfield')}")
+    print(f"方法族: {[mf.get('family_name') for mf in result.get('method_families', [])]}")
+    print(f"总搜索词数: {sum(len(mf.get('search_queries', [])) for mf in result.get('method_families', [])) + len(result.get('broad_queries', []))}")
+
+    print()
+
+    # 测试用例 2：PaDiM（工业缺陷检测，你的领域）
+    print("=" * 60)
+    print("测试 2：PaDiM 论文（工业缺陷检测）")
+    print("=" * 60)
+    result = analyze_direction(
+        "PaDiM: a Patch Distribution Modeling Framework for Anomaly Detection and Localization",
+        "We present a new framework for anomaly detection and localization based on "
+        "patch distribution modeling. PaDiM uses pretrained convolutional neural networks "
+        "to extract patch features and models their distribution using multivariate "
+        "Gaussian distributions. It achieves state-of-the-art results on MVTec AD and "
+        "STC datasets for industrial defect detection."
+    )
+    print(f"子领域: {result.get('subfield')}")
+    print(f"趋势: {result.get('subfield_trend')}")
+    print(f"方法族数量: {len(result.get('method_families', []))}")
+    for mf in result.get("method_families", []):
+        print(f"  - {mf.get('family_name')}: {mf.get('description')[:60]}...")
+    print(f"宽泛搜索词: {result.get('broad_queries', [])}")
+
+    print()
+
+    # 测试用例 3：EfficientAD（较新论文，搜不到代码的测试）
+    print("=" * 60)
+    print("测试 3：EfficientAD 论文（2023，较新）")
+    print("=" * 60)
+    result = analyze_direction(
+        "EfficientAD: Accurate Visual Anomaly Detection at Millisecond-Level Latencies",
+        "We propose EfficientAD, a lightweight anomaly detection method that achieves "
+        "millisecond-level latency. It uses a teacher-student architecture with a simple "
+        "student network that learns to mimic the teacher's features on normal images only."
+    )
+    print(f"子领域: {result.get('subfield')}")
+    print(f"方法族: {[mf.get('family_name') for mf in result.get('method_families', [])]}")
+```
+
+### 1.3 调试指南
+
+**问题 1：LLM 返回的不是 JSON**
+- 症状：`ValueError: direction_analyzer: 无法解析 LLM 返回的 JSON`
+- 排查：打印 `raw[:500]` 看看 LLM 到底回了什么
+- 修复：如果 LLM 频繁返回非 JSON，在 system prompt 第一句加 `你必须只返回一个 JSON 对象，不要有任何解释文字。`
+- 备选：如果 DeepSeek 支持 `response_format={"type": "json_object"}` 就开启（见代码中的注释行）
+
+**问题 2：方法族太少（比如只有 2 个）**
+- 症状：搜索覆盖面不够，找不到足够的仓库
+- 修复：在 system prompt 里把"输出 3-6 个方法族"改成"必须输出至少 4 个方法族"
+
+**问题 3：搜索词质量差（搜不到仓库）**
+- 症状：生成的搜索词在 GitHub 上返回空结果或无关结果
+- 测试方法：复制生成的搜索词，手动在 GitHub 搜索框里搜，看结果质量
+- 修复：在 system prompt 的搜索示例部分增加更多好/坏例子
+
+**问题 4：方法族名称太学术化，GitHub 搜不到**
+- 症状：方法族叫 "Gated Linear Unit Enhanced Multi-Head Self-Attention"，GitHub 没结果
+- 修复：在 prompt 里要求搜索词使用常用��简称而非论文全名
+
+---
+
+## 二、Agent 2：`repo_evaluator.py` — 可复现性 + 适配度评估
+
+> **类型：Agent** | 这是你负责的第二个 Agent
+> **核心判断**：给定一个仓库的 README + 依赖文件，LLM 判断它能不能跑、适不适合拿来做对比实验
+
+### 2.1 这个 Agent 要解决什么问题
+
+当你通过 Agent 1（方向解析）和甲的两个 Workflow（搜索+抓取）拿到了 5 个候选仓库后，需要判断两个层面：
+1. **能不能跑？**（可复现性 5 维度，80 分）—— 这是"技术可行性"
+2. **适不适合直接拿来做对比实验？**（适配度 1 维度，20 分）—— 这是"论文实用性"
+
+两个层面必须分开打分。比如 anomalib（OpenVINO 的异常检测库）：
+- 可复现性评分高（README 完善、有 requirements.txt、pip install 即用）
+- 适配度评分高（有标准 benchmark 脚本、支持 MVTec AD 数据集、有预训练权重）
+
+而一个"只有推理脚本的个人项目"：
+- 可复现性可能还行（能跑通 demo）
+- 适配度一定低（没有训练脚本和标准化评估，不能用于跑对比实验）
+
+### 2.2 这个 Agent 的搭建思路
+
+```
+步骤 1：写 System Prompt，定义六维度评分框架 + 每个维度的分数锚点
+步骤 2：写 User Prompt 模板（填入 README + 依赖文件 + 仓库元信息）
+步骤 3：调 OpenAI SDK 发送给 DeepSeek
+步骤 4：解析 LLM 返回的 JSON
+步骤 5：用 5 个你自己熟悉的仓库测试（2 好 + 2 差 + 1 中），对比 LLM 评分 vs 你的人工评分
+```
+
+**这个 Agent 最难的部分**：让 LLM 区分"能跑"和"适合跑对比实验"。很多初学者会把这两个概念混淆。如果你的 prompt 没写清楚，LLM 也会混淆。调试时重点检查：README 好但只有推理的仓库，适配度是否真的低于 10 分。
+
+### 2.3 完整代码
+
+```python
+# repo_evaluator.py
+# ============================================================
+# 类型：AGENT（乙负责）
+# 功能：LLM 六维度评分（可复现性 5 维 + 对比实验适配度 1 维）
+# ============================================================
+import json
+import re
+from openai import OpenAI
+
+DEEPSEEK_API_KEY = "sk-a115c4388d444cf688d323855edb36da"
+DEEPSEEK_BASE_URL = "https://api.deepseek.com"
+MODEL = "deepseek-chat"
+
+client = OpenAI(api_key=DEEPSEEK_API_KEY, base_url=DEEPSEEK_BASE_URL)
+
+# ============================================================
+# System Prompt
+# ============================================================
+EVAL_SYSTEM_PROMPT = """你是一个 AI 论文代码评估专家。你需要同时评估一个 GitHub 仓库的两个方面：
+- **可复现性**：这个仓库的代码能不能被他人成功跑通？
+- **对比实验适配度**：这个仓库适不适合直接拿来写论文做对比实验（baseline / comparison）？
+
+## 评估框架（六维度，总分 100）
+
+### 可复现性（五维度，合计 80 分）
+
+1. **环境配置完整性（0-15 分）**
+   - 15 分：提供了 requirements.txt / environment.yml，所有依赖版本号明确
+   - 8-14 分：有依赖文件但部分版本号使用范围（>=, ~=）或缺失
+   - 0-7 分：没有依赖文件或严重不完整
+
+2. **文档质量（0-20 分）**
+   - 16-20 分：有清晰的安装步骤、训练命令、推理命令、数据集获取方式
+   - 8-15 分：有基本说明但关键步骤缺失（如没说数据集在哪下载）
+   - 0-7 分：README 只有项目简介，没有可执行命令
+
+3. **代码可用性（0-20 分）**
+   - 16-20 分：训练脚本 + 推理脚本 + 配置文件 + 模型定义入口完整
+   - 8-15 分：有核心代码但缺少关键组件（如只有推理没有训练）
+   - 0-7 分：代码残缺，只有骨架或 shell 脚本
+
+4. **社区活跃度（0-10 分）**
+   - 8-10 分：Star > 500，最近半年有 commit，Issue 有人回复
+   - 4-7 分：有一定关注度但更新不频繁
+   - 0-3 分：长期不更新，Star < 10
+
+5. **依赖健康度（0-15 分）**
+   - 12-15 分：依赖全是主流活跃包，版本相互兼容
+   - 6-11 分：有少量过时依赖但不影响安装
+   - 0-5 分：依赖涉及已停止维护的包（如 TensorFlow 1.x、Python 2），已知无法在现代环境安装
+
+### 对比实验适配度（一维度，20 分）
+
+6. **对比实验适配度（0-20 分）**
+   - 16-20 分：提供标准 benchmark 评估脚本 + 预训练权重下载 + 公开数据集支持，可直接跑出论文常用指标，可以无缝插入论文的 Experiment section
+   - 10-15 分：有训练脚本和评估代码，但需要自己准备数据或适配数据集格式
+   - 0-9 分：只有推理 demo、使用私有数据集、没有标准化评估流程、或没有预训练权重
+
+## 输出格式（严格 JSON）
+{
+  "reproducibility_score": 80,
+  "benchmark_fitness_score": 20,
+  "overall_score": 100,
+  "verdict": "reproducible",
+  "env_score": 15,
+  "doc_score": 20,
+  "code_score": 20,
+  "community_score": 10,
+  "dep_score": 15,
+  "benchmark_score": 20,
+  "reasoning": "200字以内的中文分析，必须区分'能不能跑'和'适不适合跑对比实验'两个层面",
+  "risks": ["风险1", "风险2"],
+  "benchmark_readiness": "ready",
+  "suggested_use": "可以直接作为对比实验 baseline"
+}
+
+## 判定规则
+- overall_score >= 70 → verdict = "reproducible"
+- 40 <= overall_score < 70 → verdict = "partially"
+- overall_score < 40 → verdict = "not_reproducible"
+
+- benchmark_score >= 16 → benchmark_readiness = "ready"
+- 10 <= benchmark_score < 16 → benchmark_readiness = "partial"
+- benchmark_score < 10 → benchmark_readiness = "not_ready"
+
+## bench_readiness 与 suggested_use 的对应关系
+- "ready" → "可以直接作为对比实验 baseline"
+- "partial" → "需要少量修改后可用于对比实验"
+- "not_ready" → "仅适合参考代码实现，不适合直接跑对比实验"
+"""
+
+
+def evaluate_repo(
+    repo: dict,
+    readme: str | None,
+    dependencies: dict[str, str],
+    method_family: str = "",
+) -> dict:
+    """评估单个仓库的可复现性和对比实验适配度。
+
+    Args:
+        repo: 仓库元信息 dict（来自 repo_searcher），包含 full_name, html_url, stars 等
+        readme: README 文件全文（或 None）
+        dependencies: {文件名: 文件内容} 的 dict
+        method_family: 该仓库所属的方法族名称（空字符串表示未归类）
+
+    Returns:
+        dict: 六维度评分结果
+    """
+    # 构造 README 输入
+    readme_text = (readme or "README 未找到")[:2500]
+
+    # 构造依赖文件输入
+    if dependencies:
+        deps_parts = []
+        for fname, content in dependencies.items():
+            truncated = content[:1000] if content else "(空文件)"
+            deps_parts.append(f"### {fname}\n```\n{truncated}\n```")
+        deps_text = "\n\n".join(deps_parts)
+    else:
+        deps_text = "未找到任何依赖文件（requirements.txt / environment.yml 等）"
+
+    # 方法族提示
+    family_hint = f"\n- 方法族: {method_family}" if method_family else ""
+
+    user_prompt = f"""## 仓库基本信息
+- 名称: {repo.get('full_name', '未知')}
+- URL: {repo.get('html_url', '')}
+- Stars: {repo.get('stars', 0)}
+- 描述: {repo.get('description', '无描述')}
+- 最后更新: {repo.get('updated_at', '未知')}
+- 主要语言: {repo.get('language', '未知')}{family_hint}
+
+## README 内容
+{readme_text}
+
+## 依赖文件
+{deps_text}
+
+请评估该仓库的可复现性和对比实验适配度。"""
+
+    response = client.chat.completions.create(
+        model=MODEL,
+        messages=[
+            {"role": "system", "content": EVAL_SYSTEM_PROMPT},
+            {"role": "user", "content": user_prompt},
+        ],
+        temperature=0.3,  # 评估任务用低温度
+        max_tokens=2000,
+    )
+    raw = response.choices[0].message.content.strip()
+    return _parse_json_safe(raw)
+
+
+def _parse_json_safe(raw: str) -> dict:
+    """安全 JSON 解析，多种策略容错"""
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        pass
+
+    match = re.search(r'```(?:json)?\s*([\s\S]*?)```', raw)
+    if match:
+        try:
+            return json.loads(match.group(1).strip())
+        except json.JSONDecodeError:
+            pass
+
+    match = re.search(r'\{[\s\S]*\}', raw)
+    if match:
+        try:
+            return json.loads(match.group(0))
+        except json.JSONDecodeError:
+            pass
+
+    raise ValueError(
+        f"repo_evaluator: 无法解析 LLM 返回的 JSON。\n"
+        f"原始返回（前 500 字符）:\n{raw[:500]}"
+    )
+
+
+# ============================================================
+# 自测代码 —— 写完后运行 python repo_evaluator.py 验证
+# ============================================================
+if __name__ == "__main__":
+    # 测试 1：anomalib（工业缺陷检测领域的明星项目，应该是高分）
+    print("=" * 60)
+    print("测试 1：OpenVINO anomalib（预期：可复现性高 + 适配度高）")
+    print("=" * 60)
+    mock_repo = {
+        "full_name": "openvinotoolkit/anomalib",
+        "html_url": "https://github.com/openvinotoolkit/anomalib",
+        "stars": 4000,
+        "description": "An anomaly detection library comprising state-of-the-art algorithms and features such as experiment management, hyper-parameter optimization, and edge inference.",
+        "updated_at": "2026-01-15T00:00:00Z",
+        "language": "Python",
+    }
+    mock_readme = """# Anomalib
+A library for benchmarking, developing and deploying deep learning based anomaly detection algorithms.
+
+## Installation
+```
+pip install anomalib
+```
+
+## Training
+```python
+from anomalib.engine import Engine
+engine = Engine()
+engine.train()
+```
+
+## Supported Datasets
+- MVTec AD
+- BTAD
+- KSDD2
+
+## Benchmarking
+Use `tools/benchmark.py` for standardized evaluation across all models.
+"""
+    mock_deps = {"requirements.txt": "torch>=1.10\npytorch-lightning>=1.7\nopencv-python\nnumpy\nscikit-learn"}
+    result = evaluate_repo(mock_repo, mock_readme, mock_deps, "Embedding-based")
+    print(f"  综合: {result.get('overall_score')}/100")
+    print(f"  可复现性: {result.get('reproducibility_score')}/80")
+    print(f"  适配度: {result.get('benchmark_fitness_score')}/20")
+    print(f"  判定: {result.get('verdict')} | 实验就绪: {result.get('benchmark_readiness')}")
+
+    print()
+
+    # 测试 2：一个只有推理 demo 的个人项目（应该是低适配度）
+    print("=" * 60)
+    print("测试 2：仅推理的个人项目（预期：可复现性中等 + 适配度低）")
+    print("=" * 60)
+    mock_repo2 = {
+        "full_name": "someone/anomaly-detection-demo",
+        "html_url": "https://github.com/someone/anomaly-detection-demo",
+        "stars": 15,
+        "description": "A simple demo of anomaly detection using pretrained models.",
+        "updated_at": "2024-03-01T00:00:00Z",
+        "language": "Python",
+    }
+    mock_readme2 = """# Anomaly Detection Demo
+A simple inference demo.
+
+## Usage
+```
+python demo.py --image path/to/image.jpg
+```
+
+Pretrained weights: download from Google Drive (link may expire).
+"""
+    mock_deps2 = {}
+    result2 = evaluate_repo(mock_repo2, mock_readme2, mock_deps2, "Embedding-based")
+    print(f"  综合: {result2.get('overall_score')}/100")
+    print(f"  适配度: {result2.get('benchmark_fitness_score')}/20")
+    print(f"  判定: {result2.get('verdict')} | 实验就绪: {result2.get('benchmark_readiness')}")
+    print(f"  建议: {result2.get('suggested_use')}")
+```
+
+### 2.3 调试指南
+
+**问题 1：可复现性和适配度分数总是高度相关（没分开）**
+- 症状：`reproducibility_score` 高 → `benchmark_fitness_score` 也高，低同理
+- 原因：LLM 没理解这两个是独立的维度
+- 修复：在 system prompt 中加一句明确的反例：「例如，一个仓库可以 README 很完善（文档 20 分）但只提供推理 demo 没有训练（适配度 5 分）。两个维度必须独立判断。」
+
+**问题 2：评分太高或太低（不符合常识）**
+- 症状：所有仓库都在 80+ 或 30-
+- 测试：手选 3 个你自己熟悉的仓库（一个好一个坏一个中间），人工打分，对比 LLM 打分
+- 修复：在 system prompt 中调整分数段的描述或增加参考锚点
+
+**问题 3：reasoning 太笼统（"该仓库质量较高"）**
+- 症状：分析没有引用具体内容
+- 修复：在 system prompt 的 reasoning 描述中加「必须引用 README 或依赖文件中的具体内容作为证据」
+
+---
+
+## 三、调度器：`run.py` — 把 Agent 和 Workflow 串起来
+
+> **类型：调度器（胶水代码）** | 既不是 Agent 也不是 Workflow
+> **核心逻辑**：按顺序调用 Workflow（甲）和 Agent（你），在它们之间传递数据
+
+### 3.1 这个调度器要解决什么问题
+
+你现在有了：
+- 甲的工作：3 个 Workflow（`fetch_paper_info` → `search_repos` → `fetch_readme`/`fetch_dependencies`）
+- 你的工作：2 个 Agent（`analyze_direction` → `evaluate_repo`）
+
+但这些是互相独立的函数。调度器的职责就是**按正确的顺序调用它们，把上一个的输出传给下一个的输入**。
+
+```
+调度器 = 一个函数 run(url)，里面按顺序做了：
+  1. 调甲的 Workflow: fetch_paper_info(url) → 拿到论文信息
+  2. 调你的 Agent:   analyze_direction(...)   → 拿到方向+搜索词
+  3. 调甲的 Workflow: search_repos(...)        → 拿到候选仓库
+  4. 调甲的 Workflow: fetch_readme/deps(...)   → 拿到每个仓库的详情
+  5. 调你的 Agent:   evaluate_repo(...)        → 拿到每个仓库的评分
+  6. 汇总返回
+```
+
+**就这么简单。** 没有回环、没有并发、没有流式。这 6 步就是 run.py 的全部内容。
+
+### 3.2 完整代码
+
+```python
+# run.py
+import sys
+
+# ============================================================
+# 导入所有模块
+# ============================================================
+from paper_fetcher import fetch_paper_info          # 甲的模块
+from direction_analyzer import analyze_direction     # 你的模块
+from repo_searcher import search_repos               # 甲的模块
+from repo_fetcher import fetch_readme, fetch_dependencies  # 甲的模块
+from repo_evaluator import evaluate_repo             # 你的模块
+
+
+def run(arxiv_url: str, top_n: int = 5) -> dict:
+    """主入口：从论文 arxiv URL 到研究方向全景 + 代码推荐的完整链路。
+
+    Args:
+        arxiv_url: arxiv 论文 URL，如 https://arxiv.org/abs/1706.03762
+        top_n: 最终保留的候选仓库数量
+
+    Returns:
+        dict: {
+            "paper": {...},
+            "direction": {...},
+            "repos": [{...evaluation...}, ...],
+            "error": "..."  # 仅在完全失败时存在
+        }
+    """
+    # ================================================================
+    # 第一层：研究方向解析
+    # ================================================================
+    print("=" * 60)
+    print("[1/5] 正在获取论文信息...")
+    try:
+        paper = fetch_paper_info(arxiv_url)
+    except Exception as e:
+        return {"error": f"获取论文信息失败: {e}"}
+
+    title = paper.get("title", "")
+    abstract = paper.get("abstract", "")
+    print(f"  标题: {title[:100]}...")
+    print(f"  作者: {', '.join(paper.get('authors', [])[:3])}")
+    print(f"  分类: {', '.join(paper.get('categories', []))}")
+
+    print()
+    print("[2/5] 正在解析研究方向（LLM 调用 #1）...")
+    try:
+        direction = analyze_direction(title, abstract)
+    except Exception as e:
+        return {
+            "paper": paper,
+            "error": f"研究方向解析失败: {e}",
+        }
+
+    subfield = direction.get("subfield", "未知")
+    families = direction.get("method_families", [])
+    print(f"  子领域: {subfield}")
+    print(f"  趋势: {direction.get('subfield_trend', '')[:80]}...")
+    print(f"  方法族 ({len(families)} 个):")
+    for mf in families:
+        print(f"    - {mf.get('family_name', '?')}: {mf.get('description', '')[:60]}...")
+
+    # 汇总所有搜索查询
+    all_queries = []
+    for mf in families:
+        all_queries.extend(mf.get("search_queries", []))
+    all_queries.extend(direction.get("broad_queries", []))
+    print(f"  生成 {len(all_queries)} 个搜索查询")
+
+    # ================================================================
+    # 第二层：开源代码发现
+    # ================================================================
+    print()
+    print(f"[3/5] 正在搜索 GitHub 仓库（{len(all_queries)} 个查询）...")
+    try:
+        candidates = search_repos(all_queries, max_per_keyword=5)
+    except Exception as e:
+        return {
+            "paper": paper,
+            "direction": direction,
+            "error": f"GitHub 搜索失败: {e}",
+        }
+
+    candidates = candidates[:top_n]
+    print(f"  去重后获得 {len(candidates)} 个候选仓库")
+
+    if not candidates:
+        return {
+            "paper": paper,
+            "direction": direction,
+            "repos": [],
+            "error": "未找到相关开源仓库。该方向可能太新或太冷门，暂无高质量开源实现。",
+        }
+
+    print("  候选列表:")
+    for i, c in enumerate(candidates):
+        print(f"    {i+1}. {c['full_name']} ⭐{c.get('stars', 0)}")
+
+    # ================================================================
+    # 第三层：可复现性 + 对比实验适配度评估
+    # ================================================================
+    print()
+    print(f"[4/5] 正在评估 {len(candidates)} 个仓库...")
+    evaluated = []
+
+    for i, repo in enumerate(candidates):
+        full_name = repo["full_name"]
+        try:
+            owner, name = full_name.split("/", 1)
+        except ValueError:
+            print(f"  ({i+1}/{len(candidates)}) 跳过（无法解析仓库名）: {full_name}")
+            continue
+
+        # 尝试匹配方法族
+        matched_family = _match_family(repo, families)
+        family_tag = f"[{matched_family}]" if matched_family else "[未归类]"
+        print(f"  ({i+1}/{len(candidates)}) 评估 {full_name} {family_tag}...")
+
+        try:
+            readme = fetch_readme(owner, name)
+            deps = fetch_dependencies(owner, name)
+            evaluation = evaluate_repo(repo, readme, deps, matched_family)
+        except Exception as e:
+            print(f"    ⚠ 评估失败: {e}")
+            evaluation = _make_error_evaluation(str(e))
+
+        evaluated.append({
+            "full_name": repo.get("full_name", ""),
+            "html_url": repo.get("html_url", ""),
+            "description": repo.get("description", ""),
+            "stars": repo.get("stars", 0),
+            "language": repo.get("language", ""),
+            "updated_at": repo.get("updated_at", ""),
+            "topics": repo.get("topics", []),
+            "match_keyword": repo.get("match_keyword", ""),
+            "method_family": matched_family,
+            "evaluation": evaluation,
+        })
+
+    # 按综合评分降序排列
+    evaluated.sort(key=lambda r: r["evaluation"].get("overall_score", 0), reverse=True)
+
+    # ================================================================
+    # 汇总返回
+    # ================================================================
+    print()
+    print(f"[5/5] 完成！")
+    best = evaluated[0] if evaluated else None
+    if best:
+        print(f"  最高分: {best['full_name']} ({best['evaluation'].get('overall_score', 0)}/100)")
+    print("=" * 60)
+
+    return {
+        "paper": paper,
+        "direction": direction,
+        "repos": evaluated,
+    }
+
+
+def _match_family(repo: dict, families: list[dict]) -> str:
+    """简易的仓库→方法族匹配。
+
+    策略：
+    1. 检查仓库 topics 是否包含方法族关键词
+    2. 检查仓库描述是否包含方法族名称
+    3. 都没匹配到返回空字符串（未归类）
+    """
+    desc = (repo.get("description") or "").lower()
+    topics = " ".join(repo.get("topics", [])).lower()
+    combined = desc + " " + topics
+
+    for mf in families:
+        family_name = mf.get("family_name", "")
+        if not family_name:
+            continue
+
+        # 尝试精确匹配 + 部分匹配
+        name_lower = family_name.lower()
+        # 例如 "Vision Transformer" -> ["vision", "transformer"]
+        name_parts = name_lower.split()
+
+        # 检查至少 2/3 的名称词出现在 combined 中
+        if len(name_parts) >= 2:
+            match_count = sum(1 for part in name_parts if part in combined)
+            if match_count >= max(2, len(name_parts) * 2 // 3):
+                return family_name
+        else:
+            # 单词方法名直接匹配
+            if name_lower in combined:
+                return family_name
+
+    return ""
+
+
+def _make_error_evaluation(error_msg: str) -> dict:
+    """构造一个表示评估失败的 evaluation dict"""
+    return {
+        "reproducibility_score": 0,
+        "benchmark_fitness_score": 0,
+        "overall_score": 0,
+        "verdict": "error",
+        "env_score": 0,
+        "doc_score": 0,
+        "code_score": 0,
+        "community_score": 0,
+        "dep_score": 0,
+        "benchmark_score": 0,
+        "reasoning": f"评估失败: {error_msg[:100]}",
+        "risks": ["评估过程出错，请手动检查该仓库"],
+        "benchmark_readiness": "not_ready",
+        "suggested_use": "评估失败，请手动检查",
+    }
+
+
+# ============================================================
+# 命令行入口
+# ============================================================
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("用法: python run.py <arxiv_url>")
+        print("示例: python run.py https://arxiv.org/abs/1706.03762")
+        print("示例: python run.py https://arxiv.org/abs/2010.11929")
+        sys.exit(1)
+
+    url = sys.argv[1]
+    result = run(url)
+
+    if result.get("error"):
+        print(f"\n{'='*60}")
+        print(f"运行未完全成功")
+        print(f"{'='*60}")
+        print(f"  {result['error']}")
+
+        # 即使有 error，如果有部分结果也打印出来
+        if result.get("paper"):
+            print(f"\n  论文信息已获取: {result['paper'].get('title', '')[:80]}")
+        if result.get("direction"):
+            print(f"  方向解析已完成: {result['direction'].get('subfield', '')}")
+    else:
+        # 导入 format_report 并打印
+        from app import format_report
+        print(format_report(result))
+```
+
+### 3.3 调试指南
+
+**问题 1：整个链路跑到某一步卡住不动**
+- 原因：某个 API 调用超时或限速
+- 排查：看终端最后打印的是 `[1/5]` `[2/5]` `[3/5]` 还是 `[4/5]`
+  - 卡在 `[1/5]` → arxiv API 问题
+  - 卡在 `[2/5]` → DeepSeek API 问题
+  - 卡在 `[3/5]` → GitHub Search API 限速
+  - 卡在 `[4/5]` → GitHub Content API 或 repo_evaluator 的 DeepSeek 调用问题
+
+**问题 2：`[3/5]` 返回 0 个候选仓库**
+- 排查：打印 `all_queries`，复制几个去 GitHub 手动搜，看是不是搜索词本身的问题
+- 修复方向：调 direction_analyzer 的 prompt（见 1.3 节）
+
+**问题 3：`_match_family` 匹配不到方法族**
+- 这是 Week 1 的已知限制。简易匹配基于字符串包含，精准度不高
+- Week 1 接受"未归类"的结果，Week 3 再用 LLM 做精准归类
+
+---
+
+## 四、界面：`app.py` — Gradio 界面 + 研报格式化
+
+> **类型：界面层** | 不是 Agent 也不是 Workflow
+> **核心职责**：把 run.py 的 dict 输出变成人类可读的 Markdown 研报，包装一个 Gradio 壳
+
+### 4.1 这个模块要解决什么问题
+
+两个职责：
+1. **`format_report()`**：把 `run.py` 返回的 dict 变成"研究方向全景研报"（你已经在前面看到过结构了）
+2. **`diagnose()`**：Gradio 的回调函数，用户输入 arxiv URL → 调 `run()` → 调 `format_report()` → 显示
+
+### 4.2 完整代码
+
+```python
+# app.py
+import gradio as gr
+from run import run
+
+
+def diagnose(arxiv_url: str) -> str:
+    """Gradio 回调：用户输入 arxiv URL → 返回 Markdown 研报"""
+    url = arxiv_url.strip()
+    if not url:
+        return "## ⚠️ 请输入 arxiv 论文链接\n\n示例: `https://arxiv.org/abs/1706.03762`"
+
+    # 执行完整链路
+    try:
+        result = run(url)
+    except ValueError as e:
+        return f"## ❌ 输入格式错误\n\n{str(e)}\n\n请确认输入的是有效的 arxiv 链接。"
+    except RuntimeError as e:
+        return f"## ❌ API 请求失败\n\n{str(e)}\n\n请检查网络连接或稍后重试。"
+    except Exception as e:
+        return f"## ❌ 运行出错\n\n```\n{type(e).__name__}: {str(e)}\n```\n\n请将以上错误信息反馈给开发者。"
+
+    # 处理部分失败的情况
+    if result.get("error") and not result.get("repos"):
+        paper = result.get("paper", {})
+        direction = result.get("direction", {})
+        title = paper.get("title", "未知") if paper else "未知"
+
+        md = f"""# ResearchRadar 研究方向全景研报
+
+---
+
+## 论文信息
+
+**{title}**
+
+---
+
+## ⚠️ 未能完成完整评估
+
+**原因**: {result['error']}
+
+"""
+        if direction:
+            md += f"""## 研究方向解析（部分结果）
+
+**子领域**: {direction.get('subfield', 'N/A')}
+
+**趋势**: {direction.get('subfield_trend', 'N/A')}
+"""
+        md += """
+---
+> 该论文方向可能太新或太冷门，暂无高质量开源实现。这恰好帮助你判断——在这个方向开展研究需要从头实现。
+"""
+        return md
+
+    # 正常情况
+    return format_report(result)
+
+
+def format_report(result: dict) -> str:
+    """将 run() 的结果格式化为 Markdown 研报。
+
+    研报结构：
+    1. 论文信息
+    2. 研究方向全景（子领域 + 趋势 + 方法族谱系）
+    3. 开源实现评估排名（六维度评分明细）
+    4. 对比实验推荐总结（按就绪度分组）
+    """
+    paper = result.get("paper", {})
+    direction = result.get("direction", {})
+    repos = result.get("repos", [])
+
+    # ================================================================
+    # 第一部分：论文信息
+    # ================================================================
+    arxiv_id = paper.get("arxiv_id", "")
+    arxiv_url = f"https://arxiv.org/abs/{arxiv_id}" if arxiv_id else ""
+
+    md = "# ResearchRadar 研究方向全景研报\n\n---\n\n## 一、论文信息\n\n"
+    md += "| 项目 | 内容 |\n|------|------|\n"
+    md += f"| **标题** | {paper.get('title', 'N/A')} |\n"
+    if arxiv_url:
+        md += f"| **arXiv** | [{arxiv_id}]({arxiv_url}) |\n"
+    else:
+        md += f"| **arXiv ID** | {arxiv_id or 'N/A'} |\n"
+    md += f"| **作者** | {', '.join(paper.get('authors', ['N/A'])[:5])}"
+    if len(paper.get("authors", [])) > 5:
+        md += f" 等 {len(paper.get('authors', []))} 人"
+    md += " |\n"
+    published = paper.get("published", "")
+    if published:
+        md += f"| **发表时间** | {published[:10]} |\n"
+    categories = paper.get("categories", [])
+    if categories:
+        md += f"| **分类** | {', '.join(categories)} |\n"
+
+    # ================================================================
+    # 第二部分：研究方向全景
+    # ================================================================
+    md += "\n---\n\n## 二、研究方向全景\n\n"
+    md += f"### 子领域定位\n\n**{direction.get('subfield', '未知')}**\n\n"
+    md += f"### 当前趋势\n\n{direction.get('subfield_trend', '暂无分析')}\n\n"
+    md += "### 方法族谱系\n\n"
+    md += "| # | 方法族 | 核心特点 | 代表工作 |\n|---|--------|----------|----------|\n"
+
+    families = direction.get("method_families", [])
+    for i, mf in enumerate(families):
+        family_name = mf.get("family_name", f"方法族 {i+1}")
+        desc = mf.get("description", "")[:80]
+        rep = mf.get("representative_work", "")[:60]
+        md += f"| {i+1} | **{family_name}** | {desc} | {rep} |\n"
+
+    if not families:
+        md += "| - | 未能识别出明确的方法族 | - | - |\n"
+
+    # ================================================================
+    # 第三部分：开源实现评估排名
+    # ================================================================
+    md += "\n---\n\n## 三、开源实现评估排名\n\n"
+
+    if not repos:
+        md += "**未找到相关开源仓库。**\n\n"
+        return md
+
+    for i, repo in enumerate(repos):
+        full_name = repo.get("full_name", f"仓库 {i+1}")
+        html_url = repo.get("html_url", "")
+        ev = repo.get("evaluation", {})
+        mf = repo.get("method_family", "")
+
+        # 图标映射
+        verdict_icon = {
+            "reproducible": "✅",
+            "partially": "⚠️",
+            "not_reproducible": "❌",
+            "error": "💥",
+        }.get(ev.get("verdict", ""), "❓")
+
+        readiness_icon = {
+            "ready": "🟢",
+            "partial": "🟡",
+            "not_ready": "🔴",
+        }.get(ev.get("benchmark_readiness", ""), "⚪")
+
+        family_tag = f" `[{mf}]`" if mf else ""
+
+        md += f"### {i+1}. [{full_name}]({html_url}){family_tag}\n\n"
+
+        repro_score = ev.get("reproducibility_score", ev.get("overall_score", "N/A"))
+        bench_score = ev.get("benchmark_fitness_score", ev.get("benchmark_score", "N/A"))
+        overall = ev.get("overall_score", "N/A")
+
+        md += f"{verdict_icon} **可复现性: {repro_score}/80** | "
+        md += f"{readiness_icon} **对比实验适配度: {bench_score}/20** | "
+        md += f"**综合: {overall}/100**\n\n"
+
+        # 六维度得分表
+        md += "| 维度 | 得分 | 满分 | 说明 |\n"
+        md += "|------|:----:|:----:|------|\n"
+        md += f"| 环境配置 | {_fmt(ev.get('env_score'))} | 15 | 依赖文件完整性 |\n"
+        md += f"| 文档质量 | {_fmt(ev.get('doc_score'))} | 20 | 安装/训练/数据说明 |\n"
+        md += f"| 代码可用性 | {_fmt(ev.get('code_score'))} | 20 | 训练+推理脚本 |\n"
+        md += f"| 社区活跃度 | {_fmt(ev.get('community_score'))} | 10 | Star + 更新频率 |\n"
+        md += f"| 依赖健康度 | {_fmt(ev.get('dep_score'))} | 15 | 依赖兼容性 |\n"
+        md += f"| **对比实验** | **{_fmt(ev.get('benchmark_score'))}** | **20** | **benchmark + 预训练权重** |\n"
+
+        md += f"\n⭐ Star: {repo.get('stars', 0)}"
+        if repo.get("match_keyword"):
+            md += f" | 匹配词: `{repo.get('match_keyword', '')}`"
+        md += "\n\n"
+
+        # 分析和建议
+        reasoning = ev.get("reasoning", "N/A")
+        md += f"**分析**: {reasoning}\n\n"
+        md += f"**对比实验建议**: {ev.get('suggested_use', 'N/A')}\n\n"
+
+        # 风险
+        risks = ev.get("risks", [])
+        if risks:
+            md += "**风险点**: " + " · ".join(f"`{r}`" for r in risks) + "\n\n"
+
+        md += "---\n\n"
+
+    # ================================================================
+    # 第四部分：对比实验推荐总结
+    # ================================================================
+    md += "## 四、对比实验推荐总结\n\n"
+
+    ready = [r for r in repos if r["evaluation"].get("benchmark_readiness") == "ready"]
+    partial = [r for r in repos if r["evaluation"].get("benchmark_readiness") == "partial"]
+    not_ready = [
+        r for r in repos
+        if r["evaluation"].get("benchmark_readiness") not in ("ready", "partial")
+    ]
+
+    if ready:
+        md += "### 🟢 可直接用于对比实验\n\n"
+        for r in ready:
+            url = r.get("html_url", "#")
+            name = r.get("full_name", "未知")
+            suggestion = r["evaluation"].get("suggested_use", "")
+            md += f"- **[{name}]({url})** — {suggestion}\n"
+        md += "\n"
+
+    if partial:
+        md += "### 🟡 需要少量修改后可用\n\n"
+        for r in partial:
+            url = r.get("html_url", "#")
+            name = r.get("full_name", "未知")
+            suggestion = r["evaluation"].get("suggested_use", "")
+            md += f"- **[{name}]({url})** — {suggestion}\n"
+        md += "\n"
+
+    if not_ready:
+        md += "### 🔴 仅适合参考代码实现\n\n"
+        for r in not_ready:
+            url = r.get("html_url", "#")
+            name = r.get("full_name", "未知")
+            reason = r["evaluation"].get("suggested_use") or r["evaluation"].get("reasoning", "")
+            md += f"- **[{name}]({url})** — {reason[:120]}...\n"
+        md += "\n"
+
+    md += "---\n\n> ResearchRadar · 论文研究方向全景 + 开源代码评估 + 对比实验推荐\n"
+
+    return md
+
+
+def _fmt(value) -> str:
+    """格式化数值，None 显示为 N/A"""
+    if value is None:
+        return "N/A"
+    return str(value)
+
+
+# ============================================================
+# Gradio 启动
+# ============================================================
+DEMO_EXAMPLES = [
+    ["https://arxiv.org/abs/2011.08785"],   # PaDiM（工业缺陷检测，你的领域）
+    ["https://arxiv.org/abs/1706.03762"],   # Attention Is All You Need（经典）
+    ["https://arxiv.org/abs/2108.07610"],   # DRAEM（缺陷检测，合成缺陷方法）
+]
+
+demo = gr.Interface(
+    fn=diagnose,
+    inputs=gr.Textbox(
+        label="论文 arxiv 链接",
+        placeholder="https://arxiv.org/abs/1706.03762",
+        lines=1,
+    ),
+    outputs=gr.Markdown(label="研究方向全景研报"),
+    title="ResearchRadar — 研究方向全景 + 开源代码评估",
+    description=(
+        "输入一篇 AI 论文的 arxiv 链接，AI 帮你：\n"
+        "1. 摸清该研究方向的前沿全景（子领域 + 方法族谱系）\n"
+        "2. 找到最适配的开源实现\n"
+        "3. 评估每个仓库能否直接用于写论文跑对比实验"
+    ),
+    examples=DEMO_EXAMPLES,
+    theme="soft",
+)
+
+if __name__ == "__main__":
+    # share=False: 仅本地访问
+    # share=True: 生成公网链接（演示时如果网络允许可以用）
+    demo.launch(server_name="0.0.0.0", share=False)
+```
+
+---
+
+## 中间总结：你搭建的 4 个文件与 Agent/Workflow 的关系
+
+在你被代码细节淹没之前，先退后一步看全景：
+
+```
+  ┌────────────────────────────────────────────────────────────┐
+  │                  run.py（调度器，你写）                      │
+  │                                                           │
+  │  第 1 步：paper = fetch_paper_info(url)     ← 甲的 Workflow │
+  │                       │                                   │
+  │  第 2 步：direction = analyze_direction()  ← 你的 Agent 1  │
+  │                       │                                   │
+  │  第 3 步：repos = search_repos(queries)    ← 甲的 Workflow │
+  │                       │                                   │
+  │  第 4 步：details = fetch_readme/deps()    ← 甲的 Workflow │
+  │                       │                                   │
+  │  第 5 步：scores = evaluate_repo()         ← 你的 Agent 2  │
+  │                       │                                   │
+  │  第 6 步：return 汇总结果                                  │
+  └──────────────────────┬─────────────────────────────────────┘
+                         │
+                         ▼
+  ┌────────────────────────────────────────────────────────────┐
+  │                  app.py（界面，你写）                        │
+  │  format_report(汇总结果) → Markdown 研报 → 用户看到         │
+  └────────────────────────────────────────────────────────────┘
+```
+
+**你需要实际写的东西拆解下来就是**：
+
+| 文件 | 核心工作量 | 代码行数（估算） |
+|------|-----------|:--------:|
+| `direction_analyzer.py` | 写 1 段 System Prompt + 1 段 User Prompt 模板 + JSON 解析 | ~90 行 |
+| `repo_evaluator.py` | 写 1 段 System Prompt + 1 段 User Prompt 模板 + JSON 解析 | ~110 行 |
+| `run.py` | 6 步顺序调用 + try/except + `_match_family` + print 进度 | ~120 行 |
+| `app.py` | `format_report()` 字符串拼接 + Gradio 包装 | ~180 行 |
+
+**共计约 500 行 Python，核心挑战不是代码量，而是 Prompt 工程。**
+
+---
+
+## 五、第一周五天执行计划
+
+### 你的 5 天时间线
+
+```
+周一 ──→ 写 direction_analyzer.py + 调 prompt
+周二 ──→ 写 repo_evaluator.py + 调六维评分
+周三 ──→ 写 run.py + app.py + 下午与甲联调
+周四 ──→ debug 整条链路 + PPT 三层架构图 + 状态 schema
+周五 ──→ 联调彩排 + 下午汇报
+```
+
+### 每日详细任务
+
+#### 周一：方向解析模块
+
+| 时间 | 任务 | 验收标准 |
+|------|------|----------|
+| 上午 | 建 `direction_analyzer.py`，复制上文完整代码 | 运行自测，成功打印 Transformer 和 PaDiM 的方向解析结果 |
+| 下午 | 用 3-5 篇论文测试：Transformer + PaDiM(2011.08785) + PatchCore(2106.08265) + EfficientAD(2303.14535) + DRAEM(2108.07610) | 每篇论文的方法族 ≥ 3 个，搜索词在 GitHub 手动搜有结果。特别关注：工业缺陷检测的论文是否被正确归类到 anomaly detection/defect detection 子领域 |
+| 晚上 | 根据测试结果调 system prompt（方法族太少？搜索词太学术化？子领域定位不准？） | 5 篇论文的方向解析结果你都觉得"合理" |
+
+#### 周二：评估模块
+
+| 时间 | 任务 | 验收标准 |
+|------|------|----------|
+| 上午 | 建 `repo_evaluator.py`，复制完整代码 | 运行自测，anomalib 评分在 70-95 之间，仅推理的仓库适配度 < 10 |
+| 下午 | 手挑 5 个工业缺陷检测领域的仓库测试（如 anomalib / PaDiM / PatchCore / 2 个个人项目），人工评分 vs LLM 评分对比 | 可复现性和适配度两个维度能看出独立性——anomalib 两维都高，只有推理 demo 的项目适配度远低于可复现性 |
+| 晚上 | 调 prompt，重点关注"适配度"评分是否合理 | 有标准 benchmark 脚本的仓库适配度 > 15，只有推理 demo 的 < 10 |
+
+#### 周三：串联 + UI
+
+| 时间 | 任务 | 验收标准 |
+|------|------|----------|
+| 上午 | 建 `run.py`，复制完整代码 | `python run.py https://arxiv.org/abs/2011.08785`（PaDiM）能跑通完整三层链路 |
+| 下午 | 建 `app.py`，复制完整代码，与甲联调 | 浏览器打开 `http://127.0.0.1:7860`，输入 PaDiM arxiv URL，看到完整研报，方法族包含 Embedding-based / Reconstruction-based 等 |
+| 晚上 | 处理各种边界情况（见下方周三日落前 checklist） | 见 checklist |
+
+**周三日落前 checklist**：
+- [ ] `python run.py <arxiv_url>` 能跑通，终端打印 `[5/5] 完成！`
+- [ ] 搜不到仓库时：不崩溃，返回 `error` 字段 + 方向解析结果
+- [ ] 某个仓库抓取失败时：该仓库标记为 error，其他仓库正常评估
+- [ ] 完整研报在 Gradio 中显示正常，Markdown 渲染正确
+- [ ] 端到端耗时 < 60 秒
+
+#### 周四：debug + PPT
+
+| 时间 | 任务 | 产出 |
+|------|------|------|
+| 上午 | 用 3 篇 demo 论文各跑 3 遍，记录每次结果的一致性 | 发现最频繁的失败模式，修复或记录为"已知限制" |
+| 下午 | 画 PPT 中的三层架构图 + 状态 schema + Agent I/O schema | 3 页 PPT 初稿 |
+| 晚上 | 准备答辩可能被问到的技术问题（见附录 A） | 答辩 Q&A 文档 |
+
+#### 周五：彩排 + 汇报
+
+| 时间 | 任务 |
+|------|------|
+| 上午 | 完整走一遍 demo 流程（正样本论文 → 负样本论文 → 灰色样本），每步配上讲解词 |
+| 下午 | **汇报** |
+
+---
+
+## 六、你的状态 schema 设计
+
+你需要定义项目中的核心数据结构。这部分可以用在 PPT 中展示你的架构设计能力。
+
+```python
+# state.py —— 定义整个系统的数据模型（PPT 用，Week 1 不强制要求写成代码）
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+# ---- 第一层：研究方向 ----
+
+@dataclass
+class MethodFamily:
+    """方法族"""
+    family_name: str           # 如 "Vanilla Transformer"
+    description: str           # 一句话核心特点
+    representative_work: str   # 代表论文
+    search_queries: list[str]  # GitHub 搜索词
+
+
+@dataclass
+class DirectionAnalysis:
+    """研究方向解析结果"""
+    subfield: str              # 子领域名
+    subfield_trend: str        # 当前趋势
+    method_families: list[MethodFamily]
+    broad_queries: list[str]   # 宽泛搜索词
+
+
+# ---- 第二层：候选仓库 ----
+
+@dataclass
+class CandidateRepo:
+    """候选仓库"""
+    full_name: str             # "huggingface/transformers"
+    html_url: str
+    description: str
+    stars: int
+    language: str
+    updated_at: str
+    topics: list[str]
+    match_keyword: str         # 命中哪个搜索词
+    method_family: str         # 归类到哪个方法族（可为空）
+    readme: Optional[str] = None
+    dependencies: dict[str, str] = field(default_factory=dict)
+
+
+# ---- 第三层：评估结果 ----
+
+@dataclass
+class EvalResult:
+    """单个仓库的评估结果"""
+    reproducibility_score: int   # 可复现性总分 (0-80)
+    benchmark_fitness_score: int # 对比实验适配度总分 (0-20)
+    overall_score: int           # 综合总分 (0-100)
+    verdict: str                 # reproducible / partially / not_reproducible
+    env_score: int               # 0-15
+    doc_score: int               # 0-20
+    code_score: int              # 0-20
+    community_score: int         # 0-10
+    dep_score: int               # 0-15
+    benchmark_score: int         # 0-20
+    reasoning: str               # 分析文本
+    risks: list[str]             # 风险列表
+    benchmark_readiness: str     # ready / partial / not_ready
+    suggested_use: str           # 建议用途
+
+
+# ---- 顶层：完整研报 ----
+
+@dataclass
+class ResearchReport:
+    """完整研究方向全景研报"""
+    paper_info: dict
+    direction: DirectionAnalysis
+    repos: list[tuple[CandidateRepo, EvalResult]]
+```
+
+---
+
+## 七、文件结构（你负责的文件用 ★ 标记）
+
+```
+ResearchRadar/
+├── paper_fetcher.py         # 甲
+├── repo_searcher.py         # 甲
+├── repo_fetcher.py          # 甲
+├── direction_analyzer.py    # ★ 你：LLM 研究方向解析 + 方法族 + 搜索词
+├── repo_evaluator.py        # ★ 你：LLM 六维度评分
+├── run.py                   # ★ 你：三层调度器
+├── app.py                   # ★ 你：Gradio + 研报格式化
+├── state.py                 # ★ 你：状态 schema（PPT 用，可选）
+├── eval.py                  # 甲
+├── test_set/                # 甲
+├── requirements.txt
+└── README.md
+```
+
+**你的 `requirements.txt` 需求项**：
+```
+openai>=1.0     # DeepSeek 通过 OpenAI SDK 调用
+gradio>=4.0     # UI
+```
+
+---
+
+## 八、PPT 中你需要准备的内容
+
+6 分钟演示中，你的 PPT 部分建议占 2-3 页：
+
+### Page 1：三层架构图
+```
+┌─────────────────────────────────────────┐
+│        ResearchRadar 三层架构            │
+│                                         │
+│  ① 研究方向解析 (Agent)                 │
+│     arxiv API → LLM → 子领域+方法族      │
+│          ↓                              │
+│  ② 开源代码发现 (Workflow)              │
+│     GitHub Search → 去重 → 候选仓库      │
+│          ↓                              │
+│  ③ 可复现性+适配度评估 (Agent)          │
+│     GitHub API → LLM → 六维评分         │
+│          ↓                              │
+│  研究方向全景研报                        │
+└─────────────────────────────────────────┘
+```
+
+### Page 2：状态流转
+```
+arxiv URL → paper_info dict
+              ↓
+         direction dict (subfield + method_families + queries)
+              ↓
+         [repo dict, repo dict, ...] (top 5)
+              ↓
+         每个 repo 附加 evaluation dict (六维评分)
+              ↓
+         ResearchReport (汇总 → format_report → Markdown)
+```
+
+### Page 3：6 周里程碑（与甲共用）
+展示路线图，强调 Week 1 已经实现三层全链路。
+
+---
+
+## 九、常见故障模式速查表
+
+| 现象 | 排查命令 | 可能原因 | 修复 |
+|------|----------|----------|------|
+| `direction_analyzer` JSON 解析失败 | 在代码中 `print(raw[:300])` | DeepSeek 返回了 markdown 包裹或纯文本 | 检查 `_parse_json_safe` 的三种策略是否覆盖，或加 prompt 约束 |
+| GitHub 搜不到仓库 | `print(all_queries)` 然后手动去 GitHub 搜 | 搜索词太学术化，GitHub 不匹配 | 调 direction_analyzer prompt，增加"搜索词用日常技术术语"的约束 |
+| 搜到的仓库太多（100+） | 正常，`search_repos` 内部按 star 排序取 top | 没问题 | 不需要修复 |
+| `repo_evaluator` 评分全是 70+ | 换一个公认烂仓库测试 | LLM 评分偏宽容 | 在 prompt 中加"多数仓库的分数应该在 40-70 之间"的锚定 |
+| Gradio 白屏 | 终端看错误日志 | `app.py` import 报错或端口冲突 | 检查所有 import，或换端口 `server_port=7861` |
+| 整条链路 > 2 分钟 | 分别计时每个步骤 | GitHub 搜索串行 10+ 次 | Week 2 优化，先用 `top_n=3` 减小候选数 |
+
+---
+
+## 附录 A：答辩可能被问到的问题
+
+1. **"为什么不用 LangChain/LangGraph？"**
+   → 我们的系统规模不需要编排框架。Agent 就是一个调了 LLM 的 Python 函数，Workflow 就是一个没调 LLM 的 Python 函数，run.py 就是一段胶水代码按顺序调用它们。总共不到 500 行，框架的学习成本和抽象开销远超它带来的收益。
+
+2. **"方向解析的准确率怎么保证？"**
+   → Week 1 是 baseline，我们用人眼验证了 5 篇论文（含工业缺陷检测领域的 PaDiM、PatchCore 等）的方向解析结果。Week 3 会建立方向解析的评测集，用可量化指标调优。
+
+3. **"Agent 到底是怎么搭建的？"**
+   → 三步：写 System Prompt 定义角色和输出格式 → 写 User Prompt 填入具体数据 → 调 DeepSeek API 拿到 JSON 结果。Agent 不是一个会自己跑的程序，就是一个函数里有一行 `client.chat.completions.create(...)`。
+
+4. **"对比实验适配度和可复现性有什么区别？"**
+   → 可复现性回答"能不能跑"，适配度回答"跑了能不能写进实验部分"。以 anomalib 为例：可复现性 78/80（README 完善、pip install 即用），适配度 19/20（有标准 benchmark 脚本、支持 MVTec AD 数据集、有预训练权重）。而一个只有推理 demo 的项目可以可复现性 55/80 但适配度 5/20。
+
+5. **"你和甲怎么分工？"**
+   → 他负责所有 Workflow（arxiv API、GitHub 搜索、文件抓取这些确定性流程），我负责所有 Agent（方向解析、可复现性评估这些需要 LLM 做判断的模块），以及把两者串起来的调度器。按功能层切而不是按模块切，保证接口清晰。
+
+6. **"工业缺陷检测这个方向有什么特殊性？"**
+   → 这个方向方法族清晰（Embedding-based / Reconstruction-based / Teacher-Student / Synthetic Defect），有公认 benchmark（MVTec AD），有 anomalib 这样的一站式开源库。非常适合用 ResearchRadar 做方向全景展示——输入一篇论文就能看到整个领域的方法族地图。
+
+---
+
+> **最后一个建议**：周一到周五，每天下午 5 点和甲花 10 分钟对一下进度。你们的工作有交界面（你的 run.py 调他的 fetcher/searcher），接口约定清楚就不会在周三联调时崩。

app.py

@@ -0,0 +1,317 @@
+# app.py
+# ============================================================
+# 类型：界面层（乙负责）
+# 功能：Gradio 界面 + 研究方向全景研报格式化
+# 用法：python app.py → 浏览器打开 http://127.0.0.1:7860
+# 公网：设置 NGROK_AUTH_TOKEN 环境变量后自动生成公网链接
+# ============================================================
+import sys
+import os
+import gradio as gr
+
+# 自动加载 .env 文件
+_ENV_PATH = os.path.join(os.path.dirname(os.path.abspath(__file__)), ".env")
+if os.path.isfile(_ENV_PATH):
+    with open(_ENV_PATH, "r", encoding="utf-8") as _f:
+        for _line in _f:
+            _line = _line.strip()
+            if _line and not _line.startswith("#") and "=" in _line:
+                _key, _val = _line.split("=", 1)
+                if _key not in os.environ:
+                    os.environ[_key] = _val.strip().strip('"').strip("'")
+
+try:
+    from run import run
+except (ImportError, ModuleNotFoundError) as e:
+    print(f"[错误] 无法导入 run.py，请确认甲已交付所有 Workflow 模块。")
+    print(f"  {e}")
+    sys.exit(1)
+
+
+def diagnose(arxiv_url: str) -> str:
+    """Gradio 回调：用户输入 arxiv URL → 返回 Markdown 研报"""
+    url = arxiv_url.strip()
+    if not url:
+        return "## ⚠️ 请输入 arxiv 论文链接\n\n示例: `https://arxiv.org/abs/2011.08785`"
+
+    try:
+        result = run(url)
+    except ValueError as e:
+        return f"## ❌ 输入格式错误\n\n{str(e)}\n\n请确认输入的是有效的 arxiv 链接。"
+    except RuntimeError as e:
+        return f"## ❌ API 请求失败\n\n{str(e)}\n\n请检查网络连接或稍后重试。"
+    except Exception as e:
+        return f"## ❌ 运行出错\n\n```\n{type(e).__name__}: {str(e)}\n```\n\n请将以上错误信息反馈给开发者。"
+
+    # 处理部分失败的情况
+    if result.get("error") and not result.get("repos"):
+        paper = result.get("paper", {})
+        direction = result.get("direction", {})
+        title = paper.get("title", "未知") if paper else "未知"
+
+        md = f"""# ResearchRadar 研究方向全景研报
+
+---
+
+## 论文信息
+
+**{title}**
+
+---
+
+## ⚠️ 未能完成完整评估
+
+**原因**: {result['error']}
+
+"""
+        if direction:
+            md += f"""## 研究方向解析（部分结果）
+
+**子领域**: {direction.get('subfield', 'N/A')}
+
+**趋势**: {direction.get('subfield_trend', 'N/A')}
+"""
+        md += """
+---
+> 该论文方向可能太新或太冷门，暂无高质量开源实现。这恰好帮助你判断——在这个方向开展研究需要从头实现。
+"""
+        return md
+
+    return format_report(result)
+
+
+def format_report(result: dict) -> str:
+    """将 run() 的结果格式化为"研究方向全景研报" Markdown。
+
+    研报结构：
+    1. 论文信息
+    2. 研究方向全景（子领域 + 趋势 + 方法族谱系 + 开源覆盖度）
+    3. 方法族开源覆盖度（哪些已有实现、哪些是空白）
+    4. 开源实现评估排名（六维度评分明细）
+    5. 对比实验推荐总结（按就绪度分组）
+    """
+    paper = result.get("paper", {})
+    direction = result.get("direction", {})
+    repos = result.get("repos", [])
+
+    # ===== 第一部分：论文信息 =====
+    arxiv_id = paper.get("arxiv_id", "")
+    arxiv_url = f"https://arxiv.org/abs/{arxiv_id}" if arxiv_id else ""
+
+    md = "# ResearchRadar 研究方向全景研报\n\n---\n\n## 一、论文信息\n\n"
+    md += "| 项目 | 内容 |\n|------|------|\n"
+    md += f"| **标题** | {paper.get('title', 'N/A')} |\n"
+    if arxiv_url:
+        md += f"| **arXiv** | [{arxiv_id}]({arxiv_url}) |\n"
+    else:
+        md += f"| **arXiv ID** | {arxiv_id or 'N/A'} |\n"
+    md += f"| **作者** | {', '.join(paper.get('authors', ['N/A'])[:5])}"
+    if len(paper.get("authors", [])) > 5:
+        md += f" 等 {len(paper.get('authors', []))} 人"
+    md += " |\n"
+    published = paper.get("published", "")
+    if published:
+        md += f"| **发表时间** | {published[:10]} |\n"
+    categories = paper.get("categories", [])
+    if categories:
+        md += f"| **分类** | {', '.join(categories)} |\n"
+
+    # ===== 第二部分：研究方向全景 =====
+    md += "\n---\n\n## 二、研究方向全景\n\n"
+    md += f"### 子领域定位\n\n**{direction.get('subfield', '未知')}**\n\n"
+    md += f"### 当前趋势\n\n{direction.get('subfield_trend', '暂无分析')}\n\n"
+    md += "### 方法族谱系\n\n"
+    md += "| # | 方法族 | 核心特点 | 代表工作 |\n|---|--------|----------|----------|\n"
+
+    families = direction.get("method_families", [])
+    for i, mf in enumerate(families):
+        family_name = mf.get("family_name", f"方法族 {i+1}")
+        desc = mf.get("description", "")[:80]
+        rep = mf.get("representative_work", "")[:60]
+        md += f"| {i+1} | **{family_name}** | {desc} | {rep} |\n"
+
+    if not families:
+        md += "| - | 未能识别出明确的方法��� | - | - |\n"
+
+    # 方法族开源覆盖度
+    md += "\n### 方法族开源覆盖度\n\n"
+    covered = []
+    uncovered = []
+    for mf in families:
+        name = mf.get("family_name", "未知")
+        matched = mf.get("matched_repos", [])
+        if matched:
+            covered.append((name, matched))
+        else:
+            uncovered.append(name)
+
+    if covered:
+        md += "| 方法族 | 开源仓库数 | 覆盖状态 |\n"
+        md += "|--------|:----------:|:--------:|\n"
+        for name, matched in covered:
+            md += f"| **{name}** | {len(matched)} | 🟢 已有实现 |\n"
+    if uncovered:
+        for name in uncovered:
+            md += f"| **{name}** | 0 | 🔴 暂无开源实现 |\n"
+        md += "\n> 💡 这些方法族暂无开源实现——可能是研究空白或对比实验的差异化方向。\n"
+    md += "\n"
+
+    # ===== 第三部分：仓库评估排名 =====
+    md += "\n---\n\n## 四、开源实现评估排名\n\n"
+
+    if not repos:
+        md += "**未找到相关开源仓库。**\n\n"
+        return md
+
+    for i, repo in enumerate(repos):
+        full_name = repo.get("full_name", f"仓库 {i+1}")
+        html_url = repo.get("html_url", "")
+        ev = repo.get("evaluation", {})
+        mf = repo.get("method_family", "")
+
+        verdict_icon = {
+            "reproducible": "✅", "partially": "⚠️",
+            "not_reproducible": "❌", "error": "💥",
+        }.get(ev.get("verdict", ""), "❓")
+
+        readiness_icon = {
+            "ready": "🟢", "partial": "🟡", "not_ready": "🔴",
+        }.get(ev.get("benchmark_readiness", ""), "⚪")
+
+        family_tag = f" `[{mf}]`" if mf else ""
+
+        md += f"### {i+1}. [{full_name}]({html_url}){family_tag}\n\n"
+
+        repro_score = ev.get("reproducibility_score", ev.get("overall_score", "N/A"))
+        bench_score = ev.get("benchmark_fitness_score", ev.get("benchmark_score", "N/A"))
+        overall = ev.get("overall_score", "N/A")
+
+        md += f"{verdict_icon} **可复现性: {repro_score}/80** | "
+        md += f"{readiness_icon} **对比实验适配度: {bench_score}/20** | "
+        md += f"**综合: {overall}/100**\n\n"
+
+        md += "| 维度 | 得分 | 满分 | 说明 |\n"
+        md += "|------|:----:|:----:|------|\n"
+        md += f"| 环境配置 | {_fmt(ev.get('env_score'))} | 15 | 依赖文件完整性 |\n"
+        md += f"| 文档质量 | {_fmt(ev.get('doc_score'))} | 20 | 安装/训练/数据说明 |\n"
+        md += f"| 代码可用性 | {_fmt(ev.get('code_score'))} | 20 | 训练+推理脚本 |\n"
+        md += f"| 社区活跃度 | {_fmt(ev.get('community_score'))} | 10 | Star + 更新频率 |\n"
+        md += f"| 依赖健康度 | {_fmt(ev.get('dep_score'))} | 15 | 依赖兼容性 |\n"
+        md += f"| **对比实验** | **{_fmt(ev.get('benchmark_score'))}** | **20** | **benchmark + 预训练权重** |\n"
+
+        md += f"\n⭐ Star: {repo.get('stars', 0)}"
+        if repo.get("match_keyword"):
+            md += f" | 匹配词: `{repo.get('match_keyword', '')}`"
+        md += "\n\n"
+
+        reasoning = ev.get("reasoning", "N/A")
+        md += f"**分析**: {reasoning}\n\n"
+        md += f"**对比实验建议**: {ev.get('suggested_use', 'N/A')}\n\n"
+
+        risks = ev.get("risks", [])
+        if risks:
+            md += "**风险点**: " + " · ".join(f"`{r}`" for r in risks) + "\n\n"
+
+        md += "---\n\n"
+
+    # ===== 第四部分：对比实验推荐总结 =====
+    md += "## 五、对比实验推荐总结\n\n"
+
+    ready = [r for r in repos if r["evaluation"].get("benchmark_readiness") == "ready"]
+    partial = [r for r in repos if r["evaluation"].get("benchmark_readiness") == "partial"]
+    not_ready = [
+        r for r in repos
+        if r["evaluation"].get("benchmark_readiness") not in ("ready", "partial")
+    ]
+
+    if ready:
+        md += "### 🟢 可直接用于对比实验\n\n"
+        for r in ready:
+            url = r.get("html_url", "#")
+            name = r.get("full_name", "未知")
+            suggestion = r["evaluation"].get("suggested_use", "")
+            md += f"- **[{name}]({url})** — {suggestion}\n"
+        md += "\n"
+
+    if partial:
+        md += "### 🟡 需要少量修改后可用\n\n"
+        for r in partial:
+            url = r.get("html_url", "#")
+            name = r.get("full_name", "未知")
+            suggestion = r["evaluation"].get("suggested_use", "")
+            md += f"- **[{name}]({url})** — {suggestion}\n"
+        md += "\n"
+
+    if not_ready:
+        md += "### 🔴 仅适合参考代码实现\n\n"
+        for r in not_ready:
+            url = r.get("html_url", "#")
+            name = r.get("full_name", "未知")
+            reason = r["evaluation"].get("suggested_use") or r["evaluation"].get("reasoning", "")
+            md += f"- **[{name}]({url})** — {reason[:120]}...\n"
+        md += "\n"
+
+    md += "---\n\n> ResearchRadar · 论文研究方向全景 + 开源代码评估 + 对比实验推荐\n"
+
+    return md
+
+
+def _fmt(value) -> str:
+    """格式化数值，None 显示为 N/A"""
+    if value is None:
+        return "N/A"
+    return str(value)
+
+
+# ============================================================
+# Gradio 启动
+# ============================================================
+DEMO_EXAMPLES = [
+    ["https://arxiv.org/abs/2011.08785"],   # PaDiM（工业缺陷检测）
+    ["https://arxiv.org/abs/1706.03762"],   # Attention Is All You Need
+    ["https://arxiv.org/abs/2108.07610"],   # DRAEM（缺陷检测，合成缺陷方法）
+]
+
+demo = gr.Interface(
+    fn=diagnose,
+    inputs=gr.Textbox(
+        label="论文 arxiv 链接",
+        placeholder="https://arxiv.org/abs/2011.08785",
+        lines=1,
+    ),
+    outputs=gr.Markdown(label="研究方向全景研报"),
+    title="ResearchRadar — 研究方向全景 + 开源代码评估",
+    description=(
+        "输入一篇 AI 论文的 arxiv 链接，AI 帮你：\n"
+        "1. 摸清该研究方向的前沿全景（子领域 + 方法族谱系）\n"
+        "2. 找到最适配的开源实现\n"
+        "3. 评估每个仓库能否直接用于写论文跑对比实验"
+    ),
+    examples=DEMO_EXAMPLES,
+)
+
+if __name__ == "__main__":
+    public_url = None
+
+    # 尝试 ngrok 公网隧道（国内可用）
+    ngrok_token = os.getenv("NGROK_AUTH_TOKEN", "")
+    if ngrok_token:
+        try:
+            from pyngrok import ngrok, conf
+            conf.get_default().auth_token = ngrok_token
+            tunnel = ngrok.connect(7860, "http")
+            public_url = tunnel.public_url
+            print(f"\n{'='*60}")
+            print(f"  公网链接: {public_url}")
+            print(f"  任何人可以打开此链接使用 ResearchRadar")
+            print(f"{'='*60}\n")
+        except Exception as e:
+            print(f"  [WARN] ngrok 启动失败: {e}")
+            print(f"  降级为仅本地访问")
+
+    if not public_url:
+        print("\n  未配置公网隧道，仅本地访问: http://127.0.0.1:7860")
+        print("  如需公网访问，请设置 NGROK_AUTH_TOKEN 环境变量")
+        print("  免费获取 token: https://dashboard.ngrok.com/get-started/your-authtoken\n")
+
+    demo.launch(server_name="0.0.0.0", share=False, theme="soft", show_error=True)

direction_analyzer.py

@@ -0,0 +1,202 @@
+# direction_analyzer.py
+# ============================================================
+# 类型：AGENT（乙负责）
+# 功能：基于 GitHub 搜索结果 + 论文信息 → 归纳方法族谱系
+# 用法：python direction_analyzer.py（自测）
+# ============================================================
+from llm_utils import call_llm_json, parse_json_safe, validate_direction_output, fix_windows_encoding
+
+DIRECTION_SYSTEM_PROMPT = """你是一个 AI 研究领域的开源生态分析师。你的任务是：拿到一篇论文和 GitHub 上搜到的相关仓库列表，帮研究者理清——这些仓库分别属于什么方法族、哪些方法族有成熟开源实现、哪些还是空白。
+
+## 分析流程
+
+### 步骤 1：定位子领域
+- 结合论文内容和仓库描述，判断该论文属于哪个具体子领域
+- 不要笼统（如"深度学习"），要具体（如"工业图像异常检测"）
+- 说明该子领域在 2024-2025 年的主流趋势（1-2 句中文）
+
+### 步骤 2：归纳方法族
+- 浏览所有仓库的 description 和 topics，将同类方法的仓库归为一族
+- 每个方法族给出：名称、一句话核心特点、代表论文/项目
+- 输出 3-6 个方法族
+- 如果一个仓库明显不属于任何一族（如只是教程、论文列表），不要强行归类
+- 重要：方法族名称尽量使用英文（如"Patch Distribution Modeling"），便于后续搜索
+
+### 步骤 3：为每个方法族列出归属仓库
+- matched_repos 填该族包含的仓库 full_name 列表
+- 如果一个仓库可以属于多个族（如同时实现了方法A和方法B），选最匹配的那个
+
+### 步骤 4：生成精准搜索词
+- 为每个方法族生成 2-3 个 GitHub 搜索查询（英文）
+- 格式：方法名 + 技术关键词 + 限定词（implementation / pytorch / official / code）
+- 额外生成 3 个宽泛搜索词，用于查找未被当前搜索覆盖的方法族
+
+## 搜索查询质量要求
+- 好的查询："patch distribution modeling anomaly detection pytorch"
+- 坏的查询："anomaly"（太宽泛）
+- 坏的查询："a novel approach for industrial defect detection using deep learning"（太多废话）
+
+## 输出格式（严格 JSON，紧凑格式不要缩进和多余空格）
+{
+  "subfield": "具体子领域名称",
+  "subfield_trend": "该子领域 2024-2025 的主流趋势（1-2 句中文）",
+  "method_families": [
+    {
+      "family_name": "方法族简称",
+      "description": "一句话核心特点",
+      "representative_work": "代表论文或知名项目",
+      "matched_repos": ["owner/repo1", "owner/repo2"],
+      "search_queries": ["搜索词1", "搜索词2"]
+    }
+  ],
+  "broad_queries": ["宽泛搜索1", "宽泛搜索2", "宽泛搜索3"]
+}
+"""
+
+
+def analyze_direction(title: str, abstract: str, repos: list[dict] | None = None) -> dict:
+    """基于论文信息和 GitHub 搜索结果，归纳方法族谱系。
+
+    Args:
+        title: 论文标题
+        abstract: 论文摘要（会自动截断）
+        repos: GitHub 搜索结果列表，每个 dict 包含 full_name, description,
+               stars, language, topics, html_url。如果为 None 或空列表，
+               则仅基于 LLM 自身知识分析（降级模式）。
+
+    Returns:
+        dict: 包含 subfield, subfield_trend, method_families, broad_queries
+    """
+    abstract_truncated = abstract[:2000] if abstract else "（摘要不可用）"
+    title_clean = title.strip() if title else "（标题不可用）"
+
+    # 构建仓库列表文本
+    if repos:
+        repo_lines = []
+        for r in repos[:20]:  # 最多传 20 个仓库给 LLM
+            full_name = r.get("full_name", "")
+            desc = r.get("description", "")[:100]
+            stars = r.get("stars", 0)
+            topics = ", ".join(r.get("topics", [])[:5])
+            language = r.get("language", "")
+            repo_lines.append(
+                f"- **{full_name}** (⭐{stars}, {language}) — {desc}\n"
+                f"  topics: {topics}"
+            )
+        repos_text = "\n".join(repo_lines)
+    else:
+        repos_text = "（未提供 GitHub 搜索结果，请基于你的训练知识进行分析）"
+
+    user_prompt = f"""## 论文信息
+**标题**: {title_clean}
+
+**摘要**: {abstract_truncated}
+
+## GitHub 搜索结果（共 {len(repos) if repos else 0} 个仓库）
+
+{repos_text}
+
+请分析以上论文和仓库数据，归纳方法族谱系。"""
+
+    raw = call_llm_json(DIRECTION_SYSTEM_PROMPT, user_prompt, temperature=0.4, max_tokens=5000)
+    data = parse_json_safe(raw, "direction_analyzer")
+    return validate_direction_output(data)
+
+
+# ============================================================
+# 自测
+# ============================================================
+if __name__ == "__main__":
+    fix_windows_encoding()
+
+    # 构造模拟 GitHub 搜索结果
+    mock_repos = [
+        {
+            "full_name": "openvinotoolkit/anomalib",
+            "description": "An anomaly detection library comprising state-of-the-art algorithms.",
+            "stars": 4000, "language": "Python",
+            "topics": ["anomaly-detection", "pytorch", "benchmarking", "industrial-inspection"],
+            "html_url": "https://github.com/openvinotoolkit/anomalib",
+        },
+        {
+            "full_name": "hcw-00/PatchCore",
+            "description": "Official implementation of PatchCore: Towards Total Recall in Industrial Anomaly Detection.",
+            "stars": 850, "language": "Python",
+            "topics": ["anomaly-detection", "memory-bank", "pytorch"],
+            "html_url": "https://github.com/hcw-00/PatchCore",
+        },
+        {
+            "full_name": "taikiinoue45/STFPM",
+            "description": "Student-Teacher Feature Pyramid Matching for Anomaly Detection (PyTorch).",
+            "stars": 320, "language": "Python",
+            "topics": ["teacher-student", "anomaly-detection", "pytorch"],
+            "html_url": "https://github.com/taikiinoue45/STFPM",
+        },
+        {
+            "full_name": "VitjanZ/DRAEM",
+            "description": "DRAEM: Discriminatively trained reconstruction embedding for surface anomaly detection.",
+            "stars": 180, "language": "Python",
+            "topics": ["synthetic-defect", "anomaly-detection", "reconstruction"],
+            "html_url": "https://github.com/VitjanZ/DRAEM",
+        },
+        {
+            "full_name": "marugoto/CFLow",
+            "description": "CFLow: Real-time unsupervised anomaly detection via conditional normalizing flows.",
+            "stars": 130, "language": "Python",
+            "topics": ["normalizing-flow", "anomaly-detection", "pytorch"],
+            "html_url": "https://github.com/marugoto/CFLow",
+        },
+        {
+            "full_name": "xiahaifeng1995/PaDiM-Anomaly-Detection",
+            "description": "Unofficial implementation of PaDiM: Patch Distribution Modeling for anomaly detection.",
+            "stars": 150, "language": "Python",
+            "topics": ["padim", "anomaly-detection", "mvtec-ad"],
+            "html_url": "https://github.com/xiahaifeng1995/PaDiM-Anomaly-Detection",
+        },
+        {
+            "full_name": "someone/anomaly-detection-tutorial",
+            "description": "A tutorial collection of anomaly detection papers and resources.",
+            "stars": 45, "language": "Markdown",
+            "topics": ["awesome-list", "anomaly-detection"],
+            "html_url": "https://github.com/someone/anomaly-detection-tutorial",
+        },
+    ]
+
+    print("=" * 60)
+    print("Agent 1 测试：基于 GitHub 仓库的方法族归纳")
+    print("=" * 60)
+
+    result = analyze_direction(
+        "PaDiM: a Patch Distribution Modeling Framework for Anomaly Detection and Localization",
+        "We present a new framework for anomaly detection and localization based on "
+        "patch distribution modeling. PaDiM uses pretrained convolutional neural networks "
+        "to extract patch features and models their distribution using multivariate "
+        "Gaussian distributions.",
+        mock_repos,
+    )
+
+    print(f"子领域: {result.get('subfield')}")
+    print(f"趋势: {result.get('subfield_trend')}")
+    print(f"方法族数量: {len(result.get('method_families', []))}")
+    for mf in result.get("method_families", []):
+        repos_in_family = mf.get("matched_repos", [])
+        print(f"  - {mf.get('family_name')}: {mf.get('description')[:60]}...")
+        print(f"    归属仓库: {repos_in_family}")
+        print(f"    搜索词: {mf.get('search_queries', [])}")
+    print(f"宽泛搜索词: {result.get('broad_queries', [])}")
+    total_queries = sum(len(mf.get('search_queries', [])) for mf in result.get('method_families', [])) + len(result.get('broad_queries', []))
+    print(f"总搜索词数: {total_queries}")
+
+    print()
+    print("=" * 60)
+    print("Agent 1 测试：降级模式（无 GitHub 数据）")
+    print("=" * 60)
+
+    result2 = analyze_direction(
+        "Attention Is All You Need",
+        "The dominant sequence transduction models are based on complex recurrent "
+        "or convolutional neural networks...",
+        None,
+    )
+    print(f"子领域: {result2.get('subfield')}")
+    print(f"方法族: {[mf.get('family_name') for mf in result2.get('method_families', [])]}")

gradio_output.log

@@ -0,0 +1,8 @@
+Downloading ngrok ...
                                                                                                    
                                                                                                    
+============================================================
+  ��������: https://anvil-wackiness-hazing.ngrok-free.dev
+  �κ��˿��Դ򿪴�����ʹ�� ResearchRadar
+============================================================
+
+* Running on local URL:  http://0.0.0.0:7860
+* To create a public link, set `share=True` in `launch()`.

llm_utils.py

@@ -0,0 +1,263 @@
+# llm_utils.py
+# ============================================================
+# 类型：公共工具模块（乙负责）
+# 功能：OpenAI 客户端配置、JSON 安全解析、LLM 调用重试、输出校验
+# 被 direction_analyzer.py 和 repo_evaluator.py 共用
+# ============================================================
+
+import json
+import re
+import time
+import sys
+import os
+from openai import OpenAI
+
+# ---- 配置 ----
+DEEPSEEK_API_KEY = os.getenv("DEEPSEEK_API_KEY", "sk-a115c4388d444cf688d323855edb36da")
+DEEPSEEK_BASE_URL = "https://api.deepseek.com"
+MODEL = "deepseek-v4-pro"
+MAX_RETRIES = 3          # API 调用失败时最多重试次数
+RETRY_DELAY = 2.0        # 重试间隔（秒），指数增长
+
+_client = None
+
+
+def get_client() -> OpenAI:
+    """获取 OpenAI 客户端单例"""
+    global _client
+    if _client is None:
+        _client = OpenAI(api_key=DEEPSEEK_API_KEY, base_url=DEEPSEEK_BASE_URL)
+    return _client
+
+
+# ---- LLM 调用（带重试） ----
+
+def call_llm(
+    system_prompt: str,
+    user_prompt: str,
+    temperature: float = 0.3,
+    max_tokens: int = 2000,
+    response_format: dict | None = None,
+) -> str:
+    """调用 DeepSeek API，自动重试。
+
+    Args:
+        system_prompt: 系统提示词
+        user_prompt: 用户提示词
+        temperature: 温度参数
+        max_tokens: 最大输出 token 数
+        response_format: OpenAI 兼容的 response_format，如 {"type": "json_object"}
+
+    Returns:
+        LLM 返回的原始文本
+
+    Raises:
+        RuntimeError: 重试次数用尽后仍失败
+    """
+    client = get_client()
+    last_error = None
+
+    for attempt in range(MAX_RETRIES):
+        try:
+            kwargs = dict(
+                model=MODEL,
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": user_prompt},
+                ],
+                temperature=temperature,
+                max_tokens=max_tokens,
+                timeout=120.0,
+            )
+            if response_format is not None:
+                kwargs["response_format"] = response_format
+
+            response = client.chat.completions.create(**kwargs)
+            content = response.choices[0].message.content
+            if content is None or not content.strip():
+                raise ValueError("API 返回空内容")
+            return content.strip()
+        except Exception as e:
+            last_error = e
+            if attempt < MAX_RETRIES - 1:
+                wait = RETRY_DELAY * (2 ** attempt)
+                print(f"  [重试 {attempt+1}/{MAX_RETRIES}] API 调用失败: {e}，{wait:.0f}s 后重试...")
+                time.sleep(wait)
+
+    raise RuntimeError(f"LLM API 调用失败（已重试 {MAX_RETRIES} 次）: {last_error}")
+
+
+def call_llm_json(
+    system_prompt: str,
+    user_prompt: str,
+    temperature: float = 0.3,
+    max_tokens: int = 2000,
+) -> str:
+    """调用 DeepSeek API 并强制 JSON 输出模式。
+
+    这是 call_llm 的便捷封装，自动设置 response_format={"type": "json_object"}。
+    DeepSeek API 在 JSON 模式下会约束输出为合法 JSON，大幅减少格式偏差。
+    """
+    return call_llm(
+        system_prompt=system_prompt,
+        user_prompt=user_prompt,
+        temperature=temperature,
+        max_tokens=max_tokens,
+        response_format={"type": "json_object"},
+    )
+
+
+# ---- JSON 安全解析 ----
+
+def parse_json_safe(raw: str, module_name: str = "") -> dict:
+    """安全解析 LLM 返回的 JSON，7 种策略依次尝试。
+
+    LLM 可能返回：
+    1. 纯 JSON
+    2. ```json ... ``` 代码块包裹
+    3. ``` ... ``` 无语言标记包裹
+    4. 带前缀文字 + JSON
+    5. 带后缀文字 + JSON
+    6. 多行中夹杂 JSON 对象
+    7. 含未转义控制字符的 JSON
+    """
+    # 全局预处理：替换未转义的控制字符（换行、制表符）
+    # JSON 字符串内不允许这些字符，替换为空格不会影响合法的 JSON 结构
+    raw = raw.replace('\r\n', ' ').replace('\n', ' ').replace('\r', ' ').replace('\t', ' ')
+
+    strategies_tried = []
+
+    # 策略 1：直接解析
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as e:
+        strategies_tried.append(f"直接解析: {e}")
+
+    # 策略 2：提取 ```json ... ``` 代码块
+    match = re.search(r'```json\s*([\s\S]*?)```', raw)
+    if match:
+        try:
+            return json.loads(match.group(1).strip())
+        except json.JSONDecodeError:
+            pass
+
+    # 策略 3：提取 ``` ... ``` 任意代码块
+    match = re.search(r'```\s*([\s\S]*?)```', raw)
+    if match:
+        try:
+            return json.loads(match.group(1).strip())
+        except json.JSONDecodeError:
+            pass
+
+    # 策略 4：提取最外层 { ... }
+    match = re.search(r'\{[\s\S]*\}', raw)
+    if match:
+        try:
+            return json.loads(match.group(0))
+        except json.JSONDecodeError:
+            pass
+
+    # 策略 5：修复常见 JSON 错误（尾部逗号、单引号）
+    cleaned = raw.strip()
+    cleaned = re.sub(r',\s*}', '}', cleaned)    # 移除尾部逗号
+    cleaned = re.sub(r',\s*]', ']', cleaned)    # 移除数组尾部逗号
+    try:
+        return json.loads(cleaned)
+    except json.JSONDecodeError:
+        pass
+
+    # 策略 6：尝试找包含 "subfield" 或 "score" 的 { ... }
+    for keyword in ["subfield", "overall_score", "score"]:
+        pattern = r'\{[^{}]*"' + keyword + r'"[^{}]*\{[^{}]*\}[^{}]*\}|\{[^{}]*"' + keyword + r'"[^{}]*\}'
+        match = re.search(pattern, raw)
+        if match:
+            try:
+                return json.loads(match.group(0))
+            except json.JSONDecodeError:
+                pass
+
+    # 全部失败
+    module_tag = f"[{module_name}] " if module_name else ""
+    raise ValueError(
+        f"{module_tag}无法解析 LLM 返回的 JSON。\n"
+        f"原始返回（前 500 字符）:\n{raw[:500]}"
+    )
+
+
+# ---- 输出校验 ----
+
+def validate_direction_output(data: dict) -> dict:
+    """校验 direction_analyzer 的输出，填充缺失字段为默认值。"""
+    if not isinstance(data, dict):
+        raise ValueError(f"direction_analyzer 输出不是 dict，而是 {type(data).__name__}")
+
+    # 确保 method_families 是 list
+    families = data.get("method_families", [])
+    if not isinstance(families, list):
+        families = []
+
+    # 校验每个方法族
+    validated_families = []
+    for mf in families:
+        if not isinstance(mf, dict):
+            continue
+        validated_families.append({
+            "family_name": mf.get("family_name", "未命名方法族"),
+            "description": mf.get("description", ""),
+            "representative_work": mf.get("representative_work", ""),
+            "search_queries": mf.get("search_queries", []) if isinstance(mf.get("search_queries"), list) else [],
+            "matched_repos": mf.get("matched_repos", []) if isinstance(mf.get("matched_repos"), list) else [],
+        })
+
+    # 确保 broad_queries 是 list
+    broad_queries = data.get("broad_queries", [])
+    if not isinstance(broad_queries, list):
+        broad_queries = []
+
+    return {
+        "subfield": data.get("subfield", "未知子领域"),
+        "subfield_trend": data.get("subfield_trend", "暂无趋势分析"),
+        "method_families": validated_families,
+        "broad_queries": broad_queries,
+    }
+
+
+def validate_eval_output(data: dict) -> dict:
+    """校验 repo_evaluator 的输出，填充缺失字段为默认值。"""
+    if not isinstance(data, dict):
+        raise ValueError(f"repo_evaluator 输出不是 dict，而是 {type(data).__name__}")
+
+    # 数值字段默认 0
+    int_fields = [
+        "reproducibility_score", "benchmark_fitness_score", "overall_score",
+        "env_score", "doc_score", "code_score", "community_score", "dep_score",
+        "benchmark_score",
+    ]
+    for field in int_fields:
+        if field not in data or not isinstance(data[field], (int, float)):
+            data[field] = 0
+        else:
+            data[field] = int(data[field])
+
+    # 字符串字段
+    data.setdefault("verdict", "error")
+    data.setdefault("reasoning", "评估未返回分析")
+    data.setdefault("benchmark_readiness", "not_ready")
+    data.setdefault("suggested_use", "请手动评估该仓库")
+
+    # 列表字段
+    if "risks" not in data or not isinstance(data["risks"], list):
+        data["risks"] = []
+
+    return data
+
+
+# ---- Windows 终端编码 ----
+
+def fix_windows_encoding():
+    """修复 Windows 终端中文显示乱码问题"""
+    if sys.platform == "win32":
+        try:
+            sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+        except Exception:
+            pass

paper_fetcher.py

@@ -0,0 +1,113 @@
+import urllib.request
+import urllib.error
+import xml.etree.ElementTree as ET
+import re
+import time
+
+
+def extract_arxiv_id(url: str) -> str:
+    """从 arxiv URL 提取论文 ID
+
+    支持格式:
+    - https://arxiv.org/abs/1706.03762
+    - https://arxiv.org/abs/1706.03762v2
+    - https://arxiv.org/pdf/1706.03762.pdf
+    - arxiv:1706.03762
+    - 1706.03762
+    """
+    match = re.search(r'arxiv\.org/(?:abs|pdf)/(\d{4}\.\d{4,5})(?:v\d+)?(?:\.pdf)?', url)
+    if match:
+        return match.group(1)
+    match = re.search(r'(?:arxiv:)?(\d{4}\.\d{4,5})', url)
+    if match:
+        return match.group(1)
+    raise ValueError(f"无法从 URL 提取 arxiv ID: {url}")
+
+
+def fetch_paper_info(arxiv_url: str) -> dict:
+    """从 arxiv 获取论文元信息
+
+    Returns:
+        dict: {
+            "arxiv_id": str, "title": str, "abstract": str,
+            "authors": [str, ...], "categories": [str, ...], "published": str
+        }
+    """
+    arxiv_id = extract_arxiv_id(arxiv_url)
+    api_url = f"http://export.arxiv.org/api/query?id_list={arxiv_id}&max_results=1"
+
+    req = urllib.request.Request(api_url, headers={"User-Agent": "ResearchRadar/1.0"})
+
+    last_error = None
+    for attempt in range(3):
+        try:
+            with urllib.request.urlopen(req, timeout=30) as resp:
+                xml_text = resp.read().decode("utf-8")
+            break
+        except urllib.error.HTTPError as e:
+            last_error = e
+            if e.code in (429, 503) and attempt < 2:
+                wait = 5 * (2 ** attempt)
+                print(f"  arxiv API 限速，{wait}s 后重试...")
+                time.sleep(wait)
+                continue
+            raise RuntimeError(f"arxiv API 请求失败 (HTTP {e.code})，请检查论文 ID 是否正确")
+        except urllib.error.URLError as e:
+            last_error = e
+            if attempt < 2:
+                wait = 3 * (2 ** attempt)
+                print(f"  网络错误，{wait}s 后重试: {e.reason}")
+                time.sleep(wait)
+                continue
+            raise RuntimeError(f"无法连接 arxiv API，请检查网络: {e.reason}")
+    else:
+        raise RuntimeError(f"arxiv API 请求失败 (HTTP {getattr(last_error, 'code', '?')})，重试 3 次仍失败")
+
+    root = ET.fromstring(xml_text)
+    ns = {
+        "atom": "http://www.w3.org/2005/Atom",
+        "arxiv": "http://arxiv.org/schemas/atom",
+    }
+
+    entry = root.find("atom:entry", ns)
+    if entry is None:
+        raise ValueError(f"arxiv 未找到论文 {arxiv_id}，请检查 ID 是否正确")
+
+    title_el = entry.find("atom:title", ns)
+    summary_el = entry.find("atom:summary", ns)
+    title = title_el.text.strip().replace("\n", " ") if title_el is not None and title_el.text else ""
+    abstract = summary_el.text.strip().replace("\n", " ") if summary_el is not None and summary_el.text else ""
+
+    authors = [
+        a.find("atom:name", ns).text
+        for a in entry.findall("atom:author", ns)
+        if a.find("atom:name", ns) is not None
+    ]
+    categories = [
+        c.get("term", "") for c in entry.findall("atom:category", ns)
+    ]
+    published_el = entry.find("atom:published", ns)
+    published = published_el.text if published_el is not None and published_el.text else ""
+
+    return {
+        "arxiv_id": arxiv_id,
+        "title": title,
+        "abstract": abstract,
+        "authors": authors,
+        "categories": categories,
+        "published": published,
+    }
+
+
+if __name__ == "__main__":
+    # 自测：用 PaDiM 论文测试
+    test_url = "https://arxiv.org/abs/2011.08785"
+    paper = fetch_paper_info(test_url)
+    print("=== paper_fetcher 自测 ===")
+    for k, v in paper.items():
+        val = str(v)
+        if len(val) > 120:
+            val = val[:120] + "..."
+        print(f"  {k}: {val}")
+    print("  所有必需字段:",
+          all(k in paper for k in ["arxiv_id", "title", "abstract", "authors"]))

repo_evaluator.py

@@ -0,0 +1,268 @@
+# repo_evaluator.py
+# ============================================================
+# 类型：AGENT（乙负责）
+# 功能：LLM 六维度评分（可复现性 5 维 + 对比实验适配度 1 维）
+# 用法：python repo_evaluator.py（自测）
+# ============================================================
+from llm_utils import call_llm_json, parse_json_safe, validate_eval_output, fix_windows_encoding
+
+EVAL_SYSTEM_PROMPT = """你是一个 AI 论文代码评估专家。你需要同时评估一个 GitHub 仓库的两个方面：
+- **可复现性**：这个仓库的代码能不能被他人成功跑通？
+- **对比实验适配度**：这个仓库适不适合直接拿来写论文做对比实验（baseline / comparison）？
+
+## 评估框架（六维度，总分 100）
+
+### 可复现性（五维度，合计 80 分）
+
+1. **环境配置完整性（0-15 分）**
+   - 15 分：提供了 requirements.txt / environment.yml，所有依赖版本号明确
+   - 8-14 分：有依赖文件但部分版本号使用范围（>=, ~=）或缺失
+   - 0-7 分：没有依赖文件或严重不完整
+
+2. **文档质量（0-20 分）**
+   - 16-20 分：有清晰的安装步骤、训练命令、推理命令、数据集获取方式
+   - 8-15 分：有基本说明但关键步骤缺失（如没说数据集在哪下载）
+   - 0-7 分：README 只有项目简介，没有可执行命令
+
+3. **代码可用性（0-20 分）**
+   - 16-20 分：训练脚本 + 推理脚本 + 配置文件 + 模型定义入口完整
+   - 8-15 分：有核心代码但缺少关键组件（如只有推理没有训练）
+   - 0-7 分：代码残缺，只有骨架或 shell 脚本
+
+4. **社区活跃度（0-10 分）**
+   - 8-10 分：Star > 500，最近半年有 commit，Issue 有人回复
+   - 4-7 分：有一定关注度但更新不频繁
+   - 0-3 分：长期不更新，Star < 10
+
+5. **依赖健康度（0-15 分）**
+   - 12-15 分：依赖全是主流活跃包，版本相互兼容
+   - 6-11 分：有少量过时依赖但不影响安装
+   - 0-5 分：依赖涉及已停止维护的包（如 TensorFlow 1.x、Python 2），已知无法在现代环境安装
+
+### 对比实验适配度（一维度，20 分）
+
+6. **对比实验适配度（0-20 分）**
+   - 16-20 分：提供标准 benchmark 评估脚本 + 预训练权重下载 + 公开数据集支持，可直接跑出论文常用指标，可以无缝插入论文的 Experiment section
+   - 10-15 分：有训练脚本和评估代码，但需要自己准备数据或适配数据集格式
+   - 0-9 分：只有推理 demo、使用私有数据集、没有标准化评估流程、或没有预训练权重
+
+## Few-Shot 评分锚定示例
+
+### 示例 1：高质量仓库（如 anomalib）
+- 仓库: openvinotoolkit/anomalib, 4000 Stars, 2026年更新
+- README 含详细安装步骤、训练命令、数据集列表
+- 依赖: requirements.txt 含 torch>=1.10, pytorch-lightning>=1.7, opencv-python
+- 有标准化 benchmark 脚本 tools/benchmark.py，支持 MVTec AD 等标准数据集
+
+正确评分 JSON：
+{
+  "reproducibility_score": 75,
+  "benchmark_fitness_score": 18,
+  "overall_score": 93,
+  "verdict": "reproducible",
+  "env_score": 14,
+  "doc_score": 18,
+  "code_score": 18,
+  "community_score": 10,
+  "dep_score": 15,
+  "benchmark_score": 18,
+  "reasoning": "该仓库类似anomalib级别：文档完善有安装/训练/数据说明，依赖文件完整且使用主流活跃包，社区活跃（4000+ Stars），提供标准化benchmark脚本和预训练权重，可直接跑出论文常用指标。可复现性高（安装到训练流程清晰），适配度高（benchmark可直接用于对比实验）。",
+  "risks": ["部分依赖版本号使用>=范围，可能存在breaking change风险"],
+  "benchmark_readiness": "ready",
+  "suggested_use": "可以直接作为对比实验 baseline"
+}
+
+### 示例 2：低质量仓库（仅推理 demo）
+- 仓库: someone/anomaly-demo, 15 Stars, 2024年更新
+- README 只有: "A simple demo. python demo.py --image path/to/image.jpg. Pretrained weights: Google Drive link"
+- 无依赖文件
+- 仅有推理脚本，无训练代码、无评估脚本
+
+正确评分 JSON：
+{
+  "reproducibility_score": 15,
+  "benchmark_fitness_score": 3,
+  "overall_score": 18,
+  "verdict": "not_reproducible",
+  "env_score": 2,
+  "doc_score": 4,
+  "code_score": 4,
+  "community_score": 2,
+  "dep_score": 3,
+  "benchmark_score": 3,
+  "reasoning": "可复现性极低：无依赖文件无法复现环境，文档仅有单行命令，预训练权重链接可能失效。适配度极低：仅有推理demo，无训练脚本，无标准评估流程，无法直接用于对比实验。",
+  "risks": ["无依赖文件", "预训练权重来自Google Drive链接可能失效", "无训练代码"],
+  "benchmark_readiness": "not_ready",
+  "suggested_use": "仅适合参考代码实现，不适合直接跑对比实验"
+}
+
+## 重要提醒
+- 可复现性和适配度是两个独立的维度，必须分开判断
+- 例如：一个仓库可以 README 很��善（文档 20 分）但只提供推理 demo 没有训练（适配度 5 分）
+- 又如：anomalib 在可复现性（文档好、有 requirements.txt）和适配度（有 benchmark 脚本、有预训练权重）都很高
+
+## 输出格式（严格 JSON，紧凑格式不要缩进和多余空格）
+{
+  "reproducibility_score": 80,
+  "benchmark_fitness_score": 20,
+  "overall_score": 100,
+  "verdict": "reproducible",
+  "env_score": 15,
+  "doc_score": 20,
+  "code_score": 20,
+  "community_score": 10,
+  "dep_score": 15,
+  "benchmark_score": 20,
+  "reasoning": "200字以内的中文分析，必须区分'能不能跑'和'适不适合跑对比实验'两个层面",
+  "risks": ["风险1", "风险2"],
+  "benchmark_readiness": "ready",
+  "suggested_use": "可以直接作为对比实验 baseline"
+}
+
+## 判定规则
+- overall_score >= 70 → verdict = "reproducible"
+- 40 <= overall_score < 70 → verdict = "partially"
+- overall_score < 40 → verdict = "not_reproducible"
+
+- benchmark_score >= 16 → benchmark_readiness = "ready"
+- 10 <= benchmark_score < 16 → benchmark_readiness = "partial"
+- benchmark_score < 10 → benchmark_readiness = "not_ready"
+
+## benchmark_readiness 与 suggested_use 的对应关系
+- "ready" → "可以直接作为对比实验 baseline"
+- "partial" → "需要少量修改后可用于对比实验"
+- "not_ready" → "仅适合参考代码实现，不适合直接跑对比实验"
+"""
+
+
+def evaluate_repo(
+    repo: dict,
+    readme: str | None,
+    dependencies: dict[str, str],
+    method_family: str = "",
+) -> dict:
+    """评估单个仓库的可复现性和对比实验适配度。
+
+    Args:
+        repo: 仓库元信息 dict，包含 full_name, html_url, stars 等
+        readme: README 文件全文（或 None）
+        dependencies: {文件名: 文件内容} 的 dict
+        method_family: 该仓库所属的方法族名称（空字符串表示未归类）
+
+    Returns:
+        dict: 六维度评分结果
+    """
+    readme_text = (readme or "README 未找到")[:2500]
+
+    if dependencies:
+        deps_parts = []
+        for fname, content in dependencies.items():
+            truncated = content[:1000] if content else "(空文件)"
+            deps_parts.append(f"### {fname}\n```\n{truncated}\n```")
+        deps_text = "\n\n".join(deps_parts)
+    else:
+        deps_text = "未找到任何依赖文件（requirements.txt / environment.yml 等）"
+
+    family_hint = f"\n- 方法族: {method_family}" if method_family else ""
+
+    user_prompt = f"""## 仓库基本信息
+- 名称: {repo.get('full_name', '未知')}
+- URL: {repo.get('html_url', '')}
+- Stars: {repo.get('stars', 0)}
+- 描述: {repo.get('description', '无描述')}
+- 最后更新: {repo.get('updated_at', '未知')}
+- 主要语言: {repo.get('language', '未知')}{family_hint}
+
+## README 内容
+{readme_text}
+
+## 依赖文件
+{deps_text}
+
+请评估该仓库的可复现性和对比实验适配度。"""
+
+    raw = call_llm_json(EVAL_SYSTEM_PROMPT, user_prompt, temperature=0.3, max_tokens=4000)
+    data = parse_json_safe(raw, "repo_evaluator")
+    return validate_eval_output(data)
+
+
+# ============================================================
+# 自测
+# ============================================================
+if __name__ == "__main__":
+    fix_windows_encoding()
+
+    # 测试 1：anomalib（工业缺陷检测明星项目，预期高分）
+    print("=" * 60)
+    print("测试 1：OpenVINO anomalib（预期：可复现性高 + 适配度高）")
+    print("=" * 60)
+    mock_repo = {
+        "full_name": "openvinotoolkit/anomalib",
+        "html_url": "https://github.com/openvinotoolkit/anomalib",
+        "stars": 4000,
+        "description": "An anomaly detection library comprising state-of-the-art algorithms and features such as experiment management, hyper-parameter optimization, and edge inference.",
+        "updated_at": "2026-01-15T00:00:00Z",
+        "language": "Python",
+    }
+    mock_readme = """# Anomalib
+A library for benchmarking, developing and deploying deep learning based anomaly detection algorithms.
+
+## Installation
+```
+pip install anomalib
+```
+
+## Training
+```python
+from anomalib.engine import Engine
+engine = Engine()
+engine.train()
+```
+
+## Supported Datasets
+- MVTec AD
+- BTAD
+- KSDD2
+
+## Benchmarking
+Use `tools/benchmark.py` for standardized evaluation across all models.
+"""
+    mock_deps = {"requirements.txt": "torch>=1.10\npytorch-lightning>=1.7\nopencv-python\nnumpy\nscikit-learn"}
+    result = evaluate_repo(mock_repo, mock_readme, mock_deps, "Embedding-based")
+    print(f"  综合: {result.get('overall_score')}/100")
+    print(f"  可复现性: {result.get('reproducibility_score')}/80")
+    print(f"  适配度: {result.get('benchmark_fitness_score')}/20")
+    print(f"  判定: {result.get('verdict')} | 实验就绪: {result.get('benchmark_readiness')}")
+    print(f"  分析: {result.get('reasoning')}")
+
+    print()
+
+    # 测试 2：只有推理 demo 的个人项目（预期低适配度）
+    print("=" * 60)
+    print("测试 2：仅推理的个人项目（预期：可复现性中等 + 适配度低）")
+    print("=" * 60)
+    mock_repo2 = {
+        "full_name": "someone/anomaly-detection-demo",
+        "html_url": "https://github.com/someone/anomaly-detection-demo",
+        "stars": 15,
+        "description": "A simple demo of anomaly detection using pretrained models.",
+        "updated_at": "2024-03-01T00:00:00Z",
+        "language": "Python",
+    }
+    mock_readme2 = """# Anomaly Detection Demo
+A simple inference demo.
+
+## Usage
+```
+python demo.py --image path/to/image.jpg
+```
+
+Pretrained weights: download from Google Drive (link may expire).
+"""
+    mock_deps2 = {}
+    result2 = evaluate_repo(mock_repo2, mock_readme2, mock_deps2, "Embedding-based")
+    print(f"  综合: {result2.get('overall_score')}/100")
+    print(f"  可复现性: {result2.get('reproducibility_score')}/80")
+    print(f"  适配度: {result2.get('benchmark_fitness_score')}/20")
+    print(f"  判定: {result2.get('verdict')} | 实验就绪: {result2.get('benchmark_readiness')}")
+    print(f"  建议: {result2.get('suggested_use')}")

repo_fetcher.py

@@ -0,0 +1,89 @@
+import os
+import base64
+import requests
+
+API_BASE = "https://api.github.com"
+
+DEPENDENCY_FILENAMES = [
+    "requirements.txt", "environment.yml", "environment.yaml",
+    "setup.py", "setup.cfg", "pyproject.toml",
+    "Pipfile", "Pipfile.lock", "Dockerfile", "Makefile", "CMakeLists.txt",
+]
+
+
+def _get_headers():
+    token = os.getenv("GITHUB_TOKEN", "")
+    headers = {"Accept": "application/vnd.github.v3+json"}
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    return headers
+
+
+def _github_get(path: str) -> dict | None:
+    """统一的 GitHub API GET 请求，失败返回 None"""
+    headers = _get_headers()
+    url = f"{API_BASE}{path}"
+    try:
+        resp = requests.get(url, headers=headers, timeout=15)
+        if resp.status_code == 404:
+            return None
+        if resp.status_code in (403, 429):
+            print(f"[警告] GitHub API 限速: {path}")
+            return None
+        resp.raise_for_status()
+        return resp.json()
+    except Exception as e:
+        print(f"[警告] GitHub API 请求失败 ({path}): {e}")
+        return None
+
+
+def fetch_readme(owner: str, name: str) -> str | None:
+    """获取仓库 README 文件内容"""
+    try:
+        data = _github_get(f"/repos/{owner}/{name}/readme")
+        if not data:
+            return None
+        content = data.get("content", "")
+        return base64.b64decode(content).decode("utf-8", errors="replace")
+    except Exception:
+        return None
+
+
+def fetch_dependencies(owner: str, name: str) -> dict[str, str]:
+    """获取仓库的依赖文件
+
+    Returns:
+        dict: {文件名: 文件内容}，找不到任何依赖文件时返回 {}
+    """
+    result = {}
+    try:
+        contents = _github_get(f"/repos/{owner}/{name}/contents") or []
+        for item in contents:
+            fname = item.get("name", "")
+            if fname in DEPENDENCY_FILENAMES:
+                file_data = _github_get(f"/repos/{owner}/{name}/contents/{fname}")
+                if file_data and file_data.get("content"):
+                    try:
+                        decoded = base64.b64decode(file_data["content"]).decode("utf-8", errors="replace")
+                        result[fname] = decoded
+                    except Exception:
+                        pass
+    except Exception:
+        pass
+    return result
+
+
+if __name__ == "__main__":
+    # 自测：对 anomalib 仓库调用
+    owner, name = "openvinotoolkit", "anomalib"
+    print("=== repo_fetcher 自测 ===")
+
+    readme = fetch_readme(owner, name)
+    print(f"README 长度: {len(readme) if readme else 0} 字符")
+    if readme:
+        print(f"  前 200 字符: {readme[:200]}...")
+
+    deps = fetch_dependencies(owner, name)
+    print(f"依赖文件: {len(deps)} 个 — {list(deps.keys())}")
+    for fname, content in deps.items():
+        print(f"  {fname}: {len(content)} 字符")

repo_searcher.py

@@ -0,0 +1,69 @@
+import requests
+import os
+
+
+def search_repos(queries: list[str], max_per_keyword: int = 5) -> list[dict]:
+    """在 GitHub 搜索仓库
+
+    Args:
+        queries: 搜索查询字符串列表
+        max_per_keyword: 每个查询最多保留的仓库数
+
+    Returns:
+        list[dict]: 已去重（按 full_name）、按 stars 降序排列的候选仓库列表。
+        每个 dict 包含: full_name, html_url, description, stars,
+        language, updated_at, topics, match_keyword
+    """
+    token = os.getenv("GITHUB_TOKEN", "")
+    headers = {"Accept": "application/vnd.github.v3+json"}
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+
+    seen = set()
+    results = []
+
+    for kw in queries:
+        query = f"{kw} language:python stars:>=5"
+        url = "https://api.github.com/search/repositories"
+        params = {"q": query, "sort": "stars", "order": "desc", "per_page": max_per_keyword}
+
+        try:
+            resp = requests.get(url, headers=headers, params=params, timeout=15)
+            if resp.status_code == 403 and "rate limit" in resp.text.lower():
+                print(f"[警告] GitHub 搜索限速，跳过关键词: {kw}")
+                continue
+            resp.raise_for_status()
+            data = resp.json()
+        except Exception as e:
+            print(f"[警告] 搜索关键词 '{kw}' 失败: {e}")
+            continue
+
+        for item in data.get("items", []):
+            full_name = item["full_name"]
+            if full_name not in seen:
+                seen.add(full_name)
+                results.append({
+                    "full_name": full_name,
+                    "html_url": item["html_url"],
+                    "description": item.get("description", ""),
+                    "stars": item.get("stargazers_count", 0),
+                    "language": item.get("language", ""),
+                    "updated_at": item.get("updated_at", ""),
+                    "topics": item.get("topics", []),
+                    "match_keyword": kw,
+                })
+
+    results.sort(key=lambda r: r["stars"], reverse=True)
+    return results
+
+
+if __name__ == "__main__":
+    # 自测：用几个搜索词调用
+    test_queries = [
+        "padim anomaly detection pytorch",
+        "patch distribution modeling anomaly detection",
+    ]
+    repos = search_repos(test_queries, max_per_keyword=3)
+    print(f"=== repo_searcher 自测 ===\n找到 {len(repos)} 个仓库:")
+    for r in repos:
+        print(f"  {r['full_name']}  ⭐{r['stars']}  —  {r.get('match_keyword', '?')}")

requirements.txt

@@ -0,0 +1,3 @@
+gradio>=6.0
+openai>=2.0
+requests>=2.30

run.py

@@ -0,0 +1,489 @@
+# run.py
+# ============================================================
+# 类型：调度器（乙负责）
+# 功能：按"先搜再分析"流程串联 Workflow（甲）和 Agent（乙）
+# 用法：python run.py <arxiv_url>
+# 示例：python run.py https://arxiv.org/abs/2011.08785
+# ============================================================
+import sys
+import time
+import re
+import os
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+# 自动加载 .env 文件
+_ENV_PATH = os.path.join(os.path.dirname(os.path.abspath(__file__)), ".env")
+if os.path.isfile(_ENV_PATH):
+    with open(_ENV_PATH, "r", encoding="utf-8") as _f:
+        for _line in _f:
+            _line = _line.strip()
+            if _line and not _line.startswith("#") and "=" in _line:
+                _key, _val = _line.split("=", 1)
+                if _key not in os.environ:
+                    os.environ[_key] = _val.strip().strip('"').strip("'")
+
+# ---- 导入甲的 Workflow 模块 ----
+try:
+    from paper_fetcher import fetch_paper_info
+except ImportError as e:
+    raise ImportError(
+        f"缺少模块: paper_fetcher.py（甲负责），请等待甲交付。\n"
+        f"  原始错误: {e}"
+    ) from e
+
+try:
+    from repo_searcher import search_repos
+except ImportError as e:
+    raise ImportError(
+        f"缺少模块: repo_searcher.py（甲负责），请等待甲交付。\n"
+        f"  原始错误: {e}"
+    ) from e
+
+try:
+    from repo_fetcher import fetch_readme, fetch_dependencies
+except ImportError as e:
+    raise ImportError(
+        f"缺少模块: repo_fetcher.py（甲负责），请等待甲交付。\n"
+        f"  原始错误: {e}"
+    ) from e
+
+from direction_analyzer import analyze_direction
+from repo_evaluator import evaluate_repo
+from llm_utils import call_llm_json, parse_json_safe
+
+
+def run(arxiv_url: str, top_n: int = 5) -> dict:
+    """主入口：先搜索 GitHub → 再基于实际仓库归纳方法族 → 最后评估。
+
+    新流程（方案 B）：
+      第一层：论文信息获取 (Workflow)
+      第二层：宽泛 GitHub 搜索 (Workflow)
+      第三层：基于仓库数据归纳方法族 (Agent 1)  ← 不再是 LLM 凭记忆
+      第四层：仓库评估 (Agent 2)
+
+    Args:
+        arxiv_url: arxiv 论文 URL
+        top_n: 最终评估的仓库数量
+
+    Returns:
+        dict: {"paper": {...}, "direction": {...}, "repos": [{...}], "error": "..."}
+    """
+    t_start = time.time()
+
+    # ================================================================
+    # [1/5] 论文信息获取（甲 Workflow）
+    # ================================================================
+    print("=" * 60)
+    print("[1/5] 正在获取论文信息...")
+    t0 = time.time()
+    try:
+        paper = fetch_paper_info(arxiv_url)
+    except Exception as e:
+        return {"error": f"获取论文信息失败: {e}"}
+
+    title = paper.get("title", "")
+    abstract = paper.get("abstract", "")
+    print(f"  标题: {title[:100]}...")
+    print(f"  作者: {', '.join(paper.get('authors', [])[:3])}")
+    print(f"  分类: {', '.join(paper.get('categories', []))}")
+    print(f"  耗时: {time.time() - t0:.1f}s")
+
+    # ================================================================
+    # [2/5] 宽泛 GitHub 搜索（甲 Workflow）
+    # ================================================================
+    print()
+    print("[2/5] 正在宽泛搜索 GitHub（先搜仓库，再让 Agent 分析）...")
+    t0 = time.time()
+
+    broad_queries = _extract_broad_queries(title, abstract)
+    print(f"  生成 {len(broad_queries)} 个宽泛搜索词:")
+    for q in broad_queries:
+        print(f"    - {q}")
+
+    try:
+        broad_results = search_repos(broad_queries, max_per_keyword=5)
+    except Exception as e:
+        return {
+            "paper": paper,
+            "error": f"GitHub 搜索失败: {e}",
+        }
+
+    print(f"  去重后获得 {len(broad_results)} 个候选仓库")
+    print(f"  耗时: {time.time() - t0:.1f}s")
+
+    if not broad_results:
+        return {
+            "paper": paper,
+            "direction": {},
+            "repos": [],
+            "error": "未找到相关开源仓库。该方向可能太新或太冷门，暂无高质量开源实现。",
+        }
+
+    # ================================================================
+    # [2.5] LLM 过滤不相关仓库
+    # ================================================================
+    print()
+    print("[2.5] 正在用 LLM 过滤不相关仓库...")
+    t0 = time.time()
+    filtered_results = _filter_repos(title, abstract, broad_results)
+    print(f"  耗时: {time.time() - t0:.1f}s")
+
+    # ================================================================
+    # [3/5] 基于仓库数据归纳方法族（Agent 1）  ← 核心改动
+    # ================================================================
+    print()
+    print(f"[3/5] 正在分析 {len(filtered_results)} 个仓库，归纳方法族（Agent 1）...")
+    t0 = time.time()
+
+    try:
+        direction = analyze_direction(title, abstract, filtered_results)
+    except Exception as e:
+        return {
+            "paper": paper,
+            "error": f"研究方向解析失败: {e}",
+        }
+
+    subfield = direction.get("subfield", "未知")
+    families = direction.get("method_families", [])
+    print(f"  子领域: {subfield}")
+    print(f"  趋势: {direction.get('subfield_trend', '')[:80]}...")
+    print(f"  方法族 ({len(families)} 个):")
+    for mf in families:
+        matched = mf.get("matched_repos", [])
+        print(f"    - {mf.get('family_name', '?')}: {len(matched)} 个仓库 {matched}")
+    print(f"  耗时: {time.time() - t0:.1f}s")
+
+    # ================================================================
+    # [4/5] 筛选仓库 + 构建方法族归属映射
+    # ================================================================
+    print()
+    print(f"[4/5] 正在筛选并获取仓库详情...")
+    t0 = time.time()
+
+    # 从 Agent 1 的 matched_repos 中建立 full_name → family_name 映射
+    repo_family_map = {}
+    for mf in families:
+        family_name = mf.get("family_name", "")
+        for repo_name in mf.get("matched_repos", []):
+            repo_family_map[repo_name] = family_name
+
+    # 从 filtered_results 中筛选：优先选有方法族归属的，再按 stars 排序
+    classified = [r for r in filtered_results if r["full_name"] in repo_family_map]
+    unclassified = [r for r in filtered_results if r["full_name"] not in repo_family_map]
+    classified.sort(key=lambda r: r.get("stars", 0), reverse=True)
+    unclassified.sort(key=lambda r: r.get("stars", 0), reverse=True)
+
+    candidates = (classified + unclassified)[:top_n]
+
+    print(f"  有方法族归属: {len(classified)} 个，未归类: {len(unclassified)} 个")
+    print(f"  最终选取 {len(candidates)} 个仓库:")
+    for i, c in enumerate(candidates):
+        family = repo_family_map.get(c["full_name"], "未归类")
+        print(f"    {i+1}. {c['full_name']} [{family}] Stars:{c.get('stars', 0)}")
+    print(f"  耗时: {time.time() - t0:.1f}s")
+
+    # ================================================================
+    # [5/5] 仓库详情获取 + 评估（Agent 2，并行）
+    # ================================================================
+    print()
+    print(f"[5/5] 正在获取仓库详情并评估（Agent 2，{len(candidates)} 个仓库并行）...")
+    t0 = time.time()
+
+    def _eval_single(repo, idx, total):
+        """单个仓库评估（在线程中执行）"""
+        full_name = repo["full_name"]
+        try:
+            owner, name = full_name.split("/", 1)
+        except ValueError:
+            return idx, None
+
+        matched_family = repo_family_map.get(full_name, "")
+        family_tag = f"[{matched_family}]" if matched_family else "[未归类]"
+        print(f"  ({idx+1}/{total}) {full_name} {family_tag}...")
+
+        try:
+            readme = fetch_readme(owner, name)
+            deps = fetch_dependencies(owner, name)
+            evaluation = evaluate_repo(repo, readme, deps, matched_family)
+        except Exception as e:
+            print(f"    [WARN] {full_name} 评估失败: {e}")
+            evaluation = _make_error_evaluation(str(e))
+
+        return idx, {
+            "full_name": repo.get("full_name", ""),
+            "html_url": repo.get("html_url", ""),
+            "description": repo.get("description", ""),
+            "stars": repo.get("stars", 0),
+            "language": repo.get("language", ""),
+            "updated_at": repo.get("updated_at", ""),
+            "topics": repo.get("topics", []),
+            "match_keyword": repo.get("match_keyword", ""),
+            "method_family": matched_family,
+            "evaluation": evaluation,
+        }
+
+    n = len(candidates)
+    evaluated = [None] * n
+    with ThreadPoolExecutor(max_workers=min(n, 5)) as executor:
+        futures = {
+            executor.submit(_eval_single, repo, i, n): i
+            for i, repo in enumerate(candidates)
+        }
+        for future in as_completed(futures):
+            idx, result = future.result()
+            if result is not None:
+                evaluated[idx] = result
+
+    evaluated = [r for r in evaluated if r is not None]
+
+    # 按综合评分降序排列
+    evaluated.sort(key=lambda r: r["evaluation"].get("overall_score", 0), reverse=True)
+    print(f"  耗时: {time.time() - t0:.1f}s")
+
+    # ================================================================
+    # 汇总
+    # ================================================================
+    print()
+    print("=" * 60)
+    print("完成！")
+    best = evaluated[0] if evaluated else None
+    if best:
+        print(f"  最高分: {best['full_name']} ({best['evaluation'].get('overall_score', 0)}/100)")
+    print(f"  总耗时: {time.time() - t_start:.1f}s")
+    print("=" * 60)
+
+    return {
+        "paper": paper,
+        "direction": direction,
+        "repos": evaluated,
+    }
+
+
+def _extract_broad_queries(title: str, abstract: str) -> list[str]:
+    """用 LLM 从论文标题和摘要中生成 GitHub 搜索关键词。
+
+    相比规则提取，LLM 理解论文后能生成更精准的领域搜索词。
+    如果 LLM 调用失败，降级为规则提取。
+    """
+    system_prompt = """你是学术论文搜索专家。根据论文标题和摘要，生成 6-8 个 GitHub 搜索查询，用于找到该研究方向的开源实现。
+
+要求：
+- 查询必须是英文，用空格分隔关键词
+- 包含方法名/技术关键词 + 限定词（implementation / pytorch / code）
+- 包含 1-2 个宽泛的领域查询（如 "anomaly detection pytorch library"）
+- 不要用引号或特殊符号
+- 避免太泛的词（如单一个 "anomaly"）
+
+输出严格 JSON：
+{"queries": ["query1", "query2", ...]}"""
+
+    user_prompt = f"""论文标题: {title[:300]}
+摘要: {abstract[:800]}
+
+请为该论文生成 GitHub 搜索查询。"""
+
+    try:
+        raw = call_llm_json(system_prompt, user_prompt, temperature=0.3, max_tokens=500)
+        data = parse_json_safe(raw, "broad_queries")
+        queries = data.get("queries", [])
+        if isinstance(queries, list) and len(queries) >= 3:
+            return queries[:10]
+    except Exception as e:
+        print(f"  [WARN] LLM 关键词生成失败，降级为规则提取: {e}")
+
+    return _extract_broad_queries_fallback(title, abstract)
+
+
+def _extract_broad_queries_fallback(title: str, abstract: str) -> list[str]:
+    """从论文标题和摘要中提取宽泛搜索关键词（规则降级版）。
+
+    策略：提取有意义的词组 + 搜索限定词，按多样性采样（不偏向标题前缀）。
+    不依赖 LLM，纯规则提取。
+    """
+    abstract_first = abstract.split(".")[0] if abstract else ""
+    text = f"{title} {abstract_first}".lower()
+    text = re.sub(r'[^\w\s-]', ' ', text)
+    words = text.split()
+
+    stop_words = {
+        'a', 'an', 'the', 'of', 'for', 'in', 'on', 'to', 'and', 'or', 'is', 'are',
+        'we', 'our', 'that', 'this', 'with', 'from', 'by', 'as', 'at', 'be', 'it',
+        'its', 'not', 'can', 'has', 'have', 'been', 'was', 'were', 'will', 'would',
+        'could', 'should', 'may', 'do', 'does', 'did', 'so', 'if', 'no', 'new',
+        'based', 'using', 'which', 'into', 'such', 'than', 'then', 'these', 'those',
+        'propose', 'present', 'method', 'approach', 'framework', 'novel', 'model',
+        'learning', 'deep', 'via', 'et', 'al', 'all', 'we', 'you', 'they',
+    }
+
+    meaningful = [w for w in words if w not in stop_words and len(w) > 1]
+
+    bigrams = [f"{meaningful[i]} {meaningful[i+1]}" for i in range(len(meaningful) - 1)]
+    trigrams = [f"{meaningful[i]} {meaningful[i+1]} {meaningful[i+2]}" for i in range(len(meaningful) - 2)]
+
+    def _sample_diverse(items: list[str], n: int) -> list[str]:
+        if len(items) <= n:
+            return items
+        step = max(1, len(items) // n)
+        return [items[i] for i in range(0, len(items), step)][:n]
+
+    phrases = _sample_diverse(trigrams, 3) + _sample_diverse(bigrams, 4)
+
+    seen = set()
+    unique_phrases = []
+    for p in sorted(phrases, key=len, reverse=True):
+        if p not in seen:
+            seen.add(p)
+            unique_phrases.append(p)
+
+    qualifiers = [
+        "implementation pytorch",
+        "official code",
+        "pytorch github",
+    ]
+
+    queries = []
+    for phrase in unique_phrases[:5]:
+        if len(phrase) > 5:
+            queries.append(f"{phrase} {qualifiers[0]}")
+
+    mid = len(meaningful) // 2
+    broad = " ".join(meaningful[max(0, mid-2):mid+2])
+    if len(broad) > 10:
+        queries.append(f"{broad} {qualifiers[2]}")
+
+    seen = set()
+    unique = []
+    for q in queries:
+        if q not in seen:
+            seen.add(q)
+            unique.append(q)
+
+    return unique[:10]
+
+
+def _filter_repos(title: str, abstract: str, repos: list[dict]) -> list[dict]:
+    """用 LLM 快速过滤不相关的仓库，只保留与论文方向相关的。
+
+    在 GitHub 关键词搜索之后、Agent 1 分析之前运行。
+    如果过滤后为空或 LLM 调用失败，返回原始列表作为降级方案。
+    """
+    if len(repos) <= 3:
+        return repos
+
+    # 超过 20 个仓库时，只取 top 20（按 stars），避免 JSON 输出过长
+    if len(repos) > 20:
+        repos_for_filter = sorted(repos, key=lambda r: r.get("stars", 0), reverse=True)[:20]
+    else:
+        repos_for_filter = repos
+
+    # 构造缩略的仓库清单供 LLM 判断
+    repo_list_parts = []
+    for i, r in enumerate(repos_for_filter):
+        desc = (r.get("description") or "")[:120]
+        topics = ", ".join(r.get("topics", [])[:8])
+        repo_list_parts.append(
+            f"{i+1}. {r['full_name']} (Stars:{r.get('stars',0)})\n"
+            f"   Description: {desc}\n"
+            f"   Topics: {topics}"
+        )
+    repo_list_text = "\n".join(repo_list_parts)
+
+    system_prompt = """你是一个学术论文与开源代码匹配��家。任务是判断 GitHub 仓库是否与给定论文属于同一研究方向。
+
+排除标准（满足任一即排除）：
+- 仓库解决的业务问题与论文完全不同（如论文做工业缺陷检测，仓库做医学图像/自动驾驶/人脸识别）
+- 仓库使用的核心技术方法与论文完全无关
+- 仓库是通用教程/课程作业/面试题集合
+
+保留标准（满足任一即保留）：
+- 仓库实现的方法与论文方法同属一个技术范式
+- 仓库可用于该论文的对比实验（baseline/comparison）
+- 仓库是该领域的知名 benchmarking 库
+
+输出严格 JSON（不要 reasoning 字段以节省 token）：
+{"relevant": ["owner/repo1", "owner/repo2"], "irrelevant": ["owner/repo3"]}"""
+
+    user_prompt = f"""## 论文信息
+标题: {title[:200]}
+摘要: {abstract[:500]}
+
+## GitHub 仓库清单（共 {len(repos_for_filter)} 个）
+{repo_list_text}
+
+请判断每个仓库是否与该论文方向相关。"""
+
+    try:
+        raw = call_llm_json(system_prompt, user_prompt, temperature=0.1, max_tokens=4000)
+        data = parse_json_safe(raw, "filter_repos")
+    except Exception as e:
+        print(f"  [WARN] 仓库过滤失败，保留全部: {e}")
+        return repos
+
+    relevant_set = set(data.get("relevant", []))
+    irrelevant = data.get("irrelevant", [])
+
+    if irrelevant:
+        print(f"  [过滤] 剔除 {len(irrelevant)} 个不相关仓库: {irrelevant}")
+
+    filtered = [r for r in repos if r["full_name"] in relevant_set]
+
+    if len(filtered) < 2:
+        print(f"  [WARN] 过滤后仅剩 {len(filtered)} 个仓库，回退到原始结果")
+        return repos
+
+    print(f"  过滤后保留 {len(filtered)}/{len(repos)} 个仓库")
+    return filtered
+
+
+def _make_error_evaluation(error_msg: str) -> dict:
+    """构造一个表示评估失败的 evaluation dict"""
+    return {
+        "reproducibility_score": 0,
+        "benchmark_fitness_score": 0,
+        "overall_score": 0,
+        "verdict": "error",
+        "env_score": 0,
+        "doc_score": 0,
+        "code_score": 0,
+        "community_score": 0,
+        "dep_score": 0,
+        "benchmark_score": 0,
+        "reasoning": f"评估失败: {error_msg[:100]}",
+        "risks": ["评估过程出错，请手动检查该仓库"],
+        "benchmark_readiness": "not_ready",
+        "suggested_use": "评估失败，请手动检查",
+    }
+
+
+# ============================================================
+# 命令行入口
+# ============================================================
+if __name__ == "__main__":
+    # 修复 Windows 终端 emoji 编码问题
+    from llm_utils import fix_windows_encoding
+    fix_windows_encoding()
+
+    if len(sys.argv) < 2:
+        print("用法: python run.py <arxiv_url>")
+        print("示例: python run.py https://arxiv.org/abs/1706.03762")
+        print("示例: python run.py https://arxiv.org/abs/2011.08785")
+        sys.exit(1)
+
+    url = sys.argv[1]
+    result = run(url)
+
+    if result.get("error"):
+        print(f"\n{'='*60}")
+        print(f"运行未完全成功")
+        print(f"{'='*60}")
+        print(f"  {result['error']}")
+
+        if result.get("paper"):
+            print(f"\n  论文信息已获取: {result['paper'].get('title', '')[:80]}")
+        if result.get("direction"):
+            print(f"  方向解析已完成: {result['direction'].get('subfield', '')}")
+    else:
+        from app import format_report
+        # 用 utf-8 编码输出避免 emoji 乱码
+        report = format_report(result)
+        print(report.encode(sys.stdout.encoding or 'utf-8', errors='replace').decode(sys.stdout.encoding or 'utf-8', errors='replace'))

state.py

@@ -0,0 +1,78 @@
+# state.py
+# ============================================================
+# 类型：数据模型定义（乙负责，PPT 展示用）
+# 功能：定义整个系统的核心数据结构
+# 用途：PPT 中展示架构设计能力；代码中不需要 import，仅作为参考
+# ============================================================
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+# ---- 第一层：研究方向 ----
+
+@dataclass
+class MethodFamily:
+    """方法族"""
+    family_name: str           # 如 "Embedding-based Anomaly Detection"
+    description: str           # 一句话核心特点
+    representative_work: str   # 代表论文，如 "PaDiM (2021)"
+    search_queries: list[str]  # GitHub 搜索词
+
+
+@dataclass
+class DirectionAnalysis:
+    """研究方向解析结果（Agent 1 的输出）"""
+    subfield: str              # 子领域名
+    subfield_trend: str        # 当前趋势
+    method_families: list[MethodFamily]
+    broad_queries: list[str]   # 宽泛搜索词
+
+
+# ---- 第二层：候选仓库 ----
+
+@dataclass
+class CandidateRepo:
+    """候选仓库（甲的 Workflow 输出）"""
+    full_name: str             # "openvinotoolkit/anomalib"
+    html_url: str
+    description: str
+    stars: int
+    language: str
+    updated_at: str
+    topics: list[str]
+    match_keyword: str         # 命中哪个搜索词
+    method_family: str         # 归类到哪个方法族（可为空）
+    readme: Optional[str] = None
+    dependencies: dict[str, str] = field(default_factory=dict)
+
+
+# ---- 第三层：评估结果 ----
+
+@dataclass
+class EvalResult:
+    """单个仓库的评估结果（Agent 2 的输出）"""
+    reproducibility_score: int   # 可复现性总分 (0-80)
+    benchmark_fitness_score: int # 对比实验适配度总分 (0-20)
+    overall_score: int           # 综合总分 (0-100)
+    verdict: str                 # reproducible / partially / not_reproducible
+    env_score: int               # 0-15
+    doc_score: int               # 0-20
+    code_score: int              # 0-20
+    community_score: int         # 0-10
+    dep_score: int               # 0-15
+    benchmark_score: int         # 0-20
+    reasoning: str               # 分析文本
+    risks: list[str]             # 风险列表
+    benchmark_readiness: str     # ready / partial / not_ready
+    suggested_use: str           # 建议用途
+
+
+# ---- 顶层：完整研报 ----
+
+@dataclass
+class ResearchReport:
+    """完整研究方向全景研报（run.py 的最终输出）"""
+    paper_info: dict
+    direction: DirectionAnalysis
+    repos: list[tuple[CandidateRepo, EvalResult]]

test_agents.py

@@ -0,0 +1,294 @@
+# test_agents.py
+# ============================================================
+# 类型：测试工具（乙负责）
+# 功能：一键运行两个 Agent 的自测，验证基础功能正常
+# 用法：python test_agents.py
+# ============================================================
+import sys
+from llm_utils import fix_windows_encoding
+
+
+# 模拟 GitHub 搜索结果（供 Agent 1 测试使用）
+MOCK_REPOS = [
+    {
+        "full_name": "openvinotoolkit/anomalib",
+        "html_url": "https://github.com/openvinotoolkit/anomalib",
+        "description": "An anomaly detection library comprising state-of-the-art algorithms.",
+        "stars": 4000, "language": "Python",
+        "topics": ["anomaly-detection", "pytorch", "benchmarking"],
+    },
+    {
+        "full_name": "hcw-00/PatchCore",
+        "html_url": "https://github.com/hcw-00/PatchCore",
+        "description": "Official implementation of PatchCore: Towards Total Recall in Industrial Anomaly Detection.",
+        "stars": 850, "language": "Python",
+        "topics": ["memory-bank", "anomaly-detection", "pytorch"],
+    },
+    {
+        "full_name": "taikiinoue45/STFPM",
+        "html_url": "https://github.com/taikiinoue45/STFPM",
+        "description": "Student-Teacher Feature Pyramid Matching for Anomaly Detection (PyTorch).",
+        "stars": 320, "language": "Python",
+        "topics": ["teacher-student", "anomaly-detection"],
+    },
+    {
+        "full_name": "VitjanZ/DRAEM",
+        "html_url": "https://github.com/VitjanZ/DRAEM",
+        "description": "DRAEM: Discriminatively trained reconstruction embedding for surface anomaly detection.",
+        "stars": 180, "language": "Python",
+        "topics": ["synthetic-defect", "anomaly-detection", "reconstruction"],
+    },
+    {
+        "full_name": "marugoto/CFLow",
+        "html_url": "https://github.com/marugoto/CFLow",
+        "description": "CFLow: Real-time unsupervised anomaly detection via conditional normalizing flows.",
+        "stars": 130, "language": "Python",
+        "topics": ["normalizing-flow", "anomaly-detection"],
+    },
+    {
+        "full_name": "someone/anomaly-tutorial",
+        "html_url": "https://github.com/someone/anomaly-tutorial",
+        "description": "A curated list of anomaly detection papers and resources.",
+        "stars": 45, "language": "Markdown",
+        "topics": ["awesome-list", "anomaly-detection"],
+    },
+]
+
+
+def test_agent1():
+    """测试 Agent 1：direction_analyzer（新版——基于仓库数据归纳）"""
+    from direction_analyzer import analyze_direction
+
+    print("=" * 60)
+    print("Agent 1 测试：基于 GitHub 仓库的方法族归纳")
+    print("=" * 60)
+
+    test_cases = [
+        {
+            "name": "PaDiM + 真实仓库数据",
+            "title": "PaDiM: a Patch Distribution Modeling Framework for Anomaly Detection and Localization",
+            "abstract": (
+                "We present a new framework for anomaly detection and localization based on "
+                "patch distribution modeling. PaDiM uses pretrained convolutional neural networks "
+                "to extract patch features and models their distribution using multivariate "
+                "Gaussian distributions. It achieves state-of-the-art results on MVTec AD and "
+                "STC datasets for industrial defect detection."
+            ),
+            "repos": MOCK_REPOS,
+            "checks": [
+                ("subfield 非空", lambda r: bool(r.get("subfield"))),
+                ("有 >= 2 个方法族", lambda r: len(r.get("method_families", [])) >= 2),
+                ("至少 1 个方法族有 matched_repos", lambda r: any(
+                    len(mf.get("matched_repos", [])) >= 1
+                    for mf in r.get("method_families", [])
+                )),
+                ("有 broad_queries", lambda r: len(r.get("broad_queries", [])) >= 1),
+            ],
+        },
+        {
+            "name": "Transformer (降级模式：无仓库数据)",
+            "title": "Attention Is All You Need",
+            "abstract": (
+                "The dominant sequence transduction models are based on complex recurrent "
+                "or convolutional neural networks... We propose a new simple network "
+                "architecture, the Transformer, based solely on attention mechanisms."
+            ),
+            "repos": None,  # 降级模式
+            "checks": [
+                ("subfield 非空", lambda r: bool(r.get("subfield"))),
+                ("有 >= 3 个方法族", lambda r: len(r.get("method_families", [])) >= 3),
+                ("有 broad_queries", lambda r: len(r.get("broad_queries", [])) >= 1),
+            ],
+        },
+        {
+            "name": "EfficientAD (轻量仓库数据)",
+            "title": "EfficientAD: Accurate Visual Anomaly Detection at Millisecond-Level Latencies",
+            "abstract": (
+                "We propose EfficientAD, a lightweight anomaly detection method that achieves "
+                "millisecond-level latency. It uses a teacher-student architecture with a simple "
+                "student network that learns to mimic the teacher's features on normal images only."
+            ),
+            "repos": MOCK_REPOS[:4],  # 只给 4 个仓库
+            "checks": [
+                ("subfield 非空", lambda r: bool(r.get("subfield"))),
+                ("有 subfield_trend", lambda r: len(r.get("subfield_trend", "")) >= 10),
+                ("方法族有 search_queries", lambda r: any(
+                    len(mf.get("search_queries", [])) >= 1
+                    for mf in r.get("method_families", [])
+                )),
+            ],
+        },
+    ]
+
+    passed = 0
+    failed = 0
+    for tc in test_cases:
+        print(f"\n  [{tc['name']}]")
+        try:
+            result = analyze_direction(tc["title"], tc["abstract"], tc["repos"])
+            subfield = result.get("subfield", "?")
+            families = result.get("method_families", [])
+            print(f"    子领域: {subfield}")
+            print(f"    方法族:")
+            for mf in families:
+                print(f"      - {mf.get('family_name', '?')}: matched_repos={mf.get('matched_repos', [])}")
+
+            tc_failed = False
+            for check_name, check_fn in tc["checks"]:
+                if check_fn(result):
+                    print(f"    ✅ {check_name}")
+                else:
+                    print(f"    ❌ {check_name}")
+                    tc_failed = True
+
+            if tc_failed:
+                failed += 1
+            else:
+                passed += 1
+        except Exception as e:
+            print(f"    ❌ 异常: {e}")
+            import traceback
+            traceback.print_exc()
+            failed += 1
+
+    return passed, failed
+
+
+def test_agent2():
+    """测试 Agent 2：repo_evaluator"""
+    from repo_evaluator import evaluate_repo
+
+    print("\n" + "=" * 60)
+    print("Agent 2 测试：仓库评估")
+    print("=" * 60)
+
+    test_cases = [
+        {
+            "name": "anomalib (预期高分)",
+            "repo": {
+                "full_name": "openvinotoolkit/anomalib",
+                "html_url": "https://github.com/openvinotoolkit/anomalib",
+                "stars": 4000,
+                "description": "An anomaly detection library comprising state-of-the-art algorithms.",
+                "updated_at": "2026-01-15T00:00:00Z",
+                "language": "Python",
+            },
+            "readme": (
+                "# Anomalib\nA library for benchmarking anomaly detection.\n\n"
+                "## Installation\n```\npip install anomalib\n```\n\n"
+                "## Training\n```python\nfrom anomalib.engine import Engine\nengine = Engine()\nengine.train()\n```\n\n"
+                "## Supported Datasets\n- MVTec AD\n- BTAD\n\n"
+                "## Benchmarking\nUse `tools/benchmark.py` for standardized evaluation."
+            ),
+            "deps": {"requirements.txt": "torch>=1.10\npytorch-lightning>=1.7\nopencv-python\nnumpy"},
+            "family": "Patch Distribution Modeling",
+            "checks": [
+                ("overall_score >= 55", lambda r: r.get("overall_score", 0) >= 55),
+                ("verdict 非 error", lambda r: r.get("verdict") in ("reproducible", "partially")),
+                ("benchmark_readiness 非 not_ready", lambda r: r.get("benchmark_readiness") in ("ready", "partial")),
+                ("reasoning 非空", lambda r: len(r.get("reasoning", "")) >= 10),
+            ],
+        },
+        {
+            "name": "推理 Demo 项目 (预期低分)",
+            "repo": {
+                "full_name": "someone/anomaly-demo",
+                "html_url": "https://github.com/someone/anomaly-demo",
+                "stars": 15,
+                "description": "A simple demo of anomaly detection.",
+                "updated_at": "2024-03-01T00:00:00Z",
+                "language": "Python",
+            },
+            "readme": "# Anomaly Detection Demo\nJust a demo.\n\n```\npython demo.py --image path/to/image.jpg\n```\nPretrained weights: Google Drive link.",
+            "deps": {},
+            "family": "",
+            "checks": [
+                ("overall_score < 50", lambda r: r.get("overall_score", 0) < 50),
+                ("benchmark_readiness 为 not_ready", lambda r: r.get("benchmark_readiness") == "not_ready"),
+                ("有 risks 列表", lambda r: isinstance(r.get("risks"), list)),
+            ],
+        },
+        {
+            "name": "中等项目 (部分可复现)",
+            "repo": {
+                "full_name": "research-lab/anomaly-pytorch",
+                "html_url": "https://github.com/research-lab/anomaly-pytorch",
+                "stars": 200,
+                "description": "PyTorch implementation of anomaly detection methods.",
+                "updated_at": "2025-08-01T00:00:00Z",
+                "language": "Python",
+            },
+            "readme": (
+                "# Anomaly Detection in PyTorch\n\n"
+                "## Install\n```\npip install -r requirements.txt\n```\n\n"
+                "## Train\n```\npython train.py --config config.yaml\n```"
+            ),
+            "deps": {"requirements.txt": "torch>=1.8\nnumpy\nopencv-python\nmatplotlib"},
+            "family": "Teacher-Student",
+            "checks": [
+                ("overall_score 在 40-85 之间", lambda r: 40 <= r.get("overall_score", 0) <= 85),
+                ("verdict 非 error", lambda r: r.get("verdict") != "error"),
+            ],
+        },
+    ]
+
+    passed = 0
+    failed = 0
+    for tc in test_cases:
+        print(f"\n  [{tc['name']}]")
+        try:
+            result = evaluate_repo(tc["repo"], tc["readme"], tc["deps"], tc["family"])
+            print(f"    综合: {result.get('overall_score')}/100")
+            print(f"    可复现性: {result.get('reproducibility_score')}/80")
+            print(f"    适配度: {result.get('benchmark_fitness_score')}/20")
+            print(f"    判定: {result.get('verdict')} | 就绪: {result.get('benchmark_readiness')}")
+
+            tc_failed = False
+            for check_name, check_fn in tc["checks"]:
+                if check_fn(result):
+                    print(f"    ✅ {check_name}")
+                else:
+                    print(f"    ❌ {check_name}")
+                    tc_failed = True
+
+            if tc_failed:
+                failed += 1
+            else:
+                passed += 1
+        except Exception as e:
+            print(f"    ❌ 异常: {e}")
+            import traceback
+            traceback.print_exc()
+            failed += 1
+
+    return passed, failed
+
+
+# ============================================================
+# 主入口
+# ============================================================
+if __name__ == "__main__":
+    fix_windows_encoding()
+
+    print("ResearchRadar · Agent 自检套件")
+    print("=" * 60)
+
+    a1_pass, a1_fail = test_agent1()
+    a2_pass, a2_fail = test_agent2()
+
+    print("\n" + "=" * 60)
+    print("测试汇总")
+    print("=" * 60)
+    print(f"  Agent 1 (方法族归纳):  {a1_pass} 通过, {a1_fail} 失败")
+    print(f"  Agent 2 (仓库评估):    {a2_pass} 通过, {a2_fail} 失败")
+
+    total_pass = a1_pass + a2_pass
+    total_fail = a1_fail + a2_fail
+    print(f"  总计:                  {total_pass} 通过, {total_fail} 失败")
+
+    if total_fail > 0:
+        print("\n⚠ 部分测试未通过，请检查对应 Agent 的输出。")
+        sys.exit(1)
+    else:
+        print("\n✅ 所有测试通过！")
+        sys.exit(0)

乙_实现总结.md

@@ -0,0 +1,107 @@
+# ResearchRadar · 乙实现总结
+
+> 版本：v2.0 | 日期：2026-05-04
+
+## 乙的角色
+
+在 ResearchRadar 三人分工中，乙负责**"智能判断层 + 调度层 + 界面层"**——即所有需要调用 LLM 做决策的模块、串联全流程的调度器、以及用户交互界面。
+
+---
+
+## 实现了什么
+
+共 **7 个文件**，覆盖三个层次：
+
+### 1. 公共基础设施 — `llm_utils.py`
+
+所有 Agent 的共享底座，解决 LLM 调用的三个核心痛点：
+
+| 能力 | 实现 |
+|------|------|
+| **API 韧性** | `call_llm()` — 3 次指数退避重试（2s → 4s → 8s），支持 `response_format` 强制 JSON 模式 |
+| **JSON 容错** | `parse_json_safe()` — 6 种策略依次尝试（直接解析 → ```json``` 代码块 → 通用代码块 → 正则提取 → 尾部逗号修复 → 关键词定位） |
+| **输出兜底** | `validate_direction_output()` / `validate_eval_output()` — 缺失字段自动填充默认值，类型校验 |
+
+### 2. Agent 1：方法族归纳 — `direction_analyzer.py`
+
+**输入**：论文标题 + 摘要 + GitHub 搜索结果（仓库列表）
+**输出**：研究方向全景（子领域、趋势、方法族谱系 + 每个族的归属仓库）
+
+- **核心设计**：不再让 LLM 凭记忆划分方法族，而是基于实际 GitHub 仓库数据做分析归纳
+- 每个方法族附带 `matched_repos`——明确指出哪些仓库属于该族
+- 支持降级模式（无仓库数据时基于 LLM 自身知识）
+- 使用 `response_format: {"type": "json_object"}` + Few-Shot 示例
+
+### 3. Agent 2：仓库评估 — `repo_evaluator.py`
+
+**输入**：仓库元信息 + README + 依赖文件 + 方法族
+**输出**：六维度评分（满分 100）
+
+评分框架：
+- **可复现性**（5 维度，80 分）：环境配置(15) + 文档质量(20) + 代码可用性(20) + 社区活跃度(10) + 依赖健康度(15)
+- **对比实验适配度**（1 维度，20 分）：benchmark 脚本 + 预训练权重 + 标准化评估
+- Few-Shot 评分锚定示例（高分 93 / 低分 18）
+
+### 4. 调度器 — `run.py`
+
+**新流程（先搜再分析）**：
+
+```
+arxiv URL
+  → [1] paper_fetcher（获取论文信息）
+  → [2] 关键词提取 → repo_searcher（宽泛搜索 GitHub）
+  → [3] direction_analyzer（基于仓库数据归纳方法族） ← Agent 1
+  → [4] repo_fetcher + repo_evaluator（获取详情 + 六维度评分） ← Agent 2
+  → [5] 汇总输出
+```
+
+- 仓库→方法族归属由 Agent 1 的 `matched_repos` 直接给出，不再需要关键词映射
+- 纯规则的关键词提取（`_extract_broad_queries`），不额外消耗 LLM 调用
+
+### 5. 界面层 — `app.py`
+
+Gradio Web 界面：
+- 输入框 + 3 个示例一键填充
+- `format_report()` 生成四段式 Markdown 研报：
+  1. 论文信息
+  2. 研究方向全景（子领域 + 趋势 + 方法族表格）
+  3. 开源实现评估排名（每个仓库六维度明细 + 分析 + 风险点）
+  4. 对比实验推荐总结（按 ready/partial/not_ready 分组）
+
+### 6. 数据模型 — `state.py`
+
+5 个 dataclass 定义系统核心数据结构：`MethodFamily` → `DirectionAnalysis` → `CandidateRepo` → `EvalResult` → `ResearchReport`
+
+### 7. 自检测试 — `test_agents.py`
+
+一键运行两个 Agent 的自测，6 个测试用例，断言 + 汇总，非零退出码。
+
+---
+
+## 设计原则
+
+- **无框架依赖**：Agent = Python 函数 + LLM 调用，不用 LangChain/LangGraph
+- **数据流简单**：dict 传参，if/else 分支，显式优于隐式
+- **错误不崩溃**：LLM 输出异常 → 填充默认值；API 失败 → 3 次重试；评估失败 → 标记 error 继续
+- **接口契约清晰**：与甲的对接通过函数签名 + dict 字段名约定，详见 `乙→甲_对接文档.md`
+
+---
+
+## 已确认可运行
+
+```bash
+python test_agents.py      # 6/6 通过
+python direction_analyzer.py  # 3 篇论文独立自测
+python repo_evaluator.py      # 3 个仓库场景独立自测
+```
+
+---
+
+## 甲模块已集成 ✓
+
+甲的 3 个 Workflow 模块已交付并重命名为正式文件名：
+- `paper_fetcher.py` — arxiv API 论文信息获取
+- `repo_searcher.py` — GitHub 仓库搜索（支持去重 + Stars 排序 + Token 认证）
+- `repo_fetcher.py` — GitHub 仓库 README + 依赖文件获取
+
+`python -c "import run"` 导入成功，接下来可进行端到端联调测试。

乙→甲_对接文档.md

@@ -0,0 +1,772 @@
+# ResearchRadar · 乙→甲 对接文档
+
+> 版本：v1.0 | 日期：2026-05-04 | 撰写：乙
+
+---
+
+## 目录
+
+1. [乙完成情况总览](#1-乙完成情况总览)
+2. [甲需交付的3个模块（API契约）](#2-甲需交付的3个模块api契约)
+   - [2.1 paper_fetcher.py](#21-paper_fetcherpy)
+   - [2.2 repo_searcher.py](#22-repo_searcherpy)
+   - [2.3 repo_fetcher.py](#23-repo_fetcherpy)
+3. [数据流全景图](#3-数据流全景图)
+4. [对接步骤（技术 + 沟通）](#4-对接步骤技术--沟通)
+5. [对接后效果](#5-对接后效果)
+6. [故障排查指南](#6-故障排查指南)
+7. [已知局限与后续迭代](#7-已知局限与后续迭代)
+
+---
+
+## 1. 乙完成情况总览
+
+### 1.1 已完成的7个文件
+
+| # | 文件名 | 类型 | 功能 | 状态 |
+|---|--------|------|------|------|
+| 1 | `llm_utils.py` | 公共工具 | OpenAI 客户端、LLM调用（3次重试）、JSON安全解析（6策略）、输出校验 | ✅ 完成 |
+| 2 | `direction_analyzer.py` | Agent 1 | LLM解析研究方向→子领域+方法族+搜索词 | ✅ 完成 |
+| 3 | `repo_evaluator.py` | Agent 2 | LLM六维度评分（可复现性5维80分 + 对比实验适配度1维20分） | ✅ 完成 |
+| 4 | `run.py` | 调度器 | 串联3层架构，数据传递，方法族匹配，耗时统计 | ✅ 完成 |
+| 5 | `app.py` | UI层 | Gradio界面 + Markdown研报格式化（四段式） | ✅ 完成 |
+| 6 | `state.py` | 数据模型 | dataclass定义（MethodFamily, DirectionAnalysis, CandidateRepo, EvalResult, ResearchReport） | ✅ 完成 |
+| 7 | `test_agents.py` | 测试工具 | 一键测试两个Agent，6个测试用例，断言+汇总 | ✅ 完成 |
+
+### 1.2 诚实评估：哪些是真正完成的，哪些有前提条件
+
+**可以100%确认完成的：**
+- Agent 1（方向解析）：独立可运行，3篇论文测试通过。输入标题+摘要→输出结构化的研究方向JSON。
+- Agent 2（仓库评估）：独立可运行，3个场景测试通过（高分/低分/中等）。输入仓库元信息+README+依赖→输出六维度评分JSON。
+- 公共工具层（llm_utils.py）：API重试、JSON解析容错、输出校验全部就绪。
+- 测试套件（test_agents.py）：一键运行，6/6通过。
+
+**代码已完成但需甲交付后才能验证的：**
+- `run.py`：调度逻辑完整，含耗时统计、方法族匹配（中英双语关键词）、错误处理链路。但**无法运行**——它依赖甲的3个模块，当前导入即报错。
+- `app.py`：Gradio界面 + Markdown格式化完整。同样**无法启动**——它导入 `run`，而 `run` 导入甲的模块。
+
+**已知局限（非bug，是MVP范围内的取舍）：**
+- `_match_family` 仓库→方法族匹配是关键词级别的，非LLM语义匹配。当LLM返回中文方法族名（如"基于重建的方法"）时，依赖中英双语关键词映射来兜底，但不能保证100%准确。正确率估计70-80%。任务书计划中 Week 3 用 LLM 替换。
+- LLM输出依赖提示词约束，偶有格式偏差。已通过 `parse_json_safe`（6种解析策略）+ `validate_*_output`（字段填充默认值）双重兜底，确保下游不崩溃。
+
+### 1.3 自检命令
+
+```bash
+# 甲模块尚未交付时，只能运行这两个：
+python direction_analyzer.py      # 测试 Agent 1（3篇论文）
+python repo_evaluator.py          # 测试 Agent 2（3个仓库场景）
+python test_agents.py             # 一键测试两个Agent（推荐）
+
+# 甲模块交付后：
+python run.py https://arxiv.org/abs/2011.08785   # 完整链路
+python app.py                                     # 启动 Gradio 界面
+```
+
+---
+
+## 2. 甲需交付的3个模块（API契约）
+
+> **重要**：以下契约是双方代码能对接的**唯一接口标准**。函数名、参数名、返回值类型、dict的key名都必须严格一致。如有变动，必须双方同步确认。
+
+### 2.1 paper_fetcher.py
+
+**职责**：根据 arxiv URL 获取论文元信息。
+
+#### 函数签名
+
+```python
+def fetch_paper_info(arxiv_url: str) -> dict:
+    """从 arxiv URL 获取论文信息。
+
+    Args:
+        arxiv_url: arxiv 论文 URL，如 "https://arxiv.org/abs/2011.08785"
+
+    Returns:
+        dict，必须包含以下字段。如获取失败，抛出 Exception。
+    """
+```
+
+#### 返回值 dict 字段定义
+
+| 字段名 | 类型 | 必需 | 说明 | 示例 |
+|--------|------|------|------|------|
+| `arxiv_id` | `str` | ✅ 必需 | arxiv ID | `"2011.08785"` |
+| `title` | `str` | ✅ 必需 | 论文标题（完整，不要截断） | `"PaDiM: a Patch Distribution Modeling..."` |
+| `abstract` | `str` | ✅ 必需 | 论文摘要（完整） | `"We present a new framework..."` |
+| `authors` | `list[str]` | ✅ 必需 | 作者列表 | `["Thomas Defard", ...]` |
+| `published` | `str` | 推荐 | 发表日期（ISO格式字符串即可） | `"2021-03-15"` 或 `"2021-03-15T00:00:00Z"` |
+| `categories` | `list[str]` | 推荐 | arxiv 分类标签 | `["cs.CV", "cs.LG"]` |
+
+#### 乙的调用上下文
+
+```python
+# run.py 第74行：
+paper = fetch_paper_info(arxiv_url)
+
+# 紧接着使用的字段（第78-82行）：
+title = paper.get("title", "")
+abstract = paper.get("abstract", "")
+# authors 和 categories 仅用于打印日志
+# app.py 额外使用 arxiv_id 和 published 显示在研报中
+```
+
+#### 实现提示（给甲）
+
+- arxiv 有公开 API：`https://export.arxiv.org/api/query?id_list={arxiv_id}`
+- 返回 XML 格式，需要解析 `<title>`, `<summary>`, `<author>`, `<published>`, `<category>` 等标签
+- 也可以用 `arxiv` Python 包（`pip install arxiv`）
+- 如果网络不通，可以直接抛出异常，run.py 会捕获并返回错误信息
+- 建议在 `__main__` 里写个自测：`python paper_fetcher.py` 打印一篇论文的信息
+
+---
+
+### 2.2 repo_searcher.py
+
+**职责**：根据搜索查询列表在 GitHub 上搜索仓库，去重后返回。
+
+#### 函数签名
+
+```python
+def search_repos(queries: list[str], max_per_keyword: int = 5) -> list[dict]:
+    """在 GitHub 搜索仓库。
+
+    Args:
+        queries: 搜索查询字符串列表，如 ["padim anomaly detection pytorch", ...]
+        max_per_keyword: 每个查询最多保留的仓库数
+
+    Returns:
+        list[dict]: 候选仓库列表，每个 dict 字段见下表。已去重（按 full_name）。
+    """
+```
+
+#### 返回值 list[dict] 字段定义
+
+| 字段名 | 类型 | 必需 | 说明 | 示例 |
+|--------|------|------|------|------|
+| `full_name` | `str` | ✅ 必需 | 仓库全名（owner/repo） | `"openvinotoolkit/anomalib"` |
+| `html_url` | `str` | ✅ 必需 | 仓库 URL | `"https://github.com/openvinotoolkit/anomalib"` |
+| `description` | `str` | ✅ 必需 | 仓库描述（可为空字符串） | `"An anomaly detection library..."` |
+| `stars` | `int` | ✅ 必需 | Star 数量 | `4000` |
+| `language` | `str` | ✅ 必需 | 主要语言 | `"Python"` |
+| `updated_at` | `str` | ✅ 必需 | 最后更新时间（ISO格式） | `"2026-01-15T00:00:00Z"` |
+| `topics` | `list[str]` | ✅ 必需 | GitHub topics 标签（可为空列表） | `["anomaly-detection", "pytorch"]` |
+| `match_keyword` | `str` | 推荐 | 命中了哪个搜索查询（用于研报展示） | `"padim anomaly detection pytorch"` |
+
+#### 乙的调用上下文
+
+```python
+# run.py 第119行：
+candidates = search_repos(all_queries, max_per_keyword=5)
+# all_queries 示例（18个搜索词）：
+# ["patch distribution modeling anomaly detection pytorch",
+#  "padim implementation pytorch",
+#  "memory bank anomaly detection code",
+#  ...,
+#  "industrial anomaly detection pytorch",    ← broad_queries
+#  "unsupervised anomaly localization github",
+#  "MVTec AD anomaly detection code"]
+
+# 紧接着（第127行）取前 top_n=5 个：
+candidates = candidates[:top_n]
+
+# 然后对每个 candidate 使用字段（第152-166行）：
+full_name = repo["full_name"]           # 用于拆分 owner/name 和显示
+repo.get("html_url", "")                # 用于研报链接
+repo.get("description", "")             # 用于方法族匹配
+repo.get("stars", 0)                    # 用于评分输入和显示
+repo.get("match_keyword", "")           # 用于研报展示
+```
+
+#### 重要约束
+
+- **去重**：同一个 `full_name` 只能出现一次。多个搜索查询可能命中同一个仓库。
+- **排序**：建议按 `stars` 降序排列后再去重，这样保留的是 star 最高的版本。
+- **max_per_keyword**：乙传5，意味着每个搜索查询最多返回5个仓库。如果 `all_queries` 有18个，理论最多90个，去重后通常剩10-30个。乙再截断到5个。
+- **GitHub API**：可以用 `GET /search/repositories?q=...`，未认证限制 10 req/min，认证后 30 req/min。如果18个查询全走API可能触发限流。建议：如果有 GitHub token，放到 header 里。
+
+#### 实现提示（给甲）
+
+```python
+# GitHub Search API 示例
+import requests
+url = "https://api.github.com/search/repositories"
+params = {"q": query, "sort": "stars", "order": "desc", "per_page": max_per_keyword}
+headers = {"Accept": "application/vnd.github.v3+json"}
+# 如果有 token: headers["Authorization"] = "token ghp_xxx"
+response = requests.get(url, params=params, headers=headers)
+data = response.json()
+for item in data.get("items", []):
+    # 提取字段构建 dict
+    ...
+```
+
+---
+
+### 2.3 repo_fetcher.py
+
+**职责**：获取单个仓库的 README 和依赖文件内容。
+
+#### 函数签名
+
+```python
+def fetch_readme(owner: str, name: str) -> str | None:
+    """获取仓库 README 文件内容。
+
+    Args:
+        owner: 仓库所有者，如 "openvinotoolkit"
+        name: 仓库名，如 "anomalib"
+
+    Returns:
+        README 文件全文（字符串），获取失败返回 None。
+    """
+
+def fetch_dependencies(owner: str, name: str) -> dict[str, str]:
+    """获取仓库的依赖文件。
+
+    Args:
+        owner: 仓库所有者
+        name: 仓库名
+
+    Returns:
+        dict: {文件名: 文件内容}，如 {"requirements.txt": "torch>=1.10\n...", ...}
+              找不到任何依赖文件时返回空 dict {}。
+              常见目标文件：requirements.txt, environment.yml, setup.py, setup.cfg, Pipfile, pyproject.toml
+    """
+```
+
+#### 乙的调用上下文
+
+```python
+# run.py 第165-167行（在 for 循环内对每个仓库调用）：
+readme = fetch_readme(owner, name)       # → str | None
+deps = fetch_dependencies(owner, name)   # → dict[str, str]
+evaluation = evaluate_repo(repo, readme, deps, matched_family)
+
+# repo_evaluator.py 内部（第105行）：
+readme_text = (readme or "README 未找到")[:2500]   # 截断到 2500 字符
+# deps 被格式化为文本后同样截断每个文件到 1000 字符
+```
+
+#### 重要约束
+
+- `fetch_readme`：GitHub API 路径 `GET /repos/{owner}/{name}/readme`，返回 base64 编码内容，需解码。
+- `fetch_dependencies`：需要逐个检查依赖文件是否存在。GitHub API `GET /repos/{owner}/{name}/contents/{path}`。**不要**把整个仓库 clone 下来——MVP 阶段一个 API 调用即可。
+- 两个函数都**不能抛出异常**。失败时返回 `None` 或 `{}`。乙的调度器已经对每个仓库做了 try/except，但如果函数内部抛出异常，评估循环可能会中断（当前只捕获了评估失败，未捕获 fetch 失败——这是一个乙已知的防御缺口，见7.1节）。
+
+#### 实现提示（给甲）
+
+```python
+import requests
+import base64
+
+def fetch_readme(owner, name):
+    url = f"https://api.github.com/repos/{owner}/{name}/readme"
+    headers = {"Accept": "application/vnd.github.v3+json"}
+    resp = requests.get(url, headers=headers)
+    if resp.status_code != 200:
+        return None
+    content = resp.json().get("content", "")
+    return base64.b64decode(content).decode("utf-8", errors="replace")
+
+def fetch_dependencies(owner, name):
+    target_files = ["requirements.txt", "environment.yml", "setup.py",
+                    "setup.cfg", "Pipfile", "pyproject.toml"]
+    result = {}
+    for fname in target_files:
+        url = f"https://api.github.com/repos/{owner}/{name}/contents/{fname}"
+        resp = requests.get(url, headers={"Accept": "application/vnd.github.v3+json"})
+        if resp.status_code == 200:
+            content = resp.json().get("content", "")
+            result[fname] = base64.b64decode(content).decode("utf-8", errors="replace")
+    return result
+```
+
+---
+
+## 3. 数据流全景图
+
+```
+用户输入 arxiv URL
+    │
+    ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ [1/5] paper_fetcher.py          ← 甲（Workflow）                │
+│   fetch_paper_info(url) → dict                                  │
+│   {arxiv_id, title, abstract, authors, published, categories}    │
+└──────────────────────────┬──────────────────────────────────────┘
+                           │ title, abstract
+                           ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ [2/5] direction_analyzer.py     ← 乙（Agent 1）                 │
+│   analyze_direction(title, abstract) → dict                     │
+│   {subfield, subfield_trend, method_families, broad_queries}     │
+│                                                                  │
+│   method_families: [                                            │
+│     {family_name, description, representative_work,             │
+│      search_queries: ["...", "..."]}                            │
+│   ]                                                             │
+└──────────────────────────┬──────────────────────────────────────┘
+                           │ all_queries = flatten(search_queries) + broad_queries
+                           │ 约 12-18 个搜索字符串
+                           ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ [3/5] repo_searcher.py          ← 甲（Workflow）                │
+│   search_repos(queries, max_per_keyword=5) → list[dict]         │
+│   [{full_name, html_url, description, stars, language,           │
+│     updated_at, topics, match_keyword}]                         │
+│                                                                  │
+│   去重 → 截断 top_n=5 → 传给下一步                              │
+└─────────────��────────────┬──────────────────────────────────────┘
+                           │ 每个候选仓库: full_name → owner/name
+                           ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ [4/5] 对每个仓库并行：                                          │
+│                                                                  │
+│   repo_fetcher.py            ← 甲（Workflow）                   │
+│     fetch_readme(owner, name)     → str | None                  │
+│     fetch_dependencies(owner, name) → dict[str, str]            │
+│                                                                  │
+│   run.py                     ← 乙（调度器）                     │
+│     _match_family(repo, families) → str (方法族名 or "")        │
+│                                                                  │
+│   repo_evaluator.py          ← 乙（Agent 2）                    │
+│     evaluate_repo(repo, readme, deps, method_family) → dict     │
+│     {reproducibility_score, benchmark_fitness_score,             │
+│      overall_score, verdict, env_score, doc_score,               │
+│      code_score, community_score, dep_score,                     │
+│      benchmark_score, reasoning, risks,                          │
+│      benchmark_readiness, suggested_use}                        │
+└──────────────────────────┬──────────────────────────────────────┘
+                           │ 按 overall_score 降序排列
+                           ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ [5/5] app.py                    ← 乙（UI）                      │
+│   format_report(result) → Markdown 研报                         │
+│                                                                  │
+│   研报结构：                                                     │
+│   一、论文信息（arxiv_id, title, authors, categories）          │
+│   二、研究方向全景（子领域 + 趋势 + 方法族谱系表格）            │
+│   三、仓库评估排名（每个仓库六维度明细 + 分析 + 风险点）        │
+│   四、对比实验推荐总结（按 ready/partial/not_ready 分组）      │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 数据量级参考
+
+| 阶段 | 输入 | 输出 | 预计耗时 |
+|------|------|------|----------|
+| 1. 论文信息 | 1个URL | 1个dict | ~1s（网络） |
+| 2. 方向解析 | 标题+摘要 | 1个dict（3-6方法族+3宽泛） | ~5-15s（LLM） |
+| 3. 仓库搜索 | ~15个查询 | ~5个候选仓库 | ~10-30s（GitHub API × 15） |
+| 4. 仓库评估 | 5个仓库 × (README+依赖) | 5个evaluation dict | ~25-75s（LLM × 5） |
+| **合计** | | | **约40-120秒** |
+
+---
+
+## 4. 对接步骤（技术 + 沟通）
+
+### 4.1 甲交付文件时
+
+甲每次交付一个模块，乙方按以下流程验证。
+
+#### 阶段A：甲交付 `paper_fetcher.py`
+
+**甲需确保：**
+- [ ] 文件名：`paper_fetcher.py`
+- [ ] 放入路径：`D:\Desktop\AI_opencode_judging\paper_fetcher.py`
+- [ ] 文件内包含函数 `fetch_paper_info(arxiv_url: str) -> dict`
+- [ ] 自测可运行：`python paper_fetcher.py` 能打印一篇论文的信息
+- [ ] 返回值包含所有必需字段（见2.1节）
+
+**乙验证步骤：**
+```bash
+# 1. 确认文件存在
+ls paper_fetcher.py
+
+# 2. 检查函数签名
+python -c "from paper_fetcher import fetch_paper_info; help(fetch_paper_info)"
+
+# 3. 测试实际调用
+python -c "
+from paper_fetcher import fetch_paper_info
+paper = fetch_paper_info('https://arxiv.org/abs/2011.08785')
+for k in ['arxiv_id', 'title', 'abstract', 'authors']:
+    print(f'{k}: {str(paper.get(k))[:80]}...')
+"
+
+# 4. 确认 run.py 不再报 paper_fetcher 的 ImportError
+python -c "import run" 2>&1 | head -5
+# 预期：不再出现 "缺少模块: paper_fetcher.py"，而是报下一个缺失模块
+```
+
+#### 阶段B：甲交付 `repo_searcher.py`
+
+**甲需确保：**
+- [ ] 文件名：`repo_searcher.py`
+- [ ] 函数 `search_repos(queries: list[str], max_per_keyword: int = 5) -> list[dict]`
+- [ ] 自测可运行：用几个构造的搜索词调用，打印返回的仓库数量和名称
+- [ ] 去重已实现（同一 full_name 只出现一次）
+- [ ] 每个 dict 包含所有必需字段（见2.2节）
+
+**乙验证步骤：**
+```bash
+# 1. 确认搜索可用
+python -c "
+from repo_searcher import search_repos
+repos = search_repos(['padim anomaly detection pytorch'], max_per_keyword=3)
+print(f'找到 {len(repos)} 个仓库')
+for r in repos:
+    print(f'  {r[\"full_name\"]} ⭐{r[\"stars\"]} — {r.get(\"match_keyword\", \"?\")}')
+"
+
+# 2. 确认 run.py 不再报 repo_searcher 的 ImportError
+python -c "import run" 2>&1 | head -5
+# 预期：不再出现 "缺少模块: repo_searcher.py"，而是报下一个缺失模块
+```
+
+#### 阶段C：甲交付 `repo_fetcher.py`
+
+**甲需确保：**
+- [ ] 文件名：`repo_fetcher.py`
+- [ ] 函数 `fetch_readme(owner: str, name: str) -> str | None`
+- [ ] 函数 `fetch_dependencies(owner: str, name: str) -> dict[str, str]`
+- [ ] 自测可运行：对 anomalib 仓库调用两个函数，打印结果
+
+**乙验证步骤：**
+```bash
+# 1. 确认能获取 README
+python -c "
+from repo_fetcher import fetch_readme
+readme = fetch_readme('openvinotoolkit', 'anomalib')
+print(f'README 长度: {len(readme) if readme else 0} 字符')
+print((readme or '')[:200])
+"
+
+# 2. 确认能获取依赖
+python -c "
+from repo_fetcher import fetch_dependencies
+deps = fetch_dependencies('openvinotoolkit', 'anomalib')
+print(f'找到 {len(deps)} 个依赖文件: {list(deps.keys())}')
+for fname, content in deps.items():
+    print(f'  {fname}: {len(content)} 字符')
+"
+
+# 3. 确认 run.py 不再报任何 ImportError
+python -c "import run; print('run.py 导入成功！')"
+# 预期：run.py 导入成功！
+```
+
+### 4.2 全部交付后的联调
+
+```bash
+# 第一步：确保乙的两个 Agent 正常
+python test_agents.py
+# 预期：6/6 通过
+
+# 第二步：用一篇工业缺陷检测论文跑完整链路
+python run.py https://arxiv.org/abs/2011.08785
+# 预期：
+#   [1/5] 获取论文信息 → 显示标题、作者、分类、耗时
+#   [2/5] 解析研究方向 → 显示子领域、趋势、方法族、生成的搜索词数
+#   [3/5] 搜索 GitHub → 显示候选仓库列表（最多5个）
+#   [4/5] 评估仓库 → 逐个显示评分
+#   [5/5] 完成 → 打印完整 Markdown 研报
+
+# 第三步：启动 Gradio 界面
+python app.py
+# 浏览器打开 http://127.0.0.1:7860
+# 粘贴 arxiv URL，点击 Submit，查看研报
+```
+
+### 4.3 对接时的沟通要点
+
+1. **统一开发环境**
+   - Python 版本：3.10+ （乙当前使用 3.11+，`str | None` 类型注解需要 3.10+）
+   - 依赖安装：`pip install -r requirements.txt`（openai, gradio, requests 已列好）
+   - 甲如需新增依赖，需同步更新 `requirements.txt`
+
+2. **GitHub API 限流**
+   - 未认证：10 次/分钟。18个搜索查询会超限。
+   - 认证：30 次/分钟。建议甲申请一个 GitHub Personal Access Token（免费，Settings → Developer settings → Tokens），不需要任何权限（public repo 只读不需要 scope）。
+   - Token 配置方式：甲自由选择（环境变量 `GITHUB_TOKEN`、配置文件、或硬编码——但别提交到 git）。
+
+3. **错误处理约定**
+   - Workflow 函数（甲的模块）：尽量不抛异常。获取失败返回 `None`、`[]`、`{}` 等空值。
+   - Agent 函数（乙的模块）：LLM 解析失败抛 `ValueError`，API 调用失败抛 `RuntimeError`。
+   - 调度器（run.py）：捕获所有异常，转为 `{"error": "..."}` 或 fallback 值，保证流程不崩溃。
+
+4. **Git 协作建议**
+   ```
+   D:\Desktop\AI_opencode_judging\
+   ├── .gitignore          ← 建议添加：__pycache__/, .env, *.pyc
+   ├── requirements.txt
+   ├── state.py            ← 双方共享的数据模型参考
+   ├── paper_fetcher.py    ← 甲
+   ├── repo_searcher.py    ← 甲
+   ├── repo_fetcher.py     ← 甲
+   ├── llm_utils.py        ← 乙
+   ├── direction_analyzer.py ← 乙
+   ├── repo_evaluator.py   ← 乙
+   ├── run.py              ← 乙
+   ├── app.py              ← 乙
+   ├── test_agents.py      ← 乙
+   └── test_set/           ← 甲放置测试数据
+   ```
+
+---
+
+## 5. 对接后效果
+
+### 5.1 完整研报示例（结构展示）
+
+对接完成后，输入 `https://arxiv.org/abs/2011.08785`（PaDiM），输出研报结构如下：
+
+```markdown
+# ResearchRadar 研究方向全景研报
+
+---
+
+## 一、论文信息
+
+| 项目 | 内容 |
+|------|------|
+| **标题** | PaDiM: a Patch Distribution Modeling Framework for Anomaly Detection and Localization |
+| **arXiv** | [2011.08785](https://arxiv.org/abs/2011.08785) |
+| **作者** | Thomas Defard, Aleksandr Setkov, Angelique Loesch, Romaric Audigier |
+| **发表时间** | 2021-03-15 |
+| **分类** | cs.CV, cs.LG |
+
+---
+
+## 二、研究方向全景
+
+### 子领域定位
+
+**工业图像异常检测与定位**
+
+### 当前趋势
+
+2024-2025年主流趋势包括利用预训练视觉模型提取局部特征，结合概率建模进行无监督异常检测，强调高效推理和细粒度定位。
+
+### 方法族���系
+
+| # | 方法族 | 核心特点 | 代表工作 |
+|---|--------|----------|----------|
+| 1 | **Patch Distribution Modeling** | 预训练CNN提取patch特征+高斯分布建模 | PaDiM (2021) |
+| 2 | **Memory Bank-based Methods** | 存储正常样本特征到记忆库进行检索 | PatchCore (2022) |
+| 3 | **Knowledge Distillation Methods** | 师生网络，学生学习模仿教师输出 | STFPM (2021) |
+| 4 | **Reconstruction-based Methods** | 自编码器重建正常样本，异常重建误差大 | AutoEncoder |
+| 5 | **Synthetic Defect Methods** | 生成合成缺陷用于训练 | DRAEM (2021) |
+
+---
+
+## 三、开源实现评估排名
+
+### 1. [openvinotoolkit/anomalib](https://github.com/openvinotoolkit/anomalib) `[Embedding-based]`
+
+✅ **可复现性: 80/80** | 🟢 **对比实验适配度: 20/20** | **综合: 100/100**
+
+| 维度 | 得分 | 满分 | 说明 |
+|------|:----:|:----:|------|
+| 环境配置 | 15 | 15 | 依赖文件完整性 |
+| 文档质量 | 20 | 20 | 安装/训练/数据说明 |
+| 代码可用性 | 20 | 20 | 训练+推理脚本 |
+| 社区活跃度 | 10 | 10 | Star + 更新频率 |
+| 依赖健康度 | 15 | 15 | 依赖兼容性 |
+| **对比实验** | **20** | **20** | **benchmark + 预训练权重** |
+
+⭐ Star: 4000 | 匹配词: `anomaly detection library pytorch`
+
+**分析**: anomalib提供了完整的benchmark框架，支持MVTec AD等标准数据集，有预训练权重和标准化评估脚本，可以直接用于对比实验。
+
+**对比实验建议**: 可以直接作为对比实验 baseline
+
+---
+
+### 2. [其他仓库...]
+
+（每个仓库同样格式的六维度明细表）
+
+---
+
+## 四、对比实验推荐总结
+
+### 🟢 可直接用于对比实验
+
+- **[openvinotoolkit/anomalib](https://github.com/openvinotoolkit/anomalib)** — 可以直接作为对比实验 baseline
+
+### 🟡 需要少量修改后可用
+
+- **[其他仓库...]** — 需要适配数据集格式
+
+### 🔴 仅适合参考代码实现
+
+- **[其他仓库...]** — 仅提供推理demo，无训练脚本...
+
+---
+
+> ResearchRadar · 论文研究方向全景 + 开源代码评估 + 对比实验推荐
+```
+
+### 5.2 Gradio 界面效果
+
+浏览器打开 `http://127.0.0.1:7860`，会看到：
+- 标题栏：ResearchRadar — 研究方向全景 + 开源代码评估
+- 输入框：论文 arxiv 链接（带3个示例一键填充）
+- 输出区：Markdown 渲染的完整研报（如5.1节所示）
+- 底部示例：PaDiM / Transformer / DRAEM 三篇论文快捷入口
+
+### 5.3 命令行输出效果
+
+```
+============================================================
+[1/5] 正在获取论文信息...
+  标题: PaDiM: a Patch Distribution Modeling Framework for Anomaly Detection and Localization
+  作者: Thomas Defard, Aleksandr Setkov, Angelique Loesch
+  分类: cs.CV, cs.LG
+  耗时: 0.8s
+
+[2/5] 正在解析研究方向（Agent 1：LLM 调用）...
+  子领域: 工业图像异常检测与定位
+  趋势: 2024-2025年主流趋势包括利用预训练视觉模型提取局部特征...
+  方法族 (5 个):
+    - Patch Distribution Modeling: 预训练CNN提取patch特征+高斯分布建模...
+    - Memory Bank-based Methods: 存储正常样本特征到记忆库...
+    - Knowledge Distillation Methods: 师生网络学习模仿...
+    - Reconstruction-based Methods: 自编码器重建正常样本...
+    - Synthetic Defect Methods: 生成合成缺陷用于训练...
+  生成 18 个搜索查询
+  耗时: 8.3s
+
+[3/5] 正在搜索 GitHub 仓库（18 个查询）...
+  去重后获得 5 个候选仓库
+  耗时: 22.1s
+  候选列表:
+    1. openvinotoolkit/anomalib  ⭐4000
+    2. hcw-00/PatchCore  ⭐850
+    3. taikiinoue45/STFPM  ⭐320
+    4. VitjanZ/DRAEM  ⭐180
+    5. xiahaifeng1995/PaDiM-Anomaly-Detection  ⭐150
+
+[4/5] 正在评估 5 个仓库...
+  (1/5) 评估 openvinotoolkit/anomalib [Embedding-based]...
+  (2/5) 评估 hcw-00/PatchCore [Memory Bank]...
+  (3/5) 评估 taikiinoue45/STFPM [Teacher-Student]...
+  (4/5) 评估 VitjanZ/DRAEM [Synthetic Defect]...
+  (5/5) 评估 xiahaifeng1995/PaDiM-Anomaly-Detection [Embedding-based]...
+  评估耗时: 42.5s
+
+[5/5] 完成！
+  最高分: openvinotoolkit/anomalib (100/100)
+  总耗时: 73.7s
+============================================================
+
+[此处输出完整 Markdown 研报，同5.1节]
+```
+
+---
+
+## 6. 故障排查指南
+
+### 6.1 甲模块尚未交付
+
+| 症状 | 原因 | 处理 |
+|------|------|------|
+| `python run.py ...` 报错 `缺少模块: paper_fetcher.py` | 甲未交付 | 等待甲，或先用 `python test_agents.py` 验证乙的部分 |
+| `python app.py` 报错 `无法导入 run.py` | 同上 | 同上 |
+
+### 6.2 API 相关
+
+| 症状 | 原因 | 处理 |
+|------|------|------|
+| `LLM API 调用失败（已重试 3 次）` | DeepSeek API 不可达或欠费 | 检查 `llm_utils.py` 中的 API Key 是否有效；检查网络 |
+| GitHub API `403 rate limit exceeded` | GitHub 限流 | 甲需添加 GitHub Token；或减少搜索查询数 |
+| arxiv API 超时 | arxiv 服务器慢 | 重试；甲可加 timeout 参数 |
+
+### 6.3 数据格式不匹配
+
+| 症状 | 原因 | 处理 |
+|------|------|------|
+| `KeyError: 'full_name'` | 甲的 `search_repos` 返回的 dict 缺少字段 | 对照本文档第2.2节的字段表补齐 |
+| `ValueError: 无法解析 LLM 返回的 JSON` | LLM 返回格式异常 | 查看终端输出中的"原始返回（前500字符）"；联系乙优化解析逻辑 |
+| 研报显示 "N/A" 过多 | 甲返回的 dict 中可选字段缺失 | 检查 paper dict 是否含 `published`, `categories` 等字段 |
+
+### 6.4 评分异常
+
+| 症状 | 原因 | 处理 |
+|------|------|------|
+| 所有仓库得分相近 | LLM 评分不够有区分度 | 检查传给 LLM 的 README/deps 信息是否足够丰富 |
+| 明显优质仓库得分很低 | `fetch_readme` 或 `fetch_dependencies` 返回了空值 | 检查 API 调用是否成功，网络是否可达 |
+| 所有仓库 `[未归类]` | `_match_family` 中英双语匹配都未命中 | 检查 LLM 返回的方法族名是否非常见表述；可在 `_DOMAIN_KEYWORDS` 补充关键词 |
+
+---
+
+## 7. 已知局限与后续迭代
+
+### 7.1 乙已识别但未修复的防御缺口
+
+1. **仓库评估循环中的异常粒度不够细**（`run.py` 第164-170行）：当前 `try/except` 包裹了 `fetch_readme` + `fetch_dependencies` + `evaluate_repo` 的整段。如果 `fetch_readme` 抛出异常（虽然它不应该），整个仓库的评估都会标记为 error，但无法知道是获取失败还是评估失败。改进方向：分步 try/except。
+
+2. **`_match_family` 使用关键词匹配而非语义匹配**：已通过中英双语关键词映射尽力提升匹配率，但正确率仍非100%。任务书计划 Week 3 用 LLM 做精准归类。
+
+3. **`parse_json_safe` 策略4（最外层 `{...}`的贪婪匹配）**：如果 LLM 一次返回了多个 JSON 对象（如先解释再给 JSON），策略4的 `\{[\s\S]*\}` 会从第一个 `{` 匹配到最后一个 `}`，产生一个非法 JSON 字符串。此情况极少出现，策略5（清理尾部逗号）可能也修不好，最终会触发策略6（关键词定位）或失败。当前通过约束 Prompt（"不要任何额外文字"）来避免。
+
+4. **无重试机制在 GitHub API 层面**：`run.py` 没有对甲的 Workflow 函数做重试。如果 GitHub API 临时返回 503，仓库搜索或 README 获取会直接失败。建议甲在自己的函数内部加重试（1-2次即可）。
+
+### 7.2 MVP 后建议迭代方向
+
+| 优先级 | 内容 | 负责 | 预计工作量 |
+|--------|------|------|------------|
+| P0 | 甲交付3个Workflow模块 | 甲 | 2-3天 |
+| P0 | 联调 + 端到端测试 | 甲乙一起 | 1天 |
+| P1 | `_match_family` 升级为 LLM 语义匹配 | 乙 | 半天 |
+| P1 | fetch_readme 失败时优雅降级（不阻断评估） | 乙 | 1小时 |
+| P2 | 支持更多论文源（不仅是 arxiv） | 甲 | 1天 |
+| P2 | 评估维度权重可配置 | 乙 | 2小时 |
+| P3 | 缓存 LLM 评估结果（避免重复调用花钱） | 乙 | 半天 |
+| P3 | 支持批量论文输入 | 甲+乙 | 1天 |
+
+---
+
+## 附录A：自检 Checklist（乙的代码）
+
+在甲交付前，乙可用此清单自查：
+
+- [x] `python test_agents.py` → 6/6 通过
+- [x] `python direction_analyzer.py` → 3篇论文正常输出
+- [x] `python repo_evaluator.py` → 3个场景评分合理
+- [x] `llm_utils.py` → call_llm 有3次重试、parse_json_safe 有6种策略
+- [x] `run.py` → 导入失败时抛出 ImportError 而非 sys.exit
+- [x] `_DOMAIN_KEYWORDS` → 中英双语关键词已覆盖6大方法族类别
+- [x] `app.py` → 导入失败有明确错误提示
+- [x] `state.py` → 数据模型定义完整
+- [x] `requirements.txt` → openai, gradio, requests 已列出
+
+## 附录B：自检 Checklist（甲的3个模块）
+
+甲交付时请对照此清单确认：
+
+**paper_fetcher.py**
+- [ ] `fetch_paper_info(arxiv_url)` 函数存在
+- [ ] 返回值包含 `arxiv_id`, `title`, `abstract`, `authors`（必需）
+- [ ] 返回值包含 `published`, `categories`（推荐）
+- [ ] `python paper_fetcher.py` 自测可运行
+
+**repo_searcher.py**
+- [ ] `search_repos(queries, max_per_keyword=5)` 函数存在
+- [ ] 返回值每个 dict 包含所有必需字段（见2.2节）
+- [ ] 已按 `full_name` 去重
+- [ ] 已按 `stars` 降序排列
+- [ ] 处理了 GitHub API 限流（加 token 或减少请求频率）
+- [ ] `python repo_searcher.py` 自测可运行
+
+**repo_fetcher.py**
+- [ ] `fetch_readme(owner, name)` 函数存在，失败返回 `None`
+- [ ] `fetch_dependencies(owner, name)` 函数存在，失败返回 `{}`
+- [ ] 覆盖了 `requirements.txt`, `environment.yml`, `setup.py`, `setup.cfg`, `Pipfile`, `pyproject.toml`
+- [ ] 不抛出异常
+- [ ] `python repo_fetcher.py` 自测可运行
+
+---
+
+> 本文档随代码同步维护。如有疑问或需要修改契约，请甲乙双方当面确认后再改代码，避免信息不对称。

流程架构图.md

@@ -0,0 +1,129 @@
+# ResearchRadar 流程架构图
+
+```
+用户输入 arxiv URL
+       │
+       ▼
+┌──────────────────────────────────────────────────────┐
+│  [1/5] 论文信息获取 (Workflow · 甲)                    │
+│  paper_fetcher.fetch_paper_info()                     │
+│  → arxiv API XML 解析                                 │
+│  → {title, abstract, authors, categories, published}  │
+│  含重试: 429/503 自动退避重试 3 次                      │
+└────────────────────────┬─────────────────────────────┘
+                         │
+                         ▼
+┌──────────────────────────────────────────────────────┐
+│  [2/5] 宽泛 GitHub 搜索 (Workflow · 甲)                │
+│                                                      │
+│  ① _extract_broad_queries(title, abstract)           │
+│     └─ LLM 生成 6-8 个精准英文搜索词                   │
+│        (失败则降级为规则提取 fallback)                  │
+│                                                      │
+│  ② repo_searcher.search_repos(queries)               │
+│     └─ GitHub API 搜索，每词取 top 5                  │
+│     └─ 按 full_name 去重，按 stars 降序               │
+│  → 10~36 个候选仓库                                   │
+└────────────────────────┬─────────────────────────────┘
+                         │
+                         ▼
+┌──────────────────────────────────────────────────────┐
+│  [2.5] LLM 过滤不相关仓库 (新增 · 乙)                   │
+│  _filter_repos(title, abstract, repos)               │
+│  ├─ >20 个仓库 → 按 stars 取 top 20 送给 LLM          │
+│  ├─ LLM 判断每个仓库是否与论文方向相关                    │
+│  ├─ 剔除不相关仓库                                     │
+│  └─ 过滤后 <2 个 → 回退到原始结果                       │
+│  → 15~17 个相关仓库                                   │
+└────────────────────────┬─────────────────────────────┘
+                         │
+                         ▼
+┌──────────────────────────────────────────────────────┐
+│  [3/5] 方法族归纳 (Agent 1 · 乙)                      │
+│  direction_analyzer.analyze_direction()              │
+│  输入: 论文 title + abstract + 过滤后的仓库列表         │
+│  LLM 分析仓库 description/topics/stars →              │
+│  输出:                                               │
+│  ├─ subfield (子领域定位)                              │
+│  ├─ subfield_trend (趋势判断)                         │
+│  ├─ method_families[]                                │
+│  │   ├─ family_name, description                    │
+│  │   ├─ matched_repos[] ← 仓库归属哪个方法族           │
+│  │   └─ search_queries[]  ← 该族精准搜索词            │
+│  └─ broad_queries[]  ← 未覆盖方向的宽泛搜索词          │
+└────────────────────────┬─────────────────────────────┘
+                         │
+                         ▼
+┌──────────────────────────────────────────────────────┐
+│  [4/5] 仓库筛选 + 方法族映射 (调度器 · 乙)              │
+│  ├─ 从 Agent 1 的 matched_repos 建立                  │
+│  │   full_name → family_name 映射                    │
+│  ├─ classified: 有方法族归属的仓库 (按 stars 排序)     │
+│  ├─ unclassified: 未归类的仓库 (按 stars 排序)         │
+│  └─ 取 top 5 作为最终评估候选                          │
+└────────────────────────┬─────────────────────────────┘
+                         │
+                         ▼
+┌──────────────────────────────────────────────────────┐
+│  [5/5] 仓库详情获取 + 评估 (Agent 2 · 乙) [并行]      │
+│                                                      │
+│  对 5 个候选仓库，ThreadPoolExecutor 并行执行:           │
+│                                                      │
+│  ① repo_fetcher.fetch_readme(owner, name)            │
+│     └─ GitHub Contents API，base64 解码               │
+│                                                      │
+│  ② repo_fetcher.fetch_dependencies(owner, name)      │
+│     └─ 检查 11 种依赖文件类型                          │
+│                                                      │
+│  ③ repo_evaluator.evaluate_repo()                    │
+│     └─ LLM 六维度评分 (可复现性 80 + 适配度 20)        │
+│        ├─ 环境配置 0-15                               │
+│        ├─ 文档质量 0-20                               │
+│        ├─ 代码可用性 0-20                              │
+│        ├─ 社区活跃度 0-10                              │
+│        ├─ 依赖健康度 0-15                              │
+│        └─ 对比实验适配度 0-20                          │
+│                                                      │
+│  按 overall_score 降序排列                            │
+└────────────────────────┬─────────────────────────────┘
+                         │
+                         ▼
+┌──────────────────────────────────────────────────────┐
+│  汇总 → format_report() (app.py)                     │
+│                                                      │
+│  生成 Markdown 研报，共 5 部分:                         │
+│  一、论文信息 (arXiv 链接、作者、分类)                   │
+│  二、研究方向全景                                       │
+│      ├─ 子领域定位 + 趋势                               │
+│      ├─ 方法族谱系表                                    │
+│      └─ 方法族开源覆盖度 (哪些已有实现/哪些是空白)         │
+│  四、开源实现评估排名 (六维度评分明细)                    │
+│  五、对比实验推荐总结 (🟢就绪 / 🟡需修改 / 🔴仅参考)      │
+└──────────────────────────────────────────────────────┘
+```
+
+## 核心设计决策
+
+> **先搜仓库 → 再基于实际数据让 Agent 分析**，而非让 LLM 凭记忆编造方法族。
+> Agent 是"分析整理工具"，不是"知识库"。
+
+## 模块分工
+
+| 模块 | 负责 | 类型 | 说明 |
+|------|:----:|:----:|------|
+| `paper_fetcher.py` | 甲 | Workflow | arxiv API 获取论文元信息，含重试逻辑 |
+| `repo_searcher.py` | 甲 | Workflow | GitHub API 关键词搜索，去重排序 |
+| `repo_fetcher.py` | 甲 | Workflow | 获取仓库 README + 11 种依赖文件 |
+| `direction_analyzer.py` | 乙 | Agent 1 | LLM 基于仓库数据归纳方法族谱系 |
+| `repo_evaluator.py` | 乙 | Agent 2 | LLM 六维度评分 (可复现性 + 适配度) |
+| `run.py` | 乙 | 调度器 | 串联全流程 [1/5]→[5/5] + 关键词生成 + 过滤 |
+| `app.py` | 乙 | 界面 | Gradio Web UI + Markdown 研报格式化 |
+| `llm_utils.py` | 乙 | 公共 | DeepSeek API 客户端 + JSON 安全解析 + 输出校验 |
+
+## 研报输出结构
+
+1. **论文信息** — 标题、arXiv 链接、作者、发表时间、分类
+2. **研究方向全景** — 子领域定位、当前趋势、方法族谱系表、开源覆盖度
+3. **方法族开源覆盖度** — 哪些方法族已有实现、哪些是研究空白
+4. **开源实现评估排名** — 每个仓库六维度评分明细 + 风险点 + 对比实验建议
+5. **对比实验推荐总结** — 🟢可直接使用 / 🟡需少量修改 / 🔴仅适合参考