参与开发

suqi82026/3/21...大约 14 分钟指南开发架构HookDexKitYukiHookAPIKavaRef

参与 OShin 开发

这篇文档写给准备直接动手改 OShin 的开发者与维护者。

它不是仓库观光手册，也不是旧版单体 app 时代的补丁说明。更实际的目标是让你在开始改代码前，先把下面几件事理顺：

这个项目现在的真实结构是什么
App 进程和 Hook 进程分别怎么启动
一个功能页是怎么从声明一路渲染到界面的
一个 Hook 是怎么从入口一路注册到目标进程的
什么时候该用 YukiHookAPI
什么时候该用 KavaRef
什么时候必须上 DexKit
项目里已经有 DexKitCacheManager 时，为什么不应该再到处手写 DexKitBridge.create(...)

如果你以前看过旧版文档，先把“所有代码都在 app 模块里”这个印象清掉。当前项目已经完成模块化，下面所有内容都以当前仓库的真实结构为准。

Contributor Mode

先选你的当前目标

这页内容很长，但参与开发不需要从头背到尾。先明确自己当前在改什么，再进入对应章节，效率会高很多。

我要改页面

先看这些章节

§5 Feature 页面系统§6 新功能页§17 页面、设置、Hook 对齐§18 搜索系统

先碰这些文件

feature-catalog/.../FeatureRegistry.kt
app/.../FeatureViewModel.kt
app/.../FeatureScreen.kt
core-data/.../FeatureRepository.kt

先避开这些误区

只写了 PageDefinition，但没注册到 FeatureRegistry
category / key 和 Hook 读取键对不上
页面资源塞进了错误模块，后续维护成本变高

1. 先建立整体认识

OShin 同时是两个东西：

一个 Android 应用，用来提供设置界面、更新、欢迎引导、搜索和一些工具能力
一个 Xposed / LSPosed 模块，用来在目标系统或目标应用进程中执行 Hook

这两个部分打包在同一个最终 APK 里，但开发时要分开理解。

可以先从下面两个运行世界理解整个项目：

世界 A：App 世界
用户点击桌面图标
-> DefaultApplication
-> MainActivity
-> AppNavHost
-> Main / Welcome / Feature / Update 等 Compose 页面

世界 B：Hook 世界
LSPosed 加载模块
-> xposed_init
-> YukiHookAPI 生成的入口类
-> HookEntry
-> 各个 YukiBaseHooker
-> 目标系统进程 / 目标应用进程

Development Explorer

从三个视角理解 OShin

同一套代码同时服务 App 世界与 Hook 世界。这里把最容易混淆的运行链路、模块职责和开发落点拆开看。

交互视图

Runtime

先区分 App 世界和 Hook 世界

多数定位错误都发生在没分清当前代码究竟运行在哪个进程。

DefaultApplication / MainActivity

App

负责应用侧初始化、导航、更新、广告和设置页面。这里看到的是用户直接打开 APK 后的行为。

xposed_init -> 生成入口 -> HookEntry

Hook

负责把 LSPosed 的加载入口桥接到项目的 Hook 体系。这里不是普通 Activity 生命周期。

YukiBaseHooker 与目标进程

Target

真正的行为修改发生在系统进程或目标应用进程内部，排查问题必须带着进程视角看。

界面、导航、广告、引导问题通常先看 App 世界。

系统行为没生效、版本兼容异常、方法找不到，先看 Hook 世界。

不要把 UI 层状态处理和目标进程 Hook 逻辑写在同一层里。

开发时最常见的工作大致分成四类：

新增或调整某个设置页面
新增或调整某个 Hook 行为
新增一个可搜索项、可导航项、可配置项
修补启动、验证、更新、资源、多语言等公共链路

2. 当前项目模块结构

当前仓库根目录下与开发直接相关的模块如下：

OShin
├─ app
├─ core-ads
├─ core-common
├─ core-data
├─ core-model
├─ core-navigation
├─ core-ui
├─ core-update
├─ feature-catalog
├─ hook-apps
└─ temp

首选模块

feature-catalogcore-model

页面目录、PageDefinition、ModuleEntry、ScreenItem 等声明层内容，应该留在功能目录和模型层，而不是直接堆到 app。

通常还会联动

