pinyin

保持英文输入源，只在需要时用前缀唤起中文拼音。

pinyin 是一款面向 macOS、实验支持 Windows 的前缀式中文输入工具。它不要求你在中文、英文输入法之间反复切换：平时继续使用系统英文输入源，写代码、操作终端和触发快捷键；需要手动输入中文时，键入前缀进入拼音模式，完成后再用同一字符串退出。

始终保持 macOS 的 ABC 输入源：

''nihao<空格>shijie<空格>''
                ↓
              你好世界

默认的进入与退出字符串都是两个英文单引号：''。

pinyin 想解决的不是“怎样更快地切换中英文输入法”，而是“能不能尽量不切换输入法”。

它适合谁

pinyin 尤其适合这些使用习惯：

• 大部分时间写代码、使用终端或操作键盘快捷键；
• 偶尔需要手动回复中文消息，但中文输入并不是主要工作负载；
• 希望中文输入由一次明确的前缀触发，而不是依赖当前输入法状态；
• 不喜欢 Shift 切换或按应用自动切换带来的状态猜测和意外卡顿。

如果你每天需要长时间、连续地输入中文，传统中文输入法通常会更高效。pinyin 更关注“英文为主、中文偶发”的场景。

核心特性

• 前缀模式：只有检测到指定前缀后才接管拼音输入，未激活时不影响普通字母和终端快捷键。
• Rime 候选：使用 Rime 提供拼音转换与候选结果，支持数字选词和候选翻页。
• 边输入边转换：按空格即可提交当前候选，无需等到退出字符串出现后再统一转换。
• 同串退出：再次键入触发字符串即可结束本次中文输入，回到纯英文键盘行为。
• 中英文混输：可随时把当前字母按原始英文提交；另提供实验性的 Rime 自动混输模式。
• 本地处理：核心监听和拼音转换均在本机完成，不会把输入内容发送到远程服务。
• 可配置：进入/退出字符串、候选数量、布局、选词键、翻页键和英文提交键均可调整。

下载与安装

macOS 是当前主要发布目标；Windows 后端已可从源码运行和打包，但候选面板 UI 仍在演进中。

普通用户推荐使用便携包，不需要在目标 Mac 上安装 Rust、Homebrew 或 librime。

1. 打开 GitHub Releases，按 Mac 芯片下载对应压缩包：Apple Silicon 使用 macos-arm64，Intel Mac 使用 macos-x86_64。

2. 解压后，在终端进入该目录并启动监听器：

   ./run-listener.sh

3. 按程序提示，在“系统设置 → 隐私与安全性”中为压缩包内的主程序开启：

   • 辅助功能；
   • 输入监控。

4. 授权后退出并重新运行 ./run-listener.sh。保持这个进程运行，即可在其他应用中使用 pinyin。

便携包已经包含 librime、运行所需的动态库和基础 Rime 数据。macOS 权限必须由用户在每台设备上手动授予；当前构建尚未经过 Apple 公证，如果系统拦截首次启动，请在“隐私与安全性”中确认允许打开。

第一次输入

1. 确认当前使用的是 macOS 自带的英文输入源，例如 ABC。
2. 在任意普通文本输入区域键入 ''，触发字符会被删除，同时出现候选面板。
3. 输入 nihao，按空格提交首选候选：你好。
4. 继续输入其他拼音，或再次键入 '' 退出中文输入。

完整示例：

输入：''woyaoceshizhongwenshurufa<空格>nihaoma?''
结果：我要测试中文输入法你好吗？

常用操作

按键	默认行为
''	进入或退出中文输入
空格	选择当前候选页的第一个候选
1–0	选择对应位置的候选词
= / -	下一页 / 上一页候选
`	将当前未提交的字母原样作为英文提交
Backspace	编辑当前拼音；紧跟转换后按下可恢复原始拼音
Control-W	删除当前缓冲区中的上一个拼音词

逗号、句号、问号、感叹号等常见半角标点会在中文输入过程中映射为对应的中文标点。候选面板支持横向和纵向布局，默认横向显示 5 个候选。

配置

编辑便携包或仓库根目录中的 pinyin.toml，然后重新启动监听器：

trigger_prefix = "''"
trigger_suffix = "''"

conversion_mode = "segmented"

candidate_layout = "horizontal"
candidate_count = 5
candidate_select_keys = "1234567890"
candidate_page_next_key = "="
candidate_page_previous_key = "-"
english_commit_key = "`"

触发字符串

trigger_prefix 和 trigger_suffix 可以不同，也可以像默认配置一样使用同一字符串。触发字符串不能包含会被当作拼音分隔符处理的标点，包括逗号、句号、问号、感叹号、减号、加号、省略号、波浪号和双引号，以及它们的中文或全角形式。

转换模式

• segmented：稳定的默认模式。分别转换拼音片段，并将常见半角标点映射为中文标点。
• rime-auto：实验模式。把整段输入交给 Rime，由当前输入方案决定中文、英文和标点的提交行为。

