axiom-watchos

watchOS 开发

对于任何 watchOS 特定开发，包括应用结构、独立应用、Watch Connectivity、复杂功能和 Smart Stack 小组件、控制项、在手表上的 Live Activities、后台任务以及 ClockKit 迁移，都必须使用此技能。

无法启动 Axiom Agent？ 如果此路由将你引导至某个 Agent，请直接按其流程操作。通过 MCP，axiom_get_agent 会返回相应内容；在其他环境中，请读取下方对应的文件，只需使用文件搜索和读取功能即可。

位于另一个套件中：axiom-build/skills/modernization-helper.md。

对于任何其他 Agent，通过 MCP，axiom_get_agent 也会返回相应内容；请使用 axiom_xclog_*、axiom_xcsym_* 和 axiom_xcprof_* 工具执行其 xclog、xcsym 和 xcprof 步骤。在其他环境中，请在 Axiom 的技能中搜索 skills/<agent>.md；如果没有该文件，请使用此套件的技能自行完成相关工作，并使用 PATH 中的任何 Axiom 工具。

快速参考

症状 / 任务	参考
应用结构、独立应用、watchOS 26 提交要求	参见 skills/platform-basics.md
watchOS HIG、一目了然的用户体验、导航模型	参见 skills/design-for-watchos.md
Smart Stack 小组件、复杂功能、ClockKit→WidgetKit、RelevanceKit	参见 skills/smart-stack-and-complications.md
手表界面上的控制项、手表上的 Live Activities	参见 skills/controls-and-live-activities.md
Watch Connectivity（WCSession）、配对设备间的数据传输、家庭设置	参见 skills/watch-connectivity.md
Xcode 无法在手表上安装、启动或附加；设备中心 / devicectl 中缺少手表或显示为 unavailable	参见 skills/watch-device-diag.md
后台任务、新鲜度调度、TN3135 网络限制	参见 skills/background-and-networking.md
BGTaskScheduler 迁移、已弃用的 WK 后台调度 OS27	参见 skills/background-and-networking.md
手表上的 Foundation Models / Private Cloud Compute OS27	参见 skills/platform-basics.md
WatchKit→SwiftUI 迁移、ClockKit→WidgetKit 迁移	参见 skills/modernization.md

跨套件路由

这些主题与 watchOS 开发相关，但归属其他套件：

SwiftUI（iOS/watchOS/macOS 通用）

• 视图状态、数据流、@Observable → 参见 axiom-swiftui
• 导航基础（NavigationStack）→ 参见 axiom-swiftui
• 布局、动画 → 参见 axiom-swiftui

设计

• 通用 HIG、Liquid Glass、SF Symbols、排版 → 参见 axiom-design

辅助功能

• 通用 VoiceOver、动态字体、WCAG → 参见 axiom-accessibility
• watchOS 特定功能（Digital Crown 上的 VoiceOver 转子、AssistiveTouch、轻点两下）→ 参见 axiom-accessibility（skills/watchos-a11y.md）

健康与锻炼

• HealthKit、HKWorkoutSession、HKLiveWorkoutBuilder、WorkoutKit → 参见 axiom-health
• 锻炼恢复、多设备协同 → 参见 axiom-health（skills/workouts.md）

iOS 端小组件和 App Intents

• iOS/iPadOS 小组件、配置意图、App Intents → 参见 axiom-integration
• iPhone 上的 Live Activities（启动 + ActivityKit）→ 参见 axiom-integration

并发

• Swift 6 并发、Actor、Sendable → 参见 axiom-concurrency

手表上的新框架（27 版本）

• Foundation Models 深入内容（会话、@Generable、工具、PCC）→ 参见 axiom-ai；手表端范围说明见 skills/platform-basics.md
• Vision 框架（watchOS 27 新增）→ 参见 axiom-vision
• NowPlaying / MusicUnderstanding（watchOS 27 新增）→ 参见 axiom-media

冲突解决

axiom-watchos 与 axiom-swiftui：构建 watchOS SwiftUI 应用时：

