diff --git a/README.md b/README.md
index 2765533..3b070a8 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,8 @@
 
 RIME 输入法上下文调频过滤器。根据已上屏的前文自动调整候选词顺序，越用越准。
 
+[![CI](https://github.com/sakuradairong/rime-context-filter/actions/workflows/ci.yml/badge.svg)](https://github.com/sakuradairong/rime-context-filter/actions/workflows/ci.yml)
+
 ## 原理
 
 监听每次上屏内容，自动记录「前文 → 当前选的词」的共现关系。之后遇到同样前文时，将对应的候选词提权置顶。
@@ -10,6 +12,8 @@ RIME 输入法上下文调频过滤器。根据已上屏的前文自动调整候
 - **跨会话**：学习数据持久化到本地文件，重启不丢
 - **轻量**：热路径无文件 I/O，不卡输入
 - **跨平台**：自动适配 Windows / macOS / Linux 路径
+- **安全**：数据文件在沙箱环境中加载，防止恶意代码执行
+- **自动遗忘**：内置衰减机制，长期不用的搭配逐渐消退
 
 ## 效果
 
@@ -77,7 +81,7 @@ context_filter:
 
 | 参数 | 类型 | 默认值 | 说明 |
 |---|---|---|---|
-| `save_interval` | 整数 | 30 | 每 N 次提交写一次磁盘 |
+| `save_interval` | 整数 | 30 | 每 N 次提交写一次磁盘。可设为 0 强制每次提交都存盘 |
 | `data_path` | 字符串 | 自动 | 自定义数据文件完整路径。设置后覆盖自动检测结果 |
 | `decay_enabled` | 布尔 | true | 启用衰减后，旧数据的权重随时间逐渐降低 |
 | `decay_rate` | 浮点数 | 0.95 | 每次保存时所有计数的乘数因子（0 < rate < 1） |
@@ -104,7 +108,7 @@ context_filter:
 |---|---|
 | **Windows** | `%APPDATA%\Rime\context_learned.data` |
 | **macOS** | `~/Library/Rime/context_learned.data` |
-| **Linux** | `/Library/Rime/context_learned.data`（注：Linux 路径可能随发行版不同，推荐使用 `data_path` 自定义） |
+| **Linux** | `$XDG_DATA_HOME/rime/context_learned.data`，fallback `~/.local/share/rime/context_learned.data` |
 
 也可以配置 `data_path` 指定任意路径。
 
@@ -122,7 +126,7 @@ return {
 
 ### 安全性
 
-数据文件在**沙箱环境**中加载。恶意构造的数据文件无法访问 `os`、`io`、`string` 等系统库，仅允许纯数据（表、数字、字符串）返回。兼容 Lua 5.1 / LuaJIT（自动降级为无沙箱模式）。
+数据文件在**沙箱环境**中加载。恶意构造的数据文件无法访问 `os`、`io`、`string` 等系统库，仅允许纯数据（表、数字、字符串）返回。兼容 Lua 5.1 / LuaJIT（自动降级为无沙箱模式并输出警告）。
 
 ## 工作原理
 
@@ -135,13 +139,13 @@ commit_notifier
   └─ 更新上下文窗口
 ```
 
-每次录入时，过滤器从当前上下文窗口提取 4 种 key 进行加权查询：
+每次录入时，过滤器从当前上下文窗口提取 4 种 key 进行加权查询。截取 key 时按 **UTF-8 字符边界**操作，避免中英混输时的乱码问题。
 
 | Key | 权重 | 示例 |
 |---|---|---|
 | 精确前文 | 1.0 | `"接下来的"` |
-| 末尾 2 字（≥6 字节） | 0.5 | `"来的"`（前文 `"接下来的"` 时） |
-| 末尾 1 字（≥3 字节） | 0.25 | `"的"` |
+| 末尾 2 字 | 0.5 | `"来的"`（前文 `"接下来的"` 时） |
+| 末尾 1 字 | 0.25 | `"的"` |
 | 双词组合 | 0.4 | `"接下来的任务"` |
 
 四个 key 的得分加权求和，总分 ≥ 2.0 才参与重排（约 2-3 次选择后生效）。
@@ -150,8 +154,31 @@ commit_notifier
 
 数据以 **Lua 源码格式** 存储。加载时通过 `load()` 由 Lua VM 一次性编译执行，不用逐行 regex 解析。写入使用原子重写（`.tmp` + `rename`），防止文件损坏。
 
+### 衰减 / 遗忘
+
+每次保存时对全部计数乘以 `decay_rate`（默认 0.95），计数降至 1.1 以下的条目自动清除。频率越高的搭配保留越久，偶然一次的搭配较快消亡。
+
+## 开发
+
+### 运行测试
+
+需要 Lua 5.3+ 或 LuaJIT：
+
+```bash
+lua test_rime_context_filter.lua
+```
+
+测试覆盖：评分聚合、序列化/反序列化往返、衰减计算、UTF-8 安全截取、表格复用。
+
+### CI
+
+每次推送自动运行：
+- `luacheck` 静态分析
+- 跨 Lua 5.3 / LuaJIT / Lua 5.1 三平台单元测试
+
 ## 版本历史
 
+- **v5.1** — 修复 Linux 数据路径（XDG_DATA_HOME 优先）、UTF-8 按字符截取、Lua 5.3 序列化兼容、scores 表复用减 GC、新增 40 个单元测试 + CI
 - **v5** — 跨平台路径自动检测、衰减遗忘机制、沙箱安全加载、热路径 GC 优化
 - **v4** — Lua 源码持久化格式（移除 JSON 依赖）
 - **v3** — 增量缓冲 + 批量写入