用途
axiom-swiftui-nav-diag 是一个用于调试 SwiftUI 导航问题的技能。其核心原则是：85% 的导航问题源于路径（path）状态管理错误、视图标识问题或放置位置错误，而非 SwiftUI 缺陷。SwiftUI 的导航系统被数百万应用使用，能可靠处理复杂导航模式；若导航失败、无响应或行为异常，问题几乎总是出在导航状态的管理方式上。该技能旨在提供系统化诊断，帮助在数分钟内而非数小时内定位根本原因。
危险信号
若出现以下任一情况，应怀疑是代码问题而非框架损坏：点击导航无反应（链接存在但不推入）；返回按钮弹到错误界面或根视图；深链接打开应用却显示错误界面；切换标签时导航状态丢失；应用进入后台时导航状态丢失；同一 NavigationLink 推入两次；导航动画卡住或不流畅；堆栈跟踪中出现 navigationDestination 崩溃。
资料明确禁止“SwiftUI 导航坏了，我们把 UINavigationController 包一层”这类做法，理由包括：NavigationStack 被 Apple 自家应用使用；包裹 UIKit 会增加复杂度并失去 SwiftUI 状态管理优势；UIKit 互操作有其自身的边界情况，需要数周才能发现。
强制首要步骤
在修改代码前，必须先行以下检查：
- 添加 NavigationPath 日志：在 NavigationStack 的 path 上使用 onChange(of: path.count) 打印路径变化，若从不触发说明链接未修改路径，若意外触发说明有其他代码修改路径。
- 检查 navigationDestination 是否可见：在 destination 闭包中加临时 print，若从不打印说明 destination 未被求值。
- 检查 NavigationLink 是否在 NavigationStack 内：沿视图层级向上追踪，必须命中 NavigationStack 而非其他容器。
- 检查 path 状态位置：@State 必须位于稳定的视图中（而非每次渲染都重建），必须是 @State、@StateObject 或 @Observable，不能是局部变量。
- 隔离测试基础用例：用 String 值建立最小复现，若最小用例可用，问题在你的具体设置中。
观察与诊断对照
onChange 在点击时从不触发 → NavigationLink 不在 NavigationStack 层级内；onChange 触发但不推入视图 → navigationDestination 未找到或未加载；onChange 触发、推入后立即弹出 → 视图标识问题或路径被修改；路径意外变化（非点击引起）→ 外部代码修改了路径；深链接 path.append() 不导航 → 时机问题或线程错误；切换标签时状态丢失 → NavigationStack 在标签间共享；首次可用、返回时失败 → 视图重建问题。
强制判读
修改任何代码前，须先确定以下之一：若点击链接无反应且无 onChange → 链接在 NavigationStack 外；若 onChange 触发但无推入 → navigationDestination 不在作用域内；若推入后立即弹出 → 视图标识变化或路径重置；若深链接失败 → 时机或 MainActor 问题；若崩溃 → 路径解码强制解包或类型未注册。若诊断矛盾或不清晰，应停止，不要进入模式阶段，而是在每个路径修改点加 print、建立最小复现、先用 String 值测试。
决策树
资料提供了完整决策树，按导航问题分类：点击无反应、意外弹栈、深链接不工作、状态丢失、NavigationSplitView 问题、崩溃，分别指向对应模式（Pattern 1a 至 6c）。例如点击无反应时，先判断 NavigationLink 是否在 NavigationStack 内（否则 Pattern 1a），再检查 navigationDestination 注册情况（懒容器中→1b、类型不匹配→1c、被 sheet/popover 阻挡→1d、使用基于视图的旧链接→1e）。
模式选择规则
导航点击无反应 → 先加 onChange 日志，再进 Pattern 1；意外弹栈 → 先找出谁修改了路径，再进 Pattern 2；深链接失败 → 先确认 URL 已接收（在 onOpenURL 中打印），再进 Pattern 3；状态丢失 → 先确定何时丢失（切换标签还是后台），再进 Pattern 4；崩溃 → 先获取完整堆栈跟踪，再进 Pattern 5。一次只应用一个模式，实现并充分测试后，仅当问题仍存在才尝试下一个模式；不要同时应用多个模式。
具体诊断模式
资料给出了各模式的时间成本、症状、诊断与修复代码。包括：Pattern 1a（NavigationLink 在 NavigationStack 外，5–10 分钟）、Pattern 1b（navigationDestination 在懒容器中，10–15 分钟）、Pattern 1c（类型注册不匹配，10 分钟）、Pattern 2a（每次渲染重建 NavigationPath，15–20 分钟）、Pattern 2d（在非 MainActor 修改路径，10–15 分钟）、Pattern 3a（深链接线程问题，15–20 分钟）、Pattern 3c（深链接路径构造顺序，10–15 分钟）等。每个模式均含错误示例、正确示例与验证方法。例如 Pattern 2d 指出应从后台任务修改路径会出错，修复方式是用 @MainActor 标注或 await MainActor.run 包裹，最佳实践是使用带 @MainActor 的 @Observable Router 类。
适用场景与限制
该技能适用于使用 SwiftUI 导航（NavigationStack、NavigationSplitView、NavigationLink、navigationDestination、NavigationPath、深链接）的 iOS/macOS 开发调试场景。限制方面，资料未提供具体支持的平台版本、依赖或安装方式。