# FacereDataset 执行日志 时间倒序，最新在顶部。 --- ## 2026-04-28 23:30 oshwhub 全量 listing 索引落本地：33,695 项 / 28.4 MB **Claude 会话** 为了在"扩量到 top-30 / top-50 / 全量"前先量化候选池规模 + 质量分布，把 oshwhub listing API 全量扫一遍落地。 ### 关键收获（之前以为是黑箱） - **listing API 直接返回 `total` 字段**：Pro 21,202 / Std 12,493，**合计 33,695**。 - **`pageSize` 无上限**，实测 1000 工作良好；全量索引 = 35 次请求 / 71 秒 / 35 MB 流量。 - **`sort` 参数被服务端静默忽略**——传啥都返回相同顺序（grade desc → 隐式质量分 desc）。"按时间排序"必须先拉全集再本地排。 - **`origin` 默认 std**——不带参数永远看不到 Pro 池。 - **`license` 不在 listing 响应**，必须挨个抓详情页（QPS=0.5 → ~19 小时全量）。 ### 数据画像（写到 `docs/sources/oshwhub_listing_full.md`） - **Pro 长尾极重**：grade=1 占 82%，真正 A 档（grade≥3 & like≥10）只有 1,356 (6.4%) - **Std 高质量比例反而高**：A 档 1,450 (11.6%)，因为平台老 7 年（2016 起 vs Pro 2021 起），项目有时间累积点赞 - **Std 已停滞**：2021-2022 见顶（3.4k/年），之后断崖（1.5k → 0.9k → 0.4k → 0.05k 2026Q1） - **Pro 还在快速膨胀**：2023 起线性增长，2025 全年 7.4k，2026Q1 已 1.1k - **作者长尾健康**：Pro 10,536 个 / Std 5,531 个唯一作者；top-1 占比 0.4% / 1.5% - **立创官方账号占据头部**（course-examples / li-chuang-kai-fa-ban / li-chuang-zhi-neng-ying-jian-bu） ### 实操含义 放量决策有了量化锚点：S 档 583 项 / A 档 2,806 项 / B 档 6,243 项 / 全量 33,695。Pro 工程源体积外推（基于 5 项实测均值），全 Pro 约 1 TB——超出 Gitea LFS 舒适区，必须配 size cap + license 白名单。 ### 下一步 1. 在本地 jsonl 上按 A 档过滤，做 license 详情页扫描（一次性 ~7 小时） 2. license 白名单 ∩ A 档 → 真候选清单 3. 然后再决定批量下载源 ### 文件 - `scripts/dump_listing_index.py` —— 一次性全量扫描脚本，可重抓 - `data/state/oshwhub_listing_full.jsonl` —— 28.4 MB，gitignore（可重建，不入库） - `docs/sources/oshwhub_listing_full.md` —— 给人看的简报 --- ## 2026-04-28 22:00 Pro 2.x 旧版工程源抓取链路打通，5/5 Pro 项目全部 ✅ **Claude 会话** 承接刚做的 3/5 modern Pro 批量。用户录了第三份 HAR（`tmp/prodownload3.har` 103 MB / 178 请求，目标是登录态打开**梁山派** legacy Pro 2.x 项目），让我把 RK3566 / 梁山派两个旧版项目也补上。 ### HAR 反推：Pro 2.x 用一套完全不同的端点 旧版（`editorVersion: 2.1.x`）没有 git-style branch + history 模型。HAR 里看到的关键端点： | 端点 | 作用 | |---|---| | `GET /api/projects/

/ticket?uuid=

&g_ticket=-1` | 完整项目 manifest（schematics / schs / pcbs / coppers / textpath / blobs / symbols / footprints / devices / block_symbol） | | `POST /api/schematic/lists {uuids:[]}` | 父 schematic 容器，含 `sort: [{uuid: , ticket}]` 即子图 UUIDs | | `POST /api/v2/documents/lists {uuids:[...], docType:1}` | 抓 schematic 子图（**plaintext** dataStr，跟 Std 一样的 `["DOCTYPE","SCH","1.1"]\n[HEAD,...]` 格式） | | `POST /api/v2/documents/lists {uuids:[...], docType:3}` | 抓 PCB（同样 plaintext dataStr） | | `POST /api/coppers/search {paths:[...]}` | 铺铜层数据（PCB 上独立分发的增量层） | | `POST /api/textpath/search {paths, project_uuid, path}` | 字体 / 文字路径（同上） | | `POST /api/v2/resources/search {hash, project_uuid}` | BLOB（嵌入图片） | | `POST /api/v2/components/searchByIds` / `/api/devices/searchByIds` | 元件库 metadata（其 `dataStrId` 仍走 modules.lceda.cn AES 加密 blob） | **关键差异**：旧版的工程**主体 plaintext**（无加密 / 无 history 重放），只有元件库走 Pro 3.x 的 AES 方案。这反而比 3.x 简单很多。 **判别规则**：`/api/v4/projects/

