[讨论稿] 把按键、触发、动作拆成三根正交轴 —— 接着 #2220 补上「动作命名另议」

[x4w2nyhvk8]

接续两贴：#1434 关于下一代同文主题设计规范的讨论 与 #2220 把「位置 + 功能命名」落成可校验的路径式色表。#2220 §8 的示例末尾写着「动作命名另议，本稿只谈取色」——这一稿补的就是那半边：按键、触发时机、动作的统一命名。

先说明边界：这是个人整理的讨论稿，不是 PR，也不代表维护者意见。文中的 key.* / event.* / action.* / when: 与受控词表，当前 Trime 全部不支持；目的只是把 #1434 已提出的原则，在按键与动作这一侧也写成一份可以被逐条反驳的具体方案。若方向不合官方路线，请直接指出，我据此收敛。

事实来源仍只有一个：引擎源码。 源码数字以我阅读时的 develop 分支为准：KeyBehavior.kt 13 个触发时机、KeyAction.kt 16 个平行字段、ColorKey.kt 52 个颜色枚举 / 49 条内置回退链、GeneralStyle.kt 58 个 style 字段。§5 会横向参照其他输入法的按键/动作写法，但只比较结构取舍，不作为任何字段或取值的依据；若官方认为横向对比不宜进规范，整节删去也不影响其余各节。

---

1. 为什么接着 #2220 说

#2220 把「颜色」收进了 color.<domain>[.<sub>].<part>[.<class>][.<state>] 这一条路径，键定义里不再出现颜色。但按键本身仍留着三处老问题，和当时颜色侧「同一对象多种写法」是同一种病：

1. 替身键：Return / Return1 / Return2、space / space1、Shift_L3、BackSpace2，同一颗键因为所在键盘、行宽、大小写不同就复制一份定义；bh1~bh4 更是把行号写进了名字。
2. 事件与动作挤在一个对象里：preset_keys 的一项里，click / long_click / swipe_up 是触发槽位，command / option / select / toggle / commit 是动作字段，label / hint 是显示，send 又是发给引擎的按键——全是平级字段，没有层次。
3. 动作没有词表：CommonKeyboardActionListener 用 when (action.command) 对 snake_case 字符串字面量分派，全仓没有动作枚举。多一个功能就多一个字符串，写错了不报错、只是不生效。

本稿只做一件事：把「这颗键是谁 / 什么时候触发 / 做什么」拆成三根互不越界的轴，各配一份受控词表，并对齐源码消费点。 颜色仍按 #2220，本稿不重复。

2. 一个前提：别拿配置样本当词表，也别拿别家实现当依据

现有主题里出现过哪些键名、哪些动作，是散在 KeyAction.kt、KeyBehavior.kt、CommonKeyboardActionListener.kt、内置 trime.yaml 和 doc/trime-schema.json 里的。以某份流行主题为样本来定规范，样本没写的就会漏——#2220 提过我最初这么做漏了 12 个源码字段，动作侧同理。

引擎侧动作其实是三种形态并存，这也决定了「统一」不是改拼写、而是换编址方式：

形态	源码位置	特点
16 个平行字段	KeyAction	command / option / select / toggle / commit / send …，加功能就加字段
字符串命令分派	CommonKeyboardActionListener 的 when (action.command)	liquid_keyboard / select_all / share_text 等字面量，无枚举约束
13 个触发枚举	KeyBehavior，由 Key 逐一 bind	唯一已经是封闭集合的一层，可直接沿用

所以规范里的「动词」是主题侧新抽象，不是整理已有枚举。这一点我在稿里如实标出来，不假装引擎已经支持。

3. 三根正交轴

key.<domain>.<name>       行为 ID：这颗键是谁
event.<verb>              触发时机：什么时候（YAML 字段名，保留 snake_case）
action.<domain>.<verb>    动作动词：做什么，可带 params

轴	词表规模	与源码的对应	不承载什么
key	8 域 / 26 名（key_domain ⊆ action_domain，由校验强制子集关系）	preset_keys 表名 + 数组位置	颜色、位置、动作、状态
event	13 项	逐项等于 KeyBehavior 的 13 个枚举小写化，Key 里逐一 bind	动作内容
action	9 域 / 39 动词	三种形态的归集，见 §7 的接线分档	视觉外观

