# 音元输入法编辑器

**Repository Path**: yinyuanxitong/Yime

## Basic Information

- **Project Name**: 音元输入法编辑器
- **Description**: 音元输入法是通过输入表示音元的音符输入汉字的音码输入法。音元输入法的码元是音元系统的音元。音元系统是根据音元分析法构建的以音元为元素的语音系统。在现代通用汉语中，音元共有52个：充当首音的噪音22个；构成干音的乐音30个。首音，分成虚实两类，分别对应零声母和非零声母。乐音分成高调乐音、中调乐音和低调乐音三类，每类10个。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: https://gitee.com/yinyuanxitong
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-07-28
- **Last Updated**: 2026-04-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
[![GitHub Release](https://img.shields.io/github/release/tsaanghwang/YIME)](https://github.com/tsaanghwang/YIME/releases)
[![Python Version](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/)

# 音元输入法编辑器 (Yinyuan Input Method Editor)

## 概述

音元输入法编辑器(YIME)，简称音元输入法，是以音元为码元的汉语音码输入系统。这套系统通过 52 个音元实现高效汉字输入，相比现行任何以《汉语拼音方案》为基础的全拼输入法具有以下优势：

- **更短的编码长度**：字词平均码长比现行任何一种全拼输入法的字词平均码长都短
- **更高的输入效率**：拣字和拣词率比现行任何一种全拼输入法的拣字和拣词率都高
- **更精的音系表达**：音元系统与已有各种类型的语音系统相比，主要是在和音位系统对比时，能更准确地表达汉语语音系统的特征。

## 重要设计约束

在阅读实现、测试、键盘布局或数据库相关代码前，建议先阅读 [码点与中间层策略](docs/CODEPOINT_POLICY.md)。

该文档明确规定：

- `N01-N24` 与 `M01-M33` 是系统的语义槽位层，不是可删的临时中间产物。
- `PUA-B` 是长期规范承载层，`BMP PUA` 主要是当前平台投影层。
- 测试、重构、数据库调整和键盘布局生成不应绕过语义层直接修改字符结果。

如果后续实现与该策略冲突，应先审查实现链路，而不是先删除中间层或直接改库。

## 特性

### 理论基础

音元输入法以音元系统为基础构建。音元系统是以音元为元素（基本结构单元）的汉语语音系统。在通用现代汉语的音元系统中，音元共有 52 个，分成噪音和乐音两类。其中，噪音有 22 个，乐音有 30 个。噪音特指充当首音的无固定音高的辅音音元，只有音质是区别特征。乐音特指构成干音的有固定音高的舒音音元，既有元音也有辅音，音高和音质都是区别特征。乐音，根据音质分成10类，每类3个；根据音高分成高调乐音、中调乐音和低调乐音三类，每类 10 个。乐音与音位系统的音质音位和声调音位没有简单而又直接的对应关系。在结构上，噪音充当首音；乐音构成干音；首音和干音构成音节。在音元输入系统中，在等长编码模式下，首音只由一个噪音充当，干音均由三个乐音构成；表示每个有声调的汉语音节的码元序列就是构成该有声调的汉语音节的音元序列；系统通过输入构成每个有声调的汉语音节的音元序列输入每个有声调的汉语音节对应的汉字及其构成的语句。

- **首音系统**：首音只由噪音充当，共有22个。首音指位处音节首位的除阻辅音，分成实首音和虚首音两类。在等长编码模式下，首音只由一个噪音充当。首音对应音节声母。实首音对应非零声母。虚首音对应零声母。为简洁计，虚首音通常笼统算作一个音元。
- **干音系统**：干音均由乐音构成。干音指位处在首音后的乐音序列，分成高调干音、升调干音、低调干音和降调干音四类。在等长编码模式下，干音均由三个乐音构成。高调干音由三个高调乐音构成；升调干音由一个低调乐音、一个中调乐音和一个高调乐音构成；低调干音由三个低调乐音构成；降调干音由一个高调乐音、一个中调乐音和一个低调乐音构成。干音对应带调韵母。带调韵母指由声调与韵母构成的音段。高调干音、升调干音、低调干音和降调干音依序对应带声调阴平、阳平、上声和去声的韵母。
- **系统映射**：音元系统与《汉语拼音方案》建立精确对应关系，同时保持自身独立性。

### 基本功能

- **四种模式输入**：全拼、简拼、双拼和并击四种输入模式

在全拼模式下，音节由一个充当首音的音元和三个构成干音的音元构成。音元输入也有与全拼相对的简拼、双拼和并击等输入模式。在全拼中，省略虚首音、把构成干音的两个或三个连续且相同的音元合并成一个音元、从由三个音质相同的音元构成的干音中省略中间的中调乐音，就是简拼。双拼是指在一键输入首音后一键输入干音的输入模式。并击，也称合击，是指在一键输入首音后通过同时输入一组表示干音的音元的组合键输入干音从而输入音节的输入模式。

- **智能编码转换**：实时由语音到音元到汉字双向转换引擎
- **当前实现主线**：Windows 桌面输入法原型，已具备全局监听、候选框和回贴链路

## 码元

在音元输入系统中，码元就是音元系统的音元。

### 编码原则

在音元输入系统中，全拼编码原则是一音一码。

### 键盘布局

根据一音一码原则，音元输入法可用两种键盘输入汉字：

一种是重置键位的美式键盘。这种键盘布局，把键值为 65\~90 和 97\~122的52个键位（对应美式键盘的大小写字母键）47个做成下档键和5个做成上档键，按照一音一码原则，把47个音元映射到下档键上，把5个音元（在把虚首音笼统算作一个音元时）映射到上档键上。这种键盘布局草图如图：

![104键键盘布局](Assets/Images/keyboard-layout104keys-internal-reset.png)

图 1 音元在键盘上的分布

一种是一音一键的中式键盘。这种键盘布局，通过中英文切换键设定输入状态，在中文输入状态下，主键盘区设置56个按键（在美式键盘的47键基础上增加9键并每键设置上下档位），把51个音元和5个表示虚首音的音符映射到键值为 65\~90 和 97\~122的52个键位（对应美式键盘的大小写字母键） 和4个新增键位上并全部设置成下档键。这就是说，这种键盘共有 56 个下档键位：键值为 65\~90 和 97\~122 的键位和4个新增键位。在这键盘上，其它键值的键位，包括数字符号、运算符号、标点符号、变音符号，等等，全部做成上档键位，共有56个上档键位。这种键盘主要用来根据音元输入法输入汉字。

这种键盘布局草图如图：

![128键键盘布局](Assets/Images/keyboard-layout128keys-Chinese.png)

图 2 音元在键盘上的分布

### 键音映射

在音元输入系统中，根据一音一码原则确定键音映射（从键位到音元的对应关系）。在通用现代汉语中，首音只由噪音充当。换句话说，首音就是噪音。因此，从键位到噪音的映射就是从键位到首音的映射。

在音元输入系统中，用 ASCII 码编码，在美式键盘上，音元对应的键位——首音和乐音对应的键位列表见表：

表 1 首音对应的键位

![噪音音元对应的键位](Assets/Images/噪音音元对应的键位.png)

表 2 乐音对应的键位

![乐音音元对应的键位](Assets/Images/乐音音元对应的键位.png)

在音元输入系统中，用 ASCII 码编码，在美式键盘上，键位对应的音元——上档和下档键位对应的音元列表见表：

表 3 键位对应的音元

![键位对应的音元](Assets/Images/键位对应的音元.png)

在美式键盘上，用 ASCII 码编码，音元与键位的对应关系如图：

![104键键盘布局](Assets/Images/keyboard-layout104keys.png)

在新式键盘上，用 ASCII 码编码，音元与键位的对应关系如图：

![128键键盘布局](Assets/Images/keyboard-layout128keys-Chinese.png)

### 音元音符

在音元输入系统中，根据一音一符原则确定音元的音符。在音元系统中，表示音元的字符也简称为音符。在音元系统中，为与中文或英文混排，表示音元，一共用到三套字符：与中文兼容的全宽字符、与中文兼容的半宽字符和与英文兼容的比例字符。

在音元输入系统中，用与中文兼容的全宽字符和与英文兼容的半宽字符来记音，音元的音符列表见表：

表 3 首音的音符

![首音的音符](Assets/Images/首音的音符.png)

表 4 乐音的音符

![乐音的音符](Assets/Images/乐音的音符.png)

这套字符只是临时的试样，在使用过程中，可根据社会认可度修改。

## 干音

根据音元分析法标记干音，既可采用与汉字兼容的字符标音也可采用与英文兼容的字符标音。用与汉字兼容的字符来标音，其具体方法是：首先把标记干音的三个音元的音符竖向排成一列，然后，或把这列字符制作成一个高度占居一个汉字高度、宽度占居半个汉字宽度的标记干音的半宽字符，或把这列字符制作成一个高度占居一个汉字高度、宽度占居一个汉字宽度的标记干音的全宽字符。半宽字符在首音和干音拼合成音节时使用。全宽字符在首音或干音游离在行文中时使用。干音由呼音和韵音构成。韵音由主音和末音构成。韵音的音质被简称为韵质。干音根据韵质是否相近或相同分成十八类。

干音根据韵质分类采用与汉字兼容的字符标音详见表 5。

表 5 干音（采用半宽字符标音）

![干音（采用半宽字符标音）](Assets/Images/干音的半宽字符.png)

在该表中，列标题“未”、“噫”、“呜”和“吁”依序是未名呼干音、齐齿呼干音、合口呼干音和撮口呼干音的简称。在音元系统中，根据呼音的音质分类，干音分成未名呼干音、齐齿呼干音、合口呼干音和撮口呼干音四类。未名呼干音指除齐齿呼干音、合口呼干音和撮口呼干音外的干音。齐齿呼干音指呼音的音质是 i[i]的干音。合口呼干音指呼音的音质是 u[u]的干音。撮口呼干音指呼音的音质是 ʏ[ʏ]的干音。在根据韵音的音质的差异分类制表时，把未名呼干音、齐齿呼干音、合口呼干音和撮口呼干音各放在一列，把韵质相同或相近的干音合放在一行。

用与英文兼容的字符来标音，其具体方法是：把标记干音的三个音元的音符制作成三个高度占居半个汉字高度、宽度占居半个汉字宽度的半高半宽字符，并把标记干音的三个半高半宽字符依序在基线上横向排成一列标记干音的字符。

干音根据韵质分类采用与英文兼容的字符标音详见表6。

表 6 干音（采用音符序列标音）

![干音（采用音符序列标音）](Assets/Images/干音的音列.png)

干音分别采用半宽字符、音符序列、用上标来标调的组合式音符、《国际音标》和《汉语拼音方案》五种常用方式记音的对应关系列表见表7。

表 7 干音常用几种记音方式的对应关系

![干音的记音](Assets/Images/干音的记音.png)
在该表中，列标题“高”、“升”、“低”和“降”依序是高调节调、升调节调、低调节调和降调节调的简称。高调节调、升调节调、低调节调和降调节调依序就是高调阴平、升调阳平、低调上声和降调去声。

## 音节

在音元系统中，首音和干音构成音节。由首音和干音构成的音节与有声调的音节一一对应。

音节表示例：

表 8 首音与 󰇘 类干音构成的音节
![音节表示例](Assets/Images/音节表示例.png)

音节总表暂不列出。

综述说明，在音元输入系统中，表示每个有声调的汉语音节的码元序列就是构成该有声调的汉语音节的音元序列，系统通过输入构成每个有声调的汉语音节的音元序列输入每个有声调的汉语音节对应的汉字及其构成的语句。强调说明，音元、音符与键位的对应关系可根据设计和使用需要修改。

## 码表

### 单字码表

根据音元系统的音节和《汉语拼音方案》的有声调的音节的一一对应关系构建音元输入法的单字码表。单字码表根据现有带调全拼单字码表转换。

### 词语码表

根据单字码表构建词语码表。词语码表根据现有带调全拼词语码表转换。在输入单字和词语基础上通过字频调整、词频调整和语句及语段生成算法（语义算法）输入语句和语段。

## 结论

音元输入法，在全拼模式下，是平均码长最短的音码输入法。

## 快速开始

### 环境要求

- Windows 10 / 11
- Python 3.12.x
- 可选：Miniconda / conda
- 可选：Git LFS

### 安装步骤

```bash
# 克隆仓库
git clone https://github.com/tsaanghwang/YIME.git
cd YIME

# 推荐：创建并激活 Python 3.12 conda 环境
conda create -n yime_env python=3.12
conda activate yime_env

# 安装当前 Windows 输入法原型依赖
pip install -r requirements_py312.txt

# 启动输入法原型
python -m yime.input_method.app
```

### 使用说明

1. 优先阅读 [INSTALLATION_GUIDE.md](INSTALLATION_GUIDE.md) 完成 Python 3.12 环境配置。
2. 使用 `python -m yime.input_method.app` 或 `python run_input_method.py` 启动当前 Windows 桌面输入法原型。
3. 参考 [INPUT_METHOD_SOLUTION.md](INPUT_METHOD_SOLUTION.md) 了解当前实现边界，再结合 [docs/USAGE.md](docs/USAGE.md) 查看使用说明。

## 项目结构

```text
YIME/
├── yime/                 # Python 核心引擎
├── pinyin/               # 拼音处理模块
├── syllable/             # 音节分析模块
├── src/                  # 历史前端代码与实验性界面资源
├── docs/                 # 文档
├── scripts/              # 辅助脚本（见下方说明）
├── tests/                # 测试文件
└── external_data/        # 外部数据源
```

### scripts/ 目录说明

`scripts/` 目录包含辅助脚本文件，主要用于：

- **临时验证脚本**：开发过程中用于验证功能和结果的临时脚本
- **辅助工具脚本**：方便开发工作的辅助工具

**注意**：这些脚本大多是临时验证结果的辅助文件，项目完成后一般不再需要。一些是方便工作作的辅助工具，项目完成后一般也不再需要。

**主要脚本文件**：

| 文件 | 用途 | 状态 |
| --- | --- | --- |
| `final_test_script.py` | 韵母动态添加功能测试 | 临时验证 |
| `complete_workflow_script.py` | 完整工作流程测试 | 临时验证 |
| `dynamic_finals_script.py` | 动态韵母测试 | 临时验证 |
| `ganyin_script.py` | 干音分析脚本 | 临时验证 |
| `mysql_conn_script.py` | MySQL连接测试 | 辅助工具 |

## 相关文档

- [安装指南](INSTALLATION_GUIDE.md)
- [Python 3.12 快速开始](QUICKSTART_PY312.md)
- [安装与部署说明](docs/INSTALL.md)
- [便携版 Python 3.12 安装指南（无需管理员权限）](PORTABLE_PYTHON_GUIDE.md)
- [Python 3.12 安装方案](PYTHON312_INSTALLATION_GUIDE.md)
- [Python 3.12 直接安装指南](DIRECT_INSTALL_GUIDE.md)
- [使用说明](docs/USAGE.md)
- [输入法实现方案](INPUT_METHOD_SOLUTION.md)
- [开发者文档](docs/DEVELOPMENT.md)
- [数据文件结构说明](docs/DATAFILES.md)
- [码点与中间层策略](docs/CODEPOINT_POLICY.md)
- [真源文件与生成产物清单](docs/SOURCE_AND_ARTIFACTS.md)

### 重要设计约束

- [码点与中间层策略](docs/CODEPOINT_POLICY.md)：说明 `N01-N24`、`M01-M33` 的语义层地位，以及 `PUA-B`、`BMP PUA` 和平台投影的分工。后续测试、重构、数据库调整和键盘布局生成不应绕过该约束。

### 当前原型状态

- [输入法实现方案](INPUT_METHOD_SOLUTION.md)：记录当前 Windows 桌面输入法原型的实现边界、已实现能力、限制和下一步方向。该文档优先于仓库内更早的可行性说明或临时方案稿。

### 无管理员权限安装

- [便携版 Python 3.12 安装指南（无需管理员权限）](PORTABLE_PYTHON_GUIDE.md)：当你无法安装系统级 Python 或不方便使用 conda 时，使用便携 Python 3.12 继续沿当前主线部署。

### 快速启动

- [Python 3.12 快速开始](QUICKSTART_PY312.md)：只保留最短启动命令，适合已经理解当前主线、只想尽快跑起原型时使用。

## 使用许可

本项目采用 [MIT 许可证](LICENSE)，允许自由使用、修改和分发。商业使用需遵守以下条款：

1. **开源使用**：遵循 MIT 许可证条款
2. **商业授权**：需联系作者获取商业许可证
3. **学术引用**：科研使用请引用相关论文

## 技术支持

### 官方渠道

- GitHub 仓库: [tsaanghwang/YIME](https://github.com/tsaanghwang/YIME)
- 问题追踪: [GitHub Issues](https://github.com/tsaanghwang/YIME/issues)
- 讨论区: [GitHub Discussions](https://github.com/tsaanghwang/YIME/discussions)

### 贡献指南

我们欢迎各种形式的贡献!请阅读[CONTRIBUTING.md](CONTRIBUTING.md)了解:

- 代码提交规范
- 测试要求
- Pull Request 流程

## 核心团队

- **创始人**:
  - Huang Chang (黄畅) - [yinyuanxitong@foxmail.com](mailto:yinyuanxitong@foxmail.com)
- **主要贡献者**:
  - [成为贡献者](CONTRIBUTORS.md)