` 返回的 `branch_uuid` 是不是 null。null 即旧版。 ### 实现 `crawlers/oshwhub/crawler.py` refactor： - `fetch_pro_source()` 拆成 dispatcher（先 GET project meta → 检查 `branch_uuid`） - `_fetch_pro_modern()` —— 原 EPRO2 chain 流程，去掉重复的 project meta 调用 - `_fetch_pro_legacy()` —— 新增，按上面 9 步流程拉所有 doc + 辅助层 - `_pro_post_json()` —— POST helper（与 GET helper 对称） 落盘约定（旧版）： - `source/ticket.json` —— 完整 manifest（保留备 lib 重建） - `source/.json` —— 每张原理图 - `source/pcb_.json` —— 每块 PCB - `source/coppers.json` / `textpath.json` / `blobs.json` —— 辅助 PCB 层资源 - `source/manifest.json` —— 索引 + structure_summary schema：`source_format` enum 加 `easyeda-pro-legacy`。 ### 实测：2/2 legacy 项目打通 | 项目 | editor | sheets | pcbs | sym | fp | dev | coppers | textpath | blobs | size | |---|---|---|---|---|---|---|---|---|---|---| | 立创·梁山派 | 2.1.30 | 2 | 1 | 78 | 191 | 128 | 29 | 3 | 1 | 1.0 MB | | 立创·泰山派 RK3566 | 2.1.40 | 29 | 1 | 299 | 524 | 295 | 0 | 0 | 32 | 0.8 MB | **旧版项目比新版小两个数量级**（梁山派 1 MB vs RK3576 66 MB）—— 没有增量 history、组件库走单独端点、本身就是当前快照。 ### 5/5 Pro 项目终极汇总 | # | 项目 | source_format | editor | docs | size | |---|---|---|---|---|---| | 1 | X86 主板 | easyeda-pro | 3.2.15 | 7374 | 481 MB | | 2 | 立创·泰山派 RK3566 | easyeda-pro-legacy | 2.1.40 | 30 | 0.8 MB | | 3 | 立创·梁山派 | easyeda-pro-legacy | 2.1.30 | 3 | 1.0 MB | | 4 | 220V 桌面电源 | easyeda-pro | 3.2.69 | 771 | 26 MB | | 5 | ESP-VoCat 喵伴 | easyeda-pro | 3.2.91 | 278 | 7.5 MB | 合计 8456 docs / ~516 MB plain 源数据，5/5 端到端打通。 ### 下一步 1. EPRO2 → KiCad 转换器（仍是 Forge 投影硬门槛，ESP-VoCat 7.5 MB 是不错的小样本起手） 2. 旧版 dataStr → KiCad 复用 Std 转换链（同格式，已有 `easyeda2kicad.py` 支持） 3. 阶梯放量到 50 / 500 项目时做风控压测 --- ## 2026-04-28 21:35 Pro 工程源（EPRO2）批量抓取打通：3/5 modern Pro 项目 ✅，2/5 legacy 2.x ❌ **Claude 会话** 承接刚做完 Std 链路；用户给了浏览器 HAR (`tmp/prodownload.har`，174 请求，目标 = 立创·泰山派 RK3576 现代 Pro 项目) 验证 endpoint 形态，要求"找 5 个专业版项目，看能不能批量抓 EPRO2"。 ### 5 个候选 按 `oshwhub /api/project?origin=pro&sort=hot` 取前 5（详情 API 拿 license）： | # | UUID | License | 项目 | 结果 | |---|---|---|---|---| | 1 | `b77840665e2e...` | GPL 3.0 | 【全网首发】X86电脑主板 | ✅ | | 2 | `7360e73de5dd...` | GPL 3.0 | 立创·泰山派 RK3566 开发板 | ❌ legacy 2.x | | 3 | `0c4675983733...` | GPL 3.0 | 立创·梁山派开发板 | ❌ legacy 2.x | | 4 | `dc91a91e6693...` | CC BY-NC-SA 4.0 | （高颜值）220V 300W 桌面电源 | ✅ | | 5 | `ba64bd6f1c9c...` | GPL 3.0 | ESP-VoCat 喵伴 AI 萌宠 | ✅ | License 全是限制性（CC-NC-SA / GPL）— Pro 用户群是立创团队/教育机构，默认上 NC-SA。和用户对齐：本仓库为研究用、不再分发，license 字段忠实落库；下游 Forge 投影时再用白名单过滤。 ### 关键发现：Pro 2.x ≠ Pro 3.x（重要！） 立创开发板的旗舰板（RK3566 / 梁山派）抓 `/api/v4/projects/` 返回 **`branch_uuid: null`** + `editorVersion: "2.1.40"`。 这是 **Pro 编辑器旧版（2.x）**：没有 git-style branch/history 模型，文档直接通过 `boards: [{sch, name, pcb}]` 字段定位。我们之前调研的全是 3.x（泰山派 RK3576 / 无界 PLUS），3.x 才有 `/branches//structures` + `/histories/` 全套。 旧版的访问端点暂未挖通：`/api/v4/documents/` 404；`/api/documents/` 401；`/api/v4/projects/

