clerk-swift

Clerk Swift（原生 iOS）

此技能通过读取已安装软件包的源代码，并复现当前 ClerkKit/ClerkKitUI 的行为，在原生 Swift/iOS 项目中实现 Clerk。

激活规则

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

• 用户明确要求使用 Swift、SwiftUI、UIKit 或在原生 iOS 中实现 Clerk。
• 项目看起来是原生 iOS/Swift 项目（例如 .xcodeproj、.xcworkspace、Package.swift、Swift targets）。

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

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

如果存在 Expo/React Native 的迹象，请转到通用设置技能，而不是此技能。

需要做什么？

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

快速入门

步骤	操作
1	确认项目类型为原生 Swift/iOS，而非 Expo/React Native
2	确定流程类型（prebuilt 或 custom），并加载匹配的参考文件
3	确保存在有效的 publishable key（或向开发者询问），并将其直接配置
4	确保已安装 clerk-ios 软件包，且包含所选流程需要的产品；如果缺失，则使用 up-to-next-major 版本要求安装最新可用版本
5	检查已安装的 ClerkKitUI 源代码，确定哪些 Environment 字段会控制功能/步骤的启用
6	完成步骤 5 后，调用 /v1/environment，并且仅根据与 ClerkKitUI 对齐的字段映射进行评估
7	在已安装的 clerk-ios 软件包 README 中找到 iOS 快速入门 URL，追加 .md，然后访问并阅读该 Markdown URL，以整理必需步骤清单
8	核实并完成此项目的所有快速入门前置条件（例如关联域名和必需功能）
9	仅按照所选参考清单实现流程

决策树

User asks for Clerk in Swift/iOS
    |
    +-- Expo/React Native project detected?
    |     |
    |     +-- YES -> Do not use this skill
    |     |
    |     +-- NO -> 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
    |
    +-- Ensure publishable key and direct wiring
    |
    +-- Ensure clerk-ios is installed
    |
    +-- Inspect ClerkKitUI Environment field usage
    |
    +-- Call /v1/environment using that field map
    |
    +-- Visit/read quickstart URL from installed clerk-ios package README
    |
    +-- Verify all quickstart prerequisites are completed
    |
    +-- Implement using selected flow reference

流程参考资料

确定流程类型后，只加载一个：

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

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

交互约定

在进行任何实现修改之前，Agent 必须同时具备：

• 流程选择：prebuilt 或 custom
• 真实的 Clerk publishable key

如果用户请求/上下文中缺少任一值：

• 向用户询问缺少的值
• 暂停并等待回复
• 暂时不要修改文件或安装依赖项

仅当用户已在本次对话中明确提供相应值时，才可以跳过询问。

由源代码驱动的模板

此技能中不要硬编码实现示例。实现之前，请检查当前已安装的软件包源代码。

