客户端手册Client manual

平台Platforms

Intel Mac 与 ARM Windows 暂无构建；关注 release 页后续架构。 No Intel Mac or ARM Windows builds yet; watch the release pages for more architectures.

主界面与会话Main UI & sessions

• 侧栏：Sessions / Devices 两个页签。会话按自定义分组折叠展示，分组可重排、重命名、删除；会话支持拖拽排序与跨组拖动，排序随账号漫游。Sidebar: Sessions / Devices tabs. Sessions fold into custom groups (reorderable, renamable, deletable); sessions themselves drag-sort within and across groups, and the order roams with your account.
• 过滤器：三个开关——只看已连接（attached）、只看已完成待查看（Done）、只看待办（pending 旗标，右键会话切换）。Filters: three toggles — attached only, done-but-unseen only, pending-flagged only (toggle the flag from the session context menu).
• 会话行：状态徽章（running / starting / offline / lost / exited）+ 活动指示（「工作中」圆点 / 「完成待看」对勾，跨设备同步）；悬停出状态卡（状态、P2P 通路、可复制的完整会话 ID）。名字未通过签名校验时显示 ❔。Session rows: status badge (running / starting / offline / lost / exited) + activity indicator ("working" dot / "done" checkmark, synced across devices); hover for a status card (state, P2P path, copyable full session id). An ❔ badge appears when the name fails signature verification.
• 右键 / 长按菜单：重命名（防篡改签名）、在同机快速新建、新窗口打开（桌面）、移动分组、detach、会话详情、关闭（offline 会话额外确认）。Context menu: rename (tamper-proofed by signature), quick-new on the same machine, open in a new window (desktop), move group, detach, session details, close (with extra confirmation for offline sessions).
• 新建会话：选择设备（搜索 / 按最近或字母排序）、可选名称与高级参数（命令、参数、工作目录、分组）；默认 shell 按设备 OS 解析（zsh / bash / cmd.exe）。New session: pick a device (searchable, sortable by recency or name), optional name and advanced parameters (command, args, working directory, group); the default shell resolves by the device OS (zsh / bash / cmd.exe).

终端Terminal

• 渲染：全屏 TUI 原样呈现（alt-screen、256 色、滚动区域），10000 行回看缓冲；字号 10–24、等宽字体可选（预设 + 自定义）。Rendering: fullscreen TUIs render as designed (alt-screen, 256 colors, scroll regions) with a 10,000-line scrollback; font size 10–24 and selectable monospace fonts (presets + custom).
• 移动端手势：双指滚动回看、双指捏合调字号。Mobile gestures: two-finger scroll for scrollback, pinch to zoom the font.
• Freeze：冻结输出便于回看（FROZEN 徽章），导航菜单提供顶部 / 上翻 / 下翻 / 底部、Fit 重适配、刷新快照、清屏（Ctrl+L）、Paste File。Freeze: freeze output for review (FROZEN badge); the nav menu offers top / page-up / page-down / bottom, Fit, snapshot refresh, clear (Ctrl+L), and Paste File.
• 选区与链接：移动端长按、桌面右键唤出菜单（预览、复制、折行复制、打开链接、View in Files）；URL 自动识别可点开。Selection & links: long-press (mobile) or right-click (desktop) for the menu (preview, copy, copy-wrapped, open link, View in Files); URLs are auto-detected and clickable.
• 快捷键：Ctrl+Shift+C / V 复制粘贴，另有 6 项应用内快捷键可自定义；桌面壳可注册全局呼出热键。Shortcuts: Ctrl+Shift+C / V for copy/paste plus six customizable in-app shortcuts; the desktop shell can register a global summon hotkey.
• 粘贴安全：strict / lenient / off 三档，拦截危险的多行粘贴（防「粘贴炸弹」）。Paste safety: strict / lenient / off — intercepts dangerous multi-line pastes.
• 断线与恢复：断线出全屏重连面板（倒计时、手动重试、日志），可折叠成右上角 Reconnecting 胶囊，期间终端内容仍可查看复制；多会话并行 attach 保活，切换时快照回放现场。Reconnect: a full-screen panel on disconnect (countdown, manual retry, logs), collapsible into a corner capsule — the terminal stays viewable and copyable meanwhile; multiple sessions stay attached in parallel, switching replays the snapshot.
• 主题：System / Dark / Light 跟随或固定；设置里可自定义亮暗双色板并导出 JSON。Themes: System / Dark / Light, plus custom light/dark palettes exportable as JSON.
• Vibe 模式（桌面）：底部 inputbox 整段输入直接发给 claude / codex 等 TUI，免去逐键模拟。Vibe mode (desktop): a bottom inputbox sends whole paragraphs to claude / codex TUIs instead of per-key typing.

