用途
本技能用于在构建 SwiftUI 应用时，保持 Swift 端指导与 Convex 后端指导的一致性。它面向使用 Convex 作为后端、Clerk 作为认证的 SwiftUI 应用开发场景，覆盖响应式订阅、TypeScript 服务端函数、schema 设计等内容。技能通过仓库内 references 文档提供从选型、安装、后端设计、客户端消费到平台适配、测试与部署的完整指引。
主要能力
技能按主题组织为多个 references 文档集合：
- 入门（onboarding）：判断 Convex 是否适合产品、Convex 与 Firebase/Supabase 对比、心智模型、采用检查清单与硬性停止条件。
- 安装（setup）：Node.js/npm/Convex CLI 安装、Xcode SPM 配置（ClerkKit、ClerkConvex、ConvexMobile）、Clerk 账户与 JWT 模板、连接 Clerk 到 Convex 认证配置、首次运行 npx convex dev。
- 后端（backend）：schema 与关系、索引与查询性能、查询/变更/动作与调度、认证规则与服务端所有权、内部函数与 helpers、intent+schedule 模式、结构化错误 ConvexError、文件组织与命名。
- 客户端 SDK（client-sdk）：客户端接口与认证桥、类型系统与线格式、订阅/错误/日志/连接状态、管道终止与恢复、WebSocket 状态与连接横幅、调试日志、参数编码 ConvexEncodable。
- SwiftUI：消费模式、观察与所有权、生命周期/导航/Tab/Sheet、环境注入与根架构、导航栈订阅生命周期、TabView 与 Sheet 模式、加载/错误/数据三态模式。
- 认证（authentication）：Clerk 优先设置、自定义认证提供者与 Firebase 回退、Sign in with Apple/Keychain/会话恢复。
- 平台（platforms）：iOS 后台/重连/陈旧数据、离线行为与网络切换恢复、性能/电池/线程、macOS 多窗口/菜单栏/支持限制、NWPathMonitor、二进制体积与 Instruments 分析、macOS 每窗口 ViewModel 陷阱。
- 进阶（advanced）：分页与实时尾部、文件存储上传下载、测试调试与可观测性、流式工作负载与转录、图片上传、全文搜索、订阅去重与扇出、Convex 组件生态。
- 陷阱（pitfalls）：管道首次错误后死亡、忘记主线程接收、无界 collect、数组字段 8192 限制、查询中使用 Date.now()、直接调用 action 处理副作用、信任客户端授权、@Observable 宏重初始化陷阱、.task 修饰符导航取消、无离线无乐观更新。
- 演练（walkthrough）：从零到实时聊天应用的完整示例，含 schema、后端代码、Swift 模型与 ViewModel、SwiftUI 视图、部署检查清单。
- 速查（quick-reference）：后端模式速查卡、Swift SDK API 速查、SQL 到 Convex 映射表、函数决策树、订阅放置决策矩阵。
- 测试（testing）：mock FFI 客户端单元测试、测试部署集成测试、SwiftUI 预览 mock 客户端、OSLog 与 Console.app 过滤、convex-test 服务端测试。
- 操作手册（playbooks）：全新 SwiftUI 应用构建顺序、iOS/macOS 共享应用、流式与转录构建顺序。
- 操作（operations）：已验证修正与信任边界、已知缺口/限制/非目标。
使用方式
技能以文档阅读与工作流指引形式使用。典型工作流包括：先判断 Convex 是否适合产品，再按安装步骤配置环境；重置心智模型后锁定认证与根所有权；先设计后端再连接 UI；设计客户端消费与所有权；按任务加载对应平台与进阶文档；回答前阅读操作文档并说明相关限制。
默认立场包括：优先使用 Clerk 作为 Swift 认证路径，使用官方 ClerkConvex 包（clerk-convex-swift >= 0.1.0）配合 clerk-ios >= 1.0.0 与 convex-swift >= 0.8.0；每个进程优先使用一个 @MainActor 长生命周期已认证客户端，通过 ConvexClientWithAuth(deploymentUrl:authProvider: ClerkConvexAuthProvider()) 创建；订阅持有模型优先使用 ObservableObject 加 @StateObject；将 tokenIdentifier 作为服务端所有权规范键，通过 convex-helpers 的 userQuery/userMutation 包装器强制执行；使用 ClerkKitUI 的 AuthView() 与 UserButton() 进行交互式登录与用户管理，不构建手动 client.login() 流程；将官方 WorkoutTracker 示例作为小应用基线；在根视图添加 .prefetchClerkImages() 与 .environment(Clerk.shared)；将订阅视为有界实时读取；将 iOS 视为重连在线而非离线优先；macOS 支持仅限 Apple Silicon；最低目标 iOS 17+ / macOS 14+。
硬性规则包括：当离线优先、SQL 重度、不支持平台或 Intel macOS 是真实阻碍时，不推荐 Convex 作为默认；不承诺乐观更新、原生离线持久化、Catalyst/watchOS/tvOS/visionOS 支持；不使用客户端传入的 userId 做授权设计；不将 .filter() 或无界 .collect() 作为常规后端查询策略；不在 Convex 查询中使用 Date.now()；不在单个文档中存储无界增长数组；不为重要共享实时数据推荐长生命周期视图 .task 所有权；不假设终端失败后订阅可恢复；不重复陈旧或已修正的声明。
适用场景
适用于正在构建 SwiftUI 应用并选择 Convex 作为后端、Clerk 作为认证的开发者，尤其是 SwiftUI 熟练但后端较新的开发者。也适用于需要了解 Convex 与 SwiftUI 集成细节、平台适配、性能优化、常见陷阱与测试部署的团队。
限制
技能明确列出非目标与已知缺口，具体内容见 references/operations/02-known-gaps-limitations-and-non-goals.md。不承诺乐观更新、原生离线持久化、Catalyst、watchOS、tvOS、visionOS 支持。macOS 支持仅限 Apple Silicon。最低目标 iOS 17+ / macOS 14+。其他具体限制暂未提供。