Appearance
三层模块划分
1 概述
将筷字输入法设计为三层库架构，支持其他程序以库的形式引入，提供完整的输入法能力支持：
- 引擎库
:engine：引擎库独立设计的目标是使输入法的逻辑层与 UI 和应用之间实现分离、解耦，从而方便第三方定制自己的 UI、修改交互逻辑等，提供核心输入引擎能力 - UI 库
:ui：基于 Compose 的缺省 UI 实现，对第三方应用开放，可作为即插即用的输入界面使用，也可被自定义 UI 替换 - 应用模块
:app：系统 IME 服务壳、设置页面、输入练习 UI（ExerciseScreen）、配置持久化，是库的官方消费者（注：InputActionPlayerPanel 属于:ui模块）
库的核心价值在于：任何 Android 应用都可以通过引入 :engine + :ui，获得筷字输入法的完整输入能力和缺省 UI——拼音滑行、候选选择、输入列表管理、撤销重做等——而无需依赖系统 IME 服务。仅需要引擎逻辑的场景（如文本预处理、自动化测试）可以只引入 :engine 而不引入 UI 库。需要完全自定义 UI 的场景可以只引入 :engine 并自行实现视图层。
2 模块职责与依赖
| 模块 | 职责 | 依赖 |
|---|---|---|
:engine | IME 核心引擎，逻辑层与 UI / 应用分离，方便第三方定制 UI 与交互。注意：KeyTableGenerator 已移至 :ui 模块 | Kotlin 标准库 + 协程 |
:ui | Compose 缺省 UI + KeyboardViewModel，包含完整的输入法界面组件、UI 协调逻辑和按键布局生成（KeyTableGenerator） | :engine + Compose + Material3 + Lifecycle ViewModel |
:app | 系统 IME 服务壳、ImeEngine 创建与 InputConnectionBridge 管理、配置持久化（DataStore）、设置页面、输入练习 UI（ExerciseScreen） | :engine + :ui + DataStore + Lifecycle |
:app-codegen | 通过 KSP（Kotlin Symbol Processing）自动生成 EngineConfig 和 UiConfig 的 DataStore 持久化读写代码 | Kotlin KSP + DataStore Preferences |
:app-codegen 模块通过 KSP（Kotlin Symbol Processing）自动生成 EngineConfig 和 UiConfig 的 DataStore 持久化读写代码，消除手动维护 22 个 DataStore key 的样板代码。详见 配置管理设计。
依赖关系图：
3 设计原则
- 引擎与 UI 完全分离：
:engine不包含任何 Compose 代码或 Android View，只暴露状态流和意图接口 - UI 库作为缺省实现对外开放：
:ui提供完整的 Compose UI 组件，第三方应用可直接使用，也可替换为自定义 UI - 统一配置：库不内置配置持久化，所有配置通过
ImeConfig（含引擎配置和 UI 配置的明确隔离）在创建时或运行时设置 - 数据库层可替换：字典接口与实现分离，内置 SQLite 实现，外部可提供自己的
ImeDictProvider - 功能可裁剪：收藏和剪贴板等可选功能通过
ImeConfig.engine中的布尔配置字段（favoriteInputEnabled、favoriteClipEnabled等）按需启用 / 禁用 - Fail Fast：非法操作（如禁用收藏后调用收藏功能）立即抛出异常而非静默忽略
4 引擎库核心模型
引擎库的核心模型定义了 :engine 与 :ui、:app 之间的核心契约，包括：
- ImeEngine：引擎核心入口点，通过
StateFlow暴露状态，通过ImeIntent接收操作，通过ImeEditorBridge分发编辑器操作 - ImeConfig：统一运行时配置，含引擎配置（
EngineConfig）和 UI 配置（UiConfig）的明确隔离 - EditorAction：引擎编辑器操作的 sealed class 表达，由引擎统一分发到桥梁
- ImeIntent：用户意图的 sealed class 表达，所有用户操作统一为 Intent
- ImeState 子状态类型：
InputList、CandidateList、Clipboard、FavoriteList等 - KeyboardType：键盘内容类型枚举（Pinyin/Latin/Symbol/Emoji/Number/Math/Editor/Candidate/CommitOption），决定按键集合的语义内容
- KeyboardInputMode：输入交互范式枚举（HexGrid/RectGrid），决定按键的几何排列和交互方式
完整的模型定义和代码详见 010-引擎库设计总览。
5 UI 库设计
UI 库 :ui 的核心设计目标是作为缺省 UI 实现对第三方应用开放，遵循「缺省实现、可替换、可组合、可定制」四大设计原则。UI 库提供从原子组件（KeyView、CandidateItem）到面板组件（GestureInputPanel、KeyLayoutPanel、CandidateListPanel）再到集成组件（KeyboardHost）的完整组件层次，以及 KeyboardViewModel 作为 UI 协调中心和主题系统。输入练习 UI 层（ExerciseScreen）属于 :app 模块，InputActionPlayerPanel 属于 :ui 模块的集成组件。
编辑器桥接机制（ImeEditorBridge 桥接模式）是引擎与目标编辑器之间的核心架构模式：引擎内部统一执行 when(EditorAction) 分发，桥梁实现者只需实现语义方法。ImeEditorBridge 接口和 BaseImeEditorBridge 抽象类定义在 :engine，InputConnectionBridge（系统输入连接）实现在 :app，EditTextBridge（EditText 类型）实现在 :ui。
详细设计分别见：
- UI 库设计目标与组件清单：010-UI 库设计总览
- 编辑器桥接机制：060-意图、编辑器操作与桥接