docs: explain Windows cursor and IME trade-off

refs #1637

1 files changed, 13 insertions, 0 deletions

diff --git a/website/src/content/docs/zh-cn/troubleshooting.mdx b/website/src/content/docs/zh-cn/troubleshooting.mdx
index 39d23f75..60a41153 100644
--- a/website/src/content/docs/zh-cn/troubleshooting.mdx
+++ b/website/src/content/docs/zh-cn/troubleshooting.mdx
@@ -12,6 +12,19 @@ herdr status
 
 同时记录操作系统、外层终端名称和版本、会话是本地还是远程，以及是否使用了 tmux。
 
+## Windows 上的 CJK 输入法窗口位置错误或光标闪烁
+
+Herdr 在原生 Windows 和 WSL 上默认使用单元格绘制光标,因为 ConPTY 多路复用器重绘屏幕时,原生光标可能闪烁、跳动或显示旧位置。单元格绘制光标无法提供韩语、日语和中文输入法预编辑文本及候选窗口所需的原生光标定位。
+
+如果输入法预编辑文本或候选窗口出现在错误位置,请启用原生光标:
+
+```toml
+[ui]
+host_cursor = "native"
+```
+
+原生模式会恢复输入法定位,但在持续输出期间可能再次出现偶发的光标移动异常。要恢复视觉稳定的光标,请设置 `host_cursor = "drawn"`,或删除该设置以使用 Windows 默认值。当前限制详见 [Windows 测试版](/zh-cn/docs/windows-beta/)。
+
 ## Enter、Tab 或 Backspace 触发两次
 
 旧版终端在应用启用 Kitty 键盘事件报告后，可能把 Enter、Tab 和 Backspace 的释放事件发送为与按下事件相同的字节。终端发送后，Herdr 无法区分这些重复字节。