Initial skeleton for FacereDataset
Why:
- Facere 需要一个统一的开源硬件设计数据源，用于训练专有模型与
构建检索型知识库。仓库先立骨架，把合规红线、数据 schema 要求、
爬虫规约写在 CLAUDE.md 里，避免后续实现时各站点爬虫写法发散。
- plan.md 用阶段化路线图明确"先广度后深度、先合规后规模"的策略，
让放量前必须经过 Charles 对齐一次，降低存储与法律风险。
Contents:
- README.md: 项目简介、数据源表、仓库结构、合规声明
- CLAUDE.md: 项目级 Claude 指令（工作流 / 爬虫规约 / 合规红线）
- plan.md: Phase 0-6 分阶段计划 + 风险与未决项
- log.md: 首条日志（调研 + 初始化记录）
- .gitignore: 排除 data/{raw,processed,state} 内容，保留目录占位
- 目录骨架: crawlers/ schemas/ scripts/ data/ docs/sources/
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Zhang Jiahao
135
plan.md
Normal file
135
plan.md
Normal file
@@ -0,0 +1,135 @@
|
||||
# FacereDataset 爬取与建设计划
|
||||
|
||||
**维护**：Charles
|
||||
**最近更新**：2026-04-23
|
||||
**状态**：Phase 0 已完成（仓库骨架），Phase 1 待启动
|
||||
|
||||
---
|
||||
|
||||
## 总体策略
|
||||
|
||||
**先广度后深度，先合规后规模。**
|
||||
|
||||
1. 每个数据源先做一份 "可行性调研"（一页纸，放 `docs/sources/<site>.md`），明确：访问形式、速率限制、许可证分布、ToS 摘要、数据字段覆盖。
|
||||
2. 每个站点实现一个最小 MVP 爬虫，**单项目跑通** → 然后才全量化。
|
||||
3. 全量化之前先跟 Charles 对齐抽样结果与存储开销。
|
||||
4. 所有站点输出统一到 `schemas/project.schema.json` 定义的结构，不要让下游消费者去适配 N 种 schema。
|
||||
|
||||
---
|
||||
|
||||
## Phase 0 — 仓库骨架 ✅
|
||||
|
||||
- [x] `README.md` / `CLAUDE.md` / `plan.md` / `log.md`
|
||||
- [x] 目录骨架 `crawlers/ schemas/ scripts/ data/ docs/`
|
||||
- [x] `.gitignore`（排除 `data/raw` `data/processed` `data/state` `venv` `__pycache__`）
|
||||
- [x] 初始提交并推送
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — 立创开源平台（oshwhub.com）MVP
|
||||
|
||||
**目标**：跑通 10 个项目的完整抓取，验证 schema。
|
||||
**预计工期**：2-3 天（人+Claude 协作）
|
||||
|
||||
### 1.1 调研（0.5 天）
|
||||
|
||||
- [ ] 确认 API 入口：Next.js SPA，首页 800KB HTML 里内联了首屏 props，但翻页/详情靠 `/_next/data/<buildId>/...json` 或 XHR。需要：
|
||||
- 打开浏览器 DevTools，录一段 explore → 详情 → 下载的 network trace，提取 API endpoints（推荐 `chrome-devtools` MCP）
|
||||
- 核对 `sitemap.xml` 作为项目 URL 源（已确认存在）
|
||||
- [ ] 许可证字段位置：详情页有"开源协议"显示，确认对应 JSON key
|
||||
- [ ] 确认 sitemap 完整性：是否覆盖全部公开项目；若否，fallback 用 `/explore?sort=hot&page=N`
|
||||
|
||||
### 1.2 爬虫 MVP（1 天）
|
||||
|
||||
`crawlers/oshwhub/`：
|
||||
|
||||
- [ ] `discover.py` — 从 sitemap + explore 列表产出项目 ID stream（去重、断点续）
|
||||
- [ ] `fetch.py` — 单项目抓取：详情 JSON、预览图、可下载文件（原理图 JSON / 工程压缩包）
|
||||
- [ ] `normalize.py` — 映射到统一 schema，写 `data/processed/oshwhub/projects.jsonl`
|
||||
- [ ] `__main__.py` — CLI：`--limit N --since DATE --resume`
|
||||
- [ ] 速率：默认 QPS 0.5，遇 429/5xx 指数退避
|
||||
|
||||
### 1.3 验收（0.5 天）
|
||||
|
||||
- [ ] 跑 `--limit 10` 成功，10 条 jsonl 通过 schema 校验（`scripts/validate.py`）
|
||||
- [ ] 抽查 3 条人工确认字段正确
|
||||
- [ ] 产出 `docs/sources/oshwhub.md` 调研笔记
|
||||
|
||||
### 1.4 放量（视情况）
|
||||
|
||||
- [ ] 估算全量规模（项目数 × 平均附件大小）
|
||||
- [ ] 跟 Charles 对齐存储方案（LFS vs S3 vs 单机盘）
|
||||
- [ ] 分批跑（每批 1-5 万项目），产出进度报告
|
||||
|
||||
---
|
||||
|
||||
## 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 万 / 全量？
|
||||
Reference in New Issue
Block a user