@alickjoe/webterm 0.1.4

package/README.md

@@ -0,0 +1,158 @@
+# @alickjoe/webterm
+
+webterm 桌面客户端：用 Electron 把 webterm 网页包装成独立应用窗口（纯展示壳，不打包 exe/安装器）。
+
+内核即 Chromium，页面加载、Cookie、SSE、终端渲染与浏览器访问完全一致；仅 Cookie 分区独立、无浏览器扩展。
+
+## 安装
+
+```bash
+npm install -g @alickjoe/webterm
+```
+
+**Electron 运行时下载说明**：electron@44 官方包不再带 postinstall 自动下载，默认是首次运行 `webterm` 时才下载。本包已通过自带 postinstall 把下载**合并进 npm install 阶段**（失败不阻断安装，首次运行时会自动重试）。同版本二进制有用户级缓存（Windows `%LOCALAPPDATA%\electron\Cache`），升级重装只解压不重新联网下载。企业网络下载失败的修复见「Windows 企业网络」一节。
+
+## 使用
+
+```bash
+# 默认加载内置的线上地址（部署者通过 config.json / 构建参数设定）
+webterm
+
+# 临时指向其它地址（优先级最高）
+webterm http://127.0.0.1:3300/
+```
+
+## 配置
+
+目标地址优先级：**命令行参数 > 环境变量 `WEBTERM_URL` > `~/.webterm/config.json` > 内置默认值**。
+
+修改默认地址，创建 `~/.webterm/config.json`：
+
+```json
+{ "url": "https://<your-webterm-host>/" }
+```
+
+其它环境变量：
+
+| 变量 | 说明 |
+|---|---|
+| `WEBTERM_URL` | 覆盖目标地址 |
+| `WEBTERM_INSECURE_TLS=1` | 跳过 TLS 证书校验（仅公司自签证书链特殊时使用，有安全风险） |
+| `WEBTERM_REMOTE_DEBUGGING=9222` | 开启 CDP 远程调试端口（仅调试用，勿在不可信环境开启） |
+
+窗口尺寸/位置自动记忆到 `~/.webterm/window.json`。
+
+## 平台说明
+
+### Windows（主要目标平台）
+
+- 无需任何系统依赖，Electron 自包含。
+- **页面 TLS**：Chromium 读 **Windows 系统证书库**，与 Chrome/Edge 同源——企业 TLS 解密网关重签的证书由组策略下发的公司 CA 自动受信，**无需额外配置**。判据：浏览器能正常打开 webterm，本客户端就能。
+- 例外：非公司管控的个人电脑若无公司根 CA，会显示重试页，可临时用 `WEBTERM_INSECURE_TLS=1`。
+
+#### Windows 企业网络：Electron 二进制下载失败（fetch failed）
+
+Electron 二进制下载走的是 Node 内置 fetch（undici）——它**不读 Windows 系统证书库**，遇到企业网关重签的证书会报 `TypeError: fetch failed`（重跑 `webterm` 会自动重试）。
+
+修复（PowerShell）：
+
+```powershell
+# ① 导出公司根 CA 并转为 PEM（Windows 内置工具；多条结果时改用 foreach 逐条导出）
+#    将 <公司CA关键字> 替换为公司根 CA 证书 Subject 里的可匹配关键字
+$out = "$env:USERPROFILE\corp-root-ca.pem"
+Remove-Item $out -ErrorAction SilentlyContinue
+foreach ($c in (@(Get-ChildItem Cert:\LocalMachine\Root) +
+                @(Get-ChildItem Cert:\LocalMachine\CA) |
+                Where-Object { $_.Subject -match "<公司CA关键字>" })) {
+  "-----BEGIN CERTIFICATE-----" | Add-Content $out
+  [Convert]::ToBase64String($c.RawData, 'InsertLineBreaks') | Add-Content $out
+  "-----END CERTIFICATE-----" | Add-Content $out
+}
+
+# ② 让 Node 信任公司根 CA + 走镜像，重新运行 webterm
+$env:NODE_EXTRA_CA_CERTS = "$out"
+$env:ELECTRON_MIRROR = "https://npmmirror.com/mirrors/electron/"
+webterm
+```
+
+验证通过后建议持久化（`setx` 对新开终端生效）：
+
+```powershell
+setx NODE_EXTRA_CA_CERTS "%USERPROFILE%\corp-root-ca.pem"
+```
+
+### Linux
+
+- 需要安装 GTK/NSS 等系统运行库（缺失时 `webterm` 启动会自动检测并提示）。Debian/Ubuntu：
+
+```bash
+sudo apt-get install -y libgtk-3-0 libnss3 libasound2 libgl1 \
+  libatk1.0-0 libatk-bridge2.0-0 libatspi2.0-0 libcups2 libgbm1 \
+  libpango-1.0-0 libcairo2 libxcomposite1 libxdamage1 libxfixes3 \
+  libxkbcommon0 libxrandr2 \
+  fonts-noto-cjk fonts-noto-color-emoji fonts-noto-core
+```
+
+> 字体三件套提供中文（CJK）、emoji 图标（SFTP 界面的 📁/📄 等）和符号字符；缺失会显示方块。安装后需重启客户端。
+
+- 企业 TLS 解密网关证书：Chromium 在 Linux 上读 NSS 数据库而非系统 CA bundle，需手动导入公司根 CA（前提：根 CA 已导入系统信任库）：
+
+```bash
+sudo apt-get install -y libnss3-tools
+mkdir -p ~/.pki/nssdb
+certutil -d sql:$HOME/.pki/nssdb -N --empty-password
+certutil -d sql:$HOME/.pki/nssdb -A -t "C,," -n corp-root-ca \
+  -i /path/to/corp-root-ca.crt
+```
+
+  （根 CA 文件路径以实际环境为准；导入后无需 `WEBTERM_INSECURE_TLS`。）
+
+Fedora/RHEL 系统库：
+
+```bash
+sudo dnf install gtk3 nss libnss3-tools alsa-lib libglvnd atk at-spi2-atk cups-libs mesa-libgbm pango libXcomposite libXdamage libXfixes libxkbcommon libXrandr
+```
+
+### Linux 字体排障
+
+中文/emoji 显示方块（tofu）且已安装 `fonts-noto-cjk fonts-noto-color-emoji` 时，可能是 Electron 内置 fontconfig 与系统缓存格式不匹配（日志可见 `cache files were generated by a newer version` 警告）。清掉用户缓存后重启客户端即可（启动时自动重建）：
+
+```bash
+rm -rf ~/.cache/fontconfig
+```
+
+验证 Chromium 实际字体视野（需 `WEBTERM_REMOTE_DEBUGGING=9223` 启动）：
+
+```bash
+node tools/cdp-font-probe.js "ws://127.0.0.1:9223/devtools/page/<id>"
+# 或先 curl http://127.0.0.1:9223/json/list 拿到 webSocketDebuggerUrl
+```
+
+## 行为说明
+
+- 单实例：重复执行 `webterm` 会聚焦已打开的窗口，不会开出第二个。
+- 断网/VPN 未连时显示内置重试页，可一键重试。
+- 页面里的外部链接（非 webterm 同源）会在系统默认浏览器打开。
+- 关闭窗口即完全退出。
+
+## 开发
+
+```bash
+cd desktop
+npm install
+npm start            # electron .
+```
+
+## 发布（GitHub Actions CI）
+
+发布由 tag 触发的 CI 自动完成（`.github/workflows/publish.yml`）：
+
+1. **一次性配置**：npmjs.com → Access Tokens → Generate New Token（选择 **Granular Access Token**，权限 Publish、包范围限定 `@alickjoe/webterm`、设置过期时间）→ GitHub 仓库 **Settings → Secrets and variables → Actions** 添加 secret `NPM_TOKEN`。
+2. **日常发布**：更新 `desktop/package.json` 的 `version` → 提交 → 打 tag 并推送：
+   ```bash
+   git tag v0.1.4 && git push origin v0.1.4
+   ```
+   CI 校验 tag 与 package.json 版本一致后自动 `npm publish --access public --provenance`。
+3. **手动兜底**（本地）：`cd desktop && npm publish --access public`（浏览器 OTP 授权）。
+
+> bin 路径写法注意：npm 11 的 `npm pkg fix` 会把 bin 值的 `./` 前缀剥掉，且发布时 `./xxx` 形式会被 auto-correct 移除——保持不带 `./` 的文件名形式。

