# 星火阅读

**Repository Path**: deepin20/sparkread

## Basic Information

- **Project Name**: 星火阅读
- **Description**: 星火阅读是一款功能完备的桌面端本地阅读器，专为阅读红色经典、马列主义、文学名著等纯文本书籍设计。它集成了书架管理、阅读器增强、全文搜索、网盘搜书、微信读书同步等实用功能，拥有高对比度的红黄米白配色界面，操作直观，响应迅速。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-27
- **Last Updated**: 2026-08-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🔥 星火阅读 (SparkRead)

**星火阅读** 是一款功能完备的桌面端本地阅读器，专为阅读红色经典、马列主义、文学名著等纯文本书籍设计。它集成了书架管理、阅读器增强、全文搜索、网盘搜书、微信读书同步等实用功能，拥有高对比度的红黄米白配色界面，操作直观，响应迅速。

---

## ✨ 功能特性

### 📚 核心阅读
- **书架管理**：网格卡片视图，自适应列数；卡片显示封面、书名、作者、阅读进度；支持悬停高亮，一键阅读/详情。
- **智能阅读器**：支持 `.txt`、`.md` 格式，自动检测文件编码（UTF-8/GBK/GB18030/Big5）；字体/字号/主题可调，偏好自动保存。
- **交互增强**：自动滚动阅读（速度可调）、目录树（解析 Markdown 标题和中文章节）、书签/批注管理、导出笔记（JSON/TXT）、外部程序打开。
- **进度追踪**：自动保存阅读位置（精确到行/列）和累计阅读时长，支持防抖写入。

### 📥 书籍管理
- **添加书籍**：GUI 对话框填写元数据，支持 `.txt`、`.md`、`.pdf`、`.docx`，自动提取 PDF/DOCX 文本生成 `.txt` 入库。
- **扫描导入**：批量扫描 `data/books/` 目录，自动识别分类/书籍子目录，提取内容文件和封面图片；支持 PDF/DOCX 自动转换；多线程并发（默认4线程），增量更新。
- **分类管理**：动态分类列表，支持重命名和删除（书籍迁移至“未分类”），分类面板可折叠。
- **封面管理**：扫描时自动复制封面到 `assets/covers/` 并关联数据库；支持在书籍详情中手动更换封面。

### 🔍 搜索与发现
- **全文搜索**：在 `data/books/` 下所有 `.md`/`.txt` 文件中搜索关键词（不区分大小写），结果列表显示书名、匹配行内容和行号，点击跳转阅读。
- **鹿鸣川搜书**：调用官方 API 搜索书籍元数据（书名、作者、ISBN、简介、评分），显示封面缩略图，提供百度/夸克/迅雷网盘下载链接，提取码自动复制。
- **微信读书集成**：支持设置个人 API Key（从微信读书官方页面获取），搜索微信读书书城、同步书架、查看笔记和划线，点击“阅读”通过浏览器打开微信读书网页版阅读器。

### 🎨 界面与主题
- 左侧深红色面板 + 明黄按钮 + 右侧米白内容区，高对比度红黄撞色设计，视觉醒目。
- 支持全局主题切换（仅右侧背景色微调），阅读器独立提供 5 种主题（浅色/深色/护眼绿/羊皮纸/淡蓝）。

### 🗄️ 数据持久化
- **SQLite 数据库**（`data/sparkread.db`）：书籍、阅读进度、书签、批注、用户（微信读书 API Key）等表。
- **设置保存**（`data/settings.json`）：字体、字号、阅读主题、自动滚动间隔、窗口尺寸等。

---

## 🚀 快速开始

### 环境要求
- Python 3.8 或更高版本
- pip（Python 包管理器）

### 安装与运行

**方式一：一键启动（推荐）**

1. 克隆或下载本项目源码到本地。
2. 在终端进入项目根目录，执行：
   ```bash
   chmod +x start.sh   # Linux/macOS 首次需要赋予执行权限
   ./start.sh
   ```
   脚本会自动创建虚拟环境、安装依赖、初始化数据库、生成默认封面，并启动主程序。

**方式二：手动安装**

1. 创建虚拟环境（可选）：
   ```bash
   python3 -m venv venv
   source venv/bin/activate   # Linux/macOS
   # 或 venv\Scripts\activate  # Windows
   ```
2. 安装依赖：
   ```bash
   pip install -r requirements.txt
   ```
3. 初始化数据库（可选，首次运行会自动创建）：
   ```bash
   python scripts/init_db.py
   ```
4. 生成默认封面（可选）：
   ```bash
   python scripts/generate_cover.py
   ```
5. 启动应用：
   ```bash
   python main.py
   ```

---

## 📖 使用指南

### 添加书籍
1. 点击左侧 **“➕ 添加书籍”** 按钮。
2. 填写书名、作者、分类，选择书籍文件（支持 `.txt`、`.md`、`.pdf`、`.docx`）。
3. 点击“保存”，书籍自动添加到书架。

### 扫描导入
1. 将书籍文件按分类放入 `data/books/` 目录（如 `data/books/文学/百年孤独/百年孤独.txt`）。
2. 点击 **“📥 扫描导入”**，系统自动识别并导入，同时复制封面图片（若存在）。

