PTools 路线图

当前代码基线：5.69.0（来自 VERSION，由 PooTools.podspec 读取）

当前最新正式 Git tag：5.67.3；5.69.0 为当前开发基线，真机/宿主回归与发布证据完成前尚未创建正式 tag。

5.68.0 PTCollectionView / PTBannerView 滚动统一

PTBannerView 的内部列表统一使用 PTCollectionView，保留可视区域分页、无限循环和稳定逻辑下标。
自动轮播在拖动开始时暂停；拖动无减速结束或减速完成后才恢复，避免手指仍在操作时自动跳页。
Banner 内部滚动条默认隐藏，普通 PTCollectionView 仍可通过配置保留滚动条。
迁移指南：滚动样式 / Banner 迁移。

5.67.4 导航标题布局统一

✅ 新增纯值 PTNavigationTitleLayoutResolver 与 PTNavigationTitleSizeResolver，统一标题区域和标题尺寸计算，处理非法尺寸、空间不足和安全降级。
✅ 系统导航容器与 PTNavBar 共用同一套解析结果；按钮尺寸、标题模式、分屏可见区域和伪导航栏宿主高度变化都通过同一条状态更新路径刷新。
✅ 保留现有公开方法签名、默认值、SnapKit .snp 入口、原生竖向导航栏和大标题转场行为，避免改变已有调用方的视觉契约。
✅ 增加 NAV-TITLE-001 至 NAV-TITLE-014 几何/尺寸回归，并补充系统导航容器与独立导航栏的运行时回归覆盖。
⬜ 仍需在真实宿主、iPhone Duo 和 watchOS/visionOS/macOS 对应可用边界完成设备/视觉验证；本轮未创建正式 Git tag。

5.67.0 PTLayout 3.0 原生约束布局

✅ 新增独立 PToolsConstraintLayout SwiftPM product 和 CocoaPods ConstraintLayout subspec，仅依赖 UIKit/Foundation，不依赖 SnapKit、ptools 或 PooToolsLayout。
✅ 提供 SnapKit 风格的约束、更新、重建、移除、优先级、Safe Area、键盘、RTL、组约束、布局句柄和结构化诊断入口；旧 .snp 兼容边界保持不变。
✅ 缺少父视图、跨层级引用、孤立布局指南、签名不匹配和非法事务均返回诊断，不使用 fatalError；批量约束先预检再原子激活。
✅ 增加 56 个具名故障夹具、10 个 Example Demo ID、独立测试目标、迁移清单、依赖/所有权审计和性能采集报告。
✅ PooTools-Example iOS Simulator Debug/Release、SwiftPM manifest、CocoaPods podspec/lock、依赖方向和 PTLayout 静态门禁通过。
⬜ 仍需在 iOS Simulator 上执行独立 XCTest 运行时夹具、视觉回归和同条件性能对比，并完成 watchOS/visionOS/macOS 宿主验证后创建正式 tag。

5.66.1 PTSearchViewController 清空搜索恢复

✅ 保留调用方通过 setResults、增删改入口提供的未筛选结果快照。
✅ 清空输入框时恢复未筛选列表，不再把结果错误替换为空数组。
✅ 搜索状态中的分页、远程结果和显式 clearResults 不会污染清空后应恢复的数据。
⬜ 仍需在真实宿主中验证 clear button、搜索结果、历史记录和不同列表 Cell 的视觉回归。

5.65.8 SwiftPM Core 公共产品边界修复

✅ 将已存在的 PToolsNetworkModelCore target 发布为公开 product，业务方可以直接导入 PTModelNetworkResponse 等类型化响应契约。
✅ 将已存在的 PToolsFontCatalogCore target 发布为公开 product，业务方可以直接导入 PTFont、PTFontCatalog 和兼容字体目录，而不依赖 ptools 聚合入口。
✅ 将两个公共 product 纳入 SwiftPM consumer fixture、Debug/Release 构建矩阵和包/依赖矩阵。
⬜ 仍需在真实宿主项目中完成 SwiftPM 5.65.8 的最终真机回归；本轮不修改 YD1688 的业务兼容外观。

5.65.7 SwiftPM 全模块消费者矩阵收口

✅ PooToolsBioID 显式依赖并导入 PooToolsKeyChain，复用 PTBiologyVerifyStatus 的唯一实现。
✅ PooToolsScrollBanner、PooToolsGuide 和 PooToolsMediaViewer 显式导入 PooToolsPageControl，保持 target 依赖与源码边界一致。
✅ 生成全部 152 个 library product 的独立 iOS Xcode consumer target，Debug/Release 构建逐 product 记录日志和 xcresult。
✅ 新增 API surface、ownership parity、依赖违规、条件编译/资源矩阵和历史问题矩阵报告。
✅ 新增一键审计、诊断合并、严格发布门禁及 GitHub Actions 矩阵工作流；not_run、外部宿主和真机验证不再被伪装为通过。
⬜ 当前工作树完成静态审计和关键产品验证后，仍需执行完整 152 × Debug/Release 矩阵及 BaboBuy/YD1688 真机宿主回归。

5.65.6 SwiftPM Core 视频资源入口收口

✅ 将 URL.pt_isVideoResource 提升为 Core 的公开跨 target API，保留内部视频扩展名集合实现。
✅ MediaViewer 和 ScrollBanner 不再直接访问 GlobalVideoExts，统一复用 Core 视频资源判定逻辑。
✅ 将 pt_isVideoResource 纳入全模块 SwiftPM 符号归属审计，覆盖同类隐式依赖。
⬜ 仍需在真实宿主项目中完成独立 SwiftPM Debug/Release 与真机回归。

5.65.5 SwiftPM UI Foundation 边界收口

✅ 修复 PooToolsInput/YoshikoTextField 缺少 PToolsUIFoundation 显式导入的问题。
✅ 为 PooToolsMediaViewer、PooToolsScrollBanner 和 PooToolsWhatsNewsKit 补齐直接 PToolsUIFoundation target 依赖。
✅ 将 PTRichText、PTTextActionID 和 PTTextActionRegistry 纳入全模块跨 target 符号审计。
✅ 全模块严格审计结果为 open=0，避免 CocoaPods 聚合可见性掩盖 SwiftPM 独立编译问题。
⬜ 仍需在真实宿主项目中完成独立 SwiftPM Debug/Release 与真机回归。

5.65.4 SwiftPM 全模块导入边界收口

✅ 修复 PooToolsSmartScreenshot 和 PooToolsProgressBar 独立 target 对 Core 聚合 target 的显式导入缺失。
✅ 扩展全模块 SwiftPM 审计并补齐 C7Collector、Hud、Network、Paging、SplitView、Debug、权限等可选 target 的直接导入边界。
✅ 为 ptools 聚合 target 内直接使用 PToolsCore 符号的文件补齐拆分 Core 导入，并为网络运行时测试声明 PToolsCore 直接依赖。
✅ 强化跨 target 符号归属审计，支持 @testable import 并排除非 SwiftPM 分支的误报。
⬜ 仍需在真实宿主项目中完成独立 SwiftPM Debug/Release 与真机回归。

5.65.3 WhatsNewsKit SwiftPM 颜色类型边界修复

✅ PTWhatsNewsViewController 改用公开的 lightened(amount:) 颜色 API，移除对内部 HSL 类型的跨 target 访问。
✅ 保留原有按钮高亮颜色行为，不扩大 HSL 的访问级别。
⬜ 仍需在真实宿主的 SwiftPM Debug/Release 和真机环境完成最终回归。

5.65.2 SwiftPM 独立 Target 修复

✅ Banner 不再依赖 CocoaPods 聚合模块提供的 UIStackView 扩展，直接使用 UIKit 清理排列子视图。
✅ WhatsNewsKit 和 Vision 在 SwiftPM 编译路径显式导入已有 ptools target。
✅ Vision 的随机边框颜色改用 UIColor.randomColor 公开 API。
⬜ 仍需在真实宿主的 SwiftPM Debug/Release 和真机环境完成最终回归。

5.65.1 PTCollectionView 骨架显示修复

✅ 骨架显示期间暂时隐藏底层真实 Cell，保留骨架原有绘制对比度，隐藏后恢复原有内容和透明度。
✅ shimmer-avatar 的圆形占位按最小边长绘制，避免在矩形 Item 中显示为椭圆。
⬜ 仍需在真实宿主和不同屏幕尺寸上验证视觉密度、复杂业务 cell 复用和长时间滚动表现。

5.65.0 PTCollectionView 骨架加载统一治理

✅ 骨架作为独立覆盖层接入，不写入 Diffable snapshot，不触发业务 Cell、数据源和分页回调。
✅ Skeleton、empty、loading、content 统一通过 MainActor 状态仲裁，避免异步完成回调覆盖较新的 UI 状态。
✅ 支持七类布局、分区/头尾描述、内容模板、RTL、安全尺寸裁剪、窗口填充和布局失效。
✅ 支持延迟显示、最短可见时间、取消、Reduce Motion、离屏暂停和重新进入窗口恢复。
✅ 补充 Demo、诊断快照、现有测试目标覆盖、使用指南和发布元数据。
⬜ 仍需在真实宿主和不同屏幕尺寸上验证视觉密度、复杂业务 cell 复用和长时间滚动表现。

5.64.10 TextFieldEffects 激活状态回调

✅ 在 TextFieldEffects 基类新增 activityChangeHandler 和只读 isActive，九种继承样式统一复用同一套状态判断。
✅ 激活状态覆盖获得焦点、失去焦点、用户编辑、程序化 text 和 attributedText 赋值；同一状态不会重复回调。
✅ 回调使用 @MainActor @Sendable，不改变既有动画、占位符和公开初始化方式。
⬜ 仍需在真实宿主中验证键盘联动、Cell 复用、Dynamic Type 和外部控制器的视觉回归。

