1055 lines
52 KiB
Markdown
1055 lines
52 KiB
Markdown
# xterm 移植跨平台终端核心架构方案（2026-03-01）
|
||
|
||
## 1. 目标与范围
|
||
|
||
本方案构建一个**生产可用的跨平台终端核心库**，将 xterm.js 的 VT 仿真能力移植为独立的、无 DOM 依赖的 TypeScript 包（`packages/terminal-core`），供 Web 端、iOS 端（Capacitor WKWebView）、微信小程序端三个平台共用，各端仅需实现 Transport 与 Renderer 两个平台边界。
|
||
|
||
规范基线：
|
||
|
||
1. 渲染与输入语义以 `xterm.js@5.3.0` 源码为准。
|
||
2. 文档中的换行、回显、光标、粘贴规则均以该版本源码行为校正。
|
||
3. 若未来升级 xterm 版本，需先做"规范差异审计"再修改本方案。
|
||
|
||
目标：
|
||
|
||
1. **核心包独立**：`packages/terminal-core` 无 DOM 依赖，可在任意 JS Runtime（浏览器/WKWebView/微信小程序逻辑层）中运行。
|
||
2. **三端生产可用**：Web（Vue SPA）、iOS（Capacitor WKWebView 加载同一 Web 构建产物）、微信小程序（原生 WXML 组件 + 逻辑层复用 terminal-core）。
|
||
3. **平台边界最薄**：各端只需实现 `TerminalTransport`（网络层）和 `RendererAdapter`（渲染层）两个接口，Session/VT 仿真/输入映射全部共用。
|
||
4. **SSH 协议外置**：SSH 握手与流转发由 `apps/gateway`（WebSocket）或 iOS 原生插件负责，`terminal-core` 只处理 PTY stdout/stderr 字节流。
|
||
5. **构建/运行可复用**：命令约定统一为 `dev/build/test/lint/typecheck`。
|
||
|
||
## 2. 非目标
|
||
|
||
1. 不在本方案中实现 SSH 协议本身（由 `apps/gateway` 或 iOS 原生 Swift 插件负责）。
|
||
2. 不修改 `apps/gateway` 的业务协议和转发逻辑。
|
||
3. 不改 `packages/shared` 的现有模型定义。
|
||
4. 不实现图片/Sixel/Kitty 图像协议渲染。
|
||
|
||
### 2.1 明确不实现的 xterm 能力
|
||
|
||
以下能力在本方案中确认跳过，遇到相关需求时应主动忽略，不可因"部分实现"引入不稳定行为：
|
||
|
||
1. Kitty 键盘协议（`CSI =u / >u / <u / ?u`，`KittyKeyboardFlags`）。
|
||
2. Win32InputMode（Windows 伪终端特有输入模式）。
|
||
3. 鼠标跟踪模式（`?1000 / ?1002 / ?1003` 及 `onBinary` 二进制鼠标上报通道）。
|
||
4. `screenReaderMode` 及 ARIA 无障碍支持。
|
||
5. Markers / Decorations（`registerMarker / registerDecoration`）。
|
||
6. Link Provider（`registerLinkProvider`）。
|
||
7. CharacterJoiner（`registerCharacterJoiner / deregisterCharacterJoiner`，仅 WebGL 渲染器使用）。
|
||
8. LigaturesAddon / ImageAddon（Sixel/Kitty 图片协议）。
|
||
9. SerializeAddon（终端状态序列化，由 `OutputBuffer` 承担类似职责）。
|
||
10. Unicode Grapheme Clusters（`addon-unicode-graphemes`，emoji 字形簇宽度计算）。
|
||
11. DECSCA（字符保护，`CSI "q`）与 DECRQM（模式查询，`CSI $p / ?$p`）。
|
||
12. `macOptionIsMeta`、`altClickMovesCursor`、`rightClickSelectsWord`（桌面端特有选项）。
|
||
13. OSC 52（剪贴板写入）、OSC 133（Shell 集成/语义标记）及其它非标 OSC 扩展。
|
||
14. `attachCustomKeyEventHandler / attachCustomWheelEventHandler` 公开 API（通过 `eventOwnershipRouter` 统一管理，不暴露此 API）。
|
||
|
||
## 3. 独立性与复用规则
|
||
|
||
### 3.1 必须满足
|
||
|
||
1. `packages/terminal-core` 不得 `import` `apps/*` 的业务模块；`apps/*` 可单向依赖 `terminal-core`。
|
||
2. 禁止运行时依赖 `@xterm/*` 包；xterm 仅作为源码语义参考，不作为可执行依赖。
|
||
3. `terminal-core` 构建产物在零 DOM 环境（微信小程序逻辑层）中可直接运行。
|
||
4. 各平台的 Transport / Renderer / InputBridge 实现隔离在各自 `apps/` 或平台目录内，不得混用。
|
||
|
||
### 3.2 允许复用
|
||
|
||
1. 依赖版本策略可复用（例如与根工程保持同主版本）。
|
||
2. 工程工具可复用（TypeScript、Vite、ESLint、Vitest 配置风格）。
|
||
3. 运行方式可复用（统一命令命名，不要求命令实现完全一致）。
|
||
4. 主题 token 可复用现有 Web/小程序的成熟定义（颜色变量、语义色分层、主题切换策略），但实现代码保留在各端目录内。
|
||
|
||
### 3.3 核心包 DOM 隔离约束（强制）
|
||
|
||
1. `packages/terminal-core/src/` 内所有文件**禁止**直接引用 `document / window / HTMLElement / Event / Canvas / CanvasRenderingContext2D` 等任何 DOM/BOM API。
|
||
2. 平台相关的测量（字符宽高、容器尺寸）以 `IMeasureAdapter` 接口注入；事件来源（键盘/IME/触摸）以 `IInputSource` 接口注入；`terminal-core` 只定义接口，不实现。
|
||
3. `sizeCalculator` 在 core 包内**只保留纯算法**（给定 px 宽高 → cols/rows），DOM 测量（`ResizeObserver`）和 wx 测量（`wx.createSelectorQuery`）各自在 `apps/` 中实现并注入。
|
||
4. `imeController` 在 core 包内只保留 IME 状态机逻辑（idle/composing/commit_pending），`compositionstart/end` 等 DOM 事件由 Web 层订阅后调用 core 接口；小程序通过 `bindinput` + `isComposing` 等效调用同一接口。
|
||
5. CI 中增加以下 typecheck 任务保证零 DOM 泄漏：
|
||
```bash
|
||
tsc -p packages/terminal-core/tsconfig.json --lib esnext --noEmit
|
||
```
|
||
|
||
## 4. 目录规划（实施级）
|
||
|
||
```text
|
||
packages/terminal-core/ ← 核心包，零 DOM，三端共用
|
||
package.json ← name: "@remoteconn/terminal-core"
|
||
tsconfig.json ← lib: ["esnext"]，无 dom lib
|
||
src/
|
||
session/
|
||
sessionMachine.ts ← 会话状态机（纯状态逻辑）
|
||
sessionTypes.ts
|
||
transport/
|
||
terminalTransport.ts ← TerminalTransport 接口定义
|
||
renderer/
|
||
terminalCore.ts ← VT 仿真内核（无 DOM）
|
||
rendererAdapter.ts ← RendererAdapter 接口定义
|
||
outputBuffer.ts
|
||
input/
|
||
inputBridge.ts ← 键序列映射纯逻辑
|
||
imeController.ts ← IME 状态机（无 DOM 事件）
|
||
IInputSource.ts ← 平台输入源接口
|
||
layout/
|
||
sizeCalculator.ts ← 纯算法：px → cols/rows
|
||
cursorMath.ts
|
||
IMeasureAdapter.ts ← 平台测量接口
|
||
sanitize/
|
||
terminalSanitizer.ts
|
||
|
||
packages/shared/ ← 现有，不改
|
||
|
||
apps/web/ ← Vue SPA（Web + iOS Capacitor WKWebView）
|
||
src/
|
||
transport/
|
||
gatewayTransport.ts ← WebSocket → TerminalTransport
|
||
iosNativeTransport.ts ← Capacitor Bridge → TerminalTransport
|
||
renderer/
|
||
compatRenderer.ts ← Canvas DOM 渲染
|
||
textareaRenderer.ts ← textarea DOM 渲染
|
||
input/
|
||
domInputBridge.ts ← DOM 事件 → IInputSource
|
||
domImeController.ts ← compositionstart/end → ImeController
|
||
layout/
|
||
domMeasureAdapter.ts ← ResizeObserver → IMeasureAdapter
|
||
pages/TerminalPage.vue
|
||
components/
|
||
TerminalToolbar.vue
|
||
TerminalViewport.vue
|
||
TerminalInputBar.vue
|
||
TerminalTouchTools.vue
|
||
stores/useTerminalStore.ts
|
||
styles/terminal.css
|
||
|
||
apps/miniprogram/ ← 微信小程序（原生组件）
|
||
utils/
|
||
wxTransport.js ← wx.connectSocket → TerminalTransport
|
||
wxInputBridge.js ← bindinput/bindconfirm → IInputSource
|
||
wxMeasureAdapter.js ← wx.createSelectorQuery → IMeasureAdapter
|
||
components/
|
||
terminal-core-view/ ← WXML 渲染，消费 TerminalCore.snapshot()
|
||
index.js index.wxml index.wxss
|
||
|
||
ios/plugin/RemoteConnSSHPlugin/ ← Swift SSH 插件（补全骨架后供 Capacitor 调用）
|
||
```
|
||
|
||
## 4.1 微信小程序消费 `terminal-core` 构建产物（工程约束）
|
||
|
||
由于小程序逻辑层**不支持 TypeScript 直接运行**，需要以下构建策略：
|
||
|
||
1. `packages/terminal-core/package.json` 增加 `"miniprogram": "dist-miniprogram/index.js"` 字段，提供预编译纯 JS CommonJS 产物。
|
||
2. 对应构建命令：`tsc -p packages/terminal-core/tsconfig.json --module commonjs --outDir packages/terminal-core/dist-miniprogram`，产物为零 DOM 纯 JS，可直接被小程序 `require()`。
|
||
3. `apps/miniprogram/utils/wxTransport.js` 等文件通过相对路径引用：`require('../../../packages/terminal-core/dist-miniprogram/index')`。
|
||
4. CI 中小程序相关构建步骤之前，必须先完成 `terminal-core` 构建（根 `package.json scripts` 中保证 `workspaces` 构建顺序，或通过 `prebuild` 钩子）。
|
||
5. 源码变更后必须重建 `dist-miniprogram`；**禁止**小程序逻辑层直接 `require` TypeScript 源文件。
|
||
|
||
## 5. 总体架构与数据流
|
||
|
||
```text
|
||
┌────────────── packages/terminal-core（零 DOM，三端共用）──────────────┐
|
||
│ SessionMachine → TerminalTransport(接口) ←→ Gateway/iOS/wx │
|
||
│ stdout/stderr → TerminalSanitizer → OutputBuffer → TerminalCore │
|
||
│ TerminalCore.snapshot() → RendererAdapter(接口) → 平台渲染层 │
|
||
│ IInputSource(接口) → InputBridge(键序列映射) → Transport.send() │
|
||
│ IMeasureAdapter(接口) → sizeCalculator(px→cols/rows) → resize │
|
||
└───────────────────────────────────────────────────────────────────────┘
|
||
↓ 接口注入 ↓ 接口注入
|
||
┌── Web / iOS ────────────────┐ ┌── 微信小程序 ────────────────────┐
|
||
│ GatewayTransport(WebSocket) │ │ WxTransport(wx.connectSocket) │
|
||
│ IosNativeTransport(Capacitor│ │ terminal-core-view(WXML组件) │
|
||
│ compatRenderer(Canvas DOM) │ │ wxInputBridge(bindinput) │
|
||
│ textareaRenderer(textarea) │ │ wxMeasureAdapter(selectorQuery) │
|
||
│ domInputBridge │ └─────────────────────────────────┘
|
||
│ domMeasureAdapter(ResizeObs)│
|
||
└─────────────────────────────┘
|
||
```
|
||
|
||
关键原则：
|
||
|
||
1. 传输层不感知渲染器类型；渲染器不感知传输层。
|
||
2. 输入处理统一走 `InputBridge`（键序列映射逻辑），事件来源由各平台的 `IInputSource` 实现注入。
|
||
3. 渲染器通过统一 `RendererAdapter` 接口实现，支持 compat/textarea 切换和跨端适配。
|
||
4. 输入映射遵循 xterm 规则：`Enter -> CR`，粘贴文本行结束归一到 `CR`。
|
||
5. 输出渲染遵循 xterm 控制字符纪律：`CR` 与 `LF` 分离语义，`convertEol` 默认 `false`。
|
||
6. 原生响应优先：软键盘、选区、滚动由原生通道（Web `textarea` / 小程序 `input`）主导，不得被 terminal-core 接管。
|
||
7. 事件主权清晰：键盘/触摸事件先由应用层做区域过滤与路由，再决定是否进入终端输入链路。
|
||
|
||
## 6. 状态机规划
|
||
|
||
## 6.1 会话状态机（连接生命周期）
|
||
|
||
状态集合（与现有模型对齐）：
|
||
|
||
1. `idle`
|
||
2. `connecting`
|
||
3. `auth_pending`
|
||
4. `connected`
|
||
5. `reconnecting`
|
||
6. `disconnected`
|
||
7. `error`
|
||
|
||
合法迁移（必须在 `sessionMachine.ts` 中强校验）：
|
||
|
||
1. `idle -> connecting | disconnected`
|
||
2. `connecting -> auth_pending | error | disconnected`
|
||
3. `auth_pending -> connected | error | disconnected`
|
||
4. `connected -> reconnecting | disconnected | error`
|
||
5. `reconnecting -> connected | error | disconnected`
|
||
6. `disconnected -> connecting | idle`
|
||
7. `error -> connecting | disconnected`
|
||
|
||
触发事件：
|
||
|
||
1. `connect_request`
|
||
2. `socket_open`
|
||
3. `connected_frame`
|
||
4. `stdout_first_packet`
|
||
5. `disconnect_frame/ws_close`
|
||
6. `error_frame/ws_error`
|
||
7. `manual_disconnect`
|
||
8. `auto_reconnect_timeout`
|
||
|
||
## 6.2 输入状态机（IME/普通输入）
|
||
|
||
状态：
|
||
|
||
1. `input_idle`
|
||
2. `input_composing`
|
||
3. `input_commit_pending`
|
||
|
||
规则：
|
||
|
||
1. `compositionstart` -> `input_composing`
|
||
2. `compositionend` -> 进入 `input_commit_pending`，提交非 ASCII 候选
|
||
3. `beforeinput/input` 非组合态可触发 ASCII 兜底发送
|
||
4. 超时守卫（如 1.8s）未收到 `compositionend` 时自动恢复到 `input_idle`
|
||
|
||
## 6.3 触摸焦点状态机（移动端）
|
||
|
||
动作集合：
|
||
|
||
1. `BLUR_ONLY`
|
||
2. `FOCUS_KEYBOARD`
|
||
3. `PASS_NATIVE`
|
||
4. `PASS_SCROLL`
|
||
|
||
决策优先级：
|
||
|
||
1. `hasSelectionStart || hasSelectionEnd` -> `PASS_NATIVE`
|
||
2. `scrollLike` -> `PASS_SCROLL`
|
||
3. `moved` -> `PASS_NATIVE`
|
||
4. `!inBand` -> `BLUR_ONLY`
|
||
5. `inBand` -> `FOCUS_KEYBOARD`
|
||
|
||
硬约束（新增）：
|
||
|
||
1. 只有 `FOCUS_KEYBOARD` 动作允许触发原生键盘弹出。
|
||
2. `FOCUS_KEYBOARD` 必须满足“光标附近行”条件（`inBand=true`），禁止在非光标邻近区域弹键盘。
|
||
3. `PASS_NATIVE/PASS_SCROLL` 禁止 `preventDefault`，确保原生选区和滚动不被破坏。
|
||
4. 禁止在终端根容器上全局拦截 `touchstart/touchmove/click`；仅允许在明确手势分支下做最小拦截。
|
||
5. 移动端 `compat` 仅承担回显渲染，输入焦点必须由原生 `textarea` 锚点持有。
|
||
6. 禁止在非用户手势路径下调用 `terminal.focus()` 触发软键盘。
|
||
|
||
## 6.4 渲染模式状态机
|
||
|
||
状态：
|
||
|
||
1. `renderer_compat`
|
||
2. `renderer_textarea`
|
||
|
||
切换事件：
|
||
|
||
1. `switch_to_compat`
|
||
2. `switch_to_textarea`
|
||
|
||
切换过程必须原子化：
|
||
|
||
1. `oldRenderer.dispose()`
|
||
2. `newRenderer.mount(container)`
|
||
3. `replay buffer`
|
||
4. `apply size/theme`
|
||
5. `focus restore`（仅桌面自动聚焦）
|
||
|
||
## 6.5 换行模式状态（xterm 对齐）
|
||
|
||
状态：
|
||
|
||
1. `convertEol=false`（默认）
|
||
2. `convertEol=true`（由 `CSI 20 h` 打开）
|
||
|
||
规则：
|
||
|
||
1. `LF/VT/FF` 进入 `lineFeed()`：始终 `y+1`，并在触底时滚屏。
|
||
2. `convertEol=true` 时，`lineFeed()` 额外执行 `x=0`；`false` 时保留列位置。
|
||
3. `CR` 仅执行 `x=0`，不改变 `y`。
|
||
4. `NEL`（`ESC E` / `C1.NEL`）等价 `x=0 + index()`（下移一行并在必要时滚屏）。
|
||
5. 右边界写入是否自动折行由 `DECAWM(wraparound)` 控制。
|
||
6. 自动折行触发条件按 xterm 口径：字符写入将越过末列时触发换行；换行行需标记 `isWrapped=true`。
|
||
7. 显式 `LF` 后目标行应清除 `isWrapped`，避免把硬换行误判为软换行。
|
||
|
||
## 6.6 屏幕缓冲状态（主屏/备用屏，强制）
|
||
|
||
状态：
|
||
|
||
1. `buffer_normal`（主屏）
|
||
2. `buffer_alternate`（备用屏）
|
||
|
||
切换规则（xterm 对齐）：
|
||
|
||
1. `CSI ? 47 h` / `CSI ? 1047 h`：切换到备用屏。
|
||
2. `CSI ? 47 l` / `CSI ? 1047 l`：返回主屏。
|
||
3. `CSI ? 1049 h`：保存光标状态并切换到备用屏。
|
||
4. `CSI ? 1049 l`：返回主屏并恢复保存光标状态。
|
||
5. 对齐 `xterm.js@5.3.0` 现实行为：`1049` 不强制清空备用屏历史（按源码注释口径处理）。
|
||
|
||
实现约束：
|
||
|
||
1. `TerminalCore` 必须同时维护 `normalBuffer` 与 `alternateBuffer`，仅一个为 `activeBuffer`。
|
||
2. 两个缓冲区的 `cursor`、`scroll region`、`isWrapped` 状态独立维护，禁止互相污染。
|
||
3. 切屏仅切换活动缓冲区引用，不得重建对象导致历史丢失。
|
||
4. `1049` 路径必须包含 `saveCursor/restoreCursor`，并保证退出全屏后提示符位置正确。
|
||
5. 该能力只影响输出缓冲与光标状态，不改变“原生输入主通道”与事件归属策略。
|
||
|
||
## 7. 组件职责与接口
|
||
|
||
## 7.1 `TerminalPage.vue`
|
||
|
||
职责：
|
||
|
||
1. 页面编排、模式切换、连接/断开、状态展示。
|
||
2. 组装 `store + renderer + inputBridge`。
|
||
|
||
## 7.2 `TerminalViewport.vue`
|
||
|
||
职责：
|
||
|
||
1. 只负责承载渲染容器（不直连 transport）。
|
||
2. 提供挂载点给 `RendererAdapter`。
|
||
|
||
## 7.3 `TerminalInputBar.vue`
|
||
|
||
职责：
|
||
|
||
1. 文本输入框、发送按钮、粘贴、快捷键入口。
|
||
2. 通过 `InputBridge.send()` 发送，不直接访问 transport。
|
||
|
||
## 7.4 `TerminalToolbar.vue`
|
||
|
||
职责：
|
||
|
||
1. 展示连接状态、延迟、渲染模式。
|
||
2. 触发 `connect/disconnect/clear/switchRenderer`。
|
||
|
||
## 7.5 `TerminalTouchTools.vue`
|
||
|
||
职责：
|
||
|
||
1. 方向键、Enter、Ctrl+C、Tab、Paste。
|
||
2. 输出标准控制序列（如 `ESC[A`）。
|
||
|
||
## 8. 传输与协议实现要点
|
||
|
||
## 8.1 四个核心平台接口（TypeScript 签名）
|
||
|
||
以下接口定义于 `packages/terminal-core/src/` 内，各端必须严格实现，**不得扩展签名**。
|
||
|
||
```typescript
|
||
// ── 会话状态（§6.1 状态集对应） ───────────────────────────────────────────
|
||
type SessionState =
|
||
| 'idle' | 'connecting' | 'auth_pending' | 'connected'
|
||
| 'reconnecting' | 'disconnected' | 'error';
|
||
|
||
// ── 连接参数 ──────────────────────────────────────────────────────────────
|
||
interface ConnectParams {
|
||
host: string;
|
||
port: number;
|
||
username: string;
|
||
password?: string;
|
||
privateKey?: string; // PEM 格式私钥字符串
|
||
passphrase?: string;
|
||
}
|
||
|
||
// ── 帧元数据（可选，用于去重/溯源） ──────────────────────────────────────
|
||
interface FrameMeta {
|
||
source?: 'keyboard' | 'assist' | 'paste';
|
||
txnId?: string;
|
||
}
|
||
|
||
// ── Transport 事件（出站帧，见 §8.2） ─────────────────────────────────────
|
||
type TransportEvent =
|
||
| { type: 'stdout'; data: string }
|
||
| { type: 'stderr'; data: string }
|
||
| { type: 'control'; action: 'connected' | 'disconnect' | 'pong'; data?: string }
|
||
| { type: 'error'; code: string; message: string };
|
||
|
||
type TransportEventListener = (event: TransportEvent) => void;
|
||
|
||
// ── TerminalTransport 接口 ────────────────────────────────────────────────
|
||
interface TerminalTransport {
|
||
connect(params: ConnectParams): Promise<void>;
|
||
send(data: string, meta?: FrameMeta): void;
|
||
resize(cols: number, rows: number): void;
|
||
disconnect(reason?: string): void;
|
||
on(listener: TransportEventListener): () => void; // 返回取消订阅函数
|
||
getState(): SessionState;
|
||
}
|
||
|
||
// ── RendererAdapter 接口 ──────────────────────────────────────────────────
|
||
interface RendererAdapter {
|
||
mount(container: unknown): void; // Web: HTMLElement；小程序: WXML 组件自挂载时传 null
|
||
write(data: string): void; // 增量写入 VT 字节流
|
||
resize(cols: number, rows: number): void;
|
||
applySnapshot(snapshot: TerminalSnapshot): void; // 全量重放（切换渲染器时调用）
|
||
dispose(): void;
|
||
}
|
||
|
||
// ── IMeasureAdapter 接口 ──────────────────────────────────────────────────
|
||
interface IMeasureAdapter {
|
||
measureChar(): { widthPx: number; heightPx: number }; // 单字符像素尺寸
|
||
measureContainer(): { widthPx: number; heightPx: number }; // 终端容器内部尺寸
|
||
onResize(cb: () => void): () => void; // 容器尺寸变化订阅
|
||
}
|
||
|
||
// ── IInputSource 接口 ─────────────────────────────────────────────────────
|
||
interface KeyPayload {
|
||
key: string; code: string;
|
||
ctrlKey: boolean; altKey: boolean; shiftKey: boolean; metaKey: boolean;
|
||
}
|
||
interface InputPayload { data: string; isComposing: boolean; }
|
||
interface PastePayload { text: string; }
|
||
interface CompositionPayload { data: string; }
|
||
|
||
interface IInputSource {
|
||
on(event: 'key', cb: (p: KeyPayload) => void): () => void;
|
||
on(event: 'input', cb: (p: InputPayload) => void): () => void;
|
||
on(event: 'paste', cb: (p: PastePayload) => void): () => void;
|
||
on(event: 'compositionstart', cb: (p: CompositionPayload) => void): () => void;
|
||
on(event: 'compositionend', cb: (p: CompositionPayload) => void): () => void;
|
||
}
|
||
```
|
||
|
||
## 8.2 网关帧协议（三端统一，不分叉）
|
||
|
||
帧格式：JSON 序列化后经 WebSocket / Capacitor / wx.connectSocket 传输。
|
||
|
||
```typescript
|
||
// ── 入站帧（客户端 → 网关） ──────────────────────────────────────────────
|
||
type InboundFrame =
|
||
| { type: 'init'; sessionId: string; params: ConnectParams }
|
||
| { type: 'stdin'; data: string; meta?: FrameMeta }
|
||
| { type: 'resize'; cols: number; rows: number }
|
||
| { type: 'control'; action: 'ping' | 'pong' | 'disconnect'; reason?: string };
|
||
|
||
// ── 出站帧（网关 → 客户端） ──────────────────────────────────────────────
|
||
type OutboundFrame =
|
||
| { type: 'stdout'; data: string } // PTY 输出（UTF-8 字符串）
|
||
| { type: 'stderr'; data: string } // PTY 错误输出
|
||
| { type: 'control'; action: 'connected' | 'disconnect' | 'pong'; data?: string }
|
||
| { type: 'error'; code: ErrorCode; message: string };
|
||
|
||
type ErrorCode =
|
||
| 'AUTH_FAILED' // SSH 认证失败
|
||
| 'HOST_UNREACHABLE' // 目标主机不可达
|
||
| 'TIMEOUT' // 连接超时
|
||
| 'SESSION_NOT_FOUND' // sessionId 不存在
|
||
| 'INTERNAL_ERROR'; // 服务端内部错误
|
||
```
|
||
|
||
约束：
|
||
|
||
1. `data` 字段统一为 UTF-8 字符串；二进制内容须 Base64 编码后传输。
|
||
2. `txnId` 为可选幂等键，网关对相同 `txnId` 的 `stdin` 帧去重。
|
||
3. 协议版本通过 `init` 帧扩展字段（如 `version: '1'`）传递，当前默认省略。
|
||
|
||
## 8.3 三端 Transport 实现
|
||
|
||
| 实现 | 位置 | 底层 API | 适用场景 |
|
||
|---|---|---|---|
|
||
| `GatewayTransport` | `apps/web/src/transport/gatewayTransport.ts` | `WebSocket` | Web 浏览器、微信小程序后备 |
|
||
| `IosNativeTransport` | `apps/web/src/transport/iosNativeTransport.ts` | `window.Capacitor.Plugins.RemoteConnSSH` | iOS Capacitor WKWebView |
|
||
| `WxTransport` | `apps/miniprogram/utils/wxTransport.js` | `wx.connectSocket` | 微信小程序原生 |
|
||
|
||
约束：
|
||
|
||
1. 三端帧协议完全一致（`8.2` 定义），Transport 实现只替换网络层 API，不改协议语义。
|
||
2. `IosNativeTransport` 通过 Capacitor Bridge 调用 Swift 插件（`connect/send/resize/disconnect` 四方法 + `addListener` 事件推送）；Swift 层须完成真实 SSH 接入（当前为骨架）。
|
||
3. `WxTransport` 的 `wx.connectSocket` 在小程序逻辑层运行，帧收发逻辑与 `GatewayTransport` 对称实现。
|
||
|
||
## 9. 渲染管线设计
|
||
|
||
## 9.1 输出处理链
|
||
|
||
1. 收到 `stdout/stderr`。
|
||
2. 执行 `sanitizeTerminalOutput`（过滤同步更新模式等控制序列噪音）。
|
||
3. 追加到 `OutputBuffer`（条目上限 + 字节上限双阈值）。
|
||
4. `outputRevision++`。
|
||
5. 渲染器增量写入；必要时重放。
|
||
|
||
## 9.2 缓冲策略（必须）
|
||
|
||
1. `maxEntries` 下限保护（建议 >= 200）。
|
||
2. `maxBytes` 下限保护（建议 >= 64KB）。
|
||
3. 先按条目裁剪，再按字节裁剪。
|
||
4. 至少保留最新一条，避免全清空闪烁。
|
||
|
||
## 9.3 兼容渲染规则（自研）
|
||
|
||
1. 使用 `write()` 增量写入，不用 `writeln()` 改写换行语义。
|
||
2. `convertEol` 默认值必须为 `false`（与 xterm 默认一致）。
|
||
3. 显式 `LF` 不等于 `CRLF`：`CR` 和 `LF` 分别处理，禁止业务层自行合并。
|
||
4. `fit` 后同步 `resize(cols, rows)`。
|
||
|
||
## 9.4 textarea 渲染规则
|
||
|
||
1. 采用“只读显示区 + 输入区”或“单 textarea 双模式”方案（二选一，建议前者）。
|
||
2. 输出区按文本流追加，必要时使用 `requestAnimationFrame` 批量刷新。
|
||
3. 默认自动滚到底；用户手动上滚时暂停自动跟随。
|
||
4. 不允许使用“仅按字符串估算”的粗略光标算法作为最终实现。
|
||
5. 必须模拟 xterm 的 C0/C1 换行语义：`CR`、`LF`、`VT`、`FF`、`NEL`。
|
||
6. 必须显式维护软换行标记（等价 `isWrapped`），区分“自动折行”与“显式换行”。
|
||
|
||
## 9.5 精准光标内核（强制）
|
||
|
||
为满足“回显后光标位置必须精准计算”，实验项目必须引入统一终端状态内核（`TerminalCore`），并将其作为两种渲染模式的唯一真相源。
|
||
|
||
实现要求：
|
||
|
||
1. `stdout/stderr` 必须先写入 `TerminalCore`，由内核解析控制序列并更新光标、屏幕缓冲、滚动区域状态。
|
||
2. `compat` 模式与 `textarea` 模式都必须消费同一份 `TerminalCore` 状态快照。
|
||
3. 禁止直接通过 `selectionStart + 文本长度` 推断“终端光标”，该方法仅可用于“输入框本地插入点”，不能代表远端终端光标。
|
||
4. `TerminalCore` 至少要正确处理本项目目标程序涉及的序列族，按优先级分层：
|
||
- **C0/C1 控制字符**：`CR / LF / VT / FF / NEL / BS / HT / BEL`（BEL 须抛事件，不得静默丢弃）。
|
||
- **光标移动**：`CSI A/B/C/D`（上下左右）、`CSI E/F`（行首上下）、`CSI G`（列绝对）、`CSI H/f`（行列绝对）、`CSI I`（前进 Tab）、`CSI Z`（后退 Tab）。
|
||
- **擦除**：`CSI J / ?J`（擦除显示）、`CSI K / ?K`（擦除行）、`CSI X`（擦除字符）。
|
||
- **行/字符插删（TUI 全屏必需）**：`CSI L`（insertLines）、`CSI M`（deleteLines）、`CSI @`（insertChars）、`CSI P`（deleteChars）、`CSI S`（scrollUp）、`CSI T`（scrollDown）。
|
||
- **滚动区域（TUI 全屏必需）**：`CSI r`（DECSTBM，设置滚动上下边界），与 `DECOM(?6h/l)` 联动。
|
||
- **光标保存/恢复**：`CSI s / u`（ANSI save/restore cursor）；`ESC 7 / ESC 8`（DECSC/DECRC）。
|
||
- **全终端重置**：`ESC c`（RIS，全量重置到初始状态）；`CSI !p`（DECSTR 软重置）。
|
||
- **SGR 属性**：`CSI m`（见 §9.6）。
|
||
- **模式控制**：`SM/RM (Ps=4 insertMode, Ps=20 convertEol)`；`DECSET/DECRST (含 DECAWM ?7, DECTCEM ?25, DECCKM ?1, 备用屏 ?47/?1047/?1049, bracketed paste ?2004)`。
|
||
- **OSC**：`OSC 0/2`（标题，见 §9.9）；其余 OSC 须安全解析并丢弃，不得透传到显示区。
|
||
5. `TerminalCore` 必须维护以下状态：`cursorX/cursorY`、`baseY`、`viewportY`、`scrollTop/scrollBottom`、`convertEol`、`wraparound`、`line.isWrapped`。
|
||
6. 每次输出处理后，必须产出 `cursor: { x, y, globalRow }` 与 `viewport` 快照，供触摸激活带与滚动定位复用。
|
||
|
||
## 9.6 颜色渲染规范（xterm 对齐，强制）
|
||
|
||
目标：
|
||
|
||
1. 颜色与文本属性语义必须对齐 `xterm.js@5.3.0` 的 `SGR(CSI ... m)` 行为。
|
||
2. `compat` 模式与 `textarea` 模式必须共享同一套属性状态机，避免模式切换后颜色跳变。
|
||
|
||
实现边界：
|
||
|
||
1. 必须支持基础 SGR 属性：`0/1/2/3/4/7/8/9/21/22/23/24/25/27/28/29/53/55`。
|
||
2. 必须支持前景/背景标准色：`30-37`、`40-47`。
|
||
3. 必须支持高亮色：`90-97`、`100-107`。
|
||
4. 必须支持扩展色：
|
||
- 前景 `38`
|
||
- 背景 `48`
|
||
- 下划线颜色 `58`
|
||
5. 扩展色子模式必须支持：
|
||
- `;5;INDEX`（256 色索引）
|
||
- `;2;R;G;B`（TrueColor）
|
||
6. 必须支持默认色复位：
|
||
- `39` 复位前景
|
||
- `49` 复位背景
|
||
- `59` 复位下划线颜色
|
||
|
||
颜色状态模型（建议）：
|
||
|
||
1. `fg`: `{ mode: default | p16 | p256 | rgb, value }`
|
||
2. `bg`: `{ mode: default | p16 | p256 | rgb, value }`
|
||
3. `underlineColor`: `{ mode: default | p256 | rgb, value }`
|
||
4. `flags`: `bold/dim/italic/underline/inverse/invisible/strikethrough/overline`
|
||
5. `underlineStyle`: `none/single/double/curly/dotted/dashed`
|
||
|
||
重置纪律：
|
||
|
||
1. `SGR 0` 必须重置前景、背景、下划线样式与颜色到默认（等价 xterm `_processSGR0`）。
|
||
2. `22` 仅取消 `bold` 与 `dim`，不影响颜色。
|
||
3. `24` 仅取消下划线与下划线样式，不清空其它属性。
|
||
4. `27` 仅取消 `inverse`。
|
||
5. `28` 仅取消 `invisible`。
|
||
6. `29` 仅取消删除线。
|
||
|
||
渲染映射规则：
|
||
|
||
1. `inverse` 采用“渲染时交换 fg/bg”策略，不直接改写底层存储值。
|
||
2. `invisible` 保留背景渲染，前景以透明或背景同色处理（与终端“隐藏文字”语义一致）。
|
||
3. `bold` 只作为属性位，不应强行映射为高亮颜色（除非显式启用“粗体映射亮色”策略）。
|
||
4. `blink` 在 xterm 5.3 源码中为已记录属性但渲染支持有限，实验项目默认可不做动画实现，但要保留属性位兼容。
|
||
|
||
主题与调色板约束：
|
||
|
||
1. 16 色与 256 色索引色应来自统一调色板定义，避免 `xterm` 与 `textarea` 调色板不一致。
|
||
2. TrueColor (`rgb`) 必须按原值渲染，不经过主题二次量化。
|
||
3. 主题切换只影响“默认色与索引色映射”，不应篡改已存在的 TrueColor 单元格。
|
||
|
||
## 9.7 主题复用与轻量化策略（强制）
|
||
|
||
目标：
|
||
|
||
1. 主题实现参考并复用现有 Web/小程序成熟方案，保持视觉一致与维护成本可控。
|
||
2. xterm 移植以“核心稳定 + 轻量高效”为优先级，禁止默认堆叠非必要能力。
|
||
|
||
主题复用规则：
|
||
|
||
1. 统一采用语义 token（如 `terminalFg/terminalBg/cursor/selection/ansi16`），禁止在组件内硬编码颜色。
|
||
2. 默认前景/背景与 `ansi16` 从现有主题配置映射生成，避免与现有产品主题出现明显偏差。
|
||
3. 256 色表采用固定映射（标准 xterm256 表），不随业务主题动态重算。
|
||
4. 各端只维护“主题映射层”，不复制跨端整套业务主题逻辑。
|
||
|
||
轻量化规则：
|
||
|
||
1. 不引入 `@xterm/*` 运行时依赖；实现以 `TerminalCore + 自研渲染器` 为主。
|
||
2. 兼容能力按需实现并按模块拆分，首屏仅加载连接、输入、回显、resize 必需逻辑。
|
||
3. 默认使用原生 DOM/Canvas 路径（Web 端）或 WXML 组件（小程序端），禁止引入重型图形加速依赖作为前置条件。
|
||
4. 非核心能力（复杂链接检测、额外动画）默认关闭，确保输入回显路径最短。
|
||
|
||
性能预算（建议）：
|
||
|
||
1. Web 端 JS 增量目标：gzip <= 150KB（超限需说明来源与必要性）。
|
||
2. 终端首屏可输入目标：页面进入后 1 秒内可完成输入与回显（普通开发机基线）。
|
||
3. 持续输出下避免长卡顿：连续主线程阻塞 >100ms 视为性能问题并需定位。
|
||
|
||
降级开关（必须）：
|
||
|
||
1. `compatLiteMode`：关闭可选增强，仅保留连接、输入、回显、resize。
|
||
2. `rendererFallback=textarea`：低端设备或异常场景可一键降级。
|
||
3. 主题映射失败时自动回退默认主题，禁止阻塞会话连接与输入流程。
|
||
|
||
## 9.8 主屏/备用屏落地实现（强制）
|
||
|
||
最小实现步骤：
|
||
|
||
1. 在 `TerminalCore` 新增 `bufferSet = { normal, alternate, active }` 与 `savedCursor`。
|
||
2. 解析 `DECSET/DECRST` 时接入 `47/1047/1049` 分支，不允许只做日志忽略。
|
||
3. `switchToAlternate()`：切换 `active=alternate`，同步 `viewport/baseY/cursor`。
|
||
4. `switchToNormal()`：切换 `active=normal`，恢复主屏可视与滚动位置。
|
||
5. `1049h` 先 `saveCursor()` 再切换；`1049l` 先切回主屏再 `restoreCursor()`。
|
||
6. 渲染器读取统一 `activeBuffer` 快照，禁止自行缓存“上一屏”造成穿透渲染。
|
||
|
||
兼容边界：
|
||
|
||
1. 若目标程序未使用备用屏序列，行为与当前方案完全一致。
|
||
2. 若收到未知私有模式，记录日志并安全忽略，不得破坏当前缓冲状态。
|
||
3. 对于不在首期范围的高级 TUI 能力，可延后，但 `47/1047/1049` 不可缺失。
|
||
|
||
## 9.9 OSC / BEL 处理规范（强制）
|
||
|
||
### BEL（`\x07`）
|
||
|
||
1. `TerminalCore` 必须注册 BEL 执行处理器，检测到后向外抛 `onBell` 事件，不得静默丢弃。
|
||
2. Web 层（`TerminalPage`）可选响应：振动（`navigator.vibrate`）、提示音或弹层，默认静音（但回调链路必须存在）。
|
||
3. 小程序层可通过 `wx.vibrateShort()` 响应 `onBell`；iOS 层可通过 `AudioServicesPlaySystemSound` 响应。
|
||
4. BEL 不得在显示区产生任何可见字符。
|
||
|
||
### OSC 0 / OSC 2（终端标题）
|
||
|
||
1. `TerminalCore` 必须解析 `OSC 0 ; text BEL` 与 `OSC 2 ; text BEL`，提取 `text` 后向外抛 `onTitleChange(title: string)` 事件。
|
||
2. Web 层默认将标题更新到 `TerminalToolbar` 展示区；不强制写入 `document.title`。
|
||
3. OSC 1（icon name）与 OSC 0 处理逻辑相同，`text` 同步抛出，忽略图标语义。
|
||
|
||
### OSC 4 / OSC 10 / OSC 11 / OSC 12（调色盘/默认色动态修改）
|
||
|
||
1. 首期：安全解析序列，忽略颜色写入。
|
||
2. 不得将原始 OSC 序列透传到显示区造成乱码。
|
||
3. 可记录调试日志，供后期审计。
|
||
|
||
### OSC 8（超链接）
|
||
|
||
1. 首期：安全解析并忽略，不渲染为链接。
|
||
2. 不得透传到显示区。
|
||
|
||
### 通用 OSC 兜底规则
|
||
|
||
1. 未命中任何已注册 OSC handler 的序列，必须在解析完成后安全丢弃。
|
||
2. 禁止将 OSC 原始字节写入可视 buffer；解析失败时记录错误日志但不崩溃。
|
||
3. OSC 以 `BEL(\x07)` 或 `ST(\x9C / ESC \\)` 结束，两者均须支持。
|
||
|
||
## 9.10 `TerminalSnapshot` 数据结构与 `TerminalCore` 公开 API（强制）
|
||
|
||
所有渲染器（compat、textarea、小程序 WXML `setData`）均通过 `TerminalCore.snapshot()` 获取渲染数据，以下是完整类型定义：
|
||
|
||
```typescript
|
||
// ── 颜色值 ────────────────────────────────────────────────────────────────
|
||
interface ColorValue {
|
||
mode: 'default' | 'p16' | 'p256' | 'rgb';
|
||
value: number; // p16: 0-15；p256: 0-255；rgb: 0xRRGGBB
|
||
}
|
||
|
||
// ── 单元格 ────────────────────────────────────────────────────────────────
|
||
interface TerminalCell {
|
||
char: string; // 显示字符（空单元格为 ' '）
|
||
width: 1 | 2; // 东亚宽字符占 2 列
|
||
fg: ColorValue;
|
||
bg: ColorValue;
|
||
flags: number; // SGR flags bitmask（bold=1,dim=2,italic=4,underline=8,
|
||
// inverse=16,invisible=32,strikethrough=64,overline=128）
|
||
underlineStyle: 'none' | 'single' | 'double' | 'curly' | 'dotted' | 'dashed';
|
||
underlineColor: ColorValue;
|
||
}
|
||
|
||
// ── 行 ───────────────────────────────────────────────────────────────────
|
||
interface TerminalLine {
|
||
cells: TerminalCell[]; // 长度固定为 cols
|
||
isWrapped: boolean; // 此行为前一行的自动折行续行
|
||
}
|
||
|
||
// ── 光标状态 ──────────────────────────────────────────────────────────────
|
||
interface CursorState {
|
||
x: number; // 列（0-based）
|
||
y: number; // 行（相对 baseY，0-based）
|
||
globalRow: number; // baseY + y（全局行号，供触摸激活带复用）
|
||
visible: boolean; // DECTCEM（CSI ?25h/l）控制
|
||
}
|
||
|
||
// ── 快照（渲染器唯一数据源） ─────────────────────────────────────────────
|
||
interface TerminalSnapshot {
|
||
cols: number;
|
||
rows: number;
|
||
cursor: CursorState;
|
||
lines: TerminalLine[]; // 长度 = rows，仅含当前可视区
|
||
title: string; // 最近 OSC 0/2 设置的标题
|
||
revision: number; // 每次 write() 处理后递增，供渲染器脏检测
|
||
isAlternateBuffer: boolean; // 当前是否为备用屏
|
||
}
|
||
```
|
||
|
||
`TerminalCore` 公开 API（必须实现，不可对外暴露细节方法）：
|
||
|
||
```typescript
|
||
type TerminalCoreEvent = 'bell' | 'titleChange' | 'resize';
|
||
|
||
interface TerminalCoreEventMap {
|
||
bell: void;
|
||
titleChange: string; // 新标题字符串
|
||
resize: { cols: number; rows: number }; // 内部触发的 resize 通知
|
||
}
|
||
|
||
class TerminalCore {
|
||
// 写入 VT 字节流；内部完成序列解析、状态更新、revision 自增
|
||
write(data: string): void;
|
||
|
||
// 全量重置到初始状态（等价 ESC c / RIS）
|
||
reset(): void;
|
||
|
||
// 产出当前可视区快照；调用成本 O(rows*cols)，建议仅在 RAF 回调中调用
|
||
snapshot(): TerminalSnapshot;
|
||
|
||
// 更新终端尺寸（通常由 sizeCalculator 计算后注入）
|
||
resize(cols: number, rows: number): void;
|
||
|
||
// 事件订阅；返回取消订阅函数（调用后立即停止回调）
|
||
on<K extends TerminalCoreEvent>(
|
||
event: K,
|
||
cb: (payload: TerminalCoreEventMap[K]) => void
|
||
): () => void;
|
||
}
|
||
```
|
||
|
||
渲染器实现约束：
|
||
|
||
1. 渲染器**只读** snapshot，禁止回写 `TerminalCore` 内部状态。
|
||
2. 可通过 `revision` 做脏检测，跳过无变化帧的重渲染。
|
||
3. 小程序 `terminal-core-view` 在 `onUpdate` 中调用 `snapshot()` 后执行 `this.setData({ lines, cursor })`，最小化 setData 数据量。
|
||
|
||
## 10. 页面渲染与布局规则
|
||
|
||
## 10.1 基础布局
|
||
|
||
1. 顶部：状态栏（state、latency、mode）。
|
||
2. 中部：终端视口（xterm 或 textarea 输出）。
|
||
3. 底部：输入栏与触摸工具。
|
||
|
||
## 10.2 尺寸与 PTY 计算规则（必须统一）
|
||
|
||
变量：
|
||
|
||
1. `containerInnerWidthPx`
|
||
2. `containerInnerHeightPx`
|
||
3. `charWidthPx`
|
||
4. `lineHeightPx`
|
||
|
||
公式：
|
||
|
||
1. `cols = max(20, floor(containerInnerWidthPx / charWidthPx))`
|
||
2. `rows = max(8, floor(containerInnerHeightPx / lineHeightPx))`
|
||
|
||
约束：
|
||
|
||
1. 变化阈值去抖：`|cols-lastCols| + |rows-lastRows| >= 1` 才发 `resize`。
|
||
2. 初次挂载后至少重试 fit/measure 3~10 次（应对路由切换延迟布局）。
|
||
|
||
## 11. 光标与坐标计算规则（重点）
|
||
|
||
说明：本节区分两类光标，避免语义混淆。
|
||
|
||
1. 终端光标：远端 PTY 回显语义对应的光标（用于激活带判定）。
|
||
2. 输入光标：本地输入框 `selectionStart/selectionEnd`（用于编辑行为）。
|
||
|
||
## 11.1 行高计算
|
||
|
||
优先级：
|
||
|
||
1. 优先取真实渲染行高（DOM 测量）。
|
||
2. 无法测量时回退：`lineHeightPx = fontSize * lineHeight`。
|
||
|
||
## 11.2 触点行号计算
|
||
|
||
1. `localRow = floor((clientY - viewportTop) / rowHeightPx)`
|
||
2. compat 模式：`touchRow = viewportY + localRow`
|
||
3. textarea 模式：`touchRow = viewportTopRow + localRow`
|
||
4. 若 `clientY` 不在视口边界内，判定为无效触点。
|
||
|
||
## 11.3 compat 光标行号
|
||
|
||
1. `cursorLocalRow = core.cursorY`
|
||
2. `cursorBaseRow = core.baseY`
|
||
3. `cursorRow = cursorBaseRow + cursorLocalRow`（全局行号）
|
||
4. 激活带判断：`abs(touchRow - cursorRow) <= activationRadius`（建议 2 行）。
|
||
|
||
## 11.4 textarea 光标位置计算
|
||
|
||
输入（终端光标，来自 `TerminalCore`）：
|
||
|
||
1. `coreCursorRow`
|
||
2. `coreCursorCol`
|
||
3. `viewportTopRow`
|
||
4. `rows`
|
||
|
||
规则：
|
||
|
||
1. `cursorRow = clamp(coreCursorRow, 0, +inf)`。
|
||
2. `cursorVisualRow = cursorRow - viewportTopRow`。
|
||
3. 仅当 `0 <= cursorVisualRow < rows` 时认为光标在当前可视窗口内。
|
||
4. 激活带判断统一使用 `cursorRow`（全局行号），禁止改用输入框 `selectionStart`。
|
||
5. `coreCursorRow` 语义需与 xterm 对齐：`globalRow = baseY + cursorY`。
|
||
|
||
输入（本地输入光标，仅编辑用途）：
|
||
|
||
1. `selectionStart`（光标字符索引）
|
||
2. `text`（当前显示文本）
|
||
3. `cols`（当前列数）
|
||
|
||
算法（必须实现成纯函数）：
|
||
|
||
1. 从 `text[0..selectionStart)` 顺序扫描。
|
||
2. 碰到 `\n`：`row += 1; col = 0`。
|
||
3. 普通字符：`col += charDisplayWidth(ch)`。
|
||
4. 若 `col >= cols`：按自动换行规则折行：`row += floor(col / cols); col = col % cols`。
|
||
|
||
`charDisplayWidth(ch)` 规则：
|
||
|
||
1. ASCII：宽度 1。
|
||
2. CJK/全角：宽度 2（可用简化 east-asian-width 判定）。
|
||
3. 控制字符：宽度 0。
|
||
|
||
## 11.5 坐标到光标索引（可选增强，仅输入框）
|
||
|
||
若需要“点按定位光标”：
|
||
|
||
1. 先由 `(x,y)` 推导目标 `(row,col)`。
|
||
2. 再线性扫描文本映射回最近字符索引。
|
||
3. 时间复杂度 O(n)，长文本需缓存行起始索引优化。
|
||
|
||
## 11.6 原生键盘弹出门控（强制）
|
||
|
||
必须按以下判定顺序执行：
|
||
|
||
1. `sessionState === connected`。
|
||
2. 当前手势动作被状态机判定为 `FOCUS_KEYBOARD`。
|
||
3. `inBand === true`（即 `abs(touchRow - cursorRow) <= activationRadius`）。
|
||
4. 不存在活动原生选区（否则走 `PASS_NATIVE`）。
|
||
|
||
执行动作：
|
||
|
||
1. `readOnly=false`。
|
||
2. `blur -> focus` 顺序触发输入锚点激活。
|
||
3. 进入短保护窗口，防止 iOS 瞬时 blur 立刻收回键盘。
|
||
|
||
禁止动作：
|
||
|
||
1. 非 `inBand` 区域触摸时强制 `focus()`。
|
||
2. `PASS_NATIVE/PASS_SCROLL` 分支触发键盘弹出。
|
||
|
||
## 12. 输入处理规则（必须）
|
||
|
||
## 12.1 统一发送入口
|
||
|
||
1. 所有输入只走 `InputBridge.sendRaw()`。
|
||
2. 键盘 `Enter` 必须映射为 `CR (\r)`（与 xterm `Keyboard.ts` 一致）。
|
||
3. 普通文本输入（keypress/input）按字符原样发送，不做全局换行重写。
|
||
|
||
## 12.2 meta 标记
|
||
|
||
1. 常规按键：`meta.source = "keyboard"`。
|
||
2. 语音/候选提交：`meta.source = "assist"`，可携带 `txnId` 去重。
|
||
|
||
## 12.3 粘贴规则
|
||
|
||
1. 粘贴前执行 xterm 对齐的行结束归一：`/\r?\n/g -> '\r'`。
|
||
2. 若开启 bracketed paste，按 `ESC[200~ + text + ESC[201~` 包裹发送。
|
||
3. 粘贴文本直接写入 stdin，不走逐键模拟。
|
||
|
||
## 12.4 快捷键规则
|
||
|
||
1. `Ctrl/Cmd + C`：有选中则复制；无选中则发 `\u0003`。
|
||
2. `Ctrl/Cmd + V`：读剪贴板后发送。
|
||
3. 方向键默认发送：`ESC[A`/`ESC[B`/`ESC[C`/`ESC[D`；应用光标模式下发送：`ESCOA`/`ESCOB`/`ESCOC`/`ESCOD`。
|
||
|
||
## 12.5 反劫持策略（强制）
|
||
|
||
1. 输入主通道固定为原生 `textarea`，禁止把系统软键盘直接绑定到 xterm 隐藏输入节点。
|
||
2. 兼容层键盘监听仅用于桌面对照模式；移动端默认禁用兼容层直连 stdin 的按键采集。
|
||
3. 触摸事件默认透传，只有 `FOCUS_KEYBOARD` 分支可执行最小化 `preventDefault`。
|
||
4. 原生输入法事件（`compositionstart/update/end`、`beforeinput`）必须完整透传到输入状态机，不得被 xterm 监听提前吞掉。
|
||
5. 发生冲突时遵循优先级：系统行为 > 原生输入通道 > xterm 视图行为。
|
||
|
||
## 12.6 区域过滤与事件归属（强制）
|
||
|
||
区域定义（建议使用 `data-zone` 标记）：
|
||
|
||
1. `terminal-output-zone`：终端可视回显区（仅显示与文本选区）。
|
||
2. `native-input-zone`：原生输入锚点区（软键盘与 IME 主入口）。
|
||
3. `app-control-zone`：应用工具栏、按钮、菜单区。
|
||
4. `app-overlay-zone`：应用弹层、右键菜单、浮层工具区。
|
||
|
||
归属规则：
|
||
|
||
1. 键盘事件默认归 `native-input-zone` 与应用层快捷键系统；xterm 仅消费“已路由到终端”的标准控制输入。
|
||
2. 鼠标点击在 `app-control-zone/app-overlay-zone` 必须 100% 透传应用层，禁止被 xterm 截获。
|
||
3. `wheel/touchmove` 默认交给最近可滚动容器；仅终端主视口滚动时才进入终端滚动链路。
|
||
4. 文本选择相关事件优先给系统原生选区，xterm 不得覆盖浏览器/系统的选区手柄行为。
|
||
|
||
实现约束：
|
||
|
||
1. 在捕获阶段先执行 `eventOwnershipRouter`，返回 `APP | NATIVE | XTERM`，再分发事件。
|
||
2. 未命中白名单事件时默认 `APP`，禁止“默认给 xterm”。
|
||
3. 仅以下事件允许进入 xterm：`stdin` 字符输入、终端方向键控制序列、明确授权的复制粘贴桥接。
|
||
4. 右键菜单、双击词选、三击行选等交互由应用策略统一控制，不由 xterm 内建策略隐式决定。
|
||
|
||
## 13. 关键风险与强约束
|
||
|
||
1. 风险：textarea 模式无法完整支持 TUI 全屏程序。
|
||
约束：文档中明确为已知限制，不作为首期阻塞项。
|
||
2. 风险：IME 双发或丢字。
|
||
约束：保留 `composition + beforeinput/input + fallback` 三层机制和去重窗口。
|
||
3. 风险：移动端误弹键盘。
|
||
约束：触摸状态机按优先级表执行，禁止随意新增 `preventDefault` 分支。
|
||
4. 风险：模式切换导致历史丢失。
|
||
约束：统一 `OutputBuffer`，切换只换渲染器，不换数据源。
|
||
5. 风险：xterm 事件劫持导致软键盘、选区、滚动异常。
|
||
约束：移动端输入以原生 `textarea` 为唯一焦点源，xterm 不持有输入焦点。
|
||
|
||
## 14. 分阶段实施计划（可直接执行）
|
||
|
||
### 阶段 A：核心包骨架与接口
|
||
|
||
1. 建立 `packages/terminal-core` 目录与模块骨架。
|
||
2. 定义并导出 `TerminalTransport`、`RendererAdapter`、`IMeasureAdapter`、`IInputSource` 四个核心接口。
|
||
3. 完成 `sessionMachine + terminalSanitizer + outputBuffer` 骨架。
|
||
4. `tsconfig.json` 配置 `lib: ["esnext"]`，CI 零 DOM typecheck 通过。
|
||
|
||
### 阶段 B：Web 基线（TerminalCore + compatRenderer）
|
||
|
||
1. 实现 `TerminalCore`（VT 仿真内核，含 §9.5 全部序列族）。
|
||
2. `apps/web` 接入 `terminal-core`，实现 `GatewayTransport + compatRenderer + domInputBridge + domMeasureAdapter`。
|
||
3. 跑通 SSH 会话：输入、回显、resize、快捷键、粘贴。
|
||
4. 完成基线测试用例（Enter/CR、convertEol、DECAWM、isWrapped、备用屏、颜色 SGR）。
|
||
|
||
### 阶段 C：textarea 渲染 + iOS 接入
|
||
|
||
1. 实现 `textareaRenderer`，接入 `TerminalCore.snapshot()`，完成 compat ↔ textarea 切换。
|
||
2. 实现 `iosNativeTransport`（Capacitor Bridge），`apps/web` 同一构建产物在 Capacitor 壳中加载。
|
||
3. 补全 `ios/plugin/RemoteConnSSHPlugin` Swift 真实 SSH 接入（替换骨架占位）。
|
||
4. iOS 设备冒烟：vim、htop 基础操作可用。
|
||
|
||
### 阶段 D：微信小程序原生接入
|
||
|
||
1. 实现 `WxTransport`（`wx.connectSocket`）、`wxInputBridge`、`wxMeasureAdapter`。
|
||
2. 实现 `terminal-core-view` WXML 渲染组件，消费 `TerminalCore.snapshot()`。
|
||
3. 小程序开发者工具 + 真机冒烟：vim、nano 基础操作可用。
|
||
|
||
### 阶段 E：全端验收
|
||
|
||
1. 三端（Web / iOS / 小程序）同时跑 vim / htop 冒烟测试（DECSTBM、insertLines/deleteLines、RIS、OSC 标题）。
|
||
2. 性能验收：各端高频输出不明显卡顿。
|
||
3. 删除演练：可单独删除旧版 `apps/web` 终端实现，`terminal-core` 与小程序不受影响；主工程 `typecheck/lint/test/build` 通过。
|
||
|
||
## 15. 测试与验收清单
|
||
|
||
功能验收：
|
||
|
||
1. 连接状态迁移严格符合状态机。
|
||
2. stdout/stderr 能稳定显示，无额外换行污染。
|
||
3. Enter 语义对齐 xterm：按键 Enter 发送 `CR`，不发送裸 `LF`。
|
||
4. 中文输入（含候选提交）无明显丢字/双发。
|
||
5. 模式切换后输出可重放，连接不中断。
|
||
6. 光标精准性：同一份输出流在 `compat` 与 `textarea` 模式下，终端光标 `(row,col)` 一致。
|
||
7. 光标附近弹键盘：仅在光标邻近行轻触触发原生键盘；非邻近行不弹键盘。
|
||
8. 长按选区场景下，键盘不误弹，原生选区与手柄保持可用。
|
||
9. `convertEol=false` 时，`LF` 仅下移不回列 0；`convertEol=true` 时 `LF` 同时回列 0。
|
||
10. `CR` 只回列 0；`NEL` 执行“回列 0 + 下移一行”。
|
||
11. 粘贴文本行结束归一为 `CR`，并在 bracketed paste 模式下正确包裹。
|
||
12. 自动折行与显式换行可区分：软换行行具备 `isWrapped=true` 语义。
|
||
13. 颜色回显一致性：同一输出流在 `compat` 与 `textarea` 模式下，`SGR` 属性（粗体/下划线/反显/隐藏/删除线）渲染结果一致。
|
||
14. 颜色指令完整性：`30-37/40-47/90-97/100-107/38/48/58` 与 `39/49/59/0/22/24/27/28/29` 复位行为符合预期。
|
||
15. 扩展色准确性：`38;5;INDEX`、`48;5;INDEX`、`38;2;R;G;B`、`48;2;R;G;B`、`58;2;R;G;B` 能精准渲染且模式切换后不漂移。
|
||
16. 主题切换约束：切换主题后默认色与索引色生效，历史 TrueColor 单元格颜色值保持不变。
|
||
17. 主题复用一致性：实验页主题映射与现有 Web/小程序基线一致，同主题下无明显色偏。
|
||
18. 轻量化约束：运行时不依赖 `@xterm/*`，未启用增强能力不进入首屏加载链路。
|
||
19. 降级策略有效：`compatLiteMode` 与 `rendererFallback=textarea` 能生效且核心会话稳定。
|
||
20. 原生响应优先：软键盘弹出/收起、长按选区、滚动手势在移动端与普通 `textarea` 行为一致，无明显被劫持现象。
|
||
21. 焦点纪律正确：移动端会话中 `textarea` 始终为输入焦点主体，xterm 不直接持有键盘焦点。
|
||
22. 区域归属正确：`app-control-zone/app-overlay-zone` 的键鼠事件不被 xterm 捕获，应用可独立演进交互逻辑。
|
||
23. 路由兜底正确：未声明事件默认归应用层处理，不出现“事件默认落到 xterm”导致的不可控行为。
|
||
24. 备用屏切换正确：`?1049h` 进入全屏后不污染主屏历史，`?1049l` 退出后恢复原提示符与光标位置。
|
||
25. `47/1047` 兼容正确：切换主/备用屏时两屏内容与滚动状态互不污染。
|
||
26. TUI 滚动区域正确性：`CSI r` 设定滚动边界后，vim/nano 状态栏固定不随内容区滚动，内容区滚动不越界。
|
||
27. RIS/软重置正确性：`ESC c` 后终端恢复干净初始状态，不残留 TUI 程序的绘图内容；`CSI !p` 后属性/模式复位但缓冲内容保留。
|
||
28. BEL/OSC 无乱码：`\x07` 不在显示区产生可见字符；`OSC 0;title\a` 抛出标题事件且显示区无乱码；未知 OSC 序列安全丢弃。
|
||
29. iOS 一致性：iOS Capacitor 壳加载同一 `apps/web` 构建产物，渲染与输入行为与桌面浏览器一致。
|
||
30. 小程序原生可用性：微信小程序端通过 `terminal-core-view` 组件运行，vim / nano 基础操作可用（DECSTBM + insertLines/deleteLines 验证），无 `<web-view>` 嵌套。
|
||
31. DOM 隔离验证：`packages/terminal-core` 在 `--lib esnext`（无 dom lib）的 TypeScript 编译下零错误。
|
||
|
||
性能验收：
|
||
|
||
1. 高频输出不明显卡顿（基线：普通开发机可持续滚动）。
|
||
2. 缓冲裁剪后不出现白屏或大面积闪烁。
|
||
|
||
回归验收：
|
||
|
||
1. 仅新增小程序入口改动；主页面行为一致。
|
||
2. 删除实验目录后，主项目 `typecheck/lint/test/build` 通过。
|
||
|
||
## 16. xterm 源码对照
|
||
|
||
本方案关键规则对应 `xterm.js@5.3.0` 源码：
|
||
|
||
1. `Enter -> CR`：`src/common/input/Keyboard.ts`。
|
||
2. 粘贴换行归一（`/\r?\n/g -> \r`）：`src/browser/Clipboard.ts`。
|
||
3. `LF/VT/FF -> lineFeed`、`CR -> carriageReturn`、`NEL -> nextLine`：`src/common/InputHandler.ts`。
|
||
4. `convertEol` 默认 `false`，且受 `CSI 20 h/l` 控制：`src/common/services/OptionsService.ts` + `InputHandler.ts`。
|
||
5. 自动折行（DECAWM）与 `isWrapped`：`src/common/InputHandler.ts#print`。
|
||
6. 光标全局行号语义（`cursorY` 相对 `baseY`）：`typings/xterm.d.ts` 中 `IBuffer` 定义。
|
||
7. `SGR` 属性解析与颜色扩展（含 `38/48/58`、`39/49/59`、`0/22/24/27/28/29`）：`src/common/InputHandler.ts#charAttributes`。
|
||
8. 主屏/备用屏切换与 `1049` 光标保存恢复：`src/common/InputHandler.ts#setModePrivate` + `resetModePrivate`。
|
||
9. 缓冲区实现与切屏基础结构：`src/common/buffer/BufferSet.ts`。
|
||
10. `CSI L/M`（insertLines/deleteLines）：`src/common/InputHandler.ts#insertLines` + `deleteLines`。
|
||
11. `CSI @/P/X/S/T`（insertChars/deleteChars/eraseChars/scrollUp/scrollDown）：`src/common/InputHandler.ts` 对应同名方法。
|
||
12. `CSI r`（DECSTBM 滚动区域）：`src/common/InputHandler.ts#setScrollRegion`。
|
||
13. `ESC c`（RIS 全量重置）、`CSI !p`（DECSTR 软重置）：`src/common/InputHandler.ts` execute 注册 + `softReset`。
|
||
14. `BEL → bell()`、`OSC 0/1/2 → onTitleChange`：`src/common/InputHandler.ts` execute/OSC handler 注册。
|
||
|
||
## 17. 完成定义（DoD）
|
||
|
||
1. 本文档中的状态机、组件职责、算法规则均已对应到代码模块；`packages/terminal-core` DOM 隔离 CI 检查通过。
|
||
2. 三端（Web / iOS Capacitor / 微信小程序）均可独立开发与验证，且不互相耦合。
|
||
3. 微信小程序端通过原生 WXML 组件接入，不依赖 `<web-view>` 嵌套。
|
||
4. 删除演练通过：可单独删除旧版 `apps/web` 终端实现，`terminal-core`、小程序端、iOS 端均不受影响；主工程 `typecheck/lint/test/build` 通过。
|
||
5. 换行、光标、TUI 必需 CSI 序列（含 DECSTBM/insertLines/deleteLines/RIS）及 OSC/BEL 处理已与 `xterm.js@5.3.0` 源码逐条对齐，并有对应验收用例。
|
||
6. 开发者仅依赖本方案即可按阶段落地实现。
|
||
7. 主屏/备用屏与 `1049` 光标恢复能力已落地并通过验收用例。
|