app：FeatureViewModel / FeatureScreen 消费这些声明
core-data：搜索、标题解析、路由格式化会读取这些页面定义

不要优先放到

app：不要把静态页面定义重新写成页面级硬编码
hook-apps：不要把设置声明和行为修改写到一个文件里

职责

最终应用模块，负责壳、入口、导航和应用级页面组装。

典型内容

AndroidManifest.xml
DefaultApplication
MainActivity
AppNavHost
首页、模块页、欢迎引导等 Compose 页面

不要优先放进来

通用可复用组件
目标进程 Hook 实现
页面静态声明注册中心

这里的目的不是背模块说明，而是先建立两条判断：

这段逻辑该落哪个模块
这个模块不该再继续承载什么

3. 你真正要先看的入口文件

如果你现在还不知道先开哪个文件，直接从下面这张入口图开始：

这一组先看什么

先搞清应用怎么启动、导航如何组织、Feature 页面如何被 ViewModel 和渲染器消费。

DefaultApplication

app/.../application/DefaultApplication.kt

看应用级初始化、模块环境兼容和基础设施启动。

MainActivity

app/.../ui/activity/MainActivity.kt

看语言切换、根宿主和应用侧启动时机。

AppNavHost

app/.../ui/navigation/AppNavHost.kt

看欢迎引导、主页面、独立页面与功能页路由如何接起来。

FeatureViewModel

app/.../ui/screen/common/FeatureViewModel.kt

看页面声明如何被转成界面状态和偏好状态。

FeatureScreen

app/.../ui/screen/common/FeatureScreen.kt

看标准 PageDefinition 最终如何分发到具体组件。

4. App 世界是怎么启动的

当前层职责

应用启动后先进入应用级初始化层，这里承载的是基础设施启动，不是普通占位 Application。

主要做什么

初始化 MMKV
初始化友盟
初始化 Root Shell
延迟触发静默更新检查

开发时要记住

它继承的是 ModuleApplication，不是普通 Application。
应用级初始化应优先留在这一层，而不是分散进页面。

5. Feature 页面系统是怎么工作的

FeatureRegistry 声明页面入口

feature-catalog

先用 PageDefinition、ModuleEntry、screenMap 把页面纳入目录体系，否则后续导航、搜索、渲染都无从谈起。

FeatureRepository / ViewModel 组装状态

core-data / app

仓库和 ViewModel 负责把声明转成实际可显示的数据、偏好状态和界面层所需的结构。

FeatureScreen 分发到具体组件

app / core-ui

通用页面渲染器根据 ScreenItem 类型把数据分发给 Switch、Slider、Dropdown、Arrow 等组件。

用户操作写入 prefs(category)

state

页面交互最终要写回约定好的 category / key，这一步直接决定 Hook 能不能读到正确配置。

核心作用

FeatureCatalog 是页面目录系统的接口，定义模块入口和 categoryId 到 PageDefinition 的映射。

关键点

接口核心字段是 moduleEntries 和 screenMap。
当前实际实现是 FeatureRegistry。

开发时要记住

不要把它理解成渲染器。
它负责页面声明入口，不负责真正 Hook。

这一段最核心的理解只有一条：

页面声明在 feature-catalog，状态装配在 app / core-data，渲染落到 FeatureScreen，依赖通过 Hilt 串起来。

6. 一个新功能页要怎么加

假设你要新增一个针对 com.example.demo 的功能页，可以先按下面这个顺序理解。

写在哪

`feature-catalog` 里的对应目录，例如 `features/demo/demo.kt`。

要交付什么

新增 `PageDefinition`。
把 `category`、`appList`、`title`、`items` 定义完整。
让 `key` 命名和后续 Hook 读取保持一致。

漏掉会怎样

页面声明不完整时，后面注册和渲染都没有意义。
一开始把 `category`、`key` 取乱，后续排查会很痛苦。

categorykey包名routeId

页面定义

object demo {
    val definition = PageDefinition(
        category = "demo",
        appList = listOf("com.example.demo"),
        title = AppName("com.example.demo"),
        items = listOf(
            CardDefinition(
                items = listOf(
                    Switch(
                        key = "remove_ads",
                        title = StringResource(R.string.demo_remove_ads)
                    )
                )
            )
        )
    )
}

FeatureRegistry 注册

