突破输入边界：用 Lua 脚本扩展 RIME 输入法的全指南

2026-01-18 09:46:56作者：明树来

项目概述：librime-lua 是什么？

librime-lua 是一个为 RIME（Rime Input Method Engine，中州韵输入法引擎）提供 Lua 脚本扩展能力的插件。通过该项目，开发者可以使用 Lua 语言编写自定义的处理器（processors）、分词器（segmentors）、转换器（translators）和过滤器（filters），从而极大增强 RIME 的输入灵活性和个性化程度。

项目核心优势包括：

动态加载为 librime 插件，无需修改 RIME 主程序
为转换器和过滤器提供高级编程模型
支持 RIME 核心组件的全流程扩展

快速上手：从安装到第一个 Lua 脚本

环境准备与安装

librime-lua 作为 RIME 的插件，需要先确保系统中已安装 RIME 输入法框架。安装插件的方式因操作系统而异，项目提供了跨平台的安装脚本：

Windows 系统：action-install.bat
Unix/Linux 系统：action-install.sh

项目结构解析

了解项目结构有助于快速定位关键文件：

librime-lua/
├── CMakeLists.txt        # 编译配置文件
├── src/                  # 核心源代码目录
│   ├── lib/              # Lua 扩展库实现
│   └── lua_gears.cc      # 核心齿轮组件
├── sample/               # 示例脚本目录
│   ├── rime.lua          # 主配置入口
│   └── lua/              # 各类功能脚本
└── contrib/              # 贡献者资源

第一个扩展：时间转换器

让我们通过一个简单示例了解如何使用 librime-lua。以下是将输入 "time" 转换为当前时间的转换器实现：

-- 示例代码源自 [sample/lua/time.lua](https://gitcode.com/gh_mirrors/li/librime-lua/blob/68f9c364a2d25a04c7d4794981d7c796b05ab627/sample/lua/time.lua?utm_source=gitcode_repo_files)
local function time_translator(input, seg)
    if (input == "time") then
        local time_str = os.date("%H:%M:%S")
        yield(Candidate("time", seg.start, seg._end, time_str, " 时间"))
    end
end

return time_translator

要使用此转换器，需在 RIME 配置中注册：

# 在 schema 文件中添加
engine:
  translators:
    - lua_translator@time_translator  # 引用 Lua 转换器

核心功能详解：Lua 扩展 RIME 的四种方式

1. 转换器（Translators）

转换器是 librime-lua 最常用的扩展点，用于将输入序列转换为候选词。项目提供了丰富的转换器示例：

date_translator：将 "date" 转换为当前日期
number_translator：将数字转换为大小写汉字
script_translator：通用脚本转换框架

转换器工作流程：

flowchart LR
    A[用户输入] --> B[Lua 转换器脚本]
    B --> C{是否匹配转换规则}
    C -->|是| D[生成候选词]
    C -->|否| E[传递给下一个转换器]
    D --> F[候选词排序与过滤]
    F --> G[显示给用户]

2. 过滤器（Filters）

过滤器用于对候选词列表进行二次处理，如排序、过滤或添加注释。示例包括：

single_char_filter：让单字候选优先显示
charset_filter：过滤特定字符集的候选词
reverse_lookup_filter：为候选词添加反查注释

过滤器实现示例（简化版单字优先）：

-- 源自 [sample/lua/single_char.lua](https://gitcode.com/gh_mirrors/li/librime-lua/blob/68f9c364a2d25a04c7d4794981d7c796b05ab627/sample/lua/single_char.lua?utm_source=gitcode_repo_files)
local function single_char_filter(input)
    local single_chars = {}
    local others = {}
    
    for cand in input:iter() do
        if #cand.text == 1 then
            table.insert(single_chars, cand)
        else
            table.insert(others, cand)
        end
    end
    
    for _, cand in ipairs(single_chars) do yield(cand) end
    for _, cand in ipairs(others) do yield(cand) end
end

return single_char_filter

3. 处理器（Processors）

处理器用于处理用户输入事件，如按键、鼠标操作等。switch_processor 示例展示了如何通过选择候选词切换输入法状态：

-- 按键处理逻辑源自 [sample/lua/switch.lua](https://gitcode.com/gh_mirrors/li/librime-lua/blob/68f9c364a2d25a04c7d4794981d7c796b05ab627/sample/lua/switch.lua?utm_source=gitcode_repo_files)
local function selector(key, env)
    if key:release() or key:alt() then return kNoop end
    local idx = select_index(key, env)
    if idx < 0 then return kNoop end
    
    local ctx = env.engine.context
    if ctx.input == "simp" then  -- 输入 "simp" 时触发切换
        if idx == 0 then
            apply_switch(env, "simplification", true)  -- 切换为简体
        elseif idx == 1 then
            apply_switch(env, "simplification", false) -- 切换为繁体
        end
    end
end

4. 分词器（Segmentors）

分词器用于将用户输入分割为有意义的片段。虽然示例中未直接提供，但开发者可以通过类似方式实现自定义分词逻辑。

高级应用：构建智能切换系统

多条件切换逻辑

结合处理器和过滤器，可以实现复杂的输入法状态切换系统。以下是一个基于输入内容自动切换简繁体的逻辑：

-- 伪代码示例，综合自 [sample/rime.lua](https://gitcode.com/gh_mirrors/li/librime-lua/blob/68f9c364a2d25a04c7d4794981d7c796b05ab627/sample/rime.lua?utm_source=gitcode_repo_files) 和 [sample/lua/switch.lua](https://gitcode.com/gh_mirrors/li/librime-lua/blob/68f9c364a2d25a04c7d4794981d7c796b05ab627/sample/lua/switch.lua?utm_source=gitcode_repo_files)
local function smart_switch_filter(input)
    for cand in input:iter() do
        -- 根据候选词长度决定是否切换简繁体
        if #cand.text > 5 then
            env.engine.context:set_option("simplification", true)
        end
        yield(cand)
    end
end

脚本加载流程

librime-lua 的脚本加载遵循特定流程，理解这一流程有助于排查问题：

sequenceDiagram
    participant RIME Engine
    participant Lua Plugin
    participant rime.lua
    participant Module Scripts
    
    RIME Engine->>Lua Plugin: 加载插件
    Lua Plugin->>rime.lua: 执行主配置
    rime.lua->>Module Scripts: 加载转换器模块
    Module Scripts-->>rime.lua: 返回功能函数
    rime.lua-->>Lua Plugin: 注册功能
    Lua Plugin-->>RIME Engine: 提供扩展接口

深入开发：API 与高级特性

核心 API 概览

librime-lua 提供了丰富的 API 供开发者使用，主要包括：

API 类别	关键函数/类	用途
候选词操作	Candidate()	创建候选词
上下文管理	env.engine.context	获取当前输入上下文
配置访问	env.engine.schema.config	读取配置值
状态切换	set_option()	修改输入法状态

自定义用户词典

通过 sample/lua/userdb.lua 提供的接口，可以实现自定义用户词典管理：

-- 用户词典操作示例
local function add_to_user_dict(env, entry)
    local user_db = env.engine.user_dict
    user_db:update_entry(entry, 1, "")  -- 添加词条
end

错误处理与调试

开发 Lua 扩展时，可使用以下技巧进行调试：

-- 日志输出
local function debug_log(message)
    env.engine:log_message("lua-debug: " .. message)
end

-- 错误捕获
local status, err = pcall(function()
    -- 可能出错的代码
end)
if not status then
    env.engine:log_message("error: " .. err)
end