FacereDataset/docs/plans/oshwhub_batch50.md

oshwhub 扩抓批 50：执行计划

创建：2026-04-29 目标：在已落库的 15 项（5 Pro + 10 Std）基础上，再抓 50 个高质量项目 候选清单：data/state/oshwhub_batch50_candidates.jsonl（50 行） 承接：docs/sources/oshwhub_listing_full.md（全量索引盘点）

---

1. 目标

• 把 corpus 从 15 项扩到 65 项，覆盖 Pro + Std + Pro 3.x + Pro 2.x 各形态
• 在 LFS 1 TB 红线内，先做 ~3-4 GB 量级的中等规模验证
• 结束后用 license 白名单评估这 50 项里有多少能进 Forge 投影
• 暴露 ≥ top-5 才会出现的 corner case（例如：超大 Pro 项目、私有附件、跨账号 fork）

显式不做：详情页全量扫描（19h 工作量，留待后续按 A 档全池一次性做）；下游 KiCad 转换（Phase 3 还在做）。

---

2. 候选池筛选标准

数据源：data/state/oshwhub_listing_full.jsonl（33,695 项全量 listing 索引）

硬过滤：

• grade >= 3 AND like >= 10（A 档）
• uuid 不在已抓 15 项内

排序：复合质量打分

score = like*3 + star + fork*2 + views/100 + comments_count*2 + grade*50

多样性约束：

• 单作者上限 2 个项目（避免 course-examples / 45coll 等高产账号占满）
• Pro / Std 25:25 平衡（Pro 是新平台增长焦点，Std 是 7 年质量积累）

---

3. 选出的 50 项概况

维度	值
总数	50（25 Pro + 25 Std）
唯一作者	43
Max 单作者	2
like 区间	min=246 / median=554 / max=2137
view 区间	min=54k / median=117k / max=362k
grade 分布	4: 33 项, 3: 17 项

Pro 头部（前 5）：HelloWord-Keyboard 2137 likes / STM32 桌面宠物 / OV-Watch 智能手表 / mini 加热台 / ESP-SparkBot

Std 头部（前 5）：触摸调光雪花灯 1036 likes / 桌面可调电源 / 立创 EDA PCB 直尺 / 自平衡莱洛三角 / PN532 NFC

完整名单见 data/state/oshwhub_batch50_candidates.jsonl。

---

4. 执行步骤

Step 0 — 候选池冻结 ✅

data/state/oshwhub_batch50_candidates.jsonl 已生成，作为本次批的"事实档案"。后续就算重排序也以这份为准。

Step 1 — 详情页抓 license（~5 min，QPS=0.5）

只对这 50 项扫详情页，提取 license / 完整 attachments 列表 / 原始描述。 不在这一步下载附件、不下源工程，只是获取每项的 metadata 全集。

PYTHONUNBUFFERED=1 uv run python -u -m crawlers.oshwhub \
  --uuids "$(jq -r .uuid data/state/oshwhub_batch50_candidates.jsonl | paste -sd,)" \
  --no-files \
  --out data/raw/oshwhub

目前 crawl_one 已经会落 metadata.json + description.md + cover；--no-files 跳过附件。

预期产出：50 个 data/raw/oshwhub/<uuid>/metadata.json，含 license 字段。

Step 2 — license 分布盘点

写个一次性脚本读 50 份 metadata.json，统计 license 分布。这一步只做盘点不做过滤——按 CLAUDE.md "研究用、不分发" 原则，所有 license 都入库。下游 Forge 投影时再用白名单过滤。

uv run python - <<'EOF'
import json, glob, collections
licenses = collections.Counter()
for p in glob.glob("data/raw/oshwhub/*/metadata.json"):
    m = json.load(open(p))
    if m["uuid"] in batch_50_uuids:
        licenses[m.get("license") or "<none>"] += 1
print(licenses)
EOF

预期会有大量 NC-SA / GPL（参考已抓 5 Pro：5/5 都是 GPL/NC-SA）。

Step 3 — Pro 子集预检 + 抓源（~30-60 min）

25 个 Pro 项目里要先判 3.x vs 2.x（branch_uuid 是否 null），然后对应走 modern / legacy 路径：

PYTHONUNBUFFERED=1 uv run python -u -m crawlers.oshwhub \
  --backfill-pro-source \
  --uuids "$(jq -r 'select(.origin=="pro") | .uuid' \
              data/state/oshwhub_batch50_candidates.jsonl | paste -sd,)" \
  --pro-cookie ~/.secrets/pro-lceda-cookie-header.txt