moduleEntries += ModuleEntry("com.example.demo", "demo")

screenMap += mapOf(
    "demo" to demo.definition
)

Hook 读取

loadApp(name = "com.example.demo") {
    val prefs = prefs("demo")
    if (!prefs.getBoolean("remove_ads", false)) return@loadApp

    // install hook here
}

接线规则

`category` 决定 `prefs(...)` 命名空间。
`key` 必须和 Hook 读取键完全一致。
`routeId` 要能稳定映射到 `screenMap`。

常见断线点

只写 PageDefinition，没有注册 `ModuleEntry`。
页面开关和 Hook 读取用了两个不同 key。
路由层级改了，但 `screenMap` 和面包屑没同步。

这部分真正要记住的是：页面本体先落在 feature-catalog，再接入 FeatureRegistry，最后才去看它是否需要 Hook 配套。

最小页面定义示例

建议先在 feature-catalog 新建对应目录：

feature-catalog/src/main/java/com/suqi8/oshin/features/demo/

再建 demo.kt：

package com.suqi8.oshin.features.demo

import com.suqi8.oshin.feature.catalog.R
import com.suqi8.oshin.data.models.AppName
import com.suqi8.oshin.data.models.CardDefinition
import com.suqi8.oshin.data.models.PageDefinition
import com.suqi8.oshin.data.models.StringResource
import com.suqi8.oshin.data.models.Switch

object demo {
    val definition = PageDefinition(
        category = "demo",
        appList = listOf("com.example.demo"),
        title = AppName("com.example.demo"),
        items = listOf(
            CardDefinition(
                items = listOf(
                    Switch(
                        key = "remove_ads",
                        title = StringResource(R.string.demo_remove_ads)
                    )
                )
            )
        )
    )
}

只要先把下面三件事钉住，后面的接线就不会乱：

category 会成为该页面的偏好命名空间
key 会成为具体设置项的键
title、summary 用的资源应放在页面声明所属模块能访问到的资源里

接入目录系统

页面定义写完之后，至少还要补两处注册：

1. 注册模块入口

ModuleEntry("com.example.demo", "demo")

2. 注册页面映射

"demo" to demo.definition

如果这两处缺任何一处，模块页、路由、搜索链路都会表现异常。字符串资源则跟着页面所属模块走，不要为了省事跨模块乱放。

如果这个页面最终还要改目标进程行为，下一步就进入 Hook 接线。

7. 一个新 Hook 要怎么加

页面定义在 feature-catalog，真正的行为修改在 hook-apps。这两边接得是否稳，决定了功能到底是“存在于界面里”还是“真的在目标进程生效”。

当前阶段要做什么

先判断目标到底是普通 App、系统 App 还是系统服务，再决定用 `loadApp`、`loadSystem` 还是上层聚合 Hooker。

判断点

目标包名是否明确。
目标是否运行在 `system_server` 这类系统进程。
是否已经存在对应聚合入口，而不是需要新建根入口。

常见落点

`hook-apps/src/main/java/com/suqi8/oshin/hook/android/android.kt`
`hook-apps/src/main/java/com/suqi8/oshin/hook/systemui/systemui.kt`
`hook-apps/src/main/java/com/suqi8/oshin/hook/HookEntry.kt`

最常见错误

选错作用域后，代码能编译但根本不会在目标进程执行。
目标明明已有聚合入口，却又平行造一个新的入口层。

最小 Hook 模板

例如：

package com.suqi8.oshin.hook.demo

import com.highcapable.yukihookapi.hook.entity.YukiBaseHooker

class demo : YukiBaseHooker() {
    override fun onHook() {
        loadApp(name = "com.example.demo") {
            val prefs = prefs("demo")
            if (!prefs.getBoolean("remove_ads", false)) return@loadApp

            // 在这里写 Hook
        }
    }
}

这里至少保持两个习惯：

先读 prefs("对应页面 category")
先判断开关，再执行 Hook 搜索和 Hook 安装

如果目标类名稳定，这里通常继续接 KavaRef；如果明显混淆或版本波动大，再往下接 DexKit。

接到对应的聚合入口

如果你写了 hook/demo/demo.kt，还需要把它接入某个上层入口。

例如在 HookEntry 里，或者在某个分类 Hooker 里：

registerAppHookers(
    demo(),
)

