月读 · Moon

把 KOReader 变成真正属于你的阅读系统

本地优先 · 多源同步 · 阅读统计 · AI 阅读工具 · 组合锁屏 · 局域网管理

安装 · 功能 · 截图 · 数据源 · 开发

月读是面向 KOReader 的本地优先阅读增强插件。它不是另一个阅读器，而是在 KOReader 之上补齐书库桌面、多数据源、同步、统计、阅读工具、组合锁屏、拼音输入和局域网管理。

插件使用纯 Lua/LuaJIT，无独立构建步骤，不要求 Java、Node.js 或额外运行时；运行时复用 KOReader 已提供的 UI、SQLite、网络与文件系统能力。

项目状态： 功能仍在快速迭代。升级前建议保留 .moon/ 数据目录；涉及翻页动画等补丁功能时，请按界面提示重启 KOReader。

功能一览

书库	阅读	同步与统计	系统增强
全屏书库桌面	阅读状态栏	本地 / 月读服务 / 微信读书	组合锁屏
搜索、筛选、分类、系列	目录与章节预取	进度冲突处理	输入法增强（拼音词库、仓颉、五笔、注音）
元数据刮削与封面缓存	X-Ray、翻译、百科、词典	笔记、划线、统计同步	局域网文件与输入管理
Z-Library 导入	TXT / MOBI 重排为 EPUB	日历、连续阅读、年度记录	快捷面板与翻页动画

目录

• 功能一览
• 界面预览
• 增强了什么
• 完整功能
• 数据源
• 安装
• 快速开始
• 数据与安全
• 开发与测试

界面预览

图书馆	书籍详情

阅读统计	组合锁屏

远程管理	文件管理

增强了什么

1. 用完整书库桌面替代文件夹式找书

月读提供首页、图书馆、书城、统计和设置组成的全屏桌面：

• 首页组件可自由启用和排序，包括当前阅读、最近阅读列表、最近阅读卡片、时钟、阅读统计、一言和书摘。
• 图书馆使用本地 SQLite 索引，支持关键词搜索、分类和系列筛选、分页浏览。
• 顶栏显示时间、当前数据源以及设备可提供的电量、Wi-Fi、亮度、内存和存储状态。
• 书籍详情集中展示封面、作者、简介、阅读进度、阅读统计和当前数据源允许的操作。
• 桌面字号、界面缩放和封面网格列数均可调整，布局面向墨水屏和触控操作。

书架视图	封面墙

2. 把不同来源的书统一为可靠的书籍身份

月读目前支持本地书籍、月读服务和微信读书。每本书按“数据源 + 稳定 ID”隔离，阅读时继续使用该书所属的数据源，不会因为用户切换当前数据源而把进度、笔记或统计串到另一本书。

• 同一时间只有一个活跃数据源，其他来源可单独启用或隐藏。
• 书架查询统一读取本地数据库，网络同步在后台收敛，打开桌面不必等待远端返回。
• 本地整本文件与微信读书按章内容走同一套书籍详情、阅读会话和统计界面。
• 章节文件通过物理路径精确登记；.moon 内的孤立章节不会被误认为普通本地书籍。

3. 阅读进度、笔记和统计形成闭环

• 自动记录阅读页数、时长和会话统计，不依赖 KOReader 自带统计插件。
• 支持按数据源同步书架、进度、划线/笔记和阅读统计。
• 本地与云端进度相差至少 1% 时显示冲突对话框，由用户选择跳到云端位置或保留本地位置。
• 选择本地进度后会立即上推，使两端重新一致。
• 关闭文档、休眠和网络恢复时会结清或重试待同步数据。
• 统计页提供概览、按日书单、连续阅读和年度记录；微信读书数据还可按周查看阅读书目。

每日书单	连续阅读

4. 增强阅读页，而不复制 KOReader

