Allow login content; plan cloud infra, storage tiers, EDA→KiCad conversion

Why: - 策略调整：登录后才能访问的内容从"禁止"改为"纳入本项目范围"，同时明确凭据管理红线（合法账号、不入 git、云服务器隔离）。解锁 u.lceda.cn 工程源 JSON，这是训练数据质量的关键升级。 - 计划中"存储"和"运行环境"一直模糊，现在按 Charles 提供的广州云服务器 + 存储分级演进（Gitea LFS → 对象存储）给出清晰路径。 - 打通 oshwhub (EasyEDA) 与 bshada/open-schematics (KiCad) 两个生态，需要一个 EDA→KiCad 批转换脚本。先把它纳入 plan，等拿到工程源再实现。 What: - CLAUDE.md: 登录态条款从"不抓"改为"合法账号可抓"，凭据管理写死在 ~/.secrets/，事件记 docs/secrets.md；合规红线同步更新 - plan.md §0.5: 新增基础设施段（机器初始化 / 调度 / 登录态获取） - plan.md §1.4: 存储分级演进（< 50 GB 云盘，50-200 GB 评估，> 200 GB 迁对象存储） - plan.md §1.6: 登录态抓 u.lceda.cn 工程源 - plan.md §1.7: scripts/convert_to_kicad.py 批处理，候选 easyeda2kicad.py - plan.md 风险表: 加账号封禁 / 转换失败 / 云服务器单点故障三条 - docs/sources/oshwhub.md: u.lceda.cn 从"未开放"移到"需登录，已纳入范围" - README.md 数据源表: 加"登录态"列 + 运行环境说明 - log.md: 本次策略变更记录未改：未新增 docs/infra.md（等机器到位 + 真实细节后再写），scripts/convert_to_kicad.py 尚未实现（等拿到工程源样本再实现）。 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-23 20:57:30 +08:00
parent ba501c328c
commit b0ddcf3f14
5 changed files with 158 additions and 29 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -25,7 +25,11 @@
 - **缓存**：所有 HTTP 响应落盘（`data/raw/...` + `requests-cache` 或 httpx + diskcache），重跑不要重新打目标站。
 - **UA**：声明为 `FacereDataset/<version> (+<repo-url>; contact:<email>)`，不要伪造浏览器。**例外**：目标站主动封标识 UA、且内容属公开静态资源时，允许切 lightpanda/web-access 真浏览器模式，并在 commit message 说明原因。
 - **robots.txt**：每个爬虫 **必须** 先查 `robots.txt`；命中 Disallow 的路径直接跳过，不要"绕过"。
- **登录态**：本项目**不**抓需要登录的内容。
+- **登录态**：登录后才能访问的内容**在本项目范围内**。使用前提：
+  - 账号必须是我们合法持有的（本人 / 授权的），**禁止**盗号、共享号、撞库号
+  - 依然不绕付费墙、不破 DRM、不抓对方显式标注"禁止训练 / 禁止抓取"的内容
+  - 登录凭据集中管理在云服务器的 `~/.secrets/`（见 `docs/infra.md`），**禁止**写进 git / 环境变量明文、日志
+  - cookie / session 变更时写短笔记到 `docs/secrets.md`（不含值，只含"YYYY-MM-DD 换号 / 重登 oshwhub"这类事件）
 - **失败重试**：指数退避 + jitter；连续 5xx / 429 超过阈值要停爬、提醒人介入，不要傻重试。
 - **断点续跑**：state 记到 `data/state/<site>.json`（游标、已处理 ID 集合）。

@@ -36,10 +40,11 @@

 ## 合规红线

- 不抓登录墙后的内容。
+- **登录后的内容在范围内**（须合法账号，见上文"登录态"）；但**禁止**盗号、共享号、撞库号。
 - 不绕过付费墙、不破解 DRM。
