# RDAIReaderView 架构设计

**文档状态：** Draft 0.1  
**最后更新：** 2026-07-25  
**目标版本：** RDAIReaderView 1.0

## 1. 架构目标

RDAIReaderView 必须满足四个架构目标：

1. 不改变 RDPDFReaderView、RDEpubReaderView 和 RDSpeechReaderView 的核心职责。
2. iOS 15 用户继续获得稳定阅读、基础 NLP 和 TTS；Foundation Models 仅作为可选增强。
3. 所有生成结果都能追溯到稳定原文位置。
4. AI Provider、索引实现和 UI 可替换，公共数据模型保持稳定。

## 2. 总体分层

```text
┌─────────────────────────────────────────────────────────────┐
│ Host App / RDAIReaderViewUI                                 │
│ AI 面板、摘要、问答、人物卡片、关系图、引用跳转             │
├─────────────────────────────────────────────────────────────┤
│ RDAIReaderView                                              │
│ Query Service / Summary Service / Character Service         │
├───────────────────────┬─────────────────────────────────────┤
│ NaturalLanguage       │ FoundationModels                    │
│ 分句/语言/实体/检索   │ 结构化生成/工具调用/拒答             │
├───────────────────────┴─────────────────────────────────────┤
│ Index & Storage                                             │
│ Passage / EntityMention / Citation / Artifact / Job         │
├───────────────────────┬─────────────────────────────────────┤
│ RDPDFReaderView/AI    │ RDEpubReaderView/AI                 │
│ 页码/范围/矩形/OCR    │ href/CFI/范围/章节                  │
├───────────────────────┴─────────────────────────────────────┤
│ RDPDFReaderView / RDEpubReaderView / RDSpeechReaderView     │
└─────────────────────────────────────────────────────────────┘
```

依赖方向只能从上到下。阅读器核心不能反向依赖 RDAIReaderView。

## 3. CocoaPods 模块设计

建议新增：

```ruby
pod 'RDAIReaderView/Core'
pod 'RDAIReaderView/NaturalLanguage'
pod 'RDAIReaderView/FoundationModels'
pod 'RDAIReaderView/UI'
pod 'RDPDFReaderView/AI'
pod 'RDEpubReaderView/AI'
```

### 3.1 Core

- 最低 iOS 15。
- 只依赖 Foundation、SQLite3/CryptoKit 等系统能力。
- 包含公共协议、数据模型、索引调度、存储和查询编排。
- 不导入 UIKit、PDFKit、DTCoreText 或 FoundationModels。

### 3.2 NaturalLanguage

- 最低 iOS 15。
- 依赖 Core 和 NaturalLanguage。
- 提供语言识别、分句、实体候选、关键词和语义评分。
- iOS 17+ 可选使用 `NLContextualEmbedding`；资源不可用时降级。

### 3.3 FoundationModels

- 源码使用 `@available(iOS 26.0, *)` 隔离。
- 依赖 Core 和系统 FoundationModels。
- 需要支持 Foundation Models 的 Xcode 工具链。
- 不被基础 Pod 默认引入，避免旧工具链客户无法编译。

### 3.4 UI

- 最低 iOS 15。
- 依赖 Core，可选识别 FoundationModels 可用性。
- UI 不直接构造 Prompt，也不直接访问数据库。

### 3.5 Reader Adapters

- `RDPDFReaderView/AI` 依赖 RDAIReaderView/Core。
- `RDEpubReaderView/AI` 依赖 RDAIReaderView/Core。
- Adapter 只负责内容快照、定位转换、跳转和高亮。

## 4. 建议目录

```text
Sources/RDAIReaderView/
├── RDAIReaderView.podspec
├── Core/
│   ├── Contracts/
│   ├── Models/
│   ├── Indexing/
│   ├── Retrieval/
│   ├── Storage/
│   └── Services/
├── NaturalLanguage/
│   ├── Analysis/
│   ├── Embeddings/
│   └── Retrieval/
├── FoundationModels/
│   ├── Availability/
│   ├── Generation/
│   ├── Prompts/
│   ├── Schemas/
│   └── Tools/
├── UI/
│   ├── Assistant/
│   ├── Citations/
│   └── Characters/
└── Tests/

Sources/RDPDFReaderView/AI/
Sources/RDEpubReaderView/AI/
```

## 5. 核心数据流

### 5.1 建立索引

```text
ContentProvider
    ↓ 读取资源快照
Text Snapshot + Stable Locator
    ↓
Language Detection
    ↓
Paragraph/Sentence Chunking
    ↓
Entity Mentions + Keywords + Embeddings
    ↓
Transactional Storage
    ↓
Index Checkpoint
```

