自媒体集体安利之后,这个电子书仓库的 star 曲线还没拐头
自媒体集体安利之后,这个电子书仓库的 star 曲线还没拐头
过去一年,"两万四千本电子书,一个项目全搞定"这句话在中文技术社区被反复复述。CSDN、掘金、今日头条上的推荐文一篇接一篇,口径高度一致:24,071 本、1,000 个分类、EPUB/MOBI/AZW3 三种格式、覆盖帆书、微信读书、京东读书、喜马拉雅。
这些数字并非凭空捏造,它们确实来自仓库自己的统计文件 parse-stats.json。但"存在这个数字"和"这个数字意味着自媒体所说的那件事"是两回事。本文把仓库源码和数据逐层拆开,看三件事:这套统一话术是怎么形成的、仓库实际提供的能力边界在哪里、以及这条增长曲线还能靠什么撑下去。
一、同一套话术:源头只有一段 README
把 2025 年 10 月到 2026 年 10 月的几篇代表性文章并排放,重合度高得不像巧合。
| 时间 | 平台 | 核心表述 | 互动数据 |
|---|---|---|---|
| 2025-10-19 | CSDN | 整合多平台资源,分类清晰、搜索便捷 | 3,710 阅读 / 26 收藏 |
| 2026-08-18 | 掘金 | 两万四千本、上千分类、三种格式、四个来源平台 | 480 阅读 / 7 赞 / 0 评论 |
| 2026-08-30 | CSDN | 16.9k+ stars、24,071 本、1,000+ 分类、三种格式 | 830 阅读 / 5 收藏 |
"帆书、微信读书、京东读书、喜马拉雅"这四个平台名,逐字出现在几乎所有推荐文里。它其实来自 README.md 的第 14 行:
该库涵盖了帆书app(原樊登读书)、微信读书、京东读书、喜马拉雅等读书app的大部分电子书。
"每本书都提供三种格式"同样来自 README 第 18 行。也就是说,绝大多数渠道文章并没有独立验证过这两个定语,它们只是把 README 的自述重新排版了一遍。
更值得注意的机制在 2026-08-30 那篇 CSDN 文章的页面上:文章顶部带着"本文由作者通过墨衍一键同步至各平台"的标记,下面列出的分发目标是 CSDN、微信公众号、微博、知乎、掘金、百家号、博客园、抖音、小红书——九个平台。当一篇内容可以一键铺满九个渠道,且后续跟进者只需改写标题就能再发一轮时,"集体安利"就不是自发的舆论共振,而是一条低成本的内容生产线。这也解释了为什么所有文章的论证结构都一样:先讲找书痛点,再报数字,最后提醒支持正版。
掘金那篇 2026-08-18 的文章甚至诚实地写下了自己的推断过程:"虽然作者没有公开详细的自动化流程,但从项目结构可以推断出大概。"作者看到 scripts/ 目录,推测里面有采集和清洗脚本。这个推测方向是对的,但文章没有打开脚本,也就没有发现脚本里写着什么。
二、24,071 不是一个书籍数,是一个"标签-书籍"对数
仓库的统计口径在 scripts/parse_md_to_json.py 里定义得很清楚:遍历 md/ 下 1,000 个 Markdown 文件,把每个表格行解析成一条记录,全部 extend 进同一个数组。
for md_file in md_files:
category, books = parse_single_file(md_file)
if books:
all_books.extend(books)
category_stats[category] = len(books)
这段代码没有任何跨文件去重。而 scripts/sync/test_batch_sync.py 的写入逻辑决定了同一本书必然出现在多个文件里:
tags = book_data.get('tags', [])
if tags:
for tag in tags:
books_by_tag[tag].append(book_data)
一本书在源站有几个标签,就会被写进几个 Markdown 文件。分类页是"索引视图",不是"归属关系"。于是 docs/all-books.json 里的 24,071 行,实际上是这样分布的:
- 24,071 行记录,去重后只有 11,387 个不同书名、11,349 个不同链接;
- 8,910 个书名出现了不止一次,平均每个书名挂在 2.11 个分类下;
- 极端的例子是《与机器赛跑》,同时出现在互联网、哲学、技术、生物、科普、经济六个分类里;《上海秘境》同样横跨六个分类。
打开 docs/index.html,首屏那个大号数字直接标着"总书籍数 24,071"。从数据契约的角度看,这个标签是错的:它统计的是索引条目数。真实可读的书目规模大约是它的一半,而这 11,387 还是一个上界,因为同名不同版本、套装与单册的差异无法从当前字段里区分。
分类维度的水分同样可以量化。1,000 个分类里,中位数只有 3 本书,535 个分类的书目数不超过 3 本(合计仅 942 条记录),775 个分类不超过 10 本。另一端,文学 2,711 本、历史 1,748 本,前 100 本以上的分类吃掉了 16,269 条记录,占全部的 67.6%。长尾里还躺着一批明显是源站标签噪声的条目:md/世界是.md、md/粮食、油脂及植物蛋白工程.md 各自只有 1 本书。
"1,000 个分类"作为宣传语很有冲击力,作为导航系统却接近失效——用户点开 535 个分类中的任意一个,只会看到一到三本书。它不是被设计出来的分类体系,而是被源站标签直接投影出来的结果。
三、三种格式与四个平台:两个无法被数据支撑的定语
这是仓库里最值得追问的一处。formats 字段看上去像是从每条记录里解析出来的,实际是一个常量:
# scripts/parse_md_to_json.py
book['language'] = 'ZH' # 默认中文,后续可优化
book['level'] = 'Unknown'
book['formats'] = ['epub', 'mobi', 'azw3'] # 从表格列名推断
注释写得很坦白:从表格列名推断。而 md/Python.md 的表格长这样——表头写着 epub/mobi/azw3,每一行的第三列只有一个 [下载] 链接:
| 书名 | 作者 | epub/mobi/azw3 |
| --- | --- | --- |
| Python高性能编程 | 戈雷利克/欧日沃尔德 | [下载](https://url89.ctfile.com/f/31084289-1357049494-9a6e10?p=8866) |
一条链接后面是一个网盘分享,里面是否真的躺着三个文件、三个文件是否对应同一版本,仓库里没有任何字段可以回答。相比之下,language 字段更彻底:24,071 行全是 ZH,level 字段全是 Unknown——两个字段看似做了国际化与难度分级,实际上从未被填充过。
平台来源的情况更清晰。对 all-books.json 做域名统计:
- 24,002 / 24,071 条链接指向
url89.ctfile.com,且路径前缀全部是/f/31084289-,分享参数p=全部为8866; - 剩余 69 条链接的字符串是"链接未找到",却仍然作为可点击记录进入了索引。
也就是说,这个"汇总了四个主流阅读平台"的宝库,在数据层面只对应一个网盘账号的分享目录。采集端本身也只配置了一个站点,scripts/sync/test_batch_sync.py 里:
BASE_URL = f"{BOOK_SITE_DOMAIN}/book-content-{{}}.html"
BOOK_SITE_DOMAIN 从环境变量或 config.py 读取,代码注释里的示例值是 https://www.dushupai.com。标签体系、书名、作者、下载链接,全部来自这一个源站。README 里的四个平台名,描述的是源站内容的宣称覆盖面,不是本仓库的采集范围——这两件事在传播中被合并成了一句"一个项目汇总所有平台"。
四、真正值得抄的部分:一条能跑完整链路的流水线
撇开被夸大的定语,这个仓库的工程实现有实打实的参考价值。整条链路是:异步采集 → 按标签扇出成 Markdown → 由 Markdown 生成 JSON → 由 JSON 生成静态站 → 定时增量更新。
采集层用 aiohttp 加信号量控并发,避免把源站打挂:
semaphore = asyncio.Semaphore(MAX_CONCURRENT)
async with aiohttp.ClientSession() as session:
tasks = [fetch_book_async(session, book_id, semaphore) for book_id in book_ids]
for coro in asyncio.as_completed(tasks):
book_data = await coro
写入层做了两处值得学的裁剪。第一处是隐私隔离——凡是链接里还带着源站域名的(通常是详情页而非真实下载页),直接丢弃,保证仓库里不出现源站地址:
if download_url and BOOK_SITE_DOMAIN in download_url:
continue
第二处是把网盘链接里的 ?pwd= 统一改写成 ?p=,适配网盘分享参数的格式差异。
增量更新不依赖时间戳,而是用"最大书籍 ID"做水位线,逻辑在 scripts/sync/incremental_sync.py:读取本地记录的 last_max_id,抓取源站首页当前最大 ID,两者相减得出待同步区间,只跑 last_max_id + 1 到 current_max_id。仓库根目录的 max_book_id_found.txt 记录着当前水位:64970。
编排层是三个 workflow,分工明确:
- incremental-sync.yml:
cron: '0 2 * * *',每天 UTC 2 点增量同步,之后重跑 README 热门分类和all-books.json; - full-sync.yml:只保留
workflow_dispatch,即手动触发,timeout-minutes: 600,并带--batch-size 20000分批,避免一次跑六万个 ID 时中途失败; - generate-site.yml:监听
scripts/**和md/**的 push,重建页面。
三个 workflow 里都写了同一段防御性代码:push 前先 git pull --rebase,push 失败后重新 fetch 再 rebase,最多重试 3 次。仓库唯一的那条 commit 信息恰好是"fix: 修复 GitHub Actions Git push 冲突问题"——这类双 workflow 同时写同一分支的竞态,是静态数据仓库最常见的坑,作者是被咬过之后才补上的。
前端层面,docs/search.js 的安全性做得比很多同类项目认真。搜索高亮需要把关键词拼进正则,作者先转义了正则元字符,再转义 HTML,并且对链接做了协议白名单:
let safeLink = "#";
if (b.link) {
const url = new URL(b.link, window.location.origin);
if (url.protocol === 'http:' || url.protocol === 'https:') {
safeLink = url.href;
}
}
这几个防御点对应的真实攻击面是:数据来自第三方站点,书名和作者完全不可信。一个叫 <img onerror=...> 的书名,如果没做 escapeHtml,就会在搜索结果里变成 XSS。作者在这里没有偷懒。
五、能直接验证的三个体验缺陷
第一,重复结果。 因为 searchBooks 只按关键词过滤、不做任何归并,同一本书会以不同分类标签反复出现:
return books.filter(b => {
return keywords.every(keyword =>
title.includes(keyword) || author.includes(keyword) || category.includes(keyword)
);
}).slice(0, MAX_RESULTS);
实测搜索"三体",返回 9 条记录,实际只有 5 种书:《〈三体〉中的物理学》出现 3 次(科普、三体、物理三个分类),《三体秘密》出现 2 次(三体、推理)。用户在结果列表里看到的是索引项,不是书。
第二,100 条硬截断。 MAX_RESULTS = 100,界面会显示"找到 100+ 条结果",但没有分页、没有"加载更多"。搜"文学"这类高频词时,用户永远只能看到按 JSON 顺序排在最前面的 100 条,且这个顺序与相关性无关——all-books.json 是按文件遍历顺序生成的,实际顺序取决于 md/ 目录的 glob 结果。
第三,首屏 7.1 MB。 docs/all-books.json 与 docs/books.json 的 MD5 完全一致(34de4e1183092c0a4a65fa6808004a30),各 7,132,158 字节。scripts/generate_index.py 在生成页面时把同一份 books 数组又写了一遍到 books.json,于是 docs/ 目录 14 MB 里有 7 MB 是纯冗余。search.js 的降级逻辑是先取 all-books.json、失败再取 books.json,运行时只会拉一份,但仓库体积翻倍,且首屏必须等这 7 MB 下载并 JSON.parse 完才可用——这直接解释了页面上那个"正在加载书籍数据"的等待态。
这三处都不是"架构问题",而是数据契约没定义清楚:索引项和书是两种实体,重复和截断是同一种症状。修法也不需要重写架构:
- 在
parse_md_to_json.py里以link(或title + author)为键做一次归并,把category从字符串改成数组,category字段保留首个值作为展示主分类。记录数会从 24,071 降到 11,349 左右,搜索重复问题与首屏体积同时减半。 - 生成的 JSON 按首字母或分类分片,前端按需
fetch分片;或者退一步,至少删掉books.json的重复写入,只保留一份。 - 把 69 条"链接未找到"的记录在解析阶段直接过滤,或单独标记为
unavailable,不要与可用记录混在同一个列表里。同理,formats应该由采集端在分享页内实际探测后写入,探测不到就留空——用列名反推字段值,是这套数据里最容易误导下游的一处。
六、热度还能靠什么撑住
本文无法拿到连续的 star 采样:GitHub API 在当前环境返回限流,网页端请求超时。能观测到的只有单点口径——2026-08-30 的第三方文章写的是"16.9k+ stars"。因此"曲线还没拐头"这个判断,只能用代理指标来支撑:从 2025 年 10 月到 2026 年 10 月,推荐类文章的产出没有停止,且开始出现二次加工(2026-10-05 的一篇"GitHub 趋势速报解读"已经把该项目当作"仓库可信度快速评估"的案例来讲)。持续被引用,说明注意力还在。
但注意力的形态值得警惕。掘金那篇 480 阅读、7 赞、0 评论;CSDN 那篇 830 阅读、5 收藏。收藏远高于评论,意味着读者完成的是"存起来以后用",而不是"用了之后回来讨论"。这是资源聚合类项目的典型曲线:star 涨得快,issue 涨得慢。前者衡量的是"我想拥有它",后者衡量的才是"我在用它"。当一个仓库的讨论区里没有"这本书的链接挂了""这个标签分类不对""为什么搜出来三条一样的"这类具体问题,它的 star 就尚未转化为使用。
参考同类项目的生命周期,这类链接聚合仓库通常在三到四个季度内遇到同一堵墙:网盘分享批量失效。当前数据里所有链接共用同一个分享账号前缀 31084289,这意味着失效不是渐进的,而是可能在某一天集中发生——账号被限、目录被清,24,000 条链接会同时变成死链。仓库目前没有任何链接健康度字段,也没有定期探活的 workflow。三个 workflow 里,两个在增量采集新书,一个在重建页面,没有一个是用来验证旧链接还活着的。
所以"热度还能走多久"的答案不在 star 数上,而在它是否愿意从"搬运"切换到"维护"。前者只需要一个能跑的爬虫,后者需要探活、去重、元数据补全、失效降级这一整套。前者已经做完了,后者一行都还没有。
顺带一个数据卫生的细节:sponsors.md 的赞助记录里有一条时间戳是 2026-11-11,晚于当前时间。金额都是 1 到 20 元的小额,留言集中在"谢谢整理"。这些真实的小额赞赏说明确实有人在用,但也说明这个项目的价值目前仍停留在"整理"这一层——而整理是可以被下一个爬虫复制的,维护不能。
七、结语
这个仓库值得存在的理由,不是那 24,071 这个数字,而是它证明了一件小事:用 aiohttp + Markdown 表格 + 一份静态 JSON,就能把分散的、需要登录才能看的书目信息变成可搜索、可离线、可 diff 的公共索引。这套流水线的每一段都不复杂,组合起来的可用性却超过很多号称"平台"的产品。
它现在缺的不是更多 star,而是一次诚实的自我描述:把"总书籍数"改成"索引条目数",把"三种格式"改成"网盘分享(格式以实际内容为准)",把"覆盖四个平台"改成"数据来自单一书源"。这些修改会让宣传语变弱,但会让 11,387 这个数字变硬。
至于那些还在批量复述"两万四千本"的推荐文,它们大概率不会改。这没关系——读者点进去搜一次"三体",看到九条结果里只有五种书,自己就会得出结论。