我一个人， 53 天， 425 次提交，把终端装进了鸿蒙手机

那天晚上 11 点，我在火车上 SSH 到服务器查日志。手机浏览器切了个微信回来，tab 被 kill 了，session 断了，查了一半的日志全没了。

我翻了翻手机上所有终端 app——Termius 、Blink Shell 、ServerCat——它们都有同一个问题：你不能真的"保持连接"。系统杀后台、网络切换、锁屏省电，随便哪个都能把你的 SSH 掐断。

那能不能反过来？让 shell 在远程服务器上一直跑，手机只是个"显示器"——断了就断了，重连回来输出还在。

这就是 Corterm （云枢终端）的出发点：session 不是连接，是状态。

先把架子搭起来

思路很直接：

1. Worker — 装在远程机器上的轻量 agent ，管 PTY 生命周期。你断了连，shell 照跑。


2. Gateway — 中间层，管认证、路由、session 协调。Worker 和 Client 之间不直接通信。


3. Client — 纯渲染层。断了重连时，Gateway 把 Worker 上的 scrollback buffer 吐给你，无缝衔接。

Client (Browser/iOS/Android/HarmonyOS)

         ↕  SignalR

     Gateway (.NET 10)

         ↕  SignalR

     Worker (.NET 10 + PTY)

Gateway 和 Worker 用 .NET 10 + SignalR ，Client 端浏览器用 React + xterm.js ，iOS/Android 用 MAUI 。浏览器、手机 App 都跑通了，接下来是鸿蒙。

手搓 SignalR：1091 行 ArkTS 的协议实现

鸿蒙端的第一道坎：SignalR 。

Corterm 的 Gateway 是 .NET 写的，实时通信用的 SignalR 。iOS/Android 那边有官方 SDK ，浏览器更不用说。但鸿蒙……我翻了半天文档，没有。连第三方实现都没有。

两条路：要么在 Gateway 加一层 WebSocket 中间层，要么直接在 ArkTS 里实现 SignalR 协议。前者意味着改服务端，所有客户端都得测。后者意味着我要在一个 TypeScript 的严格子集里，手写一个协议栈。

我选了后者。

Negotiate 握手

SignalR 连接的第一步不是 WebSocket ，而是一个 HTTP POST negotiate 请求。服务端返回一个 connectionToken，后续 WebSocket 连接必须带上这个 token 。

// HttpConnection.ets

private async negotiate(accessToken: string): Promise<string> {

  const negotiateUrl = `${this.url}/negotiate?negotiateVersion=1`;

  const httpClient = http.createHttp();

  const headers: Record<string, string> = {

    'Accept': 'application/json',

    'Content-Type': 'application/json',

  };

  if (accessToken.length > 0) {

    headers['Authorization'] = `Bearer ${accessToken}`;

  }



  const response = await httpClient.request(negotiateUrl, {

    method: http.RequestMethod.POST,

    header: headers,

    connectTimeout: 15000,

    readTimeout: 15000,

  });



  const body = response.result as string;

  const negotiateResponse = JSON.parse(body) as NegotiateResponse;

  this.connectionId = negotiateResponse.connectionId ?? '';

  return negotiateResponse.connectionToken ?? '';

}

鸿蒙的网络 API 是 @kit.NetworkKit 里的 http.createHttp() 和 webSocket.createWebSocket()，用法跟 Node.js 的差不多，但所有东西都得显式类型声明。

WebSocket 连接

拿到 token 后，拼 URL ，建 WebSocket：

// HttpConnection.ets

private async connectWebSocket(accessToken: string): Promise<void> {

  const wsUrl = this.url

    .replace('https://', 'wss://')

    .replace('http://', 'ws://');



  let fullUrl = wsUrl;

  const params: string[] = [];

  if (this.connectionToken.length > 0) {

    params.push(`id=${encodeURIComponent(this.connectionToken)}`);

  }

  if (accessToken.length > 0) {

    params.push(`access_token=${encodeURIComponent(accessToken)}`);

  }

  if (params.length > 0) {

    fullUrl += '?' + params.join('&');

  }



  this.ws = webSocket.createWebSocket();

  const ws = this.ws;



  const openPromise = new Promise<void>((resolve, reject) => {

    ws.on('open', () => resolve());

    ws.on('error', (err: Error) => {

      if (!this.stopRequested) reject(new Error(`WebSocket error: ${err.message}`));

    });

  });



  ws.on('message', (_err: Error, data: string | ArrayBuffer) => {

    let text: string;

    if (typeof data === 'string') {

      text = data;

    } else {

      text = buffer.from(data).toString('utf-8');

    }

    if (this.onreceive !== null) {

      this.onreceive(text);

    }

  });



  await ws.connect(fullUrl, { header: connectHeaders });

  await openPromise;

}

