应用兼容性规则

有些程序对输入法不太友好：候选框飘到错误的位置、候选窗被盖住看不见、或者你每次进去都要手动切一次英文。这些都靠 compat.toml 里的逐应用规则修正。

文件位置与合并

规则文件为 TOML 的 [[apps]] 数组表，按下面的顺序逐层叠加，靠后的层优先：

用窗口管理，不用手写 0.124 新增

成批查看、修改内置规则、新增、禁用、还原、导入导出，都可以在设置的「高级 → 应用兼容性与独立配置」打开的应用兼容性与独立配置窗口里点着完成，不用手写文件。窗口与右键菜单写的是同一份用户层。

合并语义：字段级叠加，用户层只记差异 0.124 新增

三层按顺序逐字段叠加，靠后的层优先。同名进程（不区分大小写）的规则不是整条替换，而是字段级合并：

• 用户层那条写了的字段，覆盖前面层的值；
• 没写的字段，继承前面层的值——所以你只给 Weixin.exe 写一条 initial_mode，系统层给它的 caret_use_top、stale_probe_guard 照常生效；
• 想取消前面层设的某个字段（回到「跟随全局」），在用户层写 unset：unset = ["caret_use_top"]；
• 想关掉前面层打开的开关，显式写 false；
• 想禁用整条前面层的规则，写 disabled = true（字段保留，整条不生效）。

# 用户层：只记相对系统层的差异
[[apps]]
process = "Weixin.exe"
initial_mode = "english"            # 新增一项，系统层的 caret_use_top 等照旧继承
unset = ["stale_probe_guard"]       # 取消系统层设的这一项

[[apps]]
process = "Dota2.exe"
disabled = true                     # 整条不生效

与系统层一模一样的字段写进用户层会被当成冗余自动丢掉，用户层文件里始终只有真正的差异。设置端应用兼容窗口与右键菜单写的都是这套语义，所以你在菜单里给一个有出厂规则的程序改任何一项，都不会再冲掉它的其它出厂字段。

改完手工编辑的规则后，用功能主菜单的重载配置即可生效——host_render 除外，它需要重启服务。

字段清单

[[apps]]
process = "Weixin.exe"          # 进程名（不区分大小写）
comment = "微信 - Qt WebView 输入框 caret height 不稳定，使用 rect.top 定位"
caret_use_top = true

initial_mode / initial_punct 还接受简写 en / zh。写了个认不出的值等于没写（不干预）——「拼错了」与「想要英文」是两回事，后者必须显式写对才成立。

first_show_mode 同理：认不出的值等于没写，跟随全局的 ui.candidate.first_show_mode（出厂 fast）。其它枚举字段也都是这个规矩——拼错的值不会被悄悄当成对该应用的显式设置。

内置规则

随程序分发的 data\compat.toml 已经为若干宿主预置了规则，装完即生效，不必自己写：

caret_use_top

候选窗默认贴着光标矩形的底边（bottom）显示。某些 WebView 类宿主报告的光标高度不稳定，bottom 就会跟着上下跳，候选窗随之抖动。改用顶边（top）定位可以绕开——top 通常是稳定的。

如果你遇到某个程序里候选窗位置忽上忽下、或总是偏低约一行的高度，可以试试给它加这条规则。

候选窗首显策略

这是三者里最微妙的一项。

背景：宿主插入组合内容后要 reflow 才能给出正确的光标坐标，而 reflow 需要时间——实测首帧 GetTextExt 到稳定值要 85～95 ms。这三档是「快」与「准」之间的取舍。

fast（默认档）

DLL 在首帧 reflow 期间连发几条试探坐标，取第一条与上一轮权威坐标不同的采用——宿主未 reflow 时返回的正是上一轮那个位置，一旦变化即说明新位置已就绪。

连续快速输入时更进一步：直接采信首条（连打不重排，跟手比精确更重要）。

焦点切换或用鼠标移动光标之后，手里那份坐标属于别处，此时自动退回去等真坐标（首帧信任门），不会先错位再跳。

实测：常规连打首帧中位 7 ms，焦点后首帧中位 105 ms 且位置正确；EverEdit 约 3 ms、WPS 约 11 ms 出候选窗。

wait

最准，代价是 85～95 ms 首显延迟——快速连打时候选窗只来得及显示几毫秒，观感「迟钝」。

instant

