RSSHub + Folo：从原理到源码

怎么读这份导读

这份导读给想做三件事的人：读懂 RSSHub 和 Folo 的工作原理；给它们提 PR；在它们之上定制出自己喜欢的 RSS 阅读器。

全文按这个顺序展开：

1. 全景：RSS 生态本来有什么问题，两个项目各自解决哪一段，它们之间靠什么连起来。
2. RSSHub：一个请求从进入到吐出 RSS 的完整路径，路由、缓存、抓取、输出、部署。
3. Folo：monorepo 的结构、离线优先的数据层、同步引擎、Electron 架构、AI 功能。
4. 端到端：把 rsshub://hackernews 从“订阅”到“显示在时间线上”串一遍。
5. 开源许可证：AGPL-3.0 对“自己用、提 PR、发 fork、发安装包、对外提供服务”分别意味着什么。
6. 贡献与定制：开发环境、提交规范、适合入手的方向，以及“打造自己的阅读器”的三条路线。

每张图都是可交互的 React Flow 风格节点图：在 HTML 里把鼠标悬停在节点上，会高亮它的所有连接。正文里蓝底的链接都指向 GitHub 上固定 commit 的源码行，所以即使上游继续改动，链接也不会漂移。

全景：RSS 生态的问题与两个项目的分工

RSS 本来要解决什么，现在又卡在哪里

RSS/Atom 的设想很简单：网站发布一份机器可读的“更新列表”，阅读器定时拉取，用户在一个地方看所有来源的更新，不依赖算法推荐、不需要逐个打开网站。

现实中它卡在三处：

两个项目的“要求、目标、限制”

理解一个系统最快的方法，是先弄清它在什么约束下做取舍。下面这张表是整篇导读的骨架，后面每一节都在回答“它是怎么在这些限制下做到的”。

RSSHub：把任何网站变成 feed

一个请求的完整路径

RSSHub 是一个 Hono Web 服务。启动入口 lib/index.ts 用 @hono/node-server 监听端口（默认 1200，见 config.ts），可选 cluster 多进程。真正的应用组装在 lib/app-bootstrap.tsx：一串中间件，最后挂上路由表。

Hono 的中间件是“洋葱模型”：每个中间件先做“进去时”的事，调用 await next() 进入下一层，等内层返回后再做“出来时”的事。RSSHub 巧妙地利用了这一点：路由 handler 只返回一个 JS 对象（Data），过滤、改写、渲染成 XML 全部发生在“出来的路上”。

几个值得记住的细节：

• handler 不碰输出格式。 template.tsx 在 await next() 之后读取 ctx.get('data')，再根据 ?format= 选择输出（rss / atom / json / rss3）。所以你写路由时只需要关心“这个网站有哪些条目”，同一条路由自动支持所有格式。
• 过滤是通用能力。 parameter.ts 同样在 next() 之后工作：?filter= 正则过滤（L239）、?filterout=、?limit=、?mode=fulltext 全文抽取、?opencc= 简繁转换、?brief= 截断等。这些参数对所有几千条路由都生效，路由作者不用自己实现。
• 错误也是统一的。 handler 抛出的 InvalidParameterError 等错误由 app.onError 统一渲染（L52）。

路由系统：文件即路由，构建期生成路由表

RSSHub 的路由按命名空间组织：每个网站一个目录 lib/routes/<namespace>/，目录里一个 namespace.ts 描述网站本身，若干个路由文件各导出一个 route 对象。当前快照里有约 2000 个命名空间。

问题来了：几千个路由文件，如果启动时全部 import，启动会极慢、内存会很大。RSSHub 的解法分两步：

1. 构建期扫描。 scripts/workflow/build-routes.ts 遍历所有路由文件，提取每条路由的元数据（path、名称、参数、radar 规则、分类……），生成 assets/build/routes.js。这份文件同时也是文档站和 Radar 规则的数据来源。
2. 运行期懒加载。 registry.ts 读入路由表，registerRssRoutes 为每个命名空间创建 app.basePath('/<namespace>')，为每条路由注册一个包装 handler；直到第一次有请求命中，才真正 import 对应的路由模块（L194），之后缓存在 routeData.handler 上。

路由的数据契约：Route、Data、DataItem

路由作者和框架之间只靠三个类型交流，全部定义在 lib/types.ts：

注意 Route.view 用的 ViewType 枚举：Articles=0, SocialMedia=1, Pictures=2, Videos=3, Audios=4, Notifications=5。这正是 Folo 的 6 种视图，RSSHub 的路由作者在声明路由时就告诉了 Folo“这个源应该用哪种界面展示”。两个项目的耦合点之一就在这里。