或者：

class android : YukiBaseHooker() {
    override fun onHook() {
        loadApp(hooker = SomeSubHooker())
        loadHooker(SomeSystemLevelHooker())
    }
}

这里最容易断的是 category / key 对齐问题。页面里写什么，FeatureViewModel 最终就会往 context.prefs(pageDefinition.category) 写什么；Hook 端必须读同一份命名空间和同一个键，否则界面能显示、代码能编译、功能却不会生效。

8. Hook 入口链路要彻底搞清楚

hook-apps/src/main/assets/xposed_init

LSPosed 首先从这里读取模块入口声明。

com.suqi8.oshin.hook.oshin

这是入口类名，对应 YukiHookAPI 生成的桥接入口。

hook-apps/build/generated/ksp/.../oshin.kt

KSP 生成的入口实现，负责把注解声明转换为实际桥接代码。

HookEntry_Impl

生成实现继续承接入口初始化逻辑。

HookEntry

你真正维护的主入口源码，负责注册和调度各类 Hooker。

当前现状

`xposed_init` 存在。
`HookEntry` 存在。
`@InjectYukiHookWithXposed` 仍在使用。
KSP 生成类也存在。

不要再按旧教程理解

不要默认去 `app` 模块手动维护入口类。
不要把项目描述成“删掉 `xposed_init` 也没关系”。
文档和代码都应按当前这套链路理解。

9. YukiHookAPI 在本项目里怎么用

YukiHookAPI 是本项目 Hook 体系的基础框架，也是 App 世界和 Hook 世界之间的一部分桥接层。

典型写法

class SomeHook : YukiBaseHooker() {
    override fun onHook() {
        // hook logic here
    }
}

为什么这么写

项目里的绝大多数 Hook 文件都从 `YukiBaseHooker` 起步，这是组织 Hook 逻辑的最基本单元。

一个 Hook 文件通常只负责一组相近行为。
上层通过 `loadApp(hooker = ...)` 或 `loadHooker(...)` 继续聚合。

容易写错的地方

把不相干的大量功能揉进一个超长 Hook 文件。
Hook 类写好了，但没接回上层聚合入口。

如果你只记一句：在 OShin 里，绝大部分 Hook 入口、偏好桥接、Hook DSL、模块状态判断，都建立在这套 API 上。

10. KavaRef 在本项目里怎么用

KavaRef 是当前项目处理稳定反射路径时的主力工具。只要类名、方法名、字段结构还算稳定，优先用它，不要一上来就把问题交给 DexKit。

适用场景

当类名和方法名稳定时，KavaRef 应该是第一选择。当前仓库里天气、系统类、部分设置相关 Hook 都大量采用这套写法。

用 `toClass().resolve()` 建立解析上下文。
优先 `firstMethod` / `firstField`，而不是先拿列表再自己取第一个。

切换信号

如果类名或方法名版本波动很大，就不该继续硬写固定路径。
遇到混淆严重的目标，应改用 DexKit 先搜再接 Hook。

如果你发现类名经常变、方法经常变、包路径经常变，或者只能靠字符串、数字、调用关系定位目标，那就该转到下一节的 DexKit 路线。

11. DexKit 在本项目里怎么用

DexKit 的核心用途是：

在类名、方法名、字段名可能混淆或版本变化较大时，通过字符串、数字、特征条件去找到目标类或目标方法。

11.1 什么场景必须考虑 DexKit

满足下面情况之一，优先考虑 DexKit：

目标类名不稳定
目标方法名不稳定
目标包经常改实现
只能依赖字符串常量、数字常量、方法调用关系来定位

11.2 这不是“随便搜一搜”的库

DexKit 很强，但也有成本：

建桥有开销
搜索有开销
错误查询条件会拖慢性能
多处重复创建桥会浪费资源

所以项目里已经引入了 DexKitCacheManager，你通常不应该再自己散落一堆 DexKitBridge.create(...)。

12. 为什么项目里推荐 `DexKitCacheManager`

当前项目存在两类 DexKit 用法：

12.1 较旧的直接用法

例如某些文件里会看到：

DexKitBridge.create(this.appInfo.sourceDir).use {
    ...
}

这种写法本身不是错的，但在 OShin 当前项目里，它通常不是首选。