- 遇到站点明确声明"禁止抓取/训练"的内容，跳过并记录到 `data/state/<site>_excluded.jsonl`。
+- 遇到站点明确声明"禁止抓取 / 禁止训练"的内容（robots.txt、ToS、meta 标签），跳过并记录到 `data/state/<site>_excluded.jsonl`。
 - 每条记录**必须**保留 `license` 字段；无法判定的标 `license: "unknown"` 并在下游过滤时默认剔除。
+- 登录凭据管理：只存云服务器 `~/.secrets/`，不入 git、不入日志、不入 metadata.json。

 ## 约定（项目内部）

--- a/README.md
+++ b/README.md
@@ -12,15 +12,17 @@

 ## 数据来源（第一批）

-| 站点 | URL | 覆盖 | 许可 | 抓取复杂度 |
-|------|-----|------|------|-----------|
-| 立创开源平台 | 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） |
-| CERN OHR | ohwr.org | 高质量工业级 | CERN-OHL | 低 |
-| Wikifactory | wikifactory.com | 社区项目 | 作者自定 | 中 |
+| 站点 | URL | 覆盖 | 许可 | 复杂度 | 登录态 |
+|------|-----|------|------|--------|--------|
+| 立创开源平台 | oshwhub.com | 12 493 公开项目（附件 + 元数据） | GPL 3.0 / Public Domain / CC-BY-SA 为主 | 中 | 不需要 |
+| 立创 EDA 工程源 | u.lceda.cn | 原理图 + PCB + 组件 JSON | 同 oshwhub 项目 | 中 | **需要**（合法账号，见 CLAUDE.md） |
+| **HF** `bshada/open-schematics` | huggingface.co | 10K+ KiCad 已预处理 schematics | CC-BY-4.0 | 极低（整包镜像） | 不需要 |
+| GitHub | github.com | KiCad / EasyEDA repo | 各 repo 自定 | 低（gh API） | 不需要 |
+| Hackaday.io | hackaday.io | 项目叙事 + 文件 | 作者自定 | 中 | 不需要 |
+| CERN OHR | ohwr.org | 高质量工业级 | CERN-OHL | 低 | 不需要 |
+| Wikifactory | wikifactory.com | 社区项目 | 作者自定 | 中 | 不需要 |
+
+**运行环境**：专用云服务器（广州），登录凭据集中在 `~/.secrets/`。详情见 `docs/infra.md`（部署后创建）。

 详细爬取计划见 [`plan.md`](./plan.md)；当前已入库项目清单见 [`projects.md`](./projects.md)。

--- a/docs/sources/oshwhub.md
+++ b/docs/sources/oshwhub.md
@@ -17,7 +17,7 @@
 | 单项目体积中位数 | **9 MB**（mean 22 MB, p90 54 MB, max 204 MB） | §5.1 |
 | 全量存储估算 | **110 GB (median)** / 660 GB (p90 上界) | §5.1 推算 |
 | 反爬风险 | 低 | 列表 API 无 rate-limit 实测，建议 QPS ≤ 0.5 自律 |
-| 登录态要求 | 不需要 | 所有数据走匿名端点，见 §3 |
+| 登录态要求 | **匿名够用但登录更全** | 公开元数据 + 附件走匿名端点（见 §3）；**工程源 JSON 需登录**（见 §3.5 & `plan.md` §1.6） |
 | 当前已入库 | 10 项目 / 52 附件 / 535 MB | 见仓库 `projects.md` |

 **爬虫实现**：`crawlers/oshwhub/crawler.py`
@@ -149,16 +149,18 @@ https://image.lceda.cn{attachments[].src}

  **与项目本身无关**，爬虫应跳过。

-### 3.5 未开放 / 需登录的端点
+### 3.5 需登录的端点（纳入本项目范围，待 Phase 1.6 实现）

-| 端点 | 现象 | 说明 |
+| 端点 | 现象（匿名） | 登录后预期 |
 |---|---|---|
