平台支持

Chord 主要在 macOS 上开发和测试。其他平台不同程度可用：大部分功能与平台无关，少数依赖 OS 特定能力，在其他平台会降级或 no-op。本页给出每个功能的真实支持情况、降级行为及各平台的额外安装要求。

速览矩阵

功能	macOS	Linux	Windows	WSL
核心 TUI（模式切换、消息、会话）	✅	✅	⚠️（尽力而为）	✅
`chord headless` JSON 控制面	✅	✅	✅	✅
Worktree（`chord --worktree`、`chord worktree …`）	✅	✅	✅	✅
`prevent_sleep`（阻止系统休眠）	✅	❌（no-op）	❌（no-op）	❌（no-op）
`ime_switch_target`（模式切换时自动切输入法）	✅¹	⚠️²	✅³	⚠️⁴
`desktop_notification`（终端通知）	⚠️⁵	⚠️⁵	⚠️⁵	⚠️⁵
剪贴板图片/PDF附件（`Ctrl+V` / `Alt+V`）	✅	⚠️⁶	⚠️⁶	⚠️⁶
终端图片渲染（Kitty / iTerm2）	⚠️⁷	⚠️⁷	⚠️⁷	⚠️⁷
LSP — gopls / typescript / rust-analyzer	✅⁸	✅⁸	✅⁸	✅⁸
LSP — Pyright + 项目 venv 自动探测	✅⁹	✅⁹	✅¹⁰	✅⁹（仅 WSL Linux venv，详见下文）
MCP servers（stdio / HTTP）	✅	✅	✅	✅
电源感知 idle 处理	✅	❌（no-op）	❌（no-op）	❌（no-op）

图例：✅ 支持 · ⚠️ 有注意事项 · ❌ 不支持 / no-op。

各功能详情

`prevent_sleep`

macOS 下用 caffeinate(1) 实现。Linux / Windows / WSL 上是 no-op。其他平台需常驻不休眠的话，直接用 OS 自带的电源设置。

首次运行向导只会在 macOS 上询问 prevent_sleep，并且必须由用户显式确认开启。它主要适用于长时间运行 agent、又不希望系统因空闲进入睡眠的场景。

`ime_switch_target`

从 Insert 切到 Normal 时，Chord 可调用 im-select（或 im-select.exe）切到指定 IM（通常是英文键盘布局），切回 Insert 时恢复原来的 IM。

在支持的平台上，首次运行向导也可能询问这个值。只有当你平时确实使用中文 / 日文 / 韩文等输入法，并希望 Normal 模式快捷键更稳定时，才建议配置。

ime_switch_target: com.apple.keylayout.ABC          # macOS 示例
# ime_switch_target: 1033                           # Windows 示例（locale id）

im-select 需单独安装。变量值就是字符串，Chord 原样传给 im-select，具体格式由该平台工具决定。

`desktop_notification`（终端通知）

启用后，Chord 会在权限确认、问题待回答、agent 回到 idle 等事件时发出终端通知转义序列。Chord 不负责通知守护进程；具体显示依赖终端。

当前实现会按终端自动选择协议；不支持的终端通常会忽略该序列。

实践中：

Ghostty / WezTerm / Windows Terminal：Chord 会尝试使用 OSC 777
iTerm2：Chord 使用 OSC 9
其他终端：Chord 保守回退到 OSC 9

tmux 中可能需要 set -g allow-passthrough on，通知序列才可能透传到宿主终端。

剪贴板图片/PDF附件

Ctrl+V 或 Alt+V 会从系统剪贴板读取图片或 PDF 并作为附件添加。读取及图片转换都在后台异步执行，因此 TUI 不会被阻塞；读取完成前会暂时阻止发送。普通终端 paste 事件（包括 macOS 常见的 Cmd+V）只粘贴文本，绝不会探测剪贴板附件。

Chord 使用原生剪贴板后端，不再依赖 osascript、xclip 或 wl-paste。剪贴板图片按 PNG、JPEG、WebP、BMP 的顺序读取；BMP/WebP 会先安全归一化为 PNG/JPEG。若同时提供 PDF 和图片表示，优先附加 PDF；如果没有支持的附件，会显示提示且不会回退为文本。

每条输入框消息最多支持 5 张 inline 图片附件。手动输入 [image1] 这类占位符文本本身不会附加图片；只有 Chord 内部插入的 inline 占位符才会绑定真实附件。

常见情况：

macOS + iTerm2 / WezTerm / Ghostty：Ctrl+V 附加剪贴板附件，Cmd+V 粘贴文本。
macOS + cmux：剪贴板附件请使用 Ctrl+V。Cmd+V 可能被 cmux 截获并转换成临时文件路径文本。
Linux Wayland / X11：compositor 提供 data-control，或 X11/XWayland display 可用时，Ctrl+V 读取本机剪贴板。
Windows Terminal / 由其承载的 WSL：请使用 Alt+V；Windows Terminal 默认把 Ctrl+V 用于普通文本粘贴。WSLg 提供的 BMP 剪贴板图片会在附加前归一化。
tmux / SSH 内部：Chord 读取运行所在机器的剪贴板，不会自动读取终端客户端剪贴板。

