# snail-browser

**Repository Path**: wn12cn/snail-browser

## Basic Information

- **Project Name**: snail-browser
- **Description**: 🐌 Windows 桌面聚合阅读器：输入网址自动发现全站与各板块订阅（RSS / WordPress 分类 / 无 RSS 网页抓取 / Discuz / Discourse 论坛），阅读模式正文 + 评论区一起看
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-26
- **Last Updated**: 2026-10-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🐌 Snail聚合浏览器（Poly Browser）

开源地址：<https://gitee.com/wn12cn/snail-browser> · 官网：<https://www.wn12.cn/> · 应用内置升级检测（基于 Gitee Releases，每天自动检查一次，也可在 帮助 → 检查更新 手动触发）

🐌 Snail聚合浏览器是一个「左侧列表 + 右侧内容」布局开发的个人聚合阅读桌面应用：

## 系统要求

| 项目 | 要求 |
| --- | --- |
| 操作系统 | Windows 10 及以上（64 位）；Windows 11 全系支持（含 ARM 版，通过 x64 模拟运行） |
| 内存 | 建议 4GB 及以上（应用常驻约 200–400MB） |
| 硬盘 | 约 300MB |
| 其他 | 无需安装 .NET 等额外运行库；不支持 Windows 7/8/8.1 与 32 位系统（Chromium 130 内核要求） |

安装包未做代码签名，首次安装 Windows SmartScreen 可能提示「未知发布者」，选择「仍要运行」即可。

## 移动版（Android / 鸿蒙）

v0.5.0 起提供安卓安装包（`mobile-release/Snail聚合浏览器-安卓版-x.x.x.apk`），**Android 6.0+ 与鸿蒙 HarmonyOS 2/3/4 直接安装**，功能与桌面端一致（站点级订阅发现、网页抓取、论坛正文+评论提取、未读快照、分组、全文搜索、备份、自动刷新）。手机端：科技感深色界面（玻璃拟态+渐变）、新文章系统通知、**应用内一键升级**（检测到新版直接下载安装）；布局为列表全屏 → 全屏阅读 → 抽屉导航，返回键逐级退出。HarmonyOS NEXT（纯血鸿蒙）暂不支持，路线图见 [docs/移动端.md](docs/移动端.md)。

- 添加你想关注的网站（自动发现 RSS；无 RSS 的网站自动探测常见 feed 路径，仍没有则启用「网页抓取模式」从首页识别文章列表）
- 订阅源**分组管理**：新建/重命名/删除分组，订阅可随时移动分组；侧栏按组折叠展示，点击组名聚合浏览组内全部文章，支持组内一键刷新
- 左侧文章列表一键刷新全部订阅，支持「全部标为已读」；未读视图点开的文章保留在列表直到手动刷新
- 点击左侧文章标题，右侧沉浸阅读：默认「阅读模式」（自动提取正文），可切换「网页模式」直接加载原网页
- 全部 / 未读 / 已读 / 星标视图 + 「今天 / 昨天 / 近7天 / 全部」时间范围选择（对所有视图生效），关键字全文搜索（标题 + 正文），浅色/深色主题，启动与每 30 分钟自动刷新
- 阅读模式支持字号调节、阅读进度记忆、图片灯箱、代码块一键复制、一键返回顶部；正文下方自动附带**评论区**（支持 WordPress 评论与论坛回帖，超过 15 条折叠展开）；「复制全文」分带链接 / 纯文本两种，另有复制原文链接
- 关键词过滤规则（命中标题的文章自动隐藏，星标豁免）；新文章桌面通知（应用不在前台时提醒）
- 点击窗口「×」默认**最小化到系统托盘**（驻留后台继续刷新订阅、桌面通知和未读角标）；可在侧栏「设置」改为直接退出。托盘图标单击恢复窗口，右键菜单可退出
- 已读文章 7 天自动清理；「存储清理」面板支持细分的手动清理（历史文章/已读/未读/全部/正文缓存/网页缓存），星标永久保留

## 技术栈

| 层 | 技术 | 说明 |
| --- | --- | --- |
| 桌面外壳 | Electron 33 | 主进程负责网络抓取（无跨域限制）、数据持久化 |
| 构建 | electron-vite + Vite 5 + TypeScript | main / preload / renderer 三端构建，热更新开发 |
| 前端 | React 18 + Zustand + Tailwind CSS 4 | 三栏布局，状态集中在 providers 层 |
| 订阅解析 | rss-parser | RSS 2.0 / Atom；首页 `<link rel="alternate">` 自动发现；`/feed` 等常见路径探测；无 RSS 站点的 HTML 列表抓取 |
| 正文提取 | @mozilla/readability + linkedom | Reader 模式正文抽取、净化、相对链接补全 |

## 目录结构

```
src/
├── shared/                  # models：主进程/渲染进程共享类型
│   └── models.ts
├── main/                    # 主进程
│   ├── index.ts             # 窗口、菜单、启动刷新
│   ├── ipc.ts               # IPC 通道（feeds/articles/app）
│   └── services/            # services：与 UI 无关的能力层
│       ├── httpFetch.ts     #   统一 HTTP 抓取（UA 伪装、超时）
│       ├── feedService.ts   #   RSS 发现 / 解析 / 规范化
│       ├── articleService.ts#   正文提取 + HTML 净化
│       ├── contentCache.ts  #   正文磁盘缓存（7 天）
│       └── storeService.ts  #   订阅与文章 JSON 存储
├── preload/
│   ├── index.ts             # contextBridge 安全桥
│   └── index.d.ts           # window.api 类型
└── renderer/
    └── src/
        ├── App.tsx          # 三栏布局入口 + j/k 快捷键
        ├── providers/       # providers：Zustand 全局状态
        │   └── appStore.ts
        ├── components/      # widgets：Sidebar / ArticleList / ArticleView / 对话框
        ├── utils/
        └── assets/main.css  # 阅读模式排版样式
```

