288 lines
13 KiB
Markdown
288 lines
13 KiB
Markdown
# RDAIReaderView 产品与开发规格
|
||
|
||
**文档状态：** Draft 0.1
|
||
**最后更新：** 2026-07-25
|
||
**目标版本：** RDAIReaderView 1.0
|
||
**适用工程：** ReadViewSDK
|
||
|
||
## 1. 文档目的
|
||
|
||
本文档锁定 RDAIReaderView 首个商用版本的产品范围、系统兼容策略、功能要求、非功能要求和发布门槛。架构、公共 API、生成式 AI 约束和测试方法分别见同目录其他文档。
|
||
|
||
## 2. 背景与现状
|
||
|
||
ReadViewSDK 已具备以下基础：
|
||
|
||
- RDPDFReaderView：PDF 页面、原生文本、Vision OCR、页内文本矩形、跳页与临时朗读高亮。
|
||
- RDEpubReaderView：EPUB 章节、`href`、CFI、UTF-16 文本范围、搜索与位置恢复。
|
||
- RDSpeechReaderView：基于 Natural Language 的语言识别和分句、系统 TTS、断点续听、后台播放与锁屏控制。
|
||
- 最低部署版本为 iOS 15，Demo 使用 iOS 15.6。
|
||
|
||
当前缺少统一的文档语义索引、可追溯引用、书内问答、章节摘要和人物关系能力。
|
||
|
||
## 3. 产品目标
|
||
|
||
RDAIReaderView 1.0 的目标是提供一个默认本地运行、可选启用 Apple Foundation Models、可被 PDF 和 EPUB 阅读器复用的智能阅读能力层。
|
||
|
||
首版必须实现：
|
||
|
||
1. 对书籍内容建立增量、可恢复的本地索引。
|
||
2. 识别语言、句子、人物、地点、组织和关键词。
|
||
3. 生成当前章节或已读范围摘要。
|
||
4. 回答书内问题，并为事实性陈述提供可跳转的原文引用。
|
||
5. 生成人物卡片和带证据的人物关系。
|
||
6. Foundation Models 不可用时安全降级，不影响阅读、搜索和 TTS。
|
||
7. 所有 AI 结果默认限制在用户已读内容，避免剧透。
|
||
|
||
## 4. 非目标
|
||
|
||
RDAIReaderView 1.0 不包含：
|
||
|
||
- 互联网百科、新闻或通用知识问答。
|
||
- 无来源的文学评价、复杂逻辑推理或事实推断。
|
||
- 自动改写、续写或批量导出版权书籍内容。
|
||
- 云端上传书籍全文。
|
||
- 自训练 Foundation Models Adapter。
|
||
- 自动替用户发布内容、发送消息或执行购买行为。
|
||
- 对 CBZ、漫画图片内容进行视觉剧情理解。
|
||
- 对 DRM 内容绕过访问控制或持久化超出宿主授权范围的文本。
|
||
|
||
上述能力必须在后续版本单独评审产品价值、版权、隐私和审核风险。
|
||
|
||
## 5. 用户价值与首版场景
|
||
|
||
### 5.1 阅读回顾
|
||
|
||
用户重新打开书籍时，可请求：
|
||
|
||
- 上次阅读内容的 3 句回顾。
|
||
- 当前章节摘要。
|
||
- 已读部分的关键人物变化。
|
||
|
||
输入范围默认从最近一个自然章节边界到当前阅读位置，不得包含未读段落。
|
||
|
||
### 5.2 书内问答
|
||
|
||
用户可以询问当前书籍，例如：
|
||
|
||
- “这一章发生了什么？”
|
||
- “张三为什么离开？”
|
||
- “这里提到的组织是什么？”
|
||
|
||
系统先检索相关段落，再基于检索结果生成答案。答案中的事实性结论必须关联一个或多个 `RDAICitation`。没有充分证据时必须明确拒答，而不是依赖模型常识补全。
|
||
|
||
### 5.3 人物与关系
|
||
|
||
人物卡片包含：
|
||
|
||
- 标准显示名和已发现的别名。
|
||
- 首次出现位置。
|
||
- 仅基于已读内容的简短介绍。
|
||
- 关键行为及证据。
|
||
- 与其他人物的关系边及证据。
|
||
|
||
关系状态分为：
|
||
|
||
- `confirmed`：原文明确表达。
|
||
- `possible`：模型推断但证据不充分，UI 必须显示“可能”。
|
||
- `conflicting`：不同段落给出冲突信息，UI 展示冲突而非自动覆盖。
|
||
|
||
### 5.4 与阅读器联动
|
||
|
||
- 点击引用跳转到 PDF 页面或 EPUB CFI。
|
||
- 跳转后高亮对应原文范围。
|
||
- 摘要、答案和人物卡片可交给 RDSpeechReaderView 朗读。
|
||
- 用户调整字体、页面尺寸或翻页方式后，EPUB 引用仍应通过 CFI/文本范围恢复。
|
||
|
||
## 6. 功能要求
|
||
|
||
### FR-001 文档导入
|
||
|
||
- AI 层只能通过 `RDAIContentProvider` 读取宿主已授权的文本快照。
|
||
- 不直接读取宿主数据库或下载接口。
|
||
- 支持取消导入、增量恢复和内容变更检测。
|
||
|
||
### FR-002 稳定定位
|
||
|
||
- PDF：使用文档 ID、页索引、页内 UTF-16 范围和归一化矩形。
|
||
- EPUB：使用文档 ID、规范化 `href`、UTF-16 范围和 CFI；CFI 不可用时才使用 progression 兜底。
|
||
- 所有引用必须保存源文本哈希，恢复时验证引用是否仍指向相同内容。
|
||
|
||
### FR-003 文本分析
|
||
|
||
- 使用 `NLLanguageRecognizer` 识别资源或段落语言。
|
||
- 使用 `NLTokenizer` 切分句子，保持原始 UTF-16 偏移。
|
||
- 使用 `NLTagger` 生成人名、地点、组织候选。
|
||
- 实体候选必须保留每次出现的原文位置，不能只保存名称。
|
||
- Natural Language 不支持或质量不足的语言，降级为字符/标点分段和关键词检索。
|
||
|
||
### FR-004 分块与索引
|
||
|
||
- 中文片段建议 600-900 个字符；拉丁文字建议 300-600 词。
|
||
- 优先在章节、段落和句子边界切分，不截断组合字符。
|
||
- 相邻片段保留 1-2 句重叠，便于跨边界检索。
|
||
- 每个片段保存内容哈希、语言、顺序、定位和索引版本。
|
||
- 索引任务在后台执行，并按当前章节、相邻章节、其余内容的优先级处理。
|
||
|
||
### FR-005 检索
|
||
|
||
- 首版采用关键词/BM25 风格评分与 Natural Language 语义相似度融合。
|
||
- 结果必须经过文档 ID、已读范围和访问范围过滤。
|
||
- 默认返回 3-4 个片段，最大不超过 5 个。
|
||
- 检索结果必须包含分数、匹配原因和稳定定位。
|
||
|
||
### FR-006 Foundation Models 可用性
|
||
|
||
- 编译期使用可选子模块，不提高 Core 的 iOS 15 最低版本。
|
||
- 运行时检查系统版本、设备资格、Apple Intelligence 开关、模型准备状态和语言支持。
|
||
- UI 必须区分 `deviceNotEligible`、`appleIntelligenceNotEnabled`、`modelNotReady`、不支持语言和未知错误。
|
||
- 不可用时隐藏生成入口或提供明确说明，Natural Language 索引、搜索和 TTS 保持可用。
|
||
|
||
### FR-007 结构化生成
|
||
|
||
- 摘要、答案、实体和关系均使用 `@Generable` 结构化输出。
|
||
- 输出不得依赖字符串正则解析。
|
||
- 每个事实项必须携带检索片段 ID；生成后由代码验证 ID 是否真实存在。
|
||
- 无效引用、越权引用或未读范围引用必须删除；删除后答案无证据则转为拒答。
|
||
|
||
### FR-008 防剧透
|
||
|
||
- 默认分析范围为“当前位置及之前”。
|
||
- 用户主动切换到整本书模式时必须进行一次明确确认。
|
||
- 缓存键包含阅读范围；已读摘要不得复用整本书摘要。
|
||
- 人物关系图默认只展示已读范围内已出现的人物和关系。
|
||
|
||
### FR-009 缓存与恢复
|
||
|
||
- 索引、实体、摘要和问答缓存均存储在应用沙盒。
|
||
- 缓存键包含文档内容哈希、索引版本、Prompt 版本、模型版本和阅读范围。
|
||
- 内容哈希变化时，失效受影响资源，不强制删除整本书其他有效索引。
|
||
- 提供按书删除、删除全部 AI 数据和存储空间统计接口。
|
||
|
||
### FR-010 用户控制
|
||
|
||
- 所有长任务支持取消。
|
||
- UI 展示索引或生成状态，不伪造确定进度。
|
||
- 用户可关闭 AI、清除 AI 缓存、选择“仅本地处理”。
|
||
- 生成失败不得阻塞翻页、搜索、标注或 TTS。
|
||
|
||
## 7. 系统兼容矩阵
|
||
|
||
| 环境 | 必须提供的能力 |
|
||
|------|----------------|
|
||
| iOS 15+ | 语言识别、分句、实体候选、关键词索引、基础检索 |
|
||
| iOS 17+ | 可选 contextual embedding；资源不存在时允许下载或降级 |
|
||
| iOS 26+ 且模型可用 | 摘要、问答、人物关系、结构化笔记 |
|
||
| 不支持 Apple Intelligence | Natural Language 能力完整可用，生成式入口降级 |
|
||
| 离线 | 已下载模型与本地索引可用；不得要求联网 |
|
||
| 扫描 PDF | 使用现有 Vision OCR；OCR 失败的页面明确标记不可分析 |
|
||
|
||
## 8. 非功能要求
|
||
|
||
### 8.1 性能
|
||
|
||
- 索引不得在主线程执行文本分析、向量计算或数据库批量写入。
|
||
- 当前章节索引优先完成，目标 P95 不超过 2 秒；具体阈值以目标真机基线校准。
|
||
- 10 万中文字的基础索引目标 P95 不超过 30 秒，允许后台增量完成。
|
||
- 索引期间阅读页面滚动/翻页帧率不得出现持续性下降。
|
||
- 单次 Foundation Models 响应首个可展示结果目标 P95 不超过 5 秒。
|
||
- AI 模块空闲 30 秒后应释放 contextual embedding 和不必要的内存缓存。
|
||
|
||
### 8.2 稳定性
|
||
|
||
- AI 相关 crash-free session 不低于 99.9%。
|
||
- Foundation Models 不可用或生成失败时降级成功率为 100%。
|
||
- 强制退出后索引可从最后一个已提交资源恢复。
|
||
- 数据库迁移失败时保留原数据库备份，并允许重建索引。
|
||
|
||
### 8.3 准确性
|
||
|
||
- 引用定位有效率不低于 99%。
|
||
- 事实性陈述有原文支持的比例不低于 98%。
|
||
- 无答案问题正确拒答率不低于 95%。
|
||
- 人物关系证据覆盖率为 100%。
|
||
- 结构化输出通过本地校验的比例不低于 99.5%。
|
||
|
||
### 8.4 隐私与安全
|
||
|
||
- 默认不上传书籍文本、查询、摘要、人物关系和阅读历史。
|
||
- 日志不得包含原文、用户问题全文或模型完整输出。
|
||
- 调试日志必须经过显式编译配置才能包含脱敏片段。
|
||
- AI 数据遵循宿主账户登出、删书和清除缓存生命周期。
|
||
- 文件保护等级、备份策略和共享容器由宿主配置，SDK 提供明确接口和文档。
|
||
|
||
### 8.5 可访问性
|
||
|
||
- 所有 AI 控件支持 VoiceOver、Dynamic Type 和 Reduce Motion。
|
||
- 状态变化使用可访问性公告，但不得连续播报索引细节。
|
||
- “AI 生成”“可能关系”“无原文证据”等状态不能只靠颜色表达。
|
||
|
||
## 9. 商用验收门槛
|
||
|
||
以下条件全部满足后才可发布 1.0：
|
||
|
||
- Core、NaturalLanguage、FoundationModels、PDF Adapter、EPUB Adapter 均有单元测试。
|
||
- 关键用户流有 UI 自动化测试。
|
||
- 完成至少 100 条人工标注的产品评测集。
|
||
- 所有准确性指标达到第 8.3 节门槛。
|
||
- 在最低支持系统、主流支持设备和至少两代 Apple Intelligence 设备上完成真机验证。
|
||
- 完成模型不可用、未下载、语言不支持、上下文溢出和生成取消测试。
|
||
- 完成隐私清单、App Store 隐私申报和 AI 功能说明审核。
|
||
- TestFlight 灰度无 P0/P1 缺陷，AI 相关 crash-free session 达标。
|
||
- 现有 PDF、EPUB、搜索、标注和 TTS 回归全部通过。
|
||
|
||
## 10. 实施路线
|
||
|
||
以下排期按 2 名 iOS 工程师、1 名测试工程师、产品/内容评测兼职参与估算，总周期 12-14 周。单人开发建议按 18-22 周估算。
|
||
|
||
| 周期 | 阶段 | 主要交付 | 退出条件 |
|
||
|------|------|----------|----------|
|
||
| 第 1 周 | 合同与工程骨架 | 五份开发文档、Podspec、目录、CI Scheme、ADR | 文档评审通过，空库支持 iOS 15 编译 |
|
||
| 第 2-3 周 | Core 与存储 | 公共模型、SQLite Schema、迁移、Job/Checkpoint、删除接口 | 崩溃恢复和增量失效单测通过 |
|
||
| 第 4-5 周 | Natural Language | 分句、语言、实体候选、词法/语义检索 | 基础检索评测达标，TTS 范围无漂移 |
|
||
| 第 6 周 | PDF Adapter | 原生文本/OCR 快照、Locator、引用跳转和高亮 | PDF 引用恢复率达到门槛 |
|
||
| 第 7 周 | EPUB Adapter | href/CFI/rangeCFI 快照、Locator、跳转和高亮 | 重排后引用恢复率达到门槛 |
|
||
| 第 8-9 周 | Foundation Models | 可用性、摘要、问答、结构化输出、引用校验 | 不可用降级与 AI 评测通过 |
|
||
| 第 10 周 | 人物关系 | 人物、别名、关系、冲突和证据合并 | 人物/关系指标达到门槛 |
|
||
| 第 11 周 | 商用 UI | AI 面板、状态、取消、引用、防剧透、无障碍 | 核心 UI 自动化通过 |
|
||
| 第 12 周 | 性能与隐私 | 内存、耗电、数据库、日志、清除数据、隐私说明 | 无 P0/P1，性能与隐私门禁通过 |
|
||
| 第 13-14 周 | TestFlight 灰度 | 5%→25%→100% 分阶段发布 | Crash-free 和质量反馈持续达标 |
|
||
|
||
每阶段要求：
|
||
|
||
- 功能代码、单元测试和文档同一阶段完成。
|
||
- 公共 API 变更必须先更新 API 文档。
|
||
- Prompt 变更必须增加版本并跑 AI 回归集。
|
||
- 阶段退出条件未满足时不得把未验证能力带入下一阶段默认开启。
|
||
|
||
## 11. 版本范围
|
||
|
||
### 1.0
|
||
|
||
- 本地索引。
|
||
- 章节摘要。
|
||
- 带引用的书内问答。
|
||
- 人物卡片和基础人物关系。
|
||
- PDF/EPUB 引用跳转。
|
||
- 防剧透和完整降级。
|
||
|
||
### 1.1 候选
|
||
|
||
- 关系时间线与冲突关系展示。
|
||
- 用户划线/笔记参与问答。
|
||
- 多本书对照，仅限用户主动选择的本地书籍。
|
||
- 可选 Core ML/MLX 或云端 Provider。
|
||
|
||
### 2.0 候选
|
||
|
||
- 多模态图片理解。
|
||
- 漫画/图文书内容理解。
|
||
- 经过独立法律和产品评审的云端增强能力。
|
||
|
||
## 12. 依赖文档
|
||
|
||
- [RDAIReaderView-ARCHITECTURE.md](RDAIReaderView-ARCHITECTURE.md)
|
||
- [RDAIReaderView-API.md](RDAIReaderView-API.md)
|
||
- [RDAIReaderView-AI-SPEC.md](RDAIReaderView-AI-SPEC.md)
|
||
- [RDAIReaderView-TEST-PLAN.md](RDAIReaderView-TEST-PLAN.md)
|