Hub 协议层

SignalR 不是裸 WebSocket 。它有自己的消息格式——我打开 C# 源码看了下，其实就 5 种消息类型：

• Type 1 — InvocationMessage （双向 RPC 调用）


• Type 2 — StreamItemMessage （流式结果）


• Type 3 — CompletionMessage （ RPC 响应）


• Type 6 — Ping （心跳）


• Type 7 — Close （关闭）

消息之间用 0x1E（ ASCII record separator ）分隔。processIncomingData 是整个消息分发管道的入口：

// HubConnection.ets

private processIncomingData(data: string): void {

  // 第一条消息是 handshake response

  if (this.handshakePromise !== null) {

    this.protocol.decodeHandshakeResponse(data);

    const promise = this.handshakePromise;

    this.handshakePromise = null;

    promise.resolve();

    return;

  }



  // 常规消息

  const messages = this.protocol.decodeMessages(data, this.logger);

  for (const message of messages) {

    this.dispatchMessage(message);

  }

}



private dispatchMessage(message: HubMessageBase): void {

  this.resetServerTimeout();



  switch (message.type) {

    case 1: { // Invocation

      const invocation = message as InvocationMessage;

      this.invokeHandler(invocation.target, invocation.arguments);

      break;

    }

    case 2: { // StreamItem

      const pending = this.streamManager.getInvocation(streamItem.invocationId);

      if (pending !== undefined) pending.resolve(streamItem.item);

      break;

    }

    case 3: { // Completion

      const pending = this.streamManager.removeInvocation(completion.invocationId);

      if (pending !== undefined) {

        if (completion.error.length > 0) pending.reject(new Error(completion.error));

        else pending.resolve(completion.result);

      }

      break;

    }

    case 6: break; // Ping

    case 7: this.handleCloseMessage(close); break;

  }

}

Keepalive 和重连

心跳每 15 秒发一次 Ping ，服务端 30 秒没消息就判定超时：

private resetKeepAlive(): void {

  this.pingTimer = setInterval(() => {

    const ping = new PingMessage();

    const encoded = this.protocol.encodeMessage(ping);

    this.httpConnection.send(encoded);

  }, this.keepAliveIntervalInMilliseconds) as number;  // 15000ms

}



private resetServerTimeout(): void {

  clearTimeout(this.serverTimeoutTimer);

  this.serverTimeoutTimer = setTimeout(() => {

    this.httpConnection.stop(new Error('Server timeout'));

  }, this.serverTimeoutInMilliseconds) as number;  // 30000ms

}

重连策略是 SignalR 的经典配置 [0, 2000, 5000, 10000, 30000]——先立即重试，然后 2 秒、5 秒、10 秒、30 秒。但官方 SDK 试完这 5 次就放弃了。我的实现改成了循环重试，延迟数组里的最后一个值（ 30 秒）会一直用下去，最多 15 次之后才真正断开：

private scheduleReconnect(): void {

  if (this.stopRequested) return;

  const delayIndex = Math.min(this.reconnectAttempt, this.reconnectDelays.length - 1);

  const delay = this.reconnectDelays[delayIndex];

  this.reconnectTimer = setTimeout(() => this.attemptReconnect(), delay) as number;

}

ArkTS 的那些坑

写 SignalR 客户端最痛的不是协议本身，而是 ArkTS 的限制。它是 TypeScript 的严格子集：

• 不能用 as const — 只能用 class X { static readonly A = '...' }


• 不能写无类型对象字面量 — { key: value } 直接报错，必须声明类型


• 不能用解构赋值 — const [k, v] of Object.entries(obj) 编译不过


• throw 只能抛 Error — catch 到的任意值不能直接 throw

每一条都是我在编译报错后才学到的。

在 ArkWeb 里跑 xterm.js

终端渲染的答案很明确：xterm.js 。问题是它跑在浏览器里，而我要在 HarmonyOS 的原生 app 里用它。

HarmonyOS 提供了 ArkWeb （ WebView 组件），有 WebMessagePort 做双向通信。我先试了 javaScriptProxy，崩溃不断，换成 WebMessagePort 才稳定下来。

核心逻辑：创建一对 MessagePort ，Port 0 发给 HTML 端，Port 1 留在 native 端监听：

// XtermWebview.ets

private initMessagePort() {

  this.msgPorts = this.webviewController.createWebMessagePorts();

  // Port 1 留在 native 端

  this.msgPorts[1].onMessageEvent((result: webview.WebMessage) => {

    const msg = JSON.parse(result as string) as Record<string, Object>;

    const type = msg['type'] as string;

    if (type === 'input') {

      this.onInput(msg['data'] as string);

    } else if (type === 'resize') {

      const cols = msg['cols'] as number;

      const rows = msg['rows'] as number;

      this.onResize(cols, rows);

    }

  });

  // Port 0 发给 HTML 端

  this.webviewController.postMessage('__init_port__', [this.msgPorts[0]], '*');

}

