clerk-android

Clerk Android（原生）

此技能通过遵循当前的 clerk-android SDK 和文档模式，在原生 Android 项目中集成 Clerk。

激活规则

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

• 用户明确要求在 Android 上使用 Android、Kotlin、Jetpack Compose 或原生移动版 Clerk。
• 项目看起来是原生 Android 项目（例如包含使用 Android 插件的 build.gradle(.kts)、AndroidManifest.xml、app/src/main/java 或 Compose UI 文件）。

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

• 项目使用 Expo。
• 项目使用 React Native。

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

你需要什么？

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

快速开始

步骤	操作
1	确认项目是原生 Android 项目，而不是 Expo/React Native 项目
2	确定流程类型（prebuilt 或 custom），并加载相应的参考文件
3	确保有真实的 Clerk 可发布密钥（或向开发者询问）
4	确保已为所选流程安装正确的 Clerk 构件
5	阅读官方 Android 快速入门，并核实所需设置（Native API、最低 SDK/Java 版本、清单、初始化）
6	检查与所选流程相关的 clerk-android 源码/示例模式
7	仅按照所选参考文件中的检查清单实现流程

决策树

User asks for Clerk in Android/Kotlin
    |
    +-- 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 SDK initialization path
    |
    +-- Ensure correct Android artifacts are installed
    |
    +-- Verify quickstart prerequisites in project
    |
    +-- Implement using selected flow reference

流程参考

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

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

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

交互约定

开始进行任何实现修改前，Agent 必须同时确认：

• 流程选择：prebuilt 或 custom
• 真实的 Clerk 可发布密钥

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

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

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

基于源码的模板

此技能中不要硬编码实现示例。实现前，请检查与已安装 SDK 版本对应的当前 clerk-android 源码/文档。

使用场景	信息来源
SDK 构件及依赖拆分（clerk-android-api 与 clerk-android-ui）	clerk-android README 和 Android 安装文档
SDK 初始化及可发布密钥配置	Android 快速入门和 source/api/.../Clerk.kt
预构建身份验证和个人资料行为	source/ui/.../AuthView.kt、source/ui/.../UserButton.kt 和预构建示例
自定义身份验证步骤及验证因素处理	source/ui/auth/*、source/api/auth/* 和自定义流程示例
根据实例设置进行能力/功能门控	Clerk 公共字段（例如 enabledFirstFactorAttributes、socialProviders、isGoogleOneTapEnabled、mfaIsEnabled）以及环境模型源码
Android 必需设置检查清单	官方 Android 快速入门（/docs/android/getting-started/quickstart）

执行门禁（不得跳过）

1. 完成前置要求前不得修改实现

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

2. 缺少流程类型或密钥时必须提问

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

3. 必须明确可发布密钥的接入方式

• 默认在 Clerk.initialize(...) 中直接接入开发者提供的密钥。
• 除非用户明确要求，否则不要引入间接的密钥管理机制。

4. 必须遵循依赖包安装策略

• 预构建流程：使用 clerk-android-ui（包含 API）。
• 自定义流程：使用 clerk-android-api，除非用户明确要求使用预构建组件。
• 如果缺少 Clerk 依赖包，请添加最新的稳定版本。

5. 必须符合 Android 快速入门要求

• 确认已为 Clerk 应用启用 Native API。
• 确认项目已实现 Android 快速入门中的要求（最低 SDK 和 Java 目标版本、Manifest 中的 Internet 权限、应用级 Clerk 初始化）。
• 确认应用会等待 SDK 初始化（Clerk.isInitialized），再将身份验证状态视为就绪。

6. 必须根据能力驱动行为

• 使用 Clerk 运行时能力／设置状态（例如已启用的验证因素、社交提供商、MFA 标志）来控制流程行为。
• 不要硬编码可能与控制面板配置冲突的验证因素假设。

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

• 选定流程后，只能依据该流程的参考文件进行实现和验证。

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

• 对于 custom 流程，保留多步骤身份验证进程和针对不同验证因素的处理方式（默认不得使用包含所有字段的单一表单）。
• 将 UI、状态编排和 Clerk API 集成拆分到不同模块中。

9. 选用预构建流程时必须优先使用预构建组件

• 对于 prebuilt 流程，除非用户明确要求，否则不要通过自定义 API 调用重新构建身份验证表单。
• 默认使用 AuthView/UserButton 作为构建模块。

工作流

1. 检测项目使用的是原生 Android，还是 Expo/React Native。
2. 如果未明确提供流程类型，请询问用户选择 prebuilt 或 custom。
3. 如果未明确提供可发布密钥，请向用户索要。
4. 在获得这两项答复之前，不要修改文件。
5. 加载匹配的流程参考文件。
6. 确保 Clerk.initialize(...) 调用路径和可发布密钥接入方式有效。
7. 确保依赖项／依赖包与所选流程相匹配。
8. 检查 Android 快速入门要求，并在项目中补齐缺失的配置。
9. 按照所选参考清单进行实现。
10. 按照所选参考清单和通用门禁进行验证。

常见问题

级别	问题	预防措施
CRITICAL	实现前未询问缺失的流程类型	询问用户选择 prebuilt 还是 custom，并在修改前等待答复
CRITICAL	实现前未索要缺失的可发布密钥	索要密钥，并在修改前等待答复
CRITICAL	尚未确认流程类型就开始实现	先确认流程，再加载匹配的参考文件
CRITICAL	跳过 Android 快速入门的前置要求	根据官方 Android 快速入门核实并应用所需配置
CRITICAL	缺少应用级 Clerk.initialize(...) 调用	在 Application 启动路径中初始化 Clerk
HIGH	所选流程使用了错误的依赖包	预构建：clerk-android-ui；自定义：clerk-android-api
HIGH	SDK 初始化完成前就显示身份验证 UI	根据 Clerk.isInitialized 状态控制 UI
HIGH	将身份验证因素／社交提供商硬编码	根据 Clerk 运行时能力字段来驱动行为
HIGH	将此技能用于 Expo/React Native	实现前先检测并改用其他流程

另请参阅

• clerk 技能，用于顶层 Clerk 路由
• clerk-setup 技能，用于跨框架快速入门设置
• https://github.com/clerk/clerk-android
• https://clerk.com/docs/android/getting-started/quickstart