SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场forgerock-to-ping-journey-migration

forgerock-to-ping-journey-migration

编程与开发

查看项目

更新于 10-16 11:51

技能介绍

用途

本技能帮助开发者将现有应用从旧版 ForgeRock SDK 迁移到新版 Ping Identity Journey SDK。它适用于需要将 ForgeRock 认证代码移植到 Ping SDK 的场景，即使调用方没有使用“迁移”一词，只要表达类似意图（如“我们需要摆脱 FRAuth”“把这段改成 journey-client”“升级我们的 ForgeRock 集成需要做什么”“用新 SDK 替换 FRSession.authenticate”）即可触发。

支持的平台

  • Android (Kotlin)：旧包 org.forgerock:forgerock-auth（FRAuth/FRSession），新包 com.pingidentity.sdks:journey，参考文件 android-migration.md。
  • iOS (Swift)：旧包 ForgeRock/forgerock-ios-sdk（FRAuth/FRUser），新包 ForgeRock/ping-ios-sdk（PingJourney/PingOidc），参考文件 ios-migration.md。
  • JavaScript/TypeScript：旧包 @forgerock/javascript-sdk，新包 @forgerock/journey-client + @forgerock/oidc-client，参考文件 javascript-migration.md。

每个参考文件是完整的修改前/后映射（导入、类、方法、参数变更）。仅加载与检测到的平台匹配的文件，不要预先读取全部三个。

核心原则

  • 绝不静默删除旧代码：使用可识别的标记注释掉，便于 grep、diff 和一步回滚，也使代码审查更清晰。
  • 始终保持构建可用：如果迁移前构建已损坏，先停止并帮助修复，否则无法区分迁移后失败是否由本技能引起。
  • 遇到歧义时暂停：新旧 SDK 架构不同（回调 → 协程/async-await、静态配置 → 工厂函数、抛出异常 → Result 类型）。当转换需要会改变行为的判断时，留下 TODO(ping-migration): 并询问开发者。
  • 编辑前预览：在动手前按文件分组展示全部计划修改点。
  • 在报告中解释：最终交付物是开发者会阅读的报告，应作为一等输出，而非事后补充。

使用方式（工作流）

按顺序执行以下阶段，不得静默跳过：

  1. 检测平台：查找 Android（build.gradle、build.gradle.kts、settings.gradle*、gradle.properties、AndroidManifest.xml）、iOS（Package.swift、.xcodeproj、.xcworkspace、Podfile、Podfile.lock）、JavaScript/TypeScript（package.json 中的 @forgerock/javascript-sdk 或 @forgerock/ping-protect）。单仓库可能包含多个平台，需与开发者确认本次要迁移的目标。
  2. 收集上下文：读取项目根目录的 AGENTS.md 和 CLAUDE.md。若不存在，可提供使用 agents-template.md 创建 AGENTS.md 的选项，并根据观察填写，请开发者确认。若拒绝，则继续但要在报告中注明。
  3. 预检查构建：在改动前确认应用当前可构建。询问开发者是否要运行构建以确认干净基线。若构建失败则停止，先帮助修复预存失败。若开发者表示“相信我能构建”，接受但记录在报告中。
  4. 确定迁移范围：询问是扫描整个项目还是迁移特定区域（如单个文件、功能模块、登录流程）。尊重部分范围，若为部分迁移，先确认确切的文件/目录集合。
  5. 扫描旧用法：使用 Grep 和 Read 建立所选范围内旧 SDK 用法的清单。关键搜索锚点：
    • Android：FRSession、FRUser、FRAuth、NodeListener、FROptions、FRDeviceCollector、import org.forgerock.android、WebAuthRegistrationCallback、DeviceBindingCallback、FRListener、PingOneProtect*
    • iOS：FRAuth、FRSession、FRUser、FROptions、import FRAuth、import FRCore、WebAuthnRegistrationCallback、WebAuthnAuthenticationCallback、SelectIdPCallback、FRGoogleSignIn、FRFacebookSignIn、FRCaptchaEnterprise、Node.next { ... } 完成处理器风格
    • JavaScript：@forgerock/javascript-sdk、Config.set、FRAuth.start、FRAuth.next、FRUser.logout、UserManager.getCurrentUser、TokenManager.getTokens、TokenStorage、FRWebAuthn、CallbackType、FRCallback、FRStep、@forgerock/ping-protect 同时盘点：依赖文件（build.gradle*、Package.swift、Podfile、package.json）、清单/配置文件（AndroidManifest.xml 重定向 URI、iOS Info.plist URL scheme、JS index.html）、测试文件（常复制认证设置代码，需同步迁移）。
  6. 预览计划：在编辑前向开发者展示发现结果，结构化呈现：平台、范围、依赖变更、代码变更（按文件分组，含行号与旧 → 新映射）、需人工审查项。允许开发者编辑计划。未获批准前不进入下一阶段。
  7. 应用变更：对每个位置，注释掉旧代码并在下方插入新代码。使用标记约定：
    • Kotlin/Swift：// [ping-migration] BEGIN legacy — safe to delete after verifying the migration … // [ping-migration] END legacy
    • JavaScript/TypeScript：// [ping-migration] BEGIN legacy — safe to delete after verifying the migration … // [ping-migration] END legacy 在改动依赖文件前，检查新依赖是否已声明；若是则跳过并注明。对于 package.json（JSON 不支持注释），就地更新依赖，但在报告“依赖”部分列出移除与新增的包。遇到歧义转换时，不要猜测，插入 TODO(ping-migration): 注释解释歧义，并在聊天中询问开发者。逐文件处理以保证失败隔离。
  8. 检查后构建：询问开发者是否运行构建验证。若通过则进入下一阶段。若失败，展示错误、诊断（转换错误、缺失依赖、遗漏的清单/plist 变更或无关的预存问题）、迭代修复直至通过。绝不在构建失败时宣布迁移完成。若开发者拒绝运行构建，在报告顶部写入警告横幅：⚠️ 构建验证已跳过 — 迁移尚未确认可编译。
  9. 编写迁移报告：在项目根目录（或部分迁移子项目根目录）编写 MIGRATION_REPORT.md，使用 report-template.md 结构。必须包含：摘要（迁移平台、范围、日期、构建状态）、依赖变更、逐文件变更（路径、行号旧→新、简要描述）、人工审查项（每个 TODO(ping-migration): 及 file:line 指针）、跳过项、回滚说明（grep 命令及移除步骤）、后续步骤。报告应能独立阅读，未参与会话的审查者也能理解变更内容与原因。

