文件管理

元书将 RIME 文件分别保存在“应用”“键盘”和“iCloud”三个位置。三者用途不同，并不会持续实时同步。

这三个位置中的文件会在执行“重新部署”“同步”或“复制文件至 iCloud”时按规则流转。

文件目录

目录	所在位置	主要用途	访问限制
应用	元书应用沙盒	应用读写文件位置	可通过系统“文件”App、Textastic 等支持文稿目录的第三方应用访问
键盘	App Group 共享容器	键盘读写文件的位置，键盘使用中产生的自造词、调频数据等会存储在这里	其他应用不能直接访问；需通过元书内置文件管理功能操作
iCloud 文件	iCloud 云盘中的元书目录	应用不会主动写文件到此位置，默认的备份功能会将备份文件存储在此位置	受 iCloud 登录状态、网络和文件下载状态影响

「键盘」下的文件是「应用」下文件的镜像。执行 RIME 的「重新部署」或「同步」时，元书会将「应用」下的文件复制到「键盘」中，供键盘使用。

此复制过程会先删除「键盘」中的文件，再将「应用」下的文件复制到「键盘」中。

为什么要分「应用」和「键盘」两个路径

之所以同时保留「应用」和「键盘」两个镜像路径，是因为 iOS 的键盘无法访问元书的「应用」目录。

（你可以把键盘看作是一个独立的应用。iOS 中两个独立的应用无法直接访问彼此的文件，必须通过 App Group 机制共享文件。）

同时，元书目录又需要能够被外部文件工具编辑。

所以元书采用了两个不同的目录：「应用」目录供外部工具访问，并在「部署」或「同步」时，将元书的「应用」文件复制到「键盘」目录。

如果需要保留键盘生成的文件，怎么办？

上面提到，在执行「部署」「同步」时，会先删除「键盘」下的文件，再将「应用」文件复制到「键盘」。

问题：如果键盘在使用过程中修改或新建了文件，那么每次「重新部署」或「同步」都会丢失这些文件，怎么办？

元书在 Rime 页面下有一个「禁止复制键盘文件」选项，默认是关闭的。

（如果你的方案没有需要保存的键盘文件，可以开启这个选项，以减少无用的判断逻辑。）

当这个选项关闭时，元书在「部署」「同步」前，会先将部分「键盘」文件复制到「应用」目录；这里不会复制所有键盘文件。

具体复制哪些「键盘」文件？这由 include_keyboard_rime_files.txt 控制（详情见从键盘复制文件）。

这里需要特别注意键盘方案目录根路径下的 userdb。

userdb 是 LevelDB 数据库文件目录。为了保证数据库文件的完整性，元书会先删除「应用」下的 userdb 目录，再将「键盘」下的 userdb 复制到「应用」中。

上面所说的先删除 userdb 再复制，是指方案根目录下的 userdb；其他位置的 userdb 不会先删除再复制。

如果我想从 iCloud 上复制文件，怎么办？

元书每次执行「重新部署」或「同步」时，都会先将 iCloud 中的文件复制到「应用」目录。这是默认行为，无法通过选项关闭。

需要注意的是：

从 iCloud 上复制文件到「应用」这个行为会受 exclude_iCloud_rime_files.txt 文件影响（详情见从 iCloud 复制方案文件）。
不要在 iCloud 中存储 userdb 这类数据库文件。由于受到系统同步、网络等因素的影响，文件可能发生冲突，或者尚未完成下载或上传，从而导致数据库文件受损。

三个位置存在同名文件时，部署或同步后哪个文件会生效？

文件的最终内容取决于以下三个条件：

是否开启「禁止复制键盘文件」；
文件是否匹配 exclude_iCloud_rime_files.txt 中的排除规则；
文件是否匹配 include_keyboard_rime_files.txt 中的包含规则。

处理时，元书会先按排除规则将 iCloud 文件复制到「应用」，再按包含规则将「键盘」文件复制到「应用」。因此，如果两次复制都执行，后复制的「键盘」文件会覆盖 iCloud 文件。

