哪些直接用，哪些需要额外接入

当前使用本地 Maven。我们执行 ./gradlew bundleLocalMavenRepository，将 build/distributions/risk-control-0.1.0-maven.zip 解压后的 risk-control-maven/ 给业务；本机也可直接引用 build/repository/。

// 业务 settings.gradle.kts：加入现有依赖仓库
dependencyResolutionManagement {
    repositories {
        maven { url = uri("/实际路径/risk-control-maven") }
        google()
        mavenCentral()
    }
}

首次构建仍需访问 Google / Maven 的第三方依赖仓库。SDK 是 AAR；插件是独立 Maven 产物，两者可放同一仓库。业务只使用 SDK 时，无需引入风控插件。

仅影响签名和内容两项。插件 ID 为 com.remax.riskcontrol.content-signature，配置块为 riskContentSignature；SDK 与插件需配套更新，并重新构建应用。在 settings.gradle.kts 文件开头的现有 pluginManagement.repositories 加入插件仓库：

pluginManagement {
    repositories {
        maven { url = uri("/实际路径/risk-control-maven") }
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

在宿主 App 模块的 app/build.gradle.kts 中：

plugins {
    // 保留原有 Android / Kotlin 插件。
    id("com.remax.riskcontrol.content-signature") version "0.1.0"
}

riskContentSignature {
    contentEnabled.set(true) // 只开启内容基准，签名默认 false。
}

两个开关默认关闭，可独立开启

上方示例显式开启内容校验；只应用插件、不写配置块时，两项都关闭。Demo 为验证功能显式开启两项，不代表默认值。

表中自动扫描行为以业务未传显式基准为前提。插件只在构建机运行，不会在 App 内常驻运行；其他本地检测仍按所选项目执行。

扫描回调与直接调用的区别

• selected 是候选集合。关闭且没有显式基准的签名 / 内容项目不触发 onResult，也不出现在 onComplete 的结果 Map 中；不要固定等待 12 个结果。
• 所选项目全被跳过时，仍在工作线程调用一次 onComplete(emptyMap())。
• 通过 ScanConfig(signature = ..., content = ...) 提供显式基准，即使插件未开启也会执行对应检测。useGeneratedBaselines = false 时，这两项仅使用显式基准。
• 已开启但基准缺失、损坏或不可读时仍执行并返回 UNKNOWN，不会静默跳过。
• 直接调用 checkSignature / checkApkContent 仍返回结果：关闭且未传显式基准时返回 UNKNOWN/no_baseline，不打开基准文件。主动调用 loadGeneratedBaselines 仍会读取文件。

如需签名基准，另开 signatureEnabled，选择一种来源：

riskContentSignature {
    contentEnabled.set(true)
    signatureEnabled.set(true)
    certificateFiles.setFrom(rootProject.file("certificates/play-app-signing.der"))
}

证书在 Play Console 的 Play 应用签名页面下载“应用签名密钥证书”，不要选上传证书；放到 CI 可读的项目路径。下载指引。自行签名分发改用 signingMode.set("buildSigning")，不要配置外部证书。

CI 按当前变体的开关选择输出目录

至少开启一项：使用插件导出的最终产物。

app/build/outputs/risk-control/<变体名>/apk/*.apk
app/build/outputs/risk-control/<变体名>/bundle/*.aab

两项都关闭：使用 AGP 原生输出目录。APK 的子目录取决于 flavor / buildType 配置。

app/build/outputs/apk/
app/build/outputs/bundle/<变体名>/*.aab

// 无 flavor 的 debug APK 示例：
app/build/outputs/apk/debug/*.apk
// dev flavor 的 release APK 示例：
app/build/outputs/apk/dev/release/*.apk

从开启切换为关闭无需 clean，新原生产物不会携带旧生成基准。双关闭后不会刷新旧的 outputs/risk-control 目录，CI 不要继续从旧导出目录取包。

内容开启时复用现有签名配置重新签署；.der 不替代上传密钥。只开签名时不执行 DEX 转换或额外重签。需要加固时先查看下方兼容说明。

旧插件 ID com.remax.riskcontrol.baseline 和配置块 riskBaseline 已被新名称替换，没有保留旧 ID 别名。插件实现坐标为 com.remax.riskcontrol:risk-control-content-signature-plugin:0.1.0。

riskContentSignature {
    onVariants {
        when (name) {
            "devDebug", "devRelease" -> {
                contentEnabled.set(true)
                signatureEnabled.set(true)
                signingMode.set("buildSigning")
                certificateFiles.setFrom(emptyList<Any>())
            }
            "prodRelease" -> {
                contentEnabled.set(true)
                signatureEnabled.set(true)
                signingMode.set("playAppSigning")
                certificateFiles.setFrom(rootProject.file("certificates/play-app-signing.der"))
            }
        }
    }
}

独立于内容与签名检测插件和本地扫描。Google 依赖已随 SDK 自动传递；业务提供项目编号、完成 Google 配置，并让后端解密验证凭证与请求绑定。

import com.remax.riskcontrol.sdk.integrity.PlayIntegrityClient

val client = PlayIntegrityClient(applicationContext, cloudProjectNumber)
client.requestPlayIntegrityToken()
    .addOnSuccessListener { result ->
        // 将 token 与 requestContext 等请求绑定信息交给业务后端验证。
        // 取得 token 不等于校验通过，SDK 不会自动请求业务后端。
    }
    .addOnFailureListener { error -> /* 本次未取得凭证 */ }

复用 client，可在主线程发起，默认 listener 在主线程回调。requestHash 由 SDK 自动生成，无需 Firebase JSON；不额外申请用户权限。

所有本地函数返回 CheckResult；子项在 findings，原因在 finding.reason，事实在 facts。CONSISTENT 是与基准一致，INCONSISTENT 是不一致。UNKNOWN 不能当作通过；特征检出也不直接认定作弊。

每个检测函数返回一个 CheckResult，独立子项放在 result.findings: List<Finding> 中。子项不是另外一个需要执行的函数；先执行所属检测，再读取结果即可。

检测参数与结果查询参数不是一回事

正常检测无需业务填写 su 路径、传感器类型或 DEX 文件名。su 路径、传感器类型来自 SDK 默认规则；DEX 文件名来自插件生成或业务手动提供的可信基准。没有内容基准时返回未知，不会拿当前安装包自行生成可信基准。动态 ID 方法的参数只用于精确取结果，不能增加检查对象。

import com.remax.riskcontrol.sdk.*

// 后台线程调用。使用 SDK 默认规则，不传路径、传感器类型或 DEX 文件名。
val session = DetectionSession(applicationContext)
val root = checkRoot(session)
val suItems = root.findingsByPrefix(FindingIds.SU_ARTIFACT_PREFIX)

val hardware = checkDeviceCapabilities(session)
val sensors = hardware.findingsByPrefix(FindingIds.SENSOR_MISSING_PREFIX)

// 内容依赖可信基准：可选插件生成，或业务手动传入。
val content = checkApkContent(session)
val dexItems = content.findingsByPrefix(FindingIds.DEX_INVENTORY_PREFIX)
// 无基准时 content.status=UNKNOWN，dexItems 可能为空；不能当作校验通过。

统一入口：FindingIds + 结果查询方法

导入 com.remax.riskcontrol.sdk.* 后即可使用。固定 ID 提供常量，动态 ID 提供生成方法和前缀常量；SDK 产生结果时也使用同一套定义。底层 Finding.id 仍为字符串，方便 JSON / 日志输出，其值和检测行为不变。

finding 只取首条；没有结果返回 null，列表查询没有结果返回空列表，均不伪造 NOT_DETECTED。需要处理重复内容校验结果时用 findingsById。此封装只针对子项 ID；包名、路径等仍是业务入参，facts / evidence 的键仍按文档读取。

固定 ID：以“无卡且 Wi-Fi”为例

import com.remax.riskcontrol.sdk.*

// 在业务后台线程执行；若使用 scanner，直接在回调中读取 result。
val result = checkSimNetwork(DetectionSession(applicationContext))
val item = result.finding(FindingIds.NO_SIM_AND_WIFI)

// 缺少子项时按未知处理，不能当作 NOT_DETECTED。
val status = item?.status ?: Status.UNKNOWN
val reason = item?.reason ?: "finding_unavailable"

when (status) {
    Status.DETECTED -> { /* 已确认无卡，且当前默认网络是 Wi-Fi */ }
    Status.NOT_DETECTED -> { /* 必要信息已知，组合条件不成立 */ }
    Status.NOT_APPLICABLE -> { /* 设备无电话能力 */ }
    Status.UNKNOWN -> { /* 信息不足，查看 reason */ }
    else -> { /* 非该子项的预期状态，按未知处理 */ }
}
// result.status 是 PRESENT / ABSENT / UNKNOWN / NOT_APPLICABLE，
// 不要用它代替 no_sim_and_wifi 的状态。

例如：result.status=ABSENT，no_sim_and_wifi=UNKNOWN，表示已确认无卡，但网络信息不足。即便顶层有明确结论，也要看自己关心的子项，不能用顶层状态代替所有子项。

动态 ID：取全部相关子项

import com.remax.riskcontrol.sdk.*

// 在后台线程调用。rootPaths 可通过 DetectionRules 自定义。
val result = checkRoot(DetectionSession(applicationContext))
val suItems = result.findingsByPrefix(FindingIds.SU_ARTIFACT_PREFIX)
val suStatus = when {
    suItems.any { it.status == Status.DETECTED } -> Status.DETECTED
    suItems.isEmpty() || suItems.any { it.status != Status.NOT_DETECTED } -> Status.UNKNOWN
    else -> Status.NOT_DETECTED
}

// 固定包名可以精确读取；它是辅助子项，不决定 Root 顶层状态。
val manager = result.finding(FindingIds.managerInstalled("com.topjohnwu.magisk"))
val managerStatus = manager?.status ?: Status.UNKNOWN

表中 SDK 方法用于精确查询时才需要传具体参数；通常直接用对应 *_PREFIX 取整组即可。实际 ID 栏的 {path}、{type}、{className}、{index}、{packageName}、{apk}、{entry} 是 JSON / 日志占位说明，不要手动拼接。例如 sensor_missing:1、qemu_file:/dev/qemu_pipe、entry_mismatch:base:classes.dex。动态子项可能有多条；内容校验同一文件也可能出现在多个检查阶段，不要默认所有 ID 都唯一，重复 ID 用 findingsById，动态家族用 findingsByPrefix，并检查每条结果。

在并发扫描回调中直接读取

import com.remax.riskcontrol.sdk.*

// 由 Activity / ViewModel 持有，生命周期结束时 scanner.close()。
val scanner = RiskScanner(applicationContext)
scanner.scan(
    selected = setOf(CheckId.SIM_NETWORK, CheckId.SIGNATURE),
    onResult = { id, result ->
        when (id) {
            CheckId.SIM_NETWORK -> {
                val item = result.finding(FindingIds.NO_SIM_AND_WIFI)
                val status = item?.status ?: Status.UNKNOWN
                // 使用 status；更新 UI 时切回主线程。
            }
            CheckId.SIGNATURE -> {
                val item = result.finding(FindingIds.SIGNATURE_MISMATCH)
                when (item?.status ?: Status.UNKNOWN) {
                    Status.CONSISTENT -> { /* 签名符合基准；包名另看 package_name_mismatch */ }
                    Status.INCONSISTENT -> { /* 签名不符合基准 */ }
                    else -> { /* 无法判断；查看 item?.reason */ }
                }
            }
            else -> Unit
        }
    },
)

12 项检测的子项清单

“参与汇总”只说明是否影响该函数的顶层 status，不代表业务必须拦截。特征 DETECTED 也不自动等于作弊。子项因配置、执行分支或读取异常可能缺失，缺失不等于否定结果。

模拟器 · checkEmulator

设备能力 · checkDeviceCapabilities

Root · checkRoot

Hook · checkHook

调试器 · checkDebugger

无障碍 · checkAccessibility

工具安装 · checkInstalledTools

VPN / 代理 · checkVpnProxy

SIM / eSIM · checkSimNetwork

安装来源 · checkInstallSource

签名 · checkSignature

内容 · checkApkContent

仅在异常时出现的诊断子项

不要假设每次都有全部子项。使用 finding / findingsById / findingsByPrefix，缺失时保留未知；必要时遍历该结果的所有 UNKNOWN 子项排查。不要把 UNKNOWN、NOT_APPLICABLE 或空列表当作“正常”。线程中断等仍可能向调用方传播；SDK 无法运行时也无法保证返回结果。

排查原因与证据

// result 是任意检测的返回值；以下只读取结果，不会再次检测。
val diagnostics = result.findings
    .filter { it.status == Status.UNKNOWN }
    .map { "${it.id}: ${it.reason}" }

val changedFiles = result.findingsByPrefix(FindingIds.ENTRY_MISMATCH_PREFIX)
    .filter { it.status == Status.INCONSISTENT }
changedFiles.forEach { item ->
    val detail = item.evidence["reason"] // 如 entry_missing；也可能为空。
    val actualDigest = item.evidence["actualSha256"]
    // 按业务需要消费证据，不要根据 reason 是否为空判断一致性。
}

当前插件没有通用的加固后基准生成适配。加固不必然让两项检测同时失效。以下结果以 SDK 仍能正常运行、相关数据可读取为前提；SDK 不会自动区分“合法加固”与“恶意修改”。

CONSISTENT 仅表示本次可检查范围内未发现不一致，不等于全包安全。内容子项包括 entry_mismatch:...、dex_inventory:...；未知原因在 findings[].reason。生成基准加载错误可用后台调用 loadGeneratedBaselines(context) 查看。汇总优先级：INCONSISTENT > UNKNOWN > CONSISTENT。

加固项目如何接入

不能在用户手机上读取当前加固包，再把它自身的摘要当可信基准。仅把插件任务移动到加固任务之后也不保证兼容；需确认产物输入、基准写入、最终签名及 AAB 分包均匹配。即使完成适配，落盘的壳 / 加密文件校验也不等于运行时解密代码或内存校验。

// 后台线程直接调用：默认查 SDK 内置工具。
val tools = checkInstalledTools(DetectionSession(applicationContext))

// 自定义名单：自动追加到内置名单（先在宿主 Manifest 配好该包名的 queries）。
val config = ScanConfig(tools = listOf(ToolTarget("com.example.tool", visibilityDeclared = true)))
// 不传或传空列表都保留内置名单；相同包名只查一次。

内容校验开启后，默认覆盖 base assets 和最终 DEX，不覆盖所有编译资源、native library 或运行时内存。可用 assetIncludes / assetExcludes 缩小 assets 范围。当前 assets + DEX 最多 64 个文件，单文件 64 MiB、合计 128 MiB。插件启用时，多 APK 输出暂不支持；内容开启时，部分动态功能交付和特殊签名重签暂不支持，构建会明确报错。两项都关闭时不施加插件的多 APK 输出限制。

默认工具查询包名：com.topjohnwu.magisk、de.robv.android.xposed.installer、org.lsposed.manager、org.autojs.autojs、org.autojs.autojs6。这些具体包名是实现时补充的初始名单；原需求文档列举了相关工具名称，并未提供这份完整包名清单，也尚未全部覆盖原文提到的工具。自定义包名需宿主声明精确 queries，再传 ToolTarget(packageName, visibilityDeclared = true)；不可见且查不到返回未知。传入名单自动与内置名单合并，按包名去重；空列表仍查内置名单。同名包采用业务传入的 visibilityDeclared，便于宿主移除 queries 时显式设为 false。Root 默认管理工具名单与 tools 参数独立。