# zreaderpy

**Repository Path**: huguoling/zreaderpy

## Basic Information

- **Project Name**: zreaderpy
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 4
- **Created**: 2026-09-30
- **Last Updated**: 2026-10-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ZReader —— 知乎阅读器 / 内容收藏工具

基于 **Python + PySide6(Qt) + QtWebEngine** 的桌面知乎客户端：内置浏览器内核浏览并搜索
知乎（持久化登录，下次打开无需重新登录），**自动向页面注入「收藏」按钮**：
一键把回答 / 文章 / 想法保存到本地收藏库，并同时导出成可离线阅读的 Markdown / HTML 文件。

## 功能

- **内嵌浏览器**：基于 `QWebEngineView`，独立的持久化 Profile，登录状态、Cookie、
  缓存都会被保存，下次打开无需重新登录。
- **SPA 友好的前进/后退**：知乎站内跳转几乎全是 `history.pushState`（不刷新页面），
  Qt 自带的 `back()/forward()` 对这类同文档历史条目不可靠。程序改为优先调用页面自身的
  `history.back()/forward()`（与真实浏览器一致，SPA 路由能正确响应 `popstate`），
  仅在 URL 确实未变化时才退回 Qt 的会话历史。
- **自动注入收藏按钮**：页面加载后自动识别所有内容卡片
  （`.ContentItem.AnswerItem` / `.ArticleItem` / `.PinItem` / `.List-item[data-zop]`，
  以及评论区 `.CommentItemV2` / `.CommentItem`），
  在卡片操作栏插入「收藏」按钮；已收藏的内容显示为「已收藏」，再次点击可取消。
  - **收藏即下载**：点击「收藏」除了写进收藏库，还会在后台把**原文的
    文字 + 图片 + 评论**落地成 Markdown / HTML 文件（默认开启，可在
    「设置 → 收藏时同时下载内容到本地」关闭）；
  - 使用 `MutationObserver` + 定时兜底扫描，兼容知乎的无限滚动、虚拟列表与前端路由；
  - **评论不自动翻，手动展开**：默认**不会**自动去点「查看全部 3 条回复」
    「查看更多评论」「加载更多」这类按钮，想看更多自己在页面里点。需要一次看全时，
    点工具栏「展开全部评论」——它只跑这一轮（最多 20 轮，连续 3 轮没有新内容就停），
    跑完就停，**不会变成自动翻页**；想要长期自动展开，再勾选
    「设置 → 自动展开文章评论（含全部回复）」（默认关闭）。
  - **评论也可收藏**：评论区里**每一条评论**（含楼中楼）下面都会出现
    「收藏评论」按钮，点一下就把**这条评论**（作者 / 正文 / 时间 /
    点赞 / 图片）写进收藏库并保存到本地，不会把父文章的正文或整页评论混进来。
    - 按钮位置：**始终追加在评论正文下方**，不插进知乎那条「悬停才显示」的
      操作按钮行，所以默认就看得见；
    - 每条评论都有自己的按钮：脚本定期巡检（以及每次扫描 / 手动展开后）会给
      漏掉的评论补按钮，已收藏状态刷新页面后依然正确；
    - 评论按钮的定位不依赖知乎的 `CommentItemV2` / `CommentItem` 类名：脚本用
      「评论正文」(`.CommentContent`) 反推评论根节点；连正文类名都变了，
      还能靠每条评论都有的「回复」按钮兜底识别；
    - 工具栏「诊断」里会显示「识别到的评论 / 已注入收藏评论按钮」数量，以及
      页面上所有含 Comment 的类名，便于排查；
    - 评论没有全局 ID，程序用「作者 + 正文」生成稳定指纹作为编号，刷新页面后
      「已收藏评论」状态依然正确；
    - 本地目录按「<作者>的评论 <指纹>：<评论摘录>」命名，同一位作者在同一篇
      文章下的多条评论各占一个文件夹，不会互相覆盖；
  - 只在 `*.zhihu.com` 生效，不会污染其它网站。
