# revise-read

**Repository Path**: 438704315/revise-read

## Basic Information

- **Project Name**: revise-read
- **Description**: ReviseRead温故知新
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-31
- **Last Updated**: 2026-08-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 读书笔记桌面工具

一个本地优先的 Windows 桌面读书笔记工具，支持剪贴板自动摘录、区域截图、OCR、Markdown 笔记、AI 总结和全文搜索。

当前版本：`1.0.0`

## 任务与打卡

- 工具栏或 `任务 > 任务与打卡` 可记录当日、本周、长期和临时任务。
- 任务可设置 1 到 4 级紧急程度和重要级别，默认先按紧急程度、再按重要级别排序。
- 切换到“手动排序”后可拖动调整顺序；普通任务完成后进入已完成列表并可恢复。
- 提醒支持一次、每小时、每天、每周和每月重复；完成重复提醒会记一次打卡并计算下次时间。
- 应用运行时通过系统托盘发送到期通知，任务窗口保留最近完成和打卡记录。

## 下载后如何安装和启动

### 方式一：普通使用者

1. 安装 Python 3.12，并勾选 “Add python.exe to PATH”。
2. 下载或克隆本项目后，进入项目根目录。
3. 第一次使用时，在 PowerShell 中执行：

```powershell
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -U pip
.\.venv\Scripts\python.exe -m pip install -e ".[ocr]"
```

4. 之后双击根目录下的 `启动read.bat` 即可启动。

如果双击没有反应，可以在 PowerShell 中执行：

```powershell
.\run.ps1
```

这样可以看到控制台错误信息，方便排查。

### 方式二：开发者运行

```powershell
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -U pip
.\.venv\Scripts\python.exe -m pip install -e ".[ocr,dev]"
.\.venv\Scripts\python.exe -m reading_notes
```

首次启动会在“文档”目录创建“读书笔记”资料库。资料库、AI、OCR、截图快捷键等都可以在软件设置中调整。

## 阅读与学习

- `阅读与学习 > 内置阅读`：打开 PDF/EPUB，记录阅读进度和书签；选中文字可直接保存为摘录。扫描 PDF 可对当前页 OCR，并保留页面原图。
- 阅读器支持目录/章节、跳页、缩放、跨页摘录队列、高亮批注和批注 Markdown 导出。跨页保存会在正文中保留各段页码或章节。
- `阅读与学习 > 今日复习`：按当前书籍复习到期摘录，通过“忘记 / 模糊 / 熟悉”调整间隔，并可导出 Anki `.apkg`。
- 复习窗口支持自定义牌组、牌组筛选、先显示问题再揭示答案、重置卡片、暂停卡片、恢复暂停卡、每日目标和最近 42 天热力图，并显示连续天数、保持率及难点摘要。
- `阅读与学习 > 书籍问答`：选择一本或多本书生成综合总结或提问；回答提供可跳转的摘录引用，并可保存为专题 Markdown。
- 书籍问答会先在本地重排相关摘录、显示上下文用量，并以流式方式展示回答；回答会保存为历史版本，支持回看和带上当前回答继续追问。
- `阅读与学习 > 生成读书卡片`：为当前书籍生成结构化专题 Markdown，包含核心观点、关键概念、主题脉络、行动建议和追问。
- `阅读与学习 > 生成复习卡`：基于当前书籍或多选摘录生成主动回忆问答卡，自动保存为摘录并加入“AI 问答卡”复习牌组。
- `阅读与学习 > 剪藏收件箱`：查看网页剪藏，选择目标书籍后转为摘录。剪藏不会自动创建默认书籍。

## 网页剪藏

1. 保持桌面程序运行；默认接收地址为 `http://127.0.0.1:27123/capture`。
2. 在 Chrome/Edge 扩展管理页启用开发者模式，选择“加载已解压的扩展”，目录为项目中的 `browser-extension`。
3. 点击浏览器工具栏扩展，选择“保存选中文字”或“保存网页正文”。
   也可以在网页或选中文字上点击右键直接剪藏；弹窗中填写的标签会供右键菜单复用。
4. 回到桌面程序的“剪藏收件箱”，选择书籍并转为摘录。

剪藏服务仅监听本机回环地址。可在“设置 > 常规”中关闭服务或修改端口；修改端口后还需同步调整扩展 `manifest.json` 和 `popup.js` 中的地址。
扩展目录内容更新后，需要在 Chrome/Edge 扩展管理页对该扩展点击“重新加载”。网页 HTML 快照可在收件箱查看，转为摘录后存入书籍 `assets/web`。

