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

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

适配开源地址：https://atomgit.com/OpenHarmonyPCDeveloper/ohso_teraterm

一、为什么要适配 Tera Term

Tera Term 是一款历史悠久的开源终端模拟器。对网络设备运维、嵌入式调试和服务器管理人员来说，它的价值不只在于“打开一个黑色终端窗口”，而在于把 TCP、Telnet、SSH、串口、会话日志、配置文件和 TTL 宏组织成一套稳定的桌面工作流。许多交换机、开发板和实验室设备至今仍以串口或 Telnet 提供管理入口，SSH 又是日常远程维护不可缺少的协议，因此这类工具在 PC 生产力生态中有明确的位置。

选择 Tera Term 进行 HarmonyOS PC 适配，也是在验证一个比普通桌面工具更复杂的问题：当原项目长期依赖 Win32 窗口、Windows 消息、Winsock、COM 口和 DLL 插件时，怎样在不伪装“原工程可以直接交叉编译”的前提下，保留用户真正需要的终端语义，并把网络、文件、剪贴板、持久化和 Native 能力接入鸿蒙应用模型。

本次适配没有把 Windows 可执行文件简单封装进 HAP，而是采用 ArkTS/ArkUI 桌面外壳与 C++ Native 核心的分层方案。当前应用 BundleName 为 org.teraterm.ohospc，版本为 0.1.0，面向 2in1 与 tablet，目标 Native 架构为 arm64-v8a。

二、先划清适配边界：不能机械搬运 Win32 外壳

上游 Tera Term 的主程序、宏程序、SSH 扩展和代理扩展围绕 Windows 平台演进多年。窗口和对话框依赖 HWND、资源脚本与 Windows 消息；网络层包含 Winsock 生命周期；串口使用 Windows COM 与设备枚举接口；TTX 扩展通过 DLL ABI 装载；配置、帮助和安装流程又涉及注册表、CHM 与 Inno Setup。把这些依赖逐项补成兼容层，最终仍很难得到符合 HarmonyOS PC 权限与生命周期要求的普通应用。

因此，鸿蒙版本把“兼容原来的二进制外壳”调整为“延续高价值的用户工作流”，并将职责拆成四层：

层次	主要职责	鸿蒙侧实现
应用与窗口	生命周期、菜单、标签页、连接栏、状态栏	Stage 模型 EntryAbility 与 ArkUI
终端交互	终端网格、光标、键盘、选择、滚屏	TerminalSurface.ets 与 Native styled-cell 快照
会话核心	ANSI/CSI、UTF-8、历史输出、日志与会话状态	C++ TerminalSessionCore / TerminalSession
协议与扩展	TCP、Telnet、SSH、串口、代理、传输与宏	POSIX transport、libssh2、termios、TTL 子集

这条路线没有声称完整复刻 Windows 版。当前目标是先跑通普通网络终端用户最常用的闭环，再把串口真机矩阵、完整 VT/xterm 边缘行为、全部 TTL 命令和 Windows 专属扩展留在清晰的后续边界中。

三、鸿蒙版本的整体架构

鸿蒙适配集中在仓库的 ports/ohos/ 目录。ArkUI 负责窗口布局和系统能力接入，Node-API 负责把 ArkTS 调用转换为 C++ 会话操作，Native 层维护连接、解析和终端状态。界面不会自己拼接网络数据，也不会让 C++ 线程直接操作 ArkUI 控件。

EntryAbility / Index.ets
        │
        ├── 菜单、标签页、连接参数、文件选择与 Preferences
        ├── TerminalSurface.ets（终端网格、光标、选区、键盘）
        │
        └── TerminalNative.ets
                  │ Node-API
                  ▼
          libteraterm_ohos.so
                  ├── TerminalSession / TerminalSessionCore
                  ├── POSIX TCP + Telnet negotiation
                  ├── libssh2 + Mbed TLS
                  ├── POSIX serial / termios
                  ├── known_hosts / profile importer
                  └── TTL macro runner