## 使用

```bash
npm install        # 安装依赖（.npmrc 已配置 Electron 国内镜像）
npm run dev        # 开发模式（热更新）
npm run build      # 构建产物到 out/
npm run dist       # 打包 Windows 安装包到 release/（需配 ELECTRON_BUILDER_BINARIES_MIRROR 镜像）
npm run typecheck  # 类型检查
npm run smoke      # 冒烟测试：真实抓取 RSS + 正文提取 + 无 RSS 站点兼容性
npm run seed       # 预置订阅（见 scripts/seed.ts 的 SITES 列表，可直接改）
npm run mobile:sync      # 构建移动端 Web 包并同步进安卓工程
npm run mobile:apk       # 构建签名 release APK（需本机 Android SDK，见 docs/移动端.md）
npm run mobile:e2e       # 移动端核心链路 E2E（真实网络）
npm run mobile:ui-e2e    # 移动端真实 UI E2E（本地 fixtures + 测试 Chrome）
```

### 快捷键

- `J` / `→`：下一篇文章；`K` / `←`：上一篇
- `O`：系统浏览器打开原文；`S`：星标当前文；`M`：标为已读/未读；`R`：刷新全部
- `Ctrl+N`：添加订阅；`Ctrl+R`：刷新全部

### 数据安全

- 数据备份为**手动功能**：侧栏「数据备份」随时创建/恢复/删除备份（存于数据目录 `backups/` 文件夹），应用不会自动备份；`store.json` 意外损坏时，启动仍会自动尝试用最近一份备份恢复
- 订阅支持 **OPML 导入/导出**（菜单 文件 → 导入/导出 OPML），可与其他阅读器互迁
- 新文章桌面通知可在 视图 菜单开关（应用不在前台时提醒）；托盘图标实时显示未读状态

1. 点左上角「添加订阅」（或菜单 文件 → 添加订阅，`Ctrl+N`）
2. 填网站首页地址（如 `wn12.cn` 或 `https://www.wn12.cn/`），自动做**站点级分析**：
   - **全站订阅**：页面声明的 RSS/Atom 链接 → 常见 feed 路径（`/feed`、`/rss.xml` 等）→ 首页文章列表「网页抓取」
   - **板块订阅**：自动识别导航里的各板块（含 Discuz/phpBB 论坛板块），逐一探测其 RSS（含 WordPress 分类 feed、Discuz 板块 feed）或文章列表结构，按 `板块名 · 站点名` 列出
   - **Discourse 论坛**自动识别：全站最新/热门 RSS + 各分类 RSS；帖子阅读走服务端渲染的 print 视图，回帖以评论形式显示
   - 也可以直接输入 RSS/Atom 链接
3. 发现结果按「全站 / 板块」分组展示，RSS（蓝色）与网页抓取（琥珀色）标注，**可勾选多个一次添加**，支持全选板块、自定义名称与分组

### 人机验证（Cloudflare 等）站点怎么办

抓取与「网页模式」共享同一份 Cookie：遇到人机验证时，先在「网页模式」打开该网站完成一次验证（阅读模式正文提取失败时的提示也会引导你切换），之后刷新和阅读模式都会带着验证 Cookie 通过，不再反复弹验证。

### 网页模式说明

适用于屏蔽了 RSS 的站点。订阅时会列出页面上识别出的候选文章区域（含文章数和样例标题），由你选择要订阅的区域；之后重新添加同一网址可切换抓取区域。识别规则：优先标题结构（H1-H5 / `<article>` 内的链接），排除导航栏、菜单、页脚、侧边栏中的链接；文章发布时间取自链接中的日期或页面 `time` 标签，取不到时用抓取时间。

### 快捷键

- `J` / `K`：下一篇 / 上一篇
- `Ctrl+N`：添加订阅
- `Ctrl+R`：刷新全部订阅

## 数据存放

- `%APPDATA%\Snail聚合浏览器\store.json`：订阅源与文章列表（目录名来自 productName）
  - 每个订阅源最多保留最近 100 篇（星标不清理）
  - 已读文章保留 7 天后自动清理（在每次刷新时执行；星标永久保留）
- `%APPDATA%\Snail聚合浏览器\cache\contents\`：正文缓存，7 天自动清理
- 从旧版「聚合浏览器」升级时，首次启动会自动把旧目录的数据（订阅 / 分组 / 文章 / 正文缓存）迁移到新目录

## 打包发布

**开发期间 `npm run dist` 被项目门禁拦截**（见 AGENTS.md），仅在需要发布安装包时放行：

```bash
ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ \
ELECTRON_BUILDER_BINARIES_MIRROR=https://npmmirror.com/mirrors/electron-builder-binaries/ \
SNAIL_DIST_CONFIRM=1 npm run dist
```

产物为 Windows NSIS 安装包（`release/Snail聚合浏览器 Setup x.x.x.exe`，应用图标 🐌）。

安装包未做代码签名，Windows SmartScreen 可能提示「未知发布者」，选择「仍要运行」即可。

## 版权

开发者：[Snail（蜗牛）](https://www.wn12.cn/) · 官网：<https://www.wn12.cn/>

Copyright © 2026 Snail（蜗牛）