# kindle-agent
**Repository Path**: pior/kindle-agent
## Basic Information
- **Project Name**: kindle-agent
- **Description**: kindle使用小工具，可以同步阅读记录、标记、笔记等，支持自动生成读书笔记。
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-17
- **Last Updated**: 2026-08-31
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# 一页笔记
> 当前版本：**v0.4.0**
一款 Windows 桌面应用，用于对接管理 Kindle 电子书阅读器，并通过 AI 将零散的阅读标记与笔记自动整理为结构化的「一页笔记」，也可基于全书正文生成客观的「AI 智能摘要」。
- **轻量部署**：单机桌面应用，SQLite 单文件存储，无需服务器。
- **AI 笔记整理**：以书为单位，整合全部标记/笔记、书籍信息与用户评论，生成可读性强的一页笔记。
- **AI 智能摘要**：提取全书正文，生成客观、结构化的全文摘要，回答「这本书在讲什么」。
- **在线资源接入**：自动查询豆瓣评分，并可配置接入个人ima知识库、百度网盘等资源，一键上传、一键导入，省去繁琐操作。
---
## 目录
1. [功能特性](#功能特性)
2. [界面预览](#界面预览)
3. [环境要求](#环境要求)
4. [安装与运行](#安装与运行)
5. [使用说明](#使用说明)
6. [打包为可执行文件](#打包为可执行文件)
7. [技术栈](#技术栈)
8. [项目结构](#项目结构)
9. [变更记录](#变更记录)
---
## 功能特性
- **设备自动探测**：USB 接入 Kindle 后自动识别，顶部状态栏显示连接状态与设备存储占用。
- **图书列表**：横排条目展示封面、书名、作者、阅读进度、同步时间与已读标记，支持筛选、排序与翻页。
- **一页笔记**：AI 生成结构化笔记，支持查看、复制、导出 Markdown 与重新生成。
- **AI 智能摘要**：提取 epub / mobi / azw3 全书正文，并发生成客观全文摘要（全书概览 / 主要脉络 / 核心观点 / 适读人群），支持 Kindle 书、本地图书、网盘文件三个入口，同一本书跨入口共用一份摘要。
- **本地图书导入**：配置本地目录，勾选图书一键导入到 Kindle。
- **在线知识库**：将生成的「一页笔记」一键上传到腾讯 ima、Obsidian 或印象笔记，可在知识库中多端查阅与检索。
- **在线网盘**：接入百度网盘，浏览端内文件、搜索、导入到本地目录或 Kindle。
- **豆瓣评分**：为每本书查询豆瓣评分（金色分数 + 评分人数），详情弹窗与图书列表均可展示；评分一次性查询、永久固化，不自动更新。
---
## 界面预览
### Kindle 同步
### 自动同步
### 本地图书
### 在线网盘
### 笔记标记
### 生成笔记
### 查看笔记
### 我的笔记
### 生成摘要
### 查看摘要
---
## 环境要求
- Windows 10 及以上（目标平台）
- Python 3.10 及以上
- Kindle 电子书阅读器（USB 连接）
---
## 安装与运行
### 方式一：直接下载打包好的 exe（推荐，无需安装 Python）
> 适用于 Windows 10 及以上，**无需安装 Python 或任何依赖**，下载后双击即可运行。
- [下载 `一页笔记.0.4.exe`](dist/一页笔记.0.4.exe)
> 说明：
> - 单文件 exe 已内置 Python 运行时与全部依赖，目标机器无需安装 Python。
> - 若运行报错提示缺少 WebView2，请安装 [Microsoft Edge WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2/)（Win10/11 一般自带）。
> - 首次启动因需解压到临时目录，会稍慢，属正常现象。
### 方式二：源码运行（需 Python 3.10+）
```bash
# 1. 创建并激活虚拟环境
python -m venv venv
venv\Scripts\activate
# 2. 安装依赖
pip install -r requirements.txt
# 3. 启动应用
python -m kindle_agent.app
```
启动后，将 Kindle 通过 USB 连接电脑即可自动同步。
---
## 使用说明
### 1. 连接与同步
1. 将 Kindle 通过 USB 接入电脑，系统自动识别设备并弹出同步动画弹窗。
2. 前台阶段快速读取新书信息后关闭弹窗，阅读进度、笔记与封面在后台静默更新。
3. 拔除设备后，连接状态自动回落为「未接入」。
### 2. 浏览图书
- 打开「Kindle 同步」页浏览图书列表。
- 顶部可切换筛选（全部 / 未读 / 已读 / 已删除）。
- 可切换排序方式：**最后阅读时间**、**阅读进度**，并可切换升/降序。
- 无最后阅读时间的书，按文件创建时间参与排序，并在相同位置展示该时间。
- 已删除的书籍在"全部"列表中带红色"已删除"标签，仍可标记已读/未读。
- 点击"管理"进入管理模式，可批量勾选删除；Kindle 未连接时管理按钮不可用。
### 3. 生成与查看笔记
1. 点击图书条目的「生成笔记」，弹窗展示该书标记/笔记，可输入评论。
2. 点击「生成」，AI 生成「一页笔记」后自动打开查看弹窗。
3. 查看弹窗支持**复制**（复制到剪贴板）、**导出 Markdown**、**重新生成**。
> 首次使用前，请先在右上角齿轮「设置」中配置模型服务商、API Key。
### 4. AI 智能摘要
为任意一本书生成基于**全书正文**的客观摘要，回答「这本书在讲什么」。
**生成步骤：**
1. 打开书籍详情弹窗（**Kindle 同步书 / 本地图书 / 网盘文件**三个入口均支持）。
2. 点击顶部「生成摘要」，弹窗展示生成进度（提取正文 → 分块提取要点 → 合并）。
3. 生成完成后自动打开「查看摘要」弹窗，支持**复制**与**重新生成**。
4. 已生成过摘要的书，按钮变为「查看摘要」，点击直接打开。
> 首次使用前，请先在右上角齿轮「设置」中配置模型服务商、API Key。
**与「一页笔记」的区别**：两者相互独立、可并存，请勿混淆。
| | 一页笔记 | AI 智能摘要 |
|---|---|---|
| 数据来源 | 你的**标注**与评论 | **全书正文** |
| 回答的问题 | 我从这本书里读出了什么 | 这本书在讲什么 |
| 视角 | 第一人称，主观 | 第三人称，客观 |
| 是否需要读过 | 需要已有标注 | **不需要**，未读的书也能生成 |
| 结构 | 核心观点 / 关键笔记 / 我的思考 | 全书概览 / 主要脉络 / 核心观点（3-5 条）/ 适读人群 |
| 字数 | 不限 | 500–1500 字 |
**摘要的归属与复用**：摘要按 **ISBN** 记录；无 ISBN 的书籍降级使用「主标题 + 作者」。因此同一本书无论从 Kindle、本地图书还是网盘打开，都共用同一份摘要，不会重复生成。
> 说明：
> - **支持格式**：epub / mobi / azw3。扫描版或正文过少的文件无法生成。
> - **Kindle 同步书**生成摘要时需保持设备连接（正文直接从设备读取，不做缓存）；拔除设备后已生成的摘要仍可查看，但不能重新生成。
> - **带 DRM 的书籍**需先在「设置」→「本地图书」中填写 **Kindle 序列号**，否则无法提取正文。
> - 生成采用分块并发处理，长书通常需数十秒；过程中可查看进度，摘要与 Kindle 同步的进度互不影响。
> - 正文档案**不做缓存**，仅保存摘要结果，重新生成时会重新读取源文件。
> - 个别分块调用失败不会导致整体失败，应用会跳过失败分块并合并其余内容。
### 5. 右键删除书籍
1. 在 Kindle 同步列表的图书卡片上点击**鼠标右键**，弹出菜单。
2. 点击「删除」，弹出确认框。
3. 确认后，将同时删除本地同步记录、关联笔记以及 Kindle 设备上的书籍文件（含 `.sdr` 阅读进度目录）。
> 删除书籍文件需 Kindle 已连接；设备未连接时书籍文件无法删除，但本地记录仍会清除。
### 6. 导入本地图书
1. 在「设置」中配置本地图书目录。
2. 打开「本地图书」页，勾选需要导入的图书（支持全选当前页）。
3. 点击右上角「导入到 Kindle」，文件复制到设备 `documents/` 目录。
> 未连接 Kindle 时导入按钮禁用；支持 mobi / azw3 / epub 三种格式。
### 7. 上传到在线知识库
应用支持将生成的「一页笔记」**单向上传**到以下平台：
| 目标平台 | 接入方式 | 需要配置 |
|---|---|---|
| **腾讯 ima** | 官方 OpenAPI（静态 Client ID + API Key） | Client ID、API Key、（可选）文件夹 ID |
| **Obsidian** | 本地 REST API 插件（需先在 Obsidian 安装启用） | API Key、目标文件夹、（可选）服务地址 |
| **印象笔记** | Evernote SDK（依赖 `zibuyu_evernote`） | Developer Token、（可选）笔记本 GUID、环境 |
使用步骤：
1. 打开「设置」→「上传到知识库」tab。
2. **勾选启用**一个或多个目标平台，并填写对应凭证。
3. 点击「保存」。
4. 打开已生成笔记的「查看笔记」弹窗，点击「上传到知识库」按钮。
5. 应用会同时把当前笔记发到**所有已启用**的平台，并弹出按平台汇总的上传结果。
> 说明：
> - **Obsidian** 需先在 Obsidian 中安装并启用社区插件 **Local REST API**（默认监听 `http://localhost:27124`）。
> - **印象笔记**使用社区维护的 Python 3 SDK `zibuyu_evernote`（官方 SDK 仅支持 Python 2）；未安装该依赖时仅印象笔记不可用，不影响 ima / Obsidian。
> - 上传为**单向上传**：每次点击都会在目标平台新建一篇独立文档，不会覆盖旧文档，也不会从平台拉取内容。
### 8. 在线网盘（百度网盘）
应用支持接入**百度网盘**，在「网盘」页管理云端图书文件：
1. 打开「网盘」页，首次使用点击「授权」，弹出百度 OAuth 扫码页面，用百度 App 扫码授权。
2. 授权成功后令牌自动持久化（重启无需重复授权），顶部显示已登录账号。
3. 浏览网盘文件，支持路径进入、搜索、排序与翻页。
4. 勾选文件后可「导入到 Kindle」（需Kindle 已连接时）。
5. 点击网盘图书条目直接打开详情弹窗，可查看元数据与豆瓣评分（见下节）。
> 说明：
> - 授权令牌以设备本地存储保存，不上传任何第三方。
> - 网盘文件详情中的豆瓣评分为实时查询，不落本地缓存（每次打开时查询一次）。
### 9. 豆瓣评分
应用为图书附加**豆瓣评分**，帮助快速判断书籍口碑：
- **状态语义**：
- 查询中：弹窗显示「`[豆] 查询中…`」。
- 查无评分：显示灰色「暂无评分」。
- 查询失败（如网络异常 / 豆瓣限流）：显示灰色「查询失败」。
- **固化策略**：查询成功后评分写入本地数据库，**一次性查询、永久保存**，关闭弹窗后列表自动刷新回显，不会反复查询。
> ！！！豆瓣接口存在反爬限速，高频请求可能触发临时封禁；若显示「查询失败」，稍后重新打开详情弹窗即可重试。
### 10. 系统设置
设置弹窗采用 **tab 分页**，共三个面板：
- **模型**：选择模型服务商（内置预设自动填充 Base URL 与模型名），填写 API Key。
- **本地图书**：配置本地图书目录路径，用于「本地图书」页导入；下方另有 **Kindle 序列号**（可选，用于解密个人已购图书的 DRM，也是带 DRM 书籍生成摘要的前提）与「清除同步记录」。
- **上传到知识库**：配置在线知识库上传目标（见上节）。
- **关于**：查看软件名、版本号、开发人、联系邮件与小红书主页（点击可直接打开）。
配置完成后点击「保存」生效。
> API Key 与模型配置同时供「一页笔记」与「AI 智能摘要」使用，只需配置一次。
## 技术栈
| 层次 | 技术 | 说明 |
|---|---|---|
| 桌面框架 | Python + pywebview | 本地 Web UI，避免 Chromium 打包 |
| 前端 | HTML / CSS / JavaScript（原生） | 通过 `window.pywebview.api` 调用后端 |
| 后端 | Python | 设备探测、文件解析、Agent 调用、SQLite 操作 |
| 存储 | SQLite | 单文件，零依赖 |
| 电子书解析 | mobi、ebooklib | 元数据 + 封面 + 全书正文提取（epub spine / mobi RAWML） |
| KRDS 解析 | 自实现（`krds.py`） | Kindle sidecar 二进制格式，读取阅读进度 |
| AI 调用 | httpx（OpenAI 兼容端点） | Bearer API Key 鉴权 |
| AI 智能摘要 | 标准库 concurrent.futures | 正文分块 + 并发 map-reduce 生成全书摘要 |
| 封面服务 | 内置 HTTP 服务 | 按需流式提供封面 |
| 知识库上传 | 标准库 urllib + zibuyu_evernote | 腾讯 ima OpenAPI / Obsidian Local REST API / Evernote SDK |
| 在线网盘 | 标准库 urllib + 本地 HTTP 服务 | 百度网盘 Open API（OAuth 扫码授权） |
| 豆瓣评分 | 标准库 urllib | 豆瓣搜索建议 / ISBN 页面解析（带 UA 池与限速） |
| 打包 | PyInstaller | Windows exe |
---
## 项目结构
```
kindle-agent/
├── frontend/
│ └── index.html # 前端 UI（单文件）
├── kindle_agent/
│ ├── app.py # 应用主入口
│ ├── service.py # 服务层（pywebview 暴露的 Api）
│ ├── device.py # Kindle 设备探测
│ ├── sync.py # 增量同步逻辑
│ ├── parsing.py # 电子书元数据/封面/正文解析
│ ├── krds.py # KRDS 二进制格式解析（阅读进度）
│ ├── cover_server.py # 封面 HTTP 服务
│ ├── agent.py # AI Agent 调用
│ ├── summarizer.py # 全书正文摘要（分块 + 并发 map-reduce）
│ ├── db.py # SQLite 初始化与迁移
│ ├── douban.py # 豆瓣评分查询（ISBN / 书名作者搜索）
│ ├── pan/ # 在线网盘（插件化）
│ │ ├── __init__.py # PanProvider 抽象 + 注册表
│ │ └── baidu.py # 百度网盘（OAuth 授权 / 浏览 / 导入）
│ └── upload/ # 在线知识库上传目标（插件化）
│ ├── __init__.py # UploadTarget 抽象 + 注册表
│ ├── ima.py # 腾讯 ima 上传
│ ├── obsidian.py # Obsidian 上传
│ └── evernote.py # 印象笔记上传（Markdown→ENML）
├── docs/
│ ├── 需求文档.md # 需求规格说明书（SRS）
│ └── images/ # 界面截图
├── tests/ # 单元测试
├── kindle_agent.spec # PyInstaller 打包配置
├── requirements.txt # 依赖清单
├── icon.ico / icon.png # 应用图标
└── README.md
```
---
## 变更记录
| 日期 | 版本 | 变更内容 |
|---|---|---|
| 2026-08-30 | v0.4.0 | 新增「AI 智能摘要」：提取全书正文并发生成客观全文摘要（全书概览 / 主要脉络 / 核心观点 / 适读人群），支持 Kindle 同步书、本地图书、网盘文件三个入口
摘要内容严格基于正文，与个人标注和评论隔离，与「一页笔记」相互独立可并存
新增「设置 → 关于」页：展示软件名、版本号、开发人、联系邮件与小红书主页
修复本地图书详情每次打开都重新查询豆瓣评分的问题（现复用缓存，不再受豆瓣限速影响）
书籍详情弹窗长书名自动截断，鼠标悬浮显示完整书名 |
| 2026-08-21 | v0.3.0 | 新增「豆瓣评分」：详情弹窗与图书列表展示豆瓣评分（金色），打开详情时查询一次、永久固化，列表自动回显
新增「在线网盘」：接入百度网盘，支持 OAuth 扫码授权、文件浏览/搜索、导入到本地或 Kindle
修复本地图书详情弹窗关闭后列表自动滚动回顶部的问题
修复百度网盘请求偶发超时导致整段 traceback 崩溃的问题（超时转可读错误并自动重试一次） |
| 2026-08-19 | v0.2.0 | 新增「上传到知识库」功能：生成的笔记可一键上传到腾讯 ima、Obsidian、印象笔记（可多选启用） |
| 2026-08-17 | v0.1.0 | 书单"全部"现在会显示已删除的书（带红色标签），你仍然可以对它们标记已读/未读
重新同步时，若发现已删除的书其实还在 Kindle 上，会自动把它还原回正常列表
修复翻到最后一页时界面卡在"正在同步"弹窗无法关闭的问题
Kindle 未连接时，"管理"按钮置灰不可点，鼠标悬浮会提示原因
后台还在同步时，连接状态旁会显示"后台同步中…"，完成后自动消失 |
---
## 许可证
仅供个人学习与使用。