工程中的主要文件分工如下：

ports/ohos/
├── app/
│   ├── AppScope/app.json5                    # 包名、版本与应用资源
│   └── entry/src/main/
│       ├── ets/pages/Index.ets              # PC 主界面和会话编排
│       ├── ets/components/TerminalSurface.ets
│       ├── ets/services/                    # 剪贴板、文件、日志、持久化
│       ├── cpp/CMakeLists.txt               # Native 模块构建入口
│       └── module.json5                     # 设备类型、Ability 与网络权限
├── native/
│   ├── include/                             # 会话、协议、宏和配置接口
│   ├── src/tt_ohos_napi.cpp                # ArkTS/C++ 边界
│   ├── src/terminal_session_core.cpp        # 终端状态机
│   ├── src/posix_tcp_transport.cpp          # TCP 通路
│   ├── src/telnet_filter.cpp                # Telnet 协商过滤
│   ├── src/ssh_transport_libssh2.cpp         # SSH、SCP/SFTP 与转发
│   └── tests/                               # Native 回归测试
├── third_party/libssh2/arm64-v8a/           # OHOS 目标静态依赖
└── docs/                                    # 兼容性清单与真机记录

四、在真机上跑通五个核心场景

以下五张截图均来自分辨率为 3120×2080 的 HarmonyOS PC 2in1 真机。文档整理时重新执行了 Native 与 ArkTS 构建，生成签名 HAP 后通过 hdc install -r 覆盖安装，并从设备端启动 org.teraterm.ohospc。TCP 验证由真机应用经 Native POSIX socket 连接测试端点完成，不是把预先准备的文字放进终端区域。

1. 桌面终端外壳能够正常安装和启动

启动后的信息架构沿用桌面终端用户熟悉的顺序：顶部是 File、Edit、Setup、Control、Window、Help 菜单，其下依次为会话标签、协议与连接参数、终端视口，底部保留连接状态和输入栏。控件采用紧凑的 PC 布局，窗口可以在鸿蒙桌面环境中移动和缩放。

终端区域并不是普通的多行文本框。Native 层返回行、单元格样式和光标位置，ArkUI 逐格应用前景色、背景色、反显等状态；窗口尺寸变化还会换算成行列数，再调用 resizeSession。Telnet 会据此发送 NAWS，SSH 会调整远端 PTY，避免“窗口变大了，但远端仍按旧宽度换行”。

2. TCP 连接进入 Native 会话链路

为了验证最基础也最关键的网络路径，真机选择 TCP，连接 localhost:10023。端口通过 hdc rport 转发到开发机上的 TCP 测试服务。连接建立后，服务主动返回 Tera Term HarmonyOS PC ready，应用底部状态同步变为 Connected localhost:10023。

这一步同时经过 ArkUI 表单、Node-API、TerminalSession、POSIX socket 和终端解析器。连接状态与输出内容来自两个不同方向：前者由会话管理更新，后者由 Native transport 收取后进入终端状态机，因此能够同时出现才说明链路已经越过了静态界面阶段。

3. 输入、发送、接收和显示形成双向闭环

建立连接后，从底部输入栏发送 pingohospc。测试服务实际收到带回车的字节流，并返回 echo: pingohospc；终端视口随后显示回显内容。

发送数据既可以由底部输入栏触发，也可以在终端获得焦点后直接使用 PC 键盘。接收侧按会话持续泵取数据，写入有界历史和屏幕快照；同一份 transcript 又供搜索、复制与日志保存使用。这样可以避免终端显示一份数据、保存日志却读取另一份缓存所造成的不一致。

4. 多会话不是装饰性标签页

点击“+”创建第二个会话后，界面出现 localhost 与 Session 2 两个标签。第一个标签保留已经建立连接的主机和会话状态，第二个标签拥有独立的协议、地址、终端缓冲区、日志、宏和转发状态。