最快，但只要光标位置变动过（手动移动、换行、文本重排）那个位置就是错的，会先错位显示再跳回。

三个相关的内部选项

它们在 config.toml 的 [ui.candidate] 下，不进设置页，一般不需要动：

应用独立的初始输入状态

initial_mode 与 initial_punct 让特定应用在获得焦点时自动切到指定状态，适合文件搜索框、终端、代码编辑器这类主要输入英文的场景。

[[apps]]
process = "Everything.exe"
comment = "文件搜索框，默认英文"
initial_mode = "english"

最快的设置方式是不改文件：在目标应用里打开功能主菜单 → 应用独立配置，选「初始输入模式 → 英文」。选「跟随全局」即清除该维度的规则。

忽略宿主关闭输入法 0.121 新增

有些应用「操作几下就自动变成英文」，回到输入框也不恢复。根因不在输入法：宿主自己在关全局中英状态。WinForms 的 ImeMode.Disable 与 WPF 的 IsInputMethodEnabled=False 内部都是 ImmSetOpenStatus(false)，关的是全局开关而不是「本控件不接受输入」，于是点一次按钮就被切成英文。

[[apps]]
process = "SomeDotNetApp.exe"
comment = "焦点落到按钮上就把 IME 关掉"
ignore_host_ime_close = true

开启后这类请求不再采纳，中文状态保持不变。只有「宿主主动要关、且你没有按住 Ctrl」这一种情形会被拒绝，所以 Ctrl+Space 一律放行，你仍然可以正常切中英。

菜单入口：在目标应用里打开功能主菜单 → 应用独立配置。

应用独立的候选窗定位 0.121 新增

给光标坐标本就报不准的宿主（自绘控件、坐标系不对、多进程窗口偏移）：把定位方式设成 fixed，候选窗不再跟随光标，位置由你拖一次候选窗设定，此后固定在那里。

[[apps]]
process = "SomeApp.exe"
candidate_position_mode = "fixed"
candidate_x = 800
candidate_y = 1200

坐标每个应用各记一份，互不影响；(0, 0) 表示尚未设定，首次显示落在屏幕默认位置，拖动一次即记住。定位方式在功能主菜单 → 应用独立配置里选，坐标不进菜单——拖候选窗就是设置动作本身。

应用独立的方案 0.123 新增

让某个程序固定用某个方案，或记住它自己上次用的方案。例如写代码时总用拼音、其余场合用五笔；聊天软件里用什么就记住什么：

[[apps]]
process = "Code.exe"
schema = "pinyin"        # 固定：每次切进来都用 pinyin 方案

[[apps]]
process = "Weixin.exe"
schema = "@remember"     # 记住：恢复在这个程序里上次用的方案

• 手动切方案只影响这个程序。 配了 schema 的程序里，用菜单、快捷键或工具栏切方案，都不会改全局方案，也不写 config.toml，其它程序不受影响。固定方案的程序里手切是临时的，离开再回来恢复成规则里的方案；@remember 的程序则记下手切的结果，存在 state.toml，重启后仍然有效。没配 schema 的程序手切方案，行为和以前一样。
• 只在跨程序切入时套用，同一程序里换输入框不重新切，尊重你在程序里的手切。
• 不存在或未启用的方案等于没写。 写了不在 schema.available 里的 ID，这条按跟随全局处理并在日志里警告；以后启用了该方案，规则自动生效。@remember 记下的方案被停用时同理，当作没记过。以 @ 开头的值只认 @remember，别的一律当没写。
• 不会卡住输入。 刚开机方案还没加载完时，先保持当前方案，后台加载好了（且焦点还在这个程序里）再切过去。
• 自动切换只换方案，不动中英状态、不弹状态气泡；中英状态照旧由 initial_mode 管，两者可以叠加。

菜单入口：在目标程序里打开功能主菜单 → 应用独立配置 → 方案。

密码框强制英文按应用 0.123 新增

全局的密码框强制英文默认开启。有的程序会把普通输入框误报成密码框，结果那里始终打不出中文——为此把全局关掉，真正的密码框也就不保护了。现在可以只给那一个程序关掉：

[[apps]]
process = "SomeApp.exe"
comment = "搜索框被误报成密码框"
password_force_english = false

写 true 则反过来：全局关掉时只给这个程序开。不写 = 跟随全局 input.password_force_english。

菜单入口：在目标程序里打开功能主菜单 → 应用独立配置 → 密码框强制英文。