原因是项目已经有 DexKitCacheManager 统一处理：

so 加载
DexKitBridge 复用
MMKV 缓存
结果序列化
按目标 App 版本自动清缓存

12.2 当前更推荐的封装用法

项目里更推荐的路径是：

DexKitCacheManager.findClass(...)
DexKitCacheManager.findMethods(...)
DexKitCacheManager.findAndHook(...)

12.3 `DexKitCacheManager` 到底帮你做了什么

当前它至少做了下面这些事情：

1. DexKit so 加载

内部会调用：

System.loadLibrary("dexkit")

并用 isLibLoaded 避免重复加载。

2. MMKV 初始化

它会在目标进程里初始化缓存目录。

3. `DexKitBridge` 缓存

它按 packageName 维护 DexKitBridge 缓存，避免你每次都重新创建桥。

4. 搜索结果缓存

搜索到的方法或类会被序列化后写入 MMKV。

这样下次同版本再进来，就不用重复全量搜索。

5. 按目标 App 版本自动清缓存

它会记录目标 App 的版本。

如果目标 App 升级了，就会清掉对应缓存，避免旧结果污染新版本。

这点非常关键。

否则你会遇到：

旧方法签名缓存还在
新版本类结构变了
Hook 结果失效甚至报错

12.4 什么情况下还可以直接用 `DexKitBridge`

虽然当前项目推荐优先用 DexKitCacheManager，但也不是说直接 DexKitBridge 永远不能写。

以下场景可以考虑直接用：

一次性的本地调试实验
你在验证某个搜索条件，还没准备正式接入缓存层
目标逻辑非常短，且明确不需要重复复用

但只要准备正式合入项目，建议重新评估能否切回 DexKitCacheManager。

理由很现实：

统一缓存策略更容易维护
统一版本失效策略更安全
统一日志风格更便于排查
后续别人接手时不需要猜“为什么这个文件单独绕开缓存层”

13. `DexKitCacheManager` 三个核心 API 怎么选

13.1 `findClass`

适合场景：

你最终想拿到类名列表
你后面准备自己再做反射处理

返回值是 List<String>，也就是类名列表。

典型适合：

先搜类
再用 KavaRef 对这些类做进一步处理

13.2 `findMethods`

适合场景：

你想先拿方法集合
但是否 Hook、怎么 Hook，要看方法所属类或运行时条件

返回值是 List<DexMethod>。

典型例子是 GamesAIHook。

它先搜索方法，再根据方法所在类名中是否包含：

sgame
pubg
mlbb

来决定不同分支的处理方式。

这就是典型的“先找方法，后分流”。

13.3 `findAndHook`

适合场景：

你已经确定“找到这些方法后就是要直接 Hook”
不需要自己手动把 DexMethod 再转换一遍

这是当前项目里最常见、最省事的 DexKit 接入方式。

它会：

搜索方法
反序列化方法描述
根据是否构造器选择不同 Hook 方式
调用你传进去的 Hook 块

14. `DexKitCacheManager` 的标准写法

14.1 最常见的一次性查找并 Hook

以 browser.kt 为例，典型写法如下：

findAndHook(
    param = this,
    queryKey = "remove_weather_injected_ads",
    finder = { bridge ->
        bridge.findMethod {
            matcher {
                declaredClass = "com.heytap.browser.business.weather.js.ThirdCommonJsHook"
                modifiers = Modifier.PUBLIC
                paramCount = 0
                returnType = "void"
                usingNumbers(4)
            }
        }
    }
) {
    replaceUnit {}
}

这四个参数需要理解清楚：

`param`

通常直接传当前 loadApp { ... } 作用域里的 this。

因为 DexKitCacheManager 需要它里面的：

packageName
appInfo.sourceDir
appClassLoader

`queryKey`

这是缓存键的一部分，非常重要。

要求：

稳定
唯一
能体现查询意图

不要写成这种模糊名字：

"a"
"method"
"search1"

推荐写成：

"remove_weather_injected_ads"
"games_hok_ai_v2"
"gallery_unlock_hassel_watermark"

`finder`

这里写真正的 DexKit 搜索逻辑。

注意：

条件不要堆得过多
够准就行
过度复杂会让查询维护成本上升

Hook 块

这里就写正常的 YukiHookAPI Hook DSL：