event 13 项里，后 4 项 composing / has_menu / paging / ascii 是同文特有的状态条件型触发（按 Rime 运行时状态挑 KeyAction），不是手势也不是时序。这一层源码本来就是封闭的，规范直接沿用，不新造。

沿用 #2220 §8 的 keys / layouts 结构，补齐动作侧后是这样（纯示意，当前引擎不认）：

trime_version: 5
keys:
  - id: key.edit.space
    class: space
    attributes: [repeatable]
    action: { name: action.text.commit, params: { text: " " } }
    when:
      long_click:   { name: action.system.showImePicker }
      swipe_left:   { name: action.edit.moveCursor, params: { axis: x, continuous: true } }
      double_click: { name: action.modifier.toggleCapsLock, produces_state: locked }
    label: ______
    geometry: { row: 3, col: 3, span: 3 }

三个要点：

• when: 是一张映射，不是一堆后缀字段。加一种触发时机 = 词表加一行 + when 加一键，不需要给每颗键新增一列。
• class 与动作产出的 state 正是 [讨论稿] 把「位置 + 功能命名」落成可校验的路径式色表 —— 接着 #1434 提一份具体方案 #2220 色表路径的末两段，两稿在这里接缝：event.swipe_left → action.edit.moveCursor → state: pressed → color.key.background.space.pressed。因此词表必须统一放一份并双向校验，拼错一个词两侧同时失效。
• key.* 只标识身份。同一颗空格键在 26 键、数字键盘、fixed_key_bar 里都是 key.edit.space，差异交给 label / geometry / class / when，替身键随之消失。

4. 大小写：不是规则不齐，是五层投影

讨论中常被问到「为什么一会大写一会小写」。把同一个概念在各层的合法拼写摊开，会发现那是序列化器转换的结果，跨层不可比、层内必须齐：

层	例子	规则	由谁产生
Kotlin 枚举	SWIPE_UP / KEY_SYMBOL_COLOR	UPPER_SNAKE	源码声明
Kotlin 字段	swipeUp / isLabelUppercase	lowerCamel	源码声明
YAML 字段	swipe_up / label_transform	snake_case	YamlNamingStrategy.SnakeCase 自动转
枚举转 YAML 键名	KEY_SYMBOL_COLOR → key_symbol_color	name.lowercase()	ColorKey
规范 token	event.swipe_left / action.edit.moveCursor	点分路径 + 段内 lowerCamel	本规范

本稿取 B1：token 字符串值的段内用 lowerCamel，YAML 结构字段名与 event 名保留 snake_case。理由是 ThemeYaml 用 YamlNamingStrategy.SnakeCase 且 strictMode = false——在 YAML 里把字段名写成驼峰会被静默丢弃，配置看着写了却不生效。

event 是唯一一处有意的不齐：它既是词表成员、又是 YAML 字段名。彻底驼峰需要把 when 从 map 改成数组并改 KeyBehavior 绑定代码，超出纯文档范围。留这一处，换零解析器改动，是否可接受见 §9。

另有一条书写纪律：写规范、台账、示例一律用带命名空间的全路径（action.modifier.toggleCapsLock），不用 uppercasedStateAction 这类悬空概念名——悬空名没有词表约束，会滑回替身键的老路。

5. 横向参照：借鉴什么，不借鉴什么

这一节只比较结构取舍。其他输入法与 Rime 系前端的按键/动作写法，确实给了两处有用的启发；但它们的字段、取值、命名空间一个都不进本稿词表。

