# OpsXShell 专业工具化开发优化推荐

> 面向 OpsXShell 2.1.1（Tauri 2 + Rust + React/TS）打磨为专业 SSH / SFTP / VNC / RDP 运维终端的优化清单。
> 核心目标：**操作简单、人性化、跨平台一致**（Windows / Ubuntu / macOS）。
> 编写日期：2026-08-11。

---

## 0. 现状速览

| 模块 | 完成度 | 备注 |
|------|--------|------|
| SSH 连接 / 认证 / 会话 | ✅ 完整 | 密码、私钥、Agent、ProxyJump（≤8 跳） |
| 终端（xterm + 多窗格 + 广播 + Zmodem） | ✅ 完整 | 含断线重连、快照恢复 |
| SFTP 文件管理 | 🟡 基本完整 | 目录递归批量、传输冲突策略缺失 |
| 端口转发（Local/Remote/Dynamic） | ✅ 完整 | 实时可视化待补 |
| VNC | 🟡 基本可用 | **Tight JPEG 解码缺失**，剪贴板 Latin-1 |
| RDP（NLA / 剪贴板 / 文件共享） | ✅ 完整 | 多屏 / 双向文件待补 |
| 跨平台（Win / Mac / Linux） | ✅ 完整 | 签名公证 / 自动更新待补 |
| 主题 / i18n / 命令面板 | ✅ 完整 | — |

---

## 1. P0 — 立即修复（阻断性 / 数据正确性）

### 1.1 ⚠️ 修复凭据目录路径 typo（最高优先）

- **位置**：`src-tauri/src/services/credential_store.rs:3`
- **现状**：`const KEY_DIRECTORY: &str = ".opsxshsell";`（多了一个 `s`）
- **影响**：
  - 主密钥实际写入 `~/.opsxshsell/master.key`，与产品名 `OpsXShell`、文档约定 `~/.opsxshell/` 不一致。
  - 若后续修正常量但不加迁移，**所有已加密的会话密码 / 私钥口令 / 代理密码将无法解密**，用户数据丢失。
- **修复方案**：
  1. 改常量为 `.opsxshell`。
  2. 启动时检测旧目录 `~/.opsxshsell/` 是否存在；存在则原子迁移（移动 master.key 与所有加密文件到新目录，校验权限 0700/0600）。
  3. 迁移成功后保留旧目录备份 `.opsxshsell.bak`，记录迁移日志，避免误删。
  4. 加单元测试覆盖「旧目录存在 → 迁移 → 可解密」链路。

### 1.2 🔴 补齐 VNC Tight JPEG 解码

- **位置**：`src-tauri/src/services/desktop/vnc_engine.rs:312`
- **现状**：`VncEvent::JpegImage(rect, _data)` 直接丢弃，依赖下次 FullRefresh 用 Raw/Zrle 重绘脏区。
- **影响**：TigerVNC / TightVNC / RealVNC 默认偏好 Tight+JPEG 编码；当前会表现为**画面延迟、带宽飙升、拖影**，达不到专业工具水准。
- **方案**：
  1. 引入 `turbojpeg`（或 `mozjpeg-sys`）crate。
  2. 将 JPEG bytes 解码为 RGBA，复用现有 `extract_rect` / `putImageData` 路径写入 framebuffer。
  3. 解码失败时回退到当前的 raw refresh 兜底，保证可用性。
  4. 验收：连接 TightVNC 桌面播放视频，FPS 与带宽对比应明显改善。

### 1.3 🔴 SFTP 目录递归上传 / 下载

- **现状**：UI 层（`src/components/sftp/`）以单文件操作为主，拖拽整个目录缺少递归封装。
- **影响**：专业运维高频场景（部署目录、日志归档）当前体验不达标。
- **方案**：
  1. Rust 侧新增 `sftp_upload_dir(local_dir, remote_dir)` / `sftp_download_dir(remote_dir, local_dir)`，递归遍历 + `mkdir -p` + 保留 mtime/权限。
  2. 单条传输队列项可折叠显示子任务进度（已完成 N / 总 M 文件）。
  3. 失败任务支持「重试剩余」而非整体回滚。

### 1.4 错误信息人性化

