# xterminal 与 wetty client 详细差异对比

## 1. 对比范围与结论

本文对比对象：

- `xterminal`：`/Users/gavin/lab/xterminal`
- `wetty` 当前项目前端 client：`/Users/gavin/lab/wetty/src/client/wetty/**`（以及其页面与配置面板）

核心结论：

1. 两者不是同层替代关系。`xterminal` 是前端终端组件库，`wetty client` 是完整 Web SSH 网关客户端。
2. `wetty client` 的核心能力来自 `xterm.js` 真终端仿真；`xterminal` 核心是“CLI 交互组件”，终端协议能力主要由业务层补齐。
3. 若目标是“做 SSH/PTY 级别会话”，`wetty client` 路线更直接；若目标是“嵌入式 Web CLI 组件”，`xterminal` 更轻更可控。

---

## 2. 产品定位与边界

### xterminal（组件库定位）

- 对外是 `XTerminal` 类 API（`mount/write/history/setCompleter/pause/resume/dispose`）。
- 不绑定任何固定后端协议，网络连接由业务方自行实现。
- 证据：
  - `source/index.ts:14`（类定义）
  - `source/index.ts:95`（挂载）
  - `source/index.ts:53`（输出 API）
  - `source/index.ts:90`（补全）

### wetty client（业务客户端定位）

- 页面入口直接完成：终端初始化、断线重连 UI、网关连接、数据收发。
- 与运行配置、网关协议、页面 DOM 强耦合。
- 证据：
  - `src/client/wetty.ts:26`（启动终端）
  - `src/client/wetty.ts:38`（socket 事件链）
  - `src/client/wetty/socket.ts:43`（网关 socket 实现）

---

## 3. 渲染与终端仿真能力

### wetty client：xterm.js 终端仿真

- 直接继承 `@xterm/xterm` 的 `Terminal`。
- 加载了 `FitAddon`、`WebLinksAddon`、`ImageAddon`。
- 原生具备终端仿真语义（光标、控制序列、窗口 resize、链接识别等）。
- 证据：
  - `src/client/wetty/term.ts:13`
  - `src/client/wetty/term.ts:21`
  - `src/client/wetty/term.ts:23`
  - `src/client/wetty/term.ts:24`

### xterminal：组件渲染模型

- 输出层以 HTML 片段写入为主。
- 核心库不自带完整 VT/ANSI 终端协议仿真。
- ANSI 处理与网关协议示例主要存在于 demo 脚本，不在库核心 API。
- 证据：
  - `source/output/index.ts:40`
  - `source/output/index.ts:49`
  - `demo/main.js:381`（ANSI 转换）

---

## 4. 输入模型差异（交互体验关键）

### wetty client：按键流（streaming input）

- 用户每次按键通过 `term.onData` 立即发送到后端。
- 更接近真实 SSH TTY 行为（如逐字符编辑、交互式全屏程序）。
- 证据：
  - `src/client/wetty.ts:60`

### xterminal：行输入（line-based）

- 默认在 `Enter` 时触发 `data` 事件并提交一整行。
- 上下箭头与历史命令是组件内建行为。
- 证据：
  - `source/instance.ts:136`（Enter 分支）
  - `source/instance.ts:141`（emit data）
  - `source/instance.ts:147`（历史导航）

影响：

1. 需要 PTY 级“实时按键”时，`xterminal` 必须由业务层额外桥接按键事件。
2. 需要“类 REPL 文本命令输入”时，`xterminal` 默认体验更简单。

---

## 5. 协议与连接层

### wetty client：内置网关协议适配

- 内建 `GatewaySocket`，封装事件 `connect/login/data/logout/disconnect/error`。
- 支持 `init/stdin/resize/control` 帧。
- 自动处理 `ping/pong`、`connected`、`disconnect` 控制帧。
- 证据：
  - `src/client/wetty/socket.ts:3`
  - `src/client/wetty/socket.ts:57`
  - `src/client/wetty/socket.ts:103`
  - `src/client/wetty/socket.ts:238`

