310 lines
16 KiB
Markdown
310 lines
16 KiB
Markdown
---
|
||
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）是执行的核心参照框架，所有改动必须明确标注落点层级和依赖方向
|