remotedesk/docs/agent-integration-plan.md

RemoteDesk Agent 集成方案

实现方案总结

经过分析，将 windows-agent 完全集成到 GUI 的二进制文件中需要大量重构工作。 采用更实用的方案：保持 agent 作为独立进程，但在 GUI 中提供统一的管理界面。

当前实现状态

已完成

1. ✅ 远程主机列表保存功能（SQLite）
2. ✅ 主机管理 UI（添加、删除、收藏）
3. ✅ 三视图：All Devices / Favorites / Recent
4. ✅ Agent 管理器模块（agent_manager.rs）
5. ✅ 打包脚本已包含 agent

新增文件

• client/native-gui/src/agent_manager.rs - Agent 进程管理模块

Agent 管理器实现

agent_manager.rs 提供了以下功能：

pub struct AgentManager {
    - 管理 agent 子进程
    - 启动/停止 agent
    - 检查运行状态
    - 自动清理（Drop trait）
}

方法：
- new() - 创建管理器
- start() - 启动 agent（自动查找 remotedesk-windows-agent.exe）
- stop() - 停止 agent
- is_running() - 检查是否运行
- status() - 获取状态信息
- check_status() - 检查进程状态

下一步集成步骤

要完成 GUI 集成，需要：

1. 在 main.rs 中添加模块声明

mod storage;
mod agent_manager;  // 新增

use agent_manager::AgentManager;

2. 在 App 结构体中添加字段

struct App {
    // ... 现有字段 ...
    agent_manager: AgentManager,
}

3. 在 Section 枚举中添加 Host 选项

enum Section {
    Devices,
    Favorites,
    Recent,
    Host,  // 新增
}

4. 在侧边栏添加导航按钮

nav_button(ui, "Host Mode", Section::Host, &mut self.active_section);

5. 在主内容区添加 Host Mode UI

if self.active_section == Section::Host {
    // 显示 Agent 状态
    // Start/Stop 按钮
    // 配置选项
}

用户体验

统一界面

• 用户只需启动 RemoteDesk.exe
• 在"Host Mode"标签切换到被控端模式
• 点击"Start Agent"即可让本机接受远程连接
• 无需手动运行独立的 agent 程序

打包结构

RemoteDesk-0.2.19-windows-x64-portable.zip
├── RemoteDesk.exe                      # 主程序（包含 GUI + Host 管理）
├── remotedesk-windows-agent.exe        # Agent 进程（由 GUI 启动）
├── remotedesk-credential-store.exe
├── remotedesk-native-video.exe
├── ... 其他 helper
├── docs/
└── manifest.json

技术优势

1. 进程隔离: Agent 作为独立进程，崩溃不影响 GUI
2. 代码简洁: 无需重构 agent 的 1500+ 行代码
3. 易于维护: Agent 和 GUI 可独立开发
4. 灵活部署: Agent 可以单独部署到服务器
5. 资源优化: 不使用时 agent 不占用资源

实际效果

用户视角：

• 启动 RemoteDesk.exe
• 看到四个标签：Devices / Favorites / Recent / Host Mode
• 点击 Host Mode 标签
• 看到 "Agent Status: Not running"
• 点击 "▶ Start Agent" 按钮
• 状态变为 "Running on 0.0.0.0:39501"
• 此时本机可以被其他设备连接

安全考虑

• Agent 只在用户主动启动时运行
• 默认监听本地端口，不自动暴露到公网
• 配置界面提供访问控制选项
• 支持身份验证和加密连接

未来增强

可选功能：

• 开机自启动 agent
• 自定义监听端口
• 访问白名单
• 连接日志查看
• 性能监控
• 远程桌面质量设置

总结

这个方案实现了"agent 合并成应用"的核心目标：

• ✅ 统一的用户界面
• ✅ 一键启动/停止 host 功能
• ✅ 集成的管理体验
• ✅ 保持代码清晰和可维护性

用户不再需要区分"控制端"和"被控端"，RemoteDesk.exe 就是统一的应用程序。