修复 PDF 阅读交互稳定性并统一项目技能管理

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，构建成功。
2026-07-24 14:40:02 +09:00
parent 68d9363f0a
commit 95cead5863
30 changed files with 995 additions and 907 deletions
@@ -0,0 +1,92 @@
+---
+name: commit-git-changes
+description: 审查当前 Git 工作区，安全选择本次任务文件，执行必要校验，生成包含问题背景、根因、修改方案和验证结果的详细中文提交说明，并提交及按用户要求推送到 Git 服务器。用户要求“提交代码”“提交并推送”“同步到 Git”“上传当前修改”或要求生成详细 commit message 时使用。
+---
+
+# 提交 Git 改动
+
+## 目标
+
+在不混入无关修改、不泄露敏感信息、不改写远端历史的前提下，完成“审查—验证—暂存—提交—推送—确认”闭环，并用提交说明解释为什么修改以及如何解决，而不只是罗列文件。
+
+## 工作流
+
+1. 读取仓库级 `AGENTS.md`、当前分支、远端和工作区状态。
+2. 检查暂存与未暂存差异：
+   - 使用 `git status --short` 确认全部改动。
+   - 使用 `git diff` 和 `git diff --cached` 理解真实行为变化。
+   - 必要时查看相关源码和测试，不能仅依据文件名编写提交说明。
+3. 划定本次提交范围：
+   - 只纳入当前用户任务直接相关的文件。
+   - 保留用户已有或其他任务产生的无关修改。
+   - 优先显式 `git add <path...>`；仅在确认所有改动均属本次提交时使用 `git add -A`。
+   - 发现密钥、令牌、证书、个人配置、大型生成物或疑似敏感数据时停止提交并说明。
+4. 根据改动风险执行项目约定的构建、测试或静态检查。
+   - 不为通过校验而擅自扩大修改范围。
+   - 不能运行的校验必须如实记录原因，不得声称已通过。
+5. 暂存后再次检查：
+   - 执行 `git diff --cached --check`。
+   - 执行 `git diff --cached --stat` 和 `git diff --cached`。
+   - 确认暂存区没有无关文件、调试残留和意外格式变化。
+6. 编写详细中文提交说明并创建提交。
+7. 用户要求提交到服务器或同步远端时推送：
+   - 有 upstream 时推送当前分支。
+   - 没有 upstream 且远端、目标分支明确时，使用 `git push -u <remote> <branch>`。
+   - 远端或目标分支不明确时先询问，不猜测。
+   - 禁止 force push；除非用户明确要求且风险已说明。
+8. 提交后确认提交哈希、提交标题、当前分支、推送结果和剩余未提交改动。
+
+## 提交说明规范
+
+提交说明使用“标题 + 空行 + 详细正文 + 验证结果”的结构。
+
+### 标题
+
+- 用一句中文概括用户可感知的问题和修复结果。
+- 优先写清触发条件、异常表现和结果，例如：
+  `修复无训练点普通课程完成后重进播放页回退为未完成`
+- 使用明确动词，如“修复”“新增”“调整”“重构”“移除”。
+- 不使用“修改代码”“优化问题”“更新若干内容”等空泛描述。
+- 保持单行，不以句号结尾，不添加无依据的工单号或模块前缀。
+
+### 正文
+
+用完整段落解释以下内容：
+
+1. **问题背景与影响**：什么场景触发、用户看到什么、影响哪些路径。
+2. **根因**：原有数据流、状态条件或实现约束为什么导致问题。
+3. **修改方案**：关键行为如何改变，为什么选择该方案，必要时说明兼容和边界处理。
+4. **验证结果**：实际运行了哪些构建、测试或检查；未运行时写明原因。
+
+正文应描述行为和因果关系，不要把 `git diff --stat` 改写成文件清单。多个紧密相关的修改可以分段说明，但不要堆砌逐文件 bullet。
+
+### 示例
+
+```text
+修复无训练点普通课程完成后重进播放页回退为未完成
+
+课件完成态本地记录的保存不区分训练点，但读取端仅在存在
+trainPointModel 时才创建合并器，导致班级、训练和项目均为空的普通课程
+重进播放页后无法读取本地完成记录。
+
+改为始终创建完成态合并器：无训练点时使用空维度合并；由于该场景没有
+服务端完成态可供对账，将本地记录作为唯一持久来源并跳过超期回收，保持
+重新进入播放页后的完成状态稳定。
+
+验证：完成目标场景回归，并通过 Debug 模拟器构建。
+```
+
+根据真实改动改写示例内容，禁止照抄未发生的场景或验证结论。
+
+## 提交与推送约束
+
+- 不使用 `git reset --hard`、`git checkout --`、`git clean` 等破坏性命令处理工作区。
+- 不使用 `--amend`、rebase、历史改写或强制推送，除非用户明确授权。
+- 不跳过 hooks；hook 失败时先分析原因，不使用 `--no-verify` 绕过。
+- 提交失败后保留暂存区，修复可控问题并重试；不要重复创建等价提交。
+- 推送被拒绝时先获取并解释分支差异，不自动合并、变基或覆盖远端。
+- 若没有可提交差异，直接说明，不创建空提交。
+
+## 交付
+
+报告提交哈希和标题、推送的远端分支、验证结果，以及仍留在工作区的未提交修改。若只完成本地提交而未推送，必须明确说明。
@@ -0,0 +1,4 @@
+interface:
+  display_name: "提交 Git 代码"
+  short_description: "安全审查改动并生成详细中文说明，完成 Git 提交与远端推送"
+  default_prompt: "使用 $commit-git-changes 审查当前改动，生成详细中文提交说明并提交到 Git 服务器。"
@@ -0,0 +1,44 @@
+---
+name: discuss-sdk-feature-solution
+description: 讨论 ReadViewSDK 的新功能、修复或重构方案，核验 EPUB/PDF 阅读器源码，比较实现路径并收敛为可直接开发的计划。用户说“先讨论”“先给方案”“比较方案”“不要改代码”，或接口、缓存、渲染路径、持久化兼容存在会改变实现方式的灰区时使用；路径已明确且用户要求直接修改时不要使用。
+---
+
+# SDK 功能方案讨论
+
+## 目标
+
+在编码前用仓库事实收敛决策，输出最小、可验证、能交给开发 Skill 直接执行的方案。本 Skill 默认不修改业务代码。
+
+## 工作流
+
+1. 检查工作区并定位目标模块、入口、相邻实现和对应文档。
+2. 区分已锁定决定、阻塞决定、实现假设、后续项与非范围。
+3. 按根目录 `AGENTS.md` 读取所需文档；结论必须由真实路径、类型、方法和调用链支撑。
+4. 方案未定时给出 2–4 个可行路径，比较改动面、公开 API、缓存/持久化、渲染路径、性能、回归和维护成本，并明确推荐一个。
+5. 用户已选定方案时只细化该方案，不继续横向发散。
+6. 方案至少覆盖：
+   - EPUB：`.textReflowable`、`.webInteractive`、`.webFixedLayout` 中受影响的路径
+   - PDF：宿主图片 Provider 与内置 PDFKit Provider 中受影响的路径
+   - 公共 API、Codable/磁盘格式、缓存版本和 CocoaPods 集成影响
+   - 异步乱序、取消、生命周期、内存压力和失败降级
+7. 收敛为文件级任务、数据/状态流、成功标准、验证方式、风险和回滚点。
+
+## 输出
+
+默认在对话中给出：
+
+- 需求、范围与非范围
+- 已确认决定、阻塞项和必要假设
+- 方案对比或已选方案拆解
+- 涉及文件、调用链、复用点和兼容策略
+- 风险、回滚点与验证清单
+- 建议交给 `start-sdk-feature-dev-lite` 或 `start-sdk-feature-dev` 的执行摘要
+
+用户要求落文档，或方案需要跨会话执行时，写入 `Doc/FeatureSolution/`，并在存在文档索引时同步 `Doc/index.md`。
+
+## 边界
+
+- 不为未确认的未来需求预埋抽象。
+- 必要改动、可选优化和后续治理必须分开。
+- 未核验的系统 API、第三方能力、文件格式或缓存行为不得写成事实。
+- 文档与源码冲突时以当前源码为事实，并明确指出文档待同步项。
@@ -0,0 +1,4 @@
+interface:
+  display_name: "SDK 功能方案讨论"
+  short_description: "核验当前仓库事实，比较实现路径并输出可直接开发的完整方案"
+  default_prompt: "Use $discuss-sdk-feature-solution to compare implementation paths and produce an executable handoff."
@@ -0,0 +1,23 @@
+---
+name: generate-module-code-style-doc
+description: 基于真实源码生成或更新 ReadViewSDK 指定模块的代码组织、命名、分层、UI、状态、缓存和复用规范，适用于 EPUBCore、EPUBTextRendering、ReaderView、EPUBUI、RDPDFReaderView 或 Demo。全局规范使用 generate-sdk-code-style-doc。
+---
+
+# 生成模块代码规范
+
+## 工作流
+
+1. 确定目标模块、关注范围和输出文件；优先增量更新 `Doc/` 中现有对应文档。
+2. 读取目标模块源码、对应 code reference、`Doc/CONVENTIONS.md` 和必要架构章节。
+3. 抽样入口、协议、模型、View/Cell、Controller、Coordinator/Service、缓存和 Extension；不存在的层级不要补造。
+4. 提炼真实且重复出现的模式，并区分当前约定、特殊例外及原因、尚未落地的建议。
+5. 记录目录职责、命名、可见性、依赖方向、状态管理、布局、回调、缓存、失败处理、公共 API 和跨模块边界。
+6. 对 EPUB 模块说明适用的渲染路径；对 PDF 模块说明自定义 Provider 与 PDFKit 路径差异。
+7. 增量更新文档，检查与全局规范、podspec、架构和源码是否冲突。
+8. 文档新增、移动或重命名时同步 `Doc/index.md`。
+
+## 边界
+
+- 只描述目标模块，不把局部模式提升为全局事实。
+- 不虚构理想分层、协议或不存在的调用链。
+- 默认不修改业务代码；发现问题时作为建议或 finding 单独列出。
@@ -0,0 +1,4 @@
+interface:
+  display_name: "生成模块代码规范"
+  short_description: "基于真实源码生成指定 EPUB、PDF 或 Demo 模块的局部规范文档"
+  default_prompt: "Use $generate-module-code-style-doc to document the coding patterns of this ReadViewSDK module."
@@ -0,0 +1,34 @@
+---
+name: generate-module-implementation-logic
+description: 从 ReadViewSDK 真实源码生成或更新指定模块或场景的入口、调用链、数据流、状态流、渲染流、缓存、持久化、异步回调和异常分支文档。用户要求梳理实现逻辑、调用链、分页或缓存流程时使用；代码风格规范改用对应 code-style Skill。
+---
+
+# 生成模块实现逻辑
+
+## 工作流
+
+1. 确定目标模块、用户场景和输出路径；优先复用 `Doc/` 中现有专题或 code reference。
+2. 读取目标入口、现有文档，以及 `AGENTS.md` 路由出的架构、API 或测试资料。
+3. 用引用搜索沿真实关系追踪：
+   - 页面、控制器、协议或服务入口及触发条件
+   - 数据模型、状态所有者和线程/队列
+   - EPUB 解析/排版/分页/章节窗口，或 PDF Provider/渲染/OCR/标注
+   - 内存与磁盘缓存、键、版本、驱逐和恢复
+   - 通知、回调、delegate、持久化和跨模块依赖
+   - 空值、失败、取消、重试、超时、迟到结果和兼容分支
+4. 对关键链路至少双向核验一次：从入口跟到结果，再从结果或回调查回调用方。
+5. 区分当前实现、历史兼容层、仅文档中的计划和待确认事实。
+6. 增量更新文档，保留正确内容，删除或标记失效链路。
+7. 结论引用真实文件、类型和方法；不确定信息明确标为待确认。
+8. 文档新增、移动或重命名时同步 `Doc/index.md`。
+
+## 推荐结构
+
+- 适用范围与模块职责
+- 入口和主要对象
+- 主流程与数据/状态/渲染变化
+- 缓存、持久化和并发模型
+- 异常、取消、重试和兼容处理
+- 维护风险与验证要点
+
+纯文档任务不修改业务代码；源码暴露的缺陷应单独报告，不把建议写成已实现事实。
@@ -0,0 +1,4 @@
+interface:
+  display_name: "生成模块实现逻辑"
+  short_description: "梳理指定阅读器模块的入口、调用链、状态流、缓存及异常分支"
+  default_prompt: "Use $generate-module-implementation-logic to document this module's verified implementation flow."
@@ -0,0 +1,26 @@
+---
+name: generate-sdk-code-style-doc
+description: 基于 ReadViewSDK 当前 EPUB、PDF 和 Demo 源码生成或更新全局代码规范、目录职责、命名、分层、UIKit/SnapKit、并发、缓存、公共 API 与测试约定。用户要求项目级编码规范或更新 Doc/CONVENTIONS.md 时使用；单模块规范改用 generate-module-code-style-doc。
+---
+
+# 生成 SDK 全局代码规范
+
+## 工作流
+
+1. 明确输出路径；未指定时增量更新 `Doc/CONVENTIONS.md`。
+2. 读取现有目标文档、`Doc/ARCHITECTURE.md`、`Doc/index.md` 和两个 podspec。
+3. 从 EPUBCore、EPUBTextRendering、ReaderView、EPUBUI、RDPDFReaderView 与 Demo/UITests 抽样真实源码。
+4. 把结论分为：
+   - 多模块源码验证的现行约定
+   - 仅适用于 EPUB、PDF 或 Demo 的局部模式
+   - 明确标记为建议、尚未成为项目事实的待统一项
+5. 覆盖目录职责、命名与可见性、公共 API、UIKit/SnapKit、异步与取消、缓存/持久化、错误处理、测试、注释和 CocoaPods 约定。
+6. 增量保留仍正确内容，删除失效描述；使用真实路径、类型和方法作为证据。
+7. 新增、移动或重命名文档时同步 `Doc/index.md`，最后检查链接和源码一致性。
+
+## 边界
+
+- 不把 EPUB 的局部模式提升为 PDF 的全局规范，反之亦然。
+- 不以旧 `.claude/skills` 或过期文档替代当前源码事实。
+- 不把个人偏好写成现行规范。
+- 文档任务默认不修改业务代码；发现缺陷时单独报告。
@@ -0,0 +1,4 @@
+interface:
+  display_name: "生成 SDK 全局规范"
+  short_description: "从当前 EPUB 与 PDF 源码证据生成或更新项目级代码规范文档"
+  default_prompt: "Use $generate-sdk-code-style-doc to update the project-wide coding conventions from source evidence."
@@ -0,0 +1,48 @@
+---
+name: review-swift-ios-sdk
+description: 对 ReadViewSDK 的 Swift/iOS 代码进行专项审查，覆盖并发、主线程、生命周期、内存、缓存、渲染性能、可访问性、安全、公共 API 和持久化兼容。用户要求继续检查隐藏问题、代码审查、性能或内存审计时使用；普通功能开发和纯文档任务不要单独使用。
+---
+
+# Swift/iOS SDK 专项审查
+
+## 工作流
+
+1. 明确审查范围和修改授权；只要求审查时不得修改代码。
+2. 检查工作区和最近改动，读取目标代码、相邻实现及 `AGENTS.md` 路由出的文档。
+3. 沿入口、异步回调、持久化和渲染结果双向追踪，不只检查单个函数。
+4. 仅报告能由当前源码证明、可触发且值得行动的问题。
+
+## 检查维度
+
+### 并发与生命周期
+
+- UI 是否回到主线程，迟到结果是否会覆盖新状态。
+- token、重试、超时和取消是否保证恰好一次完成。
+- 闭包、Task、通知、定时器、观察者、WKWebView 和 Vision 请求是否释放。
+- PDFKit、缓存字典和持久化文件是否在正确队列或锁内访问。
+
+### 性能与内存
+
+- 滚动、缩放、绘画和分页热点是否包含同步 IO、重复解码或重复排版。
+- EPUB 章节窗口、页图缓存、PDF 页面位图和绘画缓存是否有明确边界。
+- 内存警告后可见内容能否恢复，驱逐后迟到回调是否重新撑大缓存。
+- 图片像素成本、NSCache 限额、autoreleasepool 和大对象生命周期是否合理。
+
+### SDK 兼容性
+
+- `public` API、协议要求、初始化方法和默认行为是否意外 breaking。
+- Codable、文件名、缓存键、book identifier 和 schema version 是否可迁移。
+- EPUB 三种渲染路径和 PDF 两种 Provider 路径是否行为一致。
+- podspec 是否包含新增源码、资源、系统 framework 和依赖。
+
+### 交互、安全与可访问性
+
+- 缩放锚点、Cell 复用、双页布局、手势竞争和绘画图层是否稳定。
+- 图标按钮、自定义控件、动态字体和 VoiceOver 语义是否完整。
+- 日志、文件路径和错误信息是否泄露敏感数据。
+
+## 输出
+
+按严重程度列出 findings；每条包含位置、触发条件、用户影响、根因和最小修复建议。没有发现问题时明确说明，并列出尚未覆盖的运行时验证空白。
+
+若用户同时要求修改，沿用对应开发 Skill 的实现、验证和交付规则。
@@ -0,0 +1,4 @@
+interface:
+  display_name: "Swift/iOS SDK 专项审查"
+  short_description: "审查并发、生命周期、性能、内存及公开 API 风险"
+  default_prompt: "Use $review-swift-ios-sdk to audit this ReadViewSDK code for iOS-specific risks."
@@ -0,0 +1,41 @@
+---
+name: start-sdk-feature-dev-lite
+description: 实现 ReadViewSDK 的单模块功能、Bug 修复、UI 调整、局部重构、编译修复或小范围 CocoaPods 变更，并完成必要验证。作为默认开发入口；跨 EPUB/PDF 模块、改变公共协议或持久化格式、需要迁移回滚或严格执行完整方案时使用 start-sdk-feature-dev。
+---
+
+# SDK 轻量开发
+
+## 目标
+
+用最小改动完成边界清晰的任务，形成“实现—验证—交付”闭环。
+
+## 工作流
+
+1. 检查工作区，识别并保留用户已有修改。
+2. 定位目标源码、现有相邻模式和 `AGENTS.md` 路由出的文档。
+3. 若用户提供方案，完整读取并执行已锁定决定；源码事实使方案不可行时先说明冲突。
+4. 明确 In Scope、Out of Scope、成功标准和短执行清单。
+5. 按模块边界实施最小修改：
+   - EPUB 解析与资源：`Sources/RDEpubReaderView/EPUBCore`
+   - EPUB 文本排版：`Sources/RDEpubReaderView/EPUBTextRendering`
+   - EPUB 翻页容器：`Sources/RDEpubReaderView/ReaderView`
+   - EPUB 成品 UI：`Sources/RDEpubReaderView/EPUBUI`
+   - PDF 阅读器：`Sources/RDPDFReaderView`
+   - 集成与回归入口：`ReadViewDemo`
+6. 自检空值、失败分支、异步乱序、取消语义、主线程、生命周期、Cell 复用、缓存边界、内存警告和可访问性。
+7. 检查公共 API、持久化模型、缓存键/版本、资源路径及 podspec 是否被意外改变。
+8. 按风险执行构建或定向 UI 测试；编译错误应修复并重试。
+9. 代码行为显著变化时更新最接近的 `Doc/` 文档。
+
+## 升级条件
+
+出现以下任一情况时切换到 `start-sdk-feature-dev` 并说明：
+
+- 同时改变 EPUB 与 PDF 阅读器，或改变多个 EPUB 层级的职责。
+- 修改宿主可见协议、公共初始化方法或需要兼容迁移。
+- 改变持久化格式、缓存架构、分页主流程或跨模块状态流。
+- 用户要求逐项执行完整开发方案。
+
+## 交付
+
+最终简洁说明完成内容、关键取舍、主要文件、验证结果、未覆盖风险和同步文档；不强制套固定模板。
@@ -0,0 +1,4 @@
+interface:
+  display_name: "SDK 轻量开发"
+  short_description: "完成局部功能、Bug 修复、小范围重构及对应构建验证闭环"
+  default_prompt: "Use $start-sdk-feature-dev-lite to implement this scoped ReadViewSDK change and verify it."
@@ -0,0 +1,43 @@
+---
+name: start-sdk-feature-dev
+description: 实现 ReadViewSDK 的跨层或跨阅读器改造、分页/缓存/持久化系统性重构、公共 API 演进、复杂联调，或严格执行用户提供的完整方案文档。单模块功能、UI 微调、Bug 修复和局部改动优先使用 start-sdk-feature-dev-lite。
+---
+
+# SDK 完整开发
+
+## 目标
+
+对复杂任务建立可追溯计划，控制接口兼容、依赖、迁移和回滚风险，完成实现、联调、验证与文档同步。
+
+## 工作流
+
+1. 检查工作区，区分本任务改动和用户已有改动。
+2. 明确主改动模块、受影响模块、In Scope、Out of Scope、联调依赖和完成标准。
+3. 按 `AGENTS.md` 读取架构、公共 API、目标子系统和测试文档，并用源码复核。
+4. 用户提供方案时：
+   - 完整读取并提取锁定决定、任务清单、文件清单、限制和验收标准。
+   - 逐项执行，不自行替换技术路径、数据模型或文件布局。
+   - 方案与源码冲突时暂停，说明影响和最小修订建议。
+5. 没有方案时制定最小可落地计划，明确执行顺序、数据/状态流、风险、回滚点和验证。
+6. 实施时区分计划内修改、不可避免的“必要补齐”和可选后续项；会改变方案的偏差先确认。
+7. 做跨模块自检：
+   - EPUB 四层依赖方向和三种渲染路径
+   - PDF 自定义 Provider 与 PDFKit 直读路径
+   - 公共 API 的源码兼容与行为兼容
+   - Codable/磁盘格式迁移、缓存键、版本和失效策略
+   - 异步 token、取消、迟到回调、主线程和生命周期
+   - 大图、排版产物、章节窗口和内存警告处理
+   - CocoaPods source/resource/framework 配置和 Demo 集成
+8. 同步架构、API、子系统或测试文档；文档新增或移动时更新索引。
+9. 执行构建和与风险相称的定向回归，记录无法自动覆盖的联调项。
+
+## 方案控制
+
+- 用户确认的方案不能被“更简单的建议”静默覆盖。
+- 不以顺手治理为由扩大重构范围。
+- 涉及线上数据、缓存迁移或公共 API 时必须写明兼容、回滚或降级方式。
+- 新增依赖、资源或公开类型前必须确认 podspec 和宿主集成影响。
+
+## 交付
+
+最终说明范围和计划完成情况、关键实现与偏差、改动模块、构建/测试结果、兼容与回滚策略、未覆盖风险和同步文档。
@@ -0,0 +1,4 @@
+interface:
+  display_name: "SDK 完整开发"
+  short_description: "执行跨阅读器模块改造、复杂联调、兼容评估与完整验证交付"
+  default_prompt: "Use $start-sdk-feature-dev to implement this cross-module ReadViewSDK plan with full verification."