### xterminal：协议在业务层（demo）实现

- 核心库无 WebSocket 协议绑定。
- demo 中手工实现网关连接、帧发送、回包处理、排队与批量 flush。
- 证据：
  - `demo/main.js:635`（connectByConfig）
  - `demo/main.js:572`（handleGatewayFrame）
  - `demo/main.js:501`（stdin 发送）

---

## 6. 配置系统与可配置能力

### wetty client

- 运行时读取 `/terminal.config.json`，并做最小字段校验、选中 server 逻辑。
- 有 iframe 配置面板，可改大量 xterm 选项并持久化 `localStorage.options`。
- 证据：
  - `src/client/wetty/runtimeConfig.ts:77`
  - `src/client/wetty/runtimeConfig.ts:107`
  - `src/client/wetty/term/confiruragtion.ts:8`
  - `src/client/wetty/term/load.ts:10`
  - `src/assets/xterm_config/index.html:62`

### xterminal

- 核心库配置简单（主要是挂载 target）。
- 无内建“终端参数 GUI 编辑器”，这部分由业务层自行实现。
- 证据：
  - `source/types.d.ts:103`

---

## 7. 移动端策略对比

### wetty client

- 对 xterm 屏幕加 `contenteditable` 以触发软键盘。
- 页面内置功能键浮层（方向键、Esc、Ctrl、Tab）。
- 证据：
  - `src/client/wetty/mobile.ts:3`
  - `index.html:28`
  - `src/client/wetty/term.ts:190`

### xterminal

- 核心对移动端做了更系统处理：
  - 隐藏 textarea + 自绘光标
  - `visualViewport` 监听，动态补偿软键盘遮挡
  - 避免 iOS Safari 聚焦导致 body 整体上推
- 证据：
  - `source/instance.ts:58`
  - `source/renderer/index.ts:27`
  - `theme/index.css:68`

结论：

1. `wetty` 的移动端更偏“终端页面增强”。
2. `xterminal` 的移动端更偏“组件内部自洽”。

---

## 8. 安全与风险点

### 8.1 前端渲染安全

- `xterminal` 提供 `writeSafe/escapeHTML`，明确区分不可信文本输出路径。
- 证据：
  - `source/index.ts:61`
  - `source/output/index.ts:19`

- `wetty` 断线信息使用 `innerHTML` 注入文本，若消息来源不可信有注入风险。
- 证据：
  - `src/client/wetty/disconnect.ts:9`

### 8.2 配置泄露风险

- 两边当前 `terminal.config.json` 都包含明文密码，属于高风险配置习惯（即使是开发环境）。
- 证据：
  - `/Users/gavin/lab/wetty/terminal.config.json`
  - `/Users/gavin/lab/xterminal/terminal.config.json`

---

## 9. 特性差异清单（功能维度）

### wetty client 独有/更强

1. xterm.js 终端仿真与 addon 生态。
2. 现成文件下载控制序列解析（`ESC[5i` / `ESC[4i`）。
3. 完整连接态 UI（overlay、reconnect、配置侧栏）。
4. 网关初始化载荷构造（含证书/私钥/密码多认证类型）。

证据：

- `src/client/wetty/download.ts:4`
- `src/client/wetty/download.ts:76`
- `src/client/wetty/socket.ts:161`
- `index.html:14`

### xterminal 独有/更强

1. 组件化 API 清晰，易嵌入任意前端。
2. 事件总线与资源释放边界明确（`dispose`、`register`）。
3. 历史记录与补全接口简洁。
4. 测试覆盖相对更系统（input/output/history/emitter/xterminal）。

证据：

- `source/index.ts:117`
- `source/emitter/index.ts:16`
- `tests/xterminal.test.ts:4`
- `tests/input.test.ts:5`

---

## 10. 工程化与依赖体量

### 依赖与发布目标

- `wetty`：
  - 运行时依赖较重（含 `@xterm/*`、`express`、`socket.io`、`node-pty` 等）。
  - 发布目标是应用（`bin/main` + server + client）。
  - 证据：`package.json:44`（dependencies）

