讨论：为 librime 异步 / 可扩展插件提供前端侧的扩展挂载点

[wyjrichhh]

TL;DR

我们最近基于 librime 开发了一个神经网络候选预测插件 librime-ai-predict，在与 squirrel 集成时遇到 3 处前端侧的扩展点缺失——它们独立、互不依赖、且与 ai_predict 解耦，理论上任何"异步候选 / 可扩展配色 / 日志可发现性"相关的 librime 模块都会撞到。我们在 fork feat/ai-inference 分支里写了 3 个临时方案验证可行（每个改动 ≤ 40 行），但希望先与维护者对齐方向再决定 PR 形态。

本 issue 不直接 PR，目的是收集维护者意见。3 项改动可独立讨论、独立合并。

---

Non-goals（明确不在范围内）

• ❌ 不修改 librime C API；不影响其他前端（weasel / ibus-rime / fcitx-rime）。
• ❌ 不要求 squirrel 内置任何 AI / 模型代码；不引入新的依赖。
• ❌ 不与 librime-ai-predict 绑定；3 项改动均独立可用、对其它 librime 模块开放。
• ❌ 不讨论模型 / 推理本身的合理性。

---

背景

librime-ai-predict 是一个 librime 插件，用 CTranslate2 加载 int8 量化的 seq2seq 模型，做"基于上下文的整句联想"。它完全以 librime 插件形式存在，未修改 librime 一行代码——这部分非常顺利。

但接到 squirrel 时，下面这 3 处前端能力的缺失让我们不得不动 squirrel 源码：

1. 插件日志难以查看——librime 有静态链接 glog 的历史限制（插件想写日志只能自己初始化 glog；此时它需要知道"主程序日志目录"在哪，但 squirrel 默认放在 $TMPDIR 且不暴露给插件。
2. 想给 AI 候选加个特征色——只能改 squirrel 源码或写 lua 脚本绕，没有 theme 层 API。
3. 异步推理完成后想刷新候选栏——librime 已有 notification_handler + Context property 通道，但 squirrel 默认不响应任何 property 通知。

---

现状分析（基于 upstream/master @ 151a43c）

A. 日志路径与可发现性

• sources/Main.swift#L21：

  static let logDir = FileManager.default.temporaryDirectory.appending(
      component: "rime.squirrel", directoryHint: .isDirectory)

  落在 $TMPDIR/rime.squirrel/。

• 已知历史问题：

  • rime/squirrel#356（open since 2019，无回复）：用户报告 TMPDIR 下日志符号链接隔天失效，find 全盘也找不到。
  • rime/squirrel#303：用户找不到 $TMPDIR/rime.squirrel.INFO。

• librime 侧关联：#983 详细分析"插件静态链接 glog → 各自独立实例 → 输出路径未初始化"，#984 提议改动态链接被关闭未合并。意味着 librime 主仓短期不会从核心层解决；前端只要把日志目录约定暴露出来，插件就能各自初始化自家 glog 写到同一目录。

B. 候选 comment 配色

• sources/SquirrelTheme.swift#L48 与 #L244-245：当前 theme 只有 commentTextColor 一个色值，应用于所有 comment。
• sources/SquirrelPanel.swift#L246：渲染时无视 comment 文本内容，统一套色。
• 结果：translator / filter 想给某类候选打视觉标记，只能改 squirrel 源码或在文本里加符号。我们的 ai_predict_filter 给候选写了 comment="AI"，希望让它显示为另一种颜色——目前没有干净的做法。

C. 异步候选就绪后的前端刷新

• sources/SquirrelApplicationDelegate.swift#L238-271：notificationHandler 当前只处理 messageType == "deploy" / "schema" / "option" 这几类系统消息，对 messageType == "property" 完全不响应。

• librime 侧：插件可以调 ctx->set_property(key, value)，librime 会自动以 messageType="property", value="key=value" 回调到前端——这个通道是 librime 已有能力，没有任何前端在用。

• 实际用户痛点：rime/librime#1025 用户问"用 librime-predict 时如何在 backspace 后继续联想"——predict 类插件想在异步事件后让前端重新拉一次候选，目前没有标准路径。