• 在 KOReader 原生顶部菜单中增加“月读”Tab，可快速进入目录、阅读字体、优化排版、高亮和 X-Ray。
• 可选顶部时间状态栏和底部阅读进度栏。
• 阅读字体可从插件字体或系统字体中快速切换；章节书的字体与排版偏好会自动应用到后续章节文件。
• 划词工具栏可启用、停用和调整顺序，支持选择、高亮、复制、笔记、词典、翻译、百度百科、X-Ray、搜索、HTML 和二维码。
• 章节模式支持自动上一章/下一章、后续章节预取和全本缓存。
• 读完后提供返回首页或删除本书的结束操作。
• 可启用翻页动画补丁；补丁由月读管理并在需要时提示重启。

划词工具栏	百度百科	翻译

章节目录	阅读字体

5. 增加真正用于阅读的内容工具

• X-Ray： 使用 AI 从原文提取人物、地点和专有名词，保存实体说明，并可在正文中标记和划词查询。
• 翻译： 接入 Microsoft Edge 翻译，支持配置常用目标语言。
• 百科： 用百度百科替换原生 Wikipedia 入口，更适合中文内容。
• 词典： 提供 StarDict 词典下载、启停和管理，并接管阅读器中的词典入口。
• 脚注： 首次升级时启用 KOReader 原生脚注弹窗链接，之后仍由用户在原生菜单控制。
• 重新排版： 本地 UTF-8 TXT 和 MOBI 可先预览识别出的章节，再转换为 EPUB 并替换原文件；书籍身份和附属数据随之迁移。
• 截图分享： KOReader 保存截图后，可启动远程管理并显示二维码，让同一局域网内的设备下载图片。

AI 功能使用兼容 /chat/completions 的接口，需要配置接口地址、API 密钥和模型；设置页提供最小请求的连接测试。

X-Ray 实体	实体详情

StarDict 词典下载	查询无结果状态

6. 把锁屏变成可组合的信息页

月读可以继续使用 KOReader 原生锁屏，也可以生成“背景 × 主体 × 位置”的组合锁屏图片。

• 背景：无背景、当前书籍封面、本地壁纸文件夹、网络图片等。
• 主体：当前阅读、阅读统计、阅读账单、阅读高亮、一言、自定义留言、摸鱼日报、书架和封面海报。
• 普通主体支持九宫格位置与宽/窄布局；统计和全屏主体按内容选择合适布局。
• 阅读统计可展示累计时长、进度和近 7 日图表；阅读账单支持今日、近 7 天、近 30 天和本月周期。
• 锁屏图先在后台完整生成，再替换显示文件；生成失败时保留上一张可用图片。

当前阅读	阅读账单	阅读统计

7. 改善墨水屏上的中文输入

• 在 KOReader zh_CN 虚拟键盘首行加入中文候选栏。
• 支持拼音、五笔 86、仓颉五代和台湾注音；仓颉与注音会同步改写键帽显示。
• 支持连续编码、候选翻页和直接点选，输入码不会交给 KOReader 原生 IME。
• 词库使用本地 SQLite 查询，设备端无需常驻输入法服务。
• 大词库采用分片下载、逐片校验、断点续传和最终拼接校验。
• 在线下载不便时，可从 GitHub Release 下载已使用最终名称的词库文件，直接放入 .moon/。
• 非中文布局、数字输入框、词库缺失以及物理键盘输入保持 KOReader 原生行为。

8. 从电脑或手机管理阅读器

启用远程管理后，同一局域网中的浏览器可访问以下功能：

• 文件管理： 资源管理器式浏览、拖拽上传、下载、新建目录、重命名、移动、递归删除和图片预览。
• 冲突处理： 上传同名文件时可选择覆盖、跳过或自动重命名。
• ZIP 解压： 在设备端将 ZIP 解压到同目录的同名文件夹，并检查危险路径和异常归档。
• 远程输入： 阅读器输入框激活时，从浏览器一次发送整段文字。
• 共享剪贴板： 在浏览器与阅读器之间读取、写入和复制文本。
• 连接配置： 在电脑上填写 AI、月读服务和 Z-Library 等不适合用墨水屏键盘输入的配置。
• 生命周期： 可配置端口和开机自启；设备休眠时停止服务，唤醒后按配置恢复。

远程管理是设备内运行的轻量 HTTP 服务，不依赖云端中转；页面截图见界面预览。

完整功能

书库与书籍管理

