# RDAIReaderView AI 系统设计合同

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

## 1. 系统分类

RDAIReaderView 是一个本地优先的 Retrieval-Augmented Generation 阅读系统，包含：

- 确定性 NLP：语言识别、分句、实体候选、词法检索。
- 本地语义检索：Natural Language embeddings。
- 生成式任务：摘要、书内问答、人物卡片和人物关系。
- 引用约束：生成内容必须映射到 PDF/EPUB 原文。

系统不是通用聊天机器人，也不把模型自身知识作为书籍事实来源。

## 2. 框架选择

### 2.1 主框架

- Apple Natural Language：iOS 15+ 基础分析和检索。
- Apple Foundation Models：支持设备上的生成式增强。
- Vision：扫描 PDF OCR，继续复用 RDPDFReaderView 现有能力。

### 2.2 选择理由

- 与当前纯 Swift/UIKit/CocoaPods 架构一致。
- 默认设备端处理，不需要新增服务端和书籍上传链路。
- Natural Language 可覆盖不支持 Apple Intelligence 的设备。
- Foundation Models 支持 structured generation 和 tool calling。
- 系统 API 可与现有 PDF/EPUB 定位直接结合。

### 2.3 未选择的首版方案

| 方案 | 首版不采用原因 |
|------|----------------|
| LangChain/LlamaIndex | 主要面向 Python/服务端，增加不必要基础设施 |
| 云端 LLM | 引入内容上传、成本、隐私、版权和网络可用性问题 |
| ONNX Runtime 自带模型 | 需要自行选择、量化、分发和维护语言模型 |
| 自训练 Foundation Models Adapter | 模型版本绑定和 entitlement 增加发布复杂度 |

Core 保留 `RDAIGenerativeProvider`，以后可以增加其他 Provider，不把 Apple 实现写死在公共业务层。

## 3. 模型可用性合同

调用 Foundation Models 前必须检查：

1. API 在当前系统可用。
2. `SystemLanguageModel.default.availability` 为 available。
3. 当前 Locale 被支持。
4. 当前请求未超过并发限制。
5. 当前任务的上下文预算可满足。

不可用原因映射：

| Apple 状态 | RDAI 状态 | UI 行为 |
|------------|-----------|---------|
| deviceNotEligible | `.deviceNotEligible` | 隐藏生成操作，保留基础分析 |
| appleIntelligenceNotEnabled | `.appleIntelligenceNotEnabled` | 说明可在系统设置中开启 |
| modelNotReady | `.modelNotReady` | 展示模型准备中，可稍后重试 |
| unsupported locale | `.languageUnsupported` | 保留检索，关闭生成 |
| unknown | `.unknown` | 通用不可用状态，允许重试 |

禁止通过静态设备型号列表推断可用性，运行时状态是唯一依据。

参考：