• 长期方向：rime/librime#1004（label enhancement）已系统讨论"在 lua 里调 onnx 做联想"。这类异步 / ML 类后端如果要落地，前端必须有标准的"被通知后刷新"入口。

我们临时方案的原码（点击展开）

3 个改动各自的 commit：

• A 日志：2e8a2b8 + e1778a7 的前半
• B 配色：50e6e5b
• C 刷新：e1778a7

完整 fork 分支：https://github.com/wyjrichhh/squirrel/tree/feat/ai-inference

---

普遍性论证

抛开 librime-ai-predict 这个具体项目，下面这些场景只要存在，就会撞到与我们相同的 3 堵墙：

假设场景	撞 A	撞 B	撞 C
任何用 lua / 第三方 dylib 写的插件，想自带日志	✅
云输入插件（拉远端候选）		✅（标记云端结果）	✅（HTTP 返回是异步）
其他 ML 后端（onnx / tflite / llama.cpp）	✅	✅	✅
自定义 translator 想标记"某类候选来源"（通假字 / 罕用字 / OCR 等）		✅
任何依赖 set_property 与前端协作的插件			✅

换言之，A 是 librime 插件生态的通用诉求，B 是 theme 层缺失的通用维度，C 是 librime 已有 API 但前端未对接的通用扩展点。

---

设计提案

三个改动彼此独立，可独立评估 / 合并 / 拒绝。每段含：思路 / 兼容性 / 用户视角配置 / 待解疑问。

A. 日志路径迁移 + 通过环境变量暴露给插件

思路

1. 把 Main.swift 里的 logDir 从 $TMPDIR/rime.squirrel/ 改为 ~/Library/Logs/Squirrel/（macOS 标准日志位置，Console.app 可见）。
2. 在 SquirrelApplicationDelegate.setupRime() 里 setenv("RIME_LOG_DIR", logDir.path, 1)，让插件 dylib 在自己 InitGoogleLogging 时能读取并复用同一目录。

兼容性

• 路径变更会破坏现有用户依赖 $TMPDIR/rime.squirrel/ 路径的脚本——这是本提案最敏感处。
• 缓解方案备选：保留 $TMPDIR 路径作为 symlink 指向新位置；或加一项 ~/Library/Rime/squirrel.custom.yaml 配置 app_options/log_dir 让用户选。

用户视角配置

无需配置；插件作者参考一个新约定 RIME_LOG_DIR。

待解疑问

• ~/Library/Logs/Squirrel/ 是否符合 squirrel 长期方向？是否需要 opt-out 旧路径？
• RIME_LOG_DIR 这个环境变量名能否定为 librime 生态的事实约定（让 weasel / ibus-rime / fcitx-rime 也跟）？还是更倾向 GOOGLE_LOG_DIR（glog 自带）？
• #356 是否可以在该改动合并后一并关闭？

B. 主题层支持按候选 comment 文本自定义颜色

思路

新增 yaml 字段 style/comment_color_map，键为 comment 字符串、值为颜色：

style:
  comment_color_map:
    AI: 0xff8c5a       # ai_predict_filter 写的 comment="AI"
    云: 0x5fa8d3       # 假想云输入插件

渲染时若 candidate.comment 命中 map，则用对应颜色覆盖默认 commentTextColor；未命中走原路径。

兼容性

• 完全 opt-in：未配置 = 行为与现在一字不差。
• 现有任何 theme 文件无需修改。

用户视角配置

如上 yaml 片段，3 行起步。可在每个 color scheme 下覆盖。

待解疑问

• 按 comment 文本精确匹配是否够灵活？还是应该按 candidate type / source 之类更结构化的维度？（按 type 需要 librime 暴露 API，按 comment 文本完全在前端解决）
• yaml 字段名 comment_color_map 是否符合 squirrel 命名风格？

C. 让前端响应 librime 的 property 通知，刷新候选栏（核心讨论点）

问题

librime 插件可以 ctx->set_property("xxx/yyy", "zzz")，librime 会自动以 notification_handler(type="property", value="xxx/yyy=zzz") 通知前端。但 squirrel 当前的 notificationHandler 完全忽略 property 通知。