package/cli.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * webterm CLI 入口（bin: webterm）
+ *
+ * 职责：
+ *  1. 基本环境检查（Linux 无图形会话时给出友好报错）；
+ *  2. 支持 `webterm <url>` 快速覆盖目标地址（通过 env 传给主进程）；
+ *  3. 拉起 Electron 主进程（main.js）并转发退出码。
+ *
+ * 单实例聚焦逻辑在 Electron 主进程内（requestSingleInstanceLock）。
+ */
+
+const { spawn, spawnSync } = require('child_process');
+const path = require('path');
+
+function fail(message) {
+  console.error(`[webterm] ${message}`);
+  process.exit(1);
+}
+
+// Linux 无图形会话时 Electron 无法开窗，提前给出可读的错误
+if (process.platform === 'linux' && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) {
+  fail('未检测到图形会话（DISPLAY/WAYLAND_DISPLAY 均为空），无法打开应用窗口。');
+}
+
+// require('electron') 在普通 Node 进程中返回 electron 可执行文件路径（字符串）；
+// 二进制缺失时会触发懒下载（走公司网/TLS 网关可能失败）
+let electronPath;
+try {
+  electronPath = require('electron');
+} catch (err) {
+  fail(
+    'Electron 运行时缺失或下载失败（常见于公司网络）。\n' +
+    '修复方法（PowerShell）：\n' +
+    '  1. 公司 TLS 解密网关会重签证书，需让 Node 信任公司根 CA：\n' +
+    '     导出根 CA 为 PEM 后：$env:NODE_EXTRA_CA_CERTS="<根CA.pem路径>"\n' +
+    '  2. 或改用镜像下载：$env:ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"\n' +
+    '     然后重新运行 webterm（会自动重试下载）。\n' +
+    '详细说明见 README「Windows 企业网络」一节。'
+  );
+}
+if (typeof electronPath !== 'string') {
+  fail('electron 依赖未正确安装，请尝试在包目录重新运行 `npm install`。');
+}
+
+// Linux：检测 Electron 运行时缺失的系统库，给出发行版安装提示
+if (process.platform === 'linux') {
+  try {
+    const ldd = spawnSync('ldd', [electronPath], { encoding: 'utf8' });
+    if (ldd.status === 0 && ldd.stdout) {
+      const missing = [...new Set(
+        ldd.stdout.split('\n')
+          .filter((line) => line.includes('not found'))
+          .map((line) => line.trim().split(' ')[0])
+          .filter(Boolean)
+      )];
+      if (missing.length > 0) {
+        fail(
+          `Electron 缺少系统依赖库：\n  ${missing.join('\n  ')}\n` +
+          'Debian/Ubuntu 可执行：\n' +
+          '  sudo apt-get install -y libgtk-3-0 libnss3 libasound2 libgl1 \\\n' +
+          '    libatk1.0-0 libatk-bridge2.0-0 libatspi2.0-0 libcups2 libgbm1 \\\n' +
+          '    libpango-1.0-0 libcairo2 libxcomposite1 libxdamage1 libxfixes3 \\\n' +
+          '    libxkbcommon0 libxrandr2\n' +
+          'Fedora/RHEL 对应：sudo dnf install gtk3 nss alsa-lib atk at-spi2-atk cups-libs mesa-libgbm pango libXcomposite libXdamage libXfixes libxkbcommon libXrandr'
+        );
+      }
+    }
+  } catch {
+    // ldd 不存在时跳过检测，交给 Electron 自身报错
+  }
+}
+
+// `webterm <url>`：位置参数快速覆盖目标地址
+const urlArg = process.argv[2];
+if (urlArg) {
+  process.env.WEBTERM_URL = urlArg;
+}
+
+const appDir = __dirname;
+
+const child = spawn(electronPath, [appDir], {
+  stdio: 'inherit',
+  // 注意：Windows 上不要设 windowsHide:true —— CREATE_NO_WINDOW 会导致
+  // Electron 窗口永不显示（进程正常、日志正常但无窗口）。
+  // electron.exe 是 GUI 子系统程序，不需要隐藏控制台。
+});
+
+child.on('error', (err) => {
+  fail(`无法启动 Electron：${err.message}`);
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.exit(0);
+  }
+  process.exit(code == null ? 0 : code);
+});

