214 lines
9.3 KiB
Markdown
214 lines
9.3 KiB
Markdown
---
|
||
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 四层架构是执行的核心参照框架，单层改动也必须明确标注落点层级
|