### 阅读书籍
1. 在书架卡片上点击 **“阅读”**。
2. 阅读器窗口支持：
   - 调整字号/字体/主题
   - 目录跳转（左侧树形目录）
   - 添加书签/批注
   - 自动滚动（调节速度）
   - 导出笔记（JSON/TXT）
   - 外部打开（用系统默认程序打开原文件）

### 全文搜索
点击 **“🔍 全文搜索”**，输入关键词，结果列表显示匹配书籍和行内容，点击“打开阅读”跳转至对应位置。

### 鹿鸣川搜书
点击 **“📖 鹿鸣川搜书”**，输入书名或作者，返回书籍元数据和网盘下载链接（如有），提取码自动复制到剪贴板。

### 微信读书集成
1. 点击 **“⚙ 设置 API Key”**，按提示前往 `https://weread.qq.com/r/weread-skills` 获取个人 API Key（格式 `wrk-xxx`）。
2. 保存后，可使用 **“🔍 搜索书籍”** 搜索微信读书书城，或 **“📚 我的书架”** 同步微信读书书架。
3. 在书架或搜索结果中，可查看书籍笔记/划线，点击“阅读”跳转微信读书网页版。

---

## 🗂️ 项目结构

```
sparkread/
├── main.py                    # 程序入口
├── start.sh / start.bat       # 一键启动脚本
├── requirements.txt           # 依赖列表
├── README.md                  # 项目说明
├── config/                    # 配置模块
│   └── settings.py            # 全局设置
├── core/                      # 核心业务逻辑
│   ├── database.py            # SQLite 数据库操作
│   ├── reader.py              # 阅读器核心（解析、进度、书签、批注）
│   ├── search_engine.py       # 全文搜索
│   ├── lunarora_api.py        # 鹿鸣川搜书 API
│   └── weread_api.py          # 微信读书 API
├── ui/                        # 图形界面
│   ├── main_window.py         # 主窗口（分类面板 + 书架网格）
│   ├── reader_window.py       # 阅读器窗口
│   └── dialogs/               # 各类对话框
│       ├── add_book_dialog.py
│       ├── book_info_dialog.py
│       ├── search_dialog.py
│       ├── lunarora_search.py
│       ├── weread_api_setup.py
│       ├── weread_search.py
│       ├── weread_bookshelf.py
│       ├── weread_notes.py
│       ├── category_manager_dialog.py
│       └── export_dialog.py
├── utils/                     # 工具函数
│   ├── file_utils.py
│   ├── encoding_utils.py
│   ├── cover_utils.py
│   └── helpers.py
├── assets/                    # 静态资源
│   ├── themes/                # 主题 JSON
│   └── icons/                 # 图标
├── data/                      # 数据存储
│   ├── sparkread.db           # SQLite 数据库
│   ├── settings.json          # 用户设置
│   ├── books/                 # 书籍文件（按分类子目录存放）
│   └── covers/                # 封面图片
└── scripts/                   # 辅助工具脚本
    ├── init_db.py
    ├── generate_cover.py
    ├── import_from_filesystem.py
    ├── create_placeholders.py
    ├── fix_sparkread.py
    ├── insert_books.py
    └── migrate_categories.py
```

---

## 🛠️ 技术栈

- **GUI框架**：customtkinter
- **图像处理**：Pillow
- **编码检测**：chardet
- **HTTP请求**：requests
- **剪贴板操作**：pyperclip
- **PDF解析**：PyMuPDF
- **DOCX解析**：python-docx
- **数据库**：SQLite3（内置）

---

## ❓ 常见问题

**1. 启动时报错 `ModuleNotFoundError: No module named 'xxx'`**
   - 请确保已正确安装所有依赖：`pip install -r requirements.txt`

**2. 阅读器打开书籍显示乱码**
   - 程序会自动检测编码（UTF-8/GBK/Big5等），若仍乱码，请确认文件编码为常见格式，或手动将文件转为 UTF-8。

**3. 微信读书 API Key 无效**
   - 请确保按照提示从 `https://weread.qq.com/r/weread-skills` 获取 Key，格式为 `wrk-xxxx`。

**4. 书架显示“暂无书籍”但 `data/books/` 下有文件**
   - 请点击 **“📥 扫描导入”** 重新导入，或检查书籍文件是否为 `.txt`/`.md`/`.pdf`/`.docx` 格式。

**5. 如何更换书籍封面？**
   - 在书架卡片上点击 **“详情”**，在书籍详情对话框中点击 **“更换封面”** 选择图片即可。

**6. 如何备份数据？**
   - 直接备份 `data/` 目录（包含数据库、书籍文件和设置）即可。

---

## 🤝 贡献与反馈

欢迎提交 Issue 和 Pull Request 来完善本项目。

- **GitHub Issues**：[提交问题](https://github.com/yourusername/sparkread/issues)
- **邮箱**：your-email@example.com

---

## 📄 许可证

本项目使用 **MIT 许可证**，详见 [LICENSE](LICENSE) 文件。

---

## 🙏 致谢

感谢所有开源库的作者和社区贡献者，以及为用户提供丰富资源的鹿鸣川、微信读书等平台。

---

**星火阅读，让阅读更美好。** 🔥📖