实现中每个标签对应独立的 Native session id。切换标签时只把当前记录装载到界面状态，后台轮询仍会处理其他活动会话，因此远端输出不会因为标签处于非活动状态而停止接收。关闭标签时再按顺序停止宏、端口转发并释放 Native 会话，避免把网络资源遗留在应用进程中。

5. 配置导入、会话保存和日志输出回到主工作流

File 面板没有被做成孤立的设置页，而是紧邻当前会话提供 Open INI、Import、Save Profile、Save Log 和 Sandbox Log。用户可以导入 TERATERM.INI 中的常用 [Hosts] 配置，保存当前连接参数，也可以把当前会话 transcript 导出到用户选择的位置；系统选择器不可用时，沙箱日志提供明确的兜底路径。

配置持久化不只保存主机和端口。协议、SSH 认证、代理、串口参数以及显示设置都按相应模型组织；known_hosts 也通过独立存储处理。这样既能继续接收 Tera Term 用户已有的部分配置，又不会把敏感认证信息混入终端日志。

五、适配过程中遇到的几个难点

难点一：需要迁移的是行为，不是 Win32 类型

原工程中窗口、消息、网络和插件边界长期围绕 Windows 组织。若以消除编译错误为目标，很容易把大量精力投入 HWND、资源脚本和 DLL 装载的表面兼容，却迟迟无法形成可安装、可连接的鸿蒙应用。适配时先按用户路径划分会话、终端、协议、日志、配置和宏，再决定哪些语义由新的 C++ 核心承接，哪些系统交互交给 ArkUI。

难点二：终端显示是一台状态机，不是一段字符串

远端输出可能把一个 UTF-8 字符拆在多个网络包中，也会混入光标移动、擦除、插入、删除、颜色和滚屏控制序列。直接把每次 recv 的结果追加到 Text 组件，会很快在编辑器、分页器和带颜色的命令中失真。当前 Native 核心维护固定行列的屏幕、光标、有界 scrollback 和 styled cells，ArkUI 只渲染快照；常见 ANSI/CSI 和 UTF-8 已覆盖，但仍诚实保留完整 VT/xterm 兼容的后续空间。

难点三：多个会话要求连接、界面和清理时序一致

网络数据到达、标签切换、窗口缩放、宏执行和关闭会话可能同时发生。如果只轮询当前标签，后台会话会丢失及时处理；如果把所有状态放在页面级变量中，切换时又会串台。当前实现用 TerminalTabRecord 保存每个标签的配置与运行状态，Native 以 session id 隔离连接，pumpAllSessions 负责统一推进，再只把活动会话的快照投射到页面。

难点四：SSH 不只是增加一个协议按钮

SSH 需要握手、主机密钥策略、密码或私钥认证、PTY、读写与关闭时序，文件传输和本地端口转发还会继续复用同一套安全上下文。鸿蒙 arm64-v8a 构建中启用了 vendored libssh2，并链接对应目标架构的 Mbed TLS、Everest 与 p256m 静态库；known_hosts 解析、accept-new 策略和私钥路径则通过 Node-API 暴露给 ArkUI。这里最容易犯的错误是误用开发机架构的预编译库，产物即使打进 HAP，也无法在真机正常装载。

难点五：文件与配置要服从应用沙箱

Windows 桌面应用通常可以围绕任意绝对路径读写 INI、日志、密钥和传输文件，鸿蒙普通应用则需要通过系统选择器获得用户授权。适配版分别实现了导入、导出、沙箱日志和传输文件存储服务，并用 Preferences 保存适合持久化的配置。这样做比在输入框中接受一个路径更繁琐，却是重启后配置仍可用、日志确实能够落盘的基础。

难点六：串口“代码可编译”不等于硬件已经适配

Native 层已经实现 POSIX termios 路径，界面也提供设备扫描、波特率、数据位、停止位、校验和流控参数。但不同 USB 串口芯片在 HarmonyOS PC 上的设备节点、驱动与权限仍需要实物验证。在没有连接 CH340、CP2102 或 FTDI 等适配器完成收发回环前，只能把当前状态描述为“串口能力已实现并完成主机侧测试”，不能写成生产级串口已经通过真机验收。

