Files

douboer@gmail.com 3b7c1d558a first commit

2026-03-03 13:23:14 +08:00

52 KiB

Raw Blame History

xterm 移植跨平台终端核心架构方案（2026-03-01）

1. 目标与范围

本方案构建一个生产可用的跨平台终端核心库，将 xterm.js 的 VT 仿真能力移植为独立的、无 DOM 依赖的 TypeScript 包（packages/terminal-core），供 Web 端、iOS 端（Capacitor WKWebView）、微信小程序端三个平台共用，各端仅需实现 Transport 与 Renderer 两个平台边界。

规范基线：

渲染与输入语义以 xterm.js@5.3.0 源码为准。
文档中的换行、回显、光标、粘贴规则均以该版本源码行为校正。
若未来升级 xterm 版本，需先做"规范差异审计"再修改本方案。

目标：

核心包独立：packages/terminal-core 无 DOM 依赖，可在任意 JS Runtime（浏览器/WKWebView/微信小程序逻辑层）中运行。
三端生产可用：Web（Vue SPA）、iOS（Capacitor WKWebView 加载同一 Web 构建产物）、微信小程序（原生 WXML 组件 + 逻辑层复用 terminal-core）。
平台边界最薄：各端只需实现 TerminalTransport（网络层）和 RendererAdapter（渲染层）两个接口，Session/VT 仿真/输入映射全部共用。
SSH 协议外置：SSH 握手与流转发由 apps/gateway（WebSocket）或 iOS 原生插件负责，terminal-core 只处理 PTY stdout/stderr 字节流。
构建/运行可复用：命令约定统一为 dev/build/test/lint/typecheck。

2. 非目标

不在本方案中实现 SSH 协议本身（由 apps/gateway 或 iOS 原生 Swift 插件负责）。
不修改 apps/gateway 的业务协议和转发逻辑。
不改 packages/shared 的现有模型定义。
不实现图片/Sixel/Kitty 图像协议渲染。

2.1 明确不实现的 xterm 能力

以下能力在本方案中确认跳过，遇到相关需求时应主动忽略，不可因"部分实现"引入不稳定行为：

Kitty 键盘协议（CSI =u / >u / <u / ?u，KittyKeyboardFlags）。
Win32InputMode（Windows 伪终端特有输入模式）。
鼠标跟踪模式（?1000 / ?1002 / ?1003 及 onBinary 二进制鼠标上报通道）。
screenReaderMode 及 ARIA 无障碍支持。
Markers / Decorations（registerMarker / registerDecoration）。
Link Provider（registerLinkProvider）。
CharacterJoiner（registerCharacterJoiner / deregisterCharacterJoiner，仅 WebGL 渲染器使用）。
LigaturesAddon / ImageAddon（Sixel/Kitty 图片协议）。
SerializeAddon（终端状态序列化，由 OutputBuffer 承担类似职责）。
Unicode Grapheme Clusters（addon-unicode-graphemes，emoji 字形簇宽度计算）。
DECSCA（字符保护，CSI "q）与 DECRQM（模式查询，CSI $p / ?$p）。
macOptionIsMeta、altClickMovesCursor、rightClickSelectsWord（桌面端特有选项）。
OSC 52（剪贴板写入）、OSC 133（Shell 集成/语义标记）及其它非标 OSC 扩展。
attachCustomKeyEventHandler / attachCustomWheelEventHandler 公开 API（通过 eventOwnershipRouter 统一管理，不暴露此 API）。

3. 独立性与复用规则

3.1 必须满足