-| `/api/project/<uuid>` | `{"code":104001,"success":false}` | GET / POST / 带参数均失败；疑似需 session，作用不明 |
-| `u.lceda.cn/api/projects` | HTTP 401 "尚未登录" | EasyEDA 编辑器的工程源（真正的 schematic / PCB JSON），需登录态 |
-| `u.lceda.cn/api/project` | 302 重定向 | 同上 |
-| `/api/search/*` | 空响应 | 可能需要 CSRF token |
+| `/api/project/<uuid>` | `{"code":104001,"success":false}` | 返回项目完整元数据（待验证） |
+| `u.lceda.cn/api/projects` | HTTP 401 "尚未登录" | EasyEDA 编辑器的工程列表 |
+| `u.lceda.cn/api/project/<uuid>` | 302 重定向 | **工程源 JSON（schematic + PCB + 组件）— 训练数据最关键的一层** |
+| `/api/search/*` | 空响应 | 可能可用（待验证） |

-**当前策略**：通过 SSR HTML 解析拿到所有公开字段，工程源 JSON（`u.lceda.cn`）留作 v0.2+ 评估是否值得引入登录态。
+**策略**（按 `CLAUDE.md` "登录态"条款）：使用合法账号登录后抓，账号放云服务器 `~/.secrets/`，QPS ≤ 0.2 自律防封号，凭据不入 git。
+
+实施见 `plan.md` §1.6；抓到的源 JSON 会走 `scripts/convert_to_kicad.py`（§1.7）统一到 KiCad 格式。

 ---

@@ -343,7 +345,7 @@ data/raw/oshwhub/<uuid>/
 | R1 | 站点加反爬（UA 指纹 / 验证码 / IP 限） | 放量中断 | 自律 QPS ≤ 0.5；若触发切换到 `lightpanda` 或真 Chrome + 降速 |
 | R2 | `license: "unknown"` 或非标准字符串 | 下游合规风险 | 严格 whitelist 过滤；`oshwhub_license_normalize` 待建 |
 | R3 | 单项目附件 > 100 MB | LFS 存储激增 | 目前 p90=54 MB 可接受；大于阈值记录 URL 不下载的开关待加 (`--max-file-size`) |
-| R4 | EasyEDA 源 JSON 不可得 | 训练数据缺了"真正的源" | v0.2+ 评估登录爬的 ROI |
+| R4 | EasyEDA 源 JSON 需登录 | 账号被封 → 工程源获取中断 | Phase 1.6 登录爬，QPS ≤ 0.2，账号隔离在云服务器 `~/.secrets/`，必要时多号轮询 |
 | R5 | 长描述 HTML 格式保真 | 文本语料噪声 | 当前只存简介；长文本提取（含图片/表格）留待 Phase 5 清洗 |
 | R6 | `grade` 字段含义未官方公开 | 质量筛选判据模糊 | 经验：grade=4 是精品徽章；其它档位抽样判据后续补 |
 | R7 | 增量更新策略 | 重复抓取浪费 | `updated_at` 对比 + LFS prune 策略未实现 |
--- a/log.md
+++ b/log.md
@@ -4,6 +4,56 @@

 ---

+## 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 会话**
--- a/plan.md
+++ b/plan.md
@@ -26,6 +26,36 @@

 ---

