# FacereDataset 执行日志

时间倒序，最新在顶部。

---

## 2026-04-24 00:25  打通 pro.lceda.cn 工程源完整链 + EPRO2 格式解析

**Claude 会话**

核心成果：**立创 EDA Pro 工程源的 API + 加密 + 格式三层全打通**。

### 完整链路

```
1. GET /api/v4/projects/<PROJ>                                    → branch_uuid
2. GET /api/v4/projects/<PROJ>/branches/<BRANCH>                  → history_uuid
3. GET /api/v4/projects/<PROJ>/branches/<BRANCH>/histories/<HIST> → {key, iv, dataStrUrl}
4. GET <dataStrUrl> (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: <PROJ_UUID>` / `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/<uuid>` | 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/<uuid>` 工程源 JSON，存 `source.json`
- §1.7 写 `scripts/convert_to_kicad.py`，候选工具 `easyeda2kicad.py`（pypi，活跃维护）
- 批处理扫 `data/raw/oshwhub/` → 输出 `data/processed/oshwhub/<uuid>/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/<path>` 是 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/<uuid>/
  ├── 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/<uuid>`（示例 `f0652fd2ae3e40b8a0ecc8dc773e3512`）
  - 图片 CDN：`image.lceda.cn/oshwhub/pullImage/...`
  - 文件下载：`fs-web-stream.jlc.com/fs-web-stream/file-operation/download/<snowflake-id>`
  - 页面是 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）