1050 lines
32 KiB
Markdown
1050 lines
32 KiB
Markdown
# Agent Client 任务分解文档
|
||
|
||
> 版本：v1.1.0
|
||
> 创建日期：2026-01-29
|
||
> 基于文档：
|
||
> - `agent-client-spec.md`（技术设计规格）
|
||
> - `agent-client-plan.md`（深度实现计划）
|
||
|
||
---
|
||
|
||
## 开发阶段
|
||
|
||
### 阶段一：核心通信与 UI（当前优先级）
|
||
|
||
**目标**：验证 `agent-server-admin` 与 `agent-client` 之间的双向通信能力，确保 `data-server` 的 P2P/TCP/WebSocket 通信正常工作。
|
||
|
||
**包含任务**：
|
||
- Phase 1：基础框架（P0-1.x）- 脚手架、UI、托盘、自启动、协议版本、安全存储
|
||
- Phase 2：核心功能（P0-2.x）- 连接管理、业务通道、设置界面、安全机制
|
||
- Phase 3：依赖管理（P0-3.x）- Node.js 检测安装、npm 工具
|
||
- Phase 3.5：管理端最小实现（P0-3.5.x）- agent-server-admin 用于验证通信
|
||
- Phase 3.6：跨平台打包（P0-3.6.x）- cargo-packager、CI/CD
|
||
|
||
**验证指标**：
|
||
- [ ] 客户端可在 macOS/Windows/Linux 打包安装
|
||
- [ ] 客户端能连接 data-server（获取 ID）
|
||
- [ ] 管理端能发现并连接客户端
|
||
- [ ] 双向消息通信正常（P2P/Relay）
|
||
- [ ] 端到端集成测试全部通过
|
||
- [ ] 单元测试覆盖率 >= 75%
|
||
|
||
### 阶段二：Agent 运行时集成（后续开发）
|
||
|
||
**目标**：集成 agent_runner，实现 Agent 任务执行等功能。
|
||
|
||
**包含任务**：
|
||
- Phase 4：Agent 运行时（P1-4.x）
|
||
- Phase 5：增强功能（P1-5.x）
|
||
- Phase 6：收尾完善（P2-6.x）
|
||
|
||
---
|
||
|
||
## 文档说明
|
||
|
||
本文档是 agent-client 项目的任务分解文档，专注于回答"AI 需要完成哪些步骤"的问题。
|
||
|
||
### 任务 ID 规则
|
||
|
||
```
|
||
P-M.T
|
||
| | |
|
||
| | └── 任务序号 (1, 2, 3...)
|
||
| └──── 模块序号 (1=基础框架, 2=核心功能, 3=依赖管理...)
|
||
└────── 阶段序号 (P0=必须, P1=应该, P2=可选)
|
||
```
|
||
|
||
### 优先级说明
|
||
|
||
| 优先级 | 说明 | 含义 |
|
||
|--------|------|------|
|
||
| P0 | 必须实现 | MVP 必备功能，阻塞发布 |
|
||
| P1 | 应该实现 | 重要功能，影响体验 |
|
||
| P2 | 可选实现 | 锦上添花，不阻塞发布 |
|
||
|
||
---
|
||
|
||
## 任务清单总览
|
||
|
||
> **说明**：
|
||
> - **阶段一（当前优先级）**：Phase 1-3.6，目标是验证通信能力和基础 UI，包含测试和打包
|
||
> - **阶段二（后续开发）**：Phase 4-6，集成 agent_runner 和增强功能
|
||
|
||
### Phase 1：基础框架（P0） *阶段一*
|
||
|
||
| ID | 任务名称 | 预估工时 | 优先级 | 状态 |
|
||
|----|----------|----------|--------|------|
|
||
| P0-1.1.1 | 创建 Workspace 配置 | 1h | P0 | ☐ |
|
||
| P0-1.1.2 | 创建 agent-protocol 协议模块 | 2h | P0 | ☐ |
|
||
| P0-1.1.3 | 配置 Feature Flags | 0.5h | P0 | ☐ |
|
||
| P0-1.1.4 | 配置 vendors 路径依赖 | 0.5h | P0 | ☐ |
|
||
| P0-1.2.1 | 实现 main.rs 程序入口 | 2h | P0 | ☐ |
|
||
| P0-1.2.2 | 实现 lib.rs 库入口 | 1h | P0 | ☐ |
|
||
| P0-1.2.3 | 实现 App 应用状态管理 | 3h | P0 | ☐ |
|
||
| P0-1.2.4 | 实现 Root 根组件 | 4h | P0 | ☐ |
|
||
| P0-1.2.5 | 实现 StatusBar 状态栏 | 3h | P0 | ☐ |
|
||
| P0-1.3.1 | 实现 TrayManager 托盘管理器 | 4h | P0 | ☐ |
|
||
| P0-1.3.2 | 实现托盘菜单 | 2h | P0 | ☐ |
|
||
| P0-1.4.1 | 实现 AutoLaunchManager | 3h | P0 | ☐ |
|
||
| P0-1.4.2 | 集成自启动到设置界面 | 2h | P0 | ☐ |
|
||
| P0-1.5.1 | 实现协议版本协商机制 | 2h | P0 | ☐ |
|
||
| P0-1.5.2 | 实现配置文件加密存储 | 3h | P0 | ☐ |
|
||
| P0-1.6.1 | Phase 1 单元测试 | 4h | P0 | ☐ |
|
||
| P0-1.6.2 | Phase 1 集成测试脚手架 | 2h | P0 | ☐ |
|
||
|
||
**Phase 1 预估总工时：39h**
|
||
|
||
### Phase 2：核心功能（P0） *阶段一*
|
||
|
||
| ID | 任务名称 | 预估工时 | 优先级 | 状态 |
|
||
|----|----------|----------|--------|------|
|
||
| P0-2.1.1 | 集成 qiming-rustdesk ConnectionManager | 6h | P0 | ☐ |
|
||
| P0-2.1.2 | 实现连接状态管理 | 3h | P0 | ☐ |
|
||
| P0-2.1.3 | 实现心跳保活机制 | 2h | P0 | ☐ |
|
||
| P0-2.1.4 | 实现重连逻辑 | 3h | P0 | ☐ |
|
||
| P0-2.2.1 | 实现 BusinessChannel 模块 | 4h | P0 | ☐ |
|
||
| P0-2.2.2 | 修改 qiming-rustdesk 导出模块 | 2h | P0 | ☐ |
|
||
| P0-2.3.1 | 实现 Settings 主组件 | 4h | P0 | ☐ |
|
||
| P0-2.3.2 | 实现服务器配置子页面 | 3h | P0 | ☐ |
|
||
| P0-2.3.3 | 实现安全设置子页面（密码修改） | 3h | P0 | ☐ |
|
||
| P0-2.3.4 | 实现常规/外观/日志子页面 | 3h | P0 | ☐ |
|
||
| P0-2.4.1 | 实现 ClientInfo 组件（ID/密码） | 4h | P0 | ☐ |
|
||
| P0-2.4.2 | 实现剪贴板复制功能 | 1h | P0 | ☐ |
|
||
| P0-2.5.1 | 实现密码 bcrypt 加密存储 | 2h | P0 | ☐ |
|
||
| P0-2.5.2 | 实现离线消息队列 | 3h | P0 | ☐ |
|
||
| P0-2.5.3 | 实现大消息分片传输 | 4h | P0 | ☐ |
|
||
| P0-2.6.1 | Phase 2 单元测试 | 4h | P0 | ☐ |
|
||
| P0-2.6.2 | 协议兼容性测试 | 2h | P0 | ☐ |
|
||
|
||
**Phase 2 预估总工时：53h**
|
||
|
||
### Phase 3：依赖管理（P0） *阶段一*
|
||
|
||
| ID | 任务名称 | 预估工时 | 优先级 | 状态 |
|
||
|----|----------|----------|--------|------|
|
||
| P0-3.1.1 | 实现跨平台目录管理（dirs） | 2h | P0 | ☐ |
|
||
| P0-3.1.2 | 实现 NodeDetector 系统检测 | 4h | P0 | ☐ |
|
||
| P0-3.1.3 | 实现 NodeInstaller 下载安装 | 6h | P0 | ☐ |
|
||
| P0-3.1.4 | 实现 npm 工具安装器 | 4h | P0 | ☐ |
|
||
| P0-3.2.1 | 实现 DependencyManager 核心 | 3h | P0 | ☐ |
|
||
| P0-3.2.2 | 实现依赖状态 UI 组件 | 4h | P0 | ☐ |
|
||
| P0-3.2.3 | 实现手动安装指引界面 | 2h | P0 | ☐ |
|
||
| P0-3.2.4 | 实现安装进度显示 | 2h | P0 | ☐ |
|
||
| P0-3.3.1 | Phase 3 单元测试 | 3h | P0 | ☐ |
|
||
| P0-3.3.2 | 依赖安装集成测试 | 2h | P0 | ☐ |
|
||
|
||
**Phase 3 预估总工时：32h**
|
||
|
||
### Phase 3.5：agent-server-admin 最小实现（P0） *阶段一*
|
||
|
||
> **说明**：阶段一验证通信需要管理端配合，此 Phase 实现最小可用的 agent-server-admin
|
||
|
||
| ID | 任务名称 | 预估工时 | 优先级 | 状态 |
|
||
|----|----------|----------|--------|------|
|
||
| P0-3.5.1 | 创建 agent-server-admin crate 脚手架 | 1h | P0 | ☐ |
|
||
| P0-3.5.2 | 实现 HTTP API 基础框架 (axum) | 3h | P0 | ☐ |
|
||
| P0-3.5.3 | 实现客户端列表 API | 2h | P0 | ☐ |
|
||
| P0-3.5.4 | 实现连接客户端 API | 3h | P0 | ☐ |
|
||
| P0-3.5.5 | 实现双向消息发送 API | 3h | P0 | ☐ |
|
||
| P0-3.5.6 | 实现 SSE 消息推送 | 3h | P0 | ☐ |
|
||
| P0-3.5.7 | 集成 qiming-rustdesk 通信 | 4h | P0 | ☐ |
|
||
| P0-3.5.8 | 创建 data-server crate（封装 rustdesk-server） | 3h | P0 | ☐ |
|
||
| P0-3.5.9 | data-server 本地部署配置 | 2h | P0 | ☐ |
|
||
| P0-3.5.10 | 端到端通信集成测试 | 4h | P0 | ☐ |
|
||
|
||
**Phase 3.5 预估总工时：28h**
|
||
|
||
### Phase 3.6：跨平台打包（P0） *阶段一*
|
||
|
||
| ID | 任务名称 | 预估工时 | 优先级 | 状态 |
|
||
|----|----------|----------|--------|------|
|
||
| P0-3.6.1 | 配置 cargo-packager | 2h | P0 | ☐ |
|
||
| P0-3.6.2 | macOS 打包配置 (.dmg/.app) | 3h | P0 | ☐ |
|
||
| P0-3.6.3 | Windows 打包配置 (.msi/.exe) | 3h | P0 | ☐ |
|
||
| P0-3.6.4 | Linux 打包配置 (.deb/.AppImage) | 3h | P0 | ☐ |
|
||
| P0-3.6.5 | CI/CD 打包脚本 (GitHub Actions) | 4h | P0 | ☐ |
|
||
| P0-3.6.6 | 打包产物验证测试 | 2h | P0 | ☐ |
|
||
|
||
**Phase 3.6 预估总工时：17h**
|
||
|
||
### Phase 4：Agent 运行时（P1） *阶段二（后续开发）*
|
||
|
||
| ID | 任务名称 | 预估工时 | 优先级 | 状态 |
|
||
|----|----------|----------|--------|------|
|
||
| P1-4.1.1 | 集成 agent_runner 依赖 | 2h | P1 | ☐ |
|
||
| P1-4.1.2 | 实现 AgentManager 核心 | 4h | P1 | ☐ |
|
||
| P1-4.1.3 | 实现消息转换层 | 3h | P1 | ☐ |
|
||
| P1-4.1.4 | 实现任务执行流程 | 4h | P1 | ☐ |
|
||
| P1-4.1.5 | 实现进度回传机制 | 3h | P1 | ☐ |
|
||
| P1-4.1.6 | 实现任务取消功能 | 2h | P1 | ☐ |
|
||
| P1-4.2.1 | 实现状态栏 Agent 状态显示 | 2h | P1 | ☐ |
|
||
| P1-4.3.1 | Phase 4 单元测试 | 3h | P1 | ☐ |
|
||
| P1-4.3.2 | Agent 执行集成测试 | 3h | P1 | ☐ |
|
||
|
||
**Phase 4 预估总工时：26h**
|
||
|
||
### Phase 5：增强功能（P1） *阶段二（后续开发）*
|
||
|
||
| ID | 任务名称 | 预估工时 | 优先级 | 状态 |
|
||
|----|----------|----------|--------|------|
|
||
| P1-5.1.1 | 实现 PermissionManager 核心 | 4h | P1 | ☐ |
|
||
| P1-5.1.2 | 实现 macOS 权限检测 | 3h | P1 | ☐ |
|
||
| P1-5.1.3 | 实现 Windows 权限检测 | 3h | P1 | ☐ |
|
||
| P1-5.1.4 | 实现权限设置 UI | 3h | P1 | ☐ |
|
||
| P1-5.2.1 | 实现日志系统（tracing） | 3h | P1 | ☐ |
|
||
| P1-5.2.2 | 实现日志导出功能 | 2h | P1 | ☐ |
|
||
| P1-5.3.1 | 实现文件传输核心 | 4h | P1 | ☐ |
|
||
| P1-5.3.2 | 实现文件发送 UI | 3h | P1 | ☐ |
|
||
| P1-5.3.3 | 实现文件接收提示 | 2h | P1 | ☐ |
|
||
| P1-5.4.1 | 实现 RemoteDesktop 组件 | 6h | P1 | ☐ |
|
||
| P1-5.4.2 | 集成 enigo 输入模拟 | 3h | P1 | ☐ |
|
||
| P1-5.5.1 | Phase 5 单元测试 | 4h | P1 | ☐ |
|
||
| P1-5.5.2 | 文件传输集成测试 | 3h | P1 | ☐ |
|
||
| P1-5.5.3 | 远程桌面集成测试 | 3h | P1 | ☐ |
|
||
|
||
**Phase 5 预估总工时：46h**
|
||
|
||
### Phase 6：收尾完善（P2） *阶段二（后续开发）*
|
||
|
||
| ID | 任务名称 | 预估工时 | 优先级 | 状态 |
|
||
|----|----------|----------|--------|------|
|
||
| P2-6.1.1 | 实现 About 组件 | 2h | P2 | ☐ |
|
||
| P2-6.1.2 | 实现版本信息显示 | 1h | P2 | ☐ |
|
||
| P2-6.2.1 | 实现 Chat 聊天界面 | 6h | P2 | ☐ |
|
||
| P2-6.2.2 | 实现聊天记录管理 | 3h | P2 | ☐ |
|
||
| P2-6.3.1 | 实现客户端升级检查 | 4h | P2 | ☐ |
|
||
| P2-6.3.2 | 实现升级下载安装 | 4h | P2 | ☐ |
|
||
| P2-6.4.1 | 国际化支持（中/英） | 4h | P2 | ☐ |
|
||
| P2-6.4.2 | 主题切换功能 | 2h | P2 | ☐ |
|
||
| P2-6.5.1 | Phase 6 单元测试 | 3h | P2 | ☐ |
|
||
| P2-6.5.2 | 全量回归测试 | 4h | P2 | ☐ |
|
||
|
||
**Phase 6 预估总工时：33h**
|
||
|
||
---
|
||
|
||
## 详细任务说明
|
||
|
||
## Phase 1：基础框架（P0）
|
||
|
||
### P0-1.1.1 创建 Workspace 配置
|
||
|
||
**任务描述**：创建项目根目录的 Cargo.toml，配置 workspace 成员和共享依赖
|
||
|
||
**实现文件**：
|
||
- `crates/agent-client/Cargo.toml`
|
||
|
||
**验收标准**：
|
||
- [ ] workspace 包含 `crates/agent-client` 和 `crates/agent-protocol` 等成员
|
||
- [ ] 共享依赖版本在 workspace.dependencies 中统一定义
|
||
- [ ] `cargo check --workspace` 通过
|
||
|
||
**相关文档**：
|
||
- spec: 7. 目录结构
|
||
- plan: 1.2 Workspace Cargo.toml 完整配置
|
||
|
||
---
|
||
|
||
### P0-1.1.2 创建 agent-protocol 协议模块
|
||
|
||
**任务描述**：创建协议定义 crate，包含 protobuf 消息定义和编译脚本
|
||
|
||
**实现文件**：
|
||
- `crates/agent-protocol/Cargo.toml`
|
||
- `crates/agent-protocol/build.rs`
|
||
- `crates/agent-protocol/src/lib.rs`
|
||
- `crates/agent-protocol/src/proto/message.proto`
|
||
|
||
**验收标准**：
|
||
- [ ] proto 文件包含 HandshakeRequest/Response, AgentTaskRequest/Response 等消息定义
|
||
- [ ] build.rs 正确编译 proto 文件
|
||
- [ ] 生成的 Rust 代码可被 agent-client 引用
|
||
- [ ] 单元测试通过
|
||
|
||
**相关文档**：
|
||
- spec: 5. 通信协议设计
|
||
- plan: 1.4 agent-protocol/Cargo.toml 完整配置
|
||
|
||
---
|
||
|
||
### P0-1.2.1 实现 main.rs 程序入口
|
||
|
||
**任务描述**：实现应用入口，包含日志初始化、配置加载、信号处理、主循环
|
||
|
||
**实现文件**：
|
||
- `crates/agent-client/src/main.rs`
|
||
|
||
**验收标准**：
|
||
- [ ] 程序启动时初始化日志系统
|
||
- [ ] 加载配置文件
|
||
- [ ] 处理 Ctrl+C 和 terminate 信号
|
||
- [ ] 正确创建 App 实例并运行
|
||
- [ ] 优雅关闭（清理资源）
|
||
|
||
**代码参考**：
|
||
- plan: 1.6 项目脚手架
|
||
|
||
---
|
||
|
||
### P0-1.2.4 实现 Root 根组件
|
||
|
||
**任务描述**：实现主窗口根组件，包含标题栏、Tab 面板、内容区、状态栏
|
||
|
||
**实现文件**：
|
||
- `crates/agent-client/src/components/root.rs`
|
||
|
||
**验收标准**：
|
||
- [ ] 顶部显示应用名称和图标
|
||
- [ ] Tab 面板可切换不同功能页面
|
||
- [ ] 根据 feature 过滤不可用的 Tab（remote-desktop, chat-ui）
|
||
- [ ] 底部显示状态栏
|
||
- [ ] 主题适配（深色/浅色）
|
||
|
||
**代码参考**：
|
||
- plan: 1.8 UI 组件实现
|
||
|
||
---
|
||
|
||
### P0-1.3.1 实现 TrayManager 托盘管理器
|
||
|
||
**任务描述**：实现系统托盘图标显示和菜单功能
|
||
|
||
**实现文件**：
|
||
- `crates/agent-client/src/tray/mod.rs`
|
||
- `crates/agent-client/src/tray/menu.rs`
|
||
- `crates/agent-client/src/tray/icon.rs`
|
||
|
||
**验收标准**：
|
||
- [ ] 启动时在系统托盘显示图标
|
||
- [ ] 左键点击显示主窗口
|
||
- [ ] 右键点击显示菜单（显示窗口、设置、依赖管理、关于、退出）
|
||
- [ ] 菜单项可点击响应
|
||
- [ ] 支持跨平台（macOS/Windows/Linux）
|
||
|
||
**代码参考**：
|
||
- plan: 1.9 系统托盘
|
||
|
||
---
|
||
|
||
## Phase 2：核心功能（P0）
|
||
|
||
### P0-2.1.1 集成 qiming-rustdesk ConnectionManager
|
||
|
||
**任务描述**：集成 qiming-rustdesk 的 RendezvousMediator，实现与 data-server 的连接
|
||
|
||
**实现文件**：
|
||
- `crates/agent-client/src/core/connection.rs`
|
||
|
||
**验收标准**：
|
||
- [ ] 可配置 hbbs 和 hbbr 服务器地址
|
||
- [ ] 连接到 hbbs 获取客户端 ID
|
||
- [ ] 连接到 hbbr 准备中继
|
||
- [ ] 根据网络情况自动选择 P2P 或 Relay 模式
|
||
- [ ] 返回连接延迟（latency）
|
||
|
||
**代码参考**：
|
||
- plan: 2.1 qiming-rustdesk 集成
|
||
|
||
---
|
||
|
||
### P0-2.1.2 实现连接状态管理
|
||
|
||
**任务描述**：实现连接状态的统一管理，包括状态定义、状态切换、状态持久化
|
||
|
||
**实现文件**：
|
||
- `crates/agent-client/src/core/connection/state.rs`
|
||
|
||
**验收标准**：
|
||
- [ ] 定义完整的连接状态枚举（Disconnected/Connecting/Connected/Error）
|
||
- [ ] 状态切换时发出通知
|
||
- [ ] 状态持久化到配置文件
|
||
- [ ] 状态栏正确显示当前状态
|
||
|
||
**代码参考**：
|
||
- plan: 2.1 qiming-rustdesk 集成
|
||
|
||
---
|
||
|
||
### P0-2.1.3 实现心跳保活机制
|
||
|
||
**任务描述**：实现客户端与服务器之间的心跳保活机制，检测连接是否存活
|
||
|
||
**实现文件**：
|
||
- `crates/agent-client/src/core/connection/heartbeat.rs`
|
||
|
||
**验收标准**：
|
||
- [ ] 定期发送心跳包（默认 30 秒）
|
||
- [ ] 检测心跳超时（默认 90 秒）
|
||
- [ ] 超时后触发重连
|
||
- [ ] 心跳包最小化（仅包含必要字段）
|
||
|
||
**代码参考**：
|
||
- plan: 2.1 qiming-rustdesk 集成
|
||
|
||
---
|
||
|
||
### P0-2.1.4 实现重连逻辑
|
||
|
||
**任务描述**：实现网络断开后的自动重连机制，包含指数退避和随机抖动
|
||
|
||
**实现文件**：
|
||
- `crates/agent-client/src/core/connection/reconnect.rs`
|
||
|
||
**验收标准**：
|
||
- [ ] 断线后自动尝试重连
|
||
- [ ] 使用指数退避策略（初始 1s，最大 30s）
|
||
- [ ] 支持随机抖动避免同时重连
|
||
- [ ] 离线消息队列缓存待发送消息
|
||
- [ ] 可配置最大重试次数
|
||
|
||
**代码参考**：
|
||
- plan: 8.2 重连机制实现
|
||
|
||
---
|
||
|
||
### P0-2.2.1 实现 BusinessChannel 模块
|
||
|
||
**任务描述**：在 qiming-rustdesk 基础上实现业务数据通道，用于传输 Agent 任务数据
|
||
|
||
**实现文件**：
|
||
- `crates/agent-client/src/core/business_channel.rs`
|
||
- `vendors/qiming-rustdesk/src/business_channel.rs`
|
||
|
||
**验收标准**：
|
||
- [ ] 复用 qiming-rustdesk 的底层 Stream
|
||
- [ ] 创建独立的业务通道（channel_id = 0xBIZ）
|
||
- [ ] 支持发送/接收业务消息
|
||
- [ ] 支持消息订阅机制
|
||
- [ ] 消息格式正确（message_type + payload）
|
||
|
||
**代码参考**：
|
||
- plan: 2.2 业务数据通道
|
||
|
||
---
|
||
|
||
### P0-2.4.1 实现 ClientInfo 组件
|
||
|
||
**任务描述**：实现客户端信息 Tab，显示 ID 和密码
|
||
|
||
**实现文件**：
|
||
- `crates/agent-client/src/components/client_info.rs`
|
||
|
||
**验收标准**：
|
||
- [ ] 显示 8 位客户端 ID（只读）
|
||
- [ ] 显示连接密码，可切换显示/隐藏
|
||
- [ ] 点击复制按钮复制到剪贴板
|
||
- [ ] 点击"修改密码"跳转到设置页的安全子页面
|
||
- [ ] 显示密码强度提示
|
||
|
||
**代码参考**：
|
||
- spec: 2.2 客户端信息 Tab
|
||
|
||
---
|
||
|
||
## Phase 3：依赖管理（P0）
|
||
|
||
### P0-3.1.2 实现 NodeDetector 系统检测
|
||
|
||
**任务描述**：检测系统中已安装的 Node.js，优先使用系统全局安装
|
||
|
||
**实现文件**：
|
||
- `crates/agent-client/src/core/dependency/node.rs`
|
||
|
||
**验收标准**：
|
||
- [ ] 检测 PATH 中的 node 命令
|
||
- [ ] 检测 macOS 特定路径（/usr/local/bin/node）
|
||
- [ ] 检测 Windows 特定路径（Program Files）
|
||
- [ ] 获取版本号并验证是否 >= 18.0.0
|
||
- [ ] 区分系统全局和客户端目录安装
|
||
|
||
**代码参考**：
|
||
- plan: 3.1 Node.js 自动安装
|
||
|
||
---
|
||
|
||
### P0-3.1.3 实现 NodeInstaller 下载安装
|
||
|
||
**任务描述**：自动下载并安装 Node.js 到客户端隔离目录
|
||
|
||
**实现文件**：
|
||
- `crates/agent-client/src/core/dependency/node_installer.rs`
|
||
|
||
**验收标准**：
|
||
- [ ] 下载对应平台的 Node.js 预编译包
|
||
- [ ] 显示下载进度
|
||
- [ ] 解压到隔离目录（`<APP_DATA>/tools/node/`）
|
||
- [ ] 设置可执行权限
|
||
- [ ] 验证安装成功
|
||
- [ ] 支持断点续传（可选）
|
||
|
||
**代码参考**：
|
||
- plan: 3.1 Node.js 自动安装
|
||
|
||
---
|
||
|
||
### P0-3.2.2 实现依赖状态 UI 组件
|
||
|
||
**任务描述**：实现依赖管理 Tab 的 UI，显示依赖列表和状态
|
||
|
||
**实现文件**：
|
||
- `crates/agent-client/src/components/dependency_manager.rs`
|
||
|
||
**验收标准**：
|
||
- [ ] 显示依赖列表（Node.js, npm, opencode, claude-code 等）
|
||
- [ ] 每行显示：名称、版本、来源、状态、操作按钮
|
||
- [ ] 状态使用颜色区分（绿色=正常，红色=缺失，黄色=可更新）
|
||
- [ ] 支持一键安装所有缺失依赖
|
||
- [ ] 支持手动刷新状态
|
||
|
||
**代码参考**：
|
||
- spec: 2.4 依赖管理 Tab
|
||
|
||
---
|
||
|
||
### P0-3.3.1 Phase 3 单元测试
|
||
|
||
**任务描述**：为依赖管理模块编写单元测试
|
||
|
||
**实现文件**：
|
||
- `crates/agent-client/src/core/dependency/tests.rs`
|
||
|
||
**验收标准**：
|
||
- [ ] NodeDetector 检测逻辑测试
|
||
- [ ] 版本比较逻辑测试
|
||
- [ ] 路径解析逻辑测试
|
||
- [ ] 测试覆盖率 >= 80%
|
||
|
||
---
|
||
|
||
## Phase 3.5：agent-server-admin 最小实现（P0）
|
||
|
||
### P0-3.5.1 创建 agent-server-admin crate 脚手架
|
||
|
||
**任务描述**：创建管理端 crate 基础结构
|
||
|
||
**实现文件**：
|
||
- `crates/agent-server-admin/Cargo.toml`
|
||
- `crates/agent-server-admin/src/main.rs`
|
||
- `crates/agent-server-admin/src/lib.rs`
|
||
|
||
**验收标准**：
|
||
- [ ] crate 可编译
|
||
- [ ] 基础目录结构完整
|
||
- [ ] 依赖 agent-protocol
|
||
|
||
---
|
||
|
||
### P0-3.5.2 实现 HTTP API 基础框架
|
||
|
||
**任务描述**：使用 axum 实现 HTTP API 服务
|
||
|
||
**实现文件**：
|
||
- `crates/agent-server-admin/src/api/mod.rs`
|
||
- `crates/agent-server-admin/src/api/router.rs`
|
||
|
||
**验收标准**：
|
||
- [ ] 启动 HTTP 服务监听指定端口
|
||
- [ ] 支持 CORS 配置
|
||
- [ ] 健康检查接口 `/health`
|
||
- [ ] 错误处理中间件
|
||
|
||
---
|
||
|
||
### P0-3.5.5 实现双向消息发送 API
|
||
|
||
**任务描述**：实现向客户端发送消息并接收响应的 API
|
||
|
||
**实现文件**：
|
||
- `crates/agent-server-admin/src/api/message.rs`
|
||
|
||
**验收标准**：
|
||
- [ ] POST `/api/clients/{id}/message` 发送消息
|
||
- [ ] 支持同步等待响应
|
||
- [ ] 支持超时配置
|
||
- [ ] 消息使用 Protobuf 序列化
|
||
|
||
---
|
||
|
||
### P0-3.5.8 创建 data-server crate
|
||
|
||
**任务描述**：基于 rustdesk-server 封装 data-server crate，提供信令和中继服务
|
||
|
||
**实现文件**：
|
||
- `crates/data-server/Cargo.toml`
|
||
- `crates/data-server/src/main.rs`
|
||
- `crates/data-server/src/config.rs`
|
||
|
||
**验收标准**：
|
||
- [ ] 封装 rustdesk-server 的 hbbs（信令服务）
|
||
- [ ] 封装 rustdesk-server 的 hbbr（中继服务）
|
||
- [ ] 支持配置文件加载
|
||
- [ ] 支持端口配置
|
||
- [ ] 可独立启动运行
|
||
|
||
**代码参考**：
|
||
- vendorsdoc: rustdesk-server.md
|
||
|
||
---
|
||
|
||
### P0-3.5.9 data-server 本地部署配置
|
||
|
||
**任务描述**：配置 data-server 本地开发环境
|
||
|
||
**实现文件**：
|
||
- `config/data-server.toml`
|
||
- `scripts/start-data-server.sh`
|
||
- `docker-compose.yml` (可选)
|
||
|
||
**验收标准**：
|
||
- [ ] 本地可一键启动 data-server
|
||
- [ ] 配置默认端口（hbbs: 21116, hbbr: 21117）
|
||
- [ ] 日志输出正常
|
||
- [ ] 文档说明启动步骤
|
||
|
||
---
|
||
|
||
### P0-3.5.10 端到端通信集成测试
|
||
|
||
**任务描述**：验证 agent-client 与 agent-server-admin 的完整通信流程
|
||
|
||
**实现文件**：
|
||
- `tests/e2e/communication_test.rs`
|
||
|
||
**验收标准**：
|
||
- [ ] 客户端可连接 data-server 获取 ID
|
||
- [ ] 管理端可发现在线客户端
|
||
- [ ] 管理端可向客户端发送消息
|
||
- [ ] 客户端可向管理端返回响应
|
||
- [ ] P2P 模式测试通过
|
||
- [ ] Relay 模式测试通过
|
||
|
||
---
|
||
|
||
## Phase 3.6：跨平台打包（P0）
|
||
|
||
### P0-3.6.1 配置 cargo-packager
|
||
|
||
**任务描述**：配置 cargo-packager 打包工具
|
||
|
||
**实现文件**：
|
||
- `crates/agent-client/packager.toml`
|
||
- `crates/agent-client/Cargo.toml` (metadata)
|
||
|
||
**验收标准**：
|
||
- [ ] 配置应用名称、版本、描述
|
||
- [ ] 配置图标路径
|
||
- [ ] 配置安装目录
|
||
|
||
---
|
||
|
||
### P0-3.6.2 macOS 打包配置
|
||
|
||
**任务描述**：配置 macOS 平台打包
|
||
|
||
**实现文件**：
|
||
- `crates/agent-client/packager.toml`
|
||
- `crates/agent-client/assets/macos/Info.plist`
|
||
- `crates/agent-client/assets/macos/entitlements.plist`
|
||
|
||
**验收标准**：
|
||
- [ ] 生成 .app 应用包
|
||
- [ ] 生成 .dmg 安装镜像
|
||
- [ ] 配置代码签名（可选）
|
||
- [ ] 配置公证（可选）
|
||
|
||
---
|
||
|
||
### P0-3.6.5 CI/CD 打包脚本
|
||
|
||
**任务描述**：配置 GitHub Actions 自动打包
|
||
|
||
**实现文件**：
|
||
- `.github/workflows/build.yml`
|
||
- `.github/workflows/release.yml`
|
||
|
||
**验收标准**：
|
||
- [ ] PR 触发构建检查
|
||
- [ ] Tag 触发发布构建
|
||
- [ ] 产出 macOS/Windows/Linux 安装包
|
||
- [ ] 自动上传 Release Assets
|
||
|
||
---
|
||
|
||
## Phase 4：Agent 运行时（P1）
|
||
|
||
### P1-4.1.2 实现 AgentManager 核心
|
||
|
||
**任务描述**：实现 Agent 任务管理器，直接调用 agent_runner 内部函数
|
||
|
||
**实现文件**：
|
||
- `crates/agent-client/src/core/agent.rs`
|
||
|
||
**验收标准**：
|
||
- [ ] 通过 path 依赖调用 agent_runner（不使用 gRPC）
|
||
- [ ] 启动 Agent 任务（start_agent）
|
||
- [ ] 取消正在执行的任务（cancel_agent）
|
||
- [ ] 查询任务状态（get_agent_status）
|
||
- [ ] 管理多个并发任务
|
||
- [ ] 使用 DashMap 保证线程安全
|
||
|
||
**代码参考**：
|
||
- plan: 4.1 AgentManager 完整实现（250 行）
|
||
|
||
---
|
||
|
||
## Phase 5：增强功能（P1）
|
||
|
||
### P1-5.1.1 实现 PermissionManager 核心
|
||
|
||
**任务描述**：实现跨平台权限检测和管理
|
||
|
||
**实现文件**：
|
||
- `crates/agent-client/src/core/platform/permissions.rs`
|
||
|
||
**验收标准**：
|
||
- [ ] 检测辅助功能权限（Accessibility）
|
||
- [ ] 检测屏幕录制权限（ScreenRecording）
|
||
- [ ] 检测磁盘访问权限（FullDiskAccess）
|
||
- [ ] 打开系统设置页面
|
||
- [ ] macOS 使用 TCC 检查
|
||
- [ ] Windows 使用注册表检查
|
||
|
||
**代码参考**：
|
||
- plan: 5.1 权限检测
|
||
|
||
---
|
||
|
||
## Phase 6：收尾完善（P2）
|
||
|
||
### P2-6.1.1 实现 About 组件
|
||
|
||
**任务描述**：实现关于界面，显示版本信息和链接
|
||
|
||
**实现文件**：
|
||
- `crates/agent-client/src/components/about.rs`
|
||
|
||
**验收标准**：
|
||
- [ ] 显示应用图标
|
||
- [ ] 显示版本号（1.0.0）和构建信息
|
||
- [ ] 显示 Git commit SHA
|
||
- [ ] 提供文档、问题反馈、官网链接
|
||
- [ ] 提供导出日志按钮
|
||
|
||
**代码参考**：
|
||
- plan: 6.1 About 组件完整实现（120 行）
|
||
|
||
---
|
||
|
||
## 任务依赖关系
|
||
|
||
```
|
||
Phase 1 (基础框架)
|
||
├── P0-1.1.1 (Workspace) ───┐
|
||
├── P0-1.1.2 (Protocol) ────┤
|
||
├── P0-1.1.3 (Features) ────┤
|
||
├── P0-1.1.4 (Dependencies) ─┤
|
||
├── P0-1.5.x (协议/安全) ←──┤
|
||
└── P0-1.2.x (UI) ──────────┤
|
||
└── P0-1.3.x (Tray) ────┤
|
||
└── P0-1.4.x (AutoLaunch)
|
||
└── P0-1.6.x (Tests) ← 全部 Phase 1 任务
|
||
│
|
||
Phase 2 (核心功能) ──────────┤
|
||
├── P0-2.1.x (Connection) ←─┘
|
||
├── P0-2.2.x (BusinessChannel) ← P0-1.1.2
|
||
├── P0-2.5.x (安全/消息队列) ← P0-2.1.x
|
||
└── P0-2.3.x (Settings) ←─────┤
|
||
└── P0-2.4.x (ClientInfo) ← P0-2.1.x (Connection)
|
||
└── P0-2.6.x (Tests) ← 全部 Phase 2 任务
|
||
│
|
||
Phase 3 (依赖管理) ←────────────┤
|
||
├── P0-3.1.x (Node.js) ←───────┤
|
||
├── P0-3.2.x (UI) ←────────────┤
|
||
└── P0-3.3.x (Tests) ←─────────┘
|
||
│
|
||
Phase 3.5 (管理端最小实现) ←────┤
|
||
├── P0-3.5.1 (脚手架) ←────────┤
|
||
├── P0-3.5.2-7 (API/通信) ←────┤
|
||
└── P0-3.5.8 (E2E Tests) ← Phase 1-3.5 全部
|
||
│
|
||
Phase 3.6 (跨平台打包) ←────────┤
|
||
├── P0-3.6.1-4 (打包配置) ←────┤
|
||
├── P0-3.6.5 (CI/CD) ←─────────┤
|
||
└── P0-3.6.6 (验证) ←──────────┘
|
||
|
||
═══════════════════════════════════════
|
||
阶段一完成线 (验证里程碑)
|
||
═══════════════════════════════════════
|
||
|
||
Phase 4 (Agent) ←──────────────┤
|
||
├── P1-4.1.x (AgentManager) ← P0-1.1.2 (Protocol)
|
||
├── P1-4.2.x (UI) ←────────────┤
|
||
└── P1-4.3.x (Tests) ←─────────┘
|
||
|
||
Phase 5 (增强) ←───────────────┤
|
||
├── P1-5.1.x (Permissions) ←───┤
|
||
├── P1-5.2.x (Logging) ←───────┤
|
||
├── P1-5.3.x (FileTransfer) ←──┤
|
||
├── P1-5.4.x (RemoteDesktop) ←─┤
|
||
└── P1-5.5.x (Tests) ←─────────┘
|
||
|
||
Phase 6 (收尾) ←────────────────┤
|
||
├── P2-6.1.x (About) ←─────────┤
|
||
├── P2-6.2.x (Chat) ←─────────┤
|
||
├── P2-6.3.x (Update) ←───────┤
|
||
├── P2-6.4.x (i18n) ←─────────┤
|
||
└── P2-6.5.x (Tests) ←─────────┘
|
||
```
|
||
|
||
---
|
||
|
||
### P2-6.4.1 国际化支持（中/英）
|
||
|
||
**任务描述**：实现应用国际化，支持中文和英文两种语言
|
||
|
||
**实现文件**：
|
||
- `crates/agent-client/src/i18n/mod.rs`
|
||
- `crates/agent-client/assets/locales/zh-CN/messages.toml`
|
||
- `crates/agent-client/assets/locales/en-US/messages.toml`
|
||
|
||
**验收标准**：
|
||
- [ ] 实现 I18nManager 管理语言切换
|
||
- [ ] 创建中英文资源文件
|
||
- [ ] 支持设置界面切换语言
|
||
- [ ] 界面文本实时更新
|
||
- [ ] 日期/时间/文件大小按区域格式化
|
||
|
||
**代码参考**：
|
||
- plan: 9.1 国际化基础设施
|
||
|
||
---
|
||
|
||
### P2-6.4.2 主题切换功能
|
||
|
||
**任务描述**：实现浅色/深色/跟随系统三种主题模式
|
||
|
||
**实现文件**：
|
||
- `crates/agent-client/src/core/theme.rs`
|
||
- `crates/agent-client/src/components/theme_toggle.rs`
|
||
|
||
**验收标准**：
|
||
- [ ] 支持浅色主题
|
||
- [ ] 支持深色主题
|
||
- [ ] 支持跟随系统设置
|
||
- [ ] 主题切换实时生效
|
||
- [ ] 主题设置持久化
|
||
|
||
**代码参考**：
|
||
- spec: 2.3.5 外观设置子页面
|
||
|
||
---
|
||
|
||
## 开发顺序建议
|
||
|
||
### 阶段一：核心通信与 UI（当前优先级）
|
||
|
||
**目标**：验证 `agent-server-admin` 与 `agent-client` 之间的双向通信能力。
|
||
|
||
#### 第一批（MVP 最小可运行版本）
|
||
|
||
1. P0-1.1.1 ~ P0-1.1.4：项目脚手架、协议模块、依赖配置
|
||
2. P0-1.5.1 ~ P0-1.5.2：协议版本协商、配置加密
|
||
3. P0-1.2.1 ~ P0-1.2.5：基础 UI 框架、状态栏
|
||
4. P0-1.3.1 ~ P0-1.3.2：托盘功能
|
||
5. P0-1.4.1 ~ P0-1.4.2：开机自启动
|
||
6. P0-1.6.1 ~ P0-1.6.2：Phase 1 测试
|
||
|
||
**预计工时：~39h**
|
||
|
||
#### 第二批（核心通信）
|
||
|
||
1. P0-2.1.1 ~ P0-2.1.4：连接管理、心跳保活、重连
|
||
2. P0-2.2.1 ~ P0-2.2.2：业务通道
|
||
3. P0-2.5.1 ~ P0-2.5.3：密码加密、离线队列、消息分片
|
||
4. P0-2.3.1 ~ P0-2.3.4：设置界面
|
||
5. P0-2.4.1 ~ P0-2.4.2：客户端信息显示
|
||
6. P0-2.6.1 ~ P0-2.6.2：Phase 2 测试
|
||
|
||
**预计工时：~53h**
|
||
|
||
#### 第三批（依赖管理）
|
||
|
||
1. P0-3.1.1 ~ P0-3.1.4：Node.js 检测和安装
|
||
2. P0-3.2.1 ~ P0-3.2.4：依赖管理 UI
|
||
3. P0-3.3.1 ~ P0-3.3.2：Phase 3 测试
|
||
|
||
**预计工时：~32h**
|
||
|
||
#### 第四批（管理端最小实现）
|
||
|
||
1. P0-3.5.1 ~ P0-3.5.7：agent-server-admin API 和通信
|
||
2. P0-3.5.8 ~ P0-3.5.9：data-server crate 和部署配置
|
||
3. P0-3.5.10：端到端通信集成测试
|
||
|
||
**预计工时：~28h**
|
||
|
||
#### 第五批（跨平台打包）
|
||
|
||
1. P0-3.6.1 ~ P0-3.6.4：各平台打包配置
|
||
2. P0-3.6.5：CI/CD 配置
|
||
3. P0-3.6.6：打包验证
|
||
|
||
**预计工时：~17h**
|
||
|
||
**阶段一验证里程碑**：
|
||
- [ ] 客户端可在 macOS/Windows/Linux 打包安装
|
||
- [ ] 客户端能连接 data-server（获取 ID）
|
||
- [ ] 管理端能发现并连接客户端
|
||
- [ ] 双向消息通信正常（P2P/Relay）
|
||
- [ ] 端到端集成测试全部通过
|
||
- [ ] 所有平台安装包可用
|
||
|
||
**阶段一总预计工时：~169h**
|
||
|
||
---
|
||
|
||
### 阶段二：Agent 运行时集成（后续开发）
|
||
|
||
**目标**：集成 agent_runner，实现 Agent 任务执行等功能。
|
||
|
||
#### 第六批（Agent 功能）
|
||
|
||
1. P1-4.1.1 ~ P1-4.1.6：Agent 管理器
|
||
2. P1-4.2.1：状态栏显示
|
||
3. P1-4.3.1 ~ P1-4.3.2：Phase 4 测试
|
||
|
||
**预计工时：~26h**
|
||
|
||
#### 第七批（增强功能）
|
||
|
||
1. P1-5.1.x：权限管理
|
||
2. P1-5.2.x：日志系统
|
||
3. P1-5.3.x：文件传输
|
||
4. P1-5.4.x：远程桌面
|
||
5. P1-5.5.x：Phase 5 测试
|
||
|
||
**预计工时：~46h**
|
||
|
||
#### 第八批（收尾完善）
|
||
|
||
1. P2-6.1.x：关于界面
|
||
2. P2-6.2.x：聊天界面
|
||
3. P2-6.3.x：自动升级
|
||
4. P2-6.4.x：国际化、主题
|
||
5. P2-6.5.x：Phase 6 测试
|
||
|
||
**预计工时：~33h**
|
||
|
||
**阶段二总预计工时：~105h**
|
||
|
||
---
|
||
|
||
## 里程碑
|
||
|
||
> **说明**：Milestone 1-5 属于阶段一（当前开发），Milestone 6-8 属于阶段二（后续开发）
|
||
|
||
### Milestone 1：骨架完成
|
||
- [ ] 完成 Phase 1 所有任务（含测试）
|
||
- [ ] 应用可启动，显示 UI
|
||
- [ ] 系统托盘图标正常
|
||
- [ ] 开机自启动可配置
|
||
- [ ] Phase 1 单元测试通过
|
||
|
||
**达成条件**：编译运行成功，UI 可交互，测试覆盖率 >= 80%
|
||
|
||
### Milestone 2：核心通信
|
||
- [ ] 完成 Phase 2 所有任务（含测试）
|
||
- [ ] 可连接到 data-server
|
||
- [ ] 显示连接状态和延迟
|
||
- [ ] 客户端 ID 和密码功能正常
|
||
- [ ] 双向通信正常（P2P/Relay）
|
||
- [ ] 密码加密存储
|
||
- [ ] 离线消息队列可用
|
||
- [ ] 协议兼容性测试通过
|
||
|
||
**达成条件**：可与服务器建立双向通信，安全机制完备
|
||
|
||
### Milestone 3：依赖就绪
|
||
- [ ] 完成 Phase 3 所有任务（含测试）
|
||
- [ ] 自动检测系统 Node.js
|
||
- [ ] 可自动安装 Node.js
|
||
- [ ] 依赖管理 UI 完整
|
||
|
||
**达成条件**：Agent 运行环境准备就绪
|
||
|
||
### Milestone 4：管理端就绪
|
||
- [ ] 完成 Phase 3.5 所有任务
|
||
- [ ] agent-server-admin 可启动
|
||
- [ ] 可发现在线客户端
|
||
- [ ] 可向客户端发送消息
|
||
- [ ] 端到端集成测试全部通过
|
||
|
||
**达成条件**：客户端与管理端完整通信流程验证通过
|
||
|
||
### Milestone 5：打包发布（阶段一完成）
|
||
- [ ] 完成 Phase 3.6 所有任务
|
||
- [ ] macOS .dmg 可安装运行
|
||
- [ ] Windows .msi 可安装运行
|
||
- [ ] Linux .deb/.AppImage 可运行
|
||
- [ ] CI/CD 自动打包流程正常
|
||
- [ ] 打包产物验证测试通过
|
||
|
||
**达成条件**：阶段一完成，可发布 Alpha 版本
|
||
|
||
---
|
||
|
||
### Milestone 6：Agent 可用
|
||
- [ ] 完成 Phase 4 所有任务（含测试）
|
||
- [ ] 可执行 Agent 任务
|
||
- [ ] 进度实时回传
|
||
- [ ] 可取消任务
|
||
|
||
**达成条件**：Agent 任务完整流程可用
|
||
|
||
### Milestone 7：功能完整
|
||
- [ ] 完成 Phase 5 所有任务（含测试）
|
||
- [ ] 文件传输正常
|
||
- [ ] 远程桌面可用
|
||
- [ ] 权限检测完善
|
||
- [ ] 日志系统完整
|
||
|
||
**达成条件**：所有 P1 功能可用
|
||
|
||
### Milestone 8：发布就绪
|
||
- [ ] 完成 Phase 6 所有任务（含测试）
|
||
- [ ] 所有 P2 功能完成
|
||
- [ ] 国际化支持
|
||
- [ ] 全量回归测试通过
|
||
- [ ] 文档完善
|
||
|
||
**达成条件**：可发布正式版本
|
||
|
||
---
|
||
|
||
## 风险与注意事项
|
||
|
||
### 技术风险
|
||
|
||
| 风险 | 可能性 | 影响 | 缓解措施 |
|
||
|------|--------|------|----------|
|
||
| qiming-rustdesk API 变化 | 低 | 高 | 封装隔离层，减少直接依赖 |
|
||
| gpui API 变化 | 中 | 中 | 锁定 git commit，使用 wrapper |
|
||
| 跨平台兼容性问题 | 中 | 中 | 条件编译，CI 测试覆盖 |
|
||
|
||
### 阻塞风险
|
||
|
||
| 阻塞项 | 依赖任务 | 缓解措施 |
|
||
|--------|----------|----------|
|
||
| qiming-rustdesk 未完成 business_channel | P0-2.2.1 | 先使用模拟实现，后续替换 |
|
||
| agent_runner 函数接口未导出 | P1-4.1.1 | 确认接口，或直接调用内部函数 |
|
||
| gpui-component 组件不完整 | 多个 UI 任务 | 使用基础 gpui 替代，编写 wrapper |
|
||
|
||
---
|
||
|
||
## 变更记录
|
||
|
||
| 版本 | 日期 | 变更内容 | 作者 |
|
||
|------|------|----------|------|
|
||
| v1.1.0 | 2026-01-29 | 补充测试任务、agent-server-admin 最小实现、跨平台打包、安全存储等遗漏任务 | - |
|
||
| v1.0.0 | 2026-01-29 | 初始版本 | - |
|