一个真实的例子：hackernews 路由。它的 path 是 /:section?/:type?/:value?/:minComments?，所以 /hackernews、/hackernews/best、/hackernews/over/sources/100 都由它处理；radar 字段（L41）声明了“在 news.ycombinator.com/best 页面上，推荐订阅 /hackernews/best”。

抓取：列表页 + 详情页 + 缓存

几乎所有路由都遵循同一个套路，hackernews 的 handler 是典型：

// 简化自 lib/routes/hackernews/index.ts
async function handler(ctx) {
    const section = ctx.req.param('section') ?? 'index';
    const response = await got(currentUrl);          // 1. 抓列表页
    const $ = load(response.data);                     // 2. cheerio 解析 HTML
    const list = $('.athing').toArray().map((thing) => ({
        title: $(thing).find('.titleline').children('a').text(),
        link: `${rootUrl}/item?id=${$(thing).attr('id')}`,
        description: `<a href="...">Comments on Hacker News</a> | <a href="...">Source</a>`,
    })).slice(0, getRouteLimit(ctx, 30));             // 3. 尊重 ?limit=

    const items = await pMap(list, (item) =>           // 4. 详情页：并发抓取 + 缓存
        cache.tryGet(`hackernews:comments:${item.link}`, () => fetchDetail(item)));

    return { title: 'Hacker News', link: rootUrl, item: items };   // 5. 返回 Data
}

抓取工具都在 lib/utils/：

• HTTP：ofetch.ts（带重试，遇到 429/5xx 自动重试 REQUEST_RETRY 次）和兼容旧代码的 got.ts。它们统一注入 User-Agent、代理（PROXY_URI）、按主机限流（REQUEST_RATE_LIMITS）。
• HTML 解析：cheerio 的 load()。
• 浏览器：反爬严重、必须执行 JS 的网站用 playwright.ts（基于 patchright，可以连远程浏览器）。这类路由要在 features.requirePuppeteer 里声明，因为开浏览器很贵，部分部署形态（如 Workers）不支持。
• 日期：parseDate、parseDateInTimezone，因为各网站的时间格式五花八门。

缓存：两级缓存 + 防击穿

RSSHub 最重要的工程设计是缓存。阅读器会以分钟级频率反复请求同一个 feed，而目标网站经不起这样的压力（会封 IP），抓取本身也慢。RSSHub 用了两级缓存：

1. 路由级（整份 feed）：cache.ts 把“路径 + format + limit + sorted + 是否带过滤参数”哈希成 key。命中就直接把缓存的 Data 放进 ctx，跳过 handler；未命中则执行 handler，再把结果写回（L93，CACHE_EXPIRE 默认 5 分钟，见 config.ts）。
2. 防击穿（cache stampede）：同一个冷门 feed 被 100 个阅读器同时请求时，不能让 100 个请求都去打目标网站。L40 用一个 claim 原子锁，只让第一个请求去抓，其他请求每 6 秒检查一次，最多 10 次，超时就返回 “This path is currently fetching”。
3. 详情级（单篇文章）：列表页通常每次都变，但每篇文章的详情页基本不变。cache.tryGet(key, fn) 让路由作者把“抓详情页”的结果单独缓存（CACHE_CONTENT_EXPIRE 默认 1 小时）。列表刷新时，只有新出现的文章才真正发请求。这是给 RSSHub 写路由时 review 最常要求的一点。

缓存后端可选 memory（单进程 LRU）、redis、http、Cloudflare KV，见 lib/utils/cache/ 和 CACHE_TYPE。

Radar：从“我在看的网页”反推订阅地址

用户通常不知道某个网站对应哪条 RSSHub 路由。每条路由的 radar 字段声明了“哪些网页 URL 对应这条路由”，构建期汇总后通过 /api/radar/rules 对外提供。

• RSSHub Radar 浏览器扩展读取这些规则：你打开 news.ycombinator.com/best，它就提示可以订阅 /hackernews/best。
• Folo 的发现页也用同样的思路：在搜索框里粘贴一个网页 URL，Folo 会尝试匹配出对应的 rsshub:// 路由（见 UnifiedDiscoverForm.tsx、DiscoverFeedForm.tsx）。

部署形态与关键配置

同一份代码可以以多种形态运行，构建配置分别是仓库根目录的 tsdown*.config.ts 和 wrangler*.toml：

自建实例最常用的环境变量（全部在 lib/config.ts）：PORT、CACHE_TYPE / REDIS_URL、CACHE_EXPIRE、ACCESS_KEY（实例访问控制，见 access-control.ts）、PROXY_URI、REQUEST_RATE_LIMITS、各网站的 Cookie / Token（如 Twitter、Bilibili），以及 USER_ROUTES_PATH（挂载你自己的私有路由，见下一节）。

