必须 await vscode.env.clipboard.readText() 和 writeText()，否则 Promise 悬空导致读空或写丢；远程环境默认不可用，需终端集成或命令桥接；禁用轮询监听；writeText 仅支持字符串，需预处理富文本、控制字符及代理对。
VSCode插件中调用vscode.env.clipboard必须 await
不 await vscode.env.clipboard.readText() 或 vscode.env.clipboard.writeText() 会导致 Promise 悬空，后续逻辑可能读到空字符串或旧值。Electron 渲染进程的剪贴板 API 是异步的，且在远程开发（SSH/WSL）场景下还涉及跨进程 IPC，未等待就继续执行极易引发竞态。
常见错误写法：vscode.env.clipboard.writeText('hello'); —— 这行代码立即返回 Promise，但没处理完成状态，用户可能在写入中途切换终端，导致内容丢失。
- 正确做法始终是
await vscode.env.clipboard.writeText(text)，并在 try/catch 中包裹 - 写入前建议先
await vscode.env.clipboard.readText()做内容比对，避免无意义重复写入（尤其大文本） - 读取后若需清理换行或控制字符，用
text.replace(/\r\n|\r|\n/g, ' ')而非.trim()，后者不处理中间换行
vscode.env.clipboard 在 Remote-SSH/WSL 下默认不可用
远程会话中 vscode.env.clipboard 默认返回空字符串或抛出“not available”错误，不是插件写错了，而是 VSCode 安全策略限制：远程扩展进程无权直接访问本地剪贴板。
绕过方式只有两种：
- 启用终端剪贴板集成：在远程环境的
settings.json中设"terminal.integrated.clipboardIntegration.enabled": true，此时仅终端内粘贴有效，插件仍不能调用vscode.env.clipboard - 改用终端命令桥接：例如 WSL 中执行
/mnt/c/Windows/System32/clip.exe，Linux 用xclip -sel c，macOS 用pbcopy，通过vscode.terminal.executeInTerminal()触发并捕获输出
注意：clip.exe 在 WSL2 中常因权限被杀软拦截，测试时可用 echo test | /mnt/c/Windows/System32/clip.exe 验证通路。
监听剪贴板变化不能用 setInterval 轮询
VSCode 没有提供 onDidChangeClipboard 这类原生事件，但轮询 readText() 会快速耗尽资源：每 100ms 读一次，5 分钟就是 3000 次 IPC 调用，渲染进程 CPU 占用飙升，且在远程环境下延迟更不可控。
可行替代方案：
- 绑定用户显式动作：比如在命令面板注册
myExtension.pasteFromClipboard，让用户按 Ctrl+Shift+P 触发，而非后台自动响应 - 结合编辑器选中状态：用
vscode.window.onDidChangeTextEditorSelection+ 手动检查是否刚执行过 Ctrl+V（需配合 keyDown 监听，但注意 macOS/Linux 的 Meta 键差异） - 放弃实时监听，改为“粘贴后修正”：在用户执行
editor.insertSnippet()时，把${CLIPBOARD}作为占位符动态注入，利用 VSCode 片段引擎做兜底和转换
写入富文本或二进制内容会静默失败
vscode.env.clipboard.writeText() 只接受字符串，传入 Uint8Array、Blob 或含 null 字节的 Buffer 会直接忽略，不报错也不写入——这是 Electron 剪贴板模块的硬性限制，不是 VSCode 层面能绕过的。
若插件需要处理图片路径、base64 编码或 ANSI 日志，必须提前转换：
- 图片路径 → 提取文件名或 URL 后缀，写纯文本描述，如
"screenshot-20260818.png" - ANSI 日志 → 用
ansi-to-html库转义或直接删掉\x1b[...m序列，保留可读文本 - base64 内容 → 截断前 100 字符 +
... (base64, ${len}B)，避免写入数 MB 数据卡死主线程
真正容易被忽略的是：即使你只写纯文本，若内容含代理对（surrogate pairs）或零宽空格（\u200b），某些旧版 Electron 仍会截断。稳妥做法是写入前过一遍 text.normalize('NFC') 并过滤控制字符：text.replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u200B-\u200F\u202A-\u202E]/g, '')。