时间预算（已应用 chain replay sleep 优化，commit 1e06ba6）：

• 小型项目（chain ~10）：~30s 各
• 中型（chain ~30-50）：~1-2 min 各
• 大型（chain ~100+）：~3-5 min 各
• 超大（X86 量级 chain ~700）：~3-5 min 各（CDN 部分降到 0.2s/req）

按已抓 5 项观察，预期 25 项里：

• ~22 个 Pro 3.x（chain replay）
• ~3 个 Pro 2.x（plaintext dataStr）

Step 4 — Std 子集抓源（~30 min）

PYTHONUNBUFFERED=1 uv run python -u -m crawlers.oshwhub \
  --backfill-source \
  --uuids "$(jq -r 'select(.origin=="std") | .uuid' \
              data/state/oshwhub_batch50_candidates.jsonl | paste -sd,)"

每项 ~30s（QPS=0.2 / 5s sleep × 几个 API 调用），25 项 ≈ 12-15 min。

Step 5 — 附件下载（按需，可选）

附件（Gerber / STEP / PDF / 视频）默认存 LFS，但视频占大头（之前 Phase 1 实测 mp4+qt 占 54%）。 建议加 --skip-ext mp4,qt,mov 节省 30-50% 体积。

PYTHONUNBUFFERED=1 uv run python -u -m crawlers.oshwhub \
  --uuids "$(jq -r .uuid data/state/oshwhub_batch50_candidates.jsonl | paste -sd,)" \
  --out data/raw/oshwhub
  # 注：当前 crawler 没有 --skip-ext 选项；要加得改 crawl_one；如果偷懒就先全抓再人工删

这一步没那么紧迫，可以挪到 Step 3/4 完成后单独跑。

Step 6 — 验收 + 记录

跑 scripts/build_index.py 重建 projects.md，更新 log.md，把统计信息写到 docs/plans/oshwhub_batch50.md 末尾"实施结果"段。

---

5. 资源预算

项	估算	备注
API 调用	~600 次	50 详情 + 25×3 Pro meta + 25 Std API + chain blobs
时间	~1.5-2 小时	远低于之前估算的 19h（因为只 50 项 + sleep 优化）
存储（源工程）	~1.5 GB	Pro 平均 30 MB、Std 平均 15 MB
存储（附件，估）	2-3 GB	含视频；不含视频估 1 GB
总 LFS 增量	~3-4 GB	远低于现有 LFS 余量
网络下行	~4 GB	大部分走 LFS

距离 200 GB"对象存储迁移决策点"还很远。

---

6. 风险与预案

风险	概率	影响	预案
Pro cookie 过期半路	中	卡住 Pro 抓取	重抓 cookie；爬虫已有 oshwhub_pro_failed.jsonl 重试机制（未实现，现在失败只 stderr）
单个 Pro 项目超大（X86 量级 ~500 MB）	中	LFS 单项膨胀	设置 size cap，超过 200 MB 跳过 + 记 state
license 全是 NC-SA → 下游 Forge 投影门槛低	高	Forge 阶段才发现	提前在 Step 2 盘点；本批不做过滤，只入库
某个项目附件含 mp4 视频 → 附件总量爆炸	中	多消耗 1-2 GB LFS	加 --skip-ext mp4,qt,mov 选项（需小改 crawler）
抓 50 项过程中触发反爬 / 限流	低	中途中断	已有 5s/req QPS；如果触发，加 jitter；从中断点续

---

7. 验收标准

• data/raw/oshwhub/ 下新增 ≥ 45 个项目目录（允许 ≤ 5 项失败）
• 每个新增项目的 metadata.json 含 license、source_format、source_path
• Pro 25 项里 3.x / 2.x 分类正确（看 source_format 字段）
• LFS 增量 ≤ 5 GB
• projects.md 自动重建后包含新 50 项
• log.md 顶部一条总结性日志

---

8. 后续

成功结束后的下一步候选：

1. license 详情扫描全 A 档 —— 把 license 信息覆盖到 2,806 项 A 档候选池，为下一次扩抓提供过滤条件
2. 扩抓批 200（按 license 白名单 + 同样多样性策略）
3. Pro 工程二进制图（IMAGE/）补抓 —— 当前的真实数据 gap，要不要补取决于下游需求
4. 风控压测 —— 在某一批做并发提速试验，找 oshwhub / pro.lceda.cn 的限流真上限