参照	做法	本稿取舍
iOS 上的第三方 Rime 前端（元书一类）	键 ID 用 xxxButton 后缀；事件是 action / swipeUpAction / uppercasedStateAction / repeatAction 等后缀式字段；动作值结构化 {character} / {shortcut} / {sendKeys}	动作值结构化 → 采纳（印证 action: {name, params}）；后缀式事件字段 → 不采纳，加一种手势就多一列，是笛卡尔积的另一种形态
其他 Android 前端的布局格式（含 foxy.* 一类自定义命名空间）	用 ref: 三段分区：rime.*（引擎键名）/ qwerty.*（布局）/ foxy.*（自定义）；swipe / longPress 用嵌套对象	命名空间分区思想 → 采纳，转化为五命名空间 + §6 的引擎键名边界；事件嵌套成结构层级 → 不采纳，触发时机应当是可枚举词表，不是层级
librime 键名表（key_table）	只有按键表达式：Return / BackSpace / Shift_L / KP_1，大小写敏感，三种历史风格混用	只作「按键」引用，不作动作词表。BackSpace 是发给引擎的按键，不是「删除」这个动词
主流商业输入法	动作多为结构化对象；状态与视觉分离	方向上印证「结构化 + 分层」，不作为字段来源

还有两点反面约束值得记下来：事件槽位嵌套虽比后缀式好，但仍把「触发时机」写成结构层级而非词表；引擎键名混进动作值时若不带命名空间，就会出现「一会大写一会小写」的观感——分区比统一拼写更重要。

6. 同文自己的特色（本稿落脚点）

借鉴归借鉴，下面几条是别的输入法不会替同文做、也不可能给出的——它们全都来自同文自己的源码结构和历史包袱：

#	特色	别家通常怎么做	同文为什么必须这样	源码依据
1	五命名空间正交，而非「一个键一个大对象」	键定义里堆叠字段，加能力就加列/加层	KeyAction 已是 16 个平行字段，再堆下去不可维护；拆成 key / event / action / color / metric 后每轴只管一件事	KeyAction、GeneralStyle
2	行为 ID 消解替身键	本来就用 id / ref 引用，不存在这个问题	Return1、bh1~bh4、主题里自造的 bkg / tkg / benter 标签是同文特有历史包袱，只有引入稳定 ID + when 就地覆盖才能收掉	preset_keys、PresetKey
3	词表逐项锚定源码 + 可静态校验	配置格式只管「怎么写」，不管「实现有没有」	13 个 event 直接等于 13 个 KeyBehavior 枚举；再配受控词表、一值一路径、回退链无环、源码文件哈希漂移报警，避免规范与实现悄悄脱节	KeyBehavior、Key，呼应 #1294 / #1968
4	wired 接线分档，不写「写了不生效」的名字	词表里把「已实现」和「计划做」混列	39 动词实测 A 24 / B 10 / C 5，C 档（如滑行输入、气泡展开、隐藏键盘）源码零消费点，必须显式标 wired: false	全量检索 252 个 Kotlin 文件 + 内置配置 + schema
5	librime 键名与动作动词分区	非 Rime 前端不会遇到	Rime 系独有问题：引擎只有按键表达式、没有动作层，且大小写是语义的一部分（rime.a ≠ rime.A）。用 params.key 原样承载，不铺成 39 项别名	KeyCode.parse、RimeKeyMapping、GenKeyMapping
6	B1 五层投影 + event 唯一例外	没有 Kotlin ↔ YAML 序列化这层约束	YamlNamingStrategy.SnakeCase + strictMode = false 会静默丢弃驼峰字段，大小写必须逐层分别定，不能统一成一种拼写	ThemeYaml
7	历史名只登记坐标、不合并	没有 V3 兼容包袱	menu_keyboard 这类旧命令单独登记为「action 域 / 打开 window.switch」，不并入封闭动词表，避免历史 snake_case 污染新词表	CommonKeyboardActionListener 的窗口装配
8	二维布局收敛 gap，V3 兼容税单列	布局本就是二维/引用式	现有引擎是一维行数组顺序布局，留白只能塞空键。规范里删掉 geometry.gap（留白 = 空单元格 + span），但降级产物里的 {gap: n} 必须保留并注明是 V3 兼容税	Keyboard 的布局计算、Key.gap 声明未被读取

