docs: update README and guides to include new features such as Windows drag-and-drop support, enhanced file transfer capabilities, and diagnostics settings for improved user experience

2026-09-22 08:01:31 +00:00 · 2026-04-23 14:40:39 +08:00
parent 82a89a5988
commit 1d49ee59df
7 changed files with 112 additions and 18 deletions
@@ -30,8 +30,9 @@ Dragonfly is a desktop client for SSH-centric operations and mixed terminal work
 ### Remote operations

 - Built-in SFTP file explorer with upload, download, rename, move, delete, symlink, and properties
- Transfer queue with pause, resume, cancel, retry, timestamp preservation, duplicate handling, and configurable concurrency
+- Folder upload, multi-select actions, editable path bar, and manual / automatic sync with terminal cwd
 - Open remote files in a local editor and upload changes back through the watcher flow
+- Windows support for dragging local files or folders directly into the file explorer to upload
 - Quick Commands with categories, colors, icons, execution modes, pinning, and variable prompts

 ### Security and networking
@@ -40,6 +41,7 @@ Dragonfly is a desktop client for SSH-centric operations and mixed terminal work
 - OTP management with TOTP/HOTP, QR import, and SSH auto-fill support
 - Screen lock, master password support, and known-hosts management
 - Proxy configs, SSH jump hosts, and local / remote / dynamic tunnels
+- Diagnostics settings, local log management, and diagnostics bundle export for troubleshooting

 ### Sync, backup, and portability

@@ -48,8 +50,6 @@ Dragonfly is a desktop client for SSH-centric operations and mixed terminal work
 - Startup sync checks, debounced auto-push after supported local changes, and scheduled backup retention policies
 - Manual test / push / pull / backup actions, remote backup restore, and snapshot-level conflict resolution
 - Session import from Xshell, MobaXterm, and WindTerm, plus full-app encrypted `.dgfy` import / export
- Diagnostics bundle export for troubleshooting and support
- Dedicated **Sync & Backup** settings tab plus an in-workspace activity history panel

 ## Supported session types

@@ -67,6 +67,7 @@ The detailed user docs live in `docs-site/`.
 - Product overview: [docs-site/docs/intro.md](docs-site/docs/intro.md)
 - Quick start: [docs-site/docs/getting-started/quick-start.md](docs-site/docs/getting-started/quick-start.md)
 - Guides: [docs-site/docs/guide/](docs-site/docs/guide)
+- File transfer guide: [docs-site/docs/guide/file-transfer.md](docs-site/docs/guide/file-transfer.md)
 - Sync and backup guide: [docs-site/docs/guide/sync-and-backup.md](docs-site/docs/guide/sync-and-backup.md)
 - Development docs: [docs-site/docs/development/](docs-site/docs/development)

@@ -50,10 +50,13 @@ Dragonfly 支持以下操作系统：
 建议在正式投入使用前，先快速浏览以下几项：

 - **设置 → 常规**：启动恢复、关闭时最小化到托盘、关闭确认
+- **设置 → 常规**：日志级别、日志保留时间、打开日志目录、导出诊断包
 - **设置 → 交互**：命令建议开关、历史命令长度范围、复制与右键粘贴
- **设置 → 传输**：默认下载目录、默认编辑器、录制保存路径
+- **设置 → 传输**：默认下载目录、默认编辑器、录制保存路径、并发与重试策略
 - **设置 → 安全**：主密码、锁屏、主机密钥策略

+如果你经常在后台保留会话或同步任务，**关闭时最小化到托盘** 值得优先确认。
+
 ## 如果你要迁移旧环境

 如果你之前已经在其他工具中维护会话，安装后可以直接导入：
@@ -65,6 +68,12 @@ Dragonfly 支持以下操作系统：

 如果你的目标是完整恢复 Dragonfly 配置，优先使用 `.dgfy`；它会恢复的不只是连接，还包括更多本地配置数据。

+需要注意：
+
+- `.dgfy` 导入 / 导出需要先设置主密码
+- 导入 `.dgfy` 后通常需要重启应用
+- 普通会话导入更适合迁移连接列表，不会替代完整配置恢复
+
 ## 第一次体验建议

 如果你是第一次使用，建议按这个顺序体验：
@@ -74,3 +83,4 @@ Dragonfly 支持以下操作系统：
 3. 再创建一个 **本地终端**，体验混合工作区
 4. 在 SSH 会话里打开文件浏览器和传输面板
 5. 试试命令历史、快捷命令、录制与终端搜索
+6. 如果你在 Windows 上，可额外尝试把本地文件或文件夹直接拖到文件浏览器中上传
@@ -52,6 +52,8 @@ Dragonfly 支持从以下来源导入：
 - `.dgfy` 导入适合恢复完整本地配置
 - `.dgfy` 导入 / 导出需要先设置 **主密码**

+如果你只是想迁移 SSH 主机，通常从 **已保存连接** 面板的导入入口开始更快；如果你要恢复完整 Dragonfly 环境，再使用 `.dgfy` 更合适。
+
 ## 第四步：启动并理解工作区

 双击已保存连接，或者右键选择连接，即可启动会话。