packages/terminal-core 不得 import apps/* 的业务模块；apps/* 可单向依赖 terminal-core。
禁止运行时依赖 @xterm/* 包；xterm 仅作为源码语义参考，不作为可执行依赖。
terminal-core 构建产物在零 DOM 环境（微信小程序逻辑层）中可直接运行。
各平台的 Transport / Renderer / InputBridge 实现隔离在各自 apps/ 或平台目录内，不得混用。

3.2 允许复用

依赖版本策略可复用（例如与根工程保持同主版本）。
工程工具可复用（TypeScript、Vite、ESLint、Vitest 配置风格）。
运行方式可复用（统一命令命名，不要求命令实现完全一致）。
主题 token 可复用现有 Web/小程序的成熟定义（颜色变量、语义色分层、主题切换策略），但实现代码保留在各端目录内。

3.3 核心包 DOM 隔离约束（强制）

packages/terminal-core/src/ 内所有文件禁止直接引用 document / window / HTMLElement / Event / Canvas / CanvasRenderingContext2D 等任何 DOM/BOM API。
平台相关的测量（字符宽高、容器尺寸）以 IMeasureAdapter 接口注入；事件来源（键盘/IME/触摸）以 IInputSource 接口注入；terminal-core 只定义接口，不实现。
sizeCalculator 在 core 包内只保留纯算法（给定 px 宽高 → cols/rows），DOM 测量（ResizeObserver）和 wx 测量（wx.createSelectorQuery）各自在 apps/ 中实现并注入。
imeController 在 core 包内只保留 IME 状态机逻辑（idle/composing/commit_pending），compositionstart/end 等 DOM 事件由 Web 层订阅后调用 core 接口；小程序通过 bindinput + isComposing 等效调用同一接口。

CI 中增加以下 typecheck 任务保证零 DOM 泄漏：

tsc -p packages/terminal-core/tsconfig.json --lib esnext --noEmit

4. 目录规划（实施级）

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 直接运行，需要以下构建策略：

packages/terminal-core/package.json 增加 "miniprogram": "dist-miniprogram/index.js" 字段，提供预编译纯 JS CommonJS 产物。
对应构建命令：tsc -p packages/terminal-core/tsconfig.json --module commonjs --outDir packages/terminal-core/dist-miniprogram，产物为零 DOM 纯 JS，可直接被小程序 require()。
apps/miniprogram/utils/wxTransport.js 等文件通过相对路径引用：require('../../../packages/terminal-core/dist-miniprogram/index')。
CI 中小程序相关构建步骤之前，必须先完成 terminal-core 构建（根 package.json scripts 中保证 workspaces 构建顺序，或通过 prebuild 钩子）。
源码变更后必须重建 dist-miniprogram；禁止小程序逻辑层直接 require TypeScript 源文件。

5. 总体架构与数据流

┌────────────── 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)│
└─────────────────────────────┘

关键原则：

传输层不感知渲染器类型；渲染器不感知传输层。
输入处理统一走 InputBridge（键序列映射逻辑），事件来源由各平台的 IInputSource 实现注入。
渲染器通过统一 RendererAdapter 接口实现，支持 compat/textarea 切换和跨端适配。
输入映射遵循 xterm 规则：Enter -> CR，粘贴文本行结束归一到 CR。
输出渲染遵循 xterm 控制字符纪律：CR 与 LF 分离语义，convertEol 默认 false。
原生响应优先：软键盘、选区、滚动由原生通道（Web textarea / 小程序 input）主导，不得被 terminal-core 接管。
事件主权清晰：键盘/触摸事件先由应用层做区域过滤与路由，再决定是否进入终端输入链路。

6. 状态机规划

6.1 会话状态机（连接生命周期）

状态集合（与现有模型对齐）：

idle
connecting
auth_pending
connected
reconnecting
disconnected
error

合法迁移（必须在 sessionMachine.ts 中强校验）：

idle -> connecting | disconnected
connecting -> auth_pending | error | disconnected
auth_pending -> connected | error | disconnected
connected -> reconnecting | disconnected | error
reconnecting -> connected | error | disconnected
disconnected -> connecting | idle
error -> connecting | disconnected

触发事件：

connect_request
socket_open
connected_frame
stdout_first_packet
disconnect_frame/ws_close
error_frame/ws_error
manual_disconnect
auto_reconnect_timeout

6.2 输入状态机（IME/普通输入）

状态：

input_idle
input_composing
input_commit_pending

规则：

compositionstart -> input_composing
compositionend -> 进入 input_commit_pending，提交非 ASCII 候选
beforeinput/input 非组合态可触发 ASCII 兜底发送
超时守卫（如 1.8s）未收到 compositionend 时自动恢复到 input_idle

6.3 触摸焦点状态机（移动端）

动作集合：

BLUR_ONLY
FOCUS_KEYBOARD
PASS_NATIVE
PASS_SCROLL

决策优先级：

hasSelectionStart || hasSelectionEnd -> PASS_NATIVE
scrollLike -> PASS_SCROLL
moved -> PASS_NATIVE
!inBand -> BLUR_ONLY
inBand -> FOCUS_KEYBOARD

硬约束（新增）：

只有 FOCUS_KEYBOARD 动作允许触发原生键盘弹出。
FOCUS_KEYBOARD 必须满足“光标附近行”条件（inBand=true），禁止在非光标邻近区域弹键盘。
PASS_NATIVE/PASS_SCROLL 禁止 preventDefault，确保原生选区和滚动不被破坏。
禁止在终端根容器上全局拦截 touchstart/touchmove/click；仅允许在明确手势分支下做最小拦截。
移动端 compat 仅承担回显渲染，输入焦点必须由原生 textarea 锚点持有。
禁止在非用户手势路径下调用 terminal.focus() 触发软键盘。

6.4 渲染模式状态机

状态：

renderer_compat
renderer_textarea

切换事件：

switch_to_compat
switch_to_textarea

切换过程必须原子化：

oldRenderer.dispose()
newRenderer.mount(container)
replay buffer
apply size/theme
focus restore（仅桌面自动聚焦）

6.5 换行模式状态（xterm 对齐）

状态：

convertEol=false（默认）
convertEol=true（由 CSI 20 h 打开）

规则：

LF/VT/FF 进入 lineFeed()：始终 y+1，并在触底时滚屏。
convertEol=true 时，lineFeed() 额外执行 x=0；false 时保留列位置。
CR 仅执行 x=0，不改变 y。
NEL（ESC E / C1.NEL）等价 x=0 + index()（下移一行并在必要时滚屏）。
右边界写入是否自动折行由 DECAWM(wraparound) 控制。
自动折行触发条件按 xterm 口径：字符写入将越过末列时触发换行；换行行需标记 isWrapped=true。
显式 LF 后目标行应清除 isWrapped，避免把硬换行误判为软换行。

6.6 屏幕缓冲状态（主屏/备用屏，强制）

状态：

buffer_normal（主屏）
buffer_alternate（备用屏）

切换规则（xterm 对齐）：

CSI ? 47 h / CSI ? 1047 h：切换到备用屏。
CSI ? 47 l / CSI ? 1047 l：返回主屏。
CSI ? 1049 h：保存光标状态并切换到备用屏。
CSI ? 1049 l：返回主屏并恢复保存光标状态。
对齐 xterm.js@5.3.0 现实行为：1049 不强制清空备用屏历史（按源码注释口径处理）。

实现约束：

TerminalCore 必须同时维护 normalBuffer 与 alternateBuffer，仅一个为 activeBuffer。
两个缓冲区的 cursor、scroll region、isWrapped 状态独立维护，禁止互相污染。
切屏仅切换活动缓冲区引用，不得重建对象导致历史丢失。
1049 路径必须包含 saveCursor/restoreCursor，并保证退出全屏后提示符位置正确。
该能力只影响输出缓冲与光标状态，不改变“原生输入主通道”与事件归属策略。

7. 组件职责与接口

7.1 `TerminalPage.vue`

职责：

页面编排、模式切换、连接/断开、状态展示。
组装 store + renderer + inputBridge。

7.2 `TerminalViewport.vue`

职责：

只负责承载渲染容器（不直连 transport）。
提供挂载点给 RendererAdapter。

7.3 `TerminalInputBar.vue`

职责：

文本输入框、发送按钮、粘贴、快捷键入口。
通过 InputBridge.send() 发送，不直接访问 transport。

7.4 `TerminalToolbar.vue`

职责：

展示连接状态、延迟、渲染模式。
触发 connect/disconnect/clear/switchRenderer。

7.5 `TerminalTouchTools.vue`

职责：

方向键、Enter、Ctrl+C、Tab、Paste。
输出标准控制序列（如 ESC[A）。

8. 传输与协议实现要点

8.1 四个核心平台接口（TypeScript 签名）

以下接口定义于 packages/terminal-core/src/ 内，各端必须严格实现，不得扩展签名。

// ── 会话状态（§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 传输。

// ── 入站帧（客户端 → 网关） ──────────────────────────────────────────────
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';   // 服务端内部错误

约束：

data 字段统一为 UTF-8 字符串；二进制内容须 Base64 编码后传输。
txnId 为可选幂等键，网关对相同 txnId 的 stdin 帧去重。
协议版本通过 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`	微信小程序原生

约束：

三端帧协议完全一致（8.2 定义），Transport 实现只替换网络层 API，不改协议语义。
IosNativeTransport 通过 Capacitor Bridge 调用 Swift 插件（connect/send/resize/disconnect 四方法 + addListener 事件推送）；Swift 层须完成真实 SSH 接入（当前为骨架）。
WxTransport 的 wx.connectSocket 在小程序逻辑层运行，帧收发逻辑与 GatewayTransport 对称实现。

9. 渲染管线设计

9.1 输出处理链

收到 stdout/stderr。
执行 sanitizeTerminalOutput（过滤同步更新模式等控制序列噪音）。
追加到 OutputBuffer（条目上限 + 字节上限双阈值）。
outputRevision++。
渲染器增量写入；必要时重放。

9.2 缓冲策略（必须）

maxEntries 下限保护（建议 >= 200）。
maxBytes 下限保护（建议 >= 64KB）。
先按条目裁剪，再按字节裁剪。
至少保留最新一条，避免全清空闪烁。

9.3 兼容渲染规则（自研）

使用 write() 增量写入，不用 writeln() 改写换行语义。
convertEol 默认值必须为 false（与 xterm 默认一致）。
显式 LF 不等于 CRLF：CR 和 LF 分别处理，禁止业务层自行合并。
fit 后同步 resize(cols, rows)。

9.4 textarea 渲染规则

采用“只读显示区 + 输入区”或“单 textarea 双模式”方案（二选一，建议前者）。
输出区按文本流追加，必要时使用 requestAnimationFrame 批量刷新。
默认自动滚到底；用户手动上滚时暂停自动跟随。
不允许使用“仅按字符串估算”的粗略光标算法作为最终实现。
必须模拟 xterm 的 C0/C1 换行语义：CR、LF、VT、FF、NEL。
必须显式维护软换行标记（等价 isWrapped），区分“自动折行”与“显式换行”。

9.5 精准光标内核（强制）

为满足“回显后光标位置必须精准计算”，实验项目必须引入统一终端状态内核（TerminalCore），并将其作为两种渲染模式的唯一真相源。

实现要求：

stdout/stderr 必须先写入 TerminalCore，由内核解析控制序列并更新光标、屏幕缓冲、滚动区域状态。
compat 模式与 textarea 模式都必须消费同一份 TerminalCore 状态快照。
禁止直接通过 selectionStart + 文本长度 推断“终端光标”，该方法仅可用于“输入框本地插入点”，不能代表远端终端光标。
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 须安全解析并丢弃，不得透传到显示区。
TerminalCore 必须维护以下状态：cursorX/cursorY、baseY、viewportY、scrollTop/scrollBottom、convertEol、wraparound、line.isWrapped。
每次输出处理后，必须产出 cursor: { x, y, globalRow } 与 viewport 快照，供触摸激活带与滚动定位复用。

9.6 颜色渲染规范（xterm 对齐，强制）

目标：

颜色与文本属性语义必须对齐 xterm.js@5.3.0 的 SGR(CSI ... m) 行为。
compat 模式与 textarea 模式必须共享同一套属性状态机，避免模式切换后颜色跳变。

实现边界：

必须支持基础 SGR 属性：0/1/2/3/4/7/8/9/21/22/23/24/25/27/28/29/53/55。
必须支持前景/背景标准色：30-37、40-47。
必须支持高亮色：90-97、100-107。
必须支持扩展色：
- 前景 38
- 背景 48
- 下划线颜色 58
扩展色子模式必须支持：
- ;5;INDEX（256 色索引）
- ;2;R;G;B（TrueColor）
必须支持默认色复位：
- 39 复位前景
- 49 复位背景
- 59 复位下划线颜色

颜色状态模型（建议）：

fg: { mode: default | p16 | p256 | rgb, value }
bg: { mode: default | p16 | p256 | rgb, value }
underlineColor: { mode: default | p256 | rgb, value }
flags: bold/dim/italic/underline/inverse/invisible/strikethrough/overline
underlineStyle: none/single/double/curly/dotted/dashed

重置纪律：

SGR 0 必须重置前景、背景、下划线样式与颜色到默认（等价 xterm _processSGR0）。
22 仅取消 bold 与 dim，不影响颜色。
24 仅取消下划线与下划线样式，不清空其它属性。
27 仅取消 inverse。
28 仅取消 invisible。
29 仅取消删除线。

渲染映射规则：

inverse 采用“渲染时交换 fg/bg”策略，不直接改写底层存储值。
invisible 保留背景渲染，前景以透明或背景同色处理（与终端“隐藏文字”语义一致）。
bold 只作为属性位，不应强行映射为高亮颜色（除非显式启用“粗体映射亮色”策略）。
blink 在 xterm 5.3 源码中为已记录属性但渲染支持有限，实验项目默认可不做动画实现，但要保留属性位兼容。

主题与调色板约束：

16 色与 256 色索引色应来自统一调色板定义，避免 xterm 与 textarea 调色板不一致。
TrueColor (rgb) 必须按原值渲染，不经过主题二次量化。
主题切换只影响“默认色与索引色映射”，不应篡改已存在的 TrueColor 单元格。

9.7 主题复用与轻量化策略（强制）

目标：

主题实现参考并复用现有 Web/小程序成熟方案，保持视觉一致与维护成本可控。
xterm 移植以“核心稳定 + 轻量高效”为优先级，禁止默认堆叠非必要能力。

主题复用规则：

统一采用语义 token（如 terminalFg/terminalBg/cursor/selection/ansi16），禁止在组件内硬编码颜色。
默认前景/背景与 ansi16 从现有主题配置映射生成，避免与现有产品主题出现明显偏差。
256 色表采用固定映射（标准 xterm256 表），不随业务主题动态重算。
各端只维护“主题映射层”，不复制跨端整套业务主题逻辑。

轻量化规则：

不引入 @xterm/* 运行时依赖；实现以 TerminalCore + 自研渲染器 为主。
兼容能力按需实现并按模块拆分，首屏仅加载连接、输入、回显、resize 必需逻辑。
默认使用原生 DOM/Canvas 路径（Web 端）或 WXML 组件（小程序端），禁止引入重型图形加速依赖作为前置条件。
非核心能力（复杂链接检测、额外动画）默认关闭，确保输入回显路径最短。

性能预算（建议）：

Web 端 JS 增量目标：gzip <= 150KB（超限需说明来源与必要性）。
终端首屏可输入目标：页面进入后 1 秒内可完成输入与回显（普通开发机基线）。
持续输出下避免长卡顿：连续主线程阻塞 >100ms 视为性能问题并需定位。

降级开关（必须）：

compatLiteMode：关闭可选增强，仅保留连接、输入、回显、resize。
rendererFallback=textarea：低端设备或异常场景可一键降级。
主题映射失败时自动回退默认主题，禁止阻塞会话连接与输入流程。

9.8 主屏/备用屏落地实现（强制）

最小实现步骤：

在 TerminalCore 新增 bufferSet = { normal, alternate, active } 与 savedCursor。
解析 DECSET/DECRST 时接入 47/1047/1049 分支，不允许只做日志忽略。
switchToAlternate()：切换 active=alternate，同步 viewport/baseY/cursor。
switchToNormal()：切换 active=normal，恢复主屏可视与滚动位置。
1049h 先 saveCursor() 再切换；1049l 先切回主屏再 restoreCursor()。
渲染器读取统一 activeBuffer 快照，禁止自行缓存“上一屏”造成穿透渲染。

兼容边界：

若目标程序未使用备用屏序列，行为与当前方案完全一致。
若收到未知私有模式，记录日志并安全忽略，不得破坏当前缓冲状态。
对于不在首期范围的高级 TUI 能力，可延后，但 47/1047/1049 不可缺失。

9.9 OSC / BEL 处理规范（强制）

BEL（`\x07`）

TerminalCore 必须注册 BEL 执行处理器，检测到后向外抛 onBell 事件，不得静默丢弃。
Web 层（TerminalPage）可选响应：振动（navigator.vibrate）、提示音或弹层，默认静音（但回调链路必须存在）。
小程序层可通过 wx.vibrateShort() 响应 onBell；iOS 层可通过 AudioServicesPlaySystemSound 响应。
BEL 不得在显示区产生任何可见字符。

OSC 0 / OSC 2（终端标题）

TerminalCore 必须解析 OSC 0 ; text BEL 与 OSC 2 ; text BEL，提取 text 后向外抛 onTitleChange(title: string) 事件。
Web 层默认将标题更新到 TerminalToolbar 展示区；不强制写入 document.title。
OSC 1（icon name）与 OSC 0 处理逻辑相同，text 同步抛出，忽略图标语义。

OSC 4 / OSC 10 / OSC 11 / OSC 12（调色盘/默认色动态修改）

首期：安全解析序列，忽略颜色写入。
不得将原始 OSC 序列透传到显示区造成乱码。
可记录调试日志，供后期审计。

OSC 8（超链接）

首期：安全解析并忽略，不渲染为链接。
不得透传到显示区。

通用 OSC 兜底规则

未命中任何已注册 OSC handler 的序列，必须在解析完成后安全丢弃。
禁止将 OSC 原始字节写入可视 buffer；解析失败时记录错误日志但不崩溃。
OSC 以 BEL(\x07) 或 ST(\x9C / ESC \\) 结束，两者均须支持。

9.10 `TerminalSnapshot` 数据结构与 `TerminalCore` 公开 API（强制）

所有渲染器（compat、textarea、小程序 WXML setData）均通过 TerminalCore.snapshot() 获取渲染数据，以下是完整类型定义：

// ── 颜色值 ────────────────────────────────────────────────────────────────
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（必须实现，不可对外暴露细节方法）：

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;
}

渲染器实现约束：

渲染器只读 snapshot，禁止回写 TerminalCore 内部状态。
可通过 revision 做脏检测，跳过无变化帧的重渲染。
小程序 terminal-core-view 在 onUpdate 中调用 snapshot() 后执行 this.setData({ lines, cursor })，最小化 setData 数据量。

10. 页面渲染与布局规则

10.1 基础布局

顶部：状态栏（state、latency、mode）。
中部：终端视口（xterm 或 textarea 输出）。
底部：输入栏与触摸工具。

10.2 尺寸与 PTY 计算规则（必须统一）

变量：

containerInnerWidthPx
containerInnerHeightPx
charWidthPx
lineHeightPx

公式：

cols = max(20, floor(containerInnerWidthPx / charWidthPx))
rows = max(8, floor(containerInnerHeightPx / lineHeightPx))

约束：

变化阈值去抖：|cols-lastCols| + |rows-lastRows| >= 1 才发 resize。
初次挂载后至少重试 fit/measure 3~10 次（应对路由切换延迟布局）。

11. 光标与坐标计算规则（重点）

说明：本节区分两类光标，避免语义混淆。

终端光标：远端 PTY 回显语义对应的光标（用于激活带判定）。
输入光标：本地输入框 selectionStart/selectionEnd（用于编辑行为）。

11.1 行高计算

优先级：

优先取真实渲染行高（DOM 测量）。
无法测量时回退：lineHeightPx = fontSize * lineHeight。

11.2 触点行号计算

localRow = floor((clientY - viewportTop) / rowHeightPx)
compat 模式：touchRow = viewportY + localRow
textarea 模式：touchRow = viewportTopRow + localRow
若 clientY 不在视口边界内，判定为无效触点。

11.3 compat 光标行号

cursorLocalRow = core.cursorY
cursorBaseRow = core.baseY
cursorRow = cursorBaseRow + cursorLocalRow（全局行号）
激活带判断：abs(touchRow - cursorRow) <= activationRadius（建议 2 行）。

11.4 textarea 光标位置计算

输入（终端光标，来自 TerminalCore）：

coreCursorRow
coreCursorCol
viewportTopRow
rows

规则：

cursorRow = clamp(coreCursorRow, 0, +inf)。
cursorVisualRow = cursorRow - viewportTopRow。
仅当 0 <= cursorVisualRow < rows 时认为光标在当前可视窗口内。
激活带判断统一使用 cursorRow（全局行号），禁止改用输入框 selectionStart。
coreCursorRow 语义需与 xterm 对齐：globalRow = baseY + cursorY。

输入（本地输入光标，仅编辑用途）：

selectionStart（光标字符索引）
text（当前显示文本）
cols（当前列数）

算法（必须实现成纯函数）：

从 text[0..selectionStart) 顺序扫描。
碰到 \n：row += 1; col = 0。
普通字符：col += charDisplayWidth(ch)。
若 col >= cols：按自动换行规则折行：row += floor(col / cols); col = col % cols。

charDisplayWidth(ch) 规则：

ASCII：宽度 1。
CJK/全角：宽度 2（可用简化 east-asian-width 判定）。
控制字符：宽度 0。

11.5 坐标到光标索引（可选增强，仅输入框）

若需要“点按定位光标”：

先由 (x,y) 推导目标 (row,col)。
再线性扫描文本映射回最近字符索引。
时间复杂度 O(n)，长文本需缓存行起始索引优化。

11.6 原生键盘弹出门控（强制）

必须按以下判定顺序执行：

sessionState === connected。
当前手势动作被状态机判定为 FOCUS_KEYBOARD。
inBand === true（即 abs(touchRow - cursorRow) <= activationRadius）。
不存在活动原生选区（否则走 PASS_NATIVE）。

执行动作：

readOnly=false。
blur -> focus 顺序触发输入锚点激活。
进入短保护窗口，防止 iOS 瞬时 blur 立刻收回键盘。

禁止动作：

非 inBand 区域触摸时强制 focus()。
PASS_NATIVE/PASS_SCROLL 分支触发键盘弹出。

12. 输入处理规则（必须）

12.1 统一发送入口

所有输入只走 InputBridge.sendRaw()。
键盘 Enter 必须映射为 CR (\r)（与 xterm Keyboard.ts 一致）。
普通文本输入（keypress/input）按字符原样发送，不做全局换行重写。

12.2 meta 标记

常规按键：meta.source = "keyboard"。
语音/候选提交：meta.source = "assist"，可携带 txnId 去重。

12.3 粘贴规则

粘贴前执行 xterm 对齐的行结束归一：/\r?\n/g -> '\r'。
若开启 bracketed paste，按 ESC[200~ + text + ESC[201~ 包裹发送。
粘贴文本直接写入 stdin，不走逐键模拟。

12.4 快捷键规则

Ctrl/Cmd + C：有选中则复制；无选中则发 \u0003。
Ctrl/Cmd + V：读剪贴板后发送。
方向键默认发送：ESC[A/ESC[B/ESC[C/ESC[D；应用光标模式下发送：ESCOA/ESCOB/ESCOC/ESCOD。

12.5 反劫持策略（强制）

输入主通道固定为原生 textarea，禁止把系统软键盘直接绑定到 xterm 隐藏输入节点。
兼容层键盘监听仅用于桌面对照模式；移动端默认禁用兼容层直连 stdin 的按键采集。
触摸事件默认透传，只有 FOCUS_KEYBOARD 分支可执行最小化 preventDefault。
原生输入法事件（compositionstart/update/end、beforeinput）必须完整透传到输入状态机，不得被 xterm 监听提前吞掉。
发生冲突时遵循优先级：系统行为 > 原生输入通道 > xterm 视图行为。

12.6 区域过滤与事件归属（强制）

区域定义（建议使用 data-zone 标记）：

terminal-output-zone：终端可视回显区（仅显示与文本选区）。
native-input-zone：原生输入锚点区（软键盘与 IME 主入口）。
app-control-zone：应用工具栏、按钮、菜单区。
app-overlay-zone：应用弹层、右键菜单、浮层工具区。

归属规则：

键盘事件默认归 native-input-zone 与应用层快捷键系统；xterm 仅消费“已路由到终端”的标准控制输入。
鼠标点击在 app-control-zone/app-overlay-zone 必须 100% 透传应用层，禁止被 xterm 截获。
wheel/touchmove 默认交给最近可滚动容器；仅终端主视口滚动时才进入终端滚动链路。
文本选择相关事件优先给系统原生选区，xterm 不得覆盖浏览器/系统的选区手柄行为。