156 lines
8.6 KiB
Markdown
156 lines
8.6 KiB
Markdown
# 问题闭环记录（Question Solved）
|
||
|
||
本文档记录已确认问题的现象、根因、修复与回归要点，目标是避免重复踩坑。
|
||
|
||
## 目录
|
||
|
||
1. [2026-03-02：第三方输入法导致输入重复](#ime-dup)
|
||
2. [2026-03-02：点击粘贴触发 BAD_REQUEST / invalid_union](#paste-invalid-union)
|
||
3. [2026-03-02：多行粘贴被当作回车执行](#multiline-paste-enter)
|
||
4. [2026-03-03：回车后首字母重复显示（`aasdf`）](#enter-leading-dup)
|
||
5. [通用回归清单](#regression-checklist)
|
||
|
||
<a id="ime-dup"></a>
|
||
## 2026-03-02：第三方输入法导致输入重复（`jk -> jkjk`，`测试 -> 测试测试`）
|
||
|
||
### 现象
|
||
- 第三方输入法下输入 `jk` 显示 `jkjk`，输入 `测试` 显示 `测试测试`。
|
||
- 原生输入法或英文输入模式正常。
|
||
|
||
### 根因
|
||
- 同一文本同时走了 `keydown` 和 `input` 两条发送路径，导致双发。
|
||
- 第三方输入法会在 `keydown` 阶段给出整段文本（`key="测试"` / `key="jk"`），旧逻辑误判后直接发送。
|
||
|
||
### 修复
|
||
- 文件：`apps/web/src/terminal/components/TerminalInputBar.vue`
|
||
- 策略：
|
||
1. `keydown` 只处理控制键/功能键。
|
||
2. 文本输入统一走 `input` 通道，保证单通道发送。
|
||
3. `KEYDOWN_DIRECT_KEYS` 作为白名单，非白名单文本直接跳过。
|
||
|
||
### 验证
|
||
- `ls`、`jk`、`测试` 均不重复。
|
||
- `Enter`、`Ctrl+C` 等控制键行为保持正常。
|
||
|
||
### 自动化测试
|
||
- 文件：`apps/web/src/terminal/input/inputPolicy.test.ts`
|
||
- 覆盖文本键、功能键、组合键判定。
|
||
|
||
---
|
||
|
||
<a id="paste-invalid-union"></a>
|
||
## 2026-03-02：点击粘贴触发 BAD_REQUEST / invalid_union
|
||
|
||
### 现象
|
||
- 点击工具栏“粘贴”后出现 error，连接异常或重连。
|
||
- 日志出现 `ws:error_frame code=BAD_REQUEST`，消息含 `invalid_union`。
|
||
|
||
### 根因
|
||
- 网关 `stdin` 入参 schema 在现网存在差异；`paste` 携带 `meta` 会在部分环境触发 union 校验失败。
|
||
|
||
### 修复
|
||
- 文件：`apps/web/src/terminal/stores/useTerminalStore.ts`
|
||
- 策略：
|
||
1. `paste` 分片发送时不再携带 `meta`。
|
||
2. `keyboard/assist` 保持原有 `meta.source`。
|
||
3. 粘贴分片大小从 `512` 调整为 `256`，降低单帧风险。
|
||
|
||
### 验证
|
||
- 粘贴日志出现 `wireMetaSource: "none"`。
|
||
- 不再出现 `BAD_REQUEST invalid_union`。
|
||
|
||
---
|
||
|
||
<a id="multiline-paste-enter"></a>
|
||
## 2026-03-02：多行粘贴被当作回车执行
|
||
|
||
### 现象
|
||
- 复制多行文本后粘贴进 shell，会被当作多次回车，导致命令提前执行。
|
||
|
||
### 根因
|
||
- 旧粘贴逻辑将换行统一转为 `\r`（回车语义），不符合“多行粘贴应作为文本块输入”的预期。
|
||
|
||
### 修复
|
||
- 文件：
|
||
- `packages/terminal-core/src/input/inputBridge.ts`
|
||
- `apps/web/src/terminal/components/TerminalInputBar.vue`
|
||
- `apps/web/src/terminal/TerminalPage.vue`
|
||
- 策略：
|
||
1. `mapPaste` 将换行统一归一为 `\n`，不再转成 `\r`。
|
||
2. Web 两条粘贴链路（原生 `paste`、工具栏“粘贴”）统一走 `InputBridge.mapPaste()`。
|
||
3. 开启 bracketed paste（`\x1b[200~... \x1b[201~`），避免被解释为逐行回车执行。
|
||
|
||
### 验证
|
||
- 粘贴多行文本默认不自动逐行执行。
|
||
- 两条粘贴入口行为一致。
|
||
|
||
### 自动化测试
|
||
- 文件：`packages/terminal-core/src/input/inputBridge.test.ts`
|
||
- 覆盖：
|
||
1. `CRLF/CR/LF` 统一归一为 `LF`。
|
||
2. bracketed paste 包裹序列正确。
|
||
|
||
---
|
||
|
||
<a id="regression-checklist"></a>
|
||
## 2026-03-02：软键盘弹出后光标行定位不准与收回后页面跳动问题
|
||
|
||
### 现象
|
||
1. 终端在 iOS 移动设备上点击输入区弹出软键盘时，期望将光标（提示符行）定位到屏幕的距顶 1/4 处，但实际经常定位到键盘顶部或在屏幕中部乱跳。
|
||
2. 软键盘收回时，期望恢复到键盘弹出前的状态，但页面内容经常回跳或者复位到屏幕底部。
|
||
3. 终端输入文字（`autoFollow=true`）时，滚动条经常突然跳到屏幕中部，无法锁定在最底部。
|
||
|
||
### 根因
|
||
1. **行高计算不准确：** 在 `textareaRenderer` 的旧版计算方式中，利用 `scrollHeight / totalLines` 试图估算出单行的 `lineHeight`。但这在遇到换行文字（如超宽命令占据多行 HTML）或者终端末尾包含空白补齐的 Null Lines 时，按比例换算的 `offsetPx` 数值偏差严重。
|
||
2. **滚动到 scrollHeight 的陷阱：** `renderSnapshot` 及 `followBottom` 在自动跟随终端内容时，直接触发了 `this.outputEl.scrollTop = this.outputEl.scrollHeight`。但是 `xterm` 的 `snapshot.lines` 通常包含底部的很多未使用的纯空行（通常是为了填满预设高度而预留的。例如在你的日志中底部留有二十几行空行 Padding）。直接将 `scrollTop` 置为最大，会导致包含真实光标的行被视觉上挤到了屏幕上方，呈现出"跳到了屏幕中部"的怪异现象。
|
||
3. **iOS 异步布局时序缺陷：** `KeyboardAdjustController` 中，iOS 上软键盘收回（`visualViewport.height` 恢复）早于实际的 DOM `clientHeight` 恢复更新，用固定的时间延迟去读取和操作会导致布局错误。同时 iOS 原生的 `scroll` 行为是异步派发的，和程序的滚动重置产生了干扰覆盖（程序刚设回了 `snapshot` 高度，又被键盘底层收回的 `scroll` 冲成了底部）。
|
||
|
||
### 修复
|
||
- 文件：
|
||
- `apps/web/src/terminal/renderer/textareaRenderer.ts`
|
||
- `apps/web/src/terminal/input/keyboardAdjustController.ts`
|
||
- 策略：
|
||
1. **放弃比例估算，直接获取光标 DOM 节点：** 在 `textareaRenderer` 渲染的光标附带有专门的类名 `tc-cursor-cell`，此时我们设置外部包裹元素为 `position: relative`，并直接借助 `const cursorSpan = this.outputEl.querySelector('.tc-cursor-cell')` 拿到精确的 `offsetTop` 来计算光标此时刻在纵向的确切位置，确保毫无误差。
|
||
2. **将光标置于可视区底部，拒绝 scrollHeight：** 摒弃粗暴地拉向极限 `scrollHeight` 的做法，改为使用光标偏移量算出安全的底端视区：`let targetScrollTop = cursorBottom - clientH + 20` 并将其作为真实的自动跟随坐标，将跟随对象从"整个 Buffer 的底部"变更为"真正光标所处的区域"。
|
||
3. **Polling 等待基线恢复，长短结合阻塞 scroll 事件干扰：** 在 `keyboardAdjustController.ts` 中针对键盘关闭的 Layout 响应，引入 `requestAnimationFrame` 及定时检测（Polling），不断比对 `clientHeight` 是否已经长回键盘未弹出前的高度，只有确认恢复或者超市才恢复预存前的 `scrollTop` 快照，借此解决 iOS 下因为布局慢导致的跳闪。并通过定时锁去屏蔽由于视差调整造成的自动 `autofollow` 开关变动。
|
||
|
||
### 验证
|
||
- 点击 iOS 输入区弹出软键盘，终端精确将当前焦点处于 1/4 屏幕处。
|
||
- 收起键盘后，稳定跳掉之前的阅读点（快照复原准确）。
|
||
- 长按或者多次键盘输入不再跳动到屏幕中部。
|
||
|
||
---
|
||
|
||
<a id="enter-leading-dup"></a>
|
||
## 2026-03-03：回车后首字母重复显示（`aasdf`）
|
||
|
||
### 现象
|
||
- 输入英文命令（如 `asdf`）后回车，终端提示符行显示 `aasdf`，但服务端实际执行的是 `asdf`（例如返回 `zsh: command not found: asdf`）。
|
||
- 问题具备偶发性，通常出现在回显分片较细时。
|
||
|
||
### 根因
|
||
- 回显数据分帧到达，典型序列为：`"a"`、`"\b as"`、`"df..."`。
|
||
- 旧实现按帧即时渲染，第一帧字符已经落盘；第二帧开头的 `\b`（Backspace）无法回退上一帧已写入内容，导致视觉上保留多余首字母。
|
||
- 同时存在 `\r\r\n` 与 ANSI 控制序列交织，如果不按终端语义处理，也会放大错位和空行现象。
|
||
|
||
### 修复
|
||
- 文件：`demo/main.js`
|
||
- 策略：
|
||
1. 在 `renderAnsiToHtml` 中补齐控制字符语义：处理 `\x08`（退格）、`\r\n`（归一为换行）和裸 `\r`（回到当前行首覆盖）。
|
||
2. 增加短窗口流式合帧（`STREAM_BATCH_MS`）：将连续 `stdout/stderr` 分片合并后再渲染，确保跨帧 `\b/\r` 能作用于同一文本缓冲。
|
||
3. 保留原有“本地回显清理”策略（`clearLast()`），避免与远端回显叠加。
|
||
|
||
### 验证
|
||
- 复现输入 `asdf` 回车，不再出现 `aasdf`。
|
||
- 日志可见发送仍为 `asdf\n`，错误回显保持 `command not found: asdf`，与服务端行为一致。
|
||
- 其它输出路径（`stdout/stderr`、ANSI 颜色）不回归。
|
||
|
||
## 通用回归清单（每次改输入/粘贴链路都执行）
|
||
|
||
1. 英文输入 `ls` 不重复。
|
||
2. 第三方输入法输入 `jk`、`测试` 不重复。
|
||
3. `Enter`、`Ctrl+C`、方向键功能正常。
|
||
4. 工具栏粘贴与原生粘贴行为一致。
|
||
5. 长文本粘贴不触发网关 `BAD_REQUEST invalid_union`。
|
||
6. 多行粘贴不应被当作多次回车直接执行。
|