@@ -82,10 +84,18 @@ Dragonfly 支持从以下来源导入：

 ### 3. 打开远程文件浏览器和传输队列

-SSH 会话激活后，文件浏览器面板可直接浏览远程目录，并支持上传、下载、删除、移动、属性查看等操作。
+SSH 会话激活后，文件浏览器面板可直接浏览远程目录，并支持：
+
+- 上传文件 / 上传文件夹
+- 下载、删除、移动、重命名、属性查看
+- 路径栏点击编辑并跳转
+- 复制路径或发送路径到终端
+- 与终端当前目录手动 / 自动同步

 如果你发起上传或下载，传输面板会显示队列进度，并支持暂停、继续、取消和失败重试。

+如果你在 Windows 上使用 Dragonfly，还可以尝试把本地文件或文件夹直接拖进文件浏览器上传。
+
 ### 4. 打开命令历史和快捷命令

 - **命令历史** 适合回溯与模糊检索
@@ -97,6 +107,8 @@ SSH 会话激活后，文件浏览器面板可直接浏览远程目录，并支
 - **最小历史命令长度**
 - **最大历史命令长度**

+这些长度限制只影响历史命令建议，不影响快捷命令本身的可用性。
+
 ### 5. 试一次终端搜索 / 在线搜索 / 翻译

 在终端中选中文本后，可以通过右键菜单：
@@ -123,6 +135,20 @@ Dragonfly 支持把当前会话输出录制为日志文件。

 如果你希望把录制文件集中保存到固定目录，可以先在 **设置 → 传输** 里设置 **录制保存路径**。

+### 8. 看一下通用设置和诊断入口
+
+在正式长期使用前，建议先快速看一遍这些设置分组：
+
+- **设置 → 常规**：启动恢复、关闭时最小化到托盘、关闭确认
+- **设置 → 交互**：命令建议、历史命令长度过滤、复制与右键粘贴
+- **设置 → 传输**：下载目录、默认编辑器、录制路径、传输并发
+- **设置 → 安全**：主密码、锁屏、主机密钥策略
+
+如果你在排查问题，**设置 → 常规** 里还能直接：
+
+- 打开本地日志目录
+- 导出诊断包
+
 ## 第六步：可选配置同步与备份

 如果你希望把常用配置做跨设备同步，或给当前设备准备可恢复的加密备份，可以继续：
@@ -13,38 +13,71 @@ Dragonfly 的远程文件能力建立在 SSH 会话之上。也就是说，**文
 你会得到这些基础能力：

 - 自动进入远端用户主目录
- 进入文件夹、返回上级、手动输入路径跳转
- 刷新当前目录
+- 进入文件夹、返回上级、刷新当前目录
+- 点击路径栏直接编辑并跳转到目标路径
 - 与终端当前工作目录同步
 - 在不支持路径跟踪的会话中关闭自动同步
+- 复制当前目录路径，或把路径直接发送到终端输入区
+
+路径栏支持 `~` 和 `~/subdir` 形式的输入，适合快速跳转到主目录或常用子目录。

 ## 常见文件操作

-在文件列表或右键菜单中，你可以执行：
+在文件列表、工具栏或右键菜单中，你可以执行：

 | 操作 | 说明 |
 |------|------|
 | 打开 | 下载到本地临时目录后，用默认编辑器打开 |
-| 上传文件 | 选择本地文件上传到当前目录 |
+| 上传文件 | 选择一个或多个本地文件上传到当前目录 |
 | 上传文件夹 | 整个目录上传到当前远端路径 |
-| 下载 | 下载单个文件或整个目录 |
+| 下载 | 下载单个文件、多个已选文件，或整个目录 |
 | 重命名 | 修改远端名称 |
 | 移动 | 把文件或目录移动到新路径 |
-| 删除 | 删除文件或目录 |
+| 删除 | 删除单个文件，或批量删除当前选中的多个条目 |
 | 属性 | 查看大小、时间、UID/GID、权限等信息 |
 | 新建文件 / 文件夹 / 符号链接 | 在当前目录中直接创建 |

 其中“打开”并不只是只读预览，而是为后续本地修改后回传做准备。

+## 选择、多选与批量操作
+
+当前文件浏览器已经支持更接近日常文件管理器的选择方式：
+
+- 单击选择单个条目
+- `Ctrl / Cmd` 多选
+- `Shift` 范围选择
+- `Ctrl / Cmd + A` 全选当前目录条目
+- `Delete` 删除当前选中条目
+
+当你选中了多个条目后，工具栏中的**下载**和**删除**会直接对当前选择生效；如果在多选状态下对某个已选条目打开右键菜单，相关批量操作也会作用于整组选中项。
+
 ## 上传与下载

 ### 上传

-可通过工具栏或右键菜单把本地文件上传到当前目录。
+可通过工具栏、右键菜单或拖拽把本地内容上传到当前目录。

- 多个文件会逐个加入传输流程
+- 上传文件时可一次选择多个本地文件
 - 上传目录时会保留目录结构