- **现状**：前端常直接透传 Rust 错误字符串（如 `Io: Connection refused`）。
- **方案**：建立错误码 → 人话映射表：
  - `HostKeyChanged` → 「⚠️ 主机密钥已变更。若你刚刚重装系统这是正常的；若不是，可能存在中间人攻击。点击『更新并连接』或『拒绝』。」
  - `AuthFailed` → 「认证失败。请检查用户名 / 密码，或私钥口令是否正确。」
  - `ConnTimeout` → 「连接超时。请确认主机可达、防火墙已放行 22 端口。」
  - 每条提供「为什么 + 怎么办」两部分。

---

## 2. P1 — 专业工具基线（近期）

### 2.1 传输队列增强

- **冲突策略对话框**：目标已存在时弹出 — 覆盖 / 跳过 / 重命名 / 断点续传（已有 `.opsx-part` 机制，需暴露到 UI）。
- **全局速率限制**：可配上限（如 10 MiB/s），避免占满办公带宽。
- **并发控制**：同时活跃 3~5 个传输，其余排队。
- **失败自动重试**：N 次指数退避 + 手动「重试」按钮。
- **单位规范**：统一使用 `MiB/s`、`KiB/s`（运维语境，非 SI 单位）。

### 2.2 端口转发实时可视化

- 每条运行中规则显示：
  - ✓ 活跃连接数
  - ↑↓ 累计字节 / 实时速率
  - 远端 ping 延迟条
  - 失败时红点 + 错误原因 tooltip
- 规则修改前强制停止 Listener（`AGENTS.md` 已规定，UI 需显式引导）。

### 2.3 RDP 文件共享双向化

- **现状**：`rdpdr_fs.rs` 单文件 50MB 上限，仅挂载本地 `Downloads`。
- **方案**：
  1. 上限可配（默认提升到 200MB）。
  2. 本地→远端上传进度条（已有 `upload_file` 命令，补 UI 进度）。
  3. 可选挂载任意本地目录（而非固定 Downloads）。
  4. 远端「此电脑」显示中文友好名。

### 2.4 三平台签名 / 公证 / 自动更新

| 平台 | 必做项 |
|------|--------|
| macOS | Apple Developer ID 签名 + 公证 + Hardened Runtime + Notarization staple |
| Windows | EV / OV 代码签名证书 + SmartScreen 信誉积累 |
| Linux | AppImage / deb / rpm，glibc 版本对齐 Ubuntu 22.04 LTS |

- 接入 Tauri Updater，签名 manifest，CI 自动发布到 GitHub Releases。
- **`AGENTS.md` 已规定**：无签名凭据不得宣称完成签名 / 公证。规划时需先取得凭据。

### 2.5 VNC 剪贴板 UTF-8 化

- **现状**：`vnc_engine.rs` CutText 走 Latin-1 降级，**中文 / 日文必乱码**。
- **方案**：升级到 UTF-8 编解码；远端不支持 UTF-8 时回退 Latin-1 并提示用户。

---

## 3. P2 — 体验跃升（中期）

### 3.1 终端效率链路

- **Cmd/Ctrl + 点击文件路径** → 直接唤起 RemoteTextEditor 远程编辑（已存在组件，打通调用链）。
- **选中即复制 + 右键粘贴**：作为可选开关（对齐 iTerm2 / Windows Terminal）。
- **WebLinks 点击二次确认**：防止 ANSI 注入钓鱼链接。
- **SSH Agent 转发开关**：`auth.rs` 已支持 Agent 认证，补 ForwardAgent 请求开关。
- **tmux / screen 集成**：检测远端已 attach 会话时提示恢复。

### 3.2 RDP 多屏 / 全屏

- 全屏模式 + 远程显示器选择（`DesktopSessionView` 当前单 canvas）。
- 动态 DesktopResize PDU：窗口缩放时同步调整远端分辨率。

### 3.3 命令面板扩展

- `CommandPalette` 已存在，扩展 fuzzy 索引：
  - 会话 / 文件 / 隧道规则 / 最近主机 / 快捷动作。
- 快捷键：`Cmd+K`（macOS）/ `Ctrl+K`（Win/Linux）全局唤起。

### 3.4 首次启动引导

