改完一行配置点一下部署候选窗弹出来还是老样子——这种我改了但世界没反应的时刻几乎每个折腾输入法的人都遇过。折腾得多了才明白输入法定制不是背配置文件而是先搞清楚这套东西的分层哪一层管按键怎么变成候选哪一层管候选窗长什么样哪一层只是把你的意图翻译成二进制。本文围绕 Rime/鼠须管这套开源输入法引擎从引擎原理讲到方案配置、词库权重、外观皮肤、排错链路和维护方式把我这几年反复踩过的坑整理成一份能直接照着做的定制指南。适合两类人看一是刚装上还没找到配置目录在哪儿的新手二是已经改过几轮、但每次改动都靠试错的老手。1. 先弄清引擎和外壳的分工再动手改配置很多人一开始就扎进 yaml 文件改了半天发现方向不对——因为他不知道自己在改的是引擎还是外壳。Rime 这套东西是拆开设计的核心是一套负责输入逻辑的库外面再套一个跟操作系统输入法框架对接的程序。这两部分各管一摊配置文件也分属两边。我见过最典型的浪费时间的场景是有人想让候选窗变成竖排结果跑去改方案文件里的speller段改了一晚上也没动静。1.1 核心库负责把按键变成候选外壳只负责画窗口核心库的工作是一条流水线拿到一串按键事件先判断当前是中文状态还是英文状态ascii_composer再决定这段输入交给谁处理segmentor然后查词库翻译成一批候选translator最后对这些候选做简繁转换、去重、表情补全之类的加工filter输出给外壳去画。这条链路上任何一环缺了输入法就会表现得很怪——比如删掉punctuator你会发现中文标点全变成了半角符号。外壳那一层就简单多了它拿到一份候选列表和光标位置负责把窗口画在正确的地方、处理鼠标点击选词、跟随系统深色模式。所以判断问题归属有个很实用的口诀候选词不对查方案窗口不对查外观配置。候选排序乱、打不出想要的词、模糊音没生效这些都在方案文件里窗口位置飘、字体太小、配色刺眼这些在外观配置里。分清了这一层你排查问题的搜索范围立刻缩小一半。还有一个容易忽略的点这套引擎是跨平台的同一份方案配置在不同系统上可以用但外观配置完全不同。这意味着你的方案文件是可以跨设备复用的资产值得单独用版本管理存起来外观配置则基本是一次性投入调舒服了就不太会动。1.2 用户目录里的每份文件各管哪一摊事找到用户目录是第一步。在 macOS 上它藏在用户资源库下面图形界面里默认是隐藏的用前往文件夹输入路径才进得去。Windows 和 Linux 上路径不同但目录结构是一致的。进去之后你会看到一堆 yaml第一次看会懵我按改了会影响什么整理一下文件类型作用范围典型改动改动风险全局配置所有方案共享方案列表、候选数量、翻页键中影响面大方案文件单个输入方案按键映射、翻译器、滤镜高写错直接部署失败词典文件单个词库加词、调权重、改编码低但重编译慢外观配置外壳界面皮肤、字体、横竖排低改错只是难看补丁文件覆盖上面任意一项局部覆盖而不动原文件低推荐全走这条运行时状态引擎自己写用户词频、安装信息别手改删掉重建表格里最右边那列补丁文件是重点。新手最常见的坏习惯是直接改原始方案文件改完很爽等方案更新一次所有改动被覆盖干净。正确做法是永远不碰原文件另建一个同名的、带后缀的补丁文件把要改的路径写进去。补丁的语法本质上就是按路径覆盖路径写错了它不会报错只会安安静静地什么都不做——这也是新手最容易被坑的地方。1.3 一次部署背后到底跑了哪些步骤点部署按钮这个动作远比它看起来重。它做的事情大致是扫描目录下所有 yaml做语法解析检查方案之间的引用关系是否成立把文本词库编译成二进制索引文件把编译结果写进一个专门的产物目录最后通知外壳重新加载。也就是说你改的是源文件引擎运行的是编译产物。这两者之间隔着一次部署这就是改了没反应这个问题的全部根源。为什么非要编译因为查词要快。纯文本查词每次输入都得全表扫描几万条的词库根本撑不住。编译之后生成的是带索引的结构按编码前缀直接定位敲第一个字母就能瞬间出候选。代价是编译本身要花时间——小词库一两秒几十万条的大词库可能要十几秒甚至更久。这解释了另一个常见疑惑为什么加了一个词部署之后没生效因为它可能压根没被编进去你得回头看编译日志。一个判断部署是否真的成功的土办法看产物目录里文件的时间戳。如果时间戳没变说明编译中途失败或者压根没触发别在源文件上继续找了。2. 从最小可用方案开始搭而不是从别人的配置抄起网上流传的终极配置大多是从别人那里拷来的成品拿来能用但一旦出问题你就完全看不懂。我的建议是反过来的先写一份能跑的最小方案只包含最基本的字段跑通之后再一项一项往上加。这样每加一项你都知道它带来了什么变化出了问题也能立刻定位到刚加的那行。这个过程慢但只需要走一次。2.1 一份能跑起来的最小方案骨架最小方案要回答四个问题我是谁方案标识和名字、有哪几个开关简繁、中英、标点、按键按什么顺序处理处理链、去哪里查词词典。前三个是骨架第四个是血肉。方案文件开头的元信息段至少要写清楚方案标识、显示名称和版本号标识要跟文件名对应上否则引擎找不到它。处理链是新手最容易写错的部分因为它涉及三个不同的列表顺序不能乱。处理键事件的组件要在前因为它决定这个按键是被吃掉还是往下传分段组件在中间负责把连续输入切成有意义的块翻译组件在后负责出候选滤镜在最后负责加工候选。这三个列表里各组件之间的相对顺序是有讲究的——比如把负责英文分段的那一项放到中文分段前面你的中文输入会全变成英文。下面这份骨架我用了很久可以直接当起点schema: schema_id: my_pinyin name: 我的拼音 version: 1.2 switches: - name: ascii_mode reset: 0 - name: ascii_punct reset: 0 - name: simplification reset: 1 engine: processors: - ascii_composer - recognizer - key_binder - speller - punctuator - selector - navigator - express_editor segmentors: - ascii_segmentor - matcher - abc_segmentor - punct_segmentor - fallback_segmentor translators: - punct_translator - script_translator filters: - simplifier - uniquifierspeller这一项必须放在punctuator前面否则标点符号会被提前吃掉你打不出任何候选fallback_segmentor必须放在分段链的最后它是兜底的一旦前面所有分段都拒绝处理这段输入它就接过来当普通字符处理。这类顺序规则没法靠猜我的经验是先用这套标准顺序跑通再动任何一项之前先备份。2.2 词库文件的格式与权重列的门道词库文件的结构分两半上面是 YAML 格式的元信息中间用三个点号分隔下面才是真正的词条数据。词条一行一条字段之间用制表符分隔不是空格——这一点坑过无数人因为编辑器里看起来几乎一样但用空格分隔会导致整行解析异常。元信息里有个关键设置决定第三列怎么解释按权重排序的时候第三列是数值权重按编码排序的时候第三列是排序辅助符。权重的影响比大多数人想象的大。它是一个整数数值越大同样编码下这个词排得越靠前。但要注意它是在同一个编码内部竞争的跨编码比权重没有意义。实际调权重时我遵循两条经验常用但排在后面的词权重直接拉到明显高于邻居的量级别一点一点加因为用户词频也在参与排序加得太少会被覆盖生僻词宁可不收也别给低权重它占着位置会拖慢候选列表的刷新。还有一个隐形成本词库越大部署越慢首次输入的响应也越吃内存。我自己的做法是把词库分成两层一层是几千条的高频核心词一层是几万条的扩展词扩展词库在方案里作为附加词典挂上去。这样日常改核心词库的时候部署时间只有一两秒迭代速度完全不一样。2.3 部署之后先看日志别靠猜编译失败的时候外壳的表现往往是什么都不发生——不报错、不提示、候选窗照常弹出来只是用的还是旧配置。这种沉默是最坑人的。所以养成习惯每次改完配置部署之后立刻去翻日志。日志文件名里带日期最新的那个就是本次部署的记录出错的时候里面会有明确的文件路径和行号。读懂日志有个技巧从上往下找第一个错误后面的错误大多是它引发的连锁反应。YAML 解析器遇到语法错误之后就放弃整份文件了所以后面报的一堆字段缺失都是假的。定位到第一个错误改掉重新部署再看下一轮。我见过有人对着几十行报错逐条改改到最后发现源头只是第一个文件里少了一个冒号。如果日志干干净净但功能没生效那就是另一类问题了配置解析成功但你的改动被别的配置覆盖了。这时候要顺着补丁覆盖顺序往回查看看是不是有个补丁文件把你要改的路径又改回去了。这种情况在多份补丁共存的时候特别常见尤其是从别处拷来的成品配置里藏着一堆你不认识的补丁。3. 真正拉开体验差距的几项配置骨架跑通之后决定好不好用的就是这几个参数了。它们共同的特点是默认值能用但离好用差得远而且彼此之间有耦合改一个可能要连带调另一个。我把这几年调下来觉得收益最高的几项整理在这儿。3.1 候选数量与翻页方式五到七个是甜点区候选数量这个参数新手往往往大了调觉得一次看到十个很爽。实际用下来超过七个之后视线要横跨半个屏幕眼睛找词的成本反而上升了而且候选窗变大之后在屏幕边缘容易弹出界或者遮挡上下文。我自己的取值是六个横排配合数字键选前六个第七个开始翻页。翻页键的设置也是个细节。默认用减号和等号翻页这两个键在中文输入状态下不容易误触但如果你经常在别的输入法之间切换肌肉记忆会让你去按方括号或者逗号句号。这里有个容易忽略的点翻页键的绑定要在按键绑定组件里配而且要区分只在候选状态下生效和全局生效不然你在打英文的时候按等号会莫名其妙翻页。参数常用取值调大的代价我的建议候选数量5 / 6 / 7视线跨度变大边缘易出界6配合数字直选翻页方式减号等号 / 方括号与编辑器快捷键冲突减号等号避开方括号每页最大候选与候选数量一致翻页次数减少但定位变慢保持一致输入码长度上限4 / 5长码占用识别空间4超长码靠分词还有个小细节值得一提候选数量和你用的方案类型强相关。全拼方案编码长候选多六个刚好双拼方案编码短两三个键就是一个完整音节候选列表会明显变长这时候把数量压到五个反而更顺。这个不是理论推导是把两个值都跑一周之后的身体感受。3.2 模糊音要克制开多了重码会爆炸模糊音的原理是在编码上做变形展开你打出一个音节引擎按规则派生出若干个等价写法逐个去词库查。这个机制叫派生写起来就是一行行的规则形如把开头的某个声母替换成另一个。听起来很美好问题是它的代价是重码数量按乘法增长你每多开一组模糊候选列表长度就可能翻一倍。我踩过的坑是一开始图省事把所有常见的混淆组合全开了前后鼻音、平翘舌、鼻音边音全挂上。结果打一个普通的两字词第一页六个候选里四个是错的得翻两三页才能找到想要的那个。用了三天就受不了了。后来砍到只留两组——只留下我自己真的分不清的那两组——候选列表一下子清爽了。这里的原则很明确只开你打字时真的会打错的那几组不要开以防万一的那几组。另一个常见的误解是把派生和简写混为一谈。派生是双向的你打标准写法能出词打变体也能出词简写是单向的只允许你少打几个字母。两者的效果看起来像但对候选顺序的影响完全不同——简写出来的候选排在后面派生出来的候选和标准写法同权。想让某个高频词打首字母就出来用简写想让某个容易打错的音容错用派生。这两件事别混着做。3.3 自定义短语表把重复劳动一次性消灭这一项是我认为投入产出比最高的定制。邮箱地址、常用回复模板、日期、签名、工单号前缀这些每天都打好几遍的东西配一次能省几年。做法是单独挂一个短语翻译器指向一个独立的短语文本文件格式跟词库一样是制表符分隔的三列但第二列填的是你想要的触发码。配置的结构大概是在翻译器列表里额外挂一个表翻译器并给它起个标签名然后在方案文件里用同名段落配置它的词库路径、是否启用补全、是否允许成句、初始质量。这几个开关的组合很关键——短语表要关掉成句否则你打触发码的时候它会试图把后面的输入拼成一句话补全可以开这样打前两个字母就能看到。短语的触发码设计有讲究。别用a、s这种单字母会跟正常拼音打架我用的是两个不常用字母打头加助记符的组合比如邮箱用yx开头地址用dz日期用rq。这样在正常打字时几乎不会误触需要的时候又能一秒调出。初始质量这个参数要设得明显高于普通词否则它可能排不到第一页。一个使用细节短语表改完之后同样要部署才生效。而且因为它是独立文件部署速度极快改完立刻能用非常适合边用边加的迭代方式。3.4 简繁切换与中英混输的状态管理开关列表的顺序不是随便排的它直接决定了状态栏上按钮的排列顺序也决定了你用快捷键循环切换时的切换序列。我建议把最常用的放在第一位因为很多外壳支持用单个快捷键在第一位和第二位之间来回切。简繁转换依赖一个转换配置它把简体映射成繁体或者反过来。这里有个容易翻车的点转换是在候选生成之后做的滤镜所以它作用在最终展示上不改变词库本身。这意味着如果你同时挂了去重滤镜要注意它们的先后顺序——先去重再转换还是先转换再去重结果会不一样。我一般把转换放在去重之前因为转换后可能出现重复项。中英文混输的处理更微妙。英文状态的切换有两种模式一种是完全切到英文输入所有按键直接透传给应用另一种是临时英文打几个字母后按空格上屏然后自动切回中文。后一种在写代码注释的时候特别好用。配置上要确保英文分段组件和中文分段组件的顺序正确否则会出现打英文出来的是拼音候选这种尴尬。4. 外观定制皮肤参数里那些没写在文档里的规则外观配置是纯外壳层的东西改坏了最多是难看不会让输入法失灵所以这部分可以放心大胆试。但里面有几个约定俗成的规则不知道的话会调得很痛苦尤其是颜色。4.1 颜色值的字节序反着写的十六进制这是外观定制里最大的一个坑。你在配色方案里写的颜色值看起来像常见的十六进制颜色码但它的字节顺序是反的——红色分量在最低位。也就是说你想表达一个偏蓝的颜色按常规写法填进去显示出来会是偏红的。我第一次调的时候对着屏幕愣了十分钟以为自己看错了。正确的理解方式是这个数值按字节从低到高依次是红、绿、蓝带透明度的话再加一个字节。所以你在设计工具里取到的颜色码需要把三个字节倒过来写。实际调的时候我有个更省事的办法先随便填一个部署看效果然后按反了多少去修正两三轮就能到位比在脑子里做字节翻转快。配色方案里要配的项大概有这些背景色、边框色、普通文字色、高亮候选的文字色和高亮背景色、注释文字色、编码文字色。其中高亮候选的背景色和文字色的对比度最影响可读性这一对配不好选中项会看不清。深色主题下我建议高亮背景用中等饱和度的颜色别用纯色纯色配白字看久了眼睛累。4.2 候选窗布局横排竖排、内嵌还是浮动横排还是竖排这个选择跟你的使用场景强相关。横排占的垂直空间小适合宽屏和长文档编辑竖排视线移动距离短适合快速选词。但竖排在候选多的时候会挡住下方内容尤其是候选窗出现在屏幕下半部分的时候。我自己的选择是横排加内嵌编码这样视线基本不用离开输入位置。内嵌编码这个选项值得单独说。开启之后你打的拼音会直接显示在应用的光标位置而不是画在候选窗里。好处是视觉上更连贯坏处是在某些应用里会跟应用自己绘制的内容打架出现重影或者位置偏移。如果你的主力编辑器里出现这个问题把它关掉就行别怀疑是配置写错了。字体大小和行距这两个参数要一起调。字号调大之后如果行距不变候选窗会显得很挤反过来行距调大了字号不变又会有种空旷感。我的经验值是行距比字号多出四到六个点视觉上比较舒服。边框圆角这种纯装饰性的参数就随意了但要注意圆角太大会让候选窗看起来不够利落尤其是在小尺寸下。还有一点这些外观参数在不同系统上的键名可能不一样甚至同一个外壳的不同版本之间也会有差异。所以从网上抄配置的时候先确认对方的版本抄过来之后如果发现某个键没生效八成是键名对不上而不是值写错了。5. 按症状排查那些改完不生效的真实原因这部分是我最想写的因为前面所有内容都可以在文档里查到唯独排错经验查不到。下面这几类问题我都反复遇到过按症状整理方便你对号入座。5.1 YAML 语法的三类隐形杀手缩进、冒号、编码YAML 看起来比 JSON 友好但它的容错其实更差因为它靠缩进表达层级而缩进错误在某些情况下不会报错只是让某个字段被解析到了错误的位置。第一类杀手是制表符编辑器里按一下 Tab 看着跟空格一样但解析器遇到制表符会直接报错或者行为异常。养成习惯把这个目录下的 Tab 全部替换成两个空格。第二类杀手是冒号后面必须有空格。写成键:值这种紧凑格式整行会被当成一个普通的字符串而不是键值对。这种错误最阴险的地方在于它不报错只是那个配置项悄悄失效了。我踩过最惨的一次是一个包含多个键的段落里有一行漏了空格导致整个段落的层级判断出错排查了快一个小时。第三类杀手是编码和不可见字符。文件必须是 UTF-8 无 BOM从网页上复制粘贴配置的时候经常会带进来全角空格、中文冒号、零宽字符这些东西。肉眼完全看不出来但解析器会晕。我的做法是任何从外部拷来的配置先过一遍纯文本编辑器把不可见字符删干净再粘进去。症状大概率原因快速验证方式部署没反应日志无新内容文件没保存或存到了别的目录看文件修改时间日志报解析错误指向某一行该行缩进或冒号有问题检查该行前后两行的缩进层级某个字段改了没效果键名拼错或被补丁覆盖搜索该键名出现在几个文件里整个方案消失方案标识与文件名不一致核对标识字段和文件名候选全变成英文分段组件顺序错了对照标准顺序逐项核对5.2 改了没生效缓存、补丁路径与重载顺序排除了语法问题之后第二大类就是逻辑上没生效。这种情况我总结出三个最常见的原因按出现频率排序。第一个是忘了部署。这听起来很傻但确实是最高频的。尤其是你改的是补丁文件补丁文件的改动同样需要部署才会被合并进去。我现在养成了一个条件反射改完任何 yaml鼠标先去点部署再回来看效果。第二个是补丁路径写错。补丁的键是文件标识加路径的拼接形式格式上差一个斜杠、差一个层级它都会静默失败。写补丁的时候我的做法是先只写一个最简单的覆盖项确认它生效了再往上加更多项。这样至少能先验证路径前缀是对的。第三个是改了被另一个补丁覆盖回去。多份补丁同时存在的时候合并顺序是有先后的后合并的会覆盖先合并的。如果你从别处拷了一份配置过来它里面可能藏着一个把你刚改的项改回去的补丁。排查方法是全局搜索这个键名看它出现在哪几个文件里。5.3 词频越用越乱用户词典的清理与重建用久了之后会出现一种奇怪的现象某些明显打错的词反而排到了第一位。这是因为用户词典在你每次选词的时候都在学习而你某次手滑选错了一个词它的权重就被抬高了而且很难自然衰减下去。这不是 bug是设计如此。解决办法有两个层次。轻度的做法是在候选列表里对着那个词按下组合键把它降权甚至删除引擎会记住这个负反馈慢慢就压下去了。重度的做法是直接把用户词典文件删掉下次部署时重建——代价是所有个性化词频清零需要重新养一段时间。我一般先用轻度方案连续几次都压不下去才动重度方案。还有一种情况是词库里本身就有重复条目或者同一个词在不同词库里出现权重叠加之后异常靠前。这种问题在合并了多个来源的词库时特别容易出现。排查方法是把那个词单独拿出来搜一遍看它在几个文件里出现、各自的权重是多少。6. 多设备同步与配置的长期维护配置调舒服之后真正的挑战才刚开始换电脑了怎么办家里和公司两台机器怎么保持一致某次改动之后整体变差了怎么回退。这些问题在第一次调配置的时候想不到第二次就全是痛点。6.1 同步目录的搭建与冲突处理同步机制的原理值得先搞清楚它不是把你的用户词典文件直接拷来拷去而是把用户词典导出一份文本形式的快照放到同步目录里换到另一台设备上再从快照导入。中间多这一道文本化的原因是二进制文件没法做增量合并而文本可以。配置上要做的是在安装信息文件里指定同步目录然后每台设备给一个不同的设备名——设备名重复会导致快照互相覆盖。设置好之后手动触发一次同步去同步目录确认快照文件生成了再在另一台设备上导入。整个流程走通一次之后后续只需要定期触发。冲突处理这块要有心理预期两台设备都改了词频同步时是没法自动合并的只能以某一份为准。所以我的实际做法是只让主力设备积累词频其他设备只同步配置。配置文件的同步我用了更朴素的办法——用版本管理工具管起来比目录同步更可控。6.2 用版本管理管住配置目录这是我最后悔没有早点做的事。配置目录里真正需要版本管理的只有那几个手写的 yaml 和词典文件编译产物、用户词典、日志这些东西都应该排除在外。写一个忽略规则把它们排掉剩下的文件总共也就几十 KB提交和回滚都是瞬间的事。有了版本管理之后改动的方式完全变了想试一个新的模糊音规则先提交一个基线改完部署试两天不行就回滚。这种随时可以试错的心态会极大加快你找到最舒服配置的速度。而在没有版本管理之前每次大改我都要先手动备份一份压缩包改坏了再解压回去麻烦到根本不想试。我在实际操作中的体会是配置这件事没有终点。用了半年之后你对输入的习惯会变比如开始写更多英文技术文档就需要调中英切换的手感开始处理更多繁体材料简繁转换的位置就要往前挪。所以与其追求一次性配到位不如把配置目录当成一个持续迭代的小项目隔几个月翻出来看一次把用不上的规则删掉把新冒出来的重复劳动加成短语。每次清理完打字的手感都会好上一截。