[讨论稿] 把「位置 + 功能命名」落成可校验的路径式色表 —— 接着 #1434 提一份具体方案

[x4w2nyhvk8]

接续官方已有讨论：#1434 关于下一代同文主题设计规范的讨论。本稿逐条对应其中已提出的原则，并把两处可能相左的地方单列为「待裁决」。

先说明边界：这是个人整理的讨论稿，不是 PR，也不代表维护者意见。文中的路径格式、trime_version: 5、补充色码与校验脚本，当前 Trime 都不支持；目的只是把 #1434 里已经提出的原则写成一份可以被逐条反驳的具体方案。若方向不合官方路线，请直接指出，我据此收敛。

源码数字以我阅读时的 develop 分支为准：ColorKey.kt 52 个颜色枚举、49 条内置回退链，GeneralStyle.kt 58 个 style 字段，KeyBehavior.kt 13 个触发时机。若这些文件近期已调整，请以当前源码为准并告诉我，我重算。

---

1. 为什么接着 #1434 说

主帖开篇写的背景是「主题参数命名混乱、无配套 GUI 工具、制作调试耗时、结构复杂可维护性低」，目的就是「讨论并制定下一代同文主题的设计规范」。回复里还有一句我特别有共鸣：

「rime 现在自带的主题的配色命名太抽象了……对于配色的名字『丹青』『steam』，其实就是换个颜色，但是光看名字，想象中的颜色和实际出入比较大……同文风主题有好多颜色类似，但是名字不一样的。」

这几年下来，颜色字段本身也有类似问题：同一个视觉对象在不同位置有不同写法（back_color / keyboard_back_color / keyboard_background / root_background 并存）；状态靠 hilited_ 前缀表达，位置不统一；*_back_color 与 *_text_color 对仗，但 key_symbol_color、key_hint_color 又不完全对仗；主题里还大量使用 bc1 / tc1 这类自定义颜色标签，改全局颜色不生效。

所以本稿只做一件事：把主帖第 10 条「preset_color 使用位置和功能的命名方式，而不是使用颜色、图像内容」落成一套有词表、有回退规则、能机器校验的路径格式。

2. 一个前提：唯一事实来源是引擎源码，不是任何一份主题

现有主题里哪些颜色字段存在、哪些是同义、哪些有回退，散落在 ColorKey.kt、ThemeColors.kt、ColorTable.kt、GeneralStyle.kt 里。若以某份流行主题为样本来定规范，样本没写的字段就会漏掉——我最初这么做时漏了 12 个源码字段。

建议：规范色表 = 源码枚举的全集，主题只取子集，不新增规范路径。配套三条硬规则：

规则	内容	解决什么
一值一路径	一个可独立赋值的引擎色键，占且仅占一条规范路径；两代同义枚举必须显式声明并附源码证据	杜绝「看起来一样就合并」，避免丢信息
回退链全显式	源码 49 条内置回退链全部写成路径式引用，主题未写的字段不依赖运行时隐式行为	换主题时行为可预测，也便于静态校验
值域二元	值为 0xAARRGGBB 或图片文件名（.png/.webp/.jpg/.gif），二者不混用	呼应主帖第 09、11 条

值格式沿用 0xAARRGGBB 并一律加引号：YAML 里 # 是注释符，不能用 #RRGGBBAA；不加引号的 0x... 可能被 YAML 1.1 解析成整数。

3. 路径格式：color.<domain>[.<sub>].<part>[.<class>][.<state>]

实际存储时省略 color. 前缀（放在 color: 节点下），例如：

key.foreground.modifier.active.pressed
│    │          │        │      └─ 瞬时态：这一刻发生了什么
│    │          │        └──────── 持续态：这键现在处于什么状态
│    │          └───────────────── class：这键属于哪一类
│    └──────────────────────────── part：画的是哪个部件
└───────────────────────────────── domain：画在哪个区域

• domain（9 词，受控）：key / preedit / candidate / popup / toolbar / clipboard / root / keyboard / smartbar。其中 keyboard.background / root.background 是键盘底板，不随任何按键状态变化；键帽底色是 key.background，两者不同域。
• part（7 词，受控）：background / foreground / symbol / hint / outline / elevation / separator。取直白的「背景 / 前景」，与源码 *_back_color / *_text_color 对仗；foreground 覆盖主文字与图标 tint（keyTextColor 也被 TabUi / PaginationUi 复用），比 text 更准。Trime 是纯 YAML 扁平色表，没有容器层级概念，所以不引入需要额外解释的抽象容器词。
• class（6 词，受控）：default / character / system / modifier / action / space，直接对应主帖第 03、07 条要用 class 取代 function 属性和 shift 专属样式的方向。
• state 恒在末段：这是为了 patch 寻址「一截就到」，也把主帖第 04 条「按压状态自动按原状态前加前缀来取值」变成显式规则。顺序固定 class → 持续态 → 瞬时态（Key.kt 里两者本就正交）。
• 不用 on / off：YAML 1.1 会把它们解析成布尔字面量，作 token 段本身就是歧义；源码的 ON_KEY_* / OFF_KEY_* 统一映射到 active / inactive。