和 Folo 的专属接口

RSSHub 里有一个专门为 Folo 准备的接口：/api/follow/config（Folo 的前身叫 Follow）。它返回 ownerUserId、description、price、userLimit、cacheTime、gitHash。这是 Folo 的“RSSHub 实例市场”用的：任何人都可以把自己部署的 RSSHub 实例登记到 Folo，设置价格和用户上限，其他 Folo 用户可以选择通过这个实例抓取 rsshub:// 源。第 4 章会把这条链路完整画出来。

Folo：一个多端的 AI RSS 阅读器

Monorepo 地图

Folo 是一个 pnpm workspace + Turborepo 的 monorepo（见 AGENTS.md、pnpm-workspace.yaml）。最重要的设计决策是：业务逻辑放在 packages/internal，被桌面、Web、移动端共享；各个 app 只负责自己运行时特有的部分。

最关键的限制：后端不在仓库里

离线优先的数据层

Folo 的客户端不是“每次都去问服务器”，而是本地数据库 + 内存 store + 后台同步。打开 App 时先从本地 SQLite 把数据灌进内存，界面立刻可用，然后再和服务器对齐。

关键代码：

• 启动灌数据：initialize/index.ts 调用 hydrateDatabaseToStore，从 SQLite 读出所有表，写进各个 store。
• store 的形状：EntryState 除了 data（id → 条目），还维护了多组索引：entryIdByView、entryIdByFeed、entryIdByCategory、entryIdByInbox、entryIdByList。时间线切换视图、切换订阅源时直接查索引，不用遍历。
• 写入走事务：store 的每个 action 用 createTransaction() 同时更新内存和数据库，保证两边一致。

Sync Engine：模仿 Linear 的增量同步

多设备同步是 RSS 阅读器最难做好的部分：你在手机上读过的文章，电脑上要立即变成已读；离线时的操作，上线后要补发；本地的乐观更新不能被服务器的旧快照覆盖。

Folo 的方案写在 sync-engine.ts 的注释里，明确说是“modelled on Linear's sync engine”：

1. 客户端记住一个游标 lastSyncId：已经应用过的最大变更日志 id（class SyncEngine）。
2. 第一次（bootstrap）从服务器取当前 id 和完整快照；之后每次只拉取“游标之后的变更”（订阅变化、已读、收藏、新条目……），逐条应用到 store。
3. 本地还没被服务器确认的操作，放在 transaction queue 里，以 overlay 的形式叠加在服务器数据之上。这样即使拉到了较旧的快照，界面也不会“回退”你的操作。
4. 拉取在启动、网络恢复、窗口回到前台、定时器、服务器 ack 时触发（SyncPullReason）。

一条时间线是怎么显示出来的

以桌面端打开“文章”视图为例：

• 6 种视图是 Folo 和传统阅读器最大的区别：entry-column/Items/ 里 article-item、social-media-item、picture-item、video-item、audio-item、notification-item 各自一个组件。RSSHub 路由声明的 view 正是为这 6 种视图准备的元数据。
• 条目详情在 entry-content/，阅读模式（readability）会请求服务端抽取正文，再由 packages/readability 清洗。
• AI 排序只是 entries.list 的一个 aiSort: true 参数（L74、L534），排序在服务端完成，结果按顺序返回一页 100 条。

Electron：主进程、渲染进程与 IPC

• IPC 是类型安全的：主进程用 electron-ipc-decorator 定义 AppService、AuthService、ReaderService 等服务类，导出 IpcServices 类型；渲染进程 createIpcProxy<IpcServices>() 得到一个“像本地对象一样调用”的代理。加一个系统能力 = 在主进程加一个方法，渲染进程就有类型提示。
• 登录态在主进程：Electron 里的 API 请求经 api-client.ts 的 fetchWithElectronAuth 交给主进程带上 Cookie 发出。
• 深链协议：registerProtocols 注册 folo://（开发版是 folo-dev://，见 constants.ts）。浏览器里完成 OAuth 登录后，通过 folo://auth?token=... 回到 App。我们本地测试时遇到的“登录跳去了官方 App”，就是因为开发版只认 folo-dev://；登录页底部的“输入授权令牌”就是为这种情况准备的。

AI 功能是怎么接上的

其他端：移动端、CLI、分享页

• 移动端 apps/mobile：Expo，复用 packages/internal 的 store 和 database（expo-sqlite 驱动），UI 单独实现。
• CLI apps/cli：直接用 client-sdk 调 API，输出稳定的 JSON 信封 {ok, data, error}，skill.md 就是写给 AI agent 的使用说明，我们已经把它装成了 Claude Code skill。
• 分享页 apps/ssr：为分享出去的订阅源 / 列表生成带 OG 标签的页面。

