插件开发与配置

几维输入法拥有高度可扩展的底层架构。通过编写 Lua 脚本，你可以直接介入输入引擎的各个管线节点，实现自定义的逻辑过滤与候选词生成。当性能遭遇瓶颈或需调用操作系统底层 API 时，亦可回退至 C++ 开发标准组件。

本指南聚焦于基于 Lua 运行时的快速开发与配置。

Lua 开发的工程优势

• 极低门槛：基于 Lua 5.4 语法，无需配置复杂的 C++ 编译工具链。
• 动态重载：支持热重载（Hot-reload），修改代码后一键部署即刻生效，极大缩短调试周期。
• 性能达标：利用 LuaJIT 与引擎的 C API 绑定，对于非密集型文本计算场景（如正则匹配、查表），性能损耗可忽略不计。

引擎管线与插件类型

在 Rime 的架构中，用户的击键事件在最终渲染为候选词之前，会依次穿过以下三大核心管线。开发者可针对不同管线编写对应的 Lua 插件：

插件类型	运行时机	核心职责	典型场景
Processor	击键拦截期	决定是否接管物理按键。	快捷键绑定、跨引擎状态切换。
Translator	候选生成期	根据输入码流（Segment）构造对应的候选词（Candidate）。	动态日期生成、计算器、生僻字拓展。
Filter	候选过滤期	拦截并修改由 Translator 生成的候选流。	繁简转换、错词屏蔽、自定义权重重排。

开发快速起步

以下演示如何编写一个基础的 Filter 插件。

1. 编写脚本实体

在 用户目录\lua\ 下创建文件 myfilter.lua：

-- lua/myfilter.lua
function myfilter(input)
  for cand in input:iter() do
    -- 此处可针对候选词的文本、类型或权重进行逻辑干预
    -- 例如：抛弃特定的候选词，或者修改其 Comment 属性
    yield(cand)
  end
end

return myfilter

2. 在方案拓扑中挂载

编辑你的目标方案配置文件（如 witcraft.custom.yaml），将该 Filter 注入引擎管线：

patch:
  engine/filters/+:
    - lua_filter@myfilter

3. 热重载

保存配置后，在任务栏右键菜单中执行 重新部署，引擎将重新编译方案并载入 Lua 虚拟机。

读取持久化配置

Lua 插件支持读取 YAML 文件中的用户设定，实现逻辑与配置的分离。

local config = env.engine.schema.config
-- 获取布尔型开关
local is_enabled = config:get_bool("custom_plugin/enabled")
-- 获取字符串参数
local trigger_prefix = config:get_string("custom_plugin/trigger")

对应的 YAML 配置定义：

custom_plugin:
  enabled: true
  trigger: "cmd_"

拓扑结构的精细控制

使用 Rime 的 patch 语法，可对原有的管线列表进行精准的增删改操作。

patch:
  # 使用 + 号追加至末尾
  engine/translators/+:
    - lua_translator@*lunar_calendar
  
  # 使用 - 号从管线中剔除
  engine/translators/-:
    - lua_translator@*predict

调试与诊断机制

由于 Lua 运行在输入法的后台宿主进程中，无法直接唤出控制台。调试主要依赖于日志系统：

1. 在脚本中使用 log.info("Variable value: " .. val) 输出诊断信息。
2. 前往 %LocalAppData%\Temp\witty.outwit\ 目录，查阅最新的引擎运行时日志。
3. 若遇语法错误（如括号不匹配、空指针调用），引擎会在部署阶段报错拦截，日志中将打印具体的 Lua 堆栈追踪（Stack trace）。

技术参考与社区

• librime-lua Wiki - 包含完整的 API 文档与核心对象的生命周期说明。
• Rime Configuration - 深入理解 YAML 补丁语法与 schema 定义规范。