- **收藏内容自动落地到本地**：点「收藏」即把该条内容的完整正文与图片写成文件：

  ```
  内容保存目录/<标题>/
  ├── <标题>.md        # Markdown（含元信息、图片相对路径）
  ├── <标题>.html      # 可直接用浏览器打开的完整页面
  └── images/          # 正文图片（已本地化）
  ```

  默认内容保存目录就是下载目录（`<数据目录>/downloads`，Windows 上即
  `%APPDATA%\ZReader\downloads`），与「下载」标签页的保存位置完全一致；
  可在「设置 → 内容保存目录…」改成任意路径。

  图片抓取与写盘在工作线程中完成，不阻塞页面；完成后会提示保存位置，
  可一键打开所在文件夹。
- **收藏时抓取完整正文（避免「断章」/「只有一半」）**：
  「设置 → 收藏时抓取完整正文」开启后（默认开启），在首页 / 话题页等**列表页**
  收藏时，程序会在后台用一个独立页面打开这条内容的**固定链接**，把正文完整取回
  写库并重写本地文件。为了不出现「只有一半」的内容：

  1. **不展开文章也能取到全文**：优先读服务端下发的数据
     （页面里的 `<script id="js-initialData">`：`initialState.entities.
     answers|articles[id].content`）——这就是**整篇正文**，跟页面有没有点
     「阅读全文」、有没有懒加载完全无关，从源头拿全文；读到足够长的正文就直接用它；
  2. **打开内容自己的页面**：收藏时拿到的链接可能是问题页 / 首页甚至搜索页，
     加载它只能看到被折叠的列表片段；程序会按类型拼出回答页
     (`/question/<qid>/answer/<aid>`) / 文章页 (`zhuanlan.zhihu.com/p/<id>`) /
     想法页 (`/pin/<id>`) 的固定链接；
  3. **服务端数据没有时退回页面**：多轮「点掉阅读全文 → 去掉折叠样式 → 滚动触发
     懒加载 → 收集」，连续两轮正文不再变长才结束，只留最长的一份；并按包含关系
     优先选 `.Post-RichText` / `.RichContent-inner` 这类**整篇**容器
     （正文常被拆成多个 `.RichText.ztext` 块，只取最长的一块就会丢一半）；
  4. **不会把内容写短**：抓到的比已有的更短时判定为不完整，**不覆盖**已有全文；
     抓取算法升级后（`full_html_ver`），用旧版本抓过的收藏会自动重抓一次。

  在原文详情页上收藏时直接复用页面上的完整正文，不会重复抓取。
  判断「是不是已在原文页」一律用**内容自己的固定链接**（不是当前浏览的页面）：
  列表页 / 问题页上卡片链接常常退化成当前页面地址，过去会被误判成「已在原文页」，
  把折叠的片段当成全文存下来（v4 已修正，旧记录会自动重抓一次）。
  另外，页面上的内容只要带折叠标记（`--collapsed` /「阅读全文」等），
  即便正文看着够长也一定去取全文——**不展开文章也能存到完整版**。
  单项失败只影响对应部分，收藏与本地文件不受影响。
- **本地收藏库（SQLite）**：保存标题、问题、作者、作者简介、头像、原文链接、
  正文 HTML/纯文本、赞同数、评论数、发布时间、收藏时间、收藏夹、备注等字段。
- **图片本地化**：收藏时后台线程下载正文图片到本地，断网也能看图（可关闭）。
- **整页快照**（可选）：额外保存收藏时的整页 HTML。
- **收藏库面板**：关键词搜索、按收藏夹 / 类型筛选、查看详情、移动收藏夹、
  删除、复制链接、在内置浏览器打开原文；支持「管理收藏夹」对话框（新建 /
  重命名 / 删除空收藏夹）。
  - **双击即在本地打开完整版**：双击任意一条收藏，会先按「完整正文 → 评论」
    补齐缺的部分，再用**完整内容**重新生成本地文件并打开，包含：
    1. **正文**：优先用后台抓回的完整原文（`full_html`），其次是页面抓到的正文；
       被折叠的片段不会再写进主文件；
    2. **图片**：正文与评论里的图片都会下载到 `<标题>/images/`，
       文件中的路径改成相对路径，离线可读；
    3. **评论**：收藏时后台抓取（见下条），以「## 评论」章节附在正文之后；
    4. **元信息**：作者、类型、问题、原文链接、赞同 / 评论数、发布时间、收藏时间等。
    每次双击都重新生成（已下载的图片直接复用），总是打开最新完整版；
    右键菜单另有「显示本地文件所在目录」与「重新抓取完整正文」。