也可以只在本次启动中覆盖部分设置：

./run-listener.sh --candidate-layout vertical --candidate-count 8
./run-listener.sh --conversion-mode rime-auto

工作原理

pinyin 不是一个需要切换过去的 macOS 输入源，而是一个全局键盘监听程序。

未激活时，它只等待完整的触发前缀；前缀出现后，它删除触发字符、收集后续拼音，并通过本机的 librime 构建候选。用户提交候选时，pinyin 删除原始拼音并把转换结果写回当前输入区域。退出、切换应用、切换窗口或改变输入源时，本次会话会被清理，避免把一个窗口里的缓冲内容带到另一个窗口。

在 macOS 上，程序使用辅助功能定位输入光标、显示候选面板并完成文本回写，因此必须授予辅助功能和输入监控权限。Windows 后端使用 Win32 Raw Input 捕获键盘事件，并用 SendInput 回写文本；它不需要 macOS 式隐私授权，但普通权限进程无法向管理员权限窗口注入文本。

当前限制

• macOS 是主要支持平台；Windows 支持仍处于实验阶段，当前没有原生候选面板浮窗。
• 当前以终端常驻进程运行，尚无菜单栏界面、自动启动和自动更新。
• 只允许在 macOS 系统输入源下开启会话；第三方输入法即使处于英文模式也不会触发 pinyin。
• 依赖应用正确暴露辅助功能文本位置；少数应用中候选面板可能退回到输入框或鼠标附近显示。
• 当前便携构建没有 Apple 公证，首次运行体验仍有改进空间。
• rime-auto 混输模式仍是实验功能，追求可预测行为时请使用默认的 segmented。

从源码运行

macOS 开发环境需要 Rust、Homebrew 和 librime：

brew install librime
git clone https://github.com/oocococo/pinyin.git
cd pinyin

bash scripts/download-rime-data.sh
bash scripts/run-listener.sh

运行依赖与配置检查：

cargo run -- --doctor
bash scripts/check-librime.sh

运行格式检查、测试和本地转换冒烟测试：

bash scripts/test-conversion.sh

构建包含 librime、动态库和 Rime 数据的 macOS 便携包：

bash scripts/package-portable-macos.sh

Windows 开发环境使用 Rust、LLVM、MSYS2 和 MSYS2 的 librime：

winget install --id Rustlang.Rustup --exact
winget install --id LLVM.LLVM --exact
winget install --id MSYS2.MSYS2 --exact
C:\msys64\usr\bin\bash.exe -lc 'pacman --noconfirm -Syu'
C:\msys64\usr\bin\bash.exe -lc 'pacman --noconfirm -S --needed mingw-w64-x86_64-gcc mingw-w64-x86_64-librime git'
rustup target add x86_64-pc-windows-gnu

powershell -ExecutionPolicy Bypass -File scripts\download-rime-data.ps1
powershell -ExecutionPolicy Bypass -File scripts\test-conversion.ps1
powershell -ExecutionPolicy Bypass -File scripts\run-listener.ps1

构建 Windows 便携包：

powershell -ExecutionPolicy Bypass -File scripts\package-portable-windows.ps1

参与贡献

欢迎提交 Issue 或 Pull Request。无论是输入体验、候选交互、Rime 方案兼容、macOS 应用适配、安装分发，还是文档改进，都很有价值。完整开发流程请参阅 CONTRIBUTING.md。

报告问题时，建议附上：

• macOS 版本与芯片架构；
• 使用的系统输入源和目标应用；
• 可复现的输入序列；
• ./run-listener-debug.sh 生成的相关日志。

日志可能包含按键与输入内容，请在公开提交前先检查并删除敏感信息。

许可证

pinyin 采用 MIT License。便携包中包含的 Rime 数据、librime 及其他运行时依赖继续适用各自许可证，详见 THIRD_PARTY_NOTICES.md。

为什么做 pinyin

在代码、终端和中文消息之间来回工作时，输入法状态本身常常成为一种干扰：回复消息要中文，写代码要英文；一旦忘记切回，tmux 等终端工具的快捷键就可能失效。Shift 切换、输入法自带的中英文模式，以及按应用自动切换工具虽然能缓解问题，但仍需要持续留意“现在到底是什么状态”。

与此同时，越来越多的长段中文可以通过语音完成，真正需要键盘手动输入中文的场景反而变得零散。既然中文输入只是偶发需求，那么为它多键入一个明确的前缀是可以接受的；换来的好处是，绝大多数时间都能安心停留在英文输入源中。

espanso 的触发展开方式启发了这个思路：让一个短前缀开启一段具有特殊语义的输入。pinyin 把这种交互从“展开一个 snippet”延伸成“临时进入一次完整的中文拼音会话”。这就是它与传统输入法切换方案最重要的不同。

致谢

• 感谢 espanso 带来的前缀触发与文本展开灵感。
• 感谢 Rime 及其开放生态提供可靠、可组合的中文输入引擎与数据基础。