feat: EPUB阅读器搜索、注释、CFI模块及大书远距跳转优化

- 实现EPUB阅读器搜索功能及选中注释功能
- 优化CFI模块，修复代码审查发现的11个问题
- 实现大书远距目录跳转与后台补全优化方案
- 优化设置面板与章节运行时联动
- 重构及大量改进优化

Sources/RDReaderView/EPUBUI/RDURLReaderController.swift

@@ -1,29 +1,6 @@
-//
-//  RDURLReaderController.swift
-//  RDReaderDemo
-//
-//  文件职责：URL 阅读器入口控制器，根据文件类型自动选择阅读器。
-//  该文件是 ReadViewSDK 的最简使用入口：
-//  - .epub 文件：直接创建 RDEPUBReaderController
-//  - 其他文本文件：通过 RDPlainTextBookBuilder 分页后创建 RDEPUBReaderController
-//  - 分页失败时回退到纯文本 UITextView 展示
-//
-//  架构位置：RDReaderView 四层架构中第四层（读者 UI）的入口控制器。
-//
 
 import UIKit
 
-/// URL 阅读器入口控制器
-/// 接收一个书籍文件 URL，根据文件类型自动创建对应的阅读器控制器：
-/// - EPUB 文件：直接使用 RDEPUBReaderController
-/// - 纯文本文件：先通过 RDPlainTextBookBuilder 分页，再使用 RDEPUBReaderController
-/// - 分页失败：回退到纯文本 UITextView 展示
-///
-/// 使用方式：
-/// ```swift
-/// let controller = RDURLReaderController(bookURL: fileURL)
-/// navigationController?.pushViewController(controller, animated: true)
-/// ```
 public final class RDURLReaderController: UIViewController {
     private struct PendingDemoPageRequest {
         let pageNumber: Int
@@ -31,11 +8,10 @@ public final class RDURLReaderController: UIViewController {
         var attemptCount: Int
     }
 
-    /// 书籍文件 URL
     private let bookURL: URL
-    /// EPUB 阅读器配置（字体、行距、主题等）
+
     private let epubConfiguration: RDEPUBReaderConfiguration
-    /// 内嵌的阅读器控制器
+
     private var embeddedController: UIViewController?
     private let demoStateLabel: UILabel = {
         let label = UILabel()
@@ -58,10 +34,6 @@ public final class RDURLReaderController: UIViewController {
     private var lastActivatedExternalURL: URL?
     private var lastReaderErrorDescription = "none"
 
-    /// 初始化方法
-    /// - Parameters:
-    ///   - bookURL: 书籍文件的本地 URL
-    ///   - epubConfiguration: EPUB 阅读器配置，默认使用标准配置
     public init(
         bookURL: URL,
         epubConfiguration: RDEPUBReaderConfiguration = RDEPUBReaderConfiguration()
@@ -76,7 +48,6 @@ public final class RDURLReaderController: UIViewController {
         fatalError("init(coder:) has not been implemented")
     }
 
-    /// 视图加载完成后，设置背景色、标题并嵌入阅读器控制器
     public override func viewDidLoad() {
         super.viewDidLoad()
         view.backgroundColor = .systemBackground
@@ -101,18 +72,11 @@ public final class RDURLReaderController: UIViewController {
         stopDemoStateTimer()
     }
 
-    /// 切换阅读器的翻页模式（Demo 用）
-    /// - Parameter displayType: 目标翻页模式
     public func applyDemoDisplayType(_ displayType: RDReaderView.DisplayType) {
         readerController?.configuration.displayType = displayType
         emitDemoState(prefix: "display=\(displayType.demoArgumentValue)")
     }
 
-    /// 跳转到指定页码（Demo 用）
-    /// - Parameters:
-    ///   - pageNumber: 目标页码
-    ///   - animated: 是否动画过渡
-    /// - Returns: 是否成功跳转
     @discardableResult
     public func goToDemoPage(_ pageNumber: Int, animated: Bool = false) -> Bool {
         let moved = performDemoPageNavigation(pageNumber, animated: animated)
@@ -125,12 +89,6 @@ public final class RDURLReaderController: UIViewController {
         return moved
     }
 
-    /// 执行翻页模式切换序列（Demo 用）
-    /// 按照指定顺序和延迟依次切换翻页模式
-    /// - Parameters:
-    ///   - displayTypes: 翻页模式数组
-    ///   - initialPageNumber: 可选的初始跳转页码
-    ///   - stepDelay: 每步之间的延迟时间（秒）
     public func runDemoDisplaySequence(
         _ displayTypes: [RDReaderView.DisplayType],
         initialPageNumber: Int? = nil,
@@ -151,9 +109,6 @@ public final class RDURLReaderController: UIViewController {
         }
     }
 
-    /// 执行搜索（Demo 用）
-    /// 显示搜索栏并提交关键词。若阅读器尚未完成加载则延迟到 `didUpdateLocation` 后执行。
-    /// - Parameter keyword: 搜索关键词
     public func performDemoSearch(keyword: String) {
         guard let readerController else { return }
         readerController.showSearchBar()
@@ -187,8 +142,6 @@ public final class RDURLReaderController: UIViewController {
         submitSearchAfterDelay(keyword: keyword, retries: 5)
     }
 
-    /// 嵌入阅读器控制器到当前视图层级
-    /// 根据文件类型选择合适的阅读器控制器，并通过 Child View Controller 方式嵌入
     private func embedReaderController() {
         let controller: UIViewController
         if bookURL.pathExtension.lowercased() == "epub" {
@@ -224,7 +177,7 @@ public final class RDURLReaderController: UIViewController {
                     configuration: epubConfiguration
                 )
             } else {
-                // 分页失败时回退到纯文本展示
+
                 let fallback = UIViewController()
                 let textView = UITextView()
                 textView.isEditable = false
@@ -248,7 +201,6 @@ public final class RDURLReaderController: UIViewController {
         emitDemoState()
     }
 
-    /// 获取内嵌的 EPUB 阅读器控制器（如果存在）
     private var readerController: RDEPUBReaderController? {
         embeddedController as? RDEPUBReaderController
     }
@@ -322,7 +274,6 @@ public final class RDURLReaderController: UIViewController {
         }
     }
 
-    /// 输出当前阅读器状态日志（Demo 调试用）
     private func logDemoState(prefix: String) {
         guard let readerController else { return }
         let location = readerController.currentLocation
@@ -372,6 +323,9 @@ public final class RDURLReaderController: UIViewController {
         let location = readerController?.currentLocation
         let href = encodedDemoLocationHref(location?.href)
         let progression = location.map { String(format: "%.4f", $0.navigationProgression) } ?? "nil"
+        let cfi = encodedDemoField(location?.cfi)
+        let lastCFI = encodedDemoField(location?.lastCFI)
+        let rangeCFI = encodedDemoField(location?.rangeCFI)
         let mapSnapshot = demoPaginationSnapshot()
         let layoutConfig = readerController?.readerContext.currentTextLayoutConfig(pageSize: currentTextPageSize())
         let resourceMetrics = RDEPUBResourceURLSchemeHandler.debugMetricsSnapshot()
@@ -388,6 +342,9 @@ public final class RDURLReaderController: UIViewController {
             "selection=\(selection)",
             "href=\(href)",
             "progression=\(progression)",
+            "cfi=\(cfi)",
+            "lastCFI=\(lastCFI)",
+            "rangeCFI=\(rangeCFI)",
             "mode=\(mapSnapshot.mode)",
             "pagination=\(mapSnapshot.phase)",
             "knownPages=\(mapSnapshot.knownPages)",
@@ -464,14 +421,10 @@ public final class RDURLReaderController: UIViewController {
         return ("snapshot", snapshotPages > 0 ? "full" : "none", snapshotPages, snapshotChapters, snapshotChapters)
     }
 
-    /// 计算文本分页的页面尺寸。
-    /// 分页器使用完整 viewport，真实可绘制区域由 layoutConfig.edgeInsets 控制，
-    /// 以保持与页面展示时的内容几何一致。
     private func currentTextPageSize() -> CGSize {
         UIScreen.main.bounds.size
     }
 
-    /// 根据当前配置生成文本渲染样式
     private func currentTextRenderStyle() -> RDEPUBTextRenderStyle {
         let font = epubConfiguration.fontChoice.font(ofSize: epubConfiguration.fontSize)
         let lineSpacing = max(font.lineHeight * (epubConfiguration.lineHeightMultiple - 1), 4)
@@ -483,8 +436,6 @@ public final class RDURLReaderController: UIViewController {
         )
     }
 
-    /// 解码文本文件内容
-    /// 尝试 UTF-8 编码，失败则尝试 GBK 和 GB2312 编码
     private func rd_decodeTextFile(url: URL) -> String {
         if let content = try? NSString(contentsOf: url, encoding: String.Encoding.utf8.rawValue) as String {
             return content
@@ -536,9 +487,8 @@ extension RDURLReaderController: RDEPUBReaderDelegate {
     }
 }
 
-/// 翻页模式扩展：提供 Demo 命令行参数值
 private extension RDReaderView.DisplayType {
-    /// 返回翻页模式对应的 Demo 命令行参数字符串
+
     var demoArgumentValue: String {
         switch self {
         case .pageCurl: