# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

Android 输入法应用（IME），包含自定义键盘和社交圈（Circle）功能模块。Kotlin 开发，Jetpack Compose + XML 混合 UI。

- **包名**: `com.boshan.key.of.love`
- **命名空间**: `com.example.myapplication`
- **编译配置**: compileSdk 34, minSdk 21, targetSdk 34

## 构建命令

```bash
gradlew assembleDebug      # 构建 Debug APK
gradlew assembleRelease    # 构建 Release APK
gradlew installDebug       # 安装到设备
gradlew clean              # 清理
gradlew lint               # Lint 检查
```

## 核心架构

### 应用入口流程
```
SplashActivity → GuideActivity/ImeGuideActivity → OnboardingActivity → MainActivity
```

### 键盘模块 (keyboard/)

**继承体系**：
```
BaseKeyboard (抽象基类，提供震动、主题应用、递归设置文字颜色)
    ├── MainKeyboard (主键盘，拼音/英文输入)
    ├── AiKeyboard (AI 辅助键盘)
    ├── EmojiKeyboard (表情/颜文字键盘)
    ├── NumberKeyboard (数字键盘)
    └── SymbolKeyboard (符号键盘)
```

**核心服务 `MyInputMethodService.kt`**：
- 键盘懒加载 + 缓存机制（`ensureMainKeyboard()` 等）
- 智能联想流程：`commitKey()` → `updateCompletionsAndRender()` → 后台计算候选词 → `showCompletionSuggestions()`
- 特殊交互：Emoji 按 Unicode 代码点删除、长按连删 + 上滑清空、回填功能

### 语言模型 (data/)

**N-gram 模型架构**（`LanguageModel.kt` + `LanguageModelLoader.kt`）：
- 词表：`assets/vocab.txt`（每行一词，行号=词ID，按频率降序）
- Unigram：`assets/uni_logp.bin`（u16 分数数组，0-1000，越高越常用）
- Bigram：`assets/bi_rowptr.bin`（[u32 offset, u16 length]） + `bi_data.bin`（[u32 next_id, u16 score]）
- Trigram：`assets/tri_ctx.bin`（[u32 ctx1, u32 ctx2]） + `tri_rowptr.bin` + `tri_data.bin`

**预测算法**：3-gram → 2-gram → 1-gram 回退机制，结合用户点击学习排序

**Trie 优化**（`Trie.kt`）：
- 每个节点记录 `maxFreq`（子树最高词频）
- 优先级队列遍历快速获取 top-K
- 用户点击权重 1000，远超静态词频

### 网络层 (network/)

**双客户端架构**：
- `RetrofitClient.kt`：常规 HTTP（30s 超时）
- `NetworkClient.kt`：SSE 流式响应（无超时，用于 AI 聊天）

**请求签名机制**（`HttpInterceptors.kt`）：
1. 生成 timestamp + nonce（UUID 前 16 位）
2. 合并参数（appId + timestamp + nonce + query + body 扁平化）
3. 按 key 字典序拼接，HMAC-SHA256 签名
4. 添加 Header：X-App-Id, X-Timestamp, X-Nonce, X-Sign

**SSE 解析**（`NetworkClient.kt`）：支持 JSON 和纯文本 chunk，自动识别 `[done]` 结束标记

**Token 过期处理**：响应拦截器检测 code=40102/40103 → 清除本地 token → `AuthEventBus.emit(TokenExpired)`

### 社交圈 Repository (ui/circle/)

**缓存策略**（`CircleChatRepository.kt`）：
- 自适应 LRU 缓存大小（根据设备内存 32-120 页）
- 预加载当前页前后 N 页
- 防重加载机制（`inFlight`、`pageInFlight` HashSet）

### 主题系统 (theme/)

- `ThemeManager.kt`：观察者模式通知主题变更
- 各键盘实现 `applyKeyBackgroundsForTheme()` 应用主题
- `ThemeDownloadWorker.kt`：WorkManager 后台下载

### UI 模块 (ui/)

| 模块 | 说明 |
|------|------|
| `circle/` | 社交圈：AI 角色聊天、评论系统 |
| `shop/` | 主题商店 |
| `mine/` | 个人中心 |
| `login/` | 登录注册 |
| `recharge/` | 充值 |
| `home/` | 首页 |

导航图：`res/navigation/circle_graph.xml`

## 关键配置

**build.gradle.kts**：
```kotlin
androidResources {
    noCompress += listOf("bin")  // 禁止压缩 .bin，允许 FileChannel 内存映射
}
```

**输入法配置**：`res/xml/method.xml`
**网络安全**：`res/xml/network_security_config.xml`

## 辅助脚本

```bash
python scripts/clean_vocab.py <输入文件> <输出文件>  # 词表清洗（过滤无效词）
```

## 开发注意事项

- 输入法服务需用户在系统设置中手动启用
- 语言模型使用 `FileChannel.map()` 内存映射加载，修改 .bin 文件需重新生成
- 网络请求签名使用 Body 扁平化（支持嵌套 JSON 和数组）
- `NetworkClient.init(context)` 必须在使用 SSE 前调用（通常在 Application.onCreate）
- 项目当前无单元测试配置