docs: update README and user guides to enhance clarity on Dragonfly's features, session types, and terminal capabilities; add new sections for workspace layout, security, and network configurations

README.md

@@ -1,86 +1,124 @@
 <div align="center">
     <img src="./public/dragonfly.svg" alt="Dragonfly Logo" width="100" height="100">
-    <h3>Dragonfly is a modern, high-performance SSH client</h3>
+    <h3>Dragonfly is a modern remote terminal workspace built with Tauri and Rust</h3>
 </div>
 
-## ✨ Features
+## Overview
 
-- **🚀 Robust SSH Client**: Secure and fast SSH connections powered by Rust's `russh`.
-- **📑 Multi-Tab Interface**: Manage multiple active sessions simultaneously in a tabbed interface.
-- **💾 Session Management**: Save, organize, and edit your frequently used server connections for quick access.
-- **📂 Integrated File Explorer**: Browse, upload, and download files on your remote servers directly from the sidebar.
-- **📜 Command History**: Automatically save and easily access your command history.
-- **⚡ Quick Commands**: store and execute your most frequent commands with a single click.
-- **🎨 Customizable UI**: Resizable panels for File Explorer, Saved Connections, and Command History to fit your workflow.
-- **🌗 Theme Support**: Fully supported Dark and Light modes.
-- **🖥️ Cross-Platform**: Optimized for Windows, macOS, and Linux.
+Dragonfly is a desktop client for SSH-centric operations and mixed terminal workflows. It combines a React + Tauri interface with a Rust backend so you can manage remote hosts, local shells, file transfers, authentication, and network tooling from one workspace.
 
-## 🛠️ Tech Stack
+## Highlights
 
