whc-shell/README.md

WHC Shell

为物理键盘和鼠标设计的 Android 终端。它通过 SSH 连接本机 Termux（127.0.0.1:8022）， 目标是在平板 + 键盘鼠标上获得接近桌面终端的体验，尤其是 TUI 程序（如 CST-Agent、vim、htop）。

特性

• 完整键盘：xterm 修饰键编码（Ctrl/Alt/Shift + 方向键、功能键、PgUp/PgDn 等）、 xterm modifyOtherKeys、kitty 键盘协议 （disambiguate 级别，主屏/备用屏分开的栈），能区分 Shift+Enter、Ctrl+Backspace、Ctrl+I 与 Tab、单独的 Esc。
• 鼠标：1000/1002/1003 上报 + SGR 1006、焦点事件 1004、滚轮；按住 Shift 绕过程序的鼠标上报改为本地选择。
• 选择与剪贴板：拖动选择、双击选词、三击选行，拖到边缘自动滚动；中键粘贴上次选中内容； 右键菜单；支持程序通过 OSC 52 写剪贴板；粘贴使用 bracketed paste。
• 触屏：拖动滚动回滚区，轻点弹出软键盘，长按选词并弹出菜单；支持中文输入法。
• 外观同步：连接后通过 SFTP 读取 Termux 的 ~/.termux/font.ttf、colors.properties、 termux.properties（光标样式、闪烁、边距），与 Termux 保持一致。
• SSH：首次用密码登录后自动把本机 Ed25519 公钥写入 ~/.ssh/authorized_keys，以后免密； 主机密钥首次信任并记录指纹，变化时提示。
• 回滚 10000 行，F11 全屏，Ctrl+滚轮缩放字体。

使用

1. 在 Termux 里安装并设置 sshd：

   pkg install openssh
   passwd    # 设置登录密码，首次连接用
   sshd      # 默认监听 8022
   

2. 打开 WHC Shell，输入 Termux 密码。之后会自动用密钥登录。

可选：让 WHC Shell 在连不上时自动拉起 sshd。在 ~/.termux/termux.properties 里加上 allow-external-apps = true，然后执行 termux-reload-settings，并在 WHC Shell 首次请求时 授予“在 Termux 中运行命令”权限。

连接断开后按 Enter 重新连接。

快捷键

按键	作用
Ctrl+Shift+C / V	复制选中内容 / 粘贴
Ctrl+Shift+A	全选
Ctrl+Shift+= / - / 0	放大 / 缩小 / 恢复字号（也可 Ctrl+滚轮）
Shift+PgUp / PgDn	滚动回滚区（主屏）
Ctrl+Shift+PgUp / PgDn / Home / End	滚动回滚区 / 到顶 / 到底
F11	全屏
物理键盘的返回键	Esc
右键	菜单（复制、粘贴、全选、缩放、全屏、重新连接）
中键	粘贴上次选中的内容

其余按键全部原样发给终端程序。

构建

依赖 JDK 17、Gradle 8.14、Android SDK（platform 35、build-tools 35.0.0）。NixOS 上 shell.nix 已备好：

nix-shell --run 'gradle --no-daemon assembleDebug testDebugUnitTest'
nix-shell --run 'adb install -r app/build/outputs/apk/debug/app-debug.apk'

SshKeysTest 里的真实 sshd 登录测试需要设置 WHC_SSHD_PORT 和 WHC_SSHD_KEYDIR，否则跳过。

最低 Android 8.0（API 26）。

许可

终端模拟器和渲染器源码来自 termux-app v0.118.3 的 terminal-emulator 与 terminal-view（Apache License 2.0），修改内容见 NOTICE； termux-app 其余 GPLv3 部分未使用。SSH 使用 sshj 与 Bouncy Castle。