WezTerm 是上游一款用 Rust 写的终端模拟器与多路复用器,它的立足点是接管一个真实的 pty、把子进程的字节流解释成屏幕。鸿蒙 PC 的 Electron 适配层既没有 pty 也没有 child_process 的可用落地路径,于是这套壳做了一个反直觉的选择:不去假装能起真实 shell,而是把终端的四个零件——VT 解析器、屏幕网格、窗格树、命令解释器——全部用纯 JavaScript 重新写一遍,跑在应用沙箱里的内存文件系统上。壳内一共 19 个源文件 5539 行 175272 字节,其中七个纯函数引擎占 3296 行 100866 字节;产物 195348900 字节,四份原生库吃掉 174100264 字节。

本文严格按仓库里的真实代码展开,讲清楚三件事:为什么把终端引擎放在主进程而不是渲染层;为什么颜色只存 16 个索引而不是存 RGB;为什么窗格树要做成不可变的。同时把缺陷与限制摆在明处:本壳没有 pty、没有 SSH、没有串口,49 条内置命令是解释器而不是系统调用,光标不闪烁是因为鸿蒙渲染层禁掉了 CSS 动画。所有数字都来自当前工程文件与构建日志,没有一项是估出来的。

欢迎加入开源鸿蒙 PC 社区:https://harmonypc.csdn.net/

欢迎在 PC 社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper

AtomGit 仓库地址:https://atomgit.com/OpenHarmonyPCDeveloper/ohos_WezTerm

说明:文中代码包含源码节选;省略标记以注释表示,未展示完整函数、循环或条件分支的片段需要结合原始上下文阅读,不能独立运行。

一、技术架构分析

1.1 能力边界:先承认没有 pty,再谈终端

上游 WezTerm 的启动链路很短:开一个窗口,spawn 一个 shell,拿到 pty 的主端文件描述符,把从属端接到子进程上,然后把主端读到的字节流喂给 VT 解析器。这四步里,第一、二、四步在鸿蒙的 Electron 壳里都成立,唯独第三步不成立——应用沙箱里没有可用的 pty 设备节点,也没有可以 fork 的入口。这不是配置问题,是权限模型和进程模型的双重限制。

很多同类项目在这一步会选择「降级」:留一个假光标,让用户以为在打字,后台什么都不做。这套壳没有这么干。它把边界写进了三处互相独立的位置,让用户在任何一处都能看见真实能力。

第一处是主进程的边界清单,在 main.js 的 boundaryList 函数里,六条原文逐字如下:

function boundaryList() {
  return [
    '没有 pty 也没有子进程:鸿蒙 Electron 壳里起不了真实 shell,命令全部在内置解释器上执行',
    '只认 upstream Lua 配置的子集:config.字段 = 值(字符串/数字/布尔/单层表),不执行任意 Lua',
    '没有 SSH、串口、多路复用域:壳里没有对应的 socket 与设备能力',
    '256 色与真彩色按 xterm 调色板量化到 16 个 ANSI 槽,主题只覆盖 16 色',
    '光标不闪烁:鸿蒙渲染层禁止 CSS animation / transition',
    '内置解释器不是完整 POSIX shell:无作业控制,重定向只支持文件,不支持管道到设备'
  ];
}

第二处是主进程文件头的能力边界注释,和上面六条一一对应,只是换成了对开发者的口吻:

/* 能力边界(界面上也照实写,不做假实现):
 *   - 没有 pty、没有子进程:鸿蒙 Electron 壳里起不了真实 shell,所有命令都在
 *     内置解释器 + 内存文件系统上执行;
 *   - 只认 upstream Lua 配置的一小段子集(config.字段 = 值);
 *   - 没有 SSH / 串口 / 多路复用域:壳里没有对应的 socket 与设备能力;
 *   - 256 色与真彩色按 xterm 调色板量化到 16 个 ANSI 槽;
 *   - 光标不闪:鸿蒙渲染层禁 CSS animation。
 * 这些不是「待办」,是这层架构的真实边界。
 */

第三处是右侧栏的「已知限制」面板,界面启动后由 app:info 的 boundaries 字段渲染出来,用户在界面上直接读得到同样六条。三处措辞略有差别,语义完全一致,没有一处做了粉饰。

值得一提的是第六条的措辞,「不支持的会明确报错,不静默当成功」这句话在 term-shell.js 的文件头里还重复了一次:

/* 这一层不是真 shell:没有 fork/exec,也没有权限模型。命令全部在
 * term-fs.js 的内存文件树上执行,输出是带 ANSI 序列的字符串,
 * 由 term-session.js 喂给屏幕模型。
 *
 * 支持的结构:管道 |、重定向 > >> <、顺序 ;、短路 && ||、引号、$变量。
 * 不支持的会明确报错,不静默当成功。
 */

内存文件系统的头注释把「为什么不是真文件系统」也交代清楚了:

/* WezTerm 终端工作台 —— 内存虚拟文件系统
 *
 * 为什么不是真文件系统:鸿蒙应用沙箱里没有可用的真实 shell,
 * 终端里的命令必须有确定的行为,所以文件树放在内存里,随会话重建。
 * 这条边界会写在界面的「已知限制」里,不假装能操作真实磁盘。
 */

七类图层里最先铺底的这一层,实际上决定了整个应用的验收标准。既然命令跑在内存上,那么「ls 能不能列对」「cat 会不会漏行」「管道有没有截断」就是纯函数问题,可以离线对拍;而不像真实终端那样依赖运行时环境。这套壳的产品力恰恰来自承认边界之后的彻底性:不真,但恒真。

1.2 二十一个 IPC 与按键到快照的闭环

渲染层与主进程之间一共 21 个通道,其中 1 个是 app: 前缀,20 个是 term: 前缀。全部登记在 main.js 的 registerIpc 一个函数里,按职责可以分成六组。

应用与生命周期 5 个:app:info 负责把版本、命令表、主题名、边界清单和各项上限一次性发出去;term:init 在渲染层量出列行数后调一次;term:resize 在窗口拖动时改网格;term:theme 换配色;term:reset 清空内存文件系统并回到默认配置。

输入 5 个:term:input 收一段可见字符,term:key 收命名键,term:paste 收粘贴文本,term:scroll 收滚轮增量,term:goto 跳到指定行。

标签 3 个:term:tab-new、term:tab-close、term:tab-focus。窗格 4 个:term:pane-split、term:pane-close、term:pane-focus、term:pane-move。

配置与检索 3 个:term:config-get、term:config-set、term:search。导出 1 个:term:save,它是全篇唯一的 async 处理函数,因为要弹保存对话框。

这 21 个通道有一个好性质:两侧数量完全相等,一一对应,没有一边注册了另一边不用的死通道,也没有一边调用另一边没注册的空指针。逐字统计的结果是主进程 21 个 handle、渲染层 21 个 act 或 ipc 调用点,集合完全相同。

主进程的 handle 包装器是这套闭环的关键,它把所有异常收在一处:

function handle(channel, fn) {
  ipcMain.handle(channel, async function (event, req) {
    try {
      return await fn(req || {});
    } catch (e) {
      return { success: false, error: errText(e), code: e && e.code };
    }
  });
}

渲染层对应地也只有一个漏斗:

function ipc(channel, payload) {
  state.pending++;
  return ipcRenderer.invoke(channel, payload).then(function (r) {
    state.pending--;
    return r || { success: false, error: '主进程没有回执' };
  }).catch(function (e) {
    state.pending--;
    /* 英文原文只进 detail,状态栏只留中文 */
    return {
      success: false,
      error: '与主进程通信失败',
      detail: String((e && e.message) || e)
    };
  });
}

注意 state.pending 这个计数器,它不只是统计用途。渲染层在窗口 resize 时会触发 relayout,而 relayout 会调 term:resize。如果用户快速拖动窗口,resize 事件可能比 IPC 回执更密,就会出现「拿旧尺寸算新网格」的抖动。relayout 用 pending 挡住了这种抖动:

function relayout(force) {
  if (state.pending > 0 && !force) return;
  var box = bodyBox();
  if (box.w <= 0 || box.h <= 0) return;
  var cols = clamp(Math.floor(box.w / state.charW), 20, 400);
  var rows = clamp(Math.floor(box.h / state.lineH), 6, 200);
  if (!force && cols === state.cols && rows === state.rows) return;
  state.cols = cols;
  state.rows = rows;
  act('term:resize', { cols: cols, rows: rows });
}

一次按键的完整链路是这样的:keydown 事件在 document 上以捕获阶段挂载,渲染层判断它是不是命名键(Enter、Backspace、方向键、Tab、翻页键共 12 个),是就走 term:key,是 Ctrl 组合(a、e、u、k、w、l、c 共 7 个)就走 term:key 的命名形式,是单字符就走 term:input。主进程拿到后交给 session,session 把结果写进屏幕模型,然后返回一份新的快照。渲染层收到快照后整棵树重建 DOM。

这条链路有一个设计取舍很值得说:键盘挂在 document 上,而不是挂在隐藏输入框上。隐藏输入框只负责输入法上屏那一条路径。

function wireKeys() {
  var kbd = $('kbd');

  /* 键盘挂在 document 上而不是隐藏输入框上:输入框拿不到焦点时终端仍然可输入 */
  document.addEventListener('keydown', onKeyDown, true);
  document.addEventListener('paste', onPaste, true);

  kbd.addEventListener('input', function () {
    if (state.composing) return;
    flushText();
  });

  kbd.addEventListener('compositionstart', function () { state.composing = true; });
  kbd.addEventListener('compositionend', function () {
    state.composing = false;
    flushText();
  });
  /* 此处省略其余实现 */
}

为什么要这么绕?因为鸿蒙的渲染层里,focus() 可能会被其它控件抢走,尤其是当侧栏的按钮、搜索框、配置对话框都参与焦点竞争时。如果终端依赖隐藏输入框持有焦点才能收键,用户点一下侧栏再回来打字就会丢字。挂在 document 上之后,无论焦点在哪,只要不是搜索框或配置框,按键都能进终端。isForeignField 就是用来放行那两个框的:

/* 搜索框、配置框里的输入不能被终端吞掉;终端自己的隐藏输入框不算 */
function isForeignField(node) {
  if (!node || !node.tagName) return false;
  if (node.tagName !== 'INPUT' && node.tagName !== 'TEXTAREA') return false;
  return node.id !== 'kbd';
}

可见字符那条分支还有一句注释,把取舍讲透了:

/* 可见字符直接从 e.key 送(Shift 已体现在 e.key 里)。
   * 这里 preventDefault 掉,原生 input 事件就不会再触发,不会重复上屏;
   * 这样也不依赖隐藏输入框是否拿到焦点——鸿蒙里 focus() 让位给别的控件时照样能打字。 */

同一个字符既要走 keydown 又要走 input,就有重复上屏的风险。这里用 preventDefault 掐断了 input 那条路,只让输入法组合态的字符(此时 isComposing 为真,keydown 直接放过)从 input 进来。两条路互斥,天然不会重。

1.3 七个引擎:把终端跑在主进程里

整套代码的分层方向和常见的 Web 终端相反。xterm.js 这类库把解析器和渲染器都放在页面里,主进程只是个壳;这套壳把七个引擎全部放在主进程,渲染层退化成一块只读的显示板。

engine 目录下七个文件的实际规模:

文件行数字节职责
term-shell.js11564105949 条内置命令与管道、重定向、变量展开
term-session.js67322661标签、窗格、输入行编辑、快照生成
term-screen.js62719300字符网格、宽字符、16 索引颜色量化
term-fs.js2979115内存文件树与预置内容
term-config.js26710212Lua 配置子集解析与六套主题
term-vt.js1444332VT 控制序列解析器(六态状态机)
term-pane.js1324187不可变窗格二叉树
合计3296100866—

3296 行占全应用 5539 行的 59.51%,100866 字节占 175272 字节的 57.55%。也就是说,这个应用近六成的代码是不碰 DOM 的纯逻辑。这个比例是分层选择的直接结果。

为什么要把引擎放在主进程?有三个理由。

第一是密钥。渲染层跑的是 nodeIntegration 打开的页面,一旦页面里的脚本被注入,它在渲染层能碰到的一切就都暴露了。引擎里没有任何敏感数据,但引擎所依赖的文件系统接口(用于读写偏好与导出记录)在主进程。把引擎放在主进程,等于让渲染层永远只拿到快照字符串,拿不到任何 fs 句柄。

第二是一致性。终端的状态是「屏幕网格 + 滚动历史 + cwd + 输入行 + 窗格树」,这五样东西之间有强一致性约束:删了目录,cwd 不能还停在那个目录上;关了窗格,焦点要落到邻格;改了尺寸,光标不能跑出网格。这些约束如果分散在两侧,就会出现一半界面已经改了另一半没改的中间态。放在主进程之后,一次 IPC 就是一个事务。

