Epub阅读器0.0.1

2026-05-21 19:40:51 +08:00
commit daa36d8fe7
559 changed files with 106266 additions and 0 deletions
@@ -0,0 +1,286 @@
+---
+name: "Discuss SDK Feature Solution"
+description: "方案讨论优先 skill：用于 ReadViewSDK 新需求的实现方案分析、路径对比、取舍沟通、已定方案细化和实现交接。"
+argument-hint: "粘贴需求、目标模块、约束、已知备选方案；可附加：是否已确定方案 / 是否需要推荐方案 / 是否需要落方案文档。"
+---
+
+# Discuss SDK Feature Solution
+
+## Purpose
+
+面向 ReadViewSDK 的"实现方案讨论入口" skill。
+用于在正式开发前，先把需求、约束、可选实现路径和关键取舍聊透；若方案已经确定，则只围绕已选方案继续细化，再交接给开发 skill 进入实现。
+
+该 skill 借鉴 spec-driven 工作流思想：讨论阶段专门捕获灰区决策，计划阶段必须经过代码 / 文档事实核验，最终输出能直接喂给开发 skill 的结构化方案文档，避免"聊完还是不能开发"。
+
+该 skill 的职责固定为：
+- 先理解需求与约束
+- 捕获灰区问题和实现假设
+- 用现有代码 / 文档核验方案可行性
+- 未定方案时：输出 2-4 个可行实现方案，并做对比
+- 已定方案时：只围绕确认方案展开实现讨论，不再继续扩展其他方案
+- 最后给出交接到开发 skill 的明确指令
+- 最终必须产出一份可直接供开发 skill 使用的开发详细文档，或一段可直接执行的开发详细描述
+
+## Core Discussion Rules
+
+- Rule 1 — Think Before Coding
+  - 在提出方案前先核对代码和文档事实，不静默假设
+  - 必须显式写出关键假设、主要取舍和已知风险
+  - 遇到会改变实现路径的关键灰区，先提出并请求确认，不靠猜测补完整个方案
+  - 若存在更简单且满足目标的实现路径，必须主动指出并优先推荐
+- Rule 2 — Simplicity First
+  - 推荐方案优先选择最小可落地路径，而不是概念上更"完整"的设计
+  - 不为了未来可能性预埋推测性扩展，不为单次使用引入抽象
+  - 若某个方案明显过度设计，必须直接指出并解释为什么不推荐
+- Rule 3 — Surgical Changes
+  - 方案只覆盖完成当前目标所必需的改动面
+  - 不把无关重构、顺手统一风格或额外治理动作夹带进推荐方案
+  - 若确有相邻改动依赖，必须明确标注"必要改动"与"可选优化"的边界
+- Rule 4 — Goal-Driven Execution
+  - 讨论输出必须先定义成功标准和验证方式，再给实现交接建议
+  - 不把讨论步骤本身当结果，重点是产出可执行、可验证的方案
+  - 交接给开发 skill 时，必须让对方清楚"做到什么算完成"
+
+## When To Use
+
+当用户提出以下类型需求时使用：
+- "先讨论一下这个需求怎么实现"
+- "这个功能可能有多种实现方式，先分析方案"
+- "先别写代码，先帮我想实现路径"
+- "先比较几种方案，再决定怎么做"
+
+适用场景：
+- 同一个需求可以通过多种技术路径实现
+- 需要权衡 SDK 分层（EPUBCore / EPUBTextRendering / RDReaderView / EPUBUI）、复用、维护成本、回归影响
+- 需要在实现前先明确推荐方案和待确认细节
+- 已经明确采用某个方案，但还需要继续细化实现边界、拆解落地路径和交接开发
+
+不适用场景：
+- 用户已经明确要直接实现，且实现路径基本单一时，优先使用开发类 skill
+- 用户只想生成文档，不需要方案讨论时，优先使用文档类 skill
+
+## Inputs
+
+推荐输入：
+- 需求描述
+- 目标模块或 Feature（属于哪一层：EPUBCore / EPUBTextRendering / RDReaderView / EPUBUI / Legacy）
+- 已知约束（兼容性、性能、API 兼容、CocoaPods 发布等）
+- 已有备选方案（如有）
+- 已确认方案（如已决定）
+- 是否需要推荐方案
+- 是否需要最终落方案文档
+
+若信息不足：
+- 先通过代码和文档补齐可发现事实
+- 再围绕真正影响方案选择的灰区进行澄清
+- 若用户不想继续问答，必须显式列出"实现假设"，并把假设写入方案或交接摘要
+
+若用户已经明确指定"采用方案 X / 就按这个方案做"：
+- 视为进入"已定方案模式"
+- 后续输出禁止继续罗列其他候选方案、备选实现或横向对比
+- 仅允许在必要时补充"当前方案的风险、前提、边界和实现细化"
+
+## Scope / Required Context
+
+默认先读：
+1. `Doc/ARCHITECTURE.md` — 四层架构、数据流、分页模式、位置模型、已知限制
+2. `Doc/CODING_STYLE.md` — 命名规范（RD/RDEPUB 前缀）、分层规则、extension 拆分规则、SS→RD 迁移计划
+3. `Doc/EPUB_MAINTENANCE.md` — 文件职责表、DTCoreText 渲染管线、常见排查场景
+
+按需再读：
+- 涉及 EPUB 解析时：`Sources/RDReaderView/EPUBCore/` 下相关文件
+- 涉及文本渲染时：`Sources/RDReaderView/EPUBTextRendering/` 下相关文件
+- 涉及阅读器容器时：`Sources/RDReaderView/RDReaderView.swift` 及同级文件
+- 涉及 UI 层时：`Sources/RDReaderView/EPUBUI/` 下相关文件
+- 涉及遗留代码时：`Sources/RDReaderView/LegacyRDReaderController/` 下相关文件
+- 涉及 JS 桥接时：`Sources/RDReaderView/Resources/epub-bridge.js`
+
+若文档与代码不一致：
+- 以代码事实为准做方案讨论
+- 在推荐方案中指出不一致点和可能影响
+
+方案文档落地目录约束：
+- 讨论型方案文档统一落到 `Doc/FeatureSolution/`（若目录不存在则创建）
+- 不要把方案讨论文档写入其他目录
+
+## SDK-Specific Discussion Rules
+
+讨论时必须考虑的 SDK 特有约束：
+
+- **分层边界**：方案必须明确落在哪一层，不得跨层引入反向依赖（上层依赖下层允许，反之不允许）
+- **Public API 兼容性**：若改动涉及公共接口（`RDReaderView`、`RDReaderDataSource`、`RDURLReaderController`、`RDEPUBReaderController` 等），必须评估对宿主 App 的 breaking change 影响
+- **渲染路径差异**：方案必须考虑三种渲染路径（`webFixedLayout` / `webInteractive` / `textReflowable`）的适用性，不能只覆盖单一路径
+- **CocoaPods 发布影响**：若方案涉及新增依赖、资源文件或模块结构调整，必须评估 podspec 变更
+- **RD 前缀规范**：所有新增类型必须使用 `RD` 前缀，EPUB 相关使用 `RDEPUB` 前缀
+- **Legacy 层边界**：不在 Legacy 层新增功能；若方案涉及 Legacy 代码，必须明确是迁移还是在新层实现
+
+## GSD-Inspired Discussion Rules
+
+讨论阶段要像 `discuss -> plan -> verify` 闭环一样，先捕获决策，再验证计划，而不是直接跳到实现建议。
+
+必须执行：
+- 灰区捕获：先识别布局、接口形态、数据结构、错误态、路由、持久化、兼容性、回归范围等不明确点
+- 事实核验：方案落地前必须用本仓库代码和 `Doc/` 文档确认入口、复用点、约束和风险
+- 假设显式化：不能确认的问题必须写成 `Assumption`，不得藏在方案正文里
+- 阻塞分级：会改变实现路径的问题标记为 `Blocking Decision`，不会改变路径的问题标记为 `Follow-up`
+- 审计留痕：若落方案文档，必须包含"讨论结论 / 关键决策 / 假设 / 非范围 / 验证清单 / 开发交接指令"
+- 计划可执行：最终方案必须足够小，能被开发 skill 直接逐项执行
+
+禁止行为：
+- 不得只输出宽泛建议，必须落到文件、类、方法、数据流或协议层面的执行点
+- 不得在用户已确认方案后继续展开新方案，除非用户明确要求重新比较
+- 不得把未经核验的包、SDK、接口能力写成已确认事实
+- 不得把需要用户拍板的关键决策伪装成默认实现
+
+## Required Workflow
+
+### Phase 1 — 识别需求、范围、约束、现状
+
+- 明确目标价值、影响模块（EPUBCore / EPUBTextRendering / RDReaderView / EPUBUI / Legacy）、In Scope / Out of Scope
+- 识别当前项目里已有的实现模式、相邻能力和复用点
+- 判断这是单层需求还是跨层需求
+- 建立灰区清单，区分 `Blocking Decision` 与 `Follow-up`
+
+### Phase 2 — 判断讨论模式
+
+- 若方案未定：进入"多方案对比模式"
+- 若方案已定：进入"单方案细化模式"
+- 一旦用户已确认方案，后续同一轮讨论默认保持"单方案细化模式"，除非用户明确要求重新打开方案比较
+
+### Phase 3 — Research / Verify：核验代码与文档事实
+
+- 对照当前仓库确认真实入口、调用链、数据模型、复用的 cell / view / handler / controller / protocol
+- 若方案涉及新增文件，必须确认所属目录层级和是否需要更新 podspec 的 source_files
+- 若方案涉及接口或数据字段，必须明确字段来源、空值策略和兼容策略
+- 若方案涉及 JS 桥接，必须确认 epub-bridge.js 的交互契约
+- 若发现文档和代码不一致，必须标注为风险或阻塞项
+- 若核验结果推翻原方案，必须暂停说明，不得继续包装成可执行方案
+
+### Phase 4A — 多方案对比模式：列出多种实现路径
+
+- 至少提出 2 个可行方案，推荐 2-4 个方案
+- 每个方案都要有清晰的实现方向，而不是抽象建议
+- 优先从现有项目模式和复用能力出发
+
+### Phase 4B — 多方案对比模式：比较方案优缺点和影响范围
+
+- 比较每个方案的：
+  - 核心思路
+  - 落在哪一层（EPUBCore / EPUBTextRendering / RDReaderView / EPUBUI）
+  - 适用前提
+  - 优点
+  - 风险 / 成本
+- 对 SDK 分层、Public API、podspec、回归范围的影响
+- 明确哪些差异会真正影响后续实现和维护
+
+### Phase 5A — 多方案对比模式：提出推荐方案，并列出待确认细节
+
+- 必须明确推荐一个默认方案，不能只平铺选项
+- 待确认项只保留真正影响实现的关键决策
+- 默认产物为对话输出；若用户明确要求，再可选落到 `Doc/FeatureSolution/` 下方案文档
+
+### Phase 5B — 单方案细化模式：围绕确认方案展开
+
+- 不再输出"方案 A / 方案 B / 方案 C"式内容
+- 不再补充"其他也可以这样做"的备选实现，除非用户明确要求回到方案比较
+- 只讨论以下内容：
+  - 当前方案的实现拆解（文件 / 类 / 方法 / 协议）
+  - SDK 分层内的模块边界与职责分配
+  - 关键数据流 / 状态流 / 渲染流
+  - 复用点、依赖点、回归点
+  - 对三种渲染路径的覆盖情况
+  - 风险、前提、灰度方式、验证要点
+  - 交接给开发 skill 的实现摘要
+
+### Phase 6 — 输出实现交接建议
+
+- 在方案确认后，明确下一步应交给哪个开发 skill：
+  - 小中型、单层、MVP 优先：轻量开发 skill
+  - 跨层、复杂联调、完整交付：完整开发 skill
+- 无论是否落文档，最终都必须产出开发交接载体，且二选一不能缺失：
+  - 完整开发 skill：产出可直接执行的开发详细文档，默认落到 `Doc/FeatureSolution/`
+  - 轻量开发 skill：产出可直接粘贴执行的开发详细描述，覆盖实现目标、范围、代码落点、关键步骤、验收标准和自测要点
+- 给出可直接粘贴给开发 skill 的实现摘要；若已有更完整的详细文档/描述，则摘要必须引用它而不是只给一句话概括
+- 若落方案文档，必须让开发指令引用该文档的真实路径，并提醒开发 skill 严格按计划执行
+
+## Output Contract
+
+默认输出结构按模式区分：
+
+若方案未定：
+- A. 需求理解
+- B. 灰区问题与实现假设
+- C. 当前实现与约束
+- D. 可选方案对比
+- E. 推荐方案
+- F. 待确认实现细节
+- G. 实现交接建议
+
+若方案已定：
+- A. 需求理解
+- B. 灰区问题与实现假设
+- C. 当前实现与约束
+- D. 确认方案拆解
+- E. 实现风险与关键细节
+- F. 实现交接建议
+
+其中要求：
+- 未定方案时：
+  - `B. 灰区问题与实现假设` 必须区分 Blocking Decision / Follow-up / Assumption
+  - `D. 可选方案对比` 至少给出 2 个方案，推荐 2-4 个
+  - `E. 推荐方案` 必须明确推荐一个默认方案
+  - `F. 待确认实现细节` 只保留会改变实现路径的关键问题
+- `G. 实现交接建议` 必须明确下一步交给哪个开发 skill
+- `G. 实现交接建议` 必须附带可供开发 skill 直接使用的交接内容：
+  - 若下一步是完整开发 skill，必须提供开发详细文档路径或完整文档正文
+  - 若下一步是轻量开发 skill，必须提供开发详细描述正文
+- 已定方案时：
+  - `B. 灰区问题与实现假设` 必须列出阻塞项、假设和后续项
+  - `D. 确认方案拆解` 只能围绕确认方案展开，禁止附带其他方案信息
+  - `E. 实现风险与关键细节` 只讨论该方案落地所需信息
+  - `F. 实现交接建议` 必须明确下一步交给哪个开发 skill，并附带可直接执行的详细文档或详细描述
+
+若用户要求落方案文档，文档必须包含：
+- 需求目标
+- 讨论结论
+- 关键决策
+- 实现假设
+- 非范围
+- SDK 分层落点（文件 / 类 / 方法 / 协议）
+- 数据流 / 状态流 / 渲染流
+- 开发任务清单
+- 验收标准
+- 自测清单
+- 待确认项
+- 给开发 skill 的执行指令
+
+若未落方案文档，但下一步要交给轻量开发 skill，则最终输出中的"开发详细描述"至少必须包含：
+- 实现目标
+- In Scope / Out of Scope
+- SDK 分层落点（文件 / 类 / 方法 / 协议）
+- 实现步骤
+- 关键约束与复用点
+- 对三种渲染路径的覆盖说明
+- 验收标准
+- 自测清单
+- 待确认项或实现假设
+
+## Validation
+
+- 本 skill 默认只做方案讨论，不直接进入代码实现
+- 默认不修改仓库文件；只有用户明确要求时，才可选落方案文档到 `Doc/FeatureSolution/`
+- 即使不落方案文档，最终回复也必须包含一份可直接交给开发 skill 使用的详细交接内容，不能只停留在高层方案结论
+- 若本次调用只做讨论或只新增方案文档，可不执行构建验证
+- 若新增或移动方案文档，建议同步更新目录索引
+- 若后续进入代码实现，则由对应开发 skill 负责执行项目默认构建验证（`xcodebuild` 或 CocoaPods 集成验证）
+- 若用户已确认方案，则默认进入单方案细化模式，除非用户明确要求重新比较备选方案
+
+## Maintenance Rules
+
+- 该 skill 的职责是"讨论后交接实现"，不和开发 skill、文档类 skill 重叠
+- 优先复用 `Doc/` 作为知识源，不新增独立 references 体系
+- 方案文档目录固定为 `Doc/FeatureSolution/`
+- 持续保持 `discuss -> research/verify -> plan handoff` 的轻量闭环，避免退化成只聊天不交付的建议列表
+- 若该 skill 的默认输出结构、交接规则或适用边界调整，必须同步更新对应文档
+- SDK 四层架构（EPUBCore → EPUBTextRendering → RDReaderView → EPUBUI）是方案讨论的核心参照框架，任何方案都必须明确标注落点层级
@@ -0,0 +1,213 @@
+---
+name: "Start SDK Feature Dev Lite"
+description: "轻量开发主控 skill：用于 ReadViewSDK 的小中型功能开发、单层改动、局部重构、文档同步与编译修复。"
+argument-hint: "粘贴需求、目标层级、验收标准；可附加：仅 MVP / 禁止新增依赖 / 指定渲染路径。"
+---
+
+# Start SDK Feature Dev Lite
+
+## Purpose
+
+面向 ReadViewSDK 的轻量开发入口 skill。
+用于在现有项目约束下完成"小到中型"需求，遵循"先识别范围、再按需读文档、后实现、再验证、最后交付"的闭环。
+
+该 skill 是默认开发入口，优先覆盖：
+- 单层内的新功能 MVP 实现
+- 小范围重构或代码整理
+- 文档同步更新
+- 编译错误定位与修复
+- 单个模块的 bug 修复或行为调整
+- podspec 小幅调整
+
+默认吸收项目 `Doc/CODING_STYLE.md` 中的 Swift/iOS 通用规则；若任务重点落在并发、性能、可访问性或安全，再额外展开该专项的检查项。
+
+## Core Execution Rules
+
+- Rule 1 — Think Before Coding
+  - 先核对代码和文档事实，不静默假设
+  - 必须显式写出关键假设、主要取舍和已知风险
+  - 遇到会改变实现路径的关键灰区，先暂停确认，不靠猜测继续推进
+  - 若存在更简单且满足目标的实现路径，必须主动指出并优先采用
+- Rule 2 — Simplicity First
+  - 只做满足需求和验收标准的最小实现
+  - 不增加推测性功能，不为单次使用引入抽象
+  - 若方案让资深工程师也会觉得过度设计，必须继续简化
+- Rule 3 — Surgical Changes
+  - 只修改完成当前需求所必需的文件和代码
+  - 不顺手重构无关代码，不扩散到相邻层做"顺便优化"
+  - 非必要不改注释、格式或既有结构，新增代码保持现有风格
+- Rule 4 — Goal-Driven Execution
+  - 先定义成功标准，再围绕成功标准实施和验证
+  - 不给自己堆步骤，重点是闭环达到验收结果
+  - 修改后必须验证，未验证通过前不能视为完成
+
+## When To Use
+
+当用户提出以下类型需求时使用：
+- "使用 start-sdk-feature-dev-lite 完成这个功能"
+- 在 ReadViewSDK 中开发单一功能或单层变更
+- 需要修复局部编译错误或行为问题
+- 需要同步更新文档
+- 需要小幅调整 podspec
+
+不适用场景：
+- 需求跨多个 SDK 层级、涉及多阶段联调或需要完整项目级方案时，改用 `start-sdk-feature-dev`
+- 目标是只生成文档而不改业务代码时，优先使用文档类 skill
+- 目标是方案讨论而不进入实现时，优先使用 `discuss-sdk-feature-solution`
+
+## Inputs
+
+推荐输入：
+- 功能名称
+- 目标 / 用户价值
+- 范围（In Scope）
+- 非范围（Out of Scope）
+- 目标层级（EPUBCore / EPUBTextRendering / RDReaderView / EPUBUI）
+- 详细需求
+- 验收标准
+- 约束（兼容性 / 性能 / 禁止新增依赖 / 指定渲染路径）
+
+若信息不足：
+- 先基于代码和文档补齐可发现事实
+- 再列最多 5 条关键假设
+- 基于假设继续推进 MVP，并在交付中标注待确认项
+
+## Scope / Required Context
+
+仅针对 ReadViewSDK 现有架构执行。
+
+SDK 四层架构参照：
+- Layer 1 — EPUBCore（`Sources/RDReaderView/EPUBCore/`）：EPUB 解析引擎
+- Layer 2 — EPUBTextRendering（`Sources/RDReaderView/EPUBTextRendering/`）：文本渲染路径
+- Layer 3 — RDReaderView（`Sources/RDReaderView/` 根目录）：分页阅读器容器
+- Layer 4 — EPUBUI（`Sources/RDReaderView/EPUBUI/`）：开箱即用 UI
+- Legacy（`Sources/RDReaderView/LegacyRDReaderController/`）：遗留代码，不在其上新增功能
+
+分层依赖规则（上→下允许，下→上禁止）：
+- EPUBUI → RDReaderView → EPUBTextRendering → EPUBCore
+
+默认先读：
+1. `Doc/ARCHITECTURE.md` — 四层架构、数据流、分页模式、位置模型
+2. `Doc/CODING_STYLE.md` — 命名规范、分层规则、extension 拆分规则
+3. `Doc/EPUB_MAINTENANCE.md` — 文件职责表、渲染管线、排查场景
+
+按需再读：
+- `Doc/FeatureSolution/*.md`（若有方案文档）
+- 涉及哪一层就读该层目录下的相关源码
+- 涉及 JS 桥接时：`Sources/RDReaderView/Resources/epub-bridge.js`
+- 涉及 podspec 时：`RDReaderView.podspec`
+
+若文档与代码不一致：
+- 以代码事实为准完成本次实现
+- 在交付中标注不一致点，并指出建议更新的文档
+
+## Required Workflow
+
+### Phase 1 — 识别需求和范围
+
+- 明确目标价值、影响层级（EPUBCore / EPUBTextRendering / RDReaderView / EPUBUI）、In Scope / Out of Scope
+- 优先做最小可落地实现，不做需求外重构
+- 若需求信息不足，先通过仓库事实补齐，再基于假设推进
+
+### Phase 2 — 按需读取 Doc 与代码事实
+
+- 先读默认 Doc（ARCHITECTURE / CODING_STYLE / EPUB_MAINTENANCE）
+- 根据需求类型补读对应层级的源码
+- 用源码确认真实入口、调用链和复用点，不只依赖文档
+
+### Phase 3 — 形成最小实现方案
+
+- 保持分层边界：
+  - EPUB 解析逻辑在 EPUBCore
+  - 文本渲染逻辑在 EPUBTextRendering
+  - 分页容器逻辑在 RDReaderView
+  - 开箱即用 UI 在 EPUBUI
+  - 不在 Legacy 层新增功能
+- 命名、注释、日志风格遵循 `Doc/CODING_STYLE.md`
+- Swift / iOS 默认规则：
+  - 新增 Swift 类型遵循 `RD` / `RDEPUB` 前缀和层级目录归属
+  - 避免新增强制解包；确需使用时必须先收敛前置条件
+  - 不为"现代化"而重写稳定代码；仅在本次需求明确受益时再迁移系统 API
+  - 当前项目默认保持 UIKit + Auto Layout + 既有组件风格，SDK 层不使用 SnapKit
+  - 注释和日志使用中文
+  - Debug 输出放在 `#if DEBUG` 守卫下
+  - 不在日志中输出敏感信息
+- 异步闭包默认 `[weak self]`，UI 更新回到主线程
+- 通知 / 定时器 / 回调在生命周期结束时必须清理
+- 数据模型用 `struct` + `Codable` + `Equatable`，服务对象用 `final class`
+- 可见性按最小原则：`private` > `fileprivate` > `internal` > `public`
+- 错误使用 `enum` + `LocalizedError`，禁止 force unwrap
+- 单文件若预计超过 600 行，需主动拆分扩展文件
+
+### Phase 4 — 执行修改与文档同步
+
+- 所有代码改动遵循最小改动原则
+- 修改代码时必须补充必要注释，重点说明关键逻辑、边界条件和不直观处理；不要省略应有注释，也不要添加无信息量的描述性注释
+- 默认补做轻量 SDK 自检：
+  - 新增类型是否使用正确前缀和层级归属
+  - 本次改动涉及的渲染路径是否正常工作
+  - Public API 是否有意外 breaking change
+  - podspec 是否需要更新（新增文件时）
+  - 生命周期、通知/定时器/回调清理是否完整
+  - 异步闭包是否考虑 `[weak self]`
+- 修改代码后必须同步更新受影响文档，不能只停留在代码实现
+- 若本次改动涉及 EPUB 维护相关，必须回写 `Doc/EPUB_MAINTENANCE.md`
+- 若本次是方案讨论文档交接落地，方案类文档统一放到 `Doc/FeatureSolution/`
+- 若新增、重命名或移动文档，必须同步更新目录索引
+
+### Phase 5 — 构建验证与交付
+
+- 完成修改后，按项目默认命令执行编译验证
+- 若出现编译错误，自动修复并重编译
+- 若遇构建锁问题，自动重试
+- 交付时固定输出：
+  - A. 需求理解
+  - B. 开发计划
+  - C. 开发实施
+  - D. 验证结果
+  - E. 交付摘要
+
+## Output Contract
+
+最终回复必须完整输出以下 5 个板块，标题保持一致：
+- A. 需求理解
+- B. 开发计划
+- C. 开发实施
+- D. 验证结果
+- E. 交付摘要
+
+各板块内容要求：
+- A：3-6 条，覆盖目标价值、范围、目标层级、限制
+- B：按"方案对齐 / MVP 实现 / 验证与交付"三阶段组织
+- C：描述实际改动、关键实现取舍，以及本次补充了哪些关键代码注释
+- D：给出构建结果、关键路径验证、未覆盖风险
+- E：列出改动文件、关键取舍、已同步文档与具体文档落点、后续建议
+
+## Validation
+
+若本次调用修改了任何 Swift / Objective-C / 工程配置 / podspec 文件，必须执行构建验证。
+
+验证方式：
+- 若 Demo 工程可用：
+  ```bash
+  xcodebuild build -workspace ReadViewSDKDemo/ReadViewSDKDemo.xcworkspace -scheme ReadViewSDKDemo -sdk iphonesimulator -derivedDataPath /private/tmp/readview-sdk-derived
+  ```
+- 若仅有 SDK 源码（无 workspace）：
+  ```bash
+  pod lib lint RDReaderView.podspec --allow-warnings
+  ```
+
+验证规则：
+- 编译失败时必须自行修复并重试
+- 遇到 `database is locked` 等锁问题时自动重试，建议最多 5 次
+- 直到 `BUILD SUCCEEDED` 或 `pod lib lint passed` 才可交付
+- 如果本次仅修改文档或 skill 文件，可跳过构建，但要在交付中明确说明原因
+
+## Maintenance Rules
+
+- 优先复用 `Doc/`，不要把项目级规则复制进多个 skill 造成双份维护
+- 新增项目约束时，优先更新 `Doc/CODING_STYLE.md`、`Doc/ARCHITECTURE.md` 等主文档，再调整 skill
+- 轻量与完整要保持"轻重不同、规则不冲突"，其中完整版应在轻量版闭环基础上扩展跨层与联调要求，而不是另起一套风格
+- 变更默认流程、输出格式或适用场景时，必须同步更新相关文档
+- 本 skill 持续作为默认开发入口，保持"轻量、清晰、可直接执行"
+- SDK 四层架构是执行的核心参照框架，单层改动也必须明确标注落点层级
@@ -0,0 +1,309 @@
+---
+name: "Start SDK Feature Dev"
+description: "完整开发主控 skill：用于 ReadViewSDK 的跨层功能开发、多阶段联调、结构性重构与完整交付。"
+argument-hint: "粘贴完整需求，建议包含：背景、目标、范围、目标层级、交互说明、数据约束、验收标准、渲染路径覆盖要求。"
+---
+
+# Start SDK Feature Dev
+
+## Purpose
+
+面向 ReadViewSDK 的完整开发主控 skill。
+用于复杂度高于单层修改的需求，遵循"先识别范围、再按需读文档、后对齐既定开发计划、再严格执行、再验证、最后交付"的闭环，并补充跨层联调、风险控制、回滚点和完整交付要求。
+
+该 skill 优先覆盖：
+- 跨多个 SDK 层级（EPUBCore / EPUBTextRendering / RDReaderView / EPUBUI）的功能开发
+- 多阶段联调与完整交付
+- 结构性重构或系统性收敛
+- 涉及 EPUB 解析、渲染管线、阅读器容器、UI 层协同改造的需求
+- 需要更完整风险说明、文档同步和验收闭环的开发任务
+
+默认吸收项目 `Doc/CODING_STYLE.md` 中的 Swift/iOS 通用规则；若任务重点落在并发、性能、可访问性或安全，再额外展开该专项的检查项。
+
+## Core Execution Rules
+
+- Rule 1 — Think Before Coding
+  - 先核对代码、文档和计划事实，不静默假设
+  - 必须显式写出关键假设、主要取舍和已知风险
+  - 遇到会改变计划或实现路径的关键灰区，先暂停确认，不靠猜测继续推进
+  - 若存在更简单且满足目标的实现路径，只能作为建议提出；有既定计划时不得自行改用
+- Rule 2 — Simplicity First
+  - 只做满足需求、计划和验收标准的最小实现
+  - 不增加推测性功能，不为单次使用引入抽象
+  - 若方案让资深工程师也会觉得过度设计，必须继续简化或回到计划边界内
+- Rule 3 — Surgical Changes
+  - 只修改完成当前需求和计划项所必需的文件与代码
+  - 不顺手重构无关代码，不扩散到相邻层做"顺便优化"
+  - 非必要不改注释、格式或既有结构，新增代码保持现有风格
+- Rule 4 — Goal-Driven Execution
+  - 先定义成功标准，再围绕成功标准实施和验证
+  - 计划只是约束，不是目标本身；目标是按计划完成验收闭环
+  - 修改后必须验证，未验证通过前不能视为完成
+
+## Plan Execution Rule
+
+若用户提供了开发计划文档、方案文档或明确引用 `Doc/FeatureSolution/*.md` 中的开发方案，本 skill 必须把该文档视为本次实现的主计划来源。
+
+严格执行规则：
+- 必须先完整读取用户指定的开发计划文档，再开始代码修改
+- 必须从计划中抽取任务清单、文件清单、实现边界、非范围和验收标准
+- 必须按计划逐项实现，不得自行更换方案、合并步骤、替换文件布局、改变数据模型设计或引入计划外抽象
+- 必须遵守计划中的"不做 / 不新增 / 不使用 / 暂不实现"等限制项
+- 若计划与代码事实冲突，或计划中某项无法直接落地，必须暂停并向用户说明冲突点、影响和可选处理方式；不得自行选择替代方案继续实现
+- 若发现更优实现方式，只能作为"建议"在交付或暂停说明中提出，不得在本次实现中自由采用
+- 若计划未覆盖某个必要细节，只允许做最小补齐；补齐内容必须在交付中明确标注为"计划未写明，按最小必要实现补齐"
+- 若用户要求"严格按照开发计划执行 / 不要自由发挥"，必须把偏离计划视为阻塞项处理
+
+## When To Use
+
+当用户提出以下类型需求时使用：
+- "使用 start-sdk-feature-dev 实现这个需求"
+- 一个需求影响多个 SDK 层级（跨 EPUBCore / EPUBTextRendering / RDReaderView / EPUBUI）
+- 需要完整计划、实现、联调、回归和文档交付
+- 需要跨 EPUB 解析、渲染、阅读器容器、UI 的协同改造
+- 需要明确阶段性计划、回滚点和完整验收说明
+
+Lite 与 Full 的边界：
+- 轻量开发 skill：单层、小中型、MVP 优先
+- 本 skill（start-sdk-feature-dev）：跨层、复杂联调、需要更完整方案和验收
+
+## Inputs
+
+推荐输入模板：
+- 功能名称
+- 背景与目标
+- 用户故事
+- 详细需求
+- 非范围
+- 目标层级（EPUBCore / EPUBTextRendering / RDReaderView / EPUBUI / Legacy）
+- 交互说明（含空态 / 错误态 / 加载态）
+- 渲染路径覆盖要求（webFixedLayout / webInteractive / textReflowable / 不限）
+- 数据与接口约束
+- 验收标准（Given-When-Then）
+- 兼容性要求（Public API 是否 breaking、podspec 变更等）
+- 性能与安全要求
+- 发布时间或优先级
+
+若信息不足：
+- 先基于代码和文档补齐可发现事实
+- 再列最多 5 条关键假设
+- 若没有既定开发计划，可基于假设继续推进最小可落地实现，并在交付中标注待确认项
+- 若已有开发计划，信息不足时不得自行扩展方案；只能做计划内实现或暂停确认
+
+## Scope / Required Context
+
+仅针对 ReadViewSDK 现有架构执行。
+
+SDK 四层架构参照：
+- Layer 1 — EPUBCore（`Sources/RDReaderView/EPUBCore/`）：EPUB 解析引擎，ZIP 解压、OPF 解析、manifest/spine/TOC、资源 URL 解析、离屏 WKWebView 分页、阅读会话状态机、JS 桥接
+- Layer 2 — EPUBTextRendering（`Sources/RDReaderView/EPUBTextRendering/`）：文本渲染路径，DTCoreText 转 NSAttributedString 后按字符范围分页
+- Layer 3 — RDReaderView（`Sources/RDReaderView/` 根目录 6 个文件）：分页阅读器容器 UIView，支持 pageCurl / horizontalScroll / verticalScroll / horizontalCoverScroll 四种模式
+- Layer 4 — EPUBUI（`Sources/RDReaderView/EPUBUI/`）：开箱即用 UI，工具栏、目录面板、高亮管理、设置面板、阅读位置持久化
+- Legacy（`Sources/RDReaderView/LegacyRDReaderController/`）：遗留代码，不在其上新增功能
+
+分层依赖规则：
+- 上层可依赖下层，下层不得依赖上层
+- EPUBUI 可依赖 RDReaderView、EPUBTextRendering、EPUBCore
+- RDReaderView 可依赖 EPUBTextRendering、EPUBCore
+- EPUBTextRendering 可依赖 EPUBCore
+- EPUBCore 不依赖任何上层
+
+若确需跨层改动：
+- 必须在计划中写明影响范围
+- 必须在交付中写明回滚点或回退策略
+
+默认先读：
+1. `Doc/ARCHITECTURE.md` — 四层架构、数据流、分页模式、位置模型、已知限制
+2. `Doc/CODING_STYLE.md` — 命名规范（RD/RDEPUB 前缀）、分层规则、extension 拆分、SS→RD 迁移计划
+3. `Doc/EPUB_MAINTENANCE.md` — 文件职责表、DTCoreText 渲染管线、常见排查场景
+
+按需再读：
+- `Doc/FeatureSolution/*.md`（若有方案文档）
+- 涉及 EPUB 解析时：`Sources/RDReaderView/EPUBCore/` 下相关文件
+- 涉及文本渲染时：`Sources/RDReaderView/EPUBTextRendering/` 下相关文件
+- 涉及阅读器容器时：`Sources/RDReaderView/RDReaderView.swift` 及同级文件
+- 涉及 UI 层时：`Sources/RDReaderView/EPUBUI/` 下相关文件
+- 涉及遗留代码时：`Sources/RDReaderView/LegacyRDReaderController/` 下相关文件
+- 涉及 JS 桥接时：`Sources/RDReaderView/Resources/epub-bridge.js`
+- 涉及 podspec 时：`RDReaderView.podspec`
+
+若文档与代码不一致：
+- 以代码事实为准落地
+- 在交付中说明不一致点和建议更新的文档项
+
+若开发计划文档与代码不一致：
+- 不得直接以代码事实替换计划继续开发
+- 必须先判断不一致是否影响计划执行
+- 会影响计划执行时，暂停并向用户说明冲突点和建议调整项
+- 不影响计划执行时，按计划继续，并在交付中标注该不一致点
+
+## SDK-Specific Execution Rules
+
+### 命名与可见性
+- 所有新增类型必须使用 `RD` 前缀，EPUB 相关使用 `RDEPUB` 前缀
+- 新增类型归属正确层级目录，不得随意放置
+- 可见性按最小原则：`private` > `fileprivate` > `internal` > `public`
+- 数据模型用 `struct` + `Codable` + `Equatable`
+- 服务对象用 `final class`
+
+### 代码组织
+- 单文件超过 600 行需主动拆分 `TypeName+Feature.swift` 扩展文件
+- 大型 Controller 超过 1000 行必须拆分
+- extension 文件承担独立子职责，不只做"行数搬运"
+
+### 内存与并发
+- 异步闭包默认 `[weak self]`
+- UI 更新必须回到主线程
+- 通知 / 定时器 / 回调在 deinit 或生命周期结束时必须清理
+
+### 渲染路径覆盖
+- 新增功能必须评估对三种渲染路径的影响：
+  - `webFixedLayout`：固定版式 EPUB（漫画、绘本）— WKWebView 渲染
+  - `webInteractive`：可重排 + 交互脚本 EPUB — WKWebView 渲染
+  - `textReflowable`：纯文本可重排 EPUB — DTCoreText 渲染
+- 若功能仅适用于部分路径，必须在交付中明确标注适用范围和不适用路径的处理方式
+
+### Public API 兼容性
+- 涉及公共接口（`RDReaderView`、`RDReaderDataSource`、`RDURLReaderController`、`RDEPUBReaderController` 等）的改动，必须评估 breaking change
+- 若存在 breaking change，必须在交付中标注并给出迁移指引
+- 新增 public API 需考虑 Objective-C 互操作（`@objc`、`@objcMembers`）
+
+### CocoaPods 发布影响
+- 新增源文件：确认 podspec `source_files` glob 是否已覆盖
+- 新增资源文件：确认 podspec `resource` / `resource_bundles` 是否已覆盖
+- 新增依赖：确认 podspec `dependency` 是否已声明，评估对宿主 App 的依赖传递影响
+- 模块目录结构调整：必须同步更新 podspec
+
+### JS 桥接
+- 涉及 `epub-bridge.js` 的改动，必须确认 JS ↔ Swift 消息契约的一致性
+- JS 侧新增消息类型时，Swift 侧必须有对应处理分支
+- 修改已有消息类型时，必须评估向后兼容
+
+### 错误处理
+- 使用 `enum` + `LocalizedError` 定义错误类型
+- 禁止 force unwrap（`!`），确需使用时必须先收敛前置条件
+- 关键路径的错误必须向调用方传递，不得静默吞掉
+
+## Required Workflow
+
+### Phase 1 — 识别需求和范围
+
+- 明确目标价值、影响层级（EPUBCore / EPUBTextRendering / RDReaderView / EPUBUI / Legacy）、In Scope / Out of Scope
+- 判断是否涉及跨层、跨渲染路径、跨模块联调
+- 若用户提供开发计划文档，先确认本次执行的唯一计划来源，并提取计划任务清单
+- 优先做计划内最小可落地实现，不做需求外重构
+- 若需求信息不足，先通过仓库事实补齐，再基于假设推进
+
+### Phase 2 — 按需读取 Doc 与代码事实
+
+- 若用户指定开发计划文档，必须先完整读取该文档
+- 先读默认 Doc（ARCHITECTURE / CODING_STYLE / EPUB_MAINTENANCE）
+- 根据需求类型补读各层源码和相关文档
+- 用源码确认真实入口、调用链、数据流、状态流和复用点，不只依赖文档
+
+### Phase 3 — 对齐并锁定开发计划
+
+- 若已有开发计划，必须按计划锁定实现路径，不重新设计方案
+- 若没有开发计划，才允许形成最小可落地方案：先复用现有模式与能力，再考虑新增抽象
+- 保持分层边界：
+  - EPUB 解析逻辑在 EPUBCore
+  - 文本渲染逻辑在 EPUBTextRendering
+  - 分页容器逻辑在 RDReaderView
+  - 开箱即用 UI 在 EPUBUI
+  - 不在 Legacy 层新增功能
+- 命名、注释、日志风格遵循 `Doc/CODING_STYLE.md`
+- Swift / iOS 默认规则：
+  - 新增 Swift 类型遵循 `RD` / `RDEPUB` 前缀和层级目录归属
+  - 避免新增强制解包；确需使用时必须先收敛前置条件
+  - 不为"现代化"而重写稳定代码；仅在本次需求明确受益时再迁移系统 API
+  - 当前项目默认保持 UIKit + Auto Layout + 既有组件风格，SDK 层不使用 SnapKit
+  - 注释和日志使用中文
+  - Debug 输出放在 `#if DEBUG` 守卫下
+  - 不在日志中输出敏感信息
+- 单文件预计超过 600 行需主动拆分，超过 1000 行必须拆分
+- 若为跨层需求，计划中必须写清：
+  - 主改动层级
+  - 被影响层级
+  - 渲染路径覆盖范围
+  - 联调依赖点
+  - 关键风险
+  - 回滚点或降级方式
+- 开始编码前必须形成内部执行清单，清单项必须能追溯到开发计划；计划外项只能标记为"必要补齐"或"待确认"，不能直接实施
+
+### Phase 4 — 执行修改与文档同步
+
+- 所有代码改动遵循计划内最小改动原则
+- 严格按开发计划清单逐项修改；不得临时改换实现方式或增加计划外功能
+- 若执行中需要偏离计划，必须暂停确认，不能先改后说明
+- 修改代码时必须补充必要注释，重点说明关键逻辑、边界条件和不直观处理
+- 默认补做 SDK 自检：
+  - 检查新增类型是否使用正确前缀和层级归属
+  - 检查三种渲染路径的覆盖情况
+  - 检查 Public API 是否有意外 breaking change
+  - 检查 podspec 是否需要更新
+  - 检查 JS 桥接消息契约是否一致
+  - 关键页面或组件检查生命周期、通知/定时器/回调清理是否完整
+  - 新增 UI 检查长文本、图标按钮语义、重要状态是否只靠颜色表达
+  - 异步闭包默认考虑 `[weak self]`，UI 更新回到主线程
+- 修改代码后必须同步更新受影响文档，不能只停留在代码实现
+- 若本次改动涉及 EPUB 维护相关，必须回写 `Doc/EPUB_MAINTENANCE.md`
+- 若本次是方案讨论文档交接落地，方案类文档统一放到 `Doc/FeatureSolution/`
+- 若新增、重命名或移动文档，必须同步更新目录索引
+
+### Phase 5 — 构建验证与交付
+
+- 完成修改后，按项目默认命令执行编译验证
+- 若出现编译错误，自动修复并重编译
+- 若遇构建锁问题，自动重试（建议最多 5 次）
+- 若是跨层需求，除构建外还应补充关键联调路径说明
+- 交付时固定输出：
+  - A. 需求理解
+  - B. 开发计划
+  - C. 开发实施
+  - D. 验证结果
+  - E. 交付摘要
+
+## Output Contract
+
+最终回复必须完整输出以下 5 个固定板块：
+- A. 需求理解
+- B. 开发计划
+- C. 开发实施
+- D. 验证结果
+- E. 交付摘要
+
+各板块内容要求：
+- A：3-8 条，覆盖目标价值、范围、目标层级、渲染路径覆盖、交互流、限制
+- B：按"计划来源 / 计划任务清单 / 执行顺序 / 验证与交付"组织；若有开发计划文档，必须逐条对应计划项
+- C：描述实现过程、复用点、关键取舍，以及本次补充了哪些关键代码注释；若有计划未写明但必须补齐的内容，必须单独标注
+- D：给出编译结果、关键路径验证、自动重试/自动修复情况、未覆盖风险
+- E：列出改动文件、计划符合情况、关键取舍、回滚点或降级方式、已同步文档与具体文档落点、后续建议
+
+## Validation
+
+若本次调用修改了任何 Swift / Objective-C / 工程配置 / podspec 文件，必须执行构建验证。
+
+验证方式：
+- 若 Demo 工程可用：
+  ```bash
+  xcodebuild build -workspace ReadViewSDKDemo/ReadViewSDKDemo.xcworkspace -scheme ReadViewSDKDemo -sdk iphonesimulator -derivedDataPath /private/tmp/readview-sdk-derived
+  ```
+- 若仅有 SDK 源码（无 workspace）：
+  ```bash
+  pod lib lint RDReaderView.podspec --allow-warnings
+  ```
+
+验证规则：
+- 若出现编译错误，必须自动修复并重编译
+- 若遇到 `database is locked` 等构建锁问题，自动重试，建议最多 5 次
+- 直到 `BUILD SUCCEEDED` 或 `pod lib lint passed` 才可进入交付阶段
+- 若本次只改文档或 skill 文件，可跳过编译，但要在交付中明确说明
+
+## Maintenance Rules
+
+- 优先复用 `Doc/`，不要把项目级规则复制进多个 skill 造成双份维护
+- 新增项目约束时，优先更新 `Doc/CODING_STYLE.md`、`Doc/ARCHITECTURE.md` 等主文档，再调整 skill
+- 轻量与完整要保持"轻重不同、规则不冲突"，其中完整版应在轻量版闭环基础上扩展跨层与联调要求，而不是另起一套风格
+- 变更默认流程、输出格式或适用边界时，必须同步更新相关文档
+- 本 skill 持续作为完整开发入口，保持"可执行、可联调、可回滚、可交付"
+- SDK 四层架构（EPUBCore → EPUBTextRendering → RDReaderView → EPUBUI）是执行的核心参照框架，所有改动必须明确标注落点层级和依赖方向