3.1 特异性规则：长路径优先、短路径回退

key.background.space.pressed  未定义
  → 退 key.background.space
  → 退 key.background

一条规则，同时解释了主帖第 04 条（缺失时读原状态）、第 05 条（default 含全部属性，其他样式可简写）和第 08 条的读取顺序。不另造第二套 fallback 机制。

3.2 一处容易踩的坑：symbol 与 hint 不能合并

源码有 KEY_SYMBOL_COLOR 系列枚举，却没有 KEY_HINT_COLOR（GeneralStyle.kt 只有 key_hint_offset_* 几何字段）；但 V3 主题里 key_symbol_color 与 key_hint_color 是两个字段、取值可以不同。若把二者判成同义共占一条路径，就会丢掉主题已有的信息。因此定 key.symbol 锚定源码枚举，key.hint 归为主题自定义/补充色，四方位提示走 key.hint.up/down/left/right。

4. 与 #1434 各条的对应

#1434 里提出的	本稿的落法
01：新增 preset_key_style / fallback_style，preset_keys、preset_keyboards 移除颜色参数、增加 class	颜色全部收进 color: 节点；键定义只写 class + 行为，不写颜色
02：彻底拆分按键样式与键盘配列	布局 rows 只放坐标，取色只靠 class + state
03：class 优先使用预设名	class 是受控词表 6 词，路径修饰段与键的 class 共用同一份词表
04：按压态自动加前缀、缺失读原状态；增加 fallback_style	状态恒末段 + 长路径优先回退，49 条源码回退链全显式
05：default 含全部属性，其他可简写	短路径即 default；patch 只覆盖长路径
08 / 09：读取顺序 view → style → fallback → color；配色不出现在别处	一值一路径 + 值域二元，fallback_colors 转成路径式引用链
10：preset_color 用位置+功能命名，不用颜色名；patch class 而非 patch 颜色	路径式命名正是这条的具体化：路径里只有区域/部件/类别/状态，不出现色值与图片名
行动 1：用 trime_version 分派新旧读取方法	接受，示例产物里已写 trime_version: 5
行动 4 / 回复：配色调试工具、主题+配色预览	见 §7 的可校验性与状态切换预览
回复：用 json schema 验证主题（#1294 的 demo）	doc/trime-schema.json 之上再加「源码锚定 + 受控词表」两层静态校验

5. 键状态是矩阵，不是四份清单

源码 ColorKey.kt 的键位部分本身就是一个矩阵：常态 / 按下态 / on_key_* / off_key_* 及其按下态 × 背景 / 文字 / 符号 / 边框。把它整理成两根正交轴：

• 持续态：inactive（未激活）、active（临时激活）、locked（持久锁定）
• 瞬时态：pressed（按下）、longPress（长按持续中）、selected、focused、disabled

于是「正常 / 按下 / 长按 / 锁定」四层不是四套独立色表，而是矩阵的单元格；「锁定态下再按下」是 …locked.pressed，叠加而非替换：

part	正常	按下	长按	锁定（功能键）
background	key.background	…pressed	…longPress	…modifier.locked
foreground	key.foreground	…pressed	…longPress	…modifier.locked
symbol	key.symbol	…pressed	…longPress	…modifier.locked
hint	key.hint	…pressed	…longPress	…modifier.locked
outline	key.outline	…pressed	…longPress	…modifier.locked

两点需要说明：

• 长按在源码里没有任何颜色枚举（LONG_TEXT_* 是「键面长标签」，不是长按）。它其实是触发时机（event.long_click），气泡走 popup.* 域，键帽是否需要独立态，见 §6.3。
• keyboard.background / root.background 是键盘底板，属另一个域，不随键状态变化，不在这个矩阵里。

6. 三处想请维护者裁决，而不是我已定稿

6.1 Shift 锁定态：主帖第 07 条 vs 第三持续态

主帖第 07 条写得很明确：

「移除原有的 function 属性和 shift 的样式属性，改为 class。目前 shift 键状态太多，需要削减为默认、按下 2 个状态，锁定时使用和按下完全相同的外观。」

但主帖后面又提到：

「另外，目前同文实际上没有处理大写锁定（caplock），只是模拟了 shift 长按的动作。在输入符号及空格选字的场景下，和 pc 有差别。」

而 #1908「长按 Shift 作为 CapsLock?」 到今年仍有人问。源码 ColorKey.kt 只有 ON_KEY_* / OFF_KEY_* 两持续态，恰好对应「临时激活 / 未激活」，分不出「持久锁定」。

两条路：

• (a) 按主帖削减为两态，锁定沿用按下外观 —— 实现最省，与「削减状态」一致；代价是锁定与按下视觉上无法区分。
• (b) 补 locked 第三持续态，与 active / inactive 互斥、占持续态槽位（本稿暂取 b，另补 8 条 status: proposed 色码）。