5.64.9 Input 占位符与边框颜色解耦

✅ 修复 YoshikoTextField 激活态占位符错误读取 activeBorderColor 的问题，边框颜色只负责边框绘制。
✅ 新增可选 activePlaceholderColor、activePlaceholderFont 和 activePlaceholderAtt；未配置时沿用共享占位符配置，旧调用方式保持兼容。
✅ 悬浮占位符按实际字体/富文本高度动态计算边框和输入区域，避免激活后文字被裁剪。
✅ 审计 Input 相关样式，其他输入框未发现相同的 activeBorderColor 复用；保留 IsaoTextField 的兼容回退行为。
⬜ 仍需在真实宿主中验证 Interface Builder、Dynamic Type、富文本占位符和不同主题下的视觉效果。

5.64.8 默认 Core 移除隐式 NFC 依赖

✅ 默认 PToolsDevice / PooTools/Device 不再导入或链接 CoreNFC，避免未使用 NFC 的宿主触发 App Review 的 NFC 能力询问。
✅ PooTools/NFCKit 保留为显式可选入口并单独声明 CoreNFC；PTDeviceCapability.nfc 公共枚举保持兼容。
✅ 补齐 NFC opt-in、Info.plist、entitlement 和 App Review Notes 说明。
⬜ 真实宿主需重新安装 5.64.8 后检查最终 App 二进制链接和审核元数据；未使用 NFC 的宿主仍需移除自身工程里的 NFC 配置。

5.64.6 Input TextFieldEffects 与图片清晰度统一升级

✅ 为九种 TextFieldEffects 样式和 PTHoshiTextField 接入共享外观、占位符渲染、间距、leading 和编辑区域配置，保留旧属性与拼写兼容入口。
✅ 修复绘制初始化、布局重复执行、程序化文本、编辑状态和富文本占位符清理问题；不再依赖重复 NotificationCenter 观察者或直接调用 layoutSubviews()。
✅ 补齐 Input 的 SwiftPM/CocoaPods 直接依赖，增加统一 Input 示例、富文本/清空/间距/RTL/Dynamic Type/焦点状态演示和三语指南。
✅ 统一本地、数据、远程、PhotoKit 和视频图片加载的点数/像素/屏幕 scale 处理；保留 placeholder、取消、generation、GIF、视频和 iCloud 行为。
✅ 统一 UIImageView、UIButton、PhotoPicker 和视频封面缓存的目标尺寸与缓存键，增加图片清晰度 Demo、指南和 5.64.6 版本记录。
⬜ 真机、PhotoKit iCloud、GIF/视频和业务宿主的视觉回归仍需外部环境验证。

5.64.5 SwiftPM 全仓跨 target 兼容性闭环

✅ 动态生成 179 个 target、155 个 product、1229 个 Swift 源文件归属和无环依赖图。
✅ 补齐独立 target 对 ptools、PToolsCore、PToolsSymbols 和相关 Feature 模块的直接依赖与 import；Banner 轻量路径改用 UIKit 原生子视图移除。
✅ 新增符号声明/引用、条件编译和资源归属审计，所有当前高置信度跨 target finding 已关闭或进入真实宿主构建确认。
✅ 新增 SwiftPM consumer fixture 矩阵和 Debug/Release 宿主构建脚本；not_run 不计为通过，未配置 iOS consumer host 时会明确报告阻断。
⬜ 仍需在宿主 Xcode consumer 中逐个完成 155 个 product 的隔离 Debug/Release 编译；当前工作区完整 Example 构建与外部 Pods 构建证据单独记录。

5.64.4 Target 依赖边界修复

✅ 调试诊断文件显式声明 UIKit，避免独立 Target 编译时缺少 UIKit 类型。
✅ Input、Stepper、Router、SocketKit、Share、DEBUG 和权限入口不再依赖 CocoaPods 聚合模块的传递可见性。
✅ CocoaPods 与 SwiftPM 的 SocketKit、Share 依赖图保持一致，继续兼容 iOS 17+ / Swift 6+。

5.64.1 PTRichText 图片附件基线偏移

✅ PTTextAttribute.image、remoteImage 和 URL 图片入口支持可选 baselineOffset，旧调用保持兼容。
✅ PTRichTextImageConfiguration 与 PTRichText.image(source:) 支持动态图片来源的基线偏移配置。
✅ 占位附件、Foundation/UIKit 富文本桥接和异步图片替换保持同一基线偏移，不重复叠加。
✅ 增加 UIKit 富文本和远程/动态图片基线偏移回归覆盖。
⬜ 仍需在真实宿主中验证不同字体、Dynamic Type、RTL、图片尺寸和 TextKit 渲染视觉效果。

5.64.0 PTCustomerAlertController iOS 26 胶囊操作升级

✅ 新增统一的 1、2、3+ 按钮胶囊布局，长文案、多行标题和多按钮滚动使用同一套测量入口。
✅ 新增主操作索引、取消/主操作视觉排序、Dynamic Type、Reduce Transparency 和无障碍状态适配。
✅ iOS 26 原生 Glass 仅在非原生玻璃外层按需启用；iOS 17+ 和辅助功能场景保留稳定回退。
✅ 保留旧公开初始化器、颜色、字体、操作样式、回调索引和 UIAlertController+PTEX 兼容入口。
✅ 新增 Alert Capsule Lab、使用指南和布局测量回归覆盖。
⬜ 仍需在 iOS 17～27 模拟器、iPhone Duo 和真实宿主中完成视觉、键盘和 VoiceOver 回归。

5.63.6 PTNavBar 伪导航栏尺寸与布局统一

✅ PTNavBar 伪导航栏的外层和按钮容器改为使用宿主 View 的实际高度，不再固定压缩到全局 kNavBarHeight。
✅ 系统导航栏和 PTNavBar 统一使用导航按钮尺寸快照；按钮重新挂载前读取 bounds，避免被 UIStackView 改写后再计算错误尺寸。
✅ 自定义按钮使用确定性的 UIStackView .fill 布局，保留调用方设置的宽高、点击事件和现有公开入口。
✅ 增加伪导航栏宿主高度及左右按钮 bounds 回归覆盖。
⬜ 仍需真实 iPhone Duo、iOS 17～27 模拟器和宿主项目完成视觉回归。

5.63.5 TabBar 选中背景样式覆盖

✅ 保留 tabSelectedMetail 旧开关和默认继承行为，不改变既有项目的材质/玻璃效果。
✅ 新增 tabSelectedMetailStyle，支持 .classic 普通纯色、.material 材质和 .glass 玻璃效果。
✅ 全局 PTAppBaseConfig、PTTabBarLayoutAppearance 和单个 TabBar 外观快照共用同一配置路径。
✅ .classic 只关闭选中背景的视觉效果，不改变选中背景颜色、尺寸 Insets、动画和点击逻辑。
✅ 增加单元回归覆盖并完成 Swift 语法、Package manifest 和格式检查。
⬜ 仍需真实 iPhone Duo、iOS 17～27 模拟器和宿主项目完成视觉回归。

5.63.4 图片加载占位图一致性

✅ UIView.pt_loadCoreImage 在每次新请求开始时立即显示 emptyImage 或默认占位图。
✅ 保留旧内容清理、请求取消、generation 校验和最终结果回调行为。
⬜ 真机/宿主项目仍需验证自定义占位图、GIF、视频首帧和 PhotoKit iCloud 资源的视觉表现。

✅ 新增基于当前 Scene/View bounds、四边 safe area、verticalBarEdge 和 reserved regions 的值类型布局上下文与纯函数解算器。
✅ 新增 per-controller policy、MainActor coordinator、系统 Bar bridge、自定义 rail 宿主、overflow 适配器和 DEBUG 几何 overlay。
✅ 默认 automatic 在 iOS 27.1+ 垂直 Bar 能力可用时由 UIKit 统一拥有系统导航与 Tab 几何；iOS 17～27.0 和 unspecified edge 保持原有横向自定义路径。
✅ 保留 PTBaseViewController、PTBaseNavControl、PTBaseTabBarViewController、configure(items:)、ptCustomBar.setup、Badge/Lottie/Center/Mini 和 Insets 兼容行为。
✅ Example 增加 iPhone Duo Adaptive Bars 入口和 12 项场景；新增纯几何回归测试与 Duo 专项静态门禁。
⬜ 外屏/内屏/折叠/分屏/硬件触控和真实视觉截图仍需官方 Duo Simulator、Device Hub 或实体设备验收；当前不以普通 iPhone 模拟器替代。

5.62.8 UIButton 渐变多态支持

✅ backgroundGradient 根据运行时类型识别 UIButton，使用 backing background 绘制渐变，避免覆盖标题和图片。
✅ 保持普通 UIView 的 CAGradientLayer 路径，以及 UILabel / UIImageView 的现有内容保护行为。
✅ 增加通过 UIView 引用调用 UIButton 渐变的回归测试；保留现有 API 和调用方式。
✅ 新增 UIButton.backgroundGradient(..., for:) 状态入口，支持不同状态独立生成背景，并在 bounds / trait 变化后刷新。
✅ 保留已有 UIButton.Configuration 更新回调，状态渐变可应用到配置型按钮。
⬜ 真机视觉回归、复杂按钮配置与宿主项目组合仍待集成方验证。