期望流程：

sequenceDiagram
    participant U as 用户
    participant S as Squirrel<br/>(前端)
    participant R as librime<br/>(引擎)
    participant P as Plugin<br/>(如 ai_predict)

    U->>S: 按键
    S->>R: process_key
    R->>P: Translator.Query
    P->>P: 起后台线程异步推理
    P-->>R: 立即返回兜底候选
    R-->>S: 同步返回候选列表
    S->>U: 渲染候选栏(暂无 AI 候选)
    Note over P: 后台推理完成
    P->>R: ctx->set_property("ai_predict/ready", "1")
    R->>S: notification_handler(<br/>type="property",<br/>value="ai_predict/ready=1")
    S--xS: ❌ 当前: 无处理<br/>✅ 期望: 触发 rimeUpdate()
    S->>U: 刷新候选栏(含 AI 候选)

Loading

两个候选方案

• 方案 C1（约定式，最轻）：约定一个 namespace 后缀，譬如 */refresh_ui。插件写 set_property("foo/refresh_ui", "1")；squirrel 在 notificationHandler 里识别后缀就调 rimeUpdate()。

  • 优点：零配置；插件作者与前端互不需要知道对方。
  • 缺点：把"刷新候选"语义绑死在魔法后缀上；难以表达"只刷新某些 segment"等更细粒度需求。

• 方案 C2（声明式，可扩展）：在 schema yaml 里写白名单：

  frontend:
    refresh_on_properties: [ai_predict/ready, cloud_input/ready]

  squirrel 读这个列表，匹配即刷新。

  • 优点：显式、可控、未来可扩展为 refresh_on_properties: { ai_predict/ready: { mode: full } }。
  • 缺点：用户多一项配置；插件作者要在 README 提示用户加白名单。

我们 fork 里硬编码了 ai_predict/ready= 作为概念验证（e1778a7），这是临时方案，不应作为最终形态。

兼容性

• 完全新增能力，不破坏任何现有行为。
• C1 / C2 都不需要 librime 主仓任何改动。

待解疑问

• C1 vs C2 维护团队倾向哪个？或有第三方案？
• 多个 async 插件同帧通知时是否需要合并刷新避免抖动？squirrel 当前如何节流？
• 需要 find_session 之类的 session 校验来避免错误刷新已切走的窗口（我们 fork 里已加，可参考 e1778a7 的 refreshUIFromAsyncUpdate(for:) 方法）。
• 这个机制是否值得推到其他 Rime 前端（weasel / ibus-rime / fcitx-rime）形成跨前端约定？如是，是否需要 librime 侧出一份"前端实现指南"？

---

我们能做的

• 如果方向获得认可，我们承诺承担拆 PR 与后续维护。
• 我们倾向先 PR B（最不争议）→ 再 PR A（涉及默认行为变更，需 review 兼容策略）→ 最后 PR C（设计敲定后实施）。
• 每个 PR 控制在 ~40 行代码量级，便于 review。

---

已有讨论与背景

我们检索过 rime/squirrel 与 rime/librime 的现有 issue（关键词：property notification / comment color / TMPDIR / log_dir / predict / set_property / async 等），相关条目：

issue	与本 issue 关系
rime/squirrel#356	直接相关（A），open since 2019
rime/squirrel#303	直接相关（A），closed
rime/librime#1025	直接相关（C），用户层面对 predict 异步刷新的需求
rime/librime#1004	间接相关（C），ML 后端方向的系统讨论
rime/librime#897	邻近话题（上下文调频，非异步）

未发现完全重复的提案；如有遗漏请指出，我们会合并讨论。

---

最后，我们是第一次以项目维护方身份参与开源协作，如果上述提案在术语 / 流程 / 表达 / 与上游协作方式上有任何不妥，恳请直接指出。十分感谢 librime 与 squirrel 团队多年来的工作。

— [筠荐 / 蚌壳开发团队]

[lotem]

很好很強大

@fxliang 梁老師也來參謀參謀

[lotem]

先說簡單的：配色，我覺得也不簡單。

