# ReadViewSDK AI 开发规则

## 适用范围与语言

- 默认处理当前仓库的 EPUB SDK、PDF SDK、Demo 和测试。
- 计划、交付说明、`Doc/` 与项目 Markdown 使用中文。
- 代码标识符、文件名、API 和配置键保持英文；代码注释、Docstring 和提交信息使用中文。
- 只做当前目标所需的最小改动，保留工作区内与任务无关的未提交修改。
- 任何写文件的 agent 必须先读取 `CONTEXT.md`。

## 自动选择项目 Skill

根据用户意图选择 `.agents/skills/` 中最匹配的 Skill：

- 先讨论、比较方案、不要改代码：`discuss-sdk-feature-solution`
- 单模块功能、Bug 修复、UI 调整、局部重构、构建修复：`start-sdk-feature-dev-lite`
- 跨层/跨阅读器改造、公共 API 或持久化迁移、复杂联调、完整方案执行：`start-sdk-feature-dev`
- 隐藏问题、并发、生命周期、性能、内存、缓存或兼容性审查：`review-swift-ios-sdk`
- 全局代码规范：`generate-sdk-code-style-doc`
- 单模块代码规范：`generate-module-code-style-doc`
- 模块调用链、状态流、分页或缓存实现逻辑：`generate-module-implementation-logic`
- 审查改动、生成详细中文提交说明并提交或推送 Git：`commit-git-changes`

不要为简单任务叠加多个 Skill。用户明确指定 Skill 时优先使用；任务边界扩大时再切换或补充，并说明原因。

## 文档按需读取

先定位源码，再读取直接相关文档，不默认全文加载整个 `Doc/`：

| 任务 | 必读资料 |
| --- | --- |
| 任意代码修改 | `CONTEXT.md`、`Doc/CONVENTIONS.md` 相关章节 |
| 分层或跨模块改造 | `Doc/ARCHITECTURE.md` |
| 公共 API | `Doc/API_REFERENCE.md` 与真实 public 声明 |
| EPUB 解析/排版/分页/UI | 对应 `Doc/*_CODE_REFERENCE.md` 或专题文档 |
| PDF 阅读器 | `Sources/RDPDFReaderView` 源码；现有文档不足时以源码为准 |
| 测试与回归 | `Doc/TESTING.md` |
| 用户指定方案 | 指定文档，必须完整读取 |

`Doc/index.md` 用于路由。文档与源码冲突时以当前源码为事实，并指出待同步项。

## 模块边界

- EPUB：`EPUBCore` → `EPUBTextRendering` → `ReaderView` → `EPUBUI`，禁止下层反向依赖上层。
- PDF：通用分页容器位于 `Sources/RDPDFReaderView/ReaderView`，成品能力位于 `Sources/RDPDFReaderView/Sources`。
- Demo 和 UITests 只承担集成、样例与回归，不承载 SDK 核心业务。
- 保持 UIKit、SnapKit 和当前 CocoaPods 结构；新增依赖、资源或系统 framework 时同步检查对应 podspec。
- 新增类型遵循现有 `RD`、`RDEPUB`、`RDPDF` 前缀和最小可见性。

## SDK 兼容与质量

- 修改 public API 前评估宿主源码兼容、默认行为和迁移方式。
- 修改 Codable、持久化文件、缓存键或 book identifier 时提供版本与失效/迁移策略。
- UI 更新回主线程；异步任务处理取消、超时、迟到结果、恰好一次完成和生命周期。
- EPUB 改动检查 `.textReflowable`、`.webInteractive`、`.webFixedLayout` 的影响。
- PDF 改动检查宿主图片 Provider 与内置 PDFKit Provider 的影响。
- 滚动、缩放、分页和绘画热点避免同步 IO、重复解码、无界缓存和大对象长期驻留。

## 验证

修改 Swift、工程配置或 podspec 后默认执行：

`xcodebuild -workspace ReadViewDemo/ReadViewDemo.xcworkspace -scheme ReadViewDemo -configuration Debug -sdk iphonesimulator CODE_SIGNING_ALLOWED=NO build`

按风险补充 `Doc/TESTING.md` 中的定向 UI 测试。仅修改文档、规则或 Skill 时可跳过 Xcode 构建，但必须执行结构、引用和格式检查。

如果使用 XcodeBuildMCP，调用其工具前必须先读取已安装的 XcodeBuildMCP Skill，并先检查 session defaults。