# Reddit Scraper Benchmark v1

> Agent: reddit-scraper
> Phase: Digest (Phase 2)
> 评估维度: 6 | 满分: 100 | 目标线: ≥ 95

---

## 1. 评估维度总览

| 维度 | 满分 | 权重 | 说明 |
|------|------|------|------|
| 数据准确性 | 100 | 20% | Reddit API / HTML / RSS 数据抓取与字段映射的准确性，含端点、必填字段、数据映射 |
| 反爬策略 | 100 | 20% | 请求频率控制、UA 轮换、降级与重试机制的健壮性 |
| Schema 标准化 | 100 | 15% | 输出数据结构严格符合 agent.md 定义的 schema，字段完整且一致 |
| 数据清洗与过滤 | 100 | 15% | 去重、NSFW/低质量/删除内容过滤、阈值裁剪、内容完整性保证 |
| 戏剧性内容提取 | 100 | 20% | drama_score 计算、conflict_type 映射、戏剧性标签与下游脚本价值提取 |
| 合规与伦理 | 100 | 10% | 遵守 robots.txt 精神、频率限制、隐私与内容安全规范 |
| **总分** | **100** | **100%** | 加权计算，目标线 ≥ 95 |

---

## 2. 维度 1：数据准确性 (20%)

### 评分细则

| 子项 | 分值 | 评分标准 |
|------|------|----------|
| API 端点正确性 | 30 | 正确调用 `reddit.com/r/{subreddit}/{sort}.json`；搜索使用 `restrict_sr=1`；评论使用 `/comments/{post_id}.json`；支持 `after` 分页与 `time` 参数组合 |
| 字段提取完整率 | 40 | 必填字段 (`post_id`, `title`, `score`, `source_url`, `crawl_time`) 100% 存在且非空；评论字段 (`comment_id`, `author`, `body`, `score`, `parent_id`) 完整 |
| 数据映射准确性 | 30 | `permalink` → `source_url`，`score` → `engagement.score`，`num_comments` → `engagement.num_comments`，`created_utc` 时间戳正确，单位无误 |

### 减分项
- 端点拼写错误或漏传必要参数（如 `limit`、`after`、`restrict_sr`）: -10 ~ -30
- 字段映射错误（如把 `score` 当成 `upvotes`）: -15 ~ -40
- RSS/HTML 提取遗漏核心字段且未标注说明: -5 ~ -20

---

## 3. 维度 2：反爬策略 (20%)

### 评分细则

| 子项 | 分值 | 评分标准 |
|------|------|----------|
| 请求频率控制 | 35 | 单 IP 请求间隔 ≥ 2 秒，无突发请求（>20 次/分钟），具备随机 jitter (2–5s) |
| 请求头伪装 | 30 | 使用真实浏览器 User-Agent 并轮换（≥2 条），包含 `Accept: application/json`，必要时模拟完整 Headers |
| 降级与重试 | 35 | 遇到 429/403/503 时执行指数退避重试（2s → 5s → 15s，最多 3 次）；JSON API 不可用时降级到 `old.reddit.com` HTML 或 RSS |

### 减分项
- 无请求延迟或延迟 < 1 秒: -20 ~ -35
- 单一 UA 未轮换: -10 ~ -30
- 未处理 429/403 直接失败: -15 ~ -35
- 无降级策略或降级链路不完整: -10 ~ -20

---

## 4. 维度 3：Schema 标准化 (15%)

### 评分细则

| 子项 | 分值 | 评分标准 |
|------|------|----------|
| 结构一致性 | 40 | 所有输出记录使用统一嵌套结构：`source`, `content`, `engagement`，且字段层级正确；评论以数组形式存在于 `comments` 字段 |
| 字段命名规范 | 35 | 严格使用英文 snake_case，与 agent.md 输出 schema 完全一致（如 `post_id`, `subreddit`, `upvote_ratio`） |
| 可空与默认值 | 25 | 缺失字段使用 `null` 而非空字符串或缺失；`awards` 缺失默认 `0`；`upvote_ratio` 缺失默认 `null`；`link_post` 标记规范 |

### 减分项
- 结构层级混乱或字段拼写错误: -10 ~ -40
- 未使用 snake_case 或与 schema 定义冲突: -10 ~ -35
- 缺失字段未正确处理（导致下游解析失败）: -5 ~ -25

---

## 5. 维度 4：数据清洗与过滤 (15%)

### 评分细则