before
after
replaceUnit

14.2 需要先拿方法再做条件判断时

以 GamesAIHook 为例：

DexKitCacheManager.findMethods(
    param = this,
    queryKey = "games_ai_play_v1"
) { bridge ->
    bridge.findMethod {
        searchPackages("com.oplus.feature.utils")
        matcher {
            modifiers = Modifier.PUBLIC
            returnType = "boolean"
            usingStrings("feature.support.game.AI_PLAY")
        }
    }
}

它拿到的是方法集合，然后再根据 declaringClass.name 分情况 Hook。

所以：

如果你还要继续做二次筛选，用 findMethods
如果你已经确定找到就直接 Hook，用 findAndHook

14.3 查询类再找方法的写法

以 gallery3d.kt 为例，可以看到链式思路：

bridge.findClass {
    ...
}.findMethod {
    ...
}

这类写法适合：

先锁定一批候选类
再在候选类上找方法

当混淆严重但仍有稳定字符串特征时非常有用。

15. DexKit 查询条件怎么设计

DexKit 最容易出问题的通常不是 Hook 块，而是查询条件本身。

建议的 `queryKey`

feature_strings_hook

查询模板

DexKitCacheManager.findAndHook(
    param = this,
    queryKey = "feature_strings_hook",
    finder = { bridge ->
        bridge.findMethod {
            matcher {
        usingStrings("feature_flag")
        paramCount = 0
            }
        }
    }
) {
    replaceUnit {}
}

15.1 常见可用条件

searchPackages(...)
className = "..."
name = "..."
paramTypes(...)
paramCount = ...
returnType = "..."
usingStrings(...)
usingNumbers(...)
modifiers = ...

15.2 一个简单判断原则

类名稳定

优先 KavaRef。

类名不稳定，但有稳定字符串

优先 DexKit 的 usingStrings(...)。

字符串不够，数字常量很明显

用 usingNumbers(...) 进一步收窄。

仍有多个结果

补：

paramCount
returnType
modifiers
searchPackages

15.3 不要一开始就把条件写爆

错误思路：

一次塞十几个条件
自己几天后都看不懂为什么能匹配到

正确思路：

先找到稳定特征
只加足够用的条件
保证后续版本还能维护

16. YukiHookAPI、KavaRef、DexKit 到底怎么选

可以用一个很简单的判断表：

Hook Strategy

按场景选技术栈

不同 Hook 问题的关键不在于 DSL 写法，而在于定位目标的稳定性。下面这组开关对应项目里最常见的四种决策条件。

YukiHookAPI + KavaRef

推荐结果

YukiHookAPI + KavaRef

目标结构稳定时，反射路径最清晰，也最容易维护，通常没有必要引入特征扫描。

什么时候用

系统类、稳定业务类或长期未混淆的目标类
类名、字段名、方法名都比较可靠
Hook 后还要读写实例字段或调用成员方法

落地方式

优先用 KavaRef 定位类、字段与方法
用 YukiHookAPI 负责真正的 Hook 回调
把字段访问与方法访问留在反射封装里处理

参考写法

val targetClass = "com.example.Target".toClass().resolve()
val method = targetClass.firstMethod {
    name = "run"
}

method.hook {
    before {
        instance.asResolver().firstField {
            name = "enabled"
        }.set(true)
    }
}

16.1 直接用 YukiHookAPI

适合：

你已经有 Method 或 Constructor
只差写 Hook 回调

16.2 YukiHookAPI + KavaRef

适合：

类名稳定
方法名稳定
字段结构稳定

这是系统类、部分稳定应用类最常见的方案。

16.3 YukiHookAPI + DexKit

适合：

目标类或方法可能混淆
需要通过特征搜索定位

16.4 YukiHookAPI + DexKit + KavaRef

适合：

先用 DexKit 找到目标方法或目标类
Hook 后还需要进一步读写实例字段

这在项目里也很常见。

16.5 当前项目的推荐顺序

可以直接记下面这条：

先判断 KavaRef 能否稳定解决；如果不能，再引入 DexKit；如果项目里已经有 DexKitCacheManager，优先复用它，不要重复实现桥接和缓存层。

17. 页面、设置、Hook 三者怎么对应

这是另一类高频接线问题。

下面三样内容必须保持一致：

先检查

