From 53b76489842e98d4d03bdab92a47276eecf04bb8 Mon Sep 17 00:00:00 2001
From: Zhang Jiahao <charles@localhost.localdomain>
Date: Thu, 23 Apr 2026 19:51:24 +0800
Subject: [PATCH] Add HF bshada/open-schematics to Phase 1 plan
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Why:
- Charles 点名把该 HF 数据集纳入第一批。它是已预处理包（非待爬网站），
  和 oshwhub 的抓取逻辑不一样，先把决策面在 plan 里讲清楚，再动手拉。
- 与 oshwhub (EasyEDA 生态) 互补，补 KiCad 原生路径。

What:
- docs/sources/hf_bshada_open_schematics.md: 调研文档
  - 78 parquet shards, 6.4 GB 总量
  - CC-BY-4.0 商用友好
  - 字段：.kicad_sch 源 / PNG / 组件列表 / JSON / YAML / name / desc
  - 镜像方案（整包存 data/external/..., 不拆 per-project）
  - .gitattributes 建议（data/external/**/*.{parquet,png} → LFS）
- plan.md §1.5: 阶段说明 + 待 Charles 批 6.4 GB 预算
- README.md 数据源表: 加一行
- log.md: 本次记录

下载未触发，等 Charles 拍板。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md                                 |   3 +-
 docs/sources/hf_bshada_open_schematics.md | 107 ++++++++++++++++++++++
 log.md                                    |  26 ++++++
 plan.md                                   |  21 ++++-
 4 files changed, 154 insertions(+), 3 deletions(-)
 create mode 100644 docs/sources/hf_bshada_open_schematics.md

diff --git a/README.md b/README.md
index 7bc3718..1f40b08 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,8 @@
 
 | 站点 | URL | 覆盖 | 许可 | 抓取复杂度 |
 |------|-----|------|------|-----------|
-| 立创开源平台 | oshwhub.com | 国内 PCB/EDA 设计 ~百万量级 | 多为 CC-BY-SA / 作者自定 | 中（SPA，需 API 逆向） |
+| 立创开源平台 | oshwhub.com | 国内 PCB/EDA 设计 ~12K 精品 | 多为 GPL 3.0 / Public Domain / CC-BY-SA | 中（SPA，需 API 逆向） |
+| **HF** `bshada/open-schematics` | huggingface.co | 10K+ KiCad 已预处理 schematics | CC-BY-4.0 | 极低（整包镜像） |
 | 嘉立创 EDA 样例 | lceda.cn/example | 官方示例 | 开放 | 低 |
 | Hackaday.io | hackaday.io | 项目叙事 + 文件 | 作者自定 | 中 |
 | GitHub | github.com | KiCad/EasyEDA repo | 各 repo 自定 | 低（gh API） |