一句话概括取舍：别家给的是「配置长什么样」，同文这套多做了「规范与实现的绑定关系」——源码锚定、接线分档、静态校验、兼容税标注，都是为了让「文档写了」和「引擎真的认」不脱节。这也是我认为最值得请官方判断的部分。

7. 落地的诚实分档

39 动词按「有没有源码消费点」分三档，词频只作线索、消费点优先：

档	含义	例子	改动量
A 已接线（24）	有直接源码消费点	commit、backspace（经 librime BackSpace）、moveCursor、toggleCapsLock、showClipboard、deploy	补字段 + 统一编址，零解析器改动
B 半接线（10）	源码有等价能力但形态不同	insertText、repeatCommit（现为布尔 isRepeatable）、selectAll、cut/copy/paste	要把布尔开关升格为带 params 的动词，须改 KeyAction 解析
C 无接线（5）	源码零消费点，wired: false	glideType、expandPopup、hideKeyboard、webSearch、selectText	纯规范预留，不应投产

有两处容易误判，一并写明：backspace 在源码里词频为零，是因为它走 librime 键名 BackSpace；run / date / none 的高词频是通用词。按消费点判定，不按词频。

三道硬门也在文档里标了：引擎目前只认 config_version: "3.0"（ThemeDiagnostics 的版本门）；动词化依赖尚未存在的 V5 解析器；行为 ID 全面取代替身键依赖二维布局。所以这份词表现阶段是编址契约，不是可运行配置。

8. 与 #1434 / #2220 各条的对应

已有讨论	本稿的落法
#1434 第 01 条：preset_key_style / fallback_style，preset_keys 移除颜色参数、增加 class	键定义只写 id / class / attributes / action / when，颜色全在 color: 节点（#2220 已落），本稿补齐动作侧
#1434 第 02 条：彻底拆分按键样式与键盘配列	样式按 class + state 取色，配列只放 geometry，二者不共享字段
#1434 第 03 条：class 优先使用预设名	class 是 6 词受控词表，且与色表路径修饰段共用同一份词表
#1434 第 04 条：按压态加前缀、缺失读原状态	状态恒末段 + 长路径优先回退（#2220 §3.1）；本稿的 when 产出 state，正是这条的输入
#2220 §5：状态是矩阵不是四份清单	本稿 attributes: [sticky] 表达「这键可锁定」，是性质而非事件；produces_state: locked 与颜色侧第三持续态对应
#2220 §6.3：longPress / key.hint 等 proposed 槽位怎么收	本稿 §7 的 wired 分档给出统一判据：有消费点进 A、等价能力进 B、零消费点留 C 标 proposed

9. 想听的意见

1. 三轴（key / event / action）与官方设想的 preset_key_style / fallback_style 是冲突，还是可以作为它们内部的编址规则？ 若第 1 条就与路线不符，后面几条都不必谈，我按维护者方向重写。
2. 39 动词要不要进引擎成为公开枚举？ 还是只作主题侧编址契约、引擎继续用现有字段堆叠 + 命令分派？后者改动小，但词表与实现始终隔着一层映射。
3. wired 该不该跨轴推广（目前只标在尺寸轴的硬编码项上）？C 档动词是保留为 status: proposed，还是直接从词表删掉，避免「已封闭、可组合」的虚假承诺？
4. 「发送 librime 键」的登记位：复用现有动词的 params.key，还是新建独立的 native_key_refs 段只登记坐标？两种都不动 39 项封闭词表。
5. event 保留 snake_case 这一处不齐能否接受（换零解析器改动）？还是宁可改 KeyBehavior 绑定也要全驼峰？
6. §5 的横向参照是否适合留在规范文档里？我倾向保留为「设计取舍说明」并明确不作依据；若官方希望规范正文只锚引擎源码，整节删去即可。
7. 若方向可行，是否更适合先做只读的 schema + 词表校验工具，而不先动运行时读取器？

---

本稿基于对 develop 分支源码的阅读整理，未在官方仓库提交代码或 PR；文中命名空间、词表、when: 与接线分档均为待讨论提案，不代表同文已实现或已采纳。§5 所列其他输入法仅作结构参照，不是本稿任何字段或取值的来源。