From bde1a6b25094ff796740bf9a4a3052dd38b878a3 Mon Sep 17 00:00:00 2001
From: zzzjy <zzzjy@zzzjy.cloud>
Date: Wed, 23 Sep 2026 01:33:35 +0800
Subject: [PATCH] docs: add serial port, SSH, and block-based interaction
 survey

---
 FEATURE_SURVEY.md | 120 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 120 insertions(+)
 create mode 100644 FEATURE_SURVEY.md

diff --git a/FEATURE_SURVEY.md b/FEATURE_SURVEY.md
new file mode 100644
index 0000000..2a93187
--- /dev/null
+++ b/FEATURE_SURVEY.md
@@ -0,0 +1,120 @@
+# hatty 核心特性深度调研：串口、SSH 与 Block 式交互架构
+
+本文档记录了关于 **串口通信（Serial Port）**、**SSH 远程主机连接** 以及 **Block 式终端交互（块状卡片交互）** 的技术可行性、底层原理、业界主流实现及在 `hatty` 终端中的落地路线。
+
+---
+
+## 1. 串口（Serial Port）与 SSH 会话架构调研
+
+### 1.1 核心结论
+当前基于 **Node.js (Electron) + xterm.js** 的架构，不仅完全支持串口与 SSH，而且相比纯 C/Rust 原生终端，在实现复杂度、生态成熟度以及跨平台支持上具备明显优势。
+
+`xterm.js` 本质上是**标准 ANSI/VT100 字符流渲染器**，它与底层传输媒介完全解耦，只需实现统一的 `Session` 接口，即可无缝承载多种数据流。
+
+```
+┌────────────────────────────────────────────────────────┐
+│                   统一前端界面 (hatty)                  │
+│       多标签页 / 分屏树 / WebGL 硬件加速 / 状态栏        │
+└───────────────────────────▲────────────────────────────┘
+                            │ 统一 IPC 字符流 (data, write, resize)
+┌───────────────────────────▼────────────────────────────┐
+│               会话调度抽象层 (Session Manager)           │
+├───────────────────┬────────────────────┬───────────────┤
+│ 1. 本地 PTY 会话  │  2. 远程 SSH 会话   │ 3. 硬件串口会话│
+│ (node-pty)        │  (ssh2)            │ (serialport)  │
+└───────────────────┴────────────────────┴───────────────┘
+```
+
+### 1.2 硬件串口支持方案（Serial Port / COM / `/dev/ttyUSB*`）
+- **核心依赖**：Node.js 原生模块 `serialport`（跨平台支持 Linux、macOS、Windows）。
+- **关键能力**：
+  1. **设备自动枚举与热插拔**：调用 `SerialPort.list()` 自动枚举 `/dev/ttyUSB0`、`/dev/ttyACM0` 等设备及其硬件 VID/PID。
+  2. **波特率与通信参数配置**：支持常见波特率（`9600`、`115200`、`921600`、`1500000` 等）、数据位、停止位与奇偶校验。
+  3. **数据管道流式打通**：
+     - 串口接收数据直接通过 IPC 推送至 `xterm.write(data)`；
+     - 终端按键输入通过 `port.write(data)` 写入串口硬件。
+- **应用场景**：单片机调试（STM32 / ESP32 / Arduino）、嵌入式 Linux 开发板（U-Boot 启动日志、Kernel Console）、路由器网络设备运维。
+
+### 1.3 远程 SSH 会话支持方案
+- **两种落地形式**：
+  - **基础命令行模式**：借助本地 PTY，直接在终端中敲入 `ssh user@host` 即可使用（当前开箱即用）。
+  - **集成式主机管理器（类似 Termius / Tabby）**：
+    - 引入 `ssh2` 纯 JS/Node 驱动库。
+    - **主机簿管理**：保存 IP、端口、用户名、私钥/密码、跳板机（ProxyJump）配置。
+    - **断线自动重连**。
+    - **集成 SFTP 传输**：侧边栏可视化浏览远程文件系统，支持文件直接拖拽上传/下载。
+
+---
+
+## 2. Block 式终端交互（块状终端）深度调研
+
+### 2.1 传统流式终端 vs. Block 式现代终端
+
+| 维度 | 传统流式终端 (Stream-based) | Block 式现代终端 (Block-based) |
+| :--- | :--- | :--- |
+| **本质模型** | 无状态的 2D 字符网格，纯文本覆盖更新 | 结构化对象列表，每个命令为一个独立封闭卡片 |
+| **命令边界** | 终端不知道命令从哪一行开始、哪一行结束 | 严格识别命令起止行、输出区域与退出状态 |
+| **状态感知** | 无法感知上一条命令的耗时和执行结果 | 精准显示执行耗时（如 `⏱ 120ms`）与退出码（`✔ 0` / `✘ 127`） |
+| **交互能力** | 只能靠鼠标手动拖选文本，容易误选提示符 | 一键复制该命令输出、重新运行、折叠输出、AI 诊断 |
+| **代表产品** | Alacritty, Kitty, GNOME Terminal | **Warp**, **Wave Terminal** |
+
+### 2.2 核心底层技术机制
+
+#### A. 语义转义序列（OSC 133 / FTCS 协议）
+行业公认的标准协议（FinalTerm 规范，现为 iTerm2、VS Code、Warp 采纳）。通过 Shell 钩子向 PTY 输出不可见的 ANSI 控制序列标记生命周期：
+- `ESC ] 133 ; A ST`：**提示符开始（Prompt Start）**
+- `ESC ] 133 ; B ST`：**命令输入开始（Command Start）**
+- `ESC ] 133 ; C ST`：**输出开始（Output Start / Executed）**
+- `ESC ] 133 ; D [; exitcode] ST`：**输出结束（Command Finished）**，携带命令真实退出码。
+
+#### B. Shell 钩子自动注入（Shell Hooks）
+在终端启动子进程时，通过环境变量或临时脚本注入：
+- **Bash**：配置 `PROMPT_COMMAND` 与 `trap ... DEBUG`。
+- **Zsh**：配置 `preexec()`（捕获命令字符串）与 `precmd()`（捕获 `$?` 状态）。
+- **Fish**：注册 `fish_prompt` 与 `fish_preexec` 事件。
+
+#### C. 输入区与输出区解耦（Detached Input Editor）
+- 传统终端中，输入框与文字网格混杂在一起；
+- 现代 Block 终端将屏幕底部的输入框做成独立的现代富文本编辑器（支持多行缩进、鼠标定位光标、语法高亮、Tab 智能补全）；
+- 用户按回车后，将输入内容打包推入上方的 Block 历史卡片流中。
+
+#### D. 全屏 TUI 程序平滑退避（Fallback）
+- 当检测到进入备用屏幕序列（`\x1b[?1049h`，如运行 `vim`、`htop`、`less`）时，自动退出 Block 卡片流模式，无缝切入标准 2D 终端网格；
+- 退出全屏程序时（`\x1b[?1049l`），自动切回 Block 交互。
+
+---
+
+## 3. 业界代表产品与技术路线
+
+1. **Warp**（商业闭源标杆）：
+   - 技术栈：Rust + 自研 GPU UI 渲染引擎。
+   - 特色：Block 块式交互开创者，卡片式展示，内置 Warp AI 可直接读取当前 Block 的错误日志进行诊断。
+2. **Wave Terminal**（开源代表，Apache 2.0）：
+   - 技术栈：**Electron + xterm.js + Go**（与 `hatty` 技术栈高度契合）。
+   - 特色：卡片不仅能展示命令输出，还能在 Block 内部内嵌网页渲染、Markdown 预览、代码编辑器与图像。
+3. **VS Code 终端 Shell Integration**（轻量级标杆）：
+   - 技术栈：TypeScript + xterm.js。
+   - 特色：轻量接入 OSC 133，在滚动条上标记红/蓝状态圆点，支持命令导航与快捷复制输出。
+
+---
+
+## 4. `hatty` 落地实施路线规划
+
+### 阶段一：轻量级 Block 标记与浮动操作栏（推荐 MVP 方案）
+1. 在 `pty-manager.cjs` 中为 Bash/Zsh 注入 20 行极简 Shell 钩子脚本（输出 OSC 133 信号）。
+2. 在 `terminal-view.js` 中使用 `xterm.parser.registerOscHandler(133, ...)` 捕获命令起止行与退出码。
+3. 当鼠标悬停在对应命令输出区域时，浮现微交互操作栏：
+   - 📋 **复制命令** / 📑 **只复制命令输出**
+   - ⏱ **命令执行耗时**（如 `142ms`）
+   - 🟢/🔴 **执行状态徽章**（`0` / `1`）
+   - 🤖 **AI 解释报错**按钮
+
+### 阶段二：全功能卡片式 Block 与独立输入栏（进阶重构方案）
+1. 界面转变为由卡片流（`div.block-card`）构成的滚动容器。
+2. 底部提供常驻的独立现代输入框，具备语法高亮与多行编辑。
+3. 动态检测 `Alt Screen`，在运行 `vim`/`htop` 时自适应无缝切换。
+
+### 阶段三：多源会话管理器（串口 + SSH）
+1. 抽象 `SessionManager`，提供统一的输入输出管道。
+2. 接入 `serialport` 模块，新增“硬件串口调试”标签页。
+3. 接入 `ssh2` 模块，新增“SSH 主机管理与 SFTP”支持。