- `WelcomeView` 3 步引导：添加主机 → SSH 连接 → 文件传输。
- 降低运维新手门槛，体现"操作简单"产品定位。

### 3.5 SFTP 体验细节

- 文件覆盖前差异预览：双方 size / mtime / SHA256。
- 多选批量 chmod（`ChmodDialog` 已支持单文件）。
- 符号链接：`list` 是否返回 symlink target 需确认，UI 区分展示。

---

## 4. P3 — 差异化竞争力（加分项）

| 项 | 说明 |
|----|------|
| VNC VeNCrypt / TLS | 支持加密 VNC，公网可用 |
| RDP 远程音频重定向 | `rdpsnd` 依赖已引入，补 UI 开关 |
| RDP 打印机重定向 | 按需评估 |
| 本地终端 + 串口 | 已实现，打磨 Tab 体验即可 |
| AI 运维助手 | 已实现多 provider，可对接当前 SSH 会话上下文 |
| 会话分组 / 标签 / 着色 | 大量主机时的组织能力 |
| 配置导入 | 支持 Termius / Royal TS / .ssh/config 导入，降低迁移成本 |

---

## 5. 跨平台验收清单

> 平台安装包必须在目标系统**实机验收**（`AGENTS.md` 规定）。

### Windows
- [ ] ConPTY（Win10 1903+）下中文 / IME / 彩色正常
- [ ] Ctrl 组合键、Alt 键映射正确
- [ ] 右键粘贴、选中即复制开关生效
- [ ] SFTP 本地面板路径分隔符 `\` vs `/` 一致
- [ ] Deep Link `ssh://` / `opsxshell://` 注册表写入与卸载清理
- [ ] 代码签名 + SmartScreen 验证

### Ubuntu / Linux
- [ ] Ubuntu 22.04 / 24.04 glibc 兼容
- [ ] Wayland 下 IME、HiDPI 缩放
- [ ] deb / rpm / AppImage 三种包格式
- [ ] AppImage 可执行权限提示友好
- [ ] 系统托盘（可选）

### macOS
- [ ] Apple Developer ID 签名 + 公证
- [ ] Gatekeeper 直接打开（无需右键绕过）
- [ ] retina HiDPI 终端清晰
- [ ] 触控板手势（双指缩放映射到 VNC/RDP 远端）
- [ ] DMG 安装体验

---

## 6. 推荐实施顺序

```
第 1 周：P0
  ├─ 凭据目录 typo 修复 + 迁移逻辑（含测试）
  ├─ VNC Tight JPEG 解码
  ├─ SFTP 目录递归
  └─ 错误信息人性化映射表

第 2-3 周：P1
  ├─ 传输队列冲突策略 + 限速 + 并发
  ├─ 端口转发实时可视化
  ├─ VNC 剪贴板 UTF-8
  └─ RDP 文件共享双向化

第 4 周+：P1 收尾
  ├─ 取得签名凭据 → 三平台签名公证
  └─ 自动更新通道搭建

后续：P2 / P3 按用户反馈迭代
```

---

## 7. 关键约束（来自 AGENTS.md，开发时必须遵守）

- 未由 Rust 后端实现的能力不能在界面中显示为可用。
- 会话密码 / 私钥口令 / 代理密码必须由 Rust 加密后落盘。
- 不保存终端命令历史；批量命令结果仅保留在当前窗口。
- 主机密钥使用 `~/.ssh/known_hosts` 校验，显式拒绝 TOFU。
- 主密钥位于 `~/.opsxshell/master.key`，Unix 目录权限 0700、文件权限 0600。
- 端口转发规则可持久化，运行中状态不得持久化；停止操作必须关闭真实原生 Listener。
- SFTP read/write 不得作为 upload/download 别名；本地 / 远程路径不得含糊调用。
- 大模型新配置必须先用临时凭据完成真实测试，不得提前写 settings 或 secrets。
- `ssh://` 禁止携带密码或静默直连，必须经原生有界队列确认。
- 平台安装包必须在目标系统实机验收；无签名凭据不得宣称完成签名 / 公证 / 自动更新。

---

*本文档基于 2026-08-11 代码库现状编写，后续迭代请同步更新。*