| 子项 | 分值 | 评分标准 |
|------|------|----------|
| 基础过滤 | 35 | 按 `min_score` 过滤生效；`is_nsfw=True` 被剔除（除非显式允许）；`[deleted]` / `[removed]` 作者与正文被移除 |
| 去重 | 30 | 以 `post_id` 为唯一键去重，重复记录仅保留第一条有效数据 |
| 内容完整性 | 35 | `title` 不能为空；`selftext` 为空时标记为 `link_post` 并保留 `url`；单次采集输出有效记录数 ≥ 需求量的 80% |

### 减分项
- 未按 `min_score` / `exclude_nsfw` 过滤: -10 ~ -35
- 存在重复 `post_id`: -10 ~ -30
- 空标题或缺失 body 未正确标记为 `link_post`: -10 ~ -35

---

## 6. 维度 5：戏剧性内容提取 (20%)

### 评分细则

| 子项 | 分值 | 评分标准 |
|------|------|----------|
| Drama Score 计算 | 40 | 正确应用公式：`base_drama + comment_density + conflict_bonus`，结果限定在 0–100 之间，计算可复现 |
| Conflict Type 映射 | 35 | 基于子版块和关键词正确映射枚举值：AITA → `moral_dilemma`；relationship_advice → `betrayal`/`trust_issue`；funny → `observational_humor`/`absurdist` |
| 标签与潜在脚本价值 | 25 | 输出 `drama_tags` 数组、`hook_strength` (0–10)、`viral_elements` 标签等下游脚本可用字段 |

### 减分项
- drama_score 计算逻辑错误或结果超出 0–100: -15 ~ -40
- conflict_type 映射明显错误（如 funny 映射为 `betrayal`）: -10 ~ -35
- 任务参数要求计算 `drama_score` 但未输出戏剧性相关字段: -10 ~ -25

---

## 7. 维度 6：合规与伦理 (10%)

### 评分细则

| 子项 | 分值 | 评分标准 |
|------|------|----------|
| 平台合规 | 40 | 遵守 Reddit `robots.txt` / Crawl-delay 精神，控制频率不造成服务器压力；不绕过登录墙抓取非公开内容 |
| 隐私保护 | 30 | 不采集私信、真实身份信息、精确地理位置；对个人信息做去标识化处理 |
| 内容安全 | 30 | 对涉及自杀、自残、暴力的内容增加安全审核标记或过滤，不适合直接作为娱乐素材输出 |

### 减分项
- 高频请求对目标服务器造成明显压力（如 >30 次/分钟且无退避）: -15 ~ -40
- 采集非公开内容或用户隐私信息: -30（一票否决）
- 未对高风险内容做安全处理: -10 ~ -30

---

## 8. 总分计算方式

```
总分 = 维度1 * 0.20
     + 维度2 * 0.20
     + 维度3 * 0.15
     + 维度4 * 0.15
     + 维度5 * 0.20
     + 维度6 * 0.10
```

- **优秀**: 95–100 分（目标线，可进入下游生产使用）
- **良好**: 85–94 分（需小幅度修正）
- **及格**: 70–84 分（存在明显缺陷，需返工）
- **不及格**: < 70 分（不符合基本 skill 要求）

---

## 9. 与 train/test 数据集的关联

- `train.jsonl` 和 `test.jsonl` 中的每条记录均包含 `dimensions` 和 `score`。
- grader 在评估模型输出时，应参照本标准进行逐项打分。
- `grader_hints` 提供了该样本的关注检查点，供自动化或人工评分时聚焦重点。

---

## 10. 快速检查清单 (Quick Checklist)

- [ ] 使用 `https://www.reddit.com/r/{subreddit}/hot.json` (或等价 sort) 并携带正确 headers
- [ ] 包含 `after` 分页逻辑与 `time` 参数的正确组合
- [ ] 轮换真实浏览器 User-Agent 字符串
- [ ] 执行 ≥ 2s 延迟且 ≤ 20 req/min
- [ ] 遇到 429/403 时指数退避重试，失败后再降级到 old.reddit / RSS
- [ ] 提取所有必填字段到统一 schema
- [ ] 过滤 NSFW、`[deleted]`/`[removed]`、低于 min_score 的帖子
- [ ] 按 `post_id` 去重
- [ ] 空 `selftext` 正确标记为 `link_post` 并保留外部 `url`
- [ ] 评论树映射正确，含 `comment_id`、`parent_id`、`score`
- [ ] 计算 `drama_score` 与 `conflict_type` 并限定在合理范围
- [ ] 遵守平台 ToS 与登录墙边界
- [ ] 对高风险内容进行安全过滤或标记

---

*由 Digester Agent 生成 | 验收标准: 6 维度完整对齐 knowhow_v1.md ✅ | 满分 100 目标线 ≥95 ✅*