Novel Reader · AI 原生个人小说库

自动扫描 TXT → 自动识别编码 → 自动解析章节 → 批量建库 → 极简阅读器 → AI 阅读助手

一个面向个人小说收藏与阅读的本地化 Web 小说阅读器。把 TXT 放进目录,系统自动发现、解析并加入书库;打开网页即可享受无干扰的阅读体验,AI 助手帮你总结章节、解释设定、回顾剧情。

✨ 功能

数据层(全自动)

• 文件系统优先:递归扫描 NOVELS_DIR 下所有 *.txt,无需手动上传
• 编码自动检测:UTF-8 / UTF-8 BOM / UTF-16 / GBK / GB18030 / Big5(高频字启发式 + 严格 UTF-8 验证)
• 章节识别:多规则 + confidence 评分(第X章/Chapter N/001 标题/楔子 等),序号连续性校验,>= 0.9 自动确认,0.7~0.9 可能章节,< 0.7 忽略
• 字节偏移索引:SQLite 只存章节的 start_offset / end_offset,阅读时 seek + read,轻松支持超大 TXT
• 增量同步:file hash / size / mtime 判定 NEW / UNCHANGED / MODIFIED / DELETED,未变化不重新解析
• 批量导入:管理页拖拽/选择 TXT,显示每个文件的解析状态、章节数、编码、错误

书库

• 书架:继续阅读、最近添加、分类入口,加载骨架屏
• 全部小说:书库总览,书名/作者/分类即时筛选,支持最近更新/书名/作者/章节数排序
• 搜索:输入即搜(防抖)、最近搜索记录、书名/作者/分类结果
• 详情页:阅读进度、封面上传/移除、书籍信息编辑(书名/作者)、标签、大目录分批渲染 + 章节搜索
• 管理页:分区快捷导航、拖拽导入、扫描状态、AI 配置、最近 14 天阅读时长、分页书库列表
• 全书全文搜索:关键词按书籍编码转字节 → 整文件 Buffer.indexOf → 章节二分定位,301MB 书秒级搜索,片段展示 + 章内跳转

阅读器

• 自动分页:基于 CSS multi-column 实际排版测量,改字号/行距/窗口自动重排
• 滚动模式:连续阅读,章节内位置精确恢复
• Apple Books 式进度:底栏可拖动全书进度条跳转任意章节,显示页码/全书百分比
• 阅读设置:字体(系统/宋体/苹方)、字号 14–32 连续调节、行距/段间距滑杆、宽度 3 档、主题(白/米/深灰/纯黑/跟随系统)、正文加粗、翻页动画
• 快速设置:顶栏「Aa」一键打开,设置实时预览并自动保存
• 章节预取:后台预取相邻章节,翻章更快;跨章跳转保持阅读位置
• 键盘快捷键:←/→/↑/↓/Space 翻页、Esc 显隐 UI、T 目录、A AI、F 全屏、+/- 字号、D 切换主题、M 切换模式
• 自动进度:翻页/滚动/切章/隐藏页面时自动保存,重开自动回到上次位置
• 书签:一键添加(章节+位置,自动去重),书签列表跳转
• 阅读统计:30s 心跳按天聚合,今日/累计时长、按书统计
• 响应式:桌面 / 平板 / 手机(触摸滑动翻页、底部抽屉、长按划词)
• 无障碍:尊重系统「减弱动态效果」,翻页/过渡动画自动降级

AI 阅读助手

• 基于 Vercel AI SDK,支持 openai / anthropic / google / openrouter / OpenCode Console / 兼容端点
• 自由问答:问题关键词 → 全书检索 → 相关章节作为上下文,无预设问题
• 划词解释:选中文字 → AI 解释,带上下文(桌面 mouseup / 移动端长按)
• 打字机输出:SSE 流式 + 逐字显示 + 复制回答
• 对话历史:按书持久化,跨章节保留
• SSE 流式输出、解释结果缓存(prompt_hash)、API Key 只存服务端

🚀 快速开始

本地开发

bun install

# 放几本 TXT 到 data/novels/(或自定义 NOVELS_DIR)
bun run scripts/gen-fixtures.ts   # 可选:生成测试书籍

# 启动(server :8080 + Vite :5173)
bun run dev

生产模式:

bun run build    # 构建前端到 dist/
bun run start    # 单端口 :8080 提供前端 + API

Docker(推荐)

docker build -t novel-reader .

docker run -d \
  -p 8080:8080 \
  -v /your/txt/folder:/data/novels \
  -v /your/app/data:/data/app \
  -e AI_PROVIDER=openai \
  -e AI_MODEL=gpt-4o-mini \
  -e OPENAI_API_KEY=sk-xxx \
  novel-reader

打开 http://localhost:8080 即可。启动时自动扫描 /data/novels。

⚙️ 配置(环境变量)

变量	默认	说明
PORT	8080	服务端口
NOVELS_DIR	./data/novels(Docker: /data/novels)	小说 TXT 目录
DATA_DIR	./data(Docker: /data/app)	SQLite 数据目录
AI_PROVIDER	openai	openai / anthropic / google / openrouter / opencode
AI_MODEL	按 provider 默认	模型名
OPENAI_API_KEY	-	OpenAI 或兼容端点 Key
AI_BASE_URL	-	OpenAI 兼容端点(通义/DeepSeek/Ollama 等)
ANTHROPIC_API_KEY	-	Anthropic
GOOGLE_API_KEY	-	Google Gemini
OPENROUTER_API_KEY	-	OpenRouter
OPENCODE_API_KEY	-	OpenCode Console(默认端点 https://opencode.ai/inference/openai/v1)

未配置 AI 时,阅读器一切功能可用,AI 面板会显示配置提示。

🏗 架构

Browser (Vue 3 + TS + Pinia + Tailwind)
    │  HTTP / SSE
    ▼
Bun + Hono
    ├─ Scanner   递归扫描 / hash / 增量解析
    ├─ Parser    编码检测 + ChapterDetector(多规则评分)
    ├─ Services  书库 / 章节 / 进度 / 搜索
    ├─ AI        Vercel AI SDK 多 Provider + 缓存
    └─ bun:sqlite(books / chapters / reading_progress / ai_cache / FTS5)
    │
    ▼
/data/novels(TXT 原文,字节偏移索引)

关键设计:正文永不入库。SQLite 只存章节边界(字节偏移),阅读时按偏移读取并按检测到的编码解码。

📁 目录

src/
├── client/          Vue 3 前端(pages / components / stores / router)
├── server/          Bun 后端(routes / services / scanner / parser / ai / database)
└── shared/          共享类型
scripts/             开发辅助(dev / e2e / fixtures)

🧪 测试

bun run scripts/gen-fixtures.ts /tmp/novel-test   # 生成 6 种编码/章节结构的测试书
NOVELS_DIR=/tmp/novel-test bun src/server/index.ts
bun run test:parser          # 章节解析回归(短章/缩进/数字/Big5/目录页等 16 项)
bun run scripts/e2e.ts       # 阅读/搜索/设置/手机端 全流程(21 项)
bun scripts/mock-ai.ts &     # mock OpenAI 端点
bun run scripts/e2e-ai.ts    # AI 流式/缓存/问答
bun run scripts/e2e-p1.ts    # 书签/全文搜索/对话历史/统计
bun run scripts/e2e-meta.ts  # 封面/信息编辑/划词解释

🗺 路线图

• P1:✅ 书签、阅读历史、章节内全文搜索、封面、作者/标签
• P2:✅ EPUB/MOBI、小说 RAG、人物关系图、时间线