第三是可测试性。term-session.js 的 module.exports 只导出一个 Session 类和几个常量,不 require electron,不碰 window,给它一个 80×24 就能构造。同样地 term-vt、term-pane、term-fs、term-config 四个模块都只 require 彼此,不 require electron。整个引擎目录里唯一 require 外部模块的地方是 term-session.js 对另外五个引擎的引用:

var TermScreen = require('./term-screen.js');
var Shell = require('./term-shell.js');
var PaneTree = require('./term-pane.js');
var PaneFs = require('./term-fs.js');
var Conf = require('./term-config.js');

渲染层对引擎的引用只有一处,而且只借用属性常量,不构造对象:

var electron = require('electron');
var ipcRenderer = electron.ipcRenderer;
var Attr = require('./engines/term-screen.js');

Attr 用在哪里?用在 classOf 里把属性位翻译成 CSS 类名:

function classOf(seg) {
  var cls = [];
  if (seg.f !== '' && seg.f != null) cls.push('f' + seg.f);
  if (seg.b !== '' && seg.b != null) cls.push('b' + seg.b);
  var a = seg.a || 0;
  if (a & Attr.A_BOLD) cls.push('a-bold');
  if (a & Attr.A_DIM) cls.push('a-dim');
  if (a & Attr.A_ITALIC) cls.push('a-ital');
  if (a & Attr.A_UNDER) cls.push('a-under');
  if (a & Attr.A_STRIKE) cls.push('a-strike');
  return cls.join(' ');
}

这是一个很小但很实用的复用:属性位定义(A_BOLD 为 1、A_DIM 为 2、A_ITALIC 为 4、A_UNDER 为 8、A_STRIKE 为 16、A_INVERSE 为 32)在主进程和渲染层必须是同一套数字,否则样式会错位。让渲染层 require 引擎文件的常量表,比抄一份数字过去靠得住。

代价也很明确:每一次按键都要过一次 IPC。一次 IPC 的往返在鸿蒙的中低端设备上是零点几毫秒量级,比起渲染层重绘整屏的代价要小得多,所以这个代价是可以接受的。真正需要警惕的是「每个字符都触发一次全屏重建 DOM」——这一条我们在第四章会专门讲,因为它是这套架构最容易踩的坑。

二、环境准备

2.1 工具链版本与签名材料

这套工程的 SDK 声明写在一个产品条目里,没有给第二个产品留位置:

{
  "app": {
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.5(17)",
        "compatibleSdkVersionStage": "release",
        "runtimeOS": "HarmonyOS",
        "buildOption": {
          "nativeLib": {
            "collectAllLibs": true
          }
        }
      }
    ]
  }
}

这里有两处值得单独说明。第一处是 compatibleSdkVersion 取 5.0.5(17),版本号后面的括号是 API 级别。鸿蒙的 SDK 版本表述里这两半必须同时写对,只写 5.0.5 会让构建器猜,猜错的那一版可能把 2in1 设备形态过滤掉。第二处是 collectAllLibs 取 true,它的作用是把依赖树里所有 .so 都收进产物,而不是只收被显式引用的。这个开关对 Electron 壳是必需的,因为 libelectron.so 通过 dlopen 在运行时动态加载 libadapter.so,构建期的静态引用分析看不到这条边,收不收全靠这个开关说了算。

签名材料走的是 IDE 自动生成的默认配置,三件套都以本机绝对路径出现在工程里:

"signingConfigs": [
  {
    "name": "default",
    "type": "HarmonyOS",
    "material": {
      "certpath": "C:\\Users\\ws199\\.ohos\\config\\default_ohos_hap_...=.cer",
      "keyAlias": "debugKey",
      "keyPassword": "0000001B4AF071EA...",
      "profile": "C:\\Users\\ws199\\.ohos\\config\\default_ohos_hap_...=.p7b",
      "signAlg": "SHA256withECDSA",
      "storeFile": "C:\\Users\\ws199\\.ohos\\config\\default_ohos_hap_...=.p12",
      "storePassword": "0000001BEC2D379BF9..."
    }
  }
]

三个路径都指向用户目录下的 .ohos/config,文件名带一段随机串,说明是 IDE 在某一次自动生成时定下的。keyPassword 与 storePassword 两串十六进制不是明文口令,而是 IDE 用自己的密钥加密过的密文,长度都在 80 个字符上下。这种写法在本机能直接构建,但它有两处硬伤,我们在第四章的缺陷台账里会展开:一是换一台机器、换一个用户目录,这两个路径就失效;二是密钥与口令跟着工程文件进了仓库。

2.2 应用信息与设备形态

应用级信息在 AppScope/app.json5,一共 16 行,信息密度不低:

{
  "app": {
    "bundleName": "com.huawei.ohos_electron",
    "vendor": "example",
    "versionCode": 1000000,
    "versionName": "1.0.0",
    "icon": "$media:app_icon",
    "label": "$string:app_name",
    "configuration": "$profile:configuration",
    "multiAppMode": {
      "multiAppModeType": "multiInstance",
      "maxCount": 1
    }
  }
}

bundleName 是 com.huawei.ohos_electron,不是 com.huawei.ohos_wezterm。这说明鸿蒙里跑的其实是同一个 Electron 宿主壳,具体是哪个应用由壳内加载的 app 目录决定。vendor 写着 example,是模板默认值。versionCode 1000000 由 1.0.0 按 major×1000000 + minor×1000 + patch 推出,这是一个常见的编码口径。

multiAppMode 这一段值得单独说:multiAppModeType 取 multiInstance、maxCount 取 1,语义是「允许开多实例,但上限是 1」。这个组合等价于单实例运行,只是把限制放在了系统层而不是应用层。对终端应用来说这是对的——两个终端窗口如果共享同一份内存文件系统,用户会看到互相踩踏的结果,而当前架构下每个进程有各自的内存文件树,多开就是两份互不相通的沙箱。

跨设备的字号配置在 AppScope/resources/base/profile/configuration.json:

{
  "configuration": {
    "fontSizeScale": "followSystem",
    "fontSizeMaxScale": "1.45"
  }
}

这条配置对终端类应用格外关键。followSystem 意味着用户把系统字号调大时应用跟着放大,1.45 是放大倍数的上限。为什么要有上限?因为终端是等宽字符网格,字号放大 45% 之后,同样像素宽度能放的列数会掉到原来的三分之二左右。渲染层算列数的公式是宽度除以字符宽再取整:

var cols = clamp(Math.floor(box.w / state.charW), 20, 400);
var rows = clamp(Math.floor(box.h / state.lineH), 6, 200);

字号涨 45%,charW 跟着涨 45%,cols 就掉 31%。如果不设上限,用户在无障碍设置里把字号拉到 2 倍,80 列的终端会掉到 40 列,多数命令输出直接折行到不可读。1.45 这个数字是可用性和可达性之间的折中,不是随手填的。

设备形态声明在两处,electron 模块与 web_engine 模块是一致的:

"deviceTypes": [
  "2in1",
  "tablet"
]

2in1 就是 PC 与二合一设备,tablet 是平板。没有 phone。这个取舍和终端应用的输入模型有关:手机上没有物理键盘,软键盘和终端抢占屏幕,而终端的多数操作(Ctrl 组合、Tab 补全、翻页)在软键盘上要额外做一层映射,成本远高于收益。

electron 模块里登记了三个 ability 和两个 extensionAbility,是这套壳的固定骨架:EntryAbility 是入口,launchType 取 specified,exported 为真,带 home 与 viewData 两组 skills;BrowserAbility 与 StatelessAbility 都跑在名为 :browser 的独立进程里;extensionAbility 里 StatusBarEntryAbility 的类型是 statusBarView,BrowserEmbeddedAbility 的类型是 embeddedUI。整套应用只用一个 entry 模块加一个 har 模块,没有 feature 模块。

2.3 四条 CSP:为什么比同类应用少了六条

内容安全策略写在 index.html 的第六行,一共四条指令:

<meta http-equiv="Content-Security-Policy"
      content="default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:;" />

四条分别是:默认来源只允许同源,脚本只允许同源,样式只允许同源,图片允许同源加 data: 协议。没有 connect-src,没有 media-src,没有 font-src,没有 worker-src,没有 frame-src,也没有 object-src。

能这么精简,是因为这个应用的外部资源面本来就小。整个页面只有一条脚本引用:

<script src="renderer.js"></script>

样式是静态的 wezterm.css 加一个可换的主题文件,通过 link 标签的 href 在六套主题之间切换:

<link id="theme-link" rel="stylesheet" href="styles/themes/dracula.css" />

没有字体文件(用的是系统等宽字体栈),没有图片(配色是纯色块),没有 worker,没有 iframe,没有 blob: 也没有 data: 的脚本。少写的每一条指令都是「因为这个应用确实不需要它」,而不是「先把策略放开省事」。

这里有一个取舍要讲清楚:因为渲染层跑在 nodeIntegration 为真的环境里,它本来就能 require(‘fs’),connect-src 之类针对页面发起的网络请求的指令,管不到 Node 层的出网能力。这一点和第一章讲的「把引擎放主进程」是同一条逻辑的两面——真正的隔离靠进程边界,CSP 只是网页层的补丁。把这条界限认清,才不会误以为有了 CSP 就安全了。

页面结构本身也做了收敛。index.html 一共 132 行 6624 字节,只有一页,没有路由,没有模板引擎。DOM 元素的 id 一共 37 个,渲染层通过 document.getElementById 引用的也是 37 个,两侧集合完全相同,没有一个孤儿元素,也没有一次取到 null。这个数字是靠逐字对拍得来的:把 HTML 里所有 id 属性的值取出来去重,再把 renderer.js 里所有 $(‘…’) 的参数取出来去重,两个集合做差集为空。

37 个 id 按区块分:顶栏 10 个(品牌区与九个按钮),终端区 4 个(panes、hint-bar、measure、kbd),右栏三块 5 个(theme-list、theme-now、cmd-list、cmd-count、limits),状态栏 3 个(status、status-right、btn-about),搜索框 7 个,配置框 5 个,关于框 2 个,主题链接 1 个。这个划分能对上纯粹的 DOM 结构,说明页面是按区块一次性搭完的,没有后期补丁式的插入。

三、核心适配流程

3.1 VT 解析器:六态状态机,只管切分不管屏幕

终端接收的字节流里混着两类东西:要显示的字符,和要由程序解释的控制序列。把这两类分开的工作归 VT 解析器,把分开后的结果画到网格上的工作归屏幕模型。这两个职责在 term-vt.js 里被切得非常干净——它只有 144 行 4332 字节,是整个引擎目录最小的一份,因为它一个字符都不存。

文件头的覆盖范围写得极短,五行把边界钉死了:

/* WezTerm 终端工作台 —— VT 序列解析器
 *
 * 只做切分:把输出流拆成 print / exec / csi / osc / esc 事件,不碰屏幕状态。
 * 屏幕怎么响应这些事件由 term-screen.js 决定,所以这一层可以单独测。
 *
 * 覆盖范围(与 xterm 对齐的部分):
 *   - 控制字符:BEL BS HT LF VT FF CR
 *   - CSI:参数(含 ? < > = 前缀)、中间字节、终结字节
 *   - ESC:7 8 D M E H c = >
 *   - OSC:以 BEL 或 ST(ESC \)结尾
 *   - DCS / SOS / PM / APC:整段丢弃(不解析内容)
 */

六个状态的定义只有一行:

var ST = { GROUND: 0, ESC: 1, CSI: 2, OSC: 3, OSC_ESC: 4, DCS: 5 };

GROUND 是正常文字态。收到 0x1b(ESC)进 ESC;ESC 后面接方括号就是 CSI(控制序列引导符),接 ] 就是 OSC(操作系统命令),接大写 P、大写 X、上尖号、下划线四个字节则统一进 DCS——因为在解析器看来,DCS、SOS、PM、APC 四种字符串的处理方式完全一样,都是「整段丢弃」,所以共用同一个状态。OSC_ESC 是 OSC 态的中间态,用来处理以 ESC 反斜杠结束的另一种 OSC 终止符。

GROUND 态的四条分支顺序值得逐条看:

case ST.GROUND:
        if (c === 0x1b) { flush(); self.state = ST.ESC; }
        else if (c === 0x07 || c === 0x08 || c === 0x09 || c === 0x0a ||
                 c === 0x0b || c === 0x0c || c === 0x0d) {
          flush();
          out.push({ t: 'exec', c: c });
        } else if (c < 0x20 || c === 0x7f) {
          /* 其它控制字符丢弃,和 xterm 一致 */
        } else {
          buf += ch;
        }
        break;