- **评论抓取**：「设置 → 收藏时抓取评论」开启后，收藏时会在后台用一个**独立页面**
  加载原文（共享登录态，不影响你正在浏览的页面），点开「N 条评论」、反复展开
  「查看全部回复 / 加载更多」并多次滚动触发懒加载，
  把评论（作者 / 正文 / 时间 / 点赞，含图片）整理成 Markdown 存进收藏库
  （`comments_md` 字段，旧库自动迁移补列），并自动重写本地文件。
  一次抓取到的评论比已有的更少时不会覆盖，避免把存好的评论弄丢。
  详情对话框里也有「抓取评论 / 重新抓取评论」按钮；抓取失败只影响评论部分。
- **AI 摘取全文（收藏内容用 AI 摘取模式摘取完整）**：在「设置 → AI 设置」里勾选
  「收藏时用 AI 摘取完整正文」后，收藏时会在后台把**整篇正文交给模型整理成完整的
  Markdown 全文**（不是摘要）：

  - **长文不截断**：先按段落切成多段分别请求（每段约 4000 字，最多 12 段），
    再按原文顺序拼成完整一篇，因此不受单次上下文长度限制；
  - 结果存进收藏库（`extract_md` 字段，旧库自动迁移补列），并**另存到本地文件**：
    `<内容保存目录>/<标题>/<标题>.AI整理.md`（**主文件 `<标题>.md` / `.html` 始终是
    抓到的完整原文，不会被 AI 版本覆盖**）；
  - 详情对话框默认展示摘取的全文，可一键切回页面原文；也可随时点「AI 摘取全文」
    手动重新摘取（按钮显示「正在摘取全文…」）；
  - 导出 Markdown / HTML 时自动使用摘取的完整正文（元信息标注「正文：AI 摘取的完整全文」）。
- **AI 摘要（DeepSeek / 豆包）**：在「设置 → AI 设置」中选择服务商并配置
  后，收藏文章 / 回答 / 想法 / 评论时会在后台自动生成 **150 字以内的中文摘要**，
  保存进收藏库（`summary` 字段，旧库自动迁移补列）：
  - 摘要生成在 `QThreadPool` 后台线程执行，不阻塞界面；失败会在状态栏提示；
  - 详情对话框顶部展示摘要，并提供「生成 / 重新生成 AI 摘要」按钮（未开启
    自动摘要也能手动触发）；
  - 收藏库关键词搜索覆盖摘要；导出 Markdown / HTML 时摘要写入元信息；
  - 服务商预设（均为 OpenAI 兼容接口，切换后自动带出地址与模型）：

    | 服务商 | API 地址 | 模型 | Key |
    | --- | --- | --- | --- |
    | DeepSeek | `https://api.deepseek.com` | `deepseek-chat` / `deepseek-reasoner` | `sk-…` |
    | 豆包（本地服务） | `http://127.0.0.1:9090/v1` | `doubao` / `doubao-think` / `doubao-expert` | 任意非空（预设 `sk-doubao`） |
    | 自定义 | 任意 OpenAI 兼容地址 | 任意 | 任意 |

  - 「设置 → AI 设置」内置**测试连接**；API 地址 / 模型留空时按
    「设置 → 服务商预设 → 内置默认」逐级回退。
- **导出**：所选（或全部筛选结果）导出为 Markdown / HTML，单条一个文件或合并成合集，
  已本地化的图片会一起复制到导出目录。
- **下载保存**：内置下载队列（进度 / 大小 / 取消 / 清除已完成），保存位置可固定为
  下载目录或每次询问；右键菜单提供「图片另存为…」「链接另存为…」「复制图片/链接地址」
  「用系统浏览器打开链接」「保存本页为 HTML…」。

## 环境要求

