diff --git a/docs/sources/oshwhub_listing_full.md b/docs/sources/oshwhub_listing_full.md new file mode 100644 index 0000000..e59acfa --- /dev/null +++ b/docs/sources/oshwhub_listing_full.md @@ -0,0 +1,144 @@ +# oshwhub 全量 Listing 索引简报 + +**采集时间**：2026-04-28 +**数据**：`data/state/oshwhub_listing_full.jsonl`（28.4 MB，gitignore，可重抓） +**采集脚本**：`scripts/dump_listing_index.py` +**接口**：`https://oshwhub.com/api/project?origin={pro,std}&pageSize=1000&page=N`，无鉴权 +**耗时 / 流量**：35 次请求 × ~1 MB ≈ 35 MB / 71 秒（QPS=1） + +--- + +## 1. 总盘 + +| origin | 项目数 | 时间跨度 | 唯一作者数 | +|---|---:|---|---:| +| Pro | **21,202** | 2021-05 ~ 2026-04 | 10,536 | +| Std | **12,493** | 2016-07 ~ 2026-04 | 5,531 | +| **合计** | **33,695** | — | ~16,000 | + +> "项目"定义：listing API 返回的 `public:true` 公开项目；私有 / 草稿不计入。 +> +> Pro / Std 不重叠（单项目 origin 二选一）。 + +--- + +## 2. 增长趋势（按 `created_at` 年份） + +| year | Pro | Std | +|---:|---:|---:| +| 2016 | — | 1 | +| 2017 | — | 73 | +| 2018 | — | 30 | +| 2019 | — | 320 | +| 2020 | — | 2,545 | +| 2021 | 13 | 3,193 | +| 2022 | 1,718 | 3,394 | +| 2023 | 4,056 | 1,554 | +| 2024 | 6,827 | 905 | +| 2025 | 7,436 | 426 | +| 2026 (Q1) | 1,152 | 52 | + +**关键观察**： +- **Std 在 2021-2022 见顶后断崖下跌**（3394 → 1554 → 905 → 426），用户在迁出。 +- **Pro 2022 起线性增长**，2024-2025 合计占全 Pro 的 67%。 +- 2026 仅过 4 个月就有 1,152 Pro 新项目（外推全年 ~3,500，会比 2025 略降，但仍是主战场）。 + +→ **抓取策略含义**：Pro corpus 还在快速膨胀，索引建议每月增量重抓一次；Std 已基本静态。 + +--- + +## 3. 质量分层 + +| Tier | 条件 | Pro 命中 | Pro % | Std 命中 | Std % | +|---|---|---:|---:|---:|---:| +| S | grade≥4 & like≥50 | 390 | 1.8% | 193 | 1.5% | +| A | grade≥3 & like≥10 | 1,356 | 6.4% | 1,450 | 11.6% | +| B | grade≥2 & like≥5 | 2,292 | 10.8% | 3,951 | 31.6% | +| 总池 | grade≥1 | 20,028 | 94.5% | 9,510 | 76.1% | +| 末档 | grade==0 | 1,174 | 5.5% | 2,983 | 23.9% | + +**两点反直觉**： +- **Std 高质量比例 > Pro**（A 档 11.6% vs 6.4%）。Std 平台老，项目有时间累积点赞；Pro 大量是 2024+ 新项目，社交信号还没沉淀。 +- **Pro 末档比例反而低**（5.5% vs 23.9%）。可能是 grade 内部打分逻辑不同，Std 兜底更宽。 + +--- + +## 4. 互动指标分布 + +### like +| | p50 | p90 | p99 | max | +|---|---:|---:|---:|---:| +| Pro | 2 | 22 | 190 | 2,137 | +| Std | 6 | 40 | 207 | 1,457 | + +### views +| | p50 | p90 | p99 | max | +|---|---:|---:|---:|---:| +| Pro | 1,036 | 6,550 | 39,144 | 1,036,026 | +| Std | 3,362 | 13,519 | 53,663 | 348,877 | + +> Std 流量是 Pro 同档位的 ~3 倍（更老更普及）；但 Pro 头部单项 view 能上百万（X86 主板等）。 + +--- + +## 5. 头部作者（按项目数） + +### Pro top-10 +| # | username | n | +|---:|---|---:| +| 1 | course-examples | 79 | +| 2 | freakstudio | 79 | +| 3 | aknice | 69 | +| 4 | eda_kwazdnpkc | 64 | +| 5 | windskys | 56 | +| 6 | li-chuang-kai-fa-ban | 49 | +| 7 | dingcheng | 44 | +| 8 | o0v0o | 42 | +| 9 | xiaocc22 | 42 | +| 10 | eda_ycuzzivoa | 41 | + +### Std top-10 +| # | username | n | +|---:|---|---:| +| 1 | li-chuang-zhi-neng-ying-jian-bu | 183 | +| 2 | zhqsoft | 144 | +| 3 | jixin | 92 | +| 4 | Ismartware | 53 | +| 5 | FJ956391150 | 52 | +| 6 | an_ye | 51 | +| 7 | micespring | 48 | +| 8 | li-chuang-EDAjing-sai-xiao-zu | 47 | +| 9 | 583703056a | 46 | +| 10 | akatople | 46 | + +> 立创官方账号占据头部（`course-examples` / `li-chuang-kai-fa-ban` / `li-chuang-zhi-neng-ying-jian-bu` / `li-chuang-EDAjing-sai-xiao-zu`）—— 这些是 **开发板 / 比赛 / 教程** 系列，质量高、license 倾向 GPL/NC-SA，内容受立创内部审核。 +> +> 长尾比较健康：top 1 占比仅 0.4% (Pro) / 1.5% (Std)；不存在被少数账号 dominate 的情况。 + +--- + +## 6. listing API 注意事项（沉淀给后续爬虫开发） + +- **`origin` 默认值**：不带参数返回 Std；要 Pro 必须显式 `origin=pro`。 +- **`sort` 参数无效**：`hot/new/newest/latest/created_at/...` 全部静默 fallback 到隐式排序。实测排序 = grade desc → 内部质量分 desc。要"按时间排序"得自己拉全集后本地排。 +- **`pageSize` 无显式上限**：`pageSize=1000` 工作良好，单次响应 ~1 MB；`pageSize=30`（旧爬虫默认）效率低 30 倍。 +- **`license` 不在 listing**：要 license 必须挨个抓详情页 (`//`)，33,695 个 → QPS≤0.5 → ~19 小时；考虑同步抓索引时**只抓详情页**，不重抓 listing。 +- **`public:true` 隐含**：listing 只返公开项目；不过我们也只关心公开项目。 + +--- + +## 7. 后续放量决策的量化锚点 + +| 目标 | 候选池大小 | 估算开销（详情页 + 工程源） | +|---|---:|---| +| **保守**：S 档（grade≥4 & like≥50）双 origin | 583 | 1-2 小时详情，~50 GB Pro 工程源 + ~10 GB Std | +| **中度**：A 档（grade≥3 & like≥10）双 origin | 2,806 | ~7 小时详情，~250 GB Pro + ~25 GB Std | +| **激进**：B 档双 origin | 6,243 | ~14 小时详情，~500 GB Pro + ~60 GB Std | +| 全 Pro | 21,202 | 19h 详情，**~1 TB Pro 源** | +| 全 corpus | 33,695 | 19h 详情，~1.1 TB+ | + +> Pro 工程源体积估计基于已落库 5 项均值（最坏单项 481 MB），P50 约 30 MB；中度 + 激进档若加 size cap（如单项 ≤ 200 MB skip）能砍 30-40%。 + +**当前下一步建议**： +- 先按 **A 档**（2,806 项）在本地索引上 filter，做 license 详情扫描，得到"license 白名单 ∩ A 档"的真实候选清单 +- 再决定是否动手批量下源 diff --git a/log.md b/log.md index 7e79d5f..2343d9e 100644 --- a/log.md +++ b/log.md @@ -4,6 +4,47 @@ --- +## 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 会话** diff --git a/scripts/dump_listing_index.py b/scripts/dump_listing_index.py new file mode 100644 index 0000000..260ac25 --- /dev/null +++ b/scripts/dump_listing_index.py @@ -0,0 +1,126 @@ +"""Dump full oshwhub listing index for both origins to a local jsonl. + +只抓 listing API，不抓详情页、不抓附件、不抓工程源。结果落 +`data/state/oshwhub_listing_full.jsonl`，每行一条 listing 项。 + +Usage: + uv run python scripts/dump_listing_index.py + uv run python scripts/dump_listing_index.py --page-size 500 --sleep 0.5 + +API 注意： +- `sort` 参数被服务端静默忽略，无论传啥都返回隐式排序（grade desc → 质量 desc） +- 默认 `origin` 是 std；要 Pro 必须显式 `origin=pro` +- `pageSize` 实测 ≥1000 都接受，单次响应体 ~1 MB +""" + +from __future__ import annotations + +import argparse +import json +import math +import statistics as st +import sys +import time +from collections import Counter +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parent.parent)) +from crawlers.oshwhub.crawler import list_projects, make_client # noqa: E402 + +ORIGINS = ("pro", "std") +DEFAULT_OUT = Path("data/state/oshwhub_listing_full.jsonl") + + +def dump_origin(client, origin: str, page_size: int, sleep: float, sink) -> int: + # First call to learn `total` / `totalPage`. + res = list_projects(client, page=1, page_size=page_size, origin=origin) + total = res["total"] + n_pages = math.ceil(total / page_size) + written = 0 + for it in res["lists"]: + sink.write(json.dumps(it, ensure_ascii=False) + "\n") + written += 1 + print( + f"[{origin}] total={total} pages={n_pages} pageSize={page_size}", + flush=True, + ) + print(f" page 1/{n_pages}: {len(res['lists'])} items", flush=True) + for p in range(2, n_pages + 1): + time.sleep(sleep) + res = list_projects(client, page=p, page_size=page_size, origin=origin) + for it in res["lists"]: + sink.write(json.dumps(it, ensure_ascii=False) + "\n") + written += 1 + print(f" page {p:>2}/{n_pages}: {len(res['lists'])} items", flush=True) + if written != total: + print( + f" WARN: wrote {written} but server said total={total} " + f"(diff={total - written})", + file=sys.stderr, + ) + return written + + +def summarize(path: Path) -> None: + by_origin: dict[str, list[dict]] = {} + with path.open() as f: + for ln in f: + it = json.loads(ln) + by_origin.setdefault(it.get("origin") or "?", []).append(it) + print("\n===== summary =====") + print(f"file: {path} size={path.stat().st_size / 1024 / 1024:.1f} MB") + for origin, items in sorted(by_origin.items()): + if not items: + continue + likes = sorted(((i.get("count") or {}).get("like") or 0) for i in items) + views = sorted(((i.get("count") or {}).get("views") or 0) for i in items) + grades = Counter(i.get("grade") for i in items) + # date range from created_at + dates = sorted(i.get("created_at") or "" for i in items if i.get("created_at")) + date_min = dates[0][:10] if dates else "?" + date_max = dates[-1][:10] if dates else "?" + print(f"\n[{origin}] n={len(items)}") + print( + f" likes: median={likes[len(likes) // 2]} " + f"p90={likes[int(len(likes) * 0.9)]} " + f"p99={likes[int(len(likes) * 0.99)]} max={likes[-1]}" + ) + print( + f" views: median={views[len(views) // 2]} " + f"p90={views[int(len(views) * 0.9)]} max={views[-1]}" + ) + print(f" grade: {dict(sorted(grades.items(), key=lambda kv: -(kv[0] or 0)))}") + print(f" dates: {date_min} .. {date_max}") + # Quality tiers (handy for batch sizing) + tier_grade3 = sum(1 for i in items if (i.get("grade") or 0) >= 3) + tier_like10 = sum( + 1 + for i in items + if ((i.get("count") or {}).get("like") or 0) >= 10 + and (i.get("grade") or 0) >= 3 + ) + print(f" tier: grade>=3: {tier_grade3} grade>=3 & like>=10: {tier_like10}") + + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser() + ap.add_argument("--out", type=Path, default=DEFAULT_OUT) + ap.add_argument("--page-size", type=int, default=1000) + ap.add_argument("--sleep", type=float, default=1.0, help="seconds between page calls") + args = ap.parse_args(argv) + + args.out.parent.mkdir(parents=True, exist_ok=True) + print(f"writing -> {args.out}") + t0 = time.time() + with args.out.open("w") as sink, make_client() as client: + total = 0 + for origin in ORIGINS: + total += dump_origin(client, origin, args.page_size, args.sleep, sink) + sink.flush() + print(f"\ndone: {total} items in {time.time() - t0:.1f}s") + summarize(args.out) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main())