构建命令

优先使用项目标准构建命令。若 AGENTS.md 指定则采用其中命令。否则：

  • Android：./gradlew assembleDebug（或 ./gradlew :app:assembleDebug）
  • iOS (SPM)：xcodebuild -scheme <scheme> -destination 'generic/platform=iOS Simulator' build
  • iOS (CocoaPods)：pod install 然后 xcodebuild -workspace <name>.xcworkspace -scheme <scheme> build
  • JavaScript：通过 package.json 检测 — npm run build、pnpm build 或 yarn build，取决于锁文件。

若项目有偏差，始终与开发者确认确切命令。iOS 的 scheme 和 destination 因项目而异，首次构建前需询问。

始终需要人工关注的事项

以下转换无法安全自动化，必须在报告中标记：

  • 错误处理形态变化：旧 SDK 抛出异常；新 SDK 返回 Result/sealed 类型。开发者常想重新思考此处 UX（重试？静默失败？登出？）。
  • 令牌存储：若旧应用将令牌写入自定义存储，新 SDK 的默认存储行为可能不同，需确认存储选择。
  • 重定向 URI：新 OIDC 客户端可能需要不同的 URI scheme，需对照清单/plist 条目与新 OIDC 客户端配置。
  • 测试夹具：Mock FRListener 实现和假 FRStep 对象无法机械转换，需针对新类型系统重写。
  • 社交/IdP 处理器：旧 FRGoogleSignIn、FRFacebookSignIn 等被替换为独立的 PingExternalIdP* 模块，应用级配置（Google Client ID、Facebook App ID）可能需要在 Ping 中重新设置。
  • 设备绑定与 FIDO：类名和流程已变（WebAuthRegistrationCallback → FidoRegistrationCallback；DeviceBindingCallback.bind(...) 签名不同）。应用前务必向开发者展示 diff。

限制与禁止事项

  • 不要在没有预览的情况下运行迁移，即使开发者着急。预览即是契约。
  • 不要直接删除旧代码。注释并替换的模式就是回滚方案。
  • 不要静默选择构建命令。与开发者确认，尤其在 iOS 上 scheme/destination 各异。
  • 若有任何阶段被跳过或任何构建失败，不要宣布成功。在报告中用平实语言说明。
  • 不要作为迁移的一部分生成 shell 或特定语言的脚本 — 开发者可能没有 Node、Python 或 Ruby。直接使用文件工具进行编辑，仅调用项目原生构建工具。

参考文件

  • android-migration.md — Android (Kotlin) 完整旧→新映射。
  • ios-migration.md — iOS (Swift) 完整旧→新映射。
  • javascript-migration.md — JavaScript/TypeScript 完整旧→新映射。
  • agents-template.md — 当项目缺少 AGENTS.md 时的生成模板。
  • report-template.md — 最终 MIGRATION_REPORT.md 的结构。

仅加载与检测到的平台相关的参考文件。迁移映射较长，不要预加载全部。