端到端：一条 rsshub:// 订阅的旅程

把前面所有组件串起来。假设你在 Folo 里订阅了 rsshub://hackernews：

几个要点：

• rsshub:// 是一个“逻辑地址”：订阅里存的不是某台具体服务器的 URL，而是路由路径。具体由哪台 RSSHub 实例去抓，由后端决定：默认由 Folo 官方的实例处理，你也可以在设置里登记自己的实例（客户端在 modules/rsshub/，地址校验规则见 instance-url.ts）。这样同一个订阅可以在不同实例之间迁移，不需要改订阅本身。
• 实例的元信息来自 RSSHub 那边的 /api/follow/config：实例所有者、价格、用户上限、缓存时间、git 版本。
• 抓取频率受两层缓存叠加影响：RSSHub 的路由级缓存（默认 5 分钟）和 Folo 后端自己的刷新策略。所以“网站刚更新、Folo 里还没出现”是正常的。
• 视图：RSSHub 路由声明的 view（ViewType）和 Folo 的视图编号一一对应，用来提示这个源适合用哪种界面展示；订阅时你仍然可以自己选。

开源许可证：你能做什么、必须做什么

以下是对许可证文本的技术性解读，帮助你判断常见场景，不是法律意见。涉及商业发布时请咨询律师。

两个项目的许可证

AGPL-3.0 的核心规则

AGPL 是 GPL-3.0 加上一条“网络条款”：

1. 你可以：自由使用、学习、修改、再分发，包括商业用途。没有“非商用”限制。
2. 分发时（发布源码 fork、发安装包、发 Docker 镜像）：必须以同样的 AGPL 许可提供对应的完整源代码，保留版权和许可证声明，并标明你做了修改。
3. 网络条款（第 13 条）：如果你修改了程序，并让其他人通过网络与它交互（比如对外开放一个改过的 RSSHub 实例，或部署一个改过的 Folo Web 版），即使你没有“分发”任何文件，也必须向这些用户提供修改后的源代码。这是 AGPL 和 GPL 的关键区别。
4. 衍生作品整体适用：和 AGPL 代码组合成一个程序的部分（比如你加进 RSSHub 的新路由），整体要以 AGPL 发布。
5. 不授予商标权：许可证管代码，不管名字和 Logo。

常见场景对照

贡献与定制

给 RSSHub 贡献一条路由

git clone https://github.com/DIYgod/RSSHub.git && cd RSSHub
pnpm i
pnpm dev                      # http://localhost:1200
pnpm new:route --help         # 交互式脚手架：命名空间、文件名、维护者、模板（API / HTML / 浏览器）
# 浏览器打开 http://localhost:1200/<namespace>/<path> 检查输出

脚手架是 scripts/generate-route.mjs。提交前对照 AGENTS.md 里的 review 规则，最常被指出的问题：

• example 必须以 / 开头且能访问；categories 只写一个；radar.source 不带 https://；
• 抓详情页一定用 cache.tryGet()；不要对同一段 HTML 调用两次 load()；
• 只用 DataItem 里定义的字段；
• 只有真的用了浏览器才设置 requirePuppeteer: true；maintainers 写有效的 GitHub 用户名。

给 Folo 贡献

git clone https://github.com/RSSNext/Folo.git && cd Folo
corepack enable && corepack prepare
pnpm install
cd apps/desktop && pnpm run dev:web       # 浏览器开发，连接线上 API
# 或者：pnpm run dev:electron              # Electron 开发

• 提交前按 AGENTS.md 的顺序：pnpm run typecheck → pnpm run lint:fix → pnpm run test。
• 详细说明在 CONTRIBUTING.md，包括 Electron 登录问题的处理（复制 __Secure-better-auth.session_token）。
• 适合入手的方向：某一种视图的列表项 / 详情布局（Items/）、设置页、集成（integration.ts：发送到 Obsidian / Readwise…）、阅读模式清洗、CLI 命令、国际化文案（locales/）。
• 需要谨慎的方向：任何依赖服务端新接口的功能。你没法改后端，PR 只能用已有的 API。

打造“自己喜欢的阅读器”：三条路线

一个务实的组合是：先用 C 验证你想要的“排序 / 摘要”标准，再用 A 把它做进界面；如果某个网站没有 feed，就给 RSSHub 写一条路由（或私有路由），然后在 Folo 里订阅 rsshub://你的路由。

附录：源码索引

RSSHub

Folo