# 深度链接调试 ## 何时使用此技能使用时： * 添加仅调试深层链接以进行模拟器测试 * 启用自动导航到特定屏幕以进行屏幕截图/测试 * 与 `simulator-tester` 代理或 `/axiom:screenshot` 集成 * 需要以编程方式导航，无需生产深层链接实现 * 无需手动点击即可测试导航流程 **请勿用于**： * 生产深度链接（使用 `axiom-swiftui-nav` 技能代替） * 通用链接或应用程序剪辑 * 复杂的路由架构 ## 提示示例 #### 1\. “Claude Code 无法导航到特定屏幕进行测试” → 添加仅调试 URL 方案以启用 `xcrun simctl openurl` 导航 #### 2\. “我想自动截取不同屏幕的屏幕截图” → 为每个屏幕创建调试深层链接，可从模拟器调用 #### 3\. “自动化测试需要设置特定的应用程序状态” → 添加导航和配置状态的调试链接 ** ** ## 危险信号 - 当您需要调试深层链接时如果您遇到任何这些情况，请添加调试深层链接： **测试摩擦力**： * ❌“我必须手动点击 5 个屏幕才能测试此功能” * ❌“截图无法显示我需要调试的屏幕” * ❌“如果没有复杂的设置，自动化测试无法达到错误状态” **调试效率低下**： * ❌“我进行修复、重建、手动导航、检查 — 每次迭代需要 3 分钟” * ❌“无法直观地验证修复，因为 Claude Code 无法导航到那里” **解决方案**：添加调试深层链接，让您（和 Claude Code）直接跳转到具有任何状态配置的任何屏幕。 ** ** ## 实施 ### 模式 1：基本调试 URL 方案 (SwiftUI) 添加路由到屏幕的仅调试 URL 方案。导入 SwiftUI 结构我的应用程序：应用程序{ var body: 一些场景 { 窗口组{ 内容视图() #如果调试 .onOpenURL { 网址处理调试URL(url) } #endif } } #如果调试私人函数handleDebugURL（_ url：URL）{ 保护 url.scheme == "调试" else { return } // 基于主机的路由切换 url.host { 案例“设置”： // 导航到设置通知中心.default.post( 名称：.navigateToSettings，对象：无）案例“简介”： // 导航到个人资料让 userID = url.queryItems?["id"] ?? “当前” 通知中心.default.post( 名称：.navigateToProfile，对象：用户ID ）案例“重置”： // 将应用重置为初始状态重置应用程序() 默认： print("⚠️ 未知的调试 URL: \(url)") } } #endif } #如果调试扩展通知.名称{ 静态让navigateToSettings = Notification.Name（“navigateToSettings”）静态让navigateToProfile = Notification.Name（“navigateToProfile”） } 扩展网址 { var queryItems：[字符串：字符串]？ { Guard let Components = URLComponents(url: self, resolvingAgainstBaseURL: false), 让 items = Components.queryItems else { 返回零 } 返回字典(uniqueKeysWithValues: items.map { ($0.name, $0.value ?? "") }) } } #endif **用法**： # 来自模拟器 xcrun simctl openurl 启动“debug://settings” xcrun simctl openurl 启动“debug://profile?id=123” xcrun simctl openurl 启动“debug://reset” ** ** ### 模式 2：NavigationPath 集成（iOS 16+）将调试深层链接与 NavigationStack 集成以实现稳健的导航。导入 SwiftUI @主要演员类 DebugRouter: ObservableObject { @Published var 路径 = NavigationPath() #如果调试 func handleDebugURL(_ url: URL) { 保护 url.scheme == "调试" else { return } 切换 url.host { 案例“设置”：路径.追加（目标.设置）案例“食谱”：如果让 id = url.queryItems?["id"], 让recipeID = Int(id) { path.append(Destination.recipe(id:recipeID)) } 案例“配方编辑”：如果让 id = url.queryItems?["id"], 让recipeID = Int(id) { // 导航到菜谱，然后进行编辑 path.append(Destination.recipe(id:recipeID)) path.append(Destination.recipeEdit(id:recipeID)) } 案例“重置”： path = NavigationPath() // 弹出到根目录默认： print("⚠️ 未知的调试 URL: \(url)") } } #endif } 结构ContentView：视图{ @StateObject private var router = DebugRouter() var body: 一些视图 { NavigationStack(路径: $router.path) { 主页视图() .navigationDestination(for: Destination.self) { 目的地目的地视图（对于：目的地） } } #如果调试 .onOpenURL { 网址路由器.handleDebugURL(url) } #endif } @ViewBuilder 私人功能目的地视图（目的地：目的地）->一些视图{ 切换目的地{ 案例.设置：设置视图() 案例.recipe(let id): RecipeDetailView(recipeID: id) 案例.recipeEdit（让id）： RecipeEditView(recipeID: id) } } } 枚举目的地：Hashable { 案例设置案例配方(id: Int) 案例配方编辑(id: Int) } **用法**： # 导航至设置 xcrun simctl openurl 启动“debug://settings” # 导航到食谱#42 xcrun simctl openurl 启动“debug://recipe?id=42” # 导航到菜谱 #42 编辑屏幕 xcrun simctl openurl 启动“debug://recipe-edit?id=42” # 弹出到根目录 xcrun simctl openurl 启动“debug://reset” ** ** ### 模式 3：状态配置链接导航和配置状态的调试链接。 #如果调试扩展调试路由器 { func handleDebugURL(_ url: URL) { 保护 url.scheme == "调试" else { return } 切换 url.host { 案例“登录”： // 显示登录屏幕路径.append(目的地.登录) 案例“登录错误”： // 显示带有错误状态的登录屏幕路径.append(目的地.登录) // 触发错误状态通知中心.default.post( 名称：.showLoginError，对象：“凭据无效” ）案例“配方为空”： // 在空状态下显示菜谱列表 UserDefaults.standard.set(true, forKey: "debug_emptyRecipeList") 路径.追加（目的地.食谱）案例“配方错误”： // 显示网络错误的菜谱列表 UserDefaults.standard.set(true, forKey: "debug_networkError") 路径.追加（目的地.食谱）默认： print("⚠️ 未知的调试 URL: \(url)") } } } #endif **用法**： # 测试登录错误状态 xcrun simctl openurl 启动“debug://login-error” # 测试空食谱列表 xcrun simctl openurl 启动“debug://recipe-empty” # 测试网络错误处理 xcrun simctl openurl 启动“debug://recipe-error” ** ** ### 模式 4：Info.plist 配置（仅限调试）仅在调试版本中注册调试 URL 方案。 **第1步**：将方案添加到Info.plist CFBundleURLTypes <数组> <字典> CFBundleURLSchemes <数组> <字符串>调试 CFBundleURLName <字符串>com.example.debug **第 2 步**：从发布版本中剥离将运行脚本阶段添加到目标的构建阶段（在“复制捆绑资源”之前运行）： # 从发布版本中删除调试 URL 方案 if [ "${CONFIGURATION}" = "发布" ];那么 echo "从 Info.plist 中删除调试 URL 方案" /usr/libexec/PlistBuddy -c "删除:CFBundleURLTypes:0" "${BUILT_PRODUCTS_DIR}/${INFOPLIST_PATH}" 2>/dev/null ||真实菲 **替代**：在构建设置中使用单独的 Info.plist 文件进行调试与发布配置。 ** ** ## 与模拟器测试集成 ### 使用 `/axiom:screenshot` 命令 # 1. 导航到屏幕 xcrun simctl openurl 启动“debug://settings” # 2.等待导航睡觉 1 # 3. 截图 /公理：截图 ### 使用 `simulator-tester` 代理只需告诉代理人： *“导航至“设置”并截取屏幕截图” *“打开菜谱编辑器并验证布局” *“转到错误状态并告诉我它是什么样子” 代理将使用您的调试深层链接进行导航。 ** ** ## 强制性的第一步 **在添加调试深层链接之前，请务必完成这些步骤**： ### 第 1 步：定义导航需求列出测试所需到达的所有屏幕： - 设置屏幕 - 个人资料屏幕（带有特定的用户 ID） - 配方详细信息（带有特定配方 ID） - 错误状态（登录错误、网络错误等） - 空状态（没有食谱，没有最爱） ### 第 2 步：选择 URL 方案模式 debug://screen-name # 简单的屏幕导航 debug://screen-name?param=value # 使用参数导航 debug://state-name # 状态配置 ### 步骤 3：添加 URL 处理程序使用“#if DEBUG”确保代码从发布版本中删除。 ### 步骤 4：测试深层链接 # 启动模拟器 xcrun simctl 启动“iPhone 16 Pro” # 启动应用程序 xcrun simctl launch booted com.example.YourApp # 测试每个深层链接 xcrun simctl openurl 启动“debug://settings” xcrun simctl openurl 启动“debug://profile?id=123” ** ** ## 常见错误 ### ❌ 错误 — URL 处理程序中的硬编码导航 #如果调试 func handleDebugURL(_ url: URL) { 如果 url.host == "设置" { // ❌ 错误 — 创建紧密耦合 self.showingSettings = true } } #endif **问题**：URL 处理程序现在拥有导航逻辑，复制协调器/路由器模式。 **✅ 右 — 使用现有的导航系统**： #如果调试 func handleDebugURL(_ url: URL) { 如果 url.host == "设置" { // 使用现有的导航路径路径.追加（目标.设置） } } #endif ** ** ### ❌ 错误 — 将调试代码留在生产环境中 // ❌ 错误 — 没有 #if DEBUG func handleDebugURL(_ url: URL) { // 这运送给用户！ } **问题**：调试生产中公开的端点。安全风险。 **✅ 右 — 包含在 #if DEBUG** 中： #如果调试 func handleDebugURL(_ url: URL) { // 从发布版本中删除 } #endif ** ** ### ❌ 错误 — 使用查询参数而不进行验证 #如果调试案例“简介”：让 userID = Int(url.queryItems?["id"] ?? "0")！ // ❌ 强制展开 path.append(Destination.profile(id: userID)) #endif **问题**：如果“id”丢失或无效，则会崩溃。 **✅ 正确 — 验证参数**： #如果调试案例“简介”： Guard 让 idString = url.queryItems?["id"], 让 userID = Int(idString) else { print("⚠️ 无效的个人资料 ID") 返回 } path.append(Destination.profile(id: userID)) #endif ** ** ## 测试清单在自动化工作流程中使用调试深层链接之前： * URL 处理程序包含在 `#if DEBUG` 中 * 所有深层链接均在模拟器中手动测试 * 参数已验证（不要强制解包） * 深层链接与现有导航集成（不重复逻辑） * 从发布版本中删除 URL 方案（脚本或单独的 Info.plist） * 记录在自述文件或其他开发人员的评论中 * 与 `/axiom:screenshot` 命令一起使用 * 与“模拟器测试器”代理一起使用 ** ** ## 现实世界的例子 **场景**：您正在编辑器屏幕中调试菜谱应用程序布局问题。 **之前**（手动测试）： 1. 构建应用程序 → 30 秒 2.启动模拟器 3. 点击“食谱”→等待加载 4. 滚动到食谱 #42 5. 点击打开详细信息 6. 点击“编辑” 7. 检查布局是否固定 8. 进行更改、重建 → 从步骤 1 开始重复 **总计**：每次迭代 2-3 分钟 **之后**（带有调试深层链接）： 1. 构建应用程序 → 30 秒 2. 运行：`xcrun simctl openurl booted "debug://recipe-edit?id=42"` 3. 运行：`/axiom:screenshot` 4. 克劳德分析屏幕截图并确认布局修复 5. 根据需要进行更改，重建 → 从步骤 2 重复 **总计**：每次迭代 45 秒 **节省时间**：通过视觉验证迭代速度加快 60-75% ** ** ## 与现有导航集成 ### 对于使用 NavigationStack 的应用程序添加附加到现有 NavigationPath 的调试 URL 处理程序： router.path.append(Destination.fromDebugURL(url)) ### 对于使用协调器模式的应用程序从调试 URL 处理程序触发协调器方法： coordinator.navigate（到：.fromDebugURL（url）） ### 对于使用自定义路由的应用程序与路由器的导航 API 集成： AppRouter.shared.push(Screen.fromDebugURL(url)) **关键原则**：调试深层链接应使用现有导航，而不是替换它。 ** ** ## 高级模式 ### 模式 5：参数化状态设置 #如果调试案例“测试场景”： // 从 URL 解析复杂的测试场景 // 示例：debug://test-scenario?user=premium&recipes=empty&network=slow 如果让 userType = url.queryItems?["user"] { configureUser(type: userType) // “高级”、“免费”、“试用” } 如果让recipesState = url.queryItems?["recipes"] { configureRecipes(state:recipesState) //“空”、“满”、“错误” } 如果让 networkState = url.queryItems?["network"] { configureNetwork(state: networkState) // “快”、“慢”、“离线” } // 现在导航路径.追加（目的地.食谱） #endif **用法**： # 使用空食谱列表测试高级用户 xcrun simctl openurl 启动“debug://test-scenario?user=premium&recipes=empty” # 通过错误处理测试慢速网络 xcrun simctl openurl 启动“debug://test-scenario?network=slow&recipes=error” ** ** ### 模式 6：屏幕截图自动化助手创建一个用于设置并捕获状态的 URL： #如果调试案例“截图”： // 解析屏幕和配置 Guard let screen = url.queryItems?["screen"] else { return } // 配置状态 if let state = url.queryItems?["state"] { 应用状态（状态） } // 导航导航（到：屏幕） // 外部捕获的发布通知 DispatchQueue.main.asyncAfter(截止日期: .now() + 1.0) { 通知中心.default.post( 名称：.readyForScreenshot，对象：屏幕） } #endif **用法**： # 导航到带有错误状态的登录屏幕，等待，然后屏幕截图 xcrun simctl openurl 启动“debug://screenshot?screen=login&state=error” 睡觉2 xcrun simctl io 启动截图 login-error.png ** ** ## 相关技能 * `axiom-swiftui-nav` — 生产深度链接和 NavigationStack 模式 * `simulator-tester` — 使用调试深层链接进行自动化模拟器测试 * `axiom-xcode-debugging` — 环境优先的调试工作流程 ** ** ## 总结调试深层链接启用： * **闭环调试** 带视觉验证 * **视觉修复迭代速度加快 60-75%** * **自动化测试**，无需手动导航 * **任何应用程序状态的屏幕截图自动化** **记住**： 1. 将所有调试代码包装在`#if DEBUG`中 2. 从发布版本中删除 URL 方案 3.与现有导航集成，不重复 4. 验证所有参数（不强制解包） 5. 团队成员文件

Axiom 深度链接调试

包含技能