1. 使用 axiom-watchos 处理手表专属模式：一目了然的 UI、受限导航、Digital Crown 焦点、Smart Stack 位置
2. 使用 axiom-swiftui 处理跨平台 SwiftUI：状态管理、布局原语、动画
3. 两者都可能适用：带有复杂功能的 watchOS NavigationStack 需要使用 axiom-watchos 处理复杂功能界面，并使用 axiom-swiftui 处理 NavigationStack 基础知识

axiom-watchos 与 axiom-integration：处理小组件和实时活动时：

1. 使用 axiom-watchos 处理手表复杂功能、Smart Stack 位置、手表端实时活动呈现、RelevanceKit
2. 使用 axiom-integration 处理 iOS/iPadOS 小组件、核心 ActivityKit API、App Intents

watch-device-diag 与 watch-connectivity：两种独立连接发生故障时，表现可能完全相同。编写任何代码前，先确定是哪一种：

1. 使用 watch-device-diag 处理 Mac/Xcode → Watch 链路（CoreDevice）：安装、启动、LLDB 附加、Watch 缺失或显示为 unavailable
2. 使用 watch-connectivity 处理 iPhone 应用 ↔ watchOS 应用链路（WCSession）：传输 API 选择、交付语义、后台任务完成
3. 不确定时，从 watch-device-diag 开始。 不附加调试器运行应用——如果运行正常，问题就在隧道，修改 WCSession 无济于事。在 watchOS 开发中，为弥补调试器隧道故障而重新设计 WCSession，是代价最高的错误
4. isReachable == false 并非传输故障——这是普通生命周期转换期间的预期值，应转向 watch-connectivity，而非此处

axiom-watchos 与 axiom-health：在 Apple Watch 上处理锻炼时：

1. 使用 axiom-watchos 处理手表专属呈现：常亮显示、Smart Stack 位置、后台模式协调
2. 使用 axiom-health 处理 HKWorkoutSession 生命周期、HKLiveWorkoutBuilder、恢复、多设备镜像

决策树

digraph watchos {
    start [label="watchOS development task" shape=ellipse];
    what [label="What area?" shape=diamond];

    start -> what;
    what -> "skills/platform-basics.md" [label="app structure, independent apps, submission"];
    what -> "skills/design-for-watchos.md" [label="watch HIG, glanceable UX"];
    what -> "skills/smart-stack-and-complications.md" [label="complications, Smart Stack, RelevanceKit"];
    what -> "skills/controls-and-live-activities.md" [label="controls, watch Live Activities"];
    what -> "skills/watch-connectivity.md" [label="WCSession, paired-device transfer"];
    what -> "skills/watch-device-diag.md" [label="Xcode can't reach the Watch"];
    what -> "skills/background-and-networking.md" [label="background tasks, BGTaskScheduler, networking limits"];
    what -> "skills/platform-basics.md" [label="Foundation Models / PCC on watch"];
    what -> "skills/modernization.md" [label="WatchKit/ClockKit migration"];
    what -> "axiom-health" [label="workouts, HealthKit, WorkoutKit"];
    what -> "axiom-swiftui" [label="general SwiftUI patterns"];
    what -> "axiom-accessibility" [label="VoiceOver rotor, AssistiveTouch"];
    what -> "axiom-integration" [label="iOS-side widgets, App Intents"];
}

资源

WWDC：2021-10003、2022-10133、2023-10138、2023-10029、2023-10309、2024-10098、2024-10157、2024-10205、2025-334

文档：/watchos-apps/building_a_watchos_app、/watchos-apps/creating-independent-watchos-apps、/watchconnectivity、/widgetkit/creating-accessory-widgets-and-watch-complications、/widgetkit/converting-a-clockkit-app、/relevancekit、/technotes/tn3135-low-level-networking-on-watchos、/technotes/tn3157-updating-your-watchos-project-for-swiftui-and-widgetkit

技能：axiom-swiftui、axiom-design、axiom-accessibility、axiom-health、axiom-integration、axiom-concurrency、axiom-ai、axiom-vision、axiom-media