Add README

README.md

@@ -0,0 +1,74 @@
+# WHC Shell
+
+为物理键盘和鼠标设计的 Android 终端。它通过 SSH 连接本机 Termux（`127.0.0.1:8022`），
+目标是在平板 + 键盘鼠标上获得接近桌面终端的体验，尤其是 TUI 程序（如
+[CST-Agent](https://git.whcself.xyz/WHC/CST-agent)、vim、htop）。
+
+## 特性
+
+- **完整键盘**：xterm 修饰键编码（Ctrl/Alt/Shift + 方向键、功能键、PgUp/PgDn 等）、
+  xterm `modifyOtherKeys`、[kitty 键盘协议](https://sw.kovidgoyal.net/kitty/keyboard-protocol/)
+  （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：
+
+   ```sh
+   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` 已备好：
+
+```sh
+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](https://github.com/termux/termux-app) v0.118.3 的
+`terminal-emulator` 与 `terminal-view`（Apache License 2.0），修改内容见 [NOTICE](NOTICE)；
+termux-app 其余 GPLv3 部分未使用。SSH 使用 [sshj](https://github.com/hierynomus/sshj)
+与 Bouncy Castle。