+## Phase 0.5 — 基础设施 / 运行环境
+
+**目标**：把爬取从本地 dev 机迁到专用云服务器（广州，已规划），集中管理登录凭据、磁盘和长跑任务。
+
+### 0.5.1 云服务器初始化（待机器到位）
+
+- [ ] 机器规格确认（CPU / 内存 / 磁盘初始容量；广州可用区）
+- [ ] 基础环境：
+  - [ ] 系统升级 + 防火墙
+  - [ ] 安装：`git`, `git-lfs`, `uv`, `python 3.11+`, `jq`, `curl`
+  - [ ] 创建非 root 用户 + SSH key（不允许密码登录）
+- [ ] 克隆仓库：`git clone https://git.deepknow.site/Facere/FacereDataset.git ~/repo/FacereDataset`
+- [ ] `git lfs install` + 配置 Gitea 带 token 的 remote
+- [ ] `uv sync` 安装依赖
+- [ ] 凭据目录：`~/.secrets/` (mode 700)，放 Gitea token、oshwhub cookie、其它登录态
+- [ ] 写 `docs/infra.md` 记录主机 ID、用户、路径、端口开放情况（**不**含凭据值）
+
+### 0.5.2 调度
+
+- [ ] 单次长跑：`tmux` / `nohup` + 输出落 `~/logs/<site>-<date>.log`
+- [ ] 定期增量：`systemd timer`（优先）或 `cron`，每周扫新增 / 更新
+- [ ] 磁盘监控：` df -h | cron` 告警阈值 80%
+
+### 0.5.3 登录态获取（按站点）
+
+- [ ] oshwhub / u.lceda.cn：用浏览器登录后导出 cookie → 转 `~/.secrets/oshwhub-cookies.txt`，httpx 通过 `cookies=` 注入
+- [ ] 换号 / 重登事件记到 `docs/secrets.md`（只写事件，不写值）
+
+---
+
 ## Phase 1 — 立创开源平台（oshwhub.com）MVP ✅ 首批完成

 **目标**：跑通 10 个项目的完整抓取，验证 schema。
@@ -56,13 +86,49 @@
 ### 1.4 放量（待决策）

 - [ ] 定目标规模：50 / 500 / 5000 / 全量 12493
- [x] 实测规模分布（见 `docs/sources/oshwhub_corpus_estimate.md`）：
+- [x] 实测规模分布（见 `docs/sources/oshwhub.md` §5）：
  - median/proj 9 MB → 全量 **~110 GB**（合理预算）
  - p90 上界 **660 GB**
  - mp4+qt 视频占 54% → 加 `--skip-ext mp4,qt` 可省一半
