在现代化 iOS 多窗口环境下替换 UIKit…

将 UIKit 应用从遗留共享状态 API（UIScreen.main、interfaceOrientation、application 生命周期、对称安全区假设）迁移到适配多窗口与动态尺寸的现代 API。

适用场景

解决思路

1. 优先使用离消费点最近的信息源：例如优先用 view 的 trait collection，而不是 window 的。
2. 当目标 API 存在时必须应用替换：仅留 TODO 是失败，包含目标 API 的文件产生空 diff 也是失败；只要在活动任务参考文件中任一模式下能给出具体替换就应应用；仅当目标 API 只出现在死代码（#if 0/#endif）中才跳过；在两个有效替换间犹豫时，选择最符合用户请求的那个，而不是产生空 diff；绝不静默跳过文件，若不愿修改就与用户讨论选项；不要在简单文件上纠结边界情况，替换明显就直接应用。
3. 留下的 TODO 必须可执行：每个 TODO 要说明（a）为什么需要改，（b）正确的替换应是什么样，（c）任何生命周期或线程方面的顾虑；TODO 放在未改动代码的上一行独立成行，绝不内联；含糊的 TODO（如“以后修”）比没有更糟。
4. 当已有注解覆盖该迁移时不要添加冗余 TODO：如果调用点已有配对的 #pragma clang diagnostic ignored 加 bug 报告引用、已有 // TODO，或已有指向迁移的弃用注释，就不要再加；仅当新 TODO 提供现有注解没有的迁移指导时才添加。
5. 进行有风险的代码改动前先询问用户；仅在无法交互时回退到 TODO：当替换可能破坏调用方或改变可观察行为（例如修改被其他模块 import 的头文件中的方法签名；在左右方向重要时用 width > height 替代 orientation）时，第一步是询问用户如何处理；仅当技能非交互运行或用户明确拒绝提供指导时，才留下 TODO 继续；这不适用于活动任务参考文件中规定的标准、可直接替换的安全替换——那些必须按核心原则 2 应用。
6. 遵循用户的明确指示；否则应用任务参考文件中的默认值：当用户要求特定做法（特定属性、参数名、参数位置、trait 来源或回退行为）时，严格照做，不要静默替换为你认为的现代等价物；当用户表述笼统（“现代化这个应用”“修复 UIScreen.main 用法”）时，应用活动任务参考文件中的默认值。
7. 绝不用字面量替换动态值——始终保持替换结果是动态的。
8. 保持控制流：优先使用维持原代码结构的直接替换；仅当直接替换不可行时才添加 guard/提前返回模式；在编辑 if/else、switch/case/default、do/catch 周围代码时，验证编辑后分支结构保持不变；除非用户明确要求，绝不删除分支（} else {、default:、catch）；把 if/else 折叠成顺序执行是严重 bug——两个分支都会无条件执行。
9. 保持在范围内——不做顺手清理：只修改包含活动任务目标弃用 API 的行；不要顺便修复附近的其他弃用；不要修剪行尾空白、重排空行或“清理”周边格式；即使相邻行有明显现代化机会也放着不管——每个任务独立，范围外编辑会把成功的范围内改动变成警告。
10. 提取重复表达式：当同一替换值在某个作用域内多次使用时，提取为具名局部变量。
11. 绝不遍历全局 scene/window 状态：绝不用 UIApplication.shared、UIDevice.current、UIScreen.main 或其他共享对象作为替换；若没有可用的局部对象，就修改方法以接受新参数并弃用旧方法。
12. 完整模式——原子化，绝不部分应用：每个多部分模式要求所有部分作为单一原子单元一起应用；弃用并转发需要弃用 + 新重载 + 转发——当模式要求方法提取时，绝不只是内联替换；当活动任务同时要求 API 替换和响应式更新（例如 trait 变化观察）时，它们构成单一原子改动——绝不只应用其一；把弃用并转发模式降级为对共享对象的内联引用是错误——它会静默破坏调用方赖以找到新 API 的弃用桥；如果无法完成全部四部分（具有合适参数名/类型/位置的新重载、旧方法用共享状态（如 UITraitCollection.current、UIScreen.main）委托、旧方法用合适属性标记弃用、弃用包装保留在原位），就不要应用部分改动——要么完成完整模式，要么以明确理由跳过。
13. 添加新重载时绝不删除旧方法：应用弃用并转发时，旧方法必须留在文件中作为弃用包装，通过 .current 转发到新重载；删除旧方法（即使 diff 中看似未使用）会从代码库移除弃用信号并静默丢弃迁移桥；这适用于 ObjC 方法、Swift 方法、Swift 初始化器、计算属性和协议扩展方法；如果你发现自己在添加新重载时删除方法，停下——应保留它并加弃用属性，而不是删除。
14. 保留无关的 guard 和回退：移除 UIScreen.mainScreen 引用时只改那个引用；不要同时删除 respondsToSelector: 检查、nil-screen guard、if (screen != nil) 防御、版本检查（#available、@available）或任何其他包裹调用点的防御逻辑——除非用户明确要求；每个 guard 都有独立原因（跨 SDK 版本的选择器可用性、nil-window 安全、功能开关）；现代化只触及 screen 派生值，不触及周围控制流。
15. 在触及弃用 API 的最低层方法上应用弃用：当多个调用方汇入一个实际读取弃用共享状态的 helper 时，把弃用并转发放在该 helper 上，而不是每个公共调用方；当 helper 是唯一需要它的地方时，强迫每个公共调用方都长出 traitCollection: 参数会产生过宽改动和超出迁移需要的爆炸半径；反之，当弃用状态直接在每个公共调用方内读取（无 helper）时，弃用属于公共调用方——没有更低的层可弃用；经验法则：找出包含你否则需要修改的那行的方法，弃用那个方法；弃用链只应扩展到实际触及弃用 API 的宽度。
16. 偏离目标替换防护：编辑任何行之前验证两件事：（a）该行包含活动任务的目标弃用 API，（b）你编辑的是用户询问的那个弃用——不是附近“看起来相似”的行。
17. Phase 0 简单情况快速路径：在进入决策树之前，检查出现处是否匹配简单情况；大量 UIScreen.main/UIScreen.mainScreen 出现是 UIView/UIViewController 实例方法内、值被新鲜消费的简单替换，无需分析，直接替换：Swift 中 UIView/UIViewController 实例方法内内联使用（未存储）的 UIScreen.main.scale 替换为 self.traitCollection.displayScale；ObjC 中同样场景的 [UIScreen mainScreen].scale 替换为 self.traitCollection.displayScale；layoutSubviews、drawRect:、updateConstraints 或 viewIsAppearing: 中的 UIScreen.main.scale 替换为 self.traitCollection.displayScale（无需注册——UIKit 在 trait 变化时自动调用这些）；不要过度思考简单替换：如果所在类是 UIView/UIViewController 且值未赋给 ivar、layer 属性、约束或存储图像，就直接替换；简单文件上的空 diff 是最常见错误——应用替换并继续；仅当简单情况不匹配（非 view 类、缓存值、类/静态方法、特殊用户指示）时才使用决策树。
18. Phase 1 检测：使用每个相关任务文件的检测模式识别要现代化的模式；对 Task Registry 中适用于该代码库的每个任务运行检测，而不只是一个。
19. Phase 2 分析：对每个出现处读取周围上下文以理解：类层次（UIView/UIViewController 子类 vs 普通 NSObject vs 非 view 类）、方法类型（实例、静态、自由函数、缓存的 dispatch_once helper）、生命周期阶段（init、viewDidLoad、viewWillAppear、layoutSubviews）、代码意图（布局、渲染、显示缩放、全屏尺寸）；活动任务参考文件可能向此列表添加任务特定条目；使用子代理识别需要更新的代码以保持上下文窗口小。
20. Phase 3 决策与验证：若存在安全 1:1 替换则应用它，不加额外注释（不要 // TODO: FIXME、// TODO、// FIXME——只做替换），使用活动任务参考文件指定的替换；若有多个有效方案或代码搬迁超过 10 行则询问用户；若无法安全替换（极罕见）则添加带明确任务的 TODO 给用户，绝不产生静默空 diff，在断定无适用前用子代理重新检查每个模式；在任何代码改动前用子代理对照活动任务的 Post-file Checklist 验证。
21. Phase 3b 文件处理完整性：处理包含目标弃用 API 的每个文件；不要提前停止、跳过文件或从工作队列静默丢弃文件；Phase 1 中识别但未产生 diff 且无跳过说明的文件是处理失败；开始时用任务/todo 工具或 markdown 文件写出要修改的完整文件列表，处理每个文件时标记完成，结束前对照输出——任何没有 diff 或明确跳过理由的文件都是失败，必须完成前解决；若担心上下文大小，用子代理处理单个文件或任务；结束前用子代理比较给你的文件列表与你产生输出的文件列表，若输出中缺少任何文件就回去处理；静默丢弃的常见原因：文件大小（1000+ 行不豁免，同样处理）、复杂度（含预处理器宏、复杂类层次或不常见模式的文件仍需改动）、项目分组（不要跳过某个项目或目录的所有文件；若发现丢弃同一项目的多个文件，说明有系统性问题，调查并修复）、歧义（不确定如何修复就询问用户，不要静默产生空 diff）；大型或复杂文件：含大量预处理器使用（#if/#ifdef 嵌套）、1000+ 行或较少见模式（C++ 互操作、dispatch_once 缓存、深层嵌套宏）的文件不豁免处理；若目标 API 出现在此类文件中，应用相同决策树；若文件太大无法一次编辑，逐个处理弃用 API 用法；如有帮助可用子代理；若因宏展开或预处理器复杂性确实无法确定安全替换，询问用户——绝不静默跳过。
22. 批量处理纪律：处理文件列表时，不要先分析所有文件再一次性产生所有 diff；而是一次处理一个或小批量（3–5 个文件）：读上下文、决策、产生 diff，再进入下一批；这防止文件列表尾部因输出限制或上下文耗尽被静默丢弃；若发现产生输出的文件少于给你的文件，停下并在结束前处理剩余文件；若发现本应有直接替换的文件出现空 diff，回去处理——直接的文件处理很快，绝不应被丢弃。
23. Phase 4 实现：应用活动任务的实现门、规则和 post-file checklist（来自其参考文件）；模式特定的决策树、门问题和验证规则与它们所治理的模式一起放在每个任务文件中；用子代理验证。
24. Phase 5 最终验证：文件覆盖审计——用子代理比较给你的文件列表（或 Phase 1 检测到的）与你实际产生 diff 的文件；每个输入文件必须有非空 diff；若有文件缺少改动，现在回去处理；活动任务参考文件可能添加任务特定验证步骤。
25. Task Registry：除非开发者请求明确限定子集，否则对代码库应用此注册表中的每个任务；每个任务独立，有其参考文件中的检测模式、决策树和验证规则；从上到下依次运行：UIScreen.main 现代化（uiscreen-task.md，用上下文合适的 API 替换 UIScreen.main）、userInterfaceOrientation 现代化（orientation-task.md，用 size class 或 window bounds 替换与布局相关的 orientation 检查）、Scene 生命周期迁移（scene-lifecycle-task.md，将 AppDelegate 迁移到 SceneDelegate）、安全区 Insets（safe-area-task.md，用安全区引用替换硬编码 inset 值，并确保现有引用在非对称安全区下正常工作）。

适用边界 · 注意事项

• 目标弃用 API 只出现在死代码（#if 0/#endif）中时。
• 替换可能破坏调用方或改变可观察行为且无法与用户交互确认时（应留 TODO 而非强行替换）。
• 用户明确要求只处理某个子集任务时，不要应用 Task Registry 中的全部任务。