输出方向反过来：native 拿到 Worker 的输出，base64 编码后调 runJavaScript 写入 xterm：

writeOutput(base64Payload: string) {

  const escaped = base64Payload.replace(/\\/g, '\\\\').replace(/"/g, '\\"');

  this.webviewController.runJavaScript(`writeBase64Output("${escaped}")`);

}

为什么用 base64 ？因为终端输出包含二进制数据（ ANSI 转义序列、控制字符），直接当 JSON 字符串传会炸。

整个终端页面的生命周期是一个 9 状态的状态机：Disconnected → Connecting → Replaying → Live → Reconnecting → ...。重连时 Gateway 先 replay scrollback buffer ，然后切到 Live 模式，用户感觉不到断过。

手机上怎么按 Ctrl+C

终端有了，但我怎么在手机上发 SIGINT ？

没有键盘的设备用终端，这是所有移动端终端 app 的噩梦。

我的解法是 VirtualKeyBar——一个水平可滚动的虚拟按键条。关键是 Sticky Modifier：Ctrl 和 Alt 是 latch 按键，按一下变亮（激活），再按下一个字符键时才发送组合键。

// VirtualKeyBar.ets — LatchButton 组件

@Component

struct LatchButton {

  label: string = ''

  @Prop latched: boolean = false

  onToggle: () => void = () => {}



  build() {

    Button(this.label)

      .backgroundColor(this.latched ?

        $r('app.color.terminal_secondary_container') :

        $r('app.color.terminal_surface_container_high'))

      .onClick(() => {

        clickHaptic();

        this.onToggle();

      })

  }

}

Ctrl + 字母的映射藏在 handleVirtualKey 里：

// TerminalPage.ets

private handleVirtualKey(key: string) {

  if (key.startsWith('Ctrl+')) {

    const label = key.substring(5);

    // a-z → 0x01-0x1A

    const ch = label.toLowerCase().charCodeAt(0);

    if (ch >= 97 && ch <= 122) {

      this.sendInput(String.fromCharCode(ch - 96));

    }

  }

  // Escape sequences

  const inputMap: Record<string, string> = {

    'ArrowUp': '\x1b[A',

    'ArrowDown': '\x1b[B',

    'ArrowRight': '\x1b[C',

    'ArrowLeft': '\x1b[D',

  };

}

'c'.charCodeAt(0) 是 99 （ 0x63 ），减 96 得 3 ，String.fromCharCode(3) 就是 \x03——SIGINT 。一行数学运算解决了所有 Ctrl+字母的映射。

CI/CD 十五连跪

6 月 8 号，我开始写 harmony-release.yml。

然后接下来的 3 天里，我推了这个文件 15 次。

Pipeline 长这样：

Tag push (harmony-v*) → 版本提取 → 签名准备 → hvigor 构建

→ AGConnect 认证 → OBS 上传 → 编译轮询 → 提审

踩坑中最惨的几个：

AGConnect API 文档是解谜游戏。 /upload-url/for-obs 端点文档只写了入参，没告诉你返回的 header 要原样传给 OBS 的 PUT 请求。我是抓包才搞明白的。

编译状态要轮询。 华为的服务端编译一个 .app 文件要 60 秒以上，API 没有回调，只能 30 秒一次轮询，最多 20 次：

- name: Query compile status

  run: |

    for i in $(seq 1 20); do

      SUCCESS_STATUS=$(curl -s ... | jq -r '.pkgStateList[0].successStatus')

      if [ "$SUCCESS_STATUS" = "0" ]; then

        echo "Compile successful"

        exit 0

      fi

      sleep 30

    done

自托管 runner 的脏文件。 有一次构建失败，查了半天发现是 /tmp 下残留了上次的 .app 文件，签名步骤拿错了文件。于是加了一行 rm -rf 在 pipeline 开头。

每次看到 GitHub Actions 红叉，我都觉得自己在跟华为的文档玩解谜游戏。

53 天的数字

425 次提交。53 天。1 个人。5 个平台。

其中鸿蒙端：

• 8645 行 ArkTS


• 1091 行 手写 SignalR 客户端


• 9 个 HAR 模块（ 1 entry + 5 feature + 3 common ）


• 5 月 8 日 第一个鸿蒙 commit → 6 月 11 日 上架华为应用市场

接下来要做的：文件传输、端口转发、多 tab 、命令片段。

如果你也觉得手机上应该有个不中断的终端，来看看：github.com/monster-echo/CortexTerminal2

Docker 一键体验：

docker run -d -p 5000:5000 ghcr.io/monster-echo/cortex-terminal:latest