- [ ] 未解决：
-  - `u.lceda.cn` EasyEDA 工程 JSON（需登录，v0.1 跳过）
-  - 增量更新：`updated_at` 变动检测 + LFS prune 策略
+- [ ] **存储分级**（按规模演进）：
+  - **Phase 1.x 前期（< 50 GB）**：直接落云服务器磁盘，`git-lfs push` 到 Gitea
+  - **放量中期（50 – 200 GB）**：Gitea LFS 容量压力评估；可选方案 (a) 服务器挂载大盘扩容，(b) 分批 push 分仓（按月 / 按 grade 档位切仓库）
+  - **放量后期（> 200 GB）**：迁移到**网盘 / 对象存储**（候选：阿里云 OSS、腾讯 COS、MinIO 自建），Gitea 只存 metadata + 指针
+  - [ ] 选型决策点：达到 50 GB 时评估，**不**过早迁移
+- [ ] 增量更新：`updated_at` 变动检测 + LFS prune 策略（未实现）
+- [ ] 登录态工程源（u.lceda.cn EasyEDA JSON）现在纳入范围，见 §1.6
+
+### 1.6 登录态工程源抓取（u.lceda.cn）
+
+**目标**：拿到立创 EDA 的**真正工程源 JSON**（含原理图、PCB、组件数据），而不只是用户附件。是训练数据质量的关键升级。
+
+- [ ] 在广州云服务器上用合法账号登录 oshwhub / EasyEDA，导出 cookie
+- [ ] 探明 `u.lceda.cn/api/...` 的项目源下载端点：
+  - `/api/projects` 返回 401（需 session）——登录后试
+  - 可能的端点：`/api/project/<uuid>`、`/api/document/<uuid>/source`
+- [ ] 扩展 `crawlers/oshwhub/crawler.py`：
+  - `--with-source` 开关触发登录态抓取
+  - 把工程源 JSON 存到 `data/raw/oshwhub/<uuid>/source.json`（LFS）
+  - schema 加 `source_format: "easyeda"` 字段
+- [ ] 账号速率更保守：登录态 QPS ≤ 0.2，避免被封号
+
+### 1.7 立创 EDA → KiCad 格式转换
+
+**目标**：把 `source.json`（立创 EDA / EasyEDA 格式）批量转成 KiCad 原生格式（`.kicad_sch` + `.kicad_pcb` + 可选 `.pretty` 库），打通 oshwhub（EasyEDA 生态）与 `bshada/open-schematics`（KiCad 生态）的统一训练语料。
+
+**预选工具**：[`easyeda2kicad`](https://github.com/uPesy/easyeda2kicad.py)（pypi 包，活跃维护）
+- 支持 EasyEDA → KiCad 6/7/8 symbol / footprint / 3D model 转换
+- 可能需要扩展以支持整个 project JSON → `.kicad_pro` + 关联文件
+
+- [ ] 调研 `easyeda2kicad.py` 的整工程转换能力；若只支持单符号 / 封装，评估是否需要自写 orchestrator
+- [ ] 写 `scripts/convert_to_kicad.py`：
+  - 输入：`data/raw/oshwhub/<uuid>/source.json`
+  - 输出：`data/processed/oshwhub/<uuid>/kicad/` 下的 `.kicad_sch`、`.kicad_pcb` 等
+  - 支持批处理：`--input data/raw/oshwhub/ --output data/processed/oshwhub/` 扫全目录
+  - 失败样本落 `data/state/convert_failed.jsonl`（记 uuid + 原因）
+  - 转换后跑 KiCad CLI `kicad-cli sch erc` / `pcb drc` 做语法校验
+- [ ] 产出统计：转换成功率、常见失败模式，反馈到工具选型
+- [ ] 运行：云服务器定期批处理（每次爬完新项目后跑）

 ### 1.5 纳入第三方预处理数据集 `bshada/open-schematics`

@@ -143,11 +209,15 @@
 |-----|-----|-----|
 | oshwhub 反爬加强 | 卡住 Phase 1 | 切 lightpanda/真 Chrome；降速；部分内容弃 |
 | 许可证字段缺失 / 模糊 | 下游训练合规风险 | 默认剔除 `license: unknown`；建 whitelist |
-| 单个项目附件过大（>100MB） | 存储爆炸 | Phase 1 调研时统计分布；大文件走外部 OSS，记录 URL 不本地化 |
+| 单个项目附件过大（>100MB） | 存储爆炸 | 实测 p90=54MB 可接受；大于阈值走外部 OSS、只存 URL |
 | GitHub API rate limit | Phase 2 慢 | 使用已登录 `gh` token；必要时换 fine-grained PAT |
 | 站点改版 | 爬虫失效 | 爬虫带 schema 自检，HTML 结构变化时告警 |
+| **登录态账号被封** | §1.6 登录态工程源卡住 | 账号 QPS ≤ 0.2；多账号轮询；凭据泄露应急计划（见 `docs/infra.md`） |
+| **EDA→KiCad 转换缺失字段** | §1.7 产物不可用 | 每轮记录失败样本；扩展工具 or 保留原始 JSON 作 fallback |
+| **云服务器单点故障** | 长跑任务中断 | 数据及时 push 到 Gitea；定时快照云盘；抓取进度存 `data/state/` |

 **未决**：
- 数据存储方案：本地盘（够吗？）、Gitea LFS、或外挂对象存储？
- 是否要保留图片/Gerber/STEP 的二进制，还是只存 URL？
- 目标规模：第一版想要 1 万 / 10 万 / 全量？
+- 数据规模目标：第一版想要 1 万 / 10 万 / 全量？
+- 存储分级切换阈值：什么时机从 Gitea LFS 迁到对象存储？（当前提议 200 GB）
+- 对象存储选型：阿里云 OSS / 腾讯 COS / MinIO 自建？
+- 是否保留视频（mp4/qt 占 54% 存储）：加 `--skip-ext` 还是全保？