add epec md
This commit is contained in:
274
OSHWHUB_INGEST_SPEC.md
Normal file
274
OSHWHUB_INGEST_SPEC.md
Normal file
@@ -0,0 +1,274 @@
|
||||
# 立创开源平台抓取 → Forge 接入 spec
|
||||
|
||||
**Date**: 2026-04-23
|
||||
**给**: 同学爬 oshwhub.com / 立创开源广场
|
||||
**目的**: 爬回来的数据按这份 spec 整理，我们直接批量接入 Forge 的 BoardReference corpus。
|
||||
|
||||
---
|
||||
|
||||
## 1. TL;DR — 你交付的目标形态
|
||||
|
||||
每个项目一个目录，**三件套**：
|
||||
|
||||
```
|
||||
<project_id>/
|
||||
├── schematic.kicad_sch # ← 我们主要吃这个：KiCad 7+ S-expression 格式
|
||||
├── manifest.json # ← 项目元数据（见 §4）
|
||||
└── source/ # ← 可选：原 EasyEDA 文件归档（.json / .epro 等）
|
||||
```
|
||||
|
||||
**命名**: `project_id` = `oshwhub_<oshwhub数字ID>_<slug>`，纯小写下划线。
|
||||
例：`oshwhub_1234567_esp32_bluepill_clone`。
|
||||
|
||||
**交付**: tar.gz 或 git repo 都行。放在我们能访问的路径；我们自己跑批量 migrate。
|
||||
|
||||
---
|
||||
|
||||
## 2. 硬性前置条件 —— 任何一条不满足就跳过这个项目
|
||||
|
||||
### 2.1 License 白名单（关键！）
|
||||
|
||||
**仅抓这些许可的项目**：
|
||||
- MIT / BSD-2-Clause / BSD-3-Clause / Apache-2.0
|
||||
- CC0-1.0 / CC-BY-4.0 / CC-BY-3.0
|
||||
- CERN-OHL-P-2.0（permissive 变体）
|
||||
- Unlicense / public domain
|
||||
|
||||
**必须拒掉的**：
|
||||
- **CC-BY-SA**（share-alike，会污染我们 corpus——大比例立创项目是这个！务必过滤）
|
||||
- GPL / LGPL / AGPL 全家
|
||||
- "未声明 license" / "All rights reserved"
|
||||
- CC-BY-NC（禁商用）
|
||||
|
||||
立创项目页面上会显示许可名。你的爬虫要**先读许可、后抓文件**——许可不合格直接跳过，节省带宽。
|
||||
|
||||
### 2.2 文件格式
|
||||
|
||||
**必须有 KiCad 7+ 格式的 `.kicad_sch`**：
|
||||
- 文件首 20 字节包含 `(kicad_sch`
|
||||
- version 声明 ≥ 20210621（早于这个版本 KiCad 10 加载会 warning 一大堆）
|
||||
|
||||
**如果项目只有 EasyEDA 原文件**：
|
||||
- 用 [`easyeda2kicad`](https://github.com/uPesy/easyeda2kicad.py) 工具转（`pip install easyeda2kicad`）
|
||||
- 或者立创 EDA Professional 的"导出 KiCad"功能
|
||||
- 转完后**必须验证能被 kicad-cli 加载**（见 §6 自测）——转不出来就跳过、不要硬塞
|
||||
|
||||
### 2.3 基本质量
|
||||
|
||||
- 至少 5 个元件（太简单的 breadboard prototype 没参考价值）
|
||||
- 不超过 300 元件（太大的我们暂时不处理）
|
||||
- 不是纯 footprint 测试板（没电气连接）
|
||||
|
||||
---
|
||||
|
||||
## 3. `schematic.kicad_sch` 的要求
|
||||
|
||||
**原样保留**，不改、不格式化、不重新生成。我们的 corpus 依赖**字节级完整保留**才能做零漂移 byte-copy render。
|
||||
|
||||
**如果你用 easyeda2kicad 转换**：
|
||||
- 转一次、存盘、不要后续再处理
|
||||
- 多 sheet 项目：把主 sheet 存为 `schematic.kicad_sch`，其它 sheet 存为 `sheets/<name>.kicad_sch`
|
||||
（我们暂时只消费根 sheet，但不要删其它——留着我们以后升级）
|
||||
|
||||
---
|
||||
|
||||
## 4. `manifest.json` 格式
|
||||
|
||||
必填字段：
|
||||
|
||||
```json
|
||||
{
|
||||
"project_id": "oshwhub_1234567_esp32_bluepill_clone",
|
||||
"source_platform": "oshwhub",
|
||||
"source_url": "https://oshwhub.com/username/esp32-bluepill-clone",
|
||||
"source_author": "username",
|
||||
"title": "ESP32 Blue Pill 克隆",
|
||||
"description": "一行到三行描述。可以直接从项目页面抓。双语都抓最好（en + zh），至少一个。",
|
||||
"description_zh": "中文描述 (如果有)",
|
||||
|
||||
"license": "MIT",
|
||||
"license_source": "https://oshwhub.com/username/esp32-bluepill-clone/license",
|
||||
"license_verified": true,
|
||||
|
||||
"components_used": ["ESP32-WROOM-32", "AMS1117-3.3", "USB_B_Micro", "C", "R", "LED"],
|
||||
|
||||
"file_checksum_sha256": "abc123...",
|
||||
"file_size_bytes": 178825,
|
||||
"kicad_sch_version": "20230121",
|
||||
|
||||
"crawl_timestamp": "2026-04-23T10:00:00Z",
|
||||
"converted_from": "easyeda",
|
||||
"conversion_tool": "easyeda2kicad 0.8.2",
|
||||
|
||||
"tags_raw": ["esp32", "dev_board", "usb"]
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
- **`source_url`**：立创开源那个 project 的页面 URL。我们保存做 provenance。
|
||||
- **`license`**：必须是 §2.1 白名单里的字符串之一。**抓不准就跳过**，宁缺毋滥。
|
||||
- **`license_source`**：license 是从哪读到的（页面、LICENSE 文件、README）。方便我们事后验。
|
||||
- **`components_used`**：从 sch 里或从 EasyEDA 原 BOM 抓。用于后续 tag 派生——越全越好。
|
||||
- **`file_checksum_sha256`**：sha256 of `schematic.kicad_sch`。dedupe 用。
|
||||
- **`converted_from` / `conversion_tool`**：原生 KiCad 的项目写 `"converted_from": "native"`；EasyEDA 转来的写具体工具和版本。
|
||||
- **`tags_raw`**：立创页面上那个项目自带的标签/分类。原样塞。我们这边有一个 enrich 管线会基于 `components_used` + `description` 再派生更细的 tag（has_mcu / chip_tp4056 / use_portable...），你不用管这一步。
|
||||
|
||||
可选但有用：
|
||||
- `source_easyeda_json_path`: 原 EasyEDA 文件的路径（如果你归档到 `source/` 下的话）
|
||||
- `commit_sha` / `version`: 如果立创项目有版本号
|
||||
- `star_count` / `fork_count`: 作为后续 quality 排序参考
|
||||
|
||||
---
|
||||
|
||||
## 5. 目录结构示例
|
||||
|
||||
```
|
||||
batch_20260423/ # 你一次交付的批次目录
|
||||
├── README.md # 批次元数据（数量、时间、任何 caveat）
|
||||
├── BATCH_MANIFEST.json # 机器可读的批次清单（见 §5.1）
|
||||
│
|
||||
├── oshwhub_1234567_esp32_bluepill/
|
||||
│ ├── schematic.kicad_sch
|
||||
│ ├── manifest.json
|
||||
│ └── source/
|
||||
│ └── schematic.json # 原 EasyEDA
|
||||
│
|
||||
├── oshwhub_2234568_tp4056_charger_v2/
|
||||
│ ├── schematic.kicad_sch
|
||||
│ ├── manifest.json
|
||||
│ └── source/
|
||||
│ ├── schematic.json
|
||||
│ └── pcb.json
|
||||
│
|
||||
├── oshwhub_3234569_audio_preamp/
|
||||
│ ├── schematic.kicad_sch # 原生 KiCad，无 source/
|
||||
│ └── manifest.json
|
||||
│
|
||||
└── ... (N 个项目)
|
||||
```
|
||||
|
||||
### 5.1 BATCH_MANIFEST.json
|
||||
|
||||
让我们能一键扫批次：
|
||||
|
||||
```json
|
||||
{
|
||||
"batch_id": "batch_20260423",
|
||||
"created_at": "2026-04-23T12:00:00Z",
|
||||
"total_projects": 153,
|
||||
"by_license": {
|
||||
"MIT": 87,
|
||||
"CC-BY-4.0": 34,
|
||||
"Apache-2.0": 20,
|
||||
"CC0-1.0": 12
|
||||
},
|
||||
"projects": [
|
||||
"oshwhub_1234567_esp32_bluepill",
|
||||
"oshwhub_2234568_tp4056_charger_v2",
|
||||
...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 自测 checklist（你交付前跑一遍）
|
||||
|
||||
对每个 `<project_id>/` 跑这 4 个检查，任一失败就把这个项目踢出批次：
|
||||
|
||||
```bash
|
||||
# 1. .kicad_sch 首字节对头
|
||||
head -c 20 <project_id>/schematic.kicad_sch | grep -q "(kicad_sch" || echo FAIL_1
|
||||
|
||||
# 2. 版本 ≥ 20210621
|
||||
grep -oE "version \d{8}" <project_id>/schematic.kicad_sch | head -1
|
||||
# expect 20210621 或更大
|
||||
|
||||
# 3. 能被 kicad-cli 加载（这一步最关键，catch 掉所有转换失败）
|
||||
kicad-cli sch export netlist <project_id>/schematic.kicad_sch \
|
||||
-o /tmp/test.net 2>&1 | grep -qi "error\|失败" && echo FAIL_3
|
||||
|
||||
# 4. manifest.json 合法且必填字段齐
|
||||
python3 -c "
|
||||
import json, sys
|
||||
m = json.load(open('<project_id>/manifest.json'))
|
||||
required = ['project_id', 'source_url', 'license', 'components_used', 'file_checksum_sha256']
|
||||
missing = [k for k in required if k not in m or not m[k]]
|
||||
if missing:
|
||||
print('FAIL_4 missing:', missing)
|
||||
sys.exit(1)
|
||||
"
|
||||
```
|
||||
|
||||
把每个项目的检查结果写进 BATCH_MANIFEST 或单独一个 `failed/` 子目录归档。**交付前所有 4 个检查都要过**。
|
||||
|
||||
---
|
||||
|
||||
## 7. 已知坑 & 建议
|
||||
|
||||
### 7.1 立创开源的 license 现实
|
||||
|
||||
经验数据（不保证准确）：
|
||||
- 立创项目里**可能 50%+ 是 "CC-BY-SA 4.0"**，这是默认选项 → 我们直接拒
|
||||
- 大概 20-30% 是 "未声明 license" → 拒
|
||||
- 10-15% 是 MIT / Apache / CC0 → 要！
|
||||
- 少量 GPL → 拒
|
||||
|
||||
**预期 hit rate**: 你抓 1000 个项目可能只有 150-250 能通过 license 关卡。这是正常的，不要为了数量降低许可标准。
|
||||
|
||||
### 7.2 EasyEDA → KiCad 转换质量
|
||||
|
||||
`easyeda2kicad.py` 对大部分项目能用，但：
|
||||
- 自定义 symbol（立创 SZLCSC 专有库）可能转不过来 → 转完 kicad-cli 加载会 fail → 被 §6 check 3 过滤掉
|
||||
- 多 sheet hierarchy 偶尔乱 → 只保根 sheet 也能用
|
||||
- footprint 转换常有问题——我们暂时不在乎 footprint（corpus 主要消费 schematic），转不过就空着
|
||||
|
||||
### 7.3 描述文字
|
||||
|
||||
立创项目标题和描述常常**中英混杂 + markdown 标记 + emoji**。原样保留没关系，我们的 enrich 管线会 strip markdown。但**别主动翻译或改写** —— 原文有最多信息。
|
||||
|
||||
### 7.4 同项目多版本
|
||||
|
||||
立创有的项目带版本（v1 / v2 / Rev.B）。**不同版本视作不同项目**，分别抓、分别起 project_id。不要合并。
|
||||
|
||||
### 7.5 电气图多页
|
||||
|
||||
立创项目经常一个 sch 项目分多页（root + mcu_sheet + power_sheet 等）。你遇到时：
|
||||
- 如果 easyeda2kicad 能转出层级结构 → 主 sheet 存 `schematic.kicad_sch`，子 sheet 存 `sheets/<name>.kicad_sch`
|
||||
- 如果只导出根 sheet → 根 sheet 存 `schematic.kicad_sch`，在 `manifest.json` 加 `"has_unsaved_subsheets": true` 标记
|
||||
- 转不出来 → 跳
|
||||
|
||||
---
|
||||
|
||||
## 8. 交付后我们会做什么（你不用担心这部分）
|
||||
|
||||
参考、别去实现：
|
||||
|
||||
1. `batch_migrate_oshwhub.py` 扫整个批次，逐个 `board_ingest_from_file` 入 corpus
|
||||
2. License 白名单再 double-check 一遍（防你漏过）
|
||||
3. sha256 dedupe（跨批次）
|
||||
4. `enrich_tags.py` 跑一遍基于 `components_used` + `description` 生成 chip_* / has_* / use_* tag 家族
|
||||
5. 用 kicad-cli 跑 ERC 取 `source_erc_status`，脏的标记一下但仍入库（用户能看到警告）
|
||||
|
||||
---
|
||||
|
||||
## 9. 测试批次建议
|
||||
|
||||
**第一次交付先给小批 5-10 个项目**，覆盖：
|
||||
- 3-5 个 MIT/Apache 原生 KiCad
|
||||
- 2-3 个 CC0/CC-BY-4.0 从 EasyEDA 转的
|
||||
- 1-2 个你不确定的 edge case（多 sheet、异常元件等）
|
||||
|
||||
我们跑一遍 ingest，给你反馈"格式上还要改啥" / "这块数据不够"，再开始量产爬。
|
||||
|
||||
---
|
||||
|
||||
## 10. 联系点
|
||||
|
||||
- 这份文档的源头：`hardware_agent_docs/OSHWHUB_INGEST_SPEC.md`
|
||||
- 我们的 BoardReference schema 定义：`src/facere/references/schema.py`
|
||||
- 已有的 ingest 入口：`src/facere/references/board_ingest.py`
|
||||
- 批量 migrate 脚本参考：`benchmarks/corpus_build/migrate_raw_to_board_refs.py`
|
||||
|
||||
有问题直接问我（张大佬）—— 格式细节比速度重要，不清楚的**先对一下再做**。
|
||||
Reference in New Issue
Block a user