排列组合全部条件，最终生效的文件结果如下：

禁止复制键盘文件	匹配 iCloud 排除规则	匹配键盘包含规则	最终生效的文件
开启	是	不影响结果	「应用」中原有的文件
开启	否	不影响结果	iCloud 文件
关闭	是	是	「键盘」文件
关闭	是	否	「应用」中原有的文件
关闭	否	是	「键盘」文件
关闭	否	否	iCloud 文件

开启「禁止复制键盘文件」后，元书不会从「键盘」复制文件，因此 include_keyboard_rime_files.txt 不影响结果。详细的处理顺序请参阅工作机制。

工作机制

“重新部署”和“同步”使用相同的文件准备流程：先确保所需的 iCloud 文件已经下载，再依次把 iCloud 文件和键盘产生的数据合并到应用文件。RIME 操作结束后，应用文件会整体回写到键盘目录。

flowchart TD
    start([点击“重新部署”或“同步”]) --> checkCloud{相关 iCloud 文件是否为最新状态？}
    checkCloud -->|否| requestDownload[监听 iCloud 元数据并请求下载]
    requestDownload --> downloadDone{文件是否已下载完成？}
    downloadDone -->|否，且仍有进度| requestDownload
    downloadDone -->|长时间无进度| timeout[提示下载超时，可选择跳过 iCloud]
    timeout --> prepare
    downloadDone -->|是| prepare[准备应用文件目录]
    checkCloud -->|是| prepare
    prepare --> cloudToApp[按排除规则复制 iCloud 文件到应用文件]
    cloudToApp --> keyboardEnabled{是否允许复制键盘文件？}
    keyboardEnabled -->|是| removeUserdb[删除所选方案中应用侧的 userdb]
    removeUserdb --> keyboardToApp[按包含规则复制键盘文件到应用文件]
    keyboardEnabled -->|否| chooseAction
    keyboardToApp --> chooseAction{本次操作}
    chooseAction -->|重新部署| deploy[执行完整维护与重新部署]
    chooseAction -->|同步| sync[执行完整维护并同步 RIME 用户数据]
    deploy --> appToKeyboard[将应用侧 RimeSharedSupport 和 RimeUserData 整体回写到键盘目录]
    sync --> syncSuccess{RIME 同步是否成功？}
    syncSuccess -->|是| appToKeyboard
    syncSuccess -->|否| failed([显示同步失败，不回写])
    appToKeyboard --> finish([更新键盘并完成])

1. 等待 iCloud 文件就绪

执行“重新部署”时，元书会检查 iCloud 文件/RimeUserData；执行“同步”时，还会同时检查当前 RIME 同步目录。只要发现文件尚未下载或不是最新状态，元书便会监听 iCloud 文件状态并主动请求下载，待相关文件全部变为最新状态后再继续。

如果下载持续推进，等待计时会随进度刷新；若长时间没有进度，元书会停止等待并提示超时。用户选择跳过 iCloud 后，本次操作将直接使用设备上已有的本地文件，因此未下载的新版本不会参与本次合并。

2. iCloud 文件合并到应用文件

iCloud 文件就绪后，元书将 iCloud 文件/RimeUserData 复制到 应用文件/RimeUserData。这是覆盖式合并：命中排除规则的文件不会复制；其他文件若在目标位置已存在，会先删除旧文件再复制新文件。

复制规则由 exclude_iCloud_rime_files.txt 控制。该步骤属于“重新部署”和“同步”的固定流程，不能单独关闭。

3. 键盘数据合并到应用文件

当“RIME → 禁止复制键盘文件”处于关闭状态时，元书会：

删除应用文件中当前所选方案目录下以 userdb 结尾的目录；
按 include_keyboard_rime_files.txt 的包含规则，将匹配的键盘文件复制到应用文件。

先删除应用侧 userdb 再复制，可以避免旧数据库残留与键盘侧数据混合。若开启“禁止复制键盘文件”，这两个步骤都会跳过。

4. 执行 RIME 操作

