现象

在 Neovim 中打开 :terminal，启动 Claude Code，粘贴一段多行文本。期望看到完整内容，实际却出现：

Et -g default-terminal      # 首字符 's' 丢失且多出 'E'
et -g def                   # 后半段被截断

不同尝试之间结果不一致（非确定性）。这个问题的特殊之处在于：

• 不经过 Neovim 直接粘贴到 Claude Code 正常
• Vim 的 :terminal 粘贴正常
• nvim --clean 也能复现（排除配置/插件）
• macOS 和 WSL2 均受影响

解决方案

Neovim ≥ 0.12.2

升级即可，社区已在 #39152 修复。

# 使用你喜欢的包管理器升级
brew upgrade neovim       # macOS
winget upgrade Neovim     # Windows

Neovim < 0.12.2

在不修改 Neovim 二进制的情况下，可以通过覆盖 vim.paste 来绕过有 bug 的 terminal_paste() 实现：

-- 放到 init.lua 中
if vim.fn.has("nvim-0.12.2") == 0 then
  local paste_streaming = false

  vim.paste = (function(overridden)
    return function(lines, phase)
      if vim.bo.buftype ~= "terminal" then
        return overridden(lines, phase)
      end
      local chan = vim.bo.channel
      if not chan or chan == 0 then
        return overridden(lines, phase)
      end

      local text = table.concat(lines, "\n")
      local is_first = (phase == 1 or phase == -1)
      local is_last = (phase == 3 or phase == -1)

      if is_first and not paste_streaming then
        paste_streaming = true
        vim.api.nvim_chan_send(chan, "\27[200~")
      end
      vim.api.nvim_chan_send(chan, text)
      if is_last then
        vim.api.nvim_chan_send(chan, "\27[201~")
        paste_streaming = false
      end

      return true
    end
  end)(vim.paste)
end

这个 workaround 只在 terminal buffer 中接管 paste 处理：直接用 nvim_chan_send 把文本发送到终端 job，并为整个 paste stream 只生成一对 bracketed paste 标记，而不是每 chunk 一对。

升级到 0.12.2 后，vim.fn.has("nvim-0.12.2") 检查自动跳过覆盖代码，不会干扰已修复的行为。

Workaround 的风险

这个 workaround 在大多数场景下工作正常，但有几个值得注意的局限：

1. dot-repeat 不工作：覆盖函数直接 return true，没有像原生 vim.paste() 那样调用 paste_store() 记录 paste 历史。在 terminal 中粘贴无法通过 . 重复。这是有意为之——terminal buffer 中的 dot-repeat 应该由终端 job 自己处理，Neovim 的粘贴重放本来就不适合 terminal mode。

