Facere/FacereDataset

Files

Zhang Jiahao 5ffa10f256 Phase 1 MVP: crawl 10 high-quality oshwhub projects into LFS

Why:
- Charles 指定：先爬 10 个高质量项目存 Gitea LFS，一个项目一个文件夹，
  保留原文件和 URL。先以小批量验证 schema + LFS 流水线，放量前再拍板
  存储规模。

What:
- crawlers/oshwhub: 列表 API (`/api/project?sort=hot`) + SSR HTML 解析，
  一次性产出 metadata / description / cover / files / _urls
- schemas/project.schema.json: 跨源统一 schema
- docs/sources/oshwhub.md: API 入口 / 字段映射 / 陷阱调研
- pyproject.toml: httpx[http2] 单依赖
- .gitattributes: data/raw/**/files/** 一律走 LFS（规则写窄，避免误伤 schemas/*.json 等）
- .gitignore: 移除 data/raw/* 排除（改走 LFS 入库）

10 个项目覆盖：调试器 / 加热台 / 盖革计数器 / 数控电源 / 焊台 /
智能手表 / USB 测电流 / ZVS 感应加热 / AI 开发板 / 红外热成像。
共 52 附件 ≈ 524 MB 入 LFS，筛选判据 grade=4 & likes>=100 & 多样性。

Known gaps（见 plan.md § Phase 1.4）：
- EasyEDA 源 JSON 需登录 (u.lceda.cn)，v0.1 跳过
- fs-web-stream.jlc.com 的工程源下载未测
- scripts/validate.py 自动 schema 校验未实现

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-04-23 19:34:09 +08:00

5.0 KiB

Raw Blame History

FacereDataset 爬取与建设计划

维护：Charles 最近更新：2026-04-23 状态：Phase 0 已完成（仓库骨架），Phase 1 待启动

总体策略

先广度后深度，先合规后规模。

每个数据源先做一份 "可行性调研"（一页纸，放 docs/sources/<site>.md），明确：访问形式、速率限制、许可证分布、ToS 摘要、数据字段覆盖。
每个站点实现一个最小 MVP 爬虫，单项目跑通 → 然后才全量化。
全量化之前先跟 Charles 对齐抽样结果与存储开销。
所有站点输出统一到 schemas/project.schema.json 定义的结构，不要让下游消费者去适配 N 种 schema。

Phase 0 — 仓库骨架 ✅

README.md / CLAUDE.md / plan.md / log.md
目录骨架 crawlers/ schemas/ scripts/ data/ docs/
.gitignore（排除 derivative 目录）/ .gitattributes（LFS 规则）
初始提交并推送

Phase 1 — 立创开源平台（oshwhub.com）MVP ✅ 首批完成

目标：跑通 10 个项目的完整抓取，验证 schema。实际：10/10 成功，52 附件，524 MB 入 LFS。

1.1 调研 ✅

列表 API /api/project?page=N&pageSize=M&sort=hot（无鉴权）
详情页 SSR HTML 嵌入 escaped JSON，含 attachments 数组与 license
附件 CDN image.lceda.cn/{src} 直连
docs/sources/oshwhub.md 调研笔记

1.2 爬虫 MVP ✅

crawlers/oshwhub/crawler.py：

列表分页 + 质量打分排序
HTML 解析：title / description / license / attachments
每项目目录：metadata / description / cover / files / _urls
QPS ≤ 0.5，UA 真实声明

1.3 验收 ⏳

10/10 成功，产出符合 schemas/project.schema.json
待 Charles：随机抽查 2-3 条对照原站
scripts/validate.py 自动 schema 校验（未写，后续补）

1.4 放量（待决策）

Charles 定目标规模：50 / 500 / 5000 / 全量 12493
估算存储：52 附件 / 10 项目 ≈ 52MB/项目 → 全量约 650GB（Gitea LFS 需评估）
未解决：
- fs-web-stream.jlc.com 工程源下载路径（未测）
- u.lceda.cn EasyEDA 工程 JSON（需登录，v0.1 跳过）
- 增量更新：updated_at 变动检测 + LFS prune 策略

Phase 2 — GitHub 开源硬件 repo

目标：抓 KiCad / EasyEDA / Eagle 格式的公开 repo。

用 GitHub Code Search API 查 extension:kicad_pcb / extension:sch / filename:*.epro 等
过滤 star ≥ N（降噪，可调）
抓 repo 元数据 + 文件树 + 关键文件，不 clone 全仓（省带宽）
License 从 repo LICENSE 文件 + GitHub API license 字段双取
MCP：优先 mcp__github__* 工具；大规模批量可切 gh api + gitingest

预计工期：3-5 天。

Phase 3 — Hackaday.io

探测是否有公开 API（/api/v1/ 曾经存在，需 key）
若无 API：解析 explore 列表 + project/log 页面
重点抓项目叙事（README / build log）——这是 LLM 语料的高价值部分

预计工期：3 天。

Phase 4 — 长尾站点

并列小项目，每个 0.5-1 天：

CERN OHR（ohwr.org）—— 高质量、CERN-OHL 许可清晰
Wikifactory
Open Hardware Park
Tindie（仅商品元数据，文件多半不公开）
Instructables 硬件类目（文本叙事为主）

Phase 5 — 数据清洗与派生

去重：sha256(files) + (title, author) 模糊匹配
质量打分：字段完整度 + 文件大小合理性 + license 有效性
派生数据集：
- components.jsonl：从 BOM 汇总常见元件 → 成本曲线
- subcircuits.jsonl：常见子电路模板（电源、USB、MCU 最小系统）
- narratives.jsonl：项目叙事文本语料（给 LLM 预训练）
生成 README 级统计：项目总数、许可证分布、站点覆盖

Phase 6 — 持续运营

增量爬取 cron：每站点每周扫一次新增/更新
数据发布：版本化 snapshot（v0.1, v0.2, ...），Release tag 到 Gitea
反馈回路：模型训练团队发现脏数据 → issue → 过滤规则下沉到 scripts/

风险与未决项

风险	影响	缓解
oshwhub 反爬加强	卡住 Phase 1	切 lightpanda/真 Chrome；降速；部分内容弃
许可证字段缺失 / 模糊	下游训练合规风险	默认剔除 `license: unknown`；建 whitelist
单个项目附件过大（>100MB）	存储爆炸	Phase 1 调研时统计分布；大文件走外部 OSS，记录 URL 不本地化
GitHub API rate limit	Phase 2 慢	使用已登录 `gh` token；必要时换 fine-grained PAT
站点改版	爬虫失效	爬虫带 schema 自检，HTML 结构变化时告警

未决（需要 Charles 定）：

数据存储方案：本地盘（够吗？）、Gitea LFS、或外挂对象存储？
是否要保留图片/Gerber/STEP 的二进制，还是只存 URL？
目标规模：第一版想要 1 万 / 10 万 / 全量？