287 lines
15 KiB
Markdown
287 lines
15 KiB
Markdown
---
|
||
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）是方案讨论的核心参照框架，任何方案都必须明确标注落点层级
|