- `xterminal`：
  - 核心 runtime 无 dependencies（仅 devDependencies）。
  - 发布目标是库（UMD + ESM + CSS + types）。
  - 证据：`package.json:64`（devDependencies）、`rollup.config.js:31`

### 产物规模（当前工作区构建结果）

- `wetty` client bundle：`build/client/wetty.js` 约 `511K`（含 source map 更大）。
- `xterminal` dist：`xterminal.esm.js` 约 `8.5K`，`xterminal.umd.js` 约 `16K`。

结论：

1. 若只需要嵌入命令交互 UI，`xterminal` 体量优势明显。
2. 若需要终端仿真，`wetty`/xterm.js 的体量属于能力成本。

---

## 11. 测试对比

- `wetty` 当前仓库测试集中在：
  - 客户端 `FileDownloader`
  - 服务端 shell escaping
  - 证据：`src/client/wetty/download.spec.ts:10`、`src/server/shared/shell.spec.ts:5`

- `xterminal` 测试覆盖：
  - `xterminal/input/output/history/emitter/disposable/reactivity`
  - 证据：`/Users/gavin/lab/xterminal/tests/*.test.ts`

---

## 12. 当前项目内一个关键不一致点

在当前 `wetty` 仓库中，前端 client 已改为“网关 WebSocket 帧协议”，但后端原有代码仍是 Socket.IO 事件模型（`input/resize/commit`）。

- 前端证据：`src/client/wetty/socket.ts:97`
- 后端证据：`src/server/spawn.ts:38`、`src/server/socketServer/socket.ts:38`

这意味着：

1. 当前 client 与本仓库原 server 不天然对接。
2. client 实际更像在对接外部网关服务，而不是本地 wetty server。

---

## 13. 选型建议（按目标场景）

### 选 wetty client 路线

适合：

1. 目标是“浏览器里完整 SSH 终端”。
2. 需要 xterm.js 级别兼容能力（控制序列、终端行为一致性）。
3. 接受更重依赖与更复杂调试链路。

### 选 xterminal 路线

适合：

1. 目标是“可嵌入、可定制、轻量 CLI 组件”。
2. 协议、渲染、会话行为希望完全可控。
3. 可接受自行补齐 SSH/ANSI/PTY 的业务层逻辑。

---

## 14. 如果要做“xterminal + wetty 能力融合”，推荐最小改造路径

1. 保持 `xterminal` 作为 UI 输入输出壳，不直接替换为 xterm.js。
2. 单独抽出 `gateway client` 模块（`connect/send/receive/reconnect`），不要继续写在 demo/page 脚本。
3. 定义统一帧协议适配层，把 `init/stdin/resize/control/stdout/stderr/error` 规范化。
4. 将 ANSI 渲染器从 demo 抽为独立模块，补测试（尤其是跨帧、退格、CR/LF）。
5. 最后再评估是否有必要迁移到 xterm.js（仅在终端兼容性成为瓶颈时）。

---

## 15. 风险清单（落地前需确认）

1. 明文密码配置必须替换（令牌化或后端临时凭据）。
2. 断线错误信息渲染方式应改为安全文本输出（避免 `innerHTML` 注入）。
3. 若要支持交互式全屏程序（vim/top/tmux），需确认输入模型是按键流而非行输入。
4. 若继续沿用移动端触控条，需要统一“焦点不丢失”的处理策略（当前两项目实现不同）。

---

## 16. 快速摘要（一页版）

1. `xterminal` 是“轻量终端 UI 组件库”；`wetty client` 是“完整 Web SSH 客户端”。
2. `wetty` 的强项是 xterm.js 终端仿真；`xterminal` 的强项是组件化、轻量、可嵌入。
3. 两者可融合，但不是无缝替换；最大差异在输入模型、协议耦合、终端仿真深度。
4. 当前 `wetty` 仓库里 client/server 协议模型存在分叉，后续演进需先统一架构方向。