软键盘Soft keyboard

• 布局：折叠功能条（Esc / Ctrl / Tab / Alt / 方向 / PgUp / PgDn / Snip / 退格 / Enter）+ 展开 QWERTY 与符号层；键盘布局含 qwerty / azerty / 法语 / cyrillic / 假名。Layout: a collapsed utility strip (Esc / Ctrl / Tab / Alt / arrows / PgUp / PgDn / Snip / backspace / Enter) plus the expanded QWERTY and symbol layers; qwerty / azerty / French / Cyrillic / kana layouts.
• 手势：长按弹出候选横排（拖远取消）、上滑出备用字符、下滑大写、左右滑动移动光标。Gestures: long-press for the candidate strip (drag away to cancel), flick up for the alternate char, flick down for caps, sideways swipes move the cursor.
• 可调：长按时延、滑动增益与触发距离、震动反馈、字母动画。Tunables: long-press delay, swipe gain and trigger distance, haptics, key animation.
• Snippets：片段库（标签 + 内容），可排序，插入时支持换行 / Tab / ESC。Snippets: a snippet library (label + body), reorderable; insertions can carry newlines / Tab / ESC.

文件管理Files

• 浏览与操作：Files 页面包屑导航（Windows 可切盘符）、新建文件夹 / 文件、多选上传、下载、重命名 / 删除 / 属性、隐藏点文件开关、名称过滤。Browse & operate: the Files tab has breadcrumb navigation (drive switcher on Windows), new folder/file, multi-select upload, download, rename/delete/properties, dotfile toggle, name filter.
• 查看 / 编辑器：内置文件预览与编辑（预览↔编辑切换、自动换行、保存、编码显示）。Viewer/editor: built-in preview and editing (toggle, word wrap, save, encoding display).
• 浮动面板（桌面）：Files 以浮窗打开，不挤占终端空间，可最大化 / 折叠 / 缩放。Floating panel (desktop): Files opens as a floating window that never crowds the terminal — maximize, collapse, resize.
• 文件粘贴：Ctrl+V 粘贴带文件的剪贴板会自动上传到设备并把绝对路径注入 PTY——等效本地拖文件进终端；可在设备设置里按设备关闭。Paste files: Ctrl+V with files on the clipboard uploads them and injects the absolute path into the PTY — like dragging a file into a local terminal; can be disabled per device.

设备管理Device management

• 添加设备向导：生成 Linux/macOS 与 Windows 安装命令（一次性令牌）、公钥展示、令牌状态跟踪、安装进度（issued → registered → online）。Add-device wizard: generates the Linux/macOS and Windows install commands (one-time token), shows the public key, tracks token state and install progress (issued → registered → online).
• 每设备设置：P2P 开关、剪贴板文件粘贴开关、该机会话的默认覆盖项。Per-device settings: P2P toggle, clipboard-file-paste toggle, default overrides for sessions on that machine.
• 生命周期：设备分组管理、重命名、吊销 / 恢复、删除。Lifecycle: device grouping, rename, revoke / resume, delete.

连接与信任Connection & trust

• TOFU 首连：首次连接核对设备上的 16 位指纹（或 26 位身份信任码）；可选「跳过验证」（需确认风险），但密钥轮换时必须验证、不可跳过。TOFU first connect: verify the 16-hex fingerprint from the device (or the 26-char identity trust code); "skip verification" exists but demands a risk confirmation — and key rotation always requires verification.
• 连接密钥：设置里显示本机公钥与二维码，可复制导入；桌面壳走原生密钥库，支持自定义密钥文件与多钥匙注册表（默认钥匙、按设备绑定）。Connection keys: settings show your public key and QR code to copy/import; the desktop shell uses the native keystore with custom key files and a multi-key registry (default key, per-device binding).
• 设备密码：设备上 omtc passwd 设置后，新浏览器可用密码直连（PAKE 认证，密码不上线）。Device password: after omtc passwd on the device, a new browser can connect with the password (PAKE — the password never crosses the wire).
• 签名确认：授权公钥等敏感签名在桌面壳的原生确认小窗完成，密钥不经过页面 JS。Signed approvals: sensitive signatures (e.g. authorizing a pubkey) happen in the shell's native confirm dialog — keys never touch the page JS.

登录与账号Sign-in & account