/snapshots` 200 但响应体是 project meta 不是 doc。需要录一份"在 pro.lceda.cn 编辑器里打开 RK3566"的 HAR 才能继续。已记入 `docs/sources/easyeda_pro_source.md §1.1`。 ### EPRO2 解析坑：行末单 `|`（找了 2 轮才看到） 第一轮跑 5 个项目结果：X86 board 7374 docs 抽出来只剩 **2 个**，220V 电源和 ESP-VoCat 都是 **0 docs**。 定位过程： 1. 直接 dump 一条 history 的 lines，看到 DOCHEAD payload **行末有单个 `|`**，例如 `{"docType":"BOARD",...,"version":"..."}|`。 2. 我的解析 `json.loads(ln.split(b"||")[1])` 拿到带尾随 `|` 的字符串 → `Extra data: line 1 column 127`。 3. silently swallow exception → `cur_doc` 没设 → 全 chain 的 message 被丢弃。 4. 修复：解析前先 `ln.rstrip(b"|").split(b"||")`。已在 `docs/sources/easyeda_pro_source.md §3.1` 记录"行末单 `|` 是行终止符不是字段分隔符"。 ### 修复后批量结果 3 个 modern Pro 项目完整解出来： | 项目 | chain | docs | plain | blob | editor | |---|---|---|---|---|---| | ESP-VoCat | 12 | 278 | 7.5 MB | 1.1 MB | 3.2.91 | | 220V 电源 | 28 | 771 | 26.3 MB | 7.4 MB | 3.2.69 | | X86 主板 | 85 | 7374 | **481 MB** | 61 MB | 3.2.15 | X86 主板（5123 FOOTPRINT + 1243 DEVICE + 837 SYMBOL = 7203 个组件库 doc）数据量惊人，是个超复杂工程。 ### docType 取值表（实测扩展） 之前 doc 只列了 `BOARD/PCB/SCHEMATIC/SHEET`。实测 EPRO2 流里 docType 实际取值更细： - 用户级文档：`BOARD`（板物理边框）+ `PCB`（板内容）+ `SCH`（原理图）+ `SCH_PAGE`（子图）。一个完整 PCB 板 = 一对 `BOARD` + `PCB`，不是命名变化。 - 组件库 / 资源：`SYMBOL` / `FOOTPRINT` / `DEVICE` / `BLOB` / `FONT` / `CONFIG`。每个独特组件 / 字体 / 项目配置都是独立 doc。 - 抓 EPRO2 = 抓项目 + **完整的局部组件库快照**。下游做 EPRO2 → KiCad 转换时必须先把 lib doc 加载进 symbol cache。 已更新到 `docs/sources/easyeda_pro_source.md §3.4`。 ### 代码改动 - `crawlers/oshwhub/crawler.py`： - 新增 `make_pro_source_client()` —— 加载 `~/.secrets/pro-lceda-cookie-header.txt`，自动配 `Editor-Version` / `Referer` / per-request `path` header - 新增 `fetch_pro_source(client, project_uuid, proj_dir, sleep)` —— 4 步流程：project meta → branch HEAD → structures → history chain，然后逐 history 解密（AES-128-GCM, 16 字节 IV）+ gunzip + 按 DOCHEAD 切 per-doc - 新增 `_order_history_chain()` —— 沿 parent 链从 root 到 HEAD 排序 - 新增 `_pro_get_json()` —— 包装 `/api/v4` GET 调用，自动加 `path` header + 校验 success - 扩展 `crawl_one()` 接 `pro_source_client` 参数，按 `list_item.origin` 自动 dispatch - 新增 CLI flag `--with-pro-source` / `--backfill-pro-source` / `--pro-cookie` / `--origin` - 新增 `_run_backfill_pro_source()`（filter on `raw_fields.origin == "pro"`） - `schemas/project.schema.json`：`docType` 类型从 `integer` 放宽到 `["integer","string","null"]`（兼容 Std 的 1/3 + Pro 的 BOARD/PCB/SCH 等字符串），新增 `message_count` 字段 - `docs/sources/easyeda_pro_source.md` rev 3：加 §1.1 Pro 2.x vs 3.x、§3.1 行末 `|` 警告、§3.4 docType 实测表、§2.2 单 history endpoint 即返完整 chain ### 数据落地 ``` data/raw/oshwhub/ b77840665e2e48148c1b04ce84b5f7e7/ # X86 主板（modern Pro 3.2.15） source/ manifest.json # 7374 docs index structure.json # 项目树（boards/schematics/sheets/pcbs） .epro2 # 7374 个 EPRO2 文件 dc91a91e669349898d709a5ba02f5b5f/ # 220V 电源（modern Pro 3.2.69） ba64bd6f1c9c467ba3b674a54943557d/ # ESP-VoCat（modern Pro 3.2.91） 7360e73de5dd428e9f29e10573f2d8ac/ # legacy Pro 2.x，无 source/ 0c46759837334318aa4882d6d37f96fa/ # legacy Pro 2.x，无 source/ ``` ### 下一步 1. （重要）legacy Pro 2.x 抓取链：录 HAR 看 RK3566 / 梁山派 在 pro.lceda.cn 编辑器打开时走什么 endpoint 2. 想跑量到 50 / 500 项目时，先做风控测试：阶梯放量，监控 403 / 429 / 1111111 3. EPRO2 → KiCad 转换器是 Forge 投影前置硬门槛 4. 可考虑 cookie 轮换 / 多账号 pool（Pro 风控相对 Std 严） --- ## 2026-04-28 19:50 Std 工程源链路打通 + 10 板子 schematic/PCB 全部回填 **Claude 会话** 承接计划：把已抓 10 个板子的"需登录才能下载的原理图 + PCB"补齐。 ### 关键发现：根本不需要登录 10 个板子全是 `origin: "std"`（EasyEDA 标准版）。原 `plan.md §1.6` 假设源数据要登录 — 实际**公开项目的 `dataStr` 匿名可访**。 调研路径（4 轮探测，留痕在 `data/state/std_probe[1-5]/`）： 1. `/api/user`、`/api/projects` 401（cookie 已过期，但和源抓取无关） 2. **`oshwhub.com/api/project/` 浏览器 UA 匿名 200**，返回 `version_documents[]`（含 doc uuid + master + history chain） 3. `modules.lceda.cn/histories/.json` 仍 403（与 Pro 同结构，但 Std 不走这条路） 4. 翻 Std 编辑器 `/editor/6.5.51/js/main.min.js`（5 MB）grep `/api/`，找到 76 个端点。关键的 `ajaxDetail = '/api/documents/{uuid}'` 5. 命中：**`https://lceda.cn/api/documents/?uuid=&path=`** 匿名 200，body 是完整 EasyEDA JSON（`dataStr.{head,canvas,shape,BBox,colors[layers,objects,DRCRULE,...]}`） **两种响应 shape**（按 docType 区分）： - docType=1 (Schematic)：返"项目视图"，`result.schematics[0].dataStr` - docType=3 (PCB)：返"文档视图"，`result.dataStr` 直接在顶层 ### 与 Pro 的差异 | 维度 | Std (本轮) | Pro (`docs/sources/easyeda_pro_source.md`) | |---|---|---| | 鉴权 | **无需** | `lceda_pro_session` 必须 | | 加密 | **无** | AES-128-GCM + gzip | | 源格式 | 扁平 EasyEDA JSON（`shape[]`） | EPRO2 消息流（事件溯源） | | 多 doc | `version_documents[]` 逐个 GET | `/structures` + history chain 重放 | ### 实施 - `docs/sources/easyeda_std_source.md`：完整调研（含 dataStr 字段、抓取伪代码、附录重跑脚本） - `crawlers/oshwhub/crawler.py`： - 新增 `make_source_client()` —— 浏览器 UA + Referer，规避 oshwhub `/api/project/` 端点对 `FacereDataset/0.1` UA 的 reject（在 commit message 注明 UA 例外原因） - 新增 `fetch_std_source()`：项目 → version_documents → 逐文档 dataStr → 落 `source/.json` + `source/manifest.json` - 新增 `--with-source` 标志（爬新项目时一并抓源）和 `--backfill-source`（仅扫已有项目补源） - QPS ≤ 0.2（`SLEEP_SOURCE = 5.0s`） - `schemas/project.schema.json`：加 `source_format`/`source_path`/`source_documents`/`editor_version` 字段（前 3 个进 enum 锁定，后续新源好对齐） ### 跑批结果（dev1，QPS 0.2） 10/10 全成功；schema 验证 10/10 pass： | 项目 | docs | docTypes | 大小 | editor | |---|---|---|---|---| | ST-LINK V2-1 | 2 | [1,3] | 682 KB | 6.5.39 | | USB 电压电流表 | **4** | **[3]** | 1.2 MB | 6.5.15 | | 红外热成像 | 2 | [1,3] | 1.6 MB | 6.5.22 | | t12-858d 焊台 | **11** | [1,3] | 6.1 MB | 6.5.15 | | 加热台量产计划 | 6 | [1,3] | **12.0 MB** | 6.5.43 | | ESP32-S3 智能手表 | 4 | [1,3] | 1.4 MB | 6.5.41 | | RT300-MKV 可调电源 | 3 | [1,3] | 3.3 MB | 6.5.23 | | YuzuMaix V831 | 4 | [1,3] | 5.4 MB | 6.5.37 | | 盖革计数器 | 6 | [1,3] | 1.2 MB | 6.5.47 | | ZVS 感应加热 | 3 | [1,3] | 990 KB | 6.5.40 | **合计**：45 个文档 / 33.2 MB（中位 ~1.5 MB / 项目，附件主体约为附件主流量的 6%） 观察： - USB 电压电流表只有 PCB 文档（4 个：主板 + 盖板 + 底板 + 面板，作者未上传原理图源） - t12 焊台 11 个文档（拆得碎，估计含多个独立模块） - editor 版本散布在 6.5.15 - 6.5.47（取决于作者上一次保存项目时的客户端版本） ### 落盘结构（per project） ``` data/raw/oshwhub// ├── metadata.json # ★ 新增字段：source_format/source_path/source_documents/editor_version ├── description.md ├── cover.* ├── _urls.json ├── files/ # 用户附件（已存在，LFS） └── source/ # ★ 新：EasyEDA Std 工程源 ├── manifest.json # 文档清单 + 抓取时间 + upstream version_documents 留档 └── .json # 完整 dataStr 响应（普通 git，文件 1-5 MB 量级） ``` `source/*.json` **走普通 git** 而不是 LFS（10 项目共 33 MB 完全够用；放量时再考虑加 LFS 规则）。 ### 安全 / 合规 - 无登录态、无凭据使用 → 无账号封禁风险，无 cookie 泄漏顾虑 - UA 例外：源抓取使用浏览器 UA 而非 `FacereDataset/0.1`，原因写入 `docs/sources/easyeda_std_source.md §3` 与本 commit message - License：与原项目附件相同的 license 字段已在 metadata，下游 whitelist 过滤逻辑不变 ### 未决 / 下一步 1. dev1 上的 `~/.secrets/lceda.json` cookie 已过期（XSRF 4-22 失效，今天 4-28），但**本任务已不依赖**它。是否保留待定 —— Pro 流程可能仍要 2. `easyeda2kicad.py` 转换：现有 45 个 dataStr 是关键测试样本，可立刻跑（`plan.md §1.7`） 3. 放量决策：从 10 → 50 → 全量 12,493 时，按 33 MB / 10 ≈ 3.3 MB/proj 估算，全量源 ~40 GB（不含附件本体） 4. 多账号轮询、Pro 链路打通仍是 `plan.md §1.6` 的开放项（仅当遇到 Pro 项目时才用得上） ### 改动清单 - 新增：`docs/sources/easyeda_std_source.md`、`scripts/probe_std_api[1-5].py`、`data/raw/oshwhub//source/`（10 项目） - 修改：`crawlers/oshwhub/crawler.py`、`schemas/project.schema.json`、10 项目的 `metadata.json` - 待人工：`projects.md` 重生成（脚本未跑）；`plan.md §1.6` 状态从 ⏳ → ✅，§1.7 unblocked --- ## 2026-04-24 00:25 打通 pro.lceda.cn 工程源完整链 + EPRO2 格式解析 **Claude 会话** 核心成果：**立创 EDA Pro 工程源的 API + 加密 + 格式三层全打通**。 ### 完整链路 ``` 1. GET /api/v4/projects/ → branch_uuid 2. GET /api/v4/projects//branches/ → history_uuid 3. GET /api/v4/projects//branches//histories/ → {key, iv, dataStrUrl} 4. GET (modules.lceda.cn) → 417 KB 加密 blob 5. AES-128-GCM decrypt (tag=blob[-16:]) → 417 KB gzip 6. gunzip → 2.7 MB EPRO2 源流 ``` 关键 headers：`Editor-Version: 3.2.127` / `path: ` / `Referer: https://pro.lceda.cn/editor` / `Cookie: lceda_pro_session=...`（与 u.lceda.cn 的 session 不共享） ### 加密细节 - 算法: AES-128-GCM（从 `modules.lceda.cn/pro-mgr/.../project-worker.js` 里 `this.tool.decrypt({name:"AES-GCM",iv:this.iv,tagLength:128},...)` 反查确认） - key / iv 都是 32 hex = 16 byte - WebCrypto 约定：ciphertext || 16-byte-authTag（末尾附） - 解密后 gzip magic `1f 8b 08`，gunzip 得最终源流 ### EPRO2 格式 立创 EDA Pro 2 的**事件溯源**格式：消息流按 `\n` 分行，每行 `{"type":...,"ticket":N,"id":...}||{payload}||[extra]`。 示例样本（`无界PLUS` BOARD 文档）**8 357 条消息**，**40 种 type**： - PART / COMPONENT / ATTR / PIN（零件与属性） - PAD / VIA / WIRE / NET / PAD_NET（PCB 电气） - LINE / POLY / RECT / ARC / CIRCLE / ELLIPSE / TEXT（几何） - LAYER (1572) / LAYER_PHYS / ACTIVE_LAYER（层堆叠） - FILL / POUR / POURED（铺铜） - RULE / RULE_SELECTOR / RULE_TEMPLATE（设计规则） ### 与 Std 版对比 | | u.lceda.cn (Std) | pro.lceda.cn (Pro) | |---|---|---| | Cookie | `lceda_session` | `lceda_pro_session` | | 源 API | 单一 `/api/projects/` | 4 步 `/api/v4/...` 链 | | 版本控制 | 无 | branches + histories | | 加密 | 待验证 | AES-128-GCM | | 源格式 | EasyEDA JSON（扁平） | EPRO2 消息流 | | 工具 | `easyeda2kicad.py` 第三方 | **无**现成 KiCad 转换器 | ### 落地 - 新建 `docs/sources/easyeda_pro_source.md`（完整调研，见该文档附录 A 一键重跑） - `pyproject.toml` 加 `pycryptodome>=3.23.0` - 清理：dev1 上 `/tmp/source.blob` 与 `/tmp/source.json`（后者含 Charles 私人工程源 2.7 MB） ### 待验证 / 下一步 1. **他人公开 Pro 工程**能否同样 4 步通 —— 需 HAR 2. **SCHEMATIC docType** 的 API 入口（本次只解出 BOARD） 3. **多 document 枚举**（project → documents 列表端点） 4. Pro 编辑器"**导出 KiCad**"功能的 API 端点（若存在，能省自写转换器的工作） 5. 对齐 `OSHWHUB_INGEST_SPEC.md`（Forge 消费侧要求 `.kicad_sch` + 更严 license whitelist） ### ⚠️ 安全 Charles 在聊天里粘过两次 cookie（u.lceda.cn 一次 + pro.lceda.cn 一次），已写入 dev1 `~/.secrets/`。 当前会话 transcript 含明文 —— 本轮验证完 Charles 应登出再重登一次，让测试期间暴露过的 session invalidate。 --- ## 2026-04-23 20:10 策略大调：登录内容入场 + 云服务器 + EDA→KiCad 转换 **Claude 会话** 四项变更落实到文档（暂不写代码，等云服务器到位）： ### 1. 登录态内容纳入范围 原则（`CLAUDE.md`）： - 合法账号登录后抓，**禁止**盗号 / 共享号 - 凭据集中云服务器 `~/.secrets/` (mode 700)，**不入** git / 日志 / metadata - 仍不绕付费墙、不破 DRM、不抓站点明确禁抓的内容 - 换号 / 重登事件记 `docs/secrets.md`（只事件、不含值） ### 2. 云服务器（广州，待交付） 新增 plan.md §0.5 基础设施段： - 0.5.1 机器初始化：git / git-lfs / uv / python 3.11+，非 root SSH，`~/.secrets/` - 0.5.2 调度：tmux/nohup 长跑 + systemd timer 增量 - 0.5.3 登录态获取：cookie 导出流程 ### 3. 存储分级演进 plan.md §1.4 改写： - 前期 < 50 GB：云服务器磁盘 + Gitea LFS - 中期 50–200 GB：评估 Gitea 容量压力；扩容 or 分仓 - 后期 > 200 GB：迁对象存储（OSS / COS / MinIO），Gitea 只存元数据 + 指针 - 50 GB 是决策评估点，**不**过早迁移 ### 4. 立创 EDA → KiCad 转换 新增 plan.md §1.6（登录态工程源抓取）+ §1.7（EDA→KiCad 转换）： - §1.6 用登录账号抓 `u.lceda.cn/api/project/` 工程源 JSON，存 `source.json` - §1.7 写 `scripts/convert_to_kicad.py`，候选工具 `easyeda2kicad.py`（pypi，活跃维护） - 批处理扫 `data/raw/oshwhub/` → 输出 `data/processed/oshwhub//kicad/` - 跑 `kicad-cli sch erc / pcb drc` 做语法校验，失败样本记 `data/state/convert_failed.jsonl` - 目的：打通 oshwhub (EasyEDA) 与 bshada/open-schematics (KiCad) 两个生态的训练语料 ### 同步改动 - `docs/sources/oshwhub.md` §3.5 从"未开放"改为"需登录，纳入范围"；R4 风险更新 - `README.md` 数据源表加「登录态」列，加运行环境说明 ### 等待 - 广州云服务器到位 → 启动 Phase 0.5 - 账号登录凭据由 Charles 提供 --- ## 2026-04-23 19:55 oshwhub.md 重写成完整调研文档 **Claude 会话** Charles 要求把 12 493 总数验证、90 项目采样结果合进主调研文档。 `docs/sources/oshwhub.md` 重写为 9 节 + 2 附录的完整调研： 1. 一页纸 TL;DR 表 2. 站点架构 3. robots.txt 与合规 4. API 与抓取入口（列表 / SSR 详情 / 附件 CDN / 排除项 / 未开放端点） 5. **项目总数验证（新）**：三路 sort 一致 + 分页二分搜索（250 × 50 = 12 500 吻合）+ grade 覆盖抽样 6. **抽样语料特征（从 oshwhub_corpus_estimate.md 并入）**：体积 / 文件类型 / license 分布 7. Schema 映射 8. 速率与礼貌 9. 目录输出约定 10. 风险与未解决（7 条） 11. 附录：重跑命令、变更历史 删除重复文件 `oshwhub_corpus_estimate.md`（内容已并入 §5）。 --- ## 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` 数据源表加一行 **未下载**，等拍板 6.4 GB LFS 预算。 --- ## 2026-04-23 19:30 Phase 1 MVP：10 个高质量 oshwhub 项目入库 **Claude 会话**：承接仓库初始化 ### API 调研结论 - 列表 API：`GET https://oshwhub.com/api/project?page=N&pageSize=M&sort=hot`，无鉴权，返回 12493 个项目元数据（含 grade / likes / stars / views / forks） - 详情：`GET https://oshwhub.com/` 是 SSR HTML，嵌入 escaped JSON，含 `license` + `attachments[]`（每个带 name / src / size / md5 / ext / mime / download_count） - 附件 CDN：`https://image.lceda.cn{src}` — 已验证无鉴权直接下载 - EasyEDA 工程源 JSON（`u.lceda.cn`）需登录，v0.1 不抓 - 详细调研见 `docs/sources/oshwhub.md` ### 选 10 个高质量项目 判据：`grade == 4`（平台精品徽章） + `likes ≥ 100` + 应用领域多样（避免同类堆叠）+ 排除 `_copy` 派生仓。 10 个项目覆盖：调试器、加热台、盖革计数器、可调电源、焊台、智能手表、USB 测电流、ZVS 感应加热、AI 开发板、红外热成像。 ### MVP 爬虫 位置：`crawlers/oshwhub/crawler.py` - `list_projects()` — 列表 API 分页 - `pick_top()` — 按 like×3 + star + fork×2 + views/100 + comments×2 + grade×50 排序 - `parse_detail_html()` — 从 SSR HTML 提取 title / license / description / attachments - `crawl_one()` — 每项目产出：`metadata.json` / `description.md` / `cover.*` / `files/*` / `_urls.json` - QPS ≤ 0.5（`SLEEP_BETWEEN = 2.0`），UA 显式声明 `FacereDataset/0.1` ### 抓取与入库 - 10/10 成功，52 个附件，**524 MB** - Gitea LFS（v25.4.3 原生支持）+ 本地 `git-lfs 3.5.1`（用户态二进制装在 `~/.local/bin/`） - `.gitattributes` 规则：`data/raw/**/files/**` 一律走 LFS；元数据（metadata.json / description.md / \_urls.json / cover.\*）走普通 git - 每项目目录结构： ``` data/raw/oshwhub// ├── metadata.json # 按 schemas/project.schema.json ├── description.md ├── cover.{jpg,png,jpeg} ├── _urls.json # 所有原始 URL 清单 └── files/* # 原始附件（LFS） ``` ### 改动汇总 - 新增：`crawlers/oshwhub/{__init__,__main__,crawler}.py`、`schemas/project.schema.json`、`docs/sources/oshwhub.md`、`pyproject.toml` - 修改：`.gitattributes`（缩窄到 `data/raw/**/files/**`）、`.gitignore`（移除 `data/raw/*` 排除） ### 下一步建议 1. 验收 10 个项目元数据质量（随机抽 2-3 条对照原站） 2. 决定 Phase 1.4 放量目标（50？500？全量 12493？） 3. Phase 2 准备：GitHub KiCad repo 调研 --- ## 2026-04-23 19:40 fs-web-stream 排查 + schema 自动校验 **Claude 会话**（自主推进） ### fs-web-stream.jlc.com 定性 重新抓 `/CYIIOT/ST_LINK-V2_1` 并看 13 个 `fs-web-stream.jlc.com` 链接的上下文：全部是嘉立创服务侧栏/推广图标（3D 打印、发热片、Ican、EDA 扩展广场、开源硬件平台 badge 等），**与项目本身无关**。`image.lceda.cn/attachments/` 就是项目附件的唯一入口，已确认闭环。`docs/sources/oshwhub.md` 对应章节已更新。 ### scripts/validate.py jsonschema 做两层校验： - 默认：所有 `data/raw/**/metadata.json` 对 `schemas/project.schema.json` 的结构校验 - `--check-files`：另外验证每条 file 的本地 path 存在且 sha256 匹配 **结果**：10/10 项目两项全通过。 ### 新增 - `scripts/validate.py` - `pyproject.toml` 加 `jsonschema>=4.26` ### 待决策 - 放量规模 —— 已提供实测数据：**median ≈ 110 GB，p90 上界 ≈ 660 GB，建议预算 150–180 GB**（见 `docs/sources/oshwhub_corpus_estimate.md`） - 是否需要抓 `u.lceda.cn` 的 EasyEDA 源 JSON（需登录，v0.1 跳过） --- ## 2026-04-23 19:45 全量规模实测 + License 分布 **Claude 会话**（自主推进） 写 `scripts/estimate_size.py`，只抓详情 HTML 解析 `attachments[].size`，不下载；采样 90 个 hot 项目（3 页 × 30）。 **关键发现**： - 单项目 median 9 MB / mean 22 MB / p90 54 MB / max 204 MB；12493 全量 median 估算 **110 GB**，p90 上界 660 GB - **视频 (.mp4 + .qt) 占 54% 存储**！如果训练只要 PCB/原理图/BOM，加 `--skip-ext mp4,qt` 存储直接砍半 - License 分布健康：GPL 3.0 占 49%，Public Domain 21%，CC 系列 ~20%，CERN/TAPR OHL 6%；样本内无闭源 - **NC (Non-Commercial) 占 ~11%**，商用场景必须过滤 结果固化到 `docs/sources/oshwhub_corpus_estimate.md`，可随时重跑验证。 ### 建议 1. 存储预算定 **180 GB**（median + 15% buffer） 2. Phase 1.4 前给 crawler 加 `--skip-ext` 开关滤视频 3. 下游建立 license whitelist 过滤 NC / 未知 --- ## 2026-04-23 18:50 仓库初始化 & 数据源调研 **Claude 会话**：初始化 完成： - 从 `git.deepknow.site/Facere/FacereDataset` 克隆空仓到 `~/repo/FacereDataset` - 调研立创开源平台（oshwhub.com）初步数据： - `robots.txt` 仅 Disallow `/posts`，其他路径允许 - 存在 `sitemap.xml`（首页 + explore + activities + market 等入口已列出） - 项目详情页路径为 `/detail/`（示例 `f0652fd2ae3e40b8a0ecc8dc773e3512`） - 图片 CDN：`image.lceda.cn/oshwhub/pullImage/...` - 文件下载：`fs-web-stream.jlc.com/fs-web-stream/file-operation/download/` - 页面是 Next.js SPA，首屏 HTML 800KB，但数据加载具体 API 入口需要浏览器 trace（留给 Phase 1.1） - 创建项目骨架： - `README.md` — 项目简介与数据源表 - `CLAUDE.md` — 项目级 Claude 指令（爬虫规约、合规红线、schema 要求） - `plan.md` — 6 阶段建设计划（Phase 0 骨架 → Phase 5 数据清洗 → Phase 6 持续运营） - `log.md` — 本文件 - `.gitignore` — 排除 `data/raw` `data/processed` `data/state` Python 缓存等 - 目录骨架 `crawlers/ schemas/ scripts/ data/{raw,processed,state} docs/{sources,}` - 每个空目录放 `.gitkeep` - 首次提交 & 推送到 `origin main` **下一步建议**： 1. 拍板存储方案（本地盘 / Gitea LFS / 外部 OSS）—— 影响 Phase 1.4 放量时机 2. 目标规模（1 万 / 10 万 / 全量） 3. 决定是否保留二进制附件或只存 URL 4. 完成上述 3 项后启动 Phase 1.1（用 `chrome-devtools` MCP 录 oshwhub 的 network trace 定位真实 API）