mtfyun/reader
1
0 Fork 0
mirror of https://github.com/hectorqin/reader.git synced 2026-11-12 05:50:54 +08:00
Code Issues Packages Projects Releases Wiki Activity
26 Commits 16 Branches 1 Tag
0370cd98e8eaf5fd7fd3e924703903ef320ec5bb
Commit Graph
6 Commits
Author SHA1 Message Date
cnb.dQC5J6ohAGA 0370cd98e8 feat: HTTP TTS 与双端兼容朗读，书架体验与自定义设置 
朗读（Closes #13 的朗读部分）

新增服务端 HTTP TTS 代理与客户端第二、第三个朗读引擎，三者在同一个
SpeechEngine 接口下可切换：

- 服务端 GET /api/v1/tts 代理 TTS_URL 指向的合成服务（edge-tts / Piper
  等兼容形态），只代理不内置合成模型；GET /api/v1/tts/voices 回答
  「这个实例能用什么」，未配置时返回 http:false 而不是 404。
  按句合成、磁盘缓存、上游返回非 audio/* 时明确报错（一个指到网页的
  TTS_URL 会以 200 返回 HTML，塞进 audio 里既没声音也没事件）。
  /tts 是精确的查询串令牌白名单项之一：<audio src> 无法带 Authorization。
- 客户端 HttpTtsEngine 用 <audio> 而不是 Web Audio，事件驱动推进队列。
- 客户端 NativeTtsEngine 走 Android 外壳新增的 speech 接口（shell v3）：
  WebView 自带的合成器与系统的是两个引擎，手机系统装好的中文语音经常
  不在 getVoices() 里，这是「朗读没有中文声音」最常见的原因。
- speechAvailability 决定 auto 用哪个引擎：native → system → http。
- 原 TtsEngine 抽出 loadQueue/onChunk/onState 为公开字段以结构化满足接口。

书架

- 排序：最近更新 / 最近入库 / 书名 / 作者，中文按数字大小排。
  排序规则抽到 shelf-order.ts，离线路径与服务端用同一条规则。
- 密度、作者显隐、封面进度条；搜索一键清空 + 回车即搜；下拉刷新。
- 服务端 BookDto 增加 addedAt，否则客户端离线排序无法复现服务端结果。

自定义设置

- 朗读引擎可选（引擎多于一个时才显示该行）；音调行只对有声调的引擎出现。
- 书架设置独立成 sheet，与阅读面板分开。

测试与文档

- server: tts.test.ts（10 例）。web: tts-http / speech / shelf-order
  新增 39 例，合计 245 passing。
- android/scripts/check-shell.sh 修正为同时校验嵌套的 speech 接口，
  之前它只能看到一个顶层接口。
- README / docs/api.md / docs/architecture.md 补齐三个引擎的取舍、
  环境变量与错误码。

Ref: #13
 2026-09-16 23:29:41 +08:00
CodeBuddy b9b9c63605 merge: 把 main 合并进按窗口读取分支，并修正目录书页契约的两处缺陷 
冲突只有两处文档（README 的测试计数与端点清单、docs/api.md 的 /manifest 说明），
两边各自都是对的，所以按并集处理：计数取本分支的实际值，端点清单保留 main 新增的
/items、/toc、/file、/library/formats。

合并后按契约把两边一起验了一遍，发现目录书这条链路上有两个会被静默吞掉的缺陷，
都是「服务端仍回 200、读者看到的是坏内容」那一类：

1. 「卷」的判据里有一句 `images === 0`。整卷系列里放一张封面扫描是常态，于是
   `第01卷.cbz` 与 `第02卷/` 并列、旁边再有张图时，整个系列会被判成「不是漫画」，
   而它也不是别的格式的书——书架上直接消失。判据改成按来源问：压缩包的页就在包里，
   一个压缩包本身就是一卷；卷子目录要往下看才知道有没有页。散图仍由 MIN_IMAGES 管，
   既不能否定同级存在的整卷，也不该在自己是唯一页源时被当成书。

2. 页的资源引用被 API 层按「列表下标」拼成了 `page:<index>`，而这个格式的引用形态是
   `page:<卷>:<页>`。「一个压缩包算一页」意味着一个卷在列表里的下标与它在卷里的位置
   无关，于是按 `page:1` 去问一卷时格式处理器解不出引用，异常回退到「当普通文件发」，
   客户端请求一页、拿到的是那个压缩包——状态码 200，内容不对。引用现在由同一次页面
   遍历给出（manifest 的 files[].ref），/file 原样回传，不再有第二处实现。

顺带修正三处文档与实际不符的地方：`.cbr`/`.rar` 并未被解析（原「不做」清单暗示只有它
不做）、嵌套深度措辞与实现（读到第 4 层，且内嵌压缩包不展开）、README 的测试计数。

server 137/137（typecheck + test + build），web 179 vitest + 29 node:test（typecheck + test + build）。
 2026-09-16 22:49:45 +08:00
cnb.dQC5J6ohAGA c18664f1e3 feat(reader): 按窗口读取、真机可编译的 Android 壳，以及分章契约的收口 
两件事：把 PR #8 里那四项合并进来（A 选项），然后把 issue 里一直没落地的
「一次只取一章」从服务端契约一路做到客户端。

## 一、PR #8 的四项（Android 外壳最值钱）

- Android 原生整页图渲染：NativePageView + 桥接 v2（renderPage/hidePage）。
  只画整页图，EPUB 永远留在 WebView；画不了就返回 false 回退，不出现空白页。
- 离线队列：脏集合语义固定为契约，补上「请求在途时位置被改写」的三条用例。
- TXT 编码探测：GB18030 与 Big5 都解一遍再按损坏证据评分选优。
  原来「先 GB18030 失败再 Big5」永远走不到第二步——两者字节范围重叠，
  同一串字节通常两边都能解出合法字符，繁体书会整本乱码。
- 格式嗅探：magic number 优先于扩展名，并明确拒绝非书籍的媒体容器。

## 二、Android 壳第一次真的编译通过

上一轮说「没有 JDK/SDK，只写了契约」，这一轮补上了环境并真的编译。
编译立刻暴露三处——都是只有编译才能发现的：

- colors.xml 的注释里写了 --reader-paper。XML 禁止注释中出现双连字符，
  AAPT 直接拒绝整个文件。Android 壳此前从未构建过，所以从未发现。
- NativePageView.kt 用了 Uint8Array。那是 JavaScript 类型，Kotlin 里不存在；
  桥接的另一侧是 ByteArray。
- AndroidManifest.xml 引用了 @mipmap/ic_launcher，而资源里没有这个文件。

三条都让 :app:assembleDebug 失败，也就是说这个 APK 此前根本产不出来。
现在是 BUILD SUCCESSFUL，产物 3.6MB。

## 三、分窗读取：从契约做到客户端

服务端：
- /manifest 省略 group 现在等价于 group=0。原来省略意味着「发全部条目」，
  于是一本 1200 章的书在它最需要快的那个请求（打开书）里收到 1200 条记录，
  等于分窗对不传参的客户端完全失效。要完整结构用 ?group=all。
- /toc 在没有 OPF 标题映射时回落到章节自身的第一个标题。手作 EPUB 大量
  没有标题映射，原来整本目录会读成「第 1 章 … 第 300 章」，等于没有目录。
- 扫描时的 spine 读取不再解析 NCX 与 nav：扫一遍全库本该只读一次包文档。
- 尾部 Range（bytes=-N）在超过 8MB 时退化为整包响应并撤回 Accept-Ranges。
  前向流无法跳到文件末尾，服务这种请求意味着为三个字节读完整个 400MB 漫画包。

客户端：
- 新增 formats/remote-zip.ts：走 HTTP Range 的只读 ZIP，让浏览器端也能不下整本书。
- 新增 formats/windowed.ts：分窗文档。分窗是传输边界，目录必须完整，两者分开
  —— 合在一起就是原来目录面板显示「第 1 章 – 第 40 章」的原因。
- reader-screen 接上 /toc，并且点击目录项会先取对应窗口再跳。

## 验证

server:  133/133（typecheck + test + build）
web:     179 vitest + 29 node:test（typecheck + test + build）
android: BUILD SUCCESSFUL，app-debug.apk 3.6MB
shell:   契约双向校验 + 渲染模式词表校验通过
 2026-09-16 19:51:38 +08:00
cnb.dQC5J6ohAGA 5f1e29a3e5 fix(server,docs): 目录书页面清单成为契约，修正三处会让书静默消失的缺陷 2026-09-16 18:40:37 +08:00
cnb.dQC5J6ohAGA ca68a03e5d merge: 解决 auto/init-server-scaffold-81b3 与 main 的冲突 
两个分支各自演进：一侧引入格式注册表、H5 客户端与 Android 外壳，另一侧
引入漫画目录书与逐页取图。冲突集中在扫描器、metadata、library 路由和 web
客户端，逐项按「两边能力都要保留」的原则合并。

合并后修复了 4 个被冲突掩盖的真实缺陷：

- scanner 同时保留了两套目录书实现，类型检查与测试均无法通过；改为统一
  走格式注册表，目录书在文件遍历之前发现，其内容不再重复入库。
- /manifest 的 files 对漫画目录书返回的是文件夹路径，客户端无法逐页取图；
  改为由 manifest 派生真实页路径。
- 单个文件端点只认 book_files 行，漫画目录书的每一页都 404；改为目录书
  额外认领其目录下的路径，并修正路径归一化使穿越尝试仍被拒绝。
- 目录书判定只看图片数量，会把夹着一本书的目录整体吞掉；改为注册表驱动
  的判定，含书籍文件的目录始终是书架。

同时修复了 web 端两套测试运行器互相无法执行对方用例的问题（vitest 与
node:test 混跑会静默跳过），以及 web 侧 5 处类型错误。

Ref: #9
 2026-09-16 18:04:11 +08:00
CodeBuddy 8570fb12ef docs(android): 定义外壳与 H5 的接口契约，暂不写不可验证的代码 
本环境没有 JDK 与 Android SDK，编译不了的 APK 不放进来。

写下来的是已被验证的部分：
- 按 kind 分流的渲染分工（用户那条「epub 走 H5、其他走原生」），
  契约点在 web/src/ui/reader-view.ts 的 capabilities()
- 桥接对象契约（web/src/bridge.ts 已实现读取侧，且无桥时正常工作）
- 离线缓存与断点续传所需的接口，服务端已就绪
- 硬件键、返回回调的接法，以及明确标出哪些回调还没实现

同时写清开工需要什么（JDK/SDK/产物复制），避免下一轮重新推一遍。
 2026-09-16 15:29:11 +08:00