From e715845d1958f7b746de93fe306c7de852c879e8 Mon Sep 17 00:00:00 2001 From: songsenand Date: Sat, 28 Feb 2026 17:16:27 +0800 Subject: [PATCH] =?UTF-8?q?feat(readme):=20=E6=B7=BB=E5=8A=A0=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=E6=9E=B6=E6=9E=84=E3=80=81=E6=8A=80=E6=9C=AF=E7=BB=86?= =?UTF-8?q?=E8=8A=82=E4=B8=8E=E5=BC=80=E5=8F=91=E8=B7=AF=E7=BA=BF=E5=9B=BE?= =?UTF-8?q?=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 202 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 202 insertions(+) diff --git a/README.md b/README.md index 41efcce..7d99c3e 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,204 @@ # SUIME +**SUIME** 是一个基于深度神经网络的高性能输入法引擎项目。它采用现代化的 **C/S (Client/Server)** 架构，将繁重的 AI 推理任务与轻量级的输入交互界面解耦。 + +- 🚀 **核心智能**：基于 Rust 构建的高性能推理服务端，支持 INT8 量化 ONNX 模型。 +- 🐧 **原生 Linux 支持**：提供基于 `fcitx5` 的高性能插件。 +- 🪟 **跨平台愿景**：架构设计原生支持 Windows (计划基于 Rime/Weasel) 和 macOS。 +- 🔌 **语言无关协议**：基于 MessagePack 的通用通信协议，允许任意语言编写前端。 + +--- + +## 🏗️ 整体架构 + +项目分为两个核心部分：**智能服务端** 和 **平台相关客户端**。两者通过高效的二进制协议通信。 + +```mermaid +graph TD + subgraph "AI Inference Server (Rust)" + S[Socket Listener
UDS / TCP / Named Pipe] + M[ONNX Runtime Engine] + T[Tokenizer] + S --> M + M --> T + end + + subgraph "Client Frontends" + L[Linux Client
fcitx5 Plugin (C++)] + W[Windows Client
Rime/Weasel Mod (Planned)] + Mac[macOS Client
Rime/Squirrel Mod (Planned)] + end + + L -- "Unix Domain Socket" --> S + W -- "TCP / Named Pipes" --> S + Mac -- "Unix Domain Socket / TCP" --> S +``` + +### 1. 服务端 (Rust) +- **并发模型**：使用 `std::thread` 或 `tokio` 处理多客户端连接。 +- **推理引擎**：集成 `onnxruntime`，加载 INT8 量化模型以实现低延迟推理。 +- **分词处理**：可选集成 `tokenizers` 库进行预处理。 +- **通信适配**： + - **Linux/macOS**：默认使用 **Unix Domain Socket (UDS)**，利用文件系统路径通信，零拷贝，极低延迟。 + - **Windows**：自动切换为 **TCP (localhost)** 或 **Named Pipes**，确保跨平台兼容性。 +- **数据协议**：接收/发送 **MessagePack** 序列化的二进制数据。 + +### 2. 客户端 (Frontend) +- **Linux (当前实现)**： + - 基于 `fcitx5` 框架开发的 C++ 插件。 + - 直接通过 UDS 与服务端通信。 + - 负责捕获按键、获取上下文、渲染候选词面板。 +- **Windows (中长期计划)**： + - **目标框架**：基于 **Rime (中州韵)** 的 Windows 前端 **Weasel (小狼毫)** 进行定制开发。 + - **实现方式**：修改 Weasel 源码，将其内部解码逻辑替换为通过网络调用 Rust 服务端。 + - *注：由于 Windows TSF 架构复杂性，直接开发原生 IME 难度极大，复用 Rime 生态是最佳路径。* +- **macOS (未来计划)**： + - 基于 **Rime** 的 macOS 前端 **Squirrel (鼠须管)** 进行类似定制。 + +--- + +## 📂 项目目录结构 + +```text +SUIME/ +├── Cargo.toml # Rust 服务端配置 +├── src/ # Rust 服务端源码 +│ ├── main.rs # 入口：根据 OS 自动选择监听模式 (UDS/TCP) +│ ├── model.rs # ONNX 模型加载与推理封装 +│ ├── tokenizer.rs # 分词器封装 +│ ├── protocol.rs # 跨平台通用的请求/响应结构体 (MessagePack) +│ └── socket.rs # 【核心】通信层抽象 (支持 UDS/TCP 条件编译) +├── fcitx5-ext/ # [Linux] fcitx5 插件源码 +│ ├── CMakeLists.txt +│ ├── src/ +│ │ ├── myengine.cpp # 输入法逻辑 +│ │ ├── socket_client.cpp # Linux UDS 客户端实现 +│ │ └── protocol.hpp # 与服务端一致的协议定义 +├── clients/ # [未来] 其他平台客户端 +│ ├── weasel-mod/ # (计划) Windows Rime 定制版 +│ └── squirrel-mod/ # (计划) macOS Rime 定制版 +├── models/ # ONNX 模型文件 & 词表 +└── README.md +``` + +--- + +## 🛠️ 技术细节与接口定义 + +### 通信协议 (Protocol) +为了保证跨语言和跨平台兼容性，应用层协议采用 **TLV (Type-Length-Value)** 风格封装 **MessagePack** 数据： +1. **Header**: 4 字节大端无符号整数 (`uint32_t`)，表示后续 Payload 的长度。 +2. **Payload**: MessagePack 序列化的二进制数据。 + +**数据结构定义 (`protocol.rs` / `protocol.hpp`):** + +```rust +// Rust 服务端定义 +use serde::{Serialize, Deserialize}; + +#[derive(Debug, Serialize, Deserialize)] +pub struct Request { + pub pinyin: String, // 用户输入的拼音串 + pub context: String, // 光标前文本 (用于上下文预测) + pub personal: Vec, // 用户个性化词库 (可选) +} + +#[derive(Debug, Serialize, Deserialize)] +pub struct Candidate { + pub id: u32, // 词项 ID + pub text: String, // 候选词文本 (也可由客户端查表) + pub weight: f32, // 置信度/权重 +} + +#[derive(Debug, Serialize, Deserialize)] +pub struct Response { + pub candidates: Vec, +} +``` + +### 跨平台 socket 适配策略 +服务端代码使用 Rust 的条件编译 (`cfg`) 自动适配操作系统： + +- **`#[cfg(unix)]`**: + - 使用 `std::os::unix::net::{UnixListener, UnixStream}`。 + - 绑定路径：`/tmp/su-ime.sock` (可配置)。 + - 优势：无需网络栈开销，权限控制基于文件系统。 +- **`#[cfg(windows)]`**: + - 使用 `std::net::{TcpListener, TcpStream}`。 + - 绑定地址：`127.0.0.1:23333` (可配置)。 + - 优势：原生支持 Windows，便于穿透 WSL 或容器边界。 + +--- + +## 🗺️ 开发与部署路线图 + +### 阶段一：Linux 原生完善 (Current) +- [x] 完成 Rust 服务端 UDS 通信与 ONNX 推理。 +- [x] 完成 fcitx5 插件开发与联调。 +- [ ] 性能优化：引入线程池，减少上下文切换开销。 +- [ ] 打包：提供 `.deb` / `.rpm` 安装包及 systemd 用户服务配置。 + +### 阶段二：服务端跨平台重构 (Short Term) +- [ ] **通信层抽象**：重构 `socket.rs`，实现 UDS/TCP 自动切换逻辑。 +- [ ] **Windows 服务端验证**：在 Windows 上编译并运行 Rust 服务端，通过 TCP 暴露接口。 +- [ ] **macOS 服务端验证**：验证 macOS 下 UDS 兼容性及签名问题。 + +### 阶段三：Windows 客户端适配 (Mid-Long Term) +- [ ] **Rime/Weasel 调研**：深入分析 Weasel 源码，确定 Hook 点。 +- [ ] **原型开发**：Fork Weasel 项目，移除内置拼音引擎，植入 TCP 客户端模块。 +- [ ] **UI 适配**：确保候选词窗口在高分屏下的渲染效果。 +- [ ] **安装包制作**：制作 Windows 安装程序，包含 Rust 服务端 (后台服务) 和定制版 Weasel。 + +### 阶段四：macOS 客户端适配 (Future) +- [ ] 基于 Squirrel 进行类似 Weasel 的定制开发。 +- [ ] 适配 macOS 输入法沙盒机制 (可能需要将服务端作为 LaunchAgent 运行)。 + +--- + +## 🚀 快速开始 (Linux) + +### 前置依赖 +- Rust Toolchain (`rustup`) +- CMake, g++, pkg-config +- fcitx5 开发库 (`fcitx5-dev`, `libfcitx5utils-dev`) +- libmsgpack-c + +### 构建服务端 +```bash +cd SUIME +cargo build --release +# 二进制文件位于 target/release/su-ime +``` + +### 构建 fcitx5 插件 +```bash +cd fcitx5-ext +mkdir build && cd build +cmake .. -DCMAKE_BUILD_TYPE=Release +make +sudo make install +``` + +### 运行 +1. 启动服务端： + ```bash + ./target/release/su-ime --model ../models/model.onnx --socket /tmp/su-ime.sock + ``` +2. 重启 fcitx5 或在输入法设置中启用 "SUIME"。 +3. 开始输入体验 AI 预测。 + +--- + +## ⚠️ 注意事项 + +1. **延迟敏感**：输入法对延迟极其敏感。在跨平台架构（特别是 Windows TCP 模式）下，需严格测试网络栈带来的额外延迟（通常 localhost TCP 延迟 < 0.1ms，可接受）。 +2. **安全性**： + - Linux UDS 依赖文件权限，请确保 `/tmp/su-ime.sock` 仅对当前用户可见。 + - Windows TCP 模式默认仅绑定 `127.0.0.1`，严禁绑定 `0.0.0.0` 以防外部攻击。 +3. **服务保活**：建议配置 systemd (Linux) 或 Windows Service 来守护 Rust 服务端进程，确保其崩溃后能自动重启。 + +--- + +## 📄 许可证 + +本项目采用 MIT 许可证。