# ZReaderpy

**Repository Path**: lilhand/zreaderpy

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-28
- **Last Updated**: 2026-10-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ZReaderPy

基于 **PySide6 + QtWebEngine** 的知乎桌面阅读与收藏工具：内嵌浏览器正常浏览知乎，通过网页 JS 注入在每条内容旁添加「保存到 ZReader」按钮，一键把回答/文章结构化抓取到本地，支持离线阅读、全文检索与导出。

## 特性

- 内嵌 Chromium 内核浏览器，可正常浏览知乎（登录态持久化）
- 网页注入「保存到 ZReader」按钮，一键收藏回答/文章
- 正文 HTML 清洗 + 图片本地化（处理知乎 Referer 防盗链）
- SQLite 本地存储 + 全文检索
- 离线阅读（本地模板，无知乎脚本）
- 公式渲染：保存 LaTeX 源，离线用 KaTeX 渲染，区分行内公式与段间公式
- AI 摘要：支持 DeepSeek / OpenAI / 通义千问 / Kimi / 智谱 / 硅基流动 / Ollama 等（OpenAI 兼容），收藏时自动生成中文摘要，可一键补全历史收藏
- 自动分类：基于标签与摘要调用 DeepSeek 分类，侧栏可按分类筛选
- 自动打标签：AI 为每篇收藏提炼 3~6 个话题标签，收藏卡片以 `#标签` 展示，侧栏可按标签筛选
- 多维筛选：收藏栏支持按 **AI 分类、标签、作者、保存时间**（今天 / 最近 7 天 / 最近 30 天）组合筛选
- 评论收藏：在评论区逐条点「☆ 收藏」，自动归入所属文章（离线阅读可见）
- 侧栏可收起为**悬浮工具条**（圆角胶囊，浮在内容之上不占布局空间）：按住可拖到界面任意位置，松手自动吸边，贴近上 / 下边自动横排，位置与方向自动记忆，贴边后窗口缩放仍保持贴边
- 导出 Markdown / HTML / PDF；收藏栏支持 **Ctrl / Shift 多选 + Ctrl+A 全选批量导出**（Markdown / HTML），也可一键导出全部收藏

## 环境