- [Foundation Models](https://developer.apple.com/documentation/FoundationModels)
- [SystemLanguageModel](https://developer.apple.com/documentation/FoundationModels/SystemLanguageModel)
- [语言与 Locale 支持](https://developer.apple.com/documentation/foundationmodels/supporting-languages-and-locales-with-foundation-models)

## 4. 输入与上下文策略

### 4.1 唯一事实来源

模型可以使用：

- 本次请求提供的 Passage。
- Passage 的章节标题、页码/资源信息。
- 用户当前问题。
- 非内容性规则，例如输出语言和防剧透范围。

模型不得把训练知识、其他书籍、互联网知识或先前书籍会话作为当前书籍事实来源。

### 4.2 上下文预算

运行时读取模型 `contextSize`，并使用 `tokenCount(for:)` 估算。

初始预算比例：

- 12%：instructions 和 schema。
- 5%：用户问题。
- 60%：检索 Passage。
- 17%：输出。
- 6%：安全余量。

若预算不足，按以下顺序处理：

1. 删除低分 Passage。
2. 缩短 Passage 到完整句子边界。
3. 使用预计算的有引用片段摘要。
4. 创建新会话。
5. 仍不足则返回 `contextLimitExceeded`。

不得静默截断引用或生成半个结构化对象。

参考：[Managing the context window](https://developer.apple.com/documentation/foundationmodels/managing-the-context-window)

## 5. Prompt 资产管理

Prompt 作为版本化代码资产保存：

```text
FoundationModels/Prompts/
├── summary_v1.swift
├── answer_v1.swift
├── characters_v1.swift
└── relationships_v1.swift
```

每个 Prompt 定义：

- `identifier`
- `version`
- `minimumModelProfile`
- `instructions`
- 输入构造器
- 输出 schema
- 评测集标签

修改 Prompt 必须：

1. 增加版本号。
2. 跑完整离线评测集。
3. 与上一版本对比准确率、拒答、引用和延迟。
4. 更新缓存失效策略。

## 6. 通用 Instructions

所有任务共享以下不可省略规则：

```text
你是书内阅读助手。
只使用提供的原文片段，不使用外部知识补充书中事实。
每个事实性结论必须引用一个或多个有效片段 ID。
证据不足时返回 insufficientEvidence，不猜测。
不得引用允许阅读范围之外的内容。
区分原文明确事实与可能推断。
使用用户当前语言回答。
```

实际实现使用简洁英文或经评测验证的目标语言 instructions；以上文字表达语义合同，不要求逐字使用。

## 7. 结构化输出

### 7.1 摘要 Schema

```swift
@Generable
struct GeneratedSummary {
    var overview: String

    @Guide(.maximumCount(6))
    var points: [GeneratedStatement]
}

@Generable
struct GeneratedStatement {
    var text: String

    @Guide(.minimumCount(1), .maximumCount(3))
    var passageIDs: [String]
}
```

规则：

- `overview` 只能概括已提供 Passage。
- 每个 point 必须有 Passage ID。
- brief 最多 3 点，standard 最多 6 点。

### 7.2 问答 Schema

```swift
@Generable
enum GeneratedAnswerStatus {
    case answered
    case insufficientEvidence
}

@Generable
struct GeneratedAnswer {
    var status: GeneratedAnswerStatus
    var answer: String

    @Guide(.maximumCount(6))
    var statements: [GeneratedStatement]
}
```

若 `status == insufficientEvidence`：

- `statements` 必须为空。
- `answer` 只说明当前已读内容没有足够依据。
- 不推荐用户从互联网获取答案，除非宿主未来明确增加该产品能力。

### 7.3 人物 Schema

```swift
@Generable
struct GeneratedCharacter {
    var displayName: String

    @Guide(.maximumCount(6))
    var aliases: [String]

    var description: String

    @Guide(.minimumCount(1), .maximumCount(6))
    var evidencePassageIDs: [String]
}
```

人物必须在 Passage 中有明确名称或可验证别名。纯代词不能单独创建人物。

### 7.4 关系 Schema

```swift
@Generable
enum GeneratedRelationshipStatus {
    case confirmed
    case possible
    case conflicting
}

@Generable
struct GeneratedRelationship {
    var sourceName: String
    var targetName: String
    var label: String
    var status: GeneratedRelationshipStatus

    @Guide(.minimumCount(1), .maximumCount(5))
    var evidencePassageIDs: [String]
}
```

关系标签应简短，例如“师徒”“同事”“敌对”“亲属”。描述性事件放在人物事件中，不无限创建关系类型。

## 8. 任务设计

### 8.1 章节摘要

输入：

- 当前章节 Passage，或已读范围内的章节片段摘要。
- 目标长度。
- 用户 Locale。

流程：

1. 章节能放入上下文时直接生成。
2. 超长章节分块生成带引用局部摘要。
3. 聚合局部摘要时保留原 Passage ID。
4. 运行引用验证。

禁止只把局部摘要文本作为最终事实来源而丢失原始 Passage ID。

### 8.2 书内问答

流程：

1. 识别问题语言和实体词。
2. Hybrid Retrieval 召回 30 个候选。
3. 重排并过滤到 3-4 个 Passage。
4. 直接把 Passage 放入 Prompt。
5. 生成结构化答案。
6. 验证引用和阅读范围。
7. 无有效事实项时拒答。

首版优先使用代码检索，不默认使用 Tool Calling，这样召回过程更确定、可测试、节省 token。

### 8.3 人物卡片

流程：

1. Natural Language 提供人物候选及出现位置。
2. 按名称和明确别名聚合候选。
3. 检索候选周边 Passage。
4. Foundation Models 生成结构化人物信息。
5. 代码校验所有别名和证据。
6. 低置信别名保持独立候选。

### 8.4 人物关系

采用两阶段：

1. Chunk-level extraction：从局部 Passage 提取关系候选。
2. Document-level merge：按人物 ID、关系标签和时间顺序合并。

合并规则：

- 相同关系 + 相同方向：合并证据。
- 对称关系可由受控词典决定是否双向展示。
- 新证据否定旧关系：状态变为 conflicting。
- 隐含动机、情感和立场默认 possible。
- 任何关系没有有效证据时不入库。

## 9. Tool Calling

仅在单次检索无法回答、且评测证明多轮查找有明显收益时启用。最多提供三个工具：

```text
searchBook(query, scope, limit)
getPassages(ids)
getCharacterEvidence(name, scope, limit)
```

要求：

- 工具只读。
- 工具强制应用文档和已读范围过滤。
- 参数有严格长度和数量上限。
- 返回内容有 token 上限。
- 每个请求最大 Tool 调用次数为 3。
- 检测重复参数调用并终止循环。
- 工具调用和结果 ID进入本地 trace，但不记录原文。

不提供跳页、删除、购买、网络请求等副作用工具。

参考：[Expanding generation with tool calling](https://developer.apple.com/documentation/foundationmodels/expanding-generation-with-tool-calling)

## 10. 确定性后处理

模型输出必须经过：

1. Schema 解码。
2. Passage ID 存在性校验。
3. 阅读范围校验。
4. Quote/Locator 构造。
5. 重复 statement 合并。
6. 空文本和长度校验。
7. 敏感内容与系统错误映射。
8. Artifact 元数据补齐。

模型不能直接构造页码、CFI、CGRect 或数据库 ID；这些字段全部由代码通过 Passage ID解析。

## 11. 安全与产品规则

- 不将 AI 输出表示为作者原话。
- UI 明确标记“AI 生成”。
- possible/conflicting 关系必须视觉区分。
- 用户问题涉及未读内容时，默认拒绝并提示防剧透设置。
- 原文包含违法或敏感内容时，遵循系统模型 guardrails；不能绕过。
- 输入和输出触发系统安全限制时，返回稳定、非技术性的不可生成状态。
- 不要求模型提供医学、法律或金融建议；如果书中包含相关内容，只能解释“书中写了什么”。

发布前必须复核 Apple Foundation Models acceptable use requirements 和最新 App Review Guidelines。

## 12. 关键失败模式

| 失败模式 | 检测 | 处理 |
|----------|------|------|
| 模型编造人物或关系 | Passage ID/名称验证 | 删除无效项，无结果则拒答 |
| 引用存在但不支持结论 | 人工评测 + LLM judge | Prompt 调整，低分结果进入回归集 |
| 同名人物合并 | 别名证据检查 | 保持独立，标记待确认 |
| 未读内容泄漏 | Scope validator | 阻断输出并记录安全计数 |
| OCR 错字导致错误事实 | OCR source 标记和置信策略 | 降低置信度，展示 OCR 来源 |
| Prompt 在系统更新后退化 | 模型版本分桶评测 | 版本化 Prompt 和缓存 |
| 上下文溢出 | tokenCount/contextSize | 重建上下文或分层摘要 |
| Tool 循环 | 调用次数和参数去重 | 终止并降级为现有证据回答 |
| 用户快速重复请求 | request actor + cancellation | 取消旧任务或排队 |

## 13. 评测维度

| 维度 | 定义 | 1.0 门槛 |
|------|------|----------|
| Citation validity | 引用能否恢复到原文 | ≥ 99% |
| Context faithfulness | 事实是否由引用支持 | ≥ 98% |
| Refusal accuracy | 无证据时是否拒答 | ≥ 95% |
| Spoiler safety | 是否只使用允许范围 | 100% |
| Schema validity | 结构化输出是否通过校验 | ≥ 99.5% |
| Character precision | 人物是否真实出现 | ≥ 97% |
| Relationship evidence | 关系是否至少有一条证据 | 100% |
| Alias precision | 自动合并别名是否正确 | ≥ 98% |
| Retrieval recall@5 | 正确证据是否在 Top 5 | ≥ 90% |
| Answer usefulness | 人工 1-5 分平均值 | ≥ 4.0 |

## 14. 评测方法

- 代码指标：Schema、引用 ID、范围、阅读权限、延迟和拒答格式。
- 人工标注：人物、别名、关系、引用支持度、剧透边界。
- LLM judge：只用于语气、完整性和引用支持度的辅助评估；必须先与人工评分校准。
- 生产抽样：只上传宿主允许的匿名数值和用户显式反馈；不上传书籍原文。

评测集和完整方法见 [RDAIReaderView-TEST-PLAN.md](RDAIReaderView-TEST-PLAN.md)。

## 15. 发布检查清单

- [ ] 所有 Prompt 有 identifier 和 version。
- [ ] 每个生成任务使用 `@Generable`。
- [ ] 每个事实输出经过 Citation Validator。
- [ ] 防剧透 Scope 在检索前和生成后各检查一次。
- [ ] Foundation Models 不可用路径已真机验证。
- [ ] 上下文预算使用运行时 API 计算。
- [ ] 模型版本变化不会复用旧缓存。
- [ ] 评测集达到所有 1.0 门槛。
- [ ] 日志不包含原文、问题或完整回答。
- [ ] Apple 最新 acceptable use 与审核要求已复核。