六、构建、安装与启动

鸿蒙工程位于 ports/ohos/app/。命令行构建时建议使用 DevEco Studio 自带的 Node、ohpm、Hvigor 与 SDK，确保 ArkTS 和 Native 工具链来自同一套安装：

cd ports/ohos/app

export DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk
export HOS_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk
export PATH=/Applications/DevEco-Studio.app/Contents/tools/node/bin:\
/Applications/DevEco-Studio.app/Contents/tools/ohpm/bin:\
/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains:$PATH

/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw \
  assembleApp --no-daemon --stacktrace

主要产物位于：

ports/ohos/app/entry/build/default/outputs/default/
├── entry-default-unsigned.hap
└── entry-default-signed.hap

连接 HarmonyOS PC 后，可以安装并启动：

hdc list targets
hdc install -r \
  ports/ohos/app/entry/build/default/outputs/default/entry-default-signed.hap
hdc shell aa start -a EntryAbility -b org.teraterm.ohospc

本次构建完成了 Native CMake/Ninja、ArkTS 编译、HAP 打包与签名，Hvigor 返回 BUILD SUCCESSFUL；设备端覆盖安装返回 install bundle successfully，Ability 启动返回 start ability successfully。随后在真机上重新完成了启动、TCP 建连、输入发送、服务端回显、多会话创建和 File 面板检查。Native 侧的终端核心、transport、profile、known_hosts、SSH 配置和宏六组现有回归程序也全部正常退出。

七、当前功能边界

当前版本已经覆盖网络终端的主要使用路径：

• 多标签会话的创建、切换和关闭；
• TCP 与 Telnet 连接，以及 Telnet 常用协商和窗口尺寸更新；
• SSH2 密码/私钥认证、主机密钥检查和代理连接；
• 常用 ANSI/CSI、UTF-8、颜色样式、光标与有界滚屏；
• 键盘输入、复制粘贴、输出搜索和逐会话日志；
• TERATERM.INI 常用 Hosts 导入、连接 Profile 与显示设置持久化；
• HTTP CONNECT、TELNET、SOCKS4/SOCKS5 代理；
• SCP/SFTP 上传下载与 SSH 本地端口转发；
• 覆盖连接、发送、等待、分支、循环、变量、常用字符串与文件操作的 TTL 宏子集。

尚未达到完整对等的部分同样需要明确：USB 串口仍缺带真实适配器的设备权限与收发回环矩阵；终端解析器能够覆盖常见 CLI，但不是上游全部 VT/xterm 边缘行为的逐项复刻；TTL 解释器仍是常用子集；UI 目前以英文为主；Windows TTX DLL 插件 ABI、DDE、注册表和 CHM 帮助属于平台专属能力，当前没有迁移。

因此，现阶段更准确的定位是“Tera Term HarmonyOS PC 网络终端版本”。它已经能在真机上完成安装、启动、连接、收发、显示、多会话和日志配置主线，也具备 SSH 与文件传输的实现基础，但不应被描述成 Windows 版本所有协议边缘、插件和硬件场景的无差别替代品。

八、总结

Tera Term 的适配说明，传统 Windows 终端工具迁移到 HarmonyOS PC 时，最重要的不是保留每一个平台类型，而是保留用户能够感知和验证的连续工作流。ArkUI 承接桌面窗口、系统选择器、剪贴板与持久化，Node-API 建立稳定边界，C++ Native 核心负责终端状态和协议数据，最终让连接、输入、回显、多会话和日志在真机上形成闭环。

这次实践也给同类项目提供了一条可复用的顺序：先明确协议与终端语义，重建平台外壳；再用 Native 层承接需要性能和系统接口的部分；最后以真实设备上的双向数据、独立会话和落盘结果作为验收依据。对网络终端而言，窗口能够打开只是起点，数据确实从设备发出、由远端返回并被正确解释，才是适配真正成立的证据。