ShelfReader / 藏书室

A skeuomorphic digital library for collecting, displaying, and reading local books on iPhone.

**ShelfReader（藏书室）**是一款原生 iPhone 阅读器原型。它把数字书重新呈现为有尺寸、厚度、材质和位置的实体藏书，让“收藏、陈列、选书、继续阅读”成为同一段连贯体验。

项目不包含书店、广告或账号系统。读者从本地导入自己的文档，书籍与阅读进度保存在设备上。

设计主题

• 拟物化收藏：不同页数与开本映射成不同高度、宽度和厚度的书。
• 实体书架交互：拖动书脊浏览，选中的书会从书架中抽出并进入详情页。
• 收藏与阅读一体化：书架负责日常阅读，书库负责完整收藏、搜索和整理。
• 克制的数字辅助：可选的 AI 实验功能只帮助整理书名、原作者和中文简介，不参与阅读内容生成。

当前能力

• SwiftUI + SceneKit 原生 iOS 应用，最低目标系统为 iOS 26。
• 原生 TabView，在支持的系统上采用 Liquid Glass 外观。
• 拟物化三维书架：开本、页数厚度、书脊排版、材质、灯光和阴影。
• 横向拖动、惯性减速、逐本触觉反馈与点按选书。
• 导入 PDF、EPUB、TXT、RTF 和 HTML 到 App 本地 Documents 目录。
• 图书搜索、阅读进度、本地详情页、系统 Quick Look 与示例阅读页。
• 可选 DeepSeek 元数据整理，API Key 只保存在 iOS Keychain。

项目状态

这是一个可构建、可运行的 Beta 原型，不是 App Store 成品。

已验证：

• 无签名 generic iOS build；
• Xcode 静态分析；
• iPhone 真机构建、安装和启动；
• 书架、书库、本地导入、详情页和阅读进度主流程。

已知限制：

• AI 元数据识别仍属实验功能，部分文件会因 OCR、文档证据或模型返回格式而失败。
• EPUB 当前通过系统 Quick Look 打开，尚未包含完整的 EPUB 排版、目录、批注和精确页码引擎。
• 尚未完成 App Store 分发、辅助功能全量审计和自动化 UI 测试。

完整计划见 ROADMAP.md。

本地运行

环境

• macOS
• Xcode 27 beta 或兼容的更新工具链
• iPhone 16 模拟器，或运行 iOS 26 及以上版本的 iPhone

步骤

git clone https://github.com/DlamondEyes/ShelfReader.git
cd ShelfReader
open ShelfReader.xcodeproj

在 Xcode 中选择 ShelfReader Scheme 与一个 iPhone 模拟器，然后运行。

安装到自己的真机前，请在 Signing & Capabilities 中选择自己的开发团队，并按需要修改 Bundle Identifier。仓库不包含维护者的签名 Team ID。

AI 元数据实验功能

AI 功能默认关闭。启用时需要读者在设置中自行提供 DeepSeek API Key；Key 使用 iOS Keychain 保存，不写入源码、仓库或普通偏好设置。

启用后，应用可能把经过长度限制的文件名、嵌入元数据、OCR 结果和文档前段文本发送到 DeepSeek，以尝试整理：

• 核心书名；
• 原作者姓名；
• 100–150 字的简体中文简介。

请勿对包含敏感或无权上传内容的文档启用该功能。详见 PRIVACY.md。

架构导览

模块	主要职责
Models/LibraryBook.swift	图书、开本、元数据来源、颜色与封面设计模型
Services/LibraryStore.swift	本地书库、导入、持久化、进度与串行识别队列
Services/BookMetadataRecognitionService.swift	单本书的可选 AI 元数据识别
Views/BookshelfView.swift	SceneKit 书架、书本模型、惯性浏览与触觉反馈
Views/LibraryView.swift	主书架与阅读状态
Views/SearchLibraryView.swift	全部藏书、搜索与整理
Views/BookDetailView.swift	详情排版、封面展示与继续阅读

更多说明见 docs/ARCHITECTURE.md。

开源与第三方组件

本项目代码以 MIT License 发布。书架姿态与换书编排参考了 Mint Playground 的 MIT 开源项目 The Complete Shelf；项目没有包含 Stripe 商标或原始出版物封面。

字体、材质与依赖的详细来源和许可证见 THIRD_PARTY_NOTICES.md。

参与项目

欢迎提交问题、体验反馈和小范围改进。请先阅读 CONTRIBUTING.md 与 SECURITY.md。