- 对 SSH 场景适合拿来同步脚本、配置文件或发布包
+- 上传目录与上传文件会统一进入传输队列
+- 适合用来同步脚本、配置文件、发布包或整组静态资源
+
+### Windows 外部拖拽上传
+
+在 Windows 上，文件浏览器支持把资源管理器中的**文件或文件夹直接拖到 Dragonfly 文件浏览器区域**进行上传。
+
+典型流程：
+
+1. 打开一个 SSH 会话并进入文件浏览器
+2. 把本地文件或文件夹拖到文件列表区域
+3. 出现拖拽覆盖层后松手
+4. Dragonfly 自动把它们加入上传流程
+
+需要注意：
+
+- 这是当前的 **Windows 平台特性**
+- 只有拖到文件浏览器列表区域才会触发上传
+- 某些拖拽来源如果没有暴露本机真实路径，Dragonfly 无法直接解析，这时会提示你改用 **上传文件** 或 **上传文件夹**

 ### 下载

@@ -96,11 +129,14 @@ Dragonfly 会把上传 / 下载任务统一放进传输队列中，便于你查

 文件浏览器可以和当前 SSH 终端的工作目录配合使用：

- **手动同步**：把浏览器直接跳到终端当前路径
- **自动同步**：终端 `cd` 到新目录后，文件浏览器自动跟随
+- **手动同步**：点击同步按钮，把浏览器直接跳到终端当前路径
+- **自动同步**：开启自动同步后，终端 `cd` 到新目录时，文件浏览器自动跟随
+- **发送到终端**：把当前目录路径或某个文件路径直接发到终端输入区，便于继续补命令

 这对边跑命令边查文件非常有用，例如你在终端里进入某个发布目录后，文件浏览器会更容易保持在同一位置。

+如果当前会话没有可用的终端路径跟踪能力，手动 / 自动同步入口会变为不可用状态；这通常意味着该会话暂时不能向后端稳定报告 cwd 变化。
+
 ## 本地编辑后自动回传

 这是 Dragonfly 很适合真实运维场景的一项能力。
@@ -76,6 +76,8 @@ Dragonfly 的核心体验不是“单个终端标签页”，而是一个可组
 - Security/Auth
 - Sync & Backup

+其中 **文件浏览器** 不只是静态目录树：在 SSH 会话中，它可以和当前终端 cwd 联动，并支持把当前目录或条目路径直接发回终端继续补命令。
+
 其中 **Sync & Backup** 面板更偏“跨设备配置同步 / 备份恢复”的运行态入口：它会展示当前状态、最近的同步与备份活动，并在发生冲突时提供直接处理入口。

 如果你只是想快速知道“最近同步成功了吗”“上次备份有没有失败”，在工作区历史面板里查看通常比回到设置页更直接。
@@ -117,6 +119,16 @@ Dragonfly 的核心体验不是“单个终端标签页”，而是一个可组
 - 复杂配置可以独立完成
 - 演示和截图时结构更清晰

+## 托盘与关闭行为
+
+如果你在 **设置 → 常规** 中开启 **关闭时最小化到托盘**，关闭主窗口时应用不会立刻退出，而是转为后台驻留。
+
+这适合：
+
+- 需要保留活动会话
+- 希望让同步 / 备份继续在后台运行
+- 需要后续快速从托盘重新唤起主窗口
+
 ## 推荐的工作流组合

 ### 组合一：本地 + 远程
@@ -136,6 +148,7 @@ Dragonfly 的核心体验不是“单个终端标签页”，而是一个可组
 - SSH 终端进入目标目录
 - 文件浏览器同步到当前路径
 - 打开远程文件，本地编辑后自动回传
+- 把当前目录或文件路径直接发送到终端继续执行命令

 :::tip 截图建议
 - 推荐图片路径：`/img/docs/layout/quick-start-split-workspace.png`
@@ -139,7 +139,11 @@ SSH 首次连接未知主机时，Dragonfly 支持三种策略：
 - **导入 / 导出配置**：用于迁移或备份 Dragonfly 自身配置，文件格式为加密的 `.dgfy`
 - **导出诊断包**：用于打包近期日志、运行时摘要等排障信息

-其中 `.dgfy` 导入 / 导出需要先设置主密码；诊断包导出主要服务于排查 Bug、收集问题上下文和请求支持。
+需要注意：
+
+- `.dgfy` 导入 / 导出依赖主密码
+- 导出诊断包主要服务于排查 Bug、收集问题上下文和请求支持
+- 诊断日志相关设置、打开日志目录、导出诊断包入口位于 **设置 → 常规**

 ## 安全使用建议

@@ -53,7 +53,11 @@ Dragonfly 会为会话工作流提供两类辅助：
 - 建议参与匹配的**最小历史命令长度**
 - 建议参与匹配的**最大历史命令长度**

-这个长度过滤只影响历史命令建议，不影响快捷命令本身的可用性。
+需要注意：
+
+- 这两个长度过滤只影响**历史命令建议**
+- 它们不会影响右侧命令历史面板中的已有记录
+- 它们也不会影响**快捷命令**本身的可用性

 ## 可选终端增强项