605 lines
17 KiB
Markdown
605 lines
17 KiB
Markdown
# RDAIReaderView 公共 API 设计
|
||
|
||
**文档状态：** Proposal 0.1
|
||
**最后更新：** 2026-07-25
|
||
**目标版本：** RDAIReaderView 1.0
|
||
|
||
## 1. API 设计原则
|
||
|
||
- Core 最低支持 iOS 15，不直接依赖 UIKit、PDFKit、DTCoreText 或 FoundationModels。
|
||
- 公共模型优先使用值类型，并遵循 `Codable`、`Sendable`、`Equatable`。
|
||
- 文本范围统一使用 UTF-16 偏移，与现有 PDF、EPUB、NSString 和 TTS 范围保持一致。
|
||
- Reader Adapter 负责格式转换，Core 不识别 PDF 页视图或 EPUB 排版对象。
|
||
- Foundation Models 通过 Provider 协议接入，不能泄漏到基础 API。
|
||
- 公开 API 在 1.0 后遵循语义化版本；新增字段必须有解码默认值。
|
||
|
||
本文中的 Swift 定义是实现合同，允许在不改变语义的前提下调整文件组织和内部实现。
|
||
|
||
## 2. 标识符与基础范围
|
||
|
||
```swift
|
||
import Foundation
|
||
|
||
public struct RDAIDocumentIdentifier: RawRepresentable, Codable, Hashable, Sendable {
|
||
public let rawValue: String
|
||
|
||
public init(rawValue: String) {
|
||
self.rawValue = rawValue
|
||
}
|
||
}
|
||
|
||
public struct RDAIResourceIdentifier: RawRepresentable, Codable, Hashable, Sendable {
|
||
public let rawValue: String
|
||
|
||
public init(rawValue: String) {
|
||
self.rawValue = rawValue
|
||
}
|
||
}
|
||
|
||
public struct RDAITextRange: Codable, Hashable, Sendable {
|
||
public var location: Int
|
||
public var length: Int
|
||
|
||
public init(location: Int, length: Int) {
|
||
self.location = max(0, location)
|
||
self.length = max(0, length)
|
||
}
|
||
|
||
public var upperBound: Int { location + length }
|
||
}
|
||
```
|
||
|
||
约束：
|
||
|
||
- `RDAIDocumentIdentifier` 必须与宿主书籍 ID 一致并保持稳定。
|
||
- `RDAIResourceIdentifier` 在 PDF 中使用页索引字符串，在 EPUB 中使用规范化 `href`。
|
||
- 所有文本范围均针对资源原始文本，不针对规范化搜索文本。
|
||
|
||
## 3. 定位与引用
|
||
|
||
### 3.1 归一化矩形
|
||
|
||
Core 使用自定义矩形，避免公共存储格式依赖 UIKit：
|
||
|
||
```swift
|
||
public struct RDAINormalizedRect: Codable, Hashable, Sendable {
|
||
public var x: Double
|
||
public var y: Double
|
||
public var width: Double
|
||
public var height: Double
|
||
|
||
public init(x: Double, y: Double, width: Double, height: Double) {
|
||
self.x = x
|
||
self.y = y
|
||
self.width = width
|
||
self.height = height
|
||
}
|
||
}
|
||
```
|
||
|
||
所有值应限制在 `0...1`。Reader Adapter 负责与 `CGRect` 转换。
|
||
|
||
### 3.2 格式 Anchor
|
||
|
||
```swift
|
||
public struct RDAIPDFAnchor: Codable, Hashable, Sendable {
|
||
public enum TextSource: String, Codable, Sendable {
|
||
case native
|
||
case ocr
|
||
}
|
||
|
||
public var pageIndex: Int
|
||
public var rects: [RDAINormalizedRect]
|
||
public var textSource: TextSource
|
||
public var readingOrder: Int?
|
||
}
|
||
|
||
public struct RDAIEPUBAnchor: Codable, Hashable, Sendable {
|
||
public var href: String
|
||
public var cfi: String?
|
||
public var rangeCFI: String?
|
||
public var progression: Double?
|
||
}
|
||
|
||
public enum RDAIAnchor: Codable, Hashable, Sendable {
|
||
case pdf(RDAIPDFAnchor)
|
||
case epub(RDAIEPUBAnchor)
|
||
}
|
||
```
|
||
|
||
`RDAIAnchor` 必须实现显式 Codable discriminator，例如 `type: "pdf"`，未知类型解码为明确错误，不能误当成其他格式。
|
||
|
||
### 3.3 通用定位
|
||
|
||
```swift
|
||
public struct RDAILocator: Codable, Hashable, Sendable {
|
||
public var documentIdentifier: RDAIDocumentIdentifier
|
||
public var resourceIdentifier: RDAIResourceIdentifier
|
||
public var textRange: RDAITextRange
|
||
public var anchor: RDAIAnchor
|
||
public var sourceHash: String
|
||
}
|
||
|
||
public struct RDAICitation: Codable, Hashable, Sendable, Identifiable {
|
||
public let id: String
|
||
public let passageIdentifier: String
|
||
public let quote: String
|
||
public let locator: RDAILocator
|
||
}
|
||
```
|
||
|
||
引用恢复流程：
|
||
|
||
1. 校验文档和资源存在。
|
||
2. 校验 `sourceHash`。
|
||
3. 优先按格式 Anchor 恢复。
|
||
4. Anchor 失败时使用文本范围和 quote 搜索。
|
||
5. 仍失败则返回 `staleCitation`，不得跳转到近似但未验证的位置。
|
||
|
||
## 4. 文档与资源
|
||
|
||
```swift
|
||
public enum RDAIDocumentFormat: String, Codable, Sendable {
|
||
case pdf
|
||
case epub
|
||
}
|
||
|
||
public struct RDAIDocumentDescriptor: Codable, Equatable, Sendable {
|
||
public let identifier: RDAIDocumentIdentifier
|
||
public let title: String
|
||
public let format: RDAIDocumentFormat
|
||
public let contentRevision: String
|
||
}
|
||
|
||
public struct RDAIResourceDescriptor: Codable, Equatable, Sendable {
|
||
public let identifier: RDAIResourceIdentifier
|
||
public let title: String?
|
||
public let order: Int
|
||
public let estimatedUTF16Length: Int?
|
||
}
|
||
|
||
public struct RDAIResourceSnapshot: Sendable {
|
||
public let descriptor: RDAIResourceDescriptor
|
||
public let sourceText: String
|
||
public let sourceHash: String
|
||
public let locatorRuns: [RDAILocatorRun]
|
||
}
|
||
|
||
public struct RDAILocatorRun: Sendable {
|
||
public let textRange: RDAITextRange
|
||
public let anchor: RDAIAnchor
|
||
}
|
||
```
|
||
|
||
`contentRevision` 由宿主提供；若宿主没有版本号，Adapter 使用资源哈希汇总生成。
|
||
|
||
## 5. 内容提供协议
|
||
|
||
```swift
|
||
@MainActor
|
||
public protocol RDAIContentProvider: AnyObject {
|
||
func aiDocumentDescriptor() -> RDAIDocumentDescriptor
|
||
func aiResources() async throws -> [RDAIResourceDescriptor]
|
||
func aiResourceSnapshot(
|
||
for identifier: RDAIResourceIdentifier
|
||
) async throws -> RDAIResourceSnapshot
|
||
func aiNavigate(to locator: RDAILocator, animated: Bool) async throws
|
||
func aiShowCitationHighlight(_ citation: RDAICitation) async throws
|
||
func aiClearCitationHighlight()
|
||
}
|
||
```
|
||
|
||
协议标记为 `@MainActor`，因为现有 Reader Controller 和页面缓存均由主线程管理。实现必须只在主线程获取快照引用和 UI 状态；OCR、分块、分析和数据库写入移交后台 actor。
|
||
|
||
可选读取范围协议：
|
||
|
||
```swift
|
||
public struct RDAIReadScope: Codable, Equatable, Sendable {
|
||
public let upperBound: RDAILocator?
|
||
public let includesWholeDocument: Bool
|
||
}
|
||
|
||
@MainActor
|
||
public protocol RDAIReadScopeProviding: AnyObject {
|
||
func aiCurrentReadScope() -> RDAIReadScope
|
||
}
|
||
```
|
||
|
||
未实现时，默认只允许当前资源及之前的资源，不能默认整本书。
|
||
|
||
## 6. Passage 与分析结果
|
||
|
||
```swift
|
||
public enum RDAIPassageKind: String, Codable, Sendable {
|
||
case title
|
||
case paragraph
|
||
case list
|
||
case table
|
||
case code
|
||
case footnote
|
||
case unknown
|
||
}
|
||
|
||
public struct RDAIPassage: Codable, Equatable, Sendable, Identifiable {
|
||
public let id: String
|
||
public let documentIdentifier: RDAIDocumentIdentifier
|
||
public let resourceIdentifier: RDAIResourceIdentifier
|
||
public let text: String
|
||
public let languageCode: String?
|
||
public let kind: RDAIPassageKind
|
||
public let locator: RDAILocator
|
||
public let contentHash: String
|
||
public let order: Int
|
||
}
|
||
|
||
public enum RDAIEntityKind: String, Codable, Sendable {
|
||
case person
|
||
case place
|
||
case organization
|
||
case other
|
||
}
|
||
|
||
public struct RDAIEntityMention: Codable, Equatable, Sendable, Identifiable {
|
||
public let id: String
|
||
public let normalizedName: String
|
||
public let surfaceText: String
|
||
public let kind: RDAIEntityKind
|
||
public let confidence: Double
|
||
public let locator: RDAILocator
|
||
}
|
||
```
|
||
|
||
Natural Language 的标签不是最终人物事实，只是 `RDAIEntityMention` 候选。
|
||
|
||
## 7. 索引 API
|
||
|
||
```swift
|
||
public enum RDAIIndexState: Equatable, Sendable {
|
||
case notStarted
|
||
case indexing(completedResources: Int, totalResources: Int)
|
||
case paused
|
||
case ready
|
||
case failed(RDAIError)
|
||
}
|
||
|
||
public struct RDAIIndexOptions: Sendable {
|
||
public var scope: RDAIReadScope
|
||
public var priorityResource: RDAIResourceIdentifier?
|
||
public var allowsEmbeddingAssetDownload: Bool
|
||
}
|
||
|
||
public protocol RDAIIndexing: AnyObject, Sendable {
|
||
func prepareIndex(options: RDAIIndexOptions) async throws
|
||
func pauseIndexing() async
|
||
func resumeIndexing() async
|
||
func indexState() async -> RDAIIndexState
|
||
func stateUpdates() async -> AsyncStream<RDAIIndexState>
|
||
func removeIndex() async throws
|
||
}
|
||
```
|
||
|
||
要求：
|
||
|
||
- `prepareIndex` 幂等。
|
||
- 重复调用只能扩大范围或提高优先级，不能创建重复 Job。
|
||
- `removeIndex` 删除索引、实体和生成缓存，但不删除原书或用户笔记。
|
||
|
||
## 8. 能力与可用性
|
||
|
||
```swift
|
||
public enum RDAICapability: String, Codable, Sendable {
|
||
case languageAnalysis
|
||
case entityExtraction
|
||
case lexicalSearch
|
||
case semanticSearch
|
||
case summarization
|
||
case questionAnswering
|
||
case characterRelationships
|
||
}
|
||
|
||
public enum RDAIUnavailableReason: Equatable, Sendable {
|
||
case operatingSystemUnsupported
|
||
case deviceNotEligible
|
||
case appleIntelligenceNotEnabled
|
||
case modelNotReady
|
||
case languageUnsupported(String?)
|
||
case embeddingAssetsUnavailable
|
||
case providerNotInstalled
|
||
case unknown(String)
|
||
}
|
||
|
||
public enum RDAICapabilityAvailability: Equatable, Sendable {
|
||
case available
|
||
case degraded(reason: RDAIUnavailableReason)
|
||
case unavailable(reason: RDAIUnavailableReason)
|
||
}
|
||
|
||
public protocol RDAICapabilityProviding: Sendable {
|
||
func availability(
|
||
for capability: RDAICapability,
|
||
locale: Locale?
|
||
) async -> RDAICapabilityAvailability
|
||
}
|
||
```
|
||
|
||
UI 只能根据枚举状态展示文案，不能匹配本地化 Error 字符串。
|
||
|
||
## 9. 检索 API
|
||
|
||
```swift
|
||
public struct RDAIRetrievalOptions: Sendable {
|
||
public var maximumResults: Int
|
||
public var scope: RDAIReadScope
|
||
public var minimumScore: Double
|
||
}
|
||
|
||
public struct RDAIRetrievalMatch: Sendable, Identifiable {
|
||
public let id: String
|
||
public let passage: RDAIPassage
|
||
public let score: Double
|
||
public let lexicalScore: Double?
|
||
public let semanticScore: Double?
|
||
}
|
||
|
||
public protocol RDAIRetrieving: Sendable {
|
||
func retrieve(
|
||
query: String,
|
||
options: RDAIRetrievalOptions
|
||
) async throws -> [RDAIRetrievalMatch]
|
||
}
|
||
```
|
||
|
||
检索分数只用于同一索引版本内排序，不承诺跨版本数值稳定。
|
||
|
||
## 10. 生成结果
|
||
|
||
### 10.1 摘要
|
||
|
||
```swift
|
||
public enum RDAISummaryLength: String, Codable, Sendable {
|
||
case brief
|
||
case standard
|
||
case detailed
|
||
}
|
||
|
||
public struct RDAISummary: Codable, Sendable {
|
||
public let title: String
|
||
public let overview: String
|
||
public let keyPoints: [RDAISourcedStatement]
|
||
public let citations: [RDAICitation]
|
||
public let metadata: RDAIGenerationMetadata
|
||
}
|
||
```
|
||
|
||
### 10.2 问答
|
||
|
||
```swift
|
||
public enum RDAIAnswerStatus: String, Codable, Sendable {
|
||
case answered
|
||
case insufficientEvidence
|
||
case unsupportedLanguage
|
||
case unavailable
|
||
}
|
||
|
||
public struct RDAIAnswer: Codable, Sendable {
|
||
public let status: RDAIAnswerStatus
|
||
public let text: String
|
||
public let statements: [RDAISourcedStatement]
|
||
public let citations: [RDAICitation]
|
||
public let metadata: RDAIGenerationMetadata
|
||
}
|
||
|
||
public struct RDAISourcedStatement: Codable, Sendable, Identifiable {
|
||
public let id: String
|
||
public let text: String
|
||
public let citationIdentifiers: [String]
|
||
}
|
||
```
|
||
|
||
### 10.3 人物关系
|
||
|
||
```swift
|
||
public enum RDAIRelationshipStatus: String, Codable, Sendable {
|
||
case confirmed
|
||
case possible
|
||
case conflicting
|
||
}
|
||
|
||
public struct RDAICharacter: Codable, Sendable, Identifiable {
|
||
public let id: String
|
||
public let displayName: String
|
||
public let aliases: [String]
|
||
public let description: String
|
||
public let firstAppearance: RDAICitation?
|
||
public let evidence: [RDAICitation]
|
||
}
|
||
|
||
public struct RDAIRelationship: Codable, Sendable, Identifiable {
|
||
public let id: String
|
||
public let sourceCharacterIdentifier: String
|
||
public let targetCharacterIdentifier: String
|
||
public let label: String
|
||
public let status: RDAIRelationshipStatus
|
||
public let evidence: [RDAICitation]
|
||
}
|
||
```
|
||
|
||
### 10.4 生成元数据
|
||
|
||
```swift
|
||
public struct RDAIGenerationMetadata: Codable, Sendable {
|
||
public let providerIdentifier: String
|
||
public let modelVersion: String?
|
||
public let promptIdentifier: String
|
||
public let promptVersion: Int
|
||
public let generatedAt: Date
|
||
public let scopeHash: String
|
||
}
|
||
```
|
||
|
||
元数据用于缓存失效和问题追踪，不向普通用户展示内部 Prompt。
|
||
|
||
## 11. 高层服务
|
||
|
||
```swift
|
||
public protocol RDAIReaderServicing: AnyObject, Sendable {
|
||
func prepare(options: RDAIIndexOptions) async throws
|
||
|
||
func summarize(
|
||
scope: RDAIReadScope,
|
||
length: RDAISummaryLength
|
||
) async throws -> RDAISummary
|
||
|
||
func answer(
|
||
question: String,
|
||
scope: RDAIReadScope
|
||
) async throws -> RDAIAnswer
|
||
|
||
func characters(
|
||
scope: RDAIReadScope
|
||
) async throws -> [RDAICharacter]
|
||
|
||
func relationships(
|
||
scope: RDAIReadScope
|
||
) async throws -> [RDAIRelationship]
|
||
|
||
func removeAllAIData() async throws
|
||
}
|
||
```
|
||
|
||
建议具体实现为 actor。若用户开始新的同类请求，UI 层负责决定取消旧请求或并行；同一 Foundation Models session 不允许并行请求。
|
||
|
||
## 12. Provider 协议
|
||
|
||
```swift
|
||
public struct RDAIGenerationRequest: Sendable {
|
||
public let task: RDAIGenerationTask
|
||
public let userText: String?
|
||
public let passages: [RDAIPassage]
|
||
public let locale: Locale
|
||
public let scope: RDAIReadScope
|
||
}
|
||
|
||
public enum RDAIGenerationTask: Sendable {
|
||
case summary(RDAISummaryLength)
|
||
case answer
|
||
case characters
|
||
case relationships
|
||
}
|
||
|
||
public protocol RDAIGenerativeProvider: Sendable {
|
||
var identifier: String { get }
|
||
func availability(locale: Locale) async -> RDAICapabilityAvailability
|
||
func generate(_ request: RDAIGenerationRequest) async throws -> RDAIGeneratedArtifact
|
||
}
|
||
```
|
||
|
||
`RDAIGeneratedArtifact` 是 Core 内部或受控公共枚举，用于把 Provider 输出转换为第 10 节模型。Provider 不能直接保存结果或操作 Reader UI。
|
||
|
||
## 13. 错误模型
|
||
|
||
```swift
|
||
public enum RDAIError: Error, Equatable, Sendable {
|
||
case invalidDocument
|
||
case resourceUnavailable(RDAIResourceIdentifier)
|
||
case staleCitation
|
||
case indexingFailed(code: String)
|
||
case modelUnavailable(RDAIUnavailableReason)
|
||
case unsupportedLanguage(String?)
|
||
case contextLimitExceeded
|
||
case invalidGeneratedStructure
|
||
case invalidCitation
|
||
case insufficientEvidence
|
||
case cancelled
|
||
case storageFailure(code: String)
|
||
}
|
||
```
|
||
|
||
公共错误不携带原文或数据库底层错误字符串。内部错误映射为稳定 code，并通过本地诊断系统保存脱敏详情。
|
||
|
||
## 14. PDF Adapter
|
||
|
||
建议公开：
|
||
|
||
```swift
|
||
public extension RDPDFReaderViewController {
|
||
func makeAIContentProvider() -> RDPDFAIContentProvider
|
||
func makeAIReaderService(
|
||
configuration: RDAIReaderConfiguration = .default
|
||
) throws -> RDAIReaderServicing
|
||
}
|
||
```
|
||
|
||
映射要求：
|
||
|
||
- 页面资源 ID 为十进制页索引。
|
||
- 文本顺序使用 `RDPDFReaderTextRun.readingOrder`。
|
||
- `normalizedRects` 转换为 `RDAINormalizedRect`。
|
||
- 原生文本标记为 `.native`，Vision OCR 标记为 `.ocr`。
|
||
- AI 高亮复用或泛化现有 speech highlight，不同时维护两个相互覆盖的临时层。
|
||
|
||
## 15. EPUB Adapter
|
||
|
||
建议公开：
|
||
|
||
```swift
|
||
public extension RDEPUBReaderController {
|
||
func makeAIContentProvider() -> RDEPUBAIContentProvider
|
||
func makeAIReaderService(
|
||
configuration: RDAIReaderConfiguration = .default
|
||
) throws -> RDAIReaderServicing
|
||
}
|
||
```
|
||
|
||
映射要求：
|
||
|
||
- 资源 ID 使用 ResourceResolver 规范化后的 `href`。
|
||
- Passage 范围从章节 attributed content 的原始字符串计算。
|
||
- 使用现有 index table 生成 `cfi` 和 `rangeCFI`。
|
||
- 导航复用 `go(to:)`/位置恢复流程。
|
||
- 固定版式或无法提取文本的章节返回明确 unavailable，不制造空 Passage。
|
||
|
||
## 16. TTS 集成
|
||
|
||
AI 层不依赖 RDSpeechReaderView。宿主可以把摘要或回答转换为临时 `RDSpeechContentProvider`。
|
||
|
||
后续可增加桥接 Pod：
|
||
|
||
```ruby
|
||
pod 'RDSpeechReaderView/AI'
|
||
```
|
||
|
||
桥接只负责朗读 AI 结果；Natural Language 的分句与语言识别实现应抽取为共享内部组件，避免同一文本产生不同范围。
|
||
|
||
## 17. 配置
|
||
|
||
```swift
|
||
public struct RDAIReaderConfiguration: Sendable {
|
||
public var spoilerPolicy: RDAISpoilerPolicy
|
||
public var maximumRetrievedPassages: Int
|
||
public var allowsEmbeddingAssetDownload: Bool
|
||
public var storesGeneratedArtifacts: Bool
|
||
public var diagnosticsLevel: RDAIDiagnosticsLevel
|
||
|
||
public static let `default`: RDAIReaderConfiguration
|
||
}
|
||
```
|
||
|
||
默认值：
|
||
|
||
- `spoilerPolicy = .readContentOnly`
|
||
- `maximumRetrievedPassages = 4`
|
||
- `allowsEmbeddingAssetDownload = false`
|
||
- `storesGeneratedArtifacts = true`
|
||
- `diagnosticsLevel = .metadataOnly`
|
||
|
||
## 18. API 演进规则
|
||
|
||
- 1.0 前可以调整命名，但每次调整同步更新五份设计文档。
|
||
- 1.0 后删除或改变语义需要主版本升级。
|
||
- Codable 枚举新增 case 时必须实现向后兼容策略。
|
||
- 数据库 Schema 版本与 SDK 版本独立。
|
||
- Prompt 版本与 SDK 版本独立。
|
||
- Reader Adapter 可以增加格式能力，但不能改变 Core Locator 的 UTF-16 语义。
|
||
|