opsxshell/zhipu.md

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 代码库现状编写，后续迭代请同步更新。