用例	已安装软件包中的事实来源
SDK 软件包产品、平台支持和依赖约束	ClerkKit 和 ClerkKitUI 的软件包清单与目标产品定义，以及软件包版本要求格式（up-to-next-major）
Publishable key 验证和前端 API 派生	Clerk 配置逻辑（搜索符号：configure(publishableKey、frontendApiUrl、invalidPublishableKeyFormat）
Environment 端点约定和字段语义	Environment 请求路径及请求构造，以及 ClerkKitUI 中用于启用控制的 Environment 字段用法（搜索符号：/v1/environment、Request<Clerk.Environment>、ClerkKitUI 中的 Environment 用法）
iOS 快速入门要求	已安装的 clerk-ios 软件包 README 中的快速入门链接，以及访问并阅读的快速入门页面清单步骤（包括项目设置前置条件）
原生 Sign in with Apple 实现	所选流程参考资料中的 Apple 功能和原生登录行为

执行门槛（不得跳过）

1. 满足前置条件前不得修改实现

• 在确认流程类型并获得有效、可发布的密钥之前，不得编辑项目文件。

2. 缺少流程选择或密钥时必须提问

• 如果未选择流程，必须明确询问：预构建视图还是自定义流程。
• 如果缺少可发布密钥、密钥是占位符或无效，必须明确索要真实密钥。
• 在收到这两项答复之前不得继续。

3. 必须使用可发布密钥接线模式

• 将开发者提供的可发布密钥直接写入传递给 Clerk.configure 的应用配置中。
• 除非开发者明确要求，否则不得引入 plist、本地密钥、环境文件或构建设置等间接配置方式。

4. 必须遵守软件包安装／版本策略

• 如果尚未安装 clerk-ios，请使用最新可用版本并采用 up-to-next-major 版本要求进行添加。
• 除非开发者明确要求精确锁定版本，否则不得锁定精确的软件包版本。

5. 必须检查 ClerkKitUI 的 Environment 字段

• 安装软件包后，检查已安装的 ClerkKitUI 源码，并确定所选流程中哪些 Environment 字段会影响身份验证行为。
• 在调用 /v1/environment 之前，先在 Agent 内部建立字段映射。

6. 必须调用 Environment（两种流程均适用）

• 仅在安装软件包并完成第 5 步的字段映射检查后，才能直接调用 HTTP 接口 /v1/environment。
• 使用与 ClerkKitUI 对齐的字段映射，将响应传入所选流程的参考工作流：
  • 预构建流程：据此判断是否启用了 Apple，以及是否需要更改功能配置
  • 自定义流程：仅在 Agent 内部进行完整的标准化／矩阵处理分析（绝不得在项目代码中持久化矩阵产物）

7. 必须遵守参考文件规范

• 选择流程后，实施和验证时只能遵循该流程对应的参考文件。

8. 必须遵循快速入门

• 在已安装的 clerk-ios 软件包 README 中找到 iOS 快速入门 URL，追加 .md，然后访问并阅读该 Markdown URL。
• 完成任务前，依据快速入门中的所有设置步骤检查项目。
• 如果缺少快速入门要求的设置，必须在完成任务前补齐。
• 这包括添加任何缺少的关联域条目，以及快速入门要求的其他应用功能。
• 必须明确执行快速入门步骤 Add associated domain capability（https://clerk.com/docs/ios/getting-started/quickstart#add-associated-domain-capability），并确保关联域条目符合快速入门要求（webcredentials:{YOUR_FRONTEND_API_URL}）。

9. 自定义流程的 AuthView 结构必须保持一致

• 对于 custom 流程，布局和流程结构必须与 ClerkKitUI AuthView 的默认设置基本一致。
• 如果开发者未明确要求不同的用户体验，不得对 AuthView 进行重大结构／布局偏离。
• 如果不确定自定义流程的顺序、门控条件或 Environment 的用法／语义，应以已安装的 ClerkKitUI 行为为准并加以仿照。

工作流

1. 检测项目是原生 iOS/Swift 还是 Expo/React Native。
2. 如果未明确提供流程类型，询问用户选择 prebuilt 还是 custom。
3. 如果未明确提供 publishable key，向用户索要。
4. 等待用户提供两项信息后再修改文件。
5. 加载匹配的流程参考文件。
6. 确保 publishable key 有效，并直接配置到 Clerk.configure 中。
7. 确保软件包安装和产品与所选流程匹配；新添加的软件包应遵循最新的 up-to-next-major 版本策略。
8. 检查已安装的 ClerkKitUI 源码，确定所选流程中用于门控/必需行为的 Environment 字段。
9. 调用 /v1/environment，并根据第 8 步的字段映射解读响应。
10. 从已安装的 clerk-ios 软件包 README 中查找 iOS 快速入门 URL，在末尾添加 .md，然后访问并阅读。
11. 根据访问到的 Markdown 快速入门构建检查清单，检测缺失的必需设置，并在当前项目中补齐。
12. 确保已完整应用快速入门中的关联域名功能步骤（缺少时添加 webcredentials:{YOUR_FRONTEND_API_URL}）。
13. 使用所选参考检查清单进行实现。
14. 使用所选参考检查清单和通用门控进行验证。

常见问题

级别	问题	预防措施
CRITICAL	实现前未询问缺失的流程选择	询问用户选择 prebuilt 还是 custom，并等待回复后再编辑
CRITICAL	实现前未询问缺失的 publishable key	索取密钥，并等待回复后再编辑
CRITICAL	流程类型尚未确认就开始实现	先确认流程，再加载匹配的参考文件
CRITICAL	未经请求，通过 plist/本地/环境变量间接配置 publishable key	默认直接在配置中接入密钥
CRITICAL	实现前跳过 /v1/environment 调用	对 prebuilt 和 custom 流程都始终调用环境端点
CRITICAL	安装软件包并检查 ClerkKitUI 的 Environment 字段之前，就调用 /v1/environment	先安装 clerk-ios，检查 ClerkKitUI 中 Environment 的用法，然后再调用端点
HIGH	默认安装指定版本或过时版本的 clerk-ios	如果尚未安装，使用 up-to-next-major 版本要求安装最新可用版本
CRITICAL	跳过快速入门前置条件审核	访问并阅读已安装的 clerk-ios 软件包 README 中的快速入门 URL，并确认所有必需设置步骤均已完成
CRITICAL	检测到缺少快速入门要求的功能/域名，却未予以补齐	完成前添加所有缺失的必需快速入门功能和关联域名
CRITICAL	跳过快速入门中的关联域名功能步骤	执行快速入门中的 Add associated domain capability，并确保已添加 webcredentials:{YOUR_FRONTEND_API_URL}
CRITICAL	将功能/必需字段矩阵写入应用代码	将矩阵保留在 Agent 内部，只在 UI/身份验证流程代码中应用由此得出的行为
CRITICAL	未经明确请求，自定义流程的布局偏离 AuthView	默认让自定义屏幕在结构和步骤组成上与 AuthView 保持实质相近
CRITICAL	将自定义身份验证流程压缩为一个包含所有字段的屏幕	遵循 AuthView 风格的多步骤进程，并按步骤收集字段
CRITICAL	不确定时凭猜测决定自定义流程的顺序、门控或 Environment 用法	参考已安装的 ClerkKitUI 行为，并在最终实现中保持一致
HIGH	将此技能用于 Expo/React Native	在实现前检测并改用其他方案

另请参阅

• clerk 技能，用于顶层 Clerk 路由
• clerk-setup 技能，用于非原生或跨框架设置
• 已安装的 clerk-ios 软件包 README.md（当前 iOS 快速入门链接的来源）
• https://github.com/clerk/clerk-ios