From b0ddcf3f14e495b277a92197e843dd1d38fa5363 Mon Sep 17 00:00:00 2001 From: Zhang Jiahao Date: Thu, 23 Apr 2026 20:57:30 +0800 Subject: [PATCH] =?UTF-8?q?Allow=20login=20content;=20plan=20cloud=20infra?= =?UTF-8?q?,=20storage=20tiers,=20EDA=E2=86=92KiCad=20conversion?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- CLAUDE.md | 11 ++++-- README.md | 20 +++++----- docs/sources/oshwhub.md | 20 +++++----- log.md | 50 ++++++++++++++++++++++++ plan.md | 86 +++++++++++++++++++++++++++++++++++++---- 5 files changed, 158 insertions(+), 29 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index c8cf8b2..de0f053 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -25,7 +25,11 @@ - **缓存**：所有 HTTP 响应落盘（`data/raw/...` + `requests-cache` 或 httpx + diskcache），重跑不要重新打目标站。 - **UA**：声明为 `FacereDataset/ (+; contact:)`，不要伪造浏览器。**例外**：目标站主动封标识 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/.json`（游标、已处理 ID 集合）。 @@ -36,10 +40,11 @@ ## 合规红线 -- 不抓登录墙后的内容。 +- **登录后的内容在范围内**（须合法账号，见上文"登录态"）；但**禁止**盗号、共享号、撞库号。 - 不绕过付费墙、不破解 DRM。 -- 遇到站点明确声明"禁止抓取/训练"的内容，跳过并记录到 `data/state/_excluded.jsonl`。 +- 遇到站点明确声明"禁止抓取 / 禁止训练"的内容（robots.txt、ToS、meta 标签），跳过并记录到 `data/state/_excluded.jsonl`。 - 每条记录**必须**保留 `license` 字段；无法判定的标 `license: "unknown"` 并在下游过滤时默认剔除。 +- 登录凭据管理：只存云服务器 `~/.secrets/`，不入 git、不入日志、不入 metadata.json。 ## 约定（项目内部） diff --git a/README.md b/README.md index 1f40b08..8011675 100644 --- 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)。 diff --git a/docs/sources/oshwhub.md b/docs/sources/oshwhub.md index 53048e9..30925f4 100644 --- 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/` | `{"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/` | `{"code":104001,"success":false}` | 返回项目完整元数据（待验证） | +| `u.lceda.cn/api/projects` | HTTP 401 "尚未登录" | EasyEDA 编辑器的工程列表 | +| `u.lceda.cn/api/project/` | 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// | 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 策略未实现 | diff --git a/log.md b/log.md index e24388e..6170c42 100644 --- 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/` 工程源 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 会话** diff --git a/plan.md b/plan.md index c293ef3..536cd11 100644 --- 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/-.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/`、`/api/document//source` +- [ ] 扩展 `crawlers/oshwhub/crawler.py`： + - `--with-source` 开关触发登录态抓取 + - 把工程源 JSON 存到 `data/raw/oshwhub//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//source.json` + - 输出：`data/processed/oshwhub//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` 还是全保？