页面里的 category、key 是否和 Hook 读取完全一致
Hook 是否先判断了开关再真正安装
目标进程和 loadApp/loadSystem 挂载点是否正确

高概率原因

prefs(category) 读错命名空间
Hook 根本没注册到正确入口
方法定位成功前就提前返回，或反之根本没命中目标方法

优先文件

feature-catalog/... 页面定义
hook-apps/... 目标 Hook 文件
hook-apps/.../HookEntry.kt 或聚合 Hooker

17.1 页面定义

例如：

PageDefinition(
    category = "browser",
    ...
)

17.2 页面开关

例如：

Switch(
    key = "remove_weather_search_box",
    ...
)

17.3 Hook 读取

例如：

val prefs = prefs("browser")
if (prefs.getBoolean("remove_weather_search_box", false)) {
    ...
}

如果这三者中有任何一个名字不一致，功能就会表现为：

界面有开关
开关能保存
但 Hook 完全不生效

18. 搜索系统怎么接入

怎么工作

页面注册进 FeatureRegistry 后，搜索通常会自动覆盖。
FeatureRepositoryImpl 会遍历 featureCatalog.screenMap、CardDefinition 和 TitledScreenItem，然后构建 SearchableItem。
TitleResolver 会把 StringResource / PlainText / AppName 解析成真实标题，并构建拼音索引。

关键文件

FeatureRepositoryImpl
TitleResolver

开发建议

标准 TitledScreenItem 一般不需要额外接线。
如果搜不到，先回查页面声明是否属于标准可索引项。

19. 路由和面包屑怎么生成

这一层和搜索、应用信息本质上是一条“页面如何被发现”的链路。

20. 应用信息、图标、模块页数据是怎么来的

这一层优先复用现有 AppInfoProvider，不要在页面里手写一套新的按包名取信息逻辑。

21. 更新、验证、欢迎引导的关系

核心判断

AppNavHost 会根据首次启动、协议状态、重新验证需求决定是否进入 WelcomeScreen。
欢迎引导只是入口分流点，不等于完整验证逻辑本身。

优先文件

AppNavHost
WelcomeScreen

不要只改单点

不要把“是否进入欢迎引导”和“是否需要验证”硬编码成同一层判断。

22. 多语言、资源和模块归属怎么处理

这一节的重点不是记零散规则，而是先确认资源归属和唯一入口，再补语言与翻译。

核心职责

模块页和部分页面顶部应用信息依赖 AppInfoProvider。
它会读取应用名和图标、做磁盘缓存、优先从 SystemUI 上下文拿图标，并把名称缓存到 MMKV。

优先文件

core-data/.../AppInfoProvider.kt

开发建议

不要在页面里自己到处手写“根据包名读取应用信息”。
优先复用现有 AppInfoProvider。

23. 当前应避免的过时写法

这一节专门列“不要再这样写”的点。

旧式示例

val field = targetClass.field { name = "enabled" }
field.get(instance).set(true)

23.1 不要再把项目当成单体 `app` 模块

现在不是过去那种：

app/
  hook/
  features/
  ui/

的单一结构了。

23.2 不要默认手动去 `app` 模块维护 `xposed_init`

当前项目真实入口链路已经在前面讲过。

23.3 不要一上来就手写 `DexKitBridge.create(...)`

优先看是否可以走 DexKitCacheManager。

23.4 不要页面里和 Hook 里各写一套不同的 key

category、key、prefs(...) 必须对齐。

23.5 不要为了一个功能页单独手写 Compose 页面

先判断标准 PageDefinition 能不能描述。

能描述就走声明式体系。

23.6 不要把通用逻辑直接塞进 `app`

例如：

可复用组件放 core-ui
更新逻辑放 core-update
页面静态声明放 feature-catalog

23.7 反射与 Hook 示例统一走现代写法

例如：

不要再用 instance.current() 作为主要示例路径
不要再把 get(instance) 这类旧式实例访问写成推荐写法
不要再围绕 instanceClass 组织新的 Hook 示例

当前项目示例应优先展示：

resolve()
firstMethod / firstField
instance.asResolver()
实例方法场景优先写 invoke()，不要继续把旧式 call() 当成主示例
直接拿到 Method 后再写 hook { ... }

24. 开发时建议的工作顺序