✅ 为任意 UIControl 增加原生 UIMenu、动态菜单和 Selection Menu 入口，统一由 selectedID 驱动选中态。
✅ UIButton / PTBaseButton 复用 UIKit 原生 menu 与 showsMenuAsPrimaryAction，不重复实现系统菜单行为。
✅ PTActionLayoutButton、Inspector 选择控件和 Example Demo 接入统一菜单能力，并保留长按与主点击触发语义。
✅ 增加三语使用指南、选择菜单回归测试和 iOS 17+ / Swift 6 构建验证；版本事实保持 5.62.4，不创建新 tag。

5.62.2 TabBar Item Content Insets 实际尺寸修复

✅ PTTabBarLayoutEngine.contentSize 统一解析基础尺寸、正负 Insets、非有限值和最大扩展倍率。
✅ PTTabBarItemView 移除初始化阶段固定 content.view 尺寸，改为直接约束真实媒体/自定义内容 View；标题仍独立布局。
✅ PTTabBarView 的 Badge 定位和 Mini 模式复用 resolvedContentSize，恢复布局重新应用同一尺寸。
✅ 保持 per-item override、Appearance snapshot、.zero 默认行为和 tabItemContentOffset 兼容语义。
✅ Demo Catalog 增加 Legacy、Selection、正/负 Content、Vertical、Horizontal、Offset、Combined、Per-item、Badge、Mini、Lottie 十二种场景，并显示实际尺寸。
✅ 补充 5.62.2 迁移文档、Layout Engine / Item View 回归测试和中英文西班牙文说明。
⬜ 完整 Xcode Simulator Debug / Release、真机视觉、iPad、多窗口、Dynamic Type、VoiceOver 和自定义 Content 宿主回归仍待环境/集成方验证；未完成前不创建正式 tag。

5.62.5 PTCollectionView Diffable Content Refresh 二次修复

✅ 用 PTCollectionUpdateCoordinator 串行执行更新操作，取消 busy → return 丢更新路径，并在执行时读取最新 Snapshot。
✅ 新增内容刷新与布局失效 API，保留原有 showCollectionDetail、reloadSections、reloadRows 和 PTSection/PTRows 兼容入口。
✅ 新增 PTCollectionModelStore、稳定身份类型、Debug 更新诊断和 identity churn 提示，Cell、Supplementary、Layout 和查询入口优先读取最新模型。
✅ 增加 PTCollectionCellContext、Cell Provider / Configure 分离、可见 Cell 快速重配置、结构/内容/布局动画策略和显式 Cell 替换入口。
✅ 增加 Ref、Value、External、Store 四种 Refresh Lab 数据源、Replace Cell、YD Sequence、Stress 和实时 Provider/Configure/Apply/Pending/Latency 诊断。
✅ 增加内容合并屏障、ModelStore 身份顺序和旧快照参数适配回归测试；完整 Xcode Debug/Release 已验证。
⬜ YDSearchSideController 真正宿主迁移、真机/滚动/拖放/骨架/预取视觉回归仍需外部环境验证；当前 Harbeth Metal Toolchain 相关视觉验证未完成，未创建版本 tag。

5.62.1 TabBar Insets 解耦 / 内容型渐变修复

✅ 新增 tabItemContentInsets、tabItemContentOffset 和 tabSelectedMetailInsets，分别表达内容边界、内容平移和选中背景边界。
✅ PTTabBarLayoutAppearance、PTTabBarLayoutEngine、PTTabBarItemView 和 PTTabBarSelectionCoordinator 使用同一份外观快照与几何计算。
✅ 选中背景支持四边安全 Clamp，且不会改变 Icon、Title、Badge、UIImage、Lottie 或 Custom Content 的尺寸计算。
✅ 保留并弃用 tabSelectedMetailLRSpacing；旧的 tabTopSpacing、tabBottomSpacing 和 tab26BottomSpacing 继续保持兼容语义。
✅ 增加 Legacy、Selection-only、Content Insets、Content Offset、Combined 五组 TabBar Demo，以及 Label / ImageView 渐变 Demo。
✅ UILabel / UIImageView 的背景渐变改为按当前 Bounds 栅格化到 UIColor(patternImage:)，保留普通 UIView / UIButton 的 CAGradientLayer 路径和渐变边框。
✅ 增加圆角、动态颜色、Bounds 更新、旧背景 Layer 清理和核心布局回归测试。
⬜ 完整 Xcode Simulator Debug / Release 验证仍受外部 Harbeth 缺失 Metal Toolchain 阻断；待工具链可用后补齐 iOS 17～27、iPad Split View / Stage Manager、真机视觉回归，再创建正式 tag。

5.62.0 Application Infrastructure / P0-P1

✅ P0 Database：新增 Foundation-only SQLite Core 与 actor 实现，覆盖参数绑定、事务、迁移、观察、备份/恢复和 Codable 映射。
✅ P0 Auth / Sync / Transfer：新增认证 provider 契约、Keychain 复用、单飞刷新、离线 mutation queue、幂等重试、冲突接口和后台传输能力。
✅ P0 StoreKit / Observability：新增 StoreKit 2 类型化 facade、旧 IAP 兼容层、事件/Trace/Span/Metric/Breadcrumb、脱敏、采样和离线缓冲。
✅ P1 Web / Map / Integrity：新增 WKWebView reply bridge、内容世界与安全策略、MapKit geocode/search/route/snapshot、App Attest/DeviceCheck 能力边界。
✅ P1 Remote Configuration：新增 ETag/TTL/cache/signed/LKG/composite/stable rollout/kill-switch provider 组合能力。
✅ P1 Realtime：新增 SSE 解析、重连、Last-Event-ID、心跳和订阅契约，复用现有 PooToolsSocketKit 适配器。
✅ Package / Demo / Docs：新增可选 SwiftPM products、CocoaPods subspec、Demo Catalog、三语模块索引、应用基础设施指南和验证脚本入口。
✅ Xcode / CocoaPods / Simulator：PooTools-Example 已完成 Debug 与 arm64 Simulator Release 构建，pod install --no-repo-update 已解析 5.62.0。
⬜ 真机 / 宿主 / 外部服务：仍需完成 Device、StoreKit、App Attest、后台传输、Web、Map、SSE 和长会话证据；未完成前不创建正式 5.62.0 tag。

5.61.0 Final Runtime Safety / Scene / Concurrency Closure

✅ P0 依赖收口：移除 Kakapos 的 SwiftPM/CocoaPods/锁文件/生产源码归属，C7 视频导出改用原生 AVFoundation/PTools 服务。
✅ P0 HeartRate：相机、输入输出、像素转换、滤镜、权限和 Lottie 资源失败均改为可恢复错误或安全回退。
✅ P0 NetworkSpeedTest：显式 endpoint、actor 状态、类型化 phase/snapshot、重复启动隔离和取消完成。
✅ P0 Ping：补齐 resolving/ready/sending/waiting/success/failed/stopped 状态，增加 PTPingSession，移除公共错误路径崩溃。
✅ P0 Scene：生产源码中的 AppWindows! 清零，媒体、签名、眼睛追踪和 Inspector 使用 PTSceneContext。
✅ P1 Location / Storage：定位使用 PTLocationSnapshot 和迁移兼容键；PTFileStorage 文件 I/O 移至 utility 队列并保留 atomic write。
✅ P1 并发边界：更新 @unchecked Sendable allowlist/registry，系统对象包装器注明不变量；不新增业务级 nonisolated(unsafe)。
✅ P1 UIKit：用户可触发的泛型出列、文档选择器和 iOS 18 zoom 回调移除直接 fatal 崩溃；init(coder:) 保留项按 programmatic-only/abstract contract 分类。
✅ P1 Adaptive Navigation：新增 PTSplitViewController，支持 double/triple column、compact column/push、regular secondary、Inspector、状态恢复和 Router 桥接；.automatic/.navigationPush 使用真实可见导航栈，不按设备类型分支。
✅ P2 Demo / 文档：Example 的 SplitView 入口改为 root-container，全量覆盖 iPhone compact、iPad regular、Router、状态保存/恢复和 Inspector 运行态；补齐 5.61.0 架构、迁移和模块指南。
✅ Quality：新增语义能力归属 manifest、工作树 runtime safety report、fatalError allowlist 和 validate_5_61_release.sh。
⬜ 宿主/真机/Instruments：HeartRate、真实测速服务、Ping、iPad Stage Manager、Storage、SplitView resize 和长会话证据需由集成方补充；未完成前不创建正式 5.61.0 tag。

5.60.0 Unified Architecture / PTModel / Network Usability

✅ 保持 PTModel 递归解码核心不变，补充普通 Nested Object、嵌套数组、可选值、字典和 Stringified JSON 回归。
✅ 新增 Network 显式 modelPath：根模型、$.data、深层路径和数组路径统一由 PTJSONPath 选择。
✅ 新增路径缺失与路径类型不匹配的类型化错误；默认 root 行为保持兼容，不自动猜测响应包裹字段。
✅ 增加 network.ptmodel-lab 确定性 Demo、5.60.0 Quick Start 和 Nested JSON 语义文档。
✅ P0/P1：Nested Model、Network decode error、真实 Model/Network tests Gate、Learning Lab、Quick Start、CocoaPods/Legacy migration 文档已完成。
✅ P2/P3：parity 分类、27 个 UI/Scene singleton ownership、deprecated freeze、PTPaging/PTRichText/PTCustomerAlert/PTTabBar/PTCollection 拆分、Font Catalog/Runtime、Network/Router 分层和并发例外登记已完成。
P4：Release、SwiftPM 外部 Kakapos 解析阻断、CocoaPods lint、真实宿主/真机、长会话和 Instruments 证据仍待环境完成；未完成前不创建正式 5.60.0 tag。