package/main.js

@@ -0,0 +1,210 @@
+'use strict';
+
+/**
+ * webterm Electron 主进程（纯展示壳）
+ *
+ * 行为：
+ *  - 加载目标 URL（默认线上地址，WEBTERM_URL / ~/.webterm/config.json 可覆盖）
+ *  - 单实例锁：二次启动时聚焦已有窗口
+ *  - 窗口尺寸/位置记忆到 ~/.webterm/window.json
+ *  - 主框架加载失败时展示本地重试页（retry.html）
+ *  - 外部链接 / 跨源导航交给系统默认浏览器
+ *  - 安全：contextIsolation 开启，不向页面暴露任何 Node 能力
+ */
+
+const { app, BrowserWindow, Menu, shell } = require('electron');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// 默认地址以 Base64 模糊存储：避免公开 npm 包内明文出现内部域名
+// （仅为防直接检索的混淆手段，非加密；可用 config.json / WEBTERM_URL 覆盖）
+const DEFAULT_URL = Buffer.from('aHR0cHM6Ly93ZWJ0ZXJtLmFsaWNremhvdS5jb20v', 'base64').toString('utf8');
+const DATA_DIR = path.join(os.homedir(), '.webterm');
+const CONFIG_FILE = path.join(DATA_DIR, 'config.json');
+const WINDOW_STATE_FILE = path.join(DATA_DIR, 'window.json');
+
+// ---- TLS 逃生开关（默认严格校验）----
+if (process.env.WEBTERM_INSECURE_TLS === '1') {
+  // 必须在 app ready 之前设置
+  app.commandLine.appendSwitch('ignore-certificate-errors');
+}
+
+// ---- 调试：CDP 远程调试端口（WEBTERM_REMOTE_DEBUGGING=9222）----
+if (process.env.WEBTERM_REMOTE_DEBUGGING) {
+  app.commandLine.appendSwitch(
+    'remote-debugging-port',
+    process.env.WEBTERM_REMOTE_DEBUGGING
+  );
+}
+
+// ---- 配置加载 ----
+function loadConfig() {
+  // 优先级：env > 配置文件 > 内置默认
+  const fromEnv = process.env.WEBTERM_URL;
+  if (fromEnv) {
+    return normalizeUrl(fromEnv, 'WEBTERM_URL');
+  }
+  try {
+    const raw = fs.readFileSync(CONFIG_FILE, 'utf8');
+    const cfg = JSON.parse(raw);
+    if (cfg && typeof cfg.url === 'string' && cfg.url) {
+      return normalizeUrl(cfg.url, CONFIG_FILE);
+    }
+  } catch {
+    // 配置文件不存在或解析失败都走默认
+  }
+  return normalizeUrl(DEFAULT_URL, 'default');
+}
+
+function normalizeUrl(url, source) {
+  try {
+    const u = new URL(url);
+    if (u.protocol !== 'http:' && u.protocol !== 'https:') {
+      throw new Error(`unsupported protocol: ${u.protocol}`);
+    }
+    return { url: u.toString(), source };
+  } catch (err) {
+    console.warn(`[webterm] 无效的目标地址（来源 ${source}）：${url}，回退默认地址`);
+    return { url: DEFAULT_URL, source: 'default' };
+  }
+}
+
+// ---- 窗口状态记忆 ----
+function loadWindowState() {
+  const fallback = { width: 1280, height: 800 };
+  try {
+    const raw = fs.readFileSync(WINDOW_STATE_FILE, 'utf8');
+    const state = JSON.parse(raw);
+    return {
+      width: Number(state.width) > 0 ? Number(state.width) : fallback.width,
+      height: Number(state.height) > 0 ? Number(state.height) : fallback.height,
+      x: Number.isFinite(state.x) ? state.x : undefined,
+      y: Number.isFinite(state.y) ? state.y : undefined,
+    };
+  } catch {
+    return fallback;
+  }
+}
+
+function saveWindowState(win) {
+  try {
+    fs.mkdirSync(DATA_DIR, { recursive: true });
+    const bounds = win.getNormalBounds(); // 非最大化时的位置尺寸
+    fs.writeFileSync(WINDOW_STATE_FILE, JSON.stringify(bounds, null, 2), 'utf8');
+  } catch {
+    // 写失败不影响退出
+  }
+}
+
+// ---- 主流程 ----
+const gotSingleInstanceLock = app.requestSingleInstanceLock();
+if (!gotSingleInstanceLock) {
+  // 已有实例：直接退出，由已有实例聚焦窗口
+  app.quit();
+} else {
+  let mainWindow = null;
+  let target = loadConfig();
+
+  app.on('second-instance', () => {
+    if (mainWindow) {
+      if (mainWindow.isMinimized()) mainWindow.restore();
+      if (!mainWindow.isVisible()) mainWindow.show();
+      mainWindow.focus();
+    }
+  });
+
+  function createWindow() {
+    const state = loadWindowState();
+
+    mainWindow = new BrowserWindow({
+      width: state.width,
+      height: state.height,
+      x: state.x,
+      y: state.y,
+      minWidth: 640,
+      minHeight: 480,
+      title: 'webterm',
+      autoHideMenuBar: true,
+      backgroundColor: '#1e1e1e',
+      webPreferences: {
+        contextIsolation: true,
+        nodeIntegration: false,
+        sandbox: true,
+        spellcheck: false,
+      },
+    });
+
+    Menu.setApplicationMenu(null);
+
+    // 主框架加载失败 → 本地重试页（可点 Retry 重新加载目标地址）
+    mainWindow.webContents.on('did-fail-load', (event, code, desc, url, isMainFrame) => {
+      if (!isMainFrame) return;
+      if (code === -3) return; // ERR_ABORTED：通常由重定向/手动取消引起，忽略
+      console.error(`[webterm] 页面加载失败：${code} ${desc || ''}`);
+      mainWindow
+        .loadFile(path.join(__dirname, 'retry.html'), {
+          query: { url: target.url, code: String(code), desc: desc || '' },
+        })
+        .catch(() => {});
+    });
+
+    mainWindow.webContents.on('did-finish-load', () => {
+      console.log('[webterm] 页面加载完成');
+    });
+
+    // 页面内的跨源导航 → 系统浏览器；同源导航放行
+    const appOrigin = safeOrigin(target.url);
+    mainWindow.webContents.on('will-navigate', (event, url) => {
+      if (safeOrigin(url) !== appOrigin) {
+        event.preventDefault();
+        shell.openExternal(url);
+      }
+    });
+
+    // window.open / target=_blank → 系统浏览器，不在壳内开新窗口
+    mainWindow.webContents.setWindowOpenHandler(({ url }) => {
+      shell.openExternal(url);
+      return { action: 'deny' };
+    });
+
+    // 关闭时保存窗口状态
+    mainWindow.on('close', () => {
+      if (mainWindow && !mainWindow.isDestroyed()) {
+        saveWindowState(mainWindow);
+      }
+    });
+
+    mainWindow.on('closed', () => {
+      mainWindow = null;
+    });
+
+    mainWindow.loadURL(target.url).catch(() => {
+      // did-fail-load 会处理，这里吞掉 promise 拒绝
+    });
+  }
+
+  function safeOrigin(url) {
+    try {
+      return new URL(url).origin;
+    } catch {
+      return '';
+    }
+  }
+
+  app.whenReady().then(() => {
+    createWindow();
+    console.log(`[webterm] 目标地址：${target.url}（来源：${target.source}）`);
+  });
+
+  app.on('window-all-closed', () => {
+    app.quit();
+  });
+
+  app.on('activate', () => {
+    // macOS：dock 点击时若无窗口则重建
+    if (BrowserWindow.getAllWindows().length === 0) {
+      createWindow();
+    }
+  });
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@alickjoe/webterm",
+  "version": "0.1.4",
+  "description": "webterm 桌面客户端：用 Electron 应用窗口包装 webterm 网页（不打包 exe）",
+  "bin": {
+    "webterm": "cli.js"
+  },
+  "main": "main.js",
+  "files": [
+    "cli.js",
+    "main.js",
+    "postinstall.js",
+    "retry.html",
+    "README.md",
+    "tools"
+  ],
+  "scripts": {
+    "postinstall": "node postinstall.js",
+    "start": "electron ."
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "webterm",
+    "ssh",
+    "terminal",
+    "sftp",
+    "electron",
+    "desktop"
+  ],
+  "dependencies": {
+    "electron": "^44.4.3"
+  },
+  "license": "MIT",
+  "private": false
+}