diff --git a/docs/sources/hf_bshada_open_schematics.md b/docs/sources/hf_bshada_open_schematics.md
new file mode 100644
index 0000000..bf75e33
--- /dev/null
+++ b/docs/sources/hf_bshada_open_schematics.md
@@ -0,0 +1,107 @@
+# HF Dataset: bshada/open-schematics
+
+**URL**：https://huggingface.co/datasets/bshada/open-schematics
+**调研日期**：2026-04-23
+**性质**：第三方**已预处理**数据集（非待爬网站），镜像导入。
+
+## 概要
+
+| 字段 | 值 |
+|------|---|
+| 作者 | bshada |
+| License | **CC-BY-4.0** |
+| 更新 | 2025-12-17 |
+| 下载量 | 1 769 |
+| Likes | 160 |
+| 规模 | 10K – 100K 条 (tag `size_categories: 10K<n<100K`) |
+| 存储 | 78 parquet shards, **6.4 GB** (`data/train-000XX-of-00078.parquet`) |
+| 封面 | `open-schematics.png` (6.2 MB) |
+| Tags | kicad, schematics, pcb, electronics, hardware, circuit-design |
+
+## 数据结构（每条记录）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `schematic` | string | 原始 schematic 文件内容（主要是 `.kicad_sch`） |
+| `image` | image (PNG) | schematic 渲染图 |
+| `components_used` | list[string] | 元件名列表（从 library symbol 提取） |
+| `json` | string | JSON 结构化表示 |
+| `yaml` | string | YAML 元数据 |
+| `name` | string | 项目名 |
+| `description` | string | 项目描述 |
+| `type` | string | 文件扩展名 (`.kicad_sch` 等) |
+
+数据来源：公开硬件 repo（作者未列具体来源），已做以下处理：
+- 空 schematic（无元件/符号）过滤
+- 元件名从 library symbol 抽取
+- 生成可视化 PNG
+- 多格式（raw / JSON / YAML）并存
+
+## 为什么值得纳入
+
+1. **即用**：已结构化，训练 `text → schematic` / `image → components` / `schematic → description` 几类 SFT 都能直接用
+2. **KiCad 原生**：补上我们 oshwhub 路径（EasyEDA）以外的主流 EDA 生态
+3. **License 好**：CC-BY-4.0，商用仅需署名
+4. **小**：6.4 GB vs oshwhub 全量估算 110 GB，边际成本可接受
+
+## 接入方案（Option A：镜像）
+
+**不按"每项目一文件夹"解**，因为这是整包发布的数据集，记录 10K+，拆细反而破坏结构。
+
+目录：
+```
+data/external/huggingface/bshada--open-schematics/
+├── README.md                    # 原作者 README
+├── ATTRIBUTION.md               # 我方追加：来源 + license + crawled_at
+├── open-schematics.png          # 封面（LFS）
+├── data/*.parquet               # 78 shards（LFS）
+└── _source.json                 # HF API 元数据快照（sha / lastModified / downloads / tags）
+```
+
+下载方式：
+```bash
+# 用 huggingface-cli（uv 装 hf_hub）或 datasets 库，断点续
+uv pip install huggingface_hub
+huggingface-cli download bshada/open-schematics \
+    --repo-type dataset \
+    --local-dir data/external/huggingface/bshada--open-schematics
+```
+
+或轻量走 `hf_hub_download` + 循环：
+
+```python
+from huggingface_hub import snapshot_download
+snapshot_download(
+    repo_id="bshada/open-schematics",
+    repo_type="dataset",
+    local_dir="data/external/huggingface/bshada--open-schematics",
+)
+```
+
+## .gitattributes 改动
+
+```
+data/external/**/*.parquet  filter=lfs diff=lfs merge=lfs -text
+data/external/**/*.png      filter=lfs diff=lfs merge=lfs -text
+```
+
+## 下游消费
+
+我们的 `scripts/build_index.py` 目前按 `data/raw/*/*/metadata.json` 汇总，
+不会自动收录这个。需要：
+- 在 `build_index.py` 加一个 external datasets 段（从 `_source.json` 读）
+- 或者单独维护 `datasets.md`
+
+推荐：**单独 `datasets.md`**，因为 per-project 索引和 HF 包索引是两种不同物种，合并反而乱。
+
+## 风险
+
+- **License 署名**：下游产出（模型 card / 论文）必须标注 "This dataset uses schematics from bshada/open-schematics (CC-BY-4.0)"。加 `ATTRIBUTION.md` 落地
+- **数据来源不透明**：作者没公开具体来源 repo 列表，去重时无法对齐到上游项目（可能与 oshwhub / KiCad repo 的部分项目重叠）
+- **KiCad 版本**：`.kicad_sch` 语法随 KiCad 5/6/7/8 大改，没有版本标注 → 下游若要 round-trip 需探测
+
+## 待 Charles 决策
+
+1. 6.4 GB LFS 预算批准吗？
+2. 如果 oshwhub 放量 + HF 镜像并行，Gitea 实例磁盘要确认（之前已标记：需 `df -h` 看容量）
+3. 立刻拉还是排到 oshwhub 放量之后？
diff --git a/log.md b/log.md
index 35d0c55..c68c9dd 100644
--- a/log.md
+++ b/log.md
@@ -4,6 +4,32 @@
 
 ---
 