这里有两处经验。第一处是「小于 0x20 的控制字符与 0x7f 直接丢弃」,这与 xterm 的行为一致。很多手写解析器会把 0x01 到 0x06 也当字符显示,结果遇到某些程序输出的进度条控制符时,屏幕上会多出一堆方块。第二处是 flush 的位置——进 ESC 前、发 exec 前都要先把 buf 里攒的正文推出去。这两个 flush 少写一个,就会出现「控制序列插到了文字中间」的错位,是这类解析器最常见的 bug。

print 事件的粒度也值得一句:buf 攒到遇到非打印字符才发一次。对于一行 80 字符的输出,逐字符发会产生 80 个事件,攒批只产生 1 个,对高频刷新的场景差别很大。

CSI 态的参数解析有一个细节:

/* CSI 参数:空串算 0,'?' 之类的私有前缀单独存。
 * 子参数(':' 分隔)统一降级成 ';',SGR 里空位按 0 处理。 */
function parseParams(str) {
  if (!str) return [];
  var raw = String(str).replace(/:/g, ';').split(';');
  var out = [];
  for (var i = 0; i < raw.length; i++) {
    var s = raw[i];
    if (s === '') { out.push(0); continue; }
    var n = parseInt(s, 10);
    out.push(isFinite(n) ? n : 0);
  }
  return out;
}

把冒号降级成分号是一个务实的取舍。真正的 xterm 里冒号用来表达子参数,232 色的 38:5:196 与分号形式的 38;5;196 语义相同但解析路径不同。降级之后,只需要一套分号逻辑就能同时处理两种写法,代价是「真子参数」的语义丢失。考虑到本壳已经把 256 色量化到 16 色,这个代价实际上为零。

CSI 态的三类字节判定严格按区间来:终结字节为 0x40 到 0x7e,参数字节为 0x30 到 0x3f,中间字节为 0x20 到 0x2f。其中私有前缀只在「还没有任何参数也没有中间字节」时才抢位:

} else if (c >= 0x30 && c <= 0x3f) {
          if (!self.params && !self.inter &&
              (ch === '?' || ch === '<' || ch === '>' || ch === '=')) {
            self.prefix = ch;
          } else {
            self.params += ch;
          }
        } else if (c >= 0x20 && c <= 0x2f) {
          self.inter += ch;
        } else {
          /* 非法字节:整条序列作废,回到地面态 */
          self.state = ST.GROUND;
        }

那个注释说得很到位:「整条序列作废,回到地面态」。这一条是为了对抗乱码:如果字节流在中途被截断,解析器不会卡在 CSI 态里永远出不来。一个卡在 CSI 态的解析器,表现是「终端从此不再显示任何文字」,而且用户看不出原因,这类故障极难在真机上定位。

OSC 态的设计也值得单看。OSC 的终止符有两种:BEL(0x07)和 ESC 反斜杠(ST,String Terminator)。只用一个状态处理不了后一种,因为收到 ESC 时还不知道它是不是 ST 的开头。所以有了 OSC_ESC 这一态:

case ST.OSC_ESC:
        if (ch === '\\') {
          out.push({ t: 'osc', s: self.osc });
          self.state = ST.GROUND;
        } else {
          /* 不是 ST 结尾,把 ESC 还给内容,继续收 */
          self.osc += '\u001b' + ch;
          self.state = ST.OSC;
        }
        break;

「把 ESC 还给内容」这七个字是全篇最能看出作者经验的地方。终端里最常见的两条 OSC 是改窗口标题和改配色,内容里带 ESC 是合法的。处理不当就会把内容截断,而截断后剩半条序列又会去污染后续解析,形成连锁错误。把 ESC 拼回内容继续收,语义上是「这两个字节不属于终止符,原样保留」,代价只是多拼一次字符串。

DCS 态的判定更短:

case ST.DCS:
        if (c === 0x1b) self.state = ST.ESC;
        break;

只认 ESC,其余全部吞掉。转回 ESC 态之后,如果下一个字节是反斜杠,ESC 态里没有处理反斜杠的分支,会走到 else 分支回到 GROUND——这正好就是 ST 结尾的效果。所以 DCS 实际上是靠 ESC 反斜杠退出的,只是顺带复用了一下那个 else。这个写法省了一个分支,但读代码时容易误以为 DCS 不会被正确结束,需要在脑子里多转一步。

把这套解析器单独拆出来的好处是:它没有任何副作用。给定一串字节,输出是一串事件(print 带字符串,exec 带控制字符码,csi 带参数数组与终结符,osc 带内容,esc 带单字符),事件序列可以和 xterm 对拍。这一点在 term-session.js 里体现得很直接——Session 只是消费 Parser 抛出的事件,自己不碰字节。

3.2 屏幕网格与 16 索引颜色量化

屏幕模型在 term-screen.js,627 行 19300 字节,是引擎里第二大的文件。它的核心决定是:每个字符格只存两个字节级的索引(前景色索引、背景色索引),不存 RGB。

这个决定牵到三个连锁后果。

第一,颜色量化必然发生。256 色和真彩色进来,必须落到 16 个索引上。用的方法是欧氏距离取最近:

function quantIndex(r, g, b) {
  var best = 0, bd = Infinity;
  for (var i = 0; i < 16; i++) {
    var p = PALETTE[i];
    var d = (p[0] - r) * (p[0] - r) + (p[1] - g) * (p[1] - g) + (p[2] - b) * (p[2] - b);
    if (d < bd) { bd = d; best = i; }
  }
  return best;
}

这段代码每次都循环 16 次。如果直接对真彩色调用,性能会很差,所以入口在 color256 与 colorRGB 两个函数上,前者先走调色板查表,后者才走量化。

第二,量化的失真程度可以被精确算出来。这个问题值得算一遍,因为它直接决定了界面上那句「256 色已量化到 16 色索引」到底丢了多少。

量化基准是 xterm 的默认 16 色表:

var PALETTE = [[0,0,0],[205,0,0],[0,205,0],[205,205,0],[0,0,238],[205,0,205],[0,205,205],[229,229,229],
               [127,127,127],[255,0,0],[0,255,0],[255,255,0],[92,92,255],[255,0,255],[0,255,255],[255,255,255]];

十六个值的分量取集合是 0、92、127、205、229、238、255 这七个数。而 256 色的 6×6×6 立方段,每个分量只取 0、95、135、175、215、255 这六个数(公式是 v 为零时取 0,否则取 55 加 40 乘 v)。两个集合的交集只有 0 和 255 两个值。

结论因此是确定的:216 个立方色里能精确保真的只有纯黑(索引 0)与纯白(索引 15)两个,其余 214 个全部发生偏移。灰阶段的 24 个值按 8 加 10 的倍数生成(8、18、…、238),而 PALETTE 里的灰有 0、127、229、255 四个,238 不等于 229,8 到 238 的序列里也凑不出 127,所以 24 个灰阶一个都保不了真。把三段加总:256 个输入色里,精确保真的只有 16 个基础色加上纯黑纯白这两个重复值,其余 254 个都在量化时被拉到了邻近的槽位。

这就是为什么界面上必须把这条写成「已知限制」:用户在别的终端里用 232 色画的图表,搬到这个壳里会变成 16 色的色块图,颜色之间的差异被压平了。这不是 bug,是存 16 索引的必然代价。

第三,好处是换主题时历史内容也跟着变色。因为格子里存的只是索引,渲染层拿到的类名是 f3 或 b11,真正的颜色由 CSS 变量 --ansi-3 决定,而主题文件只覆盖 :root 里的变量。用户把 Dracula 换成 Nord,三小时前的输出也会跟着变,和真终端的行为一致。

宽字符的处理在 widthOf 与 stringWidth 两个函数里。widthOf 判宽度,一共十二段区间:

