配置文件与数据目录

数据的两层结构、目录职责、覆盖机制、三层合并，以及按域组织的完整配置项参考

高级主题

普通用户通过设置工具即可完成全部配置，修改即时生效。本分类面向需要手动放置文件、编辑 config.toml、或查阅每个配置项确切含义的用户。

数据的两层结构

清风输入法把数据分成系统预置与用户数据两层，用户数据又按"是否随账户漫游"拆到两个系统目录：

目录	角色	升级行为
`<安装目录>\data\`（安装版） `<解压目录>\data\`（便携版）	程序自带的系统预置数据，只读	随安装包整体替换
`%APPDATA%\WindInput\`（漫游用户数据）	配置、词库、自定义主题 / 方案等个人化内容	升级时不清理，仅卸载时手选"删除用户数据"才删除
`%LOCALAPPDATA%\WindInput\`（本机数据）	词库编译缓存、日志、运行时状态等本机产物	升级时不清理；缓存可安全删除，会自动重建

%APPDATA%（漫游）放换机也想带走的东西；%LOCALAPPDATA%（本机）放与这台机器绑定、可重建的东西。便携版没有这种拆分，两处都指向解压目录下的 userdata\。

不要在程序目录存放个人文件

安装版升级时会先卸载旧版再安装，安装目录（默认 C:\Program Files\WindInput\）及其 data\ 子目录下的文件都会被清理重写。所有个人化内容请放入用户数据目录，升级时不会被清理。

同结构覆盖机制

%APPDATA%\WindInput\ 与程序 data\ 目录采用相同的子目录结构。两侧存在同名文件时，用户数据目录中的文件优先生效。因此你可以在漫游目录下放同名文件来覆盖内置版本，而无需修改程序目录里的任何文件——程序目录在升级时会被整体替换，放在那里的修改一定会丢。

覆盖是整份文件替换，不是逐项合并：一旦用户目录存在同名文件，内置那份就完全不参与。所以正确做法是先把内置文件复制过来再改，而不是只写你想改的那几行。

例外：config.toml 与 compat.toml 是合并的

只有这两个配置文件采用逐项合并（用户文件只需写想改的项，其余跟随内置默认值）。其余文件一律整份替换。

可以覆盖哪些文件

下表路径相对于两个目录根（程序 data\ 与 %APPDATA%\WindInput\）。

文件	作用
`schemas\<方案ID>.schema.toml`	方案定义。放同名文件即可改内置方案的词库列表、码长等固定参数
`schemas\<方案>\<词库>.dict.yaml`	词库。也可只放编译好的同名 `.wdat` 而不带源文件
`schemas\common_chars.txt`	通用规范汉字表，决定候选过滤（`filter_mode`）中"常用字"的判定范围
`schemas\shuangpin\<布局>.toml`	双拼布局定义，可改键位映射或新增布局
`schemas\<方案>\unigram.txt`	拼音长句打分用的语言模型（由方案的 `unigram_path` 指定）
`schemas\` 下的拆字库与字根字体	由方案 `[engine.chaizi]` 的 `db_path` / `font_path` 指定，见拆字配置
`themes\<主题名>\theme.toml`	主题。同名目录覆盖内置主题
`system.phrases.toml`	系统短语的初始内容，见下方说明
`pinyin_map.txt`	汉字读音表，用于逐字拼音反查与编码提示

data\opencc\（简繁转换表）不支持覆盖，它随程序版本整体更新。

覆盖 system.phrases.toml 只改「初始内容」

系统短语在首次启动时从这个文件读入用户数据库，之后一切增删改都以数据库为准。覆盖这个文件会改变系统短语的初始集合（内容变化时会同步进库），但你在设置工具里对单条短语的修改仍然只存在数据库里，不会回写任何文件。日常增删短语请用自定义短语页的方法。

确认覆盖是否生效

覆盖没有任何界面提示，但每一次生效的覆盖都会记进日志。打开 %LOCALAPPDATA%\WindInput\logs\ 下的最新日志，搜索 用户覆盖生效：

用户覆盖生效[data]: system.phrases.toml → C:\Users\你\AppData\Roaming\WindInput\system.phrases.toml
用户覆盖生效[dict]: wubi86/wubi86_jidian.dict.yaml → ...

方括号里是资源类别（schema 方案 / dict 词库 / resource 方案资源 / shuangpin 双拼布局 / theme 主题 / data 数据根文件）。默认日志级别即可看到，无需调级别。

日志里没有对应记录，说明你的文件没被认到——常见原因是路径层级或文件名不对（必须与 data\ 下的相对路径完全一致），或者放进了 %LOCALAPPDATA% 而不是 %APPDATA%。

生效时机与撤销

放置或修改覆盖文件后需要重启输入法（system.phrases.toml、pinyin_map.txt、common_chars.txt 必须重启服务；方案、词库、主题也可在设置工具里刷新 / 重建缓存）。程序不监视这些文件的变化。

撤销覆盖只需删除用户目录里的那一份，内置版本自动重新生效。

覆盖内置方案文件后，请不要在设置工具里点「删除」

用户目录一旦存在与内置方案同名的 .schema.toml（如 wubi86.schema.toml），设置工具的方案列表会把它识别为用户方案并允许删除。此时点删除虽然只删掉你的覆盖文件（方案本身会回到内置版本），但会一并清空该方案的自定义词、词频与候选调整数据。

要撤销这类覆盖，请直接到 %APPDATA%\WindInput\schemas\ 删除那个文件。

漫游数据目录（`%APPDATA%\WindInput\`）

%APPDATA%\WindInput\
├── config.toml                    # 用户全局配置（diff 保存，仅含与默认值不同的字段）
├── userdata.redb                  # 用户数据库（自定义词、词频、置顶/删词、短语等）
├── compat.toml                    # 用户自定义的应用兼容性规则
├── system.phrases.toml            # 覆盖内置系统短语的初始内容（可选）
├── schemas\                       # 输入方案与方案级词库
│   ├── pinyin.schema.toml         # 方案配置（同名即整份替换内置方案）
│   ├── wubi86.schema.toml
│   ├── my_schema.schema.toml      # 自定义新方案
│   └── <方案词库>.dict.yaml        # 方案引用的 RIME 词库（YAML 格式）
├── schema_overrides\              # 设置工具写入的方案差异项（程序维护）
│   └── <方案ID>.toml
└── themes\                        # 自定义主题
    ├── default\theme.toml         # 覆盖内置主题（可选）
    └── <自定义主题名>\theme.toml   # 新增第三方主题

文件 / 目录	职责
`config.toml`	全局配置。采用 diff 保存，只写与系统默认不同的字段
`userdata.redb`	用户词库、词频、候选调整、短语等用户数据（程序维护，勿手改）
`compat.toml`	应用兼容性规则（应用级候选定位规则也在此，不在 `config.toml`）
`system.phrases.toml`	覆盖内置系统短语的初始内容；日常增删短语走设置工具，存数据库
`schemas\*.schema.toml`	用户方案。与程序 `data\schemas\` 同名时整份替换内置方案，也可放全新方案
`schemas\*.dict.yaml`	方案引用的 RIME 词库，第三方词库文件也放同目录
`schema_overrides\<方案ID>.toml`	设置工具写入的方案差异项（附加词库开关、双拼布局等），深合并到方案文件之上（程序维护，一般无需手改）
`themes\<主题名>\theme.toml`	用户主题（TOML 格式），同名目录覆盖内置主题

config.toml 只有几行是正常的

diff 保存下，用户配置文件可能只包含 version = 1 和少量字段——只保存了与默认值不同的项，未改动的字段会自动跟随系统默认值的更新。

本机数据目录（`%LOCALAPPDATA%\WindInput\`）

%LOCALAPPDATA%\WindInput\
├── cache\        # 词库编译缓存（.wdat），可安全删除，下次自动重建
├── logs\         # 运行日志
└── state.toml    # 运行时状态（工具栏位置、上次中英/标点模式等）

文件 / 目录	职责
`cache\`	词库编译缓存，可安全删除，会自动重建
`logs\`	日志文件，默认日志目录
`state.toml`	运行时状态（上次中英/标点状态、工具栏位置等，程序维护，勿手改）

手工编辑 config.toml

全局配置为 TOML 格式，用户配置文件首行带版本号 version = 1。方案配置（*.schema.toml）也是 TOML；RIME 词库文件（*.dict.yaml）为 YAML 格式。

配置采用三层合并，优先级从低到高：

代码默认值 — 程序内置默认配置
系统预置配置 — 随程序分发的 data\config.toml
用户配置 — %APPDATA%\WindInput\config.toml

三层深合并：表递归合并（高层键覆盖 / 新增低层同名键），标量与数组由高层整体覆盖。保存时按 diff 只写与默认不同的字段。

本参考页的默认值以系统预置为准

下面各域参考页标注的"默认值"，取自随程序分发的 data\config.toml（第 2 层）。少数字段的代码内置默认值（第 1 层）与之不同，会在对应条目上注明——你实际拿到的是系统预置值。

也可以用命令行读写配置，无需手动编辑文件：

wind_input config get ui.candidate.per_page
wind_input config set ui.candidate.per_page 9
wind_input config describe ui.candidate.layout

见命令行工具 · config。

配置项分域参考

配置按七个正交大类组织，逐域列出每个配置项的类型、可选值、默认值与含义：

域	内容	参考页
`[schema]`	方案选择与全局引擎配置（码表 / 拼音 / 混输 / 调频 / 造词）	方案与引擎配置
`[input]`	输入行为：标点、智能符号、配对、临时英文 / 拼音、网址、简繁、命令栏	输入行为配置
`[keys]`	全部按键：切换、选择 / 翻页 / 以词定字、功能快捷键、全局热键	按键配置
`[ui]`	外观：候选窗、字体、主题、模式指示、悬停提示、状态气泡、工具栏	外观配置
`[stats]` `[compat]` `[debug]`	输入统计、宿主渲染白名单、日志调试	统计、兼容与调试

改配置的另外两条路

除手工编辑外，设置工具提供图形界面（覆盖绝大多数常用项），命令行 config 可脚本化读写。功能页面只讲"这个功能怎么用"，配置项的确切键名与取值一律查本分类。