想请教：4.0 里 Caps Lock 是否仍打算只做「shift 长按模拟」？ 如果是，(a) 更一致，我把 locked 全部撤掉；如果打算真正实现锁定状态，(b) 是否值得现在预留一个槽位？这一条我不坚持。

6.2 旧主题兼容：主帖行动 1 vs 构建期降级

主帖行动 1 是「新方法完全不对旧方法做兼容」，用 trime_version 分派、4.0 去除旧方法。本稿接受 trime_version 作为分派键；但额外做了一层 V5 → V3 的等价降级：同一份主题能生成一份 config_version: "3.0" 的旧格式，供当前版本导入，便于过渡期对照验证（我这边的降级检查是 0 差异、每套 44 条路径集合一致）。

这层降级是纯构建期工具行为，不要求运行时兼容。但它会不会与「完全不兼容」的路线有冲突？如果官方打算另起一套读取器，我建议把它明确定位成「迁移期工具」，不写进规范本身。

6.3 longPress 与 key.hint 这类 proposed 状态/色码要不要留

longPress（键帽长按态）、key.hint（方位提示）、key.foreground.disabled、root.foreground 等共 27 条，都是源码 52 枚举之外、我认为语义必需但当前引擎没有的槽位。全部标 status: proposed，并逐条写明「源码为什么缺、为什么必须补」。这类补充色码规范上应该怎么收？

1. 补进 ColorKey.kt 成为正式枚举；
2. 归入主题自定义别名，不进规范；
3. 保持 proposed，等 4.0 解析器一起决定。

我倾向 3，但这取决于官方要不要维护一份「引擎色键全集」的公开清单。

7. 可校验性（呼应 #1294 与 #1968）

除了 doc/trime-schema.json 那样的结构校验，本稿另加三层，都是纯静态、可离线跑：

1. 源码锚定色表：把枚举全集、49 条回退链、style 字段清单自动生成，并记录源码文件 sha256；源码一改，校验直接报警，避免规范与实现悄悄脱节。
2. 受控词表：domain / part / class / state / direction / context 各一份，路径每一段只能取词表内的值；key_domain ⊆ action_domain 这类子集关系也强制检查。
3. 去歧义规则：一值一路径、同义显式声明、回退链无环、补充色码必须写明依据。

另配一个状态可切换的配色预览（常态 / 按下 / 长按 / 选中 / 锁定），对应主帖行动 4 的「配色调试工具」和回复里「主题 + 配色搭配后实时预览」的设想。目前这些都只是本地原型，没有向官方仓库提交任何代码。

8. 最小示例（节选，纯示意）

trime_version: 5          # 呼应 #1434 行动 1 的版本分派
config_version: "5.0"

color:
  day:                    # 每主题固定两套：day / night；路径集合两套完全一致
    appearance: light
    "keyboard.background":                  "0xFFE8EAEF"  # 键盘底板，不随键状态变化
    "key.background":                       "0xFFFDFDFD"  # 键帽
    "key.foreground":                       "0xFF000000"
    "key.symbol":                           "0xFF6B7280"
    "key.hint":                             "0xFF6B7280"
    "key.background.pressed":               "0xFFC8CCD4"
    "key.background.modifier":              "0xFFD5D9E0"
    "key.background.modifier.locked":       "0xFFE8F0FE"  # 待裁决，见 §6.1
    "key.foreground.modifier.locked":       "0xFF1A73E9"
    "key.background.modifier.locked.pressed": "0xFF1A73E9"  # 持续态 × 瞬时态叠加
    "popup.background":                     "0xFFFDFDFD"
  night:
    appearance: dark
    # 同构，此处省略

keys:
  - id: shift
    class: modifier        # 取色只靠 class + state，键定义里不再出现颜色
    attributes: [sticky]   # 「可锁定」是键的性质，不靠事件名表达
    # 动作命名另议，本稿只谈取色

layouts:
  standard26.portrait:
    rows:                  # 坐标只出现在布局场景层
      - [ { key: q }, { key: w }, { key: e } ]

9. 想听的意见

1. 路径式命名（状态恒末段）与官方设想的 preset_key_style / fallback_style 是冲突，还是可以作为它们内部的取色规则？
2. trime_version 分派下，规范色表应当内置在引擎里，还是随主题分发？
3. locked、longPress 两个 proposed 状态词留不留（§6.1、§6.3）？
4. key.hint 这类「源码无枚举、但主题实际在用」的字段，规范上按补枚举 / 归别名 / 保持主题自定义 哪种收？
5. 若方向可行，是否更适合先做一个只读的 schema + 预览工具，而不先动运行时读取器？

如果第 1 条就与官方路线不符，后面几条都不必谈，我会按维护者的方向重写。

---

本稿基于对 develop 分支源码的阅读整理，未在官方仓库提交代码或 PR；文中格式、词表与补充色码均为待讨论提案，不代表同文已实现或已采纳。

[x4w2nyhvk8]

@WhiredPlanck @tumuyan @Bambooin