- Python 3.9+（推荐 3.10+）
- [uv](https://docs.astral.sh/uv/)（用于管理虚拟环境与依赖）
- Windows / macOS / Linux 桌面环境

安装 uv（任选其一）：

```bash
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"   # Windows
curl -LsSf https://astral.sh/uv/install.sh | sh              # macOS / Linux
```

## 安装与运行（uv）

```bash
uv sync          # 创建 .venv 并按 uv.lock 精确安装依赖（含 dev 分组）
uv run zreader   # 启动程序
```

### Windows 一键启动

双击项目根目录的 **`run.bat`** 即可（也可在命令行调用，参数会原样传给程序）：

| 场景 | 命令 |
| --- | --- |
| 启动 | `run.bat` |
| 阅读器模式（隐藏侧栏） | `run.bat --reader` |
| 白屏 / 无 GPU | `run.bat --software-render` |
| 自定义数据目录 | `run.bat --data-dir D:\Data` |
| 查看全部参数 | `run.bat --help` |
| 环境变量开启软件渲染 | `set ZREADER_SOFTWARE_RENDER=1` 后执行 `run.bat` |

脚本行为：自动切换到自身所在目录 → 检测 `uv`（首次运行自动执行 `uv sync`
安装依赖）→ 启动程序；若机器上没有 uv，会依次尝试 `.venv` 中的 Python、
系统 Python 运行；启动失败时保留窗口并给出提示。

等价的其它启动方式：

```bash
uv run python -m zreader    # 以模块方式启动
uv run main.py              # 运行源码入口
```

无 GPU 的虚拟机 / 远程桌面环境下若出现白屏，使用软件渲染启动：

```bash
uv run zreader --software-render
```

其它参数：

```bash
uv run zreader --reader                    # 阅读器模式：隐藏收藏库 / 下载侧栏，专注阅读
uv run zreader --data-dir D:\ZReaderData   # 自定义数据目录
uv run zreader --url https://www.zhihu.com/question/621836265
uv run zreader --force-gpu                 # 虚拟机/黑名单显卡：强制硬件加速，改善滑动流畅度
# Windows PowerShell 设置环境变量后打开开发者工具窗口
$env:ZREADER_DEBUG_TOOLS=1; uv run zreader
```

## 开发环境（uv）

| 场景 | 命令 |
| --- | --- |
| 同步/更新环境 | `uv sync` |
| 添加运行时依赖 | `uv add httpx` |
| 添加开发依赖 | `uv add --dev pytest` |
| 升级锁定版本 | `uv lock --upgrade` |
| 执行任意命令 | `uv run python -c "import zreader"` |
| 代码检查 | `uv run ruff check .` |
| 代码格式化 | `uv run ruff format .` |
| 运行单元测试 | `uv run pytest` 或 `uv run python -m unittest discover -s tests` |
| 导出传统 requirements.txt | `uv export --no-dev -o requirements.txt` |
| 构建发行包 | `uv build` |

依赖声明集中在 `pyproject.toml`，锁定结果在 `uv.lock`（应提交到版本库）；
虚拟环境位于 `.venv/`（已加入 `.gitignore`）。

> 依赖源：`pyproject.toml` 中的 `[[tool.uv.index]]` 默认指向清华 PyPI 镜像，
> 网络可直连 PyPI 时删除该段即可。

## 使用说明

1. 启动后在地址栏打开知乎（首次建议点「首页」后登录一次，登录状态会持久保存）；
   地址栏输入关键词回车即可站内搜索。
2. 打开问题页 / 专栏页，等待页面渲染完成，每条回答 / 文章的操作栏会出现「收藏」按钮。
   自己点「N 条评论」打开评论区后，每条评论（含楼中楼回复）下面都会出现
   「收藏评论」按钮；想一次看全部评论，点工具栏「展开全部评论」（手动，只展开这一次）。
3. **收藏**：点击保存进本地收藏库，同时把内容（Markdown + HTML + 图片）下载到
   `<下载目录>/<标题>/`（默认 `%APPDATA%\ZReader\downloads/<标题>/`）；按钮显示「已收藏」后，
   再点一次可取消收藏。只想入库、不想生成文件时，取消勾选
   「设置 → 收藏时同时下载内容到本地」。
4. 想取回某条内容：在收藏库里**双击**该条，会用完整内容（正文 + 图片 + 评论）
   重新生成本地文件并用系统默认程序打开；右键「显示本地文件所在目录」可定位文件夹。
   评论默认在收藏时后台抓取（可在「设置 → 收藏时抓取评论」关闭）。
5. 右侧「收藏库」面板可以搜索、查看详情、导出、删除；**双击某条收藏**会用系统
   默认程序打开它保存在本地的文件（HTML / Markdown），右键「显示本地文件所在目录」
   可定位文件夹；「下载」标签页查看附件下载队列。
6. **AI 摘要 / 摘取全文**：菜单「设置 → AI 设置」填写 API Key 后：
   - 勾选「收藏时自动生成 AI 摘要」→ 每次收藏自动生成 150 字摘要；
   - 勾选「收藏时用 AI 摘取完整正文」→ 每次收藏自动把整篇正文整理成完整 Markdown
     全文并写入本地文件；
   - 详情对话框里也可以随时手动「生成 / 重新生成摘要」或「AI 摘取全文」。
7. 想更专注地阅读，可用 `--reader` 启动（隐藏侧栏），或点工具栏「侧栏」按钮随时收起。

### 下载与保存

| 场景 | 操作 |
| --- | --- |
| 单条回答 / 文章完整内容 | 卡片操作栏 → **收藏**（自动保存 Markdown + HTML + 图片） |
| 页面里的附件 / 文件链接 | 直接点击，自动保存到下载目录（或弹出保存对话框） |
| 图片 / 视频 | 右键 → **图片另存为…** / 复制图片地址 |
| 任意链接 | 右键 → **链接另存为…** / 复制链接地址 / 用系统浏览器打开链接 |
| 当前页面 | 右键 → **保存本页为 HTML…** |
| 查看进度 | 右侧「下载」标签页（有新任务时会自动切过去） |
| 改下载位置 | 「下载」标签页 → 下载目录；或勾选「设置 → 下载时询问保存位置」 |
| 打开内容目录 | 菜单 **文件 → 打开内容下载目录** |

- 下载目录默认 `<数据目录>/downloads`，可在设置里改到任意路径。
- 同名文件不会覆盖，会自动加序号（`data.bin` → `data (1).bin`）。
- 下载走浏览器自身的下载通道（同一个持久化 Profile），因此需要登录才能访问的文件也能正常下载。

### 滑动流畅度

注入脚本对滚动做了专门优化，**滑动期间完全不做 DOM 查询与插入**：

1. 滚动中（`scroll` / `wheel` / `touchmove`）只把新增节点入队，等停止滑动后再处理；
2. 不再每次都对整页 `querySelectorAll`，只处理 MutationObserver 给出的新增子树；
3. 队列按 **≤6ms 的时间片**分批执行，避免长任务掉帧；
4. 已注入判断改为「按钮是否仍在文档中」，兼容知乎虚拟列表的节点复用。

实测（72k 节点 / 540 张卡片的合成页面，滚动中持续追加卡片）：DOM 变化 1638 批次，
脚本实际只处理 9 批，单次任务最大占用 **6.9ms**（一帧预算 16.7ms），滚动期间注入开销
≈ 6.7ms。

若在虚拟机 / 被 Chromium 列入 GPU 黑名单的机器上仍感觉卡顿，可尝试
`uv run zreader --force-gpu`（忽略 GPU 黑名单，强制硬件加速）。

### 登录与第三方授权窗口

知乎的 QQ / 微信 / 微博 登录走的是 `window.open` 弹窗，程序对此做了区分处理：

| 请求来源 | 处理方式 |
| --- | --- |
| 站内链接（`*.zhihu.com`，含 `target="_blank"`） | 在当前视图打开，历史记录完整，后退/前进可用 |
| 站外链接（`open.weixin.qq.com`、`graph.qq.com` 等） | 打开独立弹窗窗口，与主视图共用同一 Profile（登录态共享） |

弹窗窗口自带 **前进 / 后退 / 刷新 / 关闭** 按钮，并且支持第三方登录页自身的
`window.close()` 与「返回」操作；授权成功回跳到知乎域名时，弹窗会自动把地址交还
主视图并关闭自己。

## 数据目录

| 平台 | 默认路径 |
| --- | --- |
| Windows | `%APPDATA%\ZReader` |
| macOS | `~/Library/Application Support/ZReader` |
| Linux | `~/.local/share/ZReader` |

目录结构：

```
ZReader/
├── library.db          # SQLite 收藏库
├── settings.json       # 用户设置
├── profile/ cache/     # QtWebEngine 持久化 Profile 与缓存（含登录态）
├── assets/images/      # 收藏内容的离线图片
├── assets/snapshots/   # 整页快照
├── downloads/          # 下载的文件（附件 / 图片 / 保存的页面）
│                       # ★收藏保存的单条内容也在这里（Markdown + HTML + images/）
└── export/             # 默认导出目录
```

## 项目结构

```
pyproject.toml                项目元数据 / 依赖 / ruff 配置（uv）
uv.lock                       依赖锁定文件
main.py                       便捷入口（等价于 python -m zreader）
zreader/
├── __main__.py               启动入口（`uv run zreader` / `python -m zreader`）
├── config.py                 路径 / 设置
├── db.py                     SQLite 存储层
├── utils.py                  HTML 清洗、HTML→Markdown、文件名处理
├── bridge.py                 QWebChannel 桥接对象（JS ↔ Python）
├── inject.py                 把注入脚本注册到 QWebEnginePage
├── browser.py                QtWebEngine 浏览器视图
├── images.py                 图片本地化（线程池下载）
├── exporter.py               导出 Markdown / HTML
├── downloads.py              下载管理（保存位置策略 + 进度跟踪）
├── download_panel.py         下载面板（队列 / 进度 / 操作）
├── local_saver.py            收藏时把单条内容落地为 Markdown/HTML + 图片
├── library_panel.py          收藏库面板
├── folder_dialog.py          收藏夹管理对话框（新建 / 重命名 / 删除空收藏夹）
├── detail_dialog.py          详情对话框
├── comments.py               评论抓取（后台页面展开评论区 → Markdown）
├── ai.py                     AI 客户端 + 后台摘要生成 / 摘取全文（长文分段）
├── ai_dialog.py              AI 设置对话框（Key / 地址 / 模型 / 测试连接 / 开关）
├── main_window.py            主窗口
└── web/assets/
    ├── inject.js             ★ 页面注入脚本（收藏按钮 + 内容提取）
    └── inject.css            注入按钮样式
tests/                       单元测试（utils / db / downloads / exporter / local_saver）
```

## 注入实现要点

`inject.js` 通过 `QWebEngineScript`（`DocumentCreation` 注入点、主世界）在页面脚本之前执行：

1. 加载 Qt 的 `qwebchannel.js`，用 `qt.webChannelTransport` 连接桌面端对象 `zreader`；
2. 扫描内容卡片，向 `.ContentItem-actions` 插入「收藏」按钮；评论卡片则挂到评论
   自带的操作按钮行（`.CommentItemV2-footerBtns` 等），找不到时落到卡片底部；
   - **按钮自动复活**：文章 / 回答「展开、收起」时知乎（React）会复用卡片节点、
     只重渲染内部子树，注入的按钮组会随之被移除。脚本会通过「新增节点沿祖先链
     找回所属卡片」+「监听按钮被移除」两条路径自动重新注入，按钮不会丢失；
3. 点击时从 `data-zop` / `data-za-extra-module` / `meta[itemprop]` / `.RichText.ztext`
   中提取结构化内容（评论走 `extractComment()`：正文取 `.CommentContent`，
   作者兜底 `/people/` 链接，所属回答 / 文章标题与链接取自最近的父卡片），
   `JSON.stringify` 后经 `bridge.save_item()` 发送；
4. 通过 `bridge.saved_keys()` 同步本地已收藏列表，渲染「已收藏」状态；
5. 保存 / 删除结果通过回调返回，并用页面内 Toast 提示。

> 说明：知乎前端类名会不定期调整，若某类卡片识别不到，只需在
> `zreader/web/assets/inject.js` 的 `CARD_SELECTOR` 中补充选择器即可。

## 已知限制

- 只对桌面版知乎页面有效；需要在页面渲染完成后注入（脚本会自动重试）。
- 图片下载依赖网络，失败时保留原始远程地址，不影响正文保存。
- 整页快照为静态 HTML，外部资源仍需联网查看。