解构 LeanType 源码架构:Kotlin + JNI C++ 词典引擎完整导读
解构 LeanType 源码架构:Kotlin + JNI C++ 词典引擎完整导读
LeanType 是一款基于 HeliBoard 二次开发的开源 Android 键盘,其源码采用 Kotlin + JNI C++ 双栈架构:界面、输入逻辑与插件系统在 Kotlin 层完成,而决定候选词质量的词典引擎、N-gram 语言模型与滑动输入则运行在 JNI C++ 词典引擎中。本文将带你完整导读 LeanType 源码架构与项目结构,搞懂「一次按键」如何在两层代码间流转。
一分钟看懂:LeanType 项目目录结构
先建立全局地图。仓库顶层非常干净,核心内容集中在 app/ 下:
LeanType/
├── app/
│ ├── src/
│ │ ├── main/
│ │ │ ├── java/ # Kotlin 层:helium314/keyboard/ 下 400+ 个 .kt 文件
│ │ │ ├── jni/ # C++ 核心:词典引擎、建议算法、JNI 桥接
│ │ │ ├── aidl/ # 插件进程间通信接口
│ │ │ ├── assets/ # 键盘布局(.json/.txt)、词典(.dict)、Emoji 数据
│ │ │ └── res/ # 布局、图标与 100+ 种语言的本地化字符串
│ │ ├── standard/ # 在线版 flavor(支持云端 AI 与更新检查)
│ │ └── offline/ # 离线版 flavor(无网络权限,支持本地 GGUF 模型)
│ └── proguard-rules.pro
├── docs/ # 功能文档 docs/FEATURES.md、发版记录
├── tools/ # 辅助脚本(翻译检查、发布脚本等)
└── settings.gradle # Gradle 入口
构建配置上有两个值得注意的点:
| 机制 | 说明 | 代码位置 |
|---|---|---|
| 双 Flavor | standard 支持云端 AI;offline 通过 Manifest 剥离网络权限 |
app/src/standard/AndroidManifest.xml、app/src/offline/ |
| 可复现构建 | 在 Gradle 入口显式关闭 R8 Full Mode,保证每次构建产物一致 | settings.gradle |
Kotlin 层:一次按键的入口与主循环
整个输入法的进程入口是 LatinIME,它继承自系统 InputMethodService,负责窗口管理、子类型切换与全局生命周期:
- LatinIME.kt:类声明处,键盘服务总入口
- InputLogic.kt:处理按键、滑动、空格、候选词提交的核心状态机
- MainKeyboardView.kt:键盘主视图,把触摸坐标翻译成按键事件
Kotlin 层按职责拆分为几个子包,读源码时按这个顺序看最省力:
| 包 | 职责 | 代表文件 |
|---|---|---|
| keyboard/ | 按键、布局解析、弹层、主题渲染 | KeyboardView.kt、KeyboardParser.kt |
| event/ | 事件解码链与组合器(死键、Hangul 等) | EventDecoder.kt、CombinerChain.kt |
| latin/ | 建议、词典、OCR、语音、AI 等功能模块 | Suggest.kt、MathSuggestionManager.kt |
| settings/ | 自研的声明式设置界面 | SettingsNavHost.kt、screens/ |
其中 latin/ 是最活跃的模块,按能力继续细分:dictionary/(词典接口)、suggestions/(建议条 UI)、voice/(Whisper 语音)、ocr/(截图与相机 OCR)、translation/(翻译)、calculator/(行内数学求值)、personalization/(个人词典学习)。键盘布局则以 JSON/TXT 资源形式存放在 app/src/main/assets/layouts/main/,如 azerty.json、colemak.json,运行时由 Kotlin 解析器动态加载。
JNI C++ 层:词典引擎如何工作
这是 LeanType 源码中最精妙的部分。Kotlin 负责「说什么」,C++ 负责「算得多快、多准」。
1. 库加载与校验。 JniUtils.kt 定义了库名 jni_latinime(即 libjni_latinime.so),并对用户导入的库文件做 SHA-256 校验和比对,防止加载被篡改的滑动输入库——这也是 LeanType 隐私优先理念的缩影。
2. JNI 桥接。 C++ 侧只暴露了 4 组 Java 类,接口面非常克制:
- com_android_inputmethod_latin_BinaryDictionary.h:二进制词典的打开与读取
- com_android_inputmethod_latin_DicTraverseSession.h:一次搜索会话的句柄
- com_android_inputmethod_keyboard_ProximityInfo.h:按键坐标的接近度信息(滑动输入核心)
- jni_common.cpp:JNI 注册与公共工具
Kotlin 侧的对应抽象类 Dictionary.kt 定义了 getSuggestions() 签名:Kotlin 把按键序列、N-gram 上下文、接近度句柄打包传给 C++,拿回按分数排序的 SuggestedWordInfo 列表。
3. C++ 内部结构。 引擎按三层组织,代码量约 220 个源文件:
jni/src/
├── dictionary/ # 二进制词典格式:Patricia 树、bigram 表、词频属性
├── suggest/ # 建议引擎:词典树遍历 + 空间/语言模型打分
└── utils/ # 工具:时间记录、N-gram 上下文、日志
dictionary/ 实现了 .dict 文件的 v4 二进制格式:structure/v4/ 下的 ver4_patricia_trie_policy 等文件实现了前缀压缩树(Patricia Trie),content/ 子目录存放 bigram 语言模型表与概率表,property/ 则是词属性(频率、词类)。
suggest/ 是打分核心。suggest.h 用一段注释把整套命名规范讲得很清楚,理解它基本就理解了 LeanType 的纠错原理:
- Distance(距离):加权编辑距离,空间模型与语言模型各自一套
- Compound Distance:空间距离 + 语言距离,用于剪枝
- Score(分数):最终校准分,作为候选词优先级回传 Kotlin 层
Suggest 类持有 Traversal(遍历策略)、Scoring(打分策略)、Weighting(加权策略)三个策略对象,并处理替换、转置、插入、省略等全部打字错误类型(见 suggest.h)。而「空间模型 vs 语言模型的权重」正是设置界面里「Suggestion balance」那个滑杆在底层的作用点。
插件架构:AIDL 把重模块拆出去
LeanType 的语音(Whisper)、OCR、翻译、手写、GIF 等重型能力都以独立 APK 插件形式存在,通过 AIDL 跨进程调用。接口定义集中在 app/src/main/aidl/com/leanbitlab/leantype/:
| AIDL 接口 | 对应 Kotlin 侧加载器 |
|---|---|
| voice/IVoiceEngine.aidl | VoicePluginManager.kt |
| gif/IGifEngine.aidl | GifPluginManager.kt |
| —(OCR/翻译/手写) | OcrPluginLoader.kt、TranslationLoader.kt、HandwritingLoader.kt |
| —(离线 AI,offline flavor) | OfflineAiLoader.kt |
这种设计让主 APK 保持在约 10 MB,重模型按需下载,同时 offline flavor 可以在操作系统层面彻底断网。
源码阅读路线图与参考文档
如果你是第一次读这个仓库,建议按「数据流」顺序走一遍:
- MainKeyboardView.kt:触摸如何变成按键事件
- InputLogic.kt:事件如何变成词并触发建议
- Dictionary.kt + JniUtils.kt:跨层边界在哪
- suggest.h + suggest.cpp:C++ 词典引擎的打分主循环
延伸阅读:
- 官方功能与按键码参考:docs/FEATURES.md
- 键盘布局说明:layouts.md
- 贡献指南:CONTRIBUTING.md
- 构建与发布工具:tools/release.py
掌握「Kotlin 管交互、C++ 管计算、AIDL 管扩展」这条主线后,LeanType 的源码架构就不再是一团 400 多个文件的森林,而是一张清晰的三车道高速公路了。