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

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

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

Sources/RDReaderView/EPUBUI/RDEPUBReaderController+PublicAPI.swift

@@ -1,3 +1,6 @@
+// RDEPUBReaderController+PublicAPI.swift
+// RDEPUBReaderController 的公开 API 扩展，提供书签、高亮、目录跳转、搜索等操作
+
 import UIKit
 
 // MARK: - Public Reader Commands
@@ -30,14 +33,22 @@ extension RDEPUBReaderController {
         runtime.clearSelection()
     }
 
+    /// 根据唯一标识获取书签
+    /// - Parameter id: 书签 ID
+    /// - Returns: 匹配的书签对象，不存在时返回 nil
     public func bookmark(withID id: String) -> RDEPUBBookmark? {
         runtime.bookmark(withID: id)
     }
 
+    /// 根据唯一标识获取高亮标注
+    /// - Parameter id: 高亮 ID
+    /// - Returns: 匹配的高亮对象，不存在时返回 nil
     public func highlight(withID id: String) -> RDEPUBHighlight? {
         runtime.highlight(withID: id)
     }
 
+    /// 获取当前页的原生文本语义摘要，用于调试和可访问性
+    /// - Returns: 包含页码、断行原因、块类型等信息的摘要字符串，无内容时返回 nil
     public func nativeTextSemanticSummary() -> String? {
         guard let textBook,
               let page = textBook.page(at: max(readerView.currentPage + 1, 1)) ?? textBook.pages.first else {
@@ -73,6 +84,13 @@ extension RDEPUBReaderController {
         runtime.addHighlight(from: selection, color: color, note: note)
     }
 
+    /// 添加指定样式的标注，从当前选中文本或指定选区创建
+    /// - Parameters:
+    ///   - selection: 文本选区，默认使用 currentSelection
+    ///   - style: 标注样式（下划线、高亮等）
+    ///   - color: 标注颜色（CSS 格式），默认黄色
+    ///   - note: 可选批注文字
+    /// - Returns: 创建的高亮对象，重复时返回 nil
     @discardableResult
     public func addAnnotation(
         from selection: RDEPUBSelection? = nil,
@@ -83,40 +101,72 @@ extension RDEPUBReaderController {
         runtime.addAnnotation(from: selection, style: style, color: color, note: note)
     }
 
+    /// 插入或更新高亮标注（存在则更新，不存在则插入）
+    /// - Parameter highlight: 要写入的高亮对象
+    /// - Returns: 写入后的高亮对象
     @discardableResult
     public func upsertHighlight(_ highlight: RDEPUBHighlight) -> RDEPUBHighlight? {
         runtime.upsertHighlight(highlight)
     }
 
+    /// 移除指定高亮标注
+    /// - Parameter id: 高亮 ID
+    /// - Returns: 被移除的高亮对象，不存在时返回 nil
     @discardableResult
     public func removeHighlight(id: String) -> RDEPUBHighlight? {
         runtime.removeHighlight(id: id)
     }
 
+    /// 更新高亮标注的批注内容
+    /// - Parameters:
+    ///   - id: 高亮 ID
+    ///   - note: 新的批注文字，传 nil 清除批注
+    /// - Returns: 更新后的高亮对象，不存在时返回 nil
     @discardableResult
     public func updateHighlightNote(id: String, note: String?) -> RDEPUBHighlight? {
         runtime.updateHighlightNote(id: id, note: note)
     }
 
+    /// 跳转到指定高亮标注所在位置
+    /// - Parameters:
+    ///   - id: 高亮 ID
+    ///   - animated: 是否动画过渡
+    /// - Returns: 是否跳转成功
     @discardableResult
     public func go(toHighlightID id: String, animated: Bool = true) -> Bool {
         runtime.go(toHighlightID: id, animated: animated)
     }
 
+    /// 移除当前书籍的所有高亮标注
     public func removeAllHighlights() {
         runtime.removeAllHighlights()
     }
 
+    /// 跳转到目录项对应的阅读位置
+    /// - Parameters:
+    ///   - item: EPUB 原生目录项
+    ///   - animated: 是否动画过渡
+    /// - Returns: 是否跳转成功
     @discardableResult
     public func go(toTableOfContentsItem item: EPUBTableOfContentsItem, animated: Bool = true) -> Bool {
         go(toTableOfContentsHref: item.href, animated: animated)
     }
 
+    /// 跳转到目录项对应的阅读位置
+    /// - Parameters:
+    ///   - item: RDReader 目录项
+    ///   - animated: 是否动画过渡
+    /// - Returns: 是否跳转成功
     @discardableResult
     public func go(toTableOfContentsItem item: RDEPUBReaderTableOfContentsItem, animated: Bool = true) -> Bool {
         go(toTableOfContentsHref: item.href, animated: animated)
     }
 
+    /// 通过目录 href 跳转到对应阅读位置，支持带锚点的 href
+    /// - Parameters:
+    ///   - href: 目录资源路径（可含 #fragment）
+    ///   - animated: 是否动画过渡
+    /// - Returns: 是否跳转成功
     @discardableResult
     public func go(toTableOfContentsHref href: String, animated: Bool = true) -> Bool {
         guard publication != nil else { return false }
@@ -133,42 +183,61 @@ extension RDEPUBReaderController {
         return restoreReadingLocation(location, animated: animated)
     }
 
+    /// 在当前位置添加书签
+    /// - Parameter note: 可选批注文字
+    /// - Returns: 创建的书签对象，位置已存在书签时返回 nil
     @discardableResult
     public func addBookmark(note: String? = nil) -> RDEPUBBookmark? {
         runtime.addBookmark(note: note)
     }
 
+    /// 切换当前位置的书签状态（有则移除，无则添加）
+    /// - Parameter note: 添加时可附带的批注文字
+    /// - Returns: 添加时返回新书签，移除时返回被移除的书签
     @discardableResult
     public func toggleBookmark(note: String? = nil) -> RDEPUBBookmark? {
         runtime.toggleBookmark(note: note)
     }
 
+    /// 移除指定书签
+    /// - Parameter id: 书签 ID
+    /// - Returns: 被移除的书签对象，不存在时返回 nil
     @discardableResult
     public func removeBookmark(id: String) -> RDEPUBBookmark? {
         runtime.removeBookmark(id: id)
     }
 
+    /// 跳转到指定书签所在位置
+    /// - Parameters:
+    ///   - id: 书签 ID
+    ///   - animated: 是否动画过渡
+    /// - Returns: 是否跳转成功
     @discardableResult
     public func go(toBookmarkID id: String, animated: Bool = true) -> Bool {
         runtime.go(toBookmarkID: id, animated: animated)
     }
 
-    /// 执行全文搜索，自动跳转到第一个匹配项
+    /// 执行全文搜索，匹配结果非空时自动跳转到第一个匹配项，无匹配时清除搜索状态
     /// - Parameter keyword: 搜索关键词，空字符串会清除搜索
     public func search(keyword: String) {
         runtime.search(keyword: keyword)
     }
 
+    /// 跳转到下一个搜索匹配项
+    /// - Returns: 是否存在下一个匹配项并跳转成功
     @discardableResult
     public func searchNext() -> Bool {
         runtime.searchNext()
     }
 
+    /// 跳转到上一个搜索匹配项
+    /// - Returns: 是否存在上一个匹配项并跳转成功
     @discardableResult
     public func searchPrevious() -> Bool {
         runtime.searchPrevious()
     }
 
+    /// 清除搜索状态和高亮
     public func clearSearch() {
         runtime.clearSearch()
     }