5.59.0 5.x Finalization Governance 2.0 / DebugNetwork 2.0

✅ DebugNetwork 改为 observer-only：不参与业务 cache、retry、auth、dedup、decoder 或响应决策。
✅ 新增不可变 PTNetworkCaptureRecord、typed request/response/body snapshot、actor Store、预算淘汰和 exactly-once finalize。
✅ 接入 URLSessionTaskMetrics、redirect chain、Timeline、advanced filter、AsyncStream 批量 UI、Scene presentation session 和 hook registry。
✅ 新增默认脱敏、cURL/HAR/Text 导出、能力矩阵、迁移文档、Debug contract tests 和 DebugNetwork 质量门禁。
✅ 增加 current report freshness、Concurrency Exceptions v2、module/API/dependency freeze manifest；5.x 兼容入口继续保留。
仍需真实宿主/真机完成后台 URLSession、WKWebView、WebSocket、SSE、Network.framework、多 Scene 和 ON/OFF 业务一致性回归后再创建正式 5.59.0 tag。

5.58.0 PTModel 基础融合入口

✅ 新增不依赖 SmartCodable、KakaJSON、UIKit 和运行时反射的 PToolsModelCore，并由 PToolsModel 提供高级产品入口。
✅ 新增 PTJSONValue / PTJSONNumber、有界 JSON Reader/Writer、顶层 JSON fragment、重复键策略和 Foundation/Objective-C 输入桥接。
✅ 新增 PTModelSource、PTModelDecoder、PTModelEncoder、PTPresence、PTModelContext 和 Codable 互操作策略契约。
✅ 保留 KakaJSON 一行式转换体验：Model.pt.model、Model.pt.models、model.pt.jsonData/jsonString/dictionary/jsonArray。
✅ SmartCodable/KakaJSON 旧 Core 路径保持不变；本版本不删除第三方依赖，不迁移 PTBaseModel，避免破坏现有业务。
✅ 增加模型能力矩阵、Codable 互操作约定、迁移文档、模型测试和基准 manifest。
后续 5.58.x 继续按计划实现宏继承、完整容错/策略矩阵、Network decoder bridge、streaming 和性能门禁；未完成项不得标记为 6.0 parity。

5.57.4 PTSegmentedView Item Separator 配置

✅ 在 PTSegmentStyle 增加 .none、.line、颜色、线宽、上下内边距、leading/trailing 和可见性配置。
✅ 通过内部布局上下文处理首项、末项、单项、Diffable 重排和 Cell reuse，不把布局位置写入业务 Item。
✅ 使用一套可复用约束，清洗非法尺寸，适配 RTL、动态颜色、无障碍和超大内边距，不影响测量、间距、Indicator 或选择动画。
✅ 增加 PTSegmentedPagingTests 回归、Demo Catalog 示例、Paging 指南和 JX 迁移说明。
完成真实宿主在 RTL、动态颜色、快速重排和不同 Cell 高度下的真机视觉回归后，再创建正式 5.57.4 tag。

5.57.3 PTSegmentedView / PTPagingView 运行时稳定性

✅ 统一 Segment 宽度测量，Badge、选中字体、selectedScale、图片渲染尺寸和 adaptive 阈值使用同一实现。
✅ 修复 Badge Label 内边距与 Dot 约束复用，并补充动态角标和 Badge 无障碍值。
✅ 将 Indicator 的 Item/Content frame 统一投影到 viewport 坐标，横向滚动和离屏选中项均可正确更新。
✅ 修复内置 Indicator 的 widthPolicy / placement 配置被默认上下文覆盖的问题，保留旧 Context 初始化调用兼容。
✅ Segment 标题条滚动只负责浏览，不再修改业务选择或伪造页面 transition；Reduce Motion 下取消程序化滚动动画。
✅ 增加现有 UIFoundation 测试 Target 的测量、Indicator、手动滚动回归测试，补齐 Paging、JX 迁移、YD 订单和 Demo Catalog 文档。
完成 YD 订单真实宿主在 100 项、动态角标、三语、RTL、Dynamic Type、Reduce Motion、快速点击和快速滑页下的真机回归后，再创建正式 5.57.3 tag。

5.57.2 PTPageContainer 已加载页面查询 API

✅ 增加 loadedPageIDs、isPageLoaded(id:)、loadedPage(for:) 和类型化页面查询。
✅ 增加 loadedViewController(for:)、批量控制器查询和 currentViewController 类型化入口。
✅ 查询保持无副作用：不创建未加载页面、不改变选择、不改变缓存策略、不触发生命周期。
✅ 保持私有缓存封装，按 descriptor 顺序返回结果，并覆盖 keepAllLoaded、adjacent、limit 和 discardOffscreen。
✅ 补充 JX 迁移、分页指南、生命周期和架构文档，以及现有 UI 测试目标中的分页回归测试。
完成宿主项目对已加载页面批量刷新和各缓存策略的真机回归后，再创建正式 5.57.2 tag。

5.57.1 ImageEditor 独立使用修复

✅ 修复编辑图片首帧未居中的问题：容器使用稳定内容原点，并依据滚动视图可视区域动态计算居中 inset。
✅ 统一缩放和首次布局的居中逻辑，避免缩放回调与初始化布局维护两套定位算法。
✅ 新增普通/选中工具图标配置，默认图标使用白色 alwaysOriginal 渲染。
完成集成方在不同导航栏、工具栏显示状态和真机方向下的视觉回归后，再创建正式 5.57.1 tag。

5.57.0 Form 2.0

✅ 完成 Form-level、Section-level、Field-level Sendable 配置和 PTFormSnapshot 快照边界。
✅ PTFormSection 真实映射到多个 PTSection，移除控制器的单一 "form" flatten 路径。
✅ 接入 Section header/footer registry、section appearance、spacing/insets、自动高度和稳定字段 ID。
✅ 补齐字段 Renderer context、custom renderer、Picker option model、输入配置和 focus capability。
✅ 补齐跨字段校验、校验策略、取消/stale-result 防护、runtime mutation、reset、dirty 和 revision。
✅ 键盘导航改用字段位置快照，支持跨 Section 并跳过隐藏、禁用、只读和不可聚焦字段。
✅ 增加 Dynamic Type、Dark Mode、High Contrast、RTL、Reduce Motion、VoiceOver 和错误反馈适配。
✅ 增加 Form 2.0 指南、迁移说明、稳定 ID/多 Section/可见性/大表单测试和静态质量门禁。
外部 SmartCodable Simulator 宏产物恢复后，重新完成 PooTools-Example Debug/Release Xcode 全量回归，再创建正式 5.57.0 tag。

5.56.2 Form / Documents / Feedback / Button Loading 闭环

✅ Form renderer 按字段语义拆分，复用现有 PTools 输入、Picker、Switch、CheckBox、Slider 和 ActionLayoutButton。
✅ 补齐 Form 键盘 Previous/Next/Done、屏幕外聚焦滚动、主题 token、动态主题刷新、校验无障碍和语义反馈。
✅ 从 PTBaseButton 抽取 PTControlLoadingCoordinator，由 PTBaseButton 和 PTActionLayoutButton 组合复用，保留两者原有继承关系和展示方式。
✅ Documents 增加 PooToolsPDF adapter、PDFKit fallback、单/多文档分享、Scene-aware iPad popover 和 security-scoped 生命周期。
✅ Alert、ActionSheet、Banner、Popover、TabBar、Picker、Form 和 Navigation 接入 PTFeedbackCenter，避免重复本地反馈生成器。
✅ 修复 SwiftPM iOS 17 / Swift 6 下 ContentState 宿主与关联值状态判断，完成 5.56.2 文档、Pod 锁文件和治理门禁同步。
完成真实宿主、真机、扩展 target 和远程 CI 的最终回归后，再创建正式 5.56.2 tag。

5.56.1 文档、脚本、数据资产与测试治理

