菜单
English
本页内容

终端兼容性检查清单

文档首页 · 故障排查 · English

终端、终端复用器、远程 Shell 和桌面设置都可能在 Sigil 进程之外拦截键位、鼠标、剪贴板序列、图片或通知。请先运行 sigil doctor；需要保存本机检查报告时，可以使用 scripts/tui-mouse-smoke.sh。

基线

  1. 通过 Doctor 或配置指南找到当前用户 sigil.toml。
  2. 除非下面测试失败，否则保持 keyboard_enhancement = "auto"、mouse_capture = true、osc52_clipboard = true 和 scroll_sensitivity = 3；这些 [terminal] 字段需要在 TOML 中修改，然后重启 Sigil。
  3. 不需要失焦提示时，保持通知关闭；通知字段也可以在 /config → Terminal 中修改。
  4. 测试可选功能前，先确认普通文本输入、会话记录滚动、Esc 和 Ctrl-C 正常。

Windows 上分别运行无害的 Write-Output 'hello' 和 exit 7；活动卡片应该显示实际使用的 Shell、UTF-8 输出和退出码。本机命令执行不等于操作系统沙箱。

Sigil 会在异步终端输入读取器启动前只查询一次真实 cursor；后续 inline viewport resize 读取 backend 内的 cursor cache，恢复的记录或刚完成的消息则通过 scrolling region 进入终端原生 scrollback，不再让同步 cursor-position 查询与异步输入读取器竞争。长任务期间即使 TUI 保持静置，也不应再因 The cursor position could not be read within a normal duration 直接退出。

失焦通知检查

临时开启通知，并把长任务阈值设为 1000 ms。启动一个超过一秒的任务后移出焦点，预期只收到一次固定的完成提示。等待审批或 MCP 输入时，可以不受长任务阈值限制。如果 tmux 或 screen 显示控制文本或忽略提示，请尝试 bell，或者关闭通知。

真实可执行文件的默认关闭状态与 BEL 检查使用 scripts/tui-attention-signals-pty-acceptance.py。

鼠标检查

修改 mouse_capture 后重启，再检查：

  1. 点击输入框并输入；
  2. 打开 / 并点击候选命令；
  3. 滚动会话记录；
  4. 修改一个 /config 字段；
  5. 打开 /resume、选择一行，并分别用右键和 Ctrl-O 打开会话操作；
  6. 使用审批中的文件、差异、允许和拒绝控件。

点击与滚轮应只影响聚焦界面；键盘操作始终可用。

文本选择与复制

在会话记录中分别拖选单行、多行和宽字符文本，松开鼠标后直接粘贴到其他位置；不应再需要额外按键。若 Sigil 报告复制失败，确认选区仍保持高亮，并可按 Ctrl-C 重试。没有选区时按 Ctrl-L，应复制最新助手回复。所有复制内容都不应包含右侧信息栏。Sigil 会尝试本机系统剪贴板，并在启用时同时尝试带 tmux/screen passthrough 的 OSC52；只有两个适配器都无法写入时才报告剪贴板不可用。

图片粘贴检查

选择明确支持图片的 OpenAI Responses、Anthropic 或 Gemini 模型后：

  1. 复制 PNG，在空闲输入框按 Ctrl-V；
  2. 确认图片信息标签出现，而且不显示本机路径；
  3. 选中并删除该标签；
  4. 粘贴本机 PNG、JPEG 或 WebP 路径；
  5. 提交纯图片消息或图文消息。

不支持图片的模型必须保留输入草稿，并在发送前拒绝图片。远程环境可能无法访问宿主机的图片剪贴板；此时请粘贴本机图片路径。

tmux、screen、SSH 与 WSL

在每层中重复 /doctor、鼠标和复制检查。键位异常时设置 keyboard_enhancement = "off" 并重启；鼠标异常时设置 mouse_capture = false 并重启；OSC52 出现可见控制文本时设置 osc52_clipboard = false。Sigil 仍会尝试系统剪贴板，但通过 SSH 或容器时，它未必能写到宿主机剪贴板。

结果模板

Terminal / TERM:
Layers: none / tmux / screen / SSH / WSL
keyboard_enhancement / mouse_capture / osc52_clipboard:
notifications method / threshold:
Mouse smoke:
Selection copy / latest-response copy:
Image paste:
Notes:

下一步：继续排障。