文件准备完成后，元书以应用文件作为用户数据目录启动 RIME：

“重新部署”会执行完整维护和部署，然后关闭 RIME；
“同步”会先执行完整维护，再调用 RIME 用户数据同步。只有同步返回成功，后续回写才会继续。

5. 应用文件回写键盘文件

操作成功后，元书会用应用侧的 RimeSharedSupport 和整个 RimeUserData 替换键盘侧对应目录，并更新键盘重启时间。键盘下次启动时即可使用最新方案和数据。

从 iCloud 复制方案文件

排除规则

应用文件/RimeSharedSupport/exclude_iCloud_rime_files.txt 是 iCloud → 应用文件的排除列表。

每个非注释行都是一个正则表达式；当文件路径匹配某条正则表达式时，该文件不会被复制。

默认内容如下：

1
# 此文件用来控制从 iCloud 中复制文件的行为
2
# #符号为注释
3
# 其余内容每一行为一个正则表达式，匹配正则表达式的 iCloud 文件「不会」复制到应用目录
4
# 注意：匹配正则表达式的 iCloud 文件「不会」复制到应用目录
5

6
.*[.]userdb.*$
7
.*[/]installation[.]yaml$

.*[.]userdb.*$：排除路径中包含 .userdb 的文件；
.*[/]installation[.]yaml$：排除以 /installation.yaml 结尾的文件。

从键盘复制文件

包含规则

应用文件/RimeSharedSupport/include_keyboard_rime_files.txt 是键盘文件 → 应用文件的包含列表。

只有匹配正则表达式的文件才会被复制。

默认内容如下：

1
# 此文件用来控制复制键盘文件的行为
2
# #符号为注释
3
# 其余内容每一行为一个正则表达式，只有匹配正则表达式的键盘文件才会复制到应用目录
4

5
.*[.]userdb.*$
6
# 如果您使用 txt 类型自造词，可以取消此屏蔽
7
#.*[.]txt$

.*[.]userdb.*$：复制路径中包含 .userdb 的文件，即 RIME 自造词数据库；
.*[.]txt$：复制所有 .txt 文件。该规则默认被注释；使用 TXT 格式自造词时可取消注释。

将应用文件复制到 iCloud

RIME 菜单中的“复制文件至 iCloud”会将当前所选方案目录下符合规则的文件复制到 iCloud 文件/RimeUserData。

“所选方案目录”由“输入方案 → 方案目录切换”控制，默认为 RimeUserData/rime-ice。复制范围由 include_iCloud_rime_files.txt 控制：它采用包含列表机制，只有路径匹配其中正则表达式的文件才会复制；目标位置存在同名文件时会被替换。

与“重新部署”“同步”开始时自动执行的 iCloud → 应用文件复制不同，“复制文件至 iCloud”是由用户主动触发的反向复制操作。

正则规则的解析方式

三个规则文件遵循相同格式：

每行一个正则表达式；
行首为 # 的行会被忽略；
无法解析的正则表达式会被忽略；
正则表达式匹配的是源文件完整路径，而不只是文件名。

常见问题

键盘无法保存自造词

最常见的原因是没有开启键盘的“完全访问”权限。开启后若仍无法保存，请继续检查当前方案是否启用了自造词功能。

键盘生成的自造词无法进入应用文件

请依次检查：

键盘能否正常保存自造词；
“RIME → 禁止复制键盘文件”是否处于关闭状态；
include_keyboard_rime_files.txt 是否包含自造词文件对应的正则表达式；
使用 TXT 自造词时，是否已经启用 .*[.]txt$ 规则；
修改规则后，是否重新执行了“重新部署”或“同步”。

如何将键盘文件复制到应用目录

在 include_keyboard_rime_files.txt 中添加相应的正则表达式，然后执行“重新部署”或“同步”。元书会把命中规则的键盘文件合并到应用目录。

修改应用文件后，键盘为什么没有变化

应用文件不是键盘的实时工作目录。修改完成后，请执行“重新部署”或“同步”，让元书处理方案并将结果回写到键盘文件目录。