• 首页组件启停、排序和多种最近阅读布局。
• 本地 SQLite 书籍索引、最近阅读、搜索、分类、系列和分页。
• 本地目录后台扫描、失效条目清理和文件改名后的身份迁移。
• 本地书籍分类/系列编辑；目录层级随编辑结果实际移动。
• 豆瓣、微信读书元数据搜索与本地书籍刮削。
• 封面、正文、章节、目录和 HTTP 响应缓存。
• 缓存体积统计、手动清理和后台失效清理。
• 书籍下载进度、章节缓存进度、任务取消和缓存任务列表。
• 删除本地原书，或删除在线来源的云端书架/原书并清理设备上的缓存与登记。
• 本地扫描格式：PDF、EPUB、DJVU、MOBI、CBZ、CBT、DOCX、RTF、HTML、TXT、XPS、FB2、PDB、CHM 和 Markdown。

书城

• 微信读书源提供自身书城和搜索。
• 对支持导入的来源提供全局 Z-Library 书城。
• Z-Library 支持账号登录、多镜像种子、30x 跳转、挑战页检测和镜像故障转移。
• 下载完成后直接加入当前来源的书库。

阅读与同步

• 整本文件与按章阅读两种模式。
• 书架、进度、笔记/划线和统计按来源独立同步。
• 网络失败后的脏数据持久化与自动重试。
• 微信读书扫码登录、书架同步、书城、目录缓存、章节预取、全本缓存、笔记同步和阅读时长上报。
• 阅读页状态栏、快捷面板、可排序划词菜单、阅读结束对话框和翻页动画。
• 阅读字体选择支持插件字体与系统字体。

快捷面板

• 桌面动作：夜间模式、Wi-Fi、远程管理、旋转、刷新、截图、前光和休眠。
• 阅读动作：目录、字体、重新排版、高亮和 X-Ray。
• 桌面与阅读动作分别注入 KOReader 原生顶部菜单；各动作可按设备能力显示，并可启停和调整顺序。

国际化

• 简体中文为源语言。
• 提供繁体中文和英文界面资源。
• 语言切换复用 KOReader 原生语言菜单。

数据源

数据源	阅读形态	主要能力	配置要求
本地书籍	整本文件	扫描、搜索、分类/系列、编辑、刮削、统计、重新排版、Z-Library 导入	选择书籍根目录
月读服务	整本文件	书架、下载、进度、笔记和统计双向同步	服务地址与令牌
微信读书	按章阅读	扫码登录、书架与书城、目录、章节缓存、进度、笔记和统计同步	微信扫码登录

月读服务端项目见 AnkioTomas/book。

功能入口按当前数据源能力显示。例如本地书籍可编辑和刮削元数据；微信读书提供源内书城；未登录或未配置的在线源不能同步远端内容。

安装

从 Release 安装

1. 从 GitHub Releases 下载最新插件压缩包。

2. 解压后确认得到完整的 book.koplugin/ 目录。

3. 将该目录复制到 KOReader 数据目录的 plugins/：

   <KOReader 数据目录>/plugins/book.koplugin
   

4. 重启 KOReader。

5. 从主菜单打开 月读。

从源码安装

直接复制仓库中的 book.koplugin/。tests/、assets/、koreader/ 等目录不是插件交付物，不需要复制到设备。

注意： 插件目录名必须是 book.koplugin，不能改成 book，也不能多套一层仓库目录。

快速开始

本地书籍

1. 打开 月读 → 设置 → 数据源 → 本地。
2. 选择书籍根目录。
3. 将当前数据源切换为 本地书籍。
4. 返回首页；月读会在后台扫描，并把索引写入本地 SQLite。

本地源不需要账号或服务器。一级目录作为分类，二级目录可作为系列；在详情页修改分类或系列时，月读会移动实际文件并同步更新身份。

月读服务

1. 打开 设置 → 数据源 → 月读服务。
2. 填写服务地址和令牌。
3. 切换到 月读服务，再执行 立即同步。

微信读书

1. 打开 设置 → 数据源 → 微信读书。
2. 使用微信扫码登录。
3. 同步书架，或进入书城搜索并加入书籍。
4. 打开书籍后按章阅读；目录和后续章节会按需缓存。

