用途
using-xtool 是一个技能，用于在使用 xtool 构建 iOS 应用时提供指导。xtool 是跨平台的 Xcode 替代工具，基于 SwiftPM 构建 iOS 应用，支持 Linux、Windows 和 macOS。该技能适用于创建 xtool 项目、添加应用扩展或配置项目等场景。
需注意：xtool 不是 XcodeGen、Tuist 或 Xcode 工程文件。
与 XcodeGen 的区别
xtool 使用 xtool.yml，不使用 project.yml 或 Project.swift；使用 Package.swift（SwiftPM），不使用 Xcode 工程文件；主命令为 xtool dev，而非 xtool build、xtool run、xtool generate；扩展代码放在 Sources/ 目录，而非 Extensions/ 目录。
项目结构
MyApp/ 目录包含 Package.swift（SwiftPM 包定义）、xtool.yml（xtool 配置）、Sources/（含 MyApp 主应用目标和 MyWidget 扩展目标，如果有）、MyApp-Info.plist（可选自定义 Info.plist）以及 MyWidget-Info.plist（扩展必需）。
常用命令
项目生命周期：xtool new MyApp 创建新项目；xtool new MyApp --skip-setup 创建但不运行 setup；xtool dev 构建并运行（等同于 xtool dev run）；xtool dev build 仅构建；xtool dev build --ipa 构建 IPA 文件；xtool dev run -s 在 iOS 模拟器运行；xtool dev run -c release 使用 release 配置；xtool dev run -u <udid> 指定设备；xtool dev generate-xcode-project 生成 .xcodeproj 用于调试。
设备管理：xtool devices 列出已连接设备；xtool install app.ipa 安装 IPA 到设备；xtool launch 启动已安装应用；xtool uninstall 从设备卸载应用。
认证与设置：xtool setup 完整设置（认证与 SDK）；xtool auth login 使用 Apple 认证；xtool auth status 检查认证状态；xtool auth logout 登出；xtool sdk 管理 Darwin Swift SDK。
开发者服务：xtool ds teams 列出开发团队；xtool ds certificates 管理证书；xtool ds profiles 管理配置文件。
xtool.yml 格式
最小配置包含 version: 1 和 bundleID。完整配置还包括 product（指定哪个 SwiftPM 产品是主应用）、infoPath（自定义 Info.plist 并合并）、iconPath（应用图标，1024x1024 PNG）、entitlementsPath、resources（复制到应用包根目录的文件列表）以及 extensions（应用扩展列表，每项含 product 和 infoPath）。
添加应用扩展
步骤一：更新 Package.swift，同时添加 product 和 target。xtool 使用 .library（而非 .executable），它会将库打包进 iOS 应用。
步骤二：更新 xtool.yml，添加 extensions 项。
步骤三：创建扩展 Info.plist，最少只需 NSExtension 字典中的 NSExtensionPointIdentifier。
步骤四：创建扩展代码，例如 Sources/MyWidget/Widget.swift，使用 WidgetKit 和 SwiftUI 定义 WidgetBundle、Widget、TimelineEntry 和 TimelineProvider。
步骤五：运行 xtool dev 构建并运行。
常见扩展类型
Widget（WidgetKit）使用 com.apple.widgetkit-extension；Share 使用 com.apple.share-services；Action 使用 com.apple.ui-services；Safari 使用 com.apple.Safari.web-extension；键盘使用 com.apple.keyboard-service；Today（已弃用）使用 com.apple.widget-extension。
故障排查
遇到「Untrusted Developer」时，前往 设置 > 通用 > VPN 与设备管理 > 信任；设备未找到时，连接 USB、运行 xtool devices 并启用开发者模式；认证失败时，运行 xtool auth login；首次运行构建失败属正常，SDK 模块正在构建，等待完成即可。
资源与 Entitlements
SwiftPM 资源放在包子目录中，通过 .copy 声明并用 Bundle.module 访问；顶层资源通过 xtool.yml 的 resources 列表复制到应用包根目录。Entitlements 通过 xtool.yml 的 entitlementsPath 指定，并在 .entitlements 文件中以 plist 格式声明。
常见错误
不要使用 xtool build，应使用 xtool dev build；不要使用 project.yml，应使用 xtool.yml；不要使用 Extensions/ 目录，应使用 Sources/（标准 SwiftPM）；不要忘记 Package.swift，扩展需要在其中添加 product 和 target；扩展 Info.plist 不要写复杂，只需 NSExtension/NSExtensionPointIdentifier。