每次数据库事务只提交一个资源或一组有界片段。应用退出时，最多重做当前事务，不重做整本书。

### 5.2 问答

```text
User Question
    ↓
Language / Intent / Spoiler Scope
    ↓
Hybrid Retrieval
    ↓
Access + Read-Progress Filter
    ↓
Context Budget Builder
    ↓
Foundation Models Structured Generation
    ↓
Citation Validator
    ↓
Answer or Evidence-Insufficient Refusal
```

检索由代码执行。首版不让模型自由遍历整本数据库，只有需要多轮查找时才使用受限 Tool Calling。

### 5.3 人物关系

```text
Entity Mentions
    ↓
Alias Candidate Grouping
    ↓
Chunk-level Structured Extraction
    ↓
Evidence Validation
    ↓
Relationship Merge
    ↓
confirmed / possible / conflicting
```

代码只能自动合并完全相同的标准化名称和明确别名。代词消解、同名人物合并和隐含关系必须保持低置信度，等待更多证据或用户确认。

## 6. 稳定定位模型

### 6.1 通用定位

`RDAILocator` 包含：

- `documentIdentifier`
- `resourceIdentifier`
- `utf16Range`
- `sourceHash`
- 格式专属 Anchor

文本范围统一使用 UTF-16，与现有 RDSpeechReaderView、NSString 和 EPUB 搜索范围保持一致。

### 6.2 PDF Anchor

```text
pageIndex
normalizedRects
textSource: native / ocr
readingOrder
```

PDF Adapter 从现有 `RDPDFReaderTextRun` 构建连续页文本和 UTF-16 范围。每个 Passage 必须保留与 run 的映射，不能在 AI 层重新拼接后丢失矩形。

扫描 PDF 使用现有 `speechTextRuns(at:)`/OCR 能力，但商用实现应增加独立的 AI OCR 调度入口，避免页面导航取消请求时同时取消后台索引。

### 6.3 EPUB Anchor

```text
normalizedHref
cfi
rangeCFI
rangeAnchor
progressionFallback
```

优先级：

1. `rangeCFI`
2. `cfi + UTF-16 range`
3. `rangeAnchor`
4. `href + progression`

屏幕页码只用于展示，不能作为持久化引用主键。

## 7. 文本快照与分块

### 7.1 不修改原文

索引保存两份文本信息：

- `sourceText`：原始文本，用于引用与范围映射。
- `searchText`：规范化副本，用于检索。

禁止使用规范化文本范围直接驱动阅读器高亮。

### 7.2 分块策略

- 先按资源和章节边界划分。
- 再按段落划分。
- 超长段落使用 `NLTokenizer(unit: .sentence)`。
- 中文目标 600-900 字；英文目标 300-600 词。
- 片段之间保留 1-2 句重叠。
- 表格、代码、脚注和标题保留语义类型，避免与正文无差别拼接。

### 7.3 内容哈希

建议使用 SHA-256：

```text
documentHash = hash(ordered resource identifiers + resource hashes)
resourceHash = hash(source text + format-specific stable metadata)
passageHash  = hash(resource hash + UTF-16 range + source text)
```

书籍更新时按资源哈希增量失效。

## 8. 检索架构

首版采用 Hybrid Retrieval：

```text
finalScore =
    0.45 * lexicalScore +
    0.40 * semanticScore +
    0.10 * proximityScore +
    0.05 * headingBoost
```

权重是初始值，必须通过评测集调优，不作为永久常量。

检索步骤：

1. 规范化查询并识别语言。
2. 关键词倒排召回 Top 30。
3. 语义相似度重排。
4. 合并高度重叠 Passage。
5. 按已读范围、文档授权和最大上下文过滤。
6. 返回 Top 3-4，并保留评分解释。

若语义模型资源不可用，使用纯词法检索，不阻塞问答入口；UI 可提示结果质量可能降低。

## 9. Foundation Models 编排

### 9.1 Provider 抽象

Core 只依赖 `RDAIGenerativeProvider`。Apple 实现位于 FoundationModels 子模块，未来可增加 Core ML、MLX 或经用户授权的云端实现。

### 9.2 会话策略

- 摘要、问答、人物关系使用不同 instructions 和独立会话。
- 同一会话只处理一个并发请求。
- 用户切换书籍、变更阅读范围或取消时终止任务。
- 达到上下文阈值前主动新建会话，不等待系统抛错。
- 记录 Prompt 版本、模型可用性分类、耗时和 token 数，不记录原文。

### 9.3 上下文预算

默认预算建议：

