docs: 补充注释、修正过时文档、清理重复内容

源码注释：
- 为 ~60 个 Swift 文件补充缺失的 doc comment（file header、类型、属性、方法）
- 修正 4 处错误注释：翻页模式数量、搜索行为描述、手势识别器描述、悬空文档块

文档维护：
- 删除重复文档：WXRead/读书EPUB阅读器实现架构.md（与微信读书版完全一致）
- 合并重叠文档：阅读器规划.md → 阅读器功能开发计划.md（单一真值）
- 修正过时内容：所有文档中"四种翻页模式"→"三种"，移除 horizontalCoverScroll
- 更新架构图：补齐 EPUBUI/ReaderController、Paging/、Typesetter/ 等子目录
- 更新 index.md 索引：新增开发计划和架构对比文档引用

Sources/RDReaderView/EPUBUI/ReaderController/RDEPUBReaderAnnotationCoordinator.swift

@@ -1,5 +1,12 @@
 import UIKit
 
+/// EPUB 阅读器标注协调器：负责高亮、批注和书签的增删改查操作。
+///
+/// 职责：
+/// - 管理高亮（highlight）与批注（annotation）的创建、更新和删除
+/// - 管理书签（bookmark）的添加、切换和删除
+/// - 处理文本选中后的菜单操作（复制、高亮、批注）
+/// - 弹出高亮管理器和书签管理器界面
 final class RDEPUBReaderAnnotationCoordinator {
     private unowned let context: RDEPUBReaderContext
 
@@ -11,16 +18,19 @@ final class RDEPUBReaderAnnotationCoordinator {
         context.controller
     }
 
+    /// 根据 ID 查找书签。
     func bookmark(withID id: String) -> RDEPUBBookmark? {
         guard let controller else { return nil }
         return controller.activeBookmarks.first { $0.id == id }
     }
 
+    /// 根据 ID 查找高亮。
     func highlight(withID id: String) -> RDEPUBHighlight? {
         guard let controller else { return nil }
         return controller.activeHighlights.first { $0.id == id }
     }
 
+    /// 更新当前文本选区状态，并同步刷新底部工具栏的高亮按钮可用性。
     func updateCurrentSelection(_ selection: RDEPUBSelection?) {
         guard let controller else { return }
         controller.currentSelection = selection?.isEmpty == false ? selection : nil
@@ -34,6 +44,7 @@ final class RDEPUBReaderAnnotationCoordinator {
         controller.delegate?.epubReader(controller, didChangeSelection: controller.currentSelection)
     }
 
+    /// 基于当前选区添加高亮标记，自动去重并持久化。
     @discardableResult
     func addHighlight(
         from selection: RDEPUBSelection? = nil,
@@ -43,6 +54,7 @@ final class RDEPUBReaderAnnotationCoordinator {
         addAnnotation(from: selection, style: .highlight, color: color, note: note)
     }
 
+    /// 基于选区创建标注（高亮/划线/批注），支持指定样式、颜色和备注。
     @discardableResult
     func addAnnotation(
         from selection: RDEPUBSelection? = nil,
@@ -85,6 +97,7 @@ final class RDEPUBReaderAnnotationCoordinator {
         return newHighlight
     }
 
+    /// 插入或更新高亮（upsert），按 ID 匹配已有记录。
     @discardableResult
     func upsertHighlight(_ highlight: RDEPUBHighlight) -> RDEPUBHighlight? {
         guard let controller else { return nil }
@@ -101,6 +114,7 @@ final class RDEPUBReaderAnnotationCoordinator {
         return scopedHighlight
     }
 
+    /// 根据 ID 删除高亮并持久化。
     @discardableResult
     func removeHighlight(id: String) -> RDEPUBHighlight? {
         guard let controller else { return nil }
@@ -112,6 +126,7 @@ final class RDEPUBReaderAnnotationCoordinator {
         return removed
     }
 
+    /// 更新指定高亮的批注备注内容。
     @discardableResult
     func updateHighlightNote(id: String, note: String?) -> RDEPUBHighlight? {
         guard let controller else { return nil }
@@ -123,6 +138,7 @@ final class RDEPUBReaderAnnotationCoordinator {
         return controller.activeHighlights[index]
     }
 
+    /// 跳转到指定高亮所在位置。
     @discardableResult
     func go(toHighlightID id: String, animated: Bool = true) -> Bool {
         guard let controller else { return false }
@@ -132,6 +148,7 @@ final class RDEPUBReaderAnnotationCoordinator {
         return controller.restoreReadingLocation(highlight.location, animated: animated)
     }
 
+    /// 清除所有高亮标记。
     func removeAllHighlights() {
         guard let controller else { return }
         guard !controller.activeHighlights.isEmpty else { return }
@@ -139,6 +156,7 @@ final class RDEPUBReaderAnnotationCoordinator {
         persistHighlightsAndRefreshContent()
     }
 
+    /// 将选区位置相对于指定 spine 索引进行规范化。
     func scopedSelection(
         _ selection: RDEPUBSelection,
         relativeToSpineIndex spineIndex: Int?
@@ -166,6 +184,7 @@ final class RDEPUBReaderAnnotationCoordinator {
         )
     }
 
+    /// 弹出高亮管理器，支持查看、编辑备注和删除高亮。
     func presentHighlightsManager() {
         guard let controller else { return }
         guard controller.configuration.allowsHighlights else { return }
@@ -196,6 +215,7 @@ final class RDEPUBReaderAnnotationCoordinator {
         controller.present(navigationController, animated: true)
     }
 
+    /// 弹出标注创建面板（高亮/划线/批注选择）。
     func presentAnnotationCreation() {
         guard let controller else { return }
         guard controller.configuration.allowsHighlights,
@@ -205,6 +225,7 @@ final class RDEPUBReaderAnnotationCoordinator {
         presentAnnotationActionSheet(for: currentSelection)
     }
 
+    /// 处理文本选中后的菜单操作：复制、高亮、批注。
     func handleSelectionMenuAction(_ action: RDEPUBAnnotationMenuAction, selection: RDEPUBSelection?) {
         guard let selection else { return }
         switch action {
@@ -218,6 +239,7 @@ final class RDEPUBReaderAnnotationCoordinator {
         }
     }
 
+    /// 在当前位置添加书签，自动去重。
     @discardableResult
     func addBookmark(note: String? = nil) -> RDEPUBBookmark? {
         guard let controller else { return nil }
@@ -239,6 +261,7 @@ final class RDEPUBReaderAnnotationCoordinator {
         return newBookmark
     }
 
+    /// 切换当前位置的书签状态：已存在则移除，不存在则添加。
     @discardableResult
     func toggleBookmark(note: String? = nil) -> RDEPUBBookmark? {
         guard let controller else { return nil }
@@ -254,6 +277,7 @@ final class RDEPUBReaderAnnotationCoordinator {
         return addBookmark(note: note)
     }
 
+    /// 根据 ID 删除书签并持久化。
     @discardableResult
     func removeBookmark(id: String) -> RDEPUBBookmark? {
         guard let controller else { return nil }
@@ -265,6 +289,7 @@ final class RDEPUBReaderAnnotationCoordinator {
         return removed
     }
 
+    /// 跳转到指定书签所在位置。
     @discardableResult
     func go(toBookmarkID id: String, animated: Bool = true) -> Bool {
         guard let controller else { return false }
@@ -274,12 +299,14 @@ final class RDEPUBReaderAnnotationCoordinator {
         return controller.restoreReadingLocation(bookmark.location, animated: animated)
     }
 
+    /// 同步顶部书签按钮和底部书签列表按钮的 UI 状态。
     func updateBookmarkChrome() {
         guard let controller else { return }
         controller.topToolView.setBookmarkSelected(currentBookmark() != nil)
         controller.bottomToolView.setBookmarksEnabled(!controller.activeBookmarks.isEmpty)
     }
 
+    /// 弹出书签管理器，支持查看、跳转和删除书签。
     func presentBookmarksManager() {
         guard let controller else { return }
         guard !controller.activeBookmarks.isEmpty else { return }

Sources/RDReaderView/EPUBUI/ReaderController/RDEPUBReaderAssemblyCoordinator.swift

@@ -1,5 +1,11 @@
 import UIKit
 
+/// EPUB 阅读器界面组装协调器：负责阅读器初次启动时的 UI 搭建。
+///
+/// 职责：
+/// - 组装阅读器视图层次结构（readerView、loadingIndicator、errorLabel）
+/// - 注册内容视图类型
+/// - 处理外部纯文本图书的启动收尾逻辑
 final class RDEPUBReaderAssemblyCoordinator {
     private unowned let context: RDEPUBReaderContext
 
@@ -7,6 +13,7 @@ final class RDEPUBReaderAssemblyCoordinator {
         self.context = context
     }
 
+    /// 组装阅读器界面：添加 readerView、loadingIndicator、errorLabel 到控制器视图，并配置顶部工具栏。
     func assembleInterface() {
         guard let controller = context.controller,
               let readerView = context.readerView else { return }
@@ -18,6 +25,7 @@ final class RDEPUBReaderAssemblyCoordinator {
         controller.delegate?.epubReader(controller, configureTopToolView: controller.topToolView)
     }
 
+    /// 外部纯文本图书启动时，加载已保存的书签、高亮和阅读位置，完成分页收尾。
     func finishExternalTextBookLaunchIfNeeded() {
         guard let runtime = context.runtime,
               context.isExternalTextBook else {

Sources/RDReaderView/EPUBUI/ReaderController/RDEPUBReaderChromeCoordinator.swift

@@ -1,5 +1,13 @@
 import UIKit
 
+/// EPUB 阅读器 Chrome 协调器：负责顶部/底部工具栏的创建、更新和交互处理。
+///
+/// 职责：
+/// - 创建并配置顶部工具栏（返回、书签按钮）
+/// - 创建并配置底部工具栏（目录、书签、高亮、设置按钮）
+/// - 同步工具栏的主题和状态
+/// - 弹出设置面板和目录面板
+/// - 处理返回按钮的关闭逻辑
 final class RDEPUBReaderChromeCoordinator {
     private unowned let context: RDEPUBReaderContext
 
@@ -11,6 +19,7 @@ final class RDEPUBReaderChromeCoordinator {
         context.controller
     }
 
+    /// 创建顶部工具栏视图，绑定返回和书签切换回调。
     func makeTopToolView() -> RDEPUBReaderTopToolView {
         let toolView = RDEPUBReaderTopToolView()
         toolView.onBack = { [weak self] in
@@ -22,6 +31,7 @@ final class RDEPUBReaderChromeCoordinator {
         return toolView
     }
 
+    /// 创建底部工具栏视图，绑定目录、书签、高亮、设置等回调。
     func makeBottomToolView() -> RDEPUBReaderBottomToolView {
         let toolView = RDEPUBReaderBottomToolView()
         toolView.onShowTableOfContents = { [weak self] in
@@ -42,6 +52,7 @@ final class RDEPUBReaderChromeCoordinator {
         return toolView
     }
 
+    /// 同步更新顶部和底部工具栏的主题、标题、按钮可用性等状态。
     func updateReaderChrome() {
         guard let controller else { return }
         controller.topToolView.apply(theme: controller.configuration.theme)
@@ -67,6 +78,7 @@ final class RDEPUBReaderChromeCoordinator {
         controller.updateBookmarkChrome()
     }
 
+    /// 弹出阅读设置面板（字号、字体、行距、分栏、主题、亮度等）。
     func presentSettings() {
         guard let controller else { return }
         guard controller.configuration.showsSettingsPanel else { return }
@@ -101,6 +113,7 @@ final class RDEPUBReaderChromeCoordinator {
         controller.present(navigationController, animated: true)
     }
 
+    /// 弹出目录列表面板，支持点击跳转到指定章节。
     func presentTableOfContents() {
         guard let controller else { return }
         guard controller.configuration.showsTableOfContents else { return }
@@ -124,6 +137,7 @@ final class RDEPUBReaderChromeCoordinator {
         controller.present(navigationController, animated: true)
     }
 
+    /// 处理返回按钮点击，自动判断 pop 或 dismiss 方式关闭阅读器。
     func handleBackAction() {
         guard let controller else { return }
         close(controller)

Sources/RDReaderView/EPUBUI/ReaderController/RDEPUBReaderContext.swift

@@ -11,37 +11,61 @@ import UIKit
 final class RDEPUBReaderContext {
     // MARK: - 引用
 
+    /// 弱引用阅读器控制器，用于 UIKit 呈现操作。
     weak var controller: RDEPUBReaderController?
+    /// 弱引用阅读器视图，用于布局和页面状态查询。
     weak var readerView: RDReaderView?
+    /// 依赖注入容器，提供解析器、分页器等工厂方法。
     var dependencies: RDEPUBReaderDependencies = .live
+    /// 便捷访问当前控制器的运行时协调器集合。
     var runtime: RDEPUBReaderRuntime? {
         controller?.runtime
     }
 
     // MARK: - 业务状态
 
+    /// EPUB 解析器实例。
     var parser: RDEPUBParser?
+    /// 解析后的出版物模型。
     var publication: RDEPUBPublication?
+    /// 当前阅读会话，管理页面和章节状态。
     var readingSession: RDEPUBReadingSession?
+    /// 原生文本排版生成的图书模型（仅文本重排模式）。
     var textBook: RDEPUBTextBook?
+    /// 当前书籍的所有书签。
     var activeBookmarks: [RDEPUBBookmark] = []
+    /// 当前书籍的所有高亮标注。
     var activeHighlights: [RDEPUBHighlight] = []
+    /// 当前打开书籍的唯一标识。
     var currentBookIdentifier: String?
+    /// 分页操作令牌，用于取消过期的异步分页任务。
     var paginationToken = UUID()
+    /// Web 内容分页计算器。
     var paginator: RDEPUBPaginator?
+    /// 全文搜索状态。
     var searchState: RDEPUBSearchState?
+    /// 上次文本分页时的页面尺寸，用于检测是否需要重新分页。
     var lastTextPaginationPageSize: CGSize?
+    /// 当前用户文本选区。
     var currentSelection: RDEPUBSelection?
 
     // MARK: - 控制器状态（从 controller 下沉）
 
+    /// 阅读器配置（字号、字体、主题等）。
     var configuration: RDEPUBReaderConfiguration = .default
+    /// 持久化策略，负责书签、高亮、阅读位置的存取。
     var persistence: RDEPUBReaderPersistence?
+    /// 当前打开的 EPUB 文件 URL。
     var epubURL: URL = URL(string: "about:blank")!
+    /// 是否正在重新分页。
     var isRepaginating: Bool = false
+    /// 是否已完成首次加载。
     var didStartInitialLoad: Bool = false
+    /// 是否为外部传入的纯文本图书。
     var isExternalTextBook: Bool = false
+    /// 外部纯文本文件的 URL。
     var textFileURL: URL?
+    /// 文本图书缓存，避免重复排版。
     var textBookCache = RDEPUBTextBookCache()
 
     // MARK: - 初始化
@@ -53,6 +77,7 @@ final class RDEPUBReaderContext {
 
     // MARK: - 便捷方法
 
+    /// 根据当前 readerView 和控制器尺寸构建布局上下文。
     func currentLayoutContext() -> RDEPUBNavigatorLayoutContext {
         let containerSize = readerView?.bounds.size ?? .zero
         let viewSize = controller?.view.bounds.size ?? containerSize
@@ -66,10 +91,12 @@ final class RDEPUBReaderContext {
         )
     }
 
+    /// 根据当前配置生成阅读偏好设置。
     func currentPreferences() -> RDEPUBPreferences {
         configuration.makePreferences()
     }
 
+    /// 获取当前文本排版的单页尺寸，优先从 readerView 解析，兜底用布局上下文。
     func currentTextPageSize() -> CGSize {
         let pageNum = (readerView?.currentPage ?? -1) >= 0 ? readerView?.currentPage : nil
         if let readerView, let pageNum {
@@ -81,6 +108,7 @@ final class RDEPUBReaderContext {
         return currentLayoutContext().viewportSize
     }
 
+    /// 根据当前配置生成文本渲染样式（字体、行距、颜色）。
     func currentTextRenderStyle() -> RDEPUBTextRenderStyle {
         let font = configuration.fontChoice.font(ofSize: configuration.fontSize)
         let lineSpacing = max(font.lineHeight * (configuration.lineHeightMultiple - 1), 4)
@@ -92,6 +120,7 @@ final class RDEPUBReaderContext {
         )
     }
 
+    /// 根据页面尺寸和配置生成文本排版参数。
     func currentTextLayoutConfig(pageSize: CGSize) -> RDEPUBTextLayoutConfig {
         return RDEPUBTextLayoutConfig(
             frameWidth: max(pageSize.width, 1),
@@ -108,61 +137,75 @@ final class RDEPUBReaderContext {
         )
     }
 
+    /// 获取当前配置对应的文本渲染器实例。
     func resolvedTextRenderer() -> RDEPUBTextRenderer {
         dependencies.makeTextRenderer(configuration.textRenderingEngine)
     }
 
+    /// 当前活跃的页面列表。
     var activePages: [EPUBPage] {
         readingSession?.activePages ?? []
     }
 
+    /// 当前活跃的章节信息列表。
     var activeChapters: [EPUBChapterInfo] {
         readingSession?.activeChapters ?? []
     }
 
+    /// 屏幕亮度代理属性，读写均转发给系统环境。
     var currentBrightness: CGFloat {
         get { dependencies.environment.currentBrightness }
         set { dependencies.environment.currentBrightness = newValue }
     }
 
+    /// 用新快照替换当前活跃的分页快照。
     func replaceActiveSnapshot(_ snapshot: RDEPUBReadingSession.PaginationSnapshot) {
         readingSession?.setActiveSnapshot(snapshot)
     }
 
+    /// 清除当前活跃快照，重置运行时状态。
     func clearActiveSnapshot() {
         readingSession?.resetRuntimeState()
     }
 
+    /// 工厂方法：创建 EPUB 解析器。
     func makeParser() -> RDEPUBParser {
         dependencies.makeParser()
     }
 
+    /// 工厂方法：创建 Web 内容分页计算器。
     func makePaginator() -> RDEPUBPaginator {
         dependencies.makePaginator()
     }
 
+    /// 工厂方法：创建 EPUB 文本图书构建器。
     func makeTextBookBuilder(layoutConfig: RDEPUBTextLayoutConfig) -> RDEPUBTextBookBuilder {
         dependencies.makeTextBookBuilder(resolvedTextRenderer(), textBookCache, layoutConfig)
     }
 
+    /// 工厂方法：创建纯文本图书构建器。
     func makePlainTextBookBuilder(layoutConfig: RDEPUBTextLayoutConfig) -> RDPlainTextBookBuilder {
         dependencies.makePlainTextBookBuilder(resolvedTextRenderer(), layoutConfig)
     }
 
+    /// 获取当前可见页面的阅读位置。
     func currentVisibleLocation() -> RDEPUBLocation? {
         controller?.currentVisibleLocation()
     }
 
+    /// 从持久化存储加载上次保存的阅读位置。
     func persistenceLocation() -> RDEPUBLocation? {
         guard let currentBookIdentifier else { return nil }
         return persistence?.loadLocation(for: currentBookIdentifier)
     }
 
+    /// 将阅读位置持久化到存储。
     func persist(location: RDEPUBLocation) {
         guard let currentBookIdentifier else { return }
         persistence?.saveLocation(location, for: currentBookIdentifier)
     }
 
+    /// 根据规范化 href 获取文本章节数据。
     func textChapterData(forNormalizedHref href: String) -> RDEPUBChapterData? {
         guard let textBook, let publication else { return nil }
         let normalizedHref = publication.resourceResolver.normalizedHref(href) ?? href
@@ -171,38 +214,47 @@ final class RDEPUBReaderContext {
             .flatMap { textBook.chapterData(for: $0.href) }
     }
 
+    /// 显示加载指示器。
     func showLoading() {
         controller?.showLoading()
     }
 
+    /// 隐藏加载指示器。
     func hideLoading() {
         controller?.hideLoading()
     }
 
+    /// 将错误转发给控制器处理。
     func handle(error: Error) {
         controller?.handle(error: error)
     }
 
+    /// 触发工具栏状态更新。
     func updateReaderChrome() {
         controller?.updateReaderChrome()
     }
 
+    /// 刷新可见内容并保持当前阅读位置不变。
     func refreshVisibleContentPreservingLocation() {
         controller?.refreshVisibleContentPreservingLocation()
     }
 
+    /// 恢复到指定阅读位置。
     func restoreReadingLocation(_ location: RDEPUBLocation, animated: Bool = false) -> Bool {
         controller?.restoreReadingLocation(location, animated: animated) ?? false
     }
 
+    /// 重新分页并保持当前阅读位置。
     func repaginatePreservingCurrentLocation() {
         controller?.repaginatePreservingCurrentLocation()
     }
 
+    /// 将当前配置应用到阅读器视图。
     func applyReaderViewConfiguration() {
         controller?.applyReaderViewConfiguration()
     }
 
+    /// 同步书签按钮的 UI 状态。
     func updateBookmarkChrome() {
         controller?.updateBookmarkChrome()
     }

Sources/RDReaderView/EPUBUI/ReaderController/RDEPUBReaderDependencies.swift

@@ -1,10 +1,17 @@
+// RDEPUBReaderDependencies.swift
+// EPUB 阅读器依赖注入配置，定义显示环境协议与核心组件工厂
+
 import UIKit
 
+/// 阅读器显示环境协议，抽象屏幕亮度和视口尺寸以支持测试和多平台适配
 public protocol RDEPUBReaderDisplayEnvironment: AnyObject {
+    /// 当前屏幕亮度，取值范围 0.0 ~ 1.0
     var currentBrightness: CGFloat { get set }
+    /// 后备视口尺寸，用于无法获取实际视图尺寸时的布局计算
     var fallbackViewportSize: CGSize { get }
 }
 
+/// 基于 UIScreen 的默认显示环境实现，直接读写系统屏幕亮度
 public final class RDEPUBUIScreenEnvironment: RDEPUBReaderDisplayEnvironment {
     public init() {}
 
@@ -18,14 +25,29 @@ public final class RDEPUBUIScreenEnvironment: RDEPUBReaderDisplayEnvironment {
     }
 }
 
+/// EPUB 阅读器核心依赖容器，通过工厂闭包注入各组件以便替换和测试
 public struct RDEPUBReaderDependencies {
+    /// 显示环境实例
     public var environment: any RDEPUBReaderDisplayEnvironment
+    /// EPUB 解析器工厂
     public var makeParser: () -> RDEPUBParser
+    /// 分页器工厂
     public var makePaginator: () -> RDEPUBPaginator
+    /// 富文本书籍构建器工厂
     public var makeTextBookBuilder: (RDEPUBTextRenderer, RDEPUBTextBookCache?, RDEPUBTextLayoutConfig) -> RDEPUBTextBookBuilder
+    /// 纯文本书籍构建器工厂
     public var makePlainTextBookBuilder: (RDEPUBTextRenderer, RDEPUBTextLayoutConfig) -> RDPlainTextBookBuilder
+    /// 文本渲染器工厂
     public var makeTextRenderer: (RDEPUBTextRenderingEngine) -> RDEPUBTextRenderer
 
+    /// 初始化依赖容器
+    /// - Parameters:
+    ///   - environment: 显示环境实例
+    ///   - makeParser: EPUB 解析器工厂闭包
+    ///   - makePaginator: 分页器工厂闭包
+    ///   - makeTextBookBuilder: 富文本书籍构建器工厂闭包
+    ///   - makePlainTextBookBuilder: 纯文本书籍构建器工厂闭包
+    ///   - makeTextRenderer: 文本渲染器工厂闭包
     public init(
         environment: any RDEPUBReaderDisplayEnvironment,
         makeParser: @escaping () -> RDEPUBParser,
@@ -42,6 +64,7 @@ public struct RDEPUBReaderDependencies {
         self.makeTextRenderer = makeTextRenderer
     }
 
+    /// 默认生产环境依赖，使用系统屏幕环境和标准组件实现
     public static var live: RDEPUBReaderDependencies {
         RDEPUBReaderDependencies(
             environment: RDEPUBUIScreenEnvironment(),

Sources/RDReaderView/EPUBUI/ReaderController/RDEPUBReaderLoadCoordinator.swift

@@ -1,5 +1,11 @@
 import Foundation
 
+/// EPUB 阅读器加载协调器：负责 EPUB 文件的解析和出版物初始化。
+///
+/// 职责：
+/// - 判断是否需要执行首次加载
+/// - 后台解析 EPUB 文件并构建 Publication 模型
+/// - 将解析结果应用到阅读器上下文并触发分页
 final class RDEPUBReaderLoadCoordinator {
     private unowned let context: RDEPUBReaderContext
 
@@ -7,6 +13,7 @@ final class RDEPUBReaderLoadCoordinator {
         self.context = context
     }
 
+    /// 检查条件后启动首次加载，确保只执行一次且视图已布局。
     func startInitialLoadIfNeeded() {
         guard let controller = context.controller,
               let readerView = context.readerView,
@@ -19,6 +26,7 @@ final class RDEPUBReaderLoadCoordinator {
         loadPublication()
     }
 
+    /// 后台解析 EPUB 文件，加载书签、高亮和阅读位置，完成后回调主线程。
     func loadPublication() {
         guard let controller = context.controller else { return }
         context.showLoading()
@@ -57,6 +65,7 @@ final class RDEPUBReaderLoadCoordinator {
         }
     }
 
+    /// 将解析完成的出版物应用到上下文，设置书签/高亮/会话，并触发分页。
     func applyParsedPublication(
         parser: RDEPUBParser,
         publication: RDEPUBPublication,

Sources/RDReaderView/EPUBUI/ReaderController/RDEPUBReaderLocationCoordinator.swift

@@ -1,5 +1,12 @@
 import Foundation
 
+/// EPUB 阅读器位置协调器：负责阅读位置的恢复、查询和持久化。
+///
+/// 职责：
+/// - 根据保存的位置恢复阅读进度
+/// - 获取当前可见页面的阅读位置
+/// - 从持久化存储加载已保存位置
+/// - 持久化当前位置并通知委托
 final class RDEPUBReaderLocationCoordinator {
     private unowned let context: RDEPUBReaderContext
 
@@ -7,6 +14,7 @@ final class RDEPUBReaderLocationCoordinator {
         self.context = context
     }
 
+    /// 恢复到指定阅读位置，返回是否成功跳转。
     @discardableResult
     func restoreReadingLocation(_ location: RDEPUBLocation, animated: Bool = false) -> Bool {
         guard let controller = context.controller,
@@ -30,6 +38,7 @@ final class RDEPUBReaderLocationCoordinator {
         return true
     }
 
+    /// 获取当前可见页面对应的阅读位置。
     func currentVisibleLocation() -> RDEPUBLocation? {
         guard let controller = context.controller,
               let readerView = context.readerView else {
@@ -41,6 +50,7 @@ final class RDEPUBReaderLocationCoordinator {
         return context.readingSession?.currentReadingLocation(bookIdentifier: context.currentBookIdentifier)
     }
 
+    /// 从持久化存储加载上次保存的阅读位置。
     func persistenceLocation() -> RDEPUBLocation? {
         guard let controller = context.controller,
               let currentBookIdentifier = context.currentBookIdentifier else {
@@ -49,6 +59,7 @@ final class RDEPUBReaderLocationCoordinator {
         return controller.persistence?.loadLocation(for: currentBookIdentifier)
     }
 
+    /// 持久化阅读位置，并通知委托更新目录项和书签状态。
     func persist(location: RDEPUBLocation) {
         guard let controller = context.controller,
               let currentBookIdentifier = context.currentBookIdentifier else { return }

Sources/RDReaderView/EPUBUI/ReaderController/RDEPUBReaderPaginationCoordinator.swift

@@ -1,5 +1,13 @@
 import Foundation
 
+/// EPUB 阅读器分页协调器：负责出版物的分页计算和页面数据更新。
+///
+/// 职责：
+/// - 根据出版物类型（文本重排/Fixed Layout/Web 内容）选择分页策略
+/// - 后台构建文本图书模型并应用分页快照
+/// - 重新分页时保持当前阅读位置
+/// - 刷新可见内容并保持位置
+/// - 重建外部纯文本图书
 final class RDEPUBReaderPaginationCoordinator {
     private unowned let context: RDEPUBReaderContext
 
@@ -7,6 +15,7 @@ final class RDEPUBReaderPaginationCoordinator {
         self.context = context
     }
 
+    /// 对出版物执行分页：文本重排走 TextBookBuilder，Fixed Layout 直接生成快照，Web 内容走 Paginator。
     func paginatePublication(restoreLocation: RDEPUBLocation?) {
         guard let controller = context.controller,
               let parser = context.parser,
@@ -79,6 +88,7 @@ final class RDEPUBReaderPaginationCoordinator {
         }
     }
 
+    /// 应用文本图书模型：生成分页快照并完成分页流程。
     func applyTextBook(_ textBook: RDEPUBTextBook, restoreLocation: RDEPUBLocation?) {
         guard let controller = context.controller else { return }
         context.textBook = textBook
@@ -93,6 +103,7 @@ final class RDEPUBReaderPaginationCoordinator {
         finishPagination(restoreLocation: restoreLocation)
     }
 
+    /// 应用分页快照（Fixed Layout 或 Web 内容），并完成分页流程。
     func applyPaginationSnapshot(
         _ snapshot: (pages: [EPUBPage], chapters: [EPUBChapterInfo]),
         restoreLocation: RDEPUBLocation?
@@ -109,6 +120,7 @@ final class RDEPUBReaderPaginationCoordinator {
         finishPagination(restoreLocation: restoreLocation)
     }
 
+    /// 分页完成后的收尾：刷新视图、恢复阅读位置、处理待定视口变更。
     func finishPagination(restoreLocation: RDEPUBLocation?) {
         guard let controller = context.controller,
               let readerView = context.readerView else { return }
@@ -125,6 +137,7 @@ final class RDEPUBReaderPaginationCoordinator {
         context.runtime?.viewportMonitor.processPendingChangeAfterPagination()
     }
 
+    /// 重新分页并保持当前阅读位置（优先使用待恢复位置，其次当前位置，最后持久化位置）。
     func repaginatePreservingCurrentLocation() {
         guard context.publication != nil else { return }
         let restoreLocation = context.runtime?.viewportMonitor.consumePendingPresentationRestoreLocation()
@@ -133,6 +146,7 @@ final class RDEPUBReaderPaginationCoordinator {
         paginatePublication(restoreLocation: restoreLocation)
     }
 
+    /// 刷新可见内容并保持当前阅读位置不变。
     func refreshVisibleContentPreservingLocation() {
         guard let readerView = context.readerView else { return }
         let restoreLocation = context.currentVisibleLocation() ?? context.persistenceLocation()
@@ -142,6 +156,7 @@ final class RDEPUBReaderPaginationCoordinator {
         }
     }
 
+    /// 重建外部纯文本图书（布局变更后重新排版）。
     func rebuildExternalTextBook() {
         guard let controller = context.controller,
               let textFileURL = controller.textFileURL else { return }

Sources/RDReaderView/EPUBUI/ReaderController/RDEPUBReaderRuntime.swift

@@ -1,5 +1,8 @@
 import UIKit
 
+/// EPUB 阅读器运行时总协调器。
+/// 统一持有并分发给加载、分页、定位、搜索、工具栏、批注、视口监测等子协调器，
+/// 作为阅读器控制器的门面（Facade），简化外部调用。
 final class RDEPUBReaderRuntime {
     private unowned let context: RDEPUBReaderContext
 
@@ -15,18 +18,22 @@ final class RDEPUBReaderRuntime {
         self.context = context
     }
 
+    /// 创建顶部工具栏视图
     func makeTopToolView() -> RDEPUBReaderTopToolView {
         chromeCoordinator.makeTopToolView()
     }
 
+    /// 创建底部工具栏视图
     func makeBottomToolView() -> RDEPUBReaderBottomToolView {
         chromeCoordinator.makeBottomToolView()
     }
 
+    /// 若尚未加载则启动首次加载流程
     func startInitialLoadIfNeeded() {
         loadCoordinator.startInitialLoadIfNeeded()
     }
 
+    /// 重新加载当前书籍，清空解析器、分页、批注等状态后从头初始化
     func reloadBook() {
         guard let readerView = context.readerView else { return }
         context.didStartInitialLoad = false
@@ -44,10 +51,20 @@ final class RDEPUBReaderRuntime {
         startInitialLoadIfNeeded()
     }
 
+    /// 跳转到指定阅读位置
+    /// - Parameters:
+    ///   - location: 目标位置
+    ///   - animated: 是否动画过渡
+    /// - Returns: 跳转是否成功
     func go(to location: RDEPUBLocation, animated: Bool = false) -> Bool {
         locationCoordinator.restoreReadingLocation(location, animated: animated)
     }
 
+    /// 跳转到指定页码
+    /// - Parameters:
+    ///   - pageNumber: 目标页码（从 1 开始）
+    ///   - animated: 是否动画过渡
+    /// - Returns: 跳转是否成功
     @discardableResult
     func go(toPageNumber pageNumber: Int, animated: Bool = false) -> Bool {
         guard let controller = context.controller,
@@ -73,6 +90,7 @@ final class RDEPUBReaderRuntime {
         return true
     }
 
+    /// 清除当前选区
     func clearSelection() {
         annotationCoordinator.updateCurrentSelection(nil)
     }
@@ -168,20 +186,24 @@ final class RDEPUBReaderRuntime {
         annotationCoordinator.handleSelectionMenuAction(action, selection: selection)
     }
 
+    /// 按关键词搜索全文
     func search(keyword: String) {
         searchCoordinator.search(keyword: keyword)
     }
 
+    /// 跳转到下一个搜索匹配项
     @discardableResult
     func searchNext() -> Bool {
         searchCoordinator.searchNext()
     }
 
+    /// 跳转到上一个搜索匹配项
     @discardableResult
     func searchPrevious() -> Bool {
         searchCoordinator.searchPrevious()
     }
 
+    /// 清除搜索状态
     func clearSearch() {
         searchCoordinator.clearSearch()
     }
@@ -190,26 +212,32 @@ final class RDEPUBReaderRuntime {
         searchCoordinator.searchPresentation(for: page)
     }
 
+    /// 更新阅读器工具栏显示状态
     func updateReaderChrome() {
         chromeCoordinator.updateReaderChrome()
     }
 
+    /// 弹出阅读设置面板
     func presentSettings() {
         chromeCoordinator.presentSettings()
     }
 
+    /// 弹出目录面板
     func presentTableOfContents() {
         chromeCoordinator.presentTableOfContents()
     }
 
+    /// 处理返回操作
     func handleBackAction() {
         chromeCoordinator.handleBackAction()
     }
 
+    /// 启动 Publication 加载流程
     func loadPublication() {
         loadCoordinator.loadPublication()
     }
 
+    /// 将已解析的 Publication 应用到控制器
     func applyParsedPublication(
         parser: RDEPUBParser,
         publication: RDEPUBPublication,
@@ -228,14 +256,17 @@ final class RDEPUBReaderRuntime {
         )
     }
 
+    /// 对 Publication 执行分页计算
     func paginatePublication(restoreLocation: RDEPUBLocation?) {
         paginationCoordinator.paginatePublication(restoreLocation: restoreLocation)
     }
 
+    /// 应用外部 TextBook 并恢复阅读位置
     func applyTextBook(_ textBook: RDEPUBTextBook, restoreLocation: RDEPUBLocation?) {
         paginationCoordinator.applyTextBook(textBook, restoreLocation: restoreLocation)
     }
 
+    /// 应用分页快照并恢复阅读位置
     func applyPaginationSnapshot(
         _ snapshot: (pages: [EPUBPage], chapters: [EPUBChapterInfo]),
         restoreLocation: RDEPUBLocation?
@@ -243,35 +274,43 @@ final class RDEPUBReaderRuntime {
         paginationCoordinator.applyPaginationSnapshot(snapshot, restoreLocation: restoreLocation)
     }
 
+    /// 完成分页流程并恢复阅读位置
     func finishPagination(restoreLocation: RDEPUBLocation?) {
         paginationCoordinator.finishPagination(restoreLocation: restoreLocation)
     }
 
+    /// 重新分页并保持当前阅读位置不变
     func repaginatePreservingCurrentLocation() {
         paginationCoordinator.repaginatePreservingCurrentLocation()
     }
 
+    /// 刷新当前可见内容，保持阅读位置不变
     func refreshVisibleContentPreservingLocation() {
         paginationCoordinator.refreshVisibleContentPreservingLocation()
     }
 
+    /// 重建外部 TextBook 数据
     func rebuildExternalTextBook() {
         paginationCoordinator.rebuildExternalTextBook()
     }
 
+    /// 恢复到指定阅读位置
     @discardableResult
     func restoreReadingLocation(_ location: RDEPUBLocation, animated: Bool = false) -> Bool {
         locationCoordinator.restoreReadingLocation(location, animated: animated)
     }
 
+    /// 获取当前可见页面的阅读位置
     func currentVisibleLocation() -> RDEPUBLocation? {
         locationCoordinator.currentVisibleLocation()
     }
 
+    /// 获取当前视口签名快照
     func currentViewportSignature() -> RDEPUBViewportSignature? {
         viewportMonitor.currentViewportSignature()
     }
 
+    /// 视口变化时检查是否需要重新分页
     func handleViewportChangeIfNeeded(
         reason: RDEPUBViewportChangeReason,
         viewportSignature: RDEPUBViewportSignature? = nil

Sources/RDReaderView/EPUBUI/ReaderController/RDEPUBReaderSearchCoordinator.swift

@@ -1,5 +1,6 @@
 import Foundation
 
+/// 搜索协调器，负责管理全文搜索的执行、结果导航和搜索状态通知。
 final class RDEPUBReaderSearchCoordinator {
     private unowned let context: RDEPUBReaderContext
 
@@ -11,6 +12,8 @@ final class RDEPUBReaderSearchCoordinator {
         context.controller
     }
 
+    /// 按关键词执行全文搜索，匹配结果自动导航到首个命中位置
+    /// - Parameter keyword: 搜索关键词
     func search(keyword: String) {
         guard let controller else { return }
         let normalizedKeyword = keyword.trimmingCharacters(in: .whitespacesAndNewlines)
@@ -34,16 +37,21 @@ final class RDEPUBReaderSearchCoordinator {
         }
     }
 
+    /// 跳转到下一个搜索匹配项
+    /// - Returns: 是否成功跳转
     @discardableResult
     func searchNext() -> Bool {
         advanceSearch(by: 1)
     }
 
+    /// 跳转到上一个搜索匹配项
+    /// - Returns: 是否成功跳转
     @discardableResult
     func searchPrevious() -> Bool {
         advanceSearch(by: -1)
     }
 
+    /// 清除搜索状态并刷新当前可见内容
     func clearSearch() {
         guard let controller else { return }
         controller.searchState = nil
@@ -51,6 +59,9 @@ final class RDEPUBReaderSearchCoordinator {
         controller.refreshVisibleContentPreservingLocation()
     }
 
+    /// 构建指定页面的搜索结果展示信息，用于高亮渲染
+    /// - Parameter page: 目标页面
+    /// - Returns: 搜索展示数据，若无搜索状态则返回 nil
     func searchPresentation(for page: EPUBPage) -> RDEPUBSearchPresentation? {
         guard let controller else { return nil }
         guard let searchState = controller.searchState,

Sources/RDReaderView/EPUBUI/ReaderController/RDEPUBReaderViewportMonitor.swift

@@ -1,5 +1,7 @@
 import UIKit
 
+/// 视口监测器，监听视图布局和屏幕旋转等视口变化事件，
+/// 检测变化是否显著，必要时触发重新分页或内容重建。
 final class RDEPUBReaderViewportMonitor {
     private unowned let context: RDEPUBReaderContext
 
@@ -16,6 +18,7 @@ final class RDEPUBReaderViewportMonitor {
         context.controller
     }
 
+    /// 视图布局完成后检查视口是否发生变化，首次布局时触发初始加载
     func viewDidLayoutSubviews() {
         guard let controller else { return }
         guard let viewportSignature = currentViewportSignature() else { return }
@@ -38,6 +41,8 @@ final class RDEPUBReaderViewportMonitor {
         handleViewportChangeIfNeeded(reason: .viewLayout, viewportSignature: viewportSignature)
     }
 
+    /// 屏幕旋转前捕获当前阅读位置，旋转完成后检测视口变化并处理
+    /// - Parameter coordinator: 转场协调器
     func viewWillTransition(with coordinator: UIViewControllerTransitionCoordinator) {
         guard let controller else { return }
         guard controller.didStartInitialLoad else { return }
@@ -52,6 +57,7 @@ final class RDEPUBReaderViewportMonitor {
         }
     }
 
+    /// 重置所有视口状态，用于重新加载书籍
     func resetForReload() {
         lastAppliedViewportSignature = currentViewportSignature()
         pendingViewportChangeReason = nil
@@ -59,16 +65,19 @@ final class RDEPUBReaderViewportMonitor {
         isWaitingForViewportTransitionCompletion = false
     }
 
+    /// 消费并返回待恢复的阅读位置（一次性读取后清空）
     func consumePendingPresentationRestoreLocation() -> RDEPUBLocation? {
         defer { pendingPresentationRestoreLocation = nil }
         return pendingPresentationRestoreLocation
     }
 
+    /// 主动捕获当前阅读位置到待恢复队列，供后续视口变化后恢复使用
     func capturePendingPresentationRestoreLocation() {
         guard let controller else { return }
         pendingPresentationRestoreLocation = controller.currentVisibleLocation() ?? controller.persistenceLocation()
     }
 
+    /// 分页完成后处理挂起的视口变化（如有），避免分页过程中重复触发
     func processPendingChangeAfterPagination() {
         guard let pendingReason = pendingViewportChangeReason else { return }
         pendingViewportChangeReason = nil
@@ -77,6 +86,7 @@ final class RDEPUBReaderViewportMonitor {
         }
     }
 
+    /// 获取当前视口签名，包含容器尺寸和安全区域信息
     func currentViewportSignature() -> RDEPUBViewportSignature? {
         guard let controller else { return nil }
         let containerSize = controller.readerView.bounds.size == .zero ? controller.view.bounds.size : controller.readerView.bounds.size
@@ -92,6 +102,7 @@ final class RDEPUBReaderViewportMonitor {
         )
     }
 
+    /// 检测视口签名是否发生显著变化，若变化则触发重新分页或重建外部 TextBook
     func handleViewportChangeIfNeeded(
         reason: RDEPUBViewportChangeReason,
         viewportSignature: RDEPUBViewportSignature? = nil