From d6bd206b5d0dad5025ce33010a8e5f0b0c25f4db Mon Sep 17 00:00:00 2001 From: Kang Date: Thu, 30 Apr 2026 11:14:11 +0800 Subject: [PATCH] docs: Expand documentation to include AI Assistant features and updates This commit enhances the README and various documentation files to reflect the integration of the AI Assistant in Dragonfly. Key updates include descriptions of AI capabilities, usage scenarios, and configuration settings. Additionally, the installation and quick start guides have been updated to highlight AI features, ensuring users are informed about the new functionalities and how to utilize them effectively. --- README.md | 23 ++++++--- docs-site/docs/development/architecture.md | 17 ++++--- docs-site/docs/development/backend.md | 29 +++++++++-- docs-site/docs/development/frontend.md | 18 ++++++- docs-site/docs/faq.md | 14 +++++- .../docs/getting-started/installation.md | 8 ++-- docs-site/docs/getting-started/quick-start.md | 26 +++++++--- docs-site/docs/guide/layout-and-workspace.md | 28 ++++++++--- docs-site/docs/guide/security.md | 29 ++++++++--- docs-site/docs/guide/terminal.md | 48 ++++++++++++++++++- docs-site/docs/intro.md | 40 ++++++++++------ 11 files changed, 220 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index bbc13e27..ad072e45 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ ## Overview -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, network tooling, session import / export, diagnostics, and protected configuration sync / backup workflows from one workspace. +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, network tooling, AI-assisted terminal actions, session import / export, diagnostics, and protected configuration sync / backup workflows from one workspace. ## Highlights @@ -13,7 +13,8 @@ Dragonfly is a desktop client for SSH-centric operations and mixed terminal work - 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 +- Saved connections with folders, icons, duplication, reconnect, import, and encrypted config restore +- Left / right activity bars for file explorer, network, security, sync & backup, AI assistant, command history, and resource monitoring - Child windows for settings, new-session, quick-command, and auto-upload flows - Tray support with optional minimize-to-tray behavior on window close @@ -29,17 +30,24 @@ 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 +- Built-in SFTP file explorer with upload, download, rename, move, delete, symlink, create-file, and properties actions - 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 +- Open remote files in a local editor and upload changes back through the watcher-driven auto-upload 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 +### AI assistance + +- Side-panel AI assistant for command generation, terminal output explanation, error analysis, and selected-text workflows +- Model / provider management for built-in providers and custom OpenAI-compatible endpoints +- Structured command cards with risk levels, approval gates, and optional save-to-quick-command support +- Reasoning-aware response rendering when providers expose a reasoning channel + ### Security and networking - Password auth, private keys, host-key verification, and local encrypted credential storage - OTP management with TOTP/HOTP, QR import, and SSH auto-fill support -- Screen lock, master password support, and known-hosts management +- Screen lock, master password support, and redb-backed known-hosts / secret persistence - Proxy configs, SSH jump hosts, and local / remote / dynamic tunnels - Diagnostics settings, local log management, and diagnostics bundle export for troubleshooting @@ -65,8 +73,10 @@ Dragonfly is a desktop client for SSH-centric operations and mixed terminal work The detailed user docs live in `docs-site/`. - Product overview: [docs-site/docs/intro.md](docs-site/docs/intro.md) +- Installation: [docs-site/docs/getting-started/installation.md](docs-site/docs/getting-started/installation.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) +- Session guide: [docs-site/docs/guide/session-types.md](docs-site/docs/guide/session-types.md) +- Terminal guide: [docs-site/docs/guide/terminal.md](docs-site/docs/guide/terminal.md) - 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) @@ -81,6 +91,7 @@ If you want to add screenshots later, these are the recommended stable asset pat - `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 +- `docs-site/static/img/docs/readme/ai-assistant.png` — AI assistant panel with command cards or explanation flow ## Tech stack diff --git a/docs-site/docs/development/architecture.md b/docs-site/docs/development/architecture.md index 2b92bcd8..0862d9ed 100644 --- a/docs-site/docs/development/architecture.md +++ b/docs-site/docs/development/architecture.md @@ -20,9 +20,9 @@ Dragonfly 是一个基于 **Tauri 2** 的桌面应用：前端在 `src/`，后 ├─────────────────────────────────────────────────────────┤ │ Backend (Rust) │ │ ├─ SessionManager / TunnelManager / RecordingManager │ -│ ├─ PendingAuthManager │ -│ ├─ SSH / SFTP / watcher / importer / stats │ -│ └─ JSON config + encrypted credential storage │ +│ ├─ PendingAuthManager / CloudSyncManager │ +│ ├─ SSH / SFTP / watcher / importer / stats / AI │ +│ └─ redb persistence + encrypted credential storage │ └─────────────────────────────────────────────────────────┘ ``` @@ -58,6 +58,7 @@ Dragonfly 是一个基于 **Tauri 2** 的桌面应用：前端在 `src/`，后 - 应用设置与 UI 设置 - 已保存连接 / 分组刷新 - 启动时恢复 `ui.open_tabs` +- 活动栏布局和面板状态 ### ChildAppProvider @@ -124,7 +125,7 @@ Dragonfly 的终端工作区有两个容易混淆、但职责不同的层次： - SFTP 文件与传输操作 - 连接 / 密钥 / 密码 / OTP / 设置读写 - cloud sync / backup 状态、推送、拉取、恢复、冲突处理 -- watcher、翻译、导入、stats、tunnel、proxy +- watcher、翻译、导入、stats、tunnel、proxy、AI ## SessionManager 与事件流 @@ -149,8 +150,9 @@ Dragonfly 的终端工作区有两个容易混淆、但职责不同的层次： | `cloud-sync-status-changed` | 云同步 / 备份状态变化 | | `cloud-sync-history-changed` | 同步 / 备份历史变化 | | `cloud-sync-conflict` | 云同步冲突预览与处理入口 | +| AI 流式事件 | AI 响应、推理内容、命令卡片和执行状态 | -## SSH / SFTP / watcher / 导入 +## SSH / SFTP / watcher / 导入 / AI 核心后端能力主要分布在这些模块： @@ -163,15 +165,16 @@ Dragonfly 的终端工作区有两个容易混淆、但职责不同的层次： - `src-tauri/src/core/recording.rs` — 会话录制 - `src-tauri/src/core/cloud_sync.rs` — 云同步、远程备份、状态事件、冲突处理 - `src-tauri/src/core/portable_snapshot.rs` — 可移植快照构建 / 应用与同步范围控制 +- `src-tauri/src/core/ai.rs` — provider 调用、流式响应、结构化输出、命令卡片与审计历史 ## 配置与持久化 应用配置保存在 `~/.dragonfly/dragonfly.redb` 中。主要 redb 文档包括： -- JSON 文档：`settings`、`sessions`、`keys`、`passwords`、`otp`、`quick-command`、`tunnels`、`proxies`、`history`、`cloud-sync-state` +- JSON 文档：`settings`、`sessions`、`keys`、`passwords`、`otp`、`quick-command`、`tunnels`、`proxies`、`history`、`cloud-sync`、`cloud-sync-state`、`ai-history`、`ai-audit` - 文本文档：`known_hosts`、`master.key` -旧版 `.dragonfly` JSON / 文本文件会在首次启动时迁入 redb，并保留在目录中作为人工回退备份。 +旧版 `.dragonfly` JSON / 文本文件会在首次启动时迁入 redb；迁移完成后，redb 成为主要存储位置。 其中敏感值会先加密再写盘，因此前端管理的是可复用凭据条目，而不是明文配置。 diff --git a/docs-site/docs/development/backend.md b/docs-site/docs/development/backend.md index 3bbb48a7..fd68ec0b 100644 --- a/docs-site/docs/development/backend.md +++ b/docs-site/docs/development/backend.md @@ -4,7 +4,7 @@ sidebar_position: 4 # 后端开发指南 -后端代码位于 `src-tauri/src/`，使用 Rust 编写，是 Dragonfly 的运行时核心：会话管理、SSH/SFTP、录制、翻译、隧道、认证、同步备份、导入导出与配置持久化都在这里落地。 +后端代码位于 `src-tauri/src/`，使用 Rust 编写，是 Dragonfly 的运行时核心：会话管理、SSH/SFTP、录制、翻译、AI、隧道、认证、同步备份、导入导出与配置持久化都在这里落地。 ## 命令入口与模块组织 @@ -33,7 +33,8 @@ src-tauri/src/cmd/ ├── stats.rs ├── translate.rs ├── tunnel.rs -└── watcher.rs +├── watcher.rs +└── ai.rs ``` 如果你要新增一个 command，通常需要： @@ -85,6 +86,7 @@ src-tauri/src/cmd/ - `recording.rs` — 会话录制 - `watcher.rs` — 本地文件监听与自动上传 - `importer.rs` — 外部客户端会话导入 +- `ai.rs` — AI provider 调用、流式输出和命令卡片生成 ## SSH 模块 @@ -136,6 +138,22 @@ src-tauri/src/cmd/ - `core/watcher.rs` - 前端 `FileUploadPage.tsx` +## AI runtime + +`src-tauri/src/core/ai.rs` 负责 AI 功能的后端核心逻辑，包括： + +- provider 请求与模型能力适配 +- 流式文本输出与推理内容捕获 +- 结构化 JSON 输出解析 +- 命令卡片生成、风险等级和执行审计 +- AI 历史与审计记录持久化 + +如果你修改 AI provider 行为或响应解析，重点留意： + +- 推理内容与主文本可能来自不同通道 +- 某些模型会把主要答案放在 reasoning 中 +- 前端依赖结构化命令卡片和风险字段做执行审批 + ## Cloud sync / portable snapshot `src-tauri/src/core/cloud_sync.rs` 负责这条能力线的运行时行为，包括： @@ -165,7 +183,7 @@ src-tauri/src/cmd/ - 哪些数据只应该保留在本机 - 备份快照和同步快照的范围差异 -当前实现里，portable snapshot 会覆盖连接、凭据配置、OTP、代理、隧道、快捷命令和大部分应用设置；但设备本地的运行态 UI 状态不会被无差别漫游。 +当前实现里，portable snapshot 会覆盖连接、凭据配置、OTP、代理、隧道、快捷命令、大部分应用设置，以及必要的文本密钥材料；但设备本地的运行态 UI 状态不会被无差别漫游。 ## 导入、导出与诊断 @@ -180,11 +198,11 @@ src-tauri/src/cmd/ ## 配置与加密 -配置和记录保存在 `~/.dragonfly/dragonfly.redb`，主要由 `src-tauri/src/storage.rs` 和 `src-tauri/src/config/` 管理。首次启动时会把旧版 `.dragonfly` JSON / 文本文件迁入 redb，但不会继续双写旧文件。 +配置和记录保存在 `~/.dragonfly/dragonfly.redb`，主要由 `src-tauri/src/storage.rs` 和 `src-tauri/src/config/` 管理。首次启动时会把旧版 `.dragonfly` JSON / 文本文件迁入 redb；迁移完成后不会继续把旧文件当作主存储。 主要 redb 文档包括： -- JSON 文档：`settings`、`sessions`、`keys`、`passwords`、`otp`、`quick-command`、`tunnels`、`proxies`、`history`、`cloud-sync-state` +- JSON 文档：`settings`、`sessions`、`keys`、`passwords`、`otp`、`quick-command`、`tunnels`、`proxies`、`history`、`cloud-sync`、`cloud-sync-state`、`ai-history`、`ai-audit` - 文本文档：`known_hosts`、`master.key` 敏感字段会在写盘前加密，因此新增配置时要确认是否属于敏感数据边界。 @@ -211,5 +229,6 @@ src-tauri/src/cmd/ | `cloud-sync-status-changed` | 云同步 / 备份状态变化 | | `cloud-sync-history-changed` | 同步 / 备份历史变化 | | `cloud-sync-conflict` | 云同步冲突预览 | +| AI 流式事件 | AI 响应、推理内容与执行状态 | 设计新后端能力时，优先考虑是否应该通过已有事件流对前端暴露，而不是额外引入新的轮询接口。 diff --git a/docs-site/docs/development/frontend.md b/docs-site/docs/development/frontend.md index b81ddc54..20f11a53 100644 --- a/docs-site/docs/development/frontend.md +++ b/docs-site/docs/development/frontend.md @@ -57,6 +57,7 @@ src/ - 已保存连接 / 分组刷新 - 应用设置与 UI 设置 - 启动恢复工作区 +- 左右活动栏和底部区域布局 ### ChildAppProvider @@ -102,8 +103,9 @@ const sessionId = await invoke('create_ssh_session', { - `cloud-sync-status-changed` - `cloud-sync-history-changed` - `cloud-sync-conflict` +- AI 相关流式事件 -终端、文件浏览器、资源监控、传输队列，以及 Sync & Backup 的状态 / 历史 / 冲突提示都建立在这些事件之上。 +终端、文件浏览器、资源监控、传输队列、AI Assistant，以及同步与备份的状态 / 历史 / 冲突提示都建立在这些事件之上。 ## 工作区模型 @@ -141,6 +143,18 @@ const sessionId = await invoke('create_ssh_session', { 如果你改的是终端表现层，这通常是第一落点。 +## AI Assistant 前端落点 + +如果你改的是 AI 相关 UI，优先查看这些文件： + +- `src/components/panel/AIAssistantPanel.tsx` — 主 AI 面板、会话列表、消息渲染、命令卡片、执行审批 +- `src/components/settings/AiTab.tsx` — AI 总开关、provider、模型、风险与 agent 配置 +- `src/lib/aiEvents.ts` — 从终端、文件、快捷命令等入口打开 AI Assistant 的事件桥 +- `src/lib/aiSettings.ts` — provider / model 默认值、风险规则和模型发现工具 +- `src/components/app/AppPanelContent.tsx` — AI 面板在右侧栏中的挂载方式 + +这条链路和当前活跃会话耦合较深，改动时要留意 pane / connection 上下文、模型可用性和执行审批状态。 + ## Sync & Backup 前端落点 如果你改的是同步与备份相关 UI，优先查看这些文件： @@ -148,7 +162,7 @@ const sessionId = await invoke('create_ssh_session', { - `src/pages/SettingsPage.tsx` — 设置页 tab 结构、保存拦截和主密码前置逻辑 - `src/components/settings/SyncBackupTab.tsx` — provider 配置、自动策略、手动操作、远程备份与冲突处理 - `src/components/panel/SyncBackupHistoryPanel.tsx` — 工作区历史面板与冲突快速处理入口 -- `src/App.tsx` — Sync & Backup 面板在主工作区中的接入方式 +- `src/App.tsx` — 云同步与备份面板在主工作区中的接入方式 - `src/lib/cloudSync.ts` — 前端默认值、格式化和 provider 校验工具 这些文件之间通过设置状态、Tauri commands 和 cloud-sync 事件一起驱动完整体验。 diff --git a/docs-site/docs/faq.md b/docs-site/docs/faq.md index ea7dc101..0d5b2513 100644 --- a/docs-site/docs/faq.md +++ b/docs-site/docs/faq.md @@ -65,6 +65,16 @@ sidebar_position: 100 这两项也都是按需开启的可选增强项，需要在 **设置 → 终端** 中分别打开。 +### 为什么 AI Assistant 里没有可用模型？ + +通常需要检查： + +1. **设置 → AI** 是否已经启用 AI 功能 +2. 是否已经配置并启用了至少一个 provider +3. 是否已经为 provider 启用至少一个模型 + +如果你使用的是自定义 provider，请确认它兼容 OpenAI 风格接口，并且 base URL、API Key 和模型发现结果都正确。 + ### 为什么点关闭窗口后应用没有完全退出？ 请检查 **设置 → 常规** 里的 **关闭时最小化到托盘** 是否已经开启。 @@ -137,4 +147,6 @@ sidebar_position: 100 ### Dragonfly 的配置文件存放在哪里？ -应用配置位于 `~/.dragonfly/dragonfly.redb`，其中会保存设置、连接、密钥、OTP、隧道、代理、历史等本地数据。旧版本的 JSON / 文本文件会在首次启动时迁入数据库并保留在目录中作为人工回退备份。 +当前主要用户数据保存在 `~/.dragonfly/dragonfly.redb` 中，其中会保存设置、连接、密钥、密码、OTP、隧道、代理、历史、AI 历史等本地数据。 + +旧版本的 JSON / 文本文件会在首次启动时迁入 redb；迁移完成后，redb 才是主要存储位置。 diff --git a/docs-site/docs/getting-started/installation.md b/docs-site/docs/getting-started/installation.md index 7da97ed2..5bdd4942 100644 --- a/docs-site/docs/getting-started/installation.md +++ b/docs-site/docs/getting-started/installation.md @@ -34,8 +34,8 @@ Dragonfly 支持以下操作系统： - **顶部菜单与窗口栏** — File / View / Help、窗口控制与应用级入口 - **中央工作区** — 终端标签页，以及标签内横向 / 纵向分屏 -- **左侧活动栏与面板** — 文件浏览器、网络、Security/Auth、Sync & Backup 等能力入口 -- **右侧活动栏与面板** — 已保存连接、活动会话、命令历史、资源监控等运行态信息 +- **左侧活动栏与面板** — 文件浏览器、网络、Security/Auth、云同步与备份、设置等能力入口 +- **右侧活动栏与面板** — 已保存连接、AI Assistant、活动会话、命令历史、资源监控等运行态信息 - **底部辅助区** — 快捷命令、串口发送、录制、锁屏等辅助操作 某些流程会打开独立子窗口，而不是打断主工作区，例如： @@ -52,8 +52,10 @@ Dragonfly 支持以下操作系统： - **设置 → 常规**：启动恢复、关闭时最小化到托盘、关闭确认 - **设置 → 常规**：日志级别、日志保留时间、打开日志目录、导出诊断包 - **设置 → 交互**：命令建议开关、历史命令长度范围、复制与右键粘贴 +- **设置 → 终端**：回滚缓冲区、Keep-Alive、动作链接、行号 / 时间戳、关键词高亮、资源监控 - **设置 → 传输**：默认下载目录、默认编辑器、录制保存路径、并发与重试策略 - **设置 → 安全**：主密码、锁屏、主机密钥策略 +- **设置 → AI**：provider、模型、风险控制与上下文限制 如果你经常在后台保留会话或同步任务，**关闭时最小化到托盘** 值得优先确认。 @@ -82,5 +84,5 @@ Dragonfly 支持以下操作系统： 2. 创建一个 **SSH** 连接，或先导入已有会话 3. 再创建一个 **本地终端**，体验混合工作区 4. 在 SSH 会话里打开文件浏览器和传输面板 -5. 试试命令历史、快捷命令、录制与终端搜索 +5. 试试命令历史、快捷命令、AI 助手、录制与终端搜索 6. 如果你在 Windows 上，可额外尝试把本地文件或文件夹直接拖到文件浏览器中上传 diff --git a/docs-site/docs/getting-started/quick-start.md b/docs-site/docs/getting-started/quick-start.md index 86a9133c..061edbfb 100644 --- a/docs-site/docs/getting-started/quick-start.md +++ b/docs-site/docs/getting-started/quick-start.md @@ -4,7 +4,7 @@ sidebar_position: 2 # 快速开始 -本章帮助你在最短路径内体验 Dragonfly 的核心工作流：创建连接、打开会话、使用分屏、查看文件、启用终端增强功能，并了解迁移与备份入口。 +本章帮助你在最短路径内体验 Dragonfly 的核心工作流：创建连接、打开会话、使用分屏、查看文件、启用终端增强功能，并了解迁移、AI 辅助与备份入口。 ## 第一步：选择会话类型 @@ -61,8 +61,8 @@ Dragonfly 支持从以下来源导入： 连接建立后，你会看到： - **中央区域** — 当前终端标签页与分屏窗格 -- **左侧活动栏** — 文件浏览器、网络、Security/Auth、Sync & Backup 等面板入口 -- **右侧活动栏** — 已保存连接、活动会话、命令历史、资源监控等入口 +- **左侧活动栏** — 文件浏览器、网络、Security/Auth、云同步与备份、设置等面板入口 +- **右侧活动栏** — 已保存连接、AI Assistant、活动会话、命令历史、资源监控等入口 - **底部区域** — 快捷命令、串口发送、录制、锁屏等辅助区域 如果你希望关闭主窗口时保留应用在后台运行，可以到 **设置 → 常规** 开启 **关闭时最小化到托盘**。 @@ -117,7 +117,18 @@ SSH 会话激活后，文件浏览器面板可直接浏览远程目录，并支 - 用自定义搜索引擎做**在线搜索** - 按已启用的翻译 provider 做**翻译** -### 6. 启用终端增强项 +### 6. 试试 AI Assistant + +右侧活动栏中的 **AI Assistant** 适合这些场景： + +- 让 AI 根据你的目标生成一条命令 +- 解释最近终端输出或当前选中文本 +- 分析错误信息并给出修复建议 +- 将生成的结构化命令卡片保存为快捷命令 + +如果你第一次打开时没有可用模型，可以先到 **设置 → AI** 配置 provider、模型和风险控制。 + +### 7. 启用终端增强项 可在 **设置 → 终端** 中按需打开： @@ -129,20 +140,22 @@ SSH 会话激活后，文件浏览器面板可直接浏览远程目录，并支 这些能力默认更偏保守，需要你按场景开启。 -### 7. 试一次录制 +### 8. 试一次录制 Dragonfly 支持把当前会话输出录制为日志文件。 如果你希望把录制文件集中保存到固定目录，可以先在 **设置 → 传输** 里设置 **录制保存路径**。 -### 8. 看一下通用设置和诊断入口 +### 9. 看一下通用设置和诊断入口 在正式长期使用前，建议先快速看一遍这些设置分组： - **设置 → 常规**：启动恢复、关闭时最小化到托盘、关闭确认 - **设置 → 交互**：命令建议、历史命令长度过滤、复制与右键粘贴 +- **设置 → 终端**：回滚缓冲区、Keep-Alive、动作链接、关键词高亮 - **设置 → 传输**：下载目录、默认编辑器、录制路径、传输并发 - **设置 → 安全**：主密码、锁屏、主机密钥策略 +- **设置 → AI**：provider、模型、风险门槛、历史记录和上下文限制 如果你在排查问题，**设置 → 常规** 里还能直接： @@ -168,4 +181,5 @@ Dragonfly 支持把当前会话输出录制为日志文件。 - 想管理文件与自动回传：查看 [SFTP 文件传输](../guide/file-transfer) - 想了解终端增强与录制：查看 [终端功能](../guide/terminal) - 想配置 OTP：查看 [OTP 与认证](../guide/otp-and-auth) +- 想启用 AI 辅助：查看 [终端功能](../guide/terminal) - 想启用云同步和加密备份：查看 [同步与备份](../guide/sync-and-backup) diff --git a/docs-site/docs/guide/layout-and-workspace.md b/docs-site/docs/guide/layout-and-workspace.md index 584d80b3..3b597d1a 100644 --- a/docs-site/docs/guide/layout-and-workspace.md +++ b/docs-site/docs/guide/layout-and-workspace.md @@ -11,8 +11,8 @@ Dragonfly 的核心体验不是“单个终端标签页”，而是一个可组 典型工作区由几部分组成： - **中央区域**：标签页与终端窗格 -- **左侧活动栏 / 面板**：文件浏览器、网络、Security/Auth、Sync & Backup -- **右侧活动栏 / 面板**：已保存连接、活动会话、命令历史、资源监控 +- **左侧活动栏 / 面板**：文件浏览器、网络、Security/Auth、云同步与备份、设置 +- **右侧活动栏 / 面板**：已保存连接、AI Assistant、活动会话、命令历史、资源监控 - **底部辅助区域**：快捷命令、串口发送、录制、锁定 这些区域不是固定死的单一页面，而是围绕当前活跃会话动态协作。 @@ -74,11 +74,12 @@ Dragonfly 的核心体验不是“单个终端标签页”，而是一个可组 - 文件浏览器 - 网络 - Security/Auth -- Sync & Backup +- 云同步与备份 +- 设置 其中 **文件浏览器** 不只是静态目录树：在 SSH 会话中，它可以和当前终端 cwd 联动，并支持把当前目录或条目路径直接发回终端继续补命令。 -其中 **Sync & Backup** 面板更偏“跨设备配置同步 / 备份恢复”的运行态入口：它会展示当前状态、最近的同步与备份活动，并在发生冲突时提供直接处理入口。 +其中 **云同步与备份** 面板更偏“跨设备配置同步 / 备份恢复”的运行态入口：它会展示当前状态、最近的同步与备份活动，并在发生冲突时提供直接处理入口。 如果你只是想快速知道“最近同步成功了吗”“上次备份有没有失败”，在工作区历史面板里查看通常比回到设置页更直接。 @@ -87,11 +88,25 @@ Dragonfly 的核心体验不是“单个终端标签页”，而是一个可组 右侧更偏“运行态信息”，通常包括： - 已保存连接 +- AI Assistant - 活动会话 - 命令历史 - 资源监控 -如果你的工作流是“先选连接，再看运行状态”，这种左右分工会很自然。 +如果你的工作流是“先选连接，再看运行状态，必要时再调用 AI 分析”，这种左右分工会很自然。 + +## AI Assistant 面板 + +右侧的 **AI Assistant** 不是独立弹窗，而是工作区中的常驻面板。它适合配合当前活跃窗格做这些事： + +- 根据自然语言生成一条终端命令 +- 解释最近终端输出 +- 解释当前选中的文本 +- 分析错误并给出修复建议 +- 生成可审批的命令卡片并执行 +- 把合适的命令保存为快捷命令 + +因为它和当前会话上下文直接联动，所以放在工作区右侧通常比额外开窗口更顺手。 ## 底部辅助区域 @@ -135,7 +150,7 @@ Dragonfly 的核心体验不是“单个终端标签页”，而是一个可组 - 标签 1：SSH 登录远程主机 - 标签 2：本地终端执行构建或 Git 命令 -- 右侧打开命令历史 +- 右侧打开命令历史或 AI Assistant ### 组合二：双窗格排障 @@ -149,4 +164,3 @@ Dragonfly 的核心体验不是“单个终端标签页”，而是一个可组 - 文件浏览器同步到当前路径 - 打开远程文件，本地编辑后自动回传 - 把当前目录或文件路径直接发送到终端继续执行命令 - diff --git a/docs-site/docs/guide/security.md b/docs-site/docs/guide/security.md index f60a6065..06997c7d 100644 --- a/docs-site/docs/guide/security.md +++ b/docs-site/docs/guide/security.md @@ -8,17 +8,18 @@ Dragonfly 的安全能力主要围绕三件事展开： 1. 安全保存本地凭据与认证材料 2. 管理 SSH 连接过程中的主机校验与二次认证 -3. 在桌面端工作区中提供锁屏与主密码保护 +3. 在桌面端工作区中提供锁屏、主密码与敏感操作保护 ## 本地敏感数据的保存方式 -Dragonfly 会在本地保存连接相关配置，并对敏感内容做加密处理后再写入配置文件。常见的敏感数据包括： +Dragonfly 会在本地保存连接相关配置，并对敏感内容做加密处理后再写入本地存储。常见的敏感数据包括： - 已保存密码 - SSH 私钥与私钥口令 - OTP 密钥 -- 主密码本身的持久化表示 +- 主密码相关保护材料 - 代理或其他需要保护的认证材料 +- AI provider 凭据 因此，平时使用时你看到的是“可以复用的密码 / 私钥 / OTP 条目”，而不是明文直接散落在普通文本配置里。 @@ -78,7 +79,7 @@ OTP 管理支持： 如果你没有设置主密码，后续锁屏就只是一层界面遮罩，而不是严格意义上的密码保护。 -## 同步与备份的安全模型 +## 同步、备份与导入导出的安全模型 如果你准备启用 **设置 → 同步与备份**，主密码不只是“建议项”，而是前置条件。 @@ -87,6 +88,8 @@ OTP 管理支持： - 没有主密码时，不能启用同步与备份相关操作 - 云端 provider 凭据会作为受保护的本地敏感数据处理 - 上传到云端的是**加密后的可移植快照**，而不是明文配置文件 +- `.dgfy` 导入 / 导出同样依赖主密码 +- 导入 `.dgfy` 后通常需要重启应用 - 远程恢复会覆盖快照中包含的可移植本地数据，但不会把所有设备本地 UI 状态都无差别漫游到另一台设备上 这意味着它更适合被理解为： @@ -128,15 +131,26 @@ SSH 首次连接未知主机时，Dragonfly 支持三种策略： | 接受 | 自动接受新的主机密钥 | | 严格 | 拒绝所有未知主机 | -已知主机记录保存在 `~/.dragonfly/dragonfly.redb` 的本地存储中；旧版 `known_hosts` 会在首次启动时迁入。 +已知主机记录最终保存在本地 `redb` 存储中的 `known_hosts` 文本文档；旧版 `known_hosts` 文件会在首次启动时迁入。 如果你处在对主机身份校验要求更高的环境，建议使用“提示”或“严格”，而不是无条件接受。 -## 配置导入、导出与诊断 +## 本地持久化模型 + +Dragonfly 当前把主要用户数据保存在 `~/.dragonfly/dragonfly.redb` 中，而不是继续以多个 JSON 文件作为主存储。 + +其中大致包括： + +- 设置、连接、密钥、密码、OTP、代理、隧道、快捷命令、历史等 JSON 文档 +- `known_hosts`、`master.key` 等文本文档 + +旧版本的 `.dragonfly` JSON / 文本文件会在首次启动时迁入 redb，迁移完成后不会继续作为新的主写入路径。 + +## 诊断与排障材料 除了连接与凭据管理，Dragonfly 还提供两类常见的数据操作： -- **导入 / 导出配置**：用于迁移或备份 Dragonfly 自身配置，文件格式为加密的 `.dgfy` +- **导出配置**：把全部配置压缩并加密为 `.dgfy` - **导出诊断包**：用于打包近期日志、运行时摘要等排障信息 需要注意： @@ -151,3 +165,4 @@ SSH 首次连接未知主机时，Dragonfly 支持三种策略： - 对共享电脑或演示机，开启 **主密码** 与 **屏幕锁定** - 对需要经常穿过堡垒机的环境，把 **跳板机** 和 **代理** 做成明确的已保存配置 - 对首次连接的新主机，核对主机密钥来源后再信任 +- 对 AI provider 凭据、同步 provider 凭据和 `.dgfy` 备份文件，按和 SSH 凭据相同的敏感级别管理 diff --git a/docs-site/docs/guide/terminal.md b/docs-site/docs/guide/terminal.md index a5ec10a2..3a9d5339 100644 --- a/docs-site/docs/guide/terminal.md +++ b/docs-site/docs/guide/terminal.md @@ -4,7 +4,7 @@ sidebar_position: 3 # 终端功能 -Dragonfly 的终端体验围绕“在同一个工作区里高频处理远程与本地会话”设计。它基于 xterm.js，但实际体验并不只是一块终端画布，还包括搜索、命令历史、建议、可选增强项、录制和 SSH 辅助能力。 +Dragonfly 的终端体验围绕“在同一个工作区里高频处理远程与本地会话”设计。它基于 xterm.js，但实际体验并不只是一块终端画布，还包括搜索、命令历史、建议、AI 辅助、可选增强项、录制和 SSH 辅助能力。 ## 基础操作 @@ -17,6 +17,7 @@ Dragonfly 的终端体验围绕“在同一个工作区里高频处理远程与 - 查找文本 - 在线搜索选中文本 - 按 provider 翻译选中文本 +- 交给 AI Assistant 解释或分析 - 清屏 / 全部清除 - 全选 @@ -59,6 +60,39 @@ Dragonfly 会为会话工作流提供两类辅助： - 它们不会影响右侧命令历史面板中的已有记录 - 它们也不会影响**快捷命令**本身的可用性 +## AI Assistant + +Dragonfly 在右侧面板中内置了 **AI Assistant**，并且可以从终端上下文直接唤起。 + +### 常见用法 + +- **生成命令**：告诉它你想完成什么，由它生成命令卡片 +- **解释最近输出**：针对当前会话最近的终端输出做说明 +- **解释选中内容**：对选中的日志、报错或片段做解释 +- **分析错误**：把错误上下文交给 AI 生成修复建议 +- **修复选中内容**：从选中报错推导下一步命令 + +### 命令卡片与风险控制 + +AI 返回的命令可以以结构化卡片形式展示，并带有风险等级。你可以根据 **设置 → AI** 中的配置决定： + +- 哪些风险等级允许直接执行 +- 是否开启风险检查 +- 是否允许把生成命令保存为快捷命令 +- 是否记录 AI 历史 + +### Provider 与模型 + +AI 能力支持： + +- 内置 provider 配置 +- 自定义 **OpenAI Compatible** provider +- 按模型启用 / 禁用 +- 默认模型选择 +- 上下文行数限制与超时控制 + +如果你准备在生产环境或受限网络下使用，建议先到 **设置 → AI** 完成 provider、模型和风险门槛配置。 + ## 可选终端增强项 下面这些能力都需要你按需开启，而不是默认全部打开。 @@ -144,6 +178,17 @@ Dragonfly 会为会话工作流提供两类辅助： - 使用自定义搜索引擎做在线搜索 - 使用已启用的翻译 provider 打开翻译对话框 +### 搜索引擎 + +在 **设置 → 搜索** 中，你可以维护自定义搜索引擎列表，为它们设置： + +- 名称 +- URL 模板（使用 `%s` 占位） +- 图标 +- 是否显示在搜索菜单中 + +### 翻译 provider + 翻译 provider 的可见性取决于设置： - **Google**、**Microsoft** 无需额外配置 @@ -165,6 +210,7 @@ Dragonfly 支持会话录制，适合： - 关键词高亮 - 动作链接 - 命令历史 +- AI Assistant - 资源监控 这样更容易拍出“终端在真实工作流中使用”的截图，而不是单独展示某个开关。 diff --git a/docs-site/docs/intro.md b/docs-site/docs/intro.md index 125fb40a..60edde7c 100644 --- a/docs-site/docs/intro.md +++ b/docs-site/docs/intro.md @@ -5,7 +5,7 @@ slug: / # 项目介绍 -**Dragonfly** 是一个围绕远程终端工作流设计的桌面客户端。它以 Tauri + React 构建前端界面，以 Rust 负责 SSH、SFTP、会话管理、隧道、认证、同步备份与配置持久化，让你在同一个工作区中处理远程服务器、本地 shell、串口设备和网络辅助能力。 +**Dragonfly** 是一个围绕远程终端工作流设计的桌面客户端。它以 Tauri + React 构建前端界面，以 Rust 负责 SSH、SFTP、会话管理、隧道、认证、AI 能力、同步备份与配置持久化，让你在同一个工作区中处理远程服务器、本地 shell、串口设备和网络辅助能力。 ## 适合哪些场景 @@ -13,7 +13,7 @@ slug: / - 在本地终端、Telnet、串口设备之间切换排障 - 边看终端输出边操作远程文件 - 为常用运维命令、登录流程和跳板机链路做标准化配置 -- 需要 OTP、录制、资源监控、自动上传、跨设备配置同步或加密备份等增强能力 +- 需要 OTP、录制、资源监控、自动上传、AI 辅助、跨设备配置同步或加密备份等增强能力 - 想从 Xshell、MobaXterm、WindTerm 或 Dragonfly 备份文件快速迁移现有配置 ## 核心能力 @@ -31,7 +31,7 @@ Dragonfly 不只支持 SSH，还支持： - 多标签页管理多个会话 - 标签页内支持**横向/纵向分屏** -- 左右活动栏可放置文件浏览器、网络、Security/Auth、会话列表、命令历史、资源监控等面板 +- 左右活动栏可放置文件浏览器、网络、Security/Auth、云同步与备份、设置、AI 助手、会话列表、命令历史、资源监控等面板 - 底部辅助区可承载快捷命令、串口发送、录制与锁屏入口 - 设置、新建连接、快捷命令、自动上传提示均使用独立子窗口，减少主工作区干扰 - 支持托盘最小化，让窗口关闭动作可以转为后台驻留 @@ -50,10 +50,18 @@ Dragonfly 不只支持 SSH，还支持： ### 远程文件与传输队列 - SSH 会话下内置 SFTP 文件浏览器 -- 上传、下载、重命名、移动、删除、属性查看、新建符号链接 +- 上传、下载、重命名、移动、删除、属性查看、新建文件 / 文件夹 / 符号链接 - 传输队列支持暂停、继续、取消、失败重试、断点续传、时间戳保留 - 在本地编辑下载的远程文件后，可通过 watcher 流程快速上传回远端 -- 可为录制文件单独设置保存目录，便于整理排障素材 +- Windows 下支持把本地文件或文件夹直接拖进文件浏览器上传 + +### AI 助手与自动化辅助 + +- 右侧活动栏内置 **AI Assistant** 面板 +- 可从终端输出、选中文本、文件操作或手动输入发起 AI 请求 +- 支持命令生成、错误分析、输出解释、修复建议等典型场景 +- 可配置内置 provider 与自定义 **OpenAI Compatible** provider +- 支持结构化命令卡片、风险等级控制、审批后执行和保存为快捷命令 ### 安全、迁移与网络能力 @@ -63,7 +71,7 @@ Dragonfly 不只支持 SSH，还支持： - 锁屏与主密码能力 - 支持导入 **Xshell / MobaXterm / WindTerm** 会话 - 支持导入 / 导出 Dragonfly 自身的加密 `.dgfy` 配置备份 -- 可导出诊断包，便于问题排查与支持协作 +- 可打开日志目录并导出诊断包，便于问题排查与支持协作 ### 云同步与加密备份 @@ -76,12 +84,14 @@ Dragonfly 不只支持 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) -9. [同步与备份](./guide/sync-and-backup) +1. [安装指南](./getting-started/installation) +2. [快速开始](./getting-started/quick-start) +3. [会话类型](./guide/session-types) +4. [SSH 连接管理](./guide/ssh-connection) +5. [工作区与布局](./guide/layout-and-workspace) +6. [终端功能](./guide/terminal) +7. [SFTP 文件传输](./guide/file-transfer) +8. [代理、跳板机与隧道](./guide/tunnels-and-proxy) +9. [OTP 与认证](./guide/otp-and-auth) +10. [安全功能](./guide/security) +11. [同步与备份](./guide/sync-and-backup)