✅ 以 Scripts/Docs/audit_docs.py 建立文档、模块、脚本、JSON/YAML 数据资产和测试 target 的统一盘点入口。
✅ 建立 docs/_meta canonical registry、三语文档索引、正式模块三语使用指南和 report/* 生成清单。
✅ 建立 ACTIVE / ARCHIVED / GENERATED / DELETED 生命周期、术语表、provenance、测试执行 lane 和 GitHub Governance workflow。
✅ 保留历史计划的 Git 追溯能力，不机械复制或删除；版本推进到 5.56.1。
完成真实宿主、扩展 target、真机和远程 CI 的最终验收后，再创建 5.56.1 正式 tag。

5.36.1 P0/P1/P2 收口

✅ P0：补齐 IPv4/IPv6 连通性快照、单一 Keychain 适配、类型化位置通知、统一权限、Scene-aware 路由和后台任务宿主配置。
✅ P1：补齐 ContentState 网络适配、PTBaseViewController 可选状态宿主、PTCollectionView 表单、字段 Renderer、无障碍/键盘边界、PDF 桥接和生产/模拟 Provider 合同。
✅ P2：补齐 Core 语义反馈钩子、AppIntent/Widget/Live Activity 扩展示例、App Group/隐私/真机验收文档和统一质量门禁。
真实设备和宿主验收：BLE 扫描/连接/通知/恢复、通知与后台生命周期、音频/触觉、Widget/Live Activity、锁屏隐私、扩展 target 构建和多 Scene 回归完成后，再创建不带 v 的 5.36.1 tag。

5.36.0 P2 现代系统扩展与增强能力

✅ 新增 PToolsConfiguration：环境、typed config key、provider precedence、feature flag、snapshot、Storage cache 和 Debug override。
✅ 新增 PToolsFeedback：语义触觉事件、UIKit generator、CoreHaptics、硬件能力查询、policy 和 engine reset。
✅ 新增 PToolsAudio：AVAudioSession coordinator、interruption/route/reset stream、录音、简单播放、metering 和 waveform。
✅ 新增 PToolsAppIntents：原生 AppIntent/AppShortcut 声明、headless/route-to-app/hybrid 模式和 RouteCore bridge。
✅ 新增 Foundation-first PToolsWidgetCore：App Group typed store、timeline payload、reload coalescing 和 deep-link bridge。
✅ 新增 PToolsActivities：ActivityKit lifecycle、dedupe/throttle、stale/relevance、push token 和 diagnostics。
✅ SwiftPM products、CocoaPods subspec、InputAll 普通 App 模块、module parity、P2 extension-safe 门禁、测试、示例和文档同步完成。
完成 AppIntent/Widget/Live Activity 独立 Extension Target、App Group entitlement、真机音频/触觉、锁屏隐私和宿主业务回归后，再创建正式 5.36.0 tag。

5.35.0 P1 高阶能力与系统整合

✅ 新增 PToolsTheme：语义颜色、字体、间距、圆角、层级、材质、动效、玻璃降级，以及 App/Scene/Controller/组件作用域。
✅ 新增 PToolsAccessibility：VoiceOver、Dynamic Type、Reduce Motion/Transparency、RTL、焦点恢复、公告和启发式审计。
✅ 新增 PToolsContentState：idle/loading/content/empty/error/offline、旧内容保留、重试和 UIKit 状态容器。
✅ 新增 PToolsForm：稳定字段身份、常用字段类型、条件依赖、同步/异步校验、debounce、取消、generation 和提交状态。
✅ 新增通用 PToolsBluetooth：扫描、过滤、连接状态机、服务/特征发现、GATT 读写/通知、取消、超时、重连和诊断快照。
✅ 新增 PToolsDocuments：UIDocumentPicker、UTType、多选、导入导出、安全作用域、bookmark、QuickLook 和分享桥接。
✅ 新增 PToolsSimulationCore / PToolsSimulation：虚拟时钟、确定性场景回放、Provider 合约、Mock Provider 和显式启用保护。
✅ SwiftPM products、CocoaPods subspec、模块 parity、质量门禁、测试和迁移文档同步完成。
完成宿主 App 的真实 BLE、文档权限、VoiceOver、Dynamic Type、RTL、真机和多 Scene 回归后，再创建正式 5.35.0 tag。

5.34.0 P0 平台基础设施

✅ 新增 PToolsConnectivity，提供 PTConnectivityMonitor、快照、诊断和 AsyncStream 监听。
✅ 新增 PToolsStorageCore / PToolsStorage，统一 typed key、namespace、Memory、UserDefaults、File、Keychain、Composite 后端和迁移上下文。
✅ 新增 PToolsRouteCore / PToolsDeepLink，将 URL Scheme 和 Universal Link 归一化为无 UIKit 路由请求。
✅ 扩展 PooToolsRouter，提供 MainActor、Scene-aware 的 PooToolsRouter 2.0 入口，并保留旧 Router。
✅ 新增 PToolsNotifications，提供类型化通知、分类、附件、前台展示策略和通知路由适配器。
✅ 新增 PToolsBackgroundTasks，提供 BGAppRefresh、BGProcessing、过期取消和后台 URLSession 配置入口。
✅ 增加 SwiftPM/CocoaPods parity、P0 平台模块和平台契约门禁。
完成宿主 App 的通知授权、后台任务标识、Universal Link Associated Domains 和真机生命周期回归后，再创建正式 5.34.0 tag。

5.33.0 DeviceKit 吸收与 PToolsDevice

✅ 从 SwiftPM、CocoaPods、锁文件、生产源码 import 和 runtime 类型中移除 DeviceKit。
✅ 新增无第三方依赖的 PToolsDevice SwiftPM product 与 PooTools/Device subspec。
✅ 使用按平台维护的 JSON catalog 和生成 Swift 索引，支持未知设备安全回退、模拟器、Apple Silicon Mac、visionOS、watchOS、tvOS。
✅ 增加基于系统 API 的动态能力查询、Swift 6 Sendable 值类型和 Core/LocalConsole 兼容迁移。
✅ 增加 catalog 校验、生成物漂移、DeviceKit 引用、依赖方向和模块 parity 门禁，以及迁移、架构、使用和维护文档。
✅ 完成 PooTools-Example iPhone 17 Simulator Debug / Release Xcode 构建；外部 Pods 警告单独记录。
完成宿主 App 真机、各平台能力、未知设备、隐私和视觉回归后，再创建正式 5.33.0 tag。

5.32.0 Instructions 原生吸收

✅ 移除第三方 Instructions 依赖，新增 PooToolsInstructions 与 PooTools/Instructions。
✅ 复用 Overlay 的 Host、Anchor、定位、生命周期和命中测试，不新增第二套 Window 基建。
✅ 提供类型化 Tour/Step、目标等待与滚动揭示、镂空遮罩、默认内容、推进策略、取消和 UserDefaults 进度存储。
✅ 增加使用审计、架构边界、迁移指南和第三方依赖移除门禁。
完成宿主 App 的多 Scene、动态字体、RTL、VoiceOver、真机视觉和业务教程回归后，再创建正式 tag。

5.31.2 Simulator 模块依赖解析修复

✅ 修复 PooTools_Example 与 Pods/PooTools 共用 PooTools Module Identity 的配置错误。
✅ 清理示例 Target 中的 PooToolsSource/** 直接编译成员，库源码只由 CocoaPods/SwiftPM 所属 Target 编译。
✅ 移除固定 SDKROOT = iphoneos、不必要的 Module Verifier 和错误的 Swift Generated Header 配置，不排除 arm64 Simulator。
✅ 为示例直接导入的第三方模块增加显式 CocoaPods 依赖，并将 YCSymbolTracker 降级为可选 Debug 能力。
✅ 增加源码归属审计、模块身份守卫和 CocoaPods Simulator/Device 构建入口。
✅ 完成 CocoaPods workspace 的 Simulator Debug/Release、Generic Device Debug/Release 构建和真实模块解析验证；构建结果记录在 docs/audits/SIMULATOR_BUILD_BASELINE.md。
创建 5.31.2 正式 tag（需显式发布操作）。

5.31.1 JX Paging 能力补齐与迁移稳定性

✅ 对照 YDShipOrderControl.swift 完成分段、分页、懒加载、动态角标、刷新、回顶和手势场景映射。
✅ 修复稳定 ID 更新、反向分页过渡、Indicator 层级、页面生命周期、Header 尺寸和网络图片占位槽位问题。
✅ 增加 PTPagingView 迁移适配入口、内部观察者机制和旧业务完整使用教程。
完成宿主 App 的真机、多 Scene、横竖屏、Dynamic Type、RTL、刷新库、导航返回和视觉回归后，再创建 5.31.1 正式 tag。

5.31.0 Popovers 吸收与 Overlay 2.0

✅ 移除 aheze/Popovers 的直接依赖；PopoverKit 保留为原生 PooTools/Popover 的兼容别名。
✅ 在 OverlayCore 1.0 之上增加 Anchor、Geometry、碰撞修正、箭头、点击外部、排除区域、拖拽、键盘、焦点和无障碍基础契约。
✅ 新增 PTPopover、PTContextMenu、UIView/UIViewController 内容适配、菜单、更新、替换、重定位、分组和多弹层管理。
✅ PTTipsView 增加锚点展示入口；Alert 复用统一 modal 层级，ActionSheet 保留原有语义和公开 API。
✅ 增加 Popovers 使用审计、Overlay 重复实现审计、架构说明、迁移指南、Popover/Tips/ActionSheet 文档与 CI 门禁。
✅ 完成 PooTools-Example Debug 全量 Xcode 构建，源码 warning/error 为零。
完成 Release 全量构建、真机、多 Scene、键盘、安全区、Dynamic Type、RTL、拖拽和视觉回归后，再创建 5.31.0 正式 tag。

5.30.0 JX 分段与分页原生收口

✅ 移除 SwiftPM、CocoaPods、锁文件和交付源码中的 JXSegmentedView / JXPagingView 直接依赖。
✅ 新增 PTSegmentedView、稳定 ID 的 PTSegmentItem、Indicator 引擎、PTPageContainer、PTPagingView 和双向同步 Coordinator。
✅ 增加页面懒加载、生命周期、缓存策略、Header/Pinned Header、基础嵌套滚动、刷新适配和手势方向契约。
✅ 旧 SegmentControl 模型保留为不依赖第三方的弃用兼容适配器，不提供 JX 类型别名。
✅ 增加 Paging 架构、迁移、嵌套滚动、手势、生命周期和使用审计文档，以及交付源码依赖移除门禁。
完成宿主 App 的真机、复杂 Nested Paging、刷新库、多 Scene、Dynamic Type、RTL、性能和视觉回归后，再创建 5.30.0 正式 tag。

5.29.0 NotificationBanner 吸收与原生 PToolsBanner

✅ 新增 PToolsOverlay，统一 Scene 解析、Host、Overlay Window、穿透命中测试、层级、转场和生命周期基础能力。
✅ 新增 PooToolsBanner，提供原生 UIKit Banner、队列、优先级、堆叠、去重、溢出、暂停恢复、原地更新、操作按钮和无障碍适配。
✅ UIViewController.drop 保留为兼容入口；新代码通过 PTBannerCenter 和 showBanner 使用原生 Banner。
✅ 移除交付路径中的 NotificationBannerSwift、MarqueeLabel 依赖；CocoaPods NotificationBanner 保留为 Banner 兼容别名。
✅ 增加 NotificationBanner 使用审计、迁移说明、移除门禁、模块对齐报告和 Banner 队列回归测试。
完成宿主 App 真机、多 Scene、键盘、安全区、动态字体和辅助功能回归后，再创建 5.29.0 正式 tag。

5.28.0 GCDWebServer 移除与原生 HTTP Server

✅ 新增 PToolsHTTPServer SwiftPM product/target 和 PooTools/HTTPServer CocoaPods subspec，底层使用 Network.framework、actor 和严格 Sendable 值类型。
✅ 新增 PToolsHTTPFilePortal / PooTools/HTTPFilePortal，将静态文件、上传、下载、删除、创建目录和重命名与 HTTP 核心解耦。
✅ 完成增量 HTTP/1.1 parser、Content-Length/chunked framing、Keep-Alive、Range、条件缓存、SSE、gzip、TLS、Bonjour 和安全中间件入口。
✅ PooTools/GCDWebServer 保留为无第三方依赖的兼容别名，PooTools/InputAll 迁移到 HTTPFilePortal；交付依赖不再包含 GCDWebServer/WebUploader。
✅ 示例工程本地文件分享入口迁移到 PTHTTPFilePortal，新增审计、迁移、安全、架构和测试文档及质量门禁。
完成 Generic Device、真机局域网权限、TLS 身份、Bonjour、慢客户端背压和多客户端并发回归后，再创建 5.28.0 正式 tag。

范围与约束

PTools 面向 iOS 17+ / Swift 6+。5.x 的主要治理范围是 PooTools.podspec 的 default_subspec = Core 及其直接扩展边界。公开 API、CocoaPods subspec、SwiftPM product 和第三方依赖在没有迁移证据前保持兼容。

长期规则：

当前架构写入 docs/architecture/ARCHITECTURE.md。
Debug 与 PTInstruments 设计写入 docs/architecture/DEBUG_AND_INSTRUMENTS.md。
发布流程写入 docs/maintainers/RELEASE.md。
测试方法和发布门槛写入 docs/maintainers/QUALITY.md。
Swift 6 并发边界、例外和后台工作分类写入 docs/architecture/CONCURRENCY.md。
单次扫描、构建和基准结果写入 report/，不混入长期架构文档。
新版本不再创建 ARCHITECTURE_5_12.md、PERFORMANCE_BASELINE_5_12.md 等版本化长期文档。

5.27.0 SocketRocket 移除与原生 WebSocket 收口

✅ 从 SwiftPM、CocoaPods、Package.resolved、Podfile.lock 和交付源码移除 SocketRocket；历史报告只保留不可修改的演进记录。
✅ 以 URLSessionWebSocketTask 建立 PTWebSocketTransport、原生传输、actor 状态机、代际令牌和终止事件去重。
✅ 增加有界 FIFO 发送缓冲、拒绝/丢弃策略、指数退避抖动、稳定连接后重置、原生 ping/pong 超时和连接指标。
✅ 增加系统信任、证书 pinning、公钥 pinning 和备份 pin 支持；不提供 trust-all 生产入口。
✅ PTSocketManager 保留旧公开入口，单例、通知、delegate、连接配置和消息类型转换均代理到原生客户端。
✅ 增加 SocketRocket 审计、迁移、架构、测试矩阵和移除门禁；完成 Xcode Debug/Release 后再决定是否创建正式 tag。

5.26.0 SwiftDate 吸收与日期层收口

✅ 完成 SwiftDate 使用审计，区分生产调用、兼容入口、测试与历史 API 基线。
✅ 新增 Foundation-only 的 PToolsDate SwiftPM product/target 与 CocoaPods Date subspec，Core 统一依赖日期层。
✅ 以 PTDateContext、PTZonedDate、PTDateParser 和显式 PTTimestampUnit 替换 SwiftDate 的区域、格式化、解析和日历运算入口。
✅ 迁移 Calendar、Date Category、String、TimeInterval、HTTP 日期头、HealthKit、MessageKit 和 NetworkSpeedTest 的生产路径。
✅ 移除全局可变 jx_formatter，修复 Unix timestamp 重复时区偏移，并为 DST、locale、calendar、parsing、relative 和 boundary 增加回归矩阵。
✅ 增加 SwiftDate 移除门禁和 5.26.0 迁移文档；保留历史 API 报告作为不可修改的演进记录。
完成真实宿主、真机、多语言、设备时区切换和跨 DST 日期场景回归后，再决定是否创建 5.26.0 正式 tag。

5.23.0 SwifterSwift 一次性移除与 Category 收口

✅ 从 PooToolsSource、Example、Tests 和所有 SwiftPM/CocoaPods 活动清单移除 SwifterSwift 直接导入与依赖声明；历史审计和许可证说明保留在文档中。
✅ 以 Foundation/UIKit 原生实现替换实际使用的序列、数组、字典、Optional、URL、范围集合和 UIView 辅助能力，旧 PTools 入口保持兼容。
✅ 统一安全下标、JSON 序列化、URL 查询参数、视图层级查找、子视图批量操作和圆角辅助逻辑，避免强制转换、强制解包和不稳定的字典随机顺序。
✅ 新增 SWIFTERSWIFT_USAGE_AUDIT.md、SWIFTERSWIFT_TO_PTOOLS.md、PTOOLS_CATEGORY_GUIDELINES.md 与一次性移除门禁。
✅ CocoaPods lockfile、Debug/Release Xcode workspace、SwiftPM、质量与发布门禁均已通过；未创建 5.23.0 tag，等待显式发布操作。

5.24.0 SafeSFSymbols 移除与 PToolsSymbols 收口

✅ 从 SwiftPM、CocoaPods、锁文件和生产源码移除 SafeSFSymbols 直接依赖；历史审计和迁移说明保留在文档中。
✅ 新增 PToolsSymbols，提供 PTSymbol、类型化生成目录、动态 raw value 逃生口、别名、回退、变量值归一化和无崩溃诊断。
✅ 将静态 SF Symbol 使用迁移到 UIImage(ptSymbol:) / UIImage.pt_symbol；动态系统名称只保留在运行时解析白名单。
✅ 新增标准化 SFSymbolCatalog.json、PTSymbolGen、生成校验、差异报告和 5.24.0 符号门禁。
✅ 增加 SwiftPM PToolsSymbols product/target、CocoaPods Symbols subspec、Core 依赖和符号测试入口。
✅ 增加 SafeSFSymbols 使用审计、迁移指南、符号设计规范、依赖声明和第三方通知。
完成当前工作区对应的 Xcode Debug/Release、CocoaPods lint 和真实宿主 SF Symbols 视觉回归后，再决定是否创建 5.24.0 正式 tag。

5.12.0 Core / Foundation 收口

✅ 增加 Foundation-only 的 PToolsCore 并发、生命周期、缓存、日志和错误契约。
✅ CocoaPods Core 依赖并复用 PToolsCore，旧 Core 源码通过兼容别名保留公开入口。
✅ Core 的 URL 解析、关联对象和模型值类型不再在拆分构建中重复实现。
✅ 增加 Core 边界静态门禁，明确第三方适配器不得进入 PToolsCore。
UIKit、媒体和历史第三方兼容实现继续在后续 5.13–5.15 迁移，不在 5.12.0 直接删除公开入口。

✅ UIFoundation 增加安全区、Scene、动态颜色和减弱动态效果的统一上下文辅助能力。
✅ Navigation 按具体导航控制器应用导航栏项目，交互式 push/pop 不再依赖跨栈全局控制器状态。
✅ Tabbar 增加安全区、旋转、分屏和台前调度后的布局恢复，并过滤过期转场回调。
✅ Tabbar 补齐 reloadData()、reloadItem(at:)、invalidateLayout()、refreshLocalization() 入口。
✅ Lottie 图标增加取消和 generation 校验，避免快速切换后旧动画回写当前 Tab。
✅ CollectionView 增加 Diffable 快照串行保护、空 Row 身份校验和 rowCount 安全归一化。
✅ 基础 Cell 增加 PTReusableTaskBag、cancelAsyncWork() 和 resetContent() 复用契约。
✅ 列表高频 UI 文件继续通过 PTSceneContext 解析窗口，兼容多 Scene、分屏和外接显示器。
✅ 保持 iOS 17+、Swift 6+ 和现有公开 API 兼容；旧入口继续作为适配层保留。

5.14.0 Network / Socket / Security

✅ 建立 PTNetworkRequest、PTNetworkResponse 和 PTNetworkExecutor 类型化请求契约，旧动态入口继续停留在兼容层。
✅ 统一普通请求、Body、上传/下载生命周期的取消、错误快照、日志脱敏和执行边界。
✅ 增加指数退避、抖动、Retry-After、幂等键保护和可重试状态/网络错误策略。
✅ 修复请求去重的稳定 key、等待者独立取消和 multipart 兼容边界。
✅ 完成缓存策略、过期判断、ETag/Last-Modified、304、networkElseCache 和损坏缓存恢复。
✅ 增加认证刷新 actor 合并，多个 401 请求只共享一次 token 刷新并各自重放一次。
✅ 增加原生 PTWebSocketClient，覆盖状态机、队列上限、心跳、超时、网络恢复和前后台生命周期；PTSocketManager 保留兼容入口。
✅ 增加 PTSecurity 原生安全门面，使用 CryptoKit/Security.framework，旧 CryptoSwift、KeyChain 和 SecuritySuite 入口保持兼容。
✅ CocoaPods 与 SwiftPM 增加 Security 产品/子模块；不升级第三方依赖，不修改 Pods 源码。
完成真实宿主与真机上的 100 并发 401、断网恢复、WebSocket 服务端心跳和 Keychain 生物识别回归。

5.15.0 Media 全家桶

✅ MediaCore 增加统一的 PTMediaAsset、PTMediaType、PTMediaMetadata、PTMediaResource 和 PTMediaSource 值类型，Picker、Viewer、Editor 适配层不再新增重复基础模型。
✅ Core 增加 PTImageDownsampler 和 PTImageMemoryBudget；本地大图、Data 图片和视频封面统一使用 ImageIO 目标像素解码。
✅ 增加 PTMediaCache，以 Memory/Disk、处理变体、尺寸和帧号组成稳定缓存键，避免原图、缩略图、GIF 与 Live Photo 冲突。
✅ PTVideoFileCache 增加下载去重、Range 续传、.part 临时文件、原子替换和视频磁盘容量维护。
✅ MediaViewer Cell 统一复用失效、任务取消、GIF 停止、Live Photo 停止和缩放状态清理；VideoEditor 提供幂等 invalidate() 生命周期入口。
✅ ImagePicker 继续承担单媒体系统选择，PhotoPicker 继续承担自定义 PhotoKit 多媒体选择；两者保持清晰共存和兼容入口。
✅ 更新 Media、Picker、Editor 的迁移、模块和依赖文档；Xcode Simulator Debug/Release 构建作为本版本必要门禁。
在真实设备和独立宿主完成 4K 图片、100+ 媒体快速浏览、Live Photo、iCloud、编辑取消、后台切换和低磁盘空间回归。

5.16.0 Permission / System Services

✅ Permission Core 增加统一的 PTPermissionAuthorizationState，保留旧 PTPermissionStatus 入口，并将 callback 兼容层统一收敛到 exactly-once 完成闸门。
✅ Location、Bluetooth、Photos、Notification 和 Face ID 补齐 restricted、limited、provisional、ephemeral、硬件状态、精度和 passcode fallback 等值类型状态。
✅ PhotoKit、Notification、Location 和联系人等系统回调明确回到 MainActor；重复点击、系统回调缺失或重复时不会让兼容 completion 永久悬挂或重复执行。
✅ IAP、NFC、Motion、HealthKit、MetricKit 和 GPS 增加幂等 start() / stop() / invalidate() 生命周期入口，释放 delegate、observer、query、session 和 pending callback。
✅ 修复 HealthKit 统计查询未停止、IAP transaction observer 重复注册、NFC 旧 session 残留、定位授权成功后重复请求和 Photos limited 状态丢失问题。
✅ 增加 5.16 Permission / System Services 质量门禁，并保持 iOS 17+、Swift 6+、CocoaPods/SwiftPM/Xcode 入口和既有公开 API 兼容。
在真实设备和独立宿主完成权限弹窗后台切换、Scene disconnect、Location accuracy、Photos limited、通知 provisional/critical、IAP、NFC、HealthKit 和 MetricKit 回归。

5.17.0 UI Components / Utility

✅ 建立 42 个 UI/Utility 模块逐项结账清单，记录 Owner、Dependency、Lifecycle、Test、Example、Doc 和 6.0 decision。
✅ SearchBar 增加可取消防抖、异步搜索 generation、加载状态、清空入口和不覆盖自定义文字的语言刷新。
✅ Loading/HUD/TipsView 收敛场景窗口、重复展示、空配置、Timer、DisplayLink、动画和离屏生命周期。
✅ Picker、Alert、Scene、MainActor 和 WebKit 的 canonical contract 纳入 5.17 静态门禁；WebKit 增加旧导航回调隔离、外部 scheme 取消和内容进程恢复。
✅ ZipArchive、GCDWebServer、Instructions、Appz、Flag、PopoverKit 和 NotificationBanner 作为外部适配器登记边界，不修改第三方源码。
✅ 质量门禁接入 Scripts/validate_517_ui.sh，保持 iOS 17+、Swift 6+、公开 API 和三套入口兼容。
在真实宿主和设备完成键盘、Stage Manager、VoiceOver、Dynamic Type、Dark Mode、WebKit 进程恢复、外部服务、轮播/分页和所有 42 个模块的视觉回归。

5.18.0 Debug / Instruments

✅ 新增 PTDebugHookRegistry，统一 Collector 与 Core runtime adapter 的安装、卸载、owner 和状态快照；重复启动幂等，停止路径可逆。
✅ PTInstruments 增加 disk、threads、launch、ViewController lifecycle、tasks 和 signposts 类型化入口，复用现有 Debug Event Center，不新增重复 swizzle 或 Collector。
✅ PTInstrumentSession 使用固定容量环形缓冲，超过容量覆盖最旧记录并累计 droppedCount；CPU、memory、disk、threads、FPS 和主线程卡顿采样均可取消。
✅ .pttrace 增加显式导入、只读回放、轨迹对比和 PTInstrumentRecorder.liveSnapshot()；Dashboard 以固定节奏批量刷新，减少 UI 压力。
✅ LocalConsole 的窗口初始化、Scene 几何、安全区和关闭路径继续保持可逆，异常初始化不再触发 fatalError。
✅ 新增 Scripts/validate_debug_instruments_5_18.sh 并接入质量扫描；PooTools Debug Simulator Debug 构建通过。
在真实设备完成 CPU、内存、FPS、Hitch、主线程卡顿、磁盘、线程和 30–60 分钟录制的中位数/峰值对比。
在多 Scene、分屏、旋转、键盘、Scene disconnect 和真实宿主中完成 Debug window 与 Hook install/uninstall 回归。

5.18.1 Search Container

✅ 新增 PTSearchViewController<Item>，通过 PTListViewController 复用 PTBaseViewController、PTCollectionView 和 PTSearchBar，不依赖 UISearchController。
✅ 新增 PTSearchState、PTSearchConfiguration、Local/Remote/Hybrid/Custom 模式、Provider、History、Suggestion、Pagination、Refresh、Empty、Error 和 Snapshot 契约。
✅ 统一 debounce、Task cancellation、旧请求丢弃、分页锁、搜索取消、键盘处理和页面销毁时的任务释放路径。
✅ 支持 contentTop、navigationBar、navigationBarExpanded 和 custom 四种展示位置；导航栏通过 PTSearchPresentationContext 恢复原始状态。
✅ SearchBar 支持 classic、custom、glass 视觉样式；iOS 26 使用 UIGlassEffect，iOS 17–25 使用语义材质回退，并保留 Dynamic Type、RTL、Dark Mode、Reduce Transparency 和 VoiceOver 入口。
✅ 增加 SwiftPM、CocoaPods、源码解析和版本契约门禁；Search 作为 Core/SearchBar 之上的可选模块发布。
在真实宿主完成快速输入、旧请求回写、History/Suggestion、分页/刷新、Push/Pop、Dynamic Type、RTL、VoiceOver、Dark Mode、多 Scene 和 iOS 17/18/26+ 视觉回归。
不新增 XCTest target；如后续需要单元测试，先在独立测试宿主验证并保留现有公开 API 不变。

5.19.1 PhotoPicker Layout Patch

✅ 修复 PTMediaLibViewController.selectLibButton 重新测量后被导航栏左右铺满约束覆盖的问题，恢复 PTNavBar 的 .auto 标题宽度逻辑。
✅ 标题内容变化后按实际富文本与图片尺寸重新获取 bounds，向上取整并保证最小可见宽度，避免标题或下拉图标显示不全。
✅ 复用既有标题视图并刷新约束，不在每次标题更新时重复移除和添加视图；保留 iOS 17+、Swift 6+ 和公开 API 兼容。

5.19.5 Collection Refresh Inset Compatibility

✅ 底部刷新隐藏判断纳入调用方设置的 contentInset.top/bottom，避免 iOS 26 布局留白让 PTRefreshFooter / PTRefreshAutoFooter 永久隐藏。
✅ 外部修改 contentInset 后立即重新计算 footer 可见性并更新还原基线，footRefreshTask 可以在列表重新变为可滚动时正常触发。
✅ verticalScrollIndicatorInsets.bottom 保持纯展示职责，不改变内容滚动和刷新触发边界。
✅ 已创建正式 5.19.5 tag；真实设备验证不同内容高度、导航栏/TabBar 留白、旋转、分屏和 iOS 26 玻璃布局下的底部刷新回调仍属于后续回归项。

5.20.0–5.20.2 Logging Foundation

✅ 建立 COCOALUMBERJACK_USAGE_AUDIT.md，扫描 CocoaLumberjack、DDLog、File Logger、formatter、runtime level、custom logger 和公开 API 泄露。
✅ 新增 SwiftPM PToolsLogging product/target，保持 Foundation/OSLog-ready 的低层边界，不依赖 UIKit、Debug、Network、媒体或 CocoaLumberjack。
✅ 新增 CocoaPods PooTools/Logging subspec，并让 PooTools/Core 依赖该契约；旧入口在迁移窗口内保留。
✅ 新增 PTLogLevel、PTLogCategory、PTLogRecord、PTLogConfiguration、PTLogDestination 和 PTLogger，所有跨并发边界的数据为 Sendable 值类型。
✅ 新增 5.20.x logging foundation 门禁，并纳入构建、质量和发布检查。
✅ 5.20.1 接入默认 OSLog backend、subsystem/category Logger cache、runtime/category filtering 和 Error 元数据摘要。
✅ 5.20.2 接入可选文件日志、单消费者缓冲、flush、轮转、保留、脱敏和内部错误降级；文件错误不会反向触发日志递归。
✅ 新增 PToolsLoggingTests，覆盖等级、分类、隐私脱敏、文件写入和轮转边界。

5.21.0–5.21.2 Logging Migration / Debug Diagnostics / Privacy

✅ 5.21.0 将旧日志实现迁移到 PTLogger；旧 PTNSLog 入口进入兼容窗口。
✅ 5.21.1 新增 PTMemoryLogDestination、actor 所有的有界 Ring Buffer、单 worker 消费和多订阅流；LocalConsole 与 PTInstruments Logs 复用同一条内存日志管线。
✅ LocalConsole 增加 category、level、keyword 三类筛选，日志 UI 使用批量刷新，筛选不会改变底层日志记录。
✅ 5.21.2 增加 PTLogRedactor 的文本/记录脱敏 API、Network 请求与响应头脱敏、背压快照、drop policy、后台 flush 和 PTLogger.exportLogFiles。
✅ 增加内存日志边界、重要等级保留、多订阅者、策略丢弃、采样和性能测试，并新增 5.21 日志契约门禁。
5.22.0–5.22.2 Logging Dependency Removal / Closure
✅ 5.22.0 从 SwiftPM、CocoaPods、Package.resolved 和 Podfile.lock 移除旧日志第三方依赖；Core 与 Logging 的包管理器入口保持一致。
✅ 5.22.0 增加实现路径依赖扫描，迁移审计文档保留历史名称但交付源码、清单和锁文件不得出现旧后端。
✅ 5.22.1 删除旧 PTLogFileManager 的独立文件实现、PTLogSinkCenter 和 UI sink 兼容实现；保留 PTLogFileManager 历史符号作为仅转发 PTLogger 的兼容适配器，PTNSLog 与 PTOSLogger 同样完全转发到 PTLogger。
✅ 5.22.1 保证 LocalConsole 与 PTInstruments 只消费共享 PTMemoryLogDestination，不再维护第二条日志管线。
✅ 5.22.2 增加 DEPENDENCY_POLICY.md、5.22 迁移指南、依赖门禁和版本收口记录。
✅ 5.22.2 完成 API、性能、Debug、Core 依赖图和 SwiftPM/CocoaPods parity 的发布前复核；不创建未验证的 tag。

5.19.4 Dark Mode MainActor Notification Bridge

✅ 修复 PTDarkModeScheduleMonitor.environmentDidChange 被系统时间、时区或场景通知从后台队列调用时触发 dispatch_assert_queue 的问题。
✅ Objective-C 通知入口保持 nonisolated，只负责通过 PTMainActorBridge 投递；暗色模式刷新、定时器和 observer 状态仍只在 MainActor 内访问。
✅ 不使用 nonisolated(unsafe)，不改变公开暗色模式 API，也不改变通知名称和已有刷新语义。
在真实设备验证手动切换外观、跨午夜、修改时区、系统时间变化、Scene 激活和后台恢复；该验证继续随 5.19.5 开发线保留。

✅ 修复 PTNavBar.titleView 设置时覆盖 titleContainer 约束的问题，标题现在相对整条伪导航栏居中。
✅ 为标题容器设置明确可用宽度，并按左右较宽按钮组计算安全边界，避免长标题和按钮布局变化导致偏移。
✅ 修复清空右侧按钮时误操作左侧容器的问题。
✅ 已创建正式 5.19.3 tag；后续暗色模式通知线程修复和回归记录归入 5.19.4 开发线。

5.19.2 PhotoPicker / Swift 6 Concurrency / Documentation

✅ 修复 PTMediaLibAlbumListViewController.navTitle 未居中：伪导航栏标题使用 .auto 测量模式，标题单行截断并设置水平 hugging/compression resistance，保证按钮变化和长标题下仍保持视觉中心。
✅ 修复 PTHTMLHeightCalculator 在 deinit 中直接触碰 WebKit MainActor 状态的警告；销毁阶段只结束挂起 continuation，WebKit 对象由 UIKit 生命周期释放。
✅ 修复 PTHealthKit 的冗余条件转换，并移除 PTBiometricsManager 对 LAContext 的 detached 捕获。
✅ 将图片颜色计算、Vision 识别和视频封面处理改为先创建 Data/CGImage/系统对象快照，再进入后台工作；业务回调继续回到 MainActor。
✅ 将 Debug 窗口的 UIWindow.lastTouch 改为锁保护的值类型状态；PTLanguage、路由、动画配置等已有 actor/锁边界继续登记，不新增 nonisolated(unsafe)。
✅ 新增 CONCURRENCY.md 和 validate_concurrency_5_19.sh，统一记录 actor isolation、non-Sendable capture、MainActor、全局状态和 detached 使用规则。
✅ 将根目录 _config.yml 作为 GitHub Pages 文档配置使用，补充站点信息和源码排除清单；不把它误用为 iOS 构建配置。
✅ 合并历史架构收口文档到当前架构、质量和并发文档，避免重复事实源；保留公开 API、iOS 17+ / Swift 6+ 和第三方依赖兼容策略。
✅ 已创建正式 5.19.2 tag；后续导航标题修复和回归记录归入 5.19.3 开发线。

5.19.0 Package / Dependency / Tests / Docs

✅ 新增根目录 VERSION 作为唯一版本源，CocoaPods、Podfile.lock、README、CHANGELOG、ROADMAP 和版本门禁统一读取或验证 5.19.x。
✅ 生成 CocoaPods / SwiftPM PACKAGE_MATRIX.md，为模块标记 A（双入口）、B（仅 Pods）、C（仅 SPM）、D（兼容弃用）、E（合并）或 F（6.0 移除）。
✅ 生成 DEPENDENCY_MATRIX.md，记录每个模块的直接依赖、第三方依赖、可移除候选和 6.0 决策。
✅ 建立 5.18.2 Public API baseline 与 5.19.x API 差异门禁；新增 API 必须记录，删除 API 默认失败。
✅ 建立 13 个领域的测试矩阵，复用现有 SwiftPM 测试 target，并明确静态、Example、Simulator、真机和真实宿主的验证缺口。
✅ 建立历史拼写和编译宏兼容登记；新增 drop、POOTOOLS_BIOID、POOTOOLS_ZIPARCHIVE 和 POOTOOLS_MXMETRICMANAGERKIT canonical 入口，旧名称继续兼容。
✅ 补齐 Package、依赖、测试、API、迁移和文档质量门禁；不升级第三方依赖、不修改 Pods 源码。
完成真实宿主、真机和 SwiftPM/CocoaPods/Xcode 全矩阵运行回归后，再创建 5.19.x 正式 tag。

当前 5.11.x 稳定化

以下工作仍属于当前开发线，完成后是否产生新的 patch 版本由实际 bugfix 和发布需要决定：

✅ 文档目录重组完成，根目录只保留入口文档。
✅ 生成当前 Public API baseline，并由真实源码 revision 标记。
✅ 生成当前 CocoaPods / SwiftPM module graph，并检查 Core 边界。
完成 PTInstruments 在真实设备上的 CPU、内存、FPS、主线程卡顿和长会话测量。
完成 Debug 多 Scene、Scene disconnect、分屏、旋转和真实宿主回归。
完成 PooTools-Example 与至少一个真实宿主的迁移风险记录。
清理 6.0 deprecated inventory，逐项确认调用方、迁移说明和删除条件。
完成 Debug disabled/enabled 的开销对比，并把结果冻结到 report/baselines/5.11/。

已落地能力的实现事实维护在当前架构文档和发布记录中，不在路线图重复展开历史任务。

6.0 前置条件

模块和架构冻结

冻结 Core、UIFoundation、Permission、Network、Media、Debug 的模块图。
冻结公开 API baseline，并对每个变化完成人工批准。
冻结 legacy wrapper、拼写兼容入口和重复实现的删除清单。
确认 Core 不反向依赖 Debug、业务 UI 或宿主工程。
完成 CocoaPods、SwiftPM、Xcode 三套 source membership 与依赖方向检查。

迁移和发布冻结

docs/migration/MIGRATION_6.md 覆盖所有待删除入口。
PooTools-Example 不再调用计划在 6.0 删除的入口。
至少一个真实宿主完成 Core、Network、Media、Navigation、Debug 的迁移演练。
完成 Debug / Release、Simulator、Generic Device、CocoaPods lint 和 SwiftPM 验证。
生产 Core 不隐式创建 Debug UI、采样器、DisplayLink、日志 sink 或诊断 observer。

6.0 计划

当上述冻结条件全部满足后：

删除已经经过一个完整 5.x 兼容周期、且没有仓库或宿主调用方的 deprecated API。
删除经过人工批准的拼写错误入口和重复实现，保留必要的兼容适配器。
最终确认 Core、Permission、Network、Media、Debug 的边界和安装文档。
更新 CocoaPods、SwiftPM、Xcode 和 README 的安装示例。
发布 6.0 前完成完整质量矩阵、迁移说明和回滚准备。

延期能力

以下能力不作为当前 5.11.x 的发布阻断项：

完整 Time Profiler call tree。
Allocations object graph。
System / Metal Trace。
Mach stack unwinding、符号化和 dSYM profiler pipeline。

这些能力会显著扩大运行时风险，只有在有明确产品需求和独立性能预算时再立项。

验收入口

bash Scripts/validate_docs.sh
bash Scripts/validate_document_versions.sh
bash Scripts/validate_build_entries.sh
bash Scripts/validate_quality_scans.sh
git diff --check

Xcode、真机、真实宿主和 Instruments 的结果必须分别记录；静态检查或单次编译不能替代运行时验收。