## 数据管理

- “数据 > 导出”可导出当前摘录、当前书籍、多本书籍或整个书库，格式为 `.readerpack`。
- ReaderPack 包含 Markdown、书籍元数据、原图、图示、格式版本和 SHA-256 校验清单。
- 整个书库的 ReaderPack 同时包含任务和打卡记录，可用于备份及迁移；导入时安全合并，不清空当前任务。
- “数据 > 导入”会先显示书籍数、摘录数、文件数、大小和完整性检查结果，并提供跳过、导入较新版本、保留冲突双方三种策略。
- “数据 > 立即备份”创建完整书库快照；设置中可配置自动备份间隔和保留数量。
- “数据 > 恢复备份”会在替换前保留回滚目录，恢复成功后旧书库进入 Windows 回收站。
- “数据 > 迁移书库”会复制全部长期数据并在目标目录重建 SQLite 索引。
- “数据 > 多格式导出”可将当前书籍导出为 Word、PDF、HTML 或 Obsidian Vault。ReaderPack 仍是无损备份和迁移格式。
- 多格式导出支持多选书籍和“完整笔记 / 仅摘录正文 / 复习提纲”模板；Obsidian 可启用增量发布，未变化笔记不会被重写。
- “数据 > 模板导出”提供可编辑 Markdown 模板，支持 `{{book.title}}`、`{{#excerpts}}...{{/excerpts}}`、`{{excerpt.content}}` 等占位符。

## 多电脑同步

在“设置 > 备份与同步”中选择同步方式：

- 本地同步目录：适合 OneDrive、Dropbox、坚果云同步盘、移动硬盘或局域网共享目录。
- WebDAV：填写独立的 WebDAV 目录、用户名和密码。
- 同步仅传输 `books` 下的 Markdown、`book.yaml` 和图片，不同步 SQLite、日志、缓存或本机配置。
- 同一文件在两台电脑上都发生修改时，保留当前版本并生成带“冲突、设备名、时间”的远端版本副本。
- 远端删除会先移动到本机 `.reader/sync-trash`，不会直接永久删除。
- 每个同步目标绑定书库 ID，发现目标属于另一书库时会停止同步。
- “数据 > 同步冲突”可查看冲突副本、预览文本、打开文件并触发重建索引。

WebDAV 密码当前保存在本机 UTF-8 配置文件中。共享电脑上建议使用专用账号或应用密码。

## 整理与知识关联

- `整理 > 版本历史`：查看 Markdown 差异并恢复历史版本。
- `数据 > 回收站`：恢复、永久删除或清空应用内删除记录。
- 中间摘录列表支持 Ctrl、Shift 多选；`整理`菜单提供批量移动、标签、导出、AI 和删除。
- `整理 > 标签管理`：重命名、合并或删除书籍和摘录中的标签。
- 工具栏 `导入文档`：读取 PDF 页或 EPUB 章节，保存选中文字、页码、章节和原文件。
- `整理 > 合并为专题`：将所选摘录生成带双向链接的专题 Markdown。
- 搜索栏勾选“语义”后使用离线本地向量排序；右侧“相关摘录”可跳转到相近内容。
- 右侧“反向链接”显示引用当前摘录的专题笔记。

历史版本存放在 `.reader/history`，应用回收站存放在 `.reader/trash`，同步删除的安全副本存放在 `.reader/sync-trash`。

## 开发运行

```powershell
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -U pip
.\.venv\Scripts\python.exe -m pip install -e ".[ocr,dev]"
.\.venv\Scripts\python.exe -m reading_notes
```

首次启动会在“文档”目录创建“读书笔记”资料库，并自动建立一本“未分类摘录”。可在设置中修改资料库目录、截图快捷键、OCR、AI 服务、AI 费用估算单价和每日复习目标。AI 设置提供 Ollama 和 LM Studio 本地服务预设。

## 数据原则

- 一本书对应一个目录。
- 每条摘录对应一个 Markdown 文件。
- 截图原图保存在书籍的 `assets` 目录。
- SQLite 只负责索引和查询，可以从 Markdown 文件重建。
- 配置、Markdown、YAML 和日志均使用 UTF-8。
- 删除摘录或书籍时，相关文件会进入应用内回收站，可查看并恢复。