• 登录方式：密码 + TOTP（可记住设备 30 / 60 / 90 天）、OAuth（按服务器配置：钉钉 / 飞书 / GitHub / Google）、开放注册（服务器开启时）。Sign-in: password + TOTP (remember-device 30 / 60 / 90 days), OAuth (server-configured: DingTalk / Feishu / GitHub / Google), open registration (when enabled server-side).
• 账号设置：Profile（显示名 / 邮箱）、改密码、登出全部设备、TOTP 绑定 / 解绑、Linked Accounts 管理、删除账号（需密码 + TOTP 或 OAuth 再授权）。Account settings: profile (display name / email), change password, log out everywhere, TOTP bind/unbind, linked accounts, account deletion (password + TOTP or an OAuth re-auth).
• Trusted Devices：查看并管理已信任的浏览器设备指纹（重命名 / 吊销）。Trusted devices: review and manage trusted browser fingerprints (rename / revoke).
• 备份：客户端配置导出 / 导入（不含私钥与令牌）。Backup: export/import client configuration (never keys or tokens).

更新与源Updates & sources

• 三级更新，互相独立验签：omta 页面 OTA（Ed25519 验签 → 下载校验 → 原子激活，30 秒健康检查看门狗失败自动回滚；支持热切换）；omtn 壳自检（读签名 metainfo，仅提醒不自动安装）；omtd 产物下载器（验签 + 哈希校验后保存）。Three independent, separately-verified update paths: the omta page OTA (Ed25519-verified manifest → hash-checked download → atomic activation with a 30s watchdog rollback; hot-swap supported); the omtn shell self-check (signed metainfo, remind-only); the omtd artifact downloader (signature + hash verified before saving).
• 版本弹窗：一次展示 omts / omta / omtn 三个组件的版本与说明，附按平台的下载卡片。Version dialog: shows omts / omta / omtn versions and notes in one place, with per-platform download cards.
• 源切换：更新通道一键切换 GitHub / Gitee 国内镜像（同签名资产）；omtc 安装源自定义与存量设备迁移命令；启动自动检查可关。Sources: one-click channel switch between GitHub and the Gitee mirror (same signed artifacts); custom omtc install source with a migration command for existing devices; startup auto-check is optional.

桌面壳与移动端Desktop shell & mobile

• 窗口：主窗口 + 多终端窗口（可直达指定会话）+ 独立 admin 窗口；窗口标题跟随当前会话。Windows: main window plus multiple terminal windows (deep-linking a session) plus a standalone admin window; the window title follows the current session.
• 托盘（Windows / macOS）：托盘菜单 Show / Reload / Change omts URL / Quit；关最后一个终端窗即隐藏到托盘；macOS Dock 点击恢复。Linux 无托盘，关窗即退出。Tray (Windows / macOS): Show / Reload / Change omts URL / Quit; closing the last terminal window hides to tray; macOS restores from the Dock. Linux has no tray — closing quits.
• 更新与安全：壳永不加载远端页面——构建期内嵌 omta，运行期只信通过验签的 OTA 产物；服务器地址改动、更新通道变更都要原生确认。Update & safety: the shell never loads remote pages — omta is embedded at build time and only signature-verified OTA output is trusted at runtime; server-URL and channel changes need native confirmation.
• 移动端：OAuth 走系统会话（iOS ASWebAuthenticationSession / Android 系统浏览器 + 回跳）；Android 有原生快捷键桥、APK 自更新、分享身份备份；iOS 键盘直连（inputmode=none）；Play 版含内购与并发终端配额。Mobile: OAuth rides the system session (iOS ASWebAuthenticationSession / Android browser + return hop); Android adds a native shortcut bridge, APK self-update, and share-to-backup of identity; iOS drives the keyboard directly (inputmode=none); the Play build adds billing and a concurrent-terminal quota.

其他Miscellany

• 语言：界面中 / 英，默认跟随浏览器。Language: Chinese / English UI, following the browser by default.
• Remote Debug：生成授权码让运维（或别人）连上你已打开的页面协助排障——连上自动复制、TTL 倒计时、可续期、可勾选允许写入。Remote Debug: mint an authorization code to let an operator attach to your already-open page for troubleshooting — auto-copied, TTL countdown, extendable, write access opt-in.
• P2P 指示：直连会话在徽章高亮；中继被禁用时出横幅提示。P2P indicator: direct sessions highlight the badge; a banner appears when the relay is disabled.
• Help：内置入门指南、错误码、词汇表与搜索。Help: built-in getting-started guide, error codes, glossary, and search.