状态提示位置 0.123 新增

Illustrator 这类设计软件报不出光标位置，状态气泡跟随光标时只能沿用上一次拿到的位置，常常停在刚才别的程序里。可以给它单独配一个位置：

[[apps]]
process = "Illustrator.exe"
status_position_mode = "window_bottom_left"   # 这个程序里气泡始终在窗口左下角

或者平时仍跟随光标，只在这一次拿不到光标时才退到锚点：

[[apps]]
process = "Illustrator.exe"
status_fallback_position = "screen_center"

• 定位方式与坐标从同一处取：规则写了 status_position_mode 就用规则自己的 status_x/y，没写才整套用全局的。兜底位置单独回落，没写就跟随全局。
• 规则写了定位方式时，在这个程序里拖动气泡、或右键气泡选「固定位置」「恢复默认位置」，都写进这条规则而不是全局设置。
• 兜底选了锚点后，「焦点切换时显示」在这类程序里等不到光标位置时也会在锚点上弹出（约 0.15 秒后），而不是干脆不显示。
• macOS 上拿不到宿主窗口的边框，window_center / window_bottom_left 分别按 screen_center / screen_bottom_left 处理。

菜单入口：功能主菜单 → 应用独立配置 → 状态提示位置。

钉住组合起点 0.121 新增

WPS 文字与 Word 在一次长组合里，每一帧都把组合起点跟着插入点右移。候选窗的大偏移逃生阀被这份漂移数据一路骗着重锁锚点（实测从真实起点 1830 推到 2591），而删除是逐字的、每步够不到阈值，锚点就永久卡住——表现为「换行后候选窗回不去、删除也回不来」。

pin_anchor_when_start_drifts = true 让锚点钉在首帧起点，首帧的组合起点是对的。

对于能给出组合范围矩形的宿主（协议 v3），锚点直接取矩形的左下角，一个公式同时覆盖单行与跨行，本开关和另外两个「猜」的机制都自动让位。拿不到矩形的路径（旧版 DLL、macOS、宿主正在重排期间）仍然走上面这套。

游戏自己画候选框时

有些程序——尤其是较老的游戏——会自己画候选框，不需要清风再画一个。清风会自动识别这类程序并收起自己的候选框，把位置交给它们：游戏画的候选框贴着它自己的聊天输入框，而全屏游戏通常根本不向输入法报告光标位置，清风猜出来的位置往往是错的（甚至跑到另一个显示器上）。

识别是自动的，正常情况下什么都不用配。

[[apps]]
process = "某程序.exe"
host_drawn_candidates = false

[[apps]]
process = "*"
host_drawn_candidates = false

宿主渲染模式 host_render 0.113 新增

少数宿主运行在受限容器中，或其窗口层级（Band）盖过一切普通窗口，输入法自绘的候选窗被压在下面看不见——Win11 开始菜单 / 任务栏搜索的 SearchHost.exe 就是这样。

host_render = true 让候选窗改由服务进程渲染成位图，经共享内存交给宿主进程内的输入法 DLL 上屏，绕开普通窗口盖不过的 Band 层级。

上屏换行的字符样式 0.122 新增

短语、词条、命令直通的产物里可以带换行。富文本程序的段落边界是 CR，LF 落进去不构成换行；而编辑器、终端、浏览器输入框是「写进去什么就存什么」。全局出厂值是 keep（原样透传，见上屏换行的字符样式），需要转换的程序在这里逐个指定：

[[commit_newline]]
process = "WINWORD.EXE"
style = "cr"

出厂名单只有 WINWORD.EXE。同一次实测里记事本与 WPS 文字都能正常分段，所以 WPS 刻意不在名单上——按「富文本模型」推理会想当然地把它加进来，实测说的是反话。

排查：某个程序里输入法没反应

打开功能主菜单 → 高级 → 输入诊断 HUD，屏幕上会出现一个置顶小浮窗，实时显示当前焦点应用的输入状态与禁用原因（密码框抑制、应用禁用输入等）。

浮窗可拖动，双击可复制内容，便于反馈问题时附上诊断信息。排查完在同一菜单取消勾选即可关闭。

常见原因：

相关阅读

• 菜单功能 · 应用独立配置 —— 不改文件的设置方式
• 外观设置 —— 候选窗的定位方式与布局
• 配置文件与数据目录 —— compat.toml 在目录结构里的位置