function widthOf(cp) {
  if (cp >= 0x1100 && (
    cp <= 0x115f || cp === 0x2329 || cp === 0x232a ||
    (cp >= 0x2e80 && cp <= 0xa4cf && cp !== 0x303f) ||
    (cp >= 0xac00 && cp <= 0xd7a3) ||
    (cp >= 0xf900 && cp <= 0xfaff) ||
    (cp >= 0xfe10 && cp <= 0xfe19) ||
    (cp >= 0xfe30 && cp <= 0xfe6f) ||
    (cp >= 0xff00 && cp <= 0xff60) ||
    (cp >= 0xffe0 && cp <= 0xffe6) ||
    (cp >= 0x1f300 && cp <= 0x1f64f) ||
    (cp >= 0x1f900 && cp <= 0x1f9ff) ||
    (cp >= 0x20000 && cp <= 0x3fffd))) return 2;

这套区间表能对上四类东西:中日韩表意文字(0x2e80 到 0xa4cf,中文的 4e00 落在里面)、韩文音节(ac00 到 d7a3)、全角标点(ff00 到 ff60)、以及表情符号的两段(1f300 到 1f64f、1f900 到 1f9ff)。0x303f 要单独排除,因为它是全角空格之外的半边符号,宽度为一。

widthOf 只看一件事:这个码点占一列还是两列。但屏幕上真正麻烦的不是宽字符,而是「一行字符里夹着颜色序列,还算不算宽度」。这件事交给了 stringWidth,它的注释把动机写得很明白:

/* 一行文字的显示宽度:宽字符算 2 列,组合字符不占列。行编辑定位光标要用它。
 * 提示符里夹着颜色序列,ESC 开头的控制串必须整段跳过,否则光标会偏一截。 */
function stringWidth(s) {
  var t = String(s == null ? '' : s);
  var w = 0;
  for (var i = 0; i < t.length;) {
    var code = t.charCodeAt(i);
    if (code === 27) {
      var j = i + 1;
      var kind = t.charAt(j);
      if (kind === '[') {
        j++;
        while (j < t.length) {
          var cc = t.charCodeAt(j);
          j++;
          if (cc >= 0x40 && cc <= 0x7e) break;
        }
      } else if (kind === ']') {
        j++;
        while (j < t.length && t.charCodeAt(j) !== 7) j++;
        j++;
      } else {
        j++;
      }
      i = j;
      continue;
    }
    if (code === 9) { w += 8 - (w % 8); i++; continue; }
    var cp = t.codePointAt(i);
    var ch = String.fromCodePoint(cp);
    i += ch.length;
    if (isCombining(cp)) continue;
    w += widthOf(cp);
  }
  return w;
}

这段一共处理了五种情况,每一条都是踩过坑之后的产物。

第一,ESC 开头三种控制串的跳过。方括号走终结字节判定(0x40 到 0x7e),右方括号走 BEL 结尾,其余单个字节直接跳两位。注意这里只做「跳」,不做参数解析。所以 term-screen.js 里确实存在第二份控制串切分逻辑,与 term-vt.js 里的那份是独立实现的。两者不会互相校正,一旦一边改了判定区间另一边没改,就会出现「屏幕上显示正常但光标位置算错」的隐性故障。这是缺陷台账里的一笔。

第二,制表符按 8 的倍数补齐:w 加 8 减 w 对 8 的余数。这是终端里制表位的标准行为,不是固定加 8。如果固定加 8,一个已经处在第 3 列的位置按 Tab 会跳到 11 而不是 8,后续所有定位全部错开。

第三,组合字符不占列。isCombining 覆盖四段区间:0x0300 到 0x036f(主要的重音符号)、0x1ab0 到 0x1aff、0x20d0 到 0x20ff、0xfe20 到 0xfe2f。中文场景里这四段用得不多,但遇到带变量的拉丁字母或某些表情变体时,不处理就会把光标推偏。

第四,代理对的处理。循环变量不是每步加一,而是先取 codePointAt,再用 fromCodePoint 换回字符串,拿它的 length 作为步长。对于落在辅助平面的码点,length 是 2,这样既不会把代理对拆成两个乱码,也能正确地把 0x1f300 这类表情符号判成两列宽。

第五,制表符那条分支在 codePointAt 之前就 continue 了,所以不会被当成普通字符再算一遍宽度。这个顺序很容易写反:如果先算码点再判断制表符,制表符就会被 widthOf 当成一列宽,多加一列。

屏幕本身的初始化也把夹紧做齐了:

function Screen(opt) {
  opt = opt || {};
  this.cols = clamp(opt.cols || 80, 20, 400);
  this.rows = clamp(opt.rows || 24, 6, 200);
  this.maxScroll = opt.scrollback != null ? clamp(opt.scrollback, 100, 20000) : 2000;
  this.parser = new Vt.Parser();
  this.scroll = [];
  /* 此处省略其余实现 */
}

三个值都与 main.js 的常量对得上:MIN_COLS 20 与 MAX_COLS 400、MIN_ROWS 6 与 MAX_ROWS 200、滚动历史 100 到 20000 且默认 2000。这种「同一个数字在两处出现」的情况在本壳里有好几处,后面讲 Lua 配置时会看到它的更严重版本。

每个空格子的结构是 { ch, f, b, a, w } 五个字段:字符、前景索引、背景索引、属性位、宽度标记。一行 400 列乘 200 行就是 8 万个格子,每个格子五个字段,这是这套内存模型的主要开销。拿它去换「换主题时历史内容跟着变色」这个效果,值不值?考虑到 8 万格只在极端的满屏情况下才会出现,而实际使用中滚动历史才是大头(2000 行 × 80 列 = 16 万格),这个开销需要认真对待。MAX_ECHO 这个常量的存在就是因为这个。

3.3 不可变窗格二叉树与方向键邻格

一个标签页里的分屏是一棵二叉树:叶子是终端,节点是水平或垂直切分。这个结构在 term-pane.js 里只有 132 行,但有两个设计选择很见功夫。

第一个选择是树不可变。split 与 close 都返回新树,旧树不动:

/* 一个标签页里的分屏是一棵二叉树:叶子是终端,节点是水平/垂直切分。
 * 树是不可变的:split / close 都返回新树,旧树不动,方便对拍与回滚。 */
function push(tree, paneId, dir, newId) {
  if (!tree) return leaf(newId);
  if (tree.type === 'leaf') {
    if (tree.id !== paneId) return tree;
    return { type: 'split', dir: dir === 'v' ? 'v' : 'h', ratio: 50, a: tree, b: leaf(newId) };
  }
  return { type: 'split', dir: tree.dir, ratio: tree.ratio,
    a: push(tree.a, paneId, dir, newId), b: push(tree.b, paneId, dir, newId) };
}

为什么不可变值得?因为增删窗格是一个多步操作:改树、重新算布局矩形、把焦点移到合理的邻格、更新状态栏的窗格计数。这四步之间任何一步失败,可变树就会停在一个半成品状态。不可变之后,新树要么完整生成,要么根本不生成,回滚就是「不用新树」。

代价是每次改动都要复制路径上的节点。考虑到窗格数量的人机上限(一个屏幕分四块已经是常态,八块就很拥挤了),这棵树的高度不会超过四层,复制代价可以忽略。这是一个典型的「不可变用在规模可控的地方」的例子。

第二个选择是布局与选择器分离。layout 负责算矩形,neighbor 负责找邻格:

/* 布局矩形:给渲染层算 grid 分栏,也给方向键找邻格 */
function layout(tree, rect) {
  /* 此处省略前置处理 */
  var pct = Math.max(10, Math.min(90, tree.ratio || 50)) / 100;
  /* 此处省略其余实现 */
}

ratio 被夹在 10 到 90 之间。这个夹紧很有必要:如果允许 ratio 取 0 或 100,用户把分割线拖到边缘之后,另一侧的窗格宽度变成零,既看不见也点不着,等于把自己的窗口弄丢了。夹到 10% 至少留一线生机。

neighbor 的逻辑是「在指定方向上找最近的邻格」,找不到就原地不动:

/* 方向键切换:在指定方向上找最近的邻格,找不到就原地不动 */
function neighbor(tree, paneId, dir) {
  // 条件分支节选(后续三元分支未展示):dir === 'left' ? ok = c.x < mc.x
  /* 此处省略其余实现 */
}

「找不到就原地不动」这一条比看起来重要。很多分屏实现在边界上会环绕,从左边的窗格按左键跳到最右边的窗格。这个行为在编辑器里可能顺手,但在终端里容易出事:用户以为焦点没动,继续按 Ctrl-C,结果它发到了另一个正在跑长命令的窗格里,把那个命令中断了。不环绕就避免了这类误伤。

窗格树的接口一共十个:leaf、isLeaf、split、close、leaves、count、layout、neighbor、setRatio、dump。其中 dump 是给对拍用的,把一个树结构摊平成可比较的文本,这是写测试时的常规手段。

需要指出一个导出没有被用到:isLeaf。它在文件里定义一次、在 module.exports 里登记一次,但整个工程里没有第三个地方调用它——所有需要判叶子的地方都直接写了 node.type === ‘leaf’。这是纯粹的冗余导出,数量不大,但说明导出表是先按「可能有用」写的,没有回头按实际用量收。

3.4 四十九条命令的内存 Shell

term-shell.js 是全应用最大的一个文件:1156 行 41059 字节,占引擎总字节的 41%。之所以这么大,不是因为它复杂,而是因为它把四十九条命令的实现一个字一个字写了出来。

命令表本身是一份数据,四组:基础 10 条(help、clear、echo、printf、date、whoami、hostname、uname、history、exit),文件 24 条(pwd、cd、ls、cat、head、tail、wc、grep、sort、uniq、cut、tr、seq、find、tree、du、df、mkdir、touch、rm、cp、mv、basename、dirname),系统 10 条(ps、free、uptime、env、export、unset、which、type、alias、unalias),WezTerm 专属 5 条(wezterm、config、theme、demo、man)。10 加 24 加 10 加 5 刚好 49。

每一条都带四个字段,这张表直接会被 app:info 发给界面渲染右栏:

{ name: 'grep', usage: 'grep [-i] [-v] [-n] [-c] 模式 [文件...]', desc: '按行过滤', group: '文件' },

这个设计的价值在于一处数据两个用途:命令表既是解释器的注册表,又是界面的帮助文档。两处不会漂移,因为只有一份。这比「代码里一套、文档里一套」稳得多。

解析分三层:tokenize 切词,parse 拆结构,run 串起所有阶段。

tokenize 里最值得看的是引号内反斜杠的处理:

if (ch === '\\' && quote === '"') {
        var nxt = s.charAt(i + 1);
        if (nxt === '"' || nxt === '\\' || nxt === '$' || nxt === '`') { cur += nxt; i++; }
        else cur += '\\';
        has = true;
        continue;
      }

注释里给出的理由是:双引号里只对四个字符吃反斜杠,其余原样保留,否则 echo 一句带反斜杠的路径会把路径里的反斜杠吞掉。这条规则与 POSIX 的 sh 一致,而不是与 C 字符串一致。很多自写 shell 会直接用 JSON 或正则去解析命令行,结果就是 echo 一条 Windows 风格路径时少了一半斜杠。

parse 把词法结果拆成阶段与管道。三层结构的嵌套很清楚:stages 数组是最外层的分隔(分号、与、或),每个 stage 里是 pipes 数组(竖线分隔),每个 pipe 里才是一条命令的 argv 与重定向。

function parse(tokens) {
  var stages = [];
  var cur = { pipes: [], join: '' };
  var cmd = { argv: [], in: null, out: null, append: false };
  var pending = null;
  /* 此处省略其余实现 */
    if (t === '|') { endCmd(); continue; }
    if (t === ';' || t === '&&' || t === '||') {
      endCmd();
      if (cur.pipes.length) stages.push(cur);
      cur = { pipes: [], join: t };
      continue;
    }
    if (t === '>' || t === '>>' || t === '<') { pending = t; continue; }
}

append 用一个布尔值跟着走,而不是另建一个结构,这让重定向的三个变体共用一个字段。这个写法省事,但也留下一个小小的隐患:如果一个重定向后面直接跟了竖线(语法错误),pending 永远没被消费,那个 > 就静静吞掉了。考虑到内置命令全部由用户手敲,错误输入会被后续的「找不到命令」报出来,这个隐患实际影响很小。

变量展开只支持三种写法:$?、${NAME}、$NAME。一条正则同时匹配三种,靠第一个分组区分:

function expandVars(s, ctx) {
  return String(s == null ? '' : s).replace(/\$(\?|\{[A-Za-z_][\w]*\}|[A-Za-z_][\w]*)/g, function (m, k) {
    if (k === '?') return String(ctx.lastCode || 0);
    var name = k.charAt(0) === '{' ? k.slice(1, -1) : k;
    var v = ctx.env[name];
    return v == null ? '' : String(v);
  });
}

拿不存在的变量返回空串而不是保留原文,这与 POSIX 一致。注意展开发生在 parse 之后而不是之前,所以在 run 里逐阶段展开:

var stage = { pipes: st.pipes.map(function (p) {
      return {
        argv: p.argv.map(function (t) { return expandVars(t, ctx); }),
        in: p.in, out: p.out, append: p.append
      };
    }) };

为什么要在管道中间才展开?因为同一条命令串里的前后阶段可能改环境变量。export A=1 && echo $A 里,echo 那一段必须看到刚刚设置的 A。如果一开始就把整串展开,echo 拿到的是旧值。这是一个容易漏的细节,很多自写 shell 就在这里错了。

短路逻辑靠 continue 实现,而不是提前跳出:

for (var i = 0; i < stages.length; i++) {
    var st = stages[i];
    if (i > 0) {
      if (st.join === '&&' && code !== 0) continue;
      if (st.join === '||' && code === 0) continue;
    }
    /* 此处省略其余实现 */
  }

这个写法把「跳过这一阶段」和「终止整个命令串」区分开了。a 失败之后,b 被跳过,但循环还在跑,到 c 那一阶段再看 c 自己的 join 是什么。如果是分号,c 照常执行;如果是与,c 也被跳过。这正好是 shell 的语义。如果写成 break,a && b ; c 里的 c 就永远不会执行了。

另外还有一处循环内的提前退出:

if (r.exit || r.clear) break;

exit 命令要结束当前窗格,clear 命令要清屏,这两件事都意味着后面的阶段没有意义了。把它们当成两个布尔位从执行结果里带出来,而不是在命令实现里直接动手,这是纯函数式的做法——命令不知道自己在不在管道里,它只是返回一个「请终止」的信号。

term-fs.js 提供的内存文件树是这套命令的地基。它用嵌套对象表示目录:目录节点带 children 对象,文件节点带 data 字符串,两者都带 mtime。预置内容分两份,SEED_FILES 放系统目录(/etc/motd、/etc/wezterm.lua、/var/log/system.log、/var/log/term.log),SEED_TREE 放用户目录。

预置内容里有一条值得拿出来看,因为它是这个应用自我描述的一部分:

'/home/wez/notes/todo.md':
    '# 待办\n' +
    '- [x] VT 解析器支持 CSI 与 OSC\n' +
    '- [x] 终端网格支持宽字符\n' +
    '- [x] 窗格分屏与标签切换\n' +
    '- [ ] 真实系统命令(沙箱内不可得,保持不做假实现)\n' +
    '- [ ] 串口与 SSH 域(不在本壳范围)\n',

三条打勾、两条不打勾,不打的这两条写的不是「待办」,而是「不可得」与「不在范围」。这份假文件也在说真话,和第一章那三处边界声明是同一个口径。

fs 里还有一个设计选择:文件内容按字符串存而不是按 Buffer 存。这意味着处理二进制会出错,但终端里的文本操作(cat、grep、wc、head、tail)全部需要按行切分,字符串更直接。按 Buffer 存会让每一条命令都先 decode 再 encode,代价大于收益。这个取舍的前提是「内存文件系统里不可能出现二进制」——而这个前提又是由「没有真实 shell」保证的。

3.5 Lua 配置子集与六套主题

上游 WezTerm 的配置是一个完整的 Lua 脚本:可以写 if、可以 require 模块、可以调函数。本壳做不到,于是定了一个可判定的子集:只认 config.字段 = 值 这一种赋值,值支持字符串、数字、布尔、单层表。

头注释把这条边界说得不加掩饰:

/* 上游用 Lua 写配置(wezterm.lua)。这里实现一个可判定的子集:
 *   - 只认 config.字段 = 值 这种赋值;
 *   - 值支持字符串、数字、布尔、单层表;
 *   - 注释支持 -- 行内截断(字符串里的 -- 不算)。
 * 解析不了的行会给出行号与原因,绝不静默吞掉。
 */

「可判定」这个词用得很准。一个完整的 Lua 解析器需要处理任意嵌套、任意表达式、任意副作用,而「config 点字段 等于 字面量」这个形式的合法性可以被一个不回溯的线性扫描完全确定。代价是可表达力,收益是确定性。

样板配置把这个子集能用的七个字段列齐了:

config.color_scheme = "Tokyo Night"
config.font_size = 13
config.line_height = 1.45
config.scrollback_lines = 2000
config.cursor_blink = false
config.show_tab_bar = true
config.window_padding = { left = 12, right = 12, top = 10, bottom = 10 }

-- 模板写法,本壳允许出现但不会执行
return config

最后那句注释很重要:「允许出现但不会执行」。上游用户拷过来的配置里几乎都有 return config,如果把它当成语法错误,用户会困惑。放过它但不执行它,既不影响结果,也不会让用户觉得自己写错了。

七个字段各带一条校验规则:

var SCHEMA = {
  color_scheme: { type: 'string', check: function (v) { return !!THEMES[v]; }, why: '配色名必须是内置主题之一' },
  font_size: { type: 'number', min: 10, max: 28, why: '字号取值范围 10–28' },
  line_height: { type: 'number', min: 1.0, max: 2.4, why: '行高取值范围 1.0–2.4' },
  scrollback_lines: { type: 'number', min: 100, max: 20000, why: '滚动历史上限 100–20000 行' },
  cursor_blink: { type: 'boolean', why: '光标闪烁只接受 true / false' },
  show_tab_bar: { type: 'boolean', why: '标签栏开关只接受 true / false' },
  window_padding: { type: 'table', why: 'window_padding 必须是表,例如 { left = 12 }' }
};

每条规则都带一句中文的 why,这句 why 会原样回到界面。这就是为什么配置对话框的错误提示可以直接读:「字号取值范围 10–28」。错误文案与校验代码存在一起,不可能对不上,这是比把文案散在界面里更可靠的写法。

写配置的链路有一个很硬的原则:解析不过一个字都不落盘。

/* 12. 写配置:先解析,解析不过一个字都不落盘 */
  handle('term:config-set', function (req) {
    var text = String(req.text == null ? '' : req.text);
    if (!text.trim()) return { success: false, error: '配置内容为空' };
    var r = applyLua(text);
    if (!r.ok) {
      return {
        success: false,
        error: '配置有 ' + r.parsed.errors.length + ' 处没有通过校验',
        errors: r.parsed.errors,
        warnings: r.parsed.warnings
      };
    }
    savePrefs(text);
    /* 此处省略其余实现 */
  });

这里的顺序是先 applyLua 拿结果,成功了才 savePrefs。两行代码的位置反过来,用户就会得到「配置存了但没生效」的状态,而且重启之后依旧没生效,极难定位。

更细的一层在 applyLua 里,它把两种失败分得很清楚:

/* 把 Lua 子集解析结果套到会话上;解析错的字段不会被静默丢掉,errors 会原样回给界面。
 * normalize 的越界回落也当成错误上报(line 0 表示这一行语法没问题、值越界),
 * 否则 config.font_size = 99 会被悄悄换成默认值,用户以为自己改成功了。 */
function applyLua(text) {
  var parsed = Conf.parseLua(text);
  if (parsed.errors.length) return { ok: false, parsed: parsed };
  var norm = Conf.normalize(parsed.values);
  if (norm.errors.length) {
    return {
      ok: false,
      parsed: {
        errors: norm.errors.map(function (why) { return { line: 0, why: why }; }),
        warnings: parsed.warnings
      }
    };
  }
  session.applyConfig(norm.config);
  return { ok: true, parsed: parsed, config: norm.config };
}

把「值越界」也当错误而不是回落,这个决定很不留情面,但正是它守住了用户的预期。界面那边的处理也对得上:line 为 0 就不强行编个行号,只显示原因:

r.errors.forEach(function (e) {
          /* line 为 0 表示语法没错、只是值越界,不强行编个行号 */
          lines.push(e.line ? '第 ' + e.line + ' 行:' + e.why : e.why);
        });

六个主题各定义在一份 CSS 里,每份 29 行,只覆盖 :root 里的变量,不碰任何结构规则。以 Dracula 为例:

/* 主题:Dracula(默认) */
:root {
  --term-bg: #282a36;
  --term-fg: #f8f8f2;
  --term-cursor: #f8f8f2;
  --term-sel: #44475a;
  --ansi-0: #21222c;
  --ansi-1: #ff5555;
  /* 此处省略其余实现 */
  --ansi-15: #ffffff;
  --ui-bar: #282a36;
  --ui-border: #44475a;
  --ui-dim: #6272a4;
  --ui-accent: #bd93f9;
  --ui-warn: #ff5555;
}

每份 25 个变量:四个终端基色、十六个 ANSI 槽、五个界面色。六份合计 150 个颜色值。

切换主题的动作极其便宜:改一个 link 的 href。

function themeFile(name) {
  return 'styles/themes/' + String(name).toLowerCase().replace(/\s+/g, '-') + '.css';
}

function applyTheme(name) {
  state.theme = name;
  var link = $('theme-link');
  if (link) link.setAttribute('href', themeFile(name));
  $('theme-now').textContent = name;
  renderThemeList();
}

主题名到文件名的转换只有两步:转小写、空白换连字符。所以 Tokyo Night 变成 tokyo-night.css,Catppuccin Mocha 变成 catppuccin-mocha.css。这个约定看起来无害,但它意味着主题名字里不能有连续空格、不能有斜杠,否则路径会出错。好在名字是写死在 term-config 里的,不来自用户输入。

这里有一个必须指出的严重问题。同一套主题颜色在工程里存了三份。

第一份在 term-config.js 的 THEMES 对象里,每套带 bg、fg、cursor、sel 与 ansi 十六色,共 20 个值,主进程用它做配色名校验与配置回显。第二份在 styles/wezterm.css 的根选择器里,26 个变量:4 个 terminal 基色、16 个 ANSI 槽、6 个 ui 变量(多出来的第六个是 --ui-mask)。第三份在 styles/themes 目录的六份 CSS 里,每份 25 个变量(比主样式少了 --ui-mask)。

三份都在定义颜色,但数量各不相同:20、26、25。这种「多处定义同一份事实」的结构本身就是风险,而实测已经证明风险已经变现。

把主样式的 26 个变量与 dracula.css 的 25 个逐个比对,23 个一致,2 个不一致:

主样式 :--term-bg: #1e1f29    --term-cursor: #f8f8f0
Dracula :--term-bg: #282a36    --term-cursor: #f8f8f2

背景色差了 10 个色阶(从 1e1f29 到 282a36),光标色差了一个色阶。这就是漂移的实证:主样式当初可能是一个自定义的深色值,后来主题文件按官方 Dracula 的标准色写,两边没有对齐。

为什么这个问题到今天没被用户发现?因为页面加载时 link 标签已经指向 dracula.css,而它同样选中根选择器,后加载的样式会覆盖先加载的同名变量。所以运行时–term-bg 实际取的是 #282a36,主样式里那个 #1e1f29 从来没生效过。它是一句死代码,静静躺在那里,等着某一天有人真信了它。

term-config.js 的头注释对这件事是有承诺的:配色在样式表里也是同一份数据,check-wezterm.js 会逐个主题比对,防止两边漂移。

但这个脚本在整个仓库里不存在。把工程目录递归扫一遍,没有任何名字带 check 的业务文件;app 目录下只有 engines、samples、styles 三个子目录和五个文件,没有校验脚本。也就是说,这项防护目前是空的,两边一致完全靠人工纪律。

我手工比对了一遍 term-config.js 的 Dracula 与 dracula.css,二十个值逐字相同,所以 JS 与主题文件这一对当前是一致的。但六个主题共 120 个双份值,靠人眼守是不可能长久的——改一个主题色时漏改另一处,不会有任何报错,只会在某个换主题的瞬间被用户发现。加上主样式里那两份已经漂移的值,修法和优先级都很清楚:要么把主样式里的颜色变量删干净、只留结构与尺寸,要么真的把 check-wezterm.js 补上并纳入构建。前者更彻底,后者更省事,但不能一直两头都不做。

还有一个细节值得记下:term-config 导出的 themeVars 函数是用来生成 CSS 变量文本的,但在整个工程里没有调用者——它定义一次、导出一次,就这样结束了。真正在用的路径是改 link 的 href。这个函数大概是「当初想用内联样式实现,后来改成切文件但函数没删」的残留。如果当初真的用了它,三份数据就会变成两份,漂移的机会就少一半。

3.6 滚动历史与历史内搜索

终端的历史有两个方向:纵向是行数(2000 行滚动回看),横向是一行内部的列。纵向方向由 viewOff 一个整数掌控,它表示「当前视窗底部距最新内容往下滚了几行」。

滚动的实现只有三行:

Session.prototype.scrollBy = function (n) {
  var pane = this.pane(this.activeTab());
  if (!pane) return { ok: false, error: '当前没有可用的终端窗格' };
  var total = pane.screen.scroll.length + pane.screen.rows;
  var maxOff = Math.max(0, total - pane.screen.rows);
  pane.viewOff = Math.max(0, Math.min(maxOff, (pane.viewOff || 0) + (n | 0)));
  return { ok: true, viewOff: pane.viewOff };
};

两行值得细看。第一行算上限:total 是历史行数加当前屏行数,maxOff 是 total 减当前屏行数,也就是历史行数。当历史为空时 maxOff 为 0,viewOff 夹到 0,滚轮无效——这是对的,没历史可翻。

第二行是累加后夹紧。注意是「先加后夹」而不是「先判断再加」,这样无论一次滚多大(比如触控板一口气滑出 50),也不会越界。delta 在渲染层被统一成三行,而不是直接传像素:

$('panes').addEventListener('wheel', function (e) {
    e.preventDefault();
    act('term:scroll', { delta: e.deltaY > 0 ? -3 : 3 });
  }, { passive: false });

这里有两层设计。第一层是归一化:不同设备的 deltaY 可以从 1 到几百不等,传到主进程只会造成行为不一致。固定成三个行,触控板与鼠标滑轮的手感就统一了。第二层是方向:deltaY 大于零是向下滚,对应 viewOff 减三,也就是向最新的内容靠;小于零是向上滚,viewOff 加三,向更早的内容靠。这个映射如果写反,用户会立刻发现——向上滚却看到了更新的内容,是典型的「滚动反转」。

跳到具体行则要反向换算:

Session.prototype.scrollTo = function (row) {
  var pane = this.pane(this.activeTab());
  if (!pane) return { ok: false, error: '当前没有可用的终端窗格' };
  var total = pane.screen.scroll.length + pane.screen.rows;
  var maxOff = Math.max(0, total - pane.screen.rows);
  var off = total - pane.screen.rows - (row | 0);
  pane.viewOff = Math.max(0, Math.min(maxOff, off));
  return { ok: true, viewOff: pane.viewOff };
};

这里有一个容易看漏的对应关系:scrollTo 算出的 off 公式与 scrollBy 的 maxOff 完全同形,都是 total 减 rows 再减 row。把 row 取 0(最顶上一行)代入,off 等于 scroll.length,正好是 maxOff;把 row 取 scroll.length(当前屏第一行)代入,off 等于 0,回到最新。两端都对上了,说明两个函数用的是同一个坐标系。

这个一致性不是巧合——它是搜索功能能正常工作的前提。因为搜索返回的行号就是快照里的行号,点一条结果直接拿这个行号去 scrollTo,不需要再换算一次:

Session.prototype.search = function (q) {
  var pane = this.pane(this.activeTab());
  if (!pane) return { ok: false, error: '当前没有可用的终端窗格' };
  var needle = String(q == null ? '' : q);
  if (!needle) return { ok: true, total: 0, hits: [], rows: 0 };

  var snap = pane.screen.snapshot();
  var low = needle.toLowerCase();
  var hits = [];
  for (var i = 0; i < snap.lines.length; i++) {
    var text = snap.lines[i].map(function (g) { return g.t; }).join('');
    if (text.toLowerCase().indexOf(low) < 0) continue;
    hits.push({ row: i, text: text.replace(/^\s+/, '').slice(0, 160) });
    if (hits.length >= 200) break;
  }
  return { ok: true, total: hits.length, hits: hits, rows: snap.lines.length, more: hits.length >= 200 };
};

这个函数里有四个保护,每一个都是必要的。

第一,先把每行拼成完整字符串再搜,而不是逐格子搜。因为搜的词可能跨格,也可能跨样式段(比如一半字是粗体)。逐格子搜会漏掉跨段的匹配。

第二,统一转小写再比。这里用的是 toLowerCase 而不是正则的 i 标志,原因是模式里可能有正则元字符,比如用户搜 a.b,拿它直接构造正则就会把点当成通配符。用 indexOf 加 toLowerCase 等价于「纯字面量、不区分大小写」,这正是用户想要的。

第三,每条命中截到 160 字符,并去掉行首缩进。为什么不去行尾?因为行尾的空白会让列表看起来参差不齐。为什么截 160?因为 80 列宽的终端输出经过折行后,一段实质内容很少超过两行。

第四,最多 200 条并给出 more 标记。界面上的文案直接用了这个标记:「命中 N 行(只列前 200 行)」。200 这个数的选择有讲究:一次搜索要把 2000 行历史全部转成小写再 indexOf,在按一次回车的前提下这是可接受的;但把 2000 条结果都渲染成 DOM 节点就会卡。搜索在数据层收口,界面渲染就不会失控。

还有一个容易被忽略的设计:搜索不做高亮。注释里说得很直接——只报行号与行首内容,不自己做高亮。高亮意味着要返回每个匹配的位置,而位置又要跨样式段换算,复杂度和风险都比收益大。当前做法是用户点一条结果,视图直接跳到那一行(并带上滚动偏移提示),自己看。这是有意识的减法。

导出记录用了同一套快照,但做了两步清理:

Session.prototype.transcript = function () {
  var pane = this.pane(this.activeTab());
  if (!pane) return '';
  var snap = pane.screen.snapshot();
  var out = [];
  for (var i = 0; i < snap.lines.length; i++) {
    out.push(snap.lines[i].map(function (g) { return g.t; }).join('').replace(/\s+$/, ''));
  }
  return out.join(String.fromCharCode(10));
};

第一步是把格子拼回字符串,第二步是去掉每行行尾的空白。为什么一定要去行尾?因为终端的每一行都是定宽的——第 30 列有了内容,后面 50 列就是空格。不去掉的话,导出的文本每行后面拖着几十个空格,粘进任何编辑器都会带一屁股尾随空白,编辑器的横向滚动条会一直向右。

注意这里用的是 String.fromCharCode(10) 而不是 ‘\n’。这个写法在工程里出现了不止一次(CRLF 常量也是这么拼的),目的很明确:不让源码里出现真正的换行转义字面量,避免在某些编辑器的自动格式或本行处理里被误处理。这是一个防呆写法,代价是可读性。

历史与快照之间还隔着一道闸,就是 MAX_ECHO:

var MAX_ECHO = 1200;      /* 一次快照最多给渲染层的行数,超出的折成提示 */

1200 这个数字是 UI 与内存的守门人。默认 80 列 24 行的视窗,1200 行相当于能回看 50 屏。超过之后,快照只给最后 1200 行,前面折成一条提示。这个限制的存在,直接决定了渲染层的 DOM 规模上限:1200 行乘行内的几个样式段,一块屏幕的重建量就在这个量级。

渲染端的对应处理在 renderBody:

function renderBody(host, pane) {
  if (!pane) {
    var empty = document.createElement('div');
    empty.className = 'term-line';
    host.appendChild(empty);
    return;
  }

  var lines = pane.lines || [];
  var base = lines.length - pane.rows;
  var cursorRow = base + pane.cursor.y;
  var showCursor = pane.cursor.visible && !pane.viewOff;

  for (var i = 0; i < lines.length; i++) {
    var at = (showCursor && i === cursorRow) ? pane.cursor.textIndex : -1;
    host.appendChild(lineNode(lines[i], at));
  }
}

这里有两个细节。第一,base 是当前屏第一行的绝对行号,光标位置 base 加 cursor.y 才能对上。这两个数分开存的原因:cursor.y 是屏内坐标(0 到 rows 减 1),lines 是历史加当前屏的合成数组,两者差一个偏移。

第二,showCursor 多了一个条件 !pane.viewOff。正在翻看历史时,光标不显示。这不只是为了好看——光标属于当前输入行,而正在看的可能是三小时前的内容,把光标画在那里会让人误以为还能在那里输入。隐藏它,语义上就是「你现在看的是快照,不是活的行」。

四、鸿蒙稳定性适配

4.1 缺陷台账:六条实测问题

这个工程的整体质量偏上:分层干净、界限诚实、错误提示到位。但把代码与配置逐字对过一遍,还是能挑出六条问题。按严重程度排序。

第一条,主题颜色存三份且已发生漂移。3.5 节已经展开:主样式 26 个变量、主题文件 25 个、term-config 里 20 个值,主样式与 dracula.css 之间有 2 个值不一致(–term-bg 与 --term-cursor),且注释里承诺的校验脚本在整个仓库不存在。严重性在于它完全无声:没有报错、没有警告、界面上看不出任何异常,只有哪天有人把 link 标签的默认值改掉或删掉,1e1f29 这个从没生效过的值就会突然生效,用户会看到颜色莫名变了。

第二条,签名材料以本机绝对路径写进工程,密钥口令也在里面。三个路径都指向 C:\Users\ws199.ohos\config\ 下的文件,keyPassword 与 storePassword 是两串 IDE 加密过的十六进制。这把工程锁在了这一台机器上,同时把签名私钥的解锁材料一起进了仓库。上架前必须改成环境变量或签名配置外部化。

第三条,控制串切分逻辑存在两份独立实现。一份在 term-vt.js 的解析器里,一份在 term-screen.js 的 stringWidth 里。后者只做跳过不做解析,所以当前两边不会矛盾,但它是一份重复的判定规则(终结字节区间 0x40 到 0x7e)。一旦有人调整解析器的区间而忘了另一个,就会出现「屏幕显示正常但光标位置算错」的隐性故障——这类 bug 在真机上极难复现。

第四条,导出表里有两个零调用符号。把七个引擎的 module.exports 全部展开,一共 57 个导出符号。按「定义一次 + 导出表登记一次 = 两次出现;第三次才是真实调用」这个口径扫一遍,isLeaf 与 themeVars 两个都只有两次出现,即零调用。数量不大,但说明导出面没有回头收过。

第五条,权限清单是模板继承来的,与终端功能无关的条目占绝大多数。web_engine 模块的 requestPermissions 一共 26 条,其中 11 条带 reason 与 usedScene(用户授权类),15 条不带。这个应用真正用得上的只有三条:READ_WRITE_DOCUMENTS_DIRECTORY(导出记录到文档目录)、READ_PASTEBOARD(粘贴)、FILE_ACCESS_PERSIST(目录授权持久化)。剩下的 23 条里包括摄像头、麦克风、位置、蓝牙、陀螺仪、加速度计、屏幕捕获、生物识别、打印——一个终端应用为什么要申请屏幕捕获权限?审核时这是需要解释的。另有一条 WEB_NATIVE_MESSAGING 被注释掉了,旁边的注释写得很好(系统权限不可在 requestPermissions 中自定义声明),说明作者知道这个坑,只是没把其他与业务无关的条目一起清掉。

第六条,配置文件的尾逗号一共 10 处。这不是致命错误,因为 json5 允许尾逗号,构建也能过。但它是写法不统一的信号:6 个文件里 10 个位置有尾逗号,分布是 electron 模块的 build-profile 3 处、oh-package 1 处、module.json5 3 处、web_engine 模块的 build-profile 1 处、oh-package 1 处、module.json5 1 处。如果哪天有人把其中某个文件改成严格 json 解析,就会报错。

六条里前两条必须在上架前处理,第三条与第四条建议顺手清理,第五条要逐条判断能否删,第六条格式统一即可。

4.2 三个典型根因

把六条缺陷往上追一层,能归到三个根因。

根因一:模板继承而不裁剪。bundleName 是 com.huawei.ohos_electron 而不是 com.huawei.ohos_wezterm,vendor 是 example,权限表里有屏幕捕获与蓝牙,这四件事指向同一个事实——整个工程是从一套壳模板拉下来的,拉下来之后只改了业务代码,没有回头收模板。这在批量适配里是效率最优的选择(否则每个应用都要重新调一遍壳),代价是每个产物都带着一份自己用不上的权限。

正确的做法不是一次删干净,而是分层:把 26 条分成「本应用必需」「壳层通用」「本应用永不需要」三类,第一类保留并写清 reason,第二类保留,第三类删。这个分层工作一次做完,后面的项目都能复用。

根因二:同一份事实存在多处,但缺少单一真相源。主题颜色存三份是典型例子;同类例子还有 cols 的上下限(main.js 的 MIN_COLS 与 MAX_COLS、term-screen 的 clamp 参数、渲染层的 clamp 参数,三处都写了 20 与 400);MAX_ECHO 与滚动历史默认值也分散在几个文件里。

这类问题的判据很简单:如果一个数字或一组值在两个以上的地方出现,就必须问「它们一致吗」。能合并就合并(像 term-shell 的命令表那样,一份数据两个用途),不能合并就必须加自动校验。当前工程在命令表上做对了,在主题与常量上没做。

根因三:快照全量替换的渲染模式。这一条不是代码写错,而是架构选择带来的必然成本。渲染层的核心函数只有三行:

function renderPanes(snap) {
  var host = $('panes');
  clear(host);
  host.appendChild(buildNode(snap.tree, snap));
}

清空、重建。而 applySnapshot 在每一次按键后都会被调到:用户按下一个字符,主进程执行 inputText,生成新快照,渲染层把整个终端区拆了重搭。

这个成本可以算。MAX_ECHO 是 1200,意味着一份快照里最多带 1200 行;可见区域只有 rows 行(默认 24)。也就是说,为了显示 24 行内容,渲染层每次要重建 1200 行、每行若干个 span。把这 1200 行全部拆掉再建回来,只为让光标向右移动一格。

这个设计在什么条件下可接受?当设备性能充裕、单行段数少时,1200 行的 DOM 重建在一次按键的预算内能跑完,用户感知不到。在鸿蒙的中低端 PC 上,这个预算就没那么宽裕了。要改进不难:只重建可见窗口内的行,历史行滚动时再增量渲染;或者利用快照里的行文本做脏检查,没变就不重建。但这两条都要求快照里带上行版本号或行哈希,当前快照没有这些字段。

4.3 样式禁项与尺寸度量

鸿蒙渲染层的 CSS 限制被写成了样式表的第一段注释,只有两行:

/* WezTerm 终端工作台 —— 布局与配色
 *
 * 鸿蒙渲染层限制:不用 position:fixed、@keyframes、animation、transition、transform;
 * 颜色只走变量,规则体里不写裸色值。主题文件只覆盖 :root 里的变量,结构不动。
 */

这两行不只是声明,它是一份可验证的契约。把这五个禁词在 698 行的样式表里逐个数一遍:position:fixed 出现 1 次、@keyframes 1 次、animation 1 次、transition 1 次、transform 1 次——每一次都落在那行注释里。规则体里一次都没有。

这是很难得的自律。CSS 动画是终端界面里最容易被随手加上的东西(光标闪烁、滚动缓动、新行淡入),而每一条都在禁词表里。从视觉效果上看这套界面确实保守:没有任何动效,切换主题是瞬时切换,滚动是一下跳三行。但这正是平台约束下唯一干净的做法——与其写一段在某些设备上不生效、在另一些设备上掉帧的动画,不如不做。

布局靠 grid 与 flex:display:grid 出现 9 次、display:flex 出现 16 次。整体是一个三行网格(顶栏、主区、状态栏),主区再用横向网格分两栏(终端区加右栏),窗格树则在终端区内递归嵌套 flex 容器。position:fixed 的替代品是 height:100vh 加 overflow:hidden 的外层网格,这也是为什么滚动条只能出现在终端区内部而不能出现在页面上。

颜色一律走变量。整个样式表里引用 var(–ansi-*) 共 32 次,构成 16 组前后景:

.f3 { color: var(--ansi-3); }
.b3 { background: var(--ansi-3); }

前 16 个类管颜色,后 16 个管底色。渲染层只需给出 f3 b11 这样的类名组合,具体的颜色值由当前主题决定。这是一个非常干净的关注点分离:屏幕模型只知道索引,样式表只知道变量,谁也不知道对方的具体值。

尺寸度量是这套界面里最容易被低估的一段。终端的列行数不能写死,必须从真实字符尺寸算,而字符宽又取决于当前字体与字号:

function measureFont() {
  var host = $('measure');
  clear(host);

  var span = document.createElement('span');
  span.textContent = 'MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM';
  host.appendChild(span);
  var w = span.getBoundingClientRect().width / 40;
  if (w > 0) state.charW = w;

  var probe = document.createElement('div');
  probe.className = 'term-line';
  probe.textContent = 'M';
  host.appendChild(probe);
  var h = probe.getBoundingClientRect().height;
  if (h > 0) state.lineH = h;

  clear(host);
}

量字符宽用的是四十个 M。为什么不是量一个 M 再直接取?因为单个字形的宽度会带亚像素舍入,量一个字的误差可能是 0.3 像素,乘上 200 列就是 60 像素的偏差——足够多出一列或丢掉一列。四十个字的宽度总和除以四十,误差被摊薄了四十倍。

量行高则是另一套思路:一个 M 放在一个 term-line 里,量 div 的高度。因为行高由 CSS 的 line-height 与 padding 决定,不是字形本身的高度,所以必须量包着字的容器而不是字本身。两个度量分开写,是因为它们量的是不同的东西。

量完之后的结果用 clamp 夹住再用:

var cols = clamp(Math.floor(box.w / state.charW), 20, 400);
var rows = clamp(Math.floor(box.h / state.lineH), 6, 200);

下游取整(Math.floor)而不是四舍五入。如果四舍五入,宽度除以字符宽得 79.6 会变成 80 列,而实际放不下 80 列,最后一列就会被挤出去。取整后得 79,宁可少一列也不溢出。

还有一个容易被忘的点:字体度量必须在字体加载完成后做。boot 里先拿 app:info、再渲染清单、再调 measureFont,最后才开始算列行。如果字体是异步加载的,量到的可能是回退字体的宽度,字一换列数就不对了。当前用的是系统字体栈(HarmonyOS Sans SC 加两个回退),不存在异步加载问题,所以这个顺序是安全的;但哪天换成自定义字体文件,这里就会变成一个陷阱。

4.4 上架前必须替换的四类内容

第一类是应用标识。bundleName 必须从 com.huawei.ohos_electron 改成这个应用自己的包名,vendor 从 example 改成真实厂商,versionCode 与 versionName 要和上架信息一致。注意 bundleName 改了之后,prefsPath 会跟着变(因为它基于 app.getPath(‘userData’)),已安装旧版本的偏好文件不会被自动迁移。如果已经有用户在用,需要写一个迁移。

第二类是权限清单。26 条要逐条判断:保留 READ_WRITE_DOCUMENTS_DIRECTORY(term:save 要写文档目录)、READ_PASTEBOARD(粘贴),以及壳层运行必需的几条;删掉摄像头、麦克风、位置、蓝牙、陀螺仪、加速度计、屏幕捕获、生物识别、打印这些与终端无关的。每一条保留的权限都应该能对应到一段具体代码,对不上的就不该在表里。

第三类是签名材料。把 certpath、profile、storeFile 三个本机绝对路径改成构建机可配置的形式,把 keyPassword 与 storePassword 从工程文件里拿出去。当前它们的值是 IDE 加密过的,泄露风险比明文低,但依旧是「拿到工程就拿到签名能力」的状态,不适合进公共仓库。

第四类是主题数据。三份颜色定义必须先统一:主样式的 :root 里那 26 个变量如果要留,就必须与主题文件逐值对齐;更干净的做法是主样式只留结构与尺寸,颜色全部交给主题文件,并在 term-config 里也删掉冗余的颜色值、只留主题名与显示标签。做完这一步,注释里那个不存在的 check-wezterm.js 也就可以真的补上了——一个二十行的脚本,读 term-config 的 THEMES、读六份 CSS、逐值比对、不一致就非零退出,接进构建就完事。

五、构建与部署

图 1 鸿蒙 PC 真机上的主界面。顶栏从左到右依次是品牌区(logo、标题「WezTerm 终端工作台」、副标题「VT 解析 · 分屏 · 内置命令」)、标签栏与九个按钮(新标签、关标签、左右分屏、上下分屏、关窗格、搜索、配置、导出记录、重置)。终端区左上角窗格标题写的是「终端 · pty」,右上角显示当前目录 /home/wez;屏幕里是启动 banner 三行(青色粗体的欢迎行加两行灰色的能力说明与操作提示),下面提示符为 wez@harmony:~$。左下提示栏固定列着四组快捷键:Tab 补全、Ctrl+C 中断、Ctrl+L 清屏、PageUp/PageDown 翻历史、滚轮滚动。右栏分三块:配色面板列出六个主题按钮,Dracula 当前高亮;内置命令面板标着 49 条并逐条列出名称与说明;已知限制面板把本章前面引用的六条原文全部展开。最底部状态栏左侧写着「就绪 · 201×42 · 1 个窗格」——这两个数字是本文最有说服力的自证之一,代码里 cols 与 rows 的默认值是 80 与 24,而真机上因为 measureFont 真的量了字体、clamp 真的把结果夹在了 20 到 400 与 6 到 200 的区间内,才得到了 201 列 42 行。只要这两个数字不是 80 乘 24,就说明尺寸度量那条链路是真跑通的。

图 2 状态栏右下角「关于」弹出的是一个 modal,内容分三段。第一段「开源声明」说明本项目基于开源社区的 WezTerm 终端模拟器项目,遵循其原有开源协议,并明确写了本应用为独立开发的鸿蒙平台适配版本,与上游项目无隶属关系。第二段「免责声明」说明本应用按现状提供、不提供任何明示或默示担保,且内置解释器与内存文件系统不执行真实系统命令。第三段「完全开源」则注明源代码完全开源、可自由审查与分发。三段都是纯文本,没有链接按钮,也没有跳转——这与 CSP 只有四条(没有 connect-src、没有 frame-src)是同一个取舍:不给自己留任何出网的口。对一个声明自己「没有 pty」的终端应用来说,这份声明的可信度恰好来自它在技术上也真的做不到那些事。

图 3 在终端里执行 help 后的输出。命令按组分区:可见文件组尾部(head 到 dirname 共 20 条)、系统组全部 10 条(ps、free、uptime、env、export、unset、which、type、alias、unalias)、WezTerm 专属组 5 条(wezterm、config、theme、demo、man),每条都是等宽对齐的「命令名 + 中文说明」两列。最后一行输出的是解释器支持的结构:「管道 | 、重定向 > >> < 、顺序 ; 、短路 && ||、$变量」,这行文字与 term-shell.js 文件头的注释逐字对应。三处可以互证:右栏顶部写着「内置命令 49 条」,与代码里 COMMANDS 数组的长度逐字相符;右栏的「已知限制」六条与主进程 boundaryList 函数返回的六条字符串完全一致;状态栏左侧仍然是「就绪 · 201×42 · 1 个窗格」。需要说明的一点是:这张截图右下角显示 v1.8.0,而当前工程的 package.json 里 version 字段已经是 1.0.0,说明截图早于那次版本号调整。这一版本文本来自 app.getVersion(),与鸿蒙侧的 app.json5 里的 versionName 是两套独立的值。

5.1 产物与构建日志

构建产物的两个文件:签名的 195348900 字节,未签名的 193887985 字节,差 1460915 字节。这个差值只占签名的 0.75%,是 HarmonyOS 签名块(证书链、摘要、对齐填充)自身的体积。对接近 200 MB 的包而言,签名的开销可以忽略不计。

构建日志在 .hvigor/outputs/build-logs/build.log,1111242 字节,12978 行。全库只有七次构建成功、零次失败,ArkTS 编译告警 2383 条。七次的耗时与时间点如下:

序号时间耗时
12026-11-16 15:30:413 s 841 ms
22026-11-16 15:32:054 s 248 ms
32026-11-16 15:34:094 s 212 ms
42026-11-16 15:36:284 s 420 ms
52026-11-16 15:39:293 s 976 ms
62026-11-17 15:11:2117 s 279 ms
72026-11-17 15:21:513 s 663 ms

这张表里有一条值得单独看。前五次集中在 2026 年 11 月 16 日的十分半钟内(15:30 到 15:39),耗时稳定在 3.8 到 4.4 秒之间,这是增量构建的速度。第六次跳到了第二天的 15:11,耗时 17.279 秒,是前五次平均值的 4.3 倍;第七次在十分钟后,又回到了 3.663 秒。

跨天那次变慢不是偶然。前端工程都有增量缓存,隔一夜之后 IDE 可能做了清理、也可能构建缓存被回收了,于是第六次跑了接近全量。而第七次只改了很少东西,缓存又热了,所以回到了 3.6 秒。这个模式说明:这个工程的构建速度主要取决于缓存命中而不是业务代码量——175 KB 的 JavaScript 源文件根本不是构建的瓶颈。

真正决定构建时间的是 ArkTS 编译那一步,而它与权限表、模块个数相关,与壳内加载的 JS 无关。这也解释了一个现象:把这套壳从 Vokoscreen 换成 WezTerm,构建速度几乎没变——因为它们运行的是同一套带 Electron 的鸿蒙宿主。

2383 条 ArkTS 告警需要单独说一句。它们全部来自 web_engine 与 electron 两个模块的 ArkTS 代码,与 app 目录下的 JavaScript 无关。这些告警是模板自带的,七次构建里数量没有变化,也没有升级为错误——说明它们属于「能过但不够干净」的一类。上架前不必逐条清理,但应该抽测一遍,确认没有涉及权限、生命周期、内存泄漏这三类的告警。

5.2 体积构成:百分之八十九在原生库上

把签名的 195348900 字节拆开,四份原生库占了绝大部分:

文件字节占签名产物
libelectron.so16747191285.73%
libadapter.so26212001.34%
libffmpeg.so21815281.12%
libc++_shared.so18256240.93%
四库合计17410026489.12%
其余(ArkTS、资源、壳内 JS 等)2124863610.88%

壳内那 175272 字节的 JavaScript 应用代码,在 195 MB 的产物里占 0.09%——不到千分之一。把这套壳换成一个更大的应用,产物体积几乎不会变。这是 Electron 壳方案最本质的特征:体积由运行时决定,不由业务决定。

四份库里最大的一份 libelectron.so 在进包之前做过剥离。剥离前的文件在仓库根目录的 lib.unstripped 下,1143668440 字节;剥离后的 167471912 字节,只剩原来的 14.64%,砍掉 976196528 字节,约合 931 MB。同样,libadapter.so 从 15494016 字节降到 2621200 字节,只剩 16.9%。

这两个剥离比例说明一件事:符号表与调试信息在 Electron 的这两个库里占了八成以上。如果不剥离,单个包的体积会超过 1.1 GB,在应用市场根本过不了体积审核。剥离之后 1.1 GB 变成 174 MB,这才是能发的包。

剥离开关就是这个工程里那句 collectAllLibs: true 的配合。它保证 lib.unstripped 里的原始库能被构建链路看到、被剥离、被收进产物,而不是在依赖分析那一步被跳过。如果这个开关关掉,产物里可能只剩一个 libc++_shared.so,运行时一加载就崩——而构建依旧是绿色的,这正是这类问题最阴险的地方。

libffmpeg.so 与 libc++_shared.so 两份库与终端功能一点关系也没有:前者是媒体解码,后者是 C++ 运行时。它们之所以在包里,是因为 Electron 壳依赖它们。这是壳方案的又一个代价:每个应用都要为一份自己可能用不上的运行时付费。

5.3 权限清单与设备形态

web_engine 模块的权限表里,requestPermissions 一共 26 条,按顺序是:INTERNET、GET_NETWORK_INFO、ACCESS_CERT_MANAGER、RUNNING_LOCK、PRINT、PREPARE_APP_TERMINATE、ACCESS_BIOMETRIC、FILE_ACCESS_PERSIST、PRIVACY_WINDOW、WINDOW_TOPMOST、GYROSCOPE、ACCELEROMETER、SET_ABILITY_INSTANCE_INFO、GET_FILE_ICON、LOCK_WINDOW_CURSOR、READ_PASTEBOARD、READ_WRITE_DOWNLOAD_DIRECTORY、READ_WRITE_DOCUMENTS_DIRECTORY、READ_WRITE_DESKTOP_DIRECTORY、LOCATION、APPROXIMATELY_LOCATION、LOCATION_IN_BACKGROUND、MICROPHONE、CAMERA、ACCESS_BLUETOOTH、CUSTOM_SCREEN_CAPTURE。

其中前 15 条不带 reason 与 usedScene,后 11 条带。带的那 11 条全部指向同一个 abilities 字段 FormAbility、同一个 when 取值 always:

{
  "name": "ohos.permission.READ_WRITE_DOCUMENTS_DIRECTORY",
  "reason": "$string:documents_dir",
  "usedScene": {
    "abilities": [
      "FormAbility"
    ],
    "when":"always"
  }
}

这里有一个必须提的细节:usedScene 里写的 FormAbility 在当前的模块配置里并不存在。electron 模块声明的三个 ability 是 EntryAbility、BrowserAbility、StatelessAbility,没有 FormAbility。这又是模板残留的痕迹——权限表是从别的工程拷过来的,连 usedScene 里的 ability 名都没改。审核时这一项是可以被逐条比对出来的。

真正与终端业务对得上的权限只有三条。READ_WRITE_DOCUMENTS_DIRECTORY 对应 term:save(保存对话框默认落在 app.getPath(‘documents’)),READ_PASTEBOARD 对应 onPaste 那条链路(Ctrl+V 与右键粘贴),FILE_ACCESS_PERSIST 对应文件选择后的目录授权持久化。

剩下的 23 条里,与终端完全无关的有:CAMERA(不拍照)、MICROPHONE(不录音)、LOCATION 三条(不定位置)、ACCESS_BLUETOOTH(不连蓝牙)、GYROSCOPE 与 ACCELEROMETER(不读传感器)、CUSTOM_SCREEN_CAPTURE(不录屏)、ACCESS_BIOMETRIC(不验证指纹)、PRINT(不打印)。一个终端仿真器申请录屏权限,在隐私审核里是很难自圆其说的。

定义权限只有一条,且是自定义的:

"definePermissions": [
  {
    "name": "ohos.permission.LOCK_WINDOW_CURSOR"
  },
]

同一个名字在 requestPermissions 里也出现了一次(第 15 条),两处配对。这项权限对应的是「锁定窗口光标」——终端界面自定义光标形状时需要它,与图 1 里那个方块光标是对得上的。这是整套权限表里唯一一条能看出业务性的自定义权限。

设备形态写的是 2in1 与 tablet,两个模块一致。没有 phone 的声明,意味着这个包不会出现在手机上——这对终端应用是对的,因为手机的软键盘与终端的光标定位存在结构性冲突。

模块结构上,electron 是 entry 模块,web_engine 是 har 模块,没有 feature 模块,也没有动态共享库。两个模块的 deviceTypes 顺序不同(electron 是先 2in1 后 tablet,web_engine 是先 tablet 后 2in1),不影响语义,但也是一个「同一份事实写两处」的小例子。

六、常见问题与解决方案

Q1 为什么只按了一个字符,整个终端区都重建了一遍?

问题现象:终端里输出多、历史长的时候,打字开始发粘。每按一个键都有一瞬的顿感,按下退格连删十几个字符时尤其明显,而 CPU 占用并不高。

根因分析:每个可见字符都要走一次 term:input,主进程返回一份新快照,渲染层的 applySnapshot 接着调 renderPanes——而 renderPanes 只有三行:清空容器、重建整棵树。快照里带的不是可见的那 24 行,而是 MAX_ECHO 允许的 1200 行。也就是说,为了把光标向右推一格,渲染层要拆掉并重建 1200 行、每行若干个样式片段。成本与「你看到的内容」无关,与「你快照里带了多少历史」成正比。

解决方案:三条路可以选。最小改动是把 renderBody 的循环限定在可见窗口内(从 base 开始取 rows 行),历史行在滚动时再补;中等改动是给快照的每一行带上版本号或文本哈希,渲染前对比、没变就不动那个节点;彻底改动是改成活行与历史行两个容器,打字只重绘当前输入行。三条都需要快照结构先支持,所以这类优化最好在快照格式定案之前就想清楚。

教训:任何「全量替换」的渲染模式都要先问一句「这里传的到底是可见区,还是全部数据」。一旦快照里带的是上限定量的历史,而渲染又把快照全量落地,性能就会与数据量而不是与屏幕大小挂钩。

Q2 为什么 256 色的图表搬过来,变成了 16 色色块?

问题现象:本机终端里用真彩色画的分层图、热力图、带渐变的进度条,在这个壳里全部变成一两层平涂色块,层次完全看不清。

根因分析:屏幕模型的每个格子只存两个颜色索引(前景、背景),不存 RGB。于是 256 色与真彩色进来时必被量化到 16 个槽位,方法是欧氏距离取最近。这件事的失真是可精确计算的:量化基准的 PALETTE 分量只取 0、92、127、205、229、238、255 七个数,而 256 色立方段的分量只取 0、95、135、175、215、255 六个数,两者交集只有 0 与 255。所以 216 个立方色里只有纯黑与纯白能精确保真,24 个灰阶一个不保,整体上 256 个输入色有 254 个会在量化时偏移。

解决方案:这不是待修的 bug,是存 16 索引的必然代价,正确做法是把它写成界面上的「已知限制」(这一条已经写了)。如果确实需要更多颜色,只有一条路:把格子结构从「两个索引」改成「两个色值」,但那样每个格子的内存从几个字节涨到十几个字节,且换主题时历史内容不再跟着变色(因为颜色已经定死了)。这是一个「颜色保真」与「换主题时历史跟着变」之间的单选。

教训:任何量化的决策要先算一遍失真率再定。算出「216 个里只有 2 个能保真」这个结论之后,是否接受就很清楚了;不算就去做,会在用户抱怨「颜色不对」时才发现根子在哪。

Q3 为什么改了主题 CSS 里的颜色,界面上一点变化都没有?

问题现象:想调一下背景色,改了 wezterm.css 里 :root 的 --term-bg,重启应用,背景还是原来的颜色。把那个值改成醒目的红也毫无反应。

根因分析:同一套颜色在工程里存了三份:主样式 wezterm.css 的 :root(26 个变量)、主题文件 dracula.css 等(25 个变量)、term-config.js 的 THEMES(每套 20 个值)。页面加载时 link 标签指向 dracula.css,它同样选中根选择器,后加载的样式会覆盖先加载的同名变量。所以主样式里那个 --term-bg 从来没生效过。实测主样式写的是 #1e1f29,而 dracula.css 是 #282a36、term-config 里也是 #282a36——两份已经漂移,只是没人发现。

解决方案:二选一。要么把主样式里的颜色变量删干净、只留结构与尺寸,颜色完全交给主题文件,同时把 term-config 里的颜色值也删掉只留主题名;要么保留三份但补上自动校验。注释里提到了一个做这件事的 check-wezterm.js,但它在仓库里不存在。造一个二十行的脚本就能补上这个缺口。

教训:当你在一个 CSS 变量上改了没效果时,第一个该查的不是浏览器缓存,而是「还有哪一处也定义了同名变量」。同一份事实存多处而不加校验,必然会出现「改了不生效、看起来像缓存」的假象。

Q4 为什么光标不闪烁,滚动也没有缓动?

问题现象:用惯了别的终端的人第一反应是「这光标是不是卡住了」——它不动。滚轮一滑,内容是瞬跳三行,没有平滑滑动。换主题也是瞬间切,没有渐变。

根因分析:鸿蒙渲染层对 CSS 动画与过渡有限制。这一条被写成了样式表的第一段注释,列为硬禁项:不用 position:fixed、@keyframes、animation、transition、transform。把五个词在 698 行样式表里逐个数,全部只出现在那行注释里,规则体里一次都没有。光标那个方块是靠类名切换实现的静态样式,不是动画。

解决方案:不做。与其写一段在某些设备上不生效、在另一些设备上掉帧的动画,不如全不做,把一致性放在视觉顺手前面。同一条限制也解释了另外两个现象:不能有 position:fixed,所以不能做悬浮的临时提示(只能用固定在网格行里的 hint-bar);不能有 transform,所以主题切换只能是切文件而不是交叉淡入。

教训:平台限制最好写成可验证的契约——一句注释列出禁词,然后用一行命令数一遍。能数出来是零,才算真的遵守了;只写「我们不用动画」但不核对,半年后就会有人加一个 transition。

Q5 为什么中文字符和表情符号会把后面的内容挤歪?

问题现象:英文界面一切正常,一旦输出里带中文,或者命令输出里有表情符号,光标位置就开始偏,行尾折行位置也不对,粘出来的副本里多了空格。

根因分析:终端是等宽字符网格,但中文与表情符号在真实字形里占两列,ASCII 占一列。如果按「一个字符一格」算,中文字符后面的内容全部会往前错一格。这个壳用 widthOf 判宽度(十二段区间覆盖中文、韩文、全角标点、表情),并给宽字符留了第二列占位格。另外还要处理组合字符不占列、制表符按八的倍数补齐、代理对不能被拆成两个乱码。

解决方案:四条规则必须同时到位。一是 widthOf 的区间表要覆盖到实际会遇到的字符集;二是宽字符写入时占用两格,第二格标记为占位;三是 stringWidth 算宽度时把 ESC 开头的控制串整段跳过,否则提示符里的颜色序列会把光标推偏;四是循环里的步长要用 codePointAt 加 fromCodePoint 的 length,不能固定加一。

教训:终端里「一字符一格」是一个只在 ASCII 世界里成立的假设。写任何与列号、光标位置、折行相关的代码前,先把宽字符、组合字符、代理对这三种情况在纸上算一遍。

Q6 为什么配置里字号写了 99,界面报错却不给行号?

问题现象:在配置对话框里把字号写成 99,点应用,弹出一条「字号取值范围 10–28」,但没有行号。而写一个语法错的行,报错就带「第 N 行」。两种错误看起来不是一回事。

根因分析:这是两种不同性质的错。语法错能定位到行,所以报行号;值越界的话,语法是对的,只是数值超出范围,而范围校验发生在解析之后——那时行号信息已经不在数据结构里了。main.js 把这类错的 line 显式地写成 0,界面那边则判 e.line 为真才拼「第 N 行」,否则只显示原因:注释里写的是「不强行编个行号」。

解决方案:保留这个设计,并在用户的层面上做了一件事——不静默回落。很多配置系统遇到越界会默默换成默认值,用户以为自己改成功了。这个壳把越界也当错误上报,配不成就一个字不落盘,终端继续用上一份配置跑。宁可多一次报错,也不让用户产生「我改了但没生效」的疑心。

教训:校验失败的报错要区分「能定位的」与「不能定位的」,不能为了格式统一而编造位置信息。前者是帮助,后者是误导。

Q7 为什么构建是绿的、安装也成功,一启动就白屏?

问题现象:命令行里 BUILD SUCCESSFUL,包也能装进设备,点开图标却闪一下就没,或者白屏停在标题栏,日志里既没有 ArkTS 报错也没有 JS 报错。

根因分析:这是 Electron 壳最典型的故障面。构建链路的静态引用分析只看到 ArkTS 代码,看不到壳内 JavaScript 里 require 了什么,更看不到 libelectron.so 在运行时 dlopen 的 libadapter.so。如果 collectAllLibs 没有开,或者 lib.unstripped 里的原始库没有被正确剥离并收进产物,产物里就会缺 so——而缺 so 这件事发生在运行时,构建期一片绿色。

解决方案:三道检查。一是确认产物里的 libs/arm64-v8a 下四份库都在(libelectron、libadapter、libffmpeg、libc++_shared),字节数分别对得上 167471912、2621200、2181528、1825624;二是确认 build-profile 里 nativeLib 的 collectAllLibs 为 true;三是白屏时先看渲染进程的控制台,而不是只看构建日志——壳内 JS 的报错全在那里。

教训:只要引入了原生库,构建成功就不再是「能跑」的同义词。要把「产物里到底有哪些 so、每个多大」当成一条独立的验收项,而不是相信构建结果的颜色。

七、总结

WezTerm 终端工作台的适配,把一个「必须有 pty 才能成立」的命题拆成了四个可以被纯 JavaScript 完成的子命题,并把做不到的部分写进了三处互相独立的声明。它的功能面可以对照下表看:

能力实现方式对接点
终端仿真VT 六态解析器 + 字符网格term-vt.js 与 term-screen.js
颜色显示16 索引 + 主题 CSS 变量覆盖term-screen.js 与 styles/themes
多标签与分屏不可变窗格二叉树term-pane.js 与 term-session.js
命令执行49 条内置命令 + 内存文件系统term-shell.js 与 term-fs.js
管道与重定向三层解析(词法、阶段、管道)term-shell.js 的 tokenize 与 parse
配置Lua 子集解析与七字段校验term-config.js 与配置对话框
历史回看viewOff 偏移与快照term-session.js 的 scrollBy 与 scrollTo
历史搜索字面量匹配,最多 200 条term-session.js 的 search
记录导出快照转纯文本并清理行尾term-session.js 的 transcript
输入document 级键盘 + 输入法组合态兼容renderer.js 的 onKeyDown

三条最值得带走的关键经验。

第一,先把做不到的事写下来,再写做得到的。这个工程把「没有 pty」这件事写了三遍:主进程的边界清单、文件头的能力注释、界面上的已知限制面板。三处措辞不同、语义一致。这个动作的价值不只是告知用户,它同时在约自己的未来——一旦写了「不做假实现」,内部文件系统里就没法偷偷塞一个 ls /bin 的假目录,help 输出里也就不会出现一条实际上不存在的命令。

第二,把不可变用在规模可控的地方。窗格树用不可变结构,每次 split 与 close 都返回新树,让「改树、重算布局、移动焦点、更新计数」这四步变成原子操作。这个选择的成立前提是树的高度不会超过四层——人机交互里一个屏幕分八块已经很拥挤,所以复制代价可以忽略。反过来说,如果是一个可能长到几百个节点的树,同样的选择就会变成灾难。

第三,同一份事实只能有一个真相源,否则就必须有自动校验。命令表做得很好:一份数组既是解释器的注册表又是界面的帮助文档,两处永远不会对不上。主题颜色做得不好:三份数据、数量各不相同、已经漂移了两个值,而注释里承诺的校验脚本根本不存在。这两件事放在同一篇里对照看,规律就很清楚了:数据合并靠设计,数据分散靠工具,两样都不做就只能靠运气。

上架前的四件必做项:把 bundleName 从壳模板的默认值改成该应用自己的包名、把 vendor 从 example 换成真实厂商,并想清楚改名之后偏好文件不迁移的代价;把 26 条权限逐条对业务代码,删掉摄像头、麦克风、位置、蓝牙、传感器、屏幕捕获这些与终端无关的条目,并修正 usedScene 里那个并不存在的 FormAbility;把签名三件套的本机绝对路径与加密口令从工程文件里拿出去、改成构建机可配置的形式;最后把主样式、主题文件、term-config 三处的主题颜色收成一份,并把那个只存在于注释里的 check-wezterm.js 真的写出来接进构建。四件事做完,这个把它做不到的事情写在界面上的终端,才真正具备了发出去的条件。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