Karukan日文输入法仓库结构导览：4个Rust crate + 1个Swift包快速上手

Karukan日文输入法仓库结构导览：4个Rust crate + 1个Swift包快速上手

【免费下载链接】karukanJapanese Input Method System for Linux, macOS, Neural Kana-Kanji Conversion Engine项目地址: https://gitcode.com/GitHub_Trending/ka/karukan

Karukan 是一款面向Linux 和 macOS 的日文输入法系统，内置基于 llama.cpp 的神经 kana-kanji（假名转汉字）转换引擎。整个仓库由4 个 Rust crate + 1 个 Swift 包组成，结构清晰、职责分明。本文带你快速看懂 Karukan 日文输入法的仓库结构，无论新手还是进阶用户都能快速上手。

上图是 Karukan 日文输入法在编辑器中实时将罗马字转换为汉字的实际效果演示。

仓库结构一览：一张表看懂 Karukan 项目

打开仓库根目录，你会发现顶层只有三大块目录 + 若干文档，非常清爽：

所有 Rust 代码通过根目录的 Cargo.toml 组织成一个Cargo workspace，一条命令即可构建全部 crate：

cargo build --release

仓库还有一份 CLAUDE.md，相当于官方给开发者准备的"架构说明书"，包含每个模块的职责和构建命令，强烈推荐先读它。

第一步：获取 Karukan 仓库

git clone https://gitcode.com/GitHub_Trending/ka/karukan

要求：Rust 1.92+（workspace 使用 2024 edition）。macOS 前端还需要 Xcode/Swift 工具链；Linux 前端还需要 cmake、gcc、clang 等 C/C++ 构建工具（详见 karukan-im/fcitx5/README.md）。

核心大脑：karukan-engine（Rust crate 1/4）

karukan-engine/ 是整个 Karukan 日文输入法的"智力中枢"，关键源码都在 karukan-engine/src/ 下：

• 🧠romaji/— 罗马字→平假名转换，内部用 Trie + 200 多条规则驱动
• 🤖kanji/— 通过 llama.cpp 加载 GGUF 小模型（GPT-2 / Qwen3 底座），实现上下文感知的神经假名转汉字
• 📖dict.rs— 双数组 Trie 系统字典，支持高速精确/前缀匹配
• 🎓learning.rs— 学习缓存：记住你选过的转换结果，下次优先展示
• ✨rewriter/— 候选改写器（从 Mozc 移植）：自动生成半角片假名、全角/半角、数字多种写法等变体

模型清单定义在 karukan-engine/models.toml，首次运行时会自动从 Hugging Face 后台下载；下载期间假名输入和字典转换照常可用，加载完成后神经转换自动生效。

IME 本体：karukan-im core（Rust crate 2/4）

karukan-im/core/ 是输入法运行时，核心是一个Empty → Composing → Conversion的状态机：

• core/engine/ — 引擎主逻辑：输入处理、实时转换、分块（chunk）策略、LRU 转换缓存
• server/ —karukan-imserver：基于 stdio 的 JSON-RPC 2.0 服务器，专门给 macOS 前端当"引擎子进程"
• config/settings.rs — 读取用户配置config.toml

Linux 前端：karukan-fcitx5（Rust crate 3/4）

karukan-im/fcitx5/ 让 Karukan 日文输入法以插件形式运行在 fcitx5 框架上：

• src/ffi/ — Rust 侧 C FFI 层，把karukan-im引擎包装成 C API
• include/karukan.h — 暴露给 C++ 插件的 C 头文件
• fcitx5-addon/ — C++ 编写的 fcitx5 插件本体，用 CMake 构建安装

安装只需三步（系统级安装）：

cd karukan-im/fcitx5/fcitx5-addon cmake -B build -DCMAKE_INSTALL_PREFIX=/usr cmake --build build -j && sudo cmake --install build

macOS 前端：Swift 包（唯一非 Rust 组件）

karukan-im/macos/ 是一个标准的 Swift Package（定义见 Package.swift），采用服务器-客户端架构：

• Swift 端只负责与 InputMethodKit 对接：翻译键盘事件、渲染预编辑和候选窗口
• 所有 IME 状态都跑在 Rust 的karukan-imserver子进程里，通过 JSON-RPC 通信

关键文件：

• KarukanInputController.swift — IMK 输入控制器
• EngineProcess.swift — 引擎子进程生命周期管理（崩溃自动重启）
• EngineProtocol.swift — 与 Rust 侧 protocol.rs 一一对应的协议镜像

开发安装只需：

cd karukan-im/macos make install # 构建 + 打包 Karukan.app + 安装到 ~/Library/Input Methods

工具层：karukan-cli（Rust crate 4/4）

karukan-cli/ 是面向开发者的工具箱，提供 4 个二进制：

构建并运行服务器体验在线转换：

cargo run --release --bin karukan-server

新手上手路线与延伸阅读

📌推荐的上手顺序：

1. 读 README.md 了解项目全貌
2. 读 CLAUDE.md 掌握架构与构建命令
3. 跑通测试：cargo test --workspace
4. 按需深入：Linux 用户看 karukan-im/fcitx5/README.md，macOS 用户看 karukan-im/macos/README.md

📚用户向文档（日常使用最常用）：

• 键位绑定：docs/key-bindings.md
• 配置项：docs/configuration.md
• 字典说明：docs/dictionary.md
• 用户字典：docs/user-dictionary.md
• 分块机制：docs/chunking.md
• 符号与全角半角：docs/symbols.md

一句话总结：引擎在karukan-engine/，运行在karukan-im/，平台差异被封在各前端里，工具都在karukan-cli/——掌握这个分层，你就能快速定位 Karukan 日文输入法的任何功能代码。

【免费下载链接】karukanJapanese Input Method System for Linux, macOS, Neural Kana-Kanji Conversion Engine项目地址: https://gitcode.com/GitHub_Trending/ka/karukan