| 项目 | Token 预算 |
|------|------------|
| Instructions + Schema | 500 |
| 用户问题 | 200 |
| 检索上下文 | 2400 |
| 模型输出 | 700 |
| 安全余量 | 296 |

实际使用 `contextSize` 和 `tokenCount(for:)` 动态计算，不写死为 4096。

### 9.4 引用验证

生成后执行确定性校验：

1. Citation ID 必须存在于本次上下文。
2. Citation 必须属于当前文档和允许阅读范围。
3. 引用文本必须能在 Passage 原文中匹配。
4. 每个事实项至少有一个有效引用。
5. 删除无效项后答案为空，则返回 evidence insufficient。

## 10. 存储设计

建议使用 SQLite，Schema 初稿：

```text
documents
resources
passages
passage_fts
embeddings
entity_mentions
entities
entity_aliases
relationships
relationship_evidence
artifacts
index_jobs
schema_metadata
```

关键原则：

- FTS 和关系表通过 Passage ID 关联原文。
- 向量数据按模型标识符、revision 和语言分区。
- 生成结果不覆盖人工编辑内容。
- 每个 Artifact 保存 Prompt/模型/输入哈希。
- 索引表支持按文档级联删除。

## 11. 并发与生命周期

建议采用 Swift Concurrency：

- `RDAIIndexCoordinator`：actor，管理索引队列和 checkpoint。
- `RDAIStore`：actor，串行化数据库写入。
- `RDAIRetriever`：Sendable 服务，可并发读取快照。
- Reader Adapter：`@MainActor`，仅提取 UI/阅读器状态和执行跳转。
- Foundation Models Session：由单请求 actor 或服务隔离。

优先级：

1. 用户当前问答所需 Passage。
2. 当前章节。
3. 相邻章节。
4. 已读范围。
5. 其余获准内容。

发生内存警告时：

- 取消低优先级 embedding 任务。
- 卸载 contextual embedding。
- 清理内存 Passage/向量缓存。
- 保留已提交数据库和当前用户请求。

## 12. 可用性与降级

```text
Foundation Models available
    ├─ 是 → 完整生成能力
    └─ 否
       ├─ Natural Language available → 索引、实体、基础检索
       └─ 语言/资源不支持 → 关键词检索与基础分段
```

降级状态是公共 API 的一部分，UI 不根据 Error 字符串猜测原因。

## 13. 安全与隐私

- 默认 Provider 为设备端 Provider。
- Core 不包含网络代码。
- 云端 Provider 若未来增加，必须是单独 Pod，并要求宿主显式配置。
- 日志只记录文档匿名哈希、阶段、耗时、错误类别和计数。
- 禁止记录 Prompt、Passage、用户问题和模型回答全文。
- 导出诊断包前再次脱敏。
- 删除书籍时由宿主调用 `removeDocument`，同时删除索引、关系和生成缓存。

## 14. 可观测性

本地指标：

- 索引耗时、资源数、片段数、失败类别。
- 检索 P50/P95、召回数量和降级模式。
- 生成耗时、取消率、错误类别和引用校验失败率。
- Foundation Models availability 分布。
- 缓存命中率和数据库大小。

商用版本默认只汇总数值。任何远程遥测必须由宿主决定，并遵守其隐私政策。

## 15. 架构决策记录

实施时至少补充以下 ADR：

- ADR-001：独立 RDAIReaderView 而非嵌入阅读器核心。
- ADR-002：UTF-16 作为跨模块文本范围。
- ADR-003：本地 SQLite 和增量资源哈希。
- ADR-004：检索先行、生成后置、引用强校验。
- ADR-005：Foundation Models 可选依赖和运行时降级。
- ADR-006：已读范围作为默认安全边界。

## 16. 已知技术风险

| 风险 | 影响 | 缓解 |
|------|------|------|
| 中文小说实体识别不足 | 人物漏识别或误合并 | 规则候选 + 结构化模型提取 + 证据与置信度 |
| OCR 阅读顺序错误 | 摘要和引用错误 | 保留 readingOrder、双栏测试、允许宿主提供文本 |
| PDF OCR 请求被页面导航取消 | 后台索引不完整 | AI 使用独立调度队列与缓存 |
| EPUB 重排后范围变化 | 引用跳转漂移 | CFI/rangeCFI 优先，文本哈希校验 |
| 系统模型更新 | Prompt 质量回归 | Prompt 版本化、模型版本分层评测 |
| 上下文不足 | 回答遗漏 | 检索压缩、分层摘要、新会话 |
| 同名人物 | 错误关系合并 | 不自动合并低置信候选，保留冲突 |