下面这块直接按场景拆好了，照着走通常不会乱：

先在 feature-catalog 写页面或开关定义

再在 hook-apps 写 Hook

确保 category 和 key 对齐

补字符串资源

构建调试包

上机验证

常用任务

调试包编译

./gradlew :app:assembleDebug

缺失翻译 XML 输出

./gradlew reportMissingTranslationsXml

25. 常用任务与检查

调试包编译和缺失翻译输出已经合并到上面的操作面板里，这里不再重复铺开命令说明。

26. 推荐阅读顺序

DefaultApplication

先看应用侧基础设施从哪里启动。

MainActivity

看语言切换、根宿主和应用入口行为。

AppNavHost

看独立路由页与功能页是怎么接起来的。

FeatureRegistry

看整个功能目录和页面声明中心。

FeatureViewModel

看页面定义如何被转成 UI 状态。

FeatureScreen

看声明式页面最终如何渲染。

HookEntry

看 Hook 世界的总入口和注册方式。

hook/android/android.kt

看聚合 Hooker 的组织模式。

hook/weather/weather.kt

看稳定类名下 KavaRef 的典型做法。

hook/browser/browser.kt

看 DexKitCacheManager 在真实场景中的接法。

hook/gallery3d/gallery3d.kt

看另一个应用侧 Hook 场景，避免只盯一个样本。

DexKitCacheManager

最后再看缓存层，理解为什么项目不鼓励到处手写桥接。

读完这条路径，基本就能独立完成大多数常规改动。

27. 提交前自检清单

这次至少检查这些

FeatureRegistry 是否同时注册了模块入口和 screenMap
category、key、title、summary 是否都落在正确模块
搜索、路由、面包屑链路是否还能找到这个页面

最容易漏掉的点

只写了页面定义，没有真正暴露入口
资源放错模块，后续又被搬回去重构一遍
页面能打开，但 Hook 完全没有接到同名 category / key

28. 最后说明

在 OShin 里写代码，最常见的问题不是“不会写 Hook”，而是：

没先搞清楚自己在改 App 世界还是 Hook 世界
没先搞清楚某段逻辑属于哪个模块
明明有现成抽象，却重新实现了一套近似逻辑

开始改之前，建议先确认：

这段逻辑应该放哪个模块
这件事项目里有没有现成抽象
这次更适合 KavaRef 还是 DexKit

把这三件事想清楚，代码通常就不会走偏。

参与开发

先选你的当前目标

先看这些章节

先碰这些文件

先避开这些误区

从三个视角理解 OShin

先区分 App 世界和 Hook 世界

DefaultApplication / MainActivity

xposed_init -> 生成入口 -> HookEntry

YukiBaseHooker 与目标进程

先判断改动该落在哪个模块

首选模块

通常还会联动

不要优先放到

模块职责总览

职责

典型内容

不要优先放进来

依赖理解

当前关键版本

先读这些文件，比无差别翻仓库有效

这一组先看什么

App 世界启动总览

当前层职责

主要做什么

开发时要记住

切换看两条最关键的执行链路

FeatureRegistry 声明页面入口

FeatureRepository / ViewModel 组装状态

FeatureScreen 分发到具体组件

用户操作写入 prefs(category)

Feature 页面系统总览

核心作用

关键点

开发时要记住

新增功能页的标准落地顺序

写在哪

要交付什么

漏掉会怎样

把页面、注册、Hook 读取一次接通

页面定义

FeatureRegistry 注册

Hook 读取

接线规则

常见断线点

新增 Hook 时真正要跑通的闭环

当前阶段要做什么

判断点

常见落点

最常见错误

Hook 入口链路总览

当前现状

不要再按旧教程理解

本项目里的 YukiHookAPI 实战口径

典型写法

为什么这么写

容易写错的地方

KavaRef 在 OShin 里的推荐使用方式

推荐示例

适用场景

切换信号

先设计查询条件，再写搜索代码

推荐策略

建议的 `queryKey`

查询模板

按场景选技术栈

YukiHookAPI + KavaRef

什么时候用

落地方式

按症状反查第一落点

先检查

高概率原因

优先文件

搜索、路由和应用信息是一条链

怎么工作

关键文件

开发建议

欢迎引导、验证、静默更新的关系

核心判断

优先文件