Appearance
AI 技能库 — 索引
本目录存放与筷字输入法项目开发相关的 AI 技能文档，提供最佳代码写法、避免不规范写法的指导，明确哪些能做、哪些不能做，以及 Kotlin 和 Jetpack Compose 等库的功能特性使用建议。
技能库内容跨版本通用，适用于项目所有主线版本的开发。
技能文档列表
| 文档 | 说明 |
|---|---|
| Kotlin 最佳实践 | Kotlin 2.3.20 特性使用、惯用写法、避坑指南 |
| Jetpack Compose 最佳实践 | Compose BOM 2026.04.01 特性使用、IME 场景下的最佳实践 |
| 代码规范 | 项目级代码规范：命名、格式、注释、错误处理等 |
项目命名规范：三层模块命名、UI 组件后缀、已更名对照等项目特定的命名规范，详见设计文档目录下的命名规范文档。
核心原则
显式优于隐式
- 所有公开 API 必须有显式的类型声明、文档注释和访问修饰符
- 避免使用隐式转换、隐式接收者、隐式作用域等不明确的写法
- 状态变更必须有迹可循，禁止隐式修改共享状态
- 错误处理必须显式，不使用 try-catch 吞掉异常
任其崩溃（Fail Fast）
- 遇到不可恢复的错误，立即抛出异常或崩溃，而不是静默降级
- 不使用
!!以外的空值假设——如果逻辑上不可能为 null，用!!明确声明并让它在假设错误时崩溃 - 不对关键前置条件做防御性容错——使用
require()、check()在入口处断言 - 状态不一致时立即失败，而不是尝试自动修复
不可变优先
- 所有数据类默认为
data class，属性默认val - 仅在确实需要可变状态时使用
var，并需在文档中说明理由 - 集合类型默认使用只读接口（
List、Map、Set），仅在构建时使用mutableListOf等 - 状态变更通过创建新实例而非修改现有实例（
copy()模式）
单向数据流
- UI 状态自上而下流动，事件自下而上传递
- 禁止视图层直接修改模型层状态
- 所有状态变更必须经过统一的处理管道
技能文档编写规范
目的：确保技能文档聚焦于代码层面的最佳实践，避免与架构设计文档产生职责重叠和内容冗余。
1. 文档范围声明
每篇技能文档必须在开头声明其内容范围：
- 通用内容：与特定项目无关的语言 / 框架最佳实践。示例使用领域无关的类名和场景（如
Item、User、Config等），不使用本项目的类名 - 项目内容：直接涉及本项目的代码编写模式。示例使用本项目的真实类名和设计概念
声明格式：
> **说明**：本文档前半部分为通用 Kotlin 最佳实践，第 5、8 节涉及本项目的 Java → Kotlin 迁移对比。通用示例不绑定本项目领域对象，项目迁移示例则直接使用本项目的类名和设计。规则：
- 通用章节中的示例禁止使用本项目的类名（如
ImeEngine、KeyboardPanel等），应使用通用名称（如DataProcessor、ItemPanel等） - 项目特定章节中的示例必须使用本项目的真实类名，不得虚构或使用过时名称
2. 示例编写规范
2.1 通用示例
通用章节的示例应使用领域无关的命名：
kotlin
// ✅ 正确：通用示例用领域无关名称
data class ListState(
val items: List<Item> = emptyList(),
val selectedIndex: Int = 0,
)
// ❌ 错误：通用示例使用本项目类名
data class InputListState(
val chars: List<CharInput> = emptyList(),
val cursorIndex: Int = 0,
)2.2 项目示例
项目特定章节的示例必须使用本项目的真实类名，并反映最新设计。命名规范以项目设计文档中的命名规范为准。
3. 同步更新规则
当项目的命名或设计发生变更时，技能文档必须同步更新：
- 类名变更：所有技能文档中出现的旧类名必须替换为新类名，包括示例代码、表格、注释中的引用
- 架构变更：涉及组件职责变更时，相关示例必须反映新的职责边界
- 新增约定：新确认的命名约定或设计规则必须同步补充到命名规范文档