Cursor IME HUD
English | 简体中文
Cursor IME HUD 是一个面向 VS Code / Cursor 与 JetBrains IDE 的输入法状态提示项目。它会在编辑器主光标附近显示当前中文 / 英文输入状态，并同步到状态栏，帮助开发者在编码、写文档、搜索和聊天输入时减少“想输入英文却打出中文”的误输入。
项目遵循一个明确边界：只显示输入法状态，不自动切换输入法，不读取文件内容、剪贴板或实际输入文本。
目录
项目定位
中文开发环境中，输入法状态经常在 IDE、终端、搜索框、聊天框和浏览器之间切换。Cursor IME HUD 通过一个轻量的 caret-adjacent HUD 与状态栏提示，将当前 IME 状态直接放在编辑上下文附近。
仓库同时维护两个客户端：
| 客户端 |
位置 |
发布产物 |
| VS Code / Cursor 扩展 |
仓库根目录 TypeScript 项目 |
.vsix / VS Code Marketplace 扩展 |
| JetBrains IDE 插件 |
jetbrains/ |
JetBrains Marketplace ZIP 插件 |
| Native helper |
native/ |
Windows / macOS / Linux helper 与 .sha256 校验文件 |
两个客户端共享同一套产品语义、图标方向和跨平台 native helper 协议。JetBrains 插件的独立开发说明见 jetbrains/README.md。
功能特性
- 光标旁 HUD：在主光标附近显示紧凑、半透明的输入状态标签。
- 状态栏同步提示：状态栏显示
IME: 中、IME: 英、IME: ZH、IME: EN 或 IME: ?。
- 两组内置标签预设：支持
中 / 英 与 ZH / EN，不提供任意自定义标签，避免配置复杂度和 UI 噪声。
- 两种 HUD 样式：
text+icon 紧凑图标模式与 text 纯文字模式。
- 稳态宽限窗口：短时间
unknown 状态会保留最近稳定状态，降低 Windows IME 信号抖动造成的闪烁。
- 跨平台 native helper：通过独立 Rust helper 读取 Windows、macOS 与 Linux 的输入源 / IME / keyboard layout 状态，扩展侧只消费 JSONL 状态流。
- 诊断命令：内置诊断输出，便于定位 helper、协议、状态解析和生命周期问题。
- 保守权限模型：不读取文件正文，不读取剪贴板，不记录输入内容，不改变系统输入法状态。
支持范围
| 项目 |
当前状态 |
| 操作系统 |
Windows 10 / 11、macOS、Linux |
| 架构 |
win-x64、win-arm64、darwin-x64、darwin-arm64、linux-x64、linux-arm64、linux-armhf helper |
| VS Code |
^1.107.0 |
| Cursor |
兼容 VS Code 扩展安装方式 |
| JetBrains |
2026.1+ 平台插件 |
| IME 识别 |
主要面向中文 IME；macOS/Linux 依据输入源或 IME 后端推断，不能识别时显示 unknown |
| 多光标 |
仅渲染主光标状态 |
| 自动切换 |
不支持，也不会主动切换输入法 |
效果预览
HUD 会锚定在当前主光标附近。状态可靠时显示当前输入模式；状态不可判定时隐藏 HUD，并在状态栏以 ? 表示未知状态。
安装
从 GitHub Release 安装
前往 Releases 下载最新版本：
- VS Code / Cursor：
cursor-ime-hud-<version>.vsix
- JetBrains：
cursor-ime-hud-jetbrains-<version>.zip
VS Code / Cursor 可使用命令行安装：
code --install-extension .\cursor-ime-hud-<version>.vsix
Cursor 也可以在扩展页面选择 Install from VSIX... 并选择下载的 .vsix 文件。
JetBrains IDE 可在 Settings / Plugins / Install Plugin from Disk... 中选择下载的 ZIP。
安装已发布产物不需要额外安装 Rust、MSVC、PowerShell 或其他构建工具。构建工具只在从源码重新编译 helper 时需要。
快速开始
- 安装对应 IDE 的发布产物。
- 在 Windows、macOS 或 Linux 上打开 VS Code / Cursor 或 JetBrains IDE。
- 打开任意可编辑文件，并将光标放在编辑区域。
- 在中文输入法中切换中文 / 英文输入状态。
- 观察光标附近 HUD 与状态栏提示。
默认标签预设为 中 / 英。如果希望使用拉丁字母提示，可将 labelPreset 切换为 ZH / EN。
配置项
VS Code / Cursor
| 设置 |
默认值 |
说明 |
cursorImeHud.overlay.enabled |
true |
是否启用光标旁 HUD。 |
cursorImeHud.overlay.labelPreset |
zh-en |
标签预设：zh-en 显示 中 / 英，en-zh 显示 ZH / EN。 |
cursorImeHud.overlay.cnColor |
#FF5252 |
中文状态图标强调色。 |
cursorImeHud.overlay.enColor |
#1E90FF |
英文状态图标强调色。 |
cursorImeHud.overlay.backgroundEnabled |
true |
text 纯文字模式下是否显示圆角背景。 |
cursorImeHud.overlay.backgroundOpacity |
0.72 |
背景透明度；text+icon 控制图标底色，text 控制文字背景。 |
cursorImeHud.overlay.opacity |
0.78 |
HUD 整体透明度，范围 0.15 到 1。 |
cursorImeHud.overlay.mode |
text+icon |
HUD 渲染模式；text+icon 显示紧凑图标，text 显示紧凑纯文字 HUD。 |
cursorImeHud.statusBar.enabled |
true |
是否在状态栏显示输入状态。 |
cursorImeHud.overlay.hideWhenEditorUnfocused |
true |
VS Code / Cursor 窗口失焦时是否隐藏编辑器 HUD。 |
cursorImeHud.overlay.offsetX |
6 |
HUD 横向偏移，范围 0 到 32；会随编辑器缩放。 |
cursorImeHud.overlay.offsetY |
20 |
HUD 纵向偏移，范围 -30 到 30；会随编辑器缩放。 |
JetBrains
JetBrains 插件提供同等核心配置：
- 状态栏提示开关
- 光标旁 HUD 开关
- 编辑器失焦时隐藏 HUD
中 / 英 与 ZH / EN 标签预设- 中文 / 英文状态强调色
- HUD 透明度与偏移量
命令
| 命令 |
说明 |
Cursor IME HUD: Toggle Overlay |
开启或关闭光标旁 HUD。 |
Cursor IME HUD: Refresh IME State |
主动刷新一次 IME 状态。 |
Cursor IME HUD: Show Diagnostics |
显示探测器、快照、生命周期和最近日志。 |
隐私与安全边界
Cursor IME HUD 只需要知道“当前输入法状态”，不需要知道“用户输入了什么”。
项目约束如下：
- 不读取编辑器文件内容。
- 不读取剪贴板。
- 不读取、记录或上传实际输入文本。
- 不自动切换输入法或键盘布局。
- helper 只读取当前平台公开输入源 / IME / layout 状态，并通过 stdio 返回结构化状态。
- 扩展会校验 helper 的
.sha256 sidecar；不匹配时禁用 native helper。
协议说明见 docs/helper-protocol.md。安全问题请参考 SECURITY.md。
源码结构
cursor-ime-hud/
src/ # VS Code / Cursor 扩展源码
native/ # Rust 跨平台 IME helper 源码
resources/ # 图标、截图与 helper 打包资源
jetbrains/ # JetBrains IDE 插件源码（Kotlin + Gradle）
docs/ # helper 协议等共享文档
scripts/ # 构建、校验、打包脚本
.github/workflows/ # CI、VSIX release、JetBrains package workflow
本地开发
环境要求
- Node.js 24+
- npm 11+
- VS Code
^1.107.0
- Rust stable toolchain
- Windows MSVC Build Tools / Visual Studio C++ 工具链（构建 Windows helper）
- Xcode Command Line Tools（构建 macOS helper）
- Linux 构建工具链与 Rust target（构建 Linux helper）
- JetBrains 插件开发需 JDK 21 与 Gradle wrapper
npm run build:helper 只构建当前主机对应的 helper；正式发布 workflow 会在 Windows、macOS 与 Linux runner 上分别构建并汇总所有 helper。
常用命令
npm install
npm run compile
npm run lint
npm run format:check
VS Code Extension Host 测试在 Linux CI / headless 环境下需要 Xvfb：
xvfb-run -a npm test
JetBrains 插件测试：
./jetbrains/gradlew -p jetbrains test
验证与打包
VS Code / Cursor
npm run lint
npm run format:check
npm run compile
npm test
npm run package:vsix
npm run package:vsix 会执行 vscode:prepublish，其中包含 publisher 校验、TypeScript 编译和当前主机 helper 构建。正式 release 会先汇总所有平台 helper，再打包 VSIX。
JetBrains
./jetbrains/gradlew -p jetbrains test
./jetbrains/gradlew -p jetbrains buildPlugin
./jetbrains/gradlew -p jetbrains verifyPlugin
buildPlugin 会要求当前主机对应的 helper 资源存在，并在打包时包含所有已经构建好的 resources/bin/<platform> helper 与 .sha256。正式发布 workflow 会分别在 Windows、macOS 与 Linux runner 上构建 helper，再汇总进 VSIX 与 JetBrains ZIP。
GitHub Actions
仓库提供两个主要打包 workflow：
- Release：构建 VSIX，并在 tag release 时上传到 GitHub Release。
- JetBrains Plugin Package：构建 JetBrains 插件 ZIP，并上传 workflow artifact。
正式发布应以 tag 触发 workflow，并检查两个 workflow 均成功完成。
故障排查
HUD 不显示
- 确认当前系统是 Windows 10 / Windows 11。
- 确认 IDE 版本满足支持范围。
- 确认光标位于可编辑文本区域。
- 运行
Cursor IME HUD: Show Diagnostics。
- 查看 VS Code Output 面板中的 Cursor IME HUD 输出通道，或 JetBrains 诊断输出。
状态栏一直显示 ?
可能原因包括：
- 当前窗口不是可靠的 IME 上下文。
- 正在使用非中文 IME。
- helper 暂时无法读取前台窗口状态。
- helper 启动失败、退出或完整性校验失败。
可以先运行：
Cursor IME HUD: Refresh IME State
如果问题仍可稳定复现，请提交 issue，并附上 Diagnostics 输出、IDE 版本、系统版本和复现步骤。
贡献
欢迎提交 issue 和 pull request。为了便于维护，请尽量遵循以下约定：
- 涉及 VS Code / Cursor 的问题，请在标题或正文中注明
VS Code 或 Cursor。
- 涉及 JetBrains 插件的问题，请注明
JetBrains。
- 涉及 native helper 的问题，请注明 Windows 版本、输入法名称和是否可稳定复现。
- PR 应尽量包含相应测试或验证说明。
开发前建议阅读：
安全问题
请不要通过公开 issue 披露安全漏洞。请按照 SECURITY.md 中的方式报告安全问题。
许可证
本项目基于 MIT License 开源。
