月读 Logo

月读 · Moon

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

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

最新版本 下载量 GPL-3.0 许可证 LuaJIT KOReader 插件

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

月读首页 KOReader 阅读页

月读是面向 [KOReader](https://koreader.rocks/) 的本地优先阅读增强插件。它不是另一个阅读器，而是在 KOReader 之上补齐书库桌面、多数据源、同步、统计、AI 阅读助手、组合锁屏、中文输入和局域网管理。 插件使用纯 Lua/LuaJIT，无独立构建步骤，不要求 Java、Node.js 或额外运行时；运行时复用 KOReader 已提供的 UI、SQLite、网络与文件系统能力。 > **项目状态：** 功能仍在快速迭代。升级前建议保留 `.moon/` 数据目录；涉及翻页动画等补丁功能时，请按界面提示重启 KOReader。 > **升级提示：** 微信读书登录已改为墨水屏客户端扫码协议，旧版本的网页登录会视为未登录，升级后请在「账号 → 微信读书」重新扫码一次。 ## 功能一览 | 书库 | 阅读 | 同步与统计 | 系统增强 | |---|---|---|---| | 全屏书库桌面，首页组件自由组合 | 阅读页顶栏 / 底栏、左侧栏 | 十四个内置源（越狱 Kindle 上另有 Kindle 书库）+ 第三方书源（Kavita、BookOrbit） | 组合锁屏与锁屏密码 | | 搜索、筛选、分类、系列、已下载 | AI 解释、问书、章节摘要、读书报告 | 书架、进度、笔记、统计按源双向同步 | 输入法增强（拼音、小鹤双拼、五笔、仓颉、速成、注音，简繁转换） | | 元数据刮削与封面缓存 | X-Ray、统一查词窗口（词典 / 翻译 / AI / 百科）、整书双语对照、段评、生僻字注音 | 进度冲突处理与离线补推 | 局域网文件、输入、配置与更新管理 | | Z-Library 与 OPDS 书城、订阅（RSS / 网页 / 公众号） | 重新排版（另存，原书不动）、AZW3 | 热力图、阅读时段、读完预测、年度记录 | 快捷面板与 14 种翻页动画 | | 后台任务列表、单书缓存清理、漫画缓存清理（已读 / 按系列 / 全部） | 按章书的全书笔记列表、章节缓存范围 | 导入 KOReader 自带统计 | 自动夜间、自动亮度、时区与 NTP 校时 | | 游戏：小黑屋、阿页的阁楼、游戏合集（可选插件） | 蓝牙翻页器与想法选择器（可选插件 pageturner） | | | ## 目录 - [功能一览](#功能一览) - [界面预览](#界面预览) - [增强了什么](#增强了什么) - [完整功能](#完整功能) - [数据源](#数据源) - [安装](#安装) - [快速开始](#快速开始) - [数据与安全](#数据与安全) - [设置索引](#设置索引) - [开发与测试](#开发与测试) ## 界面预览 | 图书馆 | 书籍详情 | |:---:|:---:| | 图书馆 | 书籍详情 | | 阅读统计 | 组合锁屏 | |:---:|:---:| | 阅读统计概览 | 阅读回执锁屏 | | 远程管理 | 文件管理 | |:---:|:---:| | 远程管理首页 | 远程文件管理 | ## 增强了什么 ### 1. 用完整书库桌面替代文件夹式找书 月读提供由首页、图书馆、书城、统计和设置组成的全屏桌面。底栏的「Z站」「OPDS」在启用对应书城后出现，「订阅」「拓展」在设置里打开后出现，统计按当前数据源能力出现。 - **首页组件：** 当前阅读、最近阅读列表、最近阅读卡片、时钟、天气预报、每小时天气预报、时间天气、阅读统计、阅读小卡（连续阅读、近 7 天、本月挑战、今年读完）、阅读热力图、一言、书摘（居中、竖线、引号三种样式）、历史上的今天和热点新闻。组件可添加、移动、调整高度；第三方书源也能追加自己的组件。 - **图书馆：** 使用本地 SQLite 索引，顶部按书籍、作者、系列、分类分页签浏览；书籍页可在封面网格与列表间切换，工具条带排序（最近添加、最近阅读、书名、作者）与筛选（未读、已读、已下载，混合模式再加数据源）下拉，支持关键词搜索。 - **顶栏：** 时钟、当前数据源、后台任务、剩余内存、剩余存储、Wi-Fi、蓝牙（有可用蓝牙后端时出现，紧挨 Wi-Fi）、亮度、电池；各项可单独开关。 - **后台任务：** 书城下载、全本缓存、书架同步、词典与词库下载、X-Ray 提取等耗时操作进入后台队列；顶栏显示进行中 / 未结束数量，点开可查看、取消任务。断网或休眠时可续跑的任务会自动等待，恢复后继续。 - **书籍详情：** 左侧大封面，右侧书名、作者、出版信息、评分与字数，下接「开始 / 继续阅读」与进度；中间一排阅读指标（累计时长、已读页数、上次阅读、预计读完），点开看完整阅读记录；再往下是简介与书籍信息。编辑、刮削、下载、清理缓存、已读、删除等当前数据源允许的操作收在右上角「⋯」菜单。按章阅读的书可选择缓存范围（全本、从当前进度到结尾、往后 10 / 20 / 50 / 100 章）；已完整离线的在线书可单独「清理缓存」，保留元数据、进度和笔记。 - **订阅：** 设置里启用「订阅」后，底栏「图书馆」旁出现「订阅」页，可订阅 RSS / Atom、网站里的文章链接、网页本身（内容变了出新条目）和微信读书公众号，一个订阅是一本书、一篇文章是一章，用月读按章阅读打开（不记进度与统计）；可选下载文章图片，也能经远程管理网页批量添加。公众号文章不进书库。 - **底栏拓展：** 把其它 KOReader 插件的主菜单入口集中放进底栏「拓展」格，可逐个选择显示哪些。 - 桌面字号、界面缩放和封面网格列数均可调整，布局面向墨水屏和触控操作；弹出面板和菜单时可用网点「背景遮罩」压暗背景（默认开）。 - **自动夜间模式：** 按固定时间或当地日出日落切换；只在昼夜交替那一刻切换，中途手动切换不会被立刻改回。日出日落离线计算，经纬度在选择该模式时经天气接口定位一次。 - **自动亮度：** 有光线传感器的 Kindle 按环境光档位调节；其他设备按八个时段的亮度表调节，白天再按天气（阴雨雾雪）适当补光。手动调亮度即关闭自动亮度，桌面快捷面板也有开关。

首页天气与阅读热力图组件

### 2. 把不同来源的书统一为可靠的书籍身份 月读内置本地书籍（含 WebDAV）、月读服务、微信读书、京东读书、拷贝漫画、番茄小说、七猫小说、开源阅读（Legado）、晋江文学城、起点中文网、QQ阅读、iRead、长佩文学和潇湘书院十四个数据源（越狱 Kindle 上满足条件时另有「Kindle 书库」），另可安装 Kavita、BookOrbit 等第三方书源插件（见[数据源](#数据源)）。每本书按“数据源 + 稳定 ID”隔离，阅读时继续使用该书所属的数据源，不会因为用户切换当前数据源而把进度、笔记或统计串到另一本书。 - 同一时间只有一个活跃数据源，其他来源可单独启用或隐藏；也可选择“混合模式”，让书库、首页和统计跨已启用的来源展示（阅读仍按书所属的来源）。 - 书架查询统一读取本地数据库，网络同步在后台收敛，打开桌面不必等待远端返回。 - 所有操作先在本地生效；离线时写库并标记待同步，联网、唤醒后自动补推，删除也是先本地标删、远端确认后才真正清理。 - 本地整本文件与在线来源的按章内容走同一套书籍详情、阅读会话和统计界面。 - 章节文件通过物理路径精确登记；`.moon` 内的孤立章节不会被误认为普通本地书籍。 - 微信读书使用墨水屏客户端扫码登录，会话过期自动续期；书架分类优先用你自建的分组名（多个分组取第一个），没分组才回退官方分类；京东读书目录分页拉取，支持 EPUB、会员书和 TXT 网文，无下载权限时明确报错。 - 七猫、晋江、起点、潇湘验证码或风控在墨水屏上做不了，登录态走「远程管理 → 浏览器登录」（配合浏览器扩展 moon-cookie-storage 把网页登录态交给设备），也可粘贴 token / Cookie；京东读书同样支持浏览器登录，已授权的源不再重复授权。QQ阅读用阅文 App 扫码登录；长佩支持扫码、浏览器授权和 Cookie 登录，token 过期时用 refresh_token 自动续期。 - 本地源 WebDAV 模式提供「测试 WebDAV 连接」：写入、读回并删除一个测试文件，确认可读写。 ### 3. 阅读进度、笔记和统计形成闭环 - 自动记录阅读页数、时长和会话统计，不依赖 KOReader 自带统计插件；也可在维护页一次性导入 KOReader 自带统计插件的历史记录（按书匹配书库，已有的记录不会重复导入）。 - 支持按数据源同步书架、进度、划线/笔记和阅读统计；微信读书可选择把本地离线阅读时长合并上报。Kavita 的阅读统计以云端 reading-history 为准，云端条目的日期与时段按设备本机时区换算，不依赖服务端时区设置。 - 本地与云端进度相差至少 1% 时显示冲突对话框，由用户选择跳到云端位置或保留本地位置；选择本地进度后会立即上推，使两端重新一致。阅读快捷面板也可手动推送 / 拉取进度。 - 关闭文档、休眠和网络恢复时会结清或重试待同步数据。 - 手动标为已读、但没有章节信息的按章书（如微信读书），进度按最后一章读完上报；实在推不上的记录直接丢弃，不反复重试，单本失败也不影响其它书的进度同步。 - 统计页提供概览、今日总览、连续记录和阅读时段（一天中各时段的阅读分布）；首页可放阅读热力图，书籍详情显示预计读完日期。微信读书数据还可按周查看阅读书目。 | 今日总览 | 连续记录 | 阅读时段 | |:---:|:---:|:---:| | 今日阅读总览 | 年度阅读与连续记录 | 阅读时段分布 | ### 4. 增强阅读页，而不复制 KOReader - **阅读快捷面板：** 在 KOReader 原生顶部菜单中增加“月读”Tab，放目录、阅读字体、高亮与笔记、推送 / 拉取进度、优化排版、双语对照、X-Ray、AI 问书 / 回顾前文 / 读书报告、关联微信段评和翻页动画风格等动作；可启停、排序，不适用当前书或设备的动作自动隐藏。 - **阅读页顶栏 / 底栏：** 章节、书名、时钟、电池、剩余运存、Wi-Fi、亮度、页码、进度、章节序号、章内页码、剩余时间和进度条，可自由摆放到顶栏或底栏、靠左或靠右；顶栏、底栏各有「分割线」开关，在栏与正文之间画一条细线。 - **阅读侧栏：** 左缘右滑（或任意位置右滑、或在 KOReader 手势管理里绑定任意手势）打开，含书籍、目录、阅读字体、书摘、X-Ray、阅读票根和统计页（统计页需开启 KOReader 阅读统计），可选显示哪些页面并自定义页面顺序。 - **划词菜单：** 选择、高亮、复制、笔记、百度百科、词典、翻译、X-Ray、AI 解释、查看 HTML、二维码和搜索；可启停、排序，其它插件挂进来的按钮也会被识别、标明来源并可逐个屏蔽。 - 阅读字体可从插件字体或系统字体中快速切换；「中西文字体分开」默认关闭，可在「设置 → 阅读行为」开启，重新打开书籍生效。关闭时，阅读侧栏和下滑阅读菜单都直接显示普通阅读字体选择器；开启后，两处入口都可分别选择中文字体和西文字体，西文默认 Bookerly（设备没有时用 Noto Serif），阅读行为页不另设西文字体入口。西文选择全局保存、当前书自动重载；阅读面板可把当前排版和字体「保存为默认配置」供新书使用；书籍内嵌字体默认关闭（省内存）；章节书的字体与排版偏好会自动应用到后续章节文件；微信读书 WOFF 字体会解包为 TTF/OTF，避免多字号实例把内存撑爆。 - 章节模式支持自动上一章/下一章、后续章节预取和按范围缓存；「高亮与笔记」显示全书笔记列表，按章节汇总所有章的划线和笔记，点击跨章跳转。 - 整本打开没有目录的 TXT / EPUB 时自动补目录：先用 h1–h6 生成备用目录，不足再后台扫描章节标题写入自定义目录；每本书只自动处理一次。 - 原生支持 AZW3（KF8）文档。 - 读完后提供返回主页或删除本书的结束操作。 - 可启用翻页动画补丁，提供擦除、翻页阴影、百叶窗、螺旋、时钟、棋盘等 14 种风格；开关需重启，切换风格下一次翻页即生效。 | 阅读快捷面板 | 阅读侧栏 | |:---:|:---:| | 阅读快捷面板 | 阅读侧栏书籍页 | | 划词工具栏 | 查词窗口 · 词典 | 查词窗口 · 翻译 | |:---:|:---:|:---:| | 可排序的划词工具栏 | 查词窗口词典标签，显示 HTML 词条 | 查词窗口翻译标签 | | 查词窗口 · 百科 | 生僻字注音 | |:---:|:---:| | 查词窗口百科标签 | 生僻字上方标注拼音 | | 章节目录 | 阅读字体 | |:---:|:---:| | 侧栏章节目录 | 侧栏阅读字体选择 | ### 5. 增加真正用于阅读的内容工具 - **AI 解释：** 划词后让 AI 结合所在句子和段落解释，只出纯文本；结果可继续追问，也可直接存为笔记。 - **问书：** 不用划词，直接就已读部分向 AI 提问。 - **章节摘要与前情提要：** 顺着读完一章后在后台生成摘要（默认关，会消耗 API 额度）；隔 3 天以上再打开这本书时弹出最近几章的前情提要，也可在快捷面板「回顾前文」随时查看（离线可用）。 - **读书报告：** 汇总章节摘要、划线笔记和阅读统计，让 AI 写一页读后总结，可重新生成。 - **X-Ray：** 使用 AI 从原文提取人物、地点和专有名词，保存实体说明，并可在正文中画线标记和划词查询；全书提取和「按当前位置更新」在后台任务里运行，可取消。 - **统一查词窗口：** 划词后点词典、翻译或 AI 解释（以及长按查词、点生僻字注音），都在同一个居中窗口里打开；底部「词典 / 翻译 / AI / 百科」四个标签随时切换，不用重新选字。词典标签可点词典名手动切换词典，网页格式（HTML）的词条按排版显示；翻译标签可切换源语言和目标语言；结果可复制或存为笔记，AI 结果还能追问。 - **翻译：** 接入 Microsoft Edge 翻译，支持配置常用目标语言。 - **生僻字注音：** 在生僻字上方标拼音（英文生词标音标），全书注音字号统一。注音范围、字号可调，词库在线下载，中文只收《通用规范汉字表》8105 字。 - **整书双语对照：** 用 Edge 或 AI 逐段翻译整本书，在每段原文下方插入译文（按章阅读的书源也支持）；生成在后台进行，可中断续跑。双语版与原书是同一本书，进度、笔记和统计共用，可随时切回原文。 - **段评：** 微信读书的书在正文中标出他人段评较多的句子，点按查看。导入的本地书可手动关联微信读书书目；京东读书的书自动借用微信读书同一本书的正版段评（需登录微信读书）。只在本章没有自己的段评时才借用。 - **百科：** 用百度百科替换原生 Wikipedia 入口，更适合中文内容；划词菜单的「百度百科」也在统一查词窗口的百科标签里打开。 - **文字识别（OCR）：** 为 KOReader 内置的 Tesseract 下载识别语言（简体/繁体中文、英语、日语及中文竖排），扫描版 PDF / DjVu 上长按文字即可识别，结果直接进入划词菜单（复制、翻译、AI 等）；可设默认识别语言，也可开启强制文字识别。 - **词典：** 提供 StarDict 词典下载、启停和管理，并接管阅读器中的词典入口；「加载所有词典」（默认开）让查词面板列出全部已安装词典，无论是否启用、有无结果，都可手动切换。 - **脚注：** 设置 → 阅读行为 →「脚注弹窗」。开＝点按弹窗且不在页底；关＝注文显示在页面底部（与 KOReader 页内 EPUB 脚注互斥联动）。 - **优化排版：** 取出整本书的文字（TXT 直接读文件；EPUB、MOBI、PDF、DjVu 等能取出文字层的格式逐页提取），预览识别出的章节后重新生成 EPUB。排版版另存在缓存目录，原书不动；两版之间可随时切换，划线按文字互相定位。 - **截图分享：** KOReader 保存截图后，可启动远程管理并显示二维码，让同一局域网内的设备下载图片；可选「截图分享后自动删除」（默认关），图片被完整下载后删除，中途断开不删。 AI 功能使用兼容 `/chat/completions` 的接口，需要配置接口地址、API 密钥和模型；设置页提供最小请求的连接测试。未配置 AI 时相关入口不出现。 | 查词窗口 · AI | X-Ray 实体详情 | |:---:|:---:| | 查词窗口 AI 标签 | X-Ray 实体详情 | ### 6. 把锁屏变成可组合的信息页 月读可以继续使用 KOReader 原生锁屏，也可以生成“背景 × 主体 × 位置”的组合锁屏图片。 - 背景：无、当前阅读书籍封面、自定义图片、壁纸文件夹（按日期轮换）、必应壁纸、摸鱼日报、海报墙、文字海报和单向历；自定义图片与壁纸文件夹可在设置页直接选择。 - **文字海报：** 从你的划线里挑一句，自动分词找关键词，排成文字海报；版式有横排标题、竖排、巨字铺底、散落关键词、拼贴海报，默认随机；「海报字体」可选自动（优先宋体）或任意字体。 - **单向历：** 本地绘制的日历页：大号日期、英文月份与星期、农历月日、干支生肖和节气 / 节日（读摸鱼日报的当天缓存，没有缓存时不画农历），再配一句你的划线，每天换一句。 - 主体：当前阅读、阅读统计、阅读票根、阅读账单、阅读高亮、一言、自定义留言、胶囊卡片和极简。 - 普通主体支持九宫格位置与宽/窄布局；统计和全屏主体按内容选择合适布局。 - 阅读统计可展示累计时长、进度和近 7 日图表；阅读账单支持今日、近 7 天、近 30 天和本月周期。 - 锁屏图先在后台完整生成，再替换显示文件；生成失败时保留上一张可用图片。 - 海报墙里没下载过封面的网络书，联网时会在后台自动补齐封面并刷新锁屏。 - **锁屏密码：** 设置 4～6 位数字密码后，冷启动和每次唤醒都要先输入密码；连续输错会冷却。这只是隐私遮挡，不是加密，忘记密码时删除 `.moon/settings/passcode.lua` 即可解除。 | 当前阅读 × 必应壁纸 | 阅读统计 × 书籍封面 | 当前阅读 × 海报墙 | |:---:|:---:|:---:| | 当前阅读锁屏 | 阅读统计锁屏 | 海报墙锁屏 | | 文字海报 | 单向历 | |:---:|:---:| | 文字海报锁屏 | 单向历锁屏 | ### 7. 改善墨水屏上的中文输入 - 在 KOReader `zh_CN` 虚拟键盘首行加入中文候选栏。 - 支持拼音（含九宫格拼音）、小鹤双拼、五笔 86、仓颉五代、速成和台湾注音；小鹤双拼与拼音共用词库，速成与仓颉共用词库（取首尾码），仓颉与注音会同步改写键帽显示。 - 候选词可保持原样、转简体或转繁体。 - 支持连续编码、候选翻页和直接点选，输入码不会交给 KOReader 原生 IME。 - 词库使用本地 SQLite 查询，设备端无需常驻输入法服务。 - 大词库采用分片下载、逐片校验、断点续传和最终拼接校验；在线下载不便时，可从 GitHub Release 下载已使用最终名称的词库文件，直接放入 `.moon/`。 - 非中文布局、数字输入框、词库缺失以及物理键盘输入保持 KOReader 原生行为。

设置首页

### 8. 从电脑或手机管理阅读器 启用远程管理后，同一局域网中的浏览器可访问以下功能： - **文件管理：** 资源管理器式浏览、拖拽上传、上传队列（进度、取消、重试）、下载、新建目录、重命名、复制 / 剪切 / 粘贴、属性、递归删除、右键菜单与快捷键；图片和音视频预览，文本文件可直接编辑（搜索替换、编码、换行符）。上传同名文件直接覆盖；复制、移动遇到同名时可选保留两份、替换或跳过。ZIP 可在设备端解压到同名文件夹，并检查危险路径和异常归档。 - **远程输入：** 阅读器输入框激活时，从浏览器一次发送整段文字。 - **共享剪贴板：** 在浏览器与阅读器之间读取、写入和复制文本。 - **远程配置：** 在电脑上填写 AI、月读服务和 Z-Library 等不适合用墨水屏键盘输入的配置。 - **备份与恢复：** 在远程管理首页下载 `moon-backup-日期.zip`，把整个 `.moon` 数据目录（书库、笔记、进度、统计、全部配置、锁屏资源、词库）打包，不含日志和缓存；配置里有各书源登录信息、Cookie、令牌、API Key、WebDAV 密码和锁屏密码，备份文件等同账号凭据，请妥善保管。上传备份后设备先整包解到临时目录、校验通过才整体替换，随后自动重启 KOReader。 - **月读更新：** 上传 `book.koplugin-*.zip` 发布包，设备自动安装并重启 KOReader。 - **下载日志：** 首页一键打包插件日志和 KOReader 崩溃日志（已脱敏），反馈问题时附上。 - **生命周期：** 可配置端口、开机自启和空闲自动关闭；设备休眠时停止服务，唤醒后按配置恢复（设了锁屏密码时等解锁后才启动）。 远程管理是设备内运行的轻量 HTTP 服务，不依赖云端中转；页面截图见[界面预览](#界面预览)。 ### 9. 其它系统增强 - **时间与日期：** 设置时区（KOReader 本身没有时区设置）、手动修改系统时间；进入桌面时自动经 NTP 校时（最多每 6 小时一次，偏差 1 秒以上才改）。设备不支持改时间时只显示时区。 - **蓝牙：** 在桌面快捷面板开关蓝牙、扫描配对、连接 / 断开设备，顶栏显示状态（已连一台显示名字，多台显示台数）。后端按下面顺序取第一个可用的，没有可用后端时这些入口都不出现： - **kindle-hid-passthrough 守护进程**（[zampierilucas/kindle-hid-passthrough](https://github.com/zampierilucas/kindle-hid-passthrough)）：Kindle，通用 HID 设备（手柄、键盘等）；它会接管蓝牙芯片，装了就优先用它。 - **Kindle 原生蓝牙**（btfd，经 lipc）：国产蓝牙翻页器（伪装成 Kindle Click）走这条，不用装守护进程。 - **Kobo 系统蓝牙**：i.MX6 机型走 hciattach / bluetoothctl，需已装 [bluetooth.koplugin](https://github.com/onatbas/bluetooth.koplugin) 自带的 uhid.ko；MTK 机型走系统 D-Bus；连上后自动接入输入设备。 - **Android**：蓝牙在系统里，KOReader 没有接口，请在系统设置里连接。 - 系统蓝牙后端尚未在真机充分验证，遇到问题请反馈。 - **翻页器：** 蓝牙只管连上，把翻页器接成翻页键、录手势、用它选想法，由独立插件[翻页器 pageturner](https://github.com/AnkioTomas/ko-pageturner)负责（可选，见[翻页器（可选）](#翻页器可选)）。 - **网络超时：** 「网络」页可设普通请求的默认超时（默认 30 秒，5～300 秒），下载等请求按倍率放大；AI 请求单独用「AI 接口」页的「AI 请求超时」（默认 120 秒，10～600 秒）。 - **HTTP 代理：** 与 KOReader 原生「HTTP 代理」是同一份设置，月读的网络请求也会走代理；只支持 `http://` 代理，HTTPS 请求经隧道转发，保存前会经代理实测一次。 - **在线更新：** 检查 GitHub Release，直连与公益镜像竞速下载，只信任 GitHub 给出的 SHA-256；自动检查每天最多一次，只提示不自动安装。词典、词库、OCR 等资源下载也会在多个镜像间自动切换，优先用上次成功的源。 ### 10. 游戏 读累了可以玩两把。游戏都是独立的 KOReader 插件，不装月读也能从「工具」菜单玩；装了月读后会多出入口。完整说明见[官网文档：游戏](https://moon.ankio.net/manual/library/games)。 - **小黑屋**（[ko-adarkroom](https://github.com/AnkioTomas/ko-adarkroom)）：《A Dark Room》的完整 Lua 中文移植，从生火开始，建村、远征、战斗、登上星舰直到结局，可带声望重开。自动存档，远征中途关掉也能续上。 - **阿页的阁楼**（[ko-paper-sprite](https://github.com/AnkioTomas/ko-paper-sprite)）：书签变成的小纸灵「阿页」按真实时间自己出门旅行，寄回黑白明信片、带回特产；读书翻页攒灵感去小铺换东西，没有失败惩罚。月读里配置了 AI 时，明信片文案可由 AI 现写。 - **游戏合集**（[ko-games](https://github.com/AnkioTomas/ko-games)）：一个 `games.koplugin` 内含 22 个离线小游戏，界面全部用 SVG 素材绘制，适合墨水屏，支持简体 / 繁体 / English。益智（2048、扫雷、数独、华容道、数织、汉诺塔、记忆翻牌、24 点、猜数字、推箱子）、棋类人机对战（中国象棋、国际象棋、围棋 9×9、跳棋、五子棋、四子棋、黑白棋）、纸牌（Klondike、空当接龙、蜘蛛纸牌）和实时类（俄罗斯方块、贪吃蛇）。每个游戏有玩法说明，难度、大小等在右上角设置里改；长按大厅里的图钉可置顶游戏。 - **在月读里的入口：** 首页组件（小黑屋存档卡片；阿页的状态卡、阁楼、明信片、纪念物柜；游戏合集的置顶游戏卡片和「更多」）和桌面快捷面板开关，点一下全屏打开。 - **存档：** `.moon/game/adarkroom/save.lua`、`.moon/game/paper-sprite/`、`.moon/game/kogames/save.lua`，KOReader 菜单和月读两边共用同一份。安装见[游戏（可选）](#游戏可选)。 ## 完整功能 ### 书库与书籍管理 - 首页组件添加、移动、调整高度和多种最近阅读布局。 - 本地 SQLite 书籍索引、最近阅读、搜索、分类、系列和分页。 - 本地目录或 WebDAV 后台扫描、失效条目清理和文件改名后的身份迁移；遇到没有权限的目录只记日志并跳过，其中已入库的书保留、不会误删；有目录被跳过时本次 WebDAV 同步自动中止；扫描不跟随软链接。 - WebDAV 同步时会把本地有、远端没有的书上传到同一相对路径（远端目录缺失时自动创建）；上传超时或断网后本轮不再继续，失败的书 1 小时内不自动重传。 - 本地书籍分类/系列编辑；目录层级随编辑结果实际移动，移动或身份更新失败时文件回滚到原位。 - 本地书籍刮削：书名一行加候选来源列表（豆瓣、微信读书、七猫、晋江、起点、番茄、长佩、潇湘），搜不到可依次换源重搜；应用前弹出修改预览，可逐行取消。 - 书库页签可多选显示哪些分组，本地书库另有「文件夹」页签，按目录浏览（含未下载的 WebDAV 书）。 - 封面、正文、章节、目录和 HTTP 响应缓存；缓存体积统计、手动清理和后台失效清理。 - 后台任务列表：书籍下载、章节缓存、书架同步和资源下载的进度与取消。 - 图书馆「已下载」筛选；书籍详情单书清理缓存（与「下载」互斥，后台缓存中的书拒绝清理）。 - 删除本地原书，或删除在线来源的云端书架/原书并清理设备上的缓存与登记；离线时先本地标删，联网后再同步到远端。 - 本地扫描格式：PDF、EPUB、DJVU、MOBI、AZW、AZW3、CBZ、CBT、DOCX、RTF、HTML、TXT、XPS、FB2、PDB、CHM 和 Markdown。带 DRM 的 MOBI / AZW / AZW3 会跳过（越狱 Kindle 上由 Kindle 书库列出）。 ### 书城 - **Z-Library：** 在「账号」里启用后，底栏出现「Z站」。支持账号登录、多镜像种子、30x 跳转、挑战页检测和镜像故障转移。 - **OPDS：** 启用后底栏出现「OPDS」。填写一个 OPDS 目录地址（用户名、密码可选），支持 OPDS 1.x（Atom）与 2.0（JSON），下载时按格式择优。 - 下载在后台任务中进行，完成后加入本地书库。 ### 阅读与同步 - 整本文件与按章阅读两种模式。 - 书架、进度、笔记/划线和统计按来源独立同步；网络失败后的待同步数据持久化并自动重试。 - 微信读书扫码登录、书架同步、目录缓存、章节原样渲染（资源本地化、脚注可点击弹出）、章节预取、全本缓存、笔记同步和阅读时长上报。 - 阅读页顶栏 / 底栏、左侧栏、快捷面板、可排序划词菜单、阅读结束对话框和翻页动画。 - 双语版、排版版与原书是同一本书：进度、统计共用；划线只在原书坐标存一份，读衍生版时按文字定位显示，衍生版里新划的线会收回原书。 ### 快捷面板 - **桌面动作：** 夜间模式、Wi-Fi、远程管理、旋转、刷新、截图、前光、自动亮度、休眠、电源菜单（退出月读、退出 KOReader、重启、重启设备，设备不支持的项不显示），以及有可用蓝牙后端时的蓝牙开关与蓝牙设备。 - **阅读动作：** 目录、阅读字体、高亮与笔记、推送进度、拉取进度、优化排版、双语对照、X-Ray、刷新 X-Ray、回顾前文、读书报告、问书、关联微信段评、翻页动画风格（仅开启翻页动画时显示），以及装了 BookOrbit 官方插件时的「同步到 BookOrbit」。 - 桌面与阅读动作分别注入 KOReader 原生顶部菜单；各动作按设备能力和当前书显示，并可启停和调整顺序。 ### 国际化 - 简体中文为源语言。 - 提供繁体中文和英文界面资源。 - 语言切换复用 KOReader 原生语言菜单。 ## 数据源 下面这张表按源实现核对，不是按「模块里有没有这个函数」。不支持的域是 `—`，不会假装同步成功。 读法： - **书架。** `双向`：拉取，本地加入和删除都上行。`拉+删`：能拉、能删，不能从月读加架。`只拉`：没有远端删除接口，本地删除只在月读里隐藏，下次同步不会把书捞回来。 - **进度**都是双向。`页`是页码或 xpointer，`章`只到章节，`章+章内`还有章内位置。 - **笔记** `只推`：不拉远端改动，也不根据上传推断删除。 - **统计**列只看和远端同步。每个源都会在本地记阅读时长。 - **书城**是搜索加榜单，出现在书城页。按章源都能预取，并按范围缓存。 - **段评**默认关。 - **协议**是书架和正文实际走的接口，不是登录方式。`官方 App` 是对方客户端接口；`网页` 是官网或手机站；`自建 API` 是你填地址的 HTTP 服务（月读、iRead、开源阅读、Kavita）；`kosync` 是 KOReader 同步协议。 | 数据源 | 协议 | 形态 | 书架 | 进度 | 笔记 | 统计 | 书城 | 段评 | |---|---|---|---|---|---|---|---|---| | 本地书籍（目录） | 本地文件 | 整本 | 扫盘 | — | — | — | — | — | | 本地书籍（WebDAV） | WebDAV | 整本 | 文件双向 | 页 | 双向 | 双向 | — | — | | Kindle 书库 | 系统库 | 整本 | 只拉 | — | — | — | — | — | | 月读服务 | 自建 API | 整本 | 拉+删 | 页 | 双向 | 双向 | — | — | | 微信读书 | 官方 App | 按章 | 双向 | 章+章内 | 双向 | 双向 | ✓ | 自有 | | 京东读书 | 官方 App | 按章 | 双向 | 章 | — | — | ✓ | 借用微信 | | 拷贝漫画 | 官方 App | 按章（CBZ） | 拉+删 | 章 | — | — | ✓ | — | | 番茄小说 | App+网页 | 按章 | 双向 | 章 | — | — | ✓ | 自有 | | 七猫小说 | App+网页 | 按章 | 双向 | 章 | — | — | ✓ | — | | 晋江文学城 | App+网页 | 按章 | 拉+删 | — | — | — | ✓ | 自有 | | 起点中文网 | 网页 | 按章 | 双向 | 章 | — | — | ✓ | 自有 | | 开源阅读（Legado） | 自建 API（阅读 App / reader3 / 轻阅读） | 按章 | 拉+删 | 章 | — | — | — | — | | QQ阅读 | 网页 | 按章 | 双向 | 章 | — | — | ✓ | — | | iRead | 自建 API | 按章 | 双向 | 章 | — | — | ✓ | — | | 长佩文学 | 网页 | 按章 | 双向 | 章 | — | — | ✓ | — | | 潇湘书院 | 网页 | 按章 | 双向 | 章 | — | — | ✓ | — | | Kavita（拓展） | 自建 API | 整本 | 只拉 | 页 | 双向 | 只拉 | — | — | | BookOrbit（拓展） | kosync | 整本 | 只拉 | 页 | 只推 | — | — | — | 例外： - 本地书籍可编辑、刮削元数据。目录模式删除会删原文件。WebDAV 还会把书目和封面上行；进度、笔记、统计只在 WebDAV 模式有。 - Kindle 书库只在越狱设备（有 `/var/local/cc.db`）且装了 kindle.koplugin 时出现。列出 KFX 和带 DRM 的 MOBI 族，打开交给 kindle.koplugin 转换。删除不碰系统书库。 - 月读服务没有加书接口。 - 微信读书的书架、进度、笔记和统计走 Eink App，书城搜索和榜单走网页。改分类会写成书架分组。书名和作者改完只留在本地，下次书架同步会被远端盖掉。 - 京东进度恢复到章首。段评借用微信读书同一本书，只在本章没有自己的段评时借，需登录微信读书。 - 番茄正文走 App，书架走网页。搜索免登录。章内进度能推，回读常被服务端截成章首，所以表上只算到章。漫画章落成 CBZ。 - 七猫正文走匿名 App，不登录也能下；书架走网页，要登录。 - 晋江免费章走 App，收藏和已购 VIP 章走手机网页。晋江、拷贝漫画、开源阅读不能从月读把书加到远端。晋江没有能写回的进度接口，所以不接进度；已购 VIP 章会解密。 - 起点、QQ阅读、长佩、潇湘：未购 VIP 章打开是临时提示，目录标已购或未购。 - 长佩书架不同步分组里的书。长佩和潇湘不登录也能读免费章。 - iRead 从月读加架要先搜到这本书。 - QQ阅读的书不在书架上时不推进度，也不会为了推进度把书加回去。 - Kavita 没有删书接口。时长靠阅读期进度心跳记在服务端（默认 30 秒，可关），月读只拉统计。划线双向：本地新建和改备注会推上去，远端的改动与删除也会拉回本地。装了 [kamare](https://github.com/backtracker/kamare.koplugin) 且在线时，漫画交它看；增强版还能在「设置 → 数据源 → Kavita → 漫画缓存」里清理已读、按系列清理和全部清理（含未关联服务器的缓存）。 - BookOrbit 没有删书接口。划线只上传，网页上的改动和删除不会回到本地。 订阅不是书源，不进选择器，也不记进度和统计。Z-Library 与 OPDS 是书城，下载后进本地书籍，见[书城](#书城)。 | 数据源 | 配置 | |---|---| | 本地书籍 | 书籍根目录，或 WebDAV 地址 / 用户名 / 密码 / 目录 | | Kindle 书库 | 满足上面的条件时自动出现 | | 月读服务 | 服务地址与令牌 | | 微信读书 | 微信扫码 | | 京东读书 | 京东 App 扫码（跳到安全验证时，按手机提示完成后重新扫码） | | 拷贝漫画 | 站点地址与账号 | | 番茄小说 | 扫码或 Cookie | | 七猫小说 | 远程管理「浏览器登录」，或粘贴 token | | 晋江文学城 | 远程管理「浏览器登录」，或粘贴 Cookie | | 起点中文网 | 远程管理「浏览器登录」，或粘贴 Cookie | | 开源阅读 | 阅读 App 的 Web 服务局域网地址 | | QQ阅读 | 阅文 App（QQ阅读或起点）扫码，或浏览器登录 / Cookie | | iRead | 个人 Token | | 长佩文学 | 扫码 / 浏览器授权 / Cookie；不登录可读免费章 | | 潇湘书院 | 远程管理「浏览器登录」，或粘贴 Cookie；不登录可读免费章 | | Kavita | 安装拓展插件，填写服务器地址与 API Key，选择书库（0.9 及以上） | | BookOrbit | 安装拓展插件，填写服务器地址与 BookOrbit 里创建的 KOReader 同步账号；可导入官方插件的账号 | 月读服务端项目见 [AnkioTomas/book](https://github.com/AnkioTomas/book)。自己写书源可参考示例 [`examples/moonsource-demo.koplugin/`](examples/moonsource-demo.koplugin/)，契约写在它的 `moon_source.lua` 头注释里。 功能入口按当前数据源能力显示。未登录或未配置的在线源不能同步远端内容。 ## 安装 ### 从 Release 安装 1. 从 [GitHub Releases](https://github.com/AnkioTomas/moon/releases) 下载最新插件压缩包。 2. 解压后确认得到完整的 `book.koplugin/` 目录。 3. 将该目录复制到 KOReader 数据目录的 `plugins/`： ```text /plugins/book.koplugin ``` 4. 重启 KOReader。 5. 从主菜单打开 **月读**。 之后的版本可在 **设置 → 维护 → 检查更新** 在线升级，或通过远程管理上传发布包。 > Android 上旧版本首页报 `strncasecmp` 错误、微信读书 / 番茄小说获取二维码失败的问题已在 v0.2.8 修复，请升级。 > 起点 VIP 章节解密改在子进程里运行并关闭 JIT，修复 Kindle 上通过目录跨章跳转时 KOReader 崩溃重启的问题（v0.2.13）。 ### Kavita / BookOrbit Kavita（漫画缓存由 [kamare](https://github.com/backtracker/kamare.koplugin) 增强版提供）与 BookOrbit 已内置在 `book.koplugin/` 里，和其它数据源一样在月读的数据源里选择、可开关，不再需要单独安装。 ### 翻页器（可选） [翻页器 pageturner](https://github.com/AnkioTomas/ko-pageturner)（`pageturner.koplugin`）是月读的联动插件，从它的 [Release](https://github.com/AnkioTomas/ko-pageturner/releases) 下载，把解压出的 `pageturner.koplugin/` 放进 `plugins/`，重启 KOReader。没装月读也能单独用，装了会联动： - **蓝牙联动：** 月读里开蓝牙就自动接管翻页器并连上，翻页器重连后自动重新接管，连着时不息屏；没装月读时每 10 秒轮询一次。 - **设置页：** 月读 **设置 → 阅读 → 翻页器** 里录「下一个 / 上一个 / 确认」手势（单击、连按 2~3 下、长按）。 - **想法选择器：** 用翻页器选中并打开当前页的想法，段评来自月读，没装月读时只有自己带笔记的划线可选。 - **设备：** Kindle 配合 kindle-hid-passthrough 或 Kindle 原生蓝牙；Kobo 路径尚未在真机验证。Android 和桌面版不适用。 ### 游戏（可选） 三个独立的离线游戏插件，从各自仓库的 Release 下载，解压后把 `*.koplugin/` 放进 `plugins/`，重启 KOReader： | 游戏 | 插件包 | |---|---| | 小黑屋（《A Dark Room》中文移植） | [`adarkroom.koplugin.zip`](https://github.com/AnkioTomas/ko-adarkroom/releases) | | 阿页的阁楼（书签纸灵养成） | [`paper-sprite.koplugin.zip`](https://github.com/AnkioTomas/ko-paper-sprite/releases) | | 游戏合集（22 个益智 / 棋牌 / 实时小游戏） | [`games.koplugin-*.zip`](https://github.com/AnkioTomas/ko-games/releases) | 用法见[增强了什么](#10-游戏)。 ### 从源码安装 直接复制仓库中的 `book.koplugin/`。`tests/`、`assets/`、`koreader/` 等目录不是插件交付物，不需要复制到设备。 > **注意：** 插件目录名必须是 `book.koplugin`，不能改成 `book`，也不能多套一层仓库目录。 ## 快速开始 ### 本地书籍 1. 打开 **月读 → 设置 → 账号 → 本地**。 2. 选择书籍根目录（Kindle 上建议在 `documents` 里新建一个子文件夹放书；直接选 `documents` 时会弹提示，可点「重新选择」或「仍然使用」）（或填写 WebDAV 地址、用户名、密码和目录，再点「测试 WebDAV 连接」确认可读写）。 3. 在 **设置 → 当前书库** 切换为 **本地书籍**。 4. 返回首页；月读会在后台扫描，并把索引写入本地 SQLite。 本地源不需要账号或服务器。一级目录作为分类，二级目录可作为系列；在详情页修改分类或系列时，月读会移动实际文件并同步更新身份。 ### 月读服务 1. 打开 **设置 → 账号 → 月读服务 → 服务器与令牌**。 2. 填写服务地址和令牌。 3. 在 **设置 → 当前书库** 切换到 **月读服务**；打开桌面会在后台同步书架，也可在图书馆点刷新强制同步。 ### 微信读书 1. 打开 **设置 → 账号 → 微信读书 → 微信扫码登录**。 2. 使用微信扫码登录，并在 **当前书库** 里切换到微信读书。 3. 打开桌面后台同步书架。 4. 打开书籍后按章阅读；目录和后续章节会按需缓存。 ### AI 阅读助手 1. 打开 **设置 → AI 接口**，填写兼容 `/chat/completions` 的接口地址、API 密钥和模型，点连接测试。 2. 阅读时划词选「AI 解释」，或在阅读快捷面板用「问书」「读书报告」「回顾前文」。 3. 需要章节摘要和前情提要时，在 **AI 接口 → 阅读助手** 里打开（会消耗 API 额度）。 ### 中文输入 1. 打开 **设置 → 中文输入法增强**。 2. 选择键盘布局，并下载该布局的独立词库。 3. 在 KOReader 虚拟键盘上点 `🌐` 切换到中文布局。 ### 远程管理 1. 让阅读器和电脑/手机连接同一可信 Wi-Fi。 2. 打开 **设置 → 远程管理 → 远程管理服务**。 3. 在浏览器访问界面显示的地址，例如 `http://192.168.1.10:9528/`。 ## 数据与安全 ### 远程管理安全边界 远程管理默认关闭，但当前版本**没有登录、密码或访问令牌认证**，并会监听设备可访问的网络接口。服务只限制可操作的受管目录，不能阻止同一网络中的其他设备发起请求。 - 服务会拒绝非 IP Host、跨站写请求，并保护 `.moon/settings/` 等凭据路径；这些限制不能替代身份认证。 - 远程管理可以上传并安装插件更新包，等同于能在设备上执行代码。 - 只在可信局域网中临时启用。 - 不要把端口映射到公网，不要通过反向代理公开。 - 公共 Wi-Fi、访客网络或其他不可信网络中不要开启。 - 使用结束后立即关闭，或打开「空闲自动关闭」；不需要自动运行时不要启用开机自启。 ### 本地数据 插件数据位于 KOReader 数据目录下的 `.moon/`： ```text .moon/ ├── settings/ # 通用、功能和数据源配置（含凭据、锁屏密码哈希） ├── book.sqlite3 # 书籍、章节、目录、进度、笔记、统计和 AI 摘要 ├── cache/ # 下载书籍、章节、封面、双语版 / 排版版和 HTTP 缓存 ├── dictionary.sqlite3 # 拼音 / 小鹤双拼词库 ├── dictionary-wubi.sqlite3 # 五笔词库（选择后独立下载） ├── dictionary-cangjie.sqlite3 ├── dictionary-zhuyin.sqlite3 ├── screensaver/wallpapers/ # 默认锁屏壁纸文件夹 └── book.log # 月读独立日志 ``` 数据库身份使用 `(source_id, stable_id)`。本地书籍的 `stable_id` 是文件路径，在线书籍使用来源提供的稳定 ID；章节文件通过物理路径反查所属书籍和章节序号。 数据库使用增量迁移。插件升级不会主动清空用户数据；“清理缓存”只删除可重新生成的缓存（包括双语版和排版版），不删除数据库中的书籍身份、进度、笔记和统计，也保留 KOReader 的 `.sdr` 边车（阅读位置、书签和标注）。 在线来源、AI 服务和书城的凭据保存在本机 `.moon/settings/`。请自行保护 KOReader 数据目录，不要把整个目录分享给他人。 ## 设置索引 设置根页分为书库、外观、桌面、阅读、系统、安全、订阅和维护几组（订阅组在启用订阅后出现），每行下方有一句副标题说明管什么： - **书库 → 当前书库：** 点按直接弹窗切换当前数据源或混合模式。 - **书库 → 账号：** 本地书籍（目录 / WebDAV，含连接测试）与各在线来源的登录和服务配置（每个书源一行，进二级页）、Z-Library 与 OPDS 书城的开关和账号。 - **书库 → 书架显示：** 封面风格、显示名称 / 作者、点击书籍动作、随机一本及范围、书架每行数量、书库页签（多选，文件夹页签仅本地书库有）。 - **外观 → 外观 / 界面壁纸 / 屏幕 / 语言：** 界面字体、缩放、背景遮罩、弹窗关闭手势（下滑 / 上滑 / 关闭）；全局壁纸；屏幕刷新、彩色屏幕支持、夜间与亮度（自动夜间模式、自动亮度）；KOReader 界面语言。 - **桌面 → 启动与按键 / 桌面顶栏 / 桌面快捷面板 / 底栏拓展：** 启动打开桌面、物理翻页键与反转翻页键（有按键的设备）；顶栏状态项；桌面快捷动作的启停与排序；底栏「拓展」格与要显示的插件入口。 - **阅读 → 阅读行为 / 阅读页顶栏与底栏 / 阅读快捷面板：** 脚注弹窗、读到 99% 自动标记已读、翻页动画与风格、阅读侧栏；阅读页状态栏组件；阅读快捷动作的启停与排序。 - **阅读 → 查词 / 划词菜单 / 生僻字注音：** 划词手柄、翻译、X-Ray、词典、文字识别（OCR）、百科和段评；按钮开关、顺序与来源；拼音、英语音标注音。 - **阅读 → AI 接口：** 接口地址、API 密钥、模型、连接测试、AI 请求超时，以及阅读助手（章节摘要、前情提要）开关。 - **系统 → 网络 / 时间 / 输入法 / 远程管理 / 设备：** HTTP 代理与网络超时；时区、系统时间与网络校时；中文输入法开关、键盘布局、简繁转换与词库；远程管理服务开关、端口、开机自启和空闲自动关闭；设备名称与头像。 - **安全 → 锁屏壁纸 / 锁屏密码：** 锁屏接管开关、背景、主体、位置、宽度、文案和账单周期（广告版 Kindle 上提示并可一键去除锁屏广告，去除后自动重启）；开关锁屏密码（4～6 位数字）、修改密码和忘记密码说明。 - **订阅：** 启用订阅、下载文章图片。 - **维护：** 功能开关（停用用不到的功能）、存储空间、清理缓存、清除当前源统计、导入 KOReader 统计、调试日志、自动检查更新 / 检查更新、关于（含书友交流群、Bug 反馈群二维码）和关闭桌面。 ## 开发与测试 项目不需要构建，插件交付物是 `book.koplugin/`。 离线测试只需要系统 `luajit` 和 `libsqlite3`（macOS 自带；Debian/Ubuntu `apt install luajit libsqlite3-0`），不启动 KOReader、不需要克隆 KOReader 源码： ```bash ./tests/run.sh # 全部 ./tests/run.sh tests/book/catalog_spec.lua # 单个文件（可多个） ``` - 测试文件 `tests/<模块镜像>/xxx_spec.lua`，与 `book.koplugin/` 目录一一对应；跨模块的架构检查（`feature_boundary_spec`、`text_box_bg_spec`）放 `tests/` 根。 - 每个 spec 在独立 luajit 进程里跑，0 断言判失败。断言库 `tests/support/assert.lua`，KOReader 模块桩 `tests/support/stubs.lua`（缺什么补什么，不整树 stub），主题弹窗记录桩 `tests/support/theme_stubs.lua`。 - 测试数据全部写到仓库根的 `test/` 沙箱（git 忽略，可随时删除），绝不碰模拟器数据。 - 仓库根有 `koreader/` 克隆时 frontend 模块用真的；有模拟器构建时再多跑少数需要 native 库的 spec。没有也只是这几条 skip，其余全跑。 - 静态检查（LuaLS，仓库根执行，两个路径必须是绝对路径）：`lua-language-server --check="$PWD" --configpath="$PWD/.luarc.json" --checklevel=Warning`，提交前应为 0 条。 - 推到 `main` / 开 PR 时 GitHub Actions 自动跑全部测试（`.github/workflows/test.yml`）。 本机模拟器需要仓库根目录下有 KOReader 源码和 Homebrew GNU 工具链： ```bash ./run.sh ``` 新增数据源遵循 `source/base.lua` 和 `source/registry.lua` 接口；第三方书源以独立插件形式提供 `moon_source.lua`，契约见 [`examples/moonsource-demo.koplugin/moon_source.lua`](examples/moonsource-demo.koplugin/moon_source.lua)。文字处理复用 `utils/text.lua`，SQLite 访问必须使用参数化查询，耗时文件与解析任务放到 worker，数据库写入留在主进程。 模块契约写在各模块头注释里（表结构在各 `*_db.lua` 表模块头注释里），开发文档见[月读文档站](https://moon.ankio.net/develop)的「开发文档」。 ### 扩展开发 扩展是独立的 KOReader 插件（`_meta.lua` + 返回空 `WidgetContainer` 的 `main.lua` + 根目录的 `moon_source.lua`），月读在 KOReader 加载完全部插件后扫描并登记。扩展用 `provides` 自己声明能力： ```lua return { api = 1, -- 必须等于 Registry.API id = "ext.greeting", -- 非书源写在这里；书源取 meta().id provides = { source = false, home_widgets = { widget } }, } ``` - **书源与非书源：** `provides.source = true` 才是书源，需要 `meta()` / `new()`，出现在数据源列表里；`source = false` 的扩展（例如只加首页组件）不需要 meta/new，也不能当活跃源。没写 `provides` 的旧描述文件仍按书源处理（顶层 `source = false` 除外），首页组件取顶层 `home`。 - **首页组件：** 出现在首页编辑的「添加组件」里，与内置组件一样摆放。简写表 `{ id, title, build(ctx, w, h), icon?, height? / heightRange?, settings?(desktop, id) }`，用 `ui.themes.widgets.*` 拼控件；需要请求、刷新和生命周期时写继承 `desktop.pages.home.base` 的完整组件类。 - **id 规则：** 扩展 id 必须是 `ext.`（字母数字 `_-`），写进书库与配置，发布后不能改，重名时先加载的生效；组件 id 必须以 `<扩展 id>.` 开头，简写表可只写短名，月读自动补前缀。 - **出错处理：** 描述文件不合约定、组件 id 不合规或重名只记日志并跳过；组件运行时抛错被 pcall 隔离，记日志后画空白占位，不影响首页和内置源。 - **保存的布局：** 扩展卸载或禁用后组件不再显示，但首页布局里的位置保留，重装后回到原处。 - **功能挂点：** `provides.features = { setting, panel, topbar, events, hooks, lookup }` 往月读的设置页（`entries(desktop)`）、快捷面板（`actions()`）、桌面顶栏（`items()`）、数据事件（`book_identity_changed` / `book_removed`）、阅读页就绪（`hooks.onReaderReady(plugin)`）和查词面板（`lookup.tabs` / `lookup.actions`）加功能，形状与内置 `features//` 的约定文件相同（lookup 形状见 `features/rare/lookup.lua` 的 `externalTabs` / `externalActions`）；值可以是表，也可以是插件内模块名（用到时才 require）。开关、顶栏项、设置页、查词 Tab / 操作按钮 id 自动加 `<扩展 id>.` 前缀，回调出错只记日志，配置用 `utils.settings.getSource(<扩展 id>)`。查词 `actions` 由扩展自己决定是否登记，核心与示例默认不追加操作按钮。其它 KOReader 事件、菜单和手势由扩展插件自己的 `main.lua` 处理。 示例：书源 [`examples/moonsource-demo.koplugin`](examples/moonsource-demo.koplugin/moon_source.lua)（书源 + 首页组件），非书源 [`examples/moonwidget-demo.koplugin`](examples/moonwidget-demo.koplugin/moon_source.lua)（首页组件 + 设置 / 快捷面板 / 顶栏 / 查词 Tab）。分步指南见文档站[扩展插件](https://moon.ankio.net/develop/extend/plugin)、[接一个数据源](https://moon.ankio.net/develop/extend/source)与[锁屏与首页组件](https://moon.ankio.net/develop/extend/components)。 ## 版本与发布 版本文件是 `book.koplugin/bookversion.lua`，源码树中默认显示 `0.0.0-dev`。 发布时 CI 在 `v*` tag 中注入版本、打包 `book.koplugin/`，并把 `extensions/*.koplugin` 各自打成独立 zip，一起发布到 GitHub Release。本地打包：`tools/package.sh [版本] [输出 zip] [插件目录]`，插件目录默认 `book.koplugin`。 ## 许可证 本项目采用 [GNU GPLv3](LICENSE)。 ## 社区 感谢 [LINUX DO](https://linux.do/) 社区的支持与认可。