shenlei
95cead5863
PDF 阅读器在慢速双指缩放、竖向滚动页高异步更新、页面请求超时和绘画橡皮擦等场景中，存在视口跳动、迟到结果被错误丢弃、缓存边界不明确及笔迹显示与持久化不同步的问题；同一本书的标注读取和并发写入也会产生不必要的磁盘访问或覆盖风险。\n\n调整缩放 inset 计算和竖向阅读锚点恢复，避免缩放变换被重复计入、真实页高到达时改变当前阅读位置。页面请求改为带 token 的超时重试机制，可在缓存窗口内接收有效迟到结果并提供失败重试入口；页面大图、OCR、笔迹和描述缓存统一按当前页前后两页收敛，PDF 标识改为完整内容 SHA-256，避免同名或相近文件复用错误阅读状态。\n\n绘画会话内按路径实时重绘，退出会话后使用按图层派生的位图缓存，确保橡皮擦即时作用于已提交笔迹；同时为笔迹持久化增加版本控制、为标注读写增加同步保护和内存快照，降低复用与并发场景下的状态错乱。\n\n将项目技能统一迁入 .agents/skills，并以 .claude/skills 相对软链接供 Claude Code 读取；新增详细 Git 提交技能，自动审查改动、生成中文提交说明并约束安全推送。 验证：所有项目技能通过 quick_validate；执行 xcodebuild -workspace ReadViewDemo/ReadViewDemo.xcworkspace -scheme ReadViewDemo -configuration Debug -sdk iphonesimulator CODE_SIGNING_ALLOWED=NO build，构建成功。
68 lines
3.8 KiB
Markdown
68 lines
3.8 KiB
Markdown
# 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。
|