docs: Shift+Enter 换行不支持的原因分析

[hqwlkj]

Shift+Enter 换行不支持的原因分析

概述

该 CLI 项目中 Shift+Enter 的换行功能不生效，但应用层代码逻辑本身已完整实现。问题根源不在代码，而在于终端模拟器层面：绝大多数终端模拟器不会将 Shift 修饰符编码到底层字节流中传递给应用程序。

---

1. 应用层代码链路（逻辑完全正确）

应用的 Shift+Enter 处理链路分为三层，每一层都已正确实现：

1.1 输入端：useTerminalInput.ts 解析终端输入

// 第 29 行 — 定义 Shift+Enter 的四种可能终端编码
const SHIFT_RETURN_SEQUENCES = new Set([
 "\u001B\r", // ESC + CR（部分终端）
 "\u001B[13;2u", // modifyOtherKeys 标准格式（XTerm 扩展）
 "\u001B[13;2~", // 旧式编码
 "\u001B[27;2;13~" // 扩展格式
]);

// 第 116 行 — return 键置 true
return: raw === "\r" || SHIFT_RETURN_SEQUENCES.has(raw) || META_RETURN_SEQUENCES.has(raw),

// 第 119 行 — Shift 修饰符置 true
shift: SHIFT_RETURN_SEQUENCES.has(raw),

当终端发送上述任一序列时，key.return = true 且 key.shift = true。

1.2 分发层：PromptInput.tsx 按键分发

// 第 355-356 行：根据修饰符决定动作
const returnAction = getPromptReturnKeyAction(key); // shift=true → "newline"
const isPlainReturn = returnAction === "submit";

// 第 387-390 行：newline 动作 → 插入 \n
if (returnAction === "newline") {
 updateBuffer((s) => insertText(s, "\n"));
 return;
}

// 第 392-394 行：submit 动作 → 提交缓冲区
if (returnAction === "submit") {
 submitCurrentBuffer();
 return;
}

getPromptReturnKeyAction 实现（第 857-865 行）：

export function getPromptReturnKeyAction(
 key: Pick<InputKey, "return" | "shift" | "meta">
): PromptReturnKeyAction {
 if (!key.return) return null;
 if (key.shift || key.meta) return "newline"; // ← Shift → 换行
 return "submit"; // ← 无修饰符 → 提交
}

1.3 缓冲区与渲染层

• promptBuffer.ts → insertText：正确支持在缓冲区任意位置插入 \n
• promptBuffer.ts → moveUp / moveDown：支持多行文本中上下移动光标
• renderBufferWithCursor（第 888-889 行）：正确渲染换行符处的光标

if (at === "\n") {
 return before + renderCursorCell(" ") + "\n" + after;
}

结论：从输入解析 → 按键分发 → 缓冲区操作 → 终端渲染，全链路代码逻辑闭环。当 key.shift === true 时必然换行，逻辑无缺陷。

---

2. modifyOtherKeys 模式的尝试（作用有限）

cursor.ts 第 44-48 行启用了 modifyOtherKeys 模式：

export function enableTerminalExtendedKeys(): string {
 return "\u001B[>4;1m"; // 启用 modifyOtherKeys（XTerm 扩展）
}

