最佳实践

书源规则

• 保留原始 bookSourceUrl 身份，仅在请求阶段使用 effectiveBaseUrl；
• HTML/JSON 规则优先，只有真实需要才用 JS 或 WKWebView；
• 搜索/发现页只提取当前列表已有信息，不逐本请求详情；
• 目录抓取完成后再做高置信顺序修复，保留 URL、VIP/pay、tag 和 variable；
• 正文下一页设置最大深度、已访问 URL 集合和重复内容检测；
• 登录 Cookie、headers、线路和 source variable 按来源隔离；
• concurrentRate 与用户并发设置同时生效，不用无限并发绕过限制——比如写 "concurrentRate": "1000" 表示同一书源两次请求至少间隔 1000ms，用户在设置里把全局并发 调得再高，这条书源自己的限速依然生效，两者取更保守的一个。

阅读器

• 网络、磁盘、清洗和 TextKit 分页都在边界前完成；
• 字符范围连续性优先于“页面看起来差不多”；
• 独立边距、信息栏和 safe area 只计算一次；
• 连续滚动 fragment 使用实测高度；
• 进度用章节内字符 offset 恢复，不只依赖 page index；
• 低电量/热状态收缩预取和验证并发。

日志

每个 source stage 记录 source、function、request ID、URL 摘要、状态、耗时、响应类型和解析 数量。Cookie、Authorization、token、邮箱和设备值脱敏。Release 默认关闭高频全局 probe。

交付

每项功能必须有代码入口、fixture、回放、Apple build 结果；WebView、音频、VoiceOver、滚动 和性能还需要真机证据。不要把 HTTP 200 或 Python success 写成产品完整可用。