剪贴板附件不可用时，你仍可给 insert_attach_file 绑定快捷键，再通过输入框里的路径附加图片/PDF。

终端图片渲染

Chord 当前自动检测并启用：

Kitty graphics（kitty、Ghostty）
iTerm2 inline images（iTerm2、WezTerm）

如果终端不支持这些协议，图片附件仍会发给模型，只是 TUI 内不预览。

说明：

Sixel 目前未实现为 Chord 后端
tmux / zellij 内默认保守禁用图片预览，避免常见 passthrough / 占位符兼容问题
高级用户可用环境变量覆盖自动检测：CHORD_IMAGE_BACKEND=kitty|iterm2|none，以及 CHORD_IMAGE_INLINE=0|1、CHORD_IMAGE_FULLSCREEN=0|1

Pyright venv 自动探测

未在配置中手动指定 Python 解释器时，Chord 在 LSP root 下按以下顺序找项目 venv：

类 Unix（macOS、Linux、WSL）：.venv/bin/python → venv/bin/python → env/bin/python
Windows：.venv\Scripts\python.exe → venv\Scripts\python.exe → env\Scripts\python.exe

WSL 自动探测不会选 Scripts\python.exe 里的 Windows venv。WSL 内开发请在 WSL 里建 Linux venv，或在 lsp.pyright.options 中显式设置 python.pythonPath。

详见扩展与定制 — LSP。

终端兼容

很多「macOS 上能用、Linux 不行」的反馈实际是终端模拟器差异，而非 OS 差异。推荐以下终端以获得最佳体验：

iTerm2（macOS）：图片预览、终端通知、剪贴板图片粘贴
Ghostty（跨平台）：图片预览、终端通知（会尝试 OSC 777）
WezTerm（跨平台）：图片预览、终端通知（会尝试 OSC 777）、剪贴板图片粘贴
kitty（Linux/macOS）：图片预览、终端通知
Windows Terminal：作为通用 TUI 没问题；图片协议和通知依赖版本/宿主链路
macOS 自带终端（Terminal.app）：基础 TUI 使用没问题，但它 不一定能可靠区分修饰后的 Enter（例如 Shift+Enter）。在输入框里需要换行时请用 Ctrl+J，或改用 iTerm2 / Ghostty / WezTerm 获得完整按键行为。

按键区分提示：在 tmux / zellij 这类终端复用器里，Shift+Enter 这类“带修饰键的 Enter”可能会丢失或被改写（取决于外层终端与复用器的 extended keys 配置）。不确定时请直接用 Ctrl+J 换行（所有终端都可用）。

tmux、screen 在 Chord 与终端之间又多一层；部分功能（终端通知、某些图片流程）需要显式配置 pass-through，而且 Chord 当前默认会在 tmux / zellij 内禁用图片预览。

Windows 用户须知

Chord 能在 Windows 上跑，但 Windows 不是主要平台。具体：

TUI 在现代终端（Windows Terminal、WezTerm）下工作正常。
prevent_sleep 是 no-op——请用 Windows 电源设置。
ime_switch_target 需要 im-select.exe。
工具调用中的文件路径走 Windows 风格，反斜杠原样保留。
shell 和 spawn 在 Windows 上也仍是非交互的，但超时 / 取消清理依赖直接终止进程，而不是 Unix 风格的 session / 进程组控制；因此对后代进程的清理可能不如 Unix 完整。
遇到 Windows 特有 bug 的话，更可能是「还没人踩到」而非「故意不支持」。请用 Ctrl+G 导出诊断包再上报。

WSL 用户须知

WSL 大致表现得像 Linux：

Chord 作为 Linux 二进制在 WSL 内运行；sessions、配置用 Linux 路径（~/.config/chord/ 等）。
prevent_sleep 是 no-op；请用宿主 Windows 的电源设置。
ime_switch_target 通常通过 Windows interop 调 im-select.exe。
Pyright venv 自动探测在 WSL 内使用 Linux venv（.venv/bin/python 等）；Windows 风格 Scripts\python.exe venv 不会被选。
终端能力取决于宿主 Windows 上跑的终端（Windows Terminal、WezTerm、Ghostty 等）。

报告平台相关问题

报 bug 怀疑与平台相关时请附上：

OS 与版本
终端模拟器与版本
是否在 tmux / screen / WSL 内
一份诊断包（Ctrl+G）

日志位置和包结构见常见问题排查 — 何时检查日志。