-- **Frontend**: [React 19](https://react.dev/), [TypeScript](https://www.typescriptlang.org/), [Vite](https://vitejs.dev/), [TailwindCSS 4](https://tailwindcss.com/)
-- **Backend**: [Tauri 2](https://tauri.app/), [Rust](https://www.rust-lang.org/)
-- **Terminal**: [xterm.js](https://xtermjs.org/)
-- **Icons**: [Material Icons](https://fonts.google.com/icons)
+### Sessions and workspace
 
-## 🚀 Getting Started
+- SSH, Local Terminal, Telnet, and Serial session support
+- Multi-tab workspace with horizontal and vertical pane splits
+- Saved connections with folders, icons, duplication, reconnect, and import tools
+- Child windows for settings, new-session, quick-command, and auto-upload flows
+
+### Terminal experience
+
+- Search bar, command history, fuzzy suggestions, and context actions
+- Optional line numbers and timestamps gutter for dense terminal output
+- Optional action links for IPv4 addresses, `host:port`, and archive filenames
+- Optional keyword highlighting with built-in presets and custom rules
+- Session recording, configurable scrollback, and SSH keep-alive
+- Remote resource monitor for active SSH sessions
+
+### Remote operations
+
+- Built-in SFTP file explorer with upload, download, rename, move, delete, and properties
+- Transfer queue with retry, resume, timestamp preservation, and configurable concurrency
+- Open remote files in a local editor and upload changes back through the watcher flow
+- Quick Commands with categories, colors, icons, and variable prompts
+
+### Security and networking
+
+- Password auth, private keys, host-key verification, and local credential encryption
+- 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
+
+## Supported session types
+
+| Type | Typical use | Notes |
+|------|-------------|-------|
+| SSH | Linux / Unix remote servers | Supports SFTP, OTP, resource monitor, proxy, jump host, tunnels |
+| Local Terminal | Local shell workflows | Uses your local shell path and working directory |
+| Telnet | Legacy network devices / lab systems | Lightweight terminal session without SSH-only features |
+| Serial | Routers, boards, embedded devices | Configurable port, baud rate, parity, stop bits |
+
+## Documentation map
+
+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)
+- Development docs: [docs-site/docs/development/](docs-site/docs/development)
+
+## Screenshot placeholders
+
+If you want to add screenshots later, these are the recommended stable asset paths to use in the docs site:
+
+- `docs-site/static/img/docs/readme/main-workspace.png` — main workspace with split panes and both side panels
+- `docs-site/static/img/docs/readme/session-types.png` — new-session window showing SSH / Local / Telnet / Serial tabs
+- `docs-site/static/img/docs/readme/terminal-features.png` — gutter, action links, and highlight demo output
+- `docs-site/static/img/docs/readme/network-and-security.png` — proxy / tunnel / OTP related UI
+
+## Tech stack
+
+| Layer | Technology |
+|------|------------|
+| Frontend | React 19, TypeScript, Vite, TailwindCSS 4 |
+| Desktop runtime | Tauri 2 |
+| Backend | Rust |
+| Terminal | xterm.js |
+| SSH | russh |
+| File transfer | russh-sftp |
+
+## Getting started
 
 ### Prerequisites
 
-Ensure you have the following installed on your machine:
-
-- **Node.js**: v18 or newer recommended.
-- **Rust**: The latest stable version (via [rustup](https://rustup.rs/)).
-- **Tauri CLI**: (Optional) `npm install -g @tauri-apps/cli`.
+- Node.js 18+
+- Rust stable via [rustup](https://rustup.rs/)
+- pnpm recommended
 
 ### Installation
 
-1.  **Clone the repository**:
-    ```bash
-    git clone https://github.com/yourusername/dragonfly.git
-    cd dragonfly
-    ```
+```bash
+git clone https://git.coderkang.top/Tauri/dragonfly.git
+cd dragonfly
+pnpm install
+```
 
-2.  **Install dependencies**:
-    ```bash
-    npm install
-    # or
-    pnpm install
-    # or
-    yarn install
-    ```
-
-### 💻 Development
-
-Start the development server with hot-module replacement (HMR):
+### Run the app in development
 
 ```bash
-npm run tauri dev
-# or
 pnpm tauri dev
-# or
-yarn tauri dev
 ```
 
-This will start the Vite dev server and launch the Tauri application window.
-
-### 📦 Build
-
-Build the application for production:
+### Run the docs site locally
 
 ```bash
-npm run tauri build
-# or
-pnpm tauri build
-# or
-yarn tauri build
+pnpm --dir docs-site start
 ```
 
-The build artifacts will be located in `src-tauri/target/release/bundle`.
+### Build
 
-## 🤝 Contributing
+```bash
+pnpm build
+pnpm tauri build
+pnpm --dir docs-site build
+```
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+The desktop bundles are generated under `src-tauri/target/release/bundle`.
 
-## 📄 License
+## Contributing
+
+Please read the docs under [docs-site/docs/development/](docs-site/docs/development) before contributing.
+
+## License
 
 [MIT](LICENSE)

docs-site/docs/faq.md

@@ -4,84 +4,125 @@ sidebar_position: 100
 
 # 常见问题
 
-## 连接问题
+## 会话与连接
 
-### SSH 连接超时怎么办？
+### SSH 能连，本地终端 / Telnet / 串口为什么行为不一样？
 
-1. 检查服务器地址和端口是否正确
-2. 确认服务器的 SSH 服务是否正在运行
-3. 检查防火墙是否允许 SSH 端口
-4. 如果使用代理，确认代理配置是否正确
-5. 尝试增加 Keep-Alive 间隔（**设置 → 终端 → Keep-Alive 间隔**）
+因为 Dragonfly 支持多种会话类型，但能力并不完全相同：
 
-### 连接后终端没有响应？
+- **SSH**：功能最完整，支持 SFTP、OTP、资源监控、代理、跳板机、隧道
+- **本地终端**：只负责本地 shell 工作流
+- **Telnet**：轻量远程终端，不包含 SSH 专属能力
+- **串口**：用于串口调试，不属于 SSH 网络链路
 
-- 尝试按 `Enter` 键
-- 检查用户认证是否成功
-- 查看应用日志（**帮助 → 查看日志**）
+如果你希望使用文件浏览器、远程资源监控或 OTP，请确认当前打开的是 **SSH 会话**。
 
-### 如何使用私钥连接？
+### 为什么某些会话没有文件浏览器？
 
-1. 前往 **设置 → 安全 → 密钥管理**
-2. 点击 **添加密钥**，导入私钥文件
-3. 创建连接时，认证方式选择 **私钥**，然后选择对应的密钥
+文件浏览器基于 SFTP，因此只会在 **SSH 会话** 下可用。
+
+以下类型不会提供远程文件浏览器：
+
+- 本地终端
+- Telnet
+- 串口
+
+### 为什么没有看到远程资源监控？
+
+请同时检查两件事：
+
+1. 当前标签是否为 **SSH 会话**
+2. 是否已在 **设置 → 终端** 中开启 **显示远程资源信息**
+
+资源监控默认是关闭的。
+
+### 串口列表为空怎么办？
+
+先确认：
+
+- 设备已经连接到系统
+- 当前系统已经识别该串口
+- 串口未被其他工具独占
+
+切换到串口标签并重新展开端口下拉时，Dragonfly 会重新加载可用串口列表。
+
+## 终端体验
+
+### 为什么动作链接不能点击？
+
+通常有两种原因：
+
+1. 你还没有在 **设置 → 终端** 中启用 **动作链接**
+2. 点击时没有使用 **Ctrl / Cmd + 点击**
+
+动作链接默认关闭，而且为了避免误触，打开链接时需要配合修饰键。
+
+### 为什么看不到关键词高亮？
+
+关键词高亮默认关闭。请先到 **设置 → 终端** 中启用它，再确认当前输出里确实包含可匹配的文本。
+
+### 为什么行号和时间戳没有显示？
+
+这两项也都是按需开启的可选增强项，需要在 **设置 → 终端** 中分别打开。
 
 ## 文件传输
 
-### 上传/下载速度慢？
+### 打开远程文件后，为什么没有弹出自动上传提示？
 
-Dragonfly 使用管道化传输优化了大文件传输速度。如果速度仍然不理想，可能是网络带宽限制。
+自动上传提示只会在下面这种流程里出现：
 
-### 无法删除文件？
+1. 你从 SSH 文件浏览器中对远程文件执行 **打开**
+2. Dragonfly 下载该文件到本地临时目录并启动监听
+3. 你在本地编辑器里保存这个文件
 
-检查当前用户是否有该文件的删除权限。可在文件属性中查看权限信息。
+如果你是自己另外复制了一个文件再编辑，Dragonfly 不会知道它和远端文件之间的关系。
 
-## 界面问题
+### 文件浏览器为什么没有跟着 `cd` 自动切换目录？
 
-### 界面字体显示异常？
+自动跟随依赖会话的终端路径跟踪能力。如果当前会话不支持，自动同步会被关闭；这时你仍然可以手动执行同步。
 
-1. 前往 **设置 → 外观 → 字体系列**
-2. 确认首选字体已正确安装
-3. 添加备选字体作为回退
+### 上传 / 下载保存到哪里？
 
-### 终端渲染卡顿？
+取决于你的传输设置：
 
-尝试在 **设置 → 终端** 中：
-- 开启或关闭 **硬件加速**（需要重启应用）
-- 减少 **回滚缓冲区** 行数
+- 如果启用了“每次询问保存位置”，每次下载都会让你选择路径
+- 否则会使用默认下载目录
 
-### 如何重置界面布局？
+你也可以在设置里修改默认下载目录和默认编辑器。
 
-通过菜单 **视图 → 重置面板布局** 恢复默认布局。
+## 安全与认证
 
-## 安全相关
+### 锁屏后为什么不需要输入密码也能解锁？
 
-### 忘记了主密码怎么办？
+这是因为你启用了锁屏，但**还没有设置主密码**。
 
-主密码用于加密会话数据。如果忘记，需要删除 `~/.dragonfly/` 目录下的配置文件重新配置。
+当前实现中：
 
-:::warning 注意
-删除配置文件将丢失所有已保存的连接和密钥。
-:::
+- 有主密码：锁屏后必须输入主密码
+- 没有主密码：可以直接点击解锁
 
-### 忘记了锁屏密码怎么办？
+### 忘记主密码怎么办？
 
-可以手动编辑 `~/.dragonfly/settings.json` 文件，将锁屏相关配置项重置。
+当前没有内建的“找回主密码”流程。如果本地数据已经受主密码保护，而你又无法提供正确密码，那么相关敏感配置将无法按原方式继续使用。
 
-## 其他
+在手动处理前，建议先备份 `~/.dragonfly/` 目录，再决定如何重建本地配置。
 
-### 如何导入其他 SSH 客户端的会话？
+### OTP 应该在哪里管理？
 
-目前支持从 WindTerm 导入：
+请到 **Security/Auth** 面板中的 **OTP** 标签页统一管理；创建或编辑 SSH 连接时，再把某个 OTP 条目绑定到具体连接。
 
-1. 右键点击侧边栏选择 **导入会话**
-2. 选择 WindTerm
-3. 选择 WindTerm 的会话配置文件
+## 导入与迁移
 
-### 配置文件在哪里？
+### 可以从哪些客户端导入会话？
 
-所有配置文件存储在 `~/.dragonfly/` 目录下，包括连接、密钥、设置等。
+目前支持：
 
-### 如何查看应用日志？
+- Xshell（`.xts`）
+- MobaXterm（`.mxtsessions`）
+- WindTerm（`.sessions`）
 
-通过菜单 **帮助 → 查看日志** 打开日志文件。日志按天轮转，保留最近 7 天的记录。
+导入后建议检查用户名、端口、认证方式，以及是否需要补充代理 / 跳板机 / OTP。
+
+### Dragonfly 的配置文件存放在哪里？
+
+应用配置位于 `~/.dragonfly/` 目录下，其中会保存设置、连接、密钥、OTP、隧道、代理、历史等本地数据。

docs-site/docs/getting-started/quick-start.md

@@ -4,51 +4,95 @@ sidebar_position: 2
 
 # 快速开始
 
-本章将引导你完成第一个 SSH 连接的创建和使用。
+本章帮助你在最短路径内体验 Dragonfly 的核心工作流：创建连接、打开会话、使用分屏、查看文件、启用终端增强功能。
 
-## 创建 SSH 连接
+## 第一步：选择会话类型
 
-1. 点击左侧边栏中的 **新建连接** 按钮，或使用菜单 **文件 → 新建 SSH 连接**
-2. 在弹出的对话框中填写：
-   - **连接名称** — 给连接取一个便于识别的名称
-   - **主机** — 服务器的 IP 地址或域名
-   - **端口** — SSH 端口，默认 22
-   - **用户名** — 登录用户名
-   - **认证方式** — 选择密码或私钥
-3. 点击 **保存** 保存连接配置
+点击 **新建连接**，你会看到四类可选会话：
 
-## 连接服务器
+- **SSH** — 最完整的远程运维场景
+- **本地终端** — 直接在 Dragonfly 中打开本地 shell
+- **Telnet** — 适合旧系统或实验环境
+- **串口** — 适合串口调试设备
 
-在左侧边栏的已保存连接列表中，双击连接名称或右键选择 **连接** 即可开始 SSH 会话。
+如果你只是第一次体验，建议优先创建一个 **SSH** 会话，再额外创建一个 **本地终端** 对比工作区效果。
 
-连接成功后，你会在中央区域看到一个新的终端标签页。
+## 第二步：创建第一个 SSH 连接
 
-## 基本操作
+在新建连接窗口中填写：
 
-### 多标签管理
+- **连接名称** — 便于识别的显示名称
+- **主机** 与 **端口**
+- **用户名**
+- **认证方式** — 密码或私钥
 
-- 你可以同时打开多个 SSH 连接，每个连接占一个标签页
-- 使用 `Ctrl+Tab` 切换标签页
-- 使用 `Ctrl+W` 关闭当前标签页
+如有需要，还可以展开高级区域配置：
 
-### 文件浏览
+- 代理
+- 跳板机
+- OTP 绑定与自动填充
+- 图标、分组、描述等元数据
 
-连接成功后，右侧文件浏览器会自动显示远程文件系统：
+保存后，连接会出现在已保存连接列表中。
 
-- 浏览目录结构
-- 上传/下载文件
-- 右键菜单进行文件操作（重命名、删除、移动等）
+## 第三步：启动并理解工作区
 
-### 命令历史
+双击已保存连接，或者右键选择连接，即可启动会话。
 
-Dragonfly 会自动记录你输入的命令，你可以通过模糊搜索快速找到之前使用过的命令。
+连接建立后，你会看到：
 
-## 创建本地终端
+- **中央区域** — 当前终端标签页
+- **左侧活动栏** — 文件浏览器、网络、Security/Auth 等面板入口
+- **右侧活动栏** — 已保存连接、活动会话、命令历史、资源监控等入口
+- **底部区域** — 快捷命令、串口发送、录制、锁屏等辅助区域
 
-除了 SSH 连接，你还可以通过菜单 **终端 → 新建本地终端** 创建本地 Shell 会话。
+## 第四步：试试这些高频能力
 
-## 下一步
+### 1. 再打开一个本地终端
 
-- 了解 [SSH 连接管理](../guide/ssh-connection) 的更多选项
-- 学习使用 [SFTP 文件传输](../guide/file-transfer)
-- 配置 [快捷命令](../guide/quick-commands) 提升效率
+使用快捷键 ``Ctrl/Cmd + ` `` 或菜单入口创建本地终端，这样你可以在一个应用里同时看本地和远程环境。
+
+### 2. 试一次终端分屏
+
+在标签页上右键，选择：
+
+- **水平分屏**
+- **垂直分屏**
+
+这适合同时观察日志、执行命令和对照不同主机输出。
+
+### 3. 打开远程文件浏览器
+
+SSH 会话激活后，文件浏览器面板可直接浏览远程目录，并支持上传、下载、删除、移动、属性查看等操作。
+
+### 4. 打开命令历史和快捷命令
+
+- **命令历史** 适合回溯与模糊检索
+- **快捷命令** 适合保存固定操作，并支持变量输入
+
+### 5. 启用终端增强项
+
+可在 **设置 → 终端** 中按需打开：
+
+- 行号
+- 时间戳
+- 动作链接
+- 关键词高亮
+- 远程资源监控
+
+这些能力默认更偏保守，需要你按场景开启。
+
+## 第五步：按你的场景继续深入
+
+- 想了解不同会话差异：查看 [会话类型](../guide/session-types)
+- 想配置认证、代理、跳板机：查看 [SSH 连接管理](../guide/ssh-connection)
+- 想管理文件与自动回传：查看 [SFTP 文件传输](../guide/file-transfer)
+- 想了解终端增强与录制：查看 [终端功能](../guide/terminal)
+- 想配置 OTP：查看 [OTP 与认证](../guide/otp-and-auth)
+
+:::tip 截图建议
+- 推荐图片路径：`/img/docs/session-types/new-session-tabs.png`
+- 建议展示内容：新建连接窗口中 SSH / 本地终端 / Telnet / 串口四个标签
+- 另一个推荐图片路径：`/img/docs/layout/quick-start-split-workspace.png`
+- 建议先执行：连接一个 SSH 会话，再新建一个本地终端并对标签页做一次分屏
+:::

docs-site/docs/guide/file-transfer.md

@@ -4,74 +4,126 @@ sidebar_position: 2
 
 # SFTP 文件传输
 
-Dragonfly 内置了功能完善的 SFTP 文件管理器，让你无需额外工具即可管理远程文件。
+Dragonfly 的远程文件能力建立在 SSH 会话之上。也就是说，**文件浏览器、SFTP 传输、远程文件本地编辑后回传** 都只在 SSH 会话中可用；本地终端、Telnet、串口不会显示这一套能力。
 
 ## 文件浏览器
 
-连接 SSH 会话后，右侧边栏会显示远程文件浏览器：
+连接 SSH 会话后，文件浏览器面板可以直接浏览远程目录。
 
-- 自动定位到用户主目录
-- 点击文件夹进入，点击上方 **返回上级** 按钮返回
-- 点击路径栏可直接输入路径跳转
-- 支持自动同步终端当前路径
+你会得到这些基础能力：
 
-### 文件操作
+- 自动进入远端用户主目录
+- 进入文件夹、返回上级、手动输入路径跳转
+- 刷新当前目录
+- 与终端当前工作目录同步
+- 在不支持路径跟踪的会话中关闭自动同步
 
-右键点击文件或文件夹，可执行以下操作：
+## 常见文件操作
+
+在文件列表或右键菜单中，你可以执行：
 
 | 操作 | 说明 |
 |------|------|
-| 打开 | 在默认编辑器中打开文件 |
-| 下载 | 下载文件到本地 |
-| 重命名 | 重命名文件或文件夹 |
-| 移动 | 将文件移动到指定路径 |
-| 删除 | 删除文件或文件夹（递归） |
-| 属性 | 查看文件详细信息 |
-| 复制路径 | 复制文件的完整路径 |
+| 打开 | 下载到本地临时目录后，用默认编辑器打开 |
+| 上传文件 | 选择本地文件上传到当前目录 |
+| 上传文件夹 | 整个目录上传到当前远端路径 |
+| 下载 | 下载单个文件或整个目录 |
+| 重命名 | 修改远端名称 |
+| 移动 | 把文件或目录移动到新路径 |
+| 删除 | 删除文件或目录 |
+| 属性 | 查看大小、时间、UID/GID、权限等信息 |
+| 新建文件 / 文件夹 / 符号链接 | 在当前目录中直接创建 |
 
-### 新建文件和文件夹
+其中“打开”并不只是只读预览，而是为后续本地修改后回传做准备。
 
-在工具栏中可以：
+## 上传与下载
 
-- 新建文件
-- 新建文件夹
-- 新建符号链接
+### 上传
 
-## 文件上传
+可通过工具栏或右键菜单把本地文件上传到当前目录。
 
-点击工具栏的 **上传** 按钮，选择本地文件上传到当前目录。
+- 多个文件会逐个加入传输流程
+- 上传目录时会保留目录结构
+- 对 SSH 场景适合拿来同步脚本、配置文件或发布包
 
-也可以通过右键菜单选择 **上传到当前文件夹**。
+### 下载
 
-## 文件下载
+下载时有两种常见工作方式：
 
-选中文件后，点击工具栏的 **下载** 按钮，或右键选择 **下载**。
+- 使用默认下载目录，直接保存到固定位置
+- 每次都询问保存位置，适合临时排障或按任务分类归档
 
-Dragonfly 使用管道化传输技术，同时维持多个并发数据块读取，大幅提升大文件传输速度。
+目录下载与文件下载都支持，远端目录会落到你选择的本地目标目录中。
 
-## 传输进度
+## 传输面板与传输设置
 
-在右侧边栏的 **文件传输** 面板中，可以查看所有传输任务的实时进度：
+Dragonfly 会把上传 / 下载任务统一放进传输队列中，便于你查看：
 
-- 传输中的文件名和进度
-- 已完成的传输
-- 传输错误
+- 当前进度
+- 成功与失败状态
+- 同时进行中的任务
 
-可以一键清除已完成的传输记录。
+在设置中还可以按需调整传输相关策略，例如：
 
-## 路径同步
+- 上传 / 下载线程数
+- 冲突时的处理策略
+- 是否保留时间戳
+- 是否继续断点传输
+- 默认下载路径
+- 默认打开远程文件所使用的本地编辑器
 
-文件浏览器支持与终端路径同步：
+## 与终端路径同步
 
-- **手动同步** — 点击同步按钮，将文件浏览器定位到终端当前目录
-- **自动同步** — 开启后，文件浏览器会自动跟随终端的工作目录变化
+文件浏览器可以和当前 SSH 终端的工作目录配合使用：
 
-## 文件属性
+- **手动同步**：把浏览器直接跳到终端当前路径
+- **自动同步**：终端 `cd` 到新目录后，文件浏览器自动跟随
 
-右键点击文件选择 **属性**，可查看：
+这对边跑命令边查文件非常有用，例如你在终端里进入某个发布目录后，文件浏览器会更容易保持在同一位置。
+
+## 本地编辑后自动回传
+
+这是 Dragonfly 很适合文档截图和真实运维场景的一项能力。
+
+### 工作方式
+
+1. 在 SSH 文件浏览器中对远程文件执行 **打开**
+2. Dragonfly 先把文件下载到本地临时目录
+3. 同时启动文件监听
+4. 你在本地编辑器里保存后，应用会弹出上传提示窗口
+
+### 上传提示窗口
+
+文件被修改后，你可以选择：
+
+- **上传一次**
+- **始终上传**
+- **取消**
+
+如果你对某个文件选择了“始终上传”，那么在**当前会话内**后续再次保存时会直接回传，不再重复询问。
+
+### 适合的使用场景
+
+- 修改远程配置文件
+- 调整部署脚本
+- 打开日志或状态文件做本地分析
+- 为文档准备“编辑后回传”的演示截图
+
+## 文件属性与权限
+
+在 **属性** 中可以查看：
 
 - 文件大小
-- 修改时间和访问时间
+- 修改时间、访问时间
 - 所有者和组
-- 权限（用户/组/其他，八进制表示）
-- UID 和 GID
+- UID / GID
+- 权限的八进制表示
+
+如果你的流程需要先核对权限再替换文件，这里会比单纯依赖 `ls -l` 更直观。
+
+:::tip 截图建议
+- 推荐图片路径：`/img/docs/file-transfer/remote-file-browser.png`
+- 建议连接一个 SSH 会话后，在文件浏览器中展示目录树、工具栏与右键菜单
+- 另一个推荐图片路径：`/img/docs/file-transfer/auto-upload-dialog.png`
+- 建议先打开一个远程文本文件，再在本地编辑器中保存一次以触发自动上传提示
+:::

docs-site/docs/guide/keyboard-shortcuts.md

@@ -4,44 +4,63 @@ sidebar_position: 8
 
 # 快捷键
 
-Dragonfly 提供丰富的快捷键支持，提升操作效率。
+Dragonfly 的快捷键分成两类理解最不容易混淆：
+
+1. **应用级快捷键**：切换面板、开新会话、复制终端内容等
+2. **Shell 级按键**：直接发送给远端或本地 shell，例如常见的 `Ctrl+C`
+
+如果你想复制终端里的文本，请优先使用 Dragonfly 的应用级快捷键，而不是假设 shell 里的快捷键会变成复制。
+
+## 约定
+
+- 下表中的 **Ctrl / Cmd** 表示：Windows / Linux 使用 `Ctrl`，macOS 使用 `Cmd`
+- `Ctrl+Tab` 与 `Ctrl+Shift+Tab` 保持当前实现写法
 
 ## 终端操作
 
 | 快捷键 | 功能 |
 |--------|------|
-| `Ctrl+C` | 复制选中文本 / 发送中断信号 |
-| `Ctrl+V` | 粘贴 |
+| `Ctrl / Cmd + Shift + C` | 复制 |
+| `Ctrl / Cmd + Shift + V` | 粘贴 |
+| `Ctrl / Cmd + Shift + X` | 粘贴选中的文本 |
+| `Ctrl / Cmd + Shift + F` | 查找 |
+| `Ctrl / Cmd + Shift + K` | 清屏 |
+| `Ctrl / Cmd + Shift + A` | 全选 |
 
-## 标签与会话
+## 标签与工作区
 
 | 快捷键 | 功能 |
 |--------|------|
-| `Ctrl+Shift+N` | 新建 SSH 会话 |
-| `Ctrl+Shift+T` | 新建本地终端 |
-| `Ctrl+W` | 关闭当前标签 |
-| `Ctrl+Tab` | 下一个标签 |
-| `Ctrl+Shift+Tab` | 上一个标签 |
-| `Ctrl+1~9` | 切换到标签 1-9 |
+| `Ctrl / Cmd + Shift + N` | 新建会话 |
+| ``Ctrl / Cmd + ` `` | 新建本地终端 |
+| `Ctrl / Cmd + Shift + W` | 关闭当前标签 |
+| `Ctrl + Tab` | 切换到下一个标签 |
+| `Ctrl + Shift + Tab` | 切换到上一个标签 |
+| `Ctrl / Cmd + 1-9` | 跳转到指定标签 |
 
-## 视图与布局
+## 视图与面板
 
 | 快捷键 | 功能 |
 |--------|------|
-| `Ctrl+B` | 切换左侧边栏 |
-| `Ctrl+Shift+B` | 切换右侧边栏 |
-| `Ctrl++` | 放大 |
-| `Ctrl+-` | 缩小 |
-| `Ctrl+0` | 重置缩放 |
-| `F11` | 切换全屏 |
+| `Ctrl / Cmd + Shift + E` | 切换左侧活动栏 / 面板 |
+| `Ctrl / Cmd + Shift + B` | 切换右侧活动栏 / 面板 |
+| `Ctrl / Cmd + =` | 放大界面 |
+| `Ctrl / Cmd + -` | 缩小界面 |
+| `Ctrl / Cmd + 0` | 重置缩放 |
 
 ## 特殊功能
 
 | 快捷键 | 功能 |
 |--------|------|
-| `Ctrl+,` | 打开设置 |
-| `Ctrl+L` | 锁定屏幕 |
+| `Ctrl / Cmd + Shift + L` | 锁定屏幕 |
+| `Ctrl / Cmd + ,` | 打开设置 |
+
+## 使用建议
+
+- 如果你经常在终端里复制日志，优先记住 `Ctrl / Cmd + Shift + C`
+- 如果你会同时管理远程与本地会话，`Ctrl / Cmd + Shift + N` 与 ``Ctrl / Cmd + ` `` 会是最常用的两个入口
+- 如果你使用锁屏功能，建议同时记住 `Ctrl / Cmd + Shift + L`
 
 :::tip 提示
-快捷键可能因操作系统不同而有所差异。macOS 上 `Ctrl` 对应 `Cmd` 键。
+快捷键列表以当前设置页展示的实现为准。如果未来版本新增可配置快捷键，请以应用内设置中的“交互”页面为最新信息源。
 :::

docs-site/docs/guide/layout-and-workspace.md

@@ -0,0 +1,140 @@
+---
+sidebar_position: 2
+---
+
+# 工作区与布局
+
+Dragonfly 的核心体验不是“单个终端标签页”，而是一个可组合的工作区：你可以同时打开多个会话、拆分多个窗格，并把常用面板固定在左右两侧。
+
+## 工作区的组成
+
+典型工作区由几部分组成：
+
+- **中央区域**：标签页与终端窗格
+- **左侧活动栏 / 面板**：文件浏览器、网络、Security/Auth
+- **右侧活动栏 / 面板**：已保存连接、活动会话、命令历史、资源监控
+- **底部辅助区域**：快捷命令、串口发送、录制、锁定
+
+这些区域不是固定死的单一页面，而是围绕当前活跃会话动态协作。
+
+## 标签页
+
+每个标签页都可以承载一个会话，也可以继续拆分成多个窗格。
+
+你可以对标签页执行这些常见操作：
+
+- 新建会话
+- 关闭当前标签
+- 在标签之间切换
+- 自定义标签名
+- 给标签设置颜色
+- 复制当前会话
+- 重新连接会话
+- 查看会话信息
+
+这让 Dragonfly 很适合用来区分：
+
+- 不同环境
+- 不同项目
+- 不同任务阶段
+
+## 分屏能力
+
+在标签页上右键，可以把当前会话拆成：
+
+- **水平分屏**
+- **垂直分屏**
+
+分屏后的窗格仍然属于同一个标签页，但每个窗格都能承载自己独立的会话内容。适合的场景包括：
+
+- 一个窗格看日志，一个窗格执行命令
+- 并排比较两台主机状态
+- 左边本地终端，右边远程 SSH
+- 串口输出和 SSH 排障命令同时观察
+
+## 会话与工作区的关系
+
+工作区里有两个容易混淆的概念：
+
+1. **逻辑标签页 / 窗格树**：决定一个标签内部如何分屏
+2. **运行时窗口布局**：决定不同标签当前挂在哪个工作区叶子位置
+
+对普通使用者来说，可以简单理解成：
+
+- 标签页负责组织任务
+- 分屏负责并排观察
+- 活动窗格决定当前命令发往哪里
+
+## 左右侧面板
+
+### 左侧
+
+左侧更偏“能力入口”，通常包括：
+
+- 文件浏览器
+- 网络
+- Security/Auth
+
+### 右侧
+
+右侧更偏“运行态信息”，通常包括：
+
+- 已保存连接
+- 活动会话
+- 命令历史
+- 资源监控
+
+如果你的工作流是“先选连接，再看运行状态”，这种左右分工会很自然。
+
+## 底部辅助区域
+
+工作区底部用于承载一些不适合一直占满侧栏的能力，例如：
+
+- **快捷命令**：保存可复用命令片段并支持变量输入
+- **串口发送**：适合频繁向串口设备发固定文本
+- **录制**：开始或停止当前会话录制
+- **锁定**：快速锁屏
+
+这也是 Dragonfly 和“普通多标签终端”差异较大的地方：它不是只让你开终端，而是把会话周边动作也组织到工作区里。
+
+## 子窗口
+
+某些操作会打开独立子窗口，而不是把所有内容都塞进主界面，例如：
+
+- 设置
+- 新建连接
+- 快捷命令编辑
+- 自动上传提示
+
+这样做的好处是：
+
+- 不打断主工作区当前会话
+- 复杂配置可以独立完成
+- 演示和截图时结构更清晰
+
+## 推荐的工作流组合
+
+### 组合一：本地 + 远程
+
+- 标签 1：SSH 登录远程主机
+- 标签 2：本地终端执行构建或 Git 命令
+- 右侧打开命令历史
+
+### 组合二：双窗格排障
+
+- 左窗格：实时日志
+- 右窗格：执行诊断命令
+- 再打开资源监控观察 CPU / 内存变化
+
+### 组合三：文件 + 终端联动
+
+- SSH 终端进入目标目录
+- 文件浏览器同步到当前路径
+- 打开远程文件，本地编辑后自动回传
+
+:::tip 截图建议
+- 推荐图片路径：`/img/docs/layout/quick-start-split-workspace.png`
+- 建议展示一个 SSH 会话 + 一个本地终端的分屏工作区
+- 另一个推荐图片路径：`/img/docs/readme/main-workspace.png`
+- 建议同时包含左侧活动栏、右侧面板、中心终端与底部辅助区
+:::

docs-site/docs/guide/otp-and-auth.md

@@ -0,0 +1,109 @@
+---
+sidebar_position: 6
+---
+
+# OTP 与认证
+
+Dragonfly 把 OTP 管理和 SSH 认证流程结合在了一起：你既可以把 OTP 当作一个独立的验证码仓库来管理，也可以把它直接绑定到 SSH 连接中，减少重复输入。
+
+## 支持的 OTP 类型
+
+当前支持：
+
+- **TOTP**
+- **HOTP**
+
+创建或编辑 OTP 条目时，可以配置：
+
+- issuer
+- username
+- secret
+- 算法（SHA-1 / SHA-256 / SHA-512）
+- 位数
+- 周期（TOTP）
+- 计数器（HOTP）
+
+## 在哪里管理 OTP
+
+请打开 **Security/Auth** 面板中的 **OTP** 标签页。
+
+你可以在这里：
+
+- 新建 OTP 条目
+- 编辑已有条目
+- 删除条目
+- 查看验证码
+- 从二维码图片导入
+
+## 从二维码导入
+
+如果你已经有 MFA / 2FA 的二维码，可以直接导入图片文件。
+
+典型流程：
+
+1. 在 OTP 面板中点击二维码导入
+2. 选择本地图片文件
+3. Dragonfly 解析后自动填充 issuer、username、secret 等信息
+4. 确认后保存为一个 OTP 条目
+
+这比手动抄写 secret 更适合日常管理，也更适合批量整理认证资料。
+
+## 绑定到 SSH 连接
+
+在 SSH 连接表单的高级区域中，可以为连接选择一个已保存的 OTP 条目。
+
+绑定后你可以：
+
+- 在认证时快速查看当前验证码
+- 在支持的交互流程中启用 **自动填充 OTP**
+
+这非常适合需要“密码 / 私钥 + 二次验证码”组合认证的环境。
+
+## 认证弹窗中的 OTP 交互
+
+当 SSH 服务器进入 keyboard-interactive / OTP 流程时，Dragonfly 会弹出 OTP 对话框。
+
+对话框中会显示：
+
+- 当前连接名称
+- 服务端要求输入的提示项
+- 如果该连接绑定了 OTP，还会显示验证码面板
+
+你可以：
+
+- 手动输入验证码
+- 直接把当前 OTP 验证码发送到输入框
+- 提交或取消本次认证
+
+## 自动填充 OTP
+
+如果某个 SSH 连接已经绑定了 OTP 条目，还可以启用 **自动填充 OTP**。
+
+适合场景：
+
+- 固定资产环境
+- 跳板机 / 堡垒机需要验证码
+- 高频重复登录的运维场景
+
+建议只对你明确掌握认证流程的连接开启，避免在不兼容的交互提示上产生误填。
+
+## 与密码 / 私钥的关系
+
+OTP 不是替代密码或私钥，而是和它们配合使用：
+
+- **密码 + OTP**
+- **私钥 + OTP**
+
+因此更推荐的管理方式是：
+
+1. 在 Security/Auth 中先分别整理好密码、私钥、OTP
+2. 再在具体 SSH 连接中绑定这些材料
+
+这样连接配置会更干净，也更方便后续统一替换认证信息。
+
+:::tip 截图建议
+- 推荐图片路径：`/img/docs/security/otp-management.png`
+- 建议展示 OTP 管理页中的 TOTP / HOTP 切换、二维码导入入口和验证码面板
+- 另一个推荐图片路径：`/img/docs/security/otp-dialog.png`
+- 建议展示 SSH 登录过程中弹出的 OTP 输入对话框
+:::

docs-site/docs/guide/security.md

@@ -4,63 +4,121 @@ sidebar_position: 7
 
 # 安全功能
 
-Dragonfly 提供多层安全保护机制。
+Dragonfly 的安全能力主要围绕三件事展开：
 
-## 凭据存储
+1. 安全保存本地凭据与认证材料
+2. 管理 SSH 连接过程中的主机校验与二次认证
+3. 在桌面端工作区中提供锁屏与主密码保护
 
-### 系统密钥链
+## 本地敏感数据的保存方式
 
-启用 **使用系统凭据管理器** 后，凭据将安全地存储在操作系统原生的密钥链中：
+Dragonfly 会在本地保存连接相关配置，并对敏感内容做加密处理后再写入配置文件。常见的敏感数据包括：
 
-- **macOS** — Keychain
-- **Windows** — Credential Manager
-- **Linux** — Secret Service (GNOME Keyring / KWallet)
+- 已保存密码
+- SSH 私钥与私钥口令
+- OTP 密钥
+- 主密码本身的持久化表示
 
-### 加密存储
+因此，平时使用时你看到的是“可以复用的密码 / 私钥 / OTP 条目”，而不是明文直接散落在普通文本配置里。
 
-所有敏感数据（密码、私钥、密码短语）均使用 **AES-256-GCM** 加密后存储在本地配置文件中。
+## Security/Auth 面板
+
+左侧活动栏中的 **Security/Auth** 面板集中管理认证相关内容，分为三类：
+
+- **密钥**
+- **密码**
+- **OTP**
+
+这意味着你不需要在每个连接里重复录入所有敏感信息，而是先把凭据存成可复用条目，再在连接表单中引用。
+
+### SSH 密钥管理
+
+适合保存：
+
+- 常用登录私钥
+- 需要密码短语的私钥
+- 按环境区分的多个身份
+
+创建 SSH 连接时，认证方式切换到 **私钥** 后，就可以直接选择已保存的密钥。
+
+### 密码管理
+
+适合保存：
+
+- SSH 密码
+- 代理密码
+- 需要重复复用的口令条目
+
+在 SSH 连接表单中，密码认证也会直接引用这里的已保存密码。
+
+### OTP 管理
+
+OTP 管理支持：
+
+- **TOTP**
+- **HOTP**
+- 从二维码图片导入
+- 查看并生成当前验证码
+- 绑定到具体 SSH 连接
+
+详细使用方式见 [OTP 与认证](./otp-and-auth)。
 
 ## 主密码
 
-启用 **需要主密码** 后，会话数据将使用主密码加密，每次启动应用时必须输入主密码才能解密。
+主密码是 Dragonfly 桌面端最重要的一项本地保护能力。
 
-在 **设置 → 安全 → 系统认证与加密** 中配置。
+你可以在 **设置 → 安全** 中设置主密码。设置后：
+
+- 应用会用它来校验解锁
+- 本地敏感配置的保护会围绕它展开
+- 锁屏界面会要求输入这个密码才能解锁
+
+如果你没有设置主密码，后续锁屏就只是一层界面遮罩，而不是严格意义上的密码保护。
 
 ## 屏幕锁定
 
 ### 手动锁定
 
-点击状态栏的 **锁定** 按钮，或使用快捷键锁定屏幕。
+你可以随时从界面中的锁定入口或快捷键触发锁屏。
 
 ### 自动锁定
 
-启用 **屏幕锁定保护** 后，应用会在以下情况自动锁定：
+在 **设置 → 安全** 中开启屏幕锁定后，还可以配置空闲分钟数：
 
-- 应用启动时
-- 空闲一段时间后（可配置分钟数，设为 0 禁用）
+- `0` 表示不使用空闲自动锁定
+- 大于 `0` 时，空闲达到设定时间后自动进入锁屏界面
 
-### 解锁密码
+### 解锁行为
 
-可设置解锁密码。如果不设置密码，点击即可解锁。
+- **已设置主密码**：必须输入正确主密码才能解锁
+- **未设置主密码**：可以直接点击解锁
 
-## SSH 密钥管理
+如果你准备把 Dragonfly 用在共享办公环境或演示现场，建议把“主密码 + 屏幕锁定”一起开启。
 
-在 **设置 → 安全 → 密钥管理** 中管理 SSH 私钥：
+## SSH 主机密钥策略
 
-- 导入私钥文件
-- 设置密钥名称和密码短语
-- 删除不需要的密钥
-
-导入的私钥会加密存储在本地。
-
-## 主机密钥策略
-
-控制 SSH 连接时如何处理未知主机密钥：
+SSH 首次连接未知主机时，Dragonfly 支持三种策略：
 
 | 策略 | 行为 |
 |------|------|
-| 提示 | 首次连接时弹窗询问是否信任（默认） |
-| 接受 | 自动接受并记录新主机密钥 |
-| 严格 | 拒绝所有未知主机密钥 |
+| 提示 | 首次连接时询问是否信任（默认） |
+| 接受 | 自动接受新的主机密钥 |
+| 严格 | 拒绝所有未知主机 |
 
-已知主机密钥存储在 `~/.dragonfly/known_hosts` 文件中。
+已知主机记录保存在 `~/.dragonfly/known_hosts`。
+
+如果你处在对主机身份校验要求更高的环境，建议使用“提示”或“严格”，而不是无条件接受。
+
+## 安全使用建议
+
+- 生产环境优先使用 **私钥 + OTP**，不要长期依赖单一密码
+- 对共享电脑或演示机，开启 **主密码** 与 **屏幕锁定**
+- 对需要经常穿过堡垒机的环境，把 **跳板机** 和 **代理** 做成明确的已保存配置
+- 对首次连接的新主机，核对主机密钥来源后再信任
+
+:::tip 截图建议
+- 推荐图片路径：`/img/docs/security/security-settings.png`
+- 建议展示主密码、屏幕锁定、空闲锁定时间、主机密钥策略
+- 另一个推荐图片路径：`/img/docs/security/security-auth-panel.png`
+- 建议展示 Security/Auth 面板中的密钥、密码、OTP 三个标签
+:::

docs-site/docs/guide/session-types.md

@@ -0,0 +1,123 @@
+---
+sidebar_position: 0
+---
+
+# 会话类型
+
+Dragonfly 不只是 SSH 客户端，而是一个把多类终端工作流放到同一工作区中的桌面应用。当前支持四类会话：
+
+- **SSH**
+- **本地终端**
+- **Telnet**
+- **串口**
+
+理解它们之间的差异，有助于你判断某个功能为什么“只在某些标签页里出现”。
+
+## 一览对比
+
+| 会话类型 | 典型场景 | 支持的增强能力 |
+|----------|----------|----------------|
+| SSH | Linux / Unix 服务器远程运维 | SFTP、OTP、资源监控、代理、跳板机、隧道 |
+| 本地终端 | 本地 shell、脚本调试、构建命令 | 共享同一套终端 UI、命令历史、分屏 |
+| Telnet | 旧设备、实验环境、兼容性排障 | 终端工作区能力，但不包含 SSH 专属特性 |
+| 串口 | 路由器、交换机、板卡、嵌入式调试口 | 串口参数配置、终端工作区能力 |
+
+## SSH
+
+SSH 是当前能力最完整的会话类型，适合：
+
+- 登录远程 Linux / Unix 主机
+- 浏览和传输远程文件
+- 使用 OTP、跳板机、代理
+- 查看远程资源监控
+- 配置端口隧道
+
+如果你需要：
+
+- 文件浏览器
+- 自动上传 / 回传
+- 远程资源监控
+- 网络面板中的 SSH 隧道
+
+那么应该优先使用 SSH。
+
+## 本地终端
+
+本地终端适合把本机 shell 工作流也放进 Dragonfly 工作区中，例如：
+
+- 本地构建前端 / Rust 项目
+- 跑脚本、日志查看、Git 命令
+- 和远程 SSH 会话并排对照
+
+它支持的重点不在远程功能，而在“和 SSH 会话共享同一套工作区体验”：
+
+- 标签页
+- 分屏
+- 终端搜索
+- 命令历史与建议
+- 行号 / 时间戳 / 高亮等终端增强项
+
+创建本地终端时，还可以指定：
+
+- shell 路径，例如 `powershell.exe`、`cmd.exe`、`bash`、`wsl.exe`
+- 工作目录
+
+## Telnet
+
+Telnet 会话适合：
+
+- 旧设备维护
+- 实验室环境
+- 需要兼容非 SSH 登录链路的场景
+
+它保留的是 Dragonfly 的终端工作区能力，但不会附带 SSH 特有的安全和文件能力。因此通常不会有：
+
+- SFTP 文件浏览器
+- OTP 绑定
+- SSH 跳板机
+- SSH 资源监控
+
+如果你的目标只是“快速打开一个传统远程终端”，Telnet 会更直接。
+
+## 串口
+
+串口会话适合连接：
+
+- 网络设备控制台口
+- 路由器 / 交换机
+- 开发板、嵌入式设备、调试口
+
+创建串口会话时可以配置：
+
+- 串口号
+- 波特率
+- 数据位
+- 校验位
+- 停止位
+
+串口会话同样可以放进 Dragonfly 的标签页与分屏工作区中，适合边看一个串口输出，边在另一个 SSH 或本地终端里执行命令。
+
+## 如何选择？
+
+可以按下面这个简单规则判断：
+
+- 要远程服务器完整能力：用 **SSH**
+- 要本机 shell：用 **本地终端**
+- 要兼容传统远程终端：用 **Telnet**
+- 要接调试口 / 设备串口：用 **串口**
+
+## 在一个工作区里混用
+
+Dragonfly 的优势之一，是允许你把这些类型混合放进同一工作区，例如：
+
+- 左边 SSH 看远端日志
+- 右边本地终端执行打包脚本
+- 再开一个串口标签观察设备启动信息
+
+这也是为什么文档里很多功能会写成“某会话类型专属”或“某会话类型才显示”的原因——工作区统一，但能力边界仍然取决于底层会话类型。
+
+:::tip 截图建议
+- 推荐图片路径：`/img/docs/session-types/new-session-tabs.png`
+- 建议展示新建连接窗口中的 SSH / 本地终端 / Telnet / 串口四个标签
+- 可同时保留各标签的默认字段区域，便于用户理解差异
+:::

docs-site/docs/guide/ssh-connection.md

@@ -4,77 +4,157 @@ sidebar_position: 1
 
 # SSH 连接管理
 
-## 连接配置
+SSH 仍然是 Dragonfly 最完整的一类会话。除了基础登录外，SSH 连接还可以进一步挂接：
+
+- SFTP 文件浏览器
+- 远程资源监控
+- 代理
+- 跳板机
+- OTP 绑定与自动填充
+- 端口隧道
+
+如果你第一次接触 Dragonfly，通常建议先把 SSH 连接配置好，再去扩展文件、终端增强和网络能力。
+
+## 创建 SSH 连接
+
+在 **新建连接** 窗口切换到 **SSH** 标签后，可以填写这些信息：
 
 ### 基本信息
 
-创建 SSH 连接时，需要填写以下信息：
-
-| 字段 | 说明 | 必填 |
-|------|------|------|
-| 连接名称 | 用于识别的显示名称 | 否 |
-| 图标 | 自定义图标 | 否 |
-| 分组 | 连接所属分组 | 否 |
-| 主机 | 服务器 IP 或域名 | 是 |
-| 端口 | SSH 端口号（默认 22） | 否 |
-| 用户名 | 登录用户名 | 是 |
-| 认证方式 | 密码或私钥 | 是 |
-| 描述 | 连接的备注说明 | 否 |
+| 字段 | 说明 |
+|------|------|
+| 连接名称 | 在已保存连接列表中的显示名称 |
+| 主机 | 服务器 IP 或域名 |
+| 端口 | 默认 `22` |
+| 用户名 | 登录用户名 |
+| 图标 | 用于区分不同环境或服务 |
+| 分组 | 把连接整理到文件夹中 |
+| 描述 | 记录用途、环境或备注 |
 
 ### 认证方式
 
-Dragonfly 支持两种认证方式：
+Dragonfly 支持两种常见 SSH 认证方式：
+
+- **密码**
+- **私钥**
+
+你可以直接选择已经保存的密码或私钥，而不必每次重复填写。
 
 #### 密码认证
 
-直接输入服务器密码。密码会使用 AES-256-GCM 加密存储在本地。
+适合：
 
-#### 密钥认证
+- 临时测试机
+- 还未发放私钥的环境
+- 与 OTP 联合使用的账号
 
-选择已导入的 SSH 私钥进行认证。支持 RSA、Ed25519 等常见密钥格式。
+#### 私钥认证
 
-如需管理密钥，前往 **设置 → 安全 → 密钥管理**。
+适合：
 
-## 连接分组
+- 日常远程运维
+- 多台主机复用同一身份
+- 需要配合跳板机或自动化流程的场景
 
-你可以创建文件夹来组织连接：
+私钥和密码都可以在 **Security/Auth** 面板中统一管理。
 
-- 右键点击侧边栏空白区域选择 **新建文件夹**
-- 支持多级嵌套文件夹
-- 拖拽连接到文件夹中进行分组
-- 右键文件夹可重命名或删除
+## 高级配置
 
-## 连接排序
+SSH 表单的高级区域可以把连接从“能连上”扩展成“适合日常使用”的工作流配置。
 
-侧边栏支持三种排序方式：
+### 代理
 
-- **自定义顺序** — 手动拖拽调整
-- **名称 A → Z** — 按名称升序
-- **名称 Z → A** — 按名称降序
+如果需要通过代理建立 SSH 连接，可以直接为当前连接选择已保存的代理配置。
 
-## 导入会话
+当前代理支持：
 
-Dragonfly 支持从其他 SSH 客户端导入会话：
+- **SOCKS5**
+- **HTTP**
 
-1. 右键点击侧边栏选择 **导入会话**
-2. 选择导入来源（目前支持 WindTerm）
-3. 选择对应的会话配置文件
-4. 确认导入
+代理记录中可保存：
 
-## 主机密钥验证
+- 名称
+- 协议
+- 主机
+- 端口
+- 用户名 / 密码
 
-Dragonfly 使用 TOFU（Trust On First Use）策略管理主机密钥：
+### 跳板机
 
-- **提示** — 首次连接时询问是否信任（默认）
-- **接受** — 自动接受所有新主机密钥
-- **严格** — 拒绝所有未知主机密钥
+如果目标主机不能直连，可以为当前 SSH 连接指定另一个已保存的 SSH 连接作为 **跳板机**。
 
-可在 **设置 → 安全 → 连接安全** 中修改策略。
+适合的场景：
 
-## 代理支持
+- 先进入堡垒机，再访问内网服务器
+- 分环境隔离的生产网络
+- 多层 SSH 登录链路
 
-如需通过代理连接，前往 **设置 → 代理** 配置：
+### OTP 绑定
 
-- 支持 SOCKS5 协议
-- 配置代理主机和端口
-- 启用/禁用代理
+如果目标环境要求二次验证码，可以把一个 OTP 条目绑定到当前 SSH 连接。
+
+绑定后有两种常见工作方式：
+
+- 只是在认证时快速取码
+- 开启 **自动填充 OTP**，在支持的交互流程中直接带入验证码
+
+这部分可以结合 [OTP 与认证](./otp-and-auth) 一起使用。
+
+## 已保存连接的管理
+
+保存后的连接会出现在右侧 **已保存连接** 面板中。常见操作包括：
+
+- 双击直接连接
+- 按分组组织连接
+- 编辑已有配置
+- 复制连接作为新模板
+- 重新连接已存在的会话来源
+
+如果你维护大量主机，建议用分组、图标和描述把“环境 / 项目 / 角色”区分开。
+
+## 导入其他客户端的会话
+
+Dragonfly 支持导入其他客户端的会话配置，目前可导入：
+
+- **Xshell**（`.xts`）
+- **MobaXterm**（`.mxtsessions`）
+- **WindTerm**（`.sessions`）
+
+导入后建议逐条检查：
+
+- 主机与端口
+- 用户名
+- 是否需要补充代理 / 跳板机 / OTP 绑定
+- 本地保存的密码或私钥是否已经匹配
+
+## 主机密钥策略
+
+Dragonfly 会为 SSH 主机维护已知主机记录，并提供三种主机密钥策略：
+
+| 策略 | 行为 |
+|------|------|
+| 提示 | 首次连接未知主机时询问是否信任（默认） |
+| 接受 | 自动接受并记录新的主机密钥 |
+| 严格 | 拒绝所有未知主机 |
+
+已知主机记录保存在 `~/.dragonfly/known_hosts`。
+
+如果你对安全要求较高，建议至少在生产环境中确认主机密钥来源，再决定是否接受。
+
+## 什么时候该用 SSH，而不是其他会话类型？
+
+优先使用 SSH 的典型场景是：
+
+- 你需要远程文件浏览器或 SFTP
+- 你需要 OTP、跳板机、代理、隧道
+- 你需要远程资源监控
+- 你希望把连接长期保存下来复用
+
+如果你只是想在 Dragonfly 里开一个本地 shell，请改用 [会话类型](./session-types) 里的 **本地终端**。
+
+:::tip 截图建议
+- 推荐图片路径：`/img/docs/session-types/ssh-advanced-form.png`
+- 建议展示 SSH 表单中的主机、认证方式，以及高级区域中的代理 / 跳板机 / OTP 绑定
+- 另一个推荐图片路径：`/img/docs/network/ssh-import-and-groups.png`
+- 建议展示已保存连接分组与导入入口
+:::

docs-site/docs/guide/terminal.md

@@ -4,102 +4,142 @@ sidebar_position: 3
 
 # 终端功能
 
-Dragonfly 基于 xterm.js 提供了功能丰富的终端模拟器。
+Dragonfly 的终端体验围绕“在同一个工作区里高频处理远程与本地会话”设计。它基于 xterm.js，但实际体验并不只是一块终端画布，还包括搜索、命令历史、建议、可选增强项、录制和 SSH 辅助能力。
 
-## 终端渲染
+## 基础操作
 
-### 硬件加速
+### 搜索、复制与右键菜单
 
-默认启用 WebGL 渲染，利用 GPU 加速终端绘制，确保流畅的滚动和输出体验。
-
-可在 **设置 → 终端 → 硬件加速** 中开启或关闭。
-
-### 字体配置
-
-- **字体系列** — 支持多字体回退链，首选字体优先级最高
-- **字体大小** — 终端和界面字体大小分别可调
-- **字体连字** — 可启用编程字体连字特性
-
-内置 JetBrains Mono 和 Noto Sans SC 字体，也可使用系统安装的任意字体。
-
-### 光标样式
-
-支持三种光标样式：
-- 块（Block）
-- 下划线（Underline）
-- 竖线（Bar）
-
-可选择是否启用光标闪烁。
-
-## 终端操作
-
-### 右键菜单
-
-在终端中右键可以：
+终端右键菜单可直接执行这些高频操作：
 
 - 复制 / 粘贴
-- 粘贴选定的文本
+- 粘贴选中的文本
 - 查找文本
 - 在线搜索选中文本
 - 翻译选中文本
 - 清屏 / 全部清除
 - 全选
 
-### 回滚缓冲区
+在 **设置 → 交互** 中，你还可以调整：
 
-终端保留可配置行数的历史输出（默认 1000 行），可通过滚轮向上滚动查看历史内容。
+- **选中即复制**
+- **右键粘贴**
+- 单词分隔符
+- 默认字符编码
 
-在 **设置 → 终端 → 回滚缓冲区** 中调整行数。
+### 回滚缓冲区与字体
 
-### 剪贴板
+- 回滚缓冲区默认保留 **10000 行**输出
+- 可自定义字体族、字号、连字、光标样式与闪烁
+- **硬件加速**为可选项，默认并未开启；如果你希望对比渲染效果，可在 **设置 → 终端** 中手动切换
 
-- **选中即复制** — 选中文本自动复制到剪贴板
-- **右键粘贴** — 右键点击终端区域粘贴剪贴板内容
+## 命令历史与建议
 
-在 **设置 → 交互** 中配置。
+Dragonfly 会为会话工作流提供两类辅助：
 
-## 关键词高亮
+### 命令历史
 
-Dragonfly 支持终端文本的关键词高亮：
+- 自动记录终端输入过的命令
+- 支持模糊检索
+- 可从右侧的 **命令历史** 面板回看历史输入
 
-### 内置规则
+### 输入建议
 
-自动识别并高亮常见模式，包括：
-- 日期时间格式
-- 数字
-- 错误/警告关键词
+输入时会基于历史命令给出建议，适合重复执行运维命令、构建命令或排障脚本。
 
-内置规则会根据当前主题自动调整配色。
+## 可选终端增强项
 
-### 自定义规则
+下面这些能力都需要你按需开启，而不是默认全部打开。
 
-在 **设置 → 终端 → 关键词高亮** 中添加自定义规则：
+### 行号与时间戳 gutter
 
-1. 设置规则名称
-2. 选择高亮颜色
-3. 添加匹配模式（支持正则表达式），每行一个
+在 **设置 → 终端** 中可分别开启：
 
-自定义规则的优先级高于内置规则。
+- **显示行号**
+- **显示时间戳**
 
-## 命令历史
+开启后，终端左侧会出现 gutter，用于辅助阅读长日志、命令输出或回放录制内容。
 
-终端会自动记录输入的命令：
+### 动作链接
 
-- 按会话分组存储
-- 支持模糊搜索
-- 在左侧边栏的 **命令历史** 面板中查看
+动作链接默认关闭，开启后可识别并点击常见文本模式，包括：
 
-## 联想补全
+- IPv4 地址，例如 `192.168.1.10`
+- `host:port`，例如 `db.internal:5432`
+- 压缩包文件名，例如 `backup.tar.gz`
 
-终端输入时会自动显示命令联想补全建议，基于历史命令进行匹配。
+注意：
 
-## Keep-Alive
+- 需要先在 **设置 → 终端** 中开启 **动作链接**
+- 打开链接时需要使用 **Ctrl / Cmd + 点击**，避免和普通选中操作冲突
+- 具体匹配器可以单独启用或关闭
 
-可配置 SSH Keep-Alive 间隔，防止连接因空闲而断开：
+### 关键词高亮
 
-- 在 **设置 → 终端 → Keep-Alive 间隔** 中设置
-- 设为 0 则禁用
+关键词高亮同样默认关闭。启用后，Dragonfly 会先应用内置规则，再叠加你的自定义规则。
 
-## 远程资源监控
+内置规则覆盖的内容不只限于错误关键字，还包括：
 
-在 **设置 → 终端** 中启用 **显示远程资源信息** 后，状态栏会显示当前 SSH 主机的 CPU 和内存使用情况，每 10 秒更新一次。
+- error / warn / success / info / debug 等常见状态词
+- 日期时间
+- 数字、大小、持续时间
+- 地址、URL、UUID、版本号等结构化文本
+
+你也可以自定义规则：
+
+- 自定义规则名称
+- 分别设置深色 / 浅色主题颜色
+- 每行填写一个匹配模式
+- 可选择是否跨折行继续匹配
+
+## SSH 相关辅助能力
+
+### Keep-Alive
+
+对 SSH 会话，可以在 **设置 → 终端** 中配置 Keep-Alive 间隔：
+
+- 默认值为 **60 秒**
+- 设为 `0` 表示关闭
+- 适合降低长时间空闲连接被远端回收的概率
+
+### 远程资源监控
+
+远程资源监控不是全局默认显示项。要使用它，需要同时满足：
+
+1. 当前是一个 **SSH 会话**
+2. 在 **设置 → 终端** 中开启 **显示远程资源信息**
+
+启用后，右侧 **资源监控** 面板会按设定间隔轮询主机信息；默认轮询间隔为 **3 秒**，可手动调整。
+
+面板会显示的内容包括：
+
+- 主机名、系统、架构、运行时长
+- Load Average
+- CPU 使用率
+- 内存使用情况
+- 网络吞吐速率
+
+## 录制与工作流配合
+
+Dragonfly 支持会话录制，适合：
+
+- 保留排障步骤
+- 给同事复现问题
+- 截取有时间顺序的终端示例
+
+如果你准备录制文档素材，通常可以把这些能力组合起来：
+
+- 行号 / 时间戳 gutter
+- 关键词高亮
+- 动作链接
+- 命令历史
+- 资源监控
+
+这样更容易拍出“终端在真实工作流中使用”的截图，而不是单独展示某个开关。
+
+:::tip 截图建议
+- 推荐图片路径：`/img/docs/terminal/gutter-line-numbers-timestamps.png`
+- 建议先在 **设置 → 终端** 中开启行号与时间戳，再执行：`scripts/demo-terminal-gutter.sh`
+- 另一个推荐图片路径：`/img/docs/terminal/action-links-and-highlights.png`
+- 建议先开启动作链接与关键词高亮，再执行：`scripts/demo-terminal-output.sh` 与 `scripts/demo-action-links.sh`
+:::

docs-site/docs/guide/tunnels-and-proxy.md

@@ -0,0 +1,134 @@
+---
+sidebar_position: 5
+---
+
+# 代理、跳板机与隧道
+
+Dragonfly 把网络相关能力分成三层：
+
+1. **代理**：先解决“怎么连出去”
+2. **跳板机**：再解决“通过哪台 SSH 主机中转”
+3. **隧道**：最后解决“把端口流量映射到哪里”
+
+这三者经常会出现在同一个真实场景里，但职责不同，分开理解更清楚。
+
+## 代理
+
+代理用于帮助 Dragonfly 建立到远端的网络连接。
+
+当前支持：
+
+- **SOCKS5**
+- **HTTP**
+
+每个代理配置可保存：
+
+- 名称
+- 协议
+- 主机
+- 端口
+- 用户名 / 密码
+
+代理在网络面板中统一管理，之后可以在 SSH 连接的高级区域中直接选择。
+
+适合场景：
+
+- 办公网必须走代理
+- 某些区域网络不允许直连
+- 需要统一维护一组出站网络配置
+
+## 跳板机
+
+跳板机是 SSH 专属能力。它的作用不是代替代理，而是使用一个已保存的 SSH 连接作为中转入口。
+
+适合场景：
+
+- 堡垒机 / bastion host
+- 目标主机只允许内网访问
+- 多层 SSH 网络隔离
+
+在 SSH 连接高级区域中，你可以直接从已有 SSH 连接里选一个作为跳板机。
+
+## 隧道
+
+Dragonfly 在网络面板中提供专门的隧道管理页，可把端口映射保存为可复用配置。
+
+### 支持的隧道类型
+
+- **本地隧道（local）**
+- **远程隧道（remote）**
+- **动态隧道（dynamic / SOCKS5）**
+
+### 本地隧道
+
+把本机监听端口转发到远端目标地址，适合：
+
+- 访问内网数据库
+- 打开只能在远端访问的 Web 控制台
+- 通过 SSH 安全转发服务端口
+
+### 远程隧道
+
+把远端监听端口映射回本地服务，适合：
+
+- 临时把本地服务暴露给远端环境
+- 做反向调试或联调
+
+### 动态隧道
+
+创建一个本地 SOCKS5 代理端口，适合：
+
+- 浏览器或工具临时走 SSH 动态代理
+- 需要快速建立一条“经 SSH 出站”的代理链路
+
+## 隧道配置项
+
+创建隧道时，通常会配置：
+
+- 隧道名称
+- 隧道类型
+- 关联的 SSH 连接
+- 监听端口
+- 目标主机 / 目标端口（动态隧道除外）
+- 是否仅绑定 `127.0.0.1`
+- 是否自动打开
+
+如果你只想本机自己访问，建议保持绑定到 `127.0.0.1`；这通常比监听 `0.0.0.0` 更安全。
+
+## 网络面板中的日常操作
+
+在网络面板中，你可以：
+
+- 新建 / 编辑 / 删除代理
+- 新建 / 编辑 / 删除隧道
+- 直接打开或关闭某条隧道
+- 查看某条隧道当前是否处于打开状态
+
+这让网络配置不再是“一次性命令”，而是可以被保存、复用和可视化管理。
+
+## 典型组合示例
+
+### 示例 1：代理 + SSH
+
+- 先在网络面板中保存一个 SOCKS5 代理
+- 再在 SSH 连接高级区域里选择这个代理
+- 适合公司网络或跨区访问环境
+
+### 示例 2：跳板机 + 目标主机
+
+- 先保存堡垒机连接
+- 再在业务主机连接里把堡垒机设为跳板机
+- 适合内网分层登录场景
+
+### 示例 3：SSH + 本地隧道
+
+- 建立 SSH 连接
+- 保存一个本地隧道 `localhost:15432 -> db.internal:5432`
+- 之后本地工具即可通过 `127.0.0.1:15432` 访问数据库
+
+:::tip 截图建议
+- 推荐图片路径：`/img/docs/network/network-panel.png`
+- 建议展示网络面板中的代理与隧道两个标签
+- 另一个推荐图片路径：`/img/docs/network/tunnel-dialog.png`
+- 建议展示隧道类型、本地监听端口、目标主机与自动打开选项
+:::

docs-site/docs/intro.md

@@ -5,33 +5,72 @@ slug: /
 
 # 项目介绍
 
-**Dragonfly** 是一个现代、高性能的 SSH 客户端，基于 [Tauri](https://tauri.app/) 和 [React](https://react.dev/) 构建。它将精致的用户界面与强大的 Rust 后端相结合，为开发者和运维人员提供卓越的远程服务器管理体验。
+**Dragonfly** 是一个围绕远程终端工作流设计的桌面客户端。它以 Tauri + React 构建前端界面，以 Rust 负责 SSH、SFTP、会话管理、隧道、认证与配置持久化，让你在同一个工作区中处理远程服务器、本地 shell、串口设备和网络辅助能力。
 
-## 核心特性
+## 适合哪些场景
 
-- **安全高效的 SSH 连接** — 基于 Rust `russh` 库，提供原生级性能
-- **多标签界面** — 同时管理多个 SSH 和本地终端会话
-- **会话管理** — 保存、组织和快速连接常用服务器
-- **集成文件浏览器** — 通过 SFTP 直接在侧边栏浏览和管理远程文件
-- **命令历史** — 自动记录并支持模糊搜索的命令历史
-- **快捷命令** — 一键执行常用命令，支持变量替换
-- **可定制界面** — 可调整面板大小，支持深色/浅色主题
-- **跨平台** — 支持 Windows、macOS 和 Linux
+- 同时维护多台 SSH 主机
+- 在本地终端、Telnet、串口设备之间切换排障
+- 边看终端输出边操作远程文件
+- 为常用运维命令、登录流程和跳板机链路做标准化配置
+- 需要 OTP、录制、资源监控、自动上传等增强能力
 
-## 技术栈
+## 核心能力
 
-| 层级 | 技术 |
-|------|------|
-| 前端 | React 19, TypeScript, Vite, TailwindCSS 4 |
-| 后端 | Tauri 2, Rust |
-| 终端 | xterm.js (WebGL 加速) |
-| SSH | russh (纯 Rust SSH 实现) |
-| 文件传输 | russh-sftp (管道化传输) |
+### 多种会话类型
 
-## 为什么选择 Dragonfly？
+Dragonfly 不只支持 SSH，还支持：
 
-1. **原生性能** — Rust 后端确保 SSH 连接和文件传输的高性能
-2. **安全至上** — AES-256-GCM 加密存储凭据，支持系统密钥链
-3. **现代 UI** — 基于 React 和 TailwindCSS 的精致界面
-4. **轻量级** — 基于 Tauri，安装包体积远小于 Electron 应用
-5. **开源免费** — MIT 许可证，完全开源
+- **SSH** — 远程登录、文件传输、资源监控、隧道、OTP 等完整能力
+- **本地终端** — 在同一套 UI 中打开本地 shell
+- **Telnet** — 兼容旧设备或实验环境
+- **串口** — 适合网络设备、嵌入式板卡、调试口场景
+
+### 可组合的工作区
+
+- 多标签页管理多个会话
+- 标签页内支持**横向/纵向分屏**
+- 左右活动栏可放置文件浏览器、网络、Security/Auth、会话列表、命令历史、资源监控等面板
+- 设置、新建连接、快捷命令、自动上传提示均使用独立子窗口，减少主工作区干扰
+
+### 面向终端操作的增强
+
+- 命令历史与模糊建议
+- 终端搜索、复制/粘贴、上下文菜单
+- 可选的**行号 / 时间戳 gutter**
+- 可选的**动作链接**（如 IPv4、`host:port`、压缩包文件名）
+- 可选的**关键词高亮**与自定义规则
+- 会话录制与 SSH Keep-Alive
+
+### 远程文件与自动回传
+
+- SSH 会话下内置 SFTP 文件浏览器
+- 上传、下载、重命名、移动、删除、属性查看
+- 传输队列、失败重试、断点续传、时间戳保留
+- 在本地编辑下载的远程文件后，可通过 watcher 流程快速上传回远端
+
+### 安全与网络能力
+
+- 私钥、密码、主机密钥策略、本地加密存储
+- OTP 管理（TOTP / HOTP）、二维码导入、SSH 自动填充
+- 代理配置、跳板机、端口隧道
+- 锁屏与主密码能力
+
+## 文档导航建议
+
+如果你是第一次使用，建议按下面顺序阅读：
+
+1. [快速开始](./getting-started/quick-start)
+2. [会话类型](./guide/session-types)
+3. [SSH 连接管理](./guide/ssh-connection)
+4. [工作区与布局](./guide/layout-and-workspace)
+5. [终端功能](./guide/terminal)
+6. [SFTP 文件传输](./guide/file-transfer)
+7. [代理、跳板机与隧道](./guide/tunnels-and-proxy)
+8. [OTP 与认证](./guide/otp-and-auth)
+
+:::tip 截图建议
+- 推荐图片路径：`/img/docs/readme/main-workspace.png`
+- 建议展示内容：左侧活动栏、右侧面板、中心多标签终端、底部快捷区
+- 适合先执行的脚本：`scripts/demo-terminal-output.sh`
+:::