package/postinstall.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * @alickjoe/webterm postinstall：把 Electron 运行时下载合并进 npm install 阶段。
+ *
+ * 背景：electron@44 官方包不再带 postinstall 自动下载（scripts 为空），
+ * 默认体验是"装完之后第一次运行才下载"。这里在 install 阶段 require('electron')
+ * 主动触发一次下载（electron 的 index.js 会在二进制缺失时阻塞式下载）。
+ *
+ * 设计原则：
+ *  - 下载失败【不阻断】npm install：懒下载仍会在首次运行 webterm 时兜底；
+ *  - 同版本二进制有 @electron/get 用户级缓存（Windows %LOCALAPPDATA%\electron\Cache、
+ *    Linux/macOS ~/.electron 或 ~/.cache），升级重装时仅解压不重新联网下载。
+ *
+ * 企业网络失败时的两个关键环境变量（详见 README）：
+ *  - NODE_EXTRA_CA_CERTS  让 Node 的 fetch 信任公司 TLS 解密网关重签的证书
+ *  - ELECTRON_MIRROR      换下载镜像，如 https://npmmirror.com/mirrors/electron/
+ */
+
+const fs = require('fs');
+
+let binaryPath = null;
+try {
+  // 普通 Node 进程中 require('electron') 返回二进制路径字符串；
+  // 若二进制缺失会触发 electron 内置的阻塞式下载，失败则抛错。
+  const p = require('electron');
+  if (typeof p === 'string' && fs.existsSync(p)) {
+    binaryPath = p;
+  }
+} catch (err) {
+  // 落到下面的警告分支
+}
+
+if (binaryPath) {
+  console.log('[webterm] Electron 运行时就绪 ✓');
+  process.exit(0);
+}
+
+console.warn('[webterm] Electron 运行时未就绪：本次安装没有下载成功。');
+console.warn('[webterm] 不影响安装完成——首次运行 webterm 时会自动重试下载。');
+console.warn('[webterm] 公司网络下载失败时，请在运行前设置（详见 README「Windows 企业网络」）：');
+console.warn('[webterm]   NODE_EXTRA_CA_CERTS=<公司根CA.pem>  ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/');
+process.exit(0);