中文输入

1. 打开 设置 → 语言与输入 → 中文输入法增强。
2. 选择键盘布局，并下载该布局的独立词库。
3. 在 KOReader 虚拟键盘上点 🌐 切换到中文布局。

远程管理

1. 让阅读器和电脑/手机连接同一可信 Wi-Fi。
2. 打开 设置 → 远程管理 → 远程管理服务。
3. 在浏览器访问界面显示的地址，例如 http://192.168.1.10:9528/。

数据与安全

远程管理安全边界

远程管理默认关闭，但当前版本没有登录、密码或访问令牌认证，并会监听设备可访问的网络接口。服务只限制可操作的受管目录，不能阻止同一网络中的其他设备发起请求。

• 服务会拒绝非 IP Host、跨站写请求，并保护 .moon/settings/ 等凭据路径；这些限制不能替代身份认证。
• 只在可信局域网中临时启用。
• 不要把端口映射到公网，不要通过反向代理公开。
• 公共 Wi-Fi、访客网络或其他不可信网络中不要开启。
• 使用结束后立即关闭；不需要自动运行时不要启用开机自启。

本地数据

插件数据位于 KOReader 数据目录下的 .moon/：

.moon/
├── settings/                 # 通用、功能和数据源配置
├── book.sqlite3              # 书籍、章节、目录、进度、笔记和统计
├── cache/                    # 下载书籍、章节、封面和 HTTP 缓存
├── dictionary.sqlite3        # 拼音词库
├── dictionary-wubi.sqlite3   # 五笔词库（选择后独立下载）
├── dictionary-cangjie.sqlite3
├── dictionary-zhuyin.sqlite3
├── screensaver/wallpapers/   # 自定义锁屏壁纸
└── book.log                  # 月读独立日志

数据库身份使用 (source_id, stable_id)。本地书籍的 stable_id 是文件路径，在线书籍使用来源提供的稳定 ID；章节文件通过物理路径反查所属书籍和章节序号。

数据库使用增量迁移。插件升级不会主动清空用户数据；“清理缓存”只删除可重新生成的缓存，不删除数据库中的书籍身份、进度、笔记和统计。

在线来源、AI 服务和 Z-Library 的凭据保存在本机 .moon/settings/。请自行保护 KOReader 数据目录，不要把整个目录分享给他人。

设置索引

• 数据源： 切换活跃来源、隐藏不用的来源、配置账号并立即同步。
• 阅读： X-Ray、状态栏、翻页动画、划词工具栏、词典、翻译和百科。
• 显示： UI 字体、界面缩放和书库最大列数。
• 锁屏： 接管开关、背景、主体、位置、宽度、文案和账单周期。
• 桌面： 开机进入月读、首页组件和桌面行为。
• 语言与输入： KOReader 界面语言、中文输入法布局和独立词库。
• AI 服务： 接口地址、API 密钥、模型和连接测试。
• 远程管理： 服务开关、端口和开机自启。
• 快捷面板： 桌面/阅读动作的启停与排序。
• 维护： 缓存清理、调试日志、版本信息和关闭桌面。

开发与测试

项目不需要构建，唯一插件交付物是 book.koplugin/。离线测试不会启动 KOReader：

./tests/run.sh

运行单个测试：

./tests/run.sh tests/book/catalog_spec.lua

本机模拟器需要仓库根目录下有 KOReader 源码和 Homebrew GNU 工具链：

./run.sh

测试数据写入仓库根目录的 test/ 沙箱，不会写入本机 KOReader 的真实 config/。

新增数据源遵循 source/base.lua 和 source/registry.lua 接口。文字处理复用 utils/text.lua，SQLite 访问必须使用参数化查询，耗时文件与解析任务放到 worker，数据库写入留在主进程。

更完整的架构说明见 DESIGN.md。

版本与发布

版本文件是 book.koplugin/bookversion.lua，源码树中默认显示 0.0.0-dev。 发布时 CI 在 v* tag 中注入版本、打包 book.koplugin/ 并发布到 GitHub Release。

许可证

本项目采用 GNU GPLv3。