要知道，rime/squirrel, rime/weasel 都支持用戶自選配色方案，自定義註釋文本顏色如何能與各個配色方案搭配？

style:
  comment_color_map:
    AI: 0xff8c5a
    云: 0x5fa8d3

如此全局設置，無法保證與用戶所選配色方案的背景色有足夠反差，更不能保證美觀。

提案中提到「用户视角配置」「可在每个 color scheme 下覆盖。」這要用戶針對各個功能的具體註釋類型修改配置，不方便。

我希望在配色方案中引進「功能顏色代碼」，可以理解爲預設的調色板，但按照功能或者使用場合命名，如「強調重點註釋文字前景色」「特別提示註釋文字前景色」等。各個預設方案應追加定義，選取合適的顏色值；功能插件不設置具體顏色值，而是將自定義註釋類型對應到配色方案提供的顏色代碼。

[fxliang]

配色区分，要数据增加类似数据源的字段或者其他方式带上这个数据，前端识别支持吧

比如schema下定义如何在comment中提取配色和真的注释这样，前端解读

[wyjrichhh]

没有调查 没有发言权，有时间我先研究下现有关于配色的实现，之前主要关注的主流程部分。

[wyjrichhh]

            ┌─────────────────────────────────────────────┐
            │  ~/Library/Rime/  (yaml 配置仓库)           │
            │                                              │
            │  default.yaml + .custom.yaml                 │← 引擎全局
            │  luna_pinyin.schema.yaml + .custom.yaml      │← 数据/流程
            │  luna_pinyin.dict.yaml                       │← 词库
            │  squirrel.yaml + .custom.yaml                │← 前端外观
            │  weasel.yaml + .custom.yaml                  │  (各前端独立)
            └─────────────────────────────────────────────┘
                          │ Config API（按文件名读 yaml）
                          ▼
            ┌─────────────────────────────────────────────┐
            │              librime                         │
            │                                              │
            │  Engine: processors→segmentors→             │
            │          translators→filters                 │
            │                                              │
            │  对外 API 暴露的"数据"：                     │
            │   • Composition (输入串、preedit)            │
            │   • Menu / Candidates                        │
            │       └─ candidate.text                      │
            │       └─ candidate.comment   ← 纯文本 ，这里加数据标识（梁老师方案）         │    
            │       └─ candidate.label                     │
            │   • Status (schema_id, switch states)        │
            │   • Notification (deploy/schema/option/      │
            │                    property)                 │
            └─────────────────────────────────────────────┘
                          │ C API
                          ▼
    ┌──────────────┬──────────────┬──────────────┬──────────────┐
    │  Squirrel    │   Weasel     │ ibus-rime    │ fcitx-rime   │
    │  (macOS)     │  (Windows)   │  (Linux)     │  (Linux)     │
    │              │              │              │              │
    │ 读 squirrel  │ 读 weasel    │ 不读外观     │ 不读外观     │
    │ .yaml 自己   │ .yaml 自己   │ 配置（依赖   │ 配置（依赖   │
    │ 解释 colors  │ 解释 colors  │ ibus 主题）  │ fcitx 主题） │
    |                                     <-   统一增加配置处理 └──────────────┴──────────────┴──────────────┴──────────────┘

我基于这样的图例来理解当前配色的实现。

1. 配色的配置目前只与前端实现相关，与插件、librime本身无关、schema无关
2. librime只负责计算数据
3. 插件只负责计算数据

配色这里缺失的是一种插件（广义）产生数据，需要特殊渲染，通过librime提供的机制，将这个诉求告知渲染引擎（不同的前端实现）。

我的理解：
lotem 老师的方案考虑角度不只是插件这里通过 setProperty传递的数据，而是更通用的功能层面的
fxliang老师的方案考虑角度是针对 comment需要特殊配色的角度。

我觉得可能“功能”概念设计好，可以覆盖comment的配色场景 ，或许也可能应用于其它场景，虽然我还想象不到

[wyjrichhh]

