# SimeApp

**Repository Path**: noctua/SimeApp

## Basic Information

- **Project Name**: SimeApp
- **Description**: Forked from https://github.com/Ismantic/SimeApp
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: encv
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-25
- **Last Updated**: 2026-11-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 是语输入法应用

Forked from: https://github.com/Ismantic/SimeApp

SimeApp 包含是语输入法的 Android、macOS 和 Fcitx5 前端。C++ 输入引擎、CLI
工具及模型训练流水线位于独立的
[Sime](https://gitee.com/noctua/Sime) 仓库。

三端共用同一套引擎、同一份键位定义和同一套模型，全部离线运行：输入内容、
用户词库、剪贴板历史都不离开本机。

本文按「安装与启用 → 使用 → 键位与布局」组织，每个小节再按 Android、macOS、
Linux 三个系统分别展开。只想看某个平台的话，直接跳到对应小节即可。

## 安装与启用

目前需要自行编译，见[构建指南](docs/build.md#从源码构建)。

### Android

安装 APK 后分两步启用：

1. 在系统中启用：系统设置 → 语言和输入法 → 屏幕键盘 → 勾选「是语输入法」。
2. 切换为当前输入法：下拉通知栏点「选择输入法」，或按地球键。

应用主界面（应用抽屉里打开「是语输入法」）带同样的引导，并实时显示当前是否
已启用、是否为当前输入法，底部还有一个文本框可以当场试打。

### macOS

用 `.pkg` 安装后，在系统设置里启用：

1. 在系统设置中启用：系统设置 → 键盘 → 输入法「编辑」→ 左下角 `+` →
   简体中文 → 「是语」→ 勾选。
2. 切换输入法：默认 `Ctrl+Space`。与系统自带输入法冲突时，到
   系统设置 → 键盘 → 键盘快捷键 → 输入法 改成别的组合。

输入源的 Input Mode 标识是 `com.sime.inputmethod.SimeIME.Hans`。

手动安装源码构建产物时按下面走，先删干净旧版本再拷贝 —— 残留同名目录时
`cp -R` 会把新包拷成嵌套副本，系统注册的还是旧包，输入法会从键盘设置里「凭空
消失」：

```bash
APP="/Library/Input Methods/SimeIME.app"
sudo rm -rf "$APP"
ls -d "$APP" 2>/dev/null && { echo "旧版本还没删干净，先处理再继续"; exit 1; }

sudo cp -R build/macos/SimeIME.app "$APP"
sudo codesign --force --deep --sign - "$APP"   # 构建产物的签名在暂存资源前就签好了，是失效的，必须重签
sudo chown -R root:wheel "$APP"
sudo xattr -dr com.apple.quarantine "$APP" 2>/dev/null
sudo xattr -dr com.apple.provenance "$APP" 2>/dev/null
```

装完还要用登录用户身份注册到 LaunchServices，并注销磁盘上其它同 bundle id
的副本（旧的构建产物、废纸篓里的旧包都算）—— 注册指向已经不存在的 app 时，
系统会把输入源解析过去，表现就是输入法凭空消失。完整流程见
[macOS 安装说明](macOS/README.md#安装)。

### Linux（Fcitx5）

Arch Linux 直接用 AUR：

```bash
yay -S fcitx5-sime
fcitx5 -r
```

装完打开 `fcitx5-configtool`，搜索并添加「Sime」，随后即可切换使用。后续版本
会随常规的 `yay -Syu` 一起更新。

其它发行版可以照 [Fcitx5 手动编译安装](Linux/fcitx5/README.md#手动编译安装)
的步骤自行构建，模型文件也要一并装到 `/usr/share/sime/`。

## 使用

### Android

候选栏左侧的 ⚙ 齿轮打开「设置」面板。

实体键盘布局有内置的 QWERTY 与 WRDP 两套，也可以导入自己的键位 JSON。

### macOS

候选窗：显示组字串和候选词，尺寸由 `ui.yaml` 决定，见
  [macOS/README.md 的界面尺寸配置](macOS/README.md#界面尺寸配置uiyaml)。

### Linux（Fcitx5）

1. 在 `fcitx5-configtool` 中添加「Sime」输入法。
2. 切换到 Sime，输入拼音，数字键或空格选词。

在配置工具中选中「是语」→ 配置，可以改键盘布局、选择自定义键位文件等。

## 键位与布局

三端使用同一份内置键位定义 `assets/keylayouts/wrdp.yaml`，由
`python3 tools/generate_keylayouts.py` 生成各自的键位表。用户在
`keylayout.json` 里可以覆盖内置键位、继承或新增布局，格式与示例见
[用户键位配置](docs/keylayout-config.md)。

### Android

- 屏幕键盘：全键盘与九宫格两套，不受 WRDP 影响。
- 实体键盘：在设置面板的「实体键盘」一栏切换，也可以导入自己的键位 JSON。
- WRDP：外接键盘支持 WRDP 键位方案，启用入口、按键映射和退格方式见
  [WRDP 键位](docs/wrdp-keyboard.md)。

### macOS

- 内置布局：输入法只内置美式标准布局（QWERTY）。WRDP 不在输入法内部，
  改由 HID 层承担 —— 两条路二选一，同时开会二次映射。
- 用户键位：`~/Library/Application Support/Sime/keylayout.json`，首次运行
  自动写模板。改完在菜单点「重新加载键位表」生效，不用改源码重编译。
- 界面尺寸：`Contents/Resources/ui.yaml` 决定候选窗与中/英指示方块的尺寸，
  用户可以在 `~/Library/Application Support/Sime/ui.yaml` 按单项覆盖，改完点
  「重新加载界面配置」生效。详见 [macOS/README.md](macOS/README.md#界面尺寸配置uiyaml)。

#### 用 HIDUtil 改全局键位

macOS 上的 WRDP 全部交给 HID 层：字符层、功能键层、修饰键层都在 HID 层完成，
输入法侧保持 QWERTY。原理是 hidutil 在 HID 层改键位，`NSEvent.keyCode`
随之被改写，输入法按 keyCode 查自己的表，得到的就是目标字符。

工具在 `tools/hidutil-remap/`，不依赖第三方运行时。先编译：

```bash
mkdir -p build/hidutil-remap
swiftc -swift-version 5 -O tools/hidutil-remap/RemapCore.swift \
  tools/hidutil-remap/main.swift -o build/hidutil-remap/hidutil-remap
```

初始化配置（拒绝覆盖已有配置）并应用：

```bash
build/hidutil-remap/hidutil-remap init --from assets/keylayouts/wrdp.hidutil.json
build/hidutil-remap/hidutil-remap apply
```

日常切换与查看：

```bash
build/hidutil-remap/hidutil-remap switch wrdp       # 切到 WRDP
build/hidutil-remap/hidutil-remap switch standard   # 切回标准
build/hidutil-remap/hidutil-remap status            # 看当前系统映射
build/hidutil-remap/hidutil-remap watch             # 监听配置，热重载
```

与输入法配合：输入法菜单保持「标准 (QWERTY)」，全局键位由本工具控制 ——
`switch wrdp` 打开、`switch standard` 关掉，两边不要同时改键位。输入法菜单底部
的「HID 重映射：已启用(N 条) / 未启用 / 状态未知」读的是系统真实的
`UserKeyMapping`，不是输入法的记忆；状态显示为已启用时，下面会出现
「关闭 HID 重映射」，点一下就把系统映射清空（等价于 `switch standard`）。
注意它只清系统映射，不动 `~/Library/Application Support/Sime/hidutil.json`
里的 `active` —— 想彻底关掉得先停掉 `watch`。

几点必须知道：

- 映射全局生效，输入法激活与否都一样，终端、Vim 也吃这套。
- 别和系统 `.keylayout` 叠加，两边都改键位会二次映射。
- 修饰键映射会让修饰键身份消失（本项目把左 Option 换成退格），所有 ⌥ 组合键
  随之失效。
- `UserKeyMapping` 在重启或键盘服务移除后可能丢失，设备重连后需重新 `apply`。
- 首次修改前会自动备份到 `<config>.backup.json`；`restore` 可恢复。

完整说明、备份恢复、失败回滚与手工应用见
[hidutil-remap 文档](tools/hidutil-remap/README.md)。

### Linux（Fcitx5）

- 在配置工具中选中「是语」→ 配置 →「键盘布局」选择 `WRDP`，应用后立即生效，
  选择会持久保存。
- 自定义键位文件放在 `~/.config/fcitx5/sime/keylayout.json`（遵循
  `XDG_CONFIG_HOME`），或在配置工具的「键位 JSON 文件」里填绝对路径。
- 映射、功能键与退格替代方式见[WRDP 键位](docs/wrdp-keyboard.md)。

## 目录

- `Android/`：Android IME、JNI 适配层及 JUnit 测试。见
  [Android 构建说明](Android/BUILD.md)。
- `macOS/`：InputMethodKit 前端、Swift UI 和安装包脚本。见
  [`macOS/README.md`](macOS/README.md)。
- `Linux/fcitx5/`：Fcitx5 插件。见 [`Linux/fcitx5/README.md`](Linux/fcitx5/README.md)。
- `Linux/package/`：Arch Linux 打包文件。
- `cmake/`：定位并引入 Sime 引擎的共享 CMake 模块。
- `assets/keylayouts/`：三端共享的键位定义 `wrdp.yaml` 与生成的 hidutil 映射。
- `tools/`：键位表生成器、hidutil-remap 工具及其测试。
- `docs/`：技术调研与工程记录。
  - [构建指南](docs/build.md)：三端的命令行编译、验证，以及 Android 构建踩坑记录。
  - [WRDP 键位](docs/wrdp-keyboard.md)：三端共用的键位语义、映射层选择、修饰键与退格行为，以及 macOS 端的实现约束与排查方法。
  - [用户键位配置](docs/keylayout-config.md)：`keylayout.json` 的格式与示例。
  - [产物体积说明](docs/package-size.md)：各端产物的构成与体积。
  - [剪贴板功能集成方案](docs/clipboard-in-ime.md)：独立软件 vs 集成输入法的技术路线对比。
  - [语音识别（ASR）方案](docs/speech-recognition-in-ime.md)：免费 API 与离线本地模型的选型对比。

## 隐私

所有输入和用户数据仅在本机处理。完整说明见 [PRIVACY.md](PRIVACY.md)。

## License

[Apache-2.0](LICENSE)