first commit

xterminal/docs/question-solved.md

@@ -0,0 +1,43 @@
+# 问题闭环记录（Question Solved）
+
+本文档记录已确认问题的现象、根因、修复与回归要点，避免重复踩坑。
+
+## 目录
+
+1. [2026-03-03：回车后首字母重复显示（`aasdf`）](#enter-leading-dup)
+2. [回归检查清单](#regression-checklist)
+
+---
+
+<a id="enter-leading-dup"></a>
+## 2026-03-03：回车后首字母重复显示（`aasdf`）
+
+### 现象
+- 输入英文命令（如 `asdf`）后回车，提示符行偶发显示为 `aasdf`。
+- 服务端实际收到与执行仍是 `asdf`（例如返回 `zsh: command not found: asdf`）。
+
+### 根因
+- SSH 回显是分片到达的，典型序列为：`"a"`、`"\b as"`、`"df..."`。
+- 旧逻辑按帧即时渲染，第一帧字符已写入后，下一帧开头的 `\b` 不能回退上一帧字符，造成视觉重复。
+- 回显中还可能夹杂 `\r\r\n` 与 ANSI 控制序列，若不按终端语义处理会放大错位和空行问题。
+
+### 修复
+- 文件：`demo/main.js`
+- 策略：
+1. 在 `renderAnsiToHtml` 中补齐控制字符处理：`BS(\x08)`、`CRLF(\r\n)`、裸 `CR(\r)`。
+2. 增加短窗口流式合帧（`STREAM_BATCH_MS`），将连续 `stdout/stderr` 分片先合并后渲染，保证跨帧 `\b/\r` 能生效。
+3. 保留本地回显清理（`clearLast()`），避免与远端回显叠加。
+
+### 验证
+- 复现 `asdf` 回车，不再出现 `aasdf`。
+- 调试日志显示发送仍为 `asdf\n`，与服务端执行结果一致。
+
+---
+
+<a id="regression-checklist"></a>
+## 回归检查清单
+
+1. 英文输入后回车不出现首字母重复。
+2. `stdout/stderr` 样式渲染正常（ANSI 颜色不回归）。
+3. 回车后不新增多余空行。
+4. 本地回显与远端回显不叠加。