clerk-swift

Clerk Swift（原生 iOS 和 macOS）

此技能用于在原生 Swift 项目中构建 Clerk 身份验证 UI：使用预构建的 ClerkKitUI 视图，或基于 ClerkKit 构建自定义流程。请先完成设置（SDK、功能、原生注册和 Clerk 初始化），这部分有单独的工作流。

激活规则

符合以下任一条件时，激活此技能：

• 用户明确要求使用 Swift、SwiftUI、UIKit，或实现原生 iOS 或 macOS Clerk 功能。
• 项目看起来是原生 Swift 项目（例如，包含 .xcodeproj、.xcworkspace、Package.swift 或 Swift 目标）。

符合以下任一条件时，不要激活此技能：

• 项目是 Expo。
• 项目是 React Native。

如果存在 Expo/React Native 的迹象，请改用通用设置技能。

先设置 Clerk

如果尚未设置 Clerk（没有 clerk-ios 包、没有 Clerk.configure 调用，或尚未选择 Clerk 应用），请先按照 iOS 设置提示词 完成设置，再进行任何 UI 工作。该流程会使用 Clerk CLI 选择 Clerk 应用、安装 SDK、配置功能、注册原生应用，并交接后续 Swift 集成。CLI 也会提供可发布密钥，因此不要要求用户粘贴密钥。

如果 CLI 无法设置项目（例如，Xcode 不可用或项目不受支持），请改用手动 iOS 快速入门。

如果用户已要求实现登录 UI（例如自定义流程），请在设置的构建检查通过后继续。如果用户尚未提出这类要求，则等到用户希望添加或更改登录 UI 时，再返回此技能。

你需要什么？

任务	参考资料
预构建的 AuthView / UserButton（最快）	references/prebuilt.md
由 API 驱动的自定义身份验证流程（完全控制）	references/custom.md

快速开始

步骤	操作
1	确认项目是原生 Swift 项目，而不是 Expo/React Native
2	如果尚未设置 Clerk，请先按照 iOS 设置提示词操作（见上文）
3	确定流程类型（prebuilt 或 custom）；如果尚未确定，请先询问，然后加载对应的参考资料
4	检查所选流程所需的前置条件，例如包产品或功能，并且只补上缺失的指定项
5	按照所选参考资料实现流程
6	构建目标，并报告还有哪些内容尚未验证

决策树

User asks for Clerk in Swift
    |
    +-- Expo/React Native project detected?
    |     |
    |     +-- YES -> Do not use this skill
    |     |
    |     +-- NO -> Continue
    |
    +-- Clerk set up in this project?
    |     |
    |     +-- NO -> Follow the iOS setup prompt (manual quickstart if the CLI can't)
    |     |
    |     +-- YES -> Continue
    |
    +-- Existing auth UI detected?
    |     |
    |     +-- Prebuilt views detected -> Load references/prebuilt.md
    |     |
    |     +-- Custom flow detected -> Load references/custom.md
    |     |
    |     +-- New implementation -> Ask developer prebuilt/custom, then load matching reference
    |
    +-- Make targeted prerequisite changes for the selected flow
    |
    +-- Implement using selected flow reference

流程参考资料

确定流程类型后，只加载一份参考资料：

• 预构建流程：references/prebuilt.md
• 自定义流程：references/custom.md

除非开发者明确要求混合方案，否则不要在同一实现中混用这两份参考资料。

交互约定

开始编辑 UI 前，Agent 必须确定流程选项：prebuilt 或 custom。如果尚未确定，请询问用户并等待答复。只有当用户已在本次对话中选择，或现有 UI 已明确表明选项时，才可跳过询问。

保留已完成的设置

• 保留现有的 Clerk.configure 调用，以及应用加载可发布密钥的方式，包括通过 plist、构建设置或其他自定义方式加载密钥。不要将其替换为硬编码密钥。
• 保留现有的软件包要求、功能和权利文件。仅添加所选流程需要且尚缺少的内容。
• 如需在不做任何更改的情况下检查 Clerk 和项目设置，请运行 npx -y clerk@latest doctor。该命令会报告 SDK 链接、功能、原生注册和 Apple 连接情况。

基于源码的实现

使用已安装的 clerk-ios 包源码作为 UI 行为的参考，尤其是自定义流程。

用例	已安装包中的事实来源
SDK 产品、平台支持和依赖约束	ClerkKit 和 ClerkKitUI 的包清单及目标产品定义
认证流程顺序和门控	ClerkKitUI 的 AuthView 实现，以及它如何读取注入的 Clerk 实例的 environment
原生 Apple 登录	所选流程参考中的 Apple 登录行为

工作流

1. 检测使用的是原生 Swift 还是 Expo/React Native。
2. 如果尚未配置 Clerk，请遵循 iOS 设置提示（如果 CLI 无法设置项目，则使用手动快速入门），然后继续。
3. 如果尚不清楚流程类型，请询问使用 prebuilt 还是 custom。
4. 加载相应的流程参考。
5. 检查该流程的前置条件，仅进行缺少的针对性更改，并保留已完成的设置和自定义密钥加载方式。
6. 使用所选参考进行实现。
7. 使用所选参考进行验证，然后构建目标。

常见问题

级别	问题	预防措施
CRITICAL	Clerk 尚未配置时手动完成设置	遵循 iOS 设置提示；它会运行 Clerk CLI。只有在 CLI 无法设置项目时才使用手动快速入门
CRITICAL	要求用户粘贴可发布密钥	CLI 会在设置过程中提供密钥；保留现有应用自己的密钥加载方式
CRITICAL	替换自定义密钥加载方式或现有设置	保留现有的 Clerk.configure、包和功能；只添加缺少的内容
CRITICAL	尚未确认流程类型就开始实现 UI	先确认流程，再加载相应的参考
CRITICAL	未经明确要求，自定义流程布局偏离 AuthView	默认让自定义屏幕在整体结构和步骤编排上与 AuthView 基本一致
CRITICAL	将自定义认证简化为包含所有字段的单一屏幕	遵循 AuthView 风格的多步骤流程，并按步骤收集字段
CRITICAL	不确定时臆测自定义流程的顺序或门控方式	参考已安装的 ClerkKitUI 行为并与之保持一致
HIGH	在自定义流程代码中硬编码此实例的当前设置	像 AuthView 一样，在运行时根据注入的 Clerk 实例的 environment 设置步骤门控
HIGH	将此技能用于 Expo/React Native	在实现前检测并转交给其他流程

另请参阅

• iOS 设置提示，用于通过 Clerk CLI 设置 Clerk
• 用于顶层 Clerk 路由的 clerk 技能
• 用于非原生或跨框架设置的 clerk-setup 技能
• https://github.com/clerk/clerk-ios