xterm.js（@xterm/xterm）是一个运行在浏览器或 Electron 中的全功能终端模拟器。它本身不是 shell，必须连接后端进程（例如通过 node-pty + WebSocket）才能执行命令。
【安装】 使用 npm install @xterm/xterm 安装核心包，按需安装官方插件：@xterm/addon-fit、@xterm/addon-attach、@xterm/addon-web-links、@xterm/addon-search、@xterm/addon-webgl、@xterm/addon-clipboard、@xterm/addon-web-fonts、@xterm/addon-unicode11。必须引入 CSS：<link rel="stylesheet" href="node_modules/@xterm/xterm/css/xterm.css" />，或在 JS/TS 中 import '@xterm/xterm/css/xterm.css'。
【基础用法】 通过 new Terminal({ cols, rows, cursorBlink, scrollback, fontFamily, fontSize, theme }) 创建实例，调用 term.open(element) 挂载。关键点：必须在元素已进入 DOM 后再调用 open；直接写入换行时使用 \r\n 而非仅 \n。
【官方插件】 FitAddon 让终端尺寸适配容器；AttachAddon 连接 WebSocket 后端；SearchAddon 提供终端内文本搜索；WebglAddon 提供 GPU 加速的 WebGL2 渲染；WebLinksAddon 使 URL 可点击；ClipboardAddon 集成浏览器剪贴板；WebFontsAddon 等待网页字体加载后再渲染；Unicode11Addon 支持 Unicode 11 字符宽度；LigaturesAddon 提供字体连字支持（随 Canvas 渲染器移除已弃用，建议改用 WebGL + 字体特性）。插件通过 term.loadAddon() 加载，WebGL 需在 open() 之后加载并处理回退。
【响应式尺寸】 FitAddon 根据容器像素尺寸调整 cols/rows，可用 ResizeObserver 监听容器变化。容器必须有明确的 CSS 宽高，否则 fit() 返回 undefined。
【后端集成】 前端可用 AttachAddon 连接 WebSocket，并通过 term.onResize 同步终端尺寸到服务端。后端可用 Node.js + node-pty 生成 shell（Windows 用 powershell.exe，其他平台用 bash），将 PTY 数据发送到 WebSocket，并处理 resize 消息。简单双向场景下 AttachAddon 自动完成管道，自定义协议才需手动 term.onData / pty.onData 接线。
【主题与按键】 通过 ITheme 对象在构造时或运行时设置主题（背景、前景、光标、选区及 16 色等）。使用 term.attachCustomKeyEventHandler 拦截按键，返回 false 阻止、true 放行。
【搜索、标记与解析器】 SearchAddon 支持 findNext/findPrevious 及正则、全词、大小写、增量、装饰等选项。term.registerMarker 与 term.registerDecoration 可添加标记和装饰。term.parser.registerOscHandler 与 registerCsiHandler 可注册自定义控制序列处理器。
【React 集成】 在 useEffect 中创建 Terminal 与 FitAddon，open 后 fit，并用 ResizeObserver 监听容器；清理时断开观察并调用 term.dispose()。
【常见陷阱】 终端空白或尺寸错误通常因 fit 在 DOM 绘制前调用；字符宽度异常需加载 Unicode11Addon 并设置 term.unicode.activeVersion = '11'；退格失效需检查 PTY 连接与转义；复制粘贴受浏览器安全限制，需 ClipboardAddon 且运行于 HTTPS 或 localhost；WebGL 上下文丢失需 onContextLoss 回退；终端未填满容器通常是容器无高度；\n 缺少 \r 会导致阶梯状输出，可用 \r\n 或 convertEol: true。
【关键选项】 包括 cols、rows、cursorBlink、cursorStyle、scrollback、tabStopWidth、convertEol、disableStdin、allowProposedApi、allowTransparency、windowsPty、macOptionIsMeta、rightClickSelectsWord、fontSize、fontFamily、fontWeight、fontWeightBold、lineHeight、letterSpacing、logLevel 等。
【高性能数据处理】 高吞吐后端（LLM、构建工具、日志流）下需处理 UTF-8 边界（维护剩余缓冲重组多字节序列）、避免每个 PTY 数据块同步 React 状态、用 requestAnimationFrame 提取终端状态、不在活跃输出时调用 term.refresh()。快速输出时可通过隐藏光标加防抖恢复避免光标闪烁。读取正确缓冲行应使用 buffer.baseY + buffer.cursorY。小地图、书签、行计数等昂贵 UI 更新需节流。
【流拦截与 ANSI 操作】 Windows ConPTY 会破坏补充平面字符（emoji），需在传入前剥离或替换；shell 解析为 .cmd/.bat 时需注意 cmd.exe 元字符注入，使用特定引号规则。粘贴文本需过滤终端控制字符并阻止原生粘贴事件以防双重粘贴。替换或过滤后端输出（如启动横幅）可缓冲初始输出至已知分隔符后替换，并在清屏事件时重新激活拦截。优先使用 HTML 覆盖层而非内联 ANSI 操作。
【浏览器兼容与 WebGL 容错】 初始化时切勿对容器使用 display: none，应使用 visibility: hidden 或仅在可见时挂载。系统休眠后 WebGL 上下文可能静默失效，建议采用插件回调、DOM 事件、周期性健康检查三层检测并自动回退到 canvas 渲染器。切换标签页时应将 fit 推迟到下一个 requestAnimationFrame。需节流 resize 事件并在新进程启动后重置 PTY 尺寸跟踪。
【视口虚拟化与坐标转换】 注入后端 PTY 不知道的自定义内容（横幅、状态栏）时，绝对光标定位（CUP 序列）会失效。可采用“坐标欺骗”：向 PTY 发送尺寸时减去注入行偏移并设最小值，用流中间件拦截 CUP 序列并加回偏移。偏移量应从实际内容尺寸推导而非硬编码。
【资源释放】 始终调用 term.dispose() 释放终端及所有插件，也可单独释放 fitAddon、marker、decoration，防止内存泄漏。
参考：API 文档 https://xtermjs.org/docs/api/terminal/classes/terminal/ ，插件文档 https://xtermjs.org/docs/guides/using-addons 。