我发现 setProperty，本身是kv形式的，实际上是可以通过k传递标识，v传递数据的，但是property是整个engine的全局kv，并没有“哪个candidate的归属”，也就是说它更适合广播全局事件（“AI推理完成”，“切换模式”）等，不适合标记单个candidate的属性（“这个候选来自于AI，并且要标记成#ffffff颜色”）。

最取巧的方案是 给key 赋予多级语义
key = 性质/功能/标记 形式
value = 数据

前端按约定语义解析key，并通过功能+标记的语义来匹配方案配色，并在未名中格式的key中静默处理（如原本没这个语义时一些key的处理按原样处理即可）

这个方案优势是 librime代码可以不做调整，但是从功能语义上来说，property的职责我觉得在某成程度上来说绑定了新的业务语义，我个人觉得代码脏了。

所以这个功能还是需要明确 是 librime 是否参与调整，还是只由插件和前端配合做

[fxliang]

每次合成中总是传style的话在小狼毫中有点不算太合适

[wyjrichhh]

@lotem 大佬 你怎么看

[lotem]

set_property 的方法實現成本低。對 librime 透明，插件和前端協商一個規範。我沒意見～

類似這樣賦值，值爲列表：
_comment_highlight = 0 高亮註釋的有 0 號候選

[wyjrichhh]

多谢两位的耐心点评，先收敛一下三方发言、提一份合并方案。

自我修正

我 4/27 那条「set_property 走多级 key + value 直接传 style 数据」的方案有问题，现在我理解了反对意见——set_property 在 librime 设计里是低频事件通道（部署 / schema / 模式切换），不是 per-frame style 总线。squirrel 在 IMK 进程内回调可以扛，但 weasel 是 server-client 跨进程，每帧一次大对象广播 IPC 不合理；而且把"颜色信息"和"哪个候选要被高亮"混在一起，既肥也破坏了 property 的语义。这条方案撤回。

合并方案（B + C 共用一条机制）

把早期讨论的「配色方案里引进功能颜色代码」+ 5/6 给的 _comment_highlight = 0 + 「数据带标识、前端解读」三条线合到一起，B 和 C 其实是同一条机制的两个面：

配色方案 (squirrel.yaml / weasel.yaml ...)
  各 preset 追加一组「语义色」（颜色具体值由方案作者把控）：
    accent_text_color    强调（插件主输出 / 重点）
    warning_text_color   提示（云端 / 罕用 / 警告）
    ...
                ↑ 前端 theme 解读
                │
librime  (一行不改, 透明转发)
  Plugin → ctx->set_property("_xxx", "...")
  Engine → notification("property", "_xxx=...")
                │
                ↓
前端 (按约定的"保留 key"解读)
  _comment_highlight = "0,2"   ↳ 第 0、2 号候选 comment 套 accent_text_color
  _refresh_ui        = "1"      ↳ 重新拉一次候选

要点：

• librime 不动，对核心透明
• set_property 只传"索引 / 事件触发"等轻量 payload（单次几字节），weasel IPC 也扛得住
• 颜色具体值住在配色方案里，方案作者按 emphasis / warning 等语义命名色值，与背景搭配的责任落在熟悉方案的人手上
• 跨前端友好：_ 前缀的 property key 是前端"识别保留语义"，其他前端可以选择实现或忽略，不实现不会破坏插件主流程（AI 候选还是会出来，只是没特殊配色 / 没主动刷新）

协议草案 v0

配色方案侧

字段	语义	fallback
accent_text_color	强调注释（插件主输出 / 重点）	comment_text_color
warning_text_color	提示注释（云端 / 罕用 / 警告）	comment_text_color

各预设方案应追加合适色值，命名以维护团队定夺为准。

保留 property key

key	value 形式	语义
_comment_highlight	"<idx>" 或 "0,2,3"	这些索引的候选 comment 套 accent_text_color
_comment_warning	同上	套 warning_text_color
_refresh_ui	"1"	异步任务完成，前端重新拉候选

约定：

• _xxx：跨前端保留语义，需要文档约定，私自占用算违规
• <plugin_name>/yyy：插件自有语义，前端可选择性识别，不强求

我们 fork 现有的 style/comment_color_map 和硬编码 ai_predict/ready 那两个 commit 都会按新机制重写，不保留。