# 默读 1.3.1 功能与设置指南

[English](SETTINGS.md) · 简体中文 · [中文首页](../README.md) · [文档目录](README.md)

适用于正式版 **1.3.1+10152**，更新日期：2026-10-22。手机通常逐页进入设置，桌面宽窗口采用左右分栏；部分能力取决于系统、阅读内核及所选服务。

下列设置入口包含 [1.3.1](https://github.com/sobranie2406/modureader/tree/v1.3.1) 的调整。分场景操作、默认值和限制见[详细功能介绍](FEATURES_zh.md)。源码与自动检查不代表全平台实机验收。

### 1.3.4 补充

- 语种翻译与文言文翻译共用百度／微软服务凭据。加密设置同步只同步服务配置、凭据及相关 AI 服务选择，不同步语言、方向和译文外观。
- 百度与微软配置页分别显示用量估算及参考额度进度；只统计 Modu 成功请求的字符，按 UTC 自然月汇总已更新且开启加密设置同步的设备，重复同步不重复累计。不是官方账单或剩余额度，超时／取消后服务端计费可能未计入；参考额度可修改，不是消费上限。微软两把密钥分别计数，其他引擎不统计。
- AI 显示方式选择「弹出」时，出现「允许移动和调整弹窗大小」，默认关闭；开启后划词功能弹窗可拖动顶部移动、两侧／底边／四角缩放，每次重新打开恢复默认几何尺寸。
- 最后阅读排序使用同步的阅读时间，文件夹沿用封面宽度并适配可用空间。

## 设置入口

### 顶部菜单与文言文互译

- 「设置 → 翻译」拆分为「语种翻译」「文言文翻译」两个入口，沿用统一分组标题、设置行与圆角阴影卡片。两个子页均有独立的「译文外观」，可选择字体（跟随原文、系统／通用字体、已导入 TTF/OTF）、字号（跟随原文或 0.5–3.0，每次 0.1）、粗体及斜体，并提供即时预览。「字体」下方新增「字体颜色」，使用主题同款取色器、十六进制输入和预设色（含青绿色、蓝色）。两套设置分别自动保存、互不联动，普通阅读与 PDF/OCR 重排中的已有及后续对应译文同步应用；不修改原文，不重新发起翻译。外观随翻译设置备份，导入字体文件需在目标设备另行提供。

- 「设置 → 阅读 → 阅读顶部菜单」控制按钮显隐和拖动排序。已启用且在当前阅读模式中可用的功能按顺序显示，功能区（含三点「更多」）最多占阅读区域可用宽度的 40%，其余放入「更多」；按钮保持正常点击尺寸，随旋转和窗口大小变化自动调整数量。返回按钮独立保留，隐藏的项目不会出现在更多中。普通书籍与 PDF/OCR 重排共用设置。
- 「设置 → 翻译 → 文言文翻译」选择 AI、百度或 Microsoft Translator，并选择「文言文 → 现代汉语」或「现代汉语 → 文言文」。普通阅读翻译的引擎和目标语言不受影响。AI 使用已配置的独立模型选择。
- 百度：开通[通用文本翻译](https://fanyi-api.baidu.com/doc_bd/21)，填写 APP ID 与密钥，然后点击「保存配置」。不使用百度智能云 API Key。请求为官方 HTTPS POST，签名使用原始 UTF-8 文本的 `MD5(appid + q + salt + 密钥)`；方向为 `wyw ↔ zh`，应用按标准版速率串行请求并拆分长段落。
- 微软：在 Azure 创建 Translator 资源，从「密钥和终结点」复制 Key 1 或 Key 2 和区域，然后点击「保存配置」。区域／多服务资源必须填写对应区域（如 `eastasia`）；全局单服务资源可留空或填 `global`。使用全球端点 `/translate?api-version=3.0`、`Ocp-Apim-Subscription-Key` 和适用的区域请求头；方向为 `lzh ↔ zh-Hans`。参见[官方认证文档](https://learn.microsoft.com/azure/ai-services/translator/text-translation/reference/authentication)。专用网络端点不在此设置范围内。
- 两个官方接口都需要自己的账户凭据；免费额度和超额费用以账户套餐为准。密钥默认隐藏，默认导出的非敏感配置不包含它们；保存设置不会发起请求。
- 在阅读菜单点「文／白」后手动启动。支持仅译文或原文＋译文，翻译可见段落并在滚动时逐段加载；未加载部分暂保留原文。可随时停止，切换引擎／方向后重新翻译不会复用旧译文。关闭书籍不会自动续译；重排翻原书页时停止，不改动 OCR 缓存、编辑稿和笔记。谷歌官方翻译没有独立文言文语种，因此不列入文言文引擎。

未发布版本的滚动条调整：书架、阅读历史、设置、远程书库、笔记、综合查询及可滚动弹窗使用半透明可拖动滚动条；滚动时显示，停止操作约 1.2 秒后自动隐藏。竖向滚动条在右侧，横向滑动不显示滚动条；内容未超出区域时不显示。E-Ink 关闭动画时直接显示/隐藏。内嵌网页及正文连续滚动模式也提供滚动条，分页翻书和单行输入框不增加。

未发布版本的自动保存调整：普通开关、单选、多选及排序选中即保存；PDF/OCR 样式滑块松手后保存。CSS 合法编辑自动保存，无效内容不会覆盖上一份有效配置。连接地址与密钥、新建模板和需要完整校验的文本仍保留保存；删除、导入覆盖和恢复默认仍需确认。朗读缓冲参数立即记忆，停止后重新开始朗读才生效。详见[设置保存行为核查](development/settings-autosave-audit.md)。

从首页进入「设置」。应用语言可跟随系统或手动选择；内置提示词随所选语言提供默认内容，用户已编辑的提示词不会被自动翻译或覆盖。

| 栏目 | 用途 |
| --- | --- |
| 外观 | 主题、颜色、OLED / E-Ink、应用语言、封面、导航及可选的微信读书关联 |
| 阅读 | 字体、排版、翻页行为、长按自动选词或整段 |
| 阅读 → CSS 设置 | 命名方案、图形参数、自定义 CSS、正则高亮 |
| 划词工具栏 | 按钮开关、排序、标注颜色、AI 划词模板、选词搜索及自定义字典 |
| AI 设置 | 供应商、模型参数、显示形式、工具权限及 AI 阅读技能 |
| 离线本地模型设置 | 向量／嵌入与 OCR 模型、来源、下载／导入、使用及删除 |
| 朗读 | 引擎、声音、速度及可编辑的朗读风格模板 |
| 同步与备份 | WebDAV / S3、自动同步、加密凭据同步、数据库备份及全局设置文件／链接 |
| 远程书库设置 | 独立 WebDAV 浏览与书籍下载 |
| 翻译 | 引擎、目标语言、AI 与 DeepL / DeepLX |
| 实验性功能 | 插件默认关闭，警示并确认后开启；仅接受项目已审核的插件 |
| 高级 | 存储与缓存、TXT 分章、ANX 备份导入、日志与网络 |
| 关于默读 | 问题反馈与功能建议、项目、社群、许可证及检查更新 |

微信读书：在外观中开启关联并填写自己的官方 API Key，书籍详情中搜索并核对版本后确认绑定。微信读书资料、评分、书评与个人数据独立；公开缓存随已下载原书同步，密钥需明确开启敏感设置迁移。详见[微信读书说明](WEREAD.md)。

菜单采用页面同色圆角分组，高度随内容变化，适配浅／深色主题；E-Ink 保留黑白平面样式。新安装直接进入书架。阅读月亮按钮同时切换阅读模式与软件主题。

「外观 → 显示 → 界面布局」可选「自动／宽屏版／窄屏版」，选择会保存。自动模式沿用各界面原有的可用宽度大于 600 逻辑像素时启用宽屏的规则；手动模式统一导航、设置、历史、笔记及书籍详情布局，不改变阅读正文单双列设置。

默认浅色使用清纸白与青玉绿，格式和索引标签保留各自区分色。「外观 → 主题颜色 → 恢复默认」经确认仅重置软件强调色。阅读样式中的「背景颜色／文字颜色」入口带边框和文字标签，分别支持二次确认后恢复所选颜色，不覆盖另一种颜色。

文字／OCR 重排提供本页朗读和当前页翻译（优先校对稿），支持仅译文／原译对照及共用划词工具栏。原版 PDF／扫描页不朗读。「文字 → 导出本书已保存文字」可选 TXT 或 Markdown，按原页码导出。

### 首次使用的默认值

以下来自[偏好实现](../lib/config/shared_preference_provider.dart)，仅指未保存过对应设置时；升级、导入或供应商独立配置可能改变它们。

| 参数 | 默认值 |
| --- | --- |
| E-Ink、仅点击翻页、长按选择整段 | 关闭 |
| 书架布局 | 默认缩略图，可通过书架工具栏切换为无封面列表 |
| E-Ink → 关闭所有动画 | 开启；仅在 E-Ink 模式下可调整和生效 |
| 滚动翻页比例 | 80%，范围 80%–100% |
| 选词搜索 / 网页翻译缩放 | 100%，范围 50%–200% |
| 选中文本后自动翻译 | 关闭 |
| AI 阅读技能入口 | 显示 |
| 技能模板先填入输入框 | 关闭，点击直接发送 |
| 向量模型 | 启用，本地模式，BGE Small ZH v1.5；模型仍需下载 |
| 导入后自动向量化 | 关闭 |
| 云端同步连接 | 关闭，需配置 |
| 自动同步偏好 | 开启，仅在云端同步启用后工作 |
| 阅读时定时同步 | 关闭，默认间隔 5 分钟 |
| 服务配置 / 密钥同步、备份包含凭据 | 关闭 |

书架工具栏支持缩略图／无封面列表切换，并记忆上次选择。列表显示书名、作者、阅读进度、格式／索引标签和同步状态，文件夹显示名称与书籍数量。长按进入多选，可新建文件夹、批量移入和删除；每本书右侧提供三个点操作菜单。

长按书籍并拖到另一本书上，可命名并新建文件夹；拖到已有文件夹则直接移入。拖动已勾选的书时会携带全部已勾选书籍并显示数量，拖动未勾选的书只移动该书。在文件夹内，可拖到框外或「移回书架」区域移出。批量移动一次性保存，失败保留勾选状态；取消新建文件夹不会移动书籍。

## 检查与安装更新

入口：「设置 → 关于默读 → 版本检查与更新」。检查和下载共用一个「更新来源」，默认 GitHub。GitHub 暂时不可用而检查回退 Gitee 时，下载来源也一起切换；手动换源后重新检查，不在下载途中混用来源。发现新版不等于自动下载或安装，检查失败不影响阅读。

- Android：应用内下载并校验大小与 SHA-256，检查包名、签名及版本，再交给系统安装器。仅按需请求安装此来源的权限，不静默安装。
- Windows / Linux：应用内下载校验后打开 EXE / DEB，按系统安装步骤操作。Windows 需要 WebView2；Linux DEB 面向 Debian 13。
- macOS：交由默认浏览器下载 DMG，退出默读后将 Modu.app 拖到 Applications 覆盖。应用不能监测浏览器下载完成或宣称已校验该文件；可核对 Release 的 SHA-256。安装盘仅展示程序及 Applications 快捷入口，包未做 Apple 公证。
- iOS：IPA 需要自己的有效签名，不能由应用内直接安装；商店构建应使用原商店更新。

先备份，再覆盖升级，不要先卸载或清空数据。「已打开安装器」不等于安装完成。完整平台要求见[安装与发布说明](RELEASING.md)。

## 普通书籍阅读

未发布的 iOS 新功能：**书架 → + → 原位添加文件／文件夹（不复制）**，授权后直接读取 EPUB／PDF／MOBI／AZW3／FB2 原书，不导入整本副本。需在系统“文件”选择器中选定文件或文件夹，并保持文件已下载且可访问；删除书架条目不会删除外部原书。授权仅限本机，原书不自动上传或纳入备份 ZIP，换设备需重新选择原书或普通导入。封面和索引仍占空间，TXT／Markdown／UMD 仍需普通导入以转换格式，已有副本不会自动迁移或删除。仍待 iOS 实机验证。

支持 EPUB、PDF、MOBI、AZW3、FB2、TXT、Markdown 和文字 UMD；TXT / Markdown / UMD 导入后转换为 EPUB，沿用阅读和同步流程。UMD 保留章节、元数据及支持的封面，暂不支持图片／漫画 UMD。书架支持文件夹、标签、置顶及批量移入文件夹。远程书籍必须下载正文后才可离线阅读或建立索引。

导入支持多选文件、整个文件夹或进入文件夹后勾选兼容文件，包含子文件夹；桌面端也可将文件夹拖到书架或阅读界面，原始文件保持不变。拖入书籍后不再重复弹出确认和结果窗口，跳过重复文件，单文件失败不阻断其余导入。支持的系统文件关联可将书籍交给墨读打开，具体入口取决于平台与文件提供程序。封面左下角在可识别时显示 TXT／MD／UMD 原格式，否则显示实际存储格式；扫描版标签优先采用手动设置结果。

全平台统一使用封面翻开和返回过渡，并遵循关闭动画设置；iOS 保留侧滑返回。拖动 iOS 选区手柄后菜单随范围更新。MOBI 只在旧式注释结构可靠配对时恢复弹窗，AZW3 支持注释类型及明确内嵌注释文字；对应注释从正文隐藏、在弹窗显示，无法可靠配对的 MOBI 内容继续保留。

首页底部导航采用半透明浮动样式，列表底部预留空间，滚动到底仍可完整查看和操作最后一行。「外观 → E-Ink」使用黑白实色样式，默认关闭应用内页面过渡、翻页动画及动态加载效果。其下「关闭所有动画」总开关平时置灰，仅开启 E-Ink 后可调整；关闭该开关恢复原有动画设置，不改变黑白显示和硬件刷新设置。切换模式和重启后保留选择，不改写开书动画与翻页方式。外观设置提供「显示书籍格式标签」和「显示已索引标签」两个独立开关，均默认开启并记忆选择；缩略图和列表中的已索引标签与格式标签使用相同字号和内边距。关闭已索引标签不删除索引，不隐藏索引进度与失败提示，扫描版标记不受影响。书架和文件夹内长按封面（桌面也可右键）进入多选后，才显示右下角三个点菜单。

点击正文打开底部面板，可拖动进度并查看章节标题，使用上一章、上一页、下一页、下一章。「章节进度」表示章节序号 / 总章节数；「本章进度」表示本章当前页 / 本章总页数。

「样式」提供字体大小、**字体粗细 0.5–2.0（步进 0.1）**、模拟加粗、行间距、段落间距、字体及背景。实际字重取决于字体；固定字重字体可尝试模拟加粗。侧边距、页眉页脚等在更多阅读设置中调整。应用主题与书页背景是不同设置。

- 字体支持本地 TTF / OTF；成功导入后应用，批量导入使用最后一个成功项。在线字体下载需要网络。
- “设置 → 阅读 → 管理已安装字体”位于“下载字体”下方，可确认移除下载和导入的字体副本，不删除原始导入文件。系统与应用内置字体不可移除；正文、英文独立字体、两类译文、PDF/OCR 重排及摘录分享中使用该字体的选择回退默认，其他外观设置保留。字体下载进行或暂停时需先完成或取消下载。
- 滚动翻页的单次移动比例可设为 80%–100%；手动连续滚动不受该比例限制。
- 「滚动翻页自动对齐」默认开启，保留原有向上滚动对齐上沿、向下滚动对齐下沿的行为；关闭后可自由停留，不再强制对齐文字行。开关位于滚动翻页比例旁，修改即时生效并随设置备份保存，不改变翻页模式及 PDF 原页行为。
- 未发布：默认开启“跨章节连续滚动”。在阅读样式面板或阅读设置中关闭后，每章独立滚动；读到章末，通过翻页或目录进入另一章。修改即时生效并保存，不改变 PDF 原版的滚动方式。
- 长按可自动匹配词语或扩展整段，首次匹配后仍可用选择手柄调整范围。
- Android 和 iOS 使用一套触摸手柄。滑动／分页阅读时，把选区端点拖到页面上／下边缘（竖排为左／右边缘）停留约 0.75 秒，翻一页后端点停在新页交界处；松手，再抓住可见手柄继续扩选，另一端起点保持不变。滚动模式在边缘停留时缓慢自动滚动，松手即停。选区限定在同一章节；PDF 原页与桌面鼠标选择保留各自交互。
- 未发布：横排分页阅读也支持左右边缘停留，触发区位于屏幕安全区内，无需拖入系统手势区域。单栏页面拖到边缘停留即可，不必精准对准最后一个字；双栏仍需到达当前整页的选区边界。
- 移动端「仅点击翻页」不影响选词及连续滚动；桌面可使用方向键及符合翻页条件的拖动，拖选和输入不作为翻页。
- 阅读亮度默认跟随系统，可手动调节 0–100。Android 使用应用窗口亮度；其他平台应用内调暗，避免完全遮住操作控件。此偏好仅本机保存。

## PDF 与扫描图片书

PDF 使用专用原版阅读菜单。EPUB、MOBI、AZW3、FB2 在导入时最多抽样五个正文分节识别图片书；本地与远程导入共用检测。打开时只读保存的分类，不再等待抽样。书架菜单可手动设为扫描图片书或恢复普通书籍。

**普通文字书保留原菜单与样式，不受 PDF 专用设置影响。** 扫描图片书关闭普通插图的点击放大 / 长按选项。

专用面板提供适屏 / 适宽、缩放、旋转、平移、连续卷轴、裁边与分格及阅读顺序。原图与裁后图片按窗口和设置缩放；布局按书保存。

亮度面板的月亮按钮可将 PDF 页面反色、四周背景变黑，页面内插图也会反色；保留 OCR 选区及批注颜色，关闭后恢复原色。PDF 原版页面的文字／OCR 选词支持高亮、下划线和批注，标记随裁边、缩放、旋转对齐。连续卷轴惯性遵循关闭动画及 E-Ink 设置。

- 自动裁边逐页识别内容边界，保留有效正文、页码和脚注；复杂版面可改用手动裁边或分格。
- 图像增强提供墨色、对比度、加深、增白、锐化及扫描水印减淡，可调整强度、对照原图和恢复。水印减淡是保守图像处理，不保证所有水印都能去除。
- PDF 阅读会自动提前完成附近页面的裁边和增强，默认提前一个阅读区域，实际处理较快且设备信息允许时增至两个；连续卷轴也保留附近内容供反向滚动。整页／分格底图不超过约 800 万像素，页面窗口最多七个，并根据设备信息限制底图总像素；保留可见及选中内容，放大后单独补充局部高清细节。这是内存内预处理，并非提前转换整本书；快速跳页或复杂页面仍可能需要等待。
- 处理不改写原书。工具栏跟随应用主题；仅 E-Ink 模式显示手动 / 每 N 页刷新，硬件刷新需设备接口支持。
- 文字重排使用原页文字层；OCR 重排识别图像文字。均处理当前页，启用裁边时处理裁后整页，结果直接接入阅读区。
- 重排及提取结果复用电子书菜单和快捷样式，包含字体、间距、配色与背景，设置按书保存；菜单按内容自适应，最高为屏幕高度的 80%，不挤压正文视口。顶部可返回原页或切换重排模式；PDF 页码箭头自动重排相邻页，保留原有提前量和缓存。保留区域／整页／连续识别及 AI 草稿；文字／OCR 重排仅朗读本页，换页或退出时停止，复用语音服务且不改变普通电子书朗读。
- 根据原页的明确段距、首行缩进和段尾留白分段，不把每个印刷行拆成段落。新增重排笔记保存原始页码及图像区域，可通过「查看原图」核实；重新识别保留既有笔记及文字版本，旧笔记不猜测坐标、不强行匹配。
- E-Ink 强制应用和阅读界面使用纯白底、纯黑字，开启期间不切换深色；关闭后恢复原先保存的配色与背景。
- 重排后可调文字样式并使用划词、标注、AI 等工具；PDF 面板齿轮提供相关样式入口。
- 只有「提取」需要选择区域：识别结果填入 AI 输入框，编辑后再发送，不自动上传整本书。

### OCR 模型

未发布：桌面和移动端的每张模型卡片增加「离线导入」。同时选择本型号完整的检测、识别 ONNX 文件（上游原名或 `det.onnx` / `rec.onnx` 均可），按应用内固定版本的大小与 SHA-256 校验，无需联网。导入不切换当前模型，需要时再点「使用」。不接受 ZIP 压缩包或下载分片。

入口：「设置 → OCR 模型」。推荐 **PP-OCRv4 中英文**，另有 v5 中英文轻量版、v3 中英文和 v3 英文。权重不内嵌，按需下载；可选择上游或 Gitee 镜像。v4 / v3 上游为 Hugging Face，v5 为 ModelScope。

卡片支持下载并使用、切换、校验、取消和删除。完整文件通过大小及 SHA-256 校验后才可使用；删除应用内模型不删除书籍。识别在本机运行，无需 OCR API Key。模型选择和来源设置可备份，模型文件本身不随全局设置备份迁移。小字、复杂分栏或低质量扫描仍需人工校对。

桌面与安卓实体键盘可在「阅读 → 自定义按键」（翻页方式下方、滚动上方）设置翻页、菜单、播放／暂停和上一段／下一段。每项支持多个按键，拒绝冲突绑定，恢复默认需确认；播放／暂停共用按键，默认 P。输入框、选区和弹窗不会触发普通翻页，系统保留按键可能无法传给应用；播放控制作用于已开始的朗读会话。

## CSS 与划词工具

阅读内详细设置按「阅读 / 样式 / CSS / 其他」分栏，CSS 模板在独立标签中选择。样式、详细设置和 PDF 阅读设置沿用综合查询的弹窗尺寸规则，内容在框内滚动；划词工具栏与自定义按键仍从设置页进入。

「设置 → 阅读 → CSS 设置」提供 32 个命名位置和 13 个可编辑模板。启用总开关及需要的方案，可同时使用多套；当前书可跟随默认组合或单独选择。方案内容全局共享，编辑可能影响其他使用该方案的书。

CSS 控制布局，正则高亮控制匹配文字的颜色、背景和下划线，不改写正文或批注定位。导入 CSS / JSON 前确认来源可信，CSS 中的远程资源网址可能联网。新增、复制及导入的方案默认停用，导入只占空位，不自动覆盖。

「划词工具栏」可开关并拖动排序内置工具和 AI 命令，编辑标注颜色、名称、图标及提示词。常用 AI 预设默认关闭，包括 AI 知识、文言文翻译等。划词模板在这里管理，不与「AI 阅读技能」混放，但使用同一个阅读 AI 对话界面。

## 插件

未发布：**设置 → 实验性功能 → 插件**默认关闭。开启前显示风险警示，需再次确认；取消则保持关闭。授权仅保存在本设备，不随设置备份导出或恢复。开启后通过**管理插件**安装本地 `.moduplugin` 包（zip，小于 5 MB）。当前阶段插件只包含声明式数据，不执行任何代码。支持的贡献类型为 AI 提示词模板和划词工具栏动作；每个包必须声明 SPDX 许可证、能力令牌和语义化版本。详情页展示包 id、版本、作者、许可证、SHA-256、已声明权限及全部生效中的贡献。

仅接受 [Modu 项目](https://github.com/sobranie2406/modureader)审核并固化在应用可信清单中的版本。插件 ID、版本、完整文件清单及每个文件的 SHA-256 均须匹配；伪造作者地址、修改插件包或夹带额外文件均不能通过。安装、启动检查及重新启用时均执行校验，不提供自定义来源、跳过验证或脚本执行开关。新插件需经源码审核并随应用更新放行，流程见[插件信任策略](development/plugin-trust.md)。审核降低风险，但不保证 AI 输出安全或准确。

关闭实验开关会停用插件、移除未修改的贡献项，保留插件文件、配置及编辑过的普通条目。再次开启仍需确认，且不会自动启用单个插件。AI 动作仅在用户调用时通过已配置的 AI 服务发送相关阅读内容。

停用插件会移除它添加的提示词和划词动作；卸载还会删除插件包文件。修改过提示词正文的条目会保留为普通提示词或自定义划词命令，同 ID 升级时也会保留。插件设置支持文本、数字、开关、选项和说明文字，不能保存密码或 API Key；界面明确标为“预留配置”，当前只保存和备份，不改变提示词。部分提示词被用户删除后不会在重启时自动补回，避免覆盖用户的主动删除。

全局设置备份包含已安装插件记录与插件设置，但不包含插件包文件。在另一台设备恢复时，实验开关关闭则保持停用；本机确认开启后，缺少包文件的记录显示为**缺失**，需安装已审核的包，已保存配置会保留。插件添加的划词动作与你自建命令共用 24 个自定义名额。

每条 AI 划词命令可选择「结合上下文」（默认）或「仅选中文字」，并可选择联网搜索，用户明确选择的范围会保存。AI 知识优先使用当前模型已有知识；需要补查时，点击回答下方「联网搜索」（在重新生成和复制之前），在同一对话检索维基词典、维基百科、百度百科，再由同一模型整理并附来源，无需额外搜索 API Key。

## AI 配置、技能与对话

先在「设置 → AI 设置 → 供应商配置中心」添加接口、模型及 API Key，测试连接。模型参数按配置独立保存，包括温度、最大输出 Token、历史轮数及推理强度；支持范围和费用由供应商决定。RPM 控制调用节奏，不绕过服务限额。

「AI 工具」控制模型可调用的应用工具；阅读技能提示词不等于已经向模型提供整本书，实际范围取决于选文、可取得的章节及检索结果。

「AI 阅读技能」默认显示技能入口。内置和自定义技能可一起开关、排序、编辑；可恢复默认顺序，也可恢复已删除的默认技能。**「技能模板先填入输入框」默认关闭**：关闭时点击直接发送；打开时填入输入框，补充范围或要求后手动发送。设置页和对话框均有此选项。各 AI 界面及划词 AI 入口分别记忆本机开关，包括综合查询中的独立 AI 标签；修改一个不会影响其他界面，不参与同步和设置导入导出。升级时沿用原有默认值，直到单独修改相应界面的开关。

点击技能可开启新的任务对话；在当前或调阅的历史对话输入后续问题，会携带允许范围内的上文继续回答。完整对话可从历史入口恢复。生成结束后定位到新回复的开头，便于从第一段阅读。AI 字号独立调整；思维导图支持全屏、缩放、平移、节点展开收起及 PNG / SVG / Markdown / FreeMind / JSON 导出。

AI 知识在追问、历史恢复和重试时也不调用本地书库或本书检索工具；本书 AI 保留原书籍或技能限定的原文范围。AI 知识、AI 翻译、文言文翻译等 AI 界面均有各自的设置、新建对话、历史和显示菜单，字号与「编辑后发送」按界面在本机记忆。内置技能、自定义技能及首页任务分别保存历史，可在历史菜单选择技能，仅查看或清空该技能的记录。可识别的旧历史自动归类，不删除旧记录；无法归类的仍保留在原来的通用历史中。

内置默认提示词无需逐条写入备份，只保存用户修改及自定义模板；恢复默认会替换对应的自定义内容。远程 AI 会接收请求文本和实际提供的上下文，详见[隐私说明](../PRIVACY_zh.md)。

## 向量化与语义检索

未发布：本地模型卡片增加「离线导入」。从联网设备复制同一支持型号及版本的完整 `model_quantized.onnx` 和 `tokenizer.json`，在离线设备同时选择这两个文件；只按应用内清单校验，不接受任意 ONNX 模型或外部清单。保留当前模型选择和已有索引。Gitee 下载分片需先合并为完整文件。

入口：「设置 → 向量模型」。嵌入模型用于检索，大语言模型用于回答，两者配置不同。

本地模型按需下载，提供 BGE 中文（默认）、BGE 英文、MiniLM、多语言 E5；可选 Hugging Face 或 Gitee，并校验大小及 SHA-256。缺少模型时不会隐式下载。远程 embeddings API 会接收索引片段及查询，可能收费。

从书籍菜单向量化 / 重新向量化，或启用「导入后自动向量化」（默认关闭）。模型不可用或书籍未下载时不能排队。模型与源书未改变时，升级或更换安装包不应单独使有效索引失效；切换模型或更改内容需重新建库。

「停止向量化」位于书架任务栏及向量模型设置：关闭自动索引并取消当前和排队任务，保留完成的索引、书籍及模型。单独关闭自动索引取消自动任务，不妨碍之后手动向量化。

**向量索引仅本机保存，不参加 WebDAV / S3 书库同步。** 其他设备需按需建立自己的索引。本地嵌入不等于后续 AI 回答离线：提交给远程聊天模型的检索片段仍会离开设备。

## 字典、搜索与翻译

划词「综合」默认开启，可分别选择字典、百科、翻译与 AI 知识进行汇总自动查询。本书 AI、文言文翻译、联网搜索使用独立标签；本书 AI 自动填入选文但不自动发送。AI 保留上下文选择、先编辑再发送和继续提问；文言文翻译不展示阅读技能控件。原有字典／翻译／AI 单独入口保留，默认关闭。在线服务会接收查询词或所选上下文，可能产生费用。

综合查询 → 查询设置中可拖动调整四个栏目的顺序，点击「保存」后栏目标签与汇总结果按自定义顺序显示，并在本机记忆。拖动后自动关闭智能排序；可重新开启「按查询文本智能排序」用于汇总结果，关闭后恢复保存的自定义顺序。关闭来源不会丢失它的位置。该设置不参与同步或设置备份。

字典来源中可单选或多选本地词典、启用中英文维基词典；结果注明来源，在线条目附链接和许可，选中的本地词典无匹配时显示「词典名 · 无条目」。

自定义字典需自行导入有权使用的 MDX 1/2 或 StarDict 配套文件 / ZIP。离线按实际词目查询，可修改查询词；是否双向取决于原字典是否包含对应词目，不提供中文释义反查。新导入的 MDX 可配合 MDD／本地图片、音频、CSS 和脚本直接显示原版内容，视图与应用桥接、外部网络隔离，音频需主动操作；旧的纯文字字典需连同资源重新导入，StarDict 仍显示文字；字典不随书库同步和当前备份迁移。

选词搜索在内置浏览器打开搜索结果，可选择预置引擎或包含 {query} 的自定义网址，结果页支持缩放。向搜索站点发送所查询的文字。

全文翻译支持 Google、AI、百度翻译 API、Microsoft Translator、DeepL / DeepLX，原文 + 译文或仅译文直接显示在书页，跟随阅读位置；不是一键导出整本译书。AI 翻译使用已配置模型；DeepL / DeepLX 按接口要求配置。

选文翻译窗口可切换提供方，另支持百度 / 有道网页形式；网页方式不同于全文逐段翻译，支持 50%–200% 缩放和纵向滚动。扫描页须先有可用文字层或 OCR / 重排结果。在线翻译发送待译文本，结果需校对。

## 朗读与风格模板

「设置 → 朗读」提供系统语音、Edge TTS、DashScope、Xiaomi MiMo 和 OpenAI 兼容语音。按引擎填写接口和密钥，保存设置、获取声音、选择并试听。系统 TTS 已接入 Android、iOS、macOS、Windows；Linux / OpenHarmony 没有系统 TTS 后端，需主动选择在线服务。

支持可编辑的朗读风格模板，如自然叙述、睡前轻读、小说演绎、知识讲解、古文诵读和新闻播报。OpenAI 兼容服务需支持相关指令；MiMo 提供预设音色或文字设计音色，不支持声音克隆。描述是给模型的指令，不是需要读出的正文，效果由服务能力决定。

阅读区有紧凑的播放／暂停、上一段／下一段箭头及「回朗读页」「此页开始」工具；跳转段落时保留播放或暂停状态。音调、语速两组各占一半，窄屏时文字居中放在各自控件上方，空间足够时文字与控件同行。音调支持 0.5～2.0×、每次 0.1 及手动输入。紧凑语速控件支持 0.1～4.0×、每次 0.1，可点减号／加号或直接输入。安卓端 MiMo 音调直接调整本地播放，无需重新合成已缓冲语音，暂停继续后仍保留；其他平台通过服务支持的风格指令控制音高。系统及指令式语速不保证精确倍率。清除朗读设置需确认，不清空书库。迁移朗读配置使用「全局设置备份」，不再提供单独二维码入口。

在线朗读支持提前缓冲量（默认额外 3 段）、单次合成字数上限（240）、预合成并发（2）、段落停顿（0 毫秒）、缓存保留（10 分钟）及手动清理。播放参数在停止后重新开始时生效，暂停继续保留原参数。可复用音频仅缓存在内存中，上限 32 MiB；保留时间为 0 时停止朗读即清理。手动清理保留当前音频和已准备队列。系统 TTS 不应用这些在线设置；预合成可能增加用量，并发过高可能触发服务限流。

完整可选档位与用途见[详细功能介绍的朗读章节](FEATURES_zh.md#9-朗读声音与缓冲)，实现见[缓冲界面](../lib/widgets/settings/tts_buffer_settings.dart)和[参数校验](../lib/models/tts_buffer_settings.dart)。

## 阅读历史

编辑历史页时，可选择点击书籍进入详情或直接阅读，与布局修改一起保存或放弃；退出编辑后隐藏选择项。详情模式保留长按虚化预览。

点击仍在书库中的书名或封面，通过原有开书流程继续阅读；已删除书籍给出提示并保留历史记录。“最近阅读”“本周阅读回顾”“阅读日均时长”“笔记最多的书”等卡片可与原有图表自由排列，显示日期、进度、活跃天数、笔记数等标签；日均时长仅按有阅读记录的日期计算。

阅读样式面板在中文字体旁提供“原文／简体／繁体”快捷切换，仅改变显示，不改写书籍源文件。

## WebDAV 与远程书库

自动识别坚果云，重复触发的自动同步合并执行，后续至少间隔 10 分钟；同一设备、同一账号采用滚动半小时最多 480 次请求的保守预算。手动同步仍遵循请求预算和服务端冷却，重启不会重置；其他设备及应用也会共同消耗账号访问额度。其他 WebDAV 保留原有自动同步频率，所有服务均遵循 429／503 和 Retry-After，未完成的本地改动保留等待后续同步。

开启自动同步后，启动、回到前台／解锁和恢复网络时，不再等待普通触发的 2 秒合并延时，书架与阅读页均生效（包括 E-Ink 设备）。退出书籍先等待阅读／朗读位置写入完成，再请求同步。坚果云仍遵守 10 分钟间隔、请求预算和冷却；仅 Wi-Fi 设置仍有效。待同步请求保存在本机，重启不丢失，成功同步后才确认完成；前台失败后间隔 1 分钟通过同一限频入口重试。锁屏／后台只取消等待计时，不清除待同步请求，回到前台或网络恢复后继续补同步；不保证后台运行或锁屏前已经传输完成。

旧 TXT／Markdown 转换书籍若下载校验失败，请先升级并同步持有本地原书的设备，再在另一端重试；成功前保留本地副本。

「设置 → 同步」填写 WebDAV 上级地址、账号、密码，测试后启用。数据位于其下 modu 目录，地址末尾不要重复添加 /modu。迁移旧 anx / Anx 目录前暂停所有设备同步并完整备份，不覆盖已有 modu 目录。

「设置 → 同步」提供「WebDAV / 对象存储」标签。对象存储提供阿里云 OSS、腾讯云 COS、Amazon S3、Cloudflare R2、雨云 ROS、七牛 Kodo、百度 BOS、火山 TOS 预设，以及 MinIO 等自定义 S3 兼容地址。填写服务 Endpoint、区域、桶、同步前缀与访问密钥后测试连接。高级设置提供临时令牌、寻址、签名及列举版本。升级直接沿用旧 WebDAV 地址、账号、密码和开关；主动切换前需关闭同步并等待传输结束，两套连接配置分别保留。切换不会搬运旧云端书籍，须先下载仅云端书籍并备份。密码和密钥默认隐藏，统一提供显示/隐藏按钮。更换对象存储供应商会清空表单内的桶和凭据，取消不影响已保存配置。对象存储使用不可变记录和读回校验，不直接覆盖共享数据库。默认备份不含密钥；使用私有桶和限权密钥。详见[配置、权限及限制说明（英文）](OBJECT_STORAGE_SYNC.md)。

同步按稳定标识合并书籍、笔记、书签、文件夹、标签及阅读记录，阅读位置以最近真实操作为准，不简单取最大进度。可靠 ETag 服务以 database8.db 条件写入为主，清理已覆盖日志；不可靠服务使用内容寻址日志与合并整理。失败不应作为空云库上传，旧日志首次整理仍需读取。

字体、背景、本地字典、向量索引不参加书库同步。各设备尽量升级到相同版本，书架记录出现不代表正文已下载。

「阅读时定时同步」默认关闭，仅前台阅读时工作，需启用云端同步（WebDAV 或对象存储）和自动同步，并遵循仅 Wi-Fi 设置。默认 5 分钟，可选 1、2、3、5、10、15、30、60 分钟。锁屏 / 离开阅读页暂停，返回后等待完整间隔，不补发期间任务，不重叠执行。

「同步服务配置、API Key 和密码」是独立且默认关闭的开关，WebDAV 与对象存储共用。启用需至少 12 字符的独立同步加密密码，不是 WebDAV 密码或对象存储访问密钥。敏感服务配置以 AES-256-GCM 加密，不含 WebDAV / 对象存储连接凭据；加密密码不进入同步数据。书籍、笔记和整个数据库不会因此加密，忘记密码不能恢复密钥。

「远程书库设置」是独立连接，浏览和下载，不修改该书库服务器文件。配置本机保存；凭据迁移遵循独立开关。与同步目录不是同一个功能。

在「远程书库」使用当前目录导入按钮或文件夹菜单，可扫描子文件夹并勾选兼容书籍，依次下载导入。提供重复检查、进度和取消，取消后保留已导入书籍。目录响应在后台解析，上限 32 MiB；书籍下载仍保留 512 MiB 限制及完整性检查。

## 两种备份与 ANX 导入

| 需求 | 入口 | 范围 |
| --- | --- | --- |
| 迁移偏好与提示词 | 设置 → 全局设置备份 | JSON / modu 链接；不含书籍及聊天 |
| 备份本地书库 | 设置 → 同步 → 数据库备份 | ZIP；含本机书籍、封面、字体、背景、AI 历史、一般设置及数据库记录 |
| 从 ANX 迁移 | 设置 → 高级 → 导入 ANX Reader 的备份文件 | 校验 ANX ZIP，合并支持的书籍与记录 |

全局设置备份包含外观、阅读排版、自定义按键、CSS、划词工具、提示词、插件、朗读、翻译及模型选择等偏好，不包含字体 / 背景 / 字典 / 模型文件、书籍、笔记、聊天或阅读进度。**账号、密码和 API Key 默认排除；选择包含后，JSON / 链接是可还原明文，不是加密备份。** 导入前展示范围，关闭凭据开关时保留本机凭据。无需二维码；完整备份优先用文件。

数据库备份先下载要保留的书，再导出 Modu-Backup-*.zip。服务凭据默认排除，可选加密设置部分；书籍、笔记与聊天不因此整体加密。导入无需解压，会替换现有书库及备份设置而不是合并；先备份当前数据，等待同步和向量任务结束，恢复后完全关闭并重新打开。

Windows 导出默认在用户 Downloads，通常 `C:\Users\<用户名>\Downloads`；其他平台由系统保存窗口选择位置。成功后显示实际路径并可复制，Android 若仅返回文档标识则按所选目录和文件名查找。

ANX 导入接受原版 schema 7 备份 ZIP，导入已下载书籍、封面、笔记、进度、时长、文件夹及标签；不导入账号、应用设置、AI 历史及缺失正文的书。按实际文件合并，重复导入不重复建立同一记录；导入前生成本机数据库快照。不支持单独 DB、加密 ZIP、未知数据库版本。此功能不是两应用之间的持续同步。

## 数据、安全与反馈

未发布：问题与反馈页面不再显示联系方式。Bug 报告默认附带崩溃诊断与安全运行日志，可分别取消，提交前必须预览并确认，应用不自动上传。运行日志只含本次进程最近 300 条固定操作状态、相对时间、耗时和内存采样，不读取普通日志原文或书名、正文、路径、网址、账号、密钥；每次重启清空。普通本地日志仍默认启动时清理（可在高级设置调整）；独立崩溃诊断保留以便重启后排查。

存储页面可查看占用、清理可再生成的临时数据；不要在导入、同步或下载期间清理。清理缓存不应删除书籍、笔记、聊天、下载模型或已完成索引。

高级页面提供日志、网络和 JavaScript 等选项。电子书脚本与 CSS 仅对可信文件开启。反馈时区分 Bug 与功能建议，说明版本、平台、复现步骤；先预览并脱敏，不上传私人书籍、配置凭据或完整数据库。

[隐私说明](../PRIVACY_zh.md) · [安全报告](../SECURITY_zh.md) · [参与贡献](../CONTRIBUTING_zh.md)

### 译文字体颜色

- 正文颜色沿用「样式」中已有的文字／背景配色设置，不增加重复入口或独立覆盖值。普通阅读与 PDF/OCR 重排保持原有配色逻辑。
- 语种翻译和文言文翻译在各自字体下方设置译文颜色，独立保存、独立备份，不改变原文。支持预设色（含青绿 `#287D75`、蓝色 `#287FA3`）、自定义取色和十六进制输入。
- 取消不会保存。「恢复默认」二次确认后只恢复当前译文颜色，使其跟随原文，保留字体、字号、粗体、斜体和背景。
- 阅读中的两种翻译面板提供「译文外观」快捷入口，可设置各自字体、颜色、字号、粗体、斜体并预览；普通阅读和重排共用此入口。打开和修改外观不会停止或重新发起翻译。

- 两种译文的字号使用与「样式」一致的滑动条，数值为 0.5–3.0，每次 0.1（1.0 与正文一样以 16 px 为基准），拖动时实时预览，可单独恢复「跟随原文」。语种译文预览按当前翻译目标语言显示「学而时习之，不亦乐乎？」的固定译文，不随软件界面语言切换，也不调用翻译服务。