- Python >= 3.12
- [uv](https://docs.astral.sh/uv/)

## 快速开始

### Windows 双击启动（推荐）

双击项目根目录下的 **`启动ZReader.vbs`** 即可启动：

- 首次运行会自动同步依赖（会显示窗口与安装进度，可能耗时几分钟）。
- 之后为静默启动，不再弹出命令行黑框。
- 启动失败会弹窗提示，详细日志见 `logs/launcher.log`。
- 若需查看实时输出（排障），可直接双击 `start.bat`。

前提：已安装 [uv](https://docs.astral.sh/uv/)；若未安装 `uv`，脚本会尝试回退使用系统 `python` / `py` 并给出提示。

### 命令行启动

```bash
uv sync          # 安装依赖
uv run zreaderpy # 运行
```

首次运行后，在浏览器中登录知乎一次即可（Cookie 会持久化）。

### 配置 AI 服务（可选，用于摘要 / 分类）

工具栏点击 **「设置」**（或悬浮工具条的「更多 → 设置」）。
支持所有 **OpenAI 兼容**接口，内置以下服务商预设，选中即自动填好接口地址与常用模型：

| 服务商 | 接口地址 | 备注 |
|---|---|---|
| **DeepSeek**（默认） | `https://api.deepseek.com` | |
| OpenAI | `https://api.openai.com/v1` | |
| 通义千问（阿里云） | `https://dashscope.aliyuncs.com/compatible-mode/v1` | |
| Kimi（月之暗面） | `https://api.moonshot.cn/v1` | |
| 智谱 GLM | `https://open.bigmodel.cn/api/paas/v4` | |
| 硅基流动 | `https://api.siliconflow.cn/v1` | |
| OpenRouter | `https://openrouter.ai/api/v1` | |
| 本地 Ollama | `http://localhost:11434/v1` | 无需 API Key |
| 自定义 | 手填 | 任何兼容 `/chat/completions` 的服务 |

要点：

- 接口地址与模型**都可手动修改**（适配私有部署或新模型）；
- **每个服务商各存一套配置**，切换服务商时自动带出，无需重填；
- 「生成参数」可调**温度 / 最大输出 / 请求超时**；
- 点「测试连接」会按当前填入值真实发一次请求。

**历史收藏补全**：先收藏、后配置 AI 时，点收藏栏右上角的 **「AI」** 按钮（或在收藏栏右键 /
悬浮工具条「更多」中选择 **「AI：补全全部收藏」**），即可为所有缺摘要、分类或标签的收藏批量补齐。
进度显示在状态栏，成功与失败细节写入 `logs/app.log`（可搜索「自动分类」核对）。

保存并勾选「启用 AI 功能」后，每次收藏会自动在后台生成摘要与分类；未配置时应用其它功能不受影响。

### 公式渲染说明

公式使用本地 KaTeX 渲染。首次使用会在后台自动下载 KaTeX 资源并缓存到用户数据目录
（`%APPDATA%/ZReaderPy/katex/`）；若下载失败（无网络），阅读页会降级为直接显示 LaTeX 源码。

### 启动排障

双击启动器后**不会出现命令行窗口**，行为如下：

- 依赖未就绪时，先弹提示框告知首次安装（约 230MB），确认后静默安装并在完成后自动打开应用；
- 安装/运行期间重复双击会被拦截，提示「正在启动或安装依赖中」；
- 启动失败会弹窗，内容包含退出码与日志末尾。

日志（每次启动都会重置）：

- `logs/launcher.log`：启动器步骤与 `uv sync` 输出，排障首选；
- `logs/app.log`：应用自身输出（QtWebEngine 日志很多，单独存放）。

常见退出码与处理：

- `-1073741510`（即 `0xC000013A`，STATUS_CONTROL_C_EXIT）：进程被强制中断，或控制台窗口被点击后关闭。
  新版启动器已全程隐藏，一般不会再出现。
- 其它非 0：查看弹窗中的日志末尾；也可删除 `logs/.deps-ready` 后重新双击，强制重新同步依赖。

需要看实时输出时，直接双击 `start.bat`（不加 `/silent`，输出到控制台）即可。

评论区没有出现「☆ 收藏」按钮时，可导出当前页与评论相关的 DOM 结构用于排查：
按 `Ctrl+B` 收起收藏栏 → 点悬浮工具条上的 **「⋯ 更多」→「导出页面结构（排障）」**，
结果写入 `%APPDATA%/ZReaderPy/dom-dump.txt`，据此适配评论选择器。

### 国内网络加速

`start.bat` 已内置以下镜像（仅当系统未设置同名环境变量时生效，便于国内下载依赖）：

| 变量 | 用途 | 默认值 |
|---|---|---|
| `UV_DEFAULT_INDEX` | 依赖下载（PyPI） | 清华镜像 `https://pypi.tuna.tsinghua.edu.cn/simple` |
| `PIP_INDEX_URL` | Python 回退路径的 pip | 同上 |

如需更换镜像，编辑 `start.bat` 顶部对应行，或提前设置系统环境变量（已设置的值不会被覆盖）。

> **注意**：请勿设置 `UV_PYTHON_INSTALL_MIRROR`（解释器下载镜像）。
> 新版 uv（0.12+）内置的 CPython 下载元数据 URL 已不再是 `github.com` 前缀，
> uv 在检测到该变量时会直接报错 `the URL does not match the expected format`
> 并以退出码 2 结束，导致 `uv sync` 失败、程序无法启动。
> 解释器下载由 uv 默认镜像负责，无需额外配置。

安装 uv 若官方脚本较慢，可用 pip 走镜像安装：

```bash
pip install -U uv -i https://pypi.tuna.tsinghua.edu.cn/simple
```

## 数据位置

- Windows：`%APPDATA%/ZReaderPy/`
  - `zreaderpy.db`：文章数据库
  - `assets/<item_id>/`：本地化图片
  - `webengine/`：浏览器缓存与 Cookie

## 开发

```bash
uv run pytest        # 测试
uv run ruff check .  # 静态检查
```

## 目录结构

```
src/zreaderpy/
  app.py                # 入口
  config.py             # 配置与路径
  main_window.py        # 主窗口
  bridge.py             # QWebChannel 桥
  browser/              # 会话与浏览器视图
  inject/               # 注入脚本与安装器
  extractor/            # 字段解析与正文清洗
  storage/              # SQLite 仓储
  media/                # 图片下载
  ui/                   # 侧栏 / 阅读器 / 导出
  resources/            # 阅读模板与样式
```

详细设计见 [`技术实现文档.md`](技术实现文档.md)。