+## 2026-04-23 19:50  加入 HF bshada/open-schematics 计划
+
+**Claude 会话**
+
+Charles 点名把 https://huggingface.co/datasets/bshada/open-schematics 纳入第一批。
+
+调研结论：
+- 这是**已预处理**的 HF 数据集，非待爬网站
+- 78 parquet shards **6.4 GB**；CC-BY-4.0（商用友好）
+- 10K+ 条记录，每条含 `.kicad_sch` 源 / PNG / 组件列表 / JSON / YAML / name / description
+- 与 oshwhub (EasyEDA) 互补，补 KiCad 生态
+
+决定：
+- **整包镜像**到 `data/external/huggingface/bshada--open-schematics/`，**不**拆 per-project 目录
+- 用 `huggingface-cli download ... --repo-type dataset` 拉；parquet 走 LFS
+- 维护单独的 `datasets.md`，不与 per-project 的 `projects.md` 混
+
+改动：
+- 新增 `docs/sources/hf_bshada_open_schematics.md` 完整调研
+- `plan.md` 加 Phase 1.5
+- `README.md` 数据源表加一行
+
+**未下载**，等 Charles 拍板 6.4 GB LFS 预算。
+
+---
+
 ## 2026-04-23 19:30  Phase 1 MVP：10 个高质量 oshwhub 项目入库
 
 **Claude 会话**：承接仓库初始化
diff --git a/plan.md b/plan.md
index debef90..7c250e9 100644
--- a/plan.md
+++ b/plan.md
@@ -56,12 +56,29 @@
 ### 1.4 放量（待决策）
 
 - [ ] Charles 定目标规模：50 / 500 / 5000 / 全量 12493
-- [ ] 估算存储：52 附件 / 10 项目 ≈ 52MB/项目 → 全量约 **650GB**（Gitea LFS 需评估）
+- [x] 实测规模分布（见 `docs/sources/oshwhub_corpus_estimate.md`）：
+  - median/proj 9 MB → 全量 **~110 GB**（合理预算）
+  - p90 上界 **660 GB**
+  - mp4+qt 视频占 54% → 加 `--skip-ext mp4,qt` 可省一半
 - [ ] 未解决：
-  - `fs-web-stream.jlc.com` 工程源下载路径（未测）
   - `u.lceda.cn` EasyEDA 工程 JSON（需登录，v0.1 跳过）
   - 增量更新：`updated_at` 变动检测 + LFS prune 策略
 
+### 1.5 纳入第三方预处理数据集 `bshada/open-schematics`
+
+**性质**：Hugging Face 已发布的 KiCad schematics 数据集（非待爬网站），镜像导入即可。
+
+**目标**：补 KiCad 原生生态，与 oshwhub (EasyEDA) 互补。
+
+- [x] 调研（见 `docs/sources/hf_bshada_open_schematics.md`）
+- [ ] **待 Charles 拍板** 6.4 GB LFS 预算
+- [ ] 目录：`data/external/huggingface/bshada--open-schematics/`
+  - 整包镜像，**不**拆成 per-project 目录（10K+ 条记录）
+  - 78 parquet shards + README + 封面 + 追加 `ATTRIBUTION.md`
+- [ ] `.gitattributes`：`data/external/**/*.{parquet,png}` 走 LFS
+- [ ] 下载：`huggingface-cli download bshada/open-schematics --repo-type dataset --local-dir data/external/huggingface/bshada--open-schematics`
+- [ ] 单独维护 `datasets.md`（per-project 索引 `projects.md` 不适合整包数据集）
+
 ---
 
 ## Phase 2 — GitHub 开源硬件 repo