开启后，支持该模式的终端会将 Shift+Enter 编码为 \u001B[13;2u（而非裸 \r）。

限制：这是一个 XTerm 专有扩展，绝大多数终端不支持或不完整支持：

终端	支持 modifyOtherKeys？
XTerm	✅ 完整支持
iTerm2（需配置）	⚠️ 部分支持
macOS Terminal.app	❌ 不支持
Windows Terminal / ConPTY	❌ 不支持
VS Code 集成终端（xterm.js）	⚠️ 部分支持
GNOME Terminal	❌ 不支持

---

3. 根本原因：终端模拟器不传递 Shift 修饰符

3.1 TTY 驱动的设计限制

终端与应用程序通过 字节流 通信。按下组合键时，终端将其编码为一个或多个字节发送给应用：

组合键	发送字节	为何能被区分
Ctrl+C	\x03（ASCII ETX）	TTY 驱动原生支持 Control 字符编码（Ctrl 将字符码值与 0x1F 做位与）
Alt+X	\u001Bx（ESC + 字符）	Meta 前缀是终端标准，几乎所有终端都发送 leading ESC
Shift+A	A（大写字母本身就是不同的码点）	ASCII 设计使 Shift+字母产生不同字节
Shift+Enter	\r（与普通 Enter 完全相同）	❌ Enter 键没有"大写形式"，Shift 无法体现在字节层面

3.2 各主流终端实测

终端	Shift+Enter 发送的字节	应用层能区分吗？
macOS Terminal.app	\r（0x0D）	❌
iTerm2（macOS，默认配置）	\r（0x0D）	❌
VS Code 集成终端	\r（0x0D）	❌
Windows Terminal / ConPTY	\r（0x0D）	❌
GNOME Terminal（Linux）	\r（0x0D）	❌
XTerm + modifyOtherKeys	\u001B[13;2u	✅

项目记忆中也确认：Windows ConPTY 终端在默认模式下，Shift+Enter 与普通 Enter 均发送字节 \r（0x0D），不携带 Shift 修饰符信息。

3.3 为什么 footer 提示"shift+enter newline"但不生效

PromptInput.tsx 第 180 行的 footer 文本：

enter send · shift+enter newline · @ files · ctrl+v image · / commands · ctrl+d exit

这个提示信息本身就是正确的功能设计意图。代码逻辑也已经为 支持 modifyOtherKeys 的终端（如正确配置的 iTerm2 或 XTerm）做了完整实现。不生效的原因是当前使用的终端没有把 Shift 信息传递给应用。

---

4. 总结

┌─────────────────────────────────────────────────────────┐
│ 用户按下 Shift+Enter │
│ │ │
│ ▼ │
│ 终端模拟器 │
│ ┌──────────────────────────────────────────────┐ │
│ │ macOS Terminal.app / iTerm2 / Windows Terminal │ │
│ │ → 发送 0x0D (\r) │ │
│ │ → Shift 修饰符丢失 ❌ │ │
│ └──────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ parseTerminalInput() │
│ → 收到 \r → key.shift = false │
│ │ │
│ ▼ │
│ getPromptReturnKeyAction(key) │
│ → key.shift === false → return "submit" │
│ │ │
│ ▼ │
│ submitCurrentBuffer() ← 用户本想换行，却被提交了 │
└─────────────────────────────────────────────────────────┘

核心矛盾：终端模拟器在物理层把 Shift+Enter 和普通 Enter 编码成完全相同的字节序列（\r），应用层无法区分，代码逻辑无 bug。

可行的解决方向（供参考）

方案	原理	可行性
配置 iTerm2 发送转义序列	iTerm2 → Preferences → Keys → Key Mappings → 将 Shift+Enter 映射为 Send Escape Sequence: [13;2u	⚠️ 仅 iTerm2
应用层添加 Alt+Enter 作为替代快捷键	getPromptReturnKeyAction 中 key.meta 已返回 "newline"，Alt+Enter 在大多数终端天然发送 \u001B\r	✅ 通用
提供显式换行命令（如 \ + Enter）	在应用层约定一个转义前缀表示换行	⚠️ 学习成本
依赖 modifyOtherKeys 自动检测	当前已实现，仅对 XTerm 等支持终端生效	⚠️ 覆盖有限

个人推荐方案：使用 Alt+Enter（Control+j）作为跨平台换行快捷键，因为大多数终端天然对 Meta 前缀有标准编码（\u001B\r），且应用层已支持（getPromptReturnKeyAction 中 key.meta 同样返回 "newline"）。

[hqwlkj]

Mac 用户可以将终端设置中的 “将Option键用作Meta键” 勾选上，使用 Option 键作为 Meta键

Windows：用户可以使用 Ctrl + j 或者 Ctrl + Enter