package/retry.html

@@ -0,0 +1,61 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8" />
+  <title>webterm - 无法连接</title>
+  <style>
+    :root { color-scheme: dark; }
+    body {
+      margin: 0;
+      height: 100vh;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      font-family: system-ui, -apple-system, 'Segoe UI', 'PingFang SC', 'Microsoft YaHei', sans-serif;
+      background: #1e1e1e;
+      color: #d4d4d4;
+    }
+    .box { max-width: 560px; padding: 32px; text-align: center; }
+    h1 { font-size: 20px; font-weight: 600; margin: 0 0 8px; }
+    .desc { color: #9ca3af; font-size: 13px; margin: 0 0 20px; word-break: break-all; }
+    .target { font-size: 13px; color: #6b7280; margin: 0 0 24px; word-break: break-all; }
+    #retry {
+      display: inline-block;
+      padding: 8px 28px;
+      border-radius: 6px;
+      background: #2563eb;
+      color: #fff;
+      text-decoration: none;
+      font-size: 14px;
+    }
+    #retry:hover { background: #1d4ed8; }
+    .hint { margin-top: 20px; font-size: 12px; color: #6b7280; line-height: 1.7; }
+    code { background: #2d2d2d; padding: 1px 6px; border-radius: 4px; }
+  </style>
+</head>
+<body>
+  <div class="box">
+    <h1>无法连接到 webterm</h1>
+    <p class="desc" id="desc"></p>
+    <p class="target">目标地址：<span id="target"></span></p>
+    <a id="retry" href="#">重试</a>
+    <p class="hint">
+      请检查网络与 VPN 连接。<br />
+      更换地址：修改 <code>~/.webterm/config.json</code>，或用环境变量
+      <code>WEBTERM_URL</code>，或执行 <code>webterm &lt;url&gt;</code>。
+    </p>
+  </div>
+  <script>
+    var p = new URLSearchParams(location.search);
+    var url = p.get('url') || '';
+    document.getElementById('desc').textContent = p.get('desc') ? '错误：' + p.get('code') + ' ' + p.get('desc') : '';
+    if (url) {
+      document.getElementById('target').textContent = url;
+      document.getElementById('retry').href = url;
+    } else {
+      document.getElementById('retry').style.display = 'none';
+      document.getElementById('target').textContent = '未配置目标地址（WEBTERM_URL 环境变量或 ~/.webterm/config.json）';
+    }
+  </script>
+</body>
+</html>

package/tools/cdp-font-probe.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * CDP 字体探测：通过 remote-debugging-port 询问页面渲染进程
+ * document.fonts.check 是否认为 CJK / emoji 字体可用。
+ * 用法: node cdp-font-probe.js <ws-url>
+ */
+
+const wsUrl = process.argv[2];
+if (!wsUrl) {
+  console.error('usage: node cdp-font-probe.js <ws-url>');
+  process.exit(1);
+}
+
+const ws = new WebSocket(wsUrl);
+let id = 0;
+const pending = new Map();
+
+function send(method, params) {
+  return new Promise((resolve) => {
+    const msgId = ++id;
+    pending.set(msgId, resolve);
+    ws.send(JSON.stringify({ id: msgId, method, params }));
+  });
+}
+
+ws.onopen = async () => {
+  const probes = [
+    ['zh-general', 'sans-serif', '中文测试'],
+    ['zh-explicit', '"Noto Sans CJK SC"', '中'],
+    ['emoji-dir', '"Noto Color Emoji"', '📁'],
+    ['emoji-file', '"Noto Color Emoji"', '📄'],
+    ['latin', 'sans-serif', 'abc'],
+  ];
+  for (const [name, font, text] of probes) {
+    const expr = `document.fonts.check('16px ${font}', ${JSON.stringify(text)})`;
+    const res = await send('Runtime.evaluate', { expression: expr, returnByValue: true });
+    console.log(`${name.padEnd(12)} ${font.padEnd(22)} "${text}" -> ${res.result?.result?.value ?? JSON.stringify(res.result)}`);
+  }
+  ws.close();
+  process.exit(0);
+};
+
+ws.onerror = (e) => {
+  console.error('ws error', e.message || e);
+  process.exit(1);
+};
+
+ws.onmessage = (ev) => {
+  const msg = JSON.parse(ev.data);
+  if (msg.id && pending.has(msg.id)) {
+    pending.get(msg.id)(msg.result);
+    pending.delete(msg.id);
+  }
+};
+
+setTimeout(() => { console.error('timeout'); process.exit(1); }, 10000);