2. 绕过 tpf_flags 过滤：原生的 terminal_paste() 会根据 tpf_flags（'paste' 选项）过滤控制字符（如 ESC、退格等）。nvim_chan_send 不会做这个过滤。但现代终端程序（bash ≥ 4.4、Claude Code、vim 等）都已启用 bracketed paste，通过 \e[200~ / \e[201~ 标记来识别粘贴内容，对控制字符的处理更安全，因此这在实际使用中很少造成问题。

3. 仅在 buftype=terminal 生效：覆盖函数在非 terminal buffer 中直接调用原生的 overridden(lines, phase)，不影响普通 buffer 的粘贴行为。

4. 跨 chunk 状态用闭包变量管理：paste_streaming 是一个模块级闭包变量。如果两个 terminal 同时收到 streamed paste（极端边缘场景，同一个 Neovim 实例中不同 terminal 同时被粘贴），状态会冲突。实际使用中几乎不会遇到，但理论上存在。

原因

Neovim TUI 层在处理外部 paste 时，通过 bracketed paste 判断 paste 的起止位置。Paste 内容被缓冲在 4096 字节（KEY_BUFFER_SIZE = 0x1000）的内置 buffer 中。当内容超过这个值时，会被分割成多个 chunk 发送：

Chunk 1 (phase=1): \e[200~ + 前4096字节 + \e[201~
Chunk 2 (phase=2): \e[200~ + 中间4096字节 + \e[201~   ← 不应出现
Chunk 3 (phase=3): \e[200~ + 剩余部分 + \e[201~       ← 不应出现

核心问题在于 src/nvim/terminal.c 中的 terminal_paste() 函数——每次调用都无条件添加一对 vterm_keyboard_start_paste() / vterm_keyboard_end_paste()。当 chunk 机制多次调用 terminal_paste() 时，每个 chunk 都被包装成了独立的 bracketed paste。子进程（Claude Code、vim 等）收到了多个被错误分割的 paste 事件。

对于 Claude Code 这类交互式 TUI 程序，每次收到”独立 paste”后都会立即处理并重新渲染界面。多个独立 paste 之间的 UI redraw 互相覆盖，最终只有部分内容被保留。

即使内容短于 4096 字节（单 chunk），terminal_paste() 内部的 uv_write() 异步写和 vterm 输出回调之间的时序也在特定系统上引入了竞态。这也解释了为什么 Vim 的 :terminal 没有此问题——Vim 使用同步 write() 而非 libuv 的异步 uv_write()。

修复的具体策略是将 bracketed paste 标记的生成从 terminal_paste() 提升到 nvim_paste() 层级，引入 streamed_paste 标记确保整个 paste stream 只有一对 \e[200~ / \e[201~：

// nvim_paste() — 修复后
if (phase == 1 || phase == -1)
    terminal_set_streamed_paste(term, true);   // 只在开始时输出 \e[200~
// … vim.paste() → do_put() → terminal_paste() — 内部不再加标记 …
if (phase == 3 || phase == -1)
    terminal_set_streamed_paste(term, false);  // 只在结束时输出 \e[201~

相关资料

• neovim/neovim#39152 — 修复 PR：forward streamed bracketed paste properly
• folke/sidekick.nvim#207 — sidekick 用户报告的同一问题（已自动关闭）
• coder/claudecode.nvim#161 — claudecode.nvim 的同类问题报告
• Neovim :terminal paste 早期讨论 — bracketed paste 在 :terminal 中的历史演进

检查问题

先在 tmux 内运行下面这条命令，确认你是否有这个问题：

echo -e "\e[3mitalic\e[23m"

如果看到的是反色高亮而不是斜体，说明中招了。

修复步骤

一、安装修正后的 terminfo

通过 heredoc 直接传给 tic 编译安装，无需创建临时文件：

cat <<'EOF' | tic -x -
tmux-256color|tmux with 256 colors,
  ritm=\E[23m, rmso=\E[27m, sitm=\E[3m, smso=\E[7m, Ms@,
  khome=\E[1~, kend=\E[4~,
  use=xterm-256color, use=screen-256color,
EOF

tic -x - 中的 - 表示从 stdin 读取，'EOF' 加引号防止 shell 对 \E 做转义插值。

tic -x 会将编译后的 terminfo 写入 ~/.terminfo/，不需要 sudo。

二、修改 tmux 配置

在 ~/.tmux.conf 中添加：

set -g default-terminal 'tmux-256color'
set -as terminal-overrides ',xterm*:Tc:sitm=\E[3m'

第一条把 tmux 的默认终端类型切换为刚安装的 tmux-256color。第二条为 xterm 类终端显式指定斜体序列，Tc 表示支持 true color。

三、重启 tmux

tmux kill-server && tmux

再次运行验证命令：

echo -e "\e[3mitalic\e[23m"

现在应该能看到正常的斜体文字了。

原理

终端的文本属性（粗体、斜体、下划线、反色等）通过 ANSI 转义序列控制。terminfo 数据库为每种终端类型定义了这些序列的映射关系：

tmux 的默认 $TERM 是 screen 或 screen-256color。screen 终端本身不支持斜体，所以历史上它把 standout（smso）的序列映射到了 \E[3m（斜体），把斜体占为己有。tmux 继承了这个定义。

结果就是：在 tmux 内部，程序查 terminfo 得知要显示反色就发 \E[3m，但现代终端把 \E[3m 正确理解为斜体——于是反色高亮就变成了斜体。反过来，真正想显示斜体的程序发出来的序列又会被当成反色。

上面创建的 terminfo 文件关键就在于这两行：

use=xterm-256color, use=screen-256color,

它以 screen-256color 为基础，再用 xterm-256color 覆盖（后者正确定义了斜体和反色），最后显式指定 sitm=\E[3m / smso=\E[7m 确保万无一失。Ms@ 则禁用了 screen 对颜色切换的干扰行为。

哪些系统会受影响

这个问题本质上是历史遗留，主要出现在 2017 年之前的系统上。ncurses 在 2017 年才引入独立的 tmux-256color terminfo 条目，正确分离了斜体和反色。

以下场景仍可能遇到：

• 老系统：CentOS 7、旧版 macOS 等自带的 ncurses 版本过老，没有 tmux-256color
• SSH 到旧服务器：本地 $TERM 可能被 propagate 为 screen-256color（尤其当跳板机或远端 tmux 配置陈旧时）
• tmux 配置显式设了旧 TERM：如果 ~/.tmux.conf 里有 set -g default-terminal "screen-256color"，问题会被重新引入

现代发行版（Ubuntu 18.04+、Debian 10+、macOS 10.14+）的 ncurses